@lightcone-ai/daemon 0.17.1 → 0.18.1

package/mcp-servers/official/media-tools/index.js

@@ -6,13 +6,17 @@ import { z } from 'zod';
 import { addTitleEffects } from './lib/render.js';
 import { SUPPORTED_PRESETS } from './lib/presets.js';
 import { runSynthesisTtsTool } from '../../../src/tools/synthesize-tts.js';
+import { runListTtsVoicesTool } from '../../../src/tools/list-tts-voices.js';
+import { runPreviewTtsVoiceTool } from '../../../src/tools/preview-tts-voice.js';
+import { runGetDefaultVoiceTool } from '../../../src/tools/get-default-voice.js';
+import { runSetDefaultVoiceTool } from '../../../src/tools/set-default-voice.js';
 import { runPlanVideoSegmentsTool } from '../../../src/tools/plan-video-segments.js';
 import { runComposeVideoV2Tool } from '../../../src/tools/compose-video-v2.js';
 import { runRecordUrlNarrationTool } from '../../../src/tools/record-url-narration.js';
 import { runRenderTextToImageTool } from '../../../src/tools/render-text-to-image.js';
 import { runRenderHtmlToImageTool } from '../../../src/tools/render-html-to-image.js';
 import { runTakePageScreenshotTool } from '../../../src/tools/take-page-screenshot.js';
-import { hasFreshVideoBrief } from '../../../src/video-brief-flag.js';
+import { hasVideoBriefSent } from '../../../src/video-brief-flag.js';
 import { lightconeApi, CURRENT_WORKSPACE_ID, CURRENT_AGENT_ID } from './lib/lightcone-api.js';
 
 const WORKSPACE_DIR = String(process.env.WORKSPACE_DIR ?? '');
@@ -129,7 +133,9 @@ server.tool(
   + 'into a single call (segment-level audio is required for plan_video_segments to align video durations).',
   {
     text: z.string().min(1).describe('Narration text for this segment. Will be synthesized as a single mp3.'),
-    voice_id: z.string().optional().describe('TTS voice preset. Omit to use workspace default.'),
+    voice_id: z.string().optional().describe('MiniMax voice_id (e.g. "Chinese (Mandarin)_Warm_Girl"). Omit to use the workspace default. '
+      + 'If neither is set the call fails with tts_default_voice_required — call list_tts_voices to discover options '
+      + 'and set_default_voice once the user picks one.'),
     workspace_id: z.string().optional().describe('Target workspace. Defaults to the current workspace.'),
   },
   async ({ text, voice_id, workspace_id }) => runSynthesisTtsTool({
@@ -141,6 +147,87 @@ server.tool(
   })
 );
 
+// ── TTS voice catalog + workspace preference (added in the voice-selection
+// rebuild — see docs/scenario-content-creation/video-synthesis-design.md).
+// These four tools let the agent discover MiniMax voices, sample them, and
+// persist a workspace-level default — all from inside the IM conversation,
+// no separate UI. There is no fallback default voice: synthesize_tts will
+// throw tts_default_voice_required if neither the request nor the workspace
+// has a voice_id set, which is the agent's cue to run this discovery flow.
+server.tool(
+  'list_tts_voices',
+  'List TTS voices available to the current workspace (system catalog + any cloned voices owned by this workspace). '
+  + 'Use this to show the user options before calling set_default_voice or synthesize_tts. '
+  + 'Filter by language (e.g. "zh-CN"), style_tag (e.g. "recommended", "news", "warm"), or free-text query.',
+  {
+    language: z.string().optional().describe('BCP-47 language tag, e.g. "zh-CN", "en-US".'),
+    origin: z.enum(['system', 'cloned']).optional().describe('Restrict to system catalog or this workspace\'s cloned voices.'),
+    query: z.string().optional().describe('Free-text match against voice_id and display_name.'),
+    style_tag: z.string().optional().describe('Match a single style tag (e.g. "recommended" for the curated shortlist).'),
+    limit: z.number().int().positive().max(200).optional().describe('Max rows to return. Default 100.'),
+    workspace_id: z.string().optional().describe('Target workspace. Defaults to the current workspace.'),
+  },
+  async ({ language, origin, query, style_tag, limit, workspace_id }) => runListTtsVoicesTool({
+    language,
+    origin,
+    query,
+    style_tag,
+    limit,
+    workspace_id,
+    currentWorkspaceId: CURRENT_WORKSPACE_ID,
+    api: lightconeApi,
+  })
+);
+
+server.tool(
+  'preview_tts_voice',
+  'Synthesize a short sample so the user can hear a voice before committing. Returns a playable mp3 path + audio_url. '
+  + 'Pass voice_id from list_tts_voices; text is optional (defaults to a neutral Chinese sample sentence).',
+  {
+    voice_id: z.string().min(1).describe('voice_id to preview, from list_tts_voices.'),
+    text: z.string().optional().describe('Custom sample text. Defaults to a short Chinese sentence.'),
+    workspace_id: z.string().optional().describe('Target workspace. Defaults to the current workspace.'),
+  },
+  async ({ voice_id, text, workspace_id }) => runPreviewTtsVoiceTool({
+    voice_id,
+    text,
+    workspace_id,
+    currentWorkspaceId: CURRENT_WORKSPACE_ID,
+    api: lightconeApi,
+  })
+);
+
+server.tool(
+  'get_default_voice',
+  'Read the current workspace\'s default TTS voice. Returns null when not set — that is the signal to run the discovery flow '
+  + '(list_tts_voices → user picks → set_default_voice) before doing any synthesis.',
+  {
+    workspace_id: z.string().optional().describe('Target workspace. Defaults to the current workspace.'),
+  },
+  async ({ workspace_id }) => runGetDefaultVoiceTool({
+    workspace_id,
+    currentWorkspaceId: CURRENT_WORKSPACE_ID,
+    api: lightconeApi,
+  })
+);
+
+server.tool(
+  'set_default_voice',
+  'Persist a workspace-level default TTS voice. The voice_id must exist in the workspace\'s visible catalog '
+  + '(system voice or a cloned voice owned by this workspace) — otherwise this tool fails with tts_voice_not_found. '
+  + 'Call this after the user picks from list_tts_voices, OR when the user explicitly asks to change their default.',
+  {
+    voice_id: z.string().min(1).describe('voice_id to make the default. Must be in this workspace\'s catalog.'),
+    workspace_id: z.string().optional().describe('Target workspace. Defaults to the current workspace.'),
+  },
+  async ({ voice_id, workspace_id }) => runSetDefaultVoiceTool({
+    voice_id,
+    workspace_id,
+    currentWorkspaceId: CURRENT_WORKSPACE_ID,
+    api: lightconeApi,
+  })
+);
+
 // ── plan_video_segments (migrated from chat-bridge; TTS decoupled) ────────
 // Pure planner — takes per-segment {text, audio_path, visual_kind, ...} and
 // returns segments with audio_duration_ms / presentation.duration / dwell_ms
@@ -187,10 +274,14 @@ server.tool(
   'compose_video_v2',
   'Compose a video from a list of segments using ffmpeg. Each segment has a visual source (image / scroll / '
   + 'carousel / video / gif), optional audio, and optional subtitle text. Subtitles are burned in when '
-  + 'subtitle_text is provided. Segments are concatenated in order; outro clips are appended after.\n\n'
+  + 'subtitle_text is provided AND burn_subtitles is not false. Segments are concatenated in order; outro clips are appended after.\n\n'
   + 'When any segment has audio_path, MUST be preceded by plan_video_segments in the same session '
   + '(plan_video_segments fills duration/subtitle_text/audio_path mechanically; manual alignment is rejected). '
-  + 'Returns a local mp4 path + size_bytes.',
+  + 'Returns a local mp4 path + size_bytes.\n\n'
+  + 'Dual / multi-version delivery (e.g. subtitled+voiced + clean silent): pass the variants[] array — one call '
+  + 'runs the heavy per-segment ffmpeg work ONCE and only diverges at audio mux + concat + subtitle burn per '
+  + 'variant. That is ~1.2-1.4× single-version time vs ~2× when calling this tool twice. Each variant chooses '
+  + 'its own burn_subtitles and include_audio independently.',
   {
     segments: z.array(z.object({
       visual_path: z.string().optional().describe('Absolute path to a single image / video / gif.'),
@@ -207,7 +298,18 @@ server.tool(
     })).describe('Ordered list of video segments.'),
     outro_paths: z.array(z.string()).optional().describe('Absolute paths to outro video clips appended at end.'),
     resolution: z.string().optional().describe('Output resolution WxH. Default "1080x1920".'),
-    output_path: z.string().optional().describe('Absolute output path. Auto-generated if omitted.'),
+    output_path: z.string().optional().describe('Absolute output path (single-output mode). Auto-generated if omitted. Ignored when variants[] is provided.'),
+    burn_subtitles: z.boolean().optional().describe('Single-output mode only: whether to burn subtitle_text. Default true. '
+      + 'For producing multiple variants in one call, use variants[] instead.'),
+    variants: z.array(z.object({
+      output_path: z.string().describe('Absolute output path for this variant. Each variant must use a unique path.'),
+      burn_subtitles: z.boolean().optional().describe('Whether to burn subtitle_text into THIS variant. Default true.'),
+      include_audio: z.boolean().optional().describe('Whether to mux segment.audio_path into THIS variant. Default true. '
+        + 'Pass false for a fully silent copy (skips audio mux entirely; segment.audio_path is ignored for this variant).'),
+    })).optional().describe('Multi-output mode: one call produces all variants. '
+      + 'Visual segment processing (the heavy work) runs once; each variant only repeats audio mux + concat + optional subtitle burn. '
+      + 'Typical use: [{output_path:"with-sub.mp4"}, {output_path:"clean.mp4", burn_subtitles:false, include_audio:false}] '
+      + 'to deliver a subtitled+voiced version and a silent clean version together.'),
   },
   async (args) => {
     const segments = Array.isArray(args?.segments) ? args.segments : [];
@@ -223,13 +325,13 @@ server.tool(
         + 'visual_path/visual_kind for the real media). Call plan_video_segments now and pass its output here.'
       );
     }
-    if (hasNarration && !hasFreshVideoBrief({ workspaceId: CURRENT_WORKSPACE_ID, agentId: CURRENT_AGENT_ID })) {
+    if (hasNarration && !hasVideoBriefSent({ workspaceId: CURRENT_WORKSPACE_ID, agentId: CURRENT_AGENT_ID })) {
       return toolError(
         'compose_video_v2 refused: must send a 确认稿 (production-brief) to the user via send_message before '
         + 'compositing a narration video. The system scans send_message content for a brief — a message that '
         + 'BOTH asks the user to confirm (确认 / 你看 / OK 吗 / 可以吗 / 同意 / 通过 / 行不行) AND describes '
         + 'at least two of: 画面 / 时长 / 文案 / 口播 / 字幕 / 顺序 / 口吻 / 分镜 / 配音 — no such message '
-        + 'was sent in the last 6 hours for this workspace+agent.\n\n'
+        + 'has been sent in this workspace+agent.\n\n'
         + '"已生成 TTS" / "开始合成" / progress reports do NOT count. Send a concrete confirmation draft '
         + 'first (e.g. "我准备这么做：画面是真录屏，时长约 1 分钟，文案如下…，字幕开启，公司顺序 A→B→C，'
         + '口吻是…—— 你 OK 吗？") and wait for the user to reply OK before calling compose_video_v2 again.'
@@ -282,7 +384,7 @@ server.tool(
     // with synthesize_tts + plan_video_segments + compose_video_v2), so it
     // requires the same 确认稿 gate as compose_video_v2 — catching the skip
     // earlier saves TTS + recording time.
-    if (!hasFreshVideoBrief({ workspaceId: CURRENT_WORKSPACE_ID, agentId: CURRENT_AGENT_ID })) {
+    if (!hasVideoBriefSent({ workspaceId: CURRENT_WORKSPACE_ID, agentId: CURRENT_AGENT_ID })) {
       return {
         isError: true,
         content: [{ type: 'text', text:
@@ -290,7 +392,7 @@ server.tool(
           + 'send_message before starting a narration recording. The system scans send_message content for '
           + 'a brief — a message that BOTH asks the user to confirm (确认 / 你看 / OK 吗 / 可以吗 / 同意 / '
           + '通过 / 行不行) AND describes at least two of: 画面 / 时长 / 文案 / 口播 / 字幕 / 顺序 / 口吻 / '
-          + '分镜 / 配音 — no such message was sent in the last 6 hours for this workspace+agent.\n\n'
+          + '分镜 / 配音 — no such message has been sent in this workspace+agent.\n\n'
           + '"已生成 TTS" / "开始合成" / progress reports do NOT count. Send a concrete confirmation draft '
           + 'first (e.g. "我准备这么做：画面是真录屏，时长约 1 分钟，文案如下…，字幕开启，公司顺序 A→B→C，'
           + '口吻是…—— 你 OK 吗？") and wait for the user to reply OK before calling record_url_narration.'

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lightcone-ai/daemon",
-  "version": "0.17.1",
+  "version": "0.18.1",
   "type": "module",
   "main": "src/index.js",
   "bin": {

package/src/_vendor/video/composer-v2/index.js

@@ -249,16 +249,64 @@ async function applyFadeTransition({ clipA, clipB, tmpDir, style = 'fade' }) {
   return outPath;
 }
 
+// compose_video_v2 supports two modes:
+//
+//   1. Legacy single-output: pass output_path (+ optional burn_subtitles).
+//      Returns { path, duration_ms, size_bytes, variants: [..1 entry..] }.
+//
+//   2. Multi-variant: pass variants=[{output_path, burn_subtitles?, include_audio?}, ...].
+//      Visual segment processing runs ONCE (the heavy part — per-segment ffmpeg
+//      transcode/scale/scroll). Each variant then diverges only at audio mux +
+//      concat + subtitle burn — typically a few seconds per extra variant.
+//      Returns { variants: [{path, duration_ms, size_bytes, burn_subtitles,
+//      include_audio}, ...] }.
+//
+// Use the multi-variant mode when shipping the same content with different
+// subtitle/audio combinations (e.g. subtitled+voiced + clean silent). Calling
+// the legacy mode twice produces correct outputs but redoes per-segment work.
 export async function composeVideoV2({
   segments = [],
   outro_paths = [],
   resolution = '1080x1920',
   output_path,
+  burn_subtitles = true,
+  variants,
 }) {
   if (!Array.isArray(segments) || segments.length === 0) {
     throw new Error('segments must be a non-empty array');
   }
 
+  // Normalize variants. If caller did not pass an explicit variants array,
+  // synthesize a single variant from the legacy output_path + burn_subtitles.
+  // include_audio defaults to true (auto-include any segment.audio_path).
+  const normalizedVariants = (Array.isArray(variants) && variants.length > 0)
+    ? variants.map((v, idx) => {
+        if (!v || typeof v !== 'object') {
+          throw new Error(`variants[${idx}]: must be an object`);
+        }
+        const outPath = String(v.output_path ?? '').trim();
+        if (!outPath) throw new Error(`variants[${idx}]: output_path is required`);
+        return {
+          output_path: outPath,
+          burn_subtitles: v.burn_subtitles !== false,
+          include_audio: v.include_audio !== false,
+        };
+      })
+    : [{
+        output_path: output_path ?? path.join(os.tmpdir(), `lightcone-video-${Date.now()}.mp4`),
+        burn_subtitles: burn_subtitles !== false,
+        include_audio: true,
+      }];
+
+  // Disallow two variants writing to the same file — would race on disk.
+  const seenOutputs = new Set();
+  for (const v of normalizedVariants) {
+    if (seenOutputs.has(v.output_path)) {
+      throw new Error(`variants share output_path "${v.output_path}" — each variant needs a unique destination`);
+    }
+    seenOutputs.add(v.output_path);
+  }
+
   const [widthStr, heightStr] = String(resolution).split('x');
   const width = parseInt(widthStr, 10) || DEFAULT_WIDTH;
   const height = parseInt(heightStr, 10) || DEFAULT_HEIGHT;
@@ -267,23 +315,19 @@ export async function composeVideoV2({
   const tmpDir = path.join(os.tmpdir(), `compose-v2-${randomUUID().slice(0, 8)}`);
   await mkdir(tmpDir, { recursive: true });
 
-  const outPath = output_path ?? path.join(os.tmpdir(), `lightcone-video-${Date.now()}.mp4`);
-  await mkdir(path.dirname(outPath), { recursive: true });
-
   try {
-    const readyClips = [];
-
+    // ── Shared phase: generate visual clips per segment ONCE ──────────────────
+    // This is the heavy work (image scaling, scroll rendering, video resize +
+    // re-encode). Reused across every variant.
+    const visualClips = [];
     for (let i = 0; i < segments.length; i++) {
       const seg = segments[i];
       const kind = String(seg.visual_kind ?? 'image');
       const presentation = seg.presentation ?? {};
       const style = String(presentation.style ?? 'static');
       const duration = Number(presentation.duration ?? presentation.per_card_duration ?? 4);
-      const audioPath = seg.audio_path ?? null;
-      const transition = String(seg.transition ?? 'cut');
 
       let visualClip;
-
       if (kind === 'image') {
         const imgPath = String(seg.visual_path ?? '');
         if (!imgPath) throw new Error(`segments[${i}]: visual_path required for kind=image`);
@@ -311,114 +355,145 @@ export async function composeVideoV2({
       } else {
         throw new Error(`segments[${i}]: unknown visual_kind "${kind}"`);
       }
-
-      let finalClip;
-      if (audioPath && await fileExists(audioPath)) {
-        finalClip = await muxAudio({ videoPath: visualClip.path, audioPath, duration: visualClip.duration, tmpDir });
-      } else {
-        finalClip = await silentClip({ videoPath: visualClip.path, duration: visualClip.duration, tmpDir });
-      }
-
-      // Accept `text` as an alias for `subtitle_text`: plan_video_segments takes
-      // segment narration as `text` on input, compose_video_v2's canonical name is
-      // `subtitle_text`. Either reaches the burn pass so subtitles aren't silently dropped.
-      const subtitleText = (
-        typeof seg.subtitle_text === 'string' ? seg.subtitle_text
-        : typeof seg.text === 'string' ? seg.text
-        : ''
-      ).trim();
-      readyClips.push({ path: finalClip, duration: visualClip.duration, transition, subtitleText });
+      visualClips.push(visualClip);
     }
 
-    const outroClips = [];
+    // Outros are also shared — they don't depend on subtitle/audio choices.
+    const outroClipPaths = [];
     for (const outroPath of (outro_paths ?? [])) {
       if (outroPath && await fileExists(outroPath)) {
         const c = await videoToClip({ videoPath: outroPath, tmpDir, width, height, fps });
-        outroClips.push(c.path);
+        outroClipPaths.push(c.path);
       }
     }
 
-    // Build subtitle entries with cumulative timeline timestamps. When a clip's
-    // subtitle text spans several sentences, split it into one event per sentence
-    // and spread them across the clip in proportion to their length, so a long
-    // beat reads as sequential lines roughly tracking the narration instead of one
-    // static wall of text.
-    let cursorMs = 0;
-    const subtitleEntries = [];
-    for (const clip of readyClips) {
-      if (clip.subtitleText) {
-        const clipMs = Math.round(clip.duration * 1000);
-        const sentences = splitSubtitleSentences(clip.subtitleText);
-        const totalLen = sentences.reduce((sum, s) => sum + Array.from(s).length, 0) || 1;
-        let offsetMs = 0;
-        sentences.forEach((sentence, idx) => {
-          const share = Array.from(sentence).length / totalLen;
-          const isLast = idx === sentences.length - 1;
-          const spanMs = isLast ? clipMs - offsetMs : Math.max(1, Math.round(clipMs * share));
-          subtitleEntries.push({
-            text: sentence,
-            start_ms: cursorMs + offsetMs,
-            end_ms: cursorMs + offsetMs + spanMs,
+    // ── Per-variant phase ─────────────────────────────────────────────────────
+    // For each variant: mux audio (or silent), build subtitle text, concat with
+    // transitions, optionally burn subtitles. Writes to variant.output_path.
+    const variantOutputs = [];
+    for (let vi = 0; vi < normalizedVariants.length; vi++) {
+      const variant = normalizedVariants[vi];
+      await mkdir(path.dirname(variant.output_path), { recursive: true });
+
+      const variantTag = `v${vi}`;
+      const readyClips = [];
+
+      for (let i = 0; i < segments.length; i++) {
+        const seg = segments[i];
+        const visualClip = visualClips[i];
+        const transition = String(seg.transition ?? 'cut');
+        const audioPath = variant.include_audio ? (seg.audio_path ?? null) : null;
+
+        let finalClip;
+        if (audioPath && await fileExists(audioPath)) {
+          finalClip = await muxAudio({ videoPath: visualClip.path, audioPath, duration: visualClip.duration, tmpDir });
+        } else {
+          finalClip = await silentClip({ videoPath: visualClip.path, duration: visualClip.duration, tmpDir });
+        }
+
+        // Accept `text` as an alias for `subtitle_text`: plan_video_segments takes
+        // segment narration as `text` on input, compose_video_v2's canonical name is
+        // `subtitle_text`. burn_subtitles=false drops the text here so the burn-in
+        // pass skips entirely.
+        const subtitleText = variant.burn_subtitles
+          ? (
+              typeof seg.subtitle_text === 'string' ? seg.subtitle_text
+              : typeof seg.text === 'string' ? seg.text
+              : ''
+            ).trim()
+          : '';
+        readyClips.push({ path: finalClip, duration: visualClip.duration, transition, subtitleText });
+      }
+
+      // Subtitle entries: cumulative timeline timestamps. Same logic as before,
+      // scoped per variant (subtitleText is already gated by variant.burn_subtitles).
+      let cursorMs = 0;
+      const subtitleEntries = [];
+      for (const clip of readyClips) {
+        if (clip.subtitleText) {
+          const clipMs = Math.round(clip.duration * 1000);
+          const sentences = splitSubtitleSentences(clip.subtitleText);
+          const totalLen = sentences.reduce((sum, s) => sum + Array.from(s).length, 0) || 1;
+          let offsetMs = 0;
+          sentences.forEach((sentence, idx) => {
+            const share = Array.from(sentence).length / totalLen;
+            const isLast = idx === sentences.length - 1;
+            const spanMs = isLast ? clipMs - offsetMs : Math.max(1, Math.round(clipMs * share));
+            subtitleEntries.push({
+              text: sentence,
+              start_ms: cursorMs + offsetMs,
+              end_ms: cursorMs + offsetMs + spanMs,
+            });
+            offsetMs += spanMs;
           });
-          offsetMs += spanMs;
-        });
+        }
+        cursorMs += Math.round(clip.duration * 1000);
       }
-      cursorMs += Math.round(clip.duration * 1000);
-    }
 
-    const allClips = [];
-    let accumulated = readyClips[0].path;
-    for (let i = 1; i < readyClips.length; i++) {
-      const { path: nextClip, transition } = readyClips[i];
-      if (transition === 'fade' || transition === 'crossfade') {
-        accumulated = await applyFadeTransition({ clipA: accumulated, clipB: nextClip, tmpDir, style: transition });
-      } else {
-        allClips.push(accumulated);
-        accumulated = nextClip;
+      const allClips = [];
+      let accumulated = readyClips[0].path;
+      for (let i = 1; i < readyClips.length; i++) {
+        const { path: nextClip, transition } = readyClips[i];
+        if (transition === 'fade' || transition === 'crossfade') {
+          accumulated = await applyFadeTransition({ clipA: accumulated, clipB: nextClip, tmpDir, style: transition });
+        } else {
+          allClips.push(accumulated);
+          accumulated = nextClip;
+        }
       }
-    }
-    allClips.push(accumulated);
+      allClips.push(accumulated);
 
-    const finalSequence = [...allClips, ...outroClips];
+      const finalSequence = [...allClips, ...outroClipPaths];
 
-    // Compose without subtitles first (subtitles are burned in a separate pass)
-    const preSubPath = subtitleEntries.length > 0
-      ? path.join(tmpDir, `pre-sub-${randomUUID().slice(0, 8)}.mp4`)
-      : outPath;
+      // Compose without subtitles first (subtitles are burned in a separate pass)
+      const preSubPath = subtitleEntries.length > 0
+        ? path.join(tmpDir, `${variantTag}-pre-sub-${randomUUID().slice(0, 8)}.mp4`)
+        : variant.output_path;
 
-    if (finalSequence.length === 1) {
-      await runFfmpeg(['-i', finalSequence[0], '-c', 'copy', '-movflags', '+faststart', preSubPath], 'ffmpeg copy');
-    } else {
-      await concatWithCuts({ clips: finalSequence, outputPath: preSubPath });
-    }
+      if (finalSequence.length === 1) {
+        await runFfmpeg(['-i', finalSequence[0], '-c', 'copy', '-movflags', '+faststart', preSubPath], `ffmpeg copy ${variantTag}`);
+      } else {
+        await concatWithCuts({ clips: finalSequence, outputPath: preSubPath });
+      }
 
-    // Burn subtitles into final output
-    if (subtitleEntries.length > 0) {
-      const assPath = path.join(tmpDir, `subs-${randomUUID().slice(0, 8)}.ass`);
-      await writeFile(assPath, buildAssContent(subtitleEntries, { playResX: width, playResY: height }));
-      const escapedAssPath = assPath.replace(/\\/g, '/').replace(/:/g, '\\:').replace(/'/g, "\\'");
-      await runFfmpeg([
-        '-i', preSubPath,
-        '-vf', `subtitles='${escapedAssPath}'`,
-        '-c:a', 'copy',
-        '-movflags', '+faststart',
-        outPath,
-      ], 'ffmpeg burn-subtitles');
-    }
+      if (subtitleEntries.length > 0) {
+        const assPath = path.join(tmpDir, `${variantTag}-subs-${randomUUID().slice(0, 8)}.ass`);
+        await writeFile(assPath, buildAssContent(subtitleEntries, { playResX: width, playResY: height }));
+        const escapedAssPath = assPath.replace(/\\/g, '/').replace(/:/g, '\\:').replace(/'/g, "\\'");
+        await runFfmpeg([
+          '-i', preSubPath,
+          '-vf', `subtitles='${escapedAssPath}'`,
+          '-c:a', 'copy',
+          '-movflags', '+faststart',
+          variant.output_path,
+        ], `ffmpeg burn-subtitles ${variantTag}`);
+      }
 
-    const totalDuration = await probeDurationSec(outPath);
-
-    // Stat the final file before returning so the caller can rely on size and
-    // so we can detect the (rare but observed) case where ffmpeg's `close`
-    // arrived but the kernel writeback wasn't complete. A 0-byte / tiny mp4
-    // here means the burn-subtitles pass produced nothing usable — fail loudly
-    // instead of letting a broken file flow into write_workspace_file / submit.
-    const finalStat = await statAsync(outPath);
-    const sizeBytes = Number(finalStat.size ?? 0);
-    if (!Number.isFinite(sizeBytes) || sizeBytes < 1024) {
-      throw new Error(`compose_video_v2 produced an invalid output: ${outPath} size=${sizeBytes} bytes`);
+      const totalDuration = await probeDurationSec(variant.output_path);
+      const finalStat = await statAsync(variant.output_path);
+      const sizeBytes = Number(finalStat.size ?? 0);
+      if (!Number.isFinite(sizeBytes) || sizeBytes < 1024) {
+        throw new Error(`compose_video_v2 produced an invalid output: ${variant.output_path} size=${sizeBytes} bytes (variant ${vi})`);
+      }
+
+      variantOutputs.push({
+        path: variant.output_path,
+        duration_ms: Math.round(totalDuration * 1000),
+        size_bytes: sizeBytes,
+        burn_subtitles: variant.burn_subtitles,
+        include_audio: variant.include_audio,
+      });
     }
-    return { path: outPath, duration_ms: Math.round(totalDuration * 1000), size_bytes: sizeBytes };
+
+    // Legacy single-output callers (didn't pass variants) get the same flat
+    // shape they used to get, plus the variants array for forward-compat.
+    const first = variantOutputs[0];
+    return {
+      path: first.path,
+      duration_ms: first.duration_ms,
+      size_bytes: first.size_bytes,
+      variants: variantOutputs,
+    };
   } finally {
     await rm(tmpDir, { recursive: true, force: true });
   }

package/src/tools/compose-video-v2.js

@@ -22,7 +22,16 @@ function statSizeOrNull(p) {
   try { return fs.statSync(p).size; } catch { return null; }
 }
 
-export async function runComposeVideoV2Tool({ segments, outro_paths, format, resolution, output_path, workspaceDir }) {
+export async function runComposeVideoV2Tool({
+  segments,
+  outro_paths,
+  format,
+  resolution,
+  output_path,
+  burn_subtitles,
+  variants,
+  workspaceDir,
+}) {
   if (!Array.isArray(segments) || segments.length === 0) {
     return toolError('segments must be a non-empty array.');
   }
@@ -59,6 +68,37 @@ export async function runComposeVideoV2Tool({ segments, outro_paths, format, res
       );
     }
   }
+
+  // Normalize variants. If caller passed a variants[] array, that takes
+  // priority — multi-output mode. Otherwise build a single-element variants
+  // array from the legacy output_path + burn_subtitles params.
+  const outDir = workspaceDir
+    ? path.join(workspaceDir, 'artifacts', 'video')
+    : path.join(os.tmpdir(), 'lightcone-video');
+
+  let normalizedVariants;
+  if (Array.isArray(variants) && variants.length > 0) {
+    normalizedVariants = variants.map((v, idx) => {
+      if (!v || typeof v !== 'object') {
+        return null; // surfaced below
+      }
+      const outPath = String(v.output_path ?? '').trim()
+        || path.join(outDir, `composed-${Date.now()}-${idx}-${randomUUID().slice(0, 8)}.mp4`);
+      return {
+        output_path: outPath,
+        burn_subtitles: v.burn_subtitles !== false,
+        include_audio: v.include_audio !== false,
+      };
+    });
+    if (normalizedVariants.some(v => v === null)) {
+      return toolError('variants must be an array of objects, each with { output_path, burn_subtitles?, include_audio? }.');
+    }
+  } else {
+    const burnSubtitles = burn_subtitles !== false;
+    const outPath = output_path ?? path.join(outDir, `composed-${Date.now()}-${randomUUID().slice(0, 8)}.mp4`);
+    normalizedVariants = [{ output_path: outPath, burn_subtitles: burnSubtitles, include_audio: true }];
+  }
+
   const warnings = [];
   // Heuristic warning: a multi-segment image video that reuses one single image
   // will look near-static — usually a sign the source page didn't render and the
@@ -69,44 +109,59 @@ export async function runComposeVideoV2Tool({ segments, outro_paths, format, res
       + 'The output will be near-static — verify the source page actually rendered before submitting this video.'
     );
   }
-  // Warn when narration is present but no subtitle text is — compose_video_v2 burns
-  // subtitles only from `subtitle_text` (or its `text` alias); without it the video
-  // ships with no captions. Simplest fix: pass plan_video_segments' output verbatim.
-  {
+  // Warn when narration is present but no subtitle text is — only meaningful
+  // for variants that ARE supposed to burn subtitles. Variants that explicitly
+  // ask for burn_subtitles=false are the "clean" path and shouldn't trigger it.
+  const variantsWithBurn = normalizedVariants.filter(v => v.burn_subtitles && v.include_audio);
+  if (variantsWithBurn.length > 0) {
     const hasSubText = s => (typeof s?.subtitle_text === 'string' && s.subtitle_text.trim())
       || (typeof s?.text === 'string' && s.text.trim());
     const narratedNoSub = segments.filter(s =>
       (typeof s?.audio_path === 'string' && s.audio_path.trim()) && !hasSubText(s)).length;
     if (narratedNoSub > 0) {
       warnings.push(
-        `WARNING: ${narratedNoSub} segment(s) have narration audio but no subtitle text — the output will have NO subtitles. `
+        `WARNING: ${narratedNoSub} segment(s) have narration audio but no subtitle text — `
+        + `the subtitled variant${variantsWithBurn.length > 1 ? 's' : ''} will have NO subtitles. `
         + 'If subtitles are wanted, set subtitle_text per segment (or pass the plan_video_segments output array verbatim).'
       );
     }
   }
 
-  const outDir = workspaceDir
-    ? path.join(workspaceDir, 'artifacts', 'video')
-    : path.join(os.tmpdir(), 'lightcone-video');
-
-  const outPath = output_path ?? path.join(outDir, `composed-${Date.now()}-${randomUUID().slice(0, 8)}.mp4`);
-
   try {
     const result = await composeVideoV2({
       segments,
       outro_paths: outro_paths ?? [],
       resolution: resolution ?? '1080x1920',
-      output_path: outPath,
+      variants: normalizedVariants,
     });
 
-    const lines = [
-      'compose_video_v2 completed.',
-      `path=${result.path}`,
-      `duration_ms=${result.duration_ms}`,
-      `size_bytes=${result.size_bytes ?? 'unknown'}`,
-      `segments=${segments.length}`,
-      `outro_clips=${(outro_paths ?? []).length}`,
-    ];
+    const outputs = Array.isArray(result?.variants) && result.variants.length > 0
+      ? result.variants
+      : [{ path: result.path, duration_ms: result.duration_ms, size_bytes: result.size_bytes,
+           burn_subtitles: normalizedVariants[0].burn_subtitles,
+           include_audio: normalizedVariants[0].include_audio }];
+
+    const lines = ['compose_video_v2 completed.'];
+    if (outputs.length === 1) {
+      const v = outputs[0];
+      lines.push(`path=${v.path}`);
+      lines.push(`duration_ms=${v.duration_ms}`);
+      lines.push(`size_bytes=${v.size_bytes ?? 'unknown'}`);
+      lines.push(`burn_subtitles=${v.burn_subtitles}`);
+      lines.push(`include_audio=${v.include_audio}`);
+    } else {
+      lines.push(`variants=${outputs.length}`);
+      outputs.forEach((v, idx) => {
+        lines.push(`--- variant ${idx} ---`);
+        lines.push(`path=${v.path}`);
+        lines.push(`duration_ms=${v.duration_ms}`);
+        lines.push(`size_bytes=${v.size_bytes ?? 'unknown'}`);
+        lines.push(`burn_subtitles=${v.burn_subtitles}`);
+        lines.push(`include_audio=${v.include_audio}`);
+      });
+    }
+    lines.push(`segments=${segments.length}`);
+    lines.push(`outro_clips=${(outro_paths ?? []).length}`);
     for (const w of warnings) lines.push(w);
     return toolText(lines.join('\n'));
   } catch (error) {

package/src/tools/get-default-voice.js

@@ -0,0 +1,48 @@
+function toolText(text) {
+  return { content: [{ type: 'text', text }] };
+}
+
+function toolError(text) {
+  return { isError: true, content: [{ type: 'text', text }] };
+}
+
+export async function runGetDefaultVoiceTool({
+  workspace_id,
+  currentWorkspaceId,
+  api,
+}) {
+  const targetWorkspaceId = String(workspace_id ?? currentWorkspaceId ?? '').trim();
+  if (!targetWorkspaceId) {
+    return toolError('workspace_id is required (no current workspace context).');
+  }
+
+  const params = new URLSearchParams({ workspace_id: targetWorkspaceId });
+
+  let data;
+  try {
+    data = await api('GET', `/tts/preferences?${params.toString()}`);
+  } catch (error) {
+    return toolError(`get_default_voice API error: ${error.message}`);
+  }
+
+  if (!data?.default_voice_id) {
+    return toolText('No default TTS voice set for this workspace. Call list_tts_voices to show the user options, then set_default_voice once they pick one.');
+  }
+
+  const v = data.voice;
+  const lines = [
+    `Default TTS voice for workspace=${data.workspace_id} (provider=${data.provider}):`,
+    `voice_id=${data.default_voice_id}`,
+  ];
+  if (v) {
+    lines.push(`display_name=${v.display_name}`);
+    if (v.language) lines.push(`language=${v.language}`);
+    if (v.gender) lines.push(`gender=${v.gender}`);
+    if (Array.isArray(v.style_tags) && v.style_tags.length) {
+      lines.push(`style_tags=${v.style_tags.join(', ')}`);
+    }
+  } else {
+    lines.push('(voice metadata not found — catalog may have changed; ask user to pick again)');
+  }
+  return toolText(lines.join('\n'));
+}

package/src/tools/list-tts-voices.js

@@ -0,0 +1,58 @@
+function toolText(text) {
+  return { content: [{ type: 'text', text }] };
+}
+
+function toolError(text) {
+  return { isError: true, content: [{ type: 'text', text }] };
+}
+
+function formatVoiceLine(voice) {
+  const tags = Array.isArray(voice.style_tags) && voice.style_tags.length
+    ? ` [${voice.style_tags.join(', ')}]`
+    : '';
+  const gender = voice.gender ? ` (${voice.gender})` : '';
+  const origin = voice.origin === 'cloned' ? ' • cloned' : '';
+  return `- ${voice.voice_id} — ${voice.display_name}${gender}${tags}${origin}`;
+}
+
+export async function runListTtsVoicesTool({
+  language,
+  origin,
+  query,
+  style_tag,
+  limit,
+  workspace_id,
+  currentWorkspaceId,
+  api,
+}) {
+  const targetWorkspaceId = String(workspace_id ?? currentWorkspaceId ?? '').trim();
+  if (!targetWorkspaceId) {
+    return toolError('workspace_id is required (no current workspace context).');
+  }
+
+  const params = new URLSearchParams();
+  params.set('workspace_id', targetWorkspaceId);
+  if (language) params.set('language', String(language).trim());
+  if (origin) params.set('origin', String(origin).trim());
+  if (query) params.set('query', String(query).trim());
+  if (style_tag) params.set('style_tag', String(style_tag).trim());
+  if (limit != null && Number.isFinite(Number(limit))) params.set('limit', String(Math.floor(Number(limit))));
+
+  let data;
+  try {
+    data = await api('GET', `/tts/voices?${params.toString()}`);
+  } catch (error) {
+    return toolError(`list_tts_voices API error: ${error.message}`);
+  }
+
+  const voices = Array.isArray(data?.voices) ? data.voices : [];
+  if (!voices.length) {
+    return toolText('No TTS voices match the requested filters.');
+  }
+
+  const lines = [
+    `Found ${voices.length} voice(s) for provider=${data.provider}, workspace=${data.workspace_id}:`,
+    ...voices.map(formatVoiceLine),
+  ];
+  return toolText(lines.join('\n'));
+}

package/src/tools/preview-tts-voice.js

@@ -0,0 +1,75 @@
+import { mkdirSync, writeFileSync } from 'fs';
+import { randomUUID } from 'crypto';
+import path from 'path';
+import os from 'os';
+
+function toolText(text) {
+  return { content: [{ type: 'text', text }] };
+}
+
+function toolError(text) {
+  return { isError: true, content: [{ type: 'text', text }] };
+}
+
+function inferAudioExt(url) {
+  const clean = String(url ?? '').split('?')[0];
+  const ext = path.extname(clean).toLowerCase();
+  return ['.mp3', '.wav', '.flac', '.aac', '.ogg'].includes(ext) ? ext : '.mp3';
+}
+
+export async function runPreviewTtsVoiceTool({
+  voice_id,
+  text,
+  workspace_id,
+  currentWorkspaceId,
+  api,
+}) {
+  const normalizedVoiceId = String(voice_id ?? '').trim();
+  if (!normalizedVoiceId) return toolError('voice_id is required for preview_tts_voice.');
+
+  const targetWorkspaceId = String(workspace_id ?? currentWorkspaceId ?? '').trim();
+  if (!targetWorkspaceId) {
+    return toolError('workspace_id is required (no current workspace context).');
+  }
+
+  const payload = {
+    workspace_id: targetWorkspaceId,
+    voice_id: normalizedVoiceId,
+  };
+  if (text) payload.text = String(text).trim();
+
+  let data;
+  try {
+    data = await api('POST', '/tts/voices/preview', payload);
+  } catch (error) {
+    const message = String(error?.message ?? '');
+    if (message.includes('tts_voice_not_found')) {
+      return toolError(`voice_id "${normalizedVoiceId}" not found or not visible to this workspace.`);
+    }
+    return toolError(`preview_tts_voice API error: ${error.message}`);
+  }
+
+  const remoteAudioUrl = String(data.audio_url ?? '').trim();
+  if (!remoteAudioUrl) return toolError('preview_tts_voice did not return audio_url.');
+
+  const downloadRes = await fetch(remoteAudioUrl);
+  if (!downloadRes.ok) {
+    return toolError(`Failed to download preview audio (${downloadRes.status}).`);
+  }
+  const fileBuffer = Buffer.from(await downloadRes.arrayBuffer());
+  const outDir = path.join(os.tmpdir(), 'lightcone-tts');
+  mkdirSync(outDir, { recursive: true });
+  const ext = inferAudioExt(remoteAudioUrl);
+  const outPath = path.join(outDir, `tts-preview-${Date.now()}-${randomUUID().slice(0, 8)}${ext}`);
+  writeFileSync(outPath, fileBuffer);
+
+  return toolText([
+    'preview_tts_voice completed.',
+    `voice_id=${data.voice_id}`,
+    `display_name=${data.display_name ?? ''}`,
+    `path=${outPath}`,
+    `audio_url=${remoteAudioUrl}`,
+    `duration_ms=${data.duration_ms ?? 'unknown'}`,
+    `preview_text=${data.preview_text ?? ''}`,
+  ].join('\n'));
+}

package/src/tools/set-default-voice.js

@@ -0,0 +1,44 @@
+function toolText(text) {
+  return { content: [{ type: 'text', text }] };
+}
+
+function toolError(text) {
+  return { isError: true, content: [{ type: 'text', text }] };
+}
+
+export async function runSetDefaultVoiceTool({
+  voice_id,
+  workspace_id,
+  currentWorkspaceId,
+  api,
+}) {
+  const normalizedVoiceId = String(voice_id ?? '').trim();
+  if (!normalizedVoiceId) return toolError('voice_id is required for set_default_voice.');
+
+  const targetWorkspaceId = String(workspace_id ?? currentWorkspaceId ?? '').trim();
+  if (!targetWorkspaceId) {
+    return toolError('workspace_id is required (no current workspace context).');
+  }
+
+  let data;
+  try {
+    data = await api('PUT', '/tts/preferences', {
+      workspace_id: targetWorkspaceId,
+      voice_id: normalizedVoiceId,
+    });
+  } catch (error) {
+    const message = String(error?.message ?? '');
+    if (message.includes('tts_voice_not_found')) {
+      return toolError(`voice_id "${normalizedVoiceId}" not found or not visible to this workspace. Use list_tts_voices to discover valid IDs.`);
+    }
+    return toolError(`set_default_voice API error: ${error.message}`);
+  }
+
+  const v = data?.voice;
+  const lines = [
+    `Default TTS voice updated for workspace=${data.workspace_id} (provider=${data.provider}).`,
+    `voice_id=${data.default_voice_id}`,
+  ];
+  if (v?.display_name) lines.push(`display_name=${v.display_name}`);
+  return toolText(lines.join('\n'));
+}

package/src/tools/synthesize-tts.js

@@ -34,12 +34,22 @@ export async function runSynthesisTtsTool({ text, voice_id, workspace_id, curren
     speed: 1,
     format: 'mp3',
   };
-  if (voice_id) payload.voice_preset = String(voice_id).trim();
+  if (voice_id) payload.voice_id = String(voice_id).trim();
 
   let data;
   try {
     data = await api('POST', '/tts/voiceover', payload);
   } catch (error) {
+    // Server contract: tts_default_voice_required means the workspace has no
+    // default and the caller didn't pass voice_id. Surface a clear message so
+    // the agent knows to call list_tts_voices + set_default_voice first.
+    const message = String(error?.message ?? '');
+    if (message.includes('tts_default_voice_required')) {
+      return toolError('No TTS voice selected for this workspace. Call list_tts_voices, let the user pick one, then set_default_voice — or pass voice_id to synthesize_tts.');
+    }
+    if (message.includes('tts_voice_not_found')) {
+      return toolError(`voice_id "${voice_id}" not found or not visible to this workspace. Use list_tts_voices to discover valid IDs.`);
+    }
     return toolError(`synthesize_tts API error: ${error.message}`);
   }
 
@@ -63,6 +73,7 @@ export async function runSynthesisTtsTool({ text, voice_id, workspace_id, curren
   return toolText([
     'synthesize_tts completed.',
     `path=${outPath}`,
+    `voice_id=${data.voice_id ?? 'unknown'}`,
     `duration_ms=${data.duration_ms ?? 'unknown'}`,
     `size_bytes=${fileBuffer.length}`,
   ].join('\n'));

package/src/video-brief-flag.js

@@ -1,8 +1,8 @@
 // Cross-process flag for "the agent has sent a video-production 确认稿 (brief)
-// to the user in this workspace+agent context recently". chat-bridge's
-// send_message tool writes the flag when the outgoing message heuristically
-// looks like a confirmation brief; media-tools' compose_video_v2 and
-// record_url_narration read the flag and refuse to proceed without it.
+// to the user in this workspace+agent context". chat-bridge's send_message
+// tool writes the flag when the outgoing message heuristically looks like a
+// confirmation brief; media-tools' compose_video_v2 and record_url_narration
+// read the flag and refuse to proceed without it.
 //
 // Why a file flag instead of in-process state: send_message lives in
 // chat-bridge (one stdio MCP server), compose_video_v2/record_url_narration
@@ -18,11 +18,10 @@
 // codex behavior (which silently skipped the soft prompt rule) is what we
 // need to interrupt — and gaming is observable in chat history.
 
-import { mkdirSync, statSync, utimesSync, writeFileSync, existsSync } from 'node:fs';
+import { mkdirSync, writeFileSync, existsSync } from 'node:fs';
 import path from 'node:path';
 import os from 'node:os';
 
-const TTL_MS = 6 * 60 * 60 * 1000; // 6 hours
 const FILE_NAME = 'video-brief-sent.flag';
 
 function flagDir(workspaceId, agentId) {
@@ -39,18 +38,11 @@ export function markVideoBriefSent({ workspaceId, agentId, content }) {
   const p = flagPath(workspaceId, agentId);
   mkdirSync(dir, { recursive: true });
   writeFileSync(p, String(content ?? '').slice(0, 4096));
-  const now = new Date();
-  utimesSync(p, now, now);
 }
 
-export function hasFreshVideoBrief({ workspaceId, agentId, ttlMs = TTL_MS } = {}) {
+export function hasVideoBriefSent({ workspaceId, agentId } = {}) {
   if (!workspaceId || !agentId) return false;
-  const p = flagPath(workspaceId, agentId);
-  if (!existsSync(p)) return false;
-  try {
-    const st = statSync(p);
-    return (Date.now() - st.mtimeMs) <= ttlMs;
-  } catch { return false; }
+  return existsSync(flagPath(workspaceId, agentId));
 }
 
 // Permission-asking markers — the message must ask the user to decide / OK.