@starreel/mcp 0.1.133 → 0.1.135

package/SKILL.md

@@ -1103,13 +1103,15 @@ to close") tells the vendor to fit that entire sequence into each 3-second shot.
 - **Audio**: `generate_tts` (required before final cut), `clone_voice`,
   `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; optional `director` hard-locks mood / instruments / bpm / tonality for the whole episode or per act — call the free read-only `get_bgm_plan` first to see the acts),
+  `generate_bgm` (optional `prompt` steers the music; read `get_bgm_prompt_guide` first; optional `director` hard-locks mood / instruments / bpm / tonality for the whole episode or per act — call the free read-only `get_bgm_plan` first to see the acts; to let the client pick between full-length versions, `quote_bgm_candidates` → `generate_bgm` with `candidates` 2–3 + `quote_id` → `select_bgm_candidate`, each candidate billed per song),
   `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.
+  `set_episode_audio` (music level, plus `clip_audio_gain_db` for the clips' own sound and
+  `voice_gain_db` for the TTS dialogue + narration track); one music section's level, fades,
+  where in the track it starts (`track_offset_ms`) and how late after its first shot it comes in
+  (`start_shift_ms`) 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`

package/dist/tools/guide-data.js

@@ -240,7 +240,7 @@ export const PIPELINE = [
     },
     {
         step: '9 音频',
-        tools: ['assign_voices', 'generate_tts(仅 use_clip_audio=false)', 'clone_voice', 'generate_bgm', 'get_bgm_plan', 'get_bgm_status', 'generate_sfx', 'lipsync_shot', 'lipsync_episode', 'get_lipsync_status', 'set_shot_name_card'],
+        tools: ['assign_voices', 'generate_tts(仅 use_clip_audio=false)', 'clone_voice', 'generate_bgm', 'get_bgm_plan', 'quote_bgm_candidates', 'select_bgm_candidate', 'get_bgm_status', 'generate_sfx', 'lipsync_shot', 'lipsync_episode', 'get_lipsync_status', 'set_shot_name_card'],
         billing: '混合',
         note: '默认视频原声跳过 TTS 三步(pipeline-status 里显示 not_required,不是没做完)。',
     },
@@ -290,7 +290,7 @@ export const OPTIONAL_BOOSTS = [
     { what: '口型同步', tool: 'lipsync_episode', when: 'TTS 配音项目需要对口型时' },
     { what: '海报 / 封面', tool: 'generate_episode_poster', when: '成片后;`generate_drama_poster` / `generate_cover` 同族' },
     { what: '音效 / 特效 / 转场(本地库匹配)', tool: 'generate_sfx', when: '免费;`generate_effects` / `generate_transitions` 同族' },
-    { what: '配乐', tool: 'generate_bgm', when: '按整集情绪弧线生成;终拼自动接管。客户想指定音乐方向就带 prompt(整集一条),写法先读 `get_bgm_prompt_guide`(免费);不带 prompt 就是全自动。客户给了明确参数(情绪/主奏配器/BPM/大小调)用 director 锁定(硬约束,可按幕;按幕前先 get_bgm_plan 免费看分幕)' },
+    { what: '配乐', tool: 'generate_bgm', when: '按整集情绪弧线生成;终拼自动接管。客户想指定音乐方向就带 prompt(整集一条),写法先读 `get_bgm_prompt_guide`(免费);不带 prompt 就是全自动。客户给了明确参数(情绪/主奏配器/BPM/大小调)用 director 锁定(硬约束,可按幕;按幕前先 get_bgm_plan 免费看分幕)。客户想先听几版再定:candidates=2~3 出完整候选(每首单独计费,先 quote_bgm_candidates 报价),select_bgm_candidate 挑' },
     { what: '字幕翻译', tool: 'translate_subtitles', when: '出海;双语烧录在项目设定里开' },
 ];
 export const BILLING = {

package/dist/tools/produce.js

@@ -1490,11 +1490,17 @@ export function registerProduceTools(server, client) {
         '整集锁写在 director 顶层;只锁某一幕写进 director.acts[{act,…}](同名字段覆盖整集的)。' +
         '幕是按情绪弧线自动分的:按幕锁之前先调 get_bgm_plan(免费,只读)看本集分几幕、每幕覆盖哪些镜。' +
         '参数拼错(bpm 越界、调性不是 major/minor/modal、幕号不存在)会 400;配器里写人声/环境声会被丢掉并在 director_warnings 点名。' +
-        '客户说「要慢一点、小调、用古筝」这类**明确参数**用 director;说「整体更压抑」这类**方向**用 prompt;两者可同时用。', {
+        '客户说「要慢一点、小调、用古筝」这类**明确参数**用 director;说「整体更压抑」这类**方向**用 prompt;两者可同时用。\n' +
+        '★candidates 可选=候选整版对比:每幕出 2~3 首**完整**候选让客户挑(挑中的直接用,听到什么成片里就是什么)。' +
+        '每首单独按首计费 ⇒ 费用是单首的 N 倍,**必须先 quote_bgm_candidates 报价、把点数告诉客户、客户同意后**带 quote_id 调本工具。' +
+        '不传或传 1=原行为(每幕一首,无需报价)。生成后 get_bgm_status 的 candidate_groups 给每首的试听地址,select_bgm_candidate 挑选(免费),不挑默认第 1 首。', {
         episode_id: z.number().int().positive(),
         prompt: z.string().optional().describe('配乐方向,整集一条,≤800 字。只写音乐维度,别写剧情。传空字符串=清除已存的提示词。'
             + '不传=沿用该集上次填的(没填过就是全自动)。'),
         prompt_mode: z.enum(['guide', 'override']).optional().describe('guide(默认)=提示词与平台护栏一起生效;override=直通跳过审美护栏(技术底线仍在)。'),
+        candidates: z.number().int().min(1).max(3).optional()
+            .describe('每幕出几首完整候选(1~3,默认 1)。≥2 时每首单独计费,必须带 quote_bgm_candidates 拿到的 quote_id'),
+        quote_id: z.string().optional().describe('candidates≥2 时必填:quote_bgm_candidates 返回的报价凭证(一次性,15 分钟有效)'),
         director: z.object({
             ...BGM_LOCK_FIELDS,
             acts: z.array(z.object({
@@ -1503,32 +1509,57 @@ export function registerProduceTools(server, client) {
             }).strict()).optional().describe('按幕锁定;同名字段覆盖整集的,没写的继承整集'),
             // strict:拼错的字段(如 tempo)要报校验错误;zod 默认会静默剥掉它,转发出去的就是空锁 ⇒ 一次不受控的扣费生成
         }).strict().optional().describe('结构化锁定(硬约束)。顶层字段整集生效;不传=全由配乐总监判断'),
-    }, async ({ episode_id, prompt, prompt_mode, director }) => jsonResult(await client.producePost(`/episodes/${episode_id}/bgm`, {
+    }, async ({ episode_id, prompt, prompt_mode, director, candidates, quote_id }) => jsonResult(await client.producePost(`/episodes/${episode_id}/bgm`, {
         ...(prompt === undefined ? {} : { prompt }),
         ...(prompt_mode ? { prompt_mode } : {}),
         ...(director ? { director } : {}),
+        ...(candidates === undefined ? {} : { candidates }),
+        ...(quote_id ? { quote_id } : {}),
     })));
+    server.tool('quote_bgm_candidates', '给「配乐候选整版对比」报价(免费):每幕出 candidates 首完整候选的总点数 = 有配乐的幕数 × 候选数 × 单首价。' +
+        '返回 quote_id(15 分钟有效、一次性)。⚠️ 把 estimated_points 原样告诉用户,用户明确同意后才拿 quote_id 调 generate_bgm(candidates 必须与这里一致),不要擅自确认。' +
+        '另有少量配乐总监 LLM 文本费(每幕一次),不在报价内。', {
+        episode_id: z.number().int().positive(),
+        candidates: z.number().int().min(2).max(3).describe('每幕几首候选(2~3)'),
+    }, async ({ episode_id, candidates }) => jsonResult(await client.produceGet(`/episodes/${episode_id}/bgm/quote?candidates=${candidates}`)));
+    server.tool('select_bgm_candidate', '在候选整版对比里给某一幕挑一首(免费)。cue_id 与 track_id 取自 get_bgm_status 的 candidate_groups;' +
+        '同一幕的所有配乐段一起换。改完 compose_episode 重新合成才进成片。', {
+        episode_id: z.number().int().positive(),
+        cue_id: z.number().int().positive().describe('candidate_groups[].cue_ids 里任一个'),
+        track_id: z.number().int().positive().describe('candidate_groups[].candidates[].track_id'),
+    }, async ({ episode_id, cue_id, track_id }) => jsonResult(await client.producePost(`/episodes/${episode_id}/bgm-cues/${cue_id}/select`, { track_id })));
     server.tool('get_bgm_plan', '查本集配乐会分成几幕(免费、只读、不生成):每幕的幕号 act、覆盖镜号 sb_from~sb_to、时长、平均情绪强度。' +
         '要用 generate_bgm 的 director.acts 按幕锁定参数时,先调这个拿幕号。' +
         '★这是独立的只读工具:看分幕**不要**去调 generate_bgm——那个一调就是扣费生成。', { episode_id: z.number().int().positive() }, async ({ episode_id }) => jsonResult(await client.produceGet(`/episodes/${episode_id}/bgm-plan`)));
-    server.tool('set_episode_audio', '设置**本集**配乐音量(覆盖整剧设定,免费)。整剧统一的用 update_project_settings。' +
+    server.tool('set_episode_audio', '设置**本集**成片混音(免费):配乐音量(覆盖整剧设定)、片段原声增益、配音轨增益。整剧统一的配乐音量用 update_project_settings。' +
         '★只改设置:成片要 compose_episode 重新合成才变(rerender_episode 用旧时间线,不带上)。' +
-        '★想调某一段配乐的音量或淡入淡出,用 list_bgm_cues + update_bgm_cue。', {
+        '★想调某一段配乐的音量、淡入淡出或起点,用 list_bgm_cues + update_bgm_cue。' +
+        '★原声=视频片段自带的声音(原声剧里就是角色台词);配音轨=TTS 生成的对白与旁白(两者在同一轨里预混,只能整轨调,分不开)。' +
+        '★本集若走逐镜合成片终拼(每镜都有合成片),配音已烤进每镜、与原声是同一条音频,这两个增益不生效——响应里会有 warning,照实转告客户。', {
         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=清除、跟随整剧'),
+        clip_audio_gain_db: z.number().min(-30).max(6).nullable().optional()
+            .describe('片段原声比系统默认响/轻多少(dB,-30~+6;0=默认);原声剧台词听不清→调高,环境噪音太吵→调低;null=清回默认'),
+        voice_gain_db: z.number().min(-24).max(6).nullable().optional()
+            .describe('配音轨(TTS 对白与旁白)比系统默认响/轻多少(dB,-24~+6;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。' +
+    server.tool('list_bgm_cues', '列出本集的配乐段(AI 配乐按情绪分幕,每段覆盖一段镜号 sb_from~sb_to):id、覆盖范围、gain_db(null=跟随音量档)、fade_in_ms / fade_out_ms、track_offset_ms / start_shift_ms(null=系统决定)。' +
         '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 重新合成才生效。', {
+    server.tool('update_bgm_cue', '调某一段配乐的音量、淡入淡出与起点(免费)。换曲目或改覆盖镜号范围用 generate_bgm 重新生成。' +
+        '★例:配乐进得太突兀→加大 fade_in_ms;某段压对白→降 gain_db;想从曲子的高潮部分开始→设 track_offset_ms;' +
+        '想等这段第一镜开口之后再进→设 start_shift_ms。改完 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)'),
+        track_offset_ms: z.number().int().min(0).max(600000).nullable().optional()
+            .describe('从配乐文件第几毫秒开始播(0~600000),覆盖系统自动挑的切入点;超过曲长会钳到曲尾前 1 秒;null=交回系统自动挑'),
+        start_shift_ms: z.number().int().min(0).max(60000).nullable().optional()
+            .describe('这段配乐在它第一镜开始后再晚多少毫秒进(0~60000);默认卡在第一镜起点。段尾不变,至少留 1 秒;null=不平移'),
     }, 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 配乐提示词」的书写规范:两个档位怎么选、该写哪些维度(附可照抄的示例)、' +
         '哪些是写了也不会生效的硬限制(纯器乐/时长/不做音效/不复刻具体曲目)、常见写坏的方式。' +

package/openapi.json

@@ -2,8 +2,8 @@
   "openapi": "3.1.0",
   "info": {
     "title": "StarReel Production API",
-    "version": "0.1.133",
-    "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.133 tool surface (operationIds match MCP tool names 1:1)."
+    "version": "0.1.135",
+    "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.135 tool surface (operationIds match MCP tool names 1:1)."
   },
   "servers": [
     {
@@ -3475,8 +3475,8 @@
     "/episodes/{episode_id}/audio": {
       "put": {
         "operationId": "set_episode_audio",
-        "summary": "设置**本集**配乐音量(覆盖整剧设定,免费)",
-        "description": "设置**本集**配乐音量(覆盖整剧设定,免费)。整剧统一的用 update_project_settings。★只改设置:成片要 compose_episode 重新合成才变(rerender_episode 用旧时间线,不带上)。★想调某一段配乐的音量或淡入淡出,用 list_bgm_cues + update_bgm_cue。",
+        "summary": "设置**本集**成片混音(免费):配乐音量(覆盖整剧设定)、片段原声增益、配音轨增益",
+        "description": "设置**本集**成片混音(免费):配乐音量(覆盖整剧设定)、片段原声增益、配音轨增益。整剧统一的配乐音量用 update_project_settings。★只改设置:成片要 compose_episode 重新合成才变(rerender_episode 用旧时间线,不带上)。★想调某一段配乐的音量、淡入淡出或起点,用 list_bgm_cues + update_bgm_cue。★原声=视频片段自带的声音(原声剧里就是角色台词);配音轨=TTS 生成的对白与旁白(两者在同一轨里预混,只能整轨调,分不开)。★本集若走逐镜合成片终拼(每镜都有合成片),配音已烤进每镜、与原声是同一条音频,这两个增益不生效——响应里会有 warning,照实转告客户。",
         "tags": [
           "episodes"
         ],
@@ -3519,6 +3519,30 @@
                         "type": "null"
                       }
                     ]
+                  },
+                  "clip_audio_gain_db": {
+                    "anyOf": [
+                      {
+                        "type": "number",
+                        "minimum": -30,
+                        "maximum": 6
+                      },
+                      {
+                        "type": "null"
+                      }
+                    ]
+                  },
+                  "voice_gain_db": {
+                    "anyOf": [
+                      {
+                        "type": "number",
+                        "minimum": -24,
+                        "maximum": 6
+                      },
+                      {
+                        "type": "null"
+                      }
+                    ]
                   }
                 }
               }
@@ -3669,7 +3693,7 @@
       "post": {
         "operationId": "generate_bgm",
         "summary": "给整集生成/更换 AI 配乐(按情绪弧线)",
-        "description": "给整集生成/更换 AI 配乐(按情绪弧线)。后台异步,按用量后付不欠费。返回情绪弧线段数与预估耗时;用 get_bgm_status 轮询生成进度。★配乐生成/改动**不会自动进已有成片**——完成后必须重新 compose_episode(免费)才能听到;get_final_cut 的 bgm_stale=true 就是在提示这一步。别用 re-render(吃旧时间线,不含新配乐)。\n★prompt 可选:不传=全自动(和以前一样)。传了就是在自动结果上再加方向,整集一条,系统仍按情绪弧线分幕。怎么写见 get_bgm_prompt_guide(免费);要点=只写音乐维度(情绪气质/主奏配器/速度动态/厚薄空间/风格参照),别写剧情(「主角发现真相时要紧张」→写「紧张,节奏推进感强」)。只出纯器乐:要人声/歌词/拟音当乐器都不会生效,会在 prompt_warnings 里点名但**不拦生成**。\n★prompt_mode: guide(默认)=你的要求与平台专业护栏(时代与题材匹配/配器节制/高潮保规模/段间差异)一起生效;override=直通,跳过护栏,只保留技术底线(纯器乐/时长/可循环)。override 效果自负,**先用 guide 试**,确实拧不过来再换。不传 prompt 时沿用该集上次填的(get_bgm_status 可查)。\n★director 可选=结构化锁定(硬约束):逐项指定 mood 情绪 / instruments 主奏配器 / bpm / tonality 大小调,生成时**强制覆盖**配乐总监的判断(不像 prompt 只是方向,可能被护栏或 AI 取舍改写);没锁的项仍自动判断。整集锁写在 director 顶层;只锁某一幕写进 director.acts[{act,…}](同名字段覆盖整集的)。幕是按情绪弧线自动分的:按幕锁之前先调 get_bgm_plan(免费,只读)看本集分几幕、每幕覆盖哪些镜。参数拼错(bpm 越界、调性不是 major/minor/modal、幕号不存在)会 400;配器里写人声/环境声会被丢掉并在 director_warnings 点名。客户说「要慢一点、小调、用古筝」这类**明确参数**用 director;说「整体更压抑」这类**方向**用 prompt;两者可同时用。",
+        "description": "给整集生成/更换 AI 配乐(按情绪弧线)。后台异步,按用量后付不欠费。返回情绪弧线段数与预估耗时;用 get_bgm_status 轮询生成进度。★配乐生成/改动**不会自动进已有成片**——完成后必须重新 compose_episode(免费)才能听到;get_final_cut 的 bgm_stale=true 就是在提示这一步。别用 re-render(吃旧时间线,不含新配乐)。\n★prompt 可选:不传=全自动(和以前一样)。传了就是在自动结果上再加方向,整集一条,系统仍按情绪弧线分幕。怎么写见 get_bgm_prompt_guide(免费);要点=只写音乐维度(情绪气质/主奏配器/速度动态/厚薄空间/风格参照),别写剧情(「主角发现真相时要紧张」→写「紧张,节奏推进感强」)。只出纯器乐:要人声/歌词/拟音当乐器都不会生效,会在 prompt_warnings 里点名但**不拦生成**。\n★prompt_mode: guide(默认)=你的要求与平台专业护栏(时代与题材匹配/配器节制/高潮保规模/段间差异)一起生效;override=直通,跳过护栏,只保留技术底线(纯器乐/时长/可循环)。override 效果自负,**先用 guide 试**,确实拧不过来再换。不传 prompt 时沿用该集上次填的(get_bgm_status 可查)。\n★director 可选=结构化锁定(硬约束):逐项指定 mood 情绪 / instruments 主奏配器 / bpm / tonality 大小调,生成时**强制覆盖**配乐总监的判断(不像 prompt 只是方向,可能被护栏或 AI 取舍改写);没锁的项仍自动判断。整集锁写在 director 顶层;只锁某一幕写进 director.acts[{act,…}](同名字段覆盖整集的)。幕是按情绪弧线自动分的:按幕锁之前先调 get_bgm_plan(免费,只读)看本集分几幕、每幕覆盖哪些镜。参数拼错(bpm 越界、调性不是 major/minor/modal、幕号不存在)会 400;配器里写人声/环境声会被丢掉并在 director_warnings 点名。客户说「要慢一点、小调、用古筝」这类**明确参数**用 director;说「整体更压抑」这类**方向**用 prompt;两者可同时用。\n★candidates 可选=候选整版对比:每幕出 2~3 首**完整**候选让客户挑(挑中的直接用,听到什么成片里就是什么)。每首单独按首计费 ⇒ 费用是单首的 N 倍,**必须先 quote_bgm_candidates 报价、把点数告诉客户、客户同意后**带 quote_id 调本工具。不传或传 1=原行为(每幕一首,无需报价)。生成后 get_bgm_status 的 candidate_groups 给每首的试听地址,select_bgm_candidate 挑选(免费),不挑默认第 1 首。",
         "tags": [
           "episodes"
         ],
@@ -3786,6 +3810,14 @@
                       }
                     },
                     "additionalProperties": false
+                  },
+                  "candidates": {
+                    "type": "integer",
+                    "minimum": 1,
+                    "maximum": 3
+                  },
+                  "quote_id": {
+                    "type": "string"
                   }
                 }
               }
@@ -3823,8 +3855,8 @@
     "/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 的是**整剧共用段**,改它会影响所有集。免费。",
+        "summary": "列出本集的配乐段(AI 配乐按情绪分幕,每段覆盖一段镜号 sb_from~sb_to):id、覆盖范围、gain_db(null=跟随音量档)、fade_in_ms / fade_out_ms、track_offset_ms / start",
+        "description": "列出本集的配乐段(AI 配乐按情绪分幕,每段覆盖一段镜号 sb_from~sb_to):id、覆盖范围、gain_db(null=跟随音量档)、fade_in_ms / fade_out_ms、track_offset_ms / start_shift_ms(null=系统决定)。episode_id 为 null 的是**整剧共用段**,改它会影响所有集。免费。",
         "tags": [
           "episodes"
         ],
@@ -3870,8 +3902,8 @@
     "/episodes/{episode_id}/bgm-cues/{cue_id}": {
       "put": {
         "operationId": "update_bgm_cue",
-        "summary": "调某一段配乐的音量与淡入淡出(免费)",
-        "description": "调某一段配乐的音量与淡入淡出(免费)。只改这三项;换曲目或改覆盖范围用 generate_bgm 重新生成。★例:配乐进得太突兀→加大 fade_in_ms;某段压对白→降 gain_db。改完 compose_episode 重新合成才生效。",
+        "summary": "调某一段配乐的音量、淡入淡出与起点(免费)",
+        "description": "调某一段配乐的音量、淡入淡出与起点(免费)。换曲目或改覆盖镜号范围用 generate_bgm 重新生成。★例:配乐进得太突兀→加大 fade_in_ms;某段压对白→降 gain_db;想从曲子的高潮部分开始→设 track_offset_ms;想等这段第一镜开口之后再进→设 start_shift_ms。改完 compose_episode 重新合成才生效。",
         "tags": [
           "episodes"
         ],
@@ -3924,10 +3956,111 @@
                     "type": "integer",
                     "minimum": 0,
                     "maximum": 15000
+                  },
+                  "track_offset_ms": {
+                    "anyOf": [
+                      {
+                        "type": "integer",
+                        "minimum": 0,
+                        "maximum": 600000
+                      },
+                      {
+                        "type": "null"
+                      }
+                    ]
+                  },
+                  "start_shift_ms": {
+                    "anyOf": [
+                      {
+                        "type": "integer",
+                        "minimum": 0,
+                        "maximum": 60000
+                      },
+                      {
+                        "type": "null"
+                      }
+                    ]
+                  }
+                }
+              }
+            }
+          }
+        },
+        "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}/select": {
+      "post": {
+        "operationId": "select_bgm_candidate",
+        "summary": "在候选整版对比里给某一幕挑一首(免费)",
+        "description": "在候选整版对比里给某一幕挑一首(免费)。cue_id 与 track_id 取自 get_bgm_status 的 candidate_groups;同一幕的所有配乐段一起换。改完 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": "candidate_groups[].cue_ids 里任一个"
+            }
+          }
+        ],
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "type": "object",
+                "properties": {
+                  "track_id": {
+                    "type": "integer",
+                    "exclusiveMinimum": 0,
+                    "description": "candidate_groups[].candidates[].track_id"
+                  }
+                },
+                "required": [
+                  "track_id"
+                ]
+              }
+            }
           }
         },
         "responses": {
@@ -4052,6 +4185,64 @@
         }
       }
     },
+    "/episodes/{episode_id}/bgm/quote": {
+      "get": {
+        "operationId": "quote_bgm_candidates",
+        "summary": "给「配乐候选整版对比」报价(免费):每幕出 candidates 首完整候选的总点数 = 有配乐的幕数 × 候选数 × 单首价",
+        "description": "给「配乐候选整版对比」报价(免费):每幕出 candidates 首完整候选的总点数 = 有配乐的幕数 × 候选数 × 单首价。返回 quote_id(15 分钟有效、一次性)。⚠️ 把 estimated_points 原样告诉用户,用户明确同意后才拿 quote_id 调 generate_bgm(candidates 必须与这里一致),不要擅自确认。另有少量配乐总监 LLM 文本费(每幕一次),不在报价内。",
+        "tags": [
+          "episodes"
+        ],
+        "parameters": [
+          {
+            "name": "episode_id",
+            "in": "path",
+            "required": true,
+            "schema": {
+              "type": "integer",
+              "exclusiveMinimum": 0
+            }
+          },
+          {
+            "name": "candidates",
+            "in": "query",
+            "required": true,
+            "schema": {
+              "type": "integer",
+              "minimum": 2,
+              "maximum": 3,
+              "description": "每幕几首候选(2~3)"
+            }
+          }
+        ],
+        "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}/chain-frames": {
       "post": {
         "operationId": "chain_frames",

package/package.json

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