@pixeldojo/mcp 0.14.0 → 0.15.1

package/dist/cli.cjs

@@ -142,12 +142,13 @@ async function uploadLocalFile(path$1, ctx) {
     );
   }
   const isImage = mime.startsWith("image/");
-  const limit = isImage ? MAX_IMAGE_BYTES : MAX_VIDEO_BYTES;
+  const isAudio = mime.startsWith("audio/");
+  const limit = isImage ? MAX_IMAGE_BYTES : isAudio ? MAX_AUDIO_BYTES : MAX_VIDEO_BYTES;
   if (size > limit) {
     const gotMB = (size / 1024 / 1024).toFixed(1);
     const limitMB = (limit / 1024 / 1024).toFixed(0);
     throw new SkillUploadError(
-      `"${path.basename(path$1)}" is ${gotMB}MB; limit for ${isImage ? "images" : "videos"} is ${limitMB}MB. Downscale or re-encode and try again.`
+      `"${path.basename(path$1)}" is ${gotMB}MB; limit for ${isImage ? "images" : isAudio ? "audio" : "videos"} is ${limitMB}MB. Downscale or re-encode and try again.`
     );
   }
   const buffer = await promises.readFile(path$1);
@@ -159,11 +160,12 @@ async function uploadLocalFile(path$1, ctx) {
 async function uploadLocalFiles(paths, ctx) {
   return Promise.all(paths.map((p) => uploadLocalFile(p, ctx)));
 }
-var MAX_IMAGE_BYTES, MAX_VIDEO_BYTES, EXT_TO_MIME, SkillUploadError, HOSTED_LOCAL_PATH_MESSAGE;
+var MAX_IMAGE_BYTES, MAX_VIDEO_BYTES, MAX_AUDIO_BYTES, EXT_TO_MIME, SkillUploadError, HOSTED_LOCAL_PATH_MESSAGE;
 var init_upload_helpers = __esm({
   "src/skills/upload-helpers.ts"() {
     MAX_IMAGE_BYTES = 50 * 1024 * 1024;
     MAX_VIDEO_BYTES = 200 * 1024 * 1024;
+    MAX_AUDIO_BYTES = 50 * 1024 * 1024;
     EXT_TO_MIME = {
       ".jpg": "image/jpeg",
       ".jpeg": "image/jpeg",
@@ -172,7 +174,14 @@ var init_upload_helpers = __esm({
       ".gif": "image/gif",
       ".mp4": "video/mp4",
       ".webm": "video/webm",
-      ".mov": "video/quicktime"
+      ".mov": "video/quicktime",
+      // Audio: the server checks the bytes match (a Film Studio song, song_path).
+      ".mp3": "audio/mpeg",
+      ".wav": "audio/wav",
+      ".m4a": "audio/mp4",
+      ".aac": "audio/aac",
+      ".ogg": "audio/ogg",
+      ".flac": "audio/flac"
     };
     SkillUploadError = class extends Error {
       constructor(userMessage) {
@@ -542,7 +551,7 @@ var init_generate = __esm({
     InputSchema = zod.z.object({
       prompt: zod.z.string().min(1).max(8e3).describe("Prompt describing what to generate."),
       model: zod.z.string().optional().describe(
-        `Model apiId. Recommended: "seedream-5" (images, the default) or "xai-image"; "seedance-2-5" or "xai-video" for video (prompt only or a starting image); "wan-3-0-video" for video the others refuse. Use another model only when the user names one. Full catalog: https://pixeldojo.ai/api/v1/models; one model's fields: https://pixeldojo.ai/llm/{apiId}.txt. Omit for seedream-5, which makes still images only; name a video model to get a video.`
+        `Model apiId. Recommended (the models the PixelDojo studios use): "seedream-5" for images (the default), "seedance-2-5" for video (prompt only or a starting image), "wan-3-0-video" for video the others refuse. Use another model only when the user names one. Full catalog: https://pixeldojo.ai/api/v1/models; one model's fields: https://pixeldojo.ai/llm/{apiId}.txt. Omit for seedream-5, which makes still images only; name a video model to get a video.`
       ),
       preset: zod.z.string().optional().describe(
         "Preset slug that seeds the running model's settings; explicit fields and params override it. Each preset belongs to one model (browse them by model at https://pixeldojo.ai/presets), so set `model` to that preset's model: a slug the running model has no preset for is rejected with a 400 before any charge."
@@ -581,7 +590,7 @@ var init_generate = __esm({
         prompt: { type: "string", description: "Prompt describing what to generate." },
         model: {
           type: "string",
-          description: `Model apiId. Recommended: "seedream-5" (images, the default) or "xai-image"; "seedance-2-5" or "xai-video" for video (prompt only or a starting image); "wan-3-0-video" for video the others refuse. Use another model only when the user names one. Full catalog: https://pixeldojo.ai/api/v1/models; one model's fields: https://pixeldojo.ai/llm/{apiId}.txt. Omit for seedream-5, which makes still images only; name a video model to get a video.`
+          description: `Model apiId. Recommended (the models the PixelDojo studios use): "seedream-5" for images (the default), "seedance-2-5" for video (prompt only or a starting image), "wan-3-0-video" for video the others refuse. Use another model only when the user names one. Full catalog: https://pixeldojo.ai/api/v1/models; one model's fields: https://pixeldojo.ai/llm/{apiId}.txt. Omit for seedream-5, which makes still images only; name a video model to get a video.`
         },
         preset: {
           type: "string",
@@ -629,8 +638,8 @@ var init_generate = __esm({
     };
     generateSkill = {
       name: "pixeldojo_generate",
-      description: "Generate an image or video from a prompt with any model in the PixelDojo catalog. With no `model`, a prompt runs on seedream-5, which makes still images only. For a video, name seedance-2-5 (best) or xai-video; both work from a prompt alone or a starting image. If a provider refuses the content, retry once on wan-3-0-video (video) or seedream-5 (images), the least-restricted models. Name another model only when the user asks for it. References: `image_url`/`image_urls` for stills, `video_url` for a source clip, `image_path`/`image_paths` for absolute local files (uploaded to 24h temp storage first). A clip or an audio track URL with no `model` runs on seedance-2-reference; a named model that cannot read a clip is swapped for it and the result says so, while a named model with no audio input drops the track. Model-specific settings go in `params` alongside an explicit `model`. Returns asset URLs, or a jobId for pixeldojo_status when the job outlasts the 30s wait.",
-      hostedDescription: "Generate an image or video from a prompt with any model in the PixelDojo catalog. With no `model`, a prompt runs on seedream-5, which makes still images only. For a video, name seedance-2-5 (best) or xai-video; both work from a prompt alone or a starting image. If a provider refuses the content, retry once on wan-3-0-video (video) or seedream-5 (images), the least-restricted models. Name another model only when the user asks for it. References: `image_url`/`image_urls` for stills and `video_url` for a source clip, all public http(s) URLs. A clip or an audio track URL with no `model` runs on seedance-2-reference; a named model that cannot read a clip is swapped for it and the result says so, while a named model with no audio input drops the track. Model-specific settings go in `params` alongside an explicit `model`. Returns asset URLs, or a jobId for pixeldojo_status when the job outlasts the 30s wait.",
+      description: "Generate an image or video from a prompt with any model in the PixelDojo catalog. With no `model`, a prompt runs on seedream-5, which makes still images only. For a video, name seedance-2-5, which works from a prompt alone or a starting image. If a provider refuses the content, retry once on wan-3-0-video (video) or seedream-5 (images), the least-restricted models. For a multi-shot film or a music video synced to a song use pixeldojo_film; to change, move or extend an existing clip use pixeldojo_video. These are the models the PixelDojo studios use; name another only when the user asks for it. References: `image_url`/`image_urls` for stills, `video_url` for a source clip, `image_path`/`image_paths` for absolute local files (uploaded to 24h temp storage first). A clip or an audio track URL with no `model` runs on seedance-2-reference; a named model that cannot read a clip is swapped for it and the result says so, while a named model with no audio input drops the track. Model-specific settings go in `params` alongside an explicit `model`. Returns asset URLs, or a jobId for pixeldojo_status when the job outlasts the 30s wait.",
+      hostedDescription: "Generate an image or video from a prompt with any model in the PixelDojo catalog. With no `model`, a prompt runs on seedream-5, which makes still images only. For a video, name seedance-2-5, which works from a prompt alone or a starting image. If a provider refuses the content, retry once on wan-3-0-video (video) or seedream-5 (images), the least-restricted models. For a multi-shot film or a music video synced to a song use pixeldojo_film; to change, move or extend an existing clip use pixeldojo_video. These are the models the PixelDojo studios use; name another only when the user asks for it. References: `image_url`/`image_urls` for stills and `video_url` for a source clip, all public http(s) URLs. A clip or an audio track URL with no `model` runs on seedance-2-reference; a named model that cannot read a clip is swapped for it and the result says so, while a named model with no audio input drops the track. Model-specific settings go in `params` alongside an explicit `model`. Returns asset URLs, or a jobId for pixeldojo_status when the job outlasts the 30s wait.",
       inputZod: InputSchema,
       inputJsonSchema: InputJsonSchema,
       allowedModels: null,
@@ -914,6 +923,7 @@ var init_character = __esm({
       "seedream-4",
       "google-nano-banana",
       "wan-2.7-image-edit",
+      "qwen-3-pro",
       "qwen-image-2.0-pro"
     ];
     DEFAULT_MODEL3 = "seedream-5";
@@ -924,6 +934,7 @@ var init_character = __esm({
       "seedream-4": "image_urls",
       "google-nano-banana": "image_input",
       "wan-2.7-image-edit": "image_urls",
+      "qwen-3-pro": "image",
       "qwen-image-2.0-pro": "reference_images"
     };
     InputSchema3 = zod.z.object({
@@ -1399,43 +1410,124 @@ function progressLine(f) {
   const rendering = all.filter((sh) => sh.status === "clip-generating").length;
   return `frames ${frames}/${all.length}, clips ${clips}/${all.length}${rendering > 0 ? ` (${rendering} rendering)` : ""}`;
 }
+async function runPlanner(ctx, filmId, path, body, maxPolls = PLANNER_MAX_POLLS) {
+  const submit = await filmApi(ctx, "POST", path, body);
+  if (submit.data.film) return { film: submit.data.film };
+  const jobId = submit.data.jobId;
+  if (!jobId) return { error: submit.data.error ?? `HTTP ${submit.status}` };
+  const sleep = ctx.pollOverrides?.sleep ?? ((ms) => new Promise((r) => setTimeout(r, ms)));
+  for (let i = 0; i < maxPolls; i += 1) {
+    await sleep(PLANNER_POLL_MS);
+    const { data } = await filmApi(ctx, "GET", `/api/films/${filmId}`);
+    const job = data.film?.llmJob;
+    if (!data.film || job?.id !== jobId) continue;
+    if (job.status === "error") return { error: job.error ?? "the run failed" };
+    if (job.status === "done") return { film: data.film };
+  }
+  return { pending: true };
+}
+async function sliceSong(ctx, film) {
+  const r = await filmApi(ctx, "POST", `/api/films/${film.id}/music/slice`, {
+    songDurationSec: film.musicDurationSec
+  });
+  return r.status === 200 ? null : `Could not cut the song into shots: ${r.data.error ?? r.status}`;
+}
+function plannedText(film, ctx) {
+  const total = shots(film).length;
+  const music = isMusicVideo(film);
+  const sceneLines = film.scenes.map((s, i) => `  Scene ${i + 1} "${s.title}"${s.location ? ` [${s.location}]` : ""}: ${s.shots.length} shots`);
+  return [
+    `Planned ${music ? "music video " : ""}"${film.title}" (film_id: ${film.id}): ${film.scenes.length} scenes, ${total} shots, ${film.look}, ${film.aspect}.`,
+    ...sceneLines,
+    "",
+    music ? `Nothing has been charged yet. The song is cut into one slice per shot and each clip lip-syncs to its slice on the studio music video engine. Producing renders every shot, charged as each renders. No score is composed: the export plays your song.` : `Nothing has been charged yet. Producing renders every shot (roughly 35-40 credits per 5-second shot at default engines, charged as each renders) plus a few credits for the soundtrack.`,
+    `Review or edit at ${ctx.baseUrl}/film-studio/${film.id}, or call pixeldojo_film with {"film_id": "${film.id}", "action": "produce"} to start production.`
+  ].join("\n");
+}
 async function plan(input, ctx) {
+  const music = Boolean(input.song_url || input.song_path);
   if (!input.idea?.trim() && !input.script?.trim()) {
-    return { kind: "text", text: "Provide an `idea` (we write the script, free) or a full `script` to plan a film." };
+    return {
+      kind: "text",
+      text: music ? "Provide an `idea` describing the visuals of the music video (plus optional `lyrics`)." : "Provide an `idea` (we write the script, free) or a full `script` to plan a film."
+    };
+  }
+  if (input.song_path && !input.song_url) {
+    try {
+      input = { ...input, song_url: await uploadLocalFile(input.song_path, ctx) };
+    } catch (err) {
+      if (err instanceof SkillUploadError) return { kind: "text", text: `Could not upload the song: ${err.userMessage}` };
+      throw err;
+    }
   }
   const created = await filmApi(ctx, "POST", "/api/films", {
     aspect: input.aspect,
-    look: input.look,
+    look: input.look ?? (music ? MUSIC_VIDEO_LOOKS[0] : "live-action"),
     lengthTarget: input.length,
-    assetIds: []
+    assetIds: [],
+    ...music ? {
+      // No script step names a music video, so it would stay "Untitled film".
+      ...input.idea?.trim() ? { title: input.idea.trim().slice(0, 80) } : {},
+      musicVideoMode: true,
+      musicUrl: input.song_url,
+      ...input.song_duration_sec ? { musicDurationSec: input.song_duration_sec } : {},
+      clipEngine: MUSIC_CLIP_ENGINE_ID
+    } : {}
   });
   if (!created.data.film) return { kind: "text", text: `Could not create the film: ${created.data.error ?? created.status}` };
   const id = created.data.film.id;
-  let script = input.script?.trim() ?? "";
-  if (!script) {
-    const wrote = await filmApi(ctx, "POST", `/api/films/${id}/script`, { idea: input.idea.trim() });
-    script = wrote.data.film?.script ?? "";
-    if (!script) return { kind: "text", text: `Script writing failed: ${wrote.data.error ?? wrote.status}` };
-  }
-  const planned = await filmApi(ctx, "POST", `/api/films/${id}/plan`, { script });
-  const film = planned.data.film;
-  if (!film) return { kind: "text", text: `Shot planning failed: ${planned.data.error ?? planned.status}` };
-  const total = shots(film).length;
-  const sceneLines = film.scenes.map((s, i) => `  Scene ${i + 1} "${s.title}"${s.location ? ` [${s.location}]` : ""}: ${s.shots.length} shots`);
-  return {
-    kind: "text",
-    text: [
-      `Planned "${film.title}" (film_id: ${film.id}) \u2014 ${film.scenes.length} scenes, ${total} shots, ${input.look}, ${input.aspect}.`,
-      ...sceneLines,
-      "",
-      `Nothing has been charged yet. Producing renders every shot (roughly 35-40 credits per 5-second shot at default engines, charged as each renders) plus a few credits for the soundtrack.`,
-      `Review or edit at ${ctx.baseUrl}/film-studio/${film.id} \u2014 or call pixeldojo_film with {"film_id": "${film.id}", "action": "produce"} to start production.`
-    ].join("\n")
-  };
+  let planned;
+  if (music) {
+    const brief = [input.idea?.trim() || input.script.trim(), input.lyrics?.trim() ? `Lyrics:
+${input.lyrics.trim()}` : ""].filter(Boolean).join("\n\n");
+    planned = await runPlanner(ctx, id, `/api/films/${id}/plan`, { script: brief });
+  } else {
+    let script = input.script?.trim() ?? "";
+    if (!script) {
+      const wrote = await runPlanner(ctx, id, `/api/films/${id}/script`, { idea: input.idea.trim() });
+      if ("pending" in wrote) return { kind: "text", text: stillPlanningText(id, "script") };
+      if ("error" in wrote) return { kind: "text", text: `Script writing failed: ${wrote.error}` };
+      script = wrote.film.script ?? "";
+      if (!script) return { kind: "text", text: "Script writing failed: the studio returned an empty script." };
+    }
+    planned = await runPlanner(ctx, id, `/api/films/${id}/plan`, { script });
+  }
+  if ("pending" in planned) return { kind: "text", text: stillPlanningText(id) };
+  if ("error" in planned) return { kind: "text", text: `Shot planning failed: ${planned.error}` };
+  const film = planned.film;
+  if (needsSlice(film)) {
+    const err = await sliceSong(ctx, film);
+    if (err) return { kind: "text", text: `${plannedText(film, ctx)}
+
+${err} Call action "status" to retry the cut.` };
+  }
+  return { kind: "text", text: plannedText(film, ctx) };
+}
+async function resumePlanning(film, ctx) {
+  if (film.scenes.length > 0 && film.llmJob?.status !== "running") return null;
+  if (film.llmJob?.status === "running") {
+    return { kind: "text", text: stillPlanningText(film.id, film.llmJob.kind === "script" ? "script" : "plan") };
+  }
+  const prior = film.llmJob?.status === "error" ? `The last planning run failed (${film.llmJob.error ?? "unknown"}). ` : "";
+  if (!film.script?.trim()) {
+    return { kind: "text", text: `${prior}This film has nothing to plan from. Start a new one with action "plan".` };
+  }
+  const planned = await runPlanner(ctx, film.id, `/api/films/${film.id}/plan`, { script: film.script }, 0);
+  if ("pending" in planned) return { kind: "text", text: `${prior}${stillPlanningText(film.id)}` };
+  if ("error" in planned) return { kind: "text", text: `Shot planning failed: ${planned.error} Call action "status" to retry.` };
+  if (needsSlice(planned.film)) {
+    const err = await sliceSong(ctx, planned.film);
+    if (err) return { kind: "text", text: `${plannedText(planned.film, ctx)}
+
+${err} Call action "status" to retry the cut.` };
+  }
+  return { kind: "text", text: plannedText(planned.film, ctx) };
 }
 async function produce(filmId, ctx) {
   const { data } = await filmApi(ctx, "GET", `/api/films/${filmId}`);
   if (!data.film) return { kind: "text", text: `Film not found: ${data.error ?? filmId}` };
+  const planning = await resumePlanning(data.film, ctx);
+  if (planning) return planning;
   const pending = shots(data.film).filter((sh) => sh.status === "idle" || sh.status === "failed" && !sh.frameUrl);
   let fired = 0;
   for (const sh of pending.slice(0, 6)) {
@@ -1499,6 +1591,16 @@ It is saved in the Library folder "Film: ${film.title}".`
   if (film.exportError) {
     return { kind: "text", text: `Export failed: ${film.exportError} Poll again with action "status" to retry.` };
   }
+  const planning = await resumePlanning(film, ctx);
+  if (planning) return planning;
+  if (needsSlice(film)) {
+    const err = await sliceSong(ctx, film);
+    if (err) return { kind: "text", text: `${err} Poll again with action "status" to retry.` };
+    return { kind: "text", text: `Song cut into one slice per shot. Poll again with {"film_id": "${filmId}", "action": "status"} to keep production moving.` };
+  }
+  if (shots(film).length > 0 && shots(film).every((sh) => sh.status === "idle")) {
+    return { kind: "text", text: plannedText(film, ctx) };
+  }
   const idleFrames = all.filter((sh) => sh.status === "idle");
   for (const sh of idleFrames.slice(0, 6)) {
     await filmApi(ctx, "POST", `/api/films/${filmId}/shots/${sh.id}/generate`, { kind: "frame" });
@@ -1518,7 +1620,7 @@ It is saved in the Library folder "Film: ${film.title}".`
       await filmApi(ctx, "POST", `/api/films/${filmId}/save`, { kind: "clip" });
     }
     const hasMusic = film.audioStems.some((st) => st.kind === "music");
-    if (soundtrack !== "none" && !hasMusic) {
+    if (soundtrack !== "none" && !hasMusic && !isMusicVideo(film)) {
       if (musicJobId) {
         const job = await ctx.client.getJob(musicJobId);
         const out = job.output;
@@ -1557,14 +1659,22 @@ async function run8(input, ctx) {
   if (action === "produce") return produce(input.film_id, ctx);
   return advance(input.film_id, input.soundtrack, input.music_job_id, ctx);
 }
-var LOOKS, InputSchema8, InputJsonSchema8, shots, count, LOOK_MUSIC, ARC, filmSkill;
+var STORY_LOOKS, MUSIC_VIDEO_LOOKS, LOOKS, MUSIC_CLIP_ENGINE_ID, InputSchema8, InputJsonSchema8, shots, count, PLANNER_POLL_MS, PLANNER_MAX_POLLS, isMusicVideo, needsSlice, stillPlanningText, LOOK_MUSIC, ARC, filmSkill;
 var init_film = __esm({
   "src/skills/film.ts"() {
-    LOOKS = ["live-action", "anime", "3d-animation", "noir", "horror", "sci-fi", "documentary", "western", "romance", "romantic-comedy", "comedy"];
+    init_upload_helpers();
+    STORY_LOOKS = ["live-action", "anime", "3d-animation", "noir", "horror", "sci-fi", "documentary", "western", "romance", "romantic-comedy", "comedy"];
+    MUSIC_VIDEO_LOOKS = ["rap-video", "neon-club", "stage-performance", "retro-camcorder", "y2k-pop", "moody-rnb", "rock-grit", "dream-pop", "k-pop"];
+    LOOKS = [...STORY_LOOKS, ...MUSIC_VIDEO_LOOKS];
+    MUSIC_CLIP_ENGINE_ID = "minimax-h3-reference";
     InputSchema8 = zod.z.object({
       idea: zod.z.string().max(2e3).optional().describe("One-to-three sentence film idea. The studio writes the screenplay (free). Provide idea OR script for planning."),
       script: zod.z.string().max(2e4).optional().describe("A full screenplay to plan instead of an idea (sluglines, action lines, dialogue)."),
-      look: zod.z.enum(LOOKS).default("live-action").describe("Visual style carried through frames, clips, and soundtrack."),
+      look: zod.z.enum(LOOKS).optional().describe("Visual style carried through frames, clips, and soundtrack. Default live-action, or rap-video for a music video."),
+      song_url: zod.z.string().url().startsWith("https://").max(2e3).optional().describe("Music video mode: URL of the song, which must be your own PixelDojo upload (from pixeldojo_upload), not a third-party link. The film is cut to the song and every clip lip-syncs to its slice of it. idea describes the visuals."),
+      song_path: zod.z.string().max(4096).optional().describe("Music video mode, local server only: absolute path to the song file (MP3, WAV, M4A, AAC, OGG, FLAC up to 50MB). Uploaded for you; use instead of song_url."),
+      song_duration_sec: zod.z.number().positive().max(7200).optional().describe("Music video mode (optional): the song length in seconds. Omit it and the studio measures the song."),
+      lyrics: zod.z.string().max(1e4).optional().describe("Music video mode: the song lyrics, so shots land on the right lines. Optional."),
       aspect: zod.z.enum(["16:9", "9:16"]).default("16:9"),
       length: zod.z.enum(["30s", "60s", "2-3min", "5min"]).default("60s").describe("Target length; drives the shot count (~6/12/24/60 shots)."),
       film_id: zod.z.string().max(40).optional().describe("Existing film id (from a previous call) for produce/status."),
@@ -1577,9 +1687,22 @@ var init_film = __esm({
       properties: {
         idea: { type: "string", description: "Plan step: one-to-three sentence film idea. The studio writes the screenplay (free). Provide idea or script." },
         script: { type: "string", description: "Plan step: a full screenplay (sluglines, action lines, dialogue) to plan instead of an idea." },
-        look: { type: "string", enum: [...LOOKS], description: "Plan step: visual style carried through frames, clips and soundtrack. Default live-action." },
+        look: { type: "string", enum: [...LOOKS], description: `Plan step: visual style carried through frames, clips and soundtrack. Story looks: ${STORY_LOOKS.join(", ")} (default live-action). Music video looks: ${MUSIC_VIDEO_LOOKS.join(", ")} (default rap-video).` },
+        song_url: {
+          type: "string",
+          description: "Plan step, music video mode: URL of the song. It must be your own PixelDojo upload (from pixeldojo_upload or /api/v1/upload); a third-party link is refused. Makes a music video cut to this song, every clip lip-synced to its slice of it, rendered on the studio music video engine. idea (or script) describes the visuals. No score is composed: the song is the soundtrack."
+        },
+        song_path: {
+          type: "string",
+          description: "Plan step, music video mode: absolute local path to the song (MP3, WAV, M4A, AAC, OGG, FLAC up to 50MB). Uploaded for you; use instead of song_url."
+        },
+        song_duration_sec: {
+          type: "number",
+          description: "Plan step, music video mode (optional): the song length in seconds. Omit it and the studio measures the song."
+        },
+        lyrics: { type: "string", description: "Plan step, music video mode (optional): the song lyrics, so shots land on the right lines." },
         aspect: { type: "string", enum: ["16:9", "9:16"], description: "Plan step: frame aspect ratio. Default 16:9." },
-        length: { type: "string", enum: ["30s", "60s", "2-3min", "5min"], description: "Plan step: target length, which sets the shot count (~6/12/24/60 shots). Default 60s." },
+        length: { type: "string", enum: ["30s", "60s", "2-3min", "5min"], description: "Plan step: target length, which sets the shot count (~6/12/24/60 shots). Default 60s. Ignored for a music video, whose length is the song." },
         film_id: { type: "string", description: 'The film_id returned by the plan step. Required for produce and status; with it, action "plan" is treated as "status".' },
         action: {
           type: "string",
@@ -1589,7 +1712,7 @@ var init_film = __esm({
         soundtrack: {
           type: "string",
           enum: ["scene-synced", "flat", "none"],
-          description: "Read on status calls once all clips are ready. scene-synced (default): one musical section per scene. flat: one cohesive bed. none: export without music."
+          description: "Read on status calls once all clips are ready. scene-synced (default): one musical section per scene. flat: one cohesive bed. none: export without music. Ignored for a music video, which always exports with its song."
         },
         music_job_id: {
           type: "string",
@@ -1599,6 +1722,11 @@ var init_film = __esm({
     };
     shots = (f) => f.scenes.flatMap((s) => s.shots);
     count = (f, pred) => shots(f).filter(pred).length;
+    PLANNER_POLL_MS = 3e3;
+    PLANNER_MAX_POLLS = 8;
+    isMusicVideo = (f) => f.musicVideoMode === true;
+    needsSlice = (f) => isMusicVideo(f) && shots(f).length > 0 && !shots(f).some((sh) => sh.musicChunkUrl);
+    stillPlanningText = (filmId, stage = "plan") => `${stage === "script" ? "Still writing the script" : "Still planning the shots"} for film_id ${filmId}. Nothing has been charged. Call pixeldojo_film with {"film_id": "${filmId}", "action": "status"} in ~30s; it returns the plan once it is ready.`;
     LOOK_MUSIC = {
       "live-action": "modern cinematic underscore, warm strings and soft felt piano, subtle rhythmic pulse, slow emotional build",
       anime: "sweeping anime film score, lush strings and piano, taiko drum accents, soaring heartfelt theme",
@@ -1619,7 +1747,8 @@ var init_film = __esm({
     };
     filmSkill = {
       name: "pixeldojo_film",
-      description: "Make a finished short film from one idea: screenplay, storyboard frames (AI-reviewed), video clips with spoken dialogue, scene-synced soundtrack, stitched export. Phased: plan is free and returns a cost estimate; produce starts charged generation; status advances production (poll every ~30s).",
+      description: "Make a finished short film from one idea: screenplay, storyboard frames (AI-reviewed), video clips with spoken dialogue, scene-synced soundtrack, stitched export. Or a music video: pass song_path (a local file) or song_url (your own PixelDojo upload from pixeldojo_upload, never a third-party link) with optional lyrics; the film is cut to that song, each clip lip-synced to its slice on the studio music video engine, and no score is composed: the export plays the song. Phased: plan is free; produce starts charged generation; status advances production (poll every ~30s).",
+      hostedDescription: "Make a finished short film from one idea: screenplay, storyboard frames (AI-reviewed), video clips with spoken dialogue, scene-synced soundtrack, stitched export. Or a music video: pass song_url (your own PixelDojo upload made with POST /api/v1/upload, never a third-party link) with optional lyrics; the film is cut to that song, each clip lip-synced to its slice on the studio music video engine, and no score is composed: the export plays the song. Phased: plan is free; produce starts charged generation; status advances production (poll every ~30s).",
       inputZod: InputSchema8,
       inputJsonSchema: InputJsonSchema8,
       allowedModels: [],
@@ -1628,7 +1757,512 @@ var init_film = __esm({
     };
   }
 });
+function buildVideoPayload(verb, apiId, i) {
+  const prompt = i.prompt ?? "";
+  const vd = i.videoDuration;
+  if (NEEDS_VIDEO_DURATION.has(apiId) && vd === void 0) {
+    return {
+      error: `${apiId} needs video_duration: the source clip's length in seconds (it sets the credit cost).`
+    };
+  }
+  if (verb === "move" && !i.images[0]) {
+    return { error: `The move verb needs image_url: the character image to put into the video.` };
+  }
+  const droppedImages = i.images.length > 0 && (verb === "extend" || NO_IMAGE_ENGINES.has(apiId)) ? `${apiId} takes no reference images, so I left them off.` : void 0;
+  if (verb === "change") {
+    switch (apiId) {
+      case "seedance-2-5-video-edit":
+        return {
+          body: {
+            mode: "edit",
+            prompt,
+            video_url: i.videoUrl,
+            reference_images: i.images,
+            ...vd !== void 0 ? { source_duration_seconds: vd } : {}
+          }
+        };
+      case "flux-video-edit":
+        return { body: { prompt, video: i.videoUrl, video_duration: Math.ceil(vd) }, note: droppedImages };
+      case "xai-video-edit":
+        return { body: { prompt, video_url: i.videoUrl, video_duration: vd }, note: droppedImages };
+      case "happyhorse-1.0-video-edit":
+        return { body: { prompt, video_url: i.videoUrl, video_duration: vd, reference_urls: i.images } };
+      default:
+        return { body: { prompt, video_url: i.videoUrl, video_duration: vd, image_urls: i.images } };
+    }
+  }
+  if (verb === "move") {
+    if (apiId === "wan-video-character-swap") {
+      return { body: { prompt: "", image_url: i.images[0], video_url: i.videoUrl, video_duration: vd } };
+    }
+    return {
+      body: {
+        prompt,
+        video: i.videoUrl,
+        video_duration: vd,
+        character_image: i.images[0],
+        // Not a background toggle: 'video' is the 30s duration cap.
+        character_orientation: "video"
+      }
+    };
+  }
+  switch (apiId) {
+    case "seedance-2-5-video-edit":
+      return {
+        body: {
+          mode: "extend",
+          prompt,
+          video_url: i.videoUrl,
+          direction: i.direction ?? "forward",
+          duration: clamp(i.duration ?? 5, 4, 30),
+          ...vd !== void 0 ? { source_duration_seconds: vd } : {}
+        },
+        note: droppedImages
+      };
+    case "wan-2.7-i2v": {
+      const chosen = clamp(i.duration ?? 5, 2, 15);
+      return {
+        body: {
+          mode: "video-extend",
+          prompt,
+          video_url: i.videoUrl,
+          // A continuation shorter than its own source is rejected outright.
+          duration: vd ? Math.min(15, Math.max(chosen, Math.ceil(vd) + 1)) : chosen,
+          ...vd ? { source_video_duration: vd } : {}
+        },
+        note: droppedImages
+      };
+    }
+    default:
+      return {
+        body: { prompt, video_url: i.videoUrl, extension_duration: clamp(i.duration ?? 6, 2, 10) },
+        note: droppedImages
+      };
+  }
+}
 async function run9(input, ctx) {
+  const paramsGate = paramsWithoutModel(input.params, input.model);
+  if (paramsGate) return { kind: "text", text: paramsGate };
+  const verb = input.verb;
+  const engines = VIDEO_STUDIO_ENGINES[verb];
+  const notes = [];
+  let apiId = input.model ?? engines[0];
+  if (!engines.includes(apiId)) {
+    notes.push(`${apiId} is not a Video Studio ${verb} engine, so I used ${engines[0]} instead.`);
+    apiId = engines[0];
+  }
+  if (verb === "extend" && input.direction === "backward" && !BACKWARD_ENGINES.has(apiId)) {
+    notes.push(`${apiId} only extends forward, so I used ${engines[0]} to extend backward.`);
+    apiId = engines[0];
+  }
+  let videoUrl = input.video_url;
+  const images = [...input.image_url ? [input.image_url] : [], ...input.image_urls ?? []];
+  try {
+    if (!videoUrl && input.video_path) videoUrl = await uploadLocalFile(input.video_path, ctx);
+    if (!input.image_url && input.image_path) images.unshift(await uploadLocalFile(input.image_path, ctx));
+  } catch (err) {
+    if (err instanceof SkillUploadError) {
+      return { kind: "text", text: `pixeldojo_video (upload): ${err.userMessage}` };
+    }
+    throw err;
+  }
+  if (!videoUrl) {
+    return {
+      kind: "text",
+      text: `pixeldojo_video ${verb} needs video_url: the ${verb === "move" ? "driving motion clip" : "source clip"}.`
+    };
+  }
+  if (verb !== "move" && !input.prompt?.trim()) {
+    return { kind: "text", text: `pixeldojo_video ${verb} needs a prompt.` };
+  }
+  const built = buildVideoPayload(verb, apiId, {
+    prompt: input.prompt,
+    videoUrl,
+    images: images.filter((u, i, all) => all.indexOf(u) === i),
+    videoDuration: input.video_duration,
+    duration: input.duration,
+    direction: input.direction
+  });
+  if ("error" in built) return { kind: "text", text: `pixeldojo_video: ${built.error}` };
+  if (built.note) notes.push(built.note);
+  const body = built.body;
+  const paramsNote = applyParams(body, input.params, input.model, apiId);
+  if (paramsNote) notes.push(paramsNote);
+  const submitted = await ctx.client.run(apiId, body);
+  const result = await pollJobUntilDoneOrHandoff(
+    submitted.jobId,
+    (id) => ctx.client.getJob(id),
+    ctx.buildStatusUrl,
+    { now: ctx.pollOverrides?.now, sleep: ctx.pollOverrides?.sleep }
+  );
+  return prefixNote(
+    pollResultToSkillResult(
+      result,
+      (urls) => urls.length === 0 ? `Job ${submitted.jobId} completed but returned no assets.` : `Video ready (${verb} on ${apiId}). Asset: ${urls.join(", ")}`
+    ),
+    notes.join(" ")
+  );
+}
+var VIDEO_STUDIO_ENGINES, VERBS, BACKWARD_ENGINES, clamp, NEEDS_VIDEO_DURATION, NO_IMAGE_ENGINES, InputSchema9, engineList, InputJsonSchema9, BASE_DESCRIPTION, videoSkill;
+var init_video = __esm({
+  "src/skills/video.ts"() {
+    init_poll();
+    init_types();
+    init_upload_helpers();
+    init_params();
+    VIDEO_STUDIO_ENGINES = {
+      change: [
+        "seedance-2-5-video-edit",
+        "flux-video-edit",
+        "kling-video-edit",
+        "wan-video-edit",
+        "seedance-video-edit",
+        "happyhorse-1.0-video-edit",
+        "xai-video-edit"
+      ],
+      move: ["kling-motion-control", "wan-video-character-swap"],
+      extend: ["seedance-2-5-video-edit", "wan-2.7-i2v", "grok-video-extend"]
+    };
+    VERBS = ["change", "move", "extend"];
+    BACKWARD_ENGINES = /* @__PURE__ */ new Set(["seedance-2-5-video-edit"]);
+    clamp = (n, min, max) => Math.min(max, Math.max(min, Math.round(n)));
+    NEEDS_VIDEO_DURATION = /* @__PURE__ */ new Set([
+      "flux-video-edit",
+      "kling-video-edit",
+      "wan-video-edit",
+      "seedance-video-edit",
+      "happyhorse-1.0-video-edit",
+      "xai-video-edit",
+      "kling-motion-control",
+      "wan-video-character-swap"
+    ]);
+    NO_IMAGE_ENGINES = /* @__PURE__ */ new Set(["flux-video-edit", "xai-video-edit"]);
+    InputSchema9 = zod.z.object({
+      verb: zod.z.enum(VERBS),
+      prompt: zod.z.string().max(8e3).optional(),
+      video_url: zod.z.string().url().optional(),
+      video_path: zod.z.string().min(1).optional(),
+      image_url: zod.z.string().url().optional(),
+      image_urls: zod.z.array(zod.z.string().url()).optional(),
+      image_path: zod.z.string().min(1).optional(),
+      model: zod.z.string().optional(),
+      video_duration: zod.z.number().positive().optional(),
+      duration: zod.z.number().int().positive().optional(),
+      direction: zod.z.enum(["forward", "backward"]).optional(),
+      params: ParamsInput
+    });
+    engineList = (verb) => `${verb}: ${VIDEO_STUDIO_ENGINES[verb].join(", ")} (default ${VIDEO_STUDIO_ENGINES[verb][0]})`;
+    InputJsonSchema9 = {
+      type: "object",
+      properties: {
+        verb: {
+          type: "string",
+          enum: VERBS,
+          description: "change = restyle or edit an existing clip; move = put a character image into a driving video (motion transfer / character swap); extend = continue a clip forward (or backward on the default engine)."
+        },
+        prompt: {
+          type: "string",
+          description: "What to change, how the character should move, or what happens next. Required for change and extend. Optional for move (wan-video-character-swap ignores it)."
+        },
+        video_url: {
+          type: "string",
+          format: "uri",
+          description: "The source clip (change, extend) or the driving motion clip (move). Required."
+        },
+        video_path: {
+          type: "string",
+          description: "Absolute local path to the source clip (MP4, WebM, MOV). Uploaded to 24h temp storage and used as video_url."
+        },
+        image_url: {
+          type: "string",
+          format: "uri",
+          description: "The character image (move, required) or a reference image (change, optional; some engines take none)."
+        },
+        image_urls: {
+          type: "array",
+          items: { type: "string", format: "uri" },
+          description: "More reference images for change engines that take a set. Move uses the first image only."
+        },
+        image_path: {
+          type: "string",
+          description: "Absolute local path to the character or reference image. Uploaded to 24h temp storage and used as image_url."
+        },
+        model: {
+          type: "string",
+          description: `Video Studio engine for this verb. Omit for the default. ${VERBS.map((v) => engineList(v)).join("; ")}. A model not on the verb's list is replaced by the default and the result says so.`
+        },
+        video_duration: {
+          type: "number",
+          description: "The source clip's length in seconds. Required by every engine except the change/extend default and grok-video-extend, since it sets their credit cost."
+        },
+        duration: {
+          type: "integer",
+          description: "Extend only: output length in seconds (default engine 4-30, wan-2.7-i2v 2-15 total), or seconds added on grok-video-extend (2-10). Ignored by change and move, which keep the source length."
+        },
+        direction: {
+          type: "string",
+          enum: ["forward", "backward"],
+          description: "Extend only. backward adds footage before the clip; only the default engine supports it."
+        },
+        params: PARAMS_JSON_SCHEMA
+      },
+      required: ["verb"]
+    };
+    BASE_DESCRIPTION = "Video Studio verbs for an existing clip, on the same engines the studio uses. verb=change restyles or edits a clip (prompt + video_url, optional reference images). verb=move puts a character image into a driving video's motion (video_url + image_url + video_duration). verb=extend continues a clip forward, or backward on the default engine (prompt + video_url, optional duration and direction). Omit `model` for the studio default; engine-specific settings go in `params` with an explicit `model`. To make a new video, use pixeldojo_generate. Returns asset URLs, or a jobId for pixeldojo_status when the job outlasts the 30s wait.";
+    videoSkill = {
+      name: "pixeldojo_video",
+      description: `${BASE_DESCRIPTION} Local files: video_path / image_path (uploaded to 24h temp storage first).`,
+      hostedDescription: `${BASE_DESCRIPTION} Media must be public http(s) URLs.`,
+      inputZod: InputSchema9,
+      inputJsonSchema: InputJsonSchema9,
+      allowedModels: Array.from(new Set(VERBS.flatMap((v) => VIDEO_STUDIO_ENGINES[v]))),
+      defaultModel: VIDEO_STUDIO_ENGINES.change[0],
+      run: run9
+    };
+  }
+});
+async function episodeApi(ctx, method, path, body) {
+  const res = await fetch(`${ctx.baseUrl}/api/faceless-studio/episodes${path}`, {
+    method,
+    headers: {
+      Authorization: `Bearer ${ctx.apiKey}`,
+      "Content-Type": "application/json",
+      "x-pixeldojo-source": `mcp/${ctx.mcpVersion}`,
+      "x-pixeldojo-skill": "episode"
+    },
+    ...body !== void 0 ? { body: JSON.stringify(body) } : {}
+  });
+  const data = await res.json().catch(() => ({}));
+  return { status: res.status, data };
+}
+function quoteText(ep, price, ctx) {
+  const engines = [...new Set(ep.scenes.map((s) => s.engine))].join(", ");
+  const seconds = ep.scenes.reduce((n, s) => n + s.shotSeconds, 0);
+  return [
+    `Planned "${ep.title}" (episode_id: ${ep.id}): ${ep.scenes.length} scenes, about ${Math.round(seconds)}s of picture, engine ${engines}.`,
+    ...ep.scenes.slice(0, 12).map((s, i) => `  ${i + 1}. ${s.narration.slice(0, 110)}`),
+    ...ep.scenes.length > 12 ? [`  ... and ${ep.scenes.length - 12} more.`] : [],
+    "",
+    price ? `Nothing has been charged yet. Producing it costs about ${price.total} credits at list price: scenes ${price.scenes}, narration ${price.narration}, music ${price.music}. Each part is charged as it renders; an active sale can make it lower.` : "Nothing has been charged yet.",
+    `Review or edit at ${ctx.baseUrl}/faceless-studio?episode=${ep.id}, or call ${call(ep.id, "produce")} to start production.`
+  ].join("\n");
+}
+async function waitForPlan(ctx, id) {
+  const sleep = ctx.pollOverrides?.sleep ?? ((ms) => new Promise((r) => setTimeout(r, ms)));
+  for (let i = 0; i < PLAN_MAX_POLLS; i += 1) {
+    await sleep(PLAN_POLL_MS);
+    const { data } = await episodeApi(ctx, "GET", `/${id}`);
+    if (data.episode?.plan.job?.status !== "running") return data;
+  }
+  return null;
+}
+async function setEngine(ctx, ep, engine) {
+  const { data } = await episodeApi(ctx, "PATCH", `/${ep.id}`, {
+    scenes: ep.scenes.map((s) => ({ id: s.id, narration: s.narration, visualPrompt: s.visualPrompt, engine }))
+  });
+  if (!data.episode) return {};
+  return (await episodeApi(ctx, "GET", `/${ep.id}`)).data;
+}
+async function create(input, ctx) {
+  if (!input.topic?.trim()) {
+    return { kind: "text", text: "Provide a `topic` (8 to 400 characters) to create an episode." };
+  }
+  const created = await episodeApi(ctx, "POST", "", {
+    topic: input.topic.trim(),
+    category: input.category,
+    format: input.aspect,
+    targetSeconds: input.length_seconds,
+    style: input.style,
+    voiceId: input.voice,
+    ...input.title?.trim() ? { title: input.title.trim() } : {}
+  });
+  const ep = created.data.episode;
+  if (!ep) return { kind: "text", text: `Could not create the episode: ${created.data.error ?? created.status}` };
+  if (!input.music) await episodeApi(ctx, "PATCH", `/${ep.id}`, { musicEnabled: false });
+  const plan2 = await episodeApi(ctx, "POST", `/${ep.id}/plan`, { scope: "episode" });
+  if (plan2.status !== 202) {
+    return { kind: "text", text: `Episode created (episode_id: ${ep.id}) but planning did not start: ${plan2.data.error ?? plan2.status}` };
+  }
+  let planned = await waitForPlan(ctx, ep.id);
+  if (!planned) return { kind: "text", text: stillPlanning(ep.id) };
+  if (!planned.episode || planned.episode.plan.job?.status === "error" || planned.episode.scenes.length === 0) {
+    return { kind: "text", text: `Planning failed: ${planned.episode?.plan.job?.error ?? planned.error ?? "no scenes came back"}` };
+  }
+  if (input.engine) {
+    const switched = await setEngine(ctx, planned.episode, input.engine);
+    if (switched.episode) planned = switched;
+  }
+  return { kind: "text", text: quoteText(planned.episode, planned.price, ctx) };
+}
+function progress(ep) {
+  const done = ep.scenes.filter((s) => s.render.status === "done" && s.render.url && !s.render.stale).length;
+  const running = ep.scenes.filter((s) => s.render.status === "running").length;
+  const narr = ep.narration?.audioUrl ? "recorded" : ep.narration?.status === "running" ? "recording" : "not recorded";
+  const music = !ep.musicEnabled ? "off" : ep.music?.url ? "ready" : ep.music?.status ?? "not started";
+  const exp = ep.export?.status ?? "not started";
+  return `narration ${narr}, scenes ${done}/${ep.scenes.length}${running ? ` (${running} rendering)` : ""}, music ${music}, export ${exp}`;
+}
+async function status(id, ctx) {
+  const { data, status: code } = await episodeApi(ctx, "GET", `/${id}`);
+  const ep = data.episode;
+  if (!ep) return { kind: "text", text: `Episode not found: ${data.error ?? code}` };
+  if (ep.plan.job?.status === "running") return { kind: "text", text: stillPlanning(id) };
+  if (ep.scenes.length === 0) {
+    return { kind: "text", text: `"${ep.title}" has no scene plan yet${ep.plan.job?.error ? ` (${ep.plan.job.error})` : ""}. Create a new episode with action "create".` };
+  }
+  if (ep.export?.status === "done" && ep.export.url && ep.savedAt && !ep.export.stale) {
+    return { kind: "text", text: `"${ep.title}" is finished: ${ep.export.url}` };
+  }
+  const quote = data.price ? ` Plan quote: about ${data.price.total} credits at list price.` : "";
+  return { kind: "text", text: `"${ep.title}": ${progress(ep)}.${quote} Call ${call(id, "produce")} to keep production moving.` };
+}
+async function generate(ctx, id, path, label, regenerate = false) {
+  const r = await episodeApi(ctx, "POST", `/${id}${path}`, regenerate ? { regenerate: true } : {});
+  if (r.status === 200) {
+    return { ok: true, line: `${label} started (${r.data.creditCost ?? "?"} credits).` };
+  }
+  return { ok: false, line: `${label} did not start: ${r.data.error ?? r.status}` };
+}
+async function produce2(id, ctx) {
+  const { data, status: code } = await episodeApi(ctx, "GET", `/${id}`);
+  const ep = data.episode;
+  if (!ep) return { kind: "text", text: `Episode not found: ${data.error ?? code}` };
+  if (ep.plan.job?.status === "running") return { kind: "text", text: stillPlanning(id) };
+  if (ep.scenes.length === 0) {
+    return { kind: "text", text: `"${ep.title}" has no scene plan to produce. Create a new episode with action "create".` };
+  }
+  if (!ep.narration?.audioUrl) {
+    if (ep.narration?.status === "running") {
+      return { kind: "text", text: `Narration is recording. ${next(id, "produce", "~20s")}` };
+    }
+    const g = await generate(ctx, id, "/narration/generate", "Narration");
+    const failed = ep.narration?.status === "failed" ? ` (the last take failed: ${ep.narration.error ?? "unknown"})` : "";
+    return { kind: "text", text: `${g.line}${failed} ${next(id, "produce", "~20s")}` };
+  }
+  const running = ep.scenes.filter((s) => s.render.status === "running").length;
+  const queue = ep.scenes.filter(needsRender);
+  if (queue.length > 0 || running > 0) {
+    const lines = [];
+    let spent = 0;
+    for (const s of queue.slice(0, Math.max(0, MAX_IN_FLIGHT - running))) {
+      const r = await episodeApi(ctx, "POST", `/${id}/scenes/${s.id}/generate`, {});
+      if (r.status === 200) spent += r.data.creditCost ?? 0;
+      else {
+        lines.push(`Scene ${ep.scenes.indexOf(s) + 1} did not start: ${r.data.error ?? r.status}`);
+        if (r.status === 402 || r.status === 403) break;
+      }
+    }
+    const failed = ep.scenes.filter((s) => s.render.status === "failed");
+    return {
+      kind: "text",
+      text: [
+        `In progress: ${progress(ep)}.`,
+        spent > 0 ? `Started scene renders for ${Math.round(spent * 10) / 10} credits.` : "",
+        failed.length > 0 ? `${failed.length} scene(s) failed and were re-queued (${failed[0]?.render.error?.slice(0, 100) ?? ""}).` : "",
+        ...lines,
+        next(id, "produce", "~30s")
+      ].filter(Boolean).join("\n")
+    };
+  }
+  if (ep.musicEnabled && !ep.music?.url && ep.music?.status !== "failed") {
+    if (ep.music?.status === "running") {
+      return { kind: "text", text: `All scenes rendered; the music bed is composing. ${next(id, "produce", "~20s")}` };
+    }
+    const g = await generate(ctx, id, "/music/generate", "Music bed");
+    return { kind: "text", text: `All scenes rendered. ${g.line} ${next(id, "produce", "~20s")}` };
+  }
+  const exp = ep.export;
+  if (exp?.status === "running") {
+    return { kind: "text", text: `Export is stitching the episode. ${next(id, "produce", "~60s")}` };
+  }
+  if (exp?.status === "done" && exp.url && !exp.stale) {
+    if (ep.savedAt) return { kind: "text", text: `"${ep.title}" is finished: ${exp.url}` };
+    const saved = await episodeApi(ctx, "POST", `/${id}/save`, {});
+    const url = saved.data.episode?.export?.url;
+    if (saved.status !== 200 || !url) {
+      return { kind: "text", text: `The export is ready but could not be saved: ${saved.data.error ?? saved.status}. The draft (kept 24h): ${exp.url}. ${next(id, "produce", "~30s")}` };
+    }
+    return { kind: "text", text: `"${ep.title}" is finished and saved to My Media: ${url}` };
+  }
+  const started = await episodeApi(ctx, "POST", `/${id}/export`, {});
+  if (started.status !== 202) {
+    return { kind: "text", text: `Export did not start: ${started.data.error ?? started.status}. ${next(id, "produce", "~30s")}` };
+  }
+  const prior = exp?.status === "failed" ? ` (the last export failed: ${exp.error ?? "unknown"})` : "";
+  const musicNote = ep.musicEnabled && ep.music?.status === "failed" ? " The music bed failed, so this cut has no music." : "";
+  return { kind: "text", text: `Export started, free${prior}.${musicNote} ${next(id, "produce", "~60s")}` };
+}
+async function run10(input, ctx) {
+  const action = input.action === "create" && input.episode_id ? "status" : input.action;
+  if (action === "create") return create(input, ctx);
+  if (!input.episode_id) return { kind: "text", text: "produce and status need the episode_id returned by the create step." };
+  if (action === "produce") return produce2(input.episode_id, ctx);
+  return status(input.episode_id, ctx);
+}
+var STYLES, CATEGORIES, ENGINES, MIN_SECONDS, MAX_SECONDS, MAX_IN_FLIGHT, InputSchema10, InputJsonSchema10, call, next, needsRender, PLAN_POLL_MS, PLAN_MAX_POLLS, stillPlanning, episodeSkill;
+var init_episode = __esm({
+  "src/skills/episode.ts"() {
+    STYLES = ["editorial-motion", "paper-diorama", "hand-drawn", "storybook", "poster-vector", "soft-3d"];
+    CATEGORIES = ["education", "history", "kids", "storytelling", "custom"];
+    ENGINES = ["omni-draft", "omni-final", "still-motion"];
+    MIN_SECONDS = 60;
+    MAX_SECONDS = 300;
+    MAX_IN_FLIGHT = 4;
+    InputSchema10 = zod.z.object({
+      action: zod.z.enum(["create", "produce", "status"]).default("create"),
+      topic: zod.z.string().min(8).max(400).optional(),
+      episode_id: zod.z.string().max(40).optional(),
+      category: zod.z.enum(CATEGORIES).default("education"),
+      style: zod.z.enum(STYLES).default("editorial-motion"),
+      aspect: zod.z.enum(["16:9", "9:16"]).default("16:9"),
+      length_seconds: zod.z.number().int().min(MIN_SECONDS).max(MAX_SECONDS).default(120),
+      voice: zod.z.string().min(1).max(80).default("Wise_Woman"),
+      engine: zod.z.enum(ENGINES).optional(),
+      music: zod.z.boolean().default(true),
+      title: zod.z.string().max(120).optional()
+    });
+    InputJsonSchema10 = {
+      type: "object",
+      properties: {
+        action: {
+          type: "string",
+          enum: ["create", "produce", "status"],
+          description: "create (default, free): writes the script and scene plan, returns episode_id and the credit quote. produce (charged): advances production one step (narration, scene renders, music, export, save) and reports what that step cost; call it every ~30s until it returns the finished video URL. status (free): progress only."
+        },
+        topic: { type: "string", description: "Create step: what the episode is about, 8 to 400 characters." },
+        episode_id: { type: "string", description: "The episode_id from the create step. Required for produce and status." },
+        category: { type: "string", enum: [...CATEGORIES], description: "Create step: tone of the script. Default education." },
+        style: { type: "string", enum: [...STYLES], description: "Create step: visual style of every scene. Default editorial-motion." },
+        aspect: { type: "string", enum: ["16:9", "9:16"], description: "Create step: 16:9 landscape (default) or 9:16 vertical." },
+        length_seconds: { type: "integer", minimum: MIN_SECONDS, maximum: MAX_SECONDS, description: "Create step: target length in seconds. Default 120." },
+        voice: { type: "string", description: "Create step: narrator voice id from the text-to-speech tool (e.g. Wise_Woman, Deep_Voice_Man, Friendly_Person). Default Wise_Woman." },
+        engine: {
+          type: "string",
+          enum: [...ENGINES],
+          description: "Create step (optional): render every scene with one engine. omni-draft: fast, cheap motion preview. omni-final: full quality motion with sound. still-motion: one illustration per scene, gently panned, cheapest. Default: the style picks."
+        },
+        music: { type: "boolean", description: "Create step: add a music bed under the narration. Default true." },
+        title: { type: "string", description: "Create step (optional): episode title. Defaults to the topic." }
+      }
+    };
+    call = (id, action) => `pixeldojo_episode with {"episode_id": "${id}", "action": "${action}"}`;
+    next = (id, action, wait) => `Call ${call(id, action)} in ${wait}.`;
+    needsRender = (s) => s.render.status !== "running" && (s.render.status === "idle" || s.render.status === "failed" || Boolean(s.render.stale) || !s.render.url);
+    PLAN_POLL_MS = 3e3;
+    PLAN_MAX_POLLS = 8;
+    stillPlanning = (id) => `The script is still being written (episode_id: ${id}). Nothing has been charged. ${next(id, "status", "~30s")}`;
+    episodeSkill = {
+      name: "pixeldojo_episode",
+      description: "Make a finished narrated faceless video (explainer, history, kids story) from one topic: script, scene visuals, AI narration, music bed, stitched export saved to My Media. Phased: create is free and returns a credit quote; produce is charged and advances one step per call (poll every ~30s until it returns the video URL); status is free.",
+      inputZod: InputSchema10,
+      inputJsonSchema: InputJsonSchema10,
+      allowedModels: [],
+      defaultModel: "",
+      run: run10
+    };
+  }
+});
+async function run11(input, ctx) {
   const productImages = [
     ...input.product_image_urls ?? [],
     ...await Promise.all((input.product_image_paths ?? []).map((p) => uploadLocalFile(p, ctx)))
@@ -1671,13 +2305,13 @@ async function run9(input, ctx) {
     (urls) => urls.length === 0 ? `Ad job ${submitted.jobId} completed but returned no assets.` : `Ad rendered (style: ${styleLabel}${submitted.ad?.product?.name ? `, product: ${submitted.ad.product.name}` : ""}). Video: ${urls[0]}`
   );
 }
-var InputSchema9, InputJsonSchema9, adSkill;
+var InputSchema11, InputJsonSchema11, adSkill;
 var init_ad = __esm({
   "src/skills/ad.ts"() {
     init_types();
     init_poll();
     init_upload_helpers();
-    InputSchema9 = zod.z.object({
+    InputSchema11 = zod.z.object({
       style: zod.z.string().max(80).optional().describe(
         "Ad style slug (default ugc-testimonial). Catalog: GET /api/v1/marketing/presets \u2014 e.g. ugc-testimonial, unboxing-reveal, unboxing-asmr, virtual-try-on, street-style, product-showcase, macro-details, crush-test, hyper-motion, before-after, day-in-the-life, the-gift, tv-spot."
       ),
@@ -1703,7 +2337,7 @@ var init_ad = __esm({
         path: ["product_url"]
       }
     );
-    InputJsonSchema9 = {
+    InputJsonSchema11 = {
       type: "object",
       properties: {
         style: {
@@ -1790,16 +2424,16 @@ var init_ad = __esm({
       name: "pixeldojo_ad",
       description: "Marketing Studio: turn a product into a rendered video ad with voiceover. Requires `product_url` (name, description and images are extracted), or `product_name` plus product_image_urls / product_image_paths. Pick a `style` slug (default ugc-testimonial; full catalog at GET https://pixeldojo.ai/api/v1/marketing/presets), and optionally add presenter reference images, a location, a hook, and the exact spoken script. Returns the video URL, or a jobId to check with pixeldojo_status.",
       hostedDescription: "Marketing Studio: turn a product into a rendered video ad with voiceover. Requires `product_url` (name, description and images are extracted), or `product_name` plus product_image_urls (public http(s) URLs). Pick a `style` slug (default ugc-testimonial; full catalog at GET https://pixeldojo.ai/api/v1/marketing/presets), and optionally add presenter reference images, a location, a hook, and the exact spoken script. Returns the video URL, or a jobId to check with pixeldojo_status.",
-      inputZod: InputSchema9,
-      inputJsonSchema: InputJsonSchema9,
+      inputZod: InputSchema11,
+      inputJsonSchema: InputJsonSchema11,
       // Composition skill — the server routes to the ad engine internally.
       allowedModels: [],
       defaultModel: "",
-      run: run9
+      run: run11
     };
   }
 });
-async function run10(input, ctx) {
+async function run12(input, ctx) {
   const client = ctx.client;
   const result = await client.runCampaign(input);
   if (result.kind === "campaign") {
@@ -1826,10 +2460,10 @@ async function run10(input, ctx) {
     statusUrl: result.statusUrl ?? ctx.buildStatusUrl(result.campaignId)
   };
 }
-var InputSchema10, InputJsonSchema10, campaignSkill;
+var InputSchema12, InputJsonSchema12, campaignSkill;
 var init_campaign = __esm({
   "src/skills/campaign.ts"() {
-    InputSchema10 = zod.z.object({
+    InputSchema12 = zod.z.object({
       productUrl: zod.z.string().url().optional().describe("Product page URL. We extract name + description + images automatically."),
       product: zod.z.object({
         name: zod.z.string().min(1).max(200),
@@ -1845,7 +2479,7 @@ var init_campaign = __esm({
       message: "productUrl or product is required",
       path: ["productUrl"]
     });
-    InputJsonSchema10 = {
+    InputJsonSchema12 = {
       type: "object",
       properties: {
         productUrl: {
@@ -1896,17 +2530,17 @@ var init_campaign = __esm({
     campaignSkill = {
       name: "pixeldojo_campaign",
       description: "Generate a coherent product launch package (hero image + N lifestyle variants + optional vertical video) from one URL or product profile. Composes hero / lifestyle / video models server-side; returns assets in one call or a handoff with campaignId to poll via pixeldojo_campaign_status.",
-      inputZod: InputSchema10,
-      inputJsonSchema: InputJsonSchema10,
+      inputZod: InputSchema12,
+      inputJsonSchema: InputJsonSchema12,
       // Composition skill — internal sub-jobs route to per-tool models, no
       // single allowed-models list applies here.
       allowedModels: [],
       defaultModel: "",
-      run: run10
+      run: run12
     };
   }
 });
-async function run11(input, ctx) {
+async function run13(input, ctx) {
   const client = ctx.client;
   const result = await client.getCampaign(input.campaignId);
   if (result.kind === "campaign") {
@@ -1936,13 +2570,13 @@ async function run11(input, ctx) {
     statusUrl: result.statusUrl ?? ctx.buildStatusUrl(result.campaignId)
   };
 }
-var InputSchema11, InputJsonSchema11, campaignStatusSkill;
+var InputSchema13, InputJsonSchema13, campaignStatusSkill;
 var init_campaign_status = __esm({
   "src/skills/campaign-status.ts"() {
-    InputSchema11 = zod.z.object({
+    InputSchema13 = zod.z.object({
       campaignId: zod.z.string().min(1).max(200).describe("Campaign id returned from a prior pixeldojo_campaign handoff.")
     });
-    InputJsonSchema11 = {
+    InputJsonSchema13 = {
       type: "object",
       properties: {
         campaignId: {
@@ -1955,15 +2589,15 @@ var init_campaign_status = __esm({
     campaignStatusSkill = {
       name: "pixeldojo_campaign_status",
       description: "Poll a campaign by campaignId returned from pixeldojo_campaign. Returns assets when every sub-job is done, or a handoff describing what is still in flight.",
-      inputZod: InputSchema11,
-      inputJsonSchema: InputJsonSchema11,
+      inputZod: InputSchema13,
+      inputJsonSchema: InputJsonSchema13,
       allowedModels: [],
       defaultModel: "",
-      run: run11
+      run: run13
     };
   }
 });
-async function run12(input, ctx) {
+async function run14(input, ctx) {
   let url;
   try {
     url = await uploadLocalFile(input.path, ctx);
@@ -1976,40 +2610,40 @@ async function run12(input, ctx) {
   return {
     kind: "text",
     text: `Uploaded ${path.basename(input.path)} \u2192 ${url}
-(temp storage; auto-deletes in ~24h. Pass this URL as image_url, or video_url for a clip, to any pixeldojo tool that takes one.)`
+(temp storage; auto-deletes in ~24h. Pass this URL as image_url, video_url for a clip, or song_url on pixeldojo_film for a song, to any pixeldojo tool that takes one.)`
   };
 }
-var InputSchema12, InputJsonSchema12, uploadSkill;
+var InputSchema14, InputJsonSchema14, uploadSkill;
 var init_upload = __esm({
   "src/skills/upload.ts"() {
     init_upload_helpers();
-    InputSchema12 = zod.z.object({
+    InputSchema14 = zod.z.object({
       path: zod.z.string().min(1).max(4096).describe(
-        "Absolute local file path to upload. JPEG, PNG, WebP, GIF (\u226450MB) or MP4, WebM, MOV (\u2264200MB). Returns a public URL on the temp CDN; storage auto-expires after 24 hours."
+        "Absolute local file path to upload. JPEG, PNG, WebP, GIF (\u226450MB), MP4, WebM, MOV (\u2264200MB) or MP3, WAV, M4A, AAC, OGG, FLAC audio (\u226450MB). Returns a public URL on the temp CDN; storage auto-expires after 24 hours."
       )
     });
-    InputJsonSchema12 = {
+    InputJsonSchema14 = {
       type: "object",
       properties: {
         path: {
           type: "string",
-          description: "Absolute local file path. Allowed: JPEG, PNG, WebP, GIF (\u226450MB) or MP4, WebM, MOV (\u2264200MB). Returns a public URL on the temp CDN; auto-expires after 24h."
+          description: "Absolute local file path. Allowed: JPEG, PNG, WebP, GIF (\u226450MB), MP4, WebM, MOV (\u2264200MB) or MP3, WAV, M4A, AAC, OGG, FLAC audio (\u226450MB). Returns a public URL on the temp CDN; auto-expires after 24h."
         }
       },
       required: ["path"]
     };
     uploadSkill = {
       name: "pixeldojo_upload",
-      description: "Upload a local image or video (JPEG, PNG, WebP, GIF up to 50MB; MP4, WebM, MOV up to 200MB) and get back a public URL that expires after 24 hours. Free. Audio files are not accepted. Pass the URL as image_url (stills) or video_url (clips) to tools that take hosted URLs only, such as pixeldojo_character, pixeldojo_storyboard and pixeldojo_upscale. pixeldojo_generate, pixeldojo_edit and pixeldojo_ad take local paths directly and need no separate upload.",
-      inputZod: InputSchema12,
-      inputJsonSchema: InputJsonSchema12,
+      description: "Upload a local image, video or audio file (JPEG, PNG, WebP, GIF up to 50MB; MP4, WebM, MOV up to 200MB; MP3, WAV, M4A, AAC, OGG, FLAC up to 50MB) and get back a public URL that expires after 24 hours. Free. Pass an audio URL as song_url to pixeldojo_film for a music video. Pass the URL as image_url (stills) or video_url (clips) to tools that take hosted URLs only, such as pixeldojo_character, pixeldojo_storyboard and pixeldojo_upscale. pixeldojo_generate, pixeldojo_edit and pixeldojo_ad take local paths directly and need no separate upload.",
+      inputZod: InputSchema14,
+      inputJsonSchema: InputJsonSchema14,
       allowedModels: [],
       defaultModel: "",
-      run: run12
+      run: run14
     };
   }
 });
-async function run13(input, ctx) {
+async function run15(input, ctx) {
   const requested = input.model ?? DEFAULT_MODEL6;
   if (!ALLOWED4.includes(requested)) {
     return {
@@ -2047,14 +2681,14 @@ async function run13(input, ctx) {
     (urls) => urls.length === 0 ? `Job ${submitted.jobId} completed but returned no assets.` : `Audio ready. Asset: ${urls[0]}`
   );
 }
-var ALLOWED4, DEFAULT_MODEL6, InputSchema13, InputJsonSchema13, audioSkill;
+var ALLOWED4, DEFAULT_MODEL6, InputSchema15, InputJsonSchema15, audioSkill;
 var init_audio = __esm({
   "src/skills/audio.ts"() {
     init_poll();
     init_types();
     ALLOWED4 = ["seed-audio", "text-to-speech"];
     DEFAULT_MODEL6 = "seed-audio";
-    InputSchema13 = zod.z.object({
+    InputSchema15 = zod.z.object({
       prompt: zod.z.string().min(1).describe(
         "seed-audio: a script to speak, or a scene description (dialogue, sound effects, music), up to 2048 characters; refer to audio_urls clips in order as @Audio1..@Audio3. text-to-speech: the exact text to speak, up to 10,000 characters."
       ),
@@ -2064,7 +2698,7 @@ var init_audio = __esm({
       output_format: zod.z.string().optional().describe("Output format. seed-audio: mp3 (default), wav, pcm, ogg_opus. text-to-speech: mp3 (default), wav, flac, pcm."),
       speed: zod.z.number().min(0.5).max(2).optional().describe("Speech speed multiplier, 0.5-2 (default 1). Both models.")
     });
-    InputJsonSchema13 = {
+    InputJsonSchema15 = {
       type: "object",
       properties: {
         prompt: {
@@ -2102,15 +2736,15 @@ var init_audio = __esm({
     audioSkill = {
       name: "pixeldojo_audio",
       description: "Generate audio: speech, multi-character dialogue, sound effects, and background music from one prompt (Seed Audio 1.0 by default; plain text-to-speech available). Voice cloning takes hosted reference clip URLs in audio_urls; local audio files are not accepted. Returns an audio URL, or a jobId for pixeldojo_status.",
-      inputZod: InputSchema13,
-      inputJsonSchema: InputJsonSchema13,
+      inputZod: InputSchema15,
+      inputJsonSchema: InputJsonSchema15,
       allowedModels: [...ALLOWED4],
       defaultModel: DEFAULT_MODEL6,
-      run: run13
+      run: run15
     };
   }
 });
-async function run14(input, ctx) {
+async function run16(input, ctx) {
   const res = await ctx.client.listLibrary({
     q: input.q,
     model: input.model,
@@ -2141,16 +2775,16 @@ ${lines.join("\n")}
 Pass any URL back into pixeldojo_generate, pixeldojo_edit, pixeldojo_character, or pixeldojo_upscale as a reference input.`
   };
 }
-var InputSchema14, InputJsonSchema14, librarySkill;
+var InputSchema16, InputJsonSchema16, librarySkill;
 var init_library = __esm({
   "src/skills/library.ts"() {
-    InputSchema14 = zod.z.object({
+    InputSchema16 = zod.z.object({
       q: zod.z.string().optional().describe("Substring match against the prompt that produced the asset."),
       model: zod.z.string().optional().describe("Restrict to a single model (apiId)."),
       modality: zod.z.enum(["image", "video", "audio"]).optional().describe("Restrict to one output type."),
       limit: zod.z.number().int().min(1).max(50).optional().describe("Max results (default 10).")
     });
-    InputJsonSchema14 = {
+    InputJsonSchema16 = {
       type: "object",
       properties: {
         q: {
@@ -2170,11 +2804,11 @@ var init_library = __esm({
     librarySkill = {
       name: "pixeldojo_library",
       description: "Search your media library: saved My Media items (permanent) and recent API/MCP generations (deleted 1 hour after they finish), newest first. Returns asset URLs to reuse as reference inputs.",
-      inputZod: InputSchema14,
-      inputJsonSchema: InputJsonSchema14,
+      inputZod: InputSchema16,
+      inputJsonSchema: InputJsonSchema16,
       allowedModels: [],
       defaultModel: "",
-      run: run14
+      run: run16
     };
   }
 });
@@ -2424,6 +3058,7 @@ __export(skills_exports, {
   campaignStatusSkill: () => campaignStatusSkill,
   characterSkill: () => characterSkill,
   editSkill: () => editSkill,
+  episodeSkill: () => episodeSkill,
   filmSkill: () => filmSkill,
   findHostedSkill: () => findHostedSkill,
   findSkill: () => findSkill,
@@ -2436,7 +3071,8 @@ __export(skills_exports, {
   statusSkill: () => statusSkill,
   storyboardSkill: () => storyboardSkill,
   uploadSkill: () => uploadSkill,
-  upscaleSkill: () => upscaleSkill
+  upscaleSkill: () => upscaleSkill,
+  videoSkill: () => videoSkill
 });
 function findHostedSkill(name) {
   const wanted = name.replace(/^pixeldojo:/, "pixeldojo_");
@@ -2457,6 +3093,8 @@ var init_skills = __esm({
     init_status();
     init_from_url();
     init_film();
+    init_video();
+    init_episode();
     init_ad();
     init_campaign();
     init_campaign_status();
@@ -2481,7 +3119,9 @@ var init_skills = __esm({
       adSkill,
       campaignSkill,
       campaignStatusSkill,
-      filmSkill
+      filmSkill,
+      videoSkill,
+      episodeSkill
     ];
     isLocalPathField = (key) => /_paths?$/.test(key);
     HOSTED_SKILLS = ALL_SKILLS.filter(
@@ -2550,7 +3190,7 @@ function makeRedactedLogger(target = console) {
 }
 
 // src/server.ts
-var PACKAGE_VERSION = "0.14.0" ;
+var PACKAGE_VERSION = "0.15.1" ;
 var SERVER_INSTRUCTIONS = "PixelDojo generates images, video, audio and short films across 100+ models, billed in credits from the connected PixelDojo account. A job that runs past the 30-second wait returns a jobId to check later; check it rather than submitting again, since every new submission is charged. Generated asset URLs are deleted one hour after they are created, so download anything the user wants to keep. Finished films are the exception and stay in the account library.";
 function buildServer(options) {
   if (!options.apiKey) {