@starreel/mcp 0.1.49 → 0.1.50

package/SKILL.md

@@ -351,7 +351,19 @@ The table above is for **generation failures**. A different class of report is
 
 ### "话没说完就切" / a line gets cut off mid-word
 
-Three distinct causes; check in this order, they need opposite fixes.
+**By far the most common cause is #2 — the vendor's clip never said the whole
+line.** Measured across the whole platform (2026-09-01, 282 audited shots with
+dialogue): 28% have a real defect, and *half of those shots were long enough for
+the line*. So do not start by lengthening shots.
+
+Run **`scan_dialogue_coverage`** (free) first — it tells you which of the causes
+below you actually have, per shot. `compose_episode` also reports the affected
+shots as advisory `dialogue_truncated`. Both read the same measurement: a
+word-level comparison of what the clip's audio says against the shot's line.
+Note `never_audited` in the report — those shots have never been measured, which
+is not the same as passing; `rescan: true` measures them (costs ASR time).
+
+Four distinct causes; they need **opposite** fixes, so identify the family first.
 
 1. **The line moved after the video was made.** If you edited `dialogue` on a
    shot whose video already existed, the video still speaks the *old* line —
@@ -360,11 +372,21 @@ Three distinct causes; check in this order, they need opposite fixes.
    `compose_episode` reports these as advisory `stale_video_after_edit`.
    **Fix:** `regenerate_shot_video` those shots, then compose. Never just
    re-compose — no amount of re-cutting can change what the video says.
-2. **The vendor never said the whole line.** When a shot is too short for the
-   line, native-audio engines just stop where they stop. Check the shot's own
-   clip, not the final cut. **Fix:** lengthen the shot (`update_shot.duration`)
-   and regenerate, or split it (`split_shot`).
-3. **The transition ate the tail.** A cross-fade pulls the *next* shot's start
+2. **The vendor stopped partway through the line** (family `truncated` — the
+   audio *is* the line, just not all of it). **Fix:** `regenerate_shot_video`;
+   vendors are non-deterministic about how much they say, so a re-roll often
+   lands the full line. Lengthening (`update_shot.duration`) is a second resort,
+   not the first move: the platform already raises a shot's duration to fit its
+   line whenever the shot is saved, so "too short for the line" is rarely what
+   actually happened.
+3. **The vendor said something other than the line** (family `off_script` — most
+   of the audio does not match the script at all: invented lines, repeats of the
+   previous shot, or just room tone). Lengthening does nothing here. **Fix:**
+   `regenerate_shot_video`; if the same drama keeps producing this, switch
+   engine. Measured per-engine rate of shots whose line was not delivered in
+   full: `seedance-2.5` 23% · `wan3.0` 44% · `hailuo-3` 50% (30 shots, small
+   sample). For dialogue-heavy work prefer `seedance-2.5`.
+4. **The transition ate the tail.** A cross-fade pulls the *next* shot's start
    backwards, covering the end of the current one. The platform now shortens or
    drops that transition automatically so it can never cover a spoken word, so
    you should not see this any more — if you do, report it.

package/dist/tools/produce.js

@@ -602,6 +602,31 @@ export function registerProduceTools(server, client) {
         + '实测 WAN 11/12 镜有镜内跳切、Seedance 1/6、H3 0/5,且提示词层拦不住(负向约束已在其中)——'
         + '要根治只能 regenerate_shot_video 这些镜并换 seedance-2.5 或 hailuo-3。'
         + '组模式镜与显式快剪蒙太奇镜天然多机位,已自动排除(detail 里标 skipped)。', { episode_id: z.number().int().positive() }, async ({ episode_id }) => jsonResult(await client.produceGet(`/episodes/${episode_id}/intra-shot-cuts`)));
+    server.tool('scan_dialogue_coverage', '★客户报「话没说完就切 / 台词只念了一半」时先跑这个。默认**免费零扣费**(只读已落库的转录审计结果)。'
+        + '把该集每个原声镜的视频音轨与台词做词级比对,按族给出结论:'
+        + 'truncated(念到一半就停) / off_script(念的大半不是台词:自说自话、重复上一镜、只有环境音) / '
+        + 'extra_speech(台词念全了但还多念) / minor_gap(零星缺词,属转写误差,不必管) / ok。'
+        + '★判读:三个可上报的族**处置方向不同**,别一律加长镜头——实测镜长够的镜里仍有 21% 没念全,'
+        + '「太短」很少是真因(平台保存分镜时已按台词自动抬时长)。truncated/off_script 的正解都是'
+        + ' regenerate_shot_video(厂商每次说多少是随机的,重掷常能拿到整句);同一剧反复 off_script 则换引擎。'
+        + '★never_audited 是本报告最重要的一栏:那些镜从没被检测过,「没测过」不等于「没问题」。'
+        + 'rescan=true 会对它们补跑 ASR 比对(耗算力、非瞬时,limit 控制单次上限),默认不跑。'
+        + 'TTS 配音镜不在范围内(TTS 必然念全,低覆盖率只会是转写误差)。'
+        + '同一集若还伴随「切太快」,那是另一回事,跑 scan_intra_shot_cuts。', {
+        episode_id: z.number().int().positive(),
+        rescan: z.boolean().optional()
+            .describe('对从未检测过的镜补跑转写比对(耗算力,非瞬时)。默认 false = 只读已有结果'),
+        limit: z.number().int().positive().max(60).optional()
+            .describe('rescan 单次补测镜数上限,默认 20、最大 60;被上限截掉的镜数在响应 rescan_skipped_by_limit 里明说'),
+    }, async ({ episode_id, rescan, limit }) => {
+        const qs = new URLSearchParams();
+        if (rescan)
+            qs.set('rescan', '1');
+        if (limit != null)
+            qs.set('limit', String(limit));
+        const suffix = qs.toString() ? `?${qs.toString()}` : '';
+        return jsonResult(await client.produceGet(`/episodes/${episode_id}/dialogue-coverage${suffix}`));
+    });
     server.tool('update_shot', '逐镜编辑:改单个分镜的文本内容(景别/动作/台词/画面描述/运镜等)与角色绑定(character_ids)。只传要改的字段、其余不动。' +
         '**免费**(纯文本写库)。★改 dialogue 会自动失效本镜已生成的 TTS 配音与字幕(需重出 tts);' +
         '改文本不会自动重出图/视频,如需让画面跟上文本改动,改完再 regen 对应镜。用 get_storyboards 查改后结果。' +

package/openapi.json

@@ -2,8 +2,8 @@
   "openapi": "3.1.0",
   "info": {
     "title": "StarReel Production API",
-    "version": "0.1.49",
-    "description": "Turn a script into a finished, downloadable short-drama episode over REST.\n\nPipeline: script → AI rewrite → cast/scenes/props extraction → portraits & sheets → storyboards → keyframes → video shots → TTS → final cut (.mp4).\n\n**Billing is prepaid and agent-safe**: big-ticket stages are quote-then-generate (`quote_*` returns a `quote_id`; for video, quote == actual charge). Insufficient balance returns 402 — nothing half-runs and the account never goes negative.\n\nAuth: exchange your API key at `POST /v1/agent/token` for a 15-minute bearer token.\n\nGenerated from the @starreel/mcp v0.1.49 tool surface (operationIds match MCP tool names 1:1)."
+    "version": "0.1.50",
+    "description": "Turn a script into a finished, downloadable short-drama episode over REST.\n\nPipeline: script → AI rewrite → cast/scenes/props extraction → portraits & sheets → storyboards → keyframes → video shots → TTS → final cut (.mp4).\n\n**Billing is prepaid and agent-safe**: big-ticket stages are quote-then-generate (`quote_*` returns a `quote_id`; for video, quote == actual charge). Insufficient balance returns 402 — nothing half-runs and the account never goes negative.\n\nAuth: exchange your API key at `POST /v1/agent/token` for a 15-minute bearer token.\n\nGenerated from the @starreel/mcp v0.1.50 tool surface (operationIds match MCP tool names 1:1)."
   },
   "servers": [
     {
@@ -2645,6 +2645,71 @@
         }
       }
     },
+    "/episodes/{episode_id}/dialogue-coverage": {
+      "get": {
+        "operationId": "scan_dialogue_coverage",
+        "summary": "★客户报「话没说完就切 / 台词只念了一半」时先跑这个",
+        "description": "★客户报「话没说完就切 / 台词只念了一半」时先跑这个。默认**免费零扣费**(只读已落库的转录审计结果)。把该集每个原声镜的视频音轨与台词做词级比对,按族给出结论:truncated(念到一半就停) / off_script(念的大半不是台词:自说自话、重复上一镜、只有环境音) / extra_speech(台词念全了但还多念) / minor_gap(零星缺词,属转写误差,不必管) / ok。★判读:三个可上报的族**处置方向不同**,别一律加长镜头——实测镜长够的镜里仍有 21% 没念全,「太短」很少是真因(平台保存分镜时已按台词自动抬时长)。truncated/off_script 的正解都是 regenerate_shot_video(厂商每次说多少是随机的,重掷常能拿到整句);同一剧反复 off_script 则换引擎。★never_audited 是本报告最重要的一栏:那些镜从没被检测过,「没测过」不等于「没问题」。rescan=true 会对它们补跑 ASR 比对(耗算力、非瞬时,limit 控制单次上限),默认不跑。TTS 配音镜不在范围内(TTS 必然念全,低覆盖率只会是转写误差)。同一集若还伴随「切太快」,那是另一回事,跑 scan_intra_shot_cuts。",
+        "tags": [
+          "episodes"
+        ],
+        "parameters": [
+          {
+            "name": "episode_id",
+            "in": "path",
+            "required": true,
+            "schema": {
+              "type": "integer",
+              "exclusiveMinimum": 0
+            }
+          },
+          {
+            "name": "rescan",
+            "in": "query",
+            "required": false,
+            "schema": {
+              "type": "string"
+            }
+          },
+          {
+            "name": "limit",
+            "in": "query",
+            "required": false,
+            "schema": {
+              "type": "integer",
+              "exclusiveMinimum": 0,
+              "maximum": 60
+            }
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "StarReel envelope",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "type": "object",
+                  "properties": {
+                    "code": {
+                      "type": "integer"
+                    },
+                    "message": {
+                      "type": "string"
+                    },
+                    "data": {
+                      "description": "Operation result payload"
+                    }
+                  }
+                }
+              }
+            }
+          },
+          "402": {
+            "description": "Insufficient prepaid balance (never overdrafts); response carries `needed` points"
+          }
+        }
+      }
+    },
     "/episodes/{episode_id}/effects": {
       "post": {
         "operationId": "generate_effects",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@starreel/mcp",
-  "version": "0.1.49",
+  "version": "0.1.50",
   "mcpName": "ai.starreel/starreel",
   "description": "StarReel MCP server — drive the AI short-drama production pipeline (script → storyboards → frames → video → final cut) from Claude, Cursor, or any MCP client",
   "license": "MIT",

package/server.json

@@ -2,13 +2,13 @@
   "$schema": "https://static.modelcontextprotocol.io/schemas/2025-09-29/server.schema.json",
   "name": "ai.starreel/starreel",
   "description": "Turn a script into a finished, downloadable short-drama episode — via MCP or REST.",
-  "version": "0.1.49",
+  "version": "0.1.50",
   "websiteUrl": "https://starreel.ai",
   "packages": [
     {
       "registryType": "npm",
       "identifier": "@starreel/mcp",
-      "version": "0.1.49",
+      "version": "0.1.50",
       "transport": {
         "type": "stdio"
       },