@oh-story/dsh 0.1.10 → 0.1.12

package/lib/video-recap/skills/video-assemble/scripts/assemble.py

@@ -9,46 +9,160 @@ import assemble_constants as constants
 import assembly_contract
 import assembly_settings
 import audio_mix
+import adoption.audio_mix_binding as audio_mix_binding
+import adoption.frozen_audio as frozen_audio
 import media
 import narration_audio
+import adoption.narration_binding as narration_binding
+import pair_media
 import render_preflight
-import subtitle_render
+import adoption.strict_publish as strict_publish
+import subtitles.render as subtitle_render
+import subtitles.track_binding as subtitle_track_binding
 import timeline_emit
+import packaging
 import visual_render
 import lib
-from assembly_settings import assembly_settings_fingerprint
-from audio_mix import final_loudnorm_filter
 
 __all__ = [
     "assemble_video",
-    "assembly_settings_fingerprint",
-    "final_loudnorm_filter",
     "main",
 ]
 
 
-def assemble_video(input_video, tts_segments, work_dir, output_path):
+AUDIO_MODES = ("narration", "source-mix", "adopted-packet-copy")
+
+
+_current_narration_binding = strict_publish.current_narration_binding
+_current_audio_mix_binding = strict_publish.current_audio_mix_binding
+
+
+def assemble_video(input_video, tts_segments, work_dir, output_path, *,
+                   audio_mode="narration", audio_stream_index=0,
+                   narration_adoption_path=None, tts_meta_path=None,
+                   audio_mix_adoption_path=None):
     """组装最终视频"""
-    if not tts_segments:
+    if audio_mode not in AUDIO_MODES:
+        raise RuntimeError(f"不支持的 audio_mode: {audio_mode}")
+    if isinstance(audio_stream_index, bool) or not isinstance(audio_stream_index, int) or audio_stream_index < 0:
+        raise RuntimeError("audio_stream_index 必须是非负整数")
+    if audio_mode == "narration" and not tts_segments:
         raise RuntimeError("tts_meta.json 没有有效解说音频，已中止以避免生成无解说视频")
+    if audio_mode == "narration" and audio_stream_index != 0:
+        raise RuntimeError("narration 当前不支持非零 audio_stream_index")
+    if audio_mode == "source-mix" and tts_segments:
+        raise RuntimeError("source-mix 与 TTS 解说不兼容")
+    if audio_mode != "narration" and tts_meta_path is not None:
+        raise RuntimeError(f"tts_meta 与 audio_mode {audio_mode} 不兼容")
+    bgm_path = lib.CONFIG["bgm_path"]
+    has_bgm = bool(bgm_path) and os.path.exists(bgm_path)
+    if audio_mode == "source-mix" and bgm_path and not has_bgm:
+        raise RuntimeError(f"source-mix 声明的 BGM 文件不存在: {bgm_path}")
+    if (
+        audio_mode != "narration"
+        and audio_stream_index != 0
+        and lib.CONFIG["export_jianying"]
+    ):
+        raise RuntimeError("剪映导出当前不支持选择非零音频流")
+    if audio_mode == "adopted-packet-copy":
+        if tts_segments:
+            raise RuntimeError("adopted-packet-copy 与 TTS 解说不兼容")
+        if bgm_path:
+            raise RuntimeError("adopted-packet-copy 与 BGM 混音不兼容")
+    if audio_mode != "narration" and narration_adoption_path is not None:
+        raise RuntimeError("narration adoption 仅适用于 narration audio_mode")
+    if audio_mix_adoption_path is not None and (
+        audio_mode != "narration" or narration_adoption_path is None or tts_meta_path is None
+    ):
+        raise RuntimeError("audio mix adoption 要求 narration 模式及显式 narration adoption/tts_meta")
+
+    published_output = Path(output_path)
+    if audio_mix_adoption_path is not None and published_output.exists():
+        raise RuntimeError("显式音频混合要求新的 output_path，不能覆盖已有成片")
+    explicit_mix = (
+        audio_mix_binding.load_adoption(
+            audio_mix_adoption_path, input_video=input_video,
+            narration_adoption_path=narration_adoption_path, tts_segments=tts_segments,
+        )
+        if audio_mix_adoption_path is not None else None
+    )
 
+    binding = narration_binding.prepare_binding(
+        tts_segments, work_dir,
+        narration_adoption_path=narration_adoption_path,
+        tts_meta_path=tts_meta_path,
+    ) if audio_mode == "narration" else None
+    render_output = published_output
+    if binding and binding["active"]:
+        if published_output.exists():
+            raise RuntimeError("身份约束渲染要求新的 output_path，不能覆盖已有成片")
+        render_output = published_output.with_name(
+            f".{published_output.stem}.narration-rendering{published_output.suffix}"
+        )
+        render_output.unlink(missing_ok=True)
+    output_path = render_output
     video_duration = lib.get_video_duration(input_video)
     canvas = media._probe_canvas(input_video)  # drives subtitle PlayRes/scale so 竖屏 text isn't stretched
     burn_subtitles = lib.CONFIG["burn_subtitles"]
+    subtitle_track_binding.prepare_subtitle_track(
+        input_video,
+        work_dir,
+        video_duration,
+        audio_mode=audio_mode,
+        selected_audio_stream=audio_stream_index,
+    )
+    adopted_source_audio = None
+    if audio_mode == "adopted-packet-copy":
+        adopted_source_audio = frozen_audio.validate_adopted_source(
+            input_video, audio_stream_index
+        )
+        if type(adopted_source_audio["sample_rate"]) is not int \
+                or adopted_source_audio["sample_rate"] <= 0:
+            raise RuntimeError("adopted audio sample rate must be a positive integer")
+    elif audio_mode == "source-mix":
+        frozen_audio.probe_audio_packets(input_video, audio_stream_index)
 
     # 解说整体提速（可选）后，将所有 TTS 片段按时间位置合成到与视频等长的音轨上
-    narration_audio._apply_narration_speed(tts_segments, work_dir)
-    narration_wav = work_dir / "narration.wav"
-    narration_audio._build_timed_narration(tts_segments, narration_wav, video_duration, work_dir)
-    handoffs = audio_mix._apply_source_sentence_handoffs(tts_segments, work_dir, video_duration)
-    if handoffs:
-        lib.log(
-            "原声句末交接: "
-            + ", ".join(
-                f"{item['end']:.2f}s→{item.get('restore_at', item['end']):.2f}s({item['status']})"
-                for item in handoffs
-            )
+    narration_wav = None
+    if audio_mode == "narration" and explicit_mix is not None:
+        explicit_runtime = audio_mix_binding.render_explicit_mix(
+            explicit_mix, binding, tts_segments, work_dir
         )
+        narration_wav = Path(explicit_runtime["voice_bus"]["path"])
+    elif audio_mode == "narration":
+        if binding["tempo_policy"]:
+            narration_audio._apply_narration_speed(
+                tts_segments, work_dir, tempo_policy=binding["tempo_policy"]
+            )
+        else:
+            narration_audio._apply_narration_speed(tts_segments, work_dir)
+        narration_wav = work_dir / "narration.wav"
+        if binding["tempo_policy"]:
+            narration_audio._build_timed_narration(
+                tts_segments, narration_wav, video_duration, work_dir,
+                tempo_policy=binding["tempo_policy"],
+            )
+            if any(
+                segment.get("blocking") or segment.get("fit_status") == "no_safe_fit"
+                for segment in tts_segments
+            ):
+                raise RuntimeError(
+                    "严格 narration adoption 存在 no_safe_fit，禁止提速或裁尾渲染"
+                )
+        else:
+            narration_audio._build_timed_narration(
+                tts_segments, narration_wav, video_duration, work_dir
+            )
+        handoffs = audio_mix._apply_source_sentence_handoffs(tts_segments, work_dir, video_duration)
+        if handoffs:
+            lib.log(
+                "原声句末交接: "
+                + ", ".join(
+                    f"{item['end']:.2f}s→{item.get('restore_at', item['end']):.2f}s({item['status']})"
+                    for item in handoffs
+                )
+            )
+        narration_binding.seal_render_inputs(binding, tts_segments, narration_wav)
 
     # 始终生成 SRT 字幕文件（原声留白处补烧原声字幕，传入成片时长以计算留白区间）
     srt_path = subtitle_render._generate_srt(tts_segments, work_dir, video_duration)
@@ -59,17 +173,24 @@ def assemble_video(input_video, tts_segments, work_dir, output_path):
         lib.log(f"压制字幕文件: {ass_path}")
 
     # 可选 BGM：作为一条独立音轨（input [2:a]）混入，旁白处自动压低
-    bgm_path = lib.CONFIG["bgm_path"]
-    has_bgm = bool(bgm_path) and os.path.exists(bgm_path)
-    if bgm_path and not has_bgm:
+    if explicit_mix is not None:
+        lib.log("显式 adopted full-sound：忽略环境 BGM/duck/loudnorm/tempo 配置")
+    elif bgm_path and not has_bgm:
         lib.log(f"  ⚠️ BGM 文件不存在，跳过: {bgm_path}")
     elif has_bgm:
         lib.log(f"BGM 铺底: {bgm_path} (音量 {lib.CONFIG['bgm_volume']}，旁白时 {lib.CONFIG['bgm_ducking_volume']})")
 
     # 多轨时间线模型（timeline.json）：canonical 渲染仍是 ffmpeg，此模型供检视/可选导出
-    timeline_emit._emit_timeline(input_video, tts_segments, work_dir, video_duration, canvas, has_bgm)
+    timeline_emit._emit_timeline(
+        input_video, tts_segments, work_dir, video_duration, canvas, has_bgm,
+        audio_mode=audio_mode, selected_audio_stream=audio_stream_index,
+        explicit_audio_mix=(
+            {**explicit_mix, **explicit_mix["runtime"]} if explicit_mix is not None else None
+        ),
+    )
 
     overlay_filters, overlay_qc = visual_render._visual_overlay_filters(work_dir, canvas, video_duration)
+    packaging_layers = packaging.load_packaging_layers(work_dir, canvas)
     mask_filter = visual_render._source_subtitle_mask_filter(canvas, work_dir, tts_segments, video_duration)
     visual_qc = visual_render._build_visual_qc(
         tts_segments,
@@ -86,65 +207,94 @@ def assemble_video(input_video, tts_segments, work_dir, output_path):
         codes = ", ".join(visual_qc["blocking_codes"])
         raise RuntimeError(f"视觉 QC 失败: {codes}；详见 {Path(work_dir) / constants.VISUAL_QC}")
 
-    # 混合原始音频 + 解说音频（+ 可选 BGM）
+    # Select exactly one of three explicit audio paths. Only narration may synthesize
+    # a missing original track; adopted copy never decodes, mixes, normalizes or trims.
     source_has_audio = media._has_audio_stream(input_video)
-    if source_has_audio:
-        original_audio_input = []
-        original_audio_label = "0:a"
-        bgm_audio_label = "2:a"
-    else:
-        lib.log("源视频无音轨，使用静音原声音轨进行混音")
-        original_audio_input = [
-            "-f", "lavfi", "-t", str(video_duration),
-            "-i", "anullsrc=channel_layout=stereo:sample_rate=48000",
-        ]
-        original_audio_label = "2:a"
-        bgm_audio_label = "3:a"
-    filter_complex = audio_mix._build_audio_filter_complex(
-        tts_segments,
-        has_bgm,
-        original_audio_label=original_audio_label,
-        bgm_audio_label=bgm_audio_label,
-    )
-
-    # BGM is input [2:a]; -stream_loop -1 loops it to cover the whole timeline (amix
-    # duration=first + -t trim it back to the video length).
-    bgm_input = ["-stream_loop", "-1", "-i", str(bgm_path)] if has_bgm else []
-
-    # 末端整体响度归一：ducking 只管相对平衡，这一步统一成片绝对响度
-    loudnorm_measurement = audio_mix._run_loudnorm_first_pass(
-        input_video,
-        narration_wav,
-        original_audio_input,
-        bgm_input,
-        filter_complex,
-        work_dir,
-    )
-    final_ln = audio_mix.final_loudnorm_filter(loudnorm_measurement)
-    filter_complex += f";[aout]{final_ln}[aoutln]"
-    lib.log(f"成片响度归一: {final_ln}")
-
-    # 对于超长 volume 表达式（多段解说），使用 -filter_complex_script 避免命令行溢出
+    adopted_audio = None
+    loudnorm_measurement = None
+    original_audio_input = []
+    bgm_input = []
+    filter_complex = None
+    filter_args = []
+    audio_input_args = []
     fc_script = None
-    if len(filter_complex.encode("utf-8")) > constants.FILTER_SCRIPT_THRESHOLD_BYTES:
-        fc_script = Path(work_dir) / ".filter_complex.txt"
-        fc_script.write_text(filter_complex, encoding="utf-8")
-        lib.log(f"使用 filter_complex_script (表达式长度 {len(filter_complex.encode('utf-8'))} bytes)")
-        filter_args = ["-filter_complex_script", str(fc_script)]
+    if audio_mode == "adopted-packet-copy":
+        audio_map = f"0:a:{audio_stream_index}"
+    elif audio_mode == "source-mix":
+        audio_map = "[aoutln]"
+        source_label = f"0:a:{audio_stream_index}"
+        filter_complex = f"[{source_label}]volume={lib.CONFIG['idle_orig_volume']}[source]"
+        if has_bgm:
+            bgm_input = ["-stream_loop", "-1", "-i", str(bgm_path)]
+            filter_complex += (
+                f";[1:a]volume={lib.CONFIG['bgm_volume']}[bgm]"
+                ";[source][bgm]amix=inputs=2:duration=first:dropout_transition=0[aout]"
+            )
+        else:
+            filter_complex += ";[source]anull[aout]"
+        final_ln = audio_mix.final_loudnorm_filter()
+        filter_complex += f";[aout]{final_ln}[aoutln]"
+        lib.log(f"source-mix 音频处理: source volume + {final_ln}")
+    elif explicit_mix is not None:
+        audio_map = "1:a:0"
+        audio_input_args = ["-i", explicit_mix["runtime"]["master"]["path"]]
     else:
-        filter_args = ["-filter_complex", filter_complex]
+        # 混合原始音频 + 解说音频（+ 可选 BGM）
+        if source_has_audio:
+            original_audio_label = "0:a"
+            bgm_audio_label = "2:a"
+        else:
+            lib.log("源视频无音轨，使用静音原声音轨进行混音")
+            original_audio_input = [
+                "-f", "lavfi", "-t", str(video_duration),
+                "-i", "anullsrc=channel_layout=stereo:sample_rate=48000",
+            ]
+            original_audio_label = "2:a"
+            bgm_audio_label = "3:a"
+        filter_complex = audio_mix._build_audio_filter_complex(
+            tts_segments,
+            has_bgm,
+            original_audio_label=original_audio_label,
+            bgm_audio_label=bgm_audio_label,
+        )
+        # BGM is input [2:a]; -stream_loop -1 loops it to cover the whole timeline (amix
+        # duration=first + -t trim it back to the video length).
+        bgm_input = ["-stream_loop", "-1", "-i", str(bgm_path)] if has_bgm else []
+        # 末端整体响度归一：ducking 只管相对平衡，这一步统一成片绝对响度
+        loudnorm_measurement = audio_mix._run_loudnorm_first_pass(
+            input_video,
+            narration_wav,
+            original_audio_input,
+            bgm_input,
+            filter_complex,
+            work_dir,
+        )
+        final_ln = audio_mix.final_loudnorm_filter(loudnorm_measurement)
+        filter_complex += f";[aout]{final_ln}[aoutln]"
+        lib.log(f"成片响度归一: {final_ln}")
+        audio_map = "[aoutln]"
+        audio_input_args = ["-i", str(narration_wav), *original_audio_input]
+
+    # 对于超长 volume 表达式（多段解说），从脚本文件读取 filter_complex 避免命令行溢出
+    if filter_complex is not None:
+        if len(filter_complex.encode("utf-8")) > constants.FILTER_SCRIPT_THRESHOLD_BYTES:
+            fc_script = Path(work_dir) / ".filter_complex.txt"
+            fc_script.write_text(filter_complex, encoding="utf-8")
+            lib.log(f"使用 filter_complex 脚本文件 (表达式长度 {len(filter_complex.encode('utf-8'))} bytes)")
+            filter_args = lib.filter_file_args("filter_complex", fc_script)
+        else:
+            filter_args = ["-filter_complex", filter_complex]
     cmd = [
         "ffmpeg", "-y",
         "-i", str(input_video),
-        "-i", str(narration_wav),
-        *original_audio_input,
+        *audio_input_args,
         *bgm_input,
         *filter_args,
         # 0:v:0 (not 0:v): sources with attached cover art carry a second video stream.
         # -vf only ever applies to the first one, so mapping all of them makes ffmpeg
         # abort with "Could not write header (incorrect codec parameters ?)" and leave
         # an unreadable file — after the whole pipeline has already run.
-        "-map", "0:v:0", "-map", "[aoutln]",
+        "-map", "0:v:0", "-map", audio_map,
     ]
 
     # Video filter chain: mask source subtitles first (drawbox), then burn our subtitles
@@ -168,17 +318,19 @@ def assemble_video(input_video, tts_segments, work_dir, output_path):
     # needs EVEN width AND height, so normalize odd dims (4:2:2/4:4:4 permit them) before the
     # encode — otherwise libx264 aborts to a 0-byte file. The downscale helper already evens out.
     even = "scale=trunc(iw/2)*2:trunc(ih/2)*2"
-    reencode = bool(vf_chain) or lib.CONFIG["force_video_reencode"]
+    reencode = bool(vf_chain or packaging_layers) or lib.CONFIG["force_video_reencode"]
     notes = []
     video_filter_script = None
-    if vf_chain:
+    if vf_chain or packaging_layers:
         if max_h <= 0:  # no downscale in the chain to force even dims
             vf_chain.append(even)
-        video_filter = ",".join(vf_chain)
+        video_filter = packaging.compose_video_filter(
+            vf_chain, packaging_layers, mask_first=bool(mask_filter)
+        )
         if len(video_filter.encode("utf-8")) > constants.FILTER_SCRIPT_THRESHOLD_BYTES:
             video_filter_script = Path(work_dir) / ".video_filter.txt"
             video_filter_script.write_text(video_filter, encoding="utf-8")
-            cmd += ["-filter_script:v:0", str(video_filter_script)]
+            cmd += lib.filter_file_args("filter:v:0", video_filter_script)
             lib.log(
                 "使用 video filter script "
                 f"(表达式长度 {len(video_filter.encode('utf-8'))} bytes)"
@@ -187,6 +339,7 @@ def assemble_video(input_video, tts_segments, work_dir, output_path):
             cmd += ["-vf", video_filter]
         cmd += ["-c:v", "libx264", "-preset", preset, "-crf", crf, "-pix_fmt", "yuv420p"]
         notes = ((["遮挡原字幕"] if mask_filter else [])
+                 + ([f"包装图层×{len(packaging_layers)}"] if packaging_layers else [])
                  + ([f"视觉叠加×{len(overlay_filters)}"] if overlay_filters else [])
                  + (["压制解说字幕"] if burn_subtitles else [])
                  + ([f"缩放≤{max_h}p"] if max_h > 0 else []))
@@ -199,8 +352,18 @@ def assemble_video(input_video, tts_segments, work_dir, output_path):
 
     # +faststart relocates the moov atom to the front so web/social players can start
     # before the full file downloads; valid (and beneficial) on the copy path too.
-    cmd += ["-c:a", "aac", "-b:a", "192k", "-ar", "48000", "-movflags", "+faststart",
-            "-t", str(video_duration), str(output_path)]
+    if audio_mode == "adopted-packet-copy":
+        # No -t/-shortest: either would discard valid AAC priming or tail packets.
+        cmd += ["-c:a", "copy", "-movie_timescale",
+                str(adopted_source_audio["sample_rate"]),
+                "-movflags", "+faststart", str(output_path)]
+    elif explicit_mix is not None:
+        cmd += ["-c:a", "aac", "-b:a", "192k", "-ar", "48000",
+                "-movie_timescale", "48000", "-movflags", "+faststart",
+                str(output_path)]
+    else:
+        cmd += ["-c:a", "aac", "-b:a", "192k", "-ar", "48000", "-movflags", "+faststart",
+                "-t", str(video_duration), str(output_path)]
     try:
         result = lib.run_cmd(cmd)
         if result.returncode != 0:
@@ -212,25 +375,61 @@ def assemble_video(input_video, tts_segments, work_dir, output_path):
         if video_filter_script is not None:
             video_filter_script.unlink(missing_ok=True)
 
-    lib.log(f"最终视频: {output_path} ({output_path.stat().st_size / 1024 / 1024:.1f}MB)")
-    assembly_contract._write_assembly_qc(
-        work_dir,
-        assembly_contract._build_assembly_qc(
-            tts_segments,
-            video_duration,
-            output_path=output_path,
-            source_has_audio=source_has_audio,
-            loudnorm_measurement=loudnorm_measurement,
-            visual_qc=visual_qc,
-            render_delivery={
-                "video_encode_passes": 1 if reencode else 0,
-                "reencode_reason": notes,
-                "audio_sample_rate": 48000,
-                "final_compat_notes": ["yuv420p"] if reencode else ["video_copy", "aac_48000", "faststart"],
-            },
+    if audio_mode == "adopted-packet-copy":
+        # Either check failing means the file at the final path is unverified: never leave it.
+        try:
+            adopted_audio = frozen_audio.verify_adopted_audio(
+                input_video, output_path, audio_stream_index
+            )
+            pair_media.validate_aac_packet_interval(adopted_audio["output"])
+        except (RuntimeError, ValueError):
+            output_path.unlink(missing_ok=True)
+            raise
+    subtitle_track_binding.verify_rendered_picture(work_dir, output_path)
+    audio_operations = {
+        "narration": audio_mode == "narration",
+        "source_mix": audio_mode == "source-mix",
+        "bgm_mix": has_bgm and audio_mode != "adopted-packet-copy" and explicit_mix is None,
+        "ducking": audio_mode == "narration" and explicit_mix is None,
+        "loudness_normalization": (
+            audio_mode != "adopted-packet-copy" and explicit_mix is None
+            and lib.CONFIG["final_loudnorm"]
+        ),
+        "limiter": audio_mode != "adopted-packet-copy" and explicit_mix is None,
+        "resample": audio_mode != "adopted-packet-copy",
+        "tempo": audio_mode == "narration" and explicit_mix is None,
+        "packet_copy": audio_mode == "adopted-packet-copy",
+    }
+    if explicit_mix is not None:
+        audio_operations["explicit_audio_mix"] = True
+    render_delivery = {
+        "video_encode_passes": 1 if reencode else 0,
+        "reencode_reason": notes,
+        "audio_sample_rate": (
+            adopted_audio["output"]["sample_rate"] if adopted_audio else 48000
         ),
+        "final_compat_notes": (
+            (["yuv420p"] if reencode else ["video_copy"])
+            + (["aac_packet_copy", "faststart"] if adopted_audio else ["aac_48000", "faststart"])
+        ),
+    }
+    loudness_mode = (
+        "not_run" if audio_mode == "adopted-packet-copy" else
+        "fixed_master_gain_no_loudnorm" if explicit_mix is not None else None
+    )
+    source_audio_status = "prepared_bed_adopted" if explicit_mix is not None else None
+    render_output = strict_publish.publish_render(
+        work_dir=work_dir, binding=binding, explicit_mix=explicit_mix,
+        tts_segments=tts_segments, narration_wav=narration_wav,
+        render_output=render_output, published_output=published_output,
+        audio_mode=audio_mode, audio_operations=audio_operations,
+        adopted_audio=adopted_audio, loudness_mode=loudness_mode,
+        loudnorm_measurement=loudnorm_measurement, visual_qc=visual_qc,
+        source_has_audio=source_has_audio, video_duration=video_duration,
+        render_delivery=render_delivery, source_audio_status=source_audio_status,
     )
-    return output_path
+    lib.log(f"最终视频: {render_output} ({render_output.stat().st_size / 1024 / 1024:.1f}MB)")
+    return render_output
 
 
 def main():
@@ -241,6 +440,18 @@ def main():
     ap.add_argument("video", help="source video (edited_source.mp4 in cut mode, else the original)")
     ap.add_argument("--work-dir", required=True)
     ap.add_argument("--tts-meta", default=None, help="tts_meta.json (default: <work-dir>/tts_meta.json)")
+    ap.add_argument("--narration-adoption", default=None,
+                    help="strict narration_adoption v1 bound to an explicit --tts-meta")
+    ap.add_argument("--audio-mix-adoption", default=None,
+                    help="strict audio_mix_adoption v1 for adopted prepared bed and narration")
+    ap.add_argument(
+        "--audio-mode", choices=AUDIO_MODES,
+        default="narration", help="audio path (default: narration)",
+    )
+    ap.add_argument(
+        "--audio-stream-index", type=int, default=0,
+        help="zero-based input audio stream ordinal for source/adopted modes",
+    )
     ap.add_argument("--recap-stem", default=None, help="final recap filename stem (default: video stem)")
     ap.add_argument("--output-dir", default=None)
     ap.add_argument("--burn-subtitles", action=argparse.BooleanOptionalAction, default=None,
@@ -254,10 +465,12 @@ def main():
     ap.add_argument("--export-jianying", action="store_true",
                     help="also export an OPTIONAL 剪映/JianYing draft from timeline.json after rendering")
     ap.add_argument("--jianying-out", default=None, help="parent dir for the 剪映 draft (default: work-dir)")
-    ap.add_argument("--jianying-bundle-media", action="store_true",
-                    help="copy media into the 剪映 draft folder (default on; portable/self-contained)")
-    ap.add_argument("--jianying-no-bundle-media", action="store_true",
-                    help="do NOT copy media into the draft — reference in place (only if 剪映 can read those paths; macOS 剪映 usually cannot)")
+    bundle_group = ap.add_mutually_exclusive_group()
+    bundle_group.add_argument("--jianying-bundle-media", dest="jianying_bundle_media", action="store_true",
+                              help="copy media into the 剪映 draft folder (default on; portable/self-contained)")
+    bundle_group.add_argument("--jianying-no-bundle-media", dest="jianying_bundle_media", action="store_false",
+                              help="do NOT copy media into the draft — reference in place (only if 剪映 can read those paths; macOS 剪映 usually cannot)")
+    ap.set_defaults(jianying_bundle_media=None)
     args = ap.parse_args()
     work_dir = Path(args.work_dir)
     if args.burn_subtitles is not None:
@@ -291,38 +504,84 @@ def main():
         lib.CONFIG["source_video_explicit"] = False
     if args.export_jianying:
         lib.CONFIG["export_jianying"] = True
-    if args.jianying_bundle_media:
-        lib.CONFIG["jianying_bundle_media"] = True
-    if args.jianying_no_bundle_media:
-        lib.CONFIG["jianying_bundle_media"] = False
+    if args.jianying_bundle_media is not None:
+        lib.CONFIG["jianying_bundle_media"] = args.jianying_bundle_media
     render_preflight._preflight_burn_subtitles()  # fail before the render if burn-in is on but ffmpeg lacks libass
-    tts_meta = Path(args.tts_meta) if args.tts_meta else work_dir / "tts_meta.json"
-    tts_segments = json.loads(tts_meta.read_text(encoding="utf-8"))["segments"]
-    output_path = work_dir / "output.mp4"
-    assemble_video(args.video, tts_segments, work_dir, output_path)
-    assembly_qc = artifacts._load_work_json(work_dir, constants.ASSEMBLY_QC)
-    if assembly_qc["blocking"]:
-        codes = ", ".join(assembly_qc["blocking_codes"])
-        raise SystemExit(f"组装 QC 阻断交付: {codes}；详见 {work_dir / constants.ASSEMBLY_QC}")
+    # Argument combinations are validated once, by assemble_video.
+    tts_meta = Path(args.tts_meta) if args.tts_meta else None
+    tts_segments = []
+    if args.audio_mode == "narration":
+        tts_meta = tts_meta or work_dir / "tts_meta.json"
+        tts_segments = json.loads(tts_meta.read_text(encoding="utf-8"))["segments"]
     stem = args.recap_stem or Path(args.video).stem
     base = Path(args.output_dir) if args.output_dir else work_dir.parent
-    base.mkdir(parents=True, exist_ok=True)
     final_output = assembly_contract._resolve_final_output(base, stem)
-    shutil.copy2(str(output_path), str(final_output))
-    manifest = assembly_contract._assembly_manifest_payload(
-        args.video, tts_segments, work_dir, output_path,
-        tts_meta_path=tts_meta,
-        final_output=final_output,
-        settings_fingerprint=assembly_settings.assembly_settings_fingerprint,
-    )
-    assembly_contract._write_assembly_manifest(work_dir, manifest)
+    if args.audio_mix_adoption is not None and final_output.exists():
+        ap.error("explicit audio mix requires a new final delivery path")
+    delivery_stage = None
+    owned_alias = None
+    output_path = work_dir / "output.mp4"
+    try:
+        assemble_video(
+            args.video, tts_segments, work_dir, output_path,
+            audio_mode=args.audio_mode, audio_stream_index=args.audio_stream_index,
+            narration_adoption_path=args.narration_adoption, tts_meta_path=tts_meta,
+            audio_mix_adoption_path=args.audio_mix_adoption,
+        )
+        assembly_qc = artifacts._load_work_json(work_dir, constants.ASSEMBLY_QC)
+        if assembly_qc["blocking"]:
+            codes = ", ".join(assembly_qc["blocking_codes"])
+            raise SystemExit(
+                f"组装 QC 阻断交付: {codes}；详见 {work_dir / constants.ASSEMBLY_QC}"
+            )
+        base.mkdir(parents=True, exist_ok=True)
+        if args.audio_mix_adoption is not None:
+            # Publish the delivery alias only when this process created it: stage a copy,
+            # hard-link it into place (fails if the alias appeared meanwhile), remember the
+            # inode, and roll back only an alias we own.
+            delivery_stage = final_output.with_name(
+                f".{final_output.name}.rendering-{os.getpid()}"
+            )
+            with output_path.open("rb") as source, delivery_stage.open("xb") as target:
+                shutil.copyfileobj(source, target)
+                target.flush()
+                os.fsync(target.fileno())
+            try:
+                os.link(delivery_stage, final_output)
+            except FileExistsError as exc:
+                raise RuntimeError("explicit audio mix delivery alias appeared during render") from exc
+            stat = final_output.stat()
+            owned_alias = (stat.st_dev, stat.st_ino)
+            delivery_stage.unlink()
+            delivery_stage = None
+        else:
+            shutil.copy2(str(output_path), str(final_output))
+        manifest = assembly_contract._assembly_manifest_payload(
+            args.video, tts_segments, work_dir, output_path,
+            tts_meta_path=tts_meta,
+            narration_input_binding=_current_narration_binding(work_dir, args.audio_mode),
+            audio_mix_binding=_current_audio_mix_binding(work_dir, args.audio_mode),
+            final_output=final_output,
+            settings_payload=assembly_settings.assembly_settings_payload,
+            audio_mode=args.audio_mode,
+            audio_stream_index=args.audio_stream_index,
+        )
+        assembly_contract._write_assembly_manifest(work_dir, manifest)
+    except BaseException:
+        if delivery_stage is not None:
+            delivery_stage.unlink(missing_ok=True)
+        if owned_alias is not None and final_output.exists():
+            stat = final_output.stat()
+            if (stat.st_dev, stat.st_ino) == owned_alias:
+                final_output.unlink()
+        raise
     lib.log(f"组装完成: {final_output}")
 
     # OPTIONAL, decoupled: export a 剪映 draft from the timeline (lazy import; never
     # required by the core render path).
     if lib.CONFIG["export_jianying"]:
-        from jianying_optional import _maybe_export_jianying
-        _maybe_export_jianying(work_dir, args.jianying_out, stem)
+        from jianying.optional import maybe_export_jianying
+        maybe_export_jianying(work_dir, args.jianying_out, stem)
 
     print(json.dumps({"status": "assembled", "output": str(final_output), "work_dir": str(work_dir)},
                      ensure_ascii=False))