vcshort 0.2.0__py3-none-any.whl

vcshort/__init__.py

@@ -0,0 +1,3 @@
+"""vcshort — AI 短视频制作 CLI。"""
+
+__version__ = "0.1.0"

vcshort/__main__.py

@@ -0,0 +1,6 @@
+import sys
+
+from vcshort.cli import main
+
+if __name__ == "__main__":
+    sys.exit(main())

vcshort/apply_flashback_fog.py

@@ -0,0 +1,136 @@
+#!/usr/bin/env python3
+"""回忆/闪回视频后处理：给画面边缘叠加一圈白色雾气。"""
+
+import subprocess
+import sys
+import tempfile
+from pathlib import Path
+
+try:
+    import cv2
+    import numpy as np
+except ImportError:
+    cv2 = None
+    np = None
+
+
+def _has_ffmpeg() -> bool:
+    try:
+        subprocess.run(["ffmpeg", "-version"], stdout=subprocess.DEVNULL, stderr=subprocess.DEVNULL, check=True)
+        return True
+    except Exception:
+        return False
+
+
+def apply_flashback_fog(
+    video_path: str | Path,
+    output_path: str | Path | None = None,
+    inner: float = 0.55,
+    outer: float = 1.0,
+    max_alpha: float = 0.75,
+    gamma: float = 2.0,
+) -> Path:
+    """给视频叠加边缘白雾，返回输出视频路径。
+
+    参数（已按 004_01 效果固定）：
+      - inner: 中心清晰区半径比例（0~1），默认 0.55
+      - outer: 雾完全覆盖区半径比例，默认 1.0
+      - max_alpha: 边缘最大雾浓度，默认 0.75
+      - gamma: 雾浓度曲线幂次，默认 2.0（越靠边越浓）
+    """
+    if cv2 is None or np is None:
+        print("错误：回忆雾效需要 opencv-python 和 numpy，请安装：pip install opencv-python numpy", file=sys.stderr)
+        sys.exit(1)
+    if not _has_ffmpeg():
+        print("错误：回忆雾效需要 ffmpeg", file=sys.stderr)
+        sys.exit(1)
+
+    video_path = Path(video_path)
+    if output_path is None:
+        output_path = video_path
+    else:
+        output_path = Path(output_path)
+
+    # 临时文件
+    tmp_dir = Path(tempfile.gettempdir())
+    video_no_audio = tmp_dir / f"{video_path.stem}_fog_no_audio.mp4"
+    audio_path = tmp_dir / f"{video_path.stem}_audio.aac"
+
+    try:
+        # 提取音频
+        subprocess.run(
+            ["ffmpeg", "-y", "-i", str(video_path), "-vn", "-c:a", "copy", str(audio_path)],
+            check=True, stdout=subprocess.DEVNULL, stderr=subprocess.PIPE,
+        )
+
+        # 读取视频
+        cap = cv2.VideoCapture(str(video_path))
+        if not cap.isOpened():
+            print(f"错误：无法打开视频 {video_path}", file=sys.stderr)
+            sys.exit(1)
+
+        fps = cap.get(cv2.CAP_PROP_FPS)
+        w = int(cap.get(cv2.CAP_PROP_FRAME_WIDTH))
+        h = int(cap.get(cv2.CAP_PROP_FRAME_HEIGHT))
+        fourcc = cv2.VideoWriter_fourcc(*"mp4v")
+        out = cv2.VideoWriter(str(video_no_audio), fourcc, fps, (w, h))
+
+        # 径向雾遮罩：中心清晰，边缘白色
+        x = np.linspace(-1, 1, w)
+        y = np.linspace(-1, 1, h)
+        xx, yy = np.meshgrid(x, y)
+        dist = np.sqrt(xx**2 + yy**2)
+        alpha = np.clip((dist - inner) / (outer - inner), 0, 1)
+        alpha = (alpha ** gamma) * max_alpha
+        alpha = alpha[:, :, np.newaxis].astype(np.float32)
+
+        frame_count = 0
+        while True:
+            ret, frame = cap.read()
+            if not ret:
+                break
+            frame_f = frame.astype(np.float32)
+            fogged = frame_f * (1 - alpha) + 255.0 * alpha
+            fogged = np.clip(fogged, 0, 255).astype(np.uint8)
+            out.write(fogged)
+            frame_count += 1
+
+        cap.release()
+        out.release()
+        print(f"回忆雾效处理 {frame_count} 帧")
+
+        # 合并音频
+        subprocess.run(
+            [
+                "ffmpeg", "-y",
+                "-i", str(video_no_audio),
+                "-i", str(audio_path),
+                "-c:v", "libx264", "-c:a", "copy",
+                "-pix_fmt", "yuv420p",
+                "-shortest",
+                str(output_path),
+            ],
+            check=True, stdout=subprocess.DEVNULL, stderr=subprocess.PIPE,
+        )
+        print(f"已保存回忆雾效视频: {output_path}")
+    finally:
+        # 清理临时文件
+        if video_no_audio.exists():
+            video_no_audio.unlink()
+        if audio_path.exists():
+            audio_path.unlink()
+
+    return output_path
+
+
+def main(argv=None) -> int:
+    parser = argparse.ArgumentParser(prog="apply_flashback_fog", description="给视频叠加回忆白雾")
+    parser.add_argument("video", help="输入视频路径")
+    parser.add_argument("-o", "--output", default=None, help="输出路径（默认覆盖输入）")
+    args = parser.parse_args(argv)
+    apply_flashback_fog(args.video, args.output)
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

vcshort/cli.py

@@ -0,0 +1,253 @@
+#!/usr/bin/env python3
+"""vcshort CLI 主入口 — AI 短视频制作命令行工具。
+
+用法：
+    vcshort <command> [args...]
+
+子命令：
+    init              初始化项目
+    config-list       列出已有资产
+    extract           提取资产并匹配
+    gen-image         生成图片资产
+    gen-voice         生成角色音色
+    fix-image         修改图片资产
+    reshape-image     身材重塑（瘦胖/高矮/腿比/头比，纯几何变形）
+    gen-shots         拆分分镜
+    gen-keyframe      生成分镜首帧图
+    gen-video         生成分镜视频
+    compose-chapter   合成章节视频
+"""
+
+import argparse
+import sys
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="vcshort",
+        description="AI 短视频制作 CLI",
+    )
+    sub = parser.add_subparsers(dest="command", required=True)
+
+    # init <项目名>
+    p_init = sub.add_parser("init", help="初始化项目")
+    p_init.add_argument("name", help="项目名")
+
+    # config-list <项目路径> list
+    p_cfg = sub.add_parser("config-list", help="列出已有资产")
+    p_cfg.add_argument("project", help="项目路径")
+    p_cfg.add_argument("subcommand", nargs="?", default="list", help="子命令（默认 list）")
+
+    # extract <项目路径> --chapter <章节号> [--confirm]
+    p_extract = sub.add_parser("extract", help="提取资产并匹配")
+    p_extract.add_argument("project", help="项目路径")
+    p_extract.add_argument("--chapter", required=True, help="章节号（如 ch01）")
+    p_extract.add_argument("--confirm", action="store_true", help="用户确认后生成 map 文件")
+
+    # gen-image <项目路径> --type --name --prompt [--form] [--size] [--model] [--force] [--gender] [--no-voice]
+    p_gen_img = sub.add_parser("gen-image", help="生成图片资产")
+    p_gen_img.add_argument("project", help="项目路径")
+    p_gen_img.add_argument("--type", required=True, choices=["character", "costume", "prop", "scene", "face", "extra"], help="资产类型")
+    p_gen_img.add_argument("--name", required=True, help="资产名称")
+    p_gen_img.add_argument("--prompt", default=None, help="生成提示词（角色类型可省略，读 character.yaml）")
+    p_gen_img.add_argument("--size", default="2K", help="图片尺寸 (2K/3K/4K)")
+    p_gen_img.add_argument("--model", default=None, help="模型 ID（默认读 config.yaml）")
+    p_gen_img.add_argument("--force", action="store_true", help="覆盖同名资产")
+    p_gen_img.add_argument("--form", default=None, help="角色形态名（仅 type=character）")
+    p_gen_img.add_argument("--gender", default=None, choices=["male", "female"], help="角色性别（仅 type=character，生成图片后自动生成音色）")
+    p_gen_img.add_argument("--no-voice", action="store_true", help="不自动生成音色（仅 type=character）")
+    p_gen_img.add_argument("--ref-image", default=None, help="参考图路径（仅参考风格，形象按提示词走；多张用逗号分隔）")
+    p_gen_img.add_argument("--designs", action="store_true", help="服装选型图：8款同风格不同设计（仅 type=costume）")
+    p_gen_img.add_argument("--age", default=None, help="年龄段（仅 type=face/extra）")
+    p_gen_img.add_argument("--hair", default=None, help="发型整体偏向（仅 type=face/extra，八格各异）")
+    p_gen_img.add_argument("--cells", type=int, default=8, choices=[4, 8], help="格图格数（仅 type=face/extra，默认8，4为四格横排）")
+    p_gen_img.add_argument("--face-image", default=None, help="面部参考图（仅 type=character，与 --costume-image 同用）")
+    p_gen_img.add_argument("--costume-image", default=None, help="服装参考图（仅 type=character，与 --face-image 同用）")
+
+    # gen-voice <项目路径> --name --gender [--voice] [--instruction] [--emotion] [--emotion-scale] [--force]
+    p_gen_voice = sub.add_parser("gen-voice", help="生成角色音色")
+    p_gen_voice.add_argument("project", help="项目路径")
+    p_gen_voice.add_argument("--name", required=True, help="角色名")
+    p_gen_voice.add_argument("--gender", required=True, choices=["male", "female"], help="角色性别")
+    p_gen_voice.add_argument("--voice", help="指定音色 ID（如 zh_male_qingcang_uranus_bigtts），不指定则随机选")
+    p_gen_voice.add_argument("--instruction", help="自然语言情感指令，控制语气语调（如 \"用凶狠霸道的语气说\"）")
+    p_gen_voice.add_argument("--emotion", help="情感标签（如 angry/happy/sad），写入 audio_params.emotion")
+    p_gen_voice.add_argument("--emotion-scale", type=int, choices=range(1, 6), help="情感强度 1-5，需配合 --emotion 使用")
+    p_gen_voice.add_argument("--force", action="store_true", help="覆盖已有音色，换一个新音色")
+
+    # fix-image <项目路径> --name --prompt
+    p_fix_img = sub.add_parser("fix-image", help="修改图片资产")
+    p_fix_img.add_argument("project", help="项目路径")
+    p_fix_img.add_argument("--name", required=True, help="资产名称（角色名、角色名:形态名、场景名等）")
+    p_fix_img.add_argument("--prompt", required=True, help="修改提示词")
+
+    # reshape-image <项目路径> --name [--regions --width --waist --height --legs --head --inplace]
+    p_resh = sub.add_parser("reshape-image", help="身材重塑（瘦胖/高矮/腿比/头比，纯几何变形）")
+    p_resh.add_argument("project", help="项目路径")
+    p_resh.add_argument("--name", required=True, help="资产名称（角色名、角色名:形态名等）")
+    p_resh.add_argument("--regions", required=True, help="各视图语义坐标 JSON（必填，agent 看图标注）")
+    p_resh.add_argument("--width", type=float, default=1.0, help="整体宽窄：<1 瘦 / >1 胖")
+    p_resh.add_argument("--waist", type=float, default=1.0, help="腰部宽窄：<1 收腰 / >1 腰粗")
+    p_resh.add_argument("--height", type=float, default=1.0, help="身高：>1 变高 / <1 变矮")
+    p_resh.add_argument("--legs", type=float, default=1.0, help="腿长占比：>1 变长 / <1 变短")
+    p_resh.add_argument("--head", type=float, default=1.0, help="头部大小：<1 头小 / >1 头大")
+    p_resh.add_argument("--stretch", type=float, default=1.0, help="全身横向均匀缩放（含头部）：>1 拉宽")
+    p_resh.add_argument("--inplace", action="store_true", help="覆盖原图（默认输出 -reshape.png 预览）")
+
+    # gen-shots <项目路径> --chapter [--force]
+    p_gen_shots = sub.add_parser("gen-shots", help="拆分分镜")
+    p_gen_shots.add_argument("project", help="项目路径")
+    p_gen_shots.add_argument("--chapter", required=True, help="章节号（如 ch01）")
+    p_gen_shots.add_argument("--force", action="store_true", help="覆盖已有分镜文件")
+
+    # gen-keyframe <项目路径> --chapter --shot [--force]
+    p_gen_keyframe = sub.add_parser("gen-keyframe", help="生成分镜首帧图")
+    p_gen_keyframe.add_argument("project", help="项目路径")
+    p_gen_keyframe.add_argument("--chapter", required=True, help="章节号（如 ch01）")
+    p_gen_keyframe.add_argument("--shot", required=True, help="分镜号（如 001_01 或 001）")
+    p_gen_keyframe.add_argument("--anchor", default=None, help="首帧锚点：尾帧/首帧/第一帧/完整标记/none")
+    p_gen_keyframe.add_argument("--force", action="store_true", help="覆盖已有 keyframe.png")
+
+    # gen-video <项目路径> --chapter --shot
+    p_gen_video = sub.add_parser("gen-video", help="生成分镜视频")
+    p_gen_video.add_argument("project", help="项目路径")
+    p_gen_video.add_argument("--chapter", required=True, help="章节号（如 ch01）")
+    p_gen_video.add_argument("--shot", required=True, help="分镜号（如 001）")
+
+    # compose-chapter <项目路径> --chapter [--output]
+    p_compose = sub.add_parser("compose-chapter", help="合成章节视频")
+    p_compose.add_argument("project", help="项目路径")
+    p_compose.add_argument("--chapter", required=True, help="章节号（如 ch01）")
+    p_compose.add_argument("--output", default=None, help="输出文件名（默认 chapter.mp4）")
+    p_compose.add_argument("--shots-dir", default="shots", help="分镜目录名（默认 shots）")
+
+    return parser
+
+
+def main(argv=None) -> int:
+    # Windows 控制台默认 cp1252 编码，打印中文会崩，强制 UTF-8
+    if sys.platform == "win32":
+        sys.stdout.reconfigure(encoding="utf-8")
+        sys.stderr.reconfigure(encoding="utf-8")
+
+    parser = build_parser()
+    args = parser.parse_args(argv)
+    cmd = args.command
+
+    if cmd == "init":
+        from . import init as init_mod
+        return init_mod.main([args.name])
+
+    if cmd == "config-list":
+        from . import config_manager
+        sub_argv = [args.project, args.subcommand]
+        return config_manager.main(sub_argv)
+
+    if cmd == "extract":
+        from . import extract as extract_mod
+        sub_argv = [args.project, "--chapter", args.chapter]
+        if args.confirm:
+            sub_argv.append("--confirm")
+        return extract_mod.main(sub_argv)
+
+    if cmd == "gen-image":
+        from . import gen_image
+        sub_argv = [args.project, "--type", args.type, "--name", args.name]
+        if args.prompt:
+            sub_argv += ["--prompt", args.prompt]
+        if args.size:
+            sub_argv += ["--size", args.size]
+        if args.model:
+            sub_argv += ["--model", args.model]
+        if args.force:
+            sub_argv.append("--force")
+        if args.form:
+            sub_argv += ["--form", args.form]
+        if args.gender:
+            sub_argv += ["--gender", args.gender]
+        if args.no_voice:
+            sub_argv.append("--no-voice")
+        if args.ref_image:
+            sub_argv += ["--ref-image", args.ref_image]
+        if args.designs:
+            sub_argv.append("--designs")
+        if args.age:
+            sub_argv += ["--age", args.age]
+        if args.hair:
+            sub_argv += ["--hair", args.hair]
+        if args.cells and args.cells != 8:
+            sub_argv += ["--cells", str(args.cells)]
+        if args.face_image:
+            sub_argv += ["--face-image", args.face_image]
+        if args.costume_image:
+            sub_argv += ["--costume-image", args.costume_image]
+        return gen_image.main(sub_argv)
+
+    if cmd == "gen-voice":
+        from . import gen_voice
+        sub_argv = [args.project, "--name", args.name, "--gender", args.gender]
+        if args.voice:
+            sub_argv += ["--voice", args.voice]
+        if args.instruction:
+            sub_argv += ["--instruction", args.instruction]
+        if args.emotion:
+            sub_argv += ["--emotion", args.emotion]
+        if args.emotion_scale:
+            sub_argv += ["--emotion-scale", str(args.emotion_scale)]
+        if args.force:
+            sub_argv.append("--force")
+        return gen_voice.main(sub_argv)
+
+    if cmd == "fix-image":
+        from . import fix_image
+        sub_argv = [args.project, "--name", args.name, "--prompt", args.prompt]
+        return fix_image.main(sub_argv)
+
+    if cmd == "reshape-image":
+        from . import reshape_image
+        sub_argv = [args.project, "--name", args.name,
+                    "--width", str(args.width), "--waist", str(args.waist),
+                    "--height", str(args.height), "--legs", str(args.legs),
+                    "--head", str(args.head), "--stretch", str(args.stretch)]
+        if args.regions:
+            sub_argv += ["--regions", args.regions]
+        if args.inplace:
+            sub_argv.append("--inplace")
+        return reshape_image.main(sub_argv)
+
+    if cmd == "gen-shots":
+        from . import gen_shots
+        sub_argv = [args.project, "--chapter", args.chapter]
+        if args.force:
+            sub_argv.append("--force")
+        return gen_shots.main(sub_argv)
+
+    if cmd == "gen-keyframe":
+        from . import gen_keyframe
+        sub_argv = [args.project, "--chapter", args.chapter, "--shot", args.shot]
+        if args.anchor:
+            sub_argv += ["--anchor", args.anchor]
+        if args.force:
+            sub_argv.append("--force")
+        return gen_keyframe.main(sub_argv)
+
+    if cmd == "gen-video":
+        from . import gen_video
+        sub_argv = [args.project, "--chapter", args.chapter, "--shot", args.shot]
+        return gen_video.main(sub_argv)
+
+    if cmd == "compose-chapter":
+        from . import compose_chapter
+        sub_argv = [args.project, "--chapter", args.chapter]
+        if args.output:
+            sub_argv += ["--output", args.output]
+        if args.shots_dir:
+            sub_argv += ["--shots-dir", args.shots_dir]
+        return compose_chapter.main(sub_argv)
+
+    parser.print_help()
+    return 1
+
+
+if __name__ == "__main__":
+    sys.exit(main())

vcshort/compose_chapter.py

@@ -0,0 +1,274 @@
+#!/usr/bin/env python3
+"""合成章节视频：将一个章节下所有分镜的 shot.mp4 按顺序拼接成一个完整视频。
+
+用 imageio-ffmpeg 自带的 ffmpeg 二进制拼接，不依赖系统安装 ffmpeg。
+编码为 H.264，兼容所有播放器。
+
+用法：
+    vcshort compose-chapter <项目路径> --chapter <章节号> [--output <文件名>]
+
+输出默认放在 chapters/<章节号>/chapter.mp4
+"""
+import argparse
+import subprocess
+import sys
+import tempfile
+from pathlib import Path
+
+try:
+    import cv2
+except ImportError:
+    print("错误：需要 opencv-python（pip install opencv-python）", file=sys.stderr)
+    sys.exit(1)
+
+try:
+    from imageio_ffmpeg import get_ffmpeg_exe
+    FFMPEG = get_ffmpeg_exe()
+except ImportError:
+    print("错误：需要 imageio-ffmpeg（pip install imageio-ffmpeg）", file=sys.stderr)
+    sys.exit(1)
+
+
+def find_shot_videos(chapter_dir: Path, shots_dir_name: str = "shots") -> list:
+    """按分镜号顺序查找指定分镜目录下的所有 shot.mp4 文件。"""
+    shots_dir = chapter_dir / shots_dir_name
+    if not shots_dir.is_dir():
+        return []
+    videos = []
+    for shot_dir in sorted(shots_dir.iterdir()):
+        if shot_dir.is_dir() and shot_dir.name.startswith("shot_"):
+            video = shot_dir / "shot.mp4"
+            if video.exists():
+                videos.append(video)
+    return videos
+
+
+def get_video_info(video_path: Path) -> dict:
+    """用 opencv 获取视频信息。"""
+    cap = cv2.VideoCapture(str(video_path))
+    fps = cap.get(cv2.CAP_PROP_FPS) or 24.0
+    frames = int(cap.get(cv2.CAP_PROP_FRAME_COUNT))
+    info = {
+        "fps": fps,
+        "width": int(cap.get(cv2.CAP_PROP_FRAME_WIDTH)),
+        "height": int(cap.get(cv2.CAP_PROP_FRAME_HEIGHT)),
+        "frames": frames,
+        "duration": frames / fps if fps else 0.0,
+    }
+    cap.release()
+    return info
+
+
+def has_audio(video_path: Path) -> bool:
+    """检测视频是否包含音频流，供黑屏片段补齐静音音轨。"""
+    result = subprocess.run(
+        [FFMPEG, "-i", str(video_path), "-f", "null", "-"],
+        capture_output=True,
+        text=True,
+    )
+    return "Audio:" in result.stderr
+
+
+def scene_id(video_path: Path) -> str:
+    """从 shot_001_09 目录名提取场景主编号 001。"""
+    name = video_path.parent.name.removeprefix("shot_")
+    return name.split("_", 1)[0]
+
+
+def scene_name(video_path: Path) -> str:
+    """读取分镜 YAML 中的场景名，用作转场提示。"""
+    yaml_path = video_path.parent / "shot.yaml"
+    if yaml_path.exists():
+        for line in yaml_path.read_text(encoding="utf-8").splitlines():
+            if line.startswith("scene:"):
+                return line.split(":", 1)[1].strip().strip("'\\\"")
+    return scene_id(video_path)
+
+
+def find_font() -> str | None:
+    """查找可显示中文的字体；找不到时交给 ffmpeg 默认字体。"""
+    candidates = [
+        "/System/Library/Fonts/Supplemental/Songti.ttc",
+        "/System/Library/Fonts/STHeiti Medium.ttc",
+        "/System/Library/Fonts/Hiragino Sans GB.ttc",
+        "/usr/share/fonts/opentype/noto/NotoSansCJK-Regular.ttc",
+        "/usr/share/fonts/truetype/wqy/wqy-zenhei.ttc",
+    ]
+    return next((path for path in candidates if Path(path).exists()), None)
+
+
+def escape_drawtext(text: str) -> str:
+    """转义 ffmpeg drawtext 的文本内容。"""
+    return text.replace("\\\\", "\\\\\\\\").replace(":", "\\\\:").replace("'", "\\\\'")
+
+
+def run_ffmpeg(command: list) -> None:
+    result = subprocess.run(command, capture_output=True, text=True)
+    if result.returncode != 0:
+        print(f"ffmpeg 错误:\n{result.stderr}", file=sys.stderr)
+        sys.exit(1)
+
+
+def render_clip(
+    video_path: Path,
+    output_path: Path,
+    info: dict,
+    audio: bool,
+    fade_in: float = 0.0,
+    fade_out: float = 0.0,
+    scene_label: str = "",
+) -> None:
+    """为场景边界添加淡入/淡出黑屏效果和场景提示，并统一编码参数。"""
+    filters = []
+    if fade_in > 0:
+        filters.append(f"fade=t=in:st=0:d={fade_in:.3f}:color=black")
+    if fade_out > 0:
+        start = max(0.0, info["duration"] - fade_out)
+        filters.append(f"fade=t=out:st={start:.3f}:d={fade_out:.3f}:color=black")
+    if scene_label:
+        label_start = 0.0
+        label_fade = 0.4
+        label_hold_end = label_fade + 1.0
+        label_end = label_hold_end + label_fade
+        alpha = (
+            f"if(lt(t\\,{label_fade})\\,t/{label_fade}\\,"
+            f"if(lt(t\\,{label_hold_end})\\,1\\,"
+            f"if(lt(t\\,{label_end})\\,({label_end}-t)/{label_fade}\\,0)))"
+        )
+        font = find_font()
+        font_option = f":fontfile='{font}'" if font else ""
+        text = escape_drawtext(scene_label)
+        filters.append(
+            f"drawtext=text='{text}'{font_option}:x=40:y=40:fontsize=48:"
+            f"fontcolor=white:borderw=2:bordercolor=black@0.8:shadowx=2:shadowy=2:"
+            f"shadowcolor=black@0.65:alpha='{alpha}'"
+        )
+
+    command = [FFMPEG, "-y", "-i", str(video_path)]
+    clip_has_audio = has_audio(video_path)
+    if audio and not clip_has_audio:
+        # 无声镜头补静音轨，保证 concat 后整片音轨连续
+        command += ["-f", "lavfi", "-i", "anullsrc=channel_layout=stereo:sample_rate=48000"]
+    if filters:
+        command += ["-vf", ",".join(filters)]
+    command += ["-map", "0:v:0", "-c:v", "libx264", "-crf", "18", "-preset", "fast"]
+    if audio:
+        if clip_has_audio:
+            command += ["-map", "0:a:0?"]
+        else:
+            command += ["-map", "1:a:0", "-shortest"]
+        command += ["-c:a", "aac", "-ar", "48000", "-ac", "2"]
+    else:
+        command += ["-an"]
+    command += ["-r", str(info["fps"]), "-pix_fmt", "yuv420p", str(output_path)]
+    run_ffmpeg(command)
+
+
+def render_black(output_path: Path, info: dict, audio: bool, duration: float) -> None:
+    """生成场景之间的短暂黑屏，音频存在时补静音。"""
+    size = f"{info['width']}x{info['height']}"
+    command = [
+        FFMPEG, "-y",
+        "-f", "lavfi", "-i", f"color=c=black:s={size}:r={info['fps']}:d={duration:.3f}",
+    ]
+    if audio:
+        command += [
+            "-f", "lavfi", "-i", "anullsrc=channel_layout=stereo:sample_rate=48000",
+            "-t", f"{duration:.3f}", "-map", "0:v:0", "-map", "1:a:0",
+            "-c:a", "aac", "-ar", "48000", "-ac", "2",
+        ]
+    else:
+        command += ["-map", "0:v:0", "-an"]
+    command += [
+        "-c:v", "libx264", "-crf", "18", "-preset", "fast",
+        "-r", str(info["fps"]), "-pix_fmt", "yuv420p", str(output_path),
+    ]
+    run_ffmpeg(command)
+
+
+def compose(videos: list, output_path: Path) -> None:
+    """拼接视频，并在场景边界淡出黑屏、短暂黑屏后淡入下一场景。"""
+    output_path.parent.mkdir(parents=True, exist_ok=True)
+    fade_duration = 0.25
+    black_duration = 0.0
+    info = get_video_info(videos[0])
+    audio = any(has_audio(v) for v in videos)
+
+    with tempfile.TemporaryDirectory(prefix="compose_") as temp_dir:
+        temp_dir = Path(temp_dir)
+        rendered = []
+        for index, video in enumerate(videos):
+            previous_scene = scene_id(videos[index - 1]) if index else None
+            next_scene = scene_id(videos[index + 1]) if index + 1 < len(videos) else None
+            current_scene = scene_id(video)
+            is_scene_start = index > 0 and current_scene != previous_scene
+            is_scene_end = index + 1 < len(videos) and current_scene != next_scene
+            clip_info = get_video_info(video)
+            clip_path = temp_dir / f"clip_{index:04d}.mp4"
+            render_clip(
+                video,
+                clip_path,
+                clip_info,
+                audio,
+                fade_in=min(fade_duration, clip_info["duration"] / 2) if is_scene_start else 0.0,
+                fade_out=min(fade_duration, clip_info["duration"] / 2) if is_scene_end else 0.0,
+                scene_label=scene_name(video) if is_scene_start else "",
+            )
+            rendered.append(clip_path)
+            if is_scene_end and black_duration > 0:
+                black_path = temp_dir / f"black_{index:04d}.mp4"
+                render_black(black_path, info, audio, black_duration)
+                rendered.append(black_path)
+
+        list_file = temp_dir / "concat_list.txt"
+        with list_file.open("w", encoding="utf-8") as file:
+            for clip in rendered:
+                escaped = str(clip).replace("'", "'\\''")
+                file.write(f"file '{escaped}'\n")
+
+        run_ffmpeg([
+            FFMPEG, "-y", "-f", "concat", "-safe", "0", "-i", str(list_file),
+            "-c:v", "libx264", "-crf", "18", "-preset", "fast",
+            "-r", str(info["fps"]), "-pix_fmt", "yuv420p", "-movflags", "+faststart",
+            *(["-c:a", "aac", "-ar", "48000", "-ac", "2"] if audio else ["-an"]),
+            str(output_path),
+        ])
+
+
+def main(argv=None) -> int:
+    parser = argparse.ArgumentParser(prog="vcshort compose-chapter", description="合成章节视频")
+    parser.add_argument("project", help="项目路径")
+    parser.add_argument("--chapter", required=True, help="章节号（如 ch01）")
+    parser.add_argument("--output", default=None, help="输出文件名（默认 chapter.mp4）")
+    parser.add_argument("--shots-dir", default="shots", help="分镜目录名（默认 shots）")
+    args = parser.parse_args(argv)
+
+    project_root = Path(args.project).resolve()
+    if not project_root.exists():
+        print(f"错误：项目路径不存在: {project_root}", file=sys.stderr)
+        return 1
+
+    chapter_dir = project_root / "chapters" / args.chapter
+    if not chapter_dir.is_dir():
+        print(f"错误：章节目录不存在: {chapter_dir}", file=sys.stderr)
+        return 1
+
+    videos = find_shot_videos(chapter_dir, args.shots_dir)
+    if not videos:
+        print(f"错误：{chapter_dir}/{args.shots_dir}/ 下没有找到 shot.mp4 文件", file=sys.stderr)
+        return 1
+
+    print(f"找到 {len(videos)} 个分镜视频:")
+    for v in videos:
+        print(f"  {v}")
+
+    output_name = args.output or "chapter.mp4"
+    output_path = chapter_dir / output_name
+
+    print(f"\n正在合成...")
+    compose(videos, output_path)
+
+    print(f"\n✅ 章节视频合成完成")
+    print(f"   输出: {output_path}")
+    print(f"   分镜数: {len(videos)}")
+    return 0