@mevdragon/vidfarm-devcli 0.19.0 → 0.20.0

package/dist/src/cli.js

@@ -285,6 +285,8 @@ Raws (the third library — mine long-form video into a reusable raws store):
     --tracer <name>           Group this session's clips (also the default folder)
     --folder <name>           Save the clip into /raws/<name>
     --name <text>             Human name for the clip
+    --audio-only              Save just the audio of the subrange as an .m4a raw
+                            (needs --start/--end; e.g. lift a copyright-free track)
                             (multi-clip: re-run with a new range + same --tracer)
 
 Speech (TTS/STT) — LOCAL-FIRST on your own AI key; --cloud is the explicit backup:
@@ -300,7 +302,19 @@ Speech (TTS/STT) — LOCAL-FIRST on your own AI key; --cloud is the explicit bac
     --engine local            KEYLESS local Kokoro-82M engine (free, no account) — fixed voice
                               presets (af_heart, am_adam, bf_emma, …), no --style. When NO
                               provider key is found the default byok engine auto-falls back here.
-    --cloud                   BACKUP: saved-key platform job   → POST /api/v1/primitives/audio/speech (+ poll)
+    --cloud                   BACKUP: platform job → POST /api/v1/primitives/audio/speech (+ poll).
+                              Defaults to ElevenLabs on the platform key (wallet-billed); --voice
+                              takes an ElevenLabs voice_id (see: vidfarm voices).
+    --own-key                 (--cloud) use your own ElevenLabs / BYOK key instead of the wallet
+    --list-voices             List ElevenLabs voices and exit (same as: vidfarm voices)
+  music "<prompt>"          Prompt → music track (ElevenLabs).            CLOUD-ONLY (no local engine)
+    --length <sec> | --length-ms <ms>   Duration (default 30s, max 5 min)
+    --out <file>              Output mp3 path (default music-<id>.mp3)
+    --own-key                 Use your own ElevenLabs key instead of the platform key + wallet
+                              (default: platform ElevenLabs, wallet-billed) → POST /api/v1/primitives/music/generate
+  voices                    List ElevenLabs voices for TTS (voice_id + name + labels).
+    --own-key                 List voices on your own saved ElevenLabs key (default: platform account)
+    --limit <n> | --json      Show more / raw JSON
   stt <file|url>            Video or audio → transcript (alias: transcribe).  LOCAL: local ffmpeg demux +
                             Returns BOTH formats: the simple subtitle    your provider key (gemini labels
                             version (plain text + timed SRT cues) and    speakers; openai/openrouter give
@@ -315,8 +329,11 @@ Speech (TTS/STT) — LOCAL-FIRST on your own AI key; --cloud is the explicit bac
                               timestamps (words[] in the .json/--json output), no speaker labels.
                               When NO provider key is found the default byok engine auto-falls
                               back here. --model then picks the whisper model (tiny.en…large-v3).
-    --cloud                   BACKUP: saved-key platform job   → POST /api/v1/primitives/audio/transcribe (+ poll)
+    --cloud                   BACKUP: platform job → POST /api/v1/primitives/audio/transcribe (+ poll).
+                              Defaults to ElevenLabs Scribe on the platform key (wallet-billed;
+                              native diarization + real word timings).
                               (a local file uploads to your temp folder first — 30-day TTL)
+    --own-key                 (--cloud) use your own ElevenLabs / BYOK key instead of the wallet
 
 Animated captions (word-by-word TikTok/CapCut styles on a pulled/served composition):
   captions generate <dir>   Transcribe the narration & lay down animated  LOCAL: local ffmpeg demux +
@@ -586,6 +603,12 @@ async function main() {
         case "tts":
             await runTtsCommand(rest);
             return;
+        case "music":
+            await runMusicCommand(rest);
+            return;
+        case "voices":
+            await runVoicesCommand(rest);
+            return;
         case "stt":
         case "transcribe":
             await runSttCommand(rest);
@@ -3045,10 +3068,17 @@ async function runTtsCommand(argv) {
             "gemini-key": { type: "string" },
             "openai-key": { type: "string" },
             "openrouter-key": { type: "string" },
+            "own-key": { type: "boolean", default: false },
+            "list-voices": { type: "boolean", default: false },
             "no-wait": { type: "boolean", default: false },
             tracer: { type: "string" }
         }
     });
+    // --list-voices: browse the ElevenLabs voice catalog and exit (cloud call).
+    if (parsed.values["list-voices"]) {
+        await runVoicesCommand(parsed.values["own-key"] ? ["--own-key"] : []);
+        return;
+    }
     const text = (parsed.values.text ?? parsed.positionals.join(" ")).trim();
     if (!text)
         throw new Error('tts requires text: vidfarm tts "Welcome back to the channel" --style "calm, warm narrator".');
@@ -3118,7 +3148,9 @@ async function runTtsCommand(argv) {
         }
         return;
     }
-    // BACKUP: the platform primitive route (saved provider keys, async job).
+    // BACKUP: the platform primitive route (async job). Defaults to high-quality
+    // ElevenLabs on the platform key, billed to the wallet (use_wallet_credits).
+    // --own-key flips to your own saved ElevenLabs / BYOK provider key instead.
     const ctx = commonContext(parsed.values);
     const payload = { text, output_format: format };
     if (voice)
@@ -3129,6 +3161,11 @@ async function runTtsCommand(argv) {
         payload.provider = parsed.values.provider;
     if (parsed.values.model)
         payload.model = parsed.values.model;
+    if (parsed.values["own-key"])
+        payload.use_wallet_credits = false;
+    if (!ctx.json && !parsed.values["own-key"]) {
+        console.log(`${DIM}Using ElevenLabs on the platform key (wallet-billed). Browse voices: vidfarm voices — then pass --voice <voice_id>. Add --own-key to use your own key.${RESET}`);
+    }
     const tracer = parsed.values.tracer ?? `devcli-tts-${Date.now().toString(36)}`;
     const submit = await apiRequest({ method: "POST", host: ctx.host, path: "/api/v1/primitives/audio/speech", auth: ctx.auth, body: { tracer, payload } });
     assertApiOk(submit, "tts");
@@ -3290,6 +3327,112 @@ function emitSttResult(input) {
         console.log(`${GREEN}Wrote ${dest}${RESET}`);
     }
 }
+// Music generation (ElevenLabs) — cloud-only (no local engine). Defaults to the
+// platform key billed to the wallet; --own-key uses your saved ElevenLabs key.
+async function runMusicCommand(argv) {
+    const parsed = parseArgs({
+        args: argv,
+        allowPositionals: true,
+        options: {
+            ...commonOptions(),
+            prompt: { type: "string" },
+            "length-ms": { type: "string" },
+            length: { type: "string" },
+            model: { type: "string" },
+            out: { type: "string" },
+            "own-key": { type: "boolean", default: false },
+            "no-wait": { type: "boolean", default: false },
+            tracer: { type: "string" }
+        }
+    });
+    const prompt = (parsed.values.prompt ?? parsed.positionals.join(" ")).trim();
+    if (!prompt)
+        throw new Error('music requires a prompt: vidfarm music "upbeat lo-fi hip hop beat with jazzy piano" --length 30');
+    const ctx = commonContext(parsed.values);
+    let musicLengthMs;
+    const lengthMs = parsed.values["length-ms"]?.trim();
+    const lengthSec = parsed.values.length?.trim();
+    if (lengthMs)
+        musicLengthMs = Math.round(Number(lengthMs));
+    else if (lengthSec)
+        musicLengthMs = Math.round(Number(lengthSec) * 1000);
+    const payload = { prompt };
+    if (musicLengthMs && Number.isFinite(musicLengthMs))
+        payload.music_length_ms = musicLengthMs;
+    if (parsed.values.model)
+        payload.model = parsed.values.model;
+    if (parsed.values["own-key"])
+        payload.use_wallet_credits = false;
+    if (!ctx.json && !parsed.values["own-key"]) {
+        console.log(`${DIM}Composing with ElevenLabs on the platform key (wallet-billed). Add --own-key to use your own ElevenLabs key.${RESET}`);
+    }
+    const tracer = parsed.values.tracer ?? `devcli-music-${Date.now().toString(36)}`;
+    const submit = await apiRequest({ method: "POST", host: ctx.host, path: "/api/v1/primitives/music/generate", auth: ctx.auth, body: { tracer, payload } });
+    assertApiOk(submit, "music");
+    const jobId = submit.json?.job_id;
+    if (parsed.values["no-wait"] || !jobId) {
+        if (!ctx.json && jobId)
+            console.log(`${DIM}Queued ${jobId} (tracer ${tracer}). Poll: vidfarm api GET /api/v1/user/me/jobs/${jobId} — or drop --no-wait to auto-poll.${RESET}`);
+        emitResult(submit, ctx.json);
+        return;
+    }
+    if (!ctx.json)
+        console.log(`${DIM}Generating music (${jobId})… polling every 5s.${RESET}`);
+    const job = await pollPrimitiveJob(ctx, jobId);
+    const mediaUrl = resolveJobMediaUrl(job);
+    if (!mediaUrl) {
+        if (ctx.json) {
+            printJson({ ok: false, job_id: jobId, status: String(job?.status ?? ""), job });
+        }
+        else {
+            console.log(`${RED}Music ${String(job?.status ?? "did not finish")} — no audio URL.${RESET}`);
+            printJson(job);
+        }
+        process.exitCode = 1;
+        return;
+    }
+    const outPath = path.resolve(process.cwd(), parsed.values.out ?? `music-${jobId}.mp3`);
+    await downloadUrlToFile(mediaUrl, outPath);
+    if (ctx.json) {
+        printJson({ ok: true, job_id: jobId, tracer, audio_url: mediaUrl, out: outPath });
+    }
+    else {
+        console.log(`${GREEN}Wrote ${outPath}${RESET} ${DIM}(${mediaUrl})${RESET}`);
+        console.log(`${DIM}Place it as its own <audio> layer under narration (~0.1–0.2 volume).${RESET}`);
+    }
+}
+// List ElevenLabs voices for TTS. --own-key lists the voices on your own saved
+// ElevenLabs key; default lists the platform account's voices.
+async function runVoicesCommand(argv) {
+    const parsed = parseArgs({
+        args: argv,
+        allowPositionals: true,
+        options: {
+            ...commonOptions(),
+            "own-key": { type: "boolean", default: false },
+            limit: { type: "string" }
+        }
+    });
+    const ctx = commonContext(parsed.values);
+    const query = parsed.values["own-key"] ? "?use_wallet_credits=false" : "";
+    const res = await apiRequest({ method: "GET", host: ctx.host, path: `/api/v1/primitives/audio/voices${query}`, auth: ctx.auth });
+    assertApiOk(res, "voices");
+    const body = (res.json ?? {});
+    const voices = Array.isArray(body.voices) ? body.voices : [];
+    if (ctx.json) {
+        printJson(body);
+        return;
+    }
+    console.log(`${DIM}${voices.length} ElevenLabs voices (${body.scope ?? "platform"} account). Browse more: ${body.voice_library_url ?? "https://elevenlabs.io/app/voice-library"}${RESET}`);
+    const limit = Number(parsed.values.limit ?? "40") || 40;
+    for (const voice of voices.slice(0, limit)) {
+        const labels = voice.labels && typeof voice.labels === "object" ? Object.values(voice.labels).join(", ") : "";
+        console.log(`${GREEN}${voice.voice_id}${RESET}  ${voice.name}${labels ? ` ${DIM}(${labels})${RESET}` : ""}`);
+    }
+    if (voices.length > limit)
+        console.log(`${DIM}… ${voices.length - limit} more (raise with --limit or use --json).${RESET}`);
+    console.log(`${DIM}Use one: vidfarm tts "Hello" --cloud --voice <voice_id>${RESET}`);
+}
 async function runSttCommand(argv) {
     const parsed = parseArgs({
         args: argv,
@@ -3307,6 +3450,7 @@ async function runSttCommand(argv) {
             "gemini-key": { type: "string" },
             "openai-key": { type: "string" },
             "openrouter-key": { type: "string" },
+            "own-key": { type: "boolean", default: false },
             "no-wait": { type: "boolean", default: false },
             tracer: { type: "string" },
             folder: { type: "string" }
@@ -3405,6 +3549,11 @@ async function runSttCommand(argv) {
         payload.provider = parsed.values.provider;
     if (parsed.values.model)
         payload.model = parsed.values.model;
+    // Cloud STT defaults to ElevenLabs Scribe on the platform key (native
+    // diarization + real word timings), wallet-billed. --own-key uses your own
+    // ElevenLabs / BYOK key instead.
+    if (parsed.values["own-key"])
+        payload.use_wallet_credits = false;
     const tracer = parsed.values.tracer ?? `devcli-stt-${Date.now().toString(36)}`;
     const submit = await apiRequest({ method: "POST", host: ctx.host, path: "/api/v1/primitives/audio/transcribe", auth: ctx.auth, body: { tracer, payload } });
     assertApiOk(submit, "stt");
@@ -3953,7 +4102,8 @@ async function runClipperCommand(argv) {
             out: { type: "string" },
             tracer: { type: "string" },
             folder: { type: "string" },
-            name: { type: "string" }
+            name: { type: "string" },
+            "audio-only": { type: "boolean", default: false }
         }
     });
     const source = parsed.positionals[0];
@@ -3970,6 +4120,10 @@ async function runClipperCommand(argv) {
     if (!wholeVideo && (!hasStart || !hasEnd)) {
         throw new Error("clipper needs BOTH --start and --end for an exact subrange, or NEITHER to import the whole video.");
     }
+    const audioOnly = Boolean(parsed.values["audio-only"]);
+    if (audioOnly && wholeVideo) {
+        throw new Error("--audio-only needs an exact subrange (--start <t> --end <t>). Whole-video import keeps the video track.");
+    }
     const body = {};
     if (parsed.values.tracer)
         body.tracer = String(parsed.values.tracer);
@@ -3977,6 +4131,8 @@ async function runClipperCommand(argv) {
         body.folder_path = String(parsed.values.folder);
     if (parsed.values.name)
         body.name = String(parsed.values.name);
+    if (audioOnly)
+        body.audio_only = true;
     // Resolve the source into the body once: a URL rides as source_url; a local
     // file is staged into the temp store and referenced by temp_file_id.
     if (/^https?:\/\//i.test(source)) {
@@ -4037,7 +4193,8 @@ async function runClipperCommand(argv) {
     }
     const j = res.json;
     const dest = j?.folder_path ? `/raws/${j.folder_path}` : "your raws library";
-    console.log(`${GREEN}Clipped ${(j?.duration_sec ?? (endSec - startSec)).toFixed?.(2) ?? j?.duration_sec}s → ${dest} (clip ${j?.clip_id ?? "?"}).${RESET}`);
+    const kindWord = (j?.media_kind === "audio" || audioOnly) ? "audio" : "clip";
+    console.log(`${GREEN}Clipped ${kindWord} ${(j?.duration_sec ?? (endSec - startSec)).toFixed?.(2) ?? j?.duration_sec}s → ${dest} (clip ${j?.clip_id ?? "?"}).${RESET}`);
     if (j?.view_url)
         console.log(`${DIM}Preview: ${new URL(j.view_url, ctx.host).toString()}${RESET}`);
     console.log(`${DIM}Grab another range from the same source with the same --tracer/--folder.${RESET}`);

package/dist/src/config.js

@@ -32,6 +32,7 @@ const schema = z.object({
     PROVIDER_LEASE_WAIT_TIMEOUT_SECONDS: z.coerce.number().default(5 * 60),
     PROVIDER_LEASE_INLINE_WAIT_SECONDS: z.coerce.number().default(5),
     PROVIDER_LEASE_STEP_WAIT_SECONDS: z.coerce.number().int().min(1).default(60),
+    RENDER_POLL_WAIT_SECONDS: z.coerce.number().int().min(1).default(20),
     PROVIDER_LEASE_MAX_STEP_WAIT_SECONDS: z.coerce.number().int().min(1).default(12 * 60 * 60),
     MAX_ACTIVE_JOBS_PER_CUSTOMER: z.coerce.number().int().min(1).default(30),
     STORAGE_DRIVER: z.enum(["local", "s3"]).default("local"),
@@ -65,6 +66,18 @@ const schema = z.object({
     OPENROUTER_API_KEY: z.string().optional(),
     GEMINI_API_KEY: z.string().optional(),
     PERPLEXITY_API_KEY: z.string().optional(),
+    // Platform ElevenLabs key — the fallback used for music / TTS / STT primitives
+    // when the caller opts into `use_wallet_credits` (the default) or has no usable
+    // BYOK audio key. Usage on this key is billed to the customer's vidfarm wallet.
+    ELEVENLABS_API_KEY: z.string().optional(),
+    // Base provider costs for ElevenLabs primitives billed to the wallet (the
+    // billing lambda applies the standard markup on top). Defaults track published
+    // ElevenLabs list pricing: TTS multilingual v2/v3 $0.10 / 1K chars (flash/turbo
+    // is $0.05), Music $0.15 / minute, Scribe STT $0.22 / hour ≈ $0.003667 / min.
+    // Override per-environment as pricing shifts.
+    ELEVENLABS_MUSIC_USD_PER_MIN: z.coerce.number().min(0).default(0.15),
+    ELEVENLABS_TTS_USD_PER_1K_CHARS: z.coerce.number().min(0).default(0.10),
+    ELEVENLABS_STT_USD_PER_MIN: z.coerce.number().min(0).default(0.003667),
     GHOSTCUT_KEY: z.string().optional(),
     GHOSTCUT_SECRET: z.string().optional(),
     GHOSTCUT_USD_PER_30S: z.coerce.number().min(0).default(0.10),

package/dist/src/devcli/clips.js

@@ -44,6 +44,7 @@ export const CLIPS_HELP = `vidfarm raws — build & search a local raws library
     --yes                          Skip the >$1 confirmation prompt
     --frames <n>                   Keyframes per scene for tagging (1-3, default 2)
     --no-audio                     Skip per-scene audio (Gemini only; no transcripts; cheaper)
+    --audio-only                   Save each mined clip as an audio-only .m4a (no video); waveform thumb
     --concurrency <n>              Parallel scenes (default 3; agent default 2)
     --threshold <0..1>             Scene-cut sensitivity (default 0.3; lower = more cuts)
     --min-scene <sec>              Merge scenes shorter than this (default 0.6)
@@ -133,6 +134,7 @@ async function runScan(argv) {
             "allow-text": { type: "boolean" },
             "max-clips": { type: "string" },
             "no-refine": { type: "boolean" },
+            "audio-only": { type: "boolean" },
             cloud: { type: "boolean" },
             url: { type: "string" },
             tracer: { type: "string" },
@@ -197,7 +199,8 @@ async function runScan(argv) {
             aspect,
             cropFocus,
             avoidText,
-            maxClips
+            maxClips,
+            audioOnly: Boolean(values["audio-only"])
         });
     }
     const videoArg = positionals[0];
@@ -336,6 +339,7 @@ async function runScan(argv) {
         guidancePrompt: guidance,
         refineSegmentation: !values["no-refine"],
         reencodeClips: true,
+        audioOnly: Boolean(values["audio-only"]),
         crop: aspect && aspect !== "original" ? { aspect, focus: cropFocus } : undefined
     };
     console.log(`[raws] scanning ${scenes.length} scenes (${provider}/${activeClient.tagModelId}, ${concurrency}x) …`);
@@ -466,7 +470,8 @@ async function runScanCloud(input) {
                 // Send explicitly (incl. false) so --allow-text can override the
                 // server-side avoid-text default.
                 avoid_text: input.avoidText,
-                ...(input.maxClips ? { max_clips: input.maxClips } : {})
+                ...(input.maxClips ? { max_clips: input.maxClips } : {}),
+                ...(input.audioOnly ? { audio_only: true } : {})
             }
         })
     });

package/dist/src/devcli/composition-edit.js

@@ -316,9 +316,12 @@ function resolveCaptionLook(opts) {
         color: opts.color ?? preset?.color ?? "#ffffff",
         background: opts.background ?? preset?.background ?? "#000000",
         backgroundStyle: (opts.backgroundStyle ?? preset?.textBackgroundStyle ?? "plain"),
-        fontFamily: opts.fontFamily ?? "Montserrat",
+        // A 0 (or empty) font size/family renders the caption invisibly — the shared
+        // action/flag schema lets callers pass font_size:0 or font_family:"", so treat
+        // only a positive size / non-empty family as an intentional override.
+        fontFamily: opts.fontFamily?.trim() ? opts.fontFamily.trim() : "Montserrat",
         fontWeight: opts.fontWeight ?? preset?.fontWeight ?? 800,
-        fontSize: opts.fontSize ?? 38,
+        fontSize: typeof opts.fontSize === "number" && opts.fontSize > 0 ? opts.fontSize : 38,
         presetId: preset?.id ?? animation
     };
 }

package/dist/src/domain.js

@@ -1,2 +1,5 @@
+// Providers that count as a qualified AI key for text/image/video generation
+// (everything except the audio-only elevenlabs key).
+export const QUALIFIED_AI_PROVIDER_TYPES = ["openai", "gemini", "openrouter", "perplexity"];
 export const CUSTOMER_PLAN_TIERS = ["client", "standalone", "agency"];
 //# sourceMappingURL=domain.js.map

package/dist/src/editor-chat.js

@@ -21,6 +21,10 @@ export function defaultEditorChatModel(provider) {
             return "qwen/qwen3.6-plus";
         case "perplexity":
             return "sonar";
+        default:
+            // Non-text providers (e.g. audio-only elevenlabs) never reach editor chat;
+            // return a safe text default rather than undefined.
+            return "gpt-5.4-mini";
     }
 }
 export function buildTemplateEditorChatSystemPrompt(input) {
@@ -74,6 +78,9 @@ export function buildTemplateEditorChatSystemPrompt(input) {
         "If the user asks to add, remove, retime, reposition, resize, restyle, swap media, tag, note, group, ungroup, duplicate, split, animate, keyframe, nudge, ripple, trim, or restack layers on the composition timeline, call the editor_action tool. Supported action_type values are add_layer, remove_layer, set_layer_timing, set_layer_visual, set_layer_style, set_layer_media, set_layer_text, set_layer_identity, duplicate_layer, split_layer, group_layers, ungroup_layers, generate_layer, replace_composition_html, export_composition, set_captions, set_transitions, set_layer_keyframes, nudge_layers, ripple_edit, trim_layer, set_layer_zindex, set_composition, and fork_composition.",
         "FINE TIMELINE CONTROL — you have trackpad-level verbs; use them instead of rewriting the whole document for small changes: (1) set_layer_keyframes authors a custom, script-free CSS @keyframes animation on ONE layer that previews AND renders — pass layer_key + keyframes:[{offset(0..1), opacity?, translate_x?, translate_y?, scale?, rotate?}, …] (>=2 stops), optional keyframe_easing (linear/ease/ease-in/ease-out/ease-in-out/cubic-bezier(...)) and keyframe_duration (seconds, default = clip duration). translate_x/translate_y are percentages of the layer's OWN box. Example fly-up-and-fade-in: keyframes=[{offset:0,opacity:0,translate_y:40},{offset:1,opacity:1,translate_y:0}]. This is the durable way to hand-author motion beyond the Ken Burns / transition / caption presets — the JS runtime adapters (anime.js/GSAP/Lottie) are devcli-only. (2) nudge_layers shifts one or more layers by a RELATIVE delta_start (seconds) and/or delta_track (lanes) — pass layer_key or layer_keys; grouped clips move together. (3) ripple_edit inserts (delta_start>0) or closes (delta_start<0) time at at_time and shifts every downstream clip so the rest of the timeline stays in sync — use it to make room before an insert or to close a gap you can see in timeline_gaps. (4) trim_layer moves ONE edge to a time: edge='start' (left; advances the in-point, and for video/audio pushes the media start so the visible frame is unchanged) or edge='end' (right; changes duration), with to_time in composition seconds. (5) set_layer_zindex restacks: z_order='front'|'back'|'forward'|'backward' (stacking == track index; higher draws on top) or an explicit track. All of these auto-resolve track collisions and note it in the summary; read the NEXT editor_context to confirm the new start/duration/track/animation landed.",
         "If the user asks to export, render, publish, or produce the final MP4 for this composition (phrases like 'export it', 'render this', 'kick off the export', 'make the mp4'), call editor_action with action_type=export_composition and a brief explanation. This is the same action as the editor's Export button — it queues the composition on production AWS Lambda. Do NOT try to hit any /api/v1/compositions/:id/export route via http_request for this; use the editor_action tool. After calling export_composition, tell the user the export has started and that the finished MP4 URL will appear once the render succeeds; do not fabricate a URL or claim success until a later turn shows last_export_url populated in editor_context.",
+        "CONFIRM BEFORE RENDERING — DO NOT auto-render. Rendering the final MP4 is a slow, costly, screen-taking action, so by DEFAULT you must NOT call export_composition on your own initiative. After you finish an edit (a swap, a re-theme, a scene rebuild), STOP and let the user review the live preview, then ASK a short question like 'Happy with the preview? Want me to render the final MP4?' and wait for a yes. Only fire export_composition when EITHER (a) the user explicitly asks to render/export/'make the mp4' in that turn, or (b) the user has told you up front to just render without asking (e.g. 'edit and render it', 'no need to check, just export'). If in doubt, ask — never surprise the user with a render. Never render merely because you judged the edit 'done'.",
+        "MEDIA SWAP — TARGET A REAL LAYER KEY, NOT A SCENE NAME. To swap a clip's media with set_layer_media, the layer_key MUST be an EXACT key (or its slug) from editor_context.layers — that array lists every targetable layer with its key, slug, kind (video/image/audio), and current src. Read it and copy the real key of the video/image layer you mean; do NOT invent a semantic name (like 'growth_examples' or 'mistakes_reflection') unless that exact string appears as a layer key/slug in editor_context, and never target a scene label/group when you mean the video inside it. If set_layer_media returns 'No change applied' or 'Layer not found', the error now lists the actual media layers — re-read it and retry with one of those exact keys. NEVER report a swap as done until the NEXT editor_context shows the layer's src changed.",
+        "GETTING THE MEDIA URL IS EASY — USE browse_files. When the user says 'use my raws' / 'it's in my file directory' / 'the fishing clips', you do NOT need them to paste a URL. Call browse_files action=search (or list path='/raws') to find the clip, then action=read with its file_id — the read result's view_url IS the public, ready-to-use media URL. Drop that view_url straight into set_layer_media src (or add_layer src). Do not stall asking the user for a URL you can look up yourself, and never pass a placeholder like 'please-ignore' as src.",
         "The editor_context block includes last_export_url, last_export_title, last_export_status, and last_export_render_id when a render has succeeded in this session. Treat last_export_url as the current 'finished Export MP4' for this composition. If the user asks to approve, package, share, or schedule the exported video without providing an explicit URL, use last_export_url as the primary MP4 media (kind=video, role=primary) for POST /api/v1/approved/posts. If last_export_url is null, tell the user to Export first (or offer to call editor_action with action_type=export_composition on their behalf) instead of guessing a URL.",
         "Each layer in editor_context includes element_id (data-hf-id), optional slug (data-hf-slug), and optional note (data-hf-note). layer_key on any editor_action may be EITHER the element_id or the slug — prefer the slug when the user (or a viral DNA blurb) refers to a layer by its human name like 'the hero_image'. Use set_layer_identity to add/change a layer's slug or note. Slugs are the stable AI-friendly handle: when planning viral DNA notes, reference the element by its slug (e.g., 'raise the {{hero_image}} to full canvas at 4s') so future turns can resolve it deterministically.",
         "Treat the most recent <editor_context> block in the user message as the source of truth for current layer_keys, layer indices (called track in HTML: track=layer index, higher = drawn on top), durations, and composition_duration_seconds. Never invent layer_keys for remove/set/duplicate/split actions; only reference keys that appear there. Each layer also reports its current declarative MOTION so you can read the timeline's animation state instead of guessing: transition / transition_out (scene entrance/exit presets), transition_duration, ken_burns (still-image pan/zoom preset), and animation (the name of a custom CSS keyframe animation authored via set_layer_keyframes). recent_action_results reflects the REAL outcome of your previous turn's editor_action calls — each entry has ok:true with a summary (the edit landed) or ok:false with an error (it did not); trust it over the tool's echoed args, and if an edit failed, read the error and retry or explain rather than repeating a false success.",
@@ -98,7 +105,7 @@ export function buildTemplateEditorChatSystemPrompt(input) {
         "FITTING IMPERFECT-DIMENSION MEDIA (aspect mismatch — do this intelligently, per clip). A video or image whose NATIVE aspect ratio differs from the canvas — the common case is a 16:9 landscape source dropped onto a 9:16 vertical frame, but also a tall screenshot on a wide frame, a square logo, etc. — does NOT automatically look good. Every media layer defaults to object-fit:cover, which fills the frame and SILENTLY CENTER-CROPS the overflow: a landscape clip on a vertical frame loses its left and right edges (often cutting the subject in half); a portrait clip on a wide frame loses its top and bottom. Your job is to choose the fit so the important part of the frame survives, using set_layer_media (object_fit + object_position) and, when needed, set_layer_visual (geometry). The levers: (1) object_fit='cover' (default) fills the canvas and crops the excess — the right choice for most social footage, ESPECIALLY when you also steer the crop with object_position. (2) object_position aims WHERE the cover-crop lands so the subject stays in view — pass a focal point as keywords (center, left, right, top, bottom, 'top left', 'bottom right', ...) OR precise percentages ('30% 50%' holds the point 30% from the left and 50% down; '50% 20%' keeps the upper-middle in frame). Example: a landscape interview clip where the speaker sits on the LEFT third → object_fit:'cover' + object_position:'left' (or '25% 50%') keeps them framed instead of center-cropping them out; a tall screenshot whose key text is at the TOP → object_position:'top'. (3) object_fit='contain' shows the ENTIRE media with NO cropping but adds black letterbox/pillarbox bars to pad the leftover frame — use it ONLY when nothing may be cropped (a full infographic, a whole screenshot, a chart, a logo) and the bars are acceptable; note a 16:9 source on a full-canvas 9:16 frame in 'contain' leaves large black bands top and bottom that usually read as unfinished. (4) To show a whole landscape clip WITHOUT ugly bars, place it as a centered BAND rather than full-canvas: set_layer_visual to size it to the frame width at its natural height (e.g. a 16:9 clip on a 1080×1920 frame → width 100, height ~34, y ~33) with object_fit:'contain'|'cover', and optionally add a DUPLICATE full-canvas copy of the same clip on a LOWER track behind it at object_fit:'cover' with a heavy blur as a filled backdrop (the classic blurred-letterbox look). (5) Never use object_fit:'fill' unless you deliberately want to stretch/distort. Decide from what you know: you usually already know a clip's aspect from how you sourced it (a hunted raw's aspect param, a generated clip's requested aspect_ratio, the user's own description); if you genuinely need exact dimensions, GET /api/v1/primitives/videos/probe (video) or extract a frame. When you REPLACE a full-canvas scene (is_full_canvas / is_timeline_proxy), keep it full canvas (x=0,y=0,width=100,height=100) and pick cover + a subject-aware object_position rather than shrinking it — unless the whole frame must be visible. And when you GENERATE new media for the timeline, still request the canvas aspect_ratio so it needs no crop at all — this fit-tuning is for existing/mismatched footage, not for media you generate to spec.",
         "KEN BURNS / ANIMATE STILL IMAGES: every still-image layer supports a built-in Ken Burns effect — a slow pan or zoom that spans the clip's full duration in both the preview and the final render. Apply it with editor_action set_layer_media and the ken_burns field (presets: zoom-in, zoom-out, pan-left, pan-right, pan-up, pan-down, zoom-in-left, zoom-in-right; 'none' removes it), optionally ken_burns_intensity (0.04-0.5, default 0.18; ~0.1 subtle, ~0.3 dramatic). When the user says 'animate the images', 'make the photos move', 'ken burns', or similar, apply a preset to EVERY still-image layer in one pass (one set_layer_media call per layer), varying presets across adjacent clips — e.g. zoom-in, then pan-left, then zoom-out — so consecutive stills don't repeat the same motion. Zoom presets suit subjects centered in frame (products, faces); pan presets suit wide scenery or tall screenshots. You can also seed ken_burns directly on add_layer (kind=image) or generate_layer (media_type=image) so freshly placed stills arrive already animated. It only applies to image layers — never set it on video, text, or audio.",
         "SCENE TRANSITIONS: every visual clip supports first-class transitions — an ENTRANCE at its start (transition: the clip animates IN over the previous clip on its track, which is automatically held on screen beneath it for the transition window) and an EXIT at its end (transition_out: the clip animates AWAY over its last transition_out_duration seconds), in both the preview and the final render. Entrance presets: crossfade, fade-black, fade-white, flash, smoke, blur, slide-left/right/up/down, whip-left/right, wipe-left/right/up/down, zoom-in, zoom-out, circle-open. Exit presets: fade, fade-black, fade-white, flash, smoke, blur, slide-left/right/up/down, wipe-left/right/up/down, zoom-in, zoom-out, circle-close. 'none' removes either. PREFER the bulk verb: when the user says 'add transitions', 'smooth out the cuts', 'crossfade between scenes', or similar, ONE editor_action action_type=set_transitions call does the whole timeline — transition = the junction preset applied at every cut (every scene clip except each track's first), optional transition_duration, optional transition_intro (first clip's entrance, e.g. fade-black to open from black), optional transition_outro (last clip's exit, e.g. fade-black to end on black) with transition_out_duration. For a SINGLE cut, set transition with set_layer_media ON THE INCOMING CLIP (the clip AFTER the cut, never the one before it); for a single clip's exit (before a gap, or a deliberate dip-to-black) set transition_out on the OUTGOING clip. Match the preset to the template's energy: crossfade/fade-black/fade-white/blur read calm and cinematic, smoke reads dreamy, slide/wipe read energetic (vary directions across cuts), whip/flash read fast-paced social, zoom/circle read punchy and meme-y; keep ONE family per video unless asked otherwise. You can also seed transition/transition_out directly on add_layer or generate_layer so a newly placed scene arrives with its motion. Transitions belong on video/image scene clips — never on audio; on text overlays prefer them only when the user asks. Timing is handled for you — never move clip starts or durations to 'make room' for a transition. Transitions also appear as clickable chips at every cut on the editor timeline, so tell users they can fine-tune from there too.",
-        "ANIMATED CAPTIONS (word-by-word, TikTok/CapCut style): the composition supports first-class animated captions — caption layers whose words animate one at a time in both the preview and the final render. Available preset looks (caption_style): spotlight (active word gets a rounded highlight pill on bold outlined text — the classic Hormozi/CapCut look), karaoke (words fill with a color as they are spoken and stay lit), word-pop (one word at a time, punchy scale-in), stack-up (words fade/rise in and accumulate), neon (active word pulses with a glow), bounce (active word bounces). When the user asks to 'add captions', 'add animated captions', 'add subtitles', or similar, pick the cue source by where the speech lives: (a) narration that needs TRANSCRIBING — a TTS voiceover layer, replaced audio, or when word-accurate karaoke timing matters — call the captions primitive: POST /api/v1/primitives/audio/captions with body { tracer, payload: { source_url: <the narration audio/video URL from editor_context>, style } }; the finished job's result carries captions (the cue array) and set_captions_action (fully-formed editor_action arguments) — apply them verbatim with editor_action action_type=set_captions. Real word timestamps need an OpenAI key (tried first; gemini/openrouter degrade to estimated word windows). (b) speech that is the SOURCE VIDEO's own audio on an already-decomposed fork — video_context already has the transcript's timestamped segments, so skip the job and call editor_action action_type=set_captions directly with captions=[{text, start, duration, words?}] cues derived from those segments — split segment text into pages of 3-5 words, keep each cue inside its segment's time window, and pass word timings when the transcript provides them (otherwise omit words and the editor estimates). Pick caption_style to match the template's voice (composition_context), or spotlight by default; override colors with caption_active_color / caption_highlight_color / color / background / background_style, and caption_uppercase for shouty formats. set_captions REPLACES all existing animated caption layers in one call — use it for 'restyle all the captions' too (same cues, new style) when cue text/timing is already in editor_context (each caption layer's text and caption_animation are listed there). For a single cue, set_layer_style with caption_* fields restyles just that layer, set_layer_text rewrites its words (timings re-estimate), and caption_animation='none' flattens it back to static text. Never hand-build word-by-word captions out of many add_layer text layers — always use set_captions. There is also a ONE-STEP server route, POST /api/v1/compositions/:forkId/captions { audio_url?|text?, style?, ... }, which transcribes the fork's own narration and writes the caption layers into the working composition server-side — use it ONLY for headless/automation flows, never while this editor session is open (the editor's next auto-save would overwrite the server-side change; in the editor always mutate through editor_action set_captions).",
+        "ANIMATED CAPTIONS (word-by-word, TikTok/CapCut style): the composition supports first-class animated captions — caption layers whose words animate one at a time in both the preview and the final render. Available preset looks (caption_style): spotlight (active word gets a rounded highlight pill on bold outlined text — the classic Hormozi/CapCut look), karaoke (words fill with a color as they are spoken and stay lit), word-pop (one word at a time, punchy scale-in), stack-up (words fade/rise in and accumulate), neon (active word pulses with a glow), bounce (active word bounces). When the user asks to 'add captions', 'add animated captions', 'add subtitles', or similar, pick the cue source by where the speech lives: (a) narration that needs TRANSCRIBING — a TTS voiceover layer, replaced audio, or when word-accurate karaoke timing matters — call the captions primitive: POST /api/v1/primitives/audio/captions with body { tracer, payload: { source_url: <the narration audio/video URL from editor_context>, style } }; the finished job's result carries captions (the cue array) and set_captions_action (fully-formed editor_action arguments) — apply them verbatim with editor_action action_type=set_captions. Real word timestamps need an OpenAI key (tried first; gemini/openrouter degrade to estimated word windows). (b) speech that is the SOURCE VIDEO's own audio on an already-decomposed fork — video_context already has the transcript's timestamped segments, so skip the job and call editor_action action_type=set_captions directly with captions=[{text, start, duration, words?}] cues derived from those segments — split segment text into pages of 3-5 words, keep each cue inside its segment's time window, and pass word timings when the transcript provides them (otherwise omit words and the editor estimates). Pick caption_style to match the template's voice (composition_context), or spotlight by default; override colors with caption_active_color / caption_highlight_color / color / background / background_style, and caption_uppercase for shouty formats. set_captions ALSO accepts the full TYPOGRAPHY + PLACEMENT of the caption run, so set them intentionally instead of leaving the model defaults: font_family (a CSS family the composition already uses, e.g. Montserrat / Poppins / 'TikTok Sans' — match the template's caption font from editor_harness.typography or composition_context), font_weight (700-900 for the bold CapCut look), font_size in PIXELS relative to the render canvas (the frame is usually 1080-wide vertical, so ~36-64px reads well — never 0, which renders the text invisibly), and x / y / width / height as percentages of the canvas for where the caption box sits (default is a lower-third band at x:10 y:70 width:80 height:14; pass y:8 for a top strip, or center it, per the template's placement). Only send a font_size / width / height you actually want — a 0 falls back to the sane default rather than an invisible cue. set_captions REPLACES all existing animated caption layers in one call — use it for 'restyle all the captions' too (same cues, new style) when cue text/timing is already in editor_context (each caption layer's text and caption_animation are listed there). For a single cue, set_layer_style with caption_* fields restyles just that layer, set_layer_text rewrites its words (timings re-estimate), and caption_animation='none' flattens it back to static text. Never hand-build word-by-word captions out of many add_layer text layers — always use set_captions. There is also a ONE-STEP server route, POST /api/v1/compositions/:forkId/captions { audio_url?|text?, style?, ... }, which transcribes the fork's own narration and writes the caption layers into the working composition server-side — use it ONLY for headless/automation flows, never while this editor session is open (the editor's next auto-save would overwrite the server-side change; in the editor always mutate through editor_action set_captions).",
         "Use duplicate_layer to clone an existing layer; supply layer_key for the source, and optionally start/duration/track/label on the duplicate. Use split_layer with layer_key and split_time to cut at a moment in the timeline. Use group_layers with layer_keys (>=2) and optional group_label; ungroup_layers with layer_keys of any grouped members.",
         "Prefer one editor_action call per mutation. For a multi-layer composition, sequence calls: generate or fetch each asset, then add or edit each layer with its own editor_action call. Chain edits by reusing the layer_key you assigned during add_layer.",
         "Layer/track ordering is the ONLY thing that controls visual stacking. `track` is both the timeline layer index AND the CSS z-index — the editor forces `z-index = track` on every layer at publish time. Higher track draws visually on top; lower track draws underneath. There is no separate z-index override — if the AI wants a layer above another, give it a higher track. If html/text overlays should sit ABOVE a video/image, their track must be a larger integer than the visual media below them.",

package/dist/src/primitive-context.js

@@ -4,6 +4,7 @@ import { config } from "./config.js";
 import { devErrorFields, devLog } from "./lib/dev-log.js";
 import { createId } from "./lib/ids.js";
 import { jobLogStore } from "./services/job-logs.js";
+import { RenderInProgressError } from "./services/hyperframes.js";
 import { estimateNormalizationCostUsd, normalizeVideoAsset } from "./services/video-normalization.js";
 export function createPrimitiveJobContext(input) {
     const prefix = input.storage.primitiveJobPrefix(input.primitive.id, input.customer.id, input.job.id);
@@ -197,16 +198,49 @@ export function createPrimitiveJobContext(input) {
                     workerId: input.workerId,
                     ...request
                 });
+            },
+            async generateMusic(request) {
+                return input.providers.generateMusic({
+                    customerId: input.customer.id,
+                    jobId: input.job.id,
+                    workerId: input.workerId,
+                    ...request
+                });
+            },
+            async listElevenLabsVoices(request) {
+                return input.providers.listElevenLabsVoices({
+                    customerId: input.customer.id,
+                    ...request
+                });
             }
         },
         hyperframes: {
             async render(request) {
                 const hyperframesOutputKey = `renders/vidfarm/primitives/${input.primitive.id}/${input.customer.id}/${input.job.id}/output.mp4`;
-                const render = await input.hyperframes.render({
+                // Re-entrant, non-blocking render: the first invocation dispatches the
+                // render to its own Step Functions state machine and throws
+                // RenderInProgressError so the job runner parks as `waiting_for_render`;
+                // Step Functions waits + re-invokes, and a later invocation resumes the
+                // SAME render (keyed by the deterministic execution name) and finalizes
+                // once it terminates. No single Lambda holds the render open for its
+                // 15-minute lifetime.
+                const step = await input.hyperframes.renderStep({
                     ...request,
                     outputKey: hyperframesOutputKey,
-                    wait: true
+                    executionName: renderExecutionName(input.job.id)
                 });
+                if (step.state === "running") {
+                    throw new RenderInProgressError({
+                        executionArn: step.executionArn,
+                        renderId: step.renderId,
+                        waitSeconds: config.RENDER_POLL_WAIT_SECONDS,
+                        progressFraction: step.progressFraction
+                    });
+                }
+                if (step.state === "failed") {
+                    throw new Error(step.message);
+                }
+                const render = step;
                 let outputUrl = render.outputUrl;
                 let platformOutputKey = null;
                 const localOutputLocation = typeof render.metadata.outputLocation === "string"
@@ -370,4 +404,13 @@ export function createPrimitiveJobContext(input) {
 function buildPlatformMediaUrl(storageKey) {
     return `${config.PUBLIC_BASE_URL.replace(/\/$/, "")}/template-media?key=${encodeURIComponent(storageKey)}`;
 }
+/**
+ * Deterministic Step Functions execution name for a job's render. Stable across
+ * job-runner re-invocations so each poll resumes the same render execution
+ * rather than starting a new one. Step Functions execution names allow
+ * [A-Za-z0-9-_] and cap at 80 chars.
+ */
+function renderExecutionName(jobId) {
+    return `vfr-${jobId.replace(/[^A-Za-z0-9_-]/g, "-")}`.slice(0, 80);
+}
 //# sourceMappingURL=primitive-context.js.map