speechready 0.0.1 → 0.2.0

package/dist/lexicon.d.ts

@@ -0,0 +1,53 @@
+/** One pronunciation lexicon, applied in the pipeline and exported to each vendor's format.
+ *
+ * An entry says how a word is pronounced in one of three ways:
+ * - `ipa`: an IPA transcription, rendered as a phoneme tag where the provider
+ *   accepts one (Azure, Google, Polly) and exported to lexicon files;
+ * - `say`: a respelling or alias ("engine X", "sequel") that replaces the word in
+ *   the text, which works on every provider;
+ * - `spell: true`: the word is read letter by letter.
+ *
+ * When a provider cannot take a phoneme tag, an entry falls back to `say`, then
+ * to `spell`, then leaves the word alone.
+ */
+import { Intent } from "./intents.js";
+import { Profile } from "./profiles/index.js";
+export interface Entry {
+    word: string;
+    ipa: string;
+    say: string;
+    spell: boolean;
+    case_sensitive: boolean;
+}
+export type EntryInput = Partial<Entry> & {
+    word: string;
+};
+export declare function entry(e: EntryInput): Entry;
+export declare class Lexicon {
+    entries: Entry[];
+    locale: string;
+    constructor(entries?: EntryInput[], locale?: string);
+    static fromEntries(entries: EntryInput[], locale?: string): Lexicon;
+    /** Build from a parsed lexicon document (`{locale, entries}`), e.g. `JSON.parse` of a lexicon file. */
+    static fromObject(data: {
+        locale?: string;
+        entries?: EntryInput[];
+    }): Lexicon;
+    /** Read a `.json` lexicon file, or a `.yaml` one when the optional `yaml` package is installed. Node only. */
+    static load(path: string): Promise<Lexicon>;
+    toObject(): {
+        locale: string;
+        entries: Record<string, unknown>[];
+    };
+    /** Replace every lexicon word in `text` with an intent sentinel; appends to `intents`. */
+    apply(text: string, intents: Intent[]): string;
+    /** Pronunciation Lexicon Specification XML, accepted by ElevenLabs, Azure and Amazon Polly. */
+    toPls(alphabet?: string): string;
+    /** Google Cloud TTS custom pronunciations (v1beta1 `customPronunciations`). IPA entries only. */
+    toGoogleJson(): string;
+    toJson(): string;
+    /** The upload file for a provider profile, or null when the provider takes no lexicon. */
+    exportFor(profile: Profile): string | null;
+    /** `pls`, `google`, or `json`. */
+    export(fmt: string, alphabet?: string): string;
+}

package/dist/lexicon.js

@@ -0,0 +1,131 @@
+/** One pronunciation lexicon, applied in the pipeline and exported to each vendor's format.
+ *
+ * An entry says how a word is pronounced in one of three ways:
+ * - `ipa`: an IPA transcription, rendered as a phoneme tag where the provider
+ *   accepts one (Azure, Google, Polly) and exported to lexicon files;
+ * - `say`: a respelling or alias ("engine X", "sequel") that replaces the word in
+ *   the text, which works on every provider;
+ * - `spell: true`: the word is read letter by letter.
+ *
+ * When a provider cannot take a phoneme tag, an entry falls back to `say`, then
+ * to `spell`, then leaves the word alone.
+ */
+import { SENTINEL_CLOSE, SENTINEL_OPEN, intent } from "./intents.js";
+import { W, escapeRe, escapeXml, re, sub } from "./util.js";
+export function entry(e) {
+    return { ipa: "", say: "", spell: false, case_sensitive: false, ...e };
+}
+function entryIntent(e, matched) {
+    if (e.spell && !e.ipa && !e.say)
+        return intent("spell", { text: matched });
+    return intent("phoneme", { text: matched, ipa: e.ipa, say: e.say });
+}
+export class Lexicon {
+    entries;
+    locale;
+    constructor(entries = [], locale = "en-US") {
+        this.entries = entries.map(entry);
+        this.locale = locale;
+    }
+    // --- construction ---------------------------------------------------------------
+    static fromEntries(entries, locale = "en-US") {
+        return new Lexicon(entries, locale);
+    }
+    /** Build from a parsed lexicon document (`{locale, entries}`), e.g. `JSON.parse` of a lexicon file. */
+    static fromObject(data) {
+        return new Lexicon(data.entries ?? [], data.locale ?? "en-US");
+    }
+    /** Read a `.json` lexicon file, or a `.yaml` one when the optional `yaml` package is installed. Node only. */
+    static async load(path) {
+        const fs = await import("node:fs/promises");
+        const text = await fs.readFile(path, "utf-8");
+        if (/\.ya?ml$/i.test(path)) {
+            let yaml;
+            try {
+                yaml = (await import("yaml"));
+            }
+            catch {
+                throw new Error("reading a YAML lexicon needs the `yaml` package (npm install yaml); JSON lexicons need nothing");
+            }
+            return Lexicon.fromObject(yaml.parse(text));
+        }
+        return Lexicon.fromObject(JSON.parse(text));
+    }
+    toObject() {
+        return {
+            locale: this.locale,
+            entries: this.entries.map((e) => {
+                const out = {};
+                for (const [k, v] of Object.entries({ word: e.word, ipa: e.ipa, say: e.say, spell: e.spell, case_sensitive: e.case_sensitive })) {
+                    if (v)
+                        out[k] = v;
+                }
+                return out;
+            }),
+        };
+    }
+    // --- applying to text ------------------------------------------------------------
+    /** Replace every lexicon word in `text` with an intent sentinel; appends to `intents`. */
+    apply(text, intents) {
+        if (!this.entries.length)
+            return text;
+        let work = text;
+        const ordered = [...this.entries].sort((a, b) => b.word.length - a.word.length);
+        for (const e of ordered) {
+            const flags = e.case_sensitive ? "" : "i";
+            const pattern = re(`(?<![${W}${SENTINEL_OPEN}${SENTINEL_CLOSE}])${escapeRe(e.word)}(?![${W}])`, flags);
+            work = sub(pattern, work, (m) => {
+                intents.push(entryIntent(e, m[0]));
+                return `${SENTINEL_OPEN}${intents.length - 1}${SENTINEL_CLOSE}`;
+            });
+        }
+        return work;
+    }
+    // --- export ----------------------------------------------------------------------------
+    /** Pronunciation Lexicon Specification XML, accepted by ElevenLabs, Azure and Amazon Polly. */
+    toPls(alphabet = "ipa") {
+        const lines = [
+            '<?xml version="1.0" encoding="UTF-8"?>',
+            `<lexicon version="1.0" xmlns="http://www.w3.org/2005/01/pronunciation-lexicon" alphabet="${alphabet}" xml:lang="${this.locale}">`,
+        ];
+        for (const e of this.entries) {
+            lines.push("  <lexeme>");
+            lines.push(`    <grapheme>${escapeXml(e.word)}</grapheme>`);
+            if (e.ipa)
+                lines.push(`    <phoneme>${escapeXml(e.ipa)}</phoneme>`);
+            else if (e.say)
+                lines.push(`    <alias>${escapeXml(e.say)}</alias>`);
+            else if (e.spell)
+                lines.push(`    <alias>${escapeXml(Array.from(e.word).join(" "))}</alias>`);
+            lines.push("  </lexeme>");
+        }
+        lines.push("</lexicon>");
+        return lines.join("\n") + "\n";
+    }
+    /** Google Cloud TTS custom pronunciations (v1beta1 `customPronunciations`). IPA entries only. */
+    toGoogleJson() {
+        const items = this.entries
+            .filter((e) => e.ipa)
+            .map((e) => ({ phrase: e.word, phoneticEncoding: "PHONETIC_ENCODING_IPA", pronunciation: e.ipa }));
+        return JSON.stringify({ pronunciations: items }, null, 2) + "\n";
+    }
+    toJson() {
+        return JSON.stringify(this.toObject(), null, 2) + "\n";
+    }
+    /** The upload file for a provider profile, or null when the provider takes no lexicon. */
+    exportFor(profile) {
+        if (profile.lexiconFormat === "none")
+            return null;
+        return this.export(profile.lexiconFormat, profile.lexiconAlphabet);
+    }
+    /** `pls`, `google`, or `json`. */
+    export(fmt, alphabet = "ipa") {
+        if (fmt === "pls")
+            return this.toPls(alphabet);
+        if (fmt === "google")
+            return this.toGoogleJson();
+        if (fmt === "json")
+            return this.toJson();
+        throw new Error(`unknown lexicon format ${JSON.stringify(fmt)}; use pls, google or json`);
+    }
+}

package/dist/pipeline.d.ts

@@ -0,0 +1,34 @@
+/** The pipeline: clean -> verbalize -> compile -> chunk, with a change log. */
+import { Change } from "./changes.js";
+import { Options } from "./clean.js";
+import { EntryInput, Lexicon } from "./lexicon.js";
+import { Profile } from "./profiles/index.js";
+import "./verbalize/en.js";
+import "./verbalize/tr.js";
+export interface Prepared {
+    /** The full compiled text. */
+    text: string;
+    /** The same text split under the model's request limit. */
+    chunks: string[];
+    /** Every rewrite: rule, before, after, note. */
+    changes: Change[];
+    profile: Profile;
+    locale: string;
+}
+export interface PrepareInit {
+    provider?: string | null;
+    model?: string | null;
+    /** A profile picked directly; overrides provider and model. */
+    profile?: Profile | null;
+    locale?: string;
+    /** Overrides the profile's request limit (null = no limit, undefined = the profile's). */
+    limit?: number | null;
+    options?: Partial<Options> | null;
+    /** A Lexicon, or its entries; its words are pronounced as it says. */
+    lexicon?: Lexicon | EntryInput[] | null;
+}
+/** Prepare `text` for the given provider and model.
+ *
+ * Returns the full compiled text, the request-sized chunks, and every change made.
+ */
+export declare function prepare(text: string, init?: PrepareInit): Prepared;

package/dist/pipeline.js

@@ -0,0 +1,49 @@
+/** The pipeline: clean -> verbalize -> compile -> chunk, with a change log. */
+import { Recorder } from "./changes.js";
+import { pack, splitSentences } from "./chunk.js";
+import { clean } from "./clean.js";
+import { compileText } from "./compile.js";
+import { extract, sentinelPattern } from "./intents.js";
+import { Lexicon } from "./lexicon.js";
+import { resolveProfile } from "./profiles/index.js";
+import { sub } from "./util.js";
+import { verbalize } from "./verbalize/index.js";
+import "./verbalize/en.js";
+import "./verbalize/tr.js";
+/** Prepare `text` for the given provider and model.
+ *
+ * Returns the full compiled text, the request-sized chunks, and every change made.
+ */
+export function prepare(text, init = {}) {
+    const locale = init.locale ?? "en-US";
+    const lex = Array.isArray(init.lexicon) ? Lexicon.fromEntries(init.lexicon, locale) : init.lexicon ?? null;
+    const prof = init.profile ?? resolveProfile(init.provider ?? null, init.model ?? null);
+    const rec = new Recorder();
+    let [work, intents] = extract(text);
+    work = clean(work, init.options, rec, locale);
+    [work, intents] = extract(work, intents);
+    if (lex) {
+        const before = work;
+        work = lex.apply(work, intents);
+        rec.add("lexicon", "lexicon.apply", before, work, "lexicon words marked for pronunciation");
+    }
+    work = verbalize(work, locale, rec, init.options);
+    work = compileText(work, intents, prof, rec);
+    const maxSize = init.limit !== undefined ? init.limit : prof.limitFor(init.model ?? null);
+    const sentences = splitSentences(work, locale);
+    const chunks = pack(sentences, maxSize, prof.limitUnit, " ");
+    return { text: work, chunks, changes: readable(rec.changes, intents), profile: prof, locale };
+}
+function intentTag(intent) {
+    if (intent.kind === "pause")
+        return `[pause ${intent.ms}ms]`;
+    if (intent.kind === "phoneme")
+        return `[ipa ${intent.text} ${intent.ipa || intent.say}]`;
+    return `[${intent.kind} ${intent.text}]`;
+}
+/** Show intents in the change log as the tags the developer wrote, not as sentinels. */
+function readable(changes, intents) {
+    const pattern = sentinelPattern();
+    const fix = (text) => sub(pattern, text, (m) => intentTag(intents[parseInt(m[1], 10)]));
+    return changes.map((c) => ({ ...c, before: fix(c.before), after: fix(c.after) }));
+}

package/dist/profiles/data.d.ts

@@ -0,0 +1 @@
+export declare const PROFILE_DATA: Record<string, unknown>[];