@leiboss/dsh-tts 0.0.0-stage → 0.3.0

package/dist/audio-route.js

@@ -0,0 +1,408 @@
+/**
+ * Same-origin HTTP route for generated audio.
+ *
+ * The DSH Web host owns the HTTP server; this module only registers a prefix
+ * route on the host `webServer` service (never listens on its own port). URLs
+ * carry an HMAC-signed, expiring token that names a file *relative to the
+ * configured output directory*, so a token can never be turned into an
+ * arbitrary path read. Range requests are answered with `206 Partial Content`,
+ * which is what lets an `<audio>` element seek inside a long file.
+ */
+import { createHmac, randomBytes, timingSafeEqual } from 'node:crypto';
+import { chmodSync, createReadStream, mkdirSync, readFileSync, writeFileSync, } from 'node:fs';
+import { stat } from 'node:fs/promises';
+import { dirname, extname, isAbsolute, join, relative, resolve } from 'node:path';
+/** Path prefix owned by this plugin. The signed token is the next segment. */
+export const AUDIO_ROUTE_PREFIX = '/dsh-tts/audio';
+/** Signed URLs stay valid for six hours by default. */
+export const DEFAULT_URL_TTL_MS = 6 * 60 * 60 * 1000;
+/** Name of the persisted HMAC secret inside the output directory. */
+export const SECRET_FILE_NAME = '.audio-route-secret';
+/** Longest suffix accepted by {@link parseRange}; keeps the parser simple. */
+const RANGE_PATTERN = /^bytes=(\d*)-(\d*)$/;
+function parseRange(header, size) {
+    const match = RANGE_PATTERN.exec(header.trim());
+    if (!match)
+        return undefined;
+    const startRaw = match[1] ?? '';
+    const endRaw = match[2] ?? '';
+    if (startRaw === '' && endRaw === '')
+        return undefined;
+    if (startRaw === '') {
+        const suffix = Number(endRaw);
+        if (!Number.isInteger(suffix) || suffix <= 0)
+            return undefined;
+        const start = Math.max(0, size - suffix);
+        return { start, end: size - 1 };
+    }
+    const start = Number(startRaw);
+    if (!Number.isInteger(start) || start < 0 || start >= size)
+        return undefined;
+    const end = endRaw === '' ? size - 1 : Number(endRaw);
+    if (!Number.isInteger(end) || end < start)
+        return undefined;
+    return { start, end: Math.min(end, size - 1) };
+}
+function sendText(res, status, message, headers = {}) {
+    const body = Buffer.from(message, 'utf8');
+    res.statusCode = status;
+    res.setHeader('Content-Type', 'text/plain; charset=utf-8');
+    res.setHeader('Content-Length', String(body.length));
+    for (const [name, value] of Object.entries(headers)) {
+        res.setHeader(name, value);
+    }
+    res.end(body);
+}
+function headerValue(value) {
+    return Array.isArray(value) ? value[0] : value;
+}
+/**
+ * Hostnames trusted by default for a bind address. Wildcard binds accept any
+ * hostname (the port and same-origin checks still apply), because the public
+ * hostname is not knowable from `0.0.0.0`.
+ */
+function defaultAllowedHosts(host) {
+    const normalized = host.replace(/^\[|\]$/g, '').toLowerCase();
+    if (normalized === '0.0.0.0' || normalized === '::' || normalized === '*') {
+        return [];
+    }
+    return [...new Set(['localhost', '127.0.0.1', '::1', normalized])];
+}
+function isLoopbackHost(host) {
+    if (host === undefined)
+        return true;
+    const normalized = host.replace(/^\[|\]$/g, '').toLowerCase();
+    return (normalized === '' ||
+        normalized === 'localhost' ||
+        normalized === '::1' ||
+        normalized.startsWith('127.'));
+}
+function describe(error) {
+    return error instanceof Error ? error.message : String(error);
+}
+/**
+ * Load the persisted HMAC secret, creating it on first use. Persistence keeps
+ * previously issued URLs valid across plugin reloads. Any filesystem failure
+ * degrades to an in-memory secret instead of failing plugin load.
+ */
+function loadOrCreateSecret(path, debug) {
+    try {
+        const hex = readFileSync(path, 'utf8').trim();
+        if (/^[0-9a-f]{64}$/i.test(hex))
+            return Buffer.from(hex, 'hex');
+        debug?.('audio route secret was malformed; rotating');
+    }
+    catch (error) {
+        const code = typeof error === 'object' && error !== null && 'code' in error
+            ? error.code
+            : undefined;
+        if (code !== 'ENOENT') {
+            debug?.(`audio route secret read failed: ${describe(error)}`);
+        }
+    }
+    const secret = randomBytes(32);
+    try {
+        mkdirSync(dirname(path), { recursive: true });
+        writeFileSync(path, secret.toString('hex'), { encoding: 'utf8', mode: 0o600 });
+        try {
+            chmodSync(path, 0o600);
+        }
+        catch {
+            // Windows does not implement POSIX modes; best effort only.
+        }
+    }
+    catch (error) {
+        debug?.(`audio route secret persistence failed: ${describe(error)}`);
+    }
+    return secret;
+}
+/**
+ * Owns the signed-token format and the HTTP handler. One instance per plugin
+ * load; `register` binds it to the host router and returns a disposer.
+ */
+export class AudioRoute {
+    root;
+    prefix;
+    ttlMs;
+    secret;
+    now;
+    debug;
+    trustedHosts;
+    connection;
+    allowedHosts;
+    expectedPort;
+    skipPortCheck = false;
+    active = false;
+    origin;
+    constructor(options) {
+        this.root = resolve(options.outputDir);
+        this.prefix = options.prefix ?? AUDIO_ROUTE_PREFIX;
+        this.ttlMs = options.ttlMs ?? DEFAULT_URL_TTL_MS;
+        this.now = options.now ?? Date.now;
+        this.debug = options.debug;
+        this.connection = options.connection;
+        this.trustedHosts = (options.trustedHosts ?? [])
+            .map((host) => host.trim().toLowerCase())
+            .filter((host) => host.length > 0);
+        this.allowedHosts = options.allowedHosts;
+        this.expectedPort = options.expectedPort;
+        this.secret =
+            options.secret ??
+                loadOrCreateSecret(options.secretPath ?? join(this.root, SECRET_FILE_NAME), this.debug);
+    }
+    /** True once the host router accepted the route. */
+    get registered() {
+        return this.active;
+    }
+    /** Register on the DSH host router; the disposer unregisters and disables URLs. */
+    register(server) {
+        const remote = this.connection?.allowsRemoteAuthorities === true;
+        if (this.trustedHosts.length > 0) {
+            // A configured whitelist implies a proxy that may rewrite the port.
+            this.allowedHosts = this.trustedHosts;
+            this.skipPortCheck = true;
+        }
+        else if (remote && !isLoopbackHost(server.host)) {
+            this.allowedHosts = [];
+            this.skipPortCheck = true;
+            this.debug?.('audio route relaxed Host checks for remote authorities');
+        }
+        else if (this.expectedPort === undefined) {
+            this.expectedPort = server.port;
+            if (this.allowedHosts === undefined && server.host) {
+                this.allowedHosts = defaultAllowedHosts(server.host);
+            }
+        }
+        const dispose = server.register({
+            kind: 'prefix',
+            path: this.prefix,
+            handler: (req, res) => this.handle(req, res),
+        });
+        this.active = true;
+        let disposed = false;
+        return () => {
+            if (disposed)
+                return;
+            disposed = true;
+            this.active = false;
+            dispose();
+        };
+    }
+    /**
+     * Browser-openable same-origin URL, or `undefined` when the route is not
+     * registered or the file is outside the output directory / not an MP3.
+     */
+    urlFor(filePath) {
+        if (!this.active)
+            return undefined;
+        const relativePath = this.relativePath(filePath);
+        if (relativePath === undefined)
+            return undefined;
+        const expires = Math.ceil((this.now() + this.ttlMs) / 1000);
+        const encoded = Buffer.from(relativePath, 'utf8').toString('base64url');
+        const payload = `${expires}.${encoded}`;
+        return `${this.prefix}/${payload}.${this.sign(payload)}`;
+    }
+    /** Remember the host-advertised origin, trimmed of any trailing slash. */
+    setOrigin(origin) {
+        const trimmed = origin.trim().replace(/\/+$/, '');
+        if (trimmed.length > 0)
+            this.origin = trimmed;
+    }
+    /**
+     * Absolute playback URL for humans, or `undefined` when the host did not
+     * advertise an origin. Never guesses a host: callers fall back to the
+     * relative {@link urlFor} result instead.
+     */
+    absoluteUrlFor(filePath) {
+        const relative = this.urlFor(filePath);
+        if (relative === undefined || this.origin === undefined)
+            return undefined;
+        return `${this.origin}${relative}`;
+    }
+    /** Serve one request. Exported behaviour is exercised directly by tests. */
+    async handle(req, res) {
+        const method = req.method ?? 'GET';
+        if (method !== 'GET' && method !== 'HEAD') {
+            sendText(res, 405, 'Method Not Allowed', { Allow: 'GET, HEAD' });
+            return;
+        }
+        const rejection = this.connection?.requestRejection?.({
+            headers: req.headers,
+        });
+        if (rejection === 401 || rejection === 403) {
+            this.debug?.(`audio route rejected by host connection: ${rejection}`);
+            sendText(res, rejection, rejection === 401 ? 'Unauthorized' : 'Forbidden');
+            return;
+        }
+        const originRejection = this.checkOrigin(req);
+        if (originRejection !== undefined) {
+            this.debug?.(`audio route rejected: ${originRejection}`);
+            sendText(res, 403, 'Forbidden');
+            return;
+        }
+        const rawUrl = req.url ?? '';
+        const query = rawUrl.indexOf('?');
+        const pathname = query === -1 ? rawUrl : rawUrl.slice(0, query);
+        if (!pathname.startsWith(`${this.prefix}/`)) {
+            sendText(res, 404, 'Not Found');
+            return;
+        }
+        let token;
+        try {
+            token = decodeURIComponent(pathname.slice(this.prefix.length + 1));
+        }
+        catch {
+            sendText(res, 404, 'Not Found');
+            return;
+        }
+        const target = this.verify(token);
+        if (target === undefined) {
+            sendText(res, 404, 'Not Found');
+            return;
+        }
+        let size;
+        try {
+            const info = await stat(target);
+            if (!info.isFile() || info.size <= 0) {
+                sendText(res, 404, 'Not Found');
+                return;
+            }
+            size = info.size;
+        }
+        catch {
+            sendText(res, 404, 'Not Found');
+            return;
+        }
+        const header = req.headers.range;
+        const rangeHeader = Array.isArray(header) ? header[0] : header;
+        let range;
+        if (rangeHeader !== undefined) {
+            range = parseRange(rangeHeader, size);
+            if (range === undefined) {
+                sendText(res, 416, 'Range Not Satisfiable', {
+                    'Content-Range': `bytes */${size}`,
+                });
+                return;
+            }
+        }
+        res.setHeader('Content-Type', 'audio/mpeg');
+        res.setHeader('Accept-Ranges', 'bytes');
+        res.setHeader('Cache-Control', 'private, max-age=300');
+        if (range === undefined) {
+            res.statusCode = 200;
+            res.setHeader('Content-Length', String(size));
+        }
+        else {
+            res.statusCode = 206;
+            res.setHeader('Content-Range', `bytes ${range.start}-${range.end}/${size}`);
+            res.setHeader('Content-Length', String(range.end - range.start + 1));
+        }
+        if (method === 'HEAD') {
+            res.end();
+            return;
+        }
+        const stream = createReadStream(target, range);
+        stream.on('error', () => {
+            res.destroy();
+        });
+        stream.pipe(res);
+    }
+    /** HMAC-SHA-256 over the payload, base64url-encoded. */
+    sign(payload) {
+        return createHmac('sha256', this.secret).update(payload, 'utf8').digest('base64url');
+    }
+    /**
+     * Same-origin fence in front of the token check. Returns a reason when the
+     * request must be rejected. Missing headers are tolerated only when neither
+     * a port nor an Origin pins the request to a browser origin, which keeps
+     * non-browser callers working while DSH provides no trust-fence API.
+     */
+    checkOrigin(req) {
+        const host = headerValue(req.headers.host);
+        const origin = headerValue(req.headers.origin);
+        if (host === undefined) {
+            return origin === undefined ? undefined : 'origin present without host';
+        }
+        let parsed;
+        try {
+            parsed = new URL(`http://${host}`);
+        }
+        catch {
+            return 'malformed host header';
+        }
+        const hostname = parsed.hostname.replace(/^\[|\]$/g, '').toLowerCase();
+        if (this.allowedHosts !== undefined &&
+            this.allowedHosts.length > 0 &&
+            !this.allowedHosts.includes(hostname)) {
+            return `untrusted host ${hostname}`;
+        }
+        if (this.expectedPort !== undefined && !this.skipPortCheck) {
+            const port = parsed.port === ''
+                ? parsed.protocol === 'https:'
+                    ? 443
+                    : 80
+                : Number(parsed.port);
+            if (port !== this.expectedPort) {
+                return `host port ${port} does not match ${this.expectedPort}`;
+            }
+        }
+        if (origin !== undefined) {
+            let parsedOrigin;
+            try {
+                parsedOrigin = new URL(origin);
+            }
+            catch {
+                return 'malformed origin header';
+            }
+            if (parsedOrigin.protocol !== 'http:' &&
+                parsedOrigin.protocol !== 'https:') {
+                return `unsupported origin scheme ${parsedOrigin.protocol}`;
+            }
+            if (parsedOrigin.host.toLowerCase() !== host.toLowerCase()) {
+                return 'origin and host differ';
+            }
+        }
+        return undefined;
+    }
+    /** Path relative to the ledger root, using `/` on every platform. */
+    relativePath(filePath) {
+        if (extname(filePath).toLowerCase() !== '.mp3')
+            return undefined;
+        const target = resolve(filePath);
+        const rel = relative(this.root, target);
+        if (rel === '' || rel.startsWith('..') || isAbsolute(rel))
+            return undefined;
+        return rel.split('\\').join('/');
+    }
+    /** Verify signature + expiry, then confine the decoded path to the root. */
+    verify(token) {
+        const segments = token.split('.');
+        if (segments.length !== 3)
+            return undefined;
+        const expiresRaw = segments[0] ?? '';
+        const encoded = segments[1] ?? '';
+        const signature = segments[2] ?? '';
+        if (!expiresRaw || !encoded || !signature)
+            return undefined;
+        const expected = Buffer.from(this.sign(`${expiresRaw}.${encoded}`), 'utf8');
+        const actual = Buffer.from(signature, 'utf8');
+        if (expected.length !== actual.length || !timingSafeEqual(expected, actual)) {
+            return undefined;
+        }
+        const expires = Number(expiresRaw);
+        if (!Number.isFinite(expires) || this.now() > expires * 1000)
+            return undefined;
+        const rel = Buffer.from(encoded, 'base64url').toString('utf8');
+        if (rel.length === 0 || rel.includes('\u0000'))
+            return undefined;
+        const target = resolve(this.root, rel);
+        const check = relative(this.root, target);
+        if (check === '' || check.startsWith('..') || isAbsolute(check))
+            return undefined;
+        if (extname(target).toLowerCase() !== '.mp3')
+            return undefined;
+        return target;
+    }
+}
+//# sourceMappingURL=audio-route.js.map

package/dist/audio-route.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"audio-route.js","sourceRoot":"","sources":["../src/audio-route.ts"],"names":[],"mappings":"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"}

package/dist/cache.d.ts

@@ -0,0 +1,50 @@
+/** Audio container Edge-TTS writes. */
+export declare const AUDIO_FORMAT = "mp3";
+/**
+ * Stable cache key for one synthesis request. The first 16 hex characters of
+ * SHA-256 are enough to name a file while keeping names short.
+ */
+export declare function cacheKey(text: string, voice: string, rate: string): string;
+/** Local-calendar `YYYY-MM-DD` bucket for a timestamp. */
+export declare function dateDirName(date?: Date): string;
+/**
+ * Target path for a fresh synthesis: `<outputDir>/<date>/<hash>-<epochMs>.mp3`.
+ * The timestamp keeps concurrent first-time syntheses from colliding.
+ */
+export declare function outputFilePath(outputDir: string, hash: string, date?: Date): string;
+/**
+ * Diagnostic record stored next to a finished MP3. It never participates in
+ * cache lookup; it only lets a later cache hit report which engine produced
+ * the file (for example `sapi` after a fallback).
+ */
+export interface CacheMetadata {
+    engine: string;
+    voice: string;
+    rate: string;
+    pitch: string;
+    volume: string;
+    createdAt: string;
+    /**
+     * Word timings the backend reported. Persisted so a later cache hit keeps
+     * exact subtitle timing instead of silently degrading to an estimate.
+     */
+    words?: {
+        text: string;
+        offsetMs: number;
+        durationMs: number;
+    }[];
+}
+/** Sidecar path for one audio file. */
+export declare function metadataPath(filePath: string): string;
+/** Best-effort metadata write; diagnostics must never fail synthesis. */
+export declare function writeCacheMetadata(filePath: string, metadata: CacheMetadata): Promise<void>;
+/** Read a sidecar, treating missing, unreadable, or malformed data as absent. */
+export declare function readCacheMetadata(filePath: string): Promise<CacheMetadata | undefined>;
+/**
+ * Find an existing non-empty file for `hash`, newest date bucket first. Only
+ * files carrying the exact key prefix and a positive size qualify, so a
+ * partial or unrelated file never satisfies the cache. The `.mp3.json`
+ * sidecars and the `.audio-route-secret` file never match this filter.
+ */
+export declare function findCachedFile(outputDir: string, hash: string): Promise<string | undefined>;
+//# sourceMappingURL=cache.d.ts.map

package/dist/cache.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cache.d.ts","sourceRoot":"","sources":["../src/cache.ts"],"names":[],"mappings":"AAOA,uCAAuC;AACvC,eAAO,MAAM,YAAY,QAAQ,CAAA;AAEjC;;;GAGG;AACH,wBAAgB,QAAQ,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,CAK1E;AAED,0DAA0D;AAC1D,wBAAgB,WAAW,CAAC,IAAI,GAAE,IAAiB,GAAG,MAAM,CAK3D;AAED;;;GAGG;AACH,wBAAgB,cAAc,CAC5B,SAAS,EAAE,MAAM,EACjB,IAAI,EAAE,MAAM,EACZ,IAAI,GAAE,IAAiB,GACtB,MAAM,CAER;AAED;;;;GAIG;AACH,MAAM,WAAW,aAAa;IAC5B,MAAM,EAAE,MAAM,CAAA;IACd,KAAK,EAAE,MAAM,CAAA;IACb,IAAI,EAAE,MAAM,CAAA;IACZ,KAAK,EAAE,MAAM,CAAA;IACb,MAAM,EAAE,MAAM,CAAA;IACd,SAAS,EAAE,MAAM,CAAA;IACjB;;;OAGG;IACH,KAAK,CAAC,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,QAAQ,EAAE,MAAM,CAAC;QAAC,UAAU,EAAE,MAAM,CAAA;KAAE,EAAE,CAAA;CACjE;AAED,uCAAuC;AACvC,wBAAgB,YAAY,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,CAErD;AAED,yEAAyE;AACzE,wBAAsB,kBAAkB,CACtC,QAAQ,EAAE,MAAM,EAChB,QAAQ,EAAE,aAAa,GACtB,OAAO,CAAC,IAAI,CAAC,CAMf;AAED,iFAAiF;AACjF,wBAAsB,iBAAiB,CACrC,QAAQ,EAAE,MAAM,GACf,OAAO,CAAC,aAAa,GAAG,SAAS,CAAC,CAapC;AAED;;;;;GAKG;AACH,wBAAsB,cAAc,CAClC,SAAS,EAAE,MAAM,EACjB,IAAI,EAAE,MAAM,GACX,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC,CAmC7B"}

package/dist/cache.js

@@ -0,0 +1,105 @@
+import { createHash } from 'node:crypto';
+import { readdir, readFile, stat, writeFile } from 'node:fs/promises';
+import { join } from 'node:path';
+/** Directory names this module owns: `YYYY-MM-DD`. */
+const DATE_DIRECTORY = /^\d{4}-\d{2}-\d{2}$/;
+/** Audio container Edge-TTS writes. */
+export const AUDIO_FORMAT = 'mp3';
+/**
+ * Stable cache key for one synthesis request. The first 16 hex characters of
+ * SHA-256 are enough to name a file while keeping names short.
+ */
+export function cacheKey(text, voice, rate) {
+    return createHash('sha256')
+        .update(`${text}\u0000${voice}\u0000${rate}`, 'utf8')
+        .digest('hex')
+        .slice(0, 16);
+}
+/** Local-calendar `YYYY-MM-DD` bucket for a timestamp. */
+export function dateDirName(date = new Date()) {
+    const year = String(date.getFullYear()).padStart(4, '0');
+    const month = String(date.getMonth() + 1).padStart(2, '0');
+    const day = String(date.getDate()).padStart(2, '0');
+    return `${year}-${month}-${day}`;
+}
+/**
+ * Target path for a fresh synthesis: `<outputDir>/<date>/<hash>-<epochMs>.mp3`.
+ * The timestamp keeps concurrent first-time syntheses from colliding.
+ */
+export function outputFilePath(outputDir, hash, date = new Date()) {
+    return join(outputDir, dateDirName(date), `${hash}-${date.getTime()}.${AUDIO_FORMAT}`);
+}
+/** Sidecar path for one audio file. */
+export function metadataPath(filePath) {
+    return `${filePath}.json`;
+}
+/** Best-effort metadata write; diagnostics must never fail synthesis. */
+export async function writeCacheMetadata(filePath, metadata) {
+    try {
+        await writeFile(metadataPath(filePath), JSON.stringify(metadata), 'utf8');
+    }
+    catch {
+        // The audio file is already valid; a missing sidecar only loses engine info.
+    }
+}
+/** Read a sidecar, treating missing, unreadable, or malformed data as absent. */
+export async function readCacheMetadata(filePath) {
+    try {
+        const parsed = JSON.parse(await readFile(metadataPath(filePath), 'utf8'));
+        if (typeof parsed !== 'object' || parsed === null)
+            return undefined;
+        if (typeof parsed.engine !== 'string' || parsed.engine.length === 0) {
+            return undefined;
+        }
+        return parsed;
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * Find an existing non-empty file for `hash`, newest date bucket first. Only
+ * files carrying the exact key prefix and a positive size qualify, so a
+ * partial or unrelated file never satisfies the cache. The `.mp3.json`
+ * sidecars and the `.audio-route-secret` file never match this filter.
+ */
+export async function findCachedFile(outputDir, hash) {
+    let entries;
+    try {
+        entries = await readdir(outputDir, { withFileTypes: true });
+    }
+    catch {
+        return undefined;
+    }
+    const dateDirs = entries
+        .filter((entry) => entry.isDirectory() && DATE_DIRECTORY.test(entry.name))
+        .map((entry) => entry.name)
+        .sort()
+        .reverse();
+    const prefix = `${hash}-`;
+    for (const dirName of dateDirs) {
+        const dir = join(outputDir, dirName);
+        let names;
+        try {
+            names = await readdir(dir);
+        }
+        catch {
+            continue;
+        }
+        for (const name of names) {
+            if (!name.startsWith(prefix) || !name.endsWith(`.${AUDIO_FORMAT}`))
+                continue;
+            const filePath = join(dir, name);
+            try {
+                const info = await stat(filePath);
+                if (info.isFile() && info.size > 0)
+                    return filePath;
+            }
+            catch {
+                // Raced with a cleanup; try the next candidate.
+            }
+        }
+    }
+    return undefined;
+}
+//# sourceMappingURL=cache.js.map

package/dist/cache.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cache.js","sourceRoot":"","sources":["../src/cache.ts"],"names":[],"mappings":"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"}

package/dist/chunked-tts.d.ts

@@ -0,0 +1,34 @@
+import { type SpawnFunction, type SynthesizedAudio } from './edge-tts.ts';
+/** Pause between chunk subprocesses so Edge-TTS is not rate-limited. */
+export declare const DEFAULT_INTER_CHUNK_DELAY_MS = 200;
+export interface ChunkedSynthesisOptions {
+    voice: string;
+    rate: string;
+    /** Applied uniformly to every chunk. */
+    pitch?: string;
+    /** Applied uniformly to every chunk. */
+    volume?: string;
+    /** Forwarded to every chunk subprocess as `--proxy`. */
+    proxy?: string;
+    binary: string;
+    outputDir: string;
+    /** Cache key of the full original text. */
+    hash: string;
+    timeoutMs: number;
+    /** Whole-call budget across every chunk and inter-chunk delay. */
+    totalTimeoutMs?: number;
+    chunkSize: number;
+    signal?: AbortSignal;
+    spawnImpl?: SpawnFunction;
+    now?: Date;
+    /** Injectable sleep, used by tests to avoid real delays. */
+    delay?: (ms: number) => Promise<void>;
+    interChunkDelayMs?: number;
+}
+/**
+ * Synthesize `text` chunk by chunk and return one concatenated MP3. Callers
+ * only use this above the chunk threshold; calling it with one chunk simply
+ * delegates to the one-shot path.
+ */
+export declare function synthesizeChunked(text: string, options: ChunkedSynthesisOptions): Promise<SynthesizedAudio>;
+//# sourceMappingURL=chunked-tts.d.ts.map

package/dist/chunked-tts.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"chunked-tts.d.ts","sourceRoot":"","sources":["../src/chunked-tts.ts"],"names":[],"mappings":"AAeA,OAAO,EAEL,KAAK,aAAa,EAClB,KAAK,gBAAgB,EACtB,MAAM,eAAe,CAAA;AAGtB,wEAAwE;AACxE,eAAO,MAAM,4BAA4B,MAAM,CAAA;AAE/C,MAAM,WAAW,uBAAuB;IACtC,KAAK,EAAE,MAAM,CAAA;IACb,IAAI,EAAE,MAAM,CAAA;IACZ,wCAAwC;IACxC,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,wCAAwC;IACxC,MAAM,CAAC,EAAE,MAAM,CAAA;IACf,wDAAwD;IACxD,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,MAAM,EAAE,MAAM,CAAA;IACd,SAAS,EAAE,MAAM,CAAA;IACjB,2CAA2C;IAC3C,IAAI,EAAE,MAAM,CAAA;IACZ,SAAS,EAAE,MAAM,CAAA;IACjB,kEAAkE;IAClE,cAAc,CAAC,EAAE,MAAM,CAAA;IACvB,SAAS,EAAE,MAAM,CAAA;IACjB,MAAM,CAAC,EAAE,WAAW,CAAA;IACpB,SAAS,CAAC,EAAE,aAAa,CAAA;IACzB,GAAG,CAAC,EAAE,IAAI,CAAA;IACV,4DAA4D;IAC5D,KAAK,CAAC,EAAE,CAAC,EAAE,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,CAAA;IACrC,iBAAiB,CAAC,EAAE,MAAM,CAAA;CAC3B;AA8CD;;;;GAIG;AACH,wBAAsB,iBAAiB,CACrC,IAAI,EAAE,MAAM,EACZ,OAAO,EAAE,uBAAuB,GAC/B,OAAO,CAAC,gBAAgB,CAAC,CAqF3B"}