vidspotai-shared 1.0.100 → 1.0.101-dev.0

package/lib/services/translation/translation.service.js

@@ -74,13 +74,6 @@ const PRIMARY_BASE = "https://us-central1-translation-service-3931b.cloudfunctio
 // 24s user-facing stall was itself part of the problem).
 const PRIMARY_TIMEOUT_MS = 6000;
 const PRIMARY_MAX_ATTEMPTS = 2;
-// The LLM fallback had NO timeout, so when the primary CF was also failing the
-// two layers compounded into an unbounded stall — a Vietnamese request was
-// measured at 48s in prod (2026-07-26): ~12s burning both primary attempts,
-// then ~36s waiting on a slow generateText that nothing was bounding. Cap the
-// fallback so the worst case is primary (~12.2s) + fallback (15s) ≈ 27s and the
-// caller gets a definite answer instead of holding the request open.
-const FALLBACK_TIMEOUT_MS = 15000;
 // gpt-4o-mini: cheap (~$0.15/1M in, $0.60/1M out → fractions of a cent per
 // prompt), reliable, and independent of the Google video quota. Swap here if a
 // cheaper effective model becomes available.
@@ -117,25 +110,13 @@ async function callLlmTranslate(text, from, to) {
         `Preserve meaning, tone, names, numbers, hashtags, emojis and line breaks. ` +
         `Output ONLY the translated text — no quotes, no language labels, no commentary. ` +
         `If the text is already in ${target}, return it unchanged.`;
-    // Bounded: generateText itself takes no timeout, so race it. The loser is
-    // abandoned rather than cancelled (there is no AbortSignal on this path), but
-    // the caller is unblocked — which is the point.
-    let timer;
-    const { text: out } = await Promise.race([
-        service.generateText({
-            input: [
-                { role: "system", content: system },
-                { role: "user", content: text },
-            ],
-            modelKey: FALLBACK_MODEL,
-            options: { temperature: 0 },
-        }),
-        new Promise((_, reject) => {
-            timer = setTimeout(() => reject(new Error(`LLM fallback timed out after ${FALLBACK_TIMEOUT_MS}ms`)), FALLBACK_TIMEOUT_MS);
-        }),
-    ]).finally(() => {
-        if (timer)
-            clearTimeout(timer);
+    const { text: out } = await service.generateText({
+        input: [
+            { role: "system", content: system },
+            { role: "user", content: text },
+        ],
+        modelKey: FALLBACK_MODEL,
+        options: { temperature: 0 },
     });
     const trimmed = (out ?? "").trim();
     if (!trimmed || trimmed === "No response") {
@@ -189,20 +170,81 @@ async function translate(text, from, to = types_1.ELANGUAGE_CODE.en, version = "
     }
 }
 /**
- * Detect the language of `text`. Primary CF; on failure fails OPEN to English
- * (matches prior behavior — language detection must never block generation).
+ * FALLBACK: detect via the same cheap LLM `translate` falls back to. Returns
+ * the bare ISO 639-1 code. Throws if the reply doesn't look like a code.
+ */
+async function callLlmDetect(text) {
+    const { getAiGenProviderService } = await Promise.resolve().then(() => __importStar(require("../aiGen/aiGenFactory.service")));
+    const service = getAiGenProviderService(FALLBACK_MODEL);
+    const system = "You are a language identification engine. Reply with ONLY the ISO 639-1 " +
+        "code of the language the user's text is written in — two lowercase " +
+        'letters, nothing else (e.g. "es", "ja", "ar"). Use "zh-cn" or "zh-tw" ' +
+        "for Chinese. No punctuation, no explanation.";
+    const { text: out } = await service.generateText({
+        // Only the opening slice matters for identification, and capping it keeps
+        // this cheap when a long-form brief triggers the fallback.
+        input: [
+            { role: "system", content: system },
+            { role: "user", content: text.slice(0, 1000) },
+        ],
+        modelKey: FALLBACK_MODEL,
+        options: { temperature: 0 },
+    });
+    const code = (out ?? "").trim().toLowerCase().replace(/[^a-z-]/g, "");
+    if (!/^[a-z]{2}(-[a-z]{2})?$/.test(code)) {
+        throw new Error(`LLM detect returned a non-code reply: "${out}"`);
+    }
+    return code;
+}
+/**
+ * Detect the language of `text`. Primary CF → cheap LLM → fail OPEN to English.
+ *
+ * The LLM layer matters more here than it does for `translate`. The primary
+ * endpoint is the same flaky Cloud Function, but detection's failure mode is
+ * silent rather than loud: it used to return en/100% with `reliable: false`,
+ * and since every caller ignored that flag, a detect timeout quietly forced
+ * English on a non-English user. That is one of the ways the product ended up
+ * English-only regardless of what the user wrote.
+ *
+ * The terminal fallback still returns English so detection can never block a
+ * generation run — but it keeps `reliable: false`, and callers
+ * (`resolveOutputLanguage`) now honour that flag and defer to the UI locale
+ * instead of treating the guess as fact.
  */
 async function detectLanguage(text) {
+    let primaryErr;
     try {
         const res = await axios_1.default.post(`${PRIMARY_BASE}/detectLang`, { text }, {
             headers: { "internal-key": process.env.TRANSLATION_SERVICE_KEY || "" },
             timeout: PRIMARY_TIMEOUT_MS,
         });
-        return res.data;
+        if (res.data?.languages?.[0]?.code)
+            return res.data;
+        throw new Error("primary detectLang returned no language");
     }
     catch (err) {
-        logger_1.logger.warn("translation: detectLang failed, defaulting to en", {
-            err: errMsg(err),
+        primaryErr = err;
+    }
+    try {
+        const code = await callLlmDetect(text);
+        logger_1.logger.warn("translation: detectLang primary failed, LLM recovered", {
+            fallbackModel: FALLBACK_MODEL,
+            detected: code,
+            err: errMsg(primaryErr),
+        });
+        return {
+            reliable: true,
+            textBytes: Buffer.byteLength(text, "utf8"),
+            languages: [
+                { name: languageLabel(code), code, percent: 100, score: 1 },
+            ],
+            chunks: [],
+        };
+    }
+    catch (fallbackErr) {
+        logger_1.logger.warn("translation: detectLang failed on both layers, defaulting to en", {
+            primaryErr: errMsg(primaryErr),
+            fallbackErr: errMsg(fallbackErr),
         });
         return {
             reliable: false,

package/lib/services/tts/index.d.ts

@@ -1,4 +1,5 @@
 export * from "./types";
+export * from "./wordTimings";
 export * from "./providers/elevenlabs.service";
 export * from "./providers/minimax.service";
 export * from "./providers/openai.service";

package/lib/services/tts/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/services/tts/index.ts"],"names":[],"mappings":"AAAA,cAAc,SAAS,CAAC;AACxB,cAAc,gCAAgC,CAAC;AAC/C,cAAc,6BAA6B,CAAC;AAC5C,cAAc,4BAA4B,CAAC;AAC3C,cAAc,sBAAsB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/services/tts/index.ts"],"names":[],"mappings":"AAAA,cAAc,SAAS,CAAC;AACxB,cAAc,eAAe,CAAC;AAC9B,cAAc,gCAAgC,CAAC;AAC/C,cAAc,6BAA6B,CAAC;AAC5C,cAAc,4BAA4B,CAAC;AAC3C,cAAc,sBAAsB,CAAC"}

package/lib/services/tts/index.js

@@ -15,6 +15,7 @@ var __exportStar = (this && this.__exportStar) || function(m, exports) {
 };
 Object.defineProperty(exports, "__esModule", { value: true });
 __exportStar(require("./types"), exports);
+__exportStar(require("./wordTimings"), exports);
 __exportStar(require("./providers/elevenlabs.service"), exports);
 __exportStar(require("./providers/minimax.service"), exports);
 __exportStar(require("./providers/openai.service"), exports);

package/lib/services/tts/providers/elevenlabs.service.d.ts

@@ -9,6 +9,13 @@ export declare class ElevenLabsService extends BaseTtsProviderService {
      * Retries: axios timeout (ECONNABORTED), network errors (ECONNRESET/ETIMEDOUT/etc.),
      * HTTP 429 (rate limit, longer backoff), HTTP 5xx (server errors).
      * Does NOT retry: 400/401/403/404 (caller handles 400 language_code separately).
+     *
+     * Two endpoints, one code path. The plain endpoint streams audio bytes; the
+     * `/with-timestamps` endpoint returns JSON carrying base64 audio PLUS character
+     * alignment. We keep `responseType: "arraybuffer"` for BOTH and parse the JSON
+     * out of the buffer ourselves, so error bodies keep arriving as Buffers and the
+     * caller's error-decoding (which reads `err.response.data` as a Buffer) stays
+     * correct for both modes.
      */
     private postTtsWithRetry;
     getVoices(): ITtsVoiceOption[];

package/lib/services/tts/providers/elevenlabs.service.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"elevenlabs.service.d.ts","sourceRoot":"","sources":["../../../../src/services/tts/providers/elevenlabs.service.ts"],"names":[],"mappings":"AAIA,OAAO,EAAE,sBAAsB,EAAE,eAAe,EAAE,SAAS,EAAE,SAAS,EAAE,MAAM,UAAU,CAAC;AAiBzF,qBAAa,iBAAkB,SAAQ,sBAAsB;IAC3D,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAkC;IAE1D,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAS;;IAW1B,QAAQ,CAAC,MAAM,EAAE,SAAS,GAAG,OAAO,CAAC,SAAS,CAAC;IA+FrD;;;;;OAKG;YACW,gBAAgB;IAsD9B,SAAS,IAAI,eAAe,EAAE;IAI9B,eAAe,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS;CAGpD"}
+{"version":3,"file":"elevenlabs.service.d.ts","sourceRoot":"","sources":["../../../../src/services/tts/providers/elevenlabs.service.ts"],"names":[],"mappings":"AAIA,OAAO,EACL,sBAAsB,EACtB,eAAe,EAEf,SAAS,EACT,SAAS,EACV,MAAM,UAAU,CAAC;AAiBlB,qBAAa,iBAAkB,SAAQ,sBAAsB;IAC3D,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAkC;IAE1D,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAS;;IAW1B,QAAQ,CAAC,MAAM,EAAE,SAAS,GAAG,OAAO,CAAC,SAAS,CAAC;IAuGrD;;;;;;;;;;;;OAYG;YACW,gBAAgB;IAsE9B,SAAS,IAAI,eAAe,EAAE;IAI9B,eAAe,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS;CAGpD"}

package/lib/services/tts/providers/elevenlabs.service.js

@@ -88,12 +88,14 @@ class ElevenLabsService extends types_1.BaseTtsProviderService {
         };
         const outputFormat = params.outputFormat;
         const { mimeType, extension } = mimeFromOutputFormat(outputFormat);
+        const postOpts = {
+            outputFormat,
+            optimizeStreamingLatency: params.optimizeStreamingLatency,
+            withTimestamps: params.withTimestamps === true,
+        };
         try {
-            const audioBuffer = await this.postTtsWithRetry(voiceId, buildBody(languageCode), {
-                outputFormat,
-                optimizeStreamingLatency: params.optimizeStreamingLatency,
-            });
-            return { audioBuffer, mimeType, extension };
+            const { audioBuffer, alignment } = await this.postTtsWithRetry(voiceId, buildBody(languageCode), postOpts);
+            return { audioBuffer, mimeType, extension, ...(alignment ? { alignment } : {}) };
         }
         catch (err) {
             // responseType:"arraybuffer" causes error bodies to arrive as Buffer/ArrayBuffer,
@@ -114,11 +116,8 @@ class ElevenLabsService extends types_1.BaseTtsProviderService {
                 if (err.response.status === 400 &&
                     languageCode &&
                     (detail.includes("language_code") || detail.includes("does not support"))) {
-                    const audioBuffer = await this.postTtsWithRetry(voiceId, buildBody(undefined), {
-                        outputFormat,
-                        optimizeStreamingLatency: params.optimizeStreamingLatency,
-                    });
-                    return { audioBuffer, mimeType, extension };
+                    const { audioBuffer, alignment } = await this.postTtsWithRetry(voiceId, buildBody(undefined), postOpts);
+                    return { audioBuffer, mimeType, extension, ...(alignment ? { alignment } : {}) };
                 }
                 const wrapped = new Error(`ElevenLabs TTS ${err.response.status}: ${detail} [voiceId=${voiceId}, languageCode=${languageCode ?? "none"}, modelId=${modelId}, textLen=${params.text?.length ?? 0}]`);
                 wrapped.cause = err;
@@ -132,6 +131,13 @@ class ElevenLabsService extends types_1.BaseTtsProviderService {
      * Retries: axios timeout (ECONNABORTED), network errors (ECONNRESET/ETIMEDOUT/etc.),
      * HTTP 429 (rate limit, longer backoff), HTTP 5xx (server errors).
      * Does NOT retry: 400/401/403/404 (caller handles 400 language_code separately).
+     *
+     * Two endpoints, one code path. The plain endpoint streams audio bytes; the
+     * `/with-timestamps` endpoint returns JSON carrying base64 audio PLUS character
+     * alignment. We keep `responseType: "arraybuffer"` for BOTH and parse the JSON
+     * out of the buffer ourselves, so error bodies keep arriving as Buffers and the
+     * caller's error-decoding (which reads `err.response.data` as a Buffer) stays
+     * correct for both modes.
      */
     async postTtsWithRetry(voiceId, body, opts) {
         const query = {};
@@ -140,21 +146,37 @@ class ElevenLabsService extends types_1.BaseTtsProviderService {
         if (opts?.optimizeStreamingLatency !== undefined) {
             query.optimize_streaming_latency = opts.optimizeStreamingLatency;
         }
+        const withTimestamps = opts?.withTimestamps === true;
+        const url = withTimestamps
+            ? `${this.baseUrl}/text-to-speech/${voiceId}/with-timestamps`
+            : `${this.baseUrl}/text-to-speech/${voiceId}`;
         const { mimeType } = mimeFromOutputFormat(opts?.outputFormat);
+        const accept = withTimestamps ? "application/json" : mimeType;
         let lastErr;
         for (let attempt = 1; attempt <= MAX_ATTEMPTS; attempt++) {
             try {
-                const response = await axios_1.default.post(`${this.baseUrl}/text-to-speech/${voiceId}`, body, {
+                const response = await axios_1.default.post(url, body, {
                     headers: {
                         "xi-api-key": this.apiKey,
                         "Content-Type": "application/json",
-                        Accept: mimeType,
+                        Accept: accept,
                     },
                     params: Object.keys(query).length ? query : undefined,
                     responseType: "arraybuffer",
                     timeout: PER_ATTEMPT_TIMEOUT_MS,
                 });
-                return Buffer.from(response.data);
+                const raw = Buffer.from(response.data);
+                if (!withTimestamps)
+                    return { audioBuffer: raw };
+                // A malformed/partial timestamps payload must not lose us the audio —
+                // but there's no audio to salvage if the JSON itself won't parse, so
+                // that case is a real error. Missing/!ok alignment degrades to no
+                // alignment, and the caller falls back to estimated word spacing.
+                const parsed = parseTimestampedResponse(raw);
+                return {
+                    audioBuffer: parsed.audioBuffer,
+                    ...(parsed.alignment ? { alignment: parsed.alignment } : {}),
+                };
             }
             catch (err) {
                 lastErr = err;
@@ -211,6 +233,40 @@ function mimeFromOutputFormat(fmt) {
             return { mimeType: "audio/mpeg", extension: "mp3" };
     }
 }
+/** True when every element of `v` is a finite number. */
+function isNumberArray(v) {
+    return Array.isArray(v) && v.every((n) => typeof n === "number" && Number.isFinite(n));
+}
+function isStringArray(v) {
+    return Array.isArray(v) && v.every((s) => typeof s === "string");
+}
+/**
+ * Decode a `/with-timestamps` response: base64 audio + character alignment.
+ *
+ * We deliberately read `alignment` and NOT `normalized_alignment`. Normalized
+ * alignment is timed against the text ElevenLabs actually spoke after its
+ * normaliser ran — "200,000" becomes "two hundred thousand" — so its characters
+ * no longer correspond to the text we display in a caption. `alignment` is timed
+ * against the input text verbatim, which is what gets drawn.
+ */
+function parseTimestampedResponse(raw) {
+    const body = JSON.parse(raw.toString("utf8"));
+    if (typeof body.audio_base64 !== "string" || !body.audio_base64) {
+        throw new Error("ElevenLabs with-timestamps response carried no audio_base64");
+    }
+    const audioBuffer = Buffer.from(body.audio_base64, "base64");
+    const a = body.alignment;
+    const characters = a?.characters;
+    const startsSec = a?.character_start_times_seconds;
+    const endsSec = a?.character_end_times_seconds;
+    if (!isStringArray(characters) || !isNumberArray(startsSec) || !isNumberArray(endsSec)) {
+        logger_1.logger.warn("ElevenLabs returned audio without a usable character alignment", {
+            hasAlignment: Boolean(a),
+        });
+        return { audioBuffer };
+    }
+    return { audioBuffer, alignment: { characters, startsSec, endsSec } };
+}
 function isTransientHttpError(err) {
     if (!err)
         return false;

package/lib/services/tts/types.d.ts

@@ -41,11 +41,40 @@ export interface TtsParams {
         pronunciation_dictionary_id: string;
         version_id?: string;
     }>;
+    /**
+     * Ask the provider to return per-CHARACTER timings alongside the audio, so the
+     * caller can derive word timings and draw captions synced to the actual speech
+     * instead of guessing from a words-per-second estimate.
+     *
+     * Only ElevenLabs implements this (its `/with-timestamps` endpoint). Providers
+     * that don't simply ignore the flag and return `TtsResult.alignment`
+     * undefined — the audio is identical either way, so a caller can always ask.
+     */
+    withTimestamps?: boolean;
+}
+/**
+ * Per-character speech timings for one synthesized utterance. Parallel arrays —
+ * `characters[i]` is spoken from `startsSec[i]` to `endsSec[i]`, relative to the
+ * start of THIS utterance's audio (not the video timeline).
+ *
+ * Characters, not words, is the provider's native granularity; use
+ * `wordsFromAlignment` to group them.
+ */
+export interface TtsAlignment {
+    characters: string[];
+    startsSec: number[];
+    endsSec: number[];
 }
 export interface TtsResult {
     audioBuffer: Buffer;
     mimeType: string;
     extension: string;
+    /**
+     * Character timings, present only when `TtsParams.withTimestamps` was set AND
+     * the provider supports it. Always handle absence — a caller that needs word
+     * timings must degrade (e.g. to evenly-spaced words) rather than fail.
+     */
+    alignment?: TtsAlignment;
 }
 export interface ITtsVoiceOption {
     id: string;

package/lib/services/tts/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../src/services/tts/types.ts"],"names":[],"mappings":"AAAA,MAAM,WAAW,SAAS;IACxB,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB;;;;OAIG;IACH,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,kFAAkF;IAClF,YAAY,CAAC,EAAE,MAAM,CAAC;IAGtB,yGAAyG;IACzG,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,iGAAiG;IACjG,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,sGAAsG;IACtG,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,mDAAmD;IACnD,eAAe,CAAC,EAAE,OAAO,CAAC;IAC1B,qEAAqE;IACrE,KAAK,CAAC,EAAE,MAAM,CAAC;IAGf,oDAAoD;IACpD,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,qEAAqE;IACrE,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,qEAAqE;IACrE,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,oGAAoG;IACpG,kBAAkB,CAAC,EAAE,MAAM,EAAE,CAAC;IAC9B,iEAAiE;IACjE,cAAc,CAAC,EAAE,MAAM,EAAE,CAAC;IAG1B,2EAA2E;IAC3E,sBAAsB,CAAC,EAAE,MAAM,GAAG,IAAI,GAAG,KAAK,CAAC;IAC/C,4EAA4E;IAC5E,8BAA8B,CAAC,EAAE,OAAO,CAAC;IAGzC,0FAA0F;IAC1F,wBAAwB,CAAC,EAAE,CAAC,GAAG,CAAC,GAAG,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;IAE7C,qEAAqE;IACrE,+BAA+B,CAAC,EAAE,KAAK,CAAC;QACtC,2BAA2B,EAAE,MAAM,CAAC;QACpC,UAAU,CAAC,EAAE,MAAM,CAAC;KACrB,CAAC,CAAC;CACJ;AAED,MAAM,WAAW,SAAS;IACxB,WAAW,EAAE,MAAM,CAAC;IACpB,QAAQ,EAAE,MAAM,CAAC;IACjB,SAAS,EAAE,MAAM,CAAC;CACnB;AAED,MAAM,WAAW,eAAe;IAC9B,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,CAAC,EAAE,MAAM,GAAG,QAAQ,CAAC;IAC3B,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,iGAAiG;IACjG,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED,8BAAsB,sBAAsB;IAC1C,QAAQ,CAAC,QAAQ,CAAC,MAAM,EAAE,SAAS,GAAG,OAAO,CAAC,SAAS,CAAC;IAExD;;;OAGG;IACH,QAAQ,CAAC,SAAS,IAAI,eAAe,EAAE;IAEvC;;;;OAIG;IACH,QAAQ,CAAC,eAAe,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS;CAC7D"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../src/services/tts/types.ts"],"names":[],"mappings":"AAAA,MAAM,WAAW,SAAS;IACxB,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB;;;;OAIG;IACH,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,kFAAkF;IAClF,YAAY,CAAC,EAAE,MAAM,CAAC;IAGtB,yGAAyG;IACzG,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,iGAAiG;IACjG,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,sGAAsG;IACtG,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,mDAAmD;IACnD,eAAe,CAAC,EAAE,OAAO,CAAC;IAC1B,qEAAqE;IACrE,KAAK,CAAC,EAAE,MAAM,CAAC;IAGf,oDAAoD;IACpD,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,qEAAqE;IACrE,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,qEAAqE;IACrE,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,oGAAoG;IACpG,kBAAkB,CAAC,EAAE,MAAM,EAAE,CAAC;IAC9B,iEAAiE;IACjE,cAAc,CAAC,EAAE,MAAM,EAAE,CAAC;IAG1B,2EAA2E;IAC3E,sBAAsB,CAAC,EAAE,MAAM,GAAG,IAAI,GAAG,KAAK,CAAC;IAC/C,4EAA4E;IAC5E,8BAA8B,CAAC,EAAE,OAAO,CAAC;IAGzC,0FAA0F;IAC1F,wBAAwB,CAAC,EAAE,CAAC,GAAG,CAAC,GAAG,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;IAE7C,qEAAqE;IACrE,+BAA+B,CAAC,EAAE,KAAK,CAAC;QACtC,2BAA2B,EAAE,MAAM,CAAC;QACpC,UAAU,CAAC,EAAE,MAAM,CAAC;KACrB,CAAC,CAAC;IAGH;;;;;;;;OAQG;IACH,cAAc,CAAC,EAAE,OAAO,CAAC;CAC1B;AAED;;;;;;;GAOG;AACH,MAAM,WAAW,YAAY;IAC3B,UAAU,EAAE,MAAM,EAAE,CAAC;IACrB,SAAS,EAAE,MAAM,EAAE,CAAC;IACpB,OAAO,EAAE,MAAM,EAAE,CAAC;CACnB;AAED,MAAM,WAAW,SAAS;IACxB,WAAW,EAAE,MAAM,CAAC;IACpB,QAAQ,EAAE,MAAM,CAAC;IACjB,SAAS,EAAE,MAAM,CAAC;IAClB;;;;OAIG;IACH,SAAS,CAAC,EAAE,YAAY,CAAC;CAC1B;AAED,MAAM,WAAW,eAAe;IAC9B,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,CAAC,EAAE,MAAM,GAAG,QAAQ,CAAC;IAC3B,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,iGAAiG;IACjG,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED,8BAAsB,sBAAsB;IAC1C,QAAQ,CAAC,QAAQ,CAAC,MAAM,EAAE,SAAS,GAAG,OAAO,CAAC,SAAS,CAAC;IAExD;;;OAGG;IACH,QAAQ,CAAC,SAAS,IAAI,eAAe,EAAE;IAEvC;;;;OAIG;IACH,QAAQ,CAAC,eAAe,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS;CAC7D"}

package/lib/services/tts/wordTimings.d.ts

@@ -0,0 +1,27 @@
+import { TtsAlignment } from "./types";
+/**
+ * Word-level speech timings derived from a provider's character alignment.
+ * Times are relative to the start of the utterance's own audio, seconds.
+ */
+export interface TtsWord {
+    word: string;
+    startSec: number;
+    endSec: number;
+}
+/**
+ * Group a provider's per-CHARACTER alignment into words.
+ *
+ * TTS providers expose timings per character (that IS their native granularity);
+ * captions need them per word. A word runs from its first character's start to
+ * its last character's end, and whitespace characters are the delimiters —
+ * punctuation stays attached to the word it belongs to, because the caller
+ * displays this text verbatim.
+ *
+ * Defensive on purpose: the alignment is a parsed API response (a trust
+ * boundary), so mismatched array lengths are truncated to the shortest rather
+ * than trusted, and non-finite / out-of-order timings are repaired instead of
+ * poisoning the caption track. Returns `[]` for an empty or unusable alignment,
+ * which callers treat as "no word timings" and degrade from.
+ */
+export declare function wordsFromAlignment(alignment: TtsAlignment): TtsWord[];
+//# sourceMappingURL=wordTimings.d.ts.map

package/lib/services/tts/wordTimings.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"wordTimings.d.ts","sourceRoot":"","sources":["../../../src/services/tts/wordTimings.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AAEvC;;;GAGG;AACH,MAAM,WAAW,OAAO;IACtB,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,EAAE,MAAM,CAAC;IACjB,MAAM,EAAE,MAAM,CAAC;CAChB;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,kBAAkB,CAAC,SAAS,EAAE,YAAY,GAAG,OAAO,EAAE,CA6CrE"}

package/lib/services/tts/wordTimings.js

@@ -0,0 +1,57 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.wordsFromAlignment = wordsFromAlignment;
+/**
+ * Group a provider's per-CHARACTER alignment into words.
+ *
+ * TTS providers expose timings per character (that IS their native granularity);
+ * captions need them per word. A word runs from its first character's start to
+ * its last character's end, and whitespace characters are the delimiters —
+ * punctuation stays attached to the word it belongs to, because the caller
+ * displays this text verbatim.
+ *
+ * Defensive on purpose: the alignment is a parsed API response (a trust
+ * boundary), so mismatched array lengths are truncated to the shortest rather
+ * than trusted, and non-finite / out-of-order timings are repaired instead of
+ * poisoning the caption track. Returns `[]` for an empty or unusable alignment,
+ * which callers treat as "no word timings" and degrade from.
+ */
+function wordsFromAlignment(alignment) {
+    const n = Math.min(alignment.characters.length, alignment.startsSec.length, alignment.endsSec.length);
+    const words = [];
+    let text = "";
+    let start = 0;
+    let end = 0;
+    let open = false;
+    const flush = () => {
+        if (!open)
+            return;
+        const trimmed = text.trim();
+        if (trimmed) {
+            // A provider glitch can hand back end <= start; keep words strictly
+            // ordered so the renderer's `t >= start && t <= end` test can still match.
+            words.push({ word: trimmed, startSec: start, endSec: Math.max(end, start) });
+        }
+        text = "";
+        open = false;
+    };
+    for (let i = 0; i < n; i++) {
+        const ch = alignment.characters[i] ?? "";
+        if (/^\s*$/.test(ch)) {
+            flush();
+            continue;
+        }
+        const s = alignment.startsSec[i];
+        const e = alignment.endsSec[i];
+        const sSec = Number.isFinite(s) ? s : end;
+        const eSec = Number.isFinite(e) ? e : sSec;
+        if (!open) {
+            start = sSec;
+            open = true;
+        }
+        end = Math.max(end, eSec);
+        text += ch;
+    }
+    flush();
+    return words;
+}

package/lib/utils/billableDuration.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Pick the duration to bill for a scene.
+ *
+ * @param modelKey     Model the scene was generated with.
+ * @param deliveredSec Measured/reported length of the delivered clip, if known.
+ * @param requestedSec Length we asked the provider for.
+ * @returns The duration to price, or `undefined` when the delivered value
+ *          cannot be priced and the caller should fall back to `requestedSec`.
+ */
+export declare function toBillableDurationSec(modelKey: string, deliveredSec: number | undefined, requestedSec: number | undefined): number | undefined;
+//# sourceMappingURL=billableDuration.d.ts.map

package/lib/utils/billableDuration.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"billableDuration.d.ts","sourceRoot":"","sources":["../../src/utils/billableDuration.ts"],"names":[],"mappings":"AAkEA;;;;;;;;GAQG;AACH,wBAAgB,qBAAqB,CACnC,QAAQ,EAAE,MAAM,EAChB,YAAY,EAAE,MAAM,GAAG,SAAS,EAChC,YAAY,EAAE,MAAM,GAAG,SAAS,GAC/B,MAAM,GAAG,SAAS,CA4BpB"}

package/lib/utils/billableDuration.js

@@ -0,0 +1,91 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.toBillableDurationSec = toBillableDurationSec;
+const aiModels_1 = require("../globals/aiModels");
+const logger_1 = require("./logger");
+/**
+ * Normalise a DELIVERED clip length into a value the credit tables can price.
+ *
+ * WHY THIS IS REQUIRED
+ * Most provider cost tables key on duration as a literal object key —
+ * `cost.table[mode][duration]` (Kling) and
+ * `cost[audio|noAudio].table[resolution][duration]` (PixVerse). Those keys are
+ * the discrete durations the model actually sells: {5, 10}, {5, 8, 10, 15}, etc.
+ *
+ * A delivered length is NOT one of those keys. A nominal 5s clip encoded at
+ * 30fps is 5.033s on the wire; an extend appends a native increment nobody
+ * asked for. Feeding a raw measured value straight into the table MISSES,
+ * which drops the calculation into its fallback branch — a flat $1.00 (10
+ * credits) for Kling, a flat 10 credits for PixVerse. That fallback is worse
+ * than the over-billing we set out to fix: it would turn a correct 7-credit
+ * charge into 10, on every scene, for every model.
+ *
+ * So delivered durations are snapped onto the model's own declared
+ * `fields.duration.allowedValues` before they are priced. That list is
+ * uniform across providers, so this needs no per-provider special-casing.
+ *
+ * SNAPPING RULE
+ *   1. Within `SNAP_TOLERANCE_SEC` of an allowed value → that value.
+ *      Absorbs encoder drift (5.033 → 5) without changing what we charge.
+ *   2. Otherwise the smallest allowed value >= delivered.
+ *      Rounding UP matches how providers bill partial increments (Kling
+ *      lipsync explicitly bills `ceil(d / 5) * 5`) and never under-charges.
+ *   3. Longer than every allowed value → `undefined`, so the caller keeps the
+ *      REQUESTED duration. This is the genuinely unknown case (e.g. an extend
+ *      whose total exceeds any single-generation length the model sells); it
+ *      is logged and left on the pre-existing behaviour rather than guessed.
+ *
+ * Models with no declared `allowedValues` are per-second priced (kling-avatar,
+ * kling-v3.0-turbo compute `perSecond * duration` and never touch a table), so
+ * a fractional value is both safe and more accurate there — it passes through.
+ */
+/**
+ * How far a delivered length may sit above/below a sold duration and still be
+ * treated as that duration. One third of a second comfortably covers
+ * frame-quantisation drift at 24/25/30/60fps (a single frame is <= 0.042s)
+ * while staying far below the gap between any two sold durations (>= 2s).
+ */
+const SNAP_TOLERANCE_SEC = 1 / 3;
+/** Read the model's declared sellable durations, if it declares any. */
+function allowedDurations(modelKey) {
+    // Typed `string[] | number[] | boolean[]` in the config schema, so it is
+    // narrowed from `unknown` here rather than assumed to be numeric.
+    // `modelKey` arrives as a plain string from the job document, so the config
+    // map is indexed through a widened view — an unknown key yields undefined
+    // rather than a type error, and is handled as "no declared durations".
+    const configs = aiModels_1.aiModelConfigs;
+    const raw = configs[modelKey]?.fields?.duration?.allowedValues;
+    if (!Array.isArray(raw))
+        return undefined;
+    const numeric = raw.filter((v) => typeof v === "number" && Number.isFinite(v) && v > 0);
+    return numeric.length > 0 ? [...numeric].sort((a, b) => a - b) : undefined;
+}
+/**
+ * Pick the duration to bill for a scene.
+ *
+ * @param modelKey     Model the scene was generated with.
+ * @param deliveredSec Measured/reported length of the delivered clip, if known.
+ * @param requestedSec Length we asked the provider for.
+ * @returns The duration to price, or `undefined` when the delivered value
+ *          cannot be priced and the caller should fall back to `requestedSec`.
+ */
+function toBillableDurationSec(modelKey, deliveredSec, requestedSec) {
+    if (typeof deliveredSec !== "number" ||
+        !Number.isFinite(deliveredSec) ||
+        deliveredSec <= 0) {
+        return undefined;
+    }
+    const allowed = allowedDurations(modelKey);
+    // Per-second models: no table to miss, so the exact measured value is both
+    // safe and the most accurate thing to bill.
+    if (!allowed)
+        return deliveredSec;
+    const withinTolerance = allowed.find((v) => Math.abs(deliveredSec - v) <= SNAP_TOLERANCE_SEC);
+    if (withinTolerance !== undefined)
+        return withinTolerance;
+    const roundedUp = allowed.find((v) => v >= deliveredSec);
+    if (roundedUp !== undefined)
+        return roundedUp;
+    logger_1.logger.warn(`toBillableDurationSec: delivered ${deliveredSec}s exceeds every sellable duration for "${modelKey}" (max ${allowed[allowed.length - 1]}s) — billing the requested duration instead`, { modelKey, deliveredSec, requestedSec, allowed });
+    return undefined;
+}

package/lib/utils/index.d.ts

@@ -1,7 +1,10 @@
+export * from "./billableDuration";
 export * from "./errors";
 export * from "./helpers";
+export * from "./mp4Duration";
 export * from "./logger";
 export * from "./renderTier";
+export * from "./socialEntitlements";
 export * from "./ttsUtils";
 export * from "./outreachTemplate";
 //# sourceMappingURL=index.d.ts.map

package/lib/utils/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/utils/index.ts"],"names":[],"mappings":"AAAA,cAAc,UAAU,CAAC;AACzB,cAAc,WAAW,CAAC;AAC1B,cAAc,UAAU,CAAC;AACzB,cAAc,cAAc,CAAC;AAC7B,cAAc,YAAY,CAAC;AAC3B,cAAc,oBAAoB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/utils/index.ts"],"names":[],"mappings":"AAAA,cAAc,oBAAoB,CAAC;AACnC,cAAc,UAAU,CAAC;AACzB,cAAc,WAAW,CAAC;AAC1B,cAAc,eAAe,CAAC;AAC9B,cAAc,UAAU,CAAC;AACzB,cAAc,cAAc,CAAC;AAC7B,cAAc,sBAAsB,CAAC;AACrC,cAAc,YAAY,CAAC;AAC3B,cAAc,oBAAoB,CAAC"}

package/lib/utils/index.js

@@ -14,9 +14,12 @@ var __exportStar = (this && this.__exportStar) || function(m, exports) {
     for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
 };
 Object.defineProperty(exports, "__esModule", { value: true });
+__exportStar(require("./billableDuration"), exports);
 __exportStar(require("./errors"), exports);
 __exportStar(require("./helpers"), exports);
+__exportStar(require("./mp4Duration"), exports);
 __exportStar(require("./logger"), exports);
 __exportStar(require("./renderTier"), exports);
+__exportStar(require("./socialEntitlements"), exports);
 __exportStar(require("./ttsUtils"), exports);
 __exportStar(require("./outreachTemplate"), exports);

package/lib/utils/mp4Duration.d.ts

@@ -0,0 +1,38 @@
+/**
+ * Dependency-free MP4 duration reader.
+ *
+ * WHY THIS EXISTS
+ * Billing prefers the DELIVERED clip length over the REQUESTED one (see
+ * `VideoStatusResult.durationSec`). Kling reports the delivered length in its
+ * status payload, so nothing has to be measured there. PixVerse does NOT — its
+ * `/video/result` response carries `create_time, id, modify_time,
+ * negative_prompt, outputHeight, outputWidth, prompt, resolution_ratio, seed,
+ * size, status, style, url` and nothing else (verified against the official
+ * docs 2026-07-24; `size` is BYTES, not seconds). So for PixVerse the only
+ * honest source of the delivered length is the file itself.
+ *
+ * We already download the finished clip into a Buffer before uploading it to
+ * Firebase, so the bytes are in hand at zero extra network cost. This module
+ * reads the length out of that Buffer by walking the MP4 box tree to `mvhd`,
+ * following the same precedent as `mp4IsComplete()` in google.service.ts:
+ * scan the bytes rather than shell out, because `packages/shared` has no
+ * ffmpeg/ffprobe dependency and must not gain one (it ships to Firebase
+ * Functions, where no such binary exists).
+ *
+ * CONTRACT: this function never throws and never guesses. Every malformed,
+ * truncated, fragmented or otherwise unreadable input returns `undefined`, and
+ * callers fall back to the requested duration — i.e. the pre-existing billing
+ * behaviour. A wrong number here would mis-bill a real user, so "I don't know"
+ * is always the correct answer when the bytes aren't unambiguous.
+ */
+/**
+ * Read the duration, in seconds, of an MP4/MOV held in memory.
+ *
+ * Returns `undefined` for anything it cannot read with confidence: non-MP4
+ * input, a truncated download (no `moov`), fragmented MP4 with an unknown
+ * `mvhd` duration, a zero/absent timescale, or an implausible result.
+ *
+ * @param buf Raw bytes of the complete file.
+ */
+export declare function readMp4DurationSec(buf: Buffer): number | undefined;
+//# sourceMappingURL=mp4Duration.d.ts.map

package/lib/utils/mp4Duration.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"mp4Duration.d.ts","sourceRoot":"","sources":["../../src/utils/mp4Duration.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AA4EH;;;;;;;;GAQG;AACH,wBAAgB,kBAAkB,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAuDlE"}