@starreel/mcp 0.1.84 → 0.1.85

package/SKILL.md

@@ -206,6 +206,15 @@ content that will be rejected.
    character with `set_character_voice` only when you actually need it to
    dub a shot. Always pass that same `voice_id` — never a raw number from
    somewhere else.
+   **In native-audio dramas (`use_clip_audio=true`, the default) binding the
+   customer's own authorized voice is how you lock a character's voice**:
+   videos generated *after* the binding hand that voice to the video vendor as
+   a reference audio, so the character sounds the same in every shot (public
+   library voices are TTS-only and are not sent). Trade-off: that character's
+   shots stop using the portrait-video anchor, so identity rests on the
+   portrait/sheet — have those ready first. Bind **before** `generate_videos`;
+   for videos that already exist, use `repair_episode_dialogue`
+   (`only_flagged=false`) rather than regenerating whole episodes.
 
 6. **Follow the pipeline order — do not skip.** `set_script` → `rewrite_script`
    → `extract_assets` → portraits **+ sheets** → storyboards → frames → videos.

package/dist/tools/guide-data.js

@@ -95,8 +95,11 @@ export const ENTRY_POINTS = [
             'set_character_voice(绑到角色;传 voice_id 如 lib:12)',
             'assign_voices',
         ],
-        note: '所有项目默认视频原声(use_clip_audio=true,跳过 TTS);要配音把它设 false,并主动告诉客户可切换。',
-        flow: 'clone_voice → speak_with_voice(试听) → set_character_voice / assign_voices',
+        note: '所有项目默认视频原声(use_clip_audio=true,跳过 TTS);要配音把它设 false,并主动告诉客户可切换。' +
+            '★原声剧里 set_character_voice 绑客户自己的授权音色 = 锁声线:之后出的视频把它交给厂商当参考音频,前后镜声线一致;' +
+            '代价是该角色的镜不再喂定妆视频锚、身份靠定妆图/设定图。只对绑定之后出的视频生效——先绑再出视频;' +
+            '已出好的视频用 repair_episode_dialogue(only_flagged=false)换轨统一,别整集重生。',
+        flow: 'clone_voice → speak_with_voice(试听) → set_character_voice(原声剧:在 generate_videos 之前) / assign_voices',
     },
     {
         customer_has: '歌曲 + 歌词(MV)',

package/dist/tools/produce.js

@@ -1209,7 +1209,9 @@ export function registerProduceTools(server, client) {
         '★它也是「这一镜台词没念完/念了别的」最经济的修法:用克隆音重配整句并静音原声段,' +
         '**不重新生成视频**——按 TTS 档(千字符)计费,比 regenerate_shot_video(720p 212 点/秒)低几个数量级。' +
         '代价:画面口型是按原音演的,换音后可能对不上;口型看不清的镜(背身/远景/画外)几乎无损,大特写慎用。' +
-        '整集批量用 repair_episode_dialogue。', { storyboard_id: z.number().int().positive() }, async ({ storyboard_id }) => jsonResult(await client.producePost(`/storyboards/${storyboard_id}/dialogue-replace`)));
+        '★产物自动写回该镜(返回 persisted:true),但**进不进成片**取决于本集是否每镜都已合成:' +
+        '用 get_dialogue_repair_status 看 productEffective / pendingCompose,为 false 就先补合成再 rerender_episode,' +
+        '否则成片仍是旧音频。整集批量用 repair_episode_dialogue。', { storyboard_id: z.number().int().positive() }, async ({ storyboard_id }) => jsonResult(await client.producePost(`/storyboards/${storyboard_id}/dialogue-replace`)));
     server.tool('repair_episode_dialogue', '★整集批量修「台词没念完/念了别的」。默认只修 scan_dialogue_coverage 判为有缺陷的镜' +
         '(truncated/off_script/extra_speech);minor_gap 那一族是转写误差、原声本来是好的,不动。' +
         '原理与 replace_shot_dialogue 相同:克隆音重配整句 + 静音原声段,**不重新生成视频**——' +
@@ -1316,6 +1318,7 @@ export function registerProduceTools(server, client) {
     // ========== P1 · 整集配音(成片前的强制音频步)==========
     server.tool('assign_voices', '★给本集所有角色分配音色(配音导演 agent 按性别/性格/年龄/角色定位+项目语言选)。' +
         'voiceStyle 不是提取时自动填的——不分配,generate_tts 就没音色。文本步(LLM)后付。' +
+        '已用 set_character_voice 绑了客户自己授权音色的角色会被锁定、不会被改成别的音色。' +
         '后台异步,轮询 get_pipeline_status:assign_voices=done 即完成,再 generate_tts。', { episode_id: z.number().int().positive() }, async ({ episode_id }) => jsonResult(await client.producePost(`/episodes/${episode_id}/assign-voices`)));
     server.tool('generate_tts', '给整集所有对白批量配音(TTS)。成片前的音频步——不配音成片会缺对白。前置:先 assign_voices 给角色分配音色。后台异步,按用量后付不欠费。', { episode_id: z.number().int().positive() }, async ({ episode_id }) => jsonResult(await client.producePost(`/episodes/${episode_id}/tts`)));
     // ========== P1 · MV 子流程(project_type=mv 专用)==========
@@ -1508,7 +1511,17 @@ export function registerProduceTools(server, client) {
     server.tool('list_voices', '列出可用音色:我克隆的私有音色 + 平台公共音色(voice_id/名字/试听样本)。免费。', {}, async () => jsonResult(await client.produceGet('/voice-clones')));
     server.tool('delete_voice', '删除我音色库里的一个克隆音色(平台公共音色不可删)。免费。', { voice_id: z.string().describe('形如 lib:12') }, async ({ voice_id }) => jsonResult(await client.produceDelete(`/voice-clones/${String(voice_id).replace(/^lib:/, '')}`)));
     server.tool('set_character_voice', '把音色绑到某角色,之后 generate_tts 用它给该角色配音。免费。' +
-        '只有要出片时才需要这步——克隆和试听都不需要角色。', {
+        '只有要出片时才需要这步——克隆和试听都不需要角色。' +
+        '\n★★【原声剧(use_clip_audio=true,默认)里这一步就是「锁声线」】绑的是**客户自己的授权音色**' +
+        '(clone_voice 克隆的 / 客户上传的,不是公共音色)时,之后生成的视频会把这段声音直接交给视频厂商当参考音频,' +
+        '厂商按它发声、口型天然同步——否则每个组/单镜各自采样嗓音,同一角色前后镜声线会漂。' +
+        '公共音色只用于 TTS 配音,不会交给厂商。' +
+        '\n★代价:该角色出场的镜头生成视频时不再喂定妆视频锚(参考视频的音轨会压过参考音频,只能二选一),' +
+        '人物身份改由定妆图/设定图承担——所以绑之前先确认定妆图、设定图已经到位。' +
+        '\n★只对**绑定之后**生成的视频生效:要先绑、再 generate_videos。已经出好的视频要统一声线,' +
+        '用 repair_episode_dialogue(only_flagged=false,克隆音重配整句、不重生视频、按 TTS 档计费)最省;' +
+        '重生视频(regenerate_shot_video)也行但贵几个数量级。' +
+        '\n★绑好后 assign_voices 不会再覆盖这个角色(客户自己的声音优先级最高)。', {
         character_id: z.number().int().positive(),
         voice_id: z.string().describe('来自 clone_voice / list_voices 的 voice_id(形如 lib:12)'),
     }, async ({ character_id, voice_id }) => jsonResult(await client.producePost(`/characters/${character_id}/voice`, { voice_id })));

package/openapi.json

@@ -2,8 +2,8 @@
   "openapi": "3.1.0",
   "info": {
     "title": "StarReel Production API",
-    "version": "0.1.84",
-    "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.84 tool surface (operationIds match MCP tool names 1:1)."
+    "version": "0.1.85",
+    "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.85 tool surface (operationIds match MCP tool names 1:1)."
   },
   "servers": [
     {
@@ -493,7 +493,7 @@
       "post": {
         "operationId": "set_character_voice",
         "summary": "把音色绑到某角色,之后 generate_tts 用它给该角色配音",
-        "description": "把音色绑到某角色,之后 generate_tts 用它给该角色配音。免费。只有要出片时才需要这步——克隆和试听都不需要角色。",
+        "description": "把音色绑到某角色,之后 generate_tts 用它给该角色配音。免费。只有要出片时才需要这步——克隆和试听都不需要角色。\n★★【原声剧(use_clip_audio=true,默认)里这一步就是「锁声线」】绑的是**客户自己的授权音色**(clone_voice 克隆的 / 客户上传的,不是公共音色)时,之后生成的视频会把这段声音直接交给视频厂商当参考音频,厂商按它发声、口型天然同步——否则每个组/单镜各自采样嗓音,同一角色前后镜声线会漂。公共音色只用于 TTS 配音,不会交给厂商。\n★代价:该角色出场的镜头生成视频时不再喂定妆视频锚(参考视频的音轨会压过参考音频,只能二选一),人物身份改由定妆图/设定图承担——所以绑之前先确认定妆图、设定图已经到位。\n★只对**绑定之后**生成的视频生效:要先绑、再 generate_videos。已经出好的视频要统一声线,用 repair_episode_dialogue(only_flagged=false,克隆音重配整句、不重生视频、按 TTS 档计费)最省;重生视频(regenerate_shot_video)也行但贵几个数量级。\n★绑好后 assign_voices 不会再覆盖这个角色(客户自己的声音优先级最高)。",
         "tags": [
           "characters"
         ],
@@ -2835,7 +2835,7 @@
       "post": {
         "operationId": "assign_voices",
         "summary": "★给本集所有角色分配音色(配音导演 agent 按性别/性格/年龄/角色定位+项目语言选)",
-        "description": "★给本集所有角色分配音色(配音导演 agent 按性别/性格/年龄/角色定位+项目语言选)。voiceStyle 不是提取时自动填的——不分配,generate_tts 就没音色。文本步(LLM)后付。后台异步,轮询 get_pipeline_status:assign_voices=done 即完成,再 generate_tts。",
+        "description": "★给本集所有角色分配音色(配音导演 agent 按性别/性格/年龄/角色定位+项目语言选)。voiceStyle 不是提取时自动填的——不分配,generate_tts 就没音色。文本步(LLM)后付。已用 set_character_voice 绑了客户自己授权音色的角色会被锁定、不会被改成别的音色。后台异步,轮询 get_pipeline_status:assign_voices=done 即完成,再 generate_tts。",
         "tags": [
           "episodes"
         ],
@@ -8348,7 +8348,7 @@
       "post": {
         "operationId": "replace_shot_dialogue",
         "summary": "换某镜对白音色/声线(转写+克隆重配)",
-        "description": "换某镜对白音色/声线(转写+克隆重配)。后台异步,按用量后付不欠费。要求本镜有原声视频+角色声线定妆音。★它也是「这一镜台词没念完/念了别的」最经济的修法:用克隆音重配整句并静音原声段,**不重新生成视频**——按 TTS 档(千字符)计费,比 regenerate_shot_video(720p 212 点/秒)低几个数量级。代价:画面口型是按原音演的,换音后可能对不上;口型看不清的镜(背身/远景/画外)几乎无损,大特写慎用。整集批量用 repair_episode_dialogue。",
+        "description": "换某镜对白音色/声线(转写+克隆重配)。后台异步,按用量后付不欠费。要求本镜有原声视频+角色声线定妆音。★它也是「这一镜台词没念完/念了别的」最经济的修法:用克隆音重配整句并静音原声段,**不重新生成视频**——按 TTS 档(千字符)计费,比 regenerate_shot_video(720p 212 点/秒)低几个数量级。代价:画面口型是按原音演的,换音后可能对不上;口型看不清的镜(背身/远景/画外)几乎无损,大特写慎用。★产物自动写回该镜(返回 persisted:true),但**进不进成片**取决于本集是否每镜都已合成:用 get_dialogue_repair_status 看 productEffective / pendingCompose,为 false 就先补合成再 rerender_episode,否则成片仍是旧音频。整集批量用 repair_episode_dialogue。",
         "tags": [
           "storyboards"
         ],

package/package.json

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