vidspotai-shared 1.0.67 → 1.0.69-dev.0

package/lib/services/agent/tools/searchStock.tool.js

@@ -0,0 +1,314 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.searchStockTool = void 0;
+exports._clearStockDedupForTesting = _clearStockDedupForTesting;
+const zod_1 = require("zod");
+const logger_1 = require("../../../utils/logger");
+const pexels_service_1 = require("../../aiGen/providers/pexels/pexels.service");
+const pixabay_service_1 = require("../../aiGen/providers/pixabay/pixabay.service");
+const unsplash_service_1 = require("../../aiGen/providers/unsplash/unsplash.service");
+const assetCache_service_1 = require("../../assetCache.service");
+const toolRegistry_1 = require("../toolRegistry");
+/**
+ * Persistent stock-search cache. Pexels is free but slow (~300–800ms) and
+ * rate-limited; bulk runs (100 variants of one template) hammer identical
+ * queries. A 30-min TTL is safe — Pexels' library moves slowly enough that
+ * fresher results aren't worth the extra hops, and any agent run completes
+ * well within the window. Persistent (Firestore) so cache survives across
+ * worker instances and restarts — in-process maps were per-pod only and
+ * useless under autoscale.
+ */
+const SEARCH_CACHE_TTL_MS = 30 * 60 * 1000;
+/**
+ * Per-provider top-K we ask each provider for AND inspect during de-dup. The
+ * symptom we're fixing: when two scenes have semantically-similar queries
+ * (e.g. "sky violet" vs "violet science") Pexels returns the same #1 hit for
+ * both, and the stitched video shows the same 8s clip twice. By pulling 5
+ * candidates per provider we have headroom to skip already-used URLs before
+ * falling to the next provider in the cascade.
+ */
+const PROVIDER_TOP_K = 5;
+/**
+ * Cross-scene de-dup state — keyed by agent run id, holds every visual URL the
+ * cascade has already handed out within that run. The Set is mutated as scenes
+ * pick candidates and consulted on every subsequent pick so two scenes in the
+ * same run never get the same URL when an unused alternative exists.
+ *
+ * In-memory (per-pod) is fine: the executor runs a single agent run within a
+ * single worker process, so all of its scene calls hit the same Map. We
+ * deliberately do NOT persist across pods — different runs are independent,
+ * and a single agent run does not migrate workers mid-flight.
+ */
+const RUN_DEDUP_TTL_MS = 30 * 60 * 1000;
+const runUsedUrls = new Map();
+/**
+ * Lazy GC: every time we touch the map, drop entries older than the TTL. Runs
+ * complete in minutes, so the map should stay tiny — this is belt-and-braces
+ * for crashed runs that never explicitly clear their entry.
+ */
+function pruneRunDedup(now) {
+    for (const [runId, entry] of runUsedUrls) {
+        if (now - entry.createdAt > RUN_DEDUP_TTL_MS) {
+            runUsedUrls.delete(runId);
+        }
+    }
+}
+function getOrCreateUsedSet(runId) {
+    const now = Date.now();
+    pruneRunDedup(now);
+    let entry = runUsedUrls.get(runId);
+    if (!entry) {
+        entry = { urls: new Set(), createdAt: now };
+        runUsedUrls.set(runId, entry);
+    }
+    return entry.urls;
+}
+/** Test-only: clear all per-run dedup state. */
+function _clearStockDedupForTesting() {
+    runUsedUrls.clear();
+}
+const InputSchema = zod_1.z.object({
+    query: zod_1.z
+        .string()
+        .min(1)
+        .describe("Plain-English search terms. Be specific — 'cinematic golden-hour ocean cliff drone' beats 'ocean'."),
+    kind: zod_1.z
+        .enum(["video", "image"])
+        .describe("Asset kind. Music search is not yet supported."),
+    aspectRatio: zod_1.z
+        .enum(["9:16", "1:1", "4:5", "16:9"])
+        .optional()
+        .describe("Target aspect for filtering by orientation."),
+    minDurationSec: zod_1.z.number().positive().optional(),
+    maxDurationSec: zod_1.z.number().positive().optional(),
+    perPage: zod_1.z
+        .number()
+        .int()
+        .min(1)
+        .max(80)
+        .default(15)
+        .describe("Page size; capped at 80."),
+});
+const OutputSchema = zod_1.z.object({
+    assets: zod_1.z.array(zod_1.z.object({
+        id: zod_1.z.string(),
+        url: zod_1.z.string().url(),
+        thumbnailUrl: zod_1.z.string().url().optional(),
+        width: zod_1.z.number().optional(),
+        height: zod_1.z.number().optional(),
+        durationSec: zod_1.z.number().optional(),
+        source: zod_1.z.string(),
+        attribution: zod_1.z
+            .object({ name: zod_1.z.string(), url: zod_1.z.string().url().optional() })
+            .optional(),
+        trackingUrl: zod_1.z
+            .string()
+            .url()
+            .optional()
+            .describe("Provider-required download-tracking endpoint. Render path must GET it when this asset is committed to the final video (Unsplash ToS)."),
+    })),
+    totalAvailable: zod_1.z.number().optional(),
+    /**
+     * Ordered list of provider names the cascade actually attempted (whether
+     * skipped, errored, or succeeded). Mirrored into SceneAssetResult so
+     * post-mortems can see "Pexels was tried but rate-limited, Pixabay served".
+     *
+     * Annotated entries the cascade may add:
+     *   "<name>"                       — provider succeeded with an un-used pick
+     *   "<name>:dedup-skipped:<n>"     — provider returned candidates but all <n>
+     *                                    inspected were already used this run
+     *   "<name>:empty"                 — provider returned 0 results
+     *   "<name>:error"                 — provider threw
+     *   "dedup-exhausted-accepted-repeat" — every provider's top-K was used;
+     *                                       we accepted a repeat to avoid a hard
+     *                                       failure (logged warn separately)
+     */
+    attemptedProviders: zod_1.z.array(zod_1.z.string()).optional(),
+});
+function buildProviderChain(kind) {
+    const pexels = new pexels_service_1.PexelsProviderService();
+    const pixabay = new pixabay_service_1.PixabayProviderService();
+    const unsplash = new unsplash_service_1.UnsplashProviderService();
+    const chain = [
+        {
+            name: "pexels",
+            available: () => Boolean(process.env.PEXELS_API_KEY),
+            supports: () => true, // images + videos
+            search: (p) => pexels.searchStock(p),
+        },
+        {
+            name: "pixabay",
+            available: () => Boolean(process.env.PIXABAY_API_KEY),
+            supports: () => true, // images + videos
+            search: (p) => pixabay.searchStock(p),
+        },
+        {
+            name: "unsplash",
+            available: () => Boolean(process.env.UNSPLASH_ACCESS_KEY),
+            supports: (k) => k === "image", // photos-only
+            search: (p) => unsplash.searchStock(p),
+        },
+    ];
+    return chain.filter((link) => link.supports(kind));
+}
+/**
+ * Wrap a provider call with the Firestore cache lookup. We cache the FULL
+ * top-K candidate list per (provider, query, params) — not just the chosen
+ * URL — so a later scene with the same query but already-used #1 can still
+ * pull #2/#3/... from cache without re-hitting the API.
+ */
+async function searchProviderWithCache(link, params) {
+    const cacheParts = {
+        provider: link.name,
+        kind: "stock-search",
+        input: {
+            query: params.query,
+            kind: params.kind,
+            aspectRatio: params.aspectRatio,
+            minDurationSec: params.minDurationSec,
+            maxDurationSec: params.maxDurationSec,
+            perPage: params.perPage,
+        },
+    };
+    const hit = await assetCache_service_1.RawAssetCacheService.lookup(cacheParts);
+    if (hit)
+        return hit;
+    const fresh = await link.search(params);
+    if (fresh.assets.length > 0) {
+        void assetCache_service_1.RawAssetCacheService.store(cacheParts, fresh, {
+            ttlMs: SEARCH_CACHE_TTL_MS,
+        }).catch(() => undefined);
+    }
+    return fresh;
+}
+exports.searchStockTool = {
+    name: "search_stock",
+    description: [
+        "Search free stock video (Pexels → Pixabay) or image (Pexels → Pixabay → Unsplash)",
+        "footage. Tries each provider in order; if one is misconfigured / rate-limited /",
+        "returns zero results, falls through to the next so the agent always gets a usable",
+        "candidate when one exists somewhere.",
+        "Use when the scene needs filler / b-roll / generic visual context that doesn't",
+        "require AI generation — this is the cheapest option (T0 tier, ~free).",
+        "Do NOT use for: hero shots, product reveals, or branded subjects (use generate_image",
+        "or generate_video instead).",
+        "Examples:",
+        '  { query: "person typing on laptop close-up", kind: "video", aspectRatio: "9:16" }',
+        '  { query: "rolling green hills sunset", kind: "image", aspectRatio: "16:9" }',
+    ].join(" "),
+    inputSchema: InputSchema,
+    outputSchema: OutputSchema,
+    estimateCost: async () => 0,
+    handler: async (input, ctx) => {
+        const providers = buildProviderChain(input.kind);
+        const attemptedProviders = [];
+        const usedUrls = getOrCreateUsedSet(ctx.agentRunId);
+        // Always ask each provider for at least PROVIDER_TOP_K candidates so we
+        // have room to skip used URLs without paging again. Honour the caller's
+        // explicit perPage if it's larger (planner sometimes wants 15 for variety).
+        const perPage = Math.max(input.perPage ?? PROVIDER_TOP_K, PROVIDER_TOP_K);
+        const searchParams = {
+            query: input.query,
+            kind: input.kind,
+            aspectRatio: input.aspectRatio,
+            minDurationSec: input.minDurationSec,
+            maxDurationSec: input.maxDurationSec,
+            perPage,
+        };
+        // Track the first non-empty candidate we saw, so if EVERY provider's
+        // top-K is already used we can fall back to a repeat rather than hard-fail.
+        // "Repeat is better than no scene" is the explicit product call.
+        let firstSeenCandidate = null;
+        for (const link of providers) {
+            if (!link.available()) {
+                // Skip silently — keep the log so ops can spot a misconfigured deploy
+                // ("why is the cascade always landing on Unsplash?").
+                logger_1.logger.info(`search_stock: skipping ${link.name} — env key missing`, { provider: link.name, kind: input.kind });
+                continue;
+            }
+            let result;
+            try {
+                result = await searchProviderWithCache(link, searchParams);
+            }
+            catch (err) {
+                // Log + continue to the next provider. The cascade exhausting is the
+                // only hard failure; an individual provider erroring is normal (rate
+                // limit, timeout, transient 5xx).
+                const message = err instanceof Error ? err.message : String(err);
+                logger_1.logger.warn(`search_stock: ${link.name} threw, falling through`, {
+                    provider: link.name,
+                    query: input.query,
+                    kind: input.kind,
+                    error: message,
+                });
+                attemptedProviders.push(`${link.name}:error`);
+                continue;
+            }
+            if (result.assets.length === 0) {
+                logger_1.logger.info(`search_stock: ${link.name} returned 0 results, falling through`, { provider: link.name, query: input.query, kind: input.kind });
+                attemptedProviders.push(`${link.name}:empty`);
+                continue;
+            }
+            // Inspect at most PROVIDER_TOP_K of this provider's candidates.
+            const candidates = result.assets.slice(0, PROVIDER_TOP_K);
+            // Remember the very first candidate the cascade saw, in case every
+            // provider gets dedup-skipped and we have to accept a repeat.
+            if (!firstSeenCandidate) {
+                firstSeenCandidate = {
+                    asset: candidates[0],
+                    totalAvailable: result.totalAvailable,
+                };
+            }
+            const pick = candidates.find((a) => !usedUrls.has(a.url));
+            if (pick) {
+                usedUrls.add(pick.url);
+                attemptedProviders.push(link.name);
+                return {
+                    assets: [pick],
+                    totalAvailable: result.totalAvailable,
+                    attemptedProviders,
+                };
+            }
+            // All top-K from this provider were already used this run. Annotate +
+            // fall through to the next provider.
+            logger_1.logger.info(`search_stock: ${link.name} top-${candidates.length} all already used this run, falling through`, {
+                provider: link.name,
+                query: input.query,
+                kind: input.kind,
+                agentRunId: ctx.agentRunId,
+                dedupSkipped: candidates.length,
+            });
+            attemptedProviders.push(`${link.name}:dedup-skipped:${candidates.length}`);
+        }
+        // Every provider was either unavailable, errored, empty, or dedup-skipped.
+        // If we saw at least one candidate anywhere, accept that repeat rather
+        // than fail the scene — the product call is "duplicate visual beats a
+        // missing scene". Surface the situation loudly so ops can audit.
+        if (firstSeenCandidate) {
+            logger_1.logger.warn("search_stock: dedup exhausted across cascade — accepting a repeat", {
+                query: input.query,
+                kind: input.kind,
+                agentRunId: ctx.agentRunId,
+                attemptedProviders,
+                repeatedUrl: firstSeenCandidate.asset.url,
+            });
+            // Don't add to usedUrls — it's already there by definition, and the
+            // bookkeeping invariant is "every URL handed out has been added once".
+            attemptedProviders.push("dedup-exhausted-accepted-repeat");
+            return {
+                assets: [firstSeenCandidate.asset],
+                totalAvailable: firstSeenCandidate.totalAvailable,
+                attemptedProviders,
+            };
+        }
+        // Truly nothing — every provider was unavailable / errored / empty. Return
+        // an empty result so the executor can raise NO_STOCK_RESULTS with full
+        // attemptedProviders context.
+        return {
+            assets: [],
+            totalAvailable: 0,
+            attemptedProviders,
+        };
+    },
+};
+(0, toolRegistry_1.registerTool)(exports.searchStockTool);

package/lib/services/agent/tools/searchUserLibrary.tool.d.ts

@@ -0,0 +1,59 @@
+import { z } from "zod";
+import { ToolDefinition } from "../toolRegistry";
+/**
+ * Per-user asset library search — massive cost saver and consistency boost
+ * for serial creators. Looks across previously generated images, voiceovers,
+ * stock pulls, and uploads owned by the requesting user.
+ *
+ * The actual library backing (Firestore + GCS index, vector embeddings for
+ * semantic search) is host-side; tool layer accepts an injected searcher.
+ */
+export interface UserLibraryAsset {
+    id: string;
+    kind: "image" | "video" | "audio" | "stock-image" | "stock-video";
+    url: string;
+    prompt?: string;
+    width?: number;
+    height?: number;
+    durationMs?: number;
+    createdAt: string;
+}
+export type UserLibrarySearchFn = (params: {
+    userId: string;
+    query: string;
+    kind?: UserLibraryAsset["kind"];
+    limit: number;
+}) => Promise<UserLibraryAsset[]>;
+export declare function setUserLibrarySearch(fn: UserLibrarySearchFn): void;
+declare const InputSchema: z.ZodObject<{
+    query: z.ZodString;
+    kind: z.ZodOptional<z.ZodEnum<{
+        audio: "audio";
+        image: "image";
+        video: "video";
+        "stock-video": "stock-video";
+        "stock-image": "stock-image";
+    }>>;
+    limit: z.ZodDefault<z.ZodNumber>;
+}, z.core.$strip>;
+declare const OutputSchema: z.ZodObject<{
+    assets: z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        kind: z.ZodEnum<{
+            audio: "audio";
+            image: "image";
+            video: "video";
+            "stock-video": "stock-video";
+            "stock-image": "stock-image";
+        }>;
+        url: z.ZodString;
+        prompt: z.ZodOptional<z.ZodString>;
+        width: z.ZodOptional<z.ZodNumber>;
+        height: z.ZodOptional<z.ZodNumber>;
+        durationMs: z.ZodOptional<z.ZodNumber>;
+        createdAt: z.ZodString;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+export declare const searchUserLibraryTool: ToolDefinition<typeof InputSchema, typeof OutputSchema>;
+export {};
+//# sourceMappingURL=searchUserLibrary.tool.d.ts.map

package/lib/services/agent/tools/searchUserLibrary.tool.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"searchUserLibrary.tool.d.ts","sourceRoot":"","sources":["../../../../src/services/agent/tools/searchUserLibrary.tool.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,EAAgB,cAAc,EAAE,MAAM,iBAAiB,CAAC;AAE/D;;;;;;;GAOG;AAEH,MAAM,WAAW,gBAAgB;IAC/B,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,OAAO,GAAG,OAAO,GAAG,OAAO,GAAG,aAAa,GAAG,aAAa,CAAC;IAClE,GAAG,EAAE,MAAM,CAAC;IACZ,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,SAAS,EAAE,MAAM,CAAC;CACnB;AAED,MAAM,MAAM,mBAAmB,GAAG,CAAC,MAAM,EAAE;IACzC,MAAM,EAAE,MAAM,CAAC;IACf,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,CAAC,EAAE,gBAAgB,CAAC,MAAM,CAAC,CAAC;IAChC,KAAK,EAAE,MAAM,CAAC;CACf,KAAK,OAAO,CAAC,gBAAgB,EAAE,CAAC,CAAC;AAGlC,wBAAgB,oBAAoB,CAAC,EAAE,EAAE,mBAAmB,GAAG,IAAI,CAElE;AAED,QAAA,MAAM,WAAW;;;;;;;;;;iBASf,CAAC;AAEH,QAAA,MAAM,YAAY;;;;;;;;;;;;;;;;;iBAahB,CAAC;AAEH,eAAO,MAAM,qBAAqB,EAAE,cAAc,CAChD,OAAO,WAAW,EAClB,OAAO,YAAY,CA2BpB,CAAC"}

package/lib/services/agent/tools/searchUserLibrary.tool.js

@@ -0,0 +1,58 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.searchUserLibraryTool = void 0;
+exports.setUserLibrarySearch = setUserLibrarySearch;
+const zod_1 = require("zod");
+const toolRegistry_1 = require("../toolRegistry");
+let injectedSearch = null;
+function setUserLibrarySearch(fn) {
+    injectedSearch = fn;
+}
+const InputSchema = zod_1.z.object({
+    query: zod_1.z
+        .string()
+        .min(1)
+        .describe("Free-text query — semantic match against asset prompts and tags."),
+    kind: zod_1.z
+        .enum(["image", "video", "audio", "stock-image", "stock-video"])
+        .optional(),
+    limit: zod_1.z.number().int().min(1).max(20).default(8),
+});
+const OutputSchema = zod_1.z.object({
+    assets: zod_1.z.array(zod_1.z.object({
+        id: zod_1.z.string(),
+        kind: zod_1.z.enum(["image", "video", "audio", "stock-image", "stock-video"]),
+        url: zod_1.z.string().url(),
+        prompt: zod_1.z.string().optional(),
+        width: zod_1.z.number().optional(),
+        height: zod_1.z.number().optional(),
+        durationMs: zod_1.z.number().optional(),
+        createdAt: zod_1.z.string(),
+    })),
+});
+exports.searchUserLibraryTool = {
+    name: "search_user_library",
+    description: [
+        "Search the requesting user's previously-generated/uploaded assets before",
+        "spending credits to make a new one. Always try this BEFORE generate_image",
+        "or search_stock when the brief calls for something the user has likely",
+        "produced before (their product photos, recurring characters, brand b-roll).",
+        "Returns ranked candidates; the agent picks the best fit by prompt/durationMs/aspect.",
+    ].join(" "),
+    inputSchema: InputSchema,
+    outputSchema: OutputSchema,
+    idempotent: true,
+    handler: async (input, ctx) => {
+        if (!injectedSearch) {
+            throw new Error("search_user_library: no searcher wired. Host must call setUserLibrarySearch() at boot.");
+        }
+        const assets = await injectedSearch({
+            userId: ctx.userId,
+            query: input.query,
+            kind: input.kind,
+            limit: input.limit,
+        });
+        return { assets };
+    },
+};
+(0, toolRegistry_1.registerTool)(exports.searchUserLibraryTool);

package/lib/services/agent/ttsDuration.d.ts

@@ -0,0 +1,29 @@
+/**
+ * AG-28: TTS duration estimator.
+ *
+ * The planner has no idea how long the TTS engine will speak the line it just
+ * wrote, so it picks scene.durationMs based on visual pacing alone. When the
+ * VO turns out longer than the scene, the stitcher (or any video-bound mux)
+ * clips the voice mid-sentence — fatal for a UGC ad.
+ *
+ * This estimator gives the planner + executor a shared "how long will this
+ * speak?" math so both sides can budget around it BEFORE the TTS call. We
+ * deliberately err high (slower wpm) so we under-budget rather than over-
+ * budget — clipped audio is worse than slight dead-air.
+ *
+ * Calibration: ElevenLabs `eleven_multilingual_v2` at default speed reads
+ * conversational English at ~150-165 wpm. Slower-paced narration drops to
+ * ~120 wpm. We use 150 wpm as the default to match the casual/UGC voices
+ * the platform uses most.
+ */
+/** Returns a conservative estimate (ms) of how long a TTS engine will speak `text`. */
+export declare function estimateTtsMs(text: string, wpm?: number): number;
+/**
+ * Inverse: max VO words that comfortably fit in `durationMs` at default speed.
+ * Used by the planner-prompt math hint so the LLM knows how long a line can be
+ * for a given scene without having to compute the formula itself.
+ */
+export declare function maxVoWordsForMs(durationMs: number, wpm?: number): number;
+export declare const TTS_DEFAULT_WPM = 150;
+export declare const TTS_DEFAULT_WPS: number;
+//# sourceMappingURL=ttsDuration.d.ts.map

package/lib/services/agent/ttsDuration.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ttsDuration.d.ts","sourceRoot":"","sources":["../../../src/services/agent/ttsDuration.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAMH,uFAAuF;AACvF,wBAAgB,aAAa,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,GAAE,MAAoB,GAAG,MAAM,CAkB7E;AAED;;;;GAIG;AACH,wBAAgB,eAAe,CAAC,UAAU,EAAE,MAAM,EAAE,GAAG,GAAE,MAAoB,GAAG,MAAM,CAKrF;AAED,eAAO,MAAM,eAAe,MAAc,CAAC;AAC3C,eAAO,MAAM,eAAe,QAAc,CAAC"}

package/lib/services/agent/ttsDuration.js

@@ -0,0 +1,60 @@
+"use strict";
+/**
+ * AG-28: TTS duration estimator.
+ *
+ * The planner has no idea how long the TTS engine will speak the line it just
+ * wrote, so it picks scene.durationMs based on visual pacing alone. When the
+ * VO turns out longer than the scene, the stitcher (or any video-bound mux)
+ * clips the voice mid-sentence — fatal for a UGC ad.
+ *
+ * This estimator gives the planner + executor a shared "how long will this
+ * speak?" math so both sides can budget around it BEFORE the TTS call. We
+ * deliberately err high (slower wpm) so we under-budget rather than over-
+ * budget — clipped audio is worse than slight dead-air.
+ *
+ * Calibration: ElevenLabs `eleven_multilingual_v2` at default speed reads
+ * conversational English at ~150-165 wpm. Slower-paced narration drops to
+ * ~120 wpm. We use 150 wpm as the default to match the casual/UGC voices
+ * the platform uses most.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.TTS_DEFAULT_WPS = exports.TTS_DEFAULT_WPM = void 0;
+exports.estimateTtsMs = estimateTtsMs;
+exports.maxVoWordsForMs = maxVoWordsForMs;
+const DEFAULT_WPM = 150;
+/** Words per second derived from default wpm. */
+const DEFAULT_WPS = DEFAULT_WPM / 60;
+/** Returns a conservative estimate (ms) of how long a TTS engine will speak `text`. */
+function estimateTtsMs(text, wpm = DEFAULT_WPM) {
+    if (!text)
+        return 0;
+    const words = text
+        .trim()
+        .split(/\s+/)
+        .filter(Boolean).length;
+    if (words === 0)
+        return 0;
+    // Add per-clause pause budget: each comma/semicolon/em-dash adds ~150ms,
+    // each terminal punctuation (. ? !) adds ~250ms. These dominate short lines
+    // where the word count alone under-counts.
+    const punctPauseMs = (text.match(/[,;–—]/g)?.length ?? 0) * 150 +
+        (text.match(/[.?!]/g)?.length ?? 0) * 250;
+    const wps = wpm / 60;
+    const wordsMs = (words / wps) * 1000;
+    // Floor at 800ms — even one-syllable utterances ("Yes." "Wait.") need
+    // setup + decay time on real TTS.
+    return Math.max(800, Math.round(wordsMs + punctPauseMs));
+}
+/**
+ * Inverse: max VO words that comfortably fit in `durationMs` at default speed.
+ * Used by the planner-prompt math hint so the LLM knows how long a line can be
+ * for a given scene without having to compute the formula itself.
+ */
+function maxVoWordsForMs(durationMs, wpm = DEFAULT_WPM) {
+    const wps = wpm / 60;
+    // Subtract a 250ms terminal-punctuation budget to be safe.
+    const usableMs = Math.max(0, durationMs - 250);
+    return Math.max(1, Math.floor((usableMs / 1000) * wps));
+}
+exports.TTS_DEFAULT_WPM = DEFAULT_WPM;
+exports.TTS_DEFAULT_WPS = DEFAULT_WPS;

package/lib/services/aiGen/aiGenFactory.service.d.ts

@@ -1,7 +1,27 @@
 import { BaseAiGenProviderService } from "./providers/baseAiGenProvider.service";
-import { ETextGenModels, EVideoGenModels, TAiGenModel } from "../../globals/aiModels";
+import { EImageGenModelKey, EMusicGenModels, ESfxGenModels, ETextGenModels, EVideoGenModels, TAiGenModel } from "../../globals/aiModels";
 type AiGenServiceConstructor = new () => BaseAiGenProviderService;
 export declare const videoServicesMap: Record<EVideoGenModels, AiGenServiceConstructor>;
+/**
+ * Image-gen factory. Each provider service implements `generateImage()` (sync;
+ * returns a URL or base64 in a single API roundtrip — no BullMQ worker needed).
+ *
+ * Kling now has a first-party image API (api-singapore.klingai.com, same JWT auth as video):
+ *   /v1/images/omni-image   → kling-image-o1, kling-v3-omni  → KlingImageService
+ *   /v1/images/generations  → kling-v2-1-image               → KlingImageService
+ * The legacy kling-kolors key still routes to AlibabaService (DashScope-hosted Kolors v2).
+ */
+export declare const imageServicesMap: Record<EImageGenModelKey, AiGenServiceConstructor>;
+/**
+ * Music-gen factory. Each provider service implements `generateMusic()` (sync —
+ * single API roundtrip, no BullMQ worker).
+ */
+export declare const musicServicesMap: Record<EMusicGenModels, AiGenServiceConstructor>;
+/**
+ * Sound-effects factory. Each provider service implements `generateSoundEffects()`
+ * (sync — single API roundtrip, no BullMQ worker).
+ */
+export declare const sfxServicesMap: Record<ESfxGenModels, AiGenServiceConstructor>;
 export declare const textServicesMap: Record<ETextGenModels, AiGenServiceConstructor>;
 export declare function getAiGenProviderService(modelKey: TAiGenModel): BaseAiGenProviderService;
 export {};

package/lib/services/aiGen/aiGenFactory.service.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"aiGenFactory.service.d.ts","sourceRoot":"","sources":["../../../src/services/aiGen/aiGenFactory.service.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,wBAAwB,EAAE,MAAM,uCAAuC,CAAC;AACjF,OAAO,EACL,cAAc,EACd,eAAe,EACf,WAAW,EACZ,MAAM,wBAAwB,CAAC;AAYhC,KAAK,uBAAuB,GAAG,UAAU,wBAAwB,CAAC;AAElE,eAAO,MAAM,gBAAgB,EAAE,MAAM,CACnC,eAAe,EACf,uBAAuB,CAsDxB,CAAC;AAUF,eAAO,MAAM,eAAe,EAAE,MAAM,CAAC,cAAc,EAAE,uBAAuB,CAQzE,CAAC;AAEJ,wBAAgB,uBAAuB,CACrC,QAAQ,EAAE,WAAW,GACpB,wBAAwB,CAY1B"}
+{"version":3,"file":"aiGenFactory.service.d.ts","sourceRoot":"","sources":["../../../src/services/aiGen/aiGenFactory.service.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,wBAAwB,EAAE,MAAM,uCAAuC,CAAC;AACjF,OAAO,EACL,iBAAiB,EAEjB,eAAe,EACf,aAAa,EACb,cAAc,EACd,eAAe,EACf,WAAW,EACZ,MAAM,wBAAwB,CAAC;AAahC,KAAK,uBAAuB,GAAG,UAAU,wBAAwB,CAAC;AAElE,eAAO,MAAM,gBAAgB,EAAE,MAAM,CACnC,eAAe,EACf,uBAAuB,CAyDxB,CAAC;AAEF;;;;;;;;GAQG;AACH,eAAO,MAAM,gBAAgB,EAAE,MAAM,CACnC,iBAAiB,EACjB,uBAAuB,CAuCxB,CAAC;AAEF;;;GAGG;AACH,eAAO,MAAM,gBAAgB,EAAE,MAAM,CACnC,eAAe,EACf,uBAAuB,CAMxB,CAAC;AAEF;;;GAGG;AACH,eAAO,MAAM,cAAc,EAAE,MAAM,CACjC,aAAa,EACb,uBAAuB,CAGxB,CAAC;AAEF,eAAO,MAAM,eAAe,EAAE,MAAM,CAAC,cAAc,EAAE,uBAAuB,CAQzE,CAAC;AAEJ,wBAAgB,uBAAuB,CACrC,QAAQ,EAAE,WAAW,GACpB,wBAAwB,CAkB1B"}