@pipedog/core 0.1.0 → 0.2.0

package/dist/utils/text/transforms/index.js

@@ -0,0 +1,42 @@
+// Copyright (c) 2024-2026, Daily
+// Copyright (c) 2026, pipedog contributors
+// SPDX-License-Identifier: BSD-2-Clause
+//
+// Ported from pipecat: src/pipecat/utils/text/transforms/__init__.py
+/**
+ * Built-in text transformers for TTS voice formatting.
+ *
+ * Transformers are async callables with signature:
+ *
+ * ```ts
+ * async function transform(text: string, textType: string): Promise<string>
+ * ```
+ *
+ * They are registered with a TTS service via `textTransforms`:
+ *
+ * ```ts
+ * const tts = new CartesiaTTSService({
+ *   textTransforms: [["*", stripMarkdown], ["*", expandCurrency]],
+ * });
+ * ```
+ *
+ * Or use `VoiceFormatter` for a single configurable bundle:
+ *
+ * ```ts
+ * const tts = new CartesiaTTSService({
+ *   textTransforms: [["*", new VoiceFormatter({ expandCurrency: true })]],
+ * });
+ * ```
+ */
+export { normalizeAcronyms } from "./acronyms.js";
+export { expandCurrency } from "./currency.js";
+export { normalizeDates } from "./dates.js";
+export { emailToSpeech } from "./email.js";
+export { expandNumbers } from "./numbers.js";
+export { expandPercentages } from "./percentages.js";
+export { expandPhoneNumbers } from "./phone.js";
+export { replaceText } from "./replacements.js";
+export { stripMarkdown } from "./strip_markdown.js";
+export { expandUnits } from "./units.js";
+export { VoiceFormatter } from "./voice_formatter.js";
+//# sourceMappingURL=index.js.map

package/dist/utils/text/transforms/numbers.d.ts

@@ -0,0 +1,25 @@
+import type { TextType } from "../../../frames/frames.ts";
+/**
+ * Return a transform that expands numbers to their spoken form.
+ *
+ * When `digitCutoff` is set, numbers above it are read digit-by-digit
+ * (e.g. `"2026"` → `"2 0 2 6"`). Numbers at or below the cutoff are
+ * expanded as quantities (e.g. `"42"` → `"forty two"`). Pass `null`
+ * to expand all numbers as words regardless of magnitude.
+ *
+ * Decimals are read as the whole part followed by their fractional digits, one at a
+ * time, so every written digit is spoken (`"1.0"` → `"one point zero"`).
+ *
+ * @param digitCutoff Numbers larger than this value are read digit-by-digit.
+ *   `null` disables the cutoff so every number is expanded as a word.
+ * @returns An async transform callable compatible with `textTransforms`.
+ *
+ * @example
+ * ```ts
+ * const transform = expandNumbers(2025);
+ * const result = await transform("Room 42 has 1234 seats and opens in 2026", "*");
+ * // "Room forty two has one thousand two hundred thirty four seats and opens in 2 0 2 6"
+ * ```
+ */
+export declare function expandNumbers(digitCutoff?: number | bigint | null): (text: string, textType: string | TextType) => Promise<string>;
+//# sourceMappingURL=numbers.d.ts.map

package/dist/utils/text/transforms/numbers.js

@@ -0,0 +1,59 @@
+// Copyright (c) 2024-2026, Daily
+// Copyright (c) 2026, pipedog contributors
+// SPDX-License-Identifier: BSD-2-Clause
+//
+// Ported from pipecat: src/pipecat/utils/text/transforms/numbers.py
+/** Expand numeric expressions into spoken form for TTS. */
+import { num2words } from "num2words-ts";
+import { toAsciiDigits } from "../unicode_digits.js";
+// Matches integers and decimals, with optional thousand separators.
+// Python's `\b` (next to a digit here) is Unicode-aware; the lookarounds
+// rebuild it with Unicode `\w` (letters, digits and underscore).
+// `\p{Nd}` is Python's Unicode `\d`; toAsciiDigits() lets BigInt/Number parse what int()/float() accept.
+const NUMBER_RE = /(?<![\p{L}\p{N}_])(\p{Nd}{1,3}(?:,\p{Nd}{3})*|\p{Nd}+)(?:\.(\p{Nd}+))?(?![\p{L}\p{N}_])/gu;
+/**
+ * Return a transform that expands numbers to their spoken form.
+ *
+ * When `digitCutoff` is set, numbers above it are read digit-by-digit
+ * (e.g. `"2026"` → `"2 0 2 6"`). Numbers at or below the cutoff are
+ * expanded as quantities (e.g. `"42"` → `"forty two"`). Pass `null`
+ * to expand all numbers as words regardless of magnitude.
+ *
+ * Decimals are read as the whole part followed by their fractional digits, one at a
+ * time, so every written digit is spoken (`"1.0"` → `"one point zero"`).
+ *
+ * @param digitCutoff Numbers larger than this value are read digit-by-digit.
+ *   `null` disables the cutoff so every number is expanded as a word.
+ * @returns An async transform callable compatible with `textTransforms`.
+ *
+ * @example
+ * ```ts
+ * const transform = expandNumbers(2025);
+ * const result = await transform("Room 42 has 1234 seats and opens in 2026", "*");
+ * // "Room forty two has one thousand two hundred thirty four seats and opens in 2 0 2 6"
+ * ```
+ */
+export function expandNumbers(digitCutoff = 2025) {
+    const numToWords = (wholeMatch, fracStr) => {
+        const wholeStr = wholeMatch.replaceAll(",", "");
+        const whole = BigInt(toAsciiDigits(wholeStr));
+        if (digitCutoff !== null && whole > digitCutoff) {
+            let result = [...wholeStr].join(" ");
+            if (fracStr) {
+                result += ` point ${[...fracStr].join(" ")}`;
+            }
+            return result;
+        }
+        if (fracStr) {
+            // Reading the fraction one digit at a time keeps trailing zeros audible,
+            // which also keeps a decimal agreeing with the plural unit expandUnits
+            // picks for it ("1.0 kilometers").
+            return `${num2words(whole, { lang: "en" })} point ${[...fracStr]
+                .map((digit) => num2words(Number(toAsciiDigits(digit)), { lang: "en" }))
+                .join(" ")}`;
+        }
+        return num2words(whole, { lang: "en" });
+    };
+    return async (text, _textType) => text.replace(NUMBER_RE, (_match, whole, frac) => numToWords(whole, frac));
+}
+//# sourceMappingURL=numbers.js.map

package/dist/utils/text/transforms/percentages.d.ts

@@ -0,0 +1,16 @@
+import type { TextType } from "../../../frames/frames.ts";
+/**
+ * Expand percentage expressions to their spoken form.
+ *
+ * @param text Input text possibly containing percentage expressions.
+ * @param _textType Text type of the text frame (unused).
+ * @returns Text with percentages replaced by spoken equivalents.
+ *
+ * @example
+ * ```ts
+ * const result = await expandPercentages("50% off today", "*");
+ * // "fifty percent off today"
+ * ```
+ */
+export declare function expandPercentages(text: string, _textType: string | TextType): Promise<string>;
+//# sourceMappingURL=percentages.d.ts.map

package/dist/utils/text/transforms/percentages.js

@@ -0,0 +1,32 @@
+// Copyright (c) 2024-2026, Daily
+// Copyright (c) 2026, pipedog contributors
+// SPDX-License-Identifier: BSD-2-Clause
+//
+// Ported from pipecat: src/pipecat/utils/text/transforms/percentages.py
+/** Expand percentage expressions into spoken form for TTS. */
+import { asFloat, num2words } from "num2words-ts";
+import { toAsciiDigits } from "../unicode_digits.js";
+// `\p{Nd}` is Python's Unicode `\d`; toAsciiDigits() lets BigInt/Number parse what int()/float() accept.
+const PERCENT_RE = /(\p{Nd}+(?:\.\p{Nd}+)?)\s*%/gu;
+function percentToWords(value) {
+    // Upstream converts with `float(value)`, so "50" reads as the float 50.0.
+    const numberStr = num2words(asFloat(Number.parseFloat(toAsciiDigits(value))), { lang: "en" });
+    return `${numberStr} percent`;
+}
+/**
+ * Expand percentage expressions to their spoken form.
+ *
+ * @param text Input text possibly containing percentage expressions.
+ * @param _textType Text type of the text frame (unused).
+ * @returns Text with percentages replaced by spoken equivalents.
+ *
+ * @example
+ * ```ts
+ * const result = await expandPercentages("50% off today", "*");
+ * // "fifty percent off today"
+ * ```
+ */
+export async function expandPercentages(text, _textType) {
+    return text.replace(PERCENT_RE, (_match, value) => percentToWords(value));
+}
+//# sourceMappingURL=percentages.js.map

package/dist/utils/text/transforms/phone.d.ts

@@ -0,0 +1,21 @@
+/** Expand phone numbers into space-separated digit sequences for TTS. */
+import type { TextType } from "../../../frames/frames.ts";
+/**
+ * Space out phone number digits so TTS reads them individually.
+ *
+ * This transformer is alphanumeric-preserving: digits are kept, only separators
+ * change to spaces, so the `WordCompletionTracker` requires no segment-map
+ * overhead.
+ *
+ * @param text Input text possibly containing phone numbers.
+ * @param _textType Text type of the text frame (unused).
+ * @returns Text with phone numbers replaced by space-separated digit sequences.
+ *
+ * @example
+ * ```ts
+ * const result = await expandPhoneNumbers("Call 123-456-7890 now", "*");
+ * // "Call 1 2 3 4 5 6 7 8 9 0 now"
+ * ```
+ */
+export declare function expandPhoneNumbers(text: string, _textType: string | TextType): Promise<string>;
+//# sourceMappingURL=phone.d.ts.map

package/dist/utils/text/transforms/phone.js

@@ -0,0 +1,39 @@
+// Copyright (c) 2024-2026, Daily
+// Copyright (c) 2026, pipedog contributors
+// SPDX-License-Identifier: BSD-2-Clause
+//
+// Ported from pipecat: src/pipecat/utils/text/transforms/phone.py
+// Matches common phone formats: (123) 456-7890, 123-456-7890, 123.456.7890,
+// +1 800 555 1234, etc.
+const PHONE_RE = new RegExp("(?<!\\p{Nd})" + // not preceded by a digit (no partial match inside a longer number)
+    "(\\+?1[\\s.\\-]?)?" + // optional country code
+    "(\\(?\\p{Nd}{3}\\)?[\\s.\\-]?)" + // area code
+    "(\\p{Nd}{3}[\\s.\\-]?)" + // exchange
+    "(\\p{Nd}{4})" + // subscriber
+    "(?!\\p{Nd})", // not followed by a digit
+"gu");
+function spaceDigits(match) {
+    const digits = match.replace(/\P{Nd}/gu, "");
+    return [...digits].join(" ");
+}
+/**
+ * Space out phone number digits so TTS reads them individually.
+ *
+ * This transformer is alphanumeric-preserving: digits are kept, only separators
+ * change to spaces, so the `WordCompletionTracker` requires no segment-map
+ * overhead.
+ *
+ * @param text Input text possibly containing phone numbers.
+ * @param _textType Text type of the text frame (unused).
+ * @returns Text with phone numbers replaced by space-separated digit sequences.
+ *
+ * @example
+ * ```ts
+ * const result = await expandPhoneNumbers("Call 123-456-7890 now", "*");
+ * // "Call 1 2 3 4 5 6 7 8 9 0 now"
+ * ```
+ */
+export async function expandPhoneNumbers(text, _textType) {
+    return text.replace(PHONE_RE, (match) => spaceDigits(match));
+}
+//# sourceMappingURL=phone.js.map

package/dist/utils/text/transforms/pronunciations.js

@@ -93,7 +93,8 @@ export function pronunciationTransform(pronunciations, formatPronunciation, opti
     }
     let pattern = null;
     if (phonemes.size > 0) {
-        const words = [...phonemes.keys()].sort((a, b) => b.length - a.length);
+        // Python's `len` counts code points, not UTF-16 units.
+        const words = [...phonemes.keys()].sort((a, b) => [...b].length - [...a].length);
         // Python's Unicode `\w` is letters, digits and underscore.
         pattern = new RegExp(`(?<![\\p{L}\\p{N}_-])(?:${words.map(escapeRegex).join("|")})(?![\\p{L}\\p{N}_-])`, "giu");
     }

package/dist/utils/text/transforms/replacements.d.ts

@@ -0,0 +1,39 @@
+/**
+ * User-defined text replacements for TTS preprocessing.
+ *
+ * Porting notes: patterns are JavaScript regular expressions (a `RegExp`, or a
+ * string compiled with `new RegExp(pattern, "g")`), and replacement strings use
+ * JavaScript's `String.prototype.replace` syntax (`$1`, `$<name>`) rather than
+ * Python's (`\1`, `\g<name>`). Every match is replaced, as Python's `re.sub`
+ * does, whether or not a `RegExp` carries the `g` flag.
+ */
+import type { TextType } from "../../../frames/frames.ts";
+/** A find-and-replace rule: `(regexPattern, replacementString)`. */
+export type TextReplacement = readonly [pattern: string | RegExp, replacement: string];
+/**
+ * Return a transform that applies a list of find-and-replace rules.
+ *
+ * Each rule is a `(pattern, replacement)` tuple. Patterns are treated as
+ * regular expressions; escape special characters for literal string matching.
+ *
+ * Rules are applied in the order provided. Whether the resulting transform is
+ * alphanumeric-preserving depends on the replacements supplied.
+ *
+ * Patterns are compiled at construction time so invalid regex patterns raise
+ * `SyntaxError` immediately rather than during live TTS processing.
+ *
+ * @param replacements Ordered list of `(regexPattern, replacementString)` pairs.
+ * @returns An async transform callable compatible with `textTransforms`.
+ *
+ * @example
+ * ```ts
+ * const transform = replaceText([
+ *   [/\bDr\./, "Doctor"],
+ *   [/\bSt\./, "Street"],
+ *   [/\bvs\b/, "versus"],
+ * ]);
+ * const tts = new CartesiaTTSService({ textTransforms: [["*", transform]] });
+ * ```
+ */
+export declare function replaceText(replacements: readonly TextReplacement[]): (text: string, textType: string | TextType) => Promise<string>;
+//# sourceMappingURL=replacements.d.ts.map

package/dist/utils/text/transforms/replacements.js

@@ -0,0 +1,46 @@
+// Copyright (c) 2024-2026, Daily
+// Copyright (c) 2026, pipedog contributors
+// SPDX-License-Identifier: BSD-2-Clause
+//
+// Ported from pipecat: src/pipecat/utils/text/transforms/replacements.py
+function compile(pattern) {
+    if (typeof pattern === "string")
+        return new RegExp(pattern, "g");
+    return pattern.global ? new RegExp(pattern) : new RegExp(pattern, `${pattern.flags}g`);
+}
+/**
+ * Return a transform that applies a list of find-and-replace rules.
+ *
+ * Each rule is a `(pattern, replacement)` tuple. Patterns are treated as
+ * regular expressions; escape special characters for literal string matching.
+ *
+ * Rules are applied in the order provided. Whether the resulting transform is
+ * alphanumeric-preserving depends on the replacements supplied.
+ *
+ * Patterns are compiled at construction time so invalid regex patterns raise
+ * `SyntaxError` immediately rather than during live TTS processing.
+ *
+ * @param replacements Ordered list of `(regexPattern, replacementString)` pairs.
+ * @returns An async transform callable compatible with `textTransforms`.
+ *
+ * @example
+ * ```ts
+ * const transform = replaceText([
+ *   [/\bDr\./, "Doctor"],
+ *   [/\bSt\./, "Street"],
+ *   [/\bvs\b/, "versus"],
+ * ]);
+ * const tts = new CartesiaTTSService({ textTransforms: [["*", transform]] });
+ * ```
+ */
+export function replaceText(replacements) {
+    const compiled = replacements.map(([pattern, replacement]) => [compile(pattern), replacement]);
+    return async (text, _textType) => {
+        for (const [pattern, replacement] of compiled) {
+            pattern.lastIndex = 0;
+            text = text.replace(pattern, replacement);
+        }
+        return text;
+    };
+}
+//# sourceMappingURL=replacements.js.map

package/dist/utils/text/transforms/strip_markdown.d.ts

@@ -0,0 +1,25 @@
+/** Strip Markdown formatting symbols before TTS synthesis. */
+import type { TextType } from "../../../frames/frames.ts";
+/**
+ * Remove Markdown formatting symbols that have no spoken equivalent.
+ *
+ * Strips bold/italic markers, backtick code spans, fenced code blocks, ATX
+ * headers, and blockquote markers. Does not modify link or image syntax since
+ * those may carry meaningful text (the link label is preserved verbatim).
+ *
+ * This transformer is alphanumeric-preserving: the normalized alnum sequence of
+ * the output is identical to the input, so the `WordCompletionTracker`
+ * requires no segment-map overhead.
+ *
+ * @param text Input text, potentially containing Markdown formatting.
+ * @param _textType Text type of the text frame (unused).
+ * @returns Text with Markdown formatting symbols removed.
+ *
+ * @example
+ * ```ts
+ * const result = await stripMarkdown("**Hello** and _world_", "*");
+ * // "Hello and world"
+ * ```
+ */
+export declare function stripMarkdown(text: string, _textType: string | TextType): Promise<string>;
+//# sourceMappingURL=strip_markdown.d.ts.map

package/dist/utils/text/transforms/strip_markdown.js

@@ -0,0 +1,60 @@
+// Copyright (c) 2024-2026, Daily
+// Copyright (c) 2026, pipedog contributors
+// SPDX-License-Identifier: BSD-2-Clause
+//
+// Ported from pipecat: src/pipecat/utils/text/transforms/strip_markdown.py
+// Translation notes for the patterns below:
+// - Python's `.` matches anything but `\n` (JS's also skips `\r`, U+2028 and
+//   U+2029), so it is written `[^\n]`.
+// - Python's `re.MULTILINE` `^` / `$` only break lines at `\n` (JS's `m` flag
+//   also breaks at `\r`, U+2028 and U+2029), so they are written
+//   `(?<![^\n])` / `(?![^\n])`.
+// - Python's `\b` is Unicode-aware; next to `_` (a word character) it becomes a
+//   lookaround on Unicode `\w` (letters, digits and underscore).
+const W = "[\\p{L}\\p{N}_]";
+const keepGroup = (_match, inner) => inner;
+/**
+ * Remove Markdown formatting symbols that have no spoken equivalent.
+ *
+ * Strips bold/italic markers, backtick code spans, fenced code blocks, ATX
+ * headers, and blockquote markers. Does not modify link or image syntax since
+ * those may carry meaningful text (the link label is preserved verbatim).
+ *
+ * This transformer is alphanumeric-preserving: the normalized alnum sequence of
+ * the output is identical to the input, so the `WordCompletionTracker`
+ * requires no segment-map overhead.
+ *
+ * @param text Input text, potentially containing Markdown formatting.
+ * @param _textType Text type of the text frame (unused).
+ * @returns Text with Markdown formatting symbols removed.
+ *
+ * @example
+ * ```ts
+ * const result = await stripMarkdown("**Hello** and _world_", "*");
+ * // "Hello and world"
+ * ```
+ */
+export async function stripMarkdown(text, _textType) {
+    // Fenced code blocks (``` or ~~~)
+    text = text.replace(/```[\s\S]*?```/g, "");
+    text = text.replace(/~~~[\s\S]*?~~~/g, "");
+    // Inline code
+    text = text.replace(/`([^`]+)`/g, keepGroup);
+    // Bold+italic ***text*** or ___text___
+    text = text.replace(/\*{3}([^\n]+?)\*{3}/g, keepGroup);
+    text = text.replace(/_{3}([^\n]+?)_{3}/g, keepGroup);
+    // Bold **text** or __text__
+    text = text.replace(/\*{2}([^\n]+?)\*{2}/g, keepGroup);
+    text = text.replace(/_{2}([^\n]+?)_{2}/g, keepGroup);
+    // Italic *text* or _text_
+    text = text.replace(/\*([^\n]+?)\*/g, keepGroup);
+    text = text.replace(new RegExp(`(?<!${W})_([^\\n]+?)_(?!${W})`, "gu"), keepGroup);
+    // ATX headers (# ## ### etc.)
+    text = text.replace(/(?<![^\n])#{1,6}\s+/g, "");
+    // Blockquotes
+    text = text.replace(/(?<![^\n])>\s?/g, "");
+    // Horizontal rules
+    text = text.replace(/(?<![^\n])\s*[-*_]{3,}\s*(?![^\n])/g, "");
+    return text;
+}
+//# sourceMappingURL=strip_markdown.js.map

package/dist/utils/text/transforms/units.d.ts

@@ -0,0 +1,22 @@
+/** Expand unit abbreviations into their spoken form for TTS. */
+import type { TextType } from "../../../frames/frames.ts";
+/**
+ * Expand unit abbreviations to their full spoken form.
+ *
+ * A quantity of exactly one takes the singular form of the unit.
+ *
+ * @param text Input text possibly containing unit expressions.
+ * @param _textType Text type of the text frame (unused).
+ * @returns Text with unit abbreviations replaced by spoken equivalents.
+ *
+ * @example
+ * ```ts
+ * const result = await expandUnits("Run 5km at 100kph", "*");
+ * // "Run 5 kilometers at 100 kilometers per hour"
+ *
+ * const result2 = await expandUnits("Only 1km left", "*");
+ * // "Only 1 kilometer left"
+ * ```
+ */
+export declare function expandUnits(text: string, _textType: string | TextType): Promise<string>;
+//# sourceMappingURL=units.d.ts.map

package/dist/utils/text/transforms/units.js

@@ -0,0 +1,81 @@
+// Copyright (c) 2024-2026, Daily
+// Copyright (c) 2026, pipedog contributors
+// SPDX-License-Identifier: BSD-2-Clause
+//
+// Ported from pipecat: src/pipecat/utils/text/transforms/units.py
+/** Maps unit abbreviation to (singular, plural) spoken forms. */
+const UNIT_MAP = {
+    km: ["kilometer", "kilometers"],
+    m: ["meter", "meters"],
+    cm: ["centimeter", "centimeters"],
+    mm: ["millimeter", "millimeters"],
+    mi: ["mile", "miles"],
+    ft: ["foot", "feet"],
+    in: ["inch", "inches"],
+    yd: ["yard", "yards"],
+    kg: ["kilogram", "kilograms"],
+    g: ["gram", "grams"],
+    mg: ["milligram", "milligrams"],
+    lb: ["pound", "pounds"],
+    oz: ["ounce", "ounces"],
+    l: ["liter", "liters"],
+    ml: ["milliliter", "milliliters"],
+    mph: ["mile per hour", "miles per hour"],
+    kph: ["kilometer per hour", "kilometers per hour"],
+    kmh: ["kilometer per hour", "kilometers per hour"],
+    gb: ["gigabyte", "gigabytes"],
+    mb: ["megabyte", "megabytes"],
+    kb: ["kilobyte", "kilobytes"],
+    tb: ["terabyte", "terabytes"],
+    hz: ["hertz", "hertz"],
+    khz: ["kilohertz", "kilohertz"],
+    mhz: ["megahertz", "megahertz"],
+    ghz: ["gigahertz", "gigahertz"],
+};
+// Single-letter units that are also common English words: only expand when
+// they appear immediately after a digit with no intervening space, e.g. "5m"
+// but not "1 m people" (where "m" is a word) or "1 in 5" (preposition).
+const AMBIGUOUS_UNITS = new Set(["in", "m", "g", "l"]);
+// A stable sort, like Python's `sorted`, so equal lengths keep insertion order.
+const sortedUnambiguous = Object.keys(UNIT_MAP)
+    .filter((u) => !AMBIGUOUS_UNITS.has(u))
+    .sort((a, b) => b.length - a.length);
+const sortedAmbiguous = [...AMBIGUOUS_UNITS].sort((a, b) => b.length - a.length);
+// Python's `\b` (after a unit letter here) is Unicode-aware; the lookahead
+// rebuilds it with Unicode `\w` (letters, digits and underscore). The unit
+// names are plain letters, so they need no escaping.
+const W = "[\\p{L}\\p{N}_]";
+// Unambiguous units allow optional whitespace between the number and the unit.
+const UNIT_RE = new RegExp(`(\\p{Nd}+(?:\\.\\p{Nd}+)?)\\s*(${sortedUnambiguous.join("|")})(?!${W})`, "giu");
+// Ambiguous units require the unit to follow the digit with no space.
+const AMBIGUOUS_UNIT_RE = new RegExp(`(\\p{Nd}+(?:\\.\\p{Nd}+)?)(${sortedAmbiguous.join("|")})(?!${W})`, "giu");
+/**
+ * Expand unit abbreviations to their full spoken form.
+ *
+ * A quantity of exactly one takes the singular form of the unit.
+ *
+ * @param text Input text possibly containing unit expressions.
+ * @param _textType Text type of the text frame (unused).
+ * @returns Text with unit abbreviations replaced by spoken equivalents.
+ *
+ * @example
+ * ```ts
+ * const result = await expandUnits("Run 5km at 100kph", "*");
+ * // "Run 5 kilometers at 100 kilometers per hour"
+ *
+ * const result2 = await expandUnits("Only 1km left", "*");
+ * // "Only 1 kilometer left"
+ * ```
+ */
+export async function expandUnits(text, _textType) {
+    const replace = (_match, number, unit) => {
+        // Python indexes the map directly; every match is a key once lowercased.
+        const [singular, plural] = UNIT_MAP[unit.toLowerCase()];
+        // Only a bare "1" takes the singular; a decimal such as "1.0" reads as
+        // plural in speech.
+        return `${number} ${number === "1" ? singular : plural}`;
+    };
+    text = text.replace(UNIT_RE, replace);
+    return text.replace(AMBIGUOUS_UNIT_RE, replace);
+}
+//# sourceMappingURL=units.js.map

package/dist/utils/text/transforms/voice_formatter.d.ts

@@ -0,0 +1,86 @@
+/**
+ * Configurable voice formatting bundle for TTS preprocessing.
+ *
+ * Porting notes: upstream imports each transform lazily inside `__init__`;
+ * here they are imported statically (they have no optional dependencies).
+ */
+import type { TextType } from "../../../frames/frames.ts";
+import { type TextReplacement } from "./replacements.ts";
+type Transform = (text: string, textType: string | TextType) => Promise<string>;
+export interface VoiceFormatterOptions {
+    /**
+     * Strip Markdown formatting symbols (bold, italic, headers, code spans).
+     * Enabled by default.
+     */
+    stripMarkdown?: boolean;
+    /** Space out phone number digits for individual pronunciation. Enabled by default. */
+    expandPhoneNumbers?: boolean;
+    /** Space out uppercase acronyms (e.g. `"API"` → `"A P I"`). Enabled by default. */
+    normalizeAcronyms?: boolean;
+    /**
+     * Expand currency amounts to spoken form (e.g. `"$42.50"` →
+     * `"forty two dollars and fifty cents"`). Requires `num2words`.
+     */
+    expandCurrency?: boolean;
+    /**
+     * Expand numeric digits to spoken words. Disabled by default since it can
+     * affect numbers that are better read as digits. Requires `num2words`.
+     */
+    expandNumbers?: boolean;
+    /**
+     * Numbers above this value are read digit-by-digit instead of as a
+     * quantity. Defaults to null (expand all numbers as words). Only used when
+     * `expandNumbers` is true.
+     */
+    numberDigitCutoff?: number | bigint | null;
+    /** Expand percentage expressions (e.g. `"50%"` → `"fifty percent"`). Requires `num2words`. */
+    expandPercentages?: boolean;
+    /** Expand unit abbreviations (e.g. `"5km"` → `"5 kilometers"`). Enabled by default. */
+    expandUnits?: boolean;
+    /** Transform email addresses to spoken form. Enabled by default. */
+    emailToSpeech?: boolean;
+    /** Expand date expressions to spoken form. Requires `num2words`. */
+    normalizeDates?: boolean;
+    /** List of `(regexPattern, replacement)` pairs applied after all other transforms. */
+    customReplacements?: readonly TextReplacement[] | null;
+}
+export interface VoiceFormatter {
+    (text: string, textType: string | TextType): Promise<string>;
+}
+/**
+ * Configurable bundle that applies a pipeline of voice-formatting transforms.
+ *
+ * Each option enables or disables one transform. Transforms are applied in a
+ * deliberate order: structural cleanup first, language expansions second, user
+ * replacements last.
+ *
+ * @example
+ * ```ts
+ * const formatter = new VoiceFormatter({
+ *   stripMarkdown: true,
+ *   expandCurrency: true,
+ *   numberDigitCutoff: 2025,
+ *   customReplacements: [[/\bDr\./, "Doctor"]],
+ * });
+ * const tts = new CartesiaTTSService({
+ *   textTransforms: [["*", formatter]],
+ * });
+ * ```
+ */
+export declare class VoiceFormatter {
+    protected _transforms: Transform[];
+    /** Initialize the voice formatter. */
+    constructor(options?: VoiceFormatterOptions);
+    /**
+     * Apply all configured transforms in order.
+     *
+     * Python's `__call__`; calling the instance runs this.
+     *
+     * @param text Input text to transform.
+     * @param textType Text type passed through to each transform.
+     * @returns Transformed text ready for TTS synthesis.
+     */
+    transform(text: string, textType: string | TextType): Promise<string>;
+}
+export {};
+//# sourceMappingURL=voice_formatter.d.ts.map