@remixmate/cli 0.9.24 → 0.9.26

package/README.md

@@ -268,6 +268,10 @@ npm run regress:update
 # Run only the render-plan snapshot layer:
 npm run test:render-plan
 
+# Narration speed wiring (gen_script → render plan → gen-voice --speed).
+# Fully offline: no registry, no TTS call.
+npm run test:narration-speed
+
 # L3 — selective, real Remotion render of chosen template(s). NOT full-library
 # by design (rendering is slow + needs asset generation). Catches crashes /
 # black frames the static layers can't. Needs PRIV_TOKEN for narration TTS;

package/dist/manifest.json

@@ -1,7 +1,7 @@
 {
   "schemaVersion": 1,
-  "version": "0.9.24",
-  "generatedAt": "2026-09-07T14:49:54.095Z",
+  "version": "0.9.26",
+  "generatedAt": "2026-09-13T00:51:13.551Z",
   "skills": [
     {
       "id": "export-jianying",
@@ -382,6 +382,10 @@
             "type": "string",
             "description": "Narration voice id. Default depends on the bound template's outputLanguage; query gen_voice with list_voices=true to see available ids."
           },
+          "speed": {
+            "type": "number",
+            "description": "Narration speech rate, 0.5-2.0 (default 1.0). Stored at global.narration.speed and applied when prepare_video_assets synthesizes the voice-over. **Must** pass when the user picked a speech rate — a template's 语速 / speed parameter arrives as a multiplier like 1.1, and without this flag it is silently dropped and the narration comes back at 1.0. Above ~1.3 subtitle alignment drifts and the delivery sounds mechanical; suggest shortening the script instead of raising it further."
+          },
           "template_id": {
             "type": "string",
             "description": "Template id (e.g. html-slide). The template owns outputLanguage and may also declare a defaultVoiceId; both flow into the produced DSL."
@@ -401,6 +405,13 @@
             },
             "description": "Media URLs for the template's image/video carousel. When provided together with a template_id whose capabilities.payloadStyle=carousel-caption, these URLs are placed directly into customPayload.carousel.items as existing assets — NO AI image generation is triggered. **Must** pass when the user explicitly provides image/video URLs for such a template. Each element is a full URL string."
           },
+          "scene_images": {
+            "type": "array",
+            "items": {
+              "type": "string"
+            },
+            "description": "Per-scene visuals for a visual-overlay template (image-slide etc.) — the counterpart of carousel_items for templates that have real scenes. Each element is EITHER a full URL (use that existing asset for the scene, no gen-image call) OR the literal string 'ai' / 'ai:<prompt>' (leave that scene to gen-image; the text after the colon, when present, is the user's own image prompt for it). Mapping is POSITIONAL: element i is scene i, so an AI scene can sit anywhere in the order — pass ['url1','ai','url2'] verbatim when the user arranged it that way. Scenes past the last element still get an AI-generated image, so 2 images still produce a full video. When `scenes` is not set the scene count is raised (never lowered) to fit the elements, so nothing the user arranged is dropped and handing over fewer images does not shrink the video. **Must** pass when the user supplies images for such a template — otherwise their images are ignored entirely and every scene is AI-generated. Do NOT pass for carousel-caption templates; those take carousel_items."
+          },
           "caption_lines": {
             "type": "array",
             "items": {
@@ -437,10 +448,12 @@
           "ratio",
           "scenes",
           "voice_id",
+          "speed",
           "template_id",
           "headline",
           "subheadline",
           "carousel_items",
+          "scene_images",
           "caption_lines",
           "stub_image_url",
           "stub_video_url",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@remixmate/cli",
-  "version": "0.9.24",
+  "version": "0.9.26",
   "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",
@@ -23,6 +23,7 @@
     "test:validators": "PYTHONDONTWRITEBYTECODE=1 python3 scripts/test-validators.py",
     "test:template-pipeline": "PYTHONDONTWRITEBYTECODE=1 node dist/cli.js exec -- python3 scripts/test-template-pipeline.py",
     "test:props-contract": "PYTHONDONTWRITEBYTECODE=1 python3 scripts/test-props-contract.py",
+    "test:narration-speed": "PYTHONDONTWRITEBYTECODE=1 python3 scripts/test-narration-speed.py",
     "test:render-plan": "PYTHONDONTWRITEBYTECODE=1 python3 scripts/test-render-plan-snapshot.py",
     "test:render-plan:update": "PYTHONDONTWRITEBYTECODE=1 python3 scripts/test-render-plan-snapshot.py --update",
     "test:contracts": "PYTHONDONTWRITEBYTECODE=1 python3 skills/template-registry/scripts/check_contracts.py",

package/skills/gen-script/SKILL.md

@@ -200,6 +200,110 @@ python3 <SkillDir>/scripts/gen_script.py \
 Every URL the user gave becomes one carousel item, in order. How long each item holds is the template's business — `fit-images` templates derive it from the item count, `fit-caption` templates from `capabilities.durationModel`; either way you pass the URLs and let the template decide.
 
 
+## Agent behavior: user-supplied images for scene-based templates (`--scene-images`)
+
+The section above covers `carousel-caption` templates. Templates whose `payloadStyle` is
+`visual-overlay` (image-slide and friends) have **real scenes**, each with its own background
+image and its own narration — for those, user-supplied images go through `--scene-images`,
+not `--carousel-items`.
+
+Without this flag the user's images are **ignored entirely** and every scene gets an
+AI-generated picture. That failure is quiet: the video renders fine, it just isn't made of
+the material the user handed you.
+
+### The mapping rule (positional, then AI fills the rest)
+
+Each entry is one scene's visual, and it is either a **URL** (use that existing asset) or the
+literal **`ai`** / **`ai:<prompt>`** (leave that scene to gen-image). Entry i is scene i;
+scenes past the last entry still get a generated image.
+
+```
+--scene-images A --scene-images B          →  scene 1: A, scene 2: B, scene 3+: AI-generated
+--scene-images A --scene-images ai:机房 …  →  scene 1: A, scene 2: AI with the user's prompt
+```
+
+Three consequences worth internalising:
+
+- **Two images still produce a full video.** Do not ask the user to "provide enough images"
+  or pad the list; partial input is the designed case.
+- **Order is meaning, not layout.** Pass the entries in the order the user gave them — an AI
+  scene can sit *between* two of their images, and that placement is the point.
+- **`ai:<prompt>` is the user's own image prompt for that one scene.** Pass it through
+  verbatim; do not rewrite it, and do not apply it to the other scenes. It replaces the
+  prompt that would have been derived from the template, but the template's negative prompt
+  still applies.
+
+When `--scenes` is absent the scene count is **raised, never lowered**, to fit the images:
+more images than the planned scene count grows the plan so none are dropped, but fewer images
+does **not** shrink it — handing over 2 images should not turn a 30s five-scene video into a
+three-scene one. If the template's scene count is fixed (`sceneStrategy: single` / `fixed`)
+and there are still more images than scenes, `gen_script.py` prints a warning naming how many
+went unused — surface that to the user instead of pretending everything was used.
+
+### Reading the image descriptions
+
+Asset lines in the user's message carry a **`desc:` field** describing what is in the picture:
+
+```
+![4519.png](https://cdn.example.com/4519.png) (1920×1080, desc: 一个人背对镜头站在雾中的松林里)
+```
+
+`desc:` is always the **last** item in the metadata parentheses, so everything from `desc:` to
+the closing paren is the description — commas inside it are part of the text.
+
+**Use it when writing narration.** This is the whole point of the field: for a
+`visual-overlay` template you are writing the words that play over *that* picture, and the
+description is the only thing telling you what the viewer will see. Narration that contradicts
+the image is the most visible way this pipeline fails.
+
+Two things `desc:` is **not**:
+
+- It is **not an image-generation prompt.** The asset already exists; never route it through
+  `gen-image`, and never "improve" the picture to match the text.
+- It is **not a headline.** Do not copy it onto the screen as `--headline` /
+  `--subheadline`; it is input for you, not on-screen copy.
+
+A line with no `desc:` simply has no description — do not treat the file name in the alt text
+(`4519.png`) as one.
+
+### Reading `ai:` lines
+
+A line in the asset list may be an **AI scene** rather than an asset:
+
+```
+![a.png](https://cdn.example.com/a.png) (1920×1080, desc: 终端里正在跑安装命令的截图)
+ai: 赛博朋克风格的服务器机房
+![b.png](https://cdn.example.com/b.png) (1920×1080)
+```
+
+That is the user saying "scene 2 is AI-generated, and here is what I want in it". Pass it
+straight through as the second `--scene-images` entry (`ai: 赛博朋克风格的服务器机房`),
+keeping the position. A bare `ai:` with no text means "this scene is AI-generated, you decide
+what it shows" — still pass it, as `ai`, so the position is preserved.
+
+Note the two are different fields on purpose: `desc:` describes an image that **already
+exists** (input for your narration), `ai:` prescribes an image that **does not exist yet**
+(input for gen-image). Never feed a `desc:` into gen-image, and never write narration that
+describes an `ai:` prompt as if it were a picture you have seen.
+
+### Command example
+
+User: "用 image-slide 做一条讲 RAG 的视频，配图用这两张"
++ two asset lines with `desc:`
+
+```bash
+python3 <SkillDir>/scripts/gen_script.py \
+  --topic "三分钟看懂 RAG" \
+  --template-id image-slide \
+  --scene-images "https://cdn.example.com/a.png" \
+  --scene-images "ai: 赛博朋克风格的服务器机房" \
+  --scene-images "https://cdn.example.com/b.png"
+```
+
+Then write each scene's narration against that scene's image description, and pass the
+narration through `prepare_video_assets`'s `dsl_json` as usual.
+
+
 ## Test mode: skip asset generation (`--stub-image-url` / `--stub-video-url`)
 
 **Purpose**: during dev / debug the user wants to exercise the whole pipeline without burning gen-image / gen-video quota. In the DSL this becomes: image / video AssetRefs are written as `source:"existing"` + `status:"generated"` + `url:<stub>`, no `payload.prompt`; the downstream `prepare-video-assets` resolver skips the matching atomic skill.
@@ -297,6 +401,7 @@ python3 <SkillDir>/scripts/gen_script.py \
 | `--ratio` | Aspect ratio. | `16:9` |
 | `--scenes` | Scene count. | auto-planned |
 | `--voice-id` | Narration voice id. | resolved from template + language fallback |
+| `--speed` | Narration speech rate (0.5–2.0), written to `global.narration.speed` and applied when `prepare_video_assets` calls gen-voice. Pass it whenever the user picked a speed (the replicate form's 语速 field sends one). Above ~1.3 subtitle alignment drifts and the delivery turns mechanical — shorten the script instead. | `1.0` |
 | `--allow-digital-human` | Whether to allow digital-human assets. | off |
 | `--allow-ai-video` | Whether to allow AI-generated video assets. | off |
 | `--validate` | Validate-only mode: only validate the input DSL. | — |
@@ -305,6 +410,7 @@ python3 <SkillDir>/scripts/gen_script.py \
 | `--stub-image-url` | Test mode: every image AssetRef is written as existing + generated + this URL, no prompt (env: `STUB_IMAGE_URL`). | — |
 | `--stub-video-url` | Test mode: every video AssetRef is written as existing + generated + this URL, no prompt (env: `STUB_VIDEO_URL`). | — |
 | `--carousel-items` | Repeatable. Media URL placed directly into `customPayload.carousel.items` for `carousel-caption` templates. Bypasses gen-image. **Required** for `carousel-caption` templates when the user supplies images. | — |
+| `--scene-images` | Repeatable. One scene's visual for a **`visual-overlay`** template (image-slide etc.), mapped **positionally**. Each entry is a URL (that existing asset) or `ai` / `ai:<prompt>` (that scene goes to gen-image, optionally with the user's own prompt) — so an AI scene can sit anywhere in the order. Scenes past the last entry still get AI images. Scene count is raised (never lowered) to fit the entries when `--scenes` is absent. **Required** whenever the user supplies images for such a template — omitting it silently ignores every image they gave. | — |
 | `--caption-lines` | Repeatable. On-screen caption line for `carousel-caption` templates → `customPayload.caption.lines`. Line limits and `**emphasis**` support are declared per template (see its `llmHint`). **Required** for `durationStrategy: fit-caption` templates — write the lines yourself if the user did not supply them. Optional only for `fit-images` templates. | — |
 
 ## DSL generation principles

package/skills/gen-script/scripts/gen_script.py

@@ -80,6 +80,24 @@ FALLBACK_VOICE = {
     "en": "english-male-friendly-01",
 }
 
+# ── Narration speed ───────────────────────────────────────────────────────────
+# Written to global.narration.speed; render_video copies it down into the
+# gen-voice asset payload (same route as narration text) and passes it to
+# `gen-voice --speed`. The envelope mirrors gen-voice's own 0.5–2.0 contract;
+# the real per-voice limits (capabilities speedMin/speedMax) are only known at
+# synthesis time, which is several confirmation steps and a few paid image
+# generations later — so an obviously-out-of-range value fails here instead.
+DEFAULT_NARRATION_SPEED = 1.0
+SPEED_MIN = 0.5
+SPEED_MAX = 2.0
+
+
+def _resolve_narration_speed(speed):
+    """CLI speed → the value written to global.narration.speed. Total function."""
+    if speed is None:
+        return DEFAULT_NARRATION_SPEED
+    return float(speed)
+
 
 def _resolve_template_language_meta(template_config):
     """Tolerant reader for outputLanguage / defaultVoiceId on a template dict.
@@ -313,6 +331,27 @@ def generate_image_prompt(
     return {"prompt": prompts.get(purpose, f"{topic}相关配图{style_suffix}")}
 
 
+def _parse_ai_slot(slot: str) -> tuple[bool, str]:
+    """解析 --scene-images 的一项：是不是 AI 段，以及用户给的提示词。
+
+    返回 ``(is_ai, prompt)``：
+
+      - ``"https://…/a.png"`` → ``(False, "")``  用已有素材
+      - ``"ai"``              → ``(True, "")``   这一段交给 gen-image，提示词由模板推
+      - ``"ai: 深色调机房"``   → ``(True, "深色调机房")``
+
+    大小写不敏感。判定刻意收得很紧（整项等于 ``ai``，或以 ``ai:`` 开头）：URL 才是这个
+    参数的常态，把 ``ai`` 判宽了会让 ``https://ai.example.com/x.png`` 这种正常地址被
+    误当成"生成一段"，用户的图就此消失。
+    """
+    text = (slot or "").strip()
+    if text.lower() == "ai":
+        return True, ""
+    if text[:3].lower() == "ai:":
+        return True, text[3:].strip()
+    return False, ""
+
+
 def _load_template_config(template_id: str) -> dict | None:
     """Load template definition for the given template ID.
 
@@ -729,6 +768,7 @@ def _build_carousel_caption_dsl(
     resolution: str,
     output_language: str,
     resolved_voice_id: str,
+    narration_speed: float,
     font_id: str | None,
     font_name: str | None,
     narration_enabled: bool,
@@ -886,7 +926,7 @@ def _build_carousel_caption_dsl(
             # 无配音模板：关闭 CC 字幕（字幕段是 narration→TTS 的派生物），
             # 并省略 global.narration，避免下游误判存在旁白。
             "subtitle": {"enabled": narration_enabled, "style": "bottom"},
-            **({"narration": {"voiceId": resolved_voice_id, "speed": 1.0}} if narration_enabled else {}),
+            **({"narration": {"voiceId": resolved_voice_id, "speed": narration_speed}} if narration_enabled else {}),
             **({"font": {"fontId": font_id, **({"fontName": font_name} if font_name else {})}} if font_id else {}),
             "bgm": {"enabled": True, "volume": 0.12},
         },
@@ -940,6 +980,7 @@ def build_dsl(
         scene_count: int | None,
         allow_digital_human: bool,
         allow_ai_video: bool,
+        speed: float | None = None,
         template_id: str | None = None,
         stub_image_url: str = "",
         stub_video_url: str = "",
@@ -947,6 +988,7 @@ def build_dsl(
         subheadline: str | None = None,
         carousel_items: list[str] | None = None,
         caption_lines: list[str] | None = None,
+        scene_images: list[str] | None = None,
 ) -> dict:
     """Build a complete Video DSL JSON.
 
@@ -965,6 +1007,15 @@ def build_dsl(
     通过 role=headline / role=subheadline 抽出对应的 props（如 titleText / projectName）。
     注意：subtitle（CC 字幕）由 global.subtitle 与 render-plan.subtitleSegments
     单独承载，与 subheadline 完全是两个东西，命名上刻意分开避免歧义。
+
+    scene_images 是用户**自带的配图**（visual-overlay 模板专用），按顺序占位：第 i 张
+    图给第 i 个场景，没被占到的场景照常走 gen-image 补图。这条规则不是随便定的——
+    见 docs/asset-annotation-design.md §6：另外两种立场（模型自由挑选 / 严格一一对应）
+    都会让"只传两张图"要么失去可预期性，要么直接跑不通。
+
+    speed 是旁白语速倍率，落在 global.narration.speed（不给 = 1.0）。它**不写进
+    gen-voice 资产的 payload**——与旁白文本同一条规矩：唯一来源在 DSL 上，
+    render_video 在调 TTS 前按 assetRef 回查注入，免得两处存一个值各自漂移。
     """
     # Load template config（registry 单一数据源）→ 归一化 contract
     template_config = _load_template_config(template_id) if template_id else None
@@ -983,6 +1034,7 @@ def build_dsl(
     # values fall back to "zh" so old templates keep their current behavior.
     output_language, template_default_voice_id = _resolve_template_language_meta(template_config)
     resolved_voice_id = _resolve_voice_id(voice_id, template_default_voice_id, output_language)
+    narration_speed = _resolve_narration_speed(speed)
     if resolved_voice_id != voice_id:
         print(
             f"ℹ️  voice resolution: cli={voice_id!r} → resolved={resolved_voice_id!r} "
@@ -1060,6 +1112,7 @@ def build_dsl(
             resolution=resolution,
             output_language=output_language,
             resolved_voice_id=resolved_voice_id,
+            narration_speed=narration_speed,
             font_id=font_id,
             font_name=font_name,
             narration_enabled=needs_narration,
@@ -1071,8 +1124,45 @@ def build_dsl(
         return carousel_dsl
 
     # ── 其余模板：统一场景规划（arc 叙事弧 / single / fixed）+ 统一装配循环 ──────
+    #
+    # scene_images 的每一项要么是一条 URL（用已有素材），要么是 `ai` / `ai:<提示词>`
+    # （这一段留给 gen-image）。两者共用同一个位置序列 —— 用户在界面上排出来的顺序
+    # 就是它，AI 段能插在任意位置，而不是只能挂在末尾。
+    provided_slots = [s.strip() for s in (scene_images or []) if s and s.strip()]
+
     scene_plans = _plan_contract_scenes(contract, topic, duration, scene_count, output_language)
 
+    # 条目比场景多时**抬高**场景数，让每一条都有地方放。
+    #
+    # 只抬高、不压低：给 2 张图不该把一条 30s 的片子从 5 段压成 3 段。用户给图表达的是
+    # "这几张都要用上"，不是"整条片子改成这么多段"——按条目数直接改写场景数，会让
+    # "多传了两张图"变成"视频结构被换掉了"，而他根本没要求这个。
+    #
+    # 反过来条目多于场景时必须抬：不抬的话第 N+1 条之后会被静默丢掉，而用户在成片里是
+    # 看不出"我的图去哪了"的。arc 之外的策略场景数由模板钉死，抬不动（下面警告兜底）。
+    if (
+        provided_slots
+        and scene_count is None
+        and contract["scene_strategy"] == "arc"
+        and primary_visual_type == "image"
+        and has_visual
+        and len(provided_slots) > len(scene_plans)
+    ):
+        scene_plans = _plan_contract_scenes(
+            contract, topic, duration, len(provided_slots), output_language
+        )
+
+    # 排完之后仍然装不下的（single / fixed 模板，或用户显式指定了更少的场景数）就明说。
+    # 静默丢弃用户自带的素材是这条链上最难被发现的一类错。
+    if provided_slots and len(provided_slots) > len(scene_plans):
+        print(
+            f"\u26a0\ufe0f  {len(provided_slots)} scene-image entries provided but the template "
+            f"plans only {len(scene_plans)} scene(s); the extra "
+            f"{len(provided_slots) - len(scene_plans)} will not be used. "
+            f"Raise --scenes or pick a template with more scenes.",
+            file=sys.stderr,
+        )
+
     assets = []
     scenes = []
 
@@ -1091,7 +1181,22 @@ def build_dsl(
 
         # 仅 visual-overlay 模板生成视觉素材（slide 无视觉素材，carousel-caption 已提前返回）
         if has_visual and primary_visual_type == "image":
-            if stub_image_url:
+            slot = provided_slots[idx] if idx < len(provided_slots) else ""
+            slot_is_ai, slot_prompt = _parse_ai_slot(slot)
+            if slot and not slot_is_ai:
+                # 用户自带的图排在 stub 之前：stub 是"别烧配额"的测试开关，而用户给的
+                # 图同样一分钱不花，没有理由拿占位图把真素材盖掉。
+                assets.append({
+                    "assetId": visual_asset_id,
+                    "type": "image",
+                    "source": "existing",
+                    "status": "generated",
+                    "url": slot,
+                })
+            # stub 盖得住 AI 段，盖不住用户自带的图。差别在于花不花钱：--stub-image-url
+            # 的全部意义就是"这一趟别调 gen-image"，而 AI 段恰恰是要调的那种；反过来
+            # 用户自带的 URL 一分钱不花，拿占位图把真素材盖掉纯属损失。
+            elif stub_image_url:
                 assets.append({
                     "assetId": visual_asset_id,
                     "type": "image",
@@ -1102,6 +1207,13 @@ def build_dsl(
             else:
                 image_result = generate_image_prompt(plan["purpose"], topic, style, narration_text=narration_text)
 
+                # 用户在 AI 段里写了提示词就用他的。**只替换主体，不动 negativePrompt /
+                # guidanceScale**：那两项是模板的护栏（"不要文字水印、不要变形"），把它们
+                # 一起丢掉会让用户随手写的一句话换来一张带乱码文字的图，而他并没有要求
+                # 关掉护栏——他只是想说这一段画什么。
+                if slot_prompt:
+                    image_result = {**image_result, "prompt": slot_prompt}
+
                 img_payload = {
                     "prompt": image_result["prompt"],
                     "model": os.environ.get("DEFAULT_IMAGE_MODEL", "doubao/doubao-seedream-5-0-260128"),
@@ -1291,7 +1403,7 @@ def build_dsl(
             # 无配音模板：关闭 CC 字幕（字幕段是 narration→TTS 的派生物），并省略
             # global.narration，避免下游误判存在旁白。
             "subtitle": {"enabled": needs_narration, "style": "bottom"},
-            **({"narration": {"voiceId": resolved_voice_id, "speed": 1.0}} if needs_narration else {}),
+            **({"narration": {"voiceId": resolved_voice_id, "speed": narration_speed}} if needs_narration else {}),
             **({"font": {"fontId": font_id, **({"fontName": font_name} if font_name else {})}} if font_id else {}),
             "bgm": {"enabled": True, "volume": 0.12},
         },
@@ -1331,6 +1443,17 @@ Examples:
     parser.add_argument("--resolution", default="1080p", help="Resolution (default: 1080p)")
     parser.add_argument("--scenes", type=int, default=None, help="Scene count (default: auto-planned)")
     parser.add_argument("--voice-id", default=None, help="Narration voice id. When omitted, the resolver picks template.defaultVoiceId, then the language-keyed fallback (zh→Chinese (Mandarin)_Male_Announcer, en→TBD English voice). gen_voice --list-voices --local prints the language-tagged catalog.")
+    parser.add_argument(
+        "--speed",
+        type=float,
+        default=None,
+        help=(
+            f"Narration speech rate ({SPEED_MIN}-{SPEED_MAX}, default {DEFAULT_NARRATION_SPEED}). "
+            "Stored at global.narration.speed and applied by render_video when it calls gen-voice. "
+            "Above ~1.3 subtitle alignment starts to drift and the delivery turns mechanical — "
+            "shorten the script instead."
+        ),
+    )
     parser.add_argument(
         "--font-id",
         default=None,
@@ -1383,6 +1506,20 @@ Examples:
              "these URLs are placed directly into "
              "customPayload.carousel.items as existing assets, bypassing AI image generation entirely.",
     )
+    parser.add_argument(
+        "--scene-images",
+        action="append",
+        default=None,
+        help="One scene's visual for a visual-overlay template (image-slide etc.). "
+             "Can be repeated: --scene-images url1 --scene-images ai --scene-images url2. "
+             "Each entry is either a URL (use that existing asset) or the literal 'ai' / "
+             "'ai:<prompt>' (leave this scene to gen-image, optionally with the user's prompt). "
+             "Mapping is POSITIONAL: the i-th entry is the i-th scene's background, so an AI "
+             "scene can sit anywhere in the order, not just at the end; scenes past the last "
+             "entry still get an AI-generated image. When --scenes is not given the scene count "
+             "is raised (never lowered) to fit the entries. "
+             "Not for carousel-caption templates — those take --carousel-items instead.",
+    )
     parser.add_argument(
         "--caption-lines",
         action="append",
@@ -1421,6 +1558,15 @@ Examples:
         parser.print_help()
         sys.exit(1)
 
+    if args.speed is not None and not (SPEED_MIN <= args.speed <= SPEED_MAX):
+        print(
+            f"❌ --speed must be in the range {SPEED_MIN}~{SPEED_MAX} (got {args.speed}).\n"
+            "   Speech rate is a multiplier, not a percentage: 1.0 is the voice's own pace, "
+            "1.1 is slightly brisker.",
+            file=sys.stderr,
+        )
+        sys.exit(1)
+
     # ── 模板感知的 ratio 自动推导 ────────────────────────────────────────────
     # 用户没显式传 --ratio 时：
     #   1. 若指定了 --template-id，取模板 supportedAspectRatios[0]（避免横竖屏不匹配）
@@ -1452,6 +1598,8 @@ Examples:
     print(f"   platform: {args.platform}", file=sys.stderr)
     print(f"   duration: {args.duration}s", file=sys.stderr)
     print(f"   ratio: {args.ratio}", file=sys.stderr)
+    if args.speed is not None:
+        print(f"   narration speed: {args.speed}x", file=sys.stderr)
 
     # CLI flag takes precedence; env vars act as fallback with a visible warning
     # so silent cross-session leakage is always observable.
@@ -1492,6 +1640,7 @@ Examples:
         ratio=args.ratio,
         resolution=args.resolution,
         voice_id=args.voice_id,
+        speed=args.speed,
         font_id=args.font_id,
         font_name=args.font_name,
         scene_count=args.scenes,
@@ -1504,6 +1653,7 @@ Examples:
         subheadline=args.subheadline,
         carousel_items=args.carousel_items,
         caption_lines=args.caption_lines,
+        scene_images=args.scene_images,
     )
 
     # Post-process for --skip-asset-generation: rewrite all gen-voice / gen-digital-human

package/skills/gen-script/skill.json

@@ -52,6 +52,10 @@
         "type": "string",
         "description": "Narration voice id. Default depends on the bound template's outputLanguage; query gen_voice with list_voices=true to see available ids."
       },
+      "speed": {
+        "type": "number",
+        "description": "Narration speech rate, 0.5-2.0 (default 1.0). Stored at global.narration.speed and applied when prepare_video_assets synthesizes the voice-over. **Must** pass when the user picked a speech rate — a template's 语速 / speed parameter arrives as a multiplier like 1.1, and without this flag it is silently dropped and the narration comes back at 1.0. Above ~1.3 subtitle alignment drifts and the delivery sounds mechanical; suggest shortening the script instead of raising it further."
+      },
       "template_id": {
         "type": "string",
         "description": "Template id (e.g. html-slide). The template owns outputLanguage and may also declare a defaultVoiceId; both flow into the produced DSL."
@@ -71,6 +75,13 @@
         },
         "description": "Media URLs for the template's image/video carousel. When provided together with a template_id whose capabilities.payloadStyle=carousel-caption, these URLs are placed directly into customPayload.carousel.items as existing assets — NO AI image generation is triggered. **Must** pass when the user explicitly provides image/video URLs for such a template. Each element is a full URL string."
       },
+      "scene_images": {
+        "type": "array",
+        "items": {
+          "type": "string"
+        },
+        "description": "Per-scene visuals for a visual-overlay template (image-slide etc.) — the counterpart of carousel_items for templates that have real scenes. Each element is EITHER a full URL (use that existing asset for the scene, no gen-image call) OR the literal string 'ai' / 'ai:<prompt>' (leave that scene to gen-image; the text after the colon, when present, is the user's own image prompt for it). Mapping is POSITIONAL: element i is scene i, so an AI scene can sit anywhere in the order — pass ['url1','ai','url2'] verbatim when the user arranged it that way. Scenes past the last element still get an AI-generated image, so 2 images still produce a full video. When `scenes` is not set the scene count is raised (never lowered) to fit the elements, so nothing the user arranged is dropped and handing over fewer images does not shrink the video. **Must** pass when the user supplies images for such a template — otherwise their images are ignored entirely and every scene is AI-generated. Do NOT pass for carousel-caption templates; those take carousel_items."
+      },
       "caption_lines": {
         "type": "array",
         "items": {
@@ -107,10 +118,12 @@
       "ratio",
       "scenes",
       "voice_id",
+      "speed",
       "template_id",
       "headline",
       "subheadline",
       "carousel_items",
+      "scene_images",
       "caption_lines",
       "stub_image_url",
       "stub_video_url",

package/skills/gen-script/version.json

@@ -2,6 +2,6 @@
   "skillName": "gen-script",
   "repoName": "agent-skill-media-maker",
   "skillId": "474",
-  "version": "V11",
+  "version": "V12",
   "skillDescription": "Video-script generation skill. Turns a user-supplied topic into a structured Video DSL (JSON) that describes the full video — scene structure, asset requirements, and narrative flow.\n\nUse this skill as soon as the user mentions any of these intents:\n- Write a video script, generate a video script, plan a video, write storyboards\n- Create a short video, plan video content, generate a Video DSL\n- Turn a topic into a video structure / video content plan\n\nEven when the user does not say \"generate the DSL\", use this skill whenever they want to turn a topic into a structured video plan.\n\n⚠️ Stop-and-confirm gate: after this skill returns a DSL, show the full script and wait for the user's explicit confirmation. Never call `prepare_video_assets` in the same turn."
 }

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

@@ -159,6 +159,22 @@ RESOLUTION_MAP = {
 }
 
 
+def _narration_speed(narration: dict) -> Optional[float]:
+    """Read a narration block's speech-rate multiplier, or None when unset.
+
+    Tolerant on purpose: the DSL is hand-editable, and a malformed speed must
+    not take down a render that would otherwise be fine — it falls back to the
+    voice's own pace. 0 and negatives are treated as unset for the same reason
+    ab-api does (`speed: 0` there means "follow the global setting").
+    """
+    if not isinstance(narration, dict):
+        return None
+    raw = narration.get("speed")
+    if isinstance(raw, bool) or not isinstance(raw, (int, float)):
+        return None
+    return float(raw) if raw > 0 else None
+
+
 def extract_narration_lines(narration: dict) -> Optional[tuple[list[str], int, list[Optional[float]]]]:
     """If narration uses the structured {intro, items, outro} form, return
     (lines, intro_line_count, at_sec_list). `at_sec_list` is parallel to
@@ -621,6 +637,8 @@ def build_render_plan(dsl: dict, binding: dict) -> dict:
     # so adjust_timeline_to_audio can later auto-derive highlightMap from
     # per-line TTS timestamps.
     dsl_assets_by_id = {a["assetId"]: a for a in dsl.get("assets", [])}
+    global_narration = (dsl.get("global") or {}).get("narration") or {}
+    global_speed = _narration_speed(global_narration)
     for scene in dsl.get("scenes", []):
         narration = (scene.get("audio") or {}).get("narration") or {}
         ref = narration.get("assetRef")
@@ -628,6 +646,15 @@ def build_render_plan(dsl: dict, binding: dict) -> dict:
         if not asset:
             continue
         payload = asset.setdefault("payload", {})
+        # Speech rate follows the same route as the narration text: single source
+        # of truth on the DSL, copied down here because resolve_asset_audio only
+        # ever sees the asset. Scene-level overrides global (mirrors the narration
+        # editor's "行级覆盖 > 全局"); neither set = gen-voice's own 1.0 default.
+        speed = _narration_speed(narration)
+        if speed is None:
+            speed = global_speed
+        if speed is not None:
+            payload["speed"] = speed
         extracted = extract_narration_lines(narration)
         if extracted:
             lines, intro_lines, _ = extracted
@@ -862,6 +889,11 @@ def resolve_asset_audio(asset: dict, private_token: str, timeout: int) -> dict:
     cmd.extend(["--text", tts_text, "--json-output"])
     if payload.get("voiceId"):
         cmd.extend(["--voice-id", payload["voiceId"]])
+    # Injected by build_render_plan from the DSL (scene narration > global).
+    # Absent = let gen-voice apply its own default rather than pinning 1.0 here.
+    speed = _narration_speed(payload)
+    if speed is not None:
+        cmd.extend(["--speed", str(speed)])
     if private_token:
         cmd.extend(["--priv-token", private_token])
 

package/skills/render-video/version.json

@@ -2,6 +2,6 @@
   "skillName": "render-video",
   "repoName": "agent-skill-media-maker",
   "skillId": "473",
-  "version": "V19",
+  "version": "V20",
   "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."
 }