@starreel/mcp 0.1.212 → 0.1.213

package/SKILL.md

@@ -1561,7 +1561,18 @@ to close") tells the vendor to fit that entire sequence into each 3-second shot.
   gone and you should regenerate that shot rather than paper over it). Check per line
   with `shots[].spoken_lines[]`: subtitles are per-line but audio is per-shot, so
   **having subtitles never means having sound**; every shot must be cut to
-  `trim_head_ms`/`duration_ms` or you splice in frames the platform already QC'd out;
+  `trim_head_ms`/`duration_ms` or you splice in frames the platform already QC'd out.
+  Since `manifest_version` **0.2** those in/out points are projected from the
+  platform's own final-cut timeline (the same numbers `build_av_timing_contract`
+  reports, the same cut `compose_episode` renders) and `clip.url` is the file that
+  timeline actually uses (`clip.source_kind`); 0.1 packs computed their own trim and
+  did not match the platform cut. Honour `speed_factor` (retime the shot) and
+  `freeze_pad_ms` (clone the last frame) —
+  `duration_ms = (out_ms − in_ms) / speed_factor + freeze_pad_ms`; don't burn
+  subtitles again on `subtitles_burned_in=true` shots or apply the LUT on
+  `color_graded=true` shots; `trim_basis` other than `platform_timeline` means the
+  shot is untrimmed and `notes` say why. A saved toolchain that only accepts 0.1
+  will refuse a 0.2 manifest — run `save_handoff_toolchain` again;
   and all subtitle/dialogue/SFX offsets are relative to **each shot's own trimmed
   start**, not to the final timeline — add whatever overlapping transitions you like
   and let `compile_timeline.py` expand them, never hand-compute the shift.

package/assets/handoff/assemble.sh

@@ -77,14 +77,33 @@ for i in $(seq 0 $((NSHOTS - 1))); do
   SRC="${PACK}/$(jq -r '.file' <<<"${S}")"
   SS=$(ms2s "$(jq -r '.trim_head_ms' <<<"${S}")")
   DUR=$(ms2s "$(jq -r '.duration_ms' <<<"${S}")")
+  # 0.2：源片取 TAKE 毫秒，按 SPEED 变速，不够长的部分克隆末帧补 PAD（与平台渲染器同一做法）
+  TAKE=$(ms2s "$(jq -r '.src_take_ms // .duration_ms' <<<"${S}")")
+  SPEED=$(jq -r '.speed_factor // 1' <<<"${S}")
+  # 原声可能比视频流长（厂商音频尾 / 口型片按容器时长取材）：输入按整段播放所需的源片时长读，
+  # 视频再单独截到 TAKE —— 输入 -t 会连音频一起截掉，后面 apad 补出来的只是静音
+  READ=$(awk -v d="$(jq -r '.duration_ms' <<<"${S}")" -v s="${SPEED}" -v t="$(jq -r '.src_take_ms // .duration_ms' <<<"${S}")" \
+    'BEGIN{r=d*s; if(r<t)r=t; printf "%.3f", r/1000}')
+  PAD=$(jq -r '.freeze_pad_ms // 0' <<<"${S}")
   BAKED=$(jq -r '.has_baked_audio' <<<"${S}")
+  # 已调色的合成片不再套查找表（双重调色）
+  SHOT_LUT="${LUT_FILE}"
+  [ "$(jq -r '.color_graded // false' <<<"${S}")" = "true" ] && SHOT_LUT=""
+  # 人声烤在片里（逐镜判定，不看整集 mode）且片子真有音轨 → 用片子原声
+  HAS_A=$(ffprobe -v error -select_streams a -show_entries stream=index -of csv=p=0 "${SRC}" | head -1)
   DST="${TMP}/shot_$(printf '%03d' "${N}").mkv"
 
   # 中间产物一律 mkv + pcm_s16le：aac 每段都带 ~21ms(1024 samples) 编码器 priming
   # delay，走 adelay/amix 时每镜音频会整体提前约半帧，重叠转场下误差还会叠加。
   # 只在阶段 4 最后一次编 aac。
   # 视频：先 trim 再统一到目标画布/帧率。scale+pad 保证不同源尺寸也能拼。
-  VF="scale=${W}:${H}:force_original_aspect_ratio=decrease,pad=${W}:${H}:(ow-iw)/2:(oh-ih)/2,setsar=1,fps=${FPS}"
+  VF="trim=duration=${TAKE},setpts=PTS-STARTPTS,scale=${W}:${H}:force_original_aspect_ratio=decrease,pad=${W}:${H}:(ow-iw)/2:(oh-ih)/2,setsar=1,fps=${FPS}"
+  AF="anull"
+  if [ "${SPEED}" != "1" ]; then
+    VF="${VF/setpts=PTS-STARTPTS,/setpts=(PTS-STARTPTS)/${SPEED},}"
+    AF="atempo=${SPEED}"
+  fi
+  [ "${PAD}" != "0" ] && VF="${VF},tpad=stop_mode=clone:stop_duration=$(ms2s "${PAD}")"
 
   # baked-cut（闪白/闪黑）：硬切 + 本镜片头快速过曝/压黑，**不重叠**。
   # 平台实测：这类效果走 xfade 会变成双重闪 + 130ms 重叠 + 口型/音频瞬断，
@@ -96,65 +115,53 @@ for i in $(seq 0 $((NSHOTS - 1))); do
     VF="${VF},fade=t=in:st=0:d=$(ms2s "${FMS}"):color=${FLASH}"
   fi
 
-  INPUTS=(-ss "${SS}" -t "${DUR}" -i "${SRC}")
-  if [ "${MODE}" = "clip" ] && [ "${BAKED}" = "true" ]; then
-    # 裸片自带人声：直接用它的音轨，绝不再叠对白（叠了就是双声）
-    if [ -n "${LUT_FILE}" ]; then
-      ffmpeg -hide_banner -loglevel error -y "${INPUTS[@]}" -i "${LUT_FILE}" \
-        -filter_complex "[0:v]${VF}[g];[g][1:v]haldclut[v]" \
-        -map "[v]" -map 0:a:0? \
-        -c:v libx264 -b:v "${VB}" -pix_fmt yuv420p -c:a pcm_s16le -ar 48000 -ac 2 \
-        -shortest "${DST}"
-    else
-      ffmpeg -hide_banner -loglevel error -y "${INPUTS[@]}" \
-        -vf "${VF}" -map 0:v:0 -map 0:a:0? \
-        -c:v libx264 -b:v "${VB}" -pix_fmt yuv420p -c:a pcm_s16le -ar 48000 -ac 2 \
-        -shortest "${DST}"
-    fi
-  else
-    # TTS 模式：裸片无人声。静音底 + 对白 + 音效，全部按镜内 offset 落位。
-    # 输入索引是固定契约：0=静音底  1=视频  2..=对白/音效（按下面的追加顺序）
-    INPUTS=(-f lavfi -t "${DUR}" -i "anullsrc=r=48000:cl=stereo"
-            -ss "${SS}" -t "${DUR}" -i "${SRC}")
-    FILTER=""; LABELS="[0:a]"; IDX=2
+  # 静音底 + （人声烤在片里时）片子原声 + 对白 + 音效，全部按镜内 offset 落位。
+  # 输入索引是固定契约：0=静音底  1=视频  2..=对白/音效（按下面的追加顺序）
+  INPUTS=(-f lavfi -t "${DUR}" -i "anullsrc=r=48000:cl=stereo"
+          -ss "${SS}" -t "${READ}" -i "${SRC}")
+  FILTER=""; LABELS="[0:a]"; IDX=2; NCLIP=0
 
-    DLG=$(jq -c '.dialogue // empty' <<<"${S}")
-    if [ -n "${DLG}" ] && [ "${DLG}" != "null" ]; then
-      DOFF=$(jq -r '.offset_ms // 0' <<<"${DLG}")
-      DGAIN=$(jq -r '.gain_db // 0' <<<"${DLG}")
-      INPUTS+=(-i "${PACK}/$(jq -r '.file' <<<"${DLG}")")
-      FILTER+="[${IDX}:a]adelay=${DOFF}|${DOFF},volume=${DGAIN}dB[d];"
-      LABELS+="[d]"; IDX=$((IDX + 1))
-    fi
+  # 人声烤在片里（逐镜判定，不看整集 mode）：用片子原声，绝不再叠对白（叠了就是双声）；补帧段补静音
+  if [ "${BAKED}" = "true" ] && [ -n "${HAS_A}" ]; then
+    FILTER+="[1:a]${AF},apad[c];"; LABELS+="[c]"; NCLIP=1
+  fi
 
-    NSFX=$(jq -r '.sfx | length' <<<"${S}")
-    for ((j = 0; j < NSFX; j++)); do
-      X=$(jq -c ".sfx[${j}]" <<<"${S}")
-      XOFF=$(jq -r '.offset_ms // 0' <<<"${X}")
-      XGAIN=$(jq -r '.gain_db // 0' <<<"${X}")
-      INPUTS+=(-i "${PACK}/$(jq -r '.file' <<<"${X}")")
-      FILTER+="[${IDX}:a]adelay=${XOFF}|${XOFF},volume=${XGAIN}dB[x${j}];"
-      LABELS+="[x${j}]"; IDX=$((IDX + 1))
-    done
+  DLG=$(jq -c '.dialogue // empty' <<<"${S}")
+  if [ "${BAKED}" != "true" ] && [ -n "${DLG}" ] && [ "${DLG}" != "null" ]; then
+    DOFF=$(jq -r '.offset_ms // 0' <<<"${DLG}")
+    DGAIN=$(jq -r '.gain_db // 0' <<<"${DLG}")
+    INPUTS+=(-i "${PACK}/$(jq -r '.file' <<<"${DLG}")")
+    FILTER+="[${IDX}:a]adelay=${DOFF}|${DOFF},volume=${DGAIN}dB[d];"
+    LABELS+="[d]"; IDX=$((IDX + 1))
+  fi
 
-    # 混入静音底：amix 的 inputs = 底轨 + 对白 + 音效，normalize=0 保住各自增益
-    NMIX=$((IDX - 1))
-    FILTER+="${LABELS}amix=inputs=${NMIX}:normalize=0:dropout_transition=0[aout]"
+  NSFX=$(jq -r '.sfx | length' <<<"${S}")
+  for ((j = 0; j < NSFX; j++)); do
+    X=$(jq -c ".sfx[${j}]" <<<"${S}")
+    XOFF=$(jq -r '.offset_ms // 0' <<<"${X}")
+    XGAIN=$(jq -r '.gain_db // 0' <<<"${X}")
+    INPUTS+=(-i "${PACK}/$(jq -r '.file' <<<"${X}")")
+    FILTER+="[${IDX}:a]adelay=${XOFF}|${XOFF},volume=${XGAIN}dB[x${j}];"
+    LABELS+="[x${j}]"; IDX=$((IDX + 1))
+  done
 
-    if [ -n "${LUT_FILE}" ]; then
-      INPUTS+=(-i "${LUT_FILE}")
-      ffmpeg -hide_banner -loglevel error -y "${INPUTS[@]}" \
-        -filter_complex "${FILTER};[1:v]${VF}[g];[g][${IDX}:v]haldclut[v]" \
-        -map "[v]" -map "[aout]" -t "${DUR}" \
-        -c:v libx264 -b:v "${VB}" -pix_fmt yuv420p -c:a pcm_s16le -ar 48000 -ac 2 \
-        "${DST}"
-    else
-      ffmpeg -hide_banner -loglevel error -y "${INPUTS[@]}" \
-        -filter_complex "${FILTER}" \
-        -map 1:v:0 -vf "${VF}" -map "[aout]" -t "${DUR}" \
-        -c:v libx264 -b:v "${VB}" -pix_fmt yuv420p -c:a pcm_s16le -ar 48000 -ac 2 \
-        "${DST}"
-    fi
+  # 混入静音底：amix 的 inputs = 底轨 + 片子原声 + 对白 + 音效，normalize=0 保住各自增益
+  NMIX=$((IDX - 1 + NCLIP))
+  FILTER+="${LABELS}amix=inputs=${NMIX}:normalize=0:dropout_transition=0[aout]"
+
+  if [ -n "${SHOT_LUT}" ]; then
+    INPUTS+=(-i "${SHOT_LUT}")
+    ffmpeg -hide_banner -loglevel error -y "${INPUTS[@]}" \
+      -filter_complex "${FILTER};[1:v]${VF}[g];[g][${IDX}:v]haldclut[v]" \
+      -map "[v]" -map "[aout]" -t "${DUR}" \
+      -c:v libx264 -b:v "${VB}" -pix_fmt yuv420p -c:a pcm_s16le -ar 48000 -ac 2 \
+      "${DST}"
+  else
+    ffmpeg -hide_banner -loglevel error -y "${INPUTS[@]}" \
+      -filter_complex "${FILTER}" \
+      -map 1:v:0 -vf "${VF}" -map "[aout]" -t "${DUR}" \
+      -c:v libx264 -b:v "${VB}" -pix_fmt yuv420p -c:a pcm_s16le -ar 48000 -ac 2 \
+      "${DST}"
   fi
   echo "file '$(cd "$(dirname "${DST}")" && pwd)/$(basename "${DST}")'" >> "${TMP}/concat.txt"
 done

package/assets/handoff/compile_timeline.py

@@ -120,8 +120,8 @@ def write_srt(path, cues):
 # ── 编译 ───────────────────────────────────────────────────────────────────
 def compile_timeline(pack_dir, plan_path=None, outdir=None):
     manifest = json.load(open(os.path.join(pack_dir, "manifest.json"), encoding="utf-8"))
-    if manifest.get("manifest_version") != "0.1":
-        sys.exit(f"不认识的 manifest_version: {manifest.get('manifest_version')!r}，拒绝猜测")
+    if manifest.get("manifest_version") not in ("0.1", "0.2"):
+        sys.exit(f"不认识的 manifest_version: {manifest.get('manifest_version')!r}，拒绝猜测（工具链过旧请重新 save_handoff_toolchain）")
 
     overlaps, trans = {}, {}
     if plan_path:
@@ -185,6 +185,12 @@ def compile_timeline(pack_dir, plan_path=None, outdir=None):
             "trim_head_ms": int(sh["clip"].get("trim_head_ms", 0)),
             "trim_tail_ms": int(sh["clip"].get("trim_tail_ms", 0)),
             "duration_ms": dur,
+            # 0.2：源片实际取多少（变速 / 定格补帧时 ≠ duration_ms）；0.1 没有这些字段 = 常速整取
+            "src_take_ms": int(sh["clip"]["out_ms"]) - int(sh["clip"]["in_ms"])
+                           if sh["clip"].get("out_ms") is not None and sh["clip"].get("in_ms") is not None else dur,
+            "speed_factor": float(sh["clip"].get("speed_factor") or 1),
+            "freeze_pad_ms": int(sh["clip"].get("freeze_pad_ms") or 0),
+            "color_graded": bool(sh["clip"].get("color_graded")),
             "in_ms": in_ms,
             "overlap_ms": ov,
             "has_baked_audio": bool(sh["clip"].get("has_baked_audio")),

package/assets/handoff/fetch_pack.py

@@ -148,8 +148,9 @@ def main():
     # MCP 工具可能把 manifest 包在 data 里返回，两种都认
     m = m.get("data", m) if isinstance(m.get("data"), dict) else m
 
-    if m.get("manifest_version") != "0.1":
-        sys.exit(f"不认识的 manifest_version: {m.get('manifest_version')!r}，拒绝猜测")
+    # 0.2 = 入出点投影自平台终拼时间轴（新增 speed_factor / freeze_pad_ms / subtitles_burned_in 等）；0.1 仍认
+    if m.get("manifest_version") not in ("0.1", "0.2"):
+        sys.exit(f"不认识的 manifest_version: {m.get('manifest_version')!r}，拒绝猜测（工具链过旧请重新 save_handoff_toolchain）")
 
     out = a.outdir
     local_color = (m.get("postproduction") or {}).get("workflow") == "local_color"
@@ -181,7 +182,10 @@ def main():
         clip = sh.get("clip") or {}
         if clip.get("url"):
             rel = f"clips/shot_{tag}.mp4"
-            expected_hashes[rel] = (sh.get("provenance") or {}).get("generation_sha256")
+            prov = sh.get("provenance") or {}
+            # 0.2：按实际交付文件的摘要校验；发的是合成 / 口型 / 换轨片时没有落库摘要（null）= 不校验，
+            # 绝不拿原片摘要去比派生片。0.1 清单没有这个键，沿用原片摘要
+            expected_hashes[rel] = prov["delivered_sha256"] if "delivered_sha256" in prov else prov.get("generation_sha256")
             jobs.append((clip.pop("url"), rel))
             clip["file"] = rel
 
@@ -200,6 +204,10 @@ def main():
 
         # 内联 cues → 逐镜 SRT（时间码基准仍是「该镜 trim 后的第 0 毫秒」，不做任何平移）
         cues = ((sh.get("subtitle") or {}).get("cues")) or []
+        if cues and clip.get("subtitles_burned_in"):
+            # 旧版合成片已烧字幕：不出 SRT，否则装配时再烧一层
+            print(f"镜 {n}: 片里已烧字幕（subtitles_burned_in），跳过 SRT", file=sys.stderr)
+            cues = []
         if cues:
             rel = f"subs/shot_{tag}.srt"
             cnt = write_srt(os.path.join(out, rel), cues)

package/dist/i18n/tools.en.json

@@ -241,7 +241,7 @@
   "save_designed_voice": "Save the candidate selected by the client into the voice library and return voice_id (like lib:12). **Charged the same as voice cloning** (saving the same candidate repeatedly does not charge again). Then bind it to a character with set_character_voice (narrator is also a character) before using it for dubbing; you can also use speak_with_voice first to audition more sentences.",
   "set_character_voice": "Bind a voice to a character; later generate_tts will use it to dub that character. Free. This is only needed when producing video—cloning and auditioning do not require a character.\n★★【In native-audio dramas (use_clip_audio=true, default), this step is “voice locking”】When the bound voice is **the client’s own authorized voice** (cloned by clone_voice / uploaded by the client, not a public voice), later video generation will pass this audio directly to the video vendor as reference audio. The vendor will speak according to it, and lip sync is naturally aligned—otherwise each group/single shot samples the voice independently, so the same character’s voice may drift across shots. Public voices are only used for TTS dubbing and will not be passed to the vendor.\n★Cost: shots where this character appears will no longer feed a character-sheet video anchor during video generation (the reference video’s audio track overrides reference audio; only one can be used). Character identity must instead be carried by the character sheet/reference images—so confirm the character sheet and reference images are ready before binding.\n★Only affects videos generated **after binding**: bind first, then generate_videos. For videos already generated, the cheapest way to unify the voice is repair_episode_dialogue (only_flagged=false, re-dub full lines with the cloned voice, do not regenerate video, charged at the TTS tier); regenerate_shot_video also works but is orders of magnitude more expensive.\n★After binding, assign_voices will no longer overwrite this character (the client’s own voice has highest priority).",
   "set_voice_anchor_from_shot": "Select a character’s voice line (voice baseline) from a shot in this episode. Free. No external audio source is required from the client—use the voice this character has already spoken in the video.\n★★【In native-audio dramas (use_clip_audio=true, default), this is “voice locking”】After selection, later video generation will pass this audio to the video vendor as reference audio, so the same character’s voice across shots follows it; without locking, the vendor samples each shot independently and the voice may drift across shots.\n★Which shot to choose: a shot where the character **speaks alone, has a longer line, and has no background music or interruptions by others**; start_s/dur_s can clip only part of it (if omitted, the default window is used, and duration is automatically clamped to each engine’s limit).\n★Only affects videos generated **afterward**. Shots already generated before locking will appear in get_pipeline_status under native_voice_anchor.stale_shots; regenerate them with regenerate_shot_video to unify the voice. The cheapest workflow is: generate one shot for each speaking character first, select the voice line, then batch-generate the remaining shots.\n★Works even if the dialogue field is empty: actual audio is authoritative—the platform uses calibrated voice activity detection to confirm there is speech in the selected interval, and uses the transcription text as anchor text; if no speech is detected or no usable text can be transcribed, it rejects (a wrong anchor would pollute all later shots’ voices, so reject rather than guess). The response field text_source indicates whether text came from dialogue or transcription.\n★Preview first with preview:true: only clips and returns preview_url plus anchor text, **without writing to the character**; if it sounds right, remove preview and formally submit with the same start_s/dur_s.\n★Noise removal and acceptance check (effective when enabled by the platform for the episode; response contains hygiene): automatically removes pure environmental-noise pauses between two lines and measures sample noise floor (noise_floor_before/after, threshold threshold). In preview, preview_url is the **cleaned** sample and raw_preview_url is the original—**ask the client to compare both before/after by listening**. verdict=fail means obvious environmental noise or music is under the voice (removing pauses cannot fix it; cloning and the video vendor will learn it as part of the timbre), and formal submission will be rejected: choose a cleaner shot, or adjust start_s/dur_s to avoid background sound; only pass allow_issues:true to write it if the client has listened and explicitly insists.\n★If the client has an authorized external audio source, use clone_voice + set_character_voice instead; choose one of the two, and the later setting overrides the earlier one.",
-  "export_handoff_pack": "After delivery traceability is enabled, an immutable export manifest is saved (assets are not modified). Keep pack_id and manifest_sha256, and reference them when returning an external final cut. Export the “asset handoff package” manifest for this episode: downloadable URLs for each-shot raw clips + dialogue tracks + sound effects + music + subtitles, for you to complete transition decisions, stitching, mixing, and subtitle burn-in **on your own side**—the platform does not participate in final assembly. Free, zero credits.\n★Local color grading / third-party AI post: purpose=local_color; when there are only images, pass media_type=images, no need to generate video. This mode preserves source files, disables the export package’s automatic LUT, and includes post-production notes and a local comparison-page flow; it does not upload to third parties, charge for generation, or backfill the platform. Image sources may already have been processed, so not all exported images can be promised as ungraded originals.\n\n【Recommended workflow】① Call this tool to get manifest; ② Download raw clips locally via clips[].url; ③ Watch the clips yourself and decide which transition to use at each seam (manifest provides scene_boundary as a scene-boundary criterion), write a plan.json; ④ Use get_handoff_toolchain to get compile_timeline.py to expand the timeline and assemble.sh to assemble the final cut. The toolchain already calculates how subtitles/dialogue/SFX shift after overlapping transitions are added.\n\n【Three facts that will break things if ignored】\n① **Where the voice is must be read per shot from `shots[].voice_track.location`, not from the episode-level audio_contract.mode**—the latter is an episode-level declaration, while in all-offscreen-narration shots the narration is mixed into the raw clip on the platform completion side, so it can differ per shot within the same episode. The four values require different handling: `separate_file`=dialogue is in dialogue_audio; if you do not lay it in, this shot has no lines; `baked_in_clip`=already in the raw clip audio track; overlaying it again causes double voice; `missing`=**platform side confirmed missing** (narration compensation failed); subtitles still exist but the sound is nowhere—regenerate this shot on the platform; extending a transition cannot hide it; `unknown`=there are lines but the source cannot be found, **you must listen to the raw clip** before deciding. ★Subtitles never imply there is sound: subtitles are per sentence, audio is per shot. For shots with `conflicts_with_contract=true`, trust measurement; notes already name them by shot number.\n② Each shot must be trimmed using trim_head_ms / duration_ms before use; directly stitching the full raw clip will include head/tail deformed frames that the platform already QC’d out.\n③ Subtitle cues, dialogue_audio.offset_ms, and sfx[].offset_ms are all based on “millisecond 0 after this shot’s trim”, not absolute final-cut time. No matter how many overlapping transitions you add, do not modify them—let compile_timeline.py expand them; do not manually accumulate times.\n\nBefore you assemble, run build_av_timing_contract → get_av_timing_contract (free): per shot the measured source length, the platform final cut's in/out points, transition overlap and freeze padding, and whether the voice is already mixed into the clip or on a separate track — check your timeline's total against it.\n\nIf you want the platform to assemble it, or need platform-level quality gates (final assembly precheck / equal audio-video duration / loudness mastering), use compose_episode.",
+  "export_handoff_pack": "After delivery traceability is enabled, an immutable export manifest is saved (assets are not modified). Keep pack_id and manifest_sha256, and reference them when returning an external final cut. Export the “asset handoff package” manifest for this episode: downloadable URLs for each-shot raw clips + dialogue tracks + sound effects + music + subtitles, for you to complete transition decisions, stitching, mixing, and subtitle burn-in **on your own side**—the platform does not participate in final assembly. Free, zero credits.\n★Local color grading / third-party AI post: purpose=local_color; when there are only images, pass media_type=images, no need to generate video. This mode preserves source files, disables the export package’s automatic LUT, and includes post-production notes and a local comparison-page flow; it does not upload to third parties, charge for generation, or backfill the platform. Image sources may already have been processed, so not all exported images can be promised as ungraded originals.\n\n【Recommended workflow】① Call this tool to get manifest; ② Download raw clips locally via clips[].url; ③ Watch the clips yourself and decide which transition to use at each seam (manifest provides scene_boundary as a scene-boundary criterion), write a plan.json; ④ Use get_handoff_toolchain to get compile_timeline.py to expand the timeline and assemble.sh to assemble the final cut. The toolchain already calculates how subtitles/dialogue/SFX shift after overlapping transitions are added.\n\n【Three facts that will break things if ignored】\n① **Where the voice is must be read per shot from `shots[].voice_track.location`, not from the episode-level audio_contract.mode**—the latter is an episode-level declaration, while in all-offscreen-narration shots the narration is mixed into the raw clip on the platform completion side, so it can differ per shot within the same episode. The four values require different handling: `separate_file`=dialogue is in dialogue_audio; if you do not lay it in, this shot has no lines; `baked_in_clip`=already in the raw clip audio track; overlaying it again causes double voice; `missing`=**platform side confirmed missing** (narration compensation failed); subtitles still exist but the sound is nowhere—regenerate this shot on the platform; extending a transition cannot hide it; `unknown`=there are lines but the source cannot be found, **you must listen to the raw clip** before deciding. ★Subtitles never imply there is sound: subtitles are per sentence, audio is per shot. For shots with `conflicts_with_contract=true`, trust measurement; notes already name them by shot number.\n② Each shot must be trimmed using trim_head_ms / duration_ms before use; directly stitching the full raw clip will include head/tail deformed frames that the platform already QC’d out. ★From manifest_version=0.2 the in/out points are projected from the platform's final-cut timeline (the same as build_av_timing_contract and the platform cut), and clip.url is the file that timeline actually uses (clip.source_kind); in 0.1 the pack computed its own trim, which did not match the platform cut. speed_factor≠1 must be retimed by that factor and freeze_pad_ms>0 must be filled by cloning the last frame (duration_ms=(out_ms−in_ms)/speed_factor+freeze_pad_ms), or the total length will not match; subtitles_burned_in=true means do not burn subtitles again, color_graded=true means do not apply the LUT again; shots with trim_basis≠platform_timeline are untrimmed, and notes say why. An old toolchain copy that only accepts 0.1 will reject 0.2 — run save_handoff_toolchain again.\n③ Subtitle cues, dialogue_audio.offset_ms, and sfx[].offset_ms are all based on “millisecond 0 after this shot’s trim”, not absolute final-cut time. No matter how many overlapping transitions you add, do not modify them—let compile_timeline.py expand them; do not manually accumulate times.\n\nBefore you assemble, run build_av_timing_contract → get_av_timing_contract (free): per shot the measured source length, the platform final cut's in/out points, transition overlap and freeze padding, and whether the voice is already mixed into the clip or on a separate track — check your timeline's total against it.\n\nIf you want the platform to assemble it, or need platform-level quality gates (final assembly precheck / equal audio-video duration / loudness mastering), use compose_episode.",
   "get_handoff_toolchain": "Get the source code for the asset handoff package assembly toolchain (compile_timeline.py timeline compiler / assemble.sh ffmpeg assembly script). Free. This tool only returns source text and **will not** write files on your machine—save it to your working directory yourself before running.\ncompile_timeline.py expands “shot-relative” subtitle/dialogue/SFX anchors into absolute timecodes on your own timeline and handles global offsets caused by overlapping transitions; assemble.sh is a complete ffmpeg assembly baseline from raw clips to final cut (trim → normalize → concat/xfade → music sidechain → subtitles → two-pass master). Dependencies: ffmpeg (with libass for subtitle burn-in), ffprobe, jq, python3.",
   "save_handoff_toolchain": "Write the assembly toolchain (fetch_pack.py / compile_timeline.py / assemble.sh) directly to a local directory, avoiding manual copy/paste. Free. The directory must **already exist** and be an absolute path; filenames are fixed and cannot be customized.\nRefuses to write into hidden directories (~/.ssh, ~/.config, .git…) and system directories—this is disk writing, not reading, and overwriting the wrong place is irreversible.\nFull workflow after writing to disk:\n  python3 fetch_pack.py manifest.json -o ./pack   # Download assets and materialize inline subtitles as SRT\n  python3 compile_timeline.py ./pack [--transitions plan.json]\n  ./assemble.sh ./pack out.mp4 [plan.json]",
   "get_post_production_checklist": "Read this episode's **post-production effects checklist** (free). Items marked in the script as [VFX: …] or written in shot prompts as \"post-production / composited later\" are **not composited by the platform**—image and video generation leave them out and the final cut does not add them, so the finished episode lacks these story elements unless handled. Per item: shot_number, time start_s~end_s, content, source (vfx_tag shot annotation / prompt / script_unassigned = in the rewritten script but not attached to any shot), narrative_required (story-critical; cosmetic items such as color grading are false), status (pending / done_external / waived). ★Review before composing; tell the client about narrative_required pending items and ask: do it in external post (then mark_post_production_item done_external), change the shot so the platform draws it (update_shot then regenerate that shot), or drop it (waived). review_videos / compose_episode give an advisory for unhandled items.",

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

@@ -256,7 +256,7 @@
   "save_designed_voice": "把客户挑中的那条候选存进音色库,返回 voice_id(形如 lib:12)。**按声音克隆同价扣费**(同一条重复保存不重复扣)。之后用 set_character_voice 绑到角色(旁白也是一个角色)才会用它配音;也可以先 speak_with_voice 试听更多句子。",
   "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 不会再覆盖这个角色(客户自己的声音优先级最高)。",
   "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 掉的首尾形变帧一起拼进去。\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。",
+  "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]"
 }

package/dist/tools/produce.js

@@ -2637,7 +2637,11 @@ export function registerProduceTools(server, client) {
         '★有字幕从来不等于有声音:字幕是逐句的,音频是逐镜的。`conflicts_with_contract=true` 的镜' +
         '以实测为准,notes 里已按镜号点名。\n' +
         '② 每镜必须按 trim_head_ms / duration_ms 裁剪再用;直接拼整条裸片会把平台已经 QC 掉的' +
-        '首尾形变帧一起拼进去。\n' +
+        '首尾形变帧一起拼进去。★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(免费):逐镜实测源片时长、平台终拼的入出点/转场占用/定格补帧、人声已混入视频还是独立轨,拿它核对你的时间轴总长。' +

package/openapi.json

@@ -2,8 +2,8 @@
   "openapi": "3.1.0",
   "info": {
     "title": "StarReel Production API",
-    "version": "0.1.212",
-    "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.212 tool surface (operationIds match MCP tool names 1:1)."
+    "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)."
   },
   "servers": [
     {
@@ -7302,7 +7302,7 @@
       "get": {
         "operationId": "export_handoff_pack",
         "summary": "启用交付追溯后会保存不可变导出清单（不改素材）",
-        "description": "启用交付追溯后会保存不可变导出清单（不改素材）。保留 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 掉的首尾形变帧一起拼进去。\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。",
+        "description": "启用交付追溯后会保存不可变导出清单（不改素材）。保留 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。",
         "tags": [
           "episodes"
         ],

package/package.json

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