@starreel/mcp 0.1.213 → 0.1.214

package/SKILL.md

@@ -1482,6 +1482,17 @@ to close") tells the vendor to fit that entire sequence into each 3-second shot.
   `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.
+- **Theme song with vocals** (free; settings only — `compose_episode` again): `get_theme_songs` →
+  `set_theme_songs` attaches an opening / ending / insert song to an episode (the customer's own
+  upload via `upload-url` kind=audio, or a `track_id`). Give the song's backing track as
+  `instrumental_url` and dialogue lines automatically swap the vocal for the backing track;
+  without it the whole song ducks by `duck_db` (default −18 dB) while someone speaks. Background
+  music yields inside the song's range. `enabled=false` = the drama isn't switched on yet.
+- **Poem / lyric text cards** (free; `compose_episode` again): `get_shot_verse_cards` →
+  `set_shot_verse_cards` — up to 6 vertical or horizontal cards per shot (left / right / center,
+  own fade-in/out and start time), a full-screen black closing card (`backdrop: "black"`) and
+  scrolling end credits (`motion: "scroll_up"`). Cards stay out of the dialogue-subtitle band.
+  Use only the text the customer supplied. Don't overlay text on a downloaded cut.
 - **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/i18n/tools.en.json

@@ -258,5 +258,9 @@
   "get_local_frame_edit": "Check progress and results of a local frame edit (free). status=running → keep waiting; when completed, look at each candidate: composited_url (the result pasted back onto the original — show this to the customer), verdict (pass = usable; warn = usable but needs a human look — REGION_SEAM_WARN possible seam / EDIT_NOT_APPLIED barely changed / IDENTITY_NEEDS_REVIEW face-comparison score in the grey zone, not auto-approved / IDENTITY_NOT_JUDGEABLE side view, looking down or face too small to judge / IDENTITY_COMPARE_LOW legacy identity score low / IDENTITY_AUDIT_UNAVAILABLE identity not audited; reject = not recommended — REGION_MISALIGNED misaligned paste / IDENTITY_MISMATCH face comparison says it became a different person / IDENTITY_AUDIT_REJECTED frame audit failed, possibly a composition issue already present in the original frame), reason_text (a plain-language explanation of each reason — relay it to the customer as is), metrics, identity_audit, identity_compare (face edits: with method=face_embedding the decision uses face embeddings — similarity to the same face before the edit ≥0.75 passes, <0.60 is a mismatch, in between goes to a human; vlm_reference is recorded only. Without a method field it is the legacy advisory score). ★Still check face edits with your own eyes — the platform cannot judge side views, downward-looking or small faces. Download and look at composited_url yourself, tell the customer, then adopt_local_frame_edit the one they pick. Rejected candidates are not refunded (including those failing the frame audit because of an issue already in the original frame).",
   "adopt_local_frame_edit": "Adopt a local-edit candidate as this shot's current frame (free). Same follow-up as an uploaded frame: the shot video is marked for regeneration and adjacent seams are repaired. ★Only after the customer has looked and chosen. If the frame changed after the edit → 409 BASE_FRAME_CHANGED (start a new edit on the current frame); verdict=reject candidates are refused by default (409 CANDIDATE_REJECTED) — pass accept_rejected:true only when the customer insists after seeing it.",
   "audit_seam_directions": "Pre-video seam direction check (advisory, never blocks any step): for every pair of adjacent shots, compares \"previous shot's last frame (or first frame if none) ↔ this shot's first frame\" for the same subject jumping left/right sides of the frame (a reversed eyeline is noted with it), reversed motion direction, and shot-size jumps (same subject, extreme long ↔ close-up). Eyeline alone and key-light direction are observed but not reported: production replay showed too many false positives on those (better to miss than to nag). Shots that look fine alone but jump when cut together usually fail on these. Complements audit_seams, which checks identity/wardrobe/props/object state but not direction or position. ★When: after first frames (and needed last frames) are done and chain_frames has run, before review_frames / generate_videos. Scene changes, declared jump cuts, insert shots and title/black cards are skipped automatically. ★dry_run first (default, free): returns the seams to observe plus estimated_points (upper bound) and typical_points (usual cost); tell the client both — billed by actual text tokens. After the client agrees, pass dry_run=false + confirm_usage_billing=true. Execution is asynchronous and returns immediately; read results with get_seam_directions a minute or two later. Seams already observed with unchanged frames are not billed again.",
-  "get_seam_directions": "(Free) Read audit_seam_directions results: each issue gives the seam shot numbers, the problem (subject jumps sides, reversed motion, shot-size jump) and fixes (chain_shot_from mode=reframe to regenerate this shot's first frame anchored on the previous last frame / update_shot to state facing then generate_shot_frame / align_prev_shot when the previous shot already has video / split_shot to insert an intermediate shot size). Results are advisory: explain them to the client and let the client pick which to fix; intentional reverse shots, turns or impact cuts can be ignored. not_audited>0 = seams not observed yet or frames changed since; running=true = still running. review_frames' seam_direction_advisory is a summary of the same results. This tool only looks at pre-video still frames; after videos are generated, check seams with preview_seams (free short-clip previews)."
+  "get_seam_directions": "(Free) Read audit_seam_directions results: each issue gives the seam shot numbers, the problem (subject jumps sides, reversed motion, shot-size jump) and fixes (chain_shot_from mode=reframe to regenerate this shot's first frame anchored on the previous last frame / update_shot to state facing then generate_shot_frame / align_prev_shot when the previous shot already has video / split_shot to insert an intermediate shot size). Results are advisory: explain them to the client and let the client pick which to fix; intentional reverse shots, turns or impact cuts can be ignored. not_audited>0 = seams not observed yet or frames changed since; running=true = still running. review_frames' seam_direction_advisory is a summary of the same results. This tool only looks at pre-video still frames; after videos are generated, check seams with preview_seams (free short-clip previews).",
+  "get_shot_verse_cards": "Read this shot's current poem/lyric text cards (free). set_shot_verse_cards is a **full overwrite**—read before editing. enabled=false means the drama is not enabled yet (saved cards will not appear in the cut).",
+  "set_shot_verse_cards": "Add/change/clear poem & lyric text cards on one shot (burned into the final cut; free, data only). Up to 6 cards per shot, **full overwrite** (read with get_shot_verse_cards first); cards=[] clears. Covers three staples of cinematic period-style shorts: (1) vertical or horizontal poem/lyric lines fading in at the left, right or center (a newline in text starts a new column/line, punctuation is kept; stagger several cards with start_ms); (2) a full-screen black closing card with backdrop=\"black\" (usually on the last shot, orient=horizontal, position=center); (3) end credits over the picture with motion=\"scroll_up\" (scrolls bottom to top, one name per line, blank lines separate groups). Cards automatically stay out of the dialogue-subtitle band, so they never overlap spoken subtitles; oversized text is shrunk instead of overflowing. Run compose_episode afterwards to re-cut (rerender_episode reuses the saved timeline and will not pick it up). enabled=false from get_shot_verse_cards means the drama is not enabled yet. ★Do not download the video, overlay text yourself and re-upload—that bypasses renderer fonts and subtitle avoidance. ★Only use the poem/credits text the customer supplied; do not invent it.",
+  "get_theme_songs": "Read an episode's theme-song settings (free). set_theme_songs is a **full overwrite**—read before editing. enabled=false means the drama is not enabled yet.",
+  "set_theme_songs": "Attach/change/clear **theme songs with vocals** on an episode (opening song, ending song, or an insert song over a range of shots; free, data only, full overwrite, songs=[] clears; up to 3 per episode). Song source, pick one: (1) the customer's own song—upload via upload-url (kind=audio) and pass the public_url as audio_url; (2) platform-composed or library track—pass track_id; (3) an existing https URL. placement: opening = from 0 until the song ends or shot sb_to ends / ending = pinned to the end, or starting at shot sb_from / range = shots sb_from..sb_to (both required). Vocals never fight dialogue: with instrumental_url (the same song's backing track) the default dialogue_mode=instrumental fades the vocal out and the backing track in while someone speaks, then swaps back; with only the full song, dialogue_mode=duck lowers the whole song by duck_db (default -18 dB) during speech. Background music automatically yields inside the theme-song range (bgm_yield, default true) and is unchanged elsewhere. gain_db defaults to -8; track_offset_ms skips an intro. Run compose_episode afterwards; enabled=false means the drama is not enabled yet. ★Do not download the cut, remix it yourself and re-upload."
 }

package/dist/i18n/tools.zh-CN.json

@@ -258,5 +258,9 @@
   "set_voice_anchor_from_shot": "从本剧某一镜选定角色的声线(声音基准)。免费。不需要客户提供外部音源——就用片子里这个角色已经念出来的声音。\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★去环境音与验收(平台按剧开启时生效,响应里有 hygiene 字段):自动剔除两句之间的纯环境音停顿,并测样本底噪(noise_floor_before/after,阈值 threshold)。preview 时 preview_url 是**清理后**的样本、raw_preview_url 是原样本——**请让客户前后对比试听**。verdict=fail 表示人声下面垫着明显的环境声或音乐(剔停顿救不了,克隆和视频厂商会把它当音色学走),正式提交会被拒:换一镜念得更干净的、或调 start_s/dur_s 避开背景声;只有客户听过后明确坚持,才带 allow_issues:true 写入。\n★有客户授权的外部音源时改用 clone_voice + set_character_voice;两者二选一,后设的覆盖先设的。",
   "export_handoff_pack": "启用交付追溯后会保存不可变导出清单（不改素材）。保留 pack_id 和 manifest_sha256，回传外部成片时引用。导出本集「素材交接包」清单:逐镜裸片 + 对白音轨 + 音效 + 配乐 + 字幕的可下载 URL,交给你在**自己那边**完成转场决策、拼接、混音、烧字幕——平台不参与终拼。免费,零扣费。\n★本地调色/第三方 AI 后期:purpose=local_color;只有图片时传 media_type=images,无需生成视频。本模式保留源文件、关闭导出包的自动 LUT、附带后期说明和本地对比页流程;不上传第三方、不收费生成、不回填平台。图片来源可能已有处理,不能把所有导出图承诺为未调色原片。\n\n【推荐流程】① 调本工具拿 manifest;② 按 clips[].url 把裸片下载到本地;③ 你自己看片判断每个接缝该用什么转场(manifest 给了 scene_boundary 场景边界作判据),写一份 plan.json;④ 用 get_handoff_toolchain 拿到 compile_timeline.py 展开时间轴、assemble.sh 装配出成片。工具链已经把「加了重叠转场之后字幕/对白/音效怎么跟着位移」算好了。\n\n【三个不看就会翻车的事实】\n① **人声在哪要逐镜读 `shots[].voice_track.location`,不能读整集的 audio_contract.mode**——后者是整剧级声明,而全画外旁白镜的旁白是平台在完成侧混进裸片的,同一集里逐镜可以不同。四种取值各有各的处置:`separate_file`=对白在 dialogue_audio,不铺这镜就没台词;`baked_in_clip`=已在裸片音轨里,再叠一遍会双声;`missing`=**平台侧确认缺失**(旁白补偿失败),字幕还在但声音哪都没有——回平台重生成该镜,拉长转场掩盖不了;`unknown`=有台词却查不到来源,**必须试听裸片**再决定。★有字幕从来不等于有声音:字幕是逐句的,音频是逐镜的。`conflicts_with_contract=true` 的镜以实测为准,notes 里已按镜号点名。\n② 每镜必须按 trim_head_ms / duration_ms 裁剪再用;直接拼整条裸片会把平台已经 QC 掉的首尾形变帧一起拼进去。★manifest_version=0.2 起入出点投影自平台终拼时间轴(与 build_av_timing_contract、平台成片同一套),clip.url 是时间轴实际用的那个文件(clip.source_kind);0.1 时代交接包自算的 trim 与成片对不上。speed_factor≠1 要按倍率变速、freeze_pad_ms>0 要克隆末帧补齐(duration_ms=(out_ms−in_ms)/speed_factor+freeze_pad_ms),否则总长对不上;subtitles_burned_in=true 别再烧字幕,color_graded=true 别再套 LUT;trim_basis≠platform_timeline 的镜是整条不裁,notes 写了原因。工具链只认 0.1 的旧副本会拒收 0.2,重新 save_handoff_toolchain。\n③ 字幕 cue、dialogue_audio.offset_ms、sfx[].offset_ms 的基准都是「该镜 trim 之后的第 0 毫秒」,不是成片绝对时间。你加多少重叠转场都不用改它们——交给 compile_timeline.py 展开,别手算累加。\n\n拼之前先跑 build_av_timing_contract → get_av_timing_contract(免费):逐镜实测源片时长、平台终拼的入出点/转场占用/定格补帧、人声已混入视频还是独立轨,拿它核对你的时间轴总长。\n想让平台代拼、要平台级质量闸(终拼预检/音画等长/响度母带),改用 compose_episode。",
   "get_handoff_toolchain": "拿到素材交接包的装配工具链源码(compile_timeline.py 时间轴编译器 / assemble.sh ffmpeg 装配脚本)。免费。本工具只返回源码文本,**不会**在你机器上写文件——请自行保存到工作目录再执行。\ncompile_timeline.py 负责把「镜相对」的字幕/对白/音效锚点展开成你自己时间轴上的绝对时间码,并处理重叠转场引起的整体位移;assemble.sh 是从裸片到成片的完整 ffmpeg 装配基线(裁剪→规范化→拼接/xfade→配乐侧链→字幕→两 pass 母带)。依赖 ffmpeg(烧字幕需带 libass)、ffprobe、jq、python3。",
-  "save_handoff_toolchain": "把装配工具链(fetch_pack.py / compile_timeline.py / assemble.sh)直接写到你本地的一个目录,省掉自己复制粘贴。免费。目录必须**已存在**且是绝对路径;文件名固定,不接受自定义。\n拒绝写入隐藏目录(~/.ssh、~/.config、.git…)与系统目录——这是写盘不是读盘,覆盖错地方不可逆。\n落盘后完整流程:\n  python3 fetch_pack.py manifest.json -o ./pack   # 下载素材、内联字幕落成 SRT\n  python3 compile_timeline.py ./pack [--transitions plan.json]\n  ./assemble.sh ./pack out.mp4 [plan.json]"
+  "save_handoff_toolchain": "把装配工具链(fetch_pack.py / compile_timeline.py / assemble.sh)直接写到你本地的一个目录,省掉自己复制粘贴。免费。目录必须**已存在**且是绝对路径;文件名固定,不接受自定义。\n拒绝写入隐藏目录(~/.ssh、~/.config、.git…)与系统目录——这是写盘不是读盘,覆盖错地方不可逆。\n落盘后完整流程:\n  python3 fetch_pack.py manifest.json -o ./pack   # 下载素材、内联字幕落成 SRT\n  python3 compile_timeline.py ./pack [--transitions plan.json]\n  ./assemble.sh ./pack out.mp4 [plan.json]",
+  "get_shot_verse_cards": "读这一镜的诗句/歌词字卡现值(免费)。set_shot_verse_cards 是**整组覆盖**,改之前先读。enabled=false 表示本剧尚未开通(存了也暂不进成片)。",
+  "set_shot_verse_cards": "给某一镜加/改/清「诗句·歌词字卡」(终拼时烧进成片;免费纯数据)。一镜最多 6 张,**整组覆盖**(先 get_shot_verse_cards 读现值再改),cards=[] 清空。国风电影感短片的三种标配都走它:①画面一侧/居中淡入的竖排或横排诗句、歌词(text 里换行=另起一列/一行,标点原样保留,可多张错开 start_ms 依次出现);②整屏黑底结语卡 backdrop=\"black\"(通常放末镜,orient=horizontal、position=center);③叠在画面上的片尾名单 motion=\"scroll_up\"(自下而上滚动,一行一个名字,空行分组)。字卡自动避开对白字幕所在的那条带,不会与台词重叠;字号放不下会自动缩小,不会顶出画面。改完调 compose_episode 重新终拼生效(rerender_episode 沿用已存时间轴,带不上)。get_shot_verse_cards 的 enabled=false 表示本剧尚未开通(存了也暂不进成片)。★别自己下载视频叠字再上传——那会绕开渲染机字体与字幕避让。★文字只写客户给的诗句/名单,别替客户编。",
+  "get_theme_songs": "读某一集的主题曲设置(免费)。set_theme_songs 是**整组覆盖**,改之前先读。enabled=false 表示本剧尚未开通(存了也暂不进成片)。",
+  "set_theme_songs": "给某一集挂/改/清**带人声的主题曲**(片头曲、片尾曲或某几镜的插曲;免费纯数据,整组覆盖,songs=[] 清空;一集最多 3 首)。歌来源三选一:①客户自己的歌——先 upload-url(kind=audio)上传拿 public_url 当 audio_url;②平台作曲/曲库——带 track_id(get_mv_song、list 曲库返回的 id);③已有 https 地址。placement:opening=片头(从 0 开始,放到歌完或 sb_to 那镜结束)/ending=片尾(贴片尾,或从 sb_from 那镜开始)/range=sb_from~sb_to 镜头段落(两端必填)。人声不和台词打架:给了 instrumental_url(同一首歌的伴奏轨)默认 dialogue_mode=instrumental——有台词时人声渐隐、伴奏接上,说完换回;只有原曲则 dialogue_mode=duck——有台词时整首压低 duck_db(默认 -18dB)。主题曲播放区间里配乐自动让开(bgm_yield,默认 true),区间外照常。gain_db 默认 -8,track_offset_ms 跳过前奏。改完调 compose_episode 重新终拼生效;enabled=false 表示本剧尚未开通。★别自己下载成片混音再上传。"
 }

package/dist/tools/guide-data.js

@@ -278,9 +278,9 @@ export const PIPELINE = [
     },
     {
         step: '9 音频',
-        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'],
+        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', 'set_shot_verse_cards(诗句/歌词字卡·黑底结语卡·滚动片尾名单)', 'set_theme_songs(带人声的片头/片尾/插曲,台词时压低或切伴奏)'],
         billing: '混合',
-        note: '默认视频原声跳过 TTS 三步(pipeline-status 里显示 not_required,不是没做完)。',
+        note: '默认视频原声跳过 TTS 三步(pipeline-status 里显示 not_required,不是没做完)。国风电影感短片的诗句字卡与主题曲在平台内完成(compose_episode 时烧录/混音),别下载成片外挂后期。',
     },
     {
         step: '10 成片与交付',

package/dist/tools/produce.js

@@ -2009,6 +2009,42 @@ export function registerProduceTools(server, client) {
         ...(start_ms !== undefined ? { start_ms } : {}),
         ...(position !== undefined ? { position } : {}),
     })));
+    server.tool('get_shot_verse_cards', '读这一镜的诗句/歌词字卡现值(免费)。set_shot_verse_cards 是**整组覆盖**,改之前先读。enabled=false 表示本剧尚未开通(存了也暂不进成片)。', { storyboard_id: z.number().int().positive() }, async ({ storyboard_id }) => jsonResult(await client.produceGet(`/storyboards/${storyboard_id}/verse-cards`)));
+    server.tool('set_shot_verse_cards', '给某一镜加/改/清「诗句·歌词字卡」(终拼时烧进成片;免费纯数据)。一镜最多 6 张,**整组覆盖**(先 get_shot_verse_cards 读现值再改),cards=[] 清空。国风电影感短片的三种标配都走它:①画面一侧/居中淡入的竖排或横排诗句、歌词(text 里换行=另起一列/一行,标点原样保留,可多张错开 start_ms 依次出现);②整屏黑底结语卡 backdrop=\"black\"(通常放末镜,orient=horizontal、position=center);③叠在画面上的片尾名单 motion=\"scroll_up\"(自下而上滚动,一行一个名字,空行分组)。字卡自动避开对白字幕所在的那条带,不会与台词重叠;字号放不下会自动缩小,不会顶出画面。改完调 compose_episode 重新终拼生效(rerender_episode 沿用已存时间轴,带不上)。get_shot_verse_cards 的 enabled=false 表示本剧尚未开通(存了也暂不进成片)。★别自己下载视频叠字再上传——那会绕开渲染机字体与字幕避让。★文字只写客户给的诗句/名单,别替客户编。', {
+        storyboard_id: z.number().int().positive(),
+        cards: z.array(z.object({
+            text: z.string().min(1).describe('字卡文字;换行=另起一列(竖排)/一行(横排);≤300 字'),
+            orient: z.enum(['vertical', 'horizontal']).optional().describe('默认 vertical 竖排(从右往左);滚动名单自动横排'),
+            position: z.enum(['left', 'right', 'center']).optional().describe('默认 right;滚动名单默认 center'),
+            start_ms: z.number().int().min(0).max(60000).optional().describe('镜内起点毫秒(相对本镜开头),默认 0'),
+            duration_ms: z.number().int().min(500).max(60000).optional().describe('显示时长,默认 4000;超出本镜部分截掉'),
+            fade_in_ms: z.number().int().min(0).max(5000).optional().describe('淡入毫秒,默认 600'),
+            fade_out_ms: z.number().int().min(0).max(5000).optional().describe('淡出毫秒,默认 600'),
+            font_size: z.number().int().min(20).max(200).optional().describe('字号上限(输出像素),默认 64;放不下自动缩小'),
+            font: z.string().optional().describe('字体名,默认行书 Zhi Mang Xing;规整宋体填 Noto Serif CJK SC(渲染机已装的才生效)'),
+            backdrop: z.enum(['none', 'black']).optional().describe('black = 整屏黑底结语卡'),
+            motion: z.enum(['static', 'scroll_up']).optional().describe('scroll_up = 自下而上滚动的片尾名单'),
+        })).max(6).describe('整组字卡(顺序即渲染顺序);[] = 清空本镜字卡'),
+    }, async ({ storyboard_id, cards }) => jsonResult(await client.producePut(`/storyboards/${storyboard_id}/verse-cards`, { cards })));
+    server.tool('get_theme_songs', '读某一集的主题曲设置(免费)。set_theme_songs 是**整组覆盖**,改之前先读。enabled=false 表示本剧尚未开通(存了也暂不进成片)。', { episode_id: z.number().int().positive() }, async ({ episode_id }) => jsonResult(await client.produceGet(`/episodes/${episode_id}/theme-songs`)));
+    server.tool('set_theme_songs', '给某一集挂/改/清**带人声的主题曲**(片头曲、片尾曲或某几镜的插曲;免费纯数据,整组覆盖,songs=[] 清空;一集最多 3 首)。歌来源三选一:①客户自己的歌——先 upload-url(kind=audio)上传拿 public_url 当 audio_url;②平台作曲/曲库——带 track_id(get_mv_song、list 曲库返回的 id);③已有 https 地址。placement:opening=片头(从 0 开始,放到歌完或 sb_to 那镜结束)/ending=片尾(贴片尾,或从 sb_from 那镜开始)/range=sb_from~sb_to 镜头段落(两端必填)。人声不和台词打架:给了 instrumental_url(同一首歌的伴奏轨)默认 dialogue_mode=instrumental——有台词时人声渐隐、伴奏接上,说完换回;只有原曲则 dialogue_mode=duck——有台词时整首压低 duck_db(默认 -18dB)。主题曲播放区间里配乐自动让开(bgm_yield,默认 true),区间外照常。gain_db 默认 -8,track_offset_ms 跳过前奏。改完调 compose_episode 重新终拼生效;enabled=false 表示本剧尚未开通。★别自己下载成片混音再上传。', {
+        episode_id: z.number().int().positive(),
+        songs: z.array(z.object({
+            audio_url: z.string().optional().describe('原曲(带人声)https 地址或 static/ 路径;与 track_id 二选一'),
+            track_id: z.number().int().positive().optional().describe('曲库/平台作曲的曲目 id(本人上传或公开的)'),
+            instrumental_url: z.string().optional().describe('同一首歌的伴奏轨(与原曲逐采样对齐);给了才能「台词段只留伴奏」'),
+            placement: z.enum(['opening', 'ending', 'range']),
+            sb_from: z.number().int().positive().optional().describe('起镜号(storyboard_number)'),
+            sb_to: z.number().int().positive().optional().describe('止镜号(含)'),
+            track_offset_ms: z.number().int().min(0).optional().describe('从曲内第几毫秒开始放(跳过前奏)'),
+            gain_db: z.number().min(-30).max(6).optional().describe('主题曲音量 dB,默认 -8'),
+            fade_in_ms: z.number().int().min(0).max(10000).optional().describe('默认 1000'),
+            fade_out_ms: z.number().int().min(0).max(10000).optional().describe('默认 2000'),
+            dialogue_mode: z.enum(['duck', 'instrumental']).optional().describe('有台词时:duck=整首压低;instrumental=切伴奏(需 instrumental_url)'),
+            duck_db: z.number().min(-40).max(0).optional().describe('duck 模式压低量 dB,默认 -18'),
+            bgm_yield: z.boolean().optional().describe('播放区间里配乐让开,默认 true'),
+        })).max(3).describe('整组主题曲;[] = 清空'),
+    }, async ({ episode_id, songs }) => jsonResult(await client.producePut(`/episodes/${episode_id}/theme-songs`, { songs })));
     server.tool('extract_segment_to_library', '把某一镜（或某集成片）的某个时间区间抽出来，存成可复用的素材，进我的素材库。免费（纯剪切，不走厂商）。' +
         '典型用法:闪回/回忆蒙太奇——画面全用已有镜头，边际成本为 0。' +
         '区间是相对**该来源视频**的秒数;末端超出片长会自动夹回来并在 span 里回显实际区间。' +

package/openapi.json

@@ -2,8 +2,8 @@
   "openapi": "3.1.0",
   "info": {
     "title": "StarReel Production API",
-    "version": "0.1.213",
-    "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.213 tool surface (operationIds match MCP tool names 1:1)."
+    "version": "0.1.214",
+    "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.214 tool surface (operationIds match MCP tool names 1:1)."
   },
   "servers": [
     {
@@ -10277,6 +10277,199 @@
         }
       }
     },
+    "/episodes/{episode_id}/theme-songs": {
+      "get": {
+        "operationId": "get_theme_songs",
+        "summary": "读某一集的主题曲设置(免费)",
+        "description": "读某一集的主题曲设置(免费)。set_theme_songs 是**整组覆盖**,改之前先读。enabled=false 表示本剧尚未开通(存了也暂不进成片)。",
+        "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"
+          }
+        }
+      },
+      "put": {
+        "operationId": "set_theme_songs",
+        "summary": "给某一集挂/改/清**带人声的主题曲**(片头曲、片尾曲或某几镜的插曲;免费纯数据,整组覆盖,songs=[] 清空;一集最多 3 首)",
+        "description": "给某一集挂/改/清**带人声的主题曲**(片头曲、片尾曲或某几镜的插曲;免费纯数据,整组覆盖,songs=[] 清空;一集最多 3 首)。歌来源三选一:①客户自己的歌——先 upload-url(kind=audio)上传拿 public_url 当 audio_url;②平台作曲/曲库——带 track_id(get_mv_song、list 曲库返回的 id);③已有 https 地址。placement:opening=片头(从 0 开始,放到歌完或 sb_to 那镜结束)/ending=片尾(贴片尾,或从 sb_from 那镜开始)/range=sb_from~sb_to 镜头段落(两端必填)。人声不和台词打架:给了 instrumental_url(同一首歌的伴奏轨)默认 dialogue_mode=instrumental——有台词时人声渐隐、伴奏接上,说完换回;只有原曲则 dialogue_mode=duck——有台词时整首压低 duck_db(默认 -18dB)。主题曲播放区间里配乐自动让开(bgm_yield,默认 true),区间外照常。gain_db 默认 -8,track_offset_ms 跳过前奏。改完调 compose_episode 重新终拼生效;enabled=false 表示本剧尚未开通。★别自己下载成片混音再上传。",
+        "tags": [
+          "episodes"
+        ],
+        "parameters": [
+          {
+            "name": "episode_id",
+            "in": "path",
+            "required": true,
+            "schema": {
+              "type": "integer",
+              "exclusiveMinimum": 0
+            }
+          }
+        ],
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "type": "object",
+                "properties": {
+                  "songs": {
+                    "type": "array",
+                    "items": {
+                      "type": "object",
+                      "properties": {
+                        "audio_url": {
+                          "type": "string",
+                          "description": "原曲(带人声)https 地址或 static/ 路径;与 track_id 二选一"
+                        },
+                        "track_id": {
+                          "type": "integer",
+                          "exclusiveMinimum": 0,
+                          "description": "曲库/平台作曲的曲目 id(本人上传或公开的)"
+                        },
+                        "instrumental_url": {
+                          "type": "string",
+                          "description": "同一首歌的伴奏轨(与原曲逐采样对齐);给了才能「台词段只留伴奏」"
+                        },
+                        "placement": {
+                          "type": "string",
+                          "enum": [
+                            "opening",
+                            "ending",
+                            "range"
+                          ]
+                        },
+                        "sb_from": {
+                          "type": "integer",
+                          "exclusiveMinimum": 0,
+                          "description": "起镜号(storyboard_number)"
+                        },
+                        "sb_to": {
+                          "type": "integer",
+                          "exclusiveMinimum": 0,
+                          "description": "止镜号(含)"
+                        },
+                        "track_offset_ms": {
+                          "type": "integer",
+                          "minimum": 0,
+                          "description": "从曲内第几毫秒开始放(跳过前奏)"
+                        },
+                        "gain_db": {
+                          "type": "number",
+                          "minimum": -30,
+                          "maximum": 6,
+                          "description": "主题曲音量 dB,默认 -8"
+                        },
+                        "fade_in_ms": {
+                          "type": "integer",
+                          "minimum": 0,
+                          "maximum": 10000,
+                          "description": "默认 1000"
+                        },
+                        "fade_out_ms": {
+                          "type": "integer",
+                          "minimum": 0,
+                          "maximum": 10000,
+                          "description": "默认 2000"
+                        },
+                        "dialogue_mode": {
+                          "type": "string",
+                          "enum": [
+                            "duck",
+                            "instrumental"
+                          ],
+                          "description": "有台词时:duck=整首压低;instrumental=切伴奏(需 instrumental_url)"
+                        },
+                        "duck_db": {
+                          "type": "number",
+                          "minimum": -40,
+                          "maximum": 0,
+                          "description": "duck 模式压低量 dB,默认 -18"
+                        },
+                        "bgm_yield": {
+                          "type": "boolean",
+                          "description": "播放区间里配乐让开,默认 true"
+                        }
+                      },
+                      "required": [
+                        "placement"
+                      ],
+                      "additionalProperties": false
+                    },
+                    "maxItems": 3,
+                    "description": "整组主题曲;[] = 清空"
+                  }
+                },
+                "required": [
+                  "songs"
+                ]
+              }
+            }
+          }
+        },
+        "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}/transitions": {
       "post": {
         "operationId": "generate_transitions",
@@ -15621,6 +15814,199 @@
         }
       }
     },
+    "/storyboards/{storyboard_id}/verse-cards": {
+      "get": {
+        "operationId": "get_shot_verse_cards",
+        "summary": "读这一镜的诗句/歌词字卡现值(免费)",
+        "description": "读这一镜的诗句/歌词字卡现值(免费)。set_shot_verse_cards 是**整组覆盖**,改之前先读。enabled=false 表示本剧尚未开通(存了也暂不进成片)。",
+        "tags": [
+          "storyboards"
+        ],
+        "parameters": [
+          {
+            "name": "storyboard_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"
+          }
+        }
+      },
+      "put": {
+        "operationId": "set_shot_verse_cards",
+        "summary": "给某一镜加/改/清「诗句·歌词字卡」(终拼时烧进成片;免费纯数据)",
+        "description": "给某一镜加/改/清「诗句·歌词字卡」(终拼时烧进成片;免费纯数据)。一镜最多 6 张,**整组覆盖**(先 get_shot_verse_cards 读现值再改),cards=[] 清空。国风电影感短片的三种标配都走它:①画面一侧/居中淡入的竖排或横排诗句、歌词(text 里换行=另起一列/一行,标点原样保留,可多张错开 start_ms 依次出现);②整屏黑底结语卡 backdrop=\"black\"(通常放末镜,orient=horizontal、position=center);③叠在画面上的片尾名单 motion=\"scroll_up\"(自下而上滚动,一行一个名字,空行分组)。字卡自动避开对白字幕所在的那条带,不会与台词重叠;字号放不下会自动缩小,不会顶出画面。改完调 compose_episode 重新终拼生效(rerender_episode 沿用已存时间轴,带不上)。get_shot_verse_cards 的 enabled=false 表示本剧尚未开通(存了也暂不进成片)。★别自己下载视频叠字再上传——那会绕开渲染机字体与字幕避让。★文字只写客户给的诗句/名单,别替客户编。",
+        "tags": [
+          "storyboards"
+        ],
+        "parameters": [
+          {
+            "name": "storyboard_id",
+            "in": "path",
+            "required": true,
+            "schema": {
+              "type": "integer",
+              "exclusiveMinimum": 0
+            }
+          }
+        ],
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "type": "object",
+                "properties": {
+                  "cards": {
+                    "type": "array",
+                    "items": {
+                      "type": "object",
+                      "properties": {
+                        "text": {
+                          "type": "string",
+                          "minLength": 1,
+                          "description": "字卡文字;换行=另起一列(竖排)/一行(横排);≤300 字"
+                        },
+                        "orient": {
+                          "type": "string",
+                          "enum": [
+                            "vertical",
+                            "horizontal"
+                          ],
+                          "description": "默认 vertical 竖排(从右往左);滚动名单自动横排"
+                        },
+                        "position": {
+                          "type": "string",
+                          "enum": [
+                            "left",
+                            "right",
+                            "center"
+                          ],
+                          "description": "默认 right;滚动名单默认 center"
+                        },
+                        "start_ms": {
+                          "type": "integer",
+                          "minimum": 0,
+                          "maximum": 60000,
+                          "description": "镜内起点毫秒(相对本镜开头),默认 0"
+                        },
+                        "duration_ms": {
+                          "type": "integer",
+                          "minimum": 500,
+                          "maximum": 60000,
+                          "description": "显示时长,默认 4000;超出本镜部分截掉"
+                        },
+                        "fade_in_ms": {
+                          "type": "integer",
+                          "minimum": 0,
+                          "maximum": 5000,
+                          "description": "淡入毫秒,默认 600"
+                        },
+                        "fade_out_ms": {
+                          "type": "integer",
+                          "minimum": 0,
+                          "maximum": 5000,
+                          "description": "淡出毫秒,默认 600"
+                        },
+                        "font_size": {
+                          "type": "integer",
+                          "minimum": 20,
+                          "maximum": 200,
+                          "description": "字号上限(输出像素),默认 64;放不下自动缩小"
+                        },
+                        "font": {
+                          "type": "string",
+                          "description": "字体名,默认行书 Zhi Mang Xing;规整宋体填 Noto Serif CJK SC(渲染机已装的才生效)"
+                        },
+                        "backdrop": {
+                          "type": "string",
+                          "enum": [
+                            "none",
+                            "black"
+                          ],
+                          "description": "black = 整屏黑底结语卡"
+                        },
+                        "motion": {
+                          "type": "string",
+                          "enum": [
+                            "static",
+                            "scroll_up"
+                          ],
+                          "description": "scroll_up = 自下而上滚动的片尾名单"
+                        }
+                      },
+                      "required": [
+                        "text"
+                      ],
+                      "additionalProperties": false
+                    },
+                    "maxItems": 6,
+                    "description": "整组字卡(顺序即渲染顺序);[] = 清空本镜字卡"
+                  }
+                },
+                "required": [
+                  "cards"
+                ]
+              }
+            }
+          }
+        },
+        "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"
+          }
+        }
+      }
+    },
     "/storyboards/{storyboard_id}/video-lock": {
       "post": {
         "operationId": "lock_shot_video",

package/package.json

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