@autoaiai/aicut 0.1.11 → 0.1.13

package/skills/video-assemble-zenstory-ai/SKILL.md

@@ -1,153 +0,0 @@
----
-name: video-assemble-zenstory-ai
-description: "合成视频解说最终成片：把旁白音频铺到源视频上，按旁白窗口压低原声，生成 SRT / ASS 字幕并可烧录， 最后做响度标准化。作为最终合成阶段使用。输入源视频、tts_meta.json 与旁白位置； 输出 recap 成片和字幕。触发词：视频合成、混音、字幕、压字幕、assemble video、mux、ducking、subtitles、成片。 Runs in AICUT: the film is film.html, a page per shot, drawn by `aicut look` and `aicut render`."
-license: MIT
-source: "zenstory-ai/video-recap-skills"
----
-
-# video-assemble
-
-## Running it in AICUT
-
-AICUT's film is `film.html`: it cuts pages, footage, pictures and sound together on tracks. A page is a web page that
-sets `window.film = { frame(t) }` and draws that moment — no framework, no build step, no composition object, no
-`registerRoot`. Five shots are five pages cut together, not one page that changes scene, so each shot stays trimmable
-and replaceable in Studio.
-
-```sh
-npx -y @autoaiai/aicut@latest          # the manual: the format and the commands, always current
-npx -y @autoaiai/aicut@latest open .   # make this folder a film and print Studio's address
-npx -y @autoaiai/aicut@latest look     # a contact sheet of the whole film, its sound, and a determinism check
-npx -y @autoaiai/aicut@latest look 4.5 # one frame, full size — look at the PNG, not at the code
-npx -y @autoaiai/aicut@latest render   # the MP4, beside film.html
-```
-
-Run the manual before the first film: it is authoritative for the format, and this skill is about the method above it.
-
-Where the words below name another program's part, it becomes this:
-
-| elsewhere | in AICUT |
-|---|---|
-| composition, timeline, project file | `film.html`; tracks and clips inside it |
-| a scene, a sequence, a slide | a page (`pages/<name>.html`) cut onto a track |
-| `useCurrentFrame()`, `interpolate()` | `frame(t)` — the picture depends only on `t`, never on state or `Date.now()` |
-| a still, a screengrab | `aicut look <t>` |
-| `render` / `build` / `export` | `aicut render` (the person can also export from Studio) |
-| a dev server, a preview window | `aicut open` and the Studio address it prints |
-
-Hard rules that hold whatever the method says: the picture depends only on `t`; every value in the person's prompt is
-binding; look at the frames `look` writes before saying a film is done.
-
-
-## 1. 定位
-
-本技能负责最终合成：
-
-1. 把各段旁白音频放到视频时间线上。
-2. 在旁白窗口内用固定包络压低原声（盖住原声对白时与落在安静段时各用一档音量），间隙恢复原声。
-3. 根据旁白位置生成 `subtitles.srt`；默认同时生成并烧录 `subtitles.ass`，`--no-burn-subtitles` 可关闭。不烧录时（关闭或降级），`subtitles.srt` 复制到成片旁，名为 `recap_<stem>.srt`；烧录时删掉旧的同名外挂字幕。
-4. 可选把最终响度标准化到目标 LUFS：两遍 loudnorm，只用一个恒定增益，不做动态压缩；混音的真峰值放不下这么大的增益时，先过 4 倍过采样的真峰值限幅器（最多削 `LOUDNESS_LIMITER_MAX_DB`，默认 6 dB），超出部分才下调目标响度。真峰值目标针对交付的 AAC 文件：AAC 编码会让真峰值比 PCM 混音高 0.3–1.4 dB，所以首次渲染瞄准 TP 下 0.5 dB，渲染后解码成片实测；仍超过 -1 dBTP 时按超出量再降 0.1 dB 只重编码音频（画面流复制），最多两次，仍超出则以 `delivered_true_peak_over_target` 阻断。ffmpeg 实际用的模式、限幅量与成片实测值记在 `assembly_qc.json` 的 `loudness_mode` 与 `loudnorm_final_pass`（`delivered`）。
-5. 成片不带原片的容器元数据（`title`、`comment` 等标签与章节）。
-
-## 2. 声音收尾契约
-
-合成阶段只实现创作决定，不凭空制造决定。Agent 在写旁白位置前，已在 `visual_audio_board.json` 为每个 beat 指定 `audio_owner`：
-
-- `original_dialogue`
-- `action_sound`
-- `ambience` / `music`
-- `silence`
-- `narration`
-
-旁白间隙按已选声音分工保留。只在确有任务时加入 BGM，并保住必须听见的台词与有意义的沉默。
-
-当前渲染器不解析 `visual_audio_board.json`；Agent 通过旁白时间、`overlaps_speech`、原声留白与现有混音参数落实这些决定。
-
-## 3. 输入契约
-
-- `<video>`：源视频；cut 模式下为 `edited_source.mp4`。
-- `work_dir/tts_meta.json`：默认 `narration` 模式必需；配音阶段写出的 `{segments: [...]}`。每段包含 `audio_path`、时间、`pause_after_ms`、`overlaps_speech` 和用于混音/字幕的位置。显式 `source-mix` / `adopted-packet-copy` 模式不读取它。
-- 已采用的配音使用显式 `--tts-meta` 和 `--narration-adoption`：后者由调用方独立确认文字、请求的引擎/声线和速度策略，不能从待消费元数据自动“批准”出来。完整格式与记录边界见 `references/narration-adoption.md`。
-- 已采用的完整声音底轨与逐段配音可再传 `--audio-mix-adoption`；严格格式、48 kHz 声道矩阵和双 binding 事务见 `references/explicit-audio-mix.md`。
-
-下面的 `scripts/...` 均相对于本技能目录。若执行器从仓库根目录启动，请给脚本路径加上本技能的绝对目录。
-
-## 4. 运行命令
-
-```bash
-python3 scripts/assemble.py <video> --work-dir <work_dir> \
-  [--audio-mode narration|source-mix|adopted-packet-copy] [--audio-stream-index <N>] \
-  [--tts-meta <tts_meta.json> --narration-adoption <narration_adoption.json>] \
-  [--audio-mix-adoption <audio_mix_adoption.json>] \
-  [--recap-stem <name>] [--output-dir <dir>] [--no-burn-subtitles] \
-  [--subtitle-y-top <inclusive-y> --subtitle-y-bot <exclusive-y>] \
-  [--source-video <orig.mp4>] [--export-jianying [--jianying-out <dir>]]
-```
-
-## 5. 输出契约
-
-- `recap_<stem>.mp4`：稳定的最终输出别名；每次运行覆盖更新。
-- `work_dir/output.mp4`：工作目录内成片。
-- `subtitles.srt`：旁白字幕；烧录时另有 `subtitles.ass`。
-- `timeline.json`：后端无关的多轨模型，包含视频、原声、旁白、BGM、字幕和 ducking 自动化。
-- `_placed_*.wav`：实际写入主混音的完整逐段旁白 PCM；时间线与剪映只引用这些文件。
-- `narration_input_binding.json`：旁白输入、转换、实际放置、旁白总轨和最终音轨的消费记录（路径、PCM 参数、packet 计数）。区分未采用与已绑定采用决定两种状态；不等于声线鉴定或听审。
-- `audio_mix_binding.json`：显式完整声音分支消费的画面时钟、底轨、48 kHz 配音放置、premaster、固定 master gain、最终 PCM/AAC 事实与 narration binding 路径的记录。
-- `assembly_manifest.json`：输入来源、cut 来源标识（路径、大小、mtime）、渲染设置与最终输出路径。
-- `assembly_qc.json`：旁白完整性、原声句末交接、时间线素材时长与交付质量的发布门禁。
-- 剪映草稿目录：仅 `--export-jianying` 时生成，包含 `draft_content.json`、`draft_info.json` 与 `draft_meta_info.json`。
-
-## 6. 合成规则
-
-- 音频模式的处理与冻结语义见 `references/audio-modes.md`。默认仍为 `narration`；另外两种模式必须显式选择。
-- `--audio-mix-adoption` 只与显式 `--tts-meta`、`--narration-adoption` 同时使用；它保留 `narration` 模式名，但跳过旧速度/适配、原声 handoff、环境 BGM、duck、loudnorm 和 limiter。
-- 音频按轨道混合：原声、可选 BGM 与旁白各自独立。
-- 段落首块（与上一块作者留白超过 1.6 秒）从写的 `start` 放置，但不早于上一块实际结尾加它的 `pause_after_ms`，上一块超时会把它往后推；段落内后续块紧接上一块的实际结尾（间隔 0.35 秒），最多比写的 `start` 提前 1.2 秒。这一提前发生在旁白校验之后，所以提前的那一段不能进入原声对白：有对白时最多提前到最后一段对白结束处。真的提前了的块在 `source_entry_status` 记 `paragraph_tightened`，并在 `written_start` 记写的 `start`。
-- 旁白不做任何容差裁尾；温和加速后仍放不下即 `no_safe_fit`。每段 `_placed_*.wav`
-  必须与序列化后的时间线区间等长或更短，否则 `timeline_audio_mismatch` 阻断。
-- 已采用配音按其 `tempo_policy` 执行：保守默认是原速且禁止段内适速，也可显式采用符合范围要求的其他速度策略；环境默认 1.15 倍速不能覆盖采用决定。显式完整声音混音分支固定原速，不做自动适配。放不下就修订安排，不裁尾。严格运行使用新工作目录与新输出路径；输入/实际混音来源变动或 QC 失败时，不发布候选成片。没有采用文件时仍可按默认旁白路径合成，但消费记录为 `UNADOPTED`。
-- 原声在旁白结束后最多再压低 3 秒，等这段时间内的下一个句末锚点：压到它的 `pause_start`，只在实测停顿内渐强，
-  于 `source_restore_at` 回满（锚点为 `unverified` 时状态记 `sentence_boundary_unverified`）。3 秒内没有锚点时，
-  离时间线末端不足 3 秒就压到末端（`held_to_timeline_end`），否则在旁白结束处直接回满（`bounded_release`），
-  不为远处的锚点长时间压住原声对白。`assembly_qc.json` 的 `summary.max_source_duck_hold_seconds` 记录最长的压低延续。
-- `--export-jianying` / `EXPORT_JIANYING=1` 可把 `timeline.json` 导出为可编辑草稿。cut 模式应传 `--source-video <orig>`，让草稿引用真实原片区间。
-- 剪映导出默认把视频、音频与图片复制到 `Resources/local/{video,audio,image}`，保持草稿可搬迁；`--jianying-no-bundle-media` 只适合原路径始终可访问的情况。
-- 重叠覆盖物会拆到编号轨道；非空目标目录不会覆盖，而会创建编号兄弟目录。
-- 导出只接受 `schema_version: 2` 的 `timeline.json`，只映射视频、音频、字幕和图片叠层（`scale` / `position`）；变速、转场、蒙版、富文本、特效轨等手写扩展字段会被明确拒绝。
-- 剪映草稿引用未烧录的源视频，因此原片硬字幕仍会保留，必要时在剪映内另行遮罩。
-- 字幕外观可用 `SUBTITLE_FONT_SIZE`、`SUBTITLE_MARGIN_V`、`SUBTITLE_MAX_CHARS` 等控制。
-- `SUBTITLE_Y_TOP/BOT` 把 ASS 基线放到测得的原片字幕区域，坐标为显示画布上的半开 `[top, bot)`，只接受方形或近方形像素（SAR 与 1:1 相差不超过 2%，未标注的 `0:1` 按方形）；比例遮罩默认 `SUBTITLE_MASK_OPACITY=0.6`；显式指定实测字幕带时默认不透明，除非另设该变量。`SOURCE_SUBTITLE_MASK_TIMING` 默认是 `narration`。
-- 原声在旁白间隙回到 `IDLE_ORIG_VOLUME`，旁白下压到 `SPEECH_DUCKING_VOLUME`；`DUCK_FADE_SECONDS` 控制过渡。还可配置 `DUCK_BRIDGE_SECONDS`、`ZONE_DUCKING_VOLUME`、`FINAL_LOUDNORM`、`TARGET_LUFS` 与 `LOUDNESS_LIMITER_MAX_DB`。
-- 可通过 `BGM_PATH` 指定 BGM；它会循环到成片长度，并按 `BGM_VOLUME` / `BGM_DUCKING_VOLUME` 混音。不要在没有创作依据时设置通用 BGM。
-- 烧录字幕需要带 `subtitles` / libass 的 ffmpeg，合成阶段在渲染前预检。显式要求烧录（`--burn-subtitles` 或环境变量 `BURN_SUBTITLES`）时缺 libass 直接失败；只是默认开启时降级：不烧录，交付外挂 `.srt`（留白里的 `「」` 原声对白仅在有 `user_subtitles.*` 时照常写进去；原本由遮罩触发的对白随遮罩一起关闭，原片硬字幕可见），`visual_qc.json` 的 `warnings` 与 `assembly_manifest.json` 的 `warnings` 记一条 `subtitle_burn_degraded`，`subtitles.burn_degraded_reason` 写原因。降级后遮罩照旧关闭（`mask.trigger` 为 `burn_subtitles_degraded`）。
-- `visual_overlays.json` 的文字叠加用 ffmpeg `drawtext`（libfreetype）。缺 drawtext 时合成在渲染前失败；叠加是写稿时明确加的内容，不会被静默丢掉。
-- 成片画面一律是 H.264 8-bit 4:2:0 并带 `+faststart`：不需要滤镜、且源画面已是 H.264 8-bit 4:2:0（`yuv420p`，或全范围的 `yuvj420p`）、宽高为偶数时才流复制，原样交付；否则重编码为 `yuv420p`。色彩标记：源未标记或已是 BT.709 时标为 BT.709（`-colorspace/-color_primaries/-color_trc bt709`），其它已声明的色彩空间原样保留；全范围（`pc`）源保留 `pc`，其余标 `tv`。YUV 源只改标记，不转换像素；RGB 源（ffprobe 报 `gbr`，如 PNG/QuickTime RLE 封装的 MOV）没有 YUV 矩阵可保留，按 BT.709 limited 转换。结果记在 `assembly_qc.json` 的 `delivery_qc.color_tags`（RGB 源多一个 `from_rgb: true`）。
-- 原声留白中的对白字幕优先读取 Agent 校对的 `original_subtitles.json`；否则保守映射 ASR。只有遮罩覆盖留白或用户字幕明确要求替换时才烧录原声对白，并用 `「」` 与旁白区分。
-
-### 按原片区间准备声音底轨
-
-已有多段原声取舍和独立 BGM 决定时，先用 `references/source-score.md` 的独立
-`source_score.py` 从原片声音流按精确帧区间重建原声轨、音乐轨及两者之和；它只输出
-声音底轨和来源回执。要与逐段已采用配音合成，再由调用方提供 `references/explicit-audio-mix.md`
-的严格 adoption；不要将底轨塞入旧入口自动 duck，也不要从含旧解说的成片取整条声音冒充干净原声。
-
-## 7. 字幕与可选包装
-
-先锁定画面、剪点、旁白和混音，再投入字幕动画或边框包装；字幕样式不能掩盖叙事、剪点或声音问题。
-普通交付优先使用现有 ASS 路径；整片不动的包框、标题条和角标用 `packaging_layers.json` 静态叠加；
-只有用户需要逐 cue 排版、动画或透明图层时，才用项目级代码渲染器，由该项目自己把透明层合成到锁定母版。
-包装顺序与样帧抽检清单见 `references/packaging.md`。
-
-## 8. 能力边界
-
-- 不生成旁白文字，不合成 TTS，不重新转写视频。
-- 字幕烧录默认开启；关闭时不会重编码绘制字幕区域。
-
-显式输出轴字幕轨的独立合同、完整替换语义和当前边界见 `references/subtitle-track.md`。
-
-## Source
-
-Rewritten for AICUT from [`zenstory-ai/video-recap-skills`](https://github.com/zenstory-ai/video-recap-skills)
-(MIT), skills/video-assemble/SKILL.md. The method is that skill's own; the way it runs is AICUT's.
-
-The repository holds 7 skills; this is the one its entry stands for.

package/skills/video-assemble-zenstory-ai/references/audio-modes.md

@@ -1,63 +0,0 @@
-# Assembly audio modes
-
-`assemble.py` keeps `narration` as its API and CLI default. Non-narration
-behavior is opt-in with `--audio-mode`; `--audio-stream-index N` is the
-zero-based audio ordinal used by FFmpeg's `0:a:N` selector.
-
-## `narration`
-
-- Requires non-empty `tts_meta.json` segments.
-- Builds/places narration WAV, performs source ducking and optional BGM mix,
-  then applies the configured final loudness/limiter stage and AAC encoding.
-- Missing source audio may use the existing synthetic-silence fallback.
-- With the additional strict `--audio-mix-adoption`, narration instead consumes an
-  adopted prepared bed plus complete direct-to-48-kHz narration placements. This is
-  still narration mode, but it bypasses ambient BGM, ducking, speed/fit, loudnorm, and
-  limiter operations. See `explicit-audio-mix.md`.
-
-## `source-mix`
-
-- Does not read or require `tts_meta.json` and never creates narration audio.
-- Uses the selected input audio stream, applies `IDLE_ORIG_VOLUME`, mixes a
-  declared `BGM_PATH` when present, and runs the configured final
-  loudness/limiter stage before AAC encoding.
-- A declared but missing `BGM_PATH` is an error in source-mix mode. Narration
-  mode warns and skips the missing music.
-- This is a processed mix, not frozen audio. `assembly_qc.json` reports the
-  operations that actually ran.
-
-## `adopted-packet-copy`
-
-- First implementation supports a selected AAC stream from `<video>` only.
-- Rejects TTS segments, explicit `--tts-meta`, any configured `BGM_PATH`, a
-  missing/wrong stream, unsupported codec, or audio/picture interval mismatch.
-- Maps that stream with `-c:a copy`. It does not build narration, mix, duck,
-  normalize, limit, resample, change tempo, or add silence.
-- It deliberately omits `-t` and `-shortest`, preserving AAC priming and tail
-  packets. After rendering, the output is probed and compared with the input:
-  decoder parameters, packet count, total payload bytes, the packet-clock span,
-  and every packet's size and PTS/DTS/duration converted to rational time must
-  match. Packet side data also must match, including AAC skip-sample/
-  discard-padding values and their reason fields.
-- QC/manifest evidence records selected stream, absolute stream index, codec,
-  time base, sample rate, channels/layout, packet count, payload bytes, packet
-  details, and actual operation flags.
-
-The adopted-copy settings payload excludes narration/mix/loudness defaults, so
-irrelevant ambient settings do not invalidate a frozen-audio render. Video
-filters and video re-encoding remain allowed; packet verification must still
-pass afterward.
-
-These modes do not create a commercial quality profile, automatic speech
-alignment, listening approval, or release approval. An explicit subtitle track
-is only a version/media-bound timing declaration; its evidence labels and
-`NOT_CHECKED` acoustic/listening status remain authoritative.
-Matching packets and decoder parameters show the encoded audio was copied; they
-do not prove perceptual quality or that a person listened to the result.
-
-`timeline.json` represents either non-narration mode as one complete clip from
-the current input video and records the selected stream. Adopted copy uses gain
-1 with no automation. Source-mix records processed/non-frozen delivery and is
-not claimed to be reconstructable by an editor. The optional JianYing exporter
-currently supports only selected stream 0; requesting export with another
-stream fails instead of silently substituting the default stream.

package/skills/video-assemble-zenstory-ai/references/explicit-audio-mix.md

@@ -1,77 +0,0 @@
-# Explicit adopted full-sound mix
-
-Use this path only when the picture, a completed `prepared_bed_receipt`, an exact
-narration adoption, narration placements/gains, and one fixed master gain have already
-been independently selected. It is still `audio_mode=narration`, but it bypasses the
-legacy narration timing, ducking, ambient BGM, loudness-normalization, and limiter path.
-
-```bash
-python3 scripts/assemble.py picture.mp4 --work-dir NEW_WORK \
-  --tts-meta /local/tts_meta.json \
-  --narration-adoption /local/narration_adoption.json \
-  --audio-mix-adoption /local/audio_mix_adoption.json
-```
-
-All strict output paths, including the CLI delivery alias, must be new. The CLI copies
-to a hidden delivery stage and creates the alias with an exclusive atomic link, so a
-concurrent or existing file is never overwritten.
-
-## Adoption schema v1
-
-```json
-{
-  "artifact": "audio_mix_adoption",
-  "schema_version": 1,
-  "prepared_receipt": {"path": "/local/prepared_bed_receipt.json"},
-  "format": {"sample_rate": 48000, "channels": 2, "total_samples": 1856000},
-  "segments": [
-    {"index": 0, "output_start_sample": 366000, "gain": 0.4251421093940735}
-  ],
-  "master_gain_db": 0.75
-}
-```
-
-Unknown or missing fields fail; legacy `*_sha256` keys are ignored. The format must
-equal the actual zero-origin picture frame clock at 48 kHz and the prepared receipt.
-The receipt, all three float PCM beds (format, sample count, finite PCM), the picture,
-the narration adoption file and the ordered segment indices are checked before
-narration snapshots are written.
-
-## Exact audio operations
-
-Each narration snapshot is decoded directly and completely to `pcm_f32le`, 48 kHz
-stereo. Version 1 uses one fixed channel matrix, recorded per segment as
-`mono_equal_power` or `stereo_identity`:
-
-- mono is panned to left and right at `1/sqrt(2)` per channel;
-- stereo preserves independent left and right channels at unit gain;
-- inputs with more than two channels are rejected.
-
-There is no intermediate 44.1 kHz mono placement, speed change, fade, trim, tail pad,
-normalization, or automatic fit. Every complete converted WAV must fit its adopted
-integer `output_start_sample`; placements may not overlap. Adopted per-segment gains
-form a float `voice_bus.wav`. The producer's `prepared_bed.wav` and voice bus form a
-float premaster, then the sole adopted `master_gain_db` forms the float master consumed
-by the final AAC encode. The picture's old audio is never a mixer input.
-
-## Records and publication
-
-`narration_input_binding.json` records the actual direct 48 kHz placed files and voice
-bus, marking the bus `CONSUMED_BY_EXPLICIT_MIX`. `audio_mix_binding.json` records the
-mix adoption path, picture path and clock, prepared receipt path and stems, converted
-placements (path, channel matrix, PCM facts), voice bus, premaster, master, the
-narration binding path, the final decoded PCM facts, the final AAC decoder/packet
-count/payload bytes, and the actual output picture decoder/frame clock. The output
-picture must preserve fps, frame count, zero start, and duration. A video-copy path
-reports `packet_identity: EXACT` when decoder parameters and packet sizes/timestamps
-are unchanged; an allowed visual re-encode reports `REENCODED_CLOCK_MATCH`. The colour
-labels (`color_range` / `color_space` / `color_transfer` / `color_primaries`) are left out of
-that comparison, because the final render deliberately labels an untagged picture BT.709. Timeline,
-settings, QC, and manifest identify the explicit path rather than reporting ambient
-ducking/BGM/loudnorm operations.
-
-The candidate render is written to a hidden file. Both bindings are written, QC must
-pass, the media is published, and a second QC runs against the published path. Any
-render, binding, or QC failure removes the candidate, final-named media and the
-bindings written by this run instead of overwriting an older success.
-Diagnostic/staging audio may remain in the unique work directory.

package/skills/video-assemble-zenstory-ai/references/jianying/SOURCE.md

@@ -1,14 +0,0 @@
-# JianYing protocol templates
-
-These JSON protocol templates are pinned to
-[`duoec/duo-video`](https://github.com/duoec/duo-video) commit
-`ef4eb46c823910553f901649f2f13fd7575e748f`, under its MIT license. They are
-data/schema baselines, not executable upstream code. Runtime builders deep-copy
-the templates and replace authored values such as IDs, paths, timings, and canvas
-dimensions. The directory contains only templates used by the exporter.
-
-The required copyright and permission notice is preserved in
-`LICENSE.duo-video` in this directory.
-
-The exporter never uses duo-video's embedded example credentials and never
-emits resource-ID materials (stickers, effects, transitions, text templates).

package/skills/video-assemble-zenstory-ai/references/narration-adoption.md

@@ -1,103 +0,0 @@
-# Narration adoption and the consumed-input record
-
-Narration assembly accepts legacy `tts_meta.json`, but a current file by itself is
-not an adoption decision. Use an explicit adoption document when the selected spoken
-text, requested provider/voice, and tempo policy must be bound to the actual final mix.
-
-```bash
-python3 scripts/assemble.py input.mp4 --work-dir work \
-  --tts-meta /local/tts_meta.json \
-  --narration-adoption /local/narration_adoption.json
-```
-
-`--narration-adoption` is narration-only and requires an explicitly supplied
-`--tts-meta`; it never adopts an ambient work-directory file automatically.
-
-## Strict v1 schema
-
-```json
-{
-  "artifact": "narration_adoption",
-  "schema_version": 1,
-  "segments": [
-    {
-      "index": 0,
-      "spoken_text": "exact selected words",
-      "requested_provider": "caller-selected-provider",
-      "requested_voice": "caller-selected-voice"
-    }
-  ],
-  "tempo_policy": {
-    "global_atempo": 1.0,
-    "bounded_segment_fit": false,
-    "segment_tempo_max": 1.0,
-    "cumulative_tempo_max": 1.0,
-    "cumulative_tempo_hard_max": 1.0
-  }
-}
-```
-
-That policy is the conservative default. An adoption may declare its own values and
-they are honoured: `global_atempo` must be positive and no greater than
-`cumulative_tempo_hard_max`, `segment_tempo_max` and `cumulative_tempo_max` must be at
-least `1.0`, `cumulative_tempo_hard_max` must not be below `cumulative_tempo_max`, and
-`bounded_segment_fit` must be a boolean. Malformed or out-of-bounds policies fail;
-ambient defaults such as a global 1.15 speed never override an adoption. With
-`bounded_segment_fit` false, an adopted segment that does not fit its authored window
-blocks without time trimming or bounded fit.
-
-The adoption's ordered segment indices and spoken text must match both the segment
-list in the supplied `tts_meta.json` and the in-memory list passed to
-`assemble_video`; those two lists must be equal to each other. Unknown fields fail;
-legacy `tts_meta_sha256` / `processed_wav_sha256` keys are ignored. The consumer never
-creates an adoption from metadata that it is about to consume.
-
-## Validation and snapshots
-
-Every adopted `audio_path` must exist before any media is probed or rendered. The
-adopted inputs are then copied to per-run snapshots under
-`work/.narration_input_snapshots/`; the original files are never modified, and the
-render reads only the snapshots. Every conversion, placed WAV, and the completed
-narration bus is recorded with its path and probed PCM facts before the final FFmpeg
-command runs.
-
-On the legacy narration-mix path, Python's standard WAV reader cannot open every valid post-processed WAV encoding.
-Noncanonical input, including `pcm_f32le`, 48 kHz, or stereo WAV, is explicitly
-decoded by the existing FFmpeg executable to 44.1 kHz mono PCM16 before placement.
-The conversion path and actual PCM facts are recorded; the consumer does not claim
-that converted samples equal the original samples.
-
-The explicit full-sound path described in `explicit-audio-mix.md` deliberately does
-not use that 44.1 kHz mono conversion. It consumes the snapshots directly as complete
-48 kHz float placements, preserving native stereo channels.
-
-An adopted render writes to a hidden candidate path. The binding is written, QC runs
-against the candidate, the candidate is renamed to the final path, and QC runs once
-more against the published file. A blocking QC removes the candidate and the binding
-instead of publishing; the run records the final output as absent rather than
-claiming a missing file was published. Non-final work or diagnostic artifacts may
-remain for investigation.
-
-## Binding report
-
-After successful assembly, `work/narration_input_binding.json` records:
-
-- original input path and snapshot path;
-- any explicit conversion path and PCM parameters;
-- each complete placed WAV path and PCM parameters;
-- `narration.wav` path and PCM parameters;
-- the final output path and its encoded audio-stream facts (decoder parameters,
-  packet count, payload bytes, start time, duration);
-- the adoption path, its `tts_meta` path, and the exact tempo policy when supplied.
-
-The report uses one of two identity statuses:
-
-- `UNADOPTED`: no adoption was supplied; the legacy inputs were consumed as given;
-- `BOUND_TO_ADOPTION`: the adoption's selection and tempo policy were carried
-  through the final mix.
-
-`BOUND_TO_ADOPTION` records what was consumed, not provider truth, acoustic speaker
-identity, direct listening, naturalness, or release approval; voice authentication
-and direct listening stay `NOT_CHECKED`. QC, manifest, and settings records reference
-a binding only while its recorded final output path still exists; source-mix and
-adopted-packet-copy modes do not reuse narration binding evidence.

package/skills/video-assemble-zenstory-ai/references/packaging.md

@@ -1,44 +0,0 @@
-# 字幕与包装的推荐顺序
-
-先锁定画面、剪点、旁白和混音，再投入字幕动画或边框包装。字幕样式不能掩盖叙事、剪点或声音问题。
-
-普通交付优先使用现有 ASS 路径。只有用户需要更精细的逐 cue 排版、动画或透明图层时，才使用 Remotion
-或其他代码渲染器作为**项目级可选实现**，不要把特定框架、字体、颜色或黄字写成核心依赖。
-
-## 推荐顺序
-
-1. 输出无包装的锁定母版，确认音画内容不再变化。
-2. 从实际 TTS / 时间线生成 captions；TTS 块保持连续思路，字幕可以按阅读宽度拆 cue。
-3. 先抽检开头、亮背景、暗背景、人物近景和长字幕样帧，确定字号、安全区、描边、阴影及是否需要底板。
-4. 渲染完整透明字幕层，再 overlay 到锁定母版；合成后确认音轨未被意外改写。
-5. 完整播放实际最终文件，并复查字幕遮脸、跳字、断行、首尾帧和边界处残影。
-
-已有项目级渲染器时，由该项目把透明层合成到锁定母版，以保留已确认的包装样式；本技能不提供逐帧前景合成命令。合成时音轨按流复制，合成后核对帧率、时长与音轨未被改写，
-再写入新文件。片名卡有渐显或动画时须渲染完整序列，不能冻结最后一张图代替。
-
-## 静态包装图层 `packaging_layers.json`
-
-包框、标题条、角标 logo 这类整片不动的图片，可以直接在合成时叠加，不必先渲染成逐帧序列。
-在 `work_dir` 写 `packaging_layers.json`：
-
-```json
-{
-  "canvas": {"width": 1080, "height": 1920},
-  "layers": [
-    {"name": "frame", "path": "/abs/frame.png", "rect": {"x": 0, "y": 0, "width": 1080, "height": 1920}}
-  ],
-  "template": {"id": "brand-frame", "version": 2}
-}
-```
-
-- `canvas` 必须等于成片画布，否则合成前报错；`rect` 必须在画布内，图片缩放到 `rect` 大小（透明区域保持透明）。
-- 叠加顺序：遮原字幕 → 包装图层（按数组顺序）→ 画面文字 → 解说字幕 → 缩放。
-- `timeline.json` 同时得到对应的 image 轨，剪映草稿里的包框可单独编辑。
-- `assembly_manifest.json` 的 `video_filters.packaging_layers` 记录每张图片的路径与 `{size, mtime_ns}`。
-- 编排器按项目绑定的 `packaging` 模板写出这个文件时会带 `written_by` 标记；
-  手写的文件不会被它删除。有渐显或动画的包装仍由项目级渲染器自行合成。
-
-## 原则
-
-包装价值来自稳定、可读、与内容一致的排版，不来自效果数量。先建立统一字体、颜色、描边/阴影和轻量动效；
-底板、边框、花字与音效只有解决具体可读性或叙事任务时才加入。一个样帧好看不代表全片成立。

package/skills/video-assemble-zenstory-ai/references/source-score.md

@@ -1,146 +0,0 @@
-# Source and score bed producer
-
-`source_score.py` is a standalone producer for explicitly authored source-audio
-intervals and one continuous score playhead. It does not mix narration, inspect old
-masters, infer dialogue, choose music, retime sound, normalize loudness, limit peaks,
-or publish a final video.
-
-```bash
-python3 scripts/source_score.py source_score_plan.json --output-dir a-new-directory
-```
-
-The output directory must not exist. Success creates:
-
-- `source_bed.wav` — reordered/pre-gained source intervals plus explicit silence;
-- `score_bed.wav` — one continuous raw-score window or an adopted frozen stem;
-- `prepared_bed.wav` — source plus score, without master gain/limiting;
-- `prepared_bed_receipt.json` — input paths, clocks, sample ranges, PCM facts and QC facts.
-
-All three beds are `pcm_f32le`, 48 kHz, stereo. Float output avoids repeated integer
-quantization and preserves values outside `[-1,1]`; the receipt records actual peak,
-finite-sample status, and `FLOAT_PRESERVED_NO_MASTER`. A later explicitly adopted
-consumer owns final master gain and delivery encoding.
-
-## Strict plan schema v1
-
-```json
-{
-  "artifact": "source_score_plan",
-  "schema_version": 1,
-  "output": {"sample_rate": 48000, "channels": 2, "total_samples": 1920000},
-  "source_segments": [
-    {
-      "id": "protected-dialogue-1",
-      "path": "/local/source.mov",
-      "audio_stream": 0,
-      "source_fps": "24/1",
-      "source_start_frame": 120,
-      "source_end_frame": 180,
-      "output_start_sample": 240000,
-      "gain": 1.0,
-      "fade_in_samples": 0,
-      "fade_out_samples": 96,
-      "fade_shape": "linear",
-      "role": "protected_original"
-    }
-  ],
-  "source_silence": [
-    {"output_start_sample": 0, "output_end_sample": 240000, "role": "silence"},
-    {"output_start_sample": 360000, "output_end_sample": 1920000, "role": "silence"}
-  ],
-  "score": {
-    "kind": "raw",
-    "path": "/local/score.wav",
-    "audio_stream": 0,
-    "source_offset_sample": 384000,
-    "gain": 0.18,
-    "fade_in_samples": 33600,
-    "fade_out_samples": 120000,
-    "fade_shape": "half_cosine"
-  }
-}
-```
-
-Every source range is half-open in CFR picture frames. Version 1 accepts H.264 and
-HEVC picture sources whose complete packet PTS/duration grid proves one zero-origin
-packet per same-speed frame. Frame boundaries are projected onto the 48 kHz clock by
-rounding the exact position half-up once, so `48000/fps` need not be an integer and a
-broadcast rate such as 30000/1001 is accepted; every derived bound comes from those
-rounded positions. Other codecs, incomplete packet timing, VFR, retime fields,
-nominal time seeks, and unknown fields are rejected rather than called verified
-(legacy `sha256` keys are ignored).
-Each unique selected source stream is decoded from its actual PTS clock to canonical
-48 kHz stereo exactly once. All authored intervals are then cut from that canonical
-sample array—never independently decoded or `-ss`-seeked per edit.
-
-The source segment length is the difference between the rounded start and end
-sample positions described above. Its output end is derived from that integer
-length, not declared or rounded from the duration again. Source segments and explicit silence ranges
-must form an exact, nonoverlapping partition of `[0,total_samples)`. There are no
-implicit gaps. Supported roles are `protected_original` and
-`mixed_original_under_narration`; their gains and labels are retained unchanged.
-
-Source fades are explicitly `linear`. A fade of `N>=2` samples uses inclusive
-endpoints: fade-in gain is `i/(N-1)`, and fade-out gain is `(N-1-i)/(N-1)`. Thus the
-first/last samples are exactly zero and the opposite endpoints exactly one. Zero
-means no fade; a one-sample fade is rejected as ambiguous. Fade windows may not
-overlap within a segment.
-
-## Score modes
-
-`raw` decodes the selected score stream once, advances one playhead from
-`source_offset_sample`, and takes exactly `total_samples`. The input must be long
-enough; there is no implicit loop. Gain and one pair of whole-score fades are applied
-once, so score playback never resets at picture/source cuts. `linear` and
-`half_cosine` fades use inclusive endpoints.
-
-When the adopted source bed is already the complete soundtrack and no additional
-music is selected, use the exact no-score form:
-
-```json
-{"kind":"none"}
-```
-
-It accepts no other fields. `score_bed.wav` is real all-zero float PCM at the exact
-output length, while `prepared_bed.wav` is an exact canonical PCM copy of
-`source_bed.wav`; the receipt records `kind:none` rather than inventing a music asset.
-
-An adopted score that already contains its chosen offset/gain/fades uses the exact
-alternative schema:
-
-```json
-{"kind":"frozen","path":"/local/frozen.wav","audio_stream":0}
-```
-
-Frozen input must be PCM16, PCM24, or PCM float, 48 kHz stereo, and exactly
-`total_samples`. PCM16/24 values convert exactly to float canonical representation.
-No offset, gain, fade, loop, normalization or other processing fields are accepted.
-The receipt records the frozen file path and its probed PCM facts.
-
-## Receipt and failure boundary
-
-`prepared_bed_receipt` schema version 1 records the plan path, each input path,
-selected stream, actual CFR/audio clocks, canonical decoded PCM facts, resolved
-input/output sample ranges, gains, fades, roles, and each output's path, byte size,
-format, sample count, finite status and peak.
-
-Every declared input must exist and probe as declared before work starts. A selected
-source range must fit the actual canonical decoded samples; silence padding can never
-conceal a short source. WAVs remain hidden staging artifacts until every output
-validates. FFmpeg failure, invalid ranges, non-finite PCM, or an existing target
-directory cannot publish final-named beds or a receipt.
-Diagnostic command/log/intermediate files may remain in the unique failed directory.
-
-To consume a completed receipt with explicitly adopted narration, use the strict
-`--audio-mix-adoption` path in `explicit-audio-mix.md`. This path does not render a final video from a prepared bed alone. Do not feed `prepared_bed.wav` through legacy source ducking or
-ambient BGM/loudness settings.
-
-## 与旧入口的关系（中文摘要）
-
-原片完整解码一次再切样本，分别执行保留对白、低位原声和明确静音；渐变必须显式给定。
-已处理的音乐轨走 `frozen`，不能再次偏移、调增益或加渐变。若采用的原声底轨本身已包含
-完整音乐决定且不再叠加配乐，使用严格的 `score:{"kind":"none"}`；它生成真实全零 score，
-并保持 prepared 与 source 逐字节相同，不伪造静音音乐资产。
-
-这一步输出声音底轨和来源回执，后续合成负责最终视频。调用方须区分
-“底轨已验证”“配音已验证”和“完整混音已验证”三种状态，不能相互冒充。