@starreel/mcp 0.1.110 → 0.1.112

package/SKILL.md

@@ -258,7 +258,13 @@ content that will be rejected.
    `native_voice_anchor` lists `unanchored_speakers` (not locked yet) and
    `stale_shots` (made before the lock — `regenerate_shot_video` them). Decide
    the voice reference early; picking it after the whole episode is rendered
-   means redoing shots.
+   means redoing shots. The shot's line field may be empty — then the actual
+   audio decides: a calibrated speech probe must hear a voice in the chosen
+   window, and its transcript becomes the anchor text (`text_source:
+   "transcript"`); no voice or no usable transcript is refused. Call it with
+   `preview: true` first: you get `preview_url` and the anchor text without
+   anything being written, then call again without `preview` (same
+   `start_s` / `dur_s`) to lock it.
 
    **No sample? Design one.** `design_voice` turns a one-sentence description
    (age, gender, timbre, pace, mood — say what you want, not what you don't)
@@ -829,6 +835,21 @@ error from `replace_shot_dialogue`) — re-voicing can't fix them; regenerate th
 shot instead.
 Either way, `compose_episode` afterwards — the final cut still holds the old audio until you do.
 
+**Narration / voice-over is a separate track — use `revoice_narration`, not
+`replace_shot_dialogue`.** On clip-audio projects the narration is mixed into the
+shot's video when it is generated, so `replace_shot_dialogue` refuses
+narration-only shots ("no on-screen line to replace"). To change the narrator's
+voice, set it first (`set_character_voice` on the narrator character, or
+`design_voice`), or edit the narration line with `update_shot`, then call
+`revoice_narration`: it keeps the picture and on-screen lines, silences only the
+narration spans, re-synthesises them in the current voice, mixes them back and
+re-checks — no video regeneration. Shots that mix on-screen lines and narration
+work only when the clause count matches the speech spans heard in the clip;
+otherwise it refuses rather than guess (a wrong guess would silence an actor).
+If the vendor *spoke on its own* in a shot with no lines at all, use
+`replace_shot_dialogue` with `mute_only: true` (free; on clip-audio projects it
+silences any narration in that shot too).
+
 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
@@ -1058,7 +1079,12 @@ to close") tells the vendor to fit that entire sequence into each 3-second shot.
   `design_voice` → `get_voice_design` → `save_designed_voice` (no sample needed),
   `speak_with_voice`, `set_character_voice`, `list_voices`, `delete_voice`,
   `generate_bgm` (optional `prompt` steers the music; read `get_bgm_prompt_guide` first),
-  `get_bgm_prompt_guide`, `replace_shot_dialogue`
+  `get_bgm_prompt_guide`, `replace_shot_dialogue`, `revoice_narration`
+- **Mix** (free; settings only — `compose_episode` again to hear them, `rerender_episode`
+  reuses the old timeline): whole drama via `update_project_settings`
+  (`bgm_volume_preset` / `bgm_volume_db` / `lufs_target`); one episode via
+  `set_episode_audio`; one music section's level and fades via `list_bgm_cues` →
+  `update_bgm_cue`. Don't download the cut to re-mix it locally.
 - **Finish**: `compose_episode`, `get_final_cut`, `get_export`,
   `generate_episode_poster`, `generate_cover`
 - **What did this drama cost?** `get_drama_bill` — per kind `charged` / `refunded`
@@ -1161,6 +1187,7 @@ Full reference: https://api.shortreelai.com/docs/mcp
 - `ready` 和生成数量只表示产物存在；当前有效数量使用 `get_pipeline_status.asset_versions_summary.*.current_effective`。换帧后旧视频仍可查看，但失效版本不能混入当前有效汇总。
 - `get_asset_versions(storyboard_id)` 查看历史版本链接、依赖 ID/版本哈希及各自状态。历史没有快照时不从当前绑定伪造依赖。
 - `get_image_dispatch(image_id)` 查一张镜头帧的派发台账：每张参考图的用途、所属角色、是否送达模型，派发前被剔的图在哪一步因什么被剔（如时代预检点名的冲突物件），以及最终发给模型的提示词。画面「不像某角色/少了某道具」时先查它，确认是参考没送到还是模型没画对，再决定改什么；`ledger` 不是 `full` 时缺失项为 `null`，不能当作已送达。
+- `get_stale_portrait_frames(episode_id)` 换定妆图后查影响范围：列出在用帧仍基于角色旧资产的镜头，每条附证据（`ledger-old-asset` / `references-previous-asset` / `portrait-born-after-frame`）。`unknown` 是证据不足，不是已过期，不要据此批量重出。先把 `stale` 清单和 `has_video` 告诉客户，由客户决定重出哪些镜——重出帧和视频都要付费。
 - `get_asset_binding_repair_plan(episode_id)` 只返回缺失场景绑定的候选和依据，`applied=false`。必须逐项审核，不按名字自动回填，也不自动重新生成客户已完成的片子。
 
 ### Original product lettering

package/dist/tools/produce.js

@@ -255,6 +255,7 @@ const PROJECT_SETTINGS_FIELDS = {
     bgm_source: z.enum(['own', 'clip']).optional().describe("BGM来源:own=自有BGM流水线(默认,抑制裸片BGM);clip=保留视频原生BGM、终拼不叠加"),
     bgm_volume_preset: z.enum(['off', 'low', 'auto', 'high']).optional().describe('BGM音量档:off静音/low轻(-28dB)/auto自适应(默认,静段可闻·对白不压麦)/high强'),
     bgm_volume_db: z.number().optional().describe('自定义BGM音量(dB,负值),覆盖预设档、关自适应'),
+    lufs_target: z.number().min(-23).max(-10).optional().describe('成片整体响度目标(LUFS,默认-16;越接近0越响)。终拼母带按它处理,改完需 compose_episode 重新合成'),
     use_clip_audio: z.boolean().optional().describe('用视频原声(★默认开):true/不传=跳过TTS配音直接用视频自带声;false=改回TTS配音。所有类型默认视频原声,建剧时应主动告知客户可切换配音(★直接改成片音频)'),
     // 字幕(烧录/双语/仅译文/位置/边距/动效)
     show_subtitles: z.boolean().optional().describe('字幕烧录总开关:false=不烧字幕轨'),
@@ -527,6 +528,7 @@ export function registerProduceTools(server, client) {
     })));
     server.tool('get_frame_retry_diagnosis', '免费只读查询图片任务的连败诊断、证据任务 ID 和下一步动作。diagnosis_required 时先调用本工具：审计故障重审已有候选，未知原因先复核；不得原样重抽或擅自改剧本。', { image_id: z.number().int().positive() }, async ({ image_id }) => jsonResult(await client.produceGet(`/images/${image_id}/diagnosis`)));
     server.tool('get_image_dispatch', '免费只读查询一张镜头帧的派发台账：实际用了哪几张参考图、每张的用途与所属角色、是否送达模型、没送达或派发前被剔除的是哪一步因什么被剔（如时代预检点名的冲突物件），以及真正发给图片模型的最终提示词。用于回答「到底用了哪张图、为什么画面不像」；先查清再决定是否重出，别靠猜反复付费重抽。ledger=partial/none 表示该图生成于台账上线前，缺失字段如实为 null。', { image_id: z.number().int().positive() }, async ({ image_id }) => jsonResult(await client.produceGet(`/images/${image_id}/dispatch`)));
+    server.tool('get_stale_portrait_frames', '免费只读查询一集里哪些镜头的在用首帧/尾帧，是拿角色已被换掉的旧资产（旧定妆图、旧设定图、旧身体/发型图）画的。换定妆图后用它确认影响范围，再由客户决定重出哪些镜（重出要付费，本工具不改任何数据）。verdict=stale 必附证据：ledger-old-asset（派发台账直接记录用了旧图）/ references-previous-asset（参考图里有该角色以前的旧资产）/ portrait-born-after-frame（当前定妆图晚于该帧诞生）；证不了的标 unknown 并给原因，不当作已过期。has_video=true 表示该镜视频也基于旧帧，重出帧后视频需重生。', { episode_id: z.number().int().positive() }, async ({ episode_id }) => jsonResult(await client.produceGet(`/episodes/${episode_id}/stale-portrait-frames`)));
     server.tool('get_asset_versions', '只读查询一个镜头的全部图片/视频版本、历史查看链接、依赖 ID 与版本哈希，以及已生成→与当前输入一致→审核有效→已采用四项独立事实。历史缺少依赖记录时显示未知，不补造快照。免费。', { storyboard_id: z.number().int().positive() }, async ({ storyboard_id }) => jsonResult(await client.produceGet(`/storyboards/${storyboard_id}/asset-versions`)));
     server.tool('get_asset_binding_repair_plan', '只读生成一集历史缺失场景绑定的可审核修复提案。返回原始地点/时段、候选 ID、匹配依据、歧义和 proposed_scene_id；applied=false，绝不按名字自动回填。逐项核对后才由客户决定是否改绑。免费。', { episode_id: z.number().int().positive() }, async ({ episode_id }) => jsonResult(await client.produceGet(`/episodes/${episode_id}/asset-binding-repair-plan`)));
     server.tool('get_storyboards', '读某一集的分镜列表(供审阅/查进度)。含每镜首帧(first_frame_image)与视频(video_url)是否就绪。' +
@@ -1338,7 +1340,14 @@ export function registerProduceTools(server, client) {
         '★该镜已有对口型产物时,成片优先用对口型版,换轨不会生效。整集批量用 repair_episode_dialogue。' +
         '\n★写回前会对产物复核(与 scan_dialogue_coverage 同一判据):换完仍断音(truncated)、重复念/多念(extra_speech)、' +
         '念的不是台词(off_script)→ **不写回**、本次费用自动退回,返回错误说明哪一类——这类镜换音修不好,改用 regenerate_shot_video。' +
-        '成功时返回 verify:verified=false 表示没判出来(转写失败/台词太短),照常写回但没复核过,自己听一下。', { storyboard_id: z.number().int().positive() }, async ({ storyboard_id }) => jsonResult(await client.producePost(`/storyboards/${storyboard_id}/dialogue-replace`)));
+        '成功时返回 verify:verified=false 表示没判出来(转写失败/台词太短),照常写回但没复核过,自己听一下。', { storyboard_id: z.number().int().positive(), mute_only: z.boolean().optional().describe('只静音、不重配(不扣费):把视频原声里的人声段静掉。用于厂商在**没有台词的镜里自己念出声**的情况。★原声剧上本镜的旁白也在原声里,会一起被静掉——要换旁白用 revoice_narration,别用它') }, async ({ storyboard_id, mute_only }) => jsonResult(await client.producePost(`/storyboards/${storyboard_id}/dialogue-replace`, mute_only ? { mode: 'mute' } : {})));
+    server.tool('revoice_narration', '换某镜**旁白/画外音**的声音(或改过旁白文字后重配)。**不重新生成视频**:保留画面与出镜台词,只把旁白那几段静掉、' +
+        '按当前旁白声音重新合成并混回,再复核。同步调用,按 TTS 档(千字符)计费。' +
+        '★先改好再调:想换声音先 set_character_voice 给「旁白」角色(没有就 design_voice 造一个),想改文字先 update_shot 改 dialogue 里的旁白行。' +
+        '★纯旁白镜(本镜只有旁白)直接可用;**混合镜**(既有出镜台词又有旁白)要求分句数与视频里的语音段数一致,' +
+        '对不上就报错不猜(猜错会把出镜台词一起静掉)——这时只能 regenerate_shot_video。' +
+        '★台词栏没有旁白行会直接报错;厂商在无台词镜里乱念,用 replace_shot_dialogue 的 mute_only。' +
+        '★写回后成片会直接用它(不需要额外开关),rerender_episode 重拼即可;复核不通过不写回,旁白合成费不退。', { storyboard_id: z.number().int().positive() }, async ({ storyboard_id }) => jsonResult(await client.producePost(`/storyboards/${storyboard_id}/dialogue-replace`, { mode: 'narration' })));
     server.tool('repair_episode_dialogue', '★整集批量修「台词没念完/念了别的」。默认只修 scan_dialogue_coverage 判为有缺陷的镜' +
         '(truncated/off_script/extra_speech);minor_gap 那一族是转写误差、原声本来是好的,不动。' +
         '原理与 replace_shot_dialogue 相同:克隆音重配整句 + 静音原声段,**不重新生成视频**——' +
@@ -1353,9 +1362,11 @@ export function registerProduceTools(server, client) {
         only_flagged: z.boolean().optional()
             .describe('默认 true=只修被判有缺陷的镜。传 false 会把全集可替换镜都重配一遍——既花钱又可能把本来对的音频换坏,除非确有需要别关'),
         force: z.boolean().optional().describe('对已有替换产物的镜也重跑(默认跳过,幂等)'),
-    }, async ({ episode_id, only_flagged, force }) => jsonResult(await client.producePost(`/episodes/${episode_id}/dialogue-repair`, {
+        mute_only: z.boolean().optional().describe('只静音、不重配(不扣费):把视频原声里的人声段静掉。用于厂商在**没有台词的镜里自己念出声**的情况。★原声剧上本镜的旁白也在原声里,会一起被静掉——要换旁白用 revoice_narration,别用它'),
+    }, async ({ episode_id, only_flagged, force, mute_only }) => jsonResult(await client.producePost(`/episodes/${episode_id}/dialogue-repair`, {
         ...(only_flagged === undefined ? {} : { only_flagged }),
         ...(force ? { force: true } : {}),
+        ...(mute_only ? { mute_only: true } : {}),
     })));
     server.tool('get_dialogue_repair_status', '查台词修复的进度(免费)。repair_episode_dialogue 是后台异步串行跑的,用这个轮询。'
         + '\n★这个工具此前**不存在**,而 repair_episode_dialogue 的描述里却写着「进度用 '
@@ -1384,6 +1395,25 @@ export function registerProduceTools(server, client) {
         ...(prompt === undefined ? {} : { prompt }),
         ...(prompt_mode ? { prompt_mode } : {}),
     })));
+    server.tool('set_episode_audio', '设置**本集**配乐音量(覆盖整剧设定,免费)。整剧统一的用 update_project_settings。' +
+        '★只改设置:成片要 compose_episode 重新合成才变(rerender_episode 用旧时间线,不带上)。' +
+        '★想调某一段配乐的音量或淡入淡出,用 list_bgm_cues + update_bgm_cue。', {
+        episode_id: z.number().int().positive(),
+        bgm_volume_preset: z.enum(['off', 'low', 'auto', 'high', 'inherit']).optional()
+            .describe('本集配乐音量档:off静音/low轻(-28dB)/auto自适应/high强(-16dB)/inherit跟随整剧'),
+        bgm_volume_db: z.number().min(-60).max(0).nullable().optional()
+            .describe('本集自定义配乐音量(dB,-60~0),覆盖档位并关自适应;null=清除、跟随整剧'),
+    }, async ({ episode_id, ...rest }) => jsonResult(await client.producePut(`/episodes/${episode_id}/audio`, rest)));
+    server.tool('list_bgm_cues', '列出本集的配乐段(AI 配乐按情绪分幕,每段覆盖一段镜号 sb_from~sb_to):id、覆盖范围、gain_db(null=跟随音量档)、fade_in_ms / fade_out_ms。' +
+        'episode_id 为 null 的是**整剧共用段**,改它会影响所有集。免费。', { episode_id: z.number().int().positive() }, async ({ episode_id }) => jsonResult(await client.produceGet(`/episodes/${episode_id}/bgm-cues`)));
+    server.tool('update_bgm_cue', '调某一段配乐的音量与淡入淡出(免费)。只改这三项;换曲目或改覆盖范围用 generate_bgm 重新生成。' +
+        '★例:配乐进得太突兀→加大 fade_in_ms;某段压对白→降 gain_db。改完 compose_episode 重新合成才生效。', {
+        episode_id: z.number().int().positive(),
+        cue_id: z.number().int().positive().describe('来自 list_bgm_cues'),
+        gain_db: z.number().min(-60).max(0).nullable().optional().describe('这段配乐的音量(dB,-60~0),设了就覆盖音量档;null=恢复跟随本集/整剧音量档'),
+        fade_in_ms: z.number().int().min(0).max(15000).optional().describe('淡入毫秒(整数,0~15000)'),
+        fade_out_ms: z.number().int().min(0).max(15000).optional().describe('淡出毫秒(整数,0~15000)'),
+    }, async ({ episode_id, cue_id, ...rest }) => jsonResult(await client.producePut(`/episodes/${episode_id}/bgm-cues/${cue_id}`, rest)));
     server.tool('get_bgm_prompt_guide', '取「AI 配乐提示词」的书写规范:两个档位怎么选、该写哪些维度(附可照抄的示例)、' +
         '哪些是写了也不会生效的硬限制(纯器乐/时长/不做音效/不复刻具体曲目)、常见写坏的方式。' +
         '免费,纯静态,与具体剧目无关——写 generate_bgm 的 prompt 之前先读它,别自己猜。' +
@@ -1791,11 +1821,15 @@ export function registerProduceTools(server, client) {
         '\n★选哪一镜:该角色**独自说话、台词较长、没有背景音乐和别人插话**的镜;start_s/dur_s 可只截其中一段(不传则取默认窗口,时长会按各引擎上限自动钳制)。' +
         '\n★只对**之后**生成的视频生效。锁之前已经出好的镜会出现在 get_pipeline_status 的 native_voice_anchor.stale_shots 里,' +
         '用 regenerate_shot_video 重出才会统一。所以最省的做法是:每个说话角色先出一镜、选定声线,再批量出其余镜。' +
+        '\n★台词栏为空也能用:以实际音频为准——平台用已标定的人声探测确认所选区间里有人声,并把转写文字当锚文本;' +
+        '探测不到人声、或转写不出可用文字就拒(锚选错会污染此后所有镜的嗓音,宁拒不猜)。响应里 text_source 标明文本来自台词还是转写。' +
+        '\n★先 preview:true 试听:只截取并返回 preview_url 与锚文本,**不写入角色**;听着对再去掉 preview、用同样的 start_s/dur_s 正式提交。' +
         '\n★有客户授权的外部音源时改用 clone_voice + set_character_voice;两者二选一,后设的覆盖先设的。', {
         character_id: z.number().int().positive(),
-        storyboard_id: z.number().int().positive().describe('本剧里有该角色台词、已出视频的镜'),
+        storyboard_id: z.number().int().positive().describe('本剧里已出视频、该角色在里面说话的镜(台词栏为空时以实际音频为准)'),
         start_s: z.number().min(0).optional().describe('可选:从该镜第几秒开始截'),
         dur_s: z.number().positive().optional().describe('可选:截多长(秒)'),
+        preview: z.boolean().optional().describe('true=只截取试听、返回 preview_url 与锚文本,不写入角色。建议先试听再正式提交'),
     }, async ({ character_id, ...rest }) => jsonResult(await client.producePost(`/characters/${character_id}/voice-anchor-from-shot`, rest)));
     // ── 素材交接包：客户自己拼片的通道 ──────────────────────────────────────
     // 与 compose_episode 的分工：compose_episode = 「平台替你拼」；本组工具 = 「素材给你，

package/openapi.json

@@ -2,8 +2,8 @@
   "openapi": "3.1.0",
   "info": {
     "title": "StarReel Production API",
-    "version": "0.1.110",
-    "description": "Turn a script into a finished, downloadable short-drama episode over REST.\n\nPipeline: script → AI rewrite → cast/scenes/props extraction → storyboards → portraits & sheets + scene plates → 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. For images the quote is a *range* — models billed per reference image are priced before those are assembled, so `estimated_points` is the upper bound (size the balance by it and a run never dies half-way) and `typical_points` is the usual cost; fixed-price models return the two equal. 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.110 tool surface (operationIds match MCP tool names 1:1)."
+    "version": "0.1.112",
+    "description": "Turn a script into a finished, downloadable short-drama episode over REST.\n\nPipeline: script → AI rewrite → cast/scenes/props extraction → storyboards → portraits & sheets + scene plates → 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. For images the quote is a *range* — models billed per reference image are priced before those are assembled, so `estimated_points` is the upper bound (size the balance by it and a run never dies half-way) and `typical_points` is the usual cost; fixed-price models return the two equal. 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.112 tool surface (operationIds match MCP tool names 1:1)."
   },
   "servers": [
     {
@@ -567,7 +567,7 @@
       "post": {
         "operationId": "set_voice_anchor_from_shot",
         "summary": "从本剧某一镜选定角色的声线(声音基准)",
-        "description": "从本剧某一镜选定角色的声线(声音基准)。免费。不需要客户提供外部音源——就用片子里这个角色已经念出来的声音。\n★★【原声剧(use_clip_audio=true,默认)里这就是「锁声线」】选定后,之后生成的视频会把这段声音交给视频厂商当参考音频,同一角色前后镜的嗓音跟它走;不锁的话每镜由厂商各自采样,前后镜声线会漂。\n★选哪一镜:该角色**独自说话、台词较长、没有背景音乐和别人插话**的镜;start_s/dur_s 可只截其中一段(不传则取默认窗口,时长会按各引擎上限自动钳制)。\n★只对**之后**生成的视频生效。锁之前已经出好的镜会出现在 get_pipeline_status 的 native_voice_anchor.stale_shots 里,用 regenerate_shot_video 重出才会统一。所以最省的做法是:每个说话角色先出一镜、选定声线,再批量出其余镜。\n★有客户授权的外部音源时改用 clone_voice + set_character_voice;两者二选一,后设的覆盖先设的。",
+        "description": "从本剧某一镜选定角色的声线(声音基准)。免费。不需要客户提供外部音源——就用片子里这个角色已经念出来的声音。\n★★【原声剧(use_clip_audio=true,默认)里这就是「锁声线」】选定后,之后生成的视频会把这段声音交给视频厂商当参考音频,同一角色前后镜的嗓音跟它走;不锁的话每镜由厂商各自采样,前后镜声线会漂。\n★选哪一镜:该角色**独自说话、台词较长、没有背景音乐和别人插话**的镜;start_s/dur_s 可只截其中一段(不传则取默认窗口,时长会按各引擎上限自动钳制)。\n★只对**之后**生成的视频生效。锁之前已经出好的镜会出现在 get_pipeline_status 的 native_voice_anchor.stale_shots 里,用 regenerate_shot_video 重出才会统一。所以最省的做法是:每个说话角色先出一镜、选定声线,再批量出其余镜。\n★台词栏为空也能用:以实际音频为准——平台用已标定的人声探测确认所选区间里有人声,并把转写文字当锚文本;探测不到人声、或转写不出可用文字就拒(锚选错会污染此后所有镜的嗓音,宁拒不猜)。响应里 text_source 标明文本来自台词还是转写。\n★先 preview:true 试听:只截取并返回 preview_url 与锚文本,**不写入角色**;听着对再去掉 preview、用同样的 start_s/dur_s 正式提交。\n★有客户授权的外部音源时改用 clone_voice + set_character_voice;两者二选一,后设的覆盖先设的。",
         "tags": [
           "characters"
         ],
@@ -592,7 +592,7 @@
                   "storyboard_id": {
                     "type": "integer",
                     "exclusiveMinimum": 0,
-                    "description": "本剧里有该角色台词、已出视频的镜"
+                    "description": "本剧里已出视频、该角色在里面说话的镜(台词栏为空时以实际音频为准)"
                   },
                   "start_s": {
                     "type": "number",
@@ -601,6 +601,9 @@
                   "dur_s": {
                     "type": "number",
                     "exclusiveMinimum": 0
+                  },
+                  "preview": {
+                    "type": "boolean"
                   }
                 },
                 "required": [
@@ -816,6 +819,11 @@
                   "bgm_volume_db": {
                     "type": "number"
                   },
+                  "lufs_target": {
+                    "type": "number",
+                    "minimum": -23,
+                    "maximum": -10
+                  },
                   "use_clip_audio": {
                     "type": "boolean"
                   },
@@ -1151,6 +1159,11 @@
                   "bgm_volume_db": {
                     "type": "number"
                   },
+                  "lufs_target": {
+                    "type": "number",
+                    "minimum": -23,
+                    "maximum": -10
+                  },
                   "use_clip_audio": {
                     "type": "boolean"
                   },
@@ -3259,6 +3272,80 @@
         }
       }
     },
+    "/episodes/{episode_id}/audio": {
+      "put": {
+        "operationId": "set_episode_audio",
+        "summary": "设置**本集**配乐音量(覆盖整剧设定,免费)",
+        "description": "设置**本集**配乐音量(覆盖整剧设定,免费)。整剧统一的用 update_project_settings。★只改设置:成片要 compose_episode 重新合成才变(rerender_episode 用旧时间线,不带上)。★想调某一段配乐的音量或淡入淡出,用 list_bgm_cues + update_bgm_cue。",
+        "tags": [
+          "episodes"
+        ],
+        "parameters": [
+          {
+            "name": "episode_id",
+            "in": "path",
+            "required": true,
+            "schema": {
+              "type": "integer",
+              "exclusiveMinimum": 0
+            }
+          }
+        ],
+        "requestBody": {
+          "required": false,
+          "content": {
+            "application/json": {
+              "schema": {
+                "type": "object",
+                "properties": {
+                  "bgm_volume_preset": {
+                    "type": "string",
+                    "enum": [
+                      "off",
+                      "low",
+                      "auto",
+                      "high",
+                      "inherit"
+                    ]
+                  },
+                  "bgm_volume_db": {
+                    "type": "number",
+                    "minimum": -60,
+                    "maximum": 0
+                  }
+                }
+              }
+            }
+          }
+        },
+        "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}/audit-seams": {
       "post": {
         "operationId": "audit_seams",
@@ -3440,6 +3527,137 @@
         }
       }
     },
+    "/episodes/{episode_id}/bgm-cues": {
+      "get": {
+        "operationId": "list_bgm_cues",
+        "summary": "列出本集的配乐段(AI 配乐按情绪分幕,每段覆盖一段镜号 sb_from~sb_to):id、覆盖范围、gain_db(null=跟随音量档)、fade_in_ms / fade_out_ms",
+        "description": "列出本集的配乐段(AI 配乐按情绪分幕,每段覆盖一段镜号 sb_from~sb_to):id、覆盖范围、gain_db(null=跟随音量档)、fade_in_ms / fade_out_ms。episode_id 为 null 的是**整剧共用段**,改它会影响所有集。免费。",
+        "tags": [
+          "episodes"
+        ],
+        "parameters": [
+          {
+            "name": "episode_id",
+            "in": "path",
+            "required": true,
+            "schema": {
+              "type": "integer",
+              "exclusiveMinimum": 0
+            }
+          }
+        ],
+        "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}/bgm-cues/{cue_id}": {
+      "put": {
+        "operationId": "update_bgm_cue",
+        "summary": "调某一段配乐的音量与淡入淡出(免费)",
+        "description": "调某一段配乐的音量与淡入淡出(免费)。只改这三项;换曲目或改覆盖范围用 generate_bgm 重新生成。★例:配乐进得太突兀→加大 fade_in_ms;某段压对白→降 gain_db。改完 compose_episode 重新合成才生效。",
+        "tags": [
+          "episodes"
+        ],
+        "parameters": [
+          {
+            "name": "episode_id",
+            "in": "path",
+            "required": true,
+            "schema": {
+              "type": "integer",
+              "exclusiveMinimum": 0
+            }
+          },
+          {
+            "name": "cue_id",
+            "in": "path",
+            "required": true,
+            "schema": {
+              "type": "integer",
+              "exclusiveMinimum": 0,
+              "description": "来自 list_bgm_cues"
+            }
+          }
+        ],
+        "requestBody": {
+          "required": false,
+          "content": {
+            "application/json": {
+              "schema": {
+                "type": "object",
+                "properties": {
+                  "gain_db": {
+                    "type": "number",
+                    "minimum": -60,
+                    "maximum": 0
+                  },
+                  "fade_in_ms": {
+                    "type": "integer",
+                    "minimum": 0,
+                    "maximum": 15000
+                  },
+                  "fade_out_ms": {
+                    "type": "integer",
+                    "minimum": 0,
+                    "maximum": 15000
+                  }
+                }
+              }
+            }
+          }
+        },
+        "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}/bgm-status": {
       "get": {
         "operationId": "get_bgm_status",
@@ -4043,6 +4261,9 @@
                   },
                   "force": {
                     "type": "boolean"
+                  },
+                  "mute_only": {
+                    "type": "boolean"
                   }
                 }
               }
@@ -6663,6 +6884,53 @@
         }
       }
     },
+    "/episodes/{episode_id}/stale-portrait-frames": {
+      "get": {
+        "operationId": "get_stale_portrait_frames",
+        "summary": "免费只读查询一集里哪些镜头的在用首帧/尾帧，是拿角色已被换掉的旧资产（旧定妆图、旧设定图、旧身体/发型图）画的",
+        "description": "免费只读查询一集里哪些镜头的在用首帧/尾帧，是拿角色已被换掉的旧资产（旧定妆图、旧设定图、旧身体/发型图）画的。换定妆图后用它确认影响范围，再由客户决定重出哪些镜（重出要付费，本工具不改任何数据）。verdict=stale 必附证据：ledger-old-asset（派发台账直接记录用了旧图）/ references-previous-asset（参考图里有该角色以前的旧资产）/ portrait-born-after-frame（当前定妆图晚于该帧诞生）；证不了的标 unknown 并给原因，不当作已过期。has_video=true 表示该镜视频也基于旧帧，重出帧后视频需重生。",
+        "tags": [
+          "episodes"
+        ],
+        "parameters": [
+          {
+            "name": "episode_id",
+            "in": "path",
+            "required": true,
+            "schema": {
+              "type": "integer",
+              "exclusiveMinimum": 0
+            }
+          }
+        ],
+        "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}/storyboards": {
       "get": {
         "operationId": "get_storyboards",
@@ -9815,6 +10083,22 @@
             }
           }
         ],
+        "requestBody": {
+          "required": false,
+          "content": {
+            "application/json": {
+              "schema": {
+                "type": "object",
+                "properties": {
+                  "mode": {
+                    "type": "string",
+                    "description": "(assembled by the client from tool args — see tool 'replace_shot_dialogue')"
+                  }
+                }
+              }
+            }
+          }
+        },
         "responses": {
           "200": {
             "description": "StarReel envelope",
@@ -9840,7 +10124,10 @@
           "402": {
             "description": "Insufficient prepaid balance (never overdrafts); response carries `needed` points"
           }
-        }
+        },
+        "x-also-tools": [
+          "revoice_narration"
+        ]
       }
     },
     "/storyboards/{storyboard_id}/edit/generate": {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@starreel/mcp",
-  "version": "0.1.110",
+  "version": "0.1.112",
   "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.110",
+  "version": "0.1.112",
   "websiteUrl": "https://starreel.ai",
   "packages": [
     {
       "registryType": "npm",
       "identifier": "@starreel/mcp",
-      "version": "0.1.110",
+      "version": "0.1.112",
       "transport": {
         "type": "stdio"
       },