@pipedog/core 0.0.0 → 0.2.0

package/dist/utils/text/skip_tags_aggregator.js

@@ -0,0 +1,147 @@
+// Copyright (c) 2024-2026, Daily
+// Copyright (c) 2026, pipedog contributors
+// SPDX-License-Identifier: BSD-2-Clause
+//
+// Ported from pipecat: src/pipecat/utils/text/skip_tags_aggregator.py
+/**
+ * Skip tags aggregator for preventing sentence boundaries within tagged content.
+ *
+ * This module provides a text aggregator that prevents end-of-sentence matching
+ * between specified start/end tag pairs, ensuring that tagged content is processed
+ * as a unit regardless of internal punctuation.
+ */
+import { longestTrailingPartialMatch, parseStartEndTags } from "../string.js";
+import { Aggregation, TextType } from "./base_text_aggregator.js";
+import { SimpleTextAggregator, } from "./simple_text_aggregator.js";
+/**
+ * Aggregator that prevents end of sentence matching between start/end tags.
+ *
+ * This aggregator buffers text until it finds an end of sentence or a start
+ * tag. If a start tag is found the aggregator will keep aggregating text
+ * unconditionally until the corresponding end tag is found. It's particularly
+ * useful for processing content with custom delimiters that should prevent
+ * text from being considered for end of sentence matching.
+ *
+ * The aggregator ensures that tags spanning multiple text chunks are correctly
+ * identified and that content within tags is never split at sentence boundaries.
+ */
+export class SkipTagsAggregator extends SimpleTextAggregator {
+    _tags;
+    _currentTag;
+    _currentTagIndex;
+    /**
+     * Initialize the skip tags aggregator.
+     *
+     * @param options.tags Tag pairs that should prevent sentence boundary detection.
+     *   Other options are passed to SimpleTextAggregator (e.g. aggregationType).
+     */
+    constructor(options) {
+        super(options);
+        this._tags = options.tags;
+        this._currentTag = null;
+        this._currentTagIndex = 0;
+    }
+    /**
+     * Aggregate text while respecting tag boundaries.
+     *
+     * Processes the input text character-by-character, updates tag state, and
+     * uses the parent's lookahead logic for sentence detection when not
+     * inside tags.
+     *
+     * In TOKEN mode, text is passed through immediately unless we're inside
+     * a tag, in which case we buffer until the closing tag is found. Text
+     * ending in a partial start tag (e.g. `<spe` of `<spell>`) is held
+     * back until a later chunk determines whether it begins a tag, so a tag
+     * split across chunks is still recognized.
+     *
+     * @param text Text to aggregate.
+     * @returns Aggregation objects containing text up to a sentence boundary,
+     *   marked as SENTENCE type (or TOKEN type in TOKEN mode).
+     */
+    async *aggregate(text) {
+        if (this._aggregationType === TextType.TOKEN) {
+            // In TOKEN mode, process chars for tag tracking but yield the
+            // full input as a single token when not inside a tag.
+            for (const char of text) {
+                this._text += char;
+                // Update tag state
+                [this._currentTag, this._currentTagIndex] = parseStartEndTags(this._text, this._tags, this._currentTag, this._currentTagIndex);
+            }
+            // After processing all chars: if not inside a tag, yield accumulated text.
+            // A trailing partial start tag (e.g. "<spe" of "<spell>") is held back
+            // so a tag split across chunks isn't leaked as plain text; it's retained
+            // in the buffer to be completed by the next chunk. The tag-scan index
+            // resets to 0 so the retained partial tag is rescanned once complete.
+            if (!this._currentTag && this._text) {
+                const heldBack = longestTrailingPartialMatch(this._text, this._tags.map(([start]) => start));
+                const yieldLength = this._text.length - heldBack;
+                if (yieldLength > 0) {
+                    const content = this._text.slice(0, yieldLength);
+                    this._text = this._text.slice(yieldLength);
+                    this._currentTagIndex = 0;
+                    yield new Aggregation({ text: content, type: TextType.TOKEN });
+                }
+            }
+            return;
+        }
+        // Process text character by character
+        for (const char of text) {
+            this._text += char;
+            // Update tag state
+            [this._currentTag, this._currentTagIndex] = parseStartEndTags(this._text, this._tags, this._currentTag, this._currentTagIndex);
+            // If inside tags, don't check for sentences
+            if (this._currentTag) {
+                continue;
+            }
+            // Otherwise, use parent's lookahead logic for sentence detection
+            const result = await super._checkSentenceWithLookahead(char);
+            if (result) {
+                yield result;
+            }
+        }
+    }
+    /**
+     * Flush any remaining text in the buffer.
+     *
+     * In SENTENCE mode, returns the buffered text as-is: tags are
+     * pass-through markers, so content is spoken whether or not a start
+     * tag's closing tag ever arrived. In TOKEN mode, returns any text
+     * still buffered behind an unclosed tag instead of discarding it.
+     *
+     * @returns Any remaining text, or null if the buffer is empty.
+     */
+    async flush() {
+        if (this._aggregationType === TextType.TOKEN) {
+            if (this._text) {
+                const result = this._text;
+                await this.reset();
+                return new Aggregation({ text: result, type: TextType.TOKEN });
+            }
+            return null;
+        }
+        return await super.flush();
+    }
+    /**
+     * Handle interruptions by clearing the buffer and tag state.
+     *
+     * Called when an interruption occurs in the processing pipeline,
+     * to reset the state and discard any partially aggregated text.
+     */
+    async handleInterruption() {
+        await super.handleInterruption();
+        this._currentTag = null;
+        this._currentTagIndex = 0;
+    }
+    /**
+     * Clear the internally aggregated text and tag state.
+     *
+     * Resets the aggregator to its initial state, discarding any
+     * buffered text.
+     */
+    async reset() {
+        await super.reset();
+        this._currentTag = null;
+        this._currentTagIndex = 0;
+    }
+}
+//# sourceMappingURL=skip_tags_aggregator.js.map

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

@@ -0,0 +1,21 @@
+/** Normalize acronyms so TTS pronounces each letter individually. */
+import type { TextType } from "../../../frames/frames.ts";
+/**
+ * Insert spaces between letters of uppercase acronyms.
+ *
+ * This transformer is alphanumeric-preserving: the same letters are kept,
+ * only spaces are added between them, so the `WordCompletionTracker`
+ * requires no segment-map overhead.
+ *
+ * @param text Input text possibly containing acronyms like API or HTTP.
+ * @param _textType Text type of the text frame (unused).
+ * @returns Text with acronyms letter-spaced (e.g. `"API"` → `"A P I"`).
+ *
+ * @example
+ * ```ts
+ * const result = await normalizeAcronyms("Use the API or HTTP endpoint", "*");
+ * // "Use the A P I or H T T P endpoint"
+ * ```
+ */
+export declare function normalizeAcronyms(text: string, _textType: string | TextType): Promise<string>;
+//# sourceMappingURL=acronyms.d.ts.map

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

@@ -0,0 +1,31 @@
+// Copyright (c) 2024-2026, Daily
+// Copyright (c) 2026, pipedog contributors
+// SPDX-License-Identifier: BSD-2-Clause
+//
+// Ported from pipecat: src/pipecat/utils/text/transforms/acronyms.py
+// Two or more consecutive uppercase letters not immediately followed by a lowercase
+// letter (to avoid splitting CamelCase words like "iPhone" or "McDonalds").
+// Python's `\b` is Unicode-aware; the lookarounds rebuild it with Unicode `\w`
+// (letters, digits and underscore).
+const ACRONYM_RE = /(?<![\p{L}\p{N}_])[A-Z]{2,}(?![a-z])(?![\p{L}\p{N}_])/gu;
+/**
+ * Insert spaces between letters of uppercase acronyms.
+ *
+ * This transformer is alphanumeric-preserving: the same letters are kept,
+ * only spaces are added between them, so the `WordCompletionTracker`
+ * requires no segment-map overhead.
+ *
+ * @param text Input text possibly containing acronyms like API or HTTP.
+ * @param _textType Text type of the text frame (unused).
+ * @returns Text with acronyms letter-spaced (e.g. `"API"` → `"A P I"`).
+ *
+ * @example
+ * ```ts
+ * const result = await normalizeAcronyms("Use the API or HTTP endpoint", "*");
+ * // "Use the A P I or H T T P endpoint"
+ * ```
+ */
+export async function normalizeAcronyms(text, _textType) {
+    return text.replace(ACRONYM_RE, (match) => [...match].join(" "));
+}
+//# sourceMappingURL=acronyms.js.map

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

@@ -0,0 +1,16 @@
+import type { TextType } from "../../../frames/frames.ts";
+/**
+ * Expand currency amounts to their spoken form.
+ *
+ * @param text Input text possibly containing currency expressions.
+ * @param _textType Text type of the text frame (unused).
+ * @returns Text with currency amounts replaced by spoken equivalents.
+ *
+ * @example
+ * ```ts
+ * const result = await expandCurrency("Your balance is $42.50", "*");
+ * // "Your balance is forty-two dollars and fifty cents"
+ * ```
+ */
+export declare function expandCurrency(text: string, _textType: string | TextType): Promise<string>;
+//# sourceMappingURL=currency.d.ts.map

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

@@ -0,0 +1,56 @@
+// Copyright (c) 2024-2026, Daily
+// Copyright (c) 2026, pipedog contributors
+// SPDX-License-Identifier: BSD-2-Clause
+//
+// Ported from pipecat: src/pipecat/utils/text/transforms/currency.py
+/** Expand currency amounts into spoken form for TTS. */
+import { num2words } from "num2words-ts";
+import { toAsciiDigits } from "../unicode_digits.js";
+/** Maps currency symbol to (singular, plural, cents_singular, cents_plural). */
+const CURRENCY_MAP = {
+    $: ["dollar", "dollars", "cent", "cents"],
+    "€": ["euro", "euros", "cent", "cents"],
+    "£": ["pound", "pounds", "penny", "pence"],
+    "¥": ["yen", "yen", null, null],
+    "₹": ["rupee", "rupees", "paisa", "paise"],
+};
+// Python's `\b` (after a digit here) is Unicode-aware; the lookahead rebuilds
+// 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 CURRENCY_RE = /([€£¥₹$])\s*(\p{Nd}{1,3}(?:,\p{Nd}{3})*|\p{Nd}+)(?![\p{L}\p{N}_])(?:\.(\p{Nd}+))?/gu;
+function amountToWords(n, singular, plural) {
+    const words = num2words(n, { lang: "en" });
+    const unit = n === 1n ? singular : plural;
+    return `${words} ${unit}`;
+}
+function currencyMatch(symbol, wholeMatch, fracStr) {
+    const wholeStr = wholeMatch.replaceAll(",", "");
+    const currency = CURRENCY_MAP[symbol] ?? ["unit", "units", "cent", "cents"];
+    const [singular, plural, cSingular, cPlural] = currency;
+    const whole = BigInt(toAsciiDigits(wholeStr));
+    let result = amountToWords(whole, singular, plural);
+    if (fracStr && cSingular && cPlural) {
+        const frac = BigInt(toAsciiDigits(fracStr.slice(0, 2).padEnd(2, "0")));
+        if (frac > 0n) {
+            result += ` and ${amountToWords(frac, cSingular, cPlural)}`;
+        }
+    }
+    return result;
+}
+/**
+ * Expand currency amounts to their spoken form.
+ *
+ * @param text Input text possibly containing currency expressions.
+ * @param _textType Text type of the text frame (unused).
+ * @returns Text with currency amounts replaced by spoken equivalents.
+ *
+ * @example
+ * ```ts
+ * const result = await expandCurrency("Your balance is $42.50", "*");
+ * // "Your balance is forty-two dollars and fifty cents"
+ * ```
+ */
+export async function expandCurrency(text, _textType) {
+    return text.replace(CURRENCY_RE, (_match, symbol, whole, frac) => currencyMatch(symbol, whole, frac));
+}
+//# sourceMappingURL=currency.js.map

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

@@ -0,0 +1,18 @@
+import type { TextType } from "../../../frames/frames.ts";
+/**
+ * Expand date expressions to their spoken form.
+ *
+ * Handles ISO format (`YYYY-MM-DD`) and US format (`MM/DD/YYYY` or `MM-DD-YYYY`).
+ *
+ * @param text Input text possibly containing date expressions.
+ * @param _textType Text type of the text frame (unused).
+ * @returns Text with date expressions replaced by spoken equivalents.
+ *
+ * @example
+ * ```ts
+ * const result = await normalizeDates("Meeting on 2023-05-10", "*");
+ * // "Meeting on May 10th, two thousand and twenty three"
+ * ```
+ */
+export declare function normalizeDates(text: string, _textType: string | TextType): Promise<string>;
+//# sourceMappingURL=dates.d.ts.map

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

@@ -0,0 +1,102 @@
+// Copyright (c) 2024-2026, Daily
+// Copyright (c) 2026, pipedog contributors
+// SPDX-License-Identifier: BSD-2-Clause
+//
+// Ported from pipecat: src/pipecat/utils/text/transforms/dates.py
+/** Expand date expressions into spoken form for TTS. */
+import { num2words } from "num2words-ts";
+import { toAsciiDigits } from "../unicode_digits.js";
+const pyInt = (digits) => Number(toAsciiDigits(digits));
+// Python's `\b` (next to a digit here) is Unicode-aware; the lookarounds
+// rebuild it with Unicode `\w` (letters, digits and underscore).
+// ISO dates: 2023-05-10
+// `\p{Nd}` is Python's Unicode `\d`; toAsciiDigits() lets BigInt/Number parse what int()/float() accept.
+const ISO_DATE_RE = /(?<![\p{L}\p{N}_])(\p{Nd}{4})-(\p{Nd}{2})-(\p{Nd}{2})(?![\p{L}\p{N}_])/gu;
+// US dates: 05/10/2023 or 05-10-2023 (not matched by ISO because ISO has 4-digit year first)
+const US_DATE_RE = /(?<![\p{L}\p{N}_])(\p{Nd}{1,2})[/-](\p{Nd}{1,2})[/-](\p{Nd}{4})(?![\p{L}\p{N}_])/gu;
+const ORDINAL_SUFFIXES = { 1: "st", 2: "nd", 3: "rd" };
+// Indexed by month - 1. Hardcoded rather than derived from strftime("%B"), which
+// renders the month in the process's LC_TIME locale and would produce a
+// mixed-language result alongside the English year and ordinal suffix.
+const MONTH_NAMES = [
+    "January",
+    "February",
+    "March",
+    "April",
+    "May",
+    "June",
+    "July",
+    "August",
+    "September",
+    "October",
+    "November",
+    "December",
+];
+function ordinal(n) {
+    const key = [11, 12, 13].includes(n % 100) ? 0 : n % 10;
+    const suffix = ORDINAL_SUFFIXES[key] ?? "th";
+    return `${n}${suffix}`;
+}
+/**
+ * Build a date like Python's `datetime(year, month, day)`.
+ *
+ * @throws RangeError for an out-of-range year, month or day (Python's `ValueError`).
+ */
+function makeDate(year, month, day) {
+    if (year < 1 || year > 9999)
+        throw new RangeError(`year ${year} is out of range`);
+    if (month < 1 || month > 12)
+        throw new RangeError("month must be in 1..12");
+    const leap = (year % 4 === 0 && year % 100 !== 0) || year % 400 === 0;
+    const daysInMonth = [31, leap ? 29 : 28, 31, 30, 31, 30, 31, 31, 30, 31, 30, 31][month - 1];
+    if (day < 1 || day > daysInMonth)
+        throw new RangeError("day is out of range for month");
+    return { year, month, day };
+}
+function dateToSpoken(dt) {
+    const yearWords = num2words(dt.year, { lang: "en" });
+    const month = MONTH_NAMES[dt.month - 1];
+    const day = ordinal(dt.day);
+    return `${month} ${day}, ${yearWords}`;
+}
+function isoReplace(match, year, month, day) {
+    try {
+        return dateToSpoken(makeDate(pyInt(year), pyInt(month), pyInt(day)));
+    }
+    catch (e) {
+        if (e instanceof RangeError)
+            return match;
+        throw e;
+    }
+}
+function usReplace(match, month, day, year) {
+    try {
+        return dateToSpoken(makeDate(pyInt(year), pyInt(month), pyInt(day)));
+    }
+    catch (e) {
+        if (e instanceof RangeError)
+            return match;
+        throw e;
+    }
+}
+/**
+ * Expand date expressions to their spoken form.
+ *
+ * Handles ISO format (`YYYY-MM-DD`) and US format (`MM/DD/YYYY` or `MM-DD-YYYY`).
+ *
+ * @param text Input text possibly containing date expressions.
+ * @param _textType Text type of the text frame (unused).
+ * @returns Text with date expressions replaced by spoken equivalents.
+ *
+ * @example
+ * ```ts
+ * const result = await normalizeDates("Meeting on 2023-05-10", "*");
+ * // "Meeting on May 10th, two thousand and twenty three"
+ * ```
+ */
+export async function normalizeDates(text, _textType) {
+    text = text.replace(ISO_DATE_RE, isoReplace);
+    text = text.replace(US_DATE_RE, usReplace);
+    return text;
+}
+//# sourceMappingURL=dates.js.map

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

@@ -0,0 +1,17 @@
+/** Transform email addresses into spoken form for TTS. */
+import type { TextType } from "../../../frames/frames.ts";
+/**
+ * Transform email addresses into their spoken form.
+ *
+ * @param text Input text possibly containing email addresses.
+ * @param _textType Text type of the text frame (unused).
+ * @returns Text with email addresses replaced by spoken equivalents.
+ *
+ * @example
+ * ```ts
+ * const result = await emailToSpeech("Contact user@example.com today", "*");
+ * // "Contact user at example dot com today"
+ * ```
+ */
+export declare function emailToSpeech(text: string, _textType: string | TextType): Promise<string>;
+//# sourceMappingURL=email.d.ts.map

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

@@ -0,0 +1,35 @@
+// Copyright (c) 2024-2026, Daily
+// Copyright (c) 2026, pipedog contributors
+// SPDX-License-Identifier: BSD-2-Clause
+//
+// Ported from pipecat: src/pipecat/utils/text/transforms/email.py
+const EMAIL_RE = /[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\.[a-zA-Z]{2,}/g;
+function emailToSpoken(email) {
+    const at = email.indexOf("@");
+    const local = email.slice(0, at);
+    const domain = email.slice(at + 1);
+    const localSpoken = local
+        .replaceAll(".", " dot ")
+        .replaceAll("_", " underscore ")
+        .replaceAll("-", " dash ")
+        .replaceAll("+", " plus ");
+    const domainSpoken = domain.replaceAll(".", " dot ").replaceAll("-", " dash ");
+    return `${localSpoken} at ${domainSpoken}`;
+}
+/**
+ * Transform email addresses into their spoken form.
+ *
+ * @param text Input text possibly containing email addresses.
+ * @param _textType Text type of the text frame (unused).
+ * @returns Text with email addresses replaced by spoken equivalents.
+ *
+ * @example
+ * ```ts
+ * const result = await emailToSpeech("Contact user@example.com today", "*");
+ * // "Contact user at example dot com today"
+ * ```
+ */
+export async function emailToSpeech(text, _textType) {
+    return text.replace(EMAIL_RE, (match) => emailToSpoken(match));
+}
+//# sourceMappingURL=email.js.map

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

@@ -0,0 +1,37 @@
+/**
+ * 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.ts";
+export { expandCurrency } from "./currency.ts";
+export { normalizeDates } from "./dates.ts";
+export { emailToSpeech } from "./email.ts";
+export { expandNumbers } from "./numbers.ts";
+export { expandPercentages } from "./percentages.ts";
+export { expandPhoneNumbers } from "./phone.ts";
+export { replaceText } from "./replacements.ts";
+export { stripMarkdown } from "./strip_markdown.ts";
+export { expandUnits } from "./units.ts";
+export { VoiceFormatter } from "./voice_formatter.ts";
+//# sourceMappingURL=index.d.ts.map

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