feat: Add SSML support

[Tgenz1213]

Summary

Adds a pure pre-processing SSML layer to kokoro-js. All tags are resolved before the model sees the input. There is zero overhead for plain-text inputs and no changes to the model pipeline.

Supported tags

Tag	Purpose
<phoneme alphabet="ipa" ph="...">	Bypass G2P with exact IPA pronunciation
<break time="500ms"/>	Insert a timed silence (ms or s)
<sub alias="...">	Substitute spoken text while preserving display text
<say-as interpret-as="characters">	Spell out letter-by-letter (e.g. SQL → S. Q. L.)
<say-as interpret-as="ordinal">	Read as ordinal (e.g. 3 → "third")
<say-as interpret-as="number">	Read as cardinal number

Malformed or unknown tags are read as plain-text as the parser never throws.

Example

const audio = await tts.generate(
  `The <phoneme alphabet="ipa" ph="wˈɜːld">world</phoneme> record, ` +
  `set by <sub alias="World Wide Web Consortium">W3C</sub>, ` +
  `was broken in <say-as interpret-as="ordinal">3</say-as> attempts.` +
  `<break time="500ms"/>` +
  `<say-as interpret-as="characters">SQL</say-as> was also involved.`,
  { voice: "af_heart" }
);

Implementation notes

Architecture

• New src/ssml.js: Lightweight regex parser with hasSSML(), parseSSML(), splitAtBreaks(), and parseBreakMs(). The < guard in hasSSML() means the SSML path is never entered for plain text.
• phonemize() now dispatches to phonemizeSSML() when hasSSML(text) is true. Each segment type is handled independently with no double-normalization.
• <break> tags are extracted one level up in generate()/stream() via splitAtBreaks() — the phonemize layer never sees them. This clean separation means phonemize() requires no knowledge of audio timing.

Audio utilities

• generateSilence(ms): Produces a zeroed RawAudio of the requested duration at 24 kHz.
• concatAudio(chunks): Concatenates audio segments with an 8 ms linear cross-fade at each boundary to prevent audible pops.

<break> in stream()

Breaks yield { text: '', phonemes: '', audio: silence } to preserve the { text, phonemes, audio } shape that consumers iterate over.

eSpeak IPA notation

The ph attribute requires eSpeak IPA, not standard (broad) IPA. The critical difference: stress marks (ˈ ˌ) must appear immediately before the stressed vowel, not before the syllable onset consonant. Placing ˈ before a consonant causes it to be vocalized as a phoneme (heard as an "ah" sound).

• ✅ eSpeak: wˈɜːld (ˈ before vowel ɜ)
• ❌ Standard: ˈwɜːld (ˈ before onset consonant w)

Use espeak-ng --ipa -q -v en-us "word" to discover the correct notation for any word.

Partially address #36

[Copilot]

Pull request overview

This PR adds a preprocessing SSML (Speech Synthesis Markup Language) layer to kokoro-js, partially addressing Issue #36. All SSML tags are resolved before the model sees the input, with zero overhead for plain-text inputs and no changes to the model pipeline. Supported tags include <phoneme>, <break>, <sub>, and <say-as> (with characters, ordinal, and number interpret-as modes).

Changes:

• New src/ssml.js module with a regex-based SSML parser (hasSSML, parseSSML, splitAtBreaks, parseBreakMs) that gracefully degrades malformed/unknown tags to plain text.
• Extended src/phonemize.js with SSML-aware phonemization (phonemizeSSML, runEspeak, expandCharacters, expandOrdinal) and exported normalize_text for testing. The phonemize() entry point now delegates to the SSML path when tags are detected.
• Updated src/kokoro.js with generateSilence/concatAudio audio utilities and <break> tag handling in both generate() and stream() methods, splitting text at break points and concatenating with 8ms linear cross-fades.

Reviewed changes

Copilot reviewed 6 out of 6 changed files in this pull request and generated 1 comment.

Show a summary per file

File	Description
kokoro.js/src/ssml.js	New regex-based SSML parser with typed segment output, break time parsing, and graceful fallback for unknown/malformed tags
kokoro.js/src/phonemize.js	Adds SSML-aware phonemization path, refactors eSpeak invocation into reusable runEspeak, adds ordinal/character expansion helpers, exports normalize_text
kokoro.js/src/kokoro.js	Adds generateSilence/concatAudio utilities, integrates <break> handling into generate() and stream() methods
kokoro.js/tests/ssml.test.js	Comprehensive tests for SSML parsing, break time conversion, phonemization with all supported tags, and silence sizing math
kokoro.js/tests/phonemize.test.js	New unit tests for normalize_text covering quotes, whitespace, abbreviations, numbers, currency, possessives, and hyphenated initials
kokoro.js/README.md	Documents supported SSML tags, eSpeak IPA notation requirements, and usage examples

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

You can also share your feedback on Copilot code review. Take the survey.

[nptrainor]

Thank you for your work.
Any comments/progress on this?
This would be seriously useful across virtually every use case.

[Tgenz1213]

Thank you for your work. Any comments/progress on this? This would be seriously useful across virtually every use case.

I haven't heard any feedback yet.

You can try it out via NPM.

I haven't uploaded any of my side projects to Github recently, but it works well where I've tried it.