zenstory-ai/video-recap-skills / skills/video-recap
video-recap
Verified把一段或多集视频做成带画框字幕的中文解说成片或纯原声高光短片。用户提供 .mp4 / .mov / .mkv / .webm,要求做影视解说、短剧二创、加旁白配音、跨集混剪或导出剪映草稿时使用;串联完成看片识台词、定主线与留原声、按台词停顿切镜头、写词检查、TTS 配音与混音加字幕。触发词:视频解说、影视解说、视频旁白、生成解说、视频 recap、video recap、voiceover、narration、recap。
scripts/assemble.py
View on GitHub"""Canonical CLI and programmatic render entry for the assemble stage."""
import argparse
import inspect
import json
import math
import os
import shutil
import subprocess
from pathlib import Path
import artifacts
import assemble_constants as constants
import assembly_contract
import assembly_settings
import audio_mix
import codec_peak
import loudness
import media
import narration_audio
import render_preflight
import sfx_mix
import subtitles.render as subtitle_render
import timeline_emit
import packaging
import visual_render
import lib
__all__ = [
"assemble_video",
"main",
]
AUDIO_MODES = ("narration", "source-mix")
def assemble_video(input_video, tts_segments, work_dir, output_path, *,
audio_mode="narration", tts_meta_path=None):
"""组装最终视频"""
if audio_mode not in AUDIO_MODES:
raise RuntimeError(f"不支持的 audio_mode: {audio_mode}")
if audio_mode == "narration" and not tts_segments:
raise RuntimeError("tts_meta.json 没有有效解说音频,已中止以避免生成无解说视频")
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}")
media._plan_clip_spans(work_dir) # a stale cut plan fails here, not after the render
output_path = Path(output_path)
video_duration = lib.get_video_duration(input_video)
input_canvas = media._probe_canvas(input_video)
canvas = packaging.resolve_output_canvas(work_dir, input_canvas)
burn_subtitles = lib.CONFIG["burn_subtitles"]
source_has_audio = media._has_audio_stream(input_video)
if audio_mode == "source-mix" and not source_has_audio:
raise RuntimeError(f"找不到音频流 a:0: {Path(input_video)}")
# 解说整体提速(可选)后,将所有 TTS 片段按时间位置合成到与视频等长的音轨上
narration_wav = None
if audio_mode == "narration":
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
)
)
_block_before_render(tts_segments, video_duration, work_dir, output_path, audio_mode)
# 始终生成 SRT 字幕文件(原声留白处补烧原声字幕,传入成片时长以计算留白区间)
srt_params = inspect.signature(subtitle_render._generate_srt).parameters
if "canvas" in srt_params or any(
p.kind == inspect.Parameter.VAR_KEYWORD for p in srt_params.values()
):
srt_path = subtitle_render._generate_srt(
tts_segments, work_dir, video_duration, canvas=canvas
)
else:
srt_path = subtitle_render._generate_srt(tts_segments, work_dir, video_duration)
lib.log(f"字幕文件: {srt_path}")
ass_path = None
subtitle_spans = []
if burn_subtitles:
ass_path = subtitle_render._generate_ass(tts_segments, work_dir, video_duration, canvas)
lib.log(f"压制字幕文件: {ass_path}")
subtitle_spans = subtitle_render.burned_subtitle_spans(
tts_segments, work_dir, video_duration, canvas=canvas
)
# 可选 BGM:作为一条独立音轨(input [2:a])混入,旁白处自动压低
if 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']})")
pkg_params = inspect.signature(packaging.prepare_studio_packaging).parameters
if "subtitle_spans" in pkg_params or any(
p.kind == inspect.Parameter.VAR_KEYWORD for p in pkg_params.values()
):
studio_plan = packaging.prepare_studio_packaging(
work_dir, input_canvas, video_duration, tts_segments, subtitle_spans=subtitle_spans
)
else:
studio_plan = packaging.prepare_studio_packaging(
work_dir, input_canvas, video_duration, tts_segments
)
# 多轨时间线模型(timeline.json):canonical 渲染仍是 ffmpeg,此模型供检视/可选导出
timeline_emit._emit_timeline(
input_video, tts_segments, work_dir, video_duration, canvas, has_bgm,
audio_mode=audio_mode,
studio_packaging=studio_plan,
)
packaging_layers = packaging.load_packaging_layers(work_dir, canvas)
mask_filter = visual_render._source_subtitle_mask_filter(input_canvas, work_dir, tts_segments, video_duration)
visual_qc = visual_render._build_visual_qc(
tts_segments,
work_dir,
video_duration,
canvas,
mask_filter=mask_filter,
packaging_qc=studio_plan["qc"] if studio_plan else None,
)
visual_render._write_visual_qc(work_dir, visual_qc)
assembly_qc_path = Path(work_dir) / constants.ASSEMBLY_QC
assembly_qc_path.unlink(missing_ok=True)
if visual_qc["blocking"]:
codes = ", ".join(visual_qc["blocking_codes"])
raise RuntimeError(f"视觉 QC 失败: {codes};详见 {Path(work_dir) / constants.VISUAL_QC}")
# Select exactly one of two explicit audio paths. Only narration may synthesize
# a missing original track.
loudnorm_measurement = None
peak_limiter = None
peak_target = loudness.first_render_peak_target()
original_audio_input = []
bgm_input = []
filter_args = []
audio_input_args = []
fc_script = None
audio_map = "[aoutln]"
# mix_graph is the mix before the final loudness stage ([aout]).
if audio_mode == "source-mix":
tail_fade = audio_mix._tail_fade_suffix(video_duration)
mix_graph = f"[0:a:0]volume={lib.CONFIG['idle_orig_volume']}{tail_fade}[source]"
if has_bgm:
bgm_input = ["-stream_loop", "-1", "-i", str(bgm_path)]
mix_graph += (
f";[1:a]volume={lib.CONFIG['bgm_volume']}{tail_fade}[bgm]"
";[source][bgm]amix=inputs=2:duration=first:dropout_transition=0[aout]"
)
else:
mix_graph += ";[source]anull[aout]"
def plan_loudness(_target, _measured=None):
return None, None
else:
# 混合原始音频 + 解说音频(+ 可选 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"
mix_graph = audio_mix._build_audio_filter_complex(
tts_segments,
has_bgm,
original_audio_label=original_audio_label,
bgm_audio_label=bgm_audio_label,
video_duration=video_duration,
)
# 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 []
def plan_loudness(target, measured=None):
return loudness.plan_final_loudness(
input_video, narration_wav, original_audio_input, bgm_input, mix_graph,
work_dir, peak_target=target, measured=measured,
)
audio_input_args = ["-i", str(narration_wav), *original_audio_input]
sfx_wav, sfx_applied = sfx_mix.build_sfx_track(work_dir, video_duration, tts_segments)
if sfx_wav is not None:
sfx_idx = (
(1 + (1 if has_bgm else 0))
if audio_mode == "source-mix"
else (2 + (0 if source_has_audio else 1) + (1 if has_bgm else 0))
)
bgm_input = [*bgm_input, "-i", str(sfx_wav)]
tail_fade = audio_mix._tail_fade_suffix(video_duration)
mix_graph = (
f"{mix_graph[:-len('[aout]')]}[pre_sfx];"
f"[{sfx_idx}:a]aresample=48000{tail_fade}[sfx];"
"[pre_sfx][sfx]amix=inputs=2:duration=first:dropout_transition=0:normalize=0[aout]"
)
# 末端整体响度归一:ducking 只管相对平衡,这一步统一成片绝对响度
loudnorm_measurement, peak_limiter = plan_loudness(peak_target)
final_ln = loudness.final_loudnorm_filter(loudnorm_measurement, peak_limiter,
peak_target)
filter_complex = f"{mix_graph};[aout]{final_ln}[aoutln]"
lib.log(f"成片响度归一 ({audio_mode}): {final_ln}")
# 对于超长 volume 表达式(多段解说),从脚本文件读取 filter_complex 避免命令行溢出
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),
*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", audio_map,
]
# Video filter chain: mask source subtitles first (drawbox), then burn our subtitles
# on top. Either one forces a re-encode; with neither, the video stream is copied.
crf = str(lib.CONFIG["output_crf"]) # env_int already clamps to >=0; keep 0 (lossless) intact
preset = lib.CONFIG["output_preset"]
max_h = lib.CONFIG["output_max_height"]
vf_chain = []
if mask_filter:
vf_chain.append(mask_filter)
if burn_subtitles:
vf_chain.append(visual_render._subtitle_burn_filter(ass_path))
# Downscale LAST so the mask + burned subtitles render at native resolution and are then
# scaled down with the frame (crisp). The helper forces both dimensions even so an odd
# OUTPUT_MAX_HEIGHT can't crash libx264; 'min(ih,H)' only ever shrinks the source.
if max_h > 0:
vf_chain.append(visual_render._output_downscale_filter(max_h))
# yuv420p: 10-bit/4:2:2 sources re-encoded as-is play on desktop but fail on WeChat/
# mobile/Safari; force 8-bit 4:2:0 so every recap is universally decodable. yuv420p also
# 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"
# A stream copy only stays when the source already is what a re-encode would deliver
# (H.264 8-bit 4:2:0, even size); otherwise a filter-free render re-encodes too, so the
# yuv420p guarantee holds on every path, including no-burn and degraded-burn runs.
source_format = media._probe_video_format(input_video)
color_tags = media._output_color_tags(source_format)
copy_unsafe = not media._video_copy_safe(source_format)
reencode = (
bool(vf_chain or packaging_layers or studio_plan)
or lib.CONFIG["force_video_reencode"]
or copy_unsafe
)
notes = []
video_filter_script = None
if studio_plan is not None:
vf_tail = []
if burn_subtitles:
studio_font_file = studio_plan["subtitle_overrides"].get("font_file") or lib.CONFIG["subtitle_font_file"]
vf_tail.append(visual_render._subtitle_burn_filter(ass_path, font_file=studio_font_file))
if max_h > 0:
vf_tail.append(visual_render._output_downscale_filter(max_h))
else:
vf_tail.append(even)
vf_tail.append(media._color_tag_filter(color_tags))
video_filter = packaging.compose_studio_video_filter(
studio_plan, vf_tail, extra_layers=packaging_layers, mask_filter=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 += lib.filter_file_args("filter:v:0", video_filter_script)
lib.log(
"使用 video filter script "
f"(表达式长度 {video_filter.encode('utf-8').__len__()} bytes)"
)
else:
cmd += ["-vf", video_filter]
cmd += ["-c:v", "libx264", "-preset", preset, "-crf", crf, "-pix_fmt", "yuv420p"]
notes = (
(["遮挡原字幕"] if mask_filter else [])
+ [f"精装包装({studio_plan['preset']})"]
+ ([f"包装图层×{len(packaging_layers)}"] if packaging_layers else [])
+ (["压制解说字幕"] if burn_subtitles else [])
+ ([f"缩放≤{max_h}p"] if max_h > 0 else [])
)
lib.log(f"视频重编码: {' + '.join(notes)} (crf={crf}, preset={preset})")
elif vf_chain or packaging_layers:
if max_h <= 0: # no downscale in the chain to force even dims
vf_chain.append(even)
vf_chain.append(media._color_tag_filter(color_tags))
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 += lib.filter_file_args("filter:v:0", video_filter_script)
lib.log(
"使用 video filter script "
f"(表达式长度 {len(video_filter.encode('utf-8'))} bytes)"
)
else:
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 [])
+ (["压制解说字幕"] if burn_subtitles else [])
+ ([f"缩放≤{max_h}p"] if max_h > 0 else []))
lib.log(f"视频重编码: {' + '.join(notes)} (crf={crf}, preset={preset})")
elif reencode:
notes = (
["force_video_reencode"] if lib.CONFIG["force_video_reencode"]
else ["normalize_source_format"]
)
cmd += ["-vf", f"{even},{media._color_tag_filter(color_tags)}",
"-c:v", "libx264", "-preset", preset, "-crf", crf, "-pix_fmt", "yuv420p"]
if not lib.CONFIG["force_video_reencode"]:
lib.log(
"视频重编码: 源画面不是 H.264 yuv420p "
f"(codec={source_format.get('codec_name')}, pix_fmt={source_format.get('pix_fmt')})"
)
else:
cmd += ["-c:v", "copy"]
# Container (and, on a re-encode, bitstream) colour tags; see media._output_color_tags.
cmd += media._color_tag_args(color_tags)
# Never inherit the source's container/stream tags (a scraper's title, comment or URL)
# or its chapters, whose times no longer match an edit; every audio path muxes here.
cmd += ["-map_metadata", "-1", "-map_chapters", "-1"]
# +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)]
try:
result = lib.run_cmd(cmd)
if result.returncode != 0:
raise RuntimeError(f"视频组装失败: {result.stderr}")
finally:
# 清理临时 filter 脚本(无论 ffmpeg 是否成功)
if fc_script is not None:
fc_script.unlink(missing_ok=True)
if video_filter_script is not None:
video_filter_script.unlink(missing_ok=True)
loudness_stderr = result.stderr
delivered_peak = None
if lib.CONFIG["final_loudnorm"]:
def reencode_audio(target):
measured, limiter = plan_loudness(target, loudnorm_measurement)
graph = (f"{mix_graph};[aout]"
f"{loudness.final_loudnorm_filter(measured, limiter, target)}[aoutln]")
stderr = codec_peak.reencode_audio_track(
output_path, ["-i", str(input_video), *audio_input_args, *bgm_input],
graph, audio_map, video_duration, work_dir,
)
return stderr, measured, limiter
delivered_peak, corrected = codec_peak.deliver_under_true_peak(
output_path, peak_target, reencode_audio
)
if corrected is not None:
loudness_stderr, loudnorm_measurement, peak_limiter = corrected
peak_target = delivered_peak["peak_target_dbtp"]
audio_operations = {
"narration": audio_mode == "narration",
"source_mix": audio_mode == "source-mix",
"bgm_mix": has_bgm,
"ducking": audio_mode == "narration",
"loudness_normalization": lib.CONFIG["final_loudnorm"],
"limiter": True,
"resample": True,
"tempo": audio_mode == "narration",
}
render_delivery = {
"video_encode_passes": 1 if reencode else 0,
"reencode_reason": notes,
"audio_sample_rate": 48000,
"color_tags": color_tags,
"final_compat_notes": (
(["yuv420p"] if reencode else ["video_copy"]) + ["aac_48000", "faststart"]
),
}
loudnorm_final = None
if lib.CONFIG["final_loudnorm"]:
loudnorm_final = loudness.loudnorm_final_pass(
loudness_stderr, loudnorm_measurement, peak_limiter, peak_target
)
loudnorm_final["delivered"] = delivered_peak
if loudnorm_measurement and loudnorm_final["normalization_type"] == "dynamic":
lib.log(" ⚠️ loudnorm 第二遍退回动态模式(测得的响度范围或峰值超出线性条件)")
loudness_mode = loudness._loudness_mode(
loudnorm_measurement, (loudnorm_final or {}).get("normalization_type"), peak_limiter,
)
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,
loudness_mode=loudness_mode,
loudnorm_measurement=loudnorm_measurement,
loudnorm_final_pass=loudnorm_final,
visual_qc=visual_qc,
audio_mode=audio_mode,
audio_operations=audio_operations,
render_delivery=render_delivery,
))
lib.log(f"最终视频: {output_path} ({output_path.stat().st_size / 1024 / 1024:.1f}MB)")
return output_path
class AssemblyBlockedBeforeRender(RuntimeError):
"""Narration can never pass assembly QC; raised before the video encode."""
def _block_before_render(tts_segments, video_duration, work_dir, output_path, audio_mode):
"""Fail before the video encode when the narration track can already never pass QC.
The segment-level codes (no_safe_fit, skipped_segments, unsafe_source_handoff, ...) are
final once narration is placed; `main` would block the same codes after a full render.
"""
qc = assembly_contract._build_assembly_qc(
tts_segments, video_duration, audio_operations={},
render_delivery={
"video_encode_passes": 0, "reencode_reason": ["blocked_before_render"],
"audio_sample_rate": None, "final_compat_notes": [],
},
audio_mode=audio_mode,
)
if not qc["blocking"]:
return
# Never leave an earlier render or its timeline beside a FAIL for these placements.
Path(output_path).unlink(missing_ok=True)
(Path(work_dir) / "timeline.json").unlink(missing_ok=True)
assembly_contract._write_assembly_qc(work_dir, qc)
summary = qc["summary"]
blocked = sorted(set(
summary["no_safe_fit_segments"] + summary["skipped_segments"]
+ summary["tempo_exceeded_segments"] + summary["truncated_segments"]
+ summary["unsafe_source_handoff_segments"]
+ summary["timeline_audio_mismatch_segments"]
))
needed = {
seg["index"]: seg["needed_tempo_factor"]
for seg in tts_segments if seg.get("needed_tempo_factor") is not None
}
detail = ", ".join(
f"段 {index + 1}"
+ (f" needed_tempo_factor={needed[index]:.2f}" if index in needed else "")
for index in blocked
)
raise AssemblyBlockedBeforeRender(
f"组装 QC 在渲染前阻断: {', '.join(qc['blocking_codes'])}"
+ (f"({detail})" if detail else "")
+ f";详见 {Path(work_dir) / constants.ASSEMBLY_QC}"
)
def main():
ap = argparse.ArgumentParser(
description="assemble.py: mux narration audio over the video, duck the original, render subtitles.")
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(
"--audio-mode", choices=AUDIO_MODES,
default="narration", help="audio path (default: narration)",
)
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,
help="burn narration subtitles into the video (default on; without libass the default "
"delivers a .srt sidecar instead, while an explicit --burn-subtitles fails; "
"--no-burn-subtitles to disable)")
ap.add_argument("--subtitle-y-top", type=int, default=None,
help="inclusive top of a measured subtitle band in display-frame pixels")
ap.add_argument("--subtitle-y-bot", type=int, default=None,
help="exclusive bottom of a measured subtitle band in display-frame pixels")
ap.add_argument("--source-video", default=None,
help="original source video (cut mode) so timeline.json / 剪映 export reference the real clips")
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)")
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:
lib.CONFIG["burn_subtitles"] = args.burn_subtitles
lib.CONFIG["burn_subtitles_explicit"] = True
if (args.subtitle_y_top is None) != (args.subtitle_y_bot is None):
ap.error("--subtitle-y-top and --subtitle-y-bot must be provided together")
if args.subtitle_y_top is not None:
if args.subtitle_y_top < 0 or args.subtitle_y_bot <= args.subtitle_y_top:
ap.error("subtitle Y coordinates must satisfy 0 <= top < bot")
lib.CONFIG["subtitle_y_top"] = args.subtitle_y_top
lib.CONFIG["subtitle_y_bot"] = args.subtitle_y_bot
lib.CONFIG["mask_source_subtitles"] = True
# A measured band is an explicit request to conceal the known source-caption
# pixels. The general 0.6 translucent look can leave white glyphs visible under
# the generated subtitles; use an opaque mask unless the caller deliberately
# chose a different opacity through the existing environment override.
if "SUBTITLE_MASK_OPACITY" not in os.environ:
lib.CONFIG["subtitle_mask_opacity"] = 1.0
if args.source_video and not os.path.exists(args.source_video):
ap.error(f"--source-video does not exist: {args.source_video}")
lib.CONFIG["source_video"] = args.source_video or ""
if args.export_jianying:
lib.CONFIG["export_jianying"] = True
if args.jianying_bundle_media is not None:
lib.CONFIG["jianying_bundle_media"] = args.jianying_bundle_media
# Before the render: auto-prefer healthy Homebrew ffmpeg-full on macOS, then fail explicit
# burn without libass or degrade the default to the .srt sidecar.
lib.prefer_homebrew_ffmpeg_full()
render_preflight._preflight_burn_subtitles()
# 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
final_output = assembly_contract._resolve_final_output(base, stem)
sidecar = None
output_path = work_dir / "output.mp4"
try:
try:
assemble_video(
args.video, tts_segments, work_dir, output_path,
audio_mode=args.audio_mode,
tts_meta_path=tts_meta,
)
except AssemblyBlockedBeforeRender as exc:
raise SystemExit(str(exc)) from None
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)
shutil.copy2(str(output_path), str(final_output))
_export_cover_image(final_output, work_dir)
sidecar = _publish_subtitle_sidecar(work_dir, 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_payload=assembly_settings.assembly_settings_payload,
audio_mode=args.audio_mode,
)
visual_qc = artifacts._load_work_json(work_dir, constants.VISUAL_QC) or {}
warnings = visual_qc.get("warnings", [])
manifest["subtitle_sidecar"] = str(sidecar) if sidecar else None
manifest["warnings"] = warnings
assembly_contract._write_assembly_manifest(work_dir, manifest)
except BaseException:
if sidecar is not None:
sidecar.unlink(missing_ok=True)
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)
sidecar_note = f"(外挂字幕: {sidecar})" if sidecar else ""
for warning in warnings:
lib.log(f"⚠️ {warning['code']}: {warning['message']}{sidecar_note}")
print(json.dumps({"status": "assembled", "output": str(final_output), "work_dir": str(work_dir),
"subtitle_sidecar": str(sidecar) if sidecar else None,
"warnings": [warning["code"] for warning in warnings]},
ensure_ascii=False))
def _export_cover_image(final_output: Path, work_dir: Path | None = None) -> Path | None:
"""Extract a crisp cover frame (work_dir/cover.jpg) capturing the opening hook header & card."""
if work_dir is None or not final_output.is_file() or not shutil.which("ffmpeg"):
return None
try:
dur = lib.get_video_duration(final_output)
except Exception:
dur = 3.0
seek_s = min(max(0.0, dur * 0.06), max(0.0, dur - 0.1))
promo_path = Path(work_dir) / "promo_copy.json"
if promo_path.is_file():
promo = lib.read_json_object(promo_path) or {}
cover = promo.get("cover")
if isinstance(cover, dict):
for key in ("frame_s", "timestamp"):
raw_t = cover.get(key)
if isinstance(raw_t, (int, float)) and not isinstance(raw_t, bool):
t = float(raw_t)
if math.isfinite(t) and 0.0 <= t < dur:
seek_s = round(t, 3)
break
cover_path = Path(work_dir) / "cover.jpg"
try:
res = subprocess.run(
[
"ffmpeg", "-y", "-ss", f"{seek_s:.3f}", "-i", str(final_output),
"-frames:v", "1", "-q:v", "2", str(cover_path),
],
capture_output=True,
check=False,
)
except OSError:
return None
if res.returncode == 0 and cover_path.is_file() and cover_path.stat().st_size > 0:
lib.log(f"封面图: {cover_path}")
return cover_path
return None
def _publish_subtitle_sidecar(work_dir, final_output):
"""Ship subtitles.srt next to the recap when the subtitles are not burned in.
The pair shares the stable recap_<stem> alias, so a burned run removes a sidecar left by
an earlier unburned run instead of letting players stack it over the burned text. A run
with no subtitle cues (e.g. source-mix without user subtitles) ships no empty sidecar.
"""
sidecar = final_output.with_suffix(".srt")
srt = work_dir / "subtitles.srt"
has_cues = srt.is_file() and bool(srt.read_text(encoding="utf-8").strip())
if lib.CONFIG["burn_subtitles"] or not has_cues:
sidecar.unlink(missing_ok=True)
return None
shutil.copy2(srt, sidecar)
return sidecar
if __name__ == "__main__":
main()
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| slack-gif-creatoranthropics/skillsKnowledge and utilities for creating animated GIFs optimized for Slack. Provides constraints, validation tools, and animation concepts. Use when users request animated GIFs for Slack like "make me a GIF of X doing Y for Slack." | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |
| ponytailDietrichGebert/ponytailLazy senior dev mode for any coding task: the smallest change that fully solves it, and a reply a busy human understands in one read. | Stars: 196k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-debtDietrichGebert/ponytailHarvest every shortcut: comment into one debt ledger, so deferrals get tracked instead of forgotten. One-shot report. | Stars: 196k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-debtDietrichGebert/ponytailList every `shortcut:` comment (and older `ponytail:` ones) as a debt ledger. One-shot report, changes nothing. Use for "ponytail debt", "what did ponytail defer", "list the shortcuts", /ponytail-debt. | Stars: 196k | Updated | Claude CodeCodex | Verified | Install |