@mevdragon/vidfarm-devcli 0.19.1 → 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

@@ -66,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/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) {

package/dist/src/primitive-context.js

@@ -198,6 +198,20 @@ 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: {

package/dist/src/primitive-registry.js

@@ -429,7 +429,11 @@ const ttsPayloadSchema = z.preprocess((raw) => {
     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")
+    output_format: z.enum(["mp3", "wav"]).default("mp3"),
+    // Default TRUE: great ElevenLabs narration out of the box on the platform key,
+    // billed to the wallet. Set false to use your own ElevenLabs key or a BYOK
+    // openai/gemini/openrouter key instead. See voice options via /audio/voices.
+    use_wallet_credits: z.boolean().default(true)
 }).superRefine((value, ctx) => {
     // Reject an explicit provider/voice contradiction at enqueue (400) instead
     // of queueing a job that can only fail at the provider.
@@ -465,7 +469,36 @@ const sttPayloadSchema = z.preprocess((raw) => {
     // output and downstream callers estimate word windows.
     word_timestamps: z.boolean().default(false),
     language: z.string().min(2).max(16).optional(),
-    prompt: z.string().min(1).max(2000).optional()
+    prompt: z.string().min(1).max(2000).optional(),
+    // Default TRUE: platform ElevenLabs Scribe (native diarization + real word
+    // timestamps), billed to the wallet. Set false to use your own ElevenLabs
+    // key or a BYOK gemini/openai/openrouter key.
+    use_wallet_credits: z.boolean().default(true)
+}));
+// Music generation (ElevenLabs). Prompt-based, or a hand-built composition plan.
+const musicPayloadSchema = z.preprocess((raw) => {
+    if (!raw || typeof raw !== "object" || Array.isArray(raw))
+        return raw;
+    const payload = raw;
+    return {
+        ...payload,
+        prompt: payload.prompt ?? payload.text ?? payload.description,
+        music_length_ms: payload.music_length_ms ?? payload.length_ms ?? payload.duration_ms
+    };
+}, z.object({
+    prompt: z.string().min(1).max(2000).optional(),
+    // ElevenLabs music caps at 5 minutes per generation.
+    music_length_ms: z.number().int().min(3000).max(300000).default(30000),
+    // Optional ElevenLabs composition plan for granular section-by-section control.
+    composition_plan: z.record(z.string(), z.any()).optional(),
+    model: z.string().min(1).optional(),
+    output_format: z.string().min(1).optional(),
+    // Default TRUE: platform ElevenLabs key, billed to the wallet. Set false to
+    // use your own saved ElevenLabs key (no wallet charge).
+    use_wallet_credits: z.boolean().default(true)
+}).refine((value) => Boolean(value.prompt) || Boolean(value.composition_plan), {
+    message: "Provide either a prompt or a composition_plan.",
+    path: ["prompt"]
 }));
 // Animated captions from speech: STT with word-level timings, paged into
 // ready-to-apply cue layers. Either transcribe a source_url or page plain text.
@@ -714,6 +747,7 @@ const PRIMITIVE_BRAINSTORM_PRODUCT_PLACEMENT_ID = "primitive:brainstorm_product_
 const PRIMITIVE_MEDIA_DEDUPE_ID = "primitive:media_dedupe";
 const PRIMITIVE_TTS_ID = "primitive:tts";
 const PRIMITIVE_STT_ID = "primitive:stt";
+const PRIMITIVE_MUSIC_ID = "primitive:music";
 const PRIMITIVE_CAPTIONS_ID = "primitive:captions";
 const PRIMITIVE_SPEECH_REGENERATE_ID = "primitive:speech_regenerate";
 // Gemini inline audio caps out around 20MB; at the 64kbps mono mp3 we extract,
@@ -2018,20 +2052,34 @@ const ttsPrimitive = definePrimitive({
                 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.
+                responseFormat: payload.output_format,
+                useWalletCredits: payload.use_wallet_credits
+            });
+            // Route may have resolved to a different provider (e.g. platform ElevenLabs
+            // when use_wallet_credits is on); report what actually ran.
+            const effectiveProvider = generated.effectiveProvider;
+            const effectiveModel = generated.effectiveModel;
+            if (generated.billing) {
+                await ctx.billing.record({
+                    type: "ai_generation",
+                    costUsd: generated.billing.costUsd,
+                    costCenterSlug: generated.billing.costCenterSlug,
+                    metadata: { ...generated.billing.metadata, primitive: "tts", voice: payload.voice ?? null }
+                });
+            }
+            // Gemini/ElevenLabs TTS may answer 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,
+                    provider: effectiveProvider,
+                    model: effectiveModel,
                     voice: payload.voice ?? null,
-                    styleInstructions: payload.instructions ?? null
+                    styleInstructions: payload.instructions ?? null,
+                    wallet_billed: Boolean(generated.billing)
                 }
             });
             ctx.logger.progress(1, "Speech generation complete");
@@ -2044,11 +2092,72 @@ const ttsPrimitive = definePrimitive({
                     audio: {
                         file_url: stored.url,
                         content_type: generated.contentType,
-                        provider,
-                        model,
+                        provider: effectiveProvider,
+                        model: effectiveModel,
                         voice: payload.voice ?? null,
                         style_instructions: payload.instructions ?? null,
-                        text_length: payload.text.length
+                        text_length: payload.text.length,
+                        wallet_billed: Boolean(generated.billing)
+                    }
+                }
+            };
+        }
+    }
+});
+const musicPrimitive = definePrimitive({
+    id: PRIMITIVE_MUSIC_ID,
+    kind: "music",
+    operations: {
+        run: {
+            description: "Generate music (instrumental or with lyrics) from a prompt or a composition plan via ElevenLabs, persisted as a reusable platform audio URL.",
+            inputSchema: musicPayloadSchema,
+            workflow: "run"
+        }
+    },
+    jobs: {
+        async run(ctx, input) {
+            const payload = musicPayloadSchema.parse(input);
+            ctx.logger.progress(0.12, "Composing music");
+            const generated = await ctx.providers.generateMusic({
+                prompt: payload.prompt,
+                musicLengthMs: payload.music_length_ms,
+                compositionPlan: payload.composition_plan,
+                model: payload.model,
+                outputFormat: payload.output_format,
+                useWalletCredits: payload.use_wallet_credits
+            });
+            if (generated.billing) {
+                await ctx.billing.record({
+                    type: "ai_generation",
+                    costUsd: generated.billing.costUsd,
+                    costCenterSlug: generated.billing.costCenterSlug,
+                    metadata: { ...generated.billing.metadata, primitive: "music", prompt: payload.prompt ?? null }
+                });
+            }
+            const stored = await ctx.storage.putBuffer("music.mp3", generated.bytes, {
+                contentType: generated.contentType,
+                kind: "audio",
+                metadata: {
+                    primitive: "music",
+                    provider: "elevenlabs",
+                    music_length_ms: generated.musicLengthMs,
+                    wallet_billed: Boolean(generated.billing)
+                }
+            });
+            ctx.logger.progress(1, "Music 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: "elevenlabs",
+                        music_length_ms: generated.musicLengthMs,
+                        prompt: payload.prompt ?? null,
+                        wallet_billed: Boolean(generated.billing)
                     }
                 }
             };
@@ -2122,18 +2231,29 @@ const sttPrimitive = definePrimitive({
             const payload = sttPayloadSchema.parse(input);
             const { audioBytes, audioContentType, extractionMetadata } = await loadSpeechAudioForPrimitive(ctx, payload);
             ctx.logger.progress(0.45, "Transcribing speech");
-            const provider = payload.provider ?? (payload.word_timestamps ? "openai" : "gemini");
-            const model = payload.model ?? defaultSpeechModelFor("stt", provider) ?? "";
+            const requestedProvider = payload.provider ?? (payload.word_timestamps ? "openai" : "gemini");
+            const requestedModel = payload.model ?? defaultSpeechModelFor("stt", requestedProvider) ?? "";
             const transcription = await ctx.providers.transcribeSpeech({
-                provider,
-                model,
+                provider: requestedProvider,
+                model: requestedModel,
                 audio: audioBytes,
                 contentType: audioContentType,
                 prompt: payload.prompt,
                 language: payload.language,
                 diarize: payload.diarize,
-                wordTimestamps: payload.word_timestamps
-            });
+                wordTimestamps: payload.word_timestamps,
+                useWalletCredits: payload.use_wallet_credits
+            });
+            const provider = transcription.effectiveProvider;
+            const model = transcription.effectiveModel;
+            if (transcription.billing) {
+                await ctx.billing.record({
+                    type: "ai_generation",
+                    costUsd: transcription.billing.costUsd,
+                    costCenterSlug: transcription.billing.costCenterSlug,
+                    metadata: { ...transcription.billing.metadata, primitive: "stt", source_url: payload.source_url }
+                });
+            }
             ctx.logger.progress(0.85, "Storing transcript artifacts");
             const speakers = [...new Set(transcription.segments.map((segment) => segment.speaker))];
             const srt = buildSrtFromSegments(transcription.segments);
@@ -3114,6 +3234,7 @@ class PrimitiveRegistry {
         [audioNormalizePrimitive.id, audioNormalizePrimitive],
         [ttsPrimitive.id, ttsPrimitive],
         [sttPrimitive.id, sttPrimitive],
+        [musicPrimitive.id, musicPrimitive],
         [captionsPrimitive.id, captionsPrimitive],
         [speechRegeneratePrimitive.id, speechRegeneratePrimitive],
         [hyperframesRenderPrimitive.id, hyperframesRenderPrimitive],
@@ -3521,6 +3642,7 @@ function normalizeProductPlacementPayload(raw) {
     };
 }
 function preferredTextProvider(availableProviders) {
+    // Text-only priority — the audio-only elevenlabs provider is never a candidate.
     const priority = ["openai", "gemini", "openrouter", "perplexity"];
     return priority.find((provider) => availableProviders.includes(provider)) ?? "openai";
 }

package/dist/src/reskin/chat-page.js

@@ -59,8 +59,8 @@ export function renderReskinChat(input = DEFAULT_INPUT, opts = {}) {
             <select class="rk-chat-mode-select" id="rk-chat-mode">
               <option value="/chat" selected>Chat</option>
               <option value="/tools/image">Create Image</option>
-              <option value="/tools/clipper">Clip a Video</option>
               <option value="/editor/original/fork/new">Create Video</option>
+              <option value="/tools/clipper">Clip Media</option>
             </select>
             <span class="rk-chat-mode-chev" aria-hidden="true">&#9662;</span>
           </label>