@oh-story/dsh 0.1.9 → 0.1.11

package/lib/video-recap/skills/video-assemble/SKILL.md

@@ -33,14 +33,19 @@ description: >
 ## 3. 输入契约
 
 - `<video>`：源视频；cut 模式下为 `edited_source.mp4`。
-- `work_dir/tts_meta.json`：配音阶段写出的 `{segments: [...]}`。每段包含 `audio_path`、时间、`pause_after_ms`、`overlaps_speech` 和用于混音/字幕的位置。
+- `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/...` 均相对于本技能目录。若执行器从仓库根目录启动，请给脚本路径加上本技能的绝对目录。脚本不从其他技能目录读取文件；外部输入仅限命令显式传入的视频、参数与 `work_dir` 产物。
+下面的 `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>]]
@@ -53,15 +58,20 @@ python3 scripts/assemble.py <video> --work-dir <work_dir> \
 - `subtitles.srt`：旁白字幕；烧录时另有 `subtitles.ass`。
 - `timeline.json`：后端无关的多轨模型，包含视频、原声、旁白、BGM、字幕和 ducking 自动化。
 - `_placed_*.wav`：实际写入主混音的完整逐段旁白 PCM；时间线与剪映只引用这些文件。
-- `assembly_manifest.json`：输入来源、cut 来源指纹、渲染设置与最终输出路径。
+- `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 与旁白各自独立。
 - 旁白不做任何容差裁尾；温和加速后仍放不下即 `no_safe_fit`。每段 `_placed_*.wav`
   必须与序列化后的时间线区间等长或更短，否则 `timeline_audio_mismatch` 阻断。
+- 已采用配音的 v1 合同只支持原速、禁止段内适速；不能让环境默认 1.15 倍速或旧缓存覆盖它。放不下就修订安排，不裁尾。严格运行使用新工作目录与新输出路径；输入/实际混音来源变动或 QC 失败时，不发布候选成片。没有采用文件的旧入口仍是兼容模式，不自动获得同等证据。
 - 原声在旁白结束后保持压低到下一可靠句末的 `pause_start`，只在实测停顿内渐强，
   于 `source_restore_at` 回满；无后续锚点时保持压低到时间线末端，而不是放出半句。
 - `--export-jianying` / `EXPORT_JIANYING=1` 可把 `timeline.json` 导出为可编辑草稿。cut 模式应传 `--source-video <orig>`，让草稿引用真实原片区间。
@@ -76,22 +86,27 @@ python3 scripts/assemble.py <video> --work-dir <work_dir> \
 - 烧录字幕需要带 `subtitles` / libass 的 ffmpeg；合成阶段会预检并在缺失时明确失败。
 - 原声留白中的对白字幕优先读取 Agent 校对的 `original_subtitles.json`；否则保守映射 ASR。只有遮罩覆盖留白或用户字幕明确要求替换时才烧录原声对白，并用 `「」` 与旁白区分。
 
-## 7. 字幕与可选包装
-
-先锁定画面、剪点、旁白和混音，再投入字幕动画或边框包装。字幕样式不能掩盖叙事、剪点或声音问题。
+### 按原片区间准备声音，而不是整体压低旧成片
 
-普通交付优先使用现有 ASS 路径。只有用户需要更精细的逐 cue 排版、动画或透明图层时，才使用 Remotion 或其他代码渲染器作为**项目级可选实现**，不要把特定框架、字体、颜色或黄字写成核心依赖。推荐顺序：
+已有多段原声取舍和独立 BGM 决定时，先用 `references/source-score.md` 的独立
+`source_score.py` 从原片声音流按精确帧区间重建原声轨、音乐轨及两者之和；它只输出
+声音底轨和来源回执。要与逐段已采用配音合成，再由调用方提供 `references/explicit-audio-mix.md`
+的严格 adoption；不要将底轨塞入旧入口自动 duck，也不要从含旧解说的成片取整条声音冒充干净原声。
 
-1. 输出无包装的锁定母版，确认音画内容不再变化。
-2. 从实际 TTS / 时间线生成 captions；TTS 块保持连续思路，字幕可以按阅读宽度拆 cue。
-3. 先抽检开头、亮背景、暗背景、人物近景和长字幕样帧，确定字号、安全区、描边、阴影及是否需要底板。
-4. 渲染完整透明字幕层，再 overlay 到锁定母版；合成后确认音轨未被意外改写。
-5. 完整播放实际最终文件，并复查字幕遮脸、跳字、断行、首尾帧和边界处残影。
+## 7. 字幕与可选包装
 
-包装价值来自稳定、可读、与内容一致的排版，不来自效果数量。先建立统一字体、颜色、描边/阴影和轻量动效；底板、边框、花字与音效只有解决具体可读性或叙事任务时才加入。一个样帧好看不代表全片成立。
+先锁定画面、剪点、旁白和混音，再投入字幕动画或边框包装；字幕样式不能掩盖叙事、剪点或声音问题。
+普通交付优先使用现有 ASS 路径；只有用户需要逐 cue 排版、动画或透明图层时，才用项目级代码渲染器，
+并按 `references/foreground-compose.md` 把它生成的 RGBA 序列叠到锁定母版。包装顺序与样帧抽检清单见
+`references/packaging.md`。
 
 ## 8. 能力边界
 
-- 不生成旁白文字，也不合成 TTS。
-- 不重新转写视频，不擅自改变 Agent 的时间决定。
+- 不生成旁白文字，不合成 TTS，不重新转写视频。
 - 字幕烧录默认开启；关闭时不会重编码绘制字幕区域。
+
+显式输出轴字幕轨的独立合同、完整替换语义和当前边界见 `references/subtitle-track.md`。
+
+画面回原片重建后，若需保留另一文件中的已采用完整混音，先按
+`references/pair-media.md` 显式配对独立画面与音轨。配对只复制流，不补字幕或片名卡；
+后续字幕轨必须重新绑定配对后的容器与 `a:0`，不能继续沿用旧版本身份。

package/lib/video-recap/skills/video-assemble/references/audio-modes.md

@@ -0,0 +1,63 @@
+# 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, as before.
+- 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 this new mode (the legacy
+  narration-mode warn-and-skip behavior remains unchanged).
+- 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/lib/video-recap/skills/video-assemble/references/explicit-audio-mix.md

@@ -0,0 +1,75 @@
+# 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`. 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/lib/video-recap/skills/video-assemble/references/foreground-compose.md

@@ -0,0 +1,118 @@
+# Caller-rendered foreground composition
+
+`compose_foreground.py` performs one narrow operation: it overlays a caller-rendered,
+full-canvas RGBA PNG sequence on an already locked H264/CFR/AAC base, optionally
+replaces a declared tail with an explicit endcard asset, and copies `a:0` without
+decoding or rewriting it. The PNG pixels are the source schema. This is not a CSS,
+font, text, subtitle, logo, animation, or plugin renderer.
+
+## Command
+
+```bash
+python3 scripts/compose_foreground.py foreground_plan.json \
+  --output-dir a-new-directory [--plan-only]
+```
+
+The output directory must not exist. A normal run publishes `foreground.mp4` only
+after the staged media's frame clock, canvas/color metadata, AAC decoder/packets/PTS/
+side data, and a full audio/video decode pass verification.
+A failure retains `foreground_run.json` and available logs but removes staged/final
+media. `--plan-only` validates the complete plan and inputs and writes only
+`foreground_run.json`; it does not render media or update any current pointer.
+
+## Strict plan schema v1
+
+```json
+{
+  "artifact": "foreground_compose_plan",
+  "schema_version": 1,
+  "base": {"path": "/local/base.mp4"},
+  "video": {"fps": "30/1", "width": 1280, "height": 720, "total_frames": 300},
+  "foreground": {
+    "directory": "/local/foreground_sequence",
+    "pattern": "frame_%06d.png",
+    "start_frame": 0,
+    "end_frame": 270
+  },
+  "endcard": {
+    "kind": "sequence",
+    "directory": "/local/endcard_sequence",
+    "pattern": "frame_%06d.png",
+    "start_frame": 270,
+    "end_frame": 300
+  },
+  "producer_receipt": {"path": "/local/producer_receipt.json"}
+}
+```
+
+`endcard` is an exact tagged union. The alternative static form is:
+
+```json
+{
+  "kind": "still",
+  "path": "/local/endcard.png",
+  "start_frame": 270,
+  "end_frame": 300
+}
+```
+
+When the foreground itself covers the entire declared frame clock, the only accepted
+no-tail form is exactly:
+
+```json
+{"kind": "none"}
+```
+
+It accepts no additional fields. It is invalid when the foreground reserves any tail;
+there is no implicit filler, repeated last frame, or generated endcard.
+
+Use `still` only when a genuinely static full-canvas endcard is intended. A static
+PNG does not reconstruct a delivered fade or other animated endcard; supply the
+caller-rendered `sequence` form for that case.
+
+Both sequences use **local zero-based filenames** regardless of their output range.
+Thus the endcard example contains `frame_000000.png` through `frame_000029.png`,
+mapped to output frames `[270,300)`. The foreground must start at output frame zero.
+Its end must equal the endcard start, and the endcard end must equal the independently
+probed base frame count. With `kind: "none"`, the foreground end must instead equal
+that full base frame count. Bounds are half-open.
+
+The only accepted filename pattern is the literal `frame_%06d.png`. The directory
+must contain exactly the expected contiguous entries—no missing or extra files. Every
+actual image must probe as PNG, `rgba`, and the exact declared full canvas. Repeated
+files and symlinks are allowed so transparent holds need not duplicate storage. The
+run report records each sequence's directory and validated `frame_count`. Legacy
+`sha256` / `ordered_sha256` keys in a plan are ignored.
+
+## Base and output invariants
+
+The first version accepts one selected `v:0` H264, zero-origin CFR, YUV420P,
+BT.709/TV-range base and adopted AAC `a:0`. Declared fps, canvas, and frame count are
+checked independently against actual decoded frame PTS. Picture and audio intervals
+must satisfy the narrow `pair_media` timing contract.
+
+Composition explicitly overlays in RGB, converts to BT.709 limited-range YUV420P,
+limits the final video filter to the declared half-open frame clock, and re-encodes
+only video with fixed `libx264 -preset fast -crf 18` settings. A no-tail run uses only
+the base and foreground inputs; it does not synthesize or pad a tail. The filter EOF
+prevents still-image input loops without imposing an output-level video frame cap that
+could stop accepted trailing AAC packets from being copied. The run
+report records that encoder, preset, CRF, pixel format, color contract, and audio-copy
+mode explicitly. H.264 CRF encoding is lossy: preserved transparent regions are
+visually checked against tolerances, not claimed pixel-identical to decoded base
+pixels. The compositor does not use `-r`, `-shortest`, or `-t`. Audio is mapped from
+base `a:0` with `-c:a copy`; output verification requires matching decoder
+parameters, packet count, payload bytes, PTS/DTS/duration/size, and side data.
+
+## Provenance and review boundary
+
+The producer receipt is a caller artifact that must exist when the plan is read.
+Its declarations may
+describe roles or content decisions such as title/note/brand, `dialogues=[]`, or
+hidden markers. Core records those declarations as `DECLARED_NOT_CHECKED`; it does
+not infer semantic truth from pixels or claim that dialogue/subtitle duplication is
+absent. A separate producer/reviewer must establish that evidence.
+
+Every run reports `direct_listening` and `normal_speed_review` as `NOT_CHECKED` and
+`release_approved` as false. Pixel validation and deterministic rendering are not
+commercial-quality or release approval.

package/lib/video-recap/skills/video-assemble/references/narration-adoption.md

@@ -0,0 +1,103 @@
+# 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/lib/video-recap/skills/video-assemble/references/packaging.md

@@ -0,0 +1,45 @@
+# 字幕与包装的推荐顺序
+
+先锁定画面、剪点、旁白和混音，再投入字幕动画或边框包装。字幕样式不能掩盖叙事、剪点或声音问题。
+
+普通交付优先使用现有 ASS 路径。只有用户需要更精细的逐 cue 排版、动画或透明图层时，才使用 Remotion
+或其他代码渲染器作为**项目级可选实现**，不要把特定框架、字体、颜色或黄字写成核心依赖。
+
+## 推荐顺序
+
+1. 输出无包装的锁定母版，确认音画内容不再变化。
+2. 从实际 TTS / 时间线生成 captions；TTS 块保持连续思路，字幕可以按阅读宽度拆 cue。
+3. 先抽检开头、亮背景、暗背景、人物近景和长字幕样帧，确定字号、安全区、描边、阴影及是否需要底板。
+4. 渲染完整透明字幕层，再 overlay 到锁定母版；合成后确认音轨未被意外改写。
+5. 完整播放实际最终文件，并复查字幕遮脸、跳字、断行、首尾帧和边界处残影。
+
+已有项目级渲染器能输出精确包装时，使用 `foreground-compose.md` 将它生成的 RGBA 序列叠到锁定母版，
+而不是用通用白字黑框近似品牌样式。该操作保留实际帧钟和 AAC 包，不生成字体或文案；只有通过验证的
+新文件才写入新目录。片名卡有渐显或动画时须提供完整序列，不能冻结最后一张图代替。
+
+## 静态包装图层 `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` 标记；
+  手写的文件不会被它删除。有渐显或动画的包装仍走 `foreground-compose.md`。
+
+## 原则
+
+包装价值来自稳定、可读、与内容一致的排版，不来自效果数量。先建立统一字体、颜色、描边/阴影和轻量动效；
+底板、边框、花字与音效只有解决具体可读性或叙事任务时才加入。一个样帧好看不代表全片成立。

package/lib/video-recap/skills/video-assemble/references/pair-media.md

@@ -0,0 +1,74 @@
+# Pair rebuilt picture with a retained adopted soundtrack
+
+When the picture is rebuilt/reframed but the adopted mix must not change, use
+`pair_media.py` before `assemble.py --audio-mode adopted-packet-copy`. This is a
+real two-input stream copy, not re-encoding an old finished video's picture.
+It does not generate narration, align speech, design packaging, or create an
+end card. It does not decide which inputs the editor intended to adopt.
+
+```json
+{
+  "artifact": "media_pair",
+  "schema_version": 1,
+  "picture": {"path": "/project/picture.mp4"},
+  "audio": {"path": "/project/adopted.m4a", "selected_stream": 0}
+}
+```
+
+Both paths must be explicit local files. `selected_stream` is the audio ordinal
+(`a:N`), not the absolute stream index. The audio donor may be an old MP4 with
+unrelated video: only the selected audio is used. The picture's audio is ignored.
+Both files must exist when the plan is read. The plan is strict: unknown fields
+do not silently request unsupported retime, gain, trimming or offset operations
+(legacy `sha256` keys are ignored).
+
+```bash
+python3 scripts/pair_media.py pair.json --output-dir new-pair-directory --plan-only
+# A PLANNED directory is not reusable as a rendered candidate: choose a NEW one.
+python3 scripts/pair_media.py pair.json --output-dir new-render-directory
+```
+
+The output directory must not already exist. No existing input, final asset,
+current pointer, or user-approved version is overwritten. `--plan-only` checks
+actual inputs and timing but creates no video and invokes no mux. A rendered run
+provides:
+
+- `paired.mp4`: selected picture and audio, both compressed-stream copied.
+- `pair_run.json`: `PLANNED`, `PAIR_RENDERED`, or `FAILED`, explicit input and
+  plan/output paths, frame count, timing tolerance and output stream numbering.
+- `picture_identity.json`: decoder, geometry/color, complete actual frame clock
+  and compressed packet size/timing/side-data facts.
+- `adopted_audio_identity.json`: donor and output AAC packet/decoder facts.
+- mux command/log for reconstruction and diagnosis.
+
+The first implementation deliberately accepts H264 or HEVC in an MP4-family container,
+complete zero-origin CFR picture (1–120 fps), and contiguous AAC packets with
+known nominal sample duration. No VFR, retime, offset, format conversion, padding,
+trimming, `-shortest`, normalization or gain is inferred. Packet priming and skip
+metadata are retained. The packet clock must also agree with the declared audio
+stream interval (at most one nominal priming packet before the start; the packet
+end matches the stream end within one sample). This is checked again on the
+actual muxed output. Picture/audio starts and ends must differ by no more than
+the larger of one picture frame or one nominal AAC packet. The interval check is
+compatibility, **not perceptual synchronization or acoustic alignment**. A tiny
+container-tail tolerance does not authorize cutting a word.
+
+Muxing goes to a staging file. The output's video decoder/packet sizes and
+timestamps/full frame clock/geometry/color and adopted AAC packets must match
+the inputs, the output must contain only `v:0,a:0`, and full decode must pass
+before final publication. Failure leaves a FAILED record and logs, not a
+final `paired.mp4`. Rebuilding source geometry is certified by its own upstream
+render/map evidence, not by the existence of a successfully paired container.
+
+## Subtitle integration: bind AFTER pairing
+
+The output audio ordinal is always **0**, even when the donor used `a:1`.
+Create the complete output-clock `subtitle_track.json` against
+`subtitles.track_binding.current_bindings(paired_video, 0)`, then run the existing
+adopted assembly path. Do not reuse a binding computed against the picture-only
+file or the donor's old stream ordinal. A present stale subtitle track fails rather than falling
+back to estimated timings. See [subtitle-track.md](subtitle-track.md).
+
+Pairing preserves the input picture, including any explicit black tail; it does
+not turn that black tail into a branded end card. Listening, normal-speed review,
+editorial intent and release approval remain separate from this mechanical proof.