@remixmate/cli 0.13.4 → 0.13.6

package/skills/render-video/scripts/render_video.py

@@ -27,6 +27,7 @@ import argparse
 import atexit
 import builtins
 import json
+import math
 import os
 import re
 import signal
@@ -70,6 +71,8 @@ from video_dsl.runtime.timeline_compiler import (
 
 _TRAILING_PUNCT_RE = re.compile(r"[。！？；，,、：:．.…]+$")
 
+_PAUSE_TAG_RE = re.compile(r"<#\s*\d+(?:\.\d+)?\s*#>")
+
 def _strip_subtitle_trailing_punct(text: str) -> str:
 
     return _TRAILING_PUNCT_RE.sub("", text)
@@ -919,7 +922,7 @@ def build_render_plan(dsl: dict, binding: dict) -> dict:
     for idx, scene in enumerate(dsl.get("scenes", [])):
         scene_id = scene.get("id") or scene.get("sceneId") or f"scene-{idx:03d}"
         duration = scene.get("duration", 5)
-        duration_frames = int(duration * fps)
+        duration_frames = math.floor(duration * fps + 0.5)
 
         scene_binding = binding_map.get(scene_id, {})
 
@@ -1001,12 +1004,15 @@ def build_render_plan(dsl: dict, binding: dict) -> dict:
 
         if isinstance(scene.get("textLayers"), list) and scene["textLayers"]:
             entry["textLayers"] = scene["textLayers"]
+
+        if narration.get("break") is True:
+            entry["narrationBreak"] = True
         timeline.append(entry)
         current_frame += duration_frames
 
     total_frames = current_frame
 
-    return {
+    plan = {
         "version": "v1alpha1",
         "createdAt": now_iso(),
         "status": "planning",
@@ -1047,6 +1053,13 @@ def build_render_plan(dsl: dict, binding: dict) -> dict:
         ],
     }
 
+    narration_override = {
+        k: global_narration[k] for k in ("mode", "scenePauseSec") if k in global_narration
+    }
+    if narration_override:
+        plan["narration"] = narration_override
+    return plan
+
 
 def resolve_asset_image(asset: dict, private_token: str, timeout: int) -> dict:
 
@@ -1099,24 +1112,32 @@ def resolve_asset_audio(asset: dict, private_token: str, timeout: int) -> dict:
 
 
     payload = asset.get("payload", {})
+    tts_text = _tts_text_from_payload(payload)
+    if not tts_text:
+        return {"status": "failed", "error": "No text provided for TTS"}
+    return _call_gen_voice(tts_text, payload, private_token, timeout)
+
+
+def _tts_text_from_payload(payload: dict) -> str:
 
-    try:
-        cmd = build_skill_command("gen-voice")
-    except RuntimeError as e:
-        return {"status": "failed", "error": str(e)}
 
     narration_items = payload.get("narrationItems")
     if isinstance(narration_items, list) and narration_items:
         cleaned = [str(s).strip() for s in narration_items if str(s).strip()]
-        tts_text = "\n".join(cleaned)
-        if not tts_text:
-            return {"status": "failed", "error": "No text provided for TTS"}
-    else:
-        text = payload.get("text", "")
-        if not text:
-            return {"status": "failed", "error": "No text provided for TTS"}
-        segments = segment_narration(text)
-        tts_text = "\n".join(s.strip() for s in segments) if segments else text
+        return "\n".join(cleaned)
+    text = payload.get("text", "")
+    if not text:
+        return ""
+    segments = segment_narration(text)
+    return "\n".join(s.strip() for s in segments) if segments else text
+
+
+def _call_gen_voice(tts_text: str, payload: dict, private_token: str, timeout: int) -> dict:
+
+    try:
+        cmd = build_skill_command("gen-voice")
+    except RuntimeError as e:
+        return {"status": "failed", "error": str(e)}
 
     cmd.extend(["--text", tts_text, "--json-output"])
     if payload.get("voiceId"):
@@ -1379,6 +1400,7 @@ def _resolve_single_asset(
             if isinstance(src_payload.get("narrationItems"), list):
                 asset["narrationLineCount"] = len(src_payload["narrationItems"])
                 asset["narrationIntroLines"] = int(src_payload.get("narrationIntroLines") or 0)
+                asset["narrationLines"] = list(src_payload["narrationItems"])
             LogPrint(f"   ✅ {asset['assetId']} generated", file=sys.stderr)
             return True
         else:
@@ -1441,6 +1463,179 @@ def apply_stub_urls(render_plan: dict, stub_image_url: str = "", stub_video_url:
     return stubbed
 
 
+def plan_narration_runs(render_plan: dict) -> tuple[list[list[dict]], dict]:
+
+
+
+
+    import _continuous_narration as cn
+
+    cfg = cn.resolve_config(_timing_template(render_plan.get("templateId", "")), render_plan.get("narration"))
+    if cfg["mode"] != cn.MODE_CONTINUOUS:
+        return [], cfg
+    assets = {a.get("assetId"): a for a in render_plan.get("resolvedAssets", [])}
+    payloads = {
+        a.get("assetId"): a.get("payload") or {}
+        for a in render_plan.get("_dsl_assets", [])
+        if a.get("assetId")
+    }
+    timeline = render_plan.get("timeline", [])
+    refs: dict[str, int] = {}
+    for entry in timeline:
+        nar_id = (entry.get("props") or {}).get("narrationAssetId")
+        if nar_id:
+            refs[nar_id] = refs.get(nar_id, 0) + 1
+
+    candidates: list[Optional[dict]] = []
+    for entry in timeline:
+        nar_id = (entry.get("props") or {}).get("narrationAssetId")
+        asset = assets.get(nar_id)
+        payload = payloads.get(nar_id) or {}
+        text = _tts_text_from_payload(payload) if asset else ""
+        if (
+            not asset
+            or asset.get("source") != "gen-voice"
+            or asset.get("status") != "pending"
+            or refs.get(nar_id) != 1
+            or not text
+        ):
+            candidates.append(None)
+            continue
+        candidates.append({
+            "assetId": nar_id,
+            "sceneId": entry.get("sceneId"),
+            "text": text,
+            "voiceKey": (_narration_voice(payload), _narration_speed(payload), _narration_language_boost(payload)),
+            "break": bool(entry.get("narrationBreak")),
+        })
+    return cn.group_runs(candidates), cfg
+
+
+def _download_to(url: str, path: str, timeout: int) -> str:
+    os.makedirs(os.path.dirname(path), exist_ok=True)
+    with urllib.request.urlopen(url, timeout=timeout) as resp, open(path, "wb") as f:
+        while True:
+            chunk = resp.read(1 << 16)
+            if not chunk:
+                break
+            f.write(chunk)
+    return path
+
+
+def _upload_tts_clip(path: str, title: str) -> str:
+
+
+
+
+
+
+    from upload_video import upload_media_file
+    data = upload_media_file(path, title=title, role="tts_clip", retention="intermediate")
+    url = data.get("signedUrl") or data["fileUrl"]
+    if not data.get("signedUrl"):
+        req = urllib.request.Request(url, headers={"Range": "bytes=0-0"})
+        with urllib.request.urlopen(req, timeout=15):
+            pass
+    return url
+
+
+def resolve_narration_run(
+    run: list[dict],
+    cfg: dict,
+    render_plan: dict,
+    private_token: str,
+    max_retries: int,
+    timeout: int,
+    work_dir: Optional[str] = None,
+) -> bool:
+
+
+    import _continuous_narration as cn
+    from _digital_human_segments import find_ffmpeg
+
+    scene_ids = [c.get("sceneId") for c in run]
+
+    def log(message: str, level: str = "info") -> None:
+        render_plan.setdefault("logs", []).append({
+            "phase": "narration-run",
+            "level": level,
+            "message": message,
+            "timestamp": now_iso(),
+        })
+        LogPrint(f"   🎙️  {message}", file=sys.stderr)
+
+    ffmpeg = find_ffmpeg()
+    if not ffmpeg:
+        log(f"ffmpeg not found; scenes {scene_ids} fall back to per-scene TTS", level="warn")
+        return False
+
+    pause = cfg["scenePauseSec"]
+    texts = [c["text"] for c in run]
+    run_text, ranges = cn.compose_run_text(texts, pause)
+    payloads = {
+        a.get("assetId"): a.get("payload") or {}
+        for a in render_plan.get("_dsl_assets", [])
+        if a.get("assetId")
+    }
+
+    voice_payload = payloads.get(run[0]["assetId"]) or {}
+
+    result: dict = {}
+    for attempt in range(max_retries):
+        LogPrint(f"   🔄 Generating continuous narration for {len(run)} scenes (attempt {attempt + 1}/{max_retries})...", file=sys.stderr)
+        result = _call_gen_voice(run_text, voice_payload, private_token, timeout)
+        if result.get("status") == "generated":
+            break
+        if attempt < max_retries - 1:
+            time.sleep(2)
+    if result.get("status") != "generated":
+        log(f"continuous TTS failed for scenes {scene_ids}: {str(result.get('error'))[:300]}; falling back to per-scene TTS", level="warn")
+        return False
+
+    try:
+        total_ms = float(result.get("audio_length_ms") or 0)
+        if total_ms <= 0:
+            raise RuntimeError("TTS returned no audio length")
+        out_dir = work_dir or os.path.join(OUTPUT_DIR, "narration")
+        run_name = "".join(ch if ch.isalnum() or ch in "-_." else "_" for ch in run[0]["assetId"])
+        local = _download_to(result["url"], os.path.join(out_dir, f"run-{run_name}.mp3"), timeout)
+        subs = result.get("subtitles") or []
+        silences = cn.detect_silences(local, total_ms, ffmpeg)
+        cuts, method = cn.find_cuts(texts, ranges, subs, silences, total_ms, pause, run_text)
+        if cuts is None:
+            log(f"no reliable cut points for scenes {scene_ids}; falling back to per-scene TTS", level="warn")
+            return False
+        bounds = cn.slice_bounds(cuts, total_ms)
+        paths = cn.slice_audio(local, bounds, out_dir, [c["assetId"] for c in run], ffmpeg)
+        urls = [_upload_tts_clip(path, f"narration {c['assetId']}") for path, c in zip(paths, run)]
+    except Exception as exc:
+        log(f"continuous narration split failed for scenes {scene_ids}: {exc}; falling back to per-scene TTS", level="warn")
+        return False
+
+    per_scene_subs = cn.split_subtitles(subs, bounds)
+    assets = {a.get("assetId"): a for a in render_plan.get("resolvedAssets", [])}
+    run_id = run[0]["assetId"]
+    for k, c in enumerate(run):
+        asset = assets[c["assetId"]]
+        start, end = bounds[k]
+        asset["status"] = "generated"
+        asset["url"] = urls[k]
+        asset["duration"] = int(round(end - start))
+        asset["generatedBy"] = {"skill": "gen-voice", "mode": "continuous", "startedAt": now_iso(), "completedAt": now_iso()}
+
+        asset["narrationRun"] = {"id": run_id, "index": k, "count": len(run), "method": method}
+        asset["speechSpanMs"] = list(cn.speech_span(bounds[k], silences))
+        if per_scene_subs[k]:
+            asset["ttsSubtitles"] = per_scene_subs[k]
+        payload = payloads.get(c["assetId"]) or {}
+        if isinstance(payload.get("narrationItems"), list):
+            asset["narrationLineCount"] = len(payload["narrationItems"])
+            asset["narrationIntroLines"] = int(payload.get("narrationIntroLines") or 0)
+            asset["narrationLines"] = list(payload["narrationItems"])
+    log(f"continuous narration: {len(run)} scenes in one TTS call, {total_ms / 1000:.1f}s, cut by {method}")
+    return True
+
+
 def resolve_assets(
     render_plan: dict,
     private_token: str,
@@ -1480,21 +1675,56 @@ def resolve_assets(
     failed = 0
 
 
+    runs: list[list[dict]] = []
+    narration_cfg: dict = {}
+    if phase1:
+        runs, narration_cfg = plan_narration_runs(render_plan)
+    run_asset_ids = {c["assetId"] for run in runs for c in run}
+    singles = [a for a in phase1 if a.get("assetId") not in run_asset_ids]
+    assets_by_id = {a.get("assetId"): a for a in phase1}
+
+    def resolve_run(run: list[dict]) -> tuple[int, int]:
+        if resolve_narration_run(run, narration_cfg, render_plan, private_token, max_retries, timeout):
+            return len(run), 0
+        ok_count = fail_count = 0
+        for c in run:
+            asset = assets_by_id[c["assetId"]]
+            if _resolve_single_asset(asset, render_plan, private_token, max_retries, timeout):
+                ok_count += 1
+            elif asset["status"] == "failed":
+                fail_count += 1
+        return ok_count, fail_count
+
+
     if phase1:
         default_parallelism = 8
         max_workers = min(
             int(os.environ.get("REMOTION_ASSET_PARALLELISM", str(default_parallelism))),
-            len(phase1),
+            len(singles) + len(runs),
         )
         LogPrint(f"   ⚡ Phase 1: generating {len(phase1)} asset(s) in parallel (concurrency={max_workers})", file=sys.stderr)
+        if runs:
+            LogPrint(f"   🎙️  {len(runs)} continuous narration run(s) covering {len(run_asset_ids)} scene(s)", file=sys.stderr)
         with ThreadPoolExecutor(max_workers=max_workers) as executor:
             future_to_asset = {
                 executor.submit(
                     _resolve_single_asset, asset, render_plan, private_token, max_retries, timeout
                 ): asset
-                for asset in phase1
+                for asset in singles
             }
-            for future in as_completed(future_to_asset):
+            future_to_run = {executor.submit(resolve_run, run): run for run in runs}
+            for future in as_completed([*future_to_asset, *future_to_run]):
+                if future in future_to_run:
+                    try:
+                        ok_count, fail_count = future.result()
+                        generated += ok_count
+                        failed += fail_count
+                    except Exception as exc:
+                        for c in future_to_run[future]:
+                            assets_by_id[c["assetId"]]["status"] = "failed"
+                            failed += 1
+                        LogPrint(f"   ❌ continuous narration run exception: {exc}", file=sys.stderr)
+                    continue
                 asset = future_to_asset[future]
                 try:
                     ok = future.result()
@@ -1687,9 +1917,8 @@ def _auto_highlight_map(
         return
 
     props = entry.get("props") or {}
-    tdata = props.get("templateData")
-    if not isinstance(tdata, dict):
-        return
+    nested = isinstance(props.get("templateData"), dict)
+    tdata = props["templateData"] if nested else props
     if tdata.get("highlightMap"):
         return
 
@@ -1721,7 +1950,8 @@ def _auto_highlight_map(
 
     highlight_map = {str(intro_lines + i): i for i in range(item_count) if item_count > 0}
     tdata["highlightMap"] = highlight_map
-    props["templateData"] = tdata
+    if nested:
+        props["templateData"] = tdata
     entry["props"] = props
 
     render_plan.setdefault("logs", []).append({
@@ -1758,6 +1988,49 @@ def _template_default_tail_pad_frames(tpl: dict, fps: int) -> int | None:
     return int(round(float(value) * fps))
 
 
+def _structured_narration_subtitles(entry: dict, asset: dict, render_plan: dict) -> list[dict]:
+
+    from _narration_alignment import align_narration_lines
+
+    subtitles = asset.get("ttsSubtitles") or []
+    line_count = asset.get("narrationLineCount")
+    if not isinstance(line_count, int) or isinstance(line_count, bool) or line_count <= 0:
+        return subtitles
+
+
+    old_subs = entry.get("subtitleSegments") or []
+    at_sec = entry.get("subtitleAtSec") or []
+    if len(at_sec) == len(old_subs) and any(isinstance(v, (int, float)) for v in at_sec):
+        return []
+
+    lines = asset.get("narrationLines")
+    if not isinstance(lines, list) or len(lines) != line_count:
+        lines = [s.get("text") for s in old_subs] if len(old_subs) == line_count else []
+    if len(lines) != line_count or any(not isinstance(v, str) or not v.strip() for v in lines):
+        method = "authored-lines-unavailable"
+        message = "Authored narration lines unavailable; cannot restore per-line timing"
+    else:
+
+        asset["narrationLines"] = list(lines)
+        subtitles, method = align_narration_lines(
+            lines, subtitles, asset["duration"], asset.get("speechSpanMs"),
+        )
+        message = f"Preserved {line_count} narration lines using {method} timing"
+
+    logs = render_plan.setdefault("logs", [])
+    if not any(l.get("phase") == "narration-align" and l.get("sceneId") == entry.get("sceneId")
+               and l.get("method") == method for l in logs):
+        logs.append({
+            "phase": "narration-align",
+            "sceneId": entry.get("sceneId"),
+            "method": method,
+            "level": "info" if method == "tts-boundaries" else "warn",
+            "message": message,
+            "timestamp": now_iso(),
+        })
+    return subtitles
+
+
 def adjust_timeline_to_audio(render_plan: dict) -> dict:
 
 
@@ -1801,10 +2074,17 @@ def adjust_timeline_to_audio(render_plan: dict) -> dict:
 
 
                 tail_pad_override = entry.get("tailPadFrames")
+
+
+                run = narration_asset.get("narrationRun") or {}
+                scene_default_tail = (
+                    0 if run and int(run.get("index", 0)) < int(run.get("count", 0)) - 1
+                    else default_tail_pad
+                )
                 tail_pad = (
                     int(tail_pad_override)
                     if isinstance(tail_pad_override, int) and tail_pad_override >= 0
-                    else default_tail_pad
+                    else scene_default_tail
                 )
                 min_dur = int(fps * 2)
 
@@ -1816,7 +2096,7 @@ def adjust_timeline_to_audio(render_plan: dict) -> dict:
                     entry["durationFrames"] = new_dur
                     adjusted += 1
 
-                tts_subs = narration_asset.get("ttsSubtitles", [])
+                tts_subs = _structured_narration_subtitles(entry, narration_asset, render_plan)
                 if tts_subs:
 
 
@@ -1828,12 +2108,13 @@ def adjust_timeline_to_audio(render_plan: dict) -> dict:
                     )
                     entry["subtitleSegments"] = [
                         {
-                            "text": _strip_subtitle_trailing_punct(s["text"].strip()),
+                            "text": _strip_subtitle_trailing_punct(_PAUSE_TAG_RE.sub("", s["text"]).strip()),
                             "startFrame": current_frame + int(s["timeBegin"] / 1000.0 * fps),
                             "endFrame": current_frame + int(s["timeEnd"] / 1000.0 * fps),
                             "sentenceIndex": sentence_indices[i],
                         }
                         for i, s in enumerate(tts_subs)
+                        if _PAUSE_TAG_RE.sub("", s.get("text") or "").strip()
                     ]
                     _warn_step_sentence_mismatch(entry, sentence_indices, step_field)
                 else:
@@ -1887,13 +2168,18 @@ def adjust_timeline_to_audio(render_plan: dict) -> dict:
                         entry["subtitleSegments"] = new_subs
                     elif old_subs:
                         sub_span = audio_frames
+                        cursor = 0
+
+                        span = narration_asset.get("speechSpanMs")
+                        if isinstance(span, list) and len(span) == 2 and 0 <= span[0] < span[1]:
+                            cursor = int(span[0] / 1000.0 * fps)
+                            sub_span = max(math.ceil(span[1] / 1000.0 * fps) - cursor, fps // 2)
 
 
                         def _plain(t: str) -> int:
                             return len(re.sub(r"\*+", "", t or ""))
                         total_chars = max(sum(_plain(s.get("text", "")) for s in old_subs), 1)
                         new_subs = []
-                        cursor = 0
                         for s in old_subs:
                             text = s.get("text", "")
                             ratio = _plain(text) / total_chars
@@ -3143,7 +3429,7 @@ def _persist_render_plan(render_plan: dict, args, private_token: str, dsl: dict
             args.save_job = False
 
 
-def _print_resolve_only_summary(render_plan: dict) -> int:
+def _print_resolve_only_summary(render_plan: dict, dsl: dict | None = None) -> int:
 
     generated = sum(1 for a in render_plan["resolvedAssets"] if a["status"] == "generated")
     failed = sum(1 for a in render_plan["resolvedAssets"] if a["status"] == "failed")
@@ -3202,6 +3488,16 @@ def _print_resolve_only_summary(render_plan: dict) -> int:
             print(f"   {asset['assetId']:<25} {asset.get('status', '?'):<10} scenes: {scenes_on}  {asset.get('url', '')}")
     else:
         print(f"\n🧑 Digital-human segments: none (this render has no presenter)")
+    from _scene_assets import scene_assets
+    narration_texts = {}
+    for scene in (dsl or {}).get("scenes", []):
+        authored = (scene.get("audio") or {}).get("narration") or {}
+        lines = extract_narration_lines(authored)
+        if lines:
+            narration_texts[scene["id"]] = "\n".join(lines[0])
+        elif isinstance(authored.get("text"), str):
+            narration_texts[scene["id"]] = authored["text"]
+    print("__scene_assets__ " + json.dumps(scene_assets(render_plan, narration_texts), ensure_ascii=False))
 
     return failed
 
@@ -3427,7 +3723,7 @@ def main():
             LogPrint(f"💾 RenderPlan saved: {rp_output}", file=sys.stderr)
 
     if args.resolve_only:
-        if _print_resolve_only_summary(render_plan) > 0:
+        if _print_resolve_only_summary(render_plan, dsl) > 0:
             sys.exit(1)
         return
 

package/skills/render-video/version.json

@@ -2,6 +2,6 @@
   "skillName": "render-video",
   "repoName": "agent-skill-media-maker",
   "skillId": "473",
-  "version": "V40",
+  "version": "V42",
   "skillDescription": "Final-render skill: loads a persisted RenderPlan by `job_id` and drives the Remotion engine to produce the final video.\n\nUse this skill as soon as the user mentions any of these intents (after assets are already prepared):\n- Render the video, composite the video, export the video\n- Turn the prepared assets into the final clip\n- Render with Remotion\n\nPrerequisite: assets must already be generated via `prepare_video_assets`. This skill never resolves or regenerates assets — pass it a `job_id` from a previous `prepare_video_assets` call.\n\n⚠️ Stop-and-confirm gate: never call this skill until the user has explicitly confirmed the assets prepared by `prepare_video_assets`. If those assets were prepared in the current turn and the user has not replied since, stop and ask instead of rendering."
 }

package/skills/template-registry/SKILL.md

@@ -199,6 +199,7 @@ Rules:
 - The legacy flat `narration.text` form still works but the author then has to keep `highlightMap` in sync with the subtitle segmentation (error-prone, not recommended).
 - `narration.languageBoost` (optional, also accepted at `global.narration`) pins the TTS language hint (`auto` / `Chinese` / `English` / …). Leave it unset unless auto-detection gets it wrong — the service applies its own default, and a scene-level value overrides the global one, exactly like `speed`.
 - Voice: to change the narration voice, set `global.narration.voiceId` (whole video) or `narration.voiceId` on a scene (that scene only). Precedence when synthesizing is scene > global > the audio asset's `payload.voiceId`, which is only a fallback — editing the asset payload alone is not how you change a voice.
+- Continuous narration: templates that declare `capabilities.narration.mode: "continuous"` get adjacent scenes with the same voice / speed / languageBoost synthesized in one TTS call and cut back per scene, so pace and loudness stay even. Nothing to author for it. Set `narration.break: true` on a scene to start a new run there (a chapter change that wants a longer pause); `global.narration.mode` (`continuous` / `perScene`) overrides the template only when the user asks for it.
 
 ## Image sources
 

package/skills/template-registry/video_dsl/schema/video-dsl-v1alpha1.json

@@ -109,7 +109,9 @@
             "voiceId": { "type": "string", "description": "Minimax 音色 ID" },
             "voiceName": { "type": "string" },
             "speed": { "type": "number", "default": 1.0 },
-            "languageBoost": { "type": "string", "description": "TTS 语种提示（auto / Chinese / English …）。中英混排的旁白不给提示时，英文词容易被按中文音系读出来；留空由服务端取默认值。" }
+            "languageBoost": { "type": "string", "description": "TTS 语种提示（auto / Chinese / English …）。中英混排的旁白不给提示时，英文词容易被按中文音系读出来；留空由服务端取默认值。" },
+            "mode": { "type": "string", "enum": ["continuous", "perScene"], "description": "旁白合成方式，覆盖模板 capabilities.narration.mode。continuous = 相邻、音色语速语种相同的场景整段合成一次再按场景切开（语速响度一致）；perScene = 每个场景单独合成。留空跟随模板，模板没声明即 perScene。" },
+            "scenePauseSec": { "type": "number", "minimum": 0.01, "maximum": 99.99, "description": "continuous 模式下场景之间插入的停顿秒数（MiniMax <#x#>），覆盖模板声明；默认 0.8。" }
           }
         },
         "bgm": {
@@ -268,6 +270,7 @@
                 "voiceId": { "type": "string", "description": "该场旁白音色，覆盖 global.narration.voiceId；留空跟随全局。合成时优先级：场景 > 全局 > 音频资产 payload.voiceId（仅作兜底）。" },
                 "voiceName": { "type": "string", "description": "voiceId 的展示名（仅展示用，不参与合成）" },
                 "speed": { "type": "number", "description": "该场旁白语速，覆盖 global.narration.speed；留空跟随全局。" },
+                "break": { "type": "boolean", "description": "continuous 旁白模式下从这一幕起另起一段整段合成（例如换章节、需要更长停顿）。perScene 模式下无效。" },
                 "languageBoost": { "type": "string", "description": "TTS 语种提示（auto / Chinese / English …）。中英混排的旁白不给提示时，英文词容易被按中文音系读出来；覆盖 global.narration 的同名字段；留空则跟随全局/服务端默认。" }
               }
             },