@remixmate/cli 0.13.4 → 0.13.5

package/dist/handlers/gen-voice.js

@@ -1,19 +1,19 @@
-var w=Object.defineProperty;var l=(e,o)=>w(e,"name",{value:o,configurable:!0});import{mmPost as m,resolveHttpContext as v,SkillError as c}from"../http.js";import{getCapabilities as _}from"../capabilities.js";import{emitProgress as y}from"../progress.js";import{isTrue as u,toNumber as $}from"./shared.js";const b=[{id:"Chinese (Mandarin)_Male_Announcer",language:"zh",name:"Mandarin Male Announcer (legacy default)"},{id:"english-male-friendly-01",language:"en",name:"Friendly Male (English, TBD)"}];async function k(e){const t=(await m(e,"/voice/page",{current:1,pageSize:100},{timeoutMs:3e4})).list??[];if(t.length===0){process.stdout.write(`⚠️  No voices available
+var w=Object.defineProperty;var d=(e,i)=>w(e,"name",{value:i,configurable:!0});import{mmPost as m,resolveHttpContext as v,SkillError as c}from"../http.js";import{getCapabilities as y}from"../capabilities.js";import{emitProgress as x}from"../progress.js";import{isTrue as u,toNumber as _}from"./shared.js";const b=[{id:"Chinese (Mandarin)_Male_Announcer",language:"zh",name:"Mandarin Male Announcer (legacy default)"},{id:"english-male-friendly-01",language:"en",name:"Friendly Male (English, TBD)"}];async function $(e){const o=(await m(e,"/voice/page",{current:1,pageSize:100},{timeoutMs:3e4})).list??[];if(o.length===0){process.stdout.write(`⚠️  No voices available
 `);return}process.stdout.write(`
 ${"Voice ID".padEnd(30)} Name
 `),process.stdout.write(`${"-".repeat(30)} ${"-".repeat(20)}
-`);for(const s of t)process.stdout.write(`${(s.uniqId??"").padEnd(30)} ${s.name??""}
+`);for(const s of o)process.stdout.write(`${(s.uniqId??"").padEnd(30)} ${s.name??""}
 `);process.stdout.write(`
-${t.length} voice(s) available
+${o.length} voice(s) available
 `),process.stdout.write(`💡 Use --voice-id <id> to select a voice for synthesis
-`)}l(k,"listVoicesRemote");function x(){process.stderr.write(`⚠️  --local prints a hardcoded 2-entry fallback list, NOT the available voices. Drop --local to query the live catalog.
+`)}d($,"listVoicesRemote");function k(){process.stderr.write(`⚠️  --local prints a hardcoded 2-entry fallback list, NOT the available voices. Drop --local to query the live catalog.
 `);for(const e of b)process.stdout.write(`${e.id}	${e.language}	${e.name}
-`)}l(x,"listVoicesLocal");async function E(e,o){if(u(e.list_voices)){if(u(e.local))return x();const a=await v(o.skillName,{apiBaseUrl:e.api_base_url,privateToken:e.priv_token,preflightToken:o.auth?.token});return k(a)}const t=e.text;if(!t||typeof t!="string"||!t.trim())throw new c("❌ Please provide --text to specify the text to synthesize");const s=e.api_base_url,i=(await _(s)).voice,p=e.voice_id??i.defaultVoiceId,r=$(e.speed,"speed")??1;if(r<i.speedMin||r>i.speedMax)throw new c(`❌ speed must be in the range ${i.speedMin}~${i.speedMax}`);const g=e.language_boost?.trim()||void 0,h=await v(o.skillName,{apiBaseUrl:s,privateToken:e.priv_token,preflightToken:o.auth?.token});y({phase:"gen-voice:request",voiceId:p,speed:r});const n=await m(h,"/tool/tts",{provider:i.provider,text:t,voiceSetting:{voiceId:p,speed:r},outputFormat:"url",...g?{languageBoost:g}:{}},{timeoutMs:12e4}),d=n.audio;if(!d)throw new c(`❌ API response did not contain an audio URL: ${JSON.stringify(n)}`);if(u(e.json_output)){process.stdout.write(JSON.stringify({url:d,audio_length_ms:n.extraInfo?.audioLength??null,subtitles:(n.subtitles??[]).map(a=>({text:a.text??"",timeBegin:a.timeBegin??0,timeEnd:a.timeEnd??0}))})+`
-`);return}const f=n.extraInfo?.audioLength;typeof f=="number"&&process.stdout.write(`
+`)}d(k,"listVoicesLocal");async function L(e,i){if(u(e.list_voices)){if(u(e.local))return k();const t=await v(i.skillName,{apiBaseUrl:e.api_base_url,privateToken:e.priv_token,preflightToken:i.auth?.token});return $(t)}const o=e.text;if(!o||typeof o!="string"||!o.trim())throw new c("❌ Please provide --text to specify the text to synthesize");const s=e.api_base_url,n=(await y(s)).voice,p=e.voice_id??n.defaultVoiceId,r=_(e.speed,"speed")??1;if(r<n.speedMin||r>n.speedMax)throw new c(`❌ speed must be in the range ${n.speedMin}~${n.speedMax}`);const g=e.language_boost?.trim()||void 0,h=await v(i.skillName,{apiBaseUrl:s,privateToken:e.priv_token,preflightToken:i.auth?.token});x({phase:"gen-voice:request",voiceId:p,speed:r});const a=await m(h,"/tool/tts",{provider:n.provider,text:o,voiceSetting:{voiceId:p,speed:r},outputFormat:"url",...g?{languageBoost:g}:{}},{timeoutMs:12e4}),l=a.audio;if(!l)throw new c(`❌ API response did not contain an audio URL: ${JSON.stringify(a)}`);if(u(e.json_output)){process.stdout.write(JSON.stringify({url:l,audio_length_ms:a.extraInfo?.audioLength??null,subtitles:(a.subtitles??[]).map(t=>({text:t.text??"",timeBegin:t.timeBegin??0,timeEnd:t.timeEnd??0,...typeof t.textBegin=="number"&&typeof t.textEnd=="number"?{textBegin:t.textBegin,textEnd:t.textEnd}:{}}))})+`
+`);return}const f=a.extraInfo?.audioLength;typeof f=="number"&&process.stdout.write(`
 🕐 Audio length: ${(f/1e3).toFixed(1)} s
 `),process.stdout.write(`
 🔗 Audio URL (plays directly, no download needed):
-${d}
+${l}
 `),process.stdout.write(`
 🎉 TTS synthesis done!
-`)}l(E,"genVoice");export{E as genVoice};
+`)}d(L,"genVoice");export{L as genVoice};

package/dist/manifest.json

@@ -1,7 +1,7 @@
 {
   "schemaVersion": 1,
-  "version": "0.13.4",
-  "generatedAt": "2026-10-26T01:31:08.439Z",
+  "version": "0.13.5",
+  "generatedAt": "2026-10-28T14:51:31.746Z",
   "skills": [
     {
       "id": "doc-parse",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@remixmate/cli",
-  "version": "0.13.4",
+  "version": "0.13.5",
   "description": "AI media generation skills for Claude Code / Codex — 12 skills covering image, video, voice, digital human, web screenshot, web recording, script, template registry, rendering, Jianying export, and video deconstruction.",
   "type": "module",
   "main": "dist/index.js",

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

@@ -0,0 +1,468 @@
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+from __future__ import annotations
+
+import os
+import re
+import subprocess
+import unicodedata
+from typing import Optional
+
+MODE_CONTINUOUS = "continuous"
+MODE_PER_SCENE = "perScene"
+
+
+
+DEFAULT_SCENE_PAUSE_SEC = 0.8
+
+
+
+MAX_RUN_CHARS = 1500
+
+
+
+
+ESTIMATE_WINDOW_SEC = 2.0
+_ESTIMATE_WINDOW_RATIO = 0.2
+
+
+_NATURAL_PAUSE_SEC = 0.45
+
+
+_MIN_BOUNDARY_PAUSE_RATIO = 0.75
+
+_SILENCE_NOISE_DB = -40
+_SILENCE_MIN_SEC = 0.25
+
+PAUSE_TAG_RE = re.compile(r"<#\s*(\d+(?:\.\d+)?)\s*#>")
+_LEADING_TAG_RE = re.compile(r"^\s*<#\s*(\d+(?:\.\d+)?)\s*#>\s*")
+_TRAILING_TAG_RE = re.compile(r"\s*<#\s*(\d+(?:\.\d+)?)\s*#>\s*$")
+
+
+
+
+def _pause_value(raw) -> Optional[float]:
+    if isinstance(raw, bool) or not isinstance(raw, (int, float)):
+        return None
+
+    return min(max(float(raw), 0.01), 99.99) if raw > 0 else None
+
+
+def resolve_config(template: dict, override: Optional[dict]) -> dict:
+
+
+
+
+    declared = ((template or {}).get("capabilities") or {}).get("narration") or {}
+    override = override or {}
+    mode = MODE_PER_SCENE
+    for source in (declared, override):
+        if source.get("mode") in (MODE_CONTINUOUS, MODE_PER_SCENE):
+            mode = source["mode"]
+    pause = DEFAULT_SCENE_PAUSE_SEC
+    for source in (declared, override):
+        value = _pause_value(source.get("scenePauseSec"))
+        if value is not None:
+            pause = value
+    return {"mode": mode, "scenePauseSec": pause}
+
+
+
+
+def group_runs(candidates: list[Optional[dict]], max_chars: int = MAX_RUN_CHARS) -> list[list[dict]]:
+
+
+
+
+
+
+    runs: list[list[dict]] = []
+    current: list[dict] = []
+    chars = 0
+
+    def flush() -> None:
+        if len(current) >= 2:
+            runs.append(list(current))
+        current.clear()
+
+    for cand in candidates:
+        if cand is None:
+            flush()
+            chars = 0
+            continue
+        size = len(cand["text"])
+        if current and (
+            cand.get("break")
+            or cand["voiceKey"] != current[-1]["voiceKey"]
+            or chars + size > max_chars
+        ):
+            flush()
+            chars = 0
+        current.append(cand)
+        chars += size
+    flush()
+    return runs
+
+
+
+
+def format_pause(sec: float) -> str:
+    return f"{sec:.2f}".rstrip("0").rstrip(".")
+
+
+def compose_run_text(texts: list[str], pause_sec: float) -> tuple[str, list[tuple[int, int]]]:
+
+
+
+
+    parts: list[str] = []
+    for i, text in enumerate(texts):
+        text = text.strip()
+        if i > 0:
+            text = _LEADING_TAG_RE.sub("", text, count=1)
+        if i < len(texts) - 1:
+            text = _TRAILING_TAG_RE.sub("", text, count=1)
+        parts.append(text)
+
+    pauses: list[float] = []
+    for i in range(len(texts) - 1):
+        candidates = [pause_sec]
+        tail = _TRAILING_TAG_RE.search(texts[i].strip())
+        head = _LEADING_TAG_RE.search(texts[i + 1].strip())
+        for m in (tail, head):
+            if m:
+                candidates.append(_pause_value(float(m.group(1))) or 0)
+        pauses.append(max(candidates))
+
+    out = ""
+    ranges: list[tuple[int, int]] = []
+    for i, part in enumerate(parts):
+        if i > 0:
+            out += f"\n<#{format_pause(pauses[i - 1])}#>\n"
+        start = len(out)
+        out += part
+        ranges.append((start, len(out)))
+    return out, ranges
+
+
+def normalize(text: str) -> str:
+
+    text = PAUSE_TAG_RE.sub("", text or "")
+    return "".join(
+        ch for ch in text
+        if not ch.isspace() and not unicodedata.category(ch).startswith(("P", "S"))
+    )
+
+
+def estimate_durations(texts: list[str], total_ms: float, pause_sec: float) -> list[float]:
+
+
+
+
+    counts = [max(len(normalize(t)), 1) for t in texts]
+    boundaries = len(texts) - 1
+    gap_ms = (pause_sec + _NATURAL_PAUSE_SEC) * 1000
+    speech_ms = total_ms - boundaries * gap_ms
+    if speech_ms <= 0:
+        gap_ms, speech_ms = 0.0, total_ms
+    per_char = speech_ms / sum(counts)
+    durations: list[float] = []
+    for k, count in enumerate(counts):
+        edges = (k > 0) + (k < boundaries)
+        durations.append(count * per_char + edges * gap_ms / 2)
+    return durations
+
+
+
+
+def _sub_mid(subs: list[dict], i: int) -> float:
+    return (float(subs[i]["timeEnd"]) + float(subs[i + 1]["timeBegin"])) / 2
+
+
+def cuts_from_text_offsets(subs: list[dict], ranges: list[tuple[int, int]]) -> Optional[list[float]]:
+
+
+    if len(subs) < 2 or not all(
+        isinstance(s.get("textBegin"), int) and isinstance(s.get("textEnd"), int) for s in subs
+    ):
+        return None
+    cuts: list[float] = []
+    for k in range(1, len(ranges)):
+        prev_end, next_start = ranges[k - 1][1], ranges[k][0]
+        hit = next(
+            (
+                i for i in range(len(subs) - 1)
+                if subs[i]["textEnd"] <= next_start
+                and subs[i + 1]["textBegin"] >= prev_end
+                and subs[i + 1]["textBegin"] >= subs[i]["textEnd"]
+            ),
+            None,
+        )
+        if hit is None:
+            return None
+        cuts.append(_sub_mid(subs, hit))
+    return cuts if _monotonic(cuts) else None
+
+
+def speakable_ranges(run_text: str, ranges: list[tuple[int, int]]) -> list[tuple[int, int]]:
+
+
+
+
+
+
+    keep = [ch not in "\r\n" for ch in run_text]
+    for m in PAUSE_TAG_RE.finditer(run_text):
+        for i in range(m.start(), m.end()):
+            keep[i] = False
+    prefix = [0]
+    for k in keep:
+        prefix.append(prefix[-1] + k)
+    return [(prefix[a], prefix[b]) for a, b in ranges]
+
+
+def cuts_from_text_alignment(subs: list[dict], texts: list[str]) -> Optional[list[float]]:
+
+
+    if len(subs) < 2:
+        return None
+    sub_acc: list[int] = []
+    acc = 0
+    for s in subs:
+        acc += len(normalize(s.get("text") or ""))
+        sub_acc.append(acc)
+    if acc != sum(len(normalize(t)) for t in texts):
+        return None
+    cuts: list[float] = []
+    scene_acc = 0
+    for k in range(len(texts) - 1):
+        scene_acc += len(normalize(texts[k]))
+        try:
+            i = sub_acc.index(scene_acc)
+        except ValueError:
+            return None
+        if i >= len(subs) - 1:
+            return None
+        cuts.append(_sub_mid(subs, i))
+    return cuts if _monotonic(cuts) else None
+
+
+def cuts_from_silences(
+    silences: list[tuple[float, float]],
+    texts: list[str],
+    total_ms: float,
+    pause_sec: float,
+) -> Optional[list[float]]:
+
+    need = len(texts) - 1
+    if need <= 0:
+        return []
+
+    inner = [s for s in silences if 0 < s[0] and s[1] < total_ms]
+    if len(inner) < need:
+        return None
+    longest = sorted(inner, key=lambda s: s[1] - s[0], reverse=True)[:need]
+    longest.sort(key=lambda s: s[0])
+    min_len = pause_sec * _MIN_BOUNDARY_PAUSE_RATIO * 1000
+    if any(end - start < min_len for start, end in longest):
+        return None
+    cuts = [(start + end) / 2 for start, end in longest]
+    if not _durations_plausible(cuts, texts, total_ms, pause_sec):
+        return None
+    return cuts if _monotonic(cuts) else None
+
+
+def _monotonic(cuts: list[float]) -> bool:
+    return all(b > a for a, b in zip(cuts, cuts[1:])) and all(c > 0 for c in cuts)
+
+
+def _durations_plausible(cuts: list[float], texts: list[str], total_ms: float, pause_sec: float) -> bool:
+
+    edges = [0.0, *cuts, float(total_ms)]
+    for k, predicted in enumerate(estimate_durations(texts, total_ms, pause_sec)):
+        actual = edges[k + 1] - edges[k]
+        if abs(actual - predicted) > max(ESTIMATE_WINDOW_SEC * 1000, predicted * _ESTIMATE_WINDOW_RATIO):
+            return False
+    return True
+
+
+def _cuts_on_boundary_pauses(cuts: list[float], silences: list[tuple[float, float]], pause_sec: float) -> bool:
+
+
+
+    min_len = pause_sec * _MIN_BOUNDARY_PAUSE_RATIO * 1000
+    tol = 100.0
+    return all(
+        any(end - start >= min_len and start - tol <= c <= end + tol for start, end in silences)
+        for c in cuts
+    )
+
+
+def find_cuts(
+    texts: list[str],
+    ranges: list[tuple[int, int]],
+    subs: list[dict],
+    silences: Optional[list[tuple[float, float]]],
+    total_ms: float,
+    pause_sec: float,
+    run_text: Optional[str] = None,
+) -> tuple[Optional[list[float]], str]:
+
+
+
+
+    def trusted(cuts: Optional[list[float]]) -> bool:
+        return (
+            cuts is not None
+            and _durations_plausible(cuts, texts, total_ms, pause_sec)
+            and (silences is None or _cuts_on_boundary_pauses(cuts, silences, pause_sec))
+        )
+
+    candidates = [speakable_ranges(run_text, ranges)] if run_text is not None else []
+    for rs in [*candidates, ranges]:
+        cuts = cuts_from_text_offsets(subs, rs)
+        if trusted(cuts):
+            return cuts, "subtitle-offsets"
+    cuts = cuts_from_text_alignment(subs, texts)
+    if trusted(cuts):
+        return cuts, "subtitle-text"
+    if silences is not None:
+        cuts = cuts_from_silences(silences, texts, total_ms, pause_sec)
+        if cuts is not None:
+            return cuts, "silence"
+    return None, "none"
+
+
+
+
+def slice_bounds(cuts: list[float], total_ms: float) -> list[tuple[float, float]]:
+    edges = [0.0, *cuts, float(total_ms)]
+    return list(zip(edges, edges[1:]))
+
+
+def speech_span(bounds: tuple[float, float], silences: list[tuple[float, float]]) -> tuple[int, int]:
+
+    start, end = bounds
+    lo, hi = start, end
+    for s_start, s_end in silences:
+        if s_start <= lo < s_end:
+            lo = min(s_end, end)
+        if s_start < hi <= s_end:
+            hi = max(s_start, lo)
+    return int(round(lo - start)), int(round(hi - start))
+
+
+def split_subtitles(subs: list[dict], bounds: list[tuple[float, float]]) -> list[list[dict]]:
+
+    per_scene: list[list[dict]] = [[] for _ in bounds]
+    for s in subs:
+        mid = (float(s.get("timeBegin", 0)) + float(s.get("timeEnd", 0))) / 2
+        for k, (start, end) in enumerate(bounds):
+            if start <= mid < end or (k == len(bounds) - 1 and mid >= start):
+                length = end - start
+                per_scene[k].append({
+                    "text": s.get("text", ""),
+                    "timeBegin": int(round(min(max(float(s["timeBegin"]) - start, 0), length))),
+                    "timeEnd": int(round(min(max(float(s["timeEnd"]) - start, 0), length))),
+                })
+                break
+    return per_scene
+
+
+
+
+def silencedetect_command(src: str, ffmpeg: str = "ffmpeg") -> list[str]:
+    return [
+        ffmpeg, "-hide_banner", "-nostats", "-i", src,
+        "-af", f"silencedetect=noise={_SILENCE_NOISE_DB}dB:d={_SILENCE_MIN_SEC}",
+        "-f", "null", "-",
+    ]
+
+
+_SILENCE_START_RE = re.compile(r"silence_start:\s*(-?\d+(?:\.\d+)?)")
+_SILENCE_END_RE = re.compile(r"silence_end:\s*(-?\d+(?:\.\d+)?)")
+
+
+def parse_silencedetect(stderr: str, total_ms: float) -> list[tuple[float, float]]:
+
+    silences: list[tuple[float, float]] = []
+    start: Optional[float] = None
+    for line in (stderr or "").splitlines():
+        m = _SILENCE_START_RE.search(line)
+        if m:
+            start = max(float(m.group(1)) * 1000, 0.0)
+            continue
+        m = _SILENCE_END_RE.search(line)
+        if m and start is not None:
+            silences.append((start, float(m.group(1)) * 1000))
+            start = None
+    if start is not None:
+        silences.append((start, float(total_ms)))
+    return silences
+
+
+def detect_silences(src: str, total_ms: float, ffmpeg: str, timeout: int = 120) -> list[tuple[float, float]]:
+    try:
+        result = subprocess.run(
+            silencedetect_command(src, ffmpeg),
+            capture_output=True, text=True, timeout=timeout, stdin=subprocess.DEVNULL,
+        )
+    except subprocess.TimeoutExpired as exc:
+        raise RuntimeError(f"ffmpeg silencedetect timed out after {timeout}s") from exc
+    if result.returncode != 0:
+        raise RuntimeError(f"ffmpeg silencedetect failed: {(result.stderr or '').strip()[-500:]}")
+    return parse_silencedetect(result.stderr, total_ms)
+
+
+def slice_command(src: str, start_ms: float, end_ms: Optional[float], out_path: str, ffmpeg: str = "ffmpeg") -> list[str]:
+
+    cmd = [ffmpeg, "-y", "-loglevel", "error", "-i", src, "-ss", f"{start_ms / 1000:.3f}"]
+    if end_ms is not None:
+        cmd += ["-to", f"{end_ms / 1000:.3f}"]
+    cmd += ["-c:a", "libmp3lame", "-b:a", "128k", out_path]
+    return cmd
+
+
+def slice_audio(
+    src: str,
+    bounds: list[tuple[float, float]],
+    out_dir: str,
+    names: list[str],
+    ffmpeg: str,
+    timeout: int = 120,
+) -> list[str]:
+
+    os.makedirs(out_dir, exist_ok=True)
+    paths: list[str] = []
+    for k, ((start, end), name) in enumerate(zip(bounds, names)):
+        safe = "".join(ch if ch.isalnum() or ch in "-_." else "_" for ch in name)
+        out_path = os.path.join(out_dir, f"narration-{safe}.mp3")
+
+        cmd = slice_command(src, start, None if k == len(bounds) - 1 else end, out_path, ffmpeg)
+        try:
+            result = subprocess.run(cmd, capture_output=True, text=True, timeout=timeout, stdin=subprocess.DEVNULL)
+        except subprocess.TimeoutExpired as exc:
+            raise RuntimeError(f"ffmpeg slice timed out after {timeout}s") from exc
+        if result.returncode != 0 or not os.path.exists(out_path):
+            raise RuntimeError(f"ffmpeg slice failed: {(result.stderr or '').strip()[:500]}")
+        paths.append(out_path)
+    return paths

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

@@ -70,6 +70,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)
@@ -1001,12 +1003,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 +1052,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 +1111,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"):
@@ -1441,6 +1461,178 @@ 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)
+    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 +1672,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()
@@ -1801,10 +2028,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)
 
@@ -1828,12 +2062,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 +2122,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

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 的同名字段；留空则跟随全局/服务端默认。" }
               }
             },