speechready 0.0.1 → 0.2.0

package/dist/profiles/data.js

@@ -0,0 +1,411 @@
+// Generated by scripts/build-profiles.mjs from spec/profiles. Do not edit.
+export const PROFILE_DATA = [
+    {
+        "id": "amazon-polly",
+        "provider": "polly",
+        "models": [
+            "neural",
+            "generative",
+            "long-form",
+            "standard"
+        ],
+        "default": true,
+        "syntax": "ssml",
+        "escape": "xml",
+        "audio_tags": false,
+        "limit": {
+            "unit": "chars",
+            "max": 3000
+        },
+        "intents": {
+            "pause": {
+                "render": "<break time=\"{ms}ms\"/>",
+                "min_ms": 0,
+                "max_ms": 10000
+            },
+            "spell": {
+                "render": "spaced"
+            },
+            "emphasis": {
+                "render": "{text}"
+            },
+            "phoneme": {
+                "render": "<phoneme alphabet=\"ipa\" ph=\"{ipa}\">{text}</phoneme>"
+            }
+        },
+        "lexicon": {
+            "format": "pls",
+            "alphabet": "ipa"
+        },
+        "notes": "Output is the SSML body for `TextType=ssml`; the caller wraps it in <speak>. SynthesizeSpeech takes at most 3,000 billed characters (6,000 including tags); the profile counts everything, so 3,000 is safe. <break> caps at 10 seconds. <emphasis> is unavailable on neural, long-form and generative voices, so emphasis is rendered as plain text. <say-as interpret-as=\"characters\"> silently switches a neural voice to its standard counterpart for that sentence, so spelling is rendered as spaced characters instead. <phoneme> with IPA is supported (partially on generative). Lexicons are uploaded as PLS with PutLexicon.\n",
+        "sources": [
+            "https://docs.aws.amazon.com/polly/latest/dg/API_SynthesizeSpeech.html",
+            "https://docs.aws.amazon.com/polly/latest/dg/supportedtags.html",
+            "https://docs.aws.amazon.com/polly/latest/dg/break-tag.html",
+            "https://docs.aws.amazon.com/polly/latest/dg/say-as-tag.html"
+        ],
+        "verified": "2026-10-29"
+    },
+    {
+        "id": "azure-neural",
+        "provider": "azure",
+        "models": [
+            "neural",
+            "hd"
+        ],
+        "default": true,
+        "syntax": "ssml",
+        "escape": "xml",
+        "audio_tags": false,
+        "limit": {
+            "unit": "chars",
+            "max": 8000
+        },
+        "intents": {
+            "pause": {
+                "render": "<break time=\"{ms}ms\" />",
+                "min_ms": 0,
+                "max_ms": 20000
+            },
+            "spell": {
+                "render": "<say-as interpret-as=\"characters\">{text}</say-as>"
+            },
+            "emphasis": {
+                "render": "<emphasis level=\"strong\">{text}</emphasis>"
+            },
+            "phoneme": {
+                "render": "<phoneme alphabet=\"ipa\" ph=\"{ipa}\">{text}</phoneme>"
+            }
+        },
+        "lexicon": {
+            "format": "pls",
+            "alphabet": "ipa"
+        },
+        "notes": "Output is the SSML body: text with break, say-as and emphasis elements, with & < > escaped. The caller wraps it in <speak> and <voice>, since the voice name is theirs to choose. Azure caps audio at 10 minutes per request and the WebSocket SSML message at 64 KB; 8,000 characters stays well inside both at normal speaking rates. HD voices support a subset of SSML; check the HD page.\n",
+        "sources": [
+            "https://learn.microsoft.com/en-us/azure/ai-services/speech-service/speech-synthesis-markup-structure",
+            "https://learn.microsoft.com/en-us/azure/ai-services/speech-service/speech-services-quotas-and-limits"
+        ],
+        "verified": "2026-10-28"
+    },
+    {
+        "id": "cartesia-sonic",
+        "provider": "cartesia",
+        "models": [
+            "sonic-3.6",
+            "sonic-3.5",
+            "sonic-3",
+            "sonic-latest",
+            "sonic-2",
+            "sonic-turbo"
+        ],
+        "default": true,
+        "syntax": "plain",
+        "escape": "none",
+        "audio_tags": false,
+        "limit": {
+            "unit": "chars",
+            "max": null
+        },
+        "intents": {
+            "pause": {
+                "render": "<break time=\"{ms}ms\"/>",
+                "min_ms": 0
+            },
+            "spell": {
+                "render": "<spell>{text}</spell>"
+            },
+            "emphasis": {
+                "render": "{text}"
+            }
+        },
+        "lexicon": {
+            "format": "none"
+        },
+        "notes": "Sonic takes plain text with a small set of SSML-like tags, not SSML: <break time=\"500ms\"/>, <spell>ABC123</spell>, and speed, volume and emotion tags on sonic-3 and newer. Each tag counts as one character. Cartesia publishes no per-request transcript limit; its own guidance for agents is one sentence per request, which the streaming segmenter gives you. Cartesia runs its own text normalizer (request field `normalization`, default `auto`); its docs recommend pre-normalizing and setting `normalization: off` when you need full control of the spoken form, which is exactly what this library's output is for. Pronunciations are managed server-side through `pronunciation_dict_id`, so there is no lexicon export.\n",
+        "sources": [
+            "https://docs.cartesia.ai/api-reference/tts/bytes",
+            "https://docs.cartesia.ai/build-with-cartesia/capability-guides/ssml-tags",
+            "https://docs.cartesia.ai/build-with-cartesia/capability-guides/text-normalization",
+            "https://docs.cartesia.ai/build-with-cartesia/tts-models/latest"
+        ],
+        "verified": "2026-10-29"
+    },
+    {
+        "id": "deepgram-aura",
+        "provider": "deepgram",
+        "models": [
+            "aura-2",
+            "aura"
+        ],
+        "default": true,
+        "syntax": "plain",
+        "escape": "none",
+        "audio_tags": false,
+        "limit": {
+            "unit": "chars",
+            "max": 2000
+        },
+        "intents": {
+            "pause": {
+                "render": "punctuation"
+            },
+            "spell": {
+                "render": "spaced"
+            },
+            "emphasis": {
+                "render": "{text}"
+            }
+        },
+        "lexicon": {
+            "format": "none"
+        },
+        "notes": "Plain text only: no SSML, no pause or pronunciation markup, prosody only through the `speed` query parameter. Aura-2 covers English, Spanish, German, French, Dutch, Italian and Japanese; no Turkish. The 2,000 character cap is the figure Deepgram's REST reference carried at the Aura launch; the current pages state no number and their chunking guide works in 100 to 200 character sentence pieces, so treat 2,000 as the ceiling and stream sentences in practice.\n",
+        "sources": [
+            "https://developers.deepgram.com/reference/text-to-speech/speak-request",
+            "https://developers.deepgram.com/docs/tts-models",
+            "https://developers.deepgram.com/docs/text-chunking-for-tts-optimization"
+        ],
+        "verified": "2026-10-29"
+    },
+    {
+        "id": "elevenlabs-v2",
+        "provider": "elevenlabs",
+        "models": [
+            "eleven_multilingual_v2",
+            "eleven_flash_v2_5",
+            "eleven_flash_v2",
+            "eleven_turbo_v2_5",
+            "eleven_turbo_v2",
+            "eleven_multilingual_v1",
+            "eleven_monolingual_v1"
+        ],
+        "default": true,
+        "syntax": "plain",
+        "escape": "none",
+        "audio_tags": false,
+        "limit": {
+            "unit": "chars",
+            "max": 10000,
+            "per_model": {
+                "eleven_flash_v2_5": 40000,
+                "eleven_flash_v2": 30000
+            }
+        },
+        "intents": {
+            "pause": {
+                "render": "<break time=\"{s}s\" />",
+                "min_ms": 100,
+                "max_ms": 3000
+            },
+            "spell": {
+                "render": "spaced"
+            },
+            "emphasis": {
+                "render": "{text}"
+            }
+        },
+        "lexicon": {
+            "format": "pls",
+            "alphabet": "ipa"
+        },
+        "notes": "Models before v3 accept the SSML break tag and nothing else from SSML. Pauses are capped at 3 seconds; the docs warn that many breaks in one request can destabilise output, so keep them few. Dashes and ellipses are the documented fallback. Character limits per model come from the models overview page; turbo models list none there, so they inherit the 10,000 default.\n",
+        "sources": [
+            "https://elevenlabs.io/docs/product/prompting/pauses",
+            "https://elevenlabs.io/docs/overview/models"
+        ],
+        "verified": "2026-10-27"
+    },
+    {
+        "id": "elevenlabs-v3",
+        "provider": "elevenlabs",
+        "models": [
+            "eleven_v3",
+            "eleven_v3_conversational",
+            "eleven_v4",
+            "eleven_v4_turbo"
+        ],
+        "default": false,
+        "syntax": "plain",
+        "escape": "none",
+        "audio_tags": true,
+        "limit": {
+            "unit": "chars",
+            "max": 5000,
+            "per_model": {
+                "eleven_v4": 10000
+            }
+        },
+        "intents": {
+            "pause": {
+                "render": "punctuation"
+            },
+            "spell": {
+                "render": "spaced"
+            },
+            "emphasis": {
+                "render": "{text}"
+            }
+        },
+        "lexicon": {
+            "format": "pls",
+            "alphabet": "ipa"
+        },
+        "notes": "v3 and v4 do not accept SSML break tags. Pacing comes from punctuation and audio tags such as [short pause]; unknown bracket tags made of words pass through for these models. Limits: eleven_v3 5,000 characters, eleven_v4 10,000; the conversational and turbo variants list none, so they take the 5,000 default until verified.\n",
+        "sources": [
+            "https://elevenlabs.io/docs/product/prompting/pauses",
+            "https://elevenlabs.io/docs/overview/models"
+        ],
+        "verified": "2026-10-27"
+    },
+    {
+        "id": "google-chirp3",
+        "provider": "google",
+        "models": [
+            "chirp3-hd",
+            "chirp-hd",
+            "gemini-tts"
+        ],
+        "default": true,
+        "syntax": "plain",
+        "escape": "none",
+        "audio_tags": false,
+        "limit": {
+            "unit": "bytes",
+            "max": 5000
+        },
+        "intents": {
+            "pause": {
+                "render": "punctuation"
+            },
+            "spell": {
+                "render": "spaced"
+            },
+            "emphasis": {
+                "render": "{text}"
+            }
+        },
+        "lexicon": {
+            "format": "google",
+            "alphabet": "ipa"
+        },
+        "notes": "Chirp 3 HD takes plain text in `input.text`; SSML on these voices is a preview that works only for synchronous requests, so this profile stays plain. Pauses can be steered with `[pause]`, `[pause short]` and `[pause long]`, but only in the `input.markup` field, never in `text`, so the profile renders pauses as punctuation and leaves markup to callers who use that field. Pronunciations go in the request's `custom_pronunciations` list (IPA or X-SAMPA), which is what the google lexicon export produces. The request body is capped at 5,000 bytes.\n",
+        "sources": [
+            "https://docs.cloud.google.com/text-to-speech/docs/chirp3-hd",
+            "https://docs.cloud.google.com/text-to-speech/quotas"
+        ],
+        "verified": "2026-10-29"
+    },
+    {
+        "id": "google-ssml",
+        "provider": "google",
+        "models": [
+            "neural2",
+            "wavenet",
+            "studio",
+            "standard",
+            "polyglot"
+        ],
+        "default": false,
+        "syntax": "ssml",
+        "escape": "xml",
+        "audio_tags": false,
+        "limit": {
+            "unit": "bytes",
+            "max": 5000
+        },
+        "intents": {
+            "pause": {
+                "render": "<break time=\"{ms}ms\"/>",
+                "min_ms": 0
+            },
+            "spell": {
+                "render": "<say-as interpret-as=\"characters\">{text}</say-as>"
+            },
+            "emphasis": {
+                "render": "<emphasis level=\"moderate\">{text}</emphasis>"
+            },
+            "phoneme": {
+                "render": "<phoneme alphabet=\"ipa\" ph=\"{ipa}\">{text}</phoneme>"
+            }
+        },
+        "lexicon": {
+            "format": "none"
+        },
+        "notes": "The classic voice families take full SSML in `input.ssml`. Output is the body; the caller wraps it in <speak>. Studio voices ignore <emphasis>, <mark>, <prosody pitch> and <lang>. Google documents no upper bound for <break time>. The 5,000-byte cap counts the SSML tags too. There is no lexicon upload for these voices, so lexicon entries are rendered inline as <phoneme> tags.\n",
+        "sources": [
+            "https://docs.cloud.google.com/text-to-speech/docs/ssml",
+            "https://docs.cloud.google.com/text-to-speech/docs/list-voices-and-types",
+            "https://docs.cloud.google.com/text-to-speech/quotas"
+        ],
+        "verified": "2026-10-29"
+    },
+    {
+        "id": "openai-tts",
+        "provider": "openai",
+        "models": [
+            "gpt-4o-mini-tts",
+            "gpt-4o-mini-tts-2025-12-15",
+            "tts-1",
+            "tts-1-hd"
+        ],
+        "default": true,
+        "syntax": "plain",
+        "escape": "none",
+        "audio_tags": false,
+        "limit": {
+            "unit": "chars",
+            "max": 4096
+        },
+        "intents": {
+            "pause": {
+                "render": "punctuation"
+            },
+            "spell": {
+                "render": "spaced"
+            },
+            "emphasis": {
+                "render": "{text}"
+            }
+        },
+        "lexicon": {
+            "format": "none"
+        },
+        "notes": "No SSML. Tone is steered with the separate `instructions` request parameter, which does not work with tts-1 or tts-1-hd. The input is capped at 4,096 characters. OpenAI has announced that these models shut down on 6 January 2027 in favour of the Realtime API, so this profile is maintained until then.\n",
+        "sources": [
+            "https://developers.openai.com/api/docs/api-reference/audio/createSpeech",
+            "https://developers.openai.com/api/docs/guides/text-to-speech"
+        ],
+        "verified": "2026-10-28"
+    },
+    {
+        "id": "plain",
+        "provider": "plain",
+        "models": [],
+        "default": true,
+        "syntax": "plain",
+        "escape": "none",
+        "audio_tags": false,
+        "limit": {
+            "unit": "chars",
+            "max": null
+        },
+        "intents": {
+            "pause": {
+                "render": "punctuation"
+            },
+            "spell": {
+                "render": "spaced"
+            },
+            "emphasis": {
+                "render": "{text}"
+            }
+        },
+        "lexicon": {
+            "format": "none"
+        },
+        "notes": "Provider-neutral output. Pauses become punctuation, spell-outs become spaced characters, emphasis is dropped. No request limit, so one chunk.\n",
+        "sources": [],
+        "verified": "2026-10-27"
+    }
+];

package/dist/profiles/index.d.ts

@@ -0,0 +1,35 @@
+/** Provider profiles: data files that say what each TTS model accepts.
+ *
+ * The YAML files live in the repository's `spec/profiles`. The build step turns
+ * them into `data.ts` so the package needs no YAML parser at runtime. Each
+ * profile states the intent renderings, the request limit, the escaping rules
+ * and whether unknown bracket tags pass through.
+ */
+export interface Profile {
+    id: string;
+    provider: string;
+    models: string[];
+    /** plain | ssml */
+    syntax: string;
+    /** none | xml */
+    escape: string;
+    /** chars | bytes */
+    limitUnit: string;
+    limitMax: number | null;
+    limitPerModel: Record<string, number>;
+    intents: Record<string, Record<string, unknown>>;
+    audioTags: boolean;
+    /** pls | google | none: how a lexicon is uploaded to this provider */
+    lexiconFormat: string;
+    lexiconAlphabet: string;
+    default: boolean;
+    notes: string;
+    sources: string[];
+    verified: string;
+    raw: Record<string, unknown>;
+    limitFor(model?: string | null): number | null;
+}
+export declare function listProfiles(): Profile[];
+export declare function loadProfile(profileId: string): Profile;
+/** Pick the profile for a provider and model. No provider = the `plain` profile. */
+export declare function resolveProfile(provider?: string | null, model?: string | null): Profile;

package/dist/profiles/index.js

@@ -0,0 +1,72 @@
+/** Provider profiles: data files that say what each TTS model accepts.
+ *
+ * The YAML files live in the repository's `spec/profiles`. The build step turns
+ * them into `data.ts` so the package needs no YAML parser at runtime. Each
+ * profile states the intent renderings, the request limit, the escaping rules
+ * and whether unknown bracket tags pass through.
+ */
+import { PROFILE_DATA } from "./data.js";
+function fromDict(data) {
+    const limit = (data.limit ?? {});
+    const lexicon = (data.lexicon ?? {});
+    const profile = {
+        id: String(data.id),
+        provider: String(data.provider),
+        models: (data.models ?? []).map(String),
+        syntax: data.syntax ?? "plain",
+        escape: data.escape ?? "none",
+        limitUnit: limit.unit ?? "chars",
+        limitMax: limit.max ?? null,
+        limitPerModel: { ...(limit.per_model ?? {}) },
+        intents: { ...(data.intents ?? {}) },
+        audioTags: Boolean(data.audio_tags ?? false),
+        lexiconFormat: String(lexicon.format ?? "none"),
+        lexiconAlphabet: String(lexicon.alphabet ?? "ipa"),
+        default: Boolean(data.default ?? false),
+        notes: data.notes ?? "",
+        sources: (data.sources ?? []).map(String),
+        verified: String(data.verified ?? ""),
+        raw: data,
+        limitFor(model) {
+            if (model && model in this.limitPerModel)
+                return this.limitPerModel[model];
+            return this.limitMax;
+        },
+    };
+    return profile;
+}
+let cache = null;
+function all() {
+    if (!cache)
+        cache = PROFILE_DATA.map(fromDict);
+    return cache;
+}
+export function listProfiles() {
+    return [...all()];
+}
+export function loadProfile(profileId) {
+    for (const p of all())
+        if (p.id === profileId)
+            return p;
+    throw new Error(`unknown profile ${JSON.stringify(profileId)}; known: ${all().map((p) => p.id).join(", ")}`);
+}
+/** Pick the profile for a provider and model. No provider = the `plain` profile. */
+export function resolveProfile(provider, model) {
+    if (!provider && !model)
+        return loadProfile("plain");
+    const matches = all().filter((p) => !provider || p.provider === provider);
+    if (model) {
+        for (const p of matches)
+            if (p.models.includes(model))
+                return p;
+        if (!provider)
+            throw new Error(`no profile lists model ${JSON.stringify(model)}`);
+    }
+    for (const p of matches)
+        if (p.default)
+            return p;
+    if (matches.length)
+        return matches[0];
+    const known = [...new Set(all().map((p) => p.provider))].sort();
+    throw new Error(`no profile for provider ${JSON.stringify(provider)}; known providers: ${known.join(", ")}`);
+}

package/dist/util.d.ts

@@ -0,0 +1,53 @@
+/** Small helpers that make the TypeScript port line up with the Python reference.
+ *
+ * Python's `re` is Unicode-aware by default: `\w` matches letters in any script
+ * and `\b` is a boundary next to them. JavaScript's `\w` and `\b` are ASCII only,
+ * so every pattern in this package is written with `W` and `B` instead and
+ * compiled with the `u` flag.
+ */
+/** Python's `\w` under Unicode: letters, digits, underscore. Use inside a character class. */
+export declare const W = "\\p{L}\\p{N}_";
+/** Python's `\b` under Unicode. */
+export declare const B = "(?:(?<=[\\p{L}\\p{N}_])(?![\\p{L}\\p{N}_])|(?<![\\p{L}\\p{N}_])(?=[\\p{L}\\p{N}_]))";
+/** Compile a pattern with the `u` flag (plus `g`, which every helper here expects). */
+export declare function re(source: string, flags?: string): RegExp;
+/** A match as the Python-style callbacks see it: `m[0]`, `m[1]`..., `m.index`, `m.groups`. */
+export type Match = RegExpExecArray;
+/** `pattern.sub(fn, text)`: every match replaced by `fn(match)`. */
+export declare function sub(pattern: RegExp, text: string, fn: (m: Match) => string): string;
+/** `pattern.sub(repl, text)` with a plain string replacement (no `$` expansion). */
+export declare function subs(pattern: RegExp, text: string, repl: string): string;
+/** First match anywhere, or null. Safe on global patterns. */
+export declare function search(pattern: RegExp, text: string): Match | null;
+/** `pattern.match(text)`: a match anchored at the start, or null. */
+export declare function matchStart(pattern: RegExp, text: string): Match | null;
+/** `re.fullmatch(pattern, text)`. */
+export declare function fullmatch(pattern: RegExp, text: string): Match | null;
+export declare function test(pattern: RegExp, text: string): boolean;
+/** All matches, in order. */
+export declare function finditer(pattern: RegExp, text: string): Match[];
+export declare function findall(pattern: RegExp, text: string): string[];
+/** `re.escape`: escape what is special in a pattern (letters are left alone, which the `u` flag requires). */
+export declare function escapeRe(s: string): string;
+export declare function group(m: Match, i: number): string | undefined;
+export declare function strip(s: string, chars?: string): string;
+export declare function lstrip(s: string, chars?: string): string;
+export declare function rstrip(s: string, chars?: string): string;
+export declare function partition(s: string, sep: string): [string, string, string];
+export declare function rpartition(s: string, sep: string): [string, string, string];
+export declare function isDigit(s: string): boolean;
+export declare function isUpper(ch: string): boolean;
+export declare function isAlpha(s: string): boolean;
+export declare function isSpace(ch: string): boolean;
+export declare function chars(s: string): string[];
+/** Python's `round()`: ties go to the even neighbour. */
+export declare function roundHalfEven(x: number): number;
+/** Python's `divmod` for non-negative integers. */
+export declare function divmod(n: number, d: number): [number, number];
+/** `str.format` for the small templates in provider profiles: `{ms}`, `{s}`, `{text}`, `{ipa}`. */
+export declare function format(template: string, values: Record<string, string | number>): string;
+export declare function escapeXml(text: string): string;
+/** `len(text.encode("utf-8"))`. */
+export declare function utf8Length(text: string): number;
+/** `len(text)` in code points, as Python counts. */
+export declare function codePoints(text: string): number;