@pipedog/core 0.0.0 → 0.2.0

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.d.ts

@@ -0,0 +1,65 @@
+/**
+ * Replace words with a TTS service's pronunciation markup.
+ *
+ * Applications usually reach this through a service's
+ * `TTSService.pronunciationTransformIpa` static method, which supplies the
+ * service's own formatter.
+ */
+import type { TextType } from "../../../frames/frames.ts";
+/** Turns `(word, ipa)` into the text to send, or null when it cannot. */
+export type PronunciationFormatter = (word: string, ipa: string) => string | null;
+/** Returns the text to send in place of a match. */
+export type PronunciationReplacer = (match: RegExpExecArray) => string;
+export interface PronunciationTransform {
+    (text: string, textType: string | TextType): Promise<string>;
+}
+/**
+ * A text transform that replaces words with a service's pronunciation markup.
+ *
+ * TTS services recognize it among their `textTransforms` and skip it while
+ * they cannot read pronunciation markup (see `TTSService.supportsPronunciations`),
+ * so the words are spoken as written.
+ */
+export declare class PronunciationTransform {
+    protected _pattern: RegExp | null;
+    protected _replace: PronunciationReplacer;
+    /**
+     * Initialize the transform.
+     *
+     * @param pattern Matches the words to replace, or null when there are none.
+     * @param replace Returns the text to send in place of a match.
+     */
+    constructor(pattern: RegExp | null, replace: PronunciationReplacer);
+    /**
+     * Replace every matched word in `text`.
+     *
+     * Python's `__call__`; calling the instance runs this.
+     *
+     * @param text The text about to be sent to the service.
+     * @param _textType The text type of the text (unused).
+     * @returns The text with each matched word replaced.
+     */
+    transform(text: string, _textType: string | TextType): string;
+}
+/**
+ * Return a transform that replaces each word with its formatted pronunciation.
+ *
+ * Words match whole and case-insensitively, longest first, and never as part
+ * of a longer or hyphenated word. The matched text is passed to the formatter,
+ * so markup that keeps the word (such as an SSML `<phoneme>` tag) keeps it as
+ * written.
+ *
+ * Every pronunciation is formatted once here, so one the service cannot use
+ * is reported when the transform is built rather than while speaking. Those
+ * words are left out and spoken as written.
+ *
+ * @param pronunciations Word to IPA, e.g. `{ Metformin: "mɛtˈfɔɹmɪn" }`.
+ * @param formatPronunciation Turns `(word, ipa)` into the text to send, or
+ *   null when it cannot.
+ * @param options.serviceName Name used in the warning for unusable pronunciations.
+ * @returns A transform to register with `textTransforms`.
+ */
+export declare function pronunciationTransform(pronunciations: Readonly<Record<string, string>>, formatPronunciation: PronunciationFormatter, options?: {
+    serviceName?: string;
+}): PronunciationTransform;
+//# sourceMappingURL=pronunciations.d.ts.map

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

@@ -0,0 +1,112 @@
+// Copyright (c) 2024-2026, Daily
+// Copyright (c) 2026, pipedog contributors
+// SPDX-License-Identifier: BSD-2-Clause
+//
+// Ported from pipecat: src/pipecat/utils/text/transforms/pronunciations.py
+import { logger } from "../../logger.js";
+/**
+ * A text transform that replaces words with a service's pronunciation markup.
+ *
+ * TTS services recognize it among their `textTransforms` and skip it while
+ * they cannot read pronunciation markup (see `TTSService.supportsPronunciations`),
+ * so the words are spoken as written.
+ */
+// biome-ignore lint/suspicious/noUnsafeDeclarationMerging: adds Python's `__call__` signature to the class.
+export class PronunciationTransform {
+    _pattern;
+    _replace;
+    /**
+     * Initialize the transform.
+     *
+     * @param pattern Matches the words to replace, or null when there are none.
+     * @param replace Returns the text to send in place of a match.
+     */
+    constructor(pattern, replace) {
+        const call = async (text, textType) => self.transform(text, textType);
+        const self = Object.setPrototypeOf(call, new.target.prototype);
+        self._pattern = pattern;
+        self._replace = replace;
+        // biome-ignore lint/correctness/noConstructorReturn: returning the callable is the point (see above).
+        return self;
+    }
+    /**
+     * Replace every matched word in `text`.
+     *
+     * Python's `__call__`; calling the instance runs this.
+     *
+     * @param text The text about to be sent to the service.
+     * @param _textType The text type of the text (unused).
+     * @returns The text with each matched word replaced.
+     */
+    transform(text, _textType) {
+        const pattern = this._pattern;
+        if (!pattern)
+            return text;
+        pattern.lastIndex = 0;
+        return text.replace(pattern, (...args) => {
+            // `replace` passes (match, ...groups, offset, input); rebuild an exec array.
+            const match = [args[0]];
+            return this._replace(match);
+        });
+    }
+}
+/** Python's `re.escape` for a JS (`u`-flag) regular expression. */
+function escapeRegex(text) {
+    return text.replace(/[.*+?^${}()|[\]\\/]/g, "\\$&");
+}
+/**
+ * Return a transform that replaces each word with its formatted pronunciation.
+ *
+ * Words match whole and case-insensitively, longest first, and never as part
+ * of a longer or hyphenated word. The matched text is passed to the formatter,
+ * so markup that keeps the word (such as an SSML `<phoneme>` tag) keeps it as
+ * written.
+ *
+ * Every pronunciation is formatted once here, so one the service cannot use
+ * is reported when the transform is built rather than while speaking. Those
+ * words are left out and spoken as written.
+ *
+ * @param pronunciations Word to IPA, e.g. `{ Metformin: "mɛtˈfɔɹmɪn" }`.
+ * @param formatPronunciation Turns `(word, ipa)` into the text to send, or
+ *   null when it cannot.
+ * @param options.serviceName Name used in the warning for unusable pronunciations.
+ * @returns A transform to register with `textTransforms`.
+ */
+export function pronunciationTransform(pronunciations, formatPronunciation, options = {}) {
+    const serviceName = options.serviceName ?? "TTS service";
+    const phonemes = new Map();
+    const unusable = [];
+    for (const [rawWord, value] of Object.entries(pronunciations)) {
+        const word = rawWord.trim();
+        if (!word)
+            continue;
+        if (formatPronunciation(word, value) === null) {
+            unusable.push(word);
+        }
+        else {
+            phonemes.set(word.toLowerCase(), value);
+        }
+    }
+    if (unusable.length > 0) {
+        logger.warning(`${serviceName} cannot use these IPA pronunciations, so they ` +
+            `will be spoken as written: ${unusable.join(", ")}`);
+    }
+    let pattern = null;
+    if (phonemes.size > 0) {
+        // 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");
+    }
+    const replace = (match) => {
+        const word = match[0];
+        // Python indexes the dict directly; a case-folding mismatch would raise
+        // there, here the word is kept as written.
+        const ipa = phonemes.get(word.toLowerCase());
+        if (ipa === undefined)
+            return word;
+        return formatPronunciation(word, ipa) || word;
+    };
+    return new PronunciationTransform(pattern, replace);
+}
+//# sourceMappingURL=pronunciations.js.map

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