comicvid 0.1.0__py3-none-any.whl

comicvid/__init__.py

@@ -0,0 +1,3 @@
+"""comicvid — Static images to animated video with Ken Burns + ASS subtitles + audio."""
+
+__version__ = "0.1.0"

comicvid/audio.py

@@ -0,0 +1,69 @@
+"""Audio utilities: re-encode to AAC, probe duration."""
+
+from __future__ import annotations
+
+import subprocess
+from pathlib import Path
+
+
+def reencode_audio(
+    audio_path: Path,
+    output_path: Path,
+    ffmpeg: str = "ffmpeg",
+    sample_rate: int = 44100,
+    bitrate: str = "128k",
+    channels: int = 1,
+) -> bool:
+    """Re-encode any audio to AAC at a consistent format.
+
+    Args:
+        audio_path: Input audio file path.
+        output_path: Output AAC file path.
+        ffmpeg: FFmpeg binary.
+        sample_rate: Output sample rate in Hz.
+        bitrate: Output bitrate (e.g. '128k').
+        channels: Number of audio channels (1=mono).
+
+    Returns:
+        True on success.
+    """
+    cmd = [
+        ffmpeg, "-y",
+        "-i", str(audio_path),
+        "-c:a", "aac",
+        "-ar", str(sample_rate),
+        "-b:a", bitrate,
+        "-ac", str(channels),
+        str(output_path),
+    ]
+    result = subprocess.run(cmd, capture_output=True, text=True)
+    if result.returncode != 0:
+        print(f"  [audio] reencode failed: {result.stderr[-500:]}")
+        return False
+    return True
+
+
+def get_audio_duration(audio_path: Path, ffmpeg: str = "ffmpeg") -> float:
+    """Get audio duration in seconds using ffmpeg/ffprobe.
+
+    Args:
+        audio_path: Path to audio file.
+        ffmpeg: FFmpeg binary path.
+
+    Returns:
+        Duration in seconds, or 5.0 on failure.
+    """
+    result = subprocess.run(
+        [ffmpeg, "-i", str(audio_path), "-hide_banner"],
+        capture_output=True, text=True,
+    )
+    for line in result.stderr.split("\n"):
+        if "Duration" in line:
+            parts = line.strip().split(",")[0]
+            dur_str = parts.split("Duration:")[-1].strip()
+            h, m, s = dur_str.split(":")
+            try:
+                return int(h) * 3600 + int(m) * 60 + float(s)
+            except ValueError:
+                pass
+    return 5.0

comicvid/cli.py

@@ -0,0 +1,241 @@
+"""Click CLI entry point for comicvid."""
+
+from __future__ import annotations
+
+import sys
+from pathlib import Path
+
+import click
+
+from comicvid import __version__
+from comicvid.pipeline import render_video
+from comicvid.types import Config
+
+
+@click.group(invoke_without_command=True)
+@click.version_option(version=__version__, prog_name="comicvid")
+@click.pass_context
+def cli(ctx: click.Context) -> None:
+    """comicvid — Static images to animated video.
+
+    Turn a folder of images into a video with Ken Burns zoom,
+    ASS subtitles, and audio sync. Pure FFmpeg + Python.
+    """
+    if ctx.invoked_subcommand is None:
+        click.echo(ctx.get_help())
+
+
+@cli.command()
+@click.argument("image_dir", type=click.Path(exists=True, file_okay=False, dir_okay=True))
+@click.option("-o", "--output", default="output.mp4", show_default=True,
+              help="Output MP4 path.")
+@click.option("--duration", type=float, default=None,
+              help="Total video duration in seconds. If omitted, "
+                   "uses --per-image-duration per image.")
+@click.option("--per-image-duration", type=float, default=3.0, show_default=True,
+              help="Seconds per image when --duration is not set.")
+@click.option("--subtitle", type=click.Path(exists=True, dir_okay=False),
+              default=None,
+              help="External subtitle file (SRT or ASS).")
+@click.option("--subtitle-format", type=click.Choice(["ass", "srt"]),
+              default="ass", show_default=True,
+              help="Subtitle format.")
+@click.option("--text", "-t", multiple=True,
+              help="Subtitle text per image. Repeat for each image: "
+                   "-t 'line1' -t 'line2'")
+@click.option("--audio", type=click.Path(exists=True, dir_okay=False),
+              default=None, help="Audio file (WAV, MP3, etc.).")
+@click.option("--width", type=int, default=1280, show_default=True,
+              help="Output video width in pixels.")
+@click.option("--height", type=int, default=720, show_default=True,
+              help="Output video height in pixels.")
+@click.option("--resolution", type=str, default=None,
+              help="Shortcut: '1920x1080' sets width and height at once.")
+@click.option("--fps", type=int, default=24, show_default=True,
+              help="Frames per second.")
+@click.option("--crf", type=int, default=23, show_default=True,
+              help="H.264 CRF quality (lower = better).")
+@click.option("--video-bitrate", default="1500k", show_default=True,
+              help="Video bitrate.")
+@click.option("--zoom", type=float, default=0.05, show_default=True,
+              help="Ken Burns zoom amount (0.05 = 5%%).")
+@click.option("--ffmpeg", default="ffmpeg", show_default=True,
+              help="FFmpeg binary path.")
+@click.option("--keep-temps", is_flag=True, default=False,
+              help="Keep temporary files.")
+def render(
+    image_dir: str,
+    output: str,
+    duration: float | None,
+    per_image_duration: float,
+    subtitle: str | None,
+    subtitle_format: str,
+    text: tuple[str, ...],
+    audio: str | None,
+    width: int,
+    height: int,
+    resolution: str | None,
+    fps: int,
+    crf: int,
+    video_bitrate: str,
+    zoom: float,
+    ffmpeg: str,
+    keep_temps: bool,
+) -> None:
+    """Render images from IMAGE_DIR into an MP4 video.
+
+    IMAGE_DIR should contain panel images sorted by filename.
+    Supports PNG, JPG, JPEG, WEBP, BMP.
+    """
+    # Handle --resolution shortcut
+    if resolution:
+        try:
+            w, h = resolution.split("x")
+            width = int(w)
+            height = int(h)
+        except (ValueError, TypeError):
+            click.echo(f"Error: Invalid resolution format '{resolution}'. "
+                       f"Use WxH (e.g. 1920x1080).", err=True)
+            sys.exit(1)
+
+    # Parse subtitle texts
+    subs: list[str] | None = list(text) if text else None
+
+    config = Config(
+        image_dir=Path(image_dir),
+        output=Path(output),
+        duration=duration,
+        per_image_duration=per_image_duration,
+        subtitle=Path(subtitle) if subtitle else None,
+        subtitle_format=subtitle_format,
+        subtitles=subs,
+        audio=Path(audio) if audio else None,
+        width=width,
+        height=height,
+        fps=fps,
+        crf=crf,
+        video_bitrate=video_bitrate,
+        ken_burns_zoom=zoom,
+        ffmpeg=ffmpeg,
+        keep_temps=keep_temps,
+    )
+
+    report = render_video(config)
+    if report is None:
+        sys.exit(1)
+    if report.get("status") != "ok":
+        sys.exit(1)
+
+
+@cli.command()
+@click.argument("parent_dir", type=click.Path(exists=True, file_okay=False, dir_okay=True))
+@click.option("-o", "--output-dir", default="./output", show_default=True,
+              help="Output directory for batch renders.")
+@click.option("--duration", type=float, default=None,
+              help="Total video duration per subfolder.")
+@click.option("--per-image-duration", type=float, default=3.0, show_default=True,
+              help="Seconds per image when --duration is not set.")
+@click.option("--subtitle-format", type=click.Choice(["ass", "srt"]),
+              default="ass", show_default=True)
+@click.option("--audio", type=click.Path(exists=True, dir_okay=False),
+              default=None, help="Optional audio file for all batches.")
+@click.option("--width", type=int, default=1280, show_default=True)
+@click.option("--height", type=int, default=720, show_default=True)
+@click.option("--resolution", type=str, default=None)
+@click.option("--ffmpeg", default="ffmpeg", show_default=True)
+@click.option("--keep-temps", is_flag=True, default=False)
+def batch(
+    parent_dir: str,
+    output_dir: str,
+    duration: float | None,
+    per_image_duration: float,
+    subtitle_format: str,
+    audio: str | None,
+    width: int,
+    height: int,
+    resolution: str | None,
+    ffmpeg: str,
+    keep_temps: bool,
+) -> None:
+    """Batch render: process each subfolder in PARENT_DIR as a separate video.
+
+    Useful for episode directories where each subfolder contains panels.
+    Output files are named after each subfolder.
+    """
+    if resolution:
+        try:
+            w, h = resolution.split("x")
+            width = int(w)
+            height = int(h)
+        except (ValueError, TypeError):
+            click.echo(f"Error: Invalid resolution '{resolution}'.", err=True)
+            sys.exit(1)
+
+    parent = Path(parent_dir)
+    subdirs = sorted(d for d in parent.iterdir() if d.is_dir())
+
+    if not subdirs:
+        click.echo(f"No subdirectories found in {parent_dir}")
+        sys.exit(1)
+
+    out_dir = Path(output_dir)
+    out_dir.mkdir(parents=True, exist_ok=True)
+
+    success = 0
+    failed = 0
+
+    for subdir in subdirs:
+        click.echo(f"\n{'='*60}")
+        click.echo(f"Batch: {subdir.name}")
+        click.echo(f"{'='*60}")
+
+        # Look for audio_* files in the subfolder or parent
+        audio_path = None
+        if audio:
+            audio_path = Path(audio)
+        else:
+            # Auto-discover audio files
+            audio_files = sorted(
+                p for p in subdir.iterdir()
+                if p.suffix.lower() in {".wav", ".mp3", ".m4a", ".aac", ".flac"}
+            )
+            if audio_files:
+                audio_path = audio_files[0]
+
+        # Look for subtitle files
+        sub_files = sorted(
+            p for p in subdir.iterdir()
+            if p.suffix.lower() in {".srt", ".ass"}
+        )
+        sub_path = sub_files[0] if sub_files else None
+
+        config = Config(
+            image_dir=subdir,
+            output=out_dir / f"{subdir.name}.mp4",
+            duration=duration,
+            per_image_duration=per_image_duration,
+            subtitle=sub_path,
+            subtitle_format=subtitle_format,
+            audio=audio_path,
+            width=width,
+            height=height,
+            ffmpeg=ffmpeg,
+            keep_temps=keep_temps,
+        )
+
+        report = render_video(config)
+        if report and report.get("status") == "ok":
+            success += 1
+        else:
+            failed += 1
+
+    click.echo(f"\n{'='*60}")
+    click.echo(f"Batch complete: {success} succeeded, {failed} failed")
+    click.echo(f"{'='*60}")
+
+    if failed > 0:
+        sys.exit(1)
+
+
+if __name__ == "__main__":
+    cli()

comicvid/pipeline.py

@@ -0,0 +1,262 @@
+"""Orchestration: scene building, concatenation, subtitle burn-in, verification."""
+
+from __future__ import annotations
+
+import json
+import shutil
+import subprocess
+from pathlib import Path
+
+from comicvid.types import Config
+from comicvid.render import build_scene_video
+from comicvid.subtitle import write_ass, write_srt
+
+
+def _log(msg: str) -> None:
+    print(f"[comicvid] {msg}", flush=True)
+
+
+def _run_cmd(cmd: list[str], desc: str = "") -> bool:
+    """Run a command, return True on success, print error on failure."""
+    _log(f"→ {desc or 'run'}")
+    result = subprocess.run(cmd, capture_output=True, text=True)
+    if result.returncode != 0:
+        _log(f"  ✗ FAILED:")
+        _log(result.stderr[-2000:] if result.stderr else result.stdout[-2000:])
+        return False
+    tail = [l for l in result.stderr.split("\n") if l.strip()][-3:]
+    for line in tail:
+        _log(f"  {line}")
+    return True
+
+
+def resolve_image_list(image_dir: Path) -> list[Path]:
+    """Get sorted list of images from directory.
+
+    Supports: .png, .jpg, .jpeg, .webp, .bmp
+    """
+    extensions = {".png", ".jpg", ".jpeg", ".webp", ".bmp"}
+    images = sorted(
+        p for p in image_dir.iterdir()
+        if p.suffix.lower() in extensions
+    )
+    return images
+
+
+def render_video(config: Config) -> dict | None:
+    """Render video from images in config.image_dir.
+
+    Pipeline:
+    1. Resolve image list and durations
+    2. Build each scene (Ken Burns + audio)
+    3. Create subtitle file
+    4. Concatenate scenes
+    5. Burn subtitles
+    6. Verify output
+
+    Args:
+        config: Render configuration.
+
+    Returns:
+        Report dict with metadata, or None on failure.
+    """
+    _log("=" * 60)
+    _log("comicvid — Render")
+    _log("=" * 60)
+
+    images = resolve_image_list(config.image_dir)
+    if not images:
+        _log("✗ No images found in " + str(config.image_dir))
+        return None
+
+    _log(f"Found {len(images)} images")
+
+    # ── Determine durations ──
+    if config.duration is not None:
+        # Spread total duration across images
+        per_image = config.duration / len(images)
+        durations = [per_image] * len(images)
+    else:
+        durations = [config.per_image_duration] * len(images)
+
+    # ── Create temp directory ──
+    temp_dir = config.temp_dir
+    scenes_dir = temp_dir / "scenes"
+    temp_dir.mkdir(parents=True, exist_ok=True)
+    scenes_dir.mkdir(exist_ok=True)
+    config.output.parent.mkdir(parents=True, exist_ok=True)
+
+    # ── Phase 1: Build scenes ──
+    _log(f"\n── Phase 1: Build {len(images)} scene(s) ──")
+    clip_paths: list[Path] = []
+    for i, (img_path, dur) in enumerate(zip(images, durations)):
+        clip = scenes_dir / f"scene_{i:04d}.mp4"
+        label = f"img_{i:04d}"
+        _log(f"  Building {label} ({img_path.name}, {dur:.1f}s) ...")
+        if build_scene_video(clip, img_path, config.audio, dur, config, label):
+            clip_paths.append(clip)
+            size_kb = clip.stat().st_size / 1024 if clip.exists() else 0
+            _log(f"  ✓ {label}: {size_kb:.0f} KB")
+        else:
+            _log(f"  ✗ {label}: failed")
+            return None
+
+    # ── Phase 2: Create subtitles ──
+    _log(f"\n── Phase 2: Create Subtitles ──")
+    sub_texts: list[str] = []
+    if config.subtitles:
+        sub_texts = config.subtitles
+    elif config.subtitle and config.subtitle.exists():
+        # Read external subtitle file and convert to per-image mapping
+        sub_texts = _parse_external_subtitle(config.subtitle, len(images))
+    else:
+        sub_texts = [""] * len(images)
+
+    sub_path: Path | None = None
+    if any(t for t in sub_texts[:len(images)]):
+        if config.subtitle_format == "ass":
+            sub_path = temp_dir / "subtitles.ass"
+            write_ass(sub_path, durations, sub_texts[:len(images)],
+                       config.width, config.height)
+        else:
+            sub_path = temp_dir / "subtitles.srt"
+            write_srt(sub_path, durations, sub_texts[:len(images)])
+        _log(f"  {sub_path.name}: {sum(1 for t in sub_texts if t)} entries")
+
+    # ── Phase 3: Concatenate ──
+    _log(f"\n── Phase 3: Concatenate ──")
+    concat_file = temp_dir / "concat.txt"
+    with open(concat_file, "w") as f:
+        for clip in clip_paths:
+            f.write(f"file '{clip.absolute()}'\n")
+
+    concat_temp = temp_dir / "concat_output.mp4"
+    cmd_concat = [
+        config.ffmpeg, "-y",
+        "-f", "concat",
+        "-safe", "0",
+        "-i", str(concat_file),
+        "-c", "copy",
+        str(concat_temp),
+    ]
+    if not _run_cmd(cmd_concat, "Concatenate scenes"):
+        return None
+
+    # ── Phase 4: Burn subtitles ──
+    _log(f"\n── Phase 4: Burn Subtitles ──")
+    if sub_path and sub_path.exists():
+        if config.subtitle_format == "ass":
+            filter_expr = f"ass={sub_path}"
+        else:
+            filter_expr = f"subtitles={sub_path}"
+
+        cmd_sub = [
+            config.ffmpeg, "-y",
+            "-i", str(concat_temp),
+            "-vf", filter_expr,
+            "-c:v", "libx264",
+            "-preset", "medium",
+            "-crf", str(config.crf),
+            "-maxrate", config.video_bitrate,
+            "-bufsize", "3000k",
+            "-pix_fmt", "yuv420p",
+            "-c:a", "copy",
+            str(config.output),
+        ]
+        if not _run_cmd(cmd_sub, f"Burn subtitles ({config.subtitle_format.upper()})"):
+            return None
+    else:
+        shutil.copy2(concat_temp, config.output)
+        _log("  (no subtitles to burn)")
+
+    # ── Phase 5: Verify ──
+    _log(f"\n── Phase 5: Verification ──")
+    info = verify_video(config.output, config.ffmpeg)
+    _log(f"  Output:  {info['path']}")
+    _log(f"  Size:    {info['size_mb']:.2f} MB")
+    _log(f"  Dur:     {info.get('duration', 'N/A')}")
+    _log(f"  Video:   {info.get('video', 'N/A')}")
+    _log(f"  Audio:   {info.get('audio', 'N/A')}")
+
+    if info["passes"]:
+        _log(f"\n{'='*60}")
+        _log(f"✓ Render complete: {config.output}")
+        _log(f"{'='*60}")
+        info["status"] = "ok"
+    else:
+        _log(f"\n⚠ Output < 1 MB. Check manually.")
+        info["status"] = "small_output"
+
+    # ── Cleanup ──
+    if not config.keep_temps:
+        _log("  Cleaning up temp files...")
+        shutil.rmtree(temp_dir, ignore_errors=True)
+
+    return info
+
+
+def verify_video(video_path: Path, ffmpeg: str = "ffmpeg") -> dict:
+    """Extract metadata from output video using ffmpeg."""
+    result = subprocess.run(
+        [ffmpeg, "-i", str(video_path), "-hide_banner"],
+        capture_output=True, text=True,
+    )
+    info: dict = {
+        "path": str(video_path),
+        "size_bytes": video_path.stat().st_size,
+        "size_mb": video_path.stat().st_size / (1024 * 1024),
+    }
+    for line in result.stderr.split("\n"):
+        if "Duration" in line:
+            info["duration"] = line.strip().split(",")[0].split("Duration:")[-1].strip()
+        if "Stream #0:0" in line and "Video" in line:
+            info["video"] = line.strip()
+        if "Stream #0:1" in line and "Audio" in line:
+            info["audio"] = line.strip()
+        if "bitrate" in line and "kb/s" in line:
+            parts = line.strip().split(",")
+            for p in parts:
+                if "kb/s" in p:
+                    info["bitrate"] = p.strip()
+
+    info["passes"] = info.get("size_mb", 0) > 0
+    return info
+
+
+def write_report(report: dict, path: Path) -> None:
+    """Write render report as JSON."""
+    path.parent.mkdir(parents=True, exist_ok=True)
+    path.write_text(json.dumps(report, ensure_ascii=False, indent=2), encoding="utf-8")
+
+
+def _parse_external_subtitle(sub_path: Path, num_images: int) -> list[str]:
+    """Parse an external SRT/ASS file into per-image subtitle mapping.
+
+    For simplicity, returns all non-empty lines as one subtitle per image.
+    More sophisticated parsing would use the SRT/ASS timing, but since
+    we divide time equally per image, we just map line-by-line.
+    """
+    content = sub_path.read_text(encoding="utf-8")
+    # Remove ASS headers/formatting
+    if sub_path.suffix.lower() == ".ass":
+        lines = []
+        in_events = False
+        for line in content.split("\n"):
+            stripped = line.strip()
+            if stripped == "[Events]":
+                in_events = True
+                continue
+            if in_events and stripped.startswith("Dialogue:"):
+                # Extract text after last comma
+                parts = stripped.split(",", 9)
+                if len(parts) >= 10:
+                    lines.append(parts[9])
+        return (lines + [""] * num_images)[:num_images]
+    else:
+        # SRT: extract text between timestamps
+        lines = []
+        for block in content.strip().split("\n\n"):
+            parts = block.split("\n", 2)
+            if len(parts) >= 3:
+                lines.append(parts[2])
+        return (lines + [""] * num_images)[:num_images]

comicvid/render.py

@@ -0,0 +1,107 @@
+"""Single scene rendering with Ken Burns zoom effect."""
+
+from __future__ import annotations
+
+import subprocess
+from pathlib import Path
+
+from comicvid.audio import reencode_audio
+from comicvid.types import Config
+
+
+def build_scene_video(
+    clip_path: Path,
+    img_path: Path,
+    audio_path: Path | None,
+    duration: float,
+    config: Config,
+    scene_label: str = "",
+) -> bool:
+    """Build a single scene video clip with Ken Burns zoom.
+
+    Applies:
+    - Ken Burns zoom (100% → 100%+zoom) via zoompan filter
+    - Centered crop to maintain aspect ratio
+    - Audio at config sample rate
+
+    Args:
+        clip_path: Output MP4 path for this scene.
+        img_path: Input image path.
+        audio_path: Optional audio file path.
+        duration: Clip duration in seconds.
+        config: Render configuration.
+        scene_label: Label for logging.
+
+    Returns:
+        True on success.
+    """
+    frames = int(duration * config.fps)
+    zoom_expr = f"1+{config.ken_burns_zoom}*on/{frames}"
+
+    has_audio = audio_path is not None and audio_path.exists()
+    aac_temp: Path | None = None
+
+    if has_audio:
+        aac_temp = clip_path.with_suffix(".aac")
+        if not reencode_audio(
+            audio_path,  # type: ignore[arg-type]
+            aac_temp,
+            config.ffmpeg,
+            config.audio_sample_rate,
+            config.audio_bitrate,
+        ):
+            return False
+
+        cmd = [
+            config.ffmpeg, "-y",
+            "-loop", "1",
+            "-i", str(img_path),
+            "-i", str(aac_temp),
+            "-vf",
+            f"scale={config.resolution}:force_original_aspect_ratio=increase,"
+            f"crop={config.resolution},"
+            f"zoompan=z='{zoom_expr}':d={frames}:s={config.resolution_x}:fps={config.fps}",
+            "-c:v", "libx264",
+            "-preset", "medium",
+            "-crf", str(config.crf),
+            "-maxrate", config.video_bitrate,
+            "-bufsize", "3000k",
+            "-pix_fmt", "yuv420p",
+            "-c:a", "copy",
+            "-shortest",
+            "-t", str(duration),
+            str(clip_path),
+        ]
+    else:
+        cmd = [
+            config.ffmpeg, "-y",
+            "-loop", "1",
+            "-i", str(img_path),
+            "-vf",
+            f"scale={config.resolution}:force_original_aspect_ratio=increase,"
+            f"crop={config.resolution},"
+            f"zoompan=z='{zoom_expr}':d={frames}:s={config.resolution_x}:fps={config.fps}",
+            "-c:v", "libx264",
+            "-preset", "medium",
+            "-crf", str(config.crf),
+            "-maxrate", config.video_bitrate,
+            "-bufsize", "3000k",
+            "-pix_fmt", "yuv420p",
+            "-an",
+            "-t", str(duration),
+            str(clip_path),
+        ]
+
+    label = scene_label or clip_path.stem
+    result = subprocess.run(cmd, capture_output=True, text=True)
+    if result.returncode != 0:
+        print(f"  [{label}] FAILED: {result.stderr[-800:]}")
+        return False
+
+    if has_audio and aac_temp is not None:
+        try:
+            aac_temp.unlink(missing_ok=True)
+        except OSError:
+            pass
+
+    return True

comicvid/subtitle.py

@@ -0,0 +1,203 @@
+"""SRT and ASS subtitle generation.
+
+SRT: Simple, widely compatible plain-text format.
+ASS: Advanced SubStation Alpha — styled (font size, stroke, position).
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+
+def _srt_ts(sec: float) -> str:
+    """Format seconds as SRT timestamp: HH:MM:SS,mmm"""
+    h = int(sec // 3600)
+    m = int((sec % 3600) // 60)
+    s = int(sec % 60)
+    ms = int((sec - int(sec)) * 1000)
+    return f"{h:02d}:{m:02d}:{s:02d},{ms:03d}"
+
+
+def _ass_ts(sec: float) -> str:
+    """Format seconds as ASS timestamp: H:MM:SS.mm"""
+    h = int(sec // 3600)
+    m = int((sec % 3600) // 60)
+    s = sec % 60
+    return f"{h}:{m:02d}:{s:05.2f}"
+
+
+def build_srt(
+    durations: list[float],
+    subtitles: list[str],
+) -> str:
+    """Build SRT subtitle content.
+
+    Args:
+        durations: Duration in seconds for each segment.
+        subtitles: Subtitle text per segment (empty string = no subtitle).
+
+    Returns:
+        Complete SRT file content.
+    """
+    lines: list[str] = []
+    current_time = 0.0
+    sub_idx = 0
+
+    for dur, text in zip(durations, subtitles):
+        if not text:
+            current_time += dur
+            continue
+        sub_idx += 1
+        lines.append(str(sub_idx))
+        lines.append(f"{_srt_ts(current_time)} --> {_srt_ts(current_time + dur)}")
+        lines.append(text)
+        lines.append("")
+        current_time += dur
+
+    return "\n".join(lines)
+
+
+def build_ass(
+    durations: list[float],
+    subtitles: list[str],
+    video_width: int = 1280,
+    video_height: int = 720,
+    font_size: int = 28,
+    border_size: int = 2,
+) -> str:
+    """Build ASS subtitle content with styled formatting.
+
+    ASS provides:
+    - Font size (28px for readability)
+    - Border/outline (2px black stroke)
+    - Position (bottom-center)
+    - Shadow and colors
+
+    Args:
+        durations: Duration in seconds for each segment.
+        subtitles: Subtitle text per segment.
+        video_width, video_height: Output video dimensions.
+        font_size: Subtitle font size.
+        border_size: Black outline thickness.
+
+    Returns:
+        Complete ASS file content.
+    """
+    margin_v = int(video_height * 0.05)
+    margin_h = int(video_width * 0.02)
+
+    lines: list[str] = []
+    lines.append("[Script Info]")
+    lines.append("Title: comicvid Subtitles")
+    lines.append("ScriptType: v4.00+")
+    lines.append(f"PlayResX: {video_width}")
+    lines.append(f"PlayResY: {video_height}")
+    lines.append("ScaledBorderAndShadow: yes")
+    lines.append("")
+
+    lines.append("[V4+ Styles]")
+    lines.append(
+        "Format: Name, Fontname, Fontsize, PrimaryColour, SecondaryColour, "
+        "OutlineColour, BackColour, Bold, Italic, Underline, StrikeOut, "
+        "ScaleX, ScaleY, Spacing, Angle, BorderStyle, Outline, Shadow, "
+        "Alignment, MarginL, MarginR, MarginV, Encoding"
+    )
+    primary = "&H00FFFFFF"
+    outline = "&H00000000"
+    font_name = _resolve_font_name()
+    lines.append(
+        f"Style: Default,{font_name},{font_size},"
+        f"{primary},{primary},"
+        f"{outline},{outline},"
+        f"0,0,0,0,"
+        f"100,100,0,0,"
+        f"1,{border_size},0,"
+        f"2,"
+        f"{margin_h},{margin_h},{margin_v},"
+        f"1"
+    )
+    lines.append("")
+
+    lines.append("[Events]")
+    lines.append(
+        "Format: Layer, Start, End, Style, Name, MarginL, MarginR, "
+        "MarginV, Effect, Text"
+    )
+
+    current_time = 0.0
+    for dur, text in zip(durations, subtitles):
+        if not text:
+            current_time += dur
+            continue
+        escaped = text.replace("\\", "\\\\").replace("{", "\\{").replace("}", "\\}")
+        lines.append(
+            f"Dialogue: 0,{_ass_ts(current_time)},{_ass_ts(current_time + dur)},"
+            f"Default,,0,0,0,,{escaped}"
+        )
+        current_time += dur
+
+    return "\n".join(lines)
+
+
+def write_srt(path: Path, durations: list[float], subtitles: list[str]) -> Path:
+    """Write SRT file and return path."""
+    path.parent.mkdir(parents=True, exist_ok=True)
+    content = build_srt(durations, subtitles)
+    path.write_text(content, encoding="utf-8")
+    return path
+
+
+def write_ass(
+    path: Path,
+    durations: list[float],
+    subtitles: list[str],
+    video_width: int = 1280,
+    video_height: int = 720,
+) -> Path:
+    """Write ASS file and return path."""
+    path.parent.mkdir(parents=True, exist_ok=True)
+    content = build_ass(durations, subtitles, video_width, video_height)
+    path.write_text(content, encoding="utf-8")
+    return path
+
+
+def _resolve_font_name() -> str:
+    """Resolve a readable Chinese-capable font name for ASS.
+
+    Tries common system fonts; falls back to sans-serif.
+    """
+    import subprocess
+    import sys
+
+    candidates = [
+        "PingFang SC",
+        "Noto Sans CJK SC",
+        "Source Han Sans SC",
+        "STHeiti",
+        "Arial Unicode MS",
+    ]
+
+    for name in candidates:
+        try:
+            result = subprocess.run(
+                ["fc-list", f":lang=zh"],
+                capture_output=True, text=True, timeout=3,
+            )
+            if name.lower() in result.stdout.lower():
+                return name
+        except Exception:
+            pass
+
+    # Try common system fonts without Chinese filtering
+    for name in candidates:
+        try:
+            result = subprocess.run(
+                ["fc-list", name],
+                capture_output=True, text=True, timeout=3,
+            )
+            if name.lower() in result.stdout.lower():
+                return name
+        except Exception:
+            pass
+
+    return "sans-serif"

comicvid/types.py

@@ -0,0 +1,86 @@
+"""Configuration dataclass for comicvid rendering."""
+
+from __future__ import annotations
+
+import dataclasses
+from pathlib import Path
+
+
+@dataclasses.dataclass
+class Config:
+    """Render configuration for a single comicvid video."""
+
+    # Input paths
+    image_dir: Path
+    """Directory containing panel images (sorted by filename)."""
+
+    # Output
+    output: Path
+    """Output MP4 path."""
+
+    # Timing
+    duration: float | None = None
+    """Total video duration in seconds. If None, infer from image count."""
+
+    per_image_duration: float = 3.0
+    """Seconds per image when duration is not specified."""
+
+    # Subtitles
+    subtitle: Path | None = None
+    """Optional external subtitle file (SRT or ASS)."""
+
+    subtitle_format: str = "ass"
+    """Subtitle format: 'ass' (styled) or 'srt' (simple)."""
+
+    subtitles: list[str] | None = None
+    """Optional list of subtitle texts, one per image. Generated as ASS."""
+
+    # Audio
+    audio: Path | None = None
+    """Optional audio file (WAV, MP3, etc.). AAC-encoded before muxing."""
+
+    # Resolution
+    width: int = 1280
+    """Output video width in pixels."""
+
+    height: int = 720
+    """Output video height in pixels."""
+
+    # Video quality
+    fps: int = 24
+    """Frames per second."""
+
+    crf: int = 23
+    """H.264 CRF quality (lower = better, 18-28 typical)."""
+
+    video_bitrate: str = "1500k"
+    """Video bitrate."""
+
+    # Audio quality
+    audio_sample_rate: int = 44100
+    """Audio sample rate in Hz."""
+
+    audio_bitrate: str = "128k"
+    """Audio bitrate."""
+
+    # Ken Burns
+    ken_burns_zoom: float = 0.05
+    """Zoom amount (0.05 = 100% → 105%)."""
+
+    # Rendering
+    ffmpeg: str = "ffmpeg"
+    """FFmpeg binary path."""
+
+    temp_dir: Path = Path("/tmp") / "comicvid"
+    """Temporary working directory."""
+
+    keep_temps: bool = False
+    """If True, do not clean up temporary files."""
+
+    @property
+    def resolution(self) -> str:
+        return f"{self.width}:{self.height}"
+
+    @property
+    def resolution_x(self) -> str:
+        return f"{self.width}x{self.height}"

comicvid-0.1.0.dist-info/METADATA

@@ -0,0 +1,140 @@
+Metadata-Version: 2.4
+Name: comicvid
+Version: 0.1.0
+Summary: Static images to animated video — Ken Burns zoom + ASS subtitles + audio sync
+Author: comicvid contributors
+License: Apache-2.0
+Project-URL: Homepage, https://github.com/chfr19820610-cell/comicvid
+Project-URL: Repository, https://github.com/chfr19820610-cell/comicvid.git
+Keywords: video,slideshow,ken-burns,subtitles,cli
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: End Users/Desktop
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Multimedia :: Video :: Conversion
+Classifier: Topic :: Utilities
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: click>=8.0
+Dynamic: license-file
+
+# comicvid
+
+**Static images to animated video — Ken Burns zoom + ASS subtitles + audio sync.**
+
+Turn a folder of images into a polished MP4 video with a single command. Pure FFmpeg + Python — zero API costs.
+
+## Features
+
+- **Ken Burns zoom** — subtle 100% → 105% camera movement on each image
+- **ASS subtitles** — styled (28px font, black stroke, bottom-center) with Chinese font support
+- **Audio sync** — AAC 44100 Hz mono, automatically synchronized to video
+- **Landscape & portrait** — 1280×720 or 1080×1920 (any resolution)
+- **Batch mode** — process multiple subfolders at once
+- **Pure CLI** — no GUI, no config files, no API keys
+
+## Installation
+
+```bash
+pip install comicvid
+```
+
+Requires **Python 3.10+** and **FFmpeg** installed on your system.
+
+## Usage
+
+### Basic render
+
+```bash
+comicvid render ./panels/ --output episode.mp4 --duration 30
+```
+
+### With subtitles and audio
+
+```bash
+comicvid render ./panels/ \
+    --output episode.mp4 \
+    --duration 30 \
+    --subtitle captions.srt \
+    --audio narration.wav \
+    --width 1280 --height 720
+```
+
+### Per-image text subtitles
+
+```bash
+comicvid render ./panels/ \
+    --output episode.mp4 \
+    -t "Hello, world!" \
+    -t "Second panel" \
+    -t "Third panel" \
+    --audio music.wav
+```
+
+### Vertical video (TikTok/Reels)
+
+```bash
+comicvid render ./panels/ \
+    --output vertical.mp4 \
+    --duration 60 \
+    --resolution 1080x1920
+```
+
+### Batch mode (episode directories)
+
+```bash
+comicvid batch ./episodes/ --output-dir ./output/
+```
+
+### All options
+
+```
+Usage: comicvid render [OPTIONS] IMAGE_DIR
+
+  Render images from IMAGE_DIR into an MP4 video.
+
+Options:
+  -o, --output TEXT               Output MP4 path.  [default: output.mp4]
+  --duration FLOAT                Total video duration in seconds.
+  --per-image-duration FLOAT      Seconds per image.  [default: 3.0]
+  --subtitle FILE                 External subtitle file (SRT or ASS).
+  --subtitle-format [ass|srt]     Subtitle format.  [default: ass]
+  -t, --text TEXT                 Subtitle text per image.
+  --audio FILE                    Audio file (WAV, MP3, etc.).
+  --width INTEGER                 Output video width.  [default: 1280]
+  --height INTEGER                Output video height.  [default: 720]
+  --resolution TEXT               Shortcut: '1920x1080'.
+  --fps INTEGER                   Frames per second.  [default: 24]
+  --crf INTEGER                   H.264 CRF quality.  [default: 23]
+  --video-bitrate TEXT            Video bitrate.  [default: 1500k]
+  --zoom FLOAT                    Ken Burns zoom amount.  [default: 0.05]
+  --ffmpeg TEXT                   FFmpeg binary path.  [default: ffmpeg]
+  --keep-temps                    Keep temporary files.
+  --help                          Show this message and exit.
+```
+
+## Input format
+
+`IMAGE_DIR` should contain panel images sorted by filename. Supported formats:
+- PNG, JPG, JPEG, WEBP, BMP
+
+Images are processed in alphabetical order.
+
+## How it works
+
+1. **Scene building** — each image is looped for its duration with a Ken Burns `zoompan` filter (100% → 105%)
+2. **Audio encoding** — `ffmpeg` re-encodes audio to AAC at 44100 Hz mono
+3. **Subtitles** — ASS format with styled Chinese-capable fonts, burned into video
+4. **Concatenation** — FFmpeg concat demuxer assembles scenes
+5. **Output** — Final MP4 with H.264 video + AAC audio
+
+## License
+
+Apache 2.0

comicvid-0.1.0.dist-info/RECORD

@@ -0,0 +1,13 @@
+comicvid/__init__.py,sha256=9VHQ_Si5jrrCHfyvoAZqsJOKTEI72jlNhKclfZPCSDA,114
+comicvid/audio.py,sha256=6wZOU2HR8NKOjvV7vZF2YzCOfWG02NFTHN8CeWOabrM,1904
+comicvid/cli.py,sha256=nBW4StcDvzwlI3jtoCzfwd88gv3x-Fgvc70UzVv2IeE,8258
+comicvid/pipeline.py,sha256=qPzCHLGIIK6tVAZl91aOjuLqGbegABDF3yV04AfBlEo,9008
+comicvid/render.py,sha256=TzP0dL5R9_fufU-JhaIBbEI4HLEl7i43AECO9rs1DVM,3162
+comicvid/subtitle.py,sha256=64Flhkzlp5qnItRdIeG2kJ4bb0uTMPWouMenJNBf8A0,5600
+comicvid/types.py,sha256=DBZg-Oh8bGMTvRKXkBHPj_oaDQjja6kJhZkkEAKYjmI,2080
+comicvid-0.1.0.dist-info/licenses/LICENSE,sha256=xx0jnfkXJvxRnG63LTGOxlggYnIysveWIZ6H3PNdCrQ,11357
+comicvid-0.1.0.dist-info/METADATA,sha256=2olkIZEOGCvKlmRCrNCv6TL3fTNmJwVaNEW3kHPETiw,4497
+comicvid-0.1.0.dist-info/WHEEL,sha256=K260EYznzXsJYBQGqmI8VTxEdiZYNvDZwW9cBh9-_MA,91
+comicvid-0.1.0.dist-info/entry_points.txt,sha256=HAuPcX4MvNTp-1kbVS2gFU60OxGZcqPSK9dRrf_gD10,46
+comicvid-0.1.0.dist-info/top_level.txt,sha256=F1Vc9iw4wGT3q6VZ76W-NU7vnTyvv8wOWcB-7M-a9xU,9
+comicvid-0.1.0.dist-info/RECORD,,

comicvid-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (83.0.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

comicvid-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+comicvid = comicvid.cli:cli

comicvid-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,201 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

comicvid-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+comicvid