盛联国滨苑剪辑师（video-clip-composer）

把多段视频素材按顺序拼接成一条完整成片，本地离线完成，不依赖任何云服务或 API Key。
核心能力：

1. 多段拼接：按给定顺序把 ≥2 段视频连成成片
2. 自动字幕：faster-whisper 本地提取语音 → 硬字幕烧录进画面（同时导出 .srt）
3. 转场特效：叠化/滑动/擦除/缩放/闪黑/硬切等，可选背景音乐 BGM
4. 画面调节：亮度 / 对比度 / 饱和度（可全局统一，也可每段单独覆盖）
5. 输出定制：容器格式（mp4/mov/mkv/webm）与分辨率（2160p/1080p/720p/480p/原分辨率）

底层用 ffmpeg + PIL + faster-whisper，全部通过随包脚本执行，跨平台（Windows/macOS/Linux）。

输入要求

硬输入（缺一不可）
- ≥1 段视频文件（通常 ≥2 段才有拼接意义），已排好顺序
- 输出文件路径

软输入（缺省走默认值）
- 每段之间的转场类型与时长（默认：叠化 0.5s）
- 亮度/对比度/饱和度（默认：0 / 1.0 / 1.0，可全局或每段）
- 是否提取字幕、识别语言（默认：开、中文）、Whisper 模型（默认 small）
- 输出格式（默认 mp4）、分辨率（默认 1080p）、帧率（默认取第一段）、质量 crf（默认 20）

支持的输入格式：mp4 / mov / mkv / webm / avi 等 ffmpeg 可解码的常见格式。

处理流程

第 0 步 · 环境自检

运行 python scripts/bootstrap.py（缺失依赖时自动 pip install imageio-ffmpeg faster-whisper pillow opencc-python-reimplemented）。
imageio-ffmpeg 会自动带上 ffmpeg 二进制，因此通常无需手动安装 ffmpeg。

可提前下载语音识别模型（优先 ModelScope 直连，国内更稳，失败自动回退 HuggingFace）：

python scripts/download_model.py --model small   # tiny / base / small / medium

下载后把打印的本地路径作为 --model 传入，即可跳过运行时联网下载。

第 1 步 · 收集输入并生成配置

与用户确认顺序、转场、调色、字幕、输出规格后，生成 compose_config.json：

{
  "inputs": [
    {"path": "D:/素材/开头.mp4", "brightness": 0.05, "contrast": 1.1, "saturation": 1.2},
    {"path": "D:/素材/正片.mp4"},
    {"path": "D:/素材/结尾.mp4", "brightness": -0.05}
  ],
  "transition": "crossfade",
  "transition_duration": 0.5,
  "global_color": {"brightness": 0.0, "contrast": 1.0, "saturation": 1.0},
  "subtitles": {"enabled": true, "lang": "zh", "model": "small", "simplify": true},
  "output": {"path": "D:/成片/成片.mp4", "format": "mp4", "resolution": "1080p", "fps": 0, "crf": 20},
  "work_dir": "D:/成片/.compose_work"
}

也可用命令行快速模式（适合一次性任务）：

python scripts/compose.py --inputs a.mp4 b.mp4 c.mp4 --output out.mp4 \
    --transition crossfade --transition-duration 0.5 \
    --resolution 1080p --format mp4 --subtitles --lang zh --model small

第 2 步 · 探测片段

compose.py 用 ffprobe（或 ffmpeg -i 回退）读取每段的分辨率、帧率、时长、是否有音轨，并在执行前打印，供核对顺序是否正确。

第 3 步 · 字幕提取（可选）

启用字幕时，compose.py 调用 transcribe.py 对每段原始音频跑 faster-whisper（首次会下载模型），得到每段局部时间轴字幕，再映射到成片时间轴。

• 识别后自动做：opencc 繁转简 → 术语纠错（内置 references/terms.json 房产词表，可用 subtitles.terms_file 替换）→ 空白清理
• 中国网络首次下载模型较慢，可先设置 HF_ENDPOINT=https://hf-mirror.com
• 若已有现成字幕，跳过识别：配置 subtitles.segments_file 指向一个成片时间轴的 segments.json

第 4 步 · 片段规范化

每段依次应用：eq 调色（亮度/对比度/饱和度）→ scale+pad 统一到目标分辨率（不等比例则上下加黑边保持完整画面）→ 统一帧率 → yuv420p；音频统一转 AAC 48kHz 立体声，并用 loudnorm 统一响度（可配 audio.loudnorm=false 关闭）；无音轨的片段自动补静音轨。

第 5 步 · 转场拼接

• none：concat demuxer -c copy 无损硬切
• fadeblack（闪黑）：每段边界 fade 淡入/淡出接黑 + concat
• crossfade（叠化，默认）及更多 xfade 转场：xfade（视频）+ acrossfade（音频）链式，支持 slideleft / slideright / wipeleft / wiperight / zoom / circleopen / dissolve 等
• 背景音乐 BGM（可选）：bgm（音乐路径）+ bgm_volume 混入成片原声，BGM 循环到成片时长、头尾淡入淡出

第 6 步 · 硬字幕烧录（可选）

render_subs.py 用 PIL 把每条字幕渲染成全画布透明 PNG（中文字体自动探测，加载失败即报错不降级），compose.py 用 overlay ... enable='gte(t,S)*lt(t,E)' 烧入成片。字幕默认底部居中、白字黑描边；可用 subtitles.style 自定义字号、颜色、描边、位置（top/middle/bottom）、字体等。

第 7 步 · 编码输出与校验

按指定格式/分辨率/crf 编码输出，mp4/mov 加 +faststart；校验输出分辨率、时长、可播放性；打印成片规格，并交付 .srt 外挂字幕（若启用字幕）。

• 可选 output.bitrate 设码率上限（覆盖 crf）；可选 output.cover 生成封面缩略图；可选 output.logo 叠加水印（四角定位、宽度占比可调）。

建议先用 --tlimit 30 出 30 秒小样，确认转场/字幕/调色无误后再跑全长。

可配置参数

详见 references/parameters.md。速览：

输出成片规格

• 容器：mp4（默认）/ mov / mkv / webm
• 视频：H.264（libx264，yuv420p，CRF 默认 20；webm 用 VP9）
• 音频：AAC 48kHz 立体声（webm 用 Opus）
• 分辨率：默认 1920×1080（1080p），支持 720p / 4K / 原分辨率；竖屏视频用 original 或 1080x1920 等竖屏档（9:16）
• 字幕：硬字幕已烧入像素（若启用），同时导出同名 .srt

故障排查

• 找不到 ffmpeg → 运行 scripts/bootstrap.py 安装 imageio-ffmpeg
• 字幕中文变方块 → 用 --font 指定本机中文字体路径（见 render_subs.py）
• 模型下载慢/失败 → 运行 python scripts/download_model.py --model base 预下载（优先 ModelScope 直连）；或设置 HF_ENDPOINT=https://hf-mirror.com
• 转场/字幕不对 → 先 --tlimit 30 出小样，用 ffprobe 核对各段时长与顺序
• 不同分辨率素材拼接错位 → 本 skill 已自动 scale+pad 统一，黑边属正常保留完整画面的行为