@mevdragon/vidfarm-devcli 0.9.0 → 0.11.0

package/dist/src/editor-chat.js

@@ -34,14 +34,15 @@ export function buildTemplateEditorChatSystemPrompt(input) {
         "Execute REST calls sequentially. Make one API call, inspect the response, then decide the next step.",
         "A queued async POST job is enough inspection for that request. Do not poll it in the same response; continue launching any remaining requested outputs, then summarize the queued jobs.",
         "Primitive routes under /api/v1/primitives are first-class allowed routes in this editor, even when the primitive is not specific to the current template.",
-        "Never say you cannot use primitive image generation, image edit, inpaint, HTML render, AI video generation, or video render routes directly from this editor chat; use the http_request tool when the requested primitive route exists.",
+        "Never say you cannot use primitive image generation, image edit, inpaint, HTML render, AI video generation, text-to-speech, speech transcription, or video render routes directly from this editor chat; use the http_request tool when the requested primitive route exists.",
         "All primitive POST routes require the same outer JSON envelope: top-level tracer, top-level payload containing the primitive-specific fields, and optional webhook_url.",
         "When the user explicitly asks to use primitives or timeline rendering, do not redirect them to old per-template operation routes unless the requested primitive route cannot accept the available inputs.",
         "If the user asks to create, generate, or make a new image similar to an attached image, call POST /api/v1/primitives/images/generate with body { tracer, payload: { prompt, prompt_attachments: [exact attachment URL] } }.",
         "Use POST /api/v1/primitives/images/edit only when the user wants to revise the attached/source image itself; its body is { tracer, payload: { source_image_url, instruction, reference_attachments? } }. Use POST /api/v1/primitives/images/generate when they want a new image inspired by or similar to the attachment.",
         "If the user asks to modify an attached image and the message includes an attachment URL, call POST /api/v1/primitives/images/edit with source_image_url inside payload set to that exact URL and instruction inside payload set to the requested edit.",
         "If the user asks to generate a new AI video from text or reference images, call POST /api/v1/primitives/videos/generate with body { tracer, payload: { prompt, input_references?, duration? } }. AI video duration is seconds; use duration: 4 for a 4-second video and never use duration_ms on /videos/generate. input_references must be direct image asset URLs, not webpage or social post URLs. Use frame_images for exact first/last-frame image-to-video.",
-        "If the user asks to render HTML/design into an image, call POST /api/v1/primitives/images/render-html. If the user asks to turn existing media URLs into a slideshow/video, call POST /api/v1/primitives/videos/render-slides. If the user asks to dedupe, camouflage, or apply small zoom/tilt/rotate/filter/tint transforms to an image or video for reuse, call POST /api/v1/primitives/media/dedupe with body { tracer, payload: { source_media_url, media_type?, effects?: { zoom?, tilt?, rotate?, saturation?, speed?, horizontal_flip?, contrast?, brightness?, hue_rotate?, blur? }, tint_color?, tint_opacity?, width?, height?, duration_ms?, object_fit?, background_color?, output_format? }, webhook_url? }. Primitive media utility routes are also allowed directly here, including /videos/trim, /videos/remove-captions, /videos/extract-audio, /videos/probe, /videos/extract-frame, /videos/mute, /videos/replace-audio, /videos/concat, /audio/trim, /audio/probe, /audio/concat, and /audio/normalize. If the user asks to remove burned-in captions, subtitles, or on-screen text from a video, call POST /api/v1/primitives/videos/remove-captions with body { tracer, payload: { source_video_url } } — an async job that returns a durable caption-free MP4 and bills about $0.10 per 30 seconds of source video.",
+        "If the user asks to render HTML/design into an image, call POST /api/v1/primitives/images/render-html. If the user asks to turn existing media URLs into a slideshow/video, call POST /api/v1/primitives/videos/render-slides. If the user asks to dedupe, camouflage, or apply small zoom/tilt/rotate/filter/tint transforms to an image or video for reuse, call POST /api/v1/primitives/media/dedupe with body { tracer, payload: { source_media_url, media_type?, effects?: { zoom?, tilt?, rotate?, saturation?, speed?, horizontal_flip?, contrast?, brightness?, hue_rotate?, blur? }, tint_color?, tint_opacity?, width?, height?, duration_ms?, object_fit?, background_color?, output_format? }, webhook_url? }. Primitive media utility routes are also allowed directly here, including /videos/trim, /videos/remove-captions, /videos/extract-audio, /videos/probe, /videos/extract-frame, /videos/mute, /videos/replace-audio, /videos/concat, /audio/trim, /audio/probe, /audio/concat, and /audio/normalize. If the user asks to remove burned-in captions, subtitles, or on-screen text from a video, call POST /api/v1/primitives/videos/remove-captions with body { tracer, payload: { source_video_url } } — an async job that returns a durable caption-free MP4 and bills about $0.10 per 30 seconds of source video. Caption removal is capped at ~15 minutes of source and must NEVER be used on long-form video: when the user wants short clips out of a long video (a podcast, stream VOD, webinar, or a YouTube/TikTok/IG/X URL), call POST /clips/scan instead with body { source_url | temp_file_id | s3_key, prompt, ranges?: [\"MM:SS-MM:SS\"], target_duration_sec?, aspect?: \"9:16\"|\"16:9\"|\"4:3\"|\"1:1\", avoid_text?, tracer? } — target_duration_sec is a SOFT range (30 → 20-40s), ranges restrict the hunt to those source windows (big cost saver), aspect crops every clip, and avoid_text prefers text-free scenes via scene SELECTION (never caption removal on the source). The hunt is async (202 + scan_id): poll GET /clips/scan/:scanId, then browse GET /clips/feed?source=<source_video_id> or POST /clips/search. Hunts bill AWS compute only — the AI tagging runs on the user's own saved provider keys. To erase captions from a finished HUNTED clip, pass that short mp4 to /videos/remove-captions afterwards.",
+        "SPEECH PRIMITIVES (TTS/STT) are first-class here. VOICEOVER / NARRATION: when the user wants a script, hook, caption, or dub read aloud as AI audio, call POST /api/v1/primitives/audio/speech with body { tracer, payload: { text, voice?, instructions?, provider?, model?, output_format? } } — instructions is a free-form voice-STYLE prompt (tone, pacing, accent, emotion, persona; e.g. 'calm warm bedtime narrator' or 'excited sports announcer, fast paced'), and voice picks a provider preset (OpenAI: alloy/ash/coral/...; Gemini: Kore/Puck/Charon/...). The finished job returns a durable audio URL — place it on the timeline with editor_action add_layer (kind=audio, src=that URL), typically starting where the narration should begin. TRANSCRIPTION: when the user wants a transcript, subtitles/captions from speech, a translation source, or to know who says what, call POST /api/v1/primitives/audio/transcribe with body { tracer, payload: { source_url, diarize?, language?, prompt? } } — source_url may be a VIDEO or AUDIO URL (video audio is demuxed automatically; pick the fork's source via GET /api/v1/compositions/:forkId/remove-video-captions first when transcribing the current composition). One job returns BOTH formats: a simple subtitle version (plain transcript text + timed SRT cues, stored as transcript.txt/transcript.srt) and an advanced multi-speaker version (speaker-attributed timed segments in output.segments and transcript.json) for multi-narration sources like podcasts and interviews. diarize defaults to true and speaker attribution needs a Gemini key — openai/openrouter keys degrade to a plain single-speaker transcript. For transcript-grounded caption work on THIS fork, the read-only video_context tool may already contain the decompose-time transcript; prefer it before running a new billable-key transcription, and use /audio/transcribe for other URLs, multi-speaker attribution, or SRT output.",
         "Brainstorm primitives are also available directly here. If the user explicitly asks for hooks, angles, awareness-stage advice, a cold-start strategy questionnaire, or product-placement opportunities in a video, call the matching brainstorm primitive immediately instead of brainstorming in chat from memory. Use POST /api/v1/primitives/brainstorm/coldstart with body { tracer, payload: { user_message }, webhook_url? } when the user is clueless and needs foundational strategy questions. Use /brainstorm/awareness_stages with body { tracer, payload: { offer_description }, webhook_url? } when they are unsure what type of ads to make. Use /brainstorm/angles with body { tracer, payload: { offer_description, problem_awareness, solution_awareness }, webhook_url? } when they want persuasive ad angles; problem_awareness must be problem_unaware or problem_aware, and solution_awareness must be solution_unaware or solution_aware. Use /brainstorm/hooks with body { tracer, payload: { offer_description }, webhook_url? } when they are stuck on openings and want many hooks.",
         "Product placement is a first-class brainstorm primitive, just like angles and hooks. When the user asks to identify product-placement opportunities in a video, or to repurpose a video into a native ad for their product, prefer POST /api/v1/primitives/brainstorm/product_placement with body { tracer, payload: { source_video_url, offer_description }, webhook_url? }. source_video_url is the exact video to analyze — for the current composition, first call GET /api/v1/compositions/:forkId/remove-video-captions to pick the correct source (the ORIGINAL uploaded video vs the DECOMPOSED, caption-free video), then pass that URL. offer_description is the user's product/offer. This primitive watches the video and returns timestamped, native placement opportunities. It prefers a Gemini key for video understanding.",
         "BEFORE calling /brainstorm/product_placement for the CURRENT composition, first call the product_placement_context tool (or GET /api/v1/compositions/:forkId/product-placement.json). Decompose already scouted product-AGNOSTIC placement surfaces for this fork — real, grounded moments (timestamp, surface_type, surface_note, best_for, why_it_works). Use those surfaces to ground your answer and to seed the primitive: fold the strongest surfaces into offer_description (for example append 'Known native placement surfaces: 0:04 empty desk prop; 0:12 phone screen swap') so the product-specific pass builds on grounded moments instead of re-watching blind. If the user just wants a quick conversational take on where their product could go, the surfaces from product_placement_context are often enough to answer directly without the billable primitive.",

package/dist/src/frontend/homepage-view.js

@@ -11,9 +11,6 @@ function LibraryIcon() {
 function CalendarIcon() {
     return _jsxs("svg", { viewBox: "0 0 20 20", fill: "none", stroke: "currentColor", strokeWidth: "1.7", strokeLinecap: "round", strokeLinejoin: "round", children: [_jsx("circle", { cx: "10", cy: "10", r: "7.2" }), _jsx("path", { d: "M10 6.3v4.1l2.8 1.7" })] });
 }
-function ClipsIcon() {
-    return _jsxs("svg", { viewBox: "0 0 20 20", fill: "none", stroke: "currentColor", strokeWidth: "1.7", strokeLinecap: "round", strokeLinejoin: "round", children: [_jsx("rect", { x: "3", y: "4.5", width: "14", height: "11", rx: "1.5" }), _jsx("path", { d: "M3 8h14" }), _jsx("path", { d: "M6.2 4.7 4.6 8" }), _jsx("path", { d: "M9.6 4.7 8 8" }), _jsx("path", { d: "M13 4.7 11.4 8" })] });
-}
 function ChatIcon() {
     return _jsxs("svg", { viewBox: "0 0 20 20", fill: "none", stroke: "currentColor", strokeWidth: "1.7", strokeLinecap: "round", strokeLinejoin: "round", children: [_jsx("path", { d: "M4.2 5.2a2 2 0 0 1 2-2h7.6a2 2 0 0 1 2 2v5.6a2 2 0 0 1-2 2H9.2l-4.1 3.1v-3.1a2 2 0 0 1-.9-1.7Z" }), _jsx("path", { d: "M7.3 7.1h5.4" }), _jsx("path", { d: "M7.3 9.6h3.7" })] });
 }
@@ -58,13 +55,11 @@ function PrimaryNav({ account }) {
         ? [
             { id: "discover", href: withAccountQuery("/discover", account.userId), label: "Discover", icon: _jsx(DiscoverIcon, {}) },
             { id: "library", href: withAccountQuery("/library", account.userId), label: "Library", icon: _jsx(LibraryIcon, {}) },
-            { id: "clips", href: "/clips", label: "Clips", icon: _jsx(ClipsIcon, {}) },
             { id: "calendar", href: withAccountQuery("/calendar", account.userId), label: "Calendar", icon: _jsx(CalendarIcon, {}) },
             { id: "settings", href: withAccountQuery("/settings", account.userId), label: "Settings", icon: _jsx(SettingsIcon, {}) }
         ]
         : [
             { id: "discover", href: "/discover", label: "Discover", icon: _jsx(DiscoverIcon, {}) },
-            { id: "clips", href: "/clips", label: "Clips", icon: _jsx(ClipsIcon, {}) },
             { id: "login", href: "/login", label: "Login", icon: _jsx(SettingsIcon, {}) }
         ];
     const menuItems = account.isLoggedIn

package/dist/src/page-shell.js

@@ -756,6 +756,53 @@ export function renderPageShell(input) {
         color: var(--muted);
       }
 
+      .view-toggle {
+        display: inline-flex;
+        flex: 0 0 auto;
+        gap: 4px;
+        padding: 3px;
+        border: 1px solid rgba(191, 164, 109, 0.28);
+        border-radius: 999px;
+        background: linear-gradient(180deg, rgba(247, 241, 230, 0.94), rgba(244, 236, 223, 0.96));
+        box-shadow:
+          inset 0 1px 0 rgba(255, 255, 255, 0.88),
+          0 8px 18px rgba(138, 102, 32, 0.08);
+      }
+
+      .view-toggle-tab {
+        display: inline-flex;
+        align-items: center;
+        justify-content: center;
+        min-height: 38px;
+        padding: 0 18px;
+        border: 1px solid transparent;
+        border-radius: 999px;
+        background: transparent;
+        color: #6f6451;
+        text-decoration: none;
+        font-size: 0.9rem;
+        font-weight: 700;
+        font-family: inherit;
+        white-space: nowrap;
+        cursor: pointer;
+        box-shadow: none;
+        transition: background 160ms ease, color 160ms ease, border-color 160ms ease, box-shadow 160ms ease;
+      }
+
+      @media (hover: hover) {
+        .view-toggle-tab:hover {
+          transform: none;
+          color: var(--ink);
+        }
+      }
+
+      .view-toggle-tab.is-active {
+        border-color: rgba(232, 223, 204, 0.9);
+        background: rgba(255, 252, 247, 0.96);
+        color: var(--ink);
+        box-shadow: 0 8px 20px rgba(101, 73, 18, 0.08);
+      }
+
       .button,
       button,
       .link-button,

package/dist/src/primitive-context.js

@@ -181,6 +181,22 @@ export function createPrimitiveJobContext(input) {
                     workerId: input.workerId,
                     ...request
                 });
+            },
+            async generateSpeech(request) {
+                return input.providers.generateSpeech({
+                    customerId: input.customer.id,
+                    jobId: input.job.id,
+                    workerId: input.workerId,
+                    ...request
+                });
+            },
+            async transcribeSpeech(request) {
+                return input.providers.transcribeSpeech({
+                    customerId: input.customer.id,
+                    jobId: input.job.id,
+                    workerId: input.workerId,
+                    ...request
+                });
             }
         },
         hyperframes: {

package/dist/src/primitive-registry.js

@@ -7,6 +7,7 @@ import { config } from "./config.js";
 import { definePrimitive } from "./primitive-sdk.js";
 import { PrimitiveMediaLambdaService } from "./services/primitive-media-lambda.js";
 import { estimateGhostcutCostUsd, isGhostcutConfigured, pollStatus as pollGhostcutStatus, submitSubtitleRemoval } from "./services/ghostcut.js";
+import { buildSrtFromSegments, defaultSpeechModelFor } from "./services/speech.js";
 import { buildHtmlImageCompositionHtml, buildMediaDedupeCompositionHtml, DEDUPE_DEFAULT_EFFECTS } from "./primitives/hyperframes-media.js";
 const imageProviderSchema = z.enum(["openai", "gemini", "openrouter"]);
 const videoProviderSchema = z.enum(["openai", "gemini", "openrouter"]);
@@ -358,6 +359,47 @@ const trimAudioPayloadSchema = z.object({
     message: "Either duration_ms or end_ms is required.",
     path: ["duration_ms"]
 });
+const speechProviderSchema = z.enum(["openai", "gemini", "openrouter"]);
+const ttsPayloadSchema = z.preprocess((raw) => {
+    if (!raw || typeof raw !== "object" || Array.isArray(raw))
+        return raw;
+    const payload = raw;
+    return {
+        ...payload,
+        text: payload.text ?? payload.input ?? payload.script,
+        instructions: payload.instructions ?? payload.style ?? payload.style_instructions ?? payload.voice_style
+    };
+}, z.object({
+    provider: speechProviderSchema.optional(),
+    model: z.string().min(1).optional(),
+    text: z.string().min(1).max(8000),
+    voice: z.string().min(1).max(120).optional(),
+    instructions: z.string().min(1).max(4000).optional(),
+    output_format: z.enum(["mp3", "wav"]).default("mp3")
+}));
+const sttPayloadSchema = z.preprocess((raw) => {
+    if (!raw || typeof raw !== "object" || Array.isArray(raw))
+        return raw;
+    const payload = raw;
+    return {
+        ...payload,
+        source_url: payload.source_url ??
+            payload.source_video_url ??
+            payload.source_audio_url ??
+            payload.source_media_url ??
+            payload.video_url ??
+            payload.audio_url ??
+            payload.url
+    };
+}, z.object({
+    provider: speechProviderSchema.optional(),
+    model: z.string().min(1).optional(),
+    source_url: mediaSourceUrlSchema,
+    media_type: z.enum(["auto", "video", "audio"]).default("auto"),
+    diarize: z.boolean().default(true),
+    language: z.string().min(2).max(16).optional(),
+    prompt: z.string().min(1).max(2000).optional()
+}));
 const probeVideoPayloadSchema = z.object({
     source_video_url: mediaSourceUrlSchema
 });
@@ -508,6 +550,14 @@ const PRIMITIVE_BRAINSTORM_ANGLES_ID = "primitive:brainstorm_angles";
 const PRIMITIVE_BRAINSTORM_COLDSTART_ID = "primitive:brainstorm_coldstart";
 const PRIMITIVE_BRAINSTORM_PRODUCT_PLACEMENT_ID = "primitive:brainstorm_product_placement";
 const PRIMITIVE_MEDIA_DEDUPE_ID = "primitive:media_dedupe";
+const PRIMITIVE_TTS_ID = "primitive:tts";
+const PRIMITIVE_STT_ID = "primitive:stt";
+// Gemini inline audio caps out around 20MB; at the 64kbps mono mp3 we extract,
+// that is roughly 40 minutes of speech.
+const MAX_TRANSCRIBE_AUDIO_BYTES = 20 * 1024 * 1024;
+// Keep job results comfortably under the DynamoDB item limit: transcripts
+// longer than this inline budget stay artifact-only (transcript.json).
+const MAX_INLINE_TRANSCRIPT_CHARS = 20_000;
 const primitiveMediaService = new PrimitiveMediaLambdaService();
 const hooksReferenceText = readPrimitiveAsset("SELLING_WITH_HOOKS.md");
 const awarenessReferenceText = readPrimitiveAsset("SELLING_AWARENESS_STAGES.md");
@@ -1403,6 +1453,13 @@ const videoRemoveCaptionsPrimitive = definePrimitive({
             }
             const probedDurationSeconds = Number(probeMetadata.durationSeconds ?? 0);
             const durationSeconds = Number.isFinite(probedDurationSeconds) && probedDurationSeconds > 0 ? probedDurationSeconds : 30;
+            // GhostCut is a per-FINISHED-CLIP tool, never a long-form pass. Clip
+            // hunting handles "no captions" as a scene-selection filter (avoid_text);
+            // after the hunt, apply caption removal to individual finished clips.
+            if (config.GHOSTCUT_MAX_DURATION_SEC > 0 && durationSeconds > config.GHOSTCUT_MAX_DURATION_SEC) {
+                throw new Error(`Caption removal is limited to videos up to ${Math.round(config.GHOSTCUT_MAX_DURATION_SEC / 60)} minutes (this source is ${Math.round(durationSeconds / 60)} min). ` +
+                    `For long-form video, hunt clips first (POST /clips/scan with avoid_text/no-captions guidance selects text-free scenes), then remove captions from the finished clips you keep.`);
+            }
             const cost = estimateGhostcutCostUsd(durationSeconds);
             ctx.logger.progress(0.12, "Submitting caption-removal task", {
                 durationSeconds: Number(durationSeconds.toFixed(3)),
@@ -1559,6 +1616,181 @@ const audioTrimPrimitive = definePrimitive({
         }
     }
 });
+const ttsPrimitive = definePrimitive({
+    id: PRIMITIVE_TTS_ID,
+    kind: "tts",
+    operations: {
+        run: {
+            description: "Generate spoken narration audio from text (TTS) with a promptable voice style, persisted as a reusable platform audio URL.",
+            inputSchema: ttsPayloadSchema,
+            workflow: "run"
+        }
+    },
+    jobs: {
+        async run(ctx, input) {
+            const payload = ttsPayloadSchema.parse(input);
+            ctx.logger.progress(0.12, "Generating speech audio");
+            const provider = payload.provider ?? "openai";
+            const model = payload.model ?? defaultSpeechModelFor("tts", provider) ?? "";
+            const generated = await ctx.providers.generateSpeech({
+                provider,
+                model,
+                text: payload.text,
+                voice: payload.voice,
+                instructions: payload.instructions,
+                responseFormat: payload.output_format
+            });
+            // Gemini TTS answers in wav regardless of the requested format; name the
+            // artifact after what actually came back.
+            const extension = generated.contentType.includes("wav") ? "wav" : "mp3";
+            const stored = await ctx.storage.putBuffer(`speech.${extension}`, generated.bytes, {
+                contentType: generated.contentType,
+                kind: "audio",
+                metadata: {
+                    primitive: "tts",
+                    provider,
+                    model,
+                    voice: payload.voice ?? null,
+                    styleInstructions: payload.instructions ?? null
+                }
+            });
+            ctx.logger.progress(1, "Speech generation complete");
+            return {
+                progress: 1,
+                output: {
+                    files: compactUrls([stored.url]),
+                    primary_file_url: stored.url,
+                    audioUrl: stored.url,
+                    audio: {
+                        file_url: stored.url,
+                        content_type: generated.contentType,
+                        provider,
+                        model,
+                        voice: payload.voice ?? null,
+                        style_instructions: payload.instructions ?? null,
+                        text_length: payload.text.length
+                    }
+                }
+            };
+        }
+    }
+});
+const sttPrimitive = definePrimitive({
+    id: PRIMITIVE_STT_ID,
+    kind: "stt",
+    operations: {
+        run: {
+            description: "Transcribe speech from a video or audio URL (STT) into a simple subtitle transcript plus speaker-attributed multi-narration segments.",
+            inputSchema: sttPayloadSchema,
+            workflow: "run"
+        }
+    },
+    jobs: {
+        async run(ctx, input) {
+            const payload = sttPayloadSchema.parse(input);
+            const sourceKind = payload.media_type === "auto" ? inferSpeechSourceKind(payload.source_url) : payload.media_type;
+            let audioBytes;
+            let audioContentType;
+            let extractionMetadata = null;
+            if (sourceKind === "audio") {
+                ctx.logger.progress(0.1, "Fetching source audio");
+                const response = await fetch(payload.source_url);
+                if (!response.ok) {
+                    throw new Error(`Could not fetch source audio (${response.status}).`);
+                }
+                audioBytes = new Uint8Array(await response.arrayBuffer());
+                audioContentType = response.headers.get("content-type")?.split(";")[0]?.trim() || "audio/mpeg";
+            }
+            else {
+                // Videos (and unknown extensions) go through the ffmpeg seam: it
+                // demuxes video AND normalizes odd audio containers into a small
+                // mono mp3 the speech providers accept.
+                ctx.logger.progress(0.1, "Extracting audio track from source", {
+                    executionMode: config.VIDFARM_PRIMITIVE_MEDIA_LAMBDA_URL ? "lambda" : "local_fallback"
+                });
+                const extracted = await executePrimitiveMediaOperation(ctx, {
+                    operation: "video_extract_audio",
+                    payload: {
+                        source_video_url: payload.source_url,
+                        output_format: "mp3",
+                        audio_bitrate_kbps: 64
+                    },
+                    outputKey: "source-audio.mp3"
+                });
+                if (!extracted.publicUrl) {
+                    throw new Error("Audio extraction produced no readable audio URL.");
+                }
+                const response = await fetch(extracted.publicUrl);
+                if (!response.ok) {
+                    throw new Error(`Could not read extracted audio (${response.status}).`);
+                }
+                audioBytes = new Uint8Array(await response.arrayBuffer());
+                audioContentType = extracted.contentType || "audio/mpeg";
+                extractionMetadata = extracted.metadata ?? null;
+            }
+            if (audioBytes.byteLength > MAX_TRANSCRIBE_AUDIO_BYTES) {
+                const sizeMb = Math.round(audioBytes.byteLength / (1024 * 1024));
+                const maxMb = Math.round(MAX_TRANSCRIBE_AUDIO_BYTES / (1024 * 1024));
+                throw new Error(`Audio is too large to transcribe (${sizeMb}MB > ${maxMb}MB, roughly 40 minutes of speech). Trim the source with /videos/trim or /audio/trim and transcribe in parts.`);
+            }
+            ctx.logger.progress(0.45, "Transcribing speech");
+            const provider = payload.provider ?? "gemini";
+            const model = payload.model ?? defaultSpeechModelFor("stt", provider) ?? "";
+            const transcription = await ctx.providers.transcribeSpeech({
+                provider,
+                model,
+                audio: audioBytes,
+                contentType: audioContentType,
+                prompt: payload.prompt,
+                language: payload.language,
+                diarize: payload.diarize
+            });
+            ctx.logger.progress(0.85, "Storing transcript artifacts");
+            const speakers = [...new Set(transcription.segments.map((segment) => segment.speaker))];
+            const srt = buildSrtFromSegments(transcription.segments);
+            const storedText = await ctx.storage.putText("transcript.txt", transcription.text || "");
+            const storedSrt = srt ? await ctx.storage.putText("transcript.srt", srt, "application/x-subrip; charset=utf-8") : null;
+            const storedJson = await ctx.storage.putJson("transcript.json", {
+                source_url: payload.source_url,
+                provider,
+                model,
+                language: transcription.language,
+                diarization: transcription.diarization,
+                text: transcription.text,
+                speakers,
+                segments: transcription.segments,
+                ...(extractionMetadata ? { extraction: extractionMetadata } : {})
+            });
+            const inlineOk = (transcription.text?.length ?? 0) <= MAX_INLINE_TRANSCRIPT_CHARS;
+            ctx.logger.progress(1, "Speech transcription complete");
+            return {
+                progress: 1,
+                output: {
+                    files: compactUrls([storedJson.url, storedSrt?.url, storedText.url]),
+                    primary_file_url: storedJson.url,
+                    sourceUrl: payload.source_url,
+                    text: inlineOk ? transcription.text : transcription.text.slice(0, MAX_INLINE_TRANSCRIPT_CHARS),
+                    text_truncated: !inlineOk,
+                    language: transcription.language,
+                    diarization: transcription.diarization,
+                    // Format 1 — SIMPLE SUBTITLE VERSION: plain transcript + SRT cues (no speakers).
+                    subtitles: {
+                        srt: inlineOk ? srt : null,
+                        srt_url: storedSrt?.url ?? null,
+                        text_url: storedText.url
+                    },
+                    // Format 2 — ADVANCED MULTI-SPEAKER VERSION: speaker-attributed timed segments.
+                    speakers,
+                    segments: inlineOk ? transcription.segments : undefined,
+                    transcript: {
+                        json_url: storedJson.url,
+                        content_type: "application/json"
+                    }
+                }
+            };
+        }
+    }
+});
 const videoProbePrimitive = definePrimitive({
     id: PRIMITIVE_VIDEO_PROBE_ID,
     kind: "video_probe",
@@ -2135,6 +2367,8 @@ class PrimitiveRegistry {
         [videoConcatPrimitive.id, videoConcatPrimitive],
         [audioConcatPrimitive.id, audioConcatPrimitive],
         [audioNormalizePrimitive.id, audioNormalizePrimitive],
+        [ttsPrimitive.id, ttsPrimitive],
+        [sttPrimitive.id, sttPrimitive],
         [hyperframesRenderPrimitive.id, hyperframesRenderPrimitive],
         [brainstormHooksPrimitive.id, brainstormHooksPrimitive],
         [brainstormAwarenessStagesPrimitive.id, brainstormAwarenessStagesPrimitive],
@@ -2259,6 +2493,11 @@ function defaultTextModelForProvider(provider) {
             return "gpt-5.4-mini";
     }
 }
+// Extensions that are safe to feed a speech provider without the ffmpeg
+// normalization pass; everything else (video or unknown) gets demuxed first.
+function inferSpeechSourceKind(sourceUrl) {
+    return /\.(mp3|m4a|aac|ogg|oga|flac|wav)(\?|#|$)/i.test(sourceUrl) ? "audio" : "video";
+}
 function normalizeAiVideoDurationSeconds(explicitSeconds, milliseconds) {
     const seconds = Number(explicitSeconds);
     if (Number.isFinite(seconds) && seconds > 0) {

package/dist/src/services/billing.js

@@ -167,6 +167,9 @@ function resolveCostCenterSlug(input) {
             || explicitSlug === "primitive_media_lambda"
             || explicitSlug === "job_runner_lambda"
             || explicitSlug === "step_functions_standard"
+            // Clip hunting (long-form → short-form): AWS compute only — the AI
+            // tagging/embedding spend is BYOK and deliberately NOT wallet-billed.
+            || explicitSlug === "clip_scan_lambda"
             ? explicitSlug
             : null;
     }

package/dist/src/services/clip-curation/ffmpeg.js

@@ -101,18 +101,50 @@ export async function probeVideo(videoPath) {
  * Detect scene boundaries with the portable `select='gt(scene,T)',showinfo`
  * pass, parsing pts_time from ffmpeg's stderr. Falls back to fixed-interval
  * chunking when nothing is detected (e.g. a single continuous take), so a scan
- * always yields clips. Same command shape on devcli and cloud.
+ * always yields clips. Same command shape on devcli and cloud. With
+ * opts.windows set, each window is detected independently and scene times are
+ * offset back into source time.
  */
 export async function detectScenes(videoPath, opts = {}) {
+    const duration = opts.durationSec ?? (await probeVideo(videoPath)).duration_sec;
+    if (!Number.isFinite(duration) || duration <= 0)
+        return [];
+    const windows = (opts.windows ?? [])
+        .map((w) => ({ start_sec: Math.max(0, w.start_sec), end_sec: Math.min(w.end_sec, duration) }))
+        .filter((w) => w.end_sec - w.start_sec > 0.25);
+    if (windows.length === 0) {
+        return detectScenesInSpan(videoPath, { ...opts, durationSec: duration, spanStart: 0, spanEnd: duration, indexOffset: 0 });
+    }
+    const scenes = [];
+    for (const window of windows) {
+        const detected = await detectScenesInSpan(videoPath, {
+            ...opts,
+            durationSec: duration,
+            spanStart: window.start_sec,
+            spanEnd: window.end_sec,
+            indexOffset: scenes.length
+        });
+        scenes.push(...detected);
+    }
+    return scenes;
+}
+async function detectScenesInSpan(videoPath, opts) {
     const threshold = opts.threshold ?? 0.3;
     const minScene = opts.minSceneSec ?? 0.6;
     const maxScene = opts.maxSceneSec ?? 8;
-    const duration = opts.durationSec ?? (await probeVideo(videoPath)).duration_sec;
-    if (!Number.isFinite(duration) || duration <= 0)
+    const { spanStart, spanEnd } = opts;
+    const spanDuration = spanEnd - spanStart;
+    if (!Number.isFinite(spanDuration) || spanDuration <= 0)
         return [];
     const ffmpeg = await resolveFfmpeg();
+    // -ss/-t BEFORE -i: input-seek so only the window is decoded. pts_time then
+    // restarts near 0, so cuts are offset back by spanStart below.
+    const seekArgs = spanStart > 0 || spanEnd < (opts.durationSec ?? Infinity)
+        ? ["-ss", spanStart.toFixed(3), "-t", spanDuration.toFixed(3)]
+        : [];
     const { stderr } = await run(ffmpeg, [
         "-hide_banner",
+        ...seekArgs,
         "-i", videoPath,
         "-filter:v", `select='gt(scene,${threshold})',showinfo`,
         "-f", "null",
@@ -122,19 +154,19 @@ export async function detectScenes(videoPath, opts = {}) {
     const re = /pts_time:([0-9.]+)/g;
     let m;
     while ((m = re.exec(stderr)) !== null) {
-        const t = Number(m[1]);
-        if (Number.isFinite(t) && t > 0 && t < duration)
+        const t = Number(m[1]) + (seekArgs.length ? spanStart : 0);
+        if (Number.isFinite(t) && t > spanStart && t < spanEnd)
             cuts.push(t);
     }
     cuts.sort((a, b) => a - b);
-    // Build [0, cut1, cut2, …, duration] boundaries.
-    let bounds = [0, ...cuts, duration];
+    // Build [spanStart, cut1, cut2, …, spanEnd] boundaries.
+    let bounds = [spanStart, ...cuts, spanEnd];
     // If nothing detected, chunk at maxScene.
     if (cuts.length === 0) {
-        bounds = [0];
-        for (let t = maxScene; t < duration; t += maxScene)
+        bounds = [spanStart];
+        for (let t = spanStart + maxScene; t < spanEnd; t += maxScene)
             bounds.push(t);
-        bounds.push(duration);
+        bounds.push(spanEnd);
     }
     // Merge boundaries closer than minScene.
     const merged = [bounds[0]];
@@ -155,11 +187,11 @@ export async function detectScenes(videoPath, opts = {}) {
             for (let c = 0; c < chunks; c++) {
                 const s = start + c * step;
                 const e = c === chunks - 1 ? end : s + step;
-                scenes.push(makeScene(scenes.length, s, e));
+                scenes.push(makeScene(opts.indexOffset + scenes.length, s, e));
             }
         }
         else {
-            scenes.push(makeScene(scenes.length, start, end));
+            scenes.push(makeScene(opts.indexOffset + scenes.length, start, end));
         }
     }
     return scenes;
@@ -180,6 +212,7 @@ export async function extractKeyframes(input) {
     const points = count === 1
         ? [start + dur / 2]
         : Array.from({ length: count }, (_, i) => start + dur * ((i + 1) / (count + 1)));
+    const vf = input.cropFilter ? `${input.cropFilter},scale=${width}:-2` : `scale=${width}:-2`;
     const outPaths = [];
     for (let i = 0; i < points.length; i++) {
         const out = path.join(input.outDir, `scene-${input.scene.index}-kf${i}.jpg`);
@@ -188,7 +221,7 @@ export async function extractKeyframes(input) {
             "-ss", points[i].toFixed(3),
             "-i", input.videoPath,
             "-frames:v", "1",
-            "-vf", `scale=${width}:-2`,
+            "-vf", vf,
             "-q:v", "5",
             out
         ]);
@@ -202,32 +235,41 @@ export async function extractClip(input) {
     mkdirSync(path.dirname(input.outPath), { recursive: true });
     const ffmpeg = await resolveFfmpeg();
     const { start_time_sec: start, duration_sec: dur } = input.scene;
-    const args = input.reencode === false
+    // A crop cannot ride on stream-copy — force the re-encode path when present.
+    const args = input.reencode === false && !input.cropFilter
         ? ["-y", "-ss", start.toFixed(3), "-i", input.videoPath, "-t", dur.toFixed(3), "-c", "copy", "-avoid_negative_ts", "make_zero", input.outPath]
         : [
             "-y",
             "-ss", start.toFixed(3),
             "-i", input.videoPath,
             "-t", dur.toFixed(3),
+            ...(input.cropFilter ? ["-vf", input.cropFilter] : []),
             "-c:v", "libx264", "-preset", "veryfast", "-crf", "23", "-pix_fmt", "yuv420p",
             "-c:a", "aac", "-b:a", "128k",
             "-movflags", "+faststart",
             input.outPath
         ];
-    const { code } = await run(ffmpeg, args);
-    return code === 0 && existsSync(input.outPath);
+    const { code, stderr } = await run(ffmpeg, args);
+    const ok = code === 0 && existsSync(input.outPath);
+    if (!ok) {
+        input.onError?.(`ffmpeg exit ${code}: ${stderr.slice(-500).replace(/\s+/g, " ").trim()}`);
+    }
+    return ok;
 }
 /** Single representative thumbnail for the scene. */
 export async function extractThumbnail(input) {
     mkdirSync(path.dirname(input.outPath), { recursive: true });
     const ffmpeg = await resolveFfmpeg();
     const mid = input.scene.start_time_sec + input.scene.duration_sec / 2;
+    const vf = input.cropFilter
+        ? `${input.cropFilter},scale=${input.width ?? 320}:-2`
+        : `scale=${input.width ?? 320}:-2`;
     const { code } = await run(ffmpeg, [
         "-y",
         "-ss", mid.toFixed(3),
         "-i", input.videoPath,
         "-frames:v", "1",
-        "-vf", `scale=${input.width ?? 320}:-2`,
+        "-vf", vf,
         "-q:v", "3",
         input.outPath
     ]);