vidfix 0.1.0__py3-none-any.whl

vidfix/__init__.py

@@ -0,0 +1,38 @@
+"""vidfix: test-media toolkit for QA engineers."""
+
+from vidfix.core.caption import caption
+from vidfix.core.convert import ConvertPlan, convert
+from vidfix.core.formats import to_format
+from vidfix.core.generate import generate
+from vidfix.core.probe import AudioInfo, MediaInfo, probe
+from vidfix.core.verify import PropertyCheck, VerifyResult, verify
+from vidfix.exceptions import (
+    ConversionError,
+    FFmpegNotFoundError,
+    InvalidSpecError,
+    PresetError,
+    ProbeError,
+    VidfixError,
+)
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "AudioInfo",
+    "ConversionError",
+    "ConvertPlan",
+    "FFmpegNotFoundError",
+    "InvalidSpecError",
+    "MediaInfo",
+    "PresetError",
+    "ProbeError",
+    "PropertyCheck",
+    "VerifyResult",
+    "VidfixError",
+    "caption",
+    "convert",
+    "generate",
+    "probe",
+    "to_format",
+    "verify",
+]

vidfix/cli.py

@@ -0,0 +1,513 @@
+"""vidfix command-line interface."""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Annotated
+
+import typer
+from rich.console import Console
+from rich.table import Table
+
+from vidfix.core import caption as caption_mod
+from vidfix.core import convert as convert_mod
+from vidfix.core import formats as formats_mod
+from vidfix.core import generate as generate_mod
+from vidfix.core import matrix as matrix_mod
+from vidfix.core import presets as presets_mod
+from vidfix.core import probe as probe_mod
+from vidfix.core import verify as verify_mod
+from vidfix.core.duration import format_seconds, parse_duration, parse_fps, parse_resolution
+from vidfix.core.ffmpeg import ProgressCallback, ProgressEvent
+from vidfix.exceptions import VidfixError
+
+app = typer.Typer(
+    name="vidfix",
+    help=(
+        "Media toolkit: convert, generate, and verify videos and images to exact specs. "
+        "Run with no arguments for an interactive wizard."
+    ),
+    rich_markup_mode="rich",
+)
+console = Console()
+err_console = Console(stderr=True)
+
+
+@app.callback(invoke_without_command=True)
+def main(ctx: typer.Context) -> None:
+    """vidfix — exact-spec media, no syntax required (just run `vidfix`)."""
+    if ctx.invoked_subcommand is None:
+        from vidfix.interactive import wizard
+
+        app(wizard())
+
+
+def _fail(error: Exception) -> None:
+    err_console.print(f"[red]error:[/red] {error}")
+    raise typer.Exit(code=1)
+
+
+class _ProgressBar:
+    """Rich progress bar driven by FFmpeg ``-progress`` events."""
+
+    def __init__(self, label: str, total_seconds: float) -> None:
+        from rich.progress import BarColumn, Progress, TextColumn, TimeRemainingColumn
+
+        self._progress = Progress(
+            TextColumn("[bold blue]{task.description}"),
+            BarColumn(),
+            TextColumn("{task.percentage:>3.0f}%"),
+            TimeRemainingColumn(),
+            console=console,
+        )
+        self._task = self._progress.add_task(label, total=total_seconds)
+
+    def __enter__(self) -> ProgressCallback:
+        self._progress.start()
+
+        def on_progress(event: ProgressEvent) -> None:
+            self._progress.update(self._task, completed=event.seconds)
+            if event.done:
+                self._progress.update(self._task, completed=self._progress.tasks[0].total or 0)
+
+        return on_progress
+
+    def __exit__(self, *exc: object) -> None:
+        self._progress.stop()
+
+
+@app.command(
+    epilog=(
+        "Examples:\n\n"
+        "  vidfix generate -o bars.mp4 --fps 60 --duration 30s --res 720p\n\n"
+        "  vidfix generate -o df.mp4 --fps 29.97 --pattern testsrc --timecode\n\n"
+        "  vidfix generate -o red.mp4 --pattern solid:red --audio none"
+    )
+)
+def generate(
+    output: Annotated[Path, typer.Option("-o", "--output", help="Output file path.")],
+    fps: Annotated[
+        str | None, typer.Option(help="Frame rate: 30, 59.94, or 30000/1001. Default 30.")
+    ] = None,
+    duration: Annotated[
+        str | None, typer.Option(help="Duration: '30s', '1:30', or '90'. Default 5s.")
+    ] = None,
+    res: Annotated[
+        str | None, typer.Option(help="Resolution: '1280x720', '720p', '4k'. Default 1280x720.")
+    ] = None,
+    pattern: Annotated[
+        str,
+        typer.Option(help="Test pattern: smpte, color-bars, testsrc, gradient, or solid:COLOR."),
+    ] = "smpte",
+    codec: Annotated[
+        str | None, typer.Option(help="Video codec: h264, h265, prores, vp9. Default h264.")
+    ] = None,
+    audio: Annotated[str, typer.Option(help="Audio track: tone (440Hz), silence, none.")] = "tone",
+    timecode: Annotated[
+        bool,
+        typer.Option(
+            "--timecode",
+            help="Burn in running timecode (HH:MM:SS:FF; drop-frame ';FF' for NTSC 29.97/59.94).",
+        ),
+    ] = False,
+    text: Annotated[
+        str | None, typer.Option("--text", help="Burn a caption into the video.")
+    ] = None,
+    preset: Annotated[
+        str | None, typer.Option(help="Preset name for defaults ('vidfix preset list').")
+    ] = None,
+) -> None:
+    """Create a synthetic test video with exact specs — no source file needed."""
+    try:
+        merged = presets_mod.apply_preset(preset, fps=fps, duration=duration, res=res, codec=codec)
+        total = parse_duration(merged.get("duration") or "5s")
+        drop_frame = {"df": True, "ndf": False}.get(merged.get("timecode") or "")
+        with _ProgressBar(f"generate {output.name}", total) as on_progress:
+            generate_mod.generate(
+                output,
+                fps=merged.get("fps") or "30",
+                duration=merged.get("duration") or "5s",
+                res=merged.get("res") or "1280x720",
+                pattern=pattern,
+                codec=merged.get("codec") or "h264",
+                audio=audio,
+                timecode=timecode,
+                drop_frame=drop_frame,
+                text=text,
+                on_progress=on_progress,
+            )
+    except VidfixError as exc:
+        _fail(exc)
+        return
+    console.print(f"[green]✓[/green] wrote {output}")
+
+
+@app.command(
+    epilog=(
+        "Examples:\n\n"
+        '  vidfix caption in.mp4 --text "Take 42" -o out.mp4\n\n'
+        '  vidfix caption in.mp4 --text "INTRO" --position top --color yellow -o out.mp4\n\n'
+        '  vidfix caption in.mp4 --text "3..2..1" --start 0 --end 3 -o out.mp4'
+    )
+)
+def caption(
+    input: Annotated[Path, typer.Argument(help="Source video file.")],
+    output: Annotated[Path, typer.Option("-o", "--output", help="Output file path.")],
+    text: Annotated[str, typer.Option("--text", help="Caption text to burn in.")],
+    position: Annotated[
+        str, typer.Option(help="Caption placement: top, center, bottom.")
+    ] = "bottom",
+    size: Annotated[
+        str, typer.Option(help="Font size (pixels or expression like 'h/12').")
+    ] = "h/12",
+    color: Annotated[str, typer.Option(help="Font color, e.g. white, yellow, #ff0000.")] = "white",
+    start: Annotated[
+        float | None, typer.Option(help="Show caption from this second onward.")
+    ] = None,
+    end: Annotated[float | None, typer.Option(help="Hide caption after this second.")] = None,
+) -> None:
+    """Burn a text caption into a video (audio untouched)."""
+    try:
+        total = probe_mod.probe(input).duration
+        with _ProgressBar(f"caption {output.name}", total) as on_progress:
+            caption_mod.caption(
+                input,
+                output,
+                text,
+                position=position,
+                size=size,
+                color=color,
+                start=start,
+                end=end,
+                on_progress=on_progress,
+            )
+    except VidfixError as exc:
+        _fail(exc)
+        return
+    console.print(f"[green]✓[/green] wrote {output}")
+
+
+@app.command(
+    epilog=(
+        "Examples:\n\n"
+        "  vidfix convert in.mp4 --fps 60 --duration 30s --res 1280x720 -o out.mp4\n\n"
+        "  vidfix convert in.mp4 --preset df60 -o out.mp4    (preset defaults)\n\n"
+        "  vidfix convert in.mp4 --fps 60 --smooth -o out.mp4   (motion-interpolated 30→60)\n\n"
+        "  vidfix convert in.mp4 --duration 10s -o out.mp4      (stream-copy trim, instant)\n\n"
+        "  vidfix convert in.mp4 --duration 60s --extend-mode loop -o out.mp4"
+    )
+)
+def convert(
+    input: Annotated[Path, typer.Argument(help="Source video file.")],
+    output: Annotated[Path, typer.Option("-o", "--output", help="Output file path.")],
+    fps: Annotated[
+        str | None, typer.Option(help="Target frame rate: 30, 59.94, or 30000/1001.")
+    ] = None,
+    duration: Annotated[
+        str | None,
+        typer.Option(help="Target duration: '30s', '1:30', or '90'. Trims or extends."),
+    ] = None,
+    res: Annotated[
+        str | None, typer.Option(help="Target resolution: '1280x720', '720p', '4k'.")
+    ] = None,
+    codec: Annotated[
+        str | None, typer.Option(help="Video codec: h264, h265, prores, vp9. Default h264.")
+    ] = None,
+    preset: Annotated[
+        str | None, typer.Option(help="Preset name for defaults ('vidfix preset list').")
+    ] = None,
+    smooth: Annotated[
+        bool, typer.Option("--smooth", help="Motion-interpolate fps changes (minterpolate).")
+    ] = False,
+    extend_mode: Annotated[
+        str,
+        typer.Option(help="When target duration > source: 'freeze' last frame or 'loop'."),
+    ] = "freeze",
+    stretch: Annotated[
+        bool, typer.Option("--stretch", help="Stretch to target resolution (no pad bars).")
+    ] = False,
+    no_audio: Annotated[bool, typer.Option("--no-audio", help="Drop the audio track.")] = False,
+    audio_tone: Annotated[
+        bool, typer.Option("--audio-tone", help="Replace audio with a 440Hz test tone.")
+    ] = False,
+    precise: Annotated[
+        bool, typer.Option("--precise", help="Force re-encode for frame-accurate trims.")
+    ] = False,
+) -> None:
+    """Transform an existing video to exact specs (stream-copies when possible)."""
+    try:
+        merged = presets_mod.apply_preset(preset, fps=fps, duration=duration, res=res, codec=codec)
+        target_duration = merged.get("duration")
+        label = f"convert {output.name}"
+        total = (
+            parse_duration(target_duration) if target_duration else probe_mod.probe(input).duration
+        )
+        with _ProgressBar(label, total) as on_progress:
+            plan = convert_mod.convert(
+                input,
+                output,
+                fps=merged.get("fps"),
+                duration=target_duration,
+                res=merged.get("res"),
+                codec=merged.get("codec") or "h264",
+                smooth=smooth,
+                extend_mode=extend_mode,
+                stretch=stretch,
+                no_audio=no_audio,
+                audio_tone=audio_tone,
+                precise=precise,
+                on_progress=on_progress,
+            )
+    except VidfixError as exc:
+        _fail(exc)
+        return
+    for warning in plan.warnings:
+        err_console.print(f"[yellow]warning:[/yellow] {warning}")
+    mode = "stream copy" if plan.stream_copy else "re-encode"
+    console.print(f"[green]✓[/green] wrote {output} ({mode})")
+
+
+@app.command(
+    name="format",
+    epilog=(
+        "Examples:\n\n"
+        "  vidfix format clip.mov -o clip.mp4      (any container → any container)\n\n"
+        "  vidfix format clip.mp4 -o clip.gif      (palette-optimized gif)\n\n"
+        "  vidfix format photo.png -o photo.webp   (image → image)\n\n"
+        "  vidfix format clip.mp4 -o thumb.jpg     (first-frame grab)"
+    ),
+)
+def format_cmd(
+    input: Annotated[Path, typer.Argument(help="Source picture or video.")],
+    output: Annotated[
+        Path, typer.Option("-o", "--output", help="Output path; extension picks the format.")
+    ],
+) -> None:
+    """Convert any picture or video to any other format (by output extension)."""
+    try:
+        if (
+            formats_mod.media_kind(str(input)) == "video"
+            and formats_mod.media_kind(str(output)) == "video"
+        ):
+            total = probe_mod.probe(input).duration
+            with _ProgressBar(f"format {output.name}", total) as on_progress:
+                formats_mod.to_format(input, output, on_progress=on_progress)
+        else:
+            formats_mod.to_format(input, output)
+    except VidfixError as exc:
+        _fail(exc)
+        return
+    console.print(f"[green]✓[/green] wrote {output}")
+
+
+@app.command(
+    epilog=(
+        "Exit code 0 when all checks pass, 1 otherwise — wire it straight into CI.\n\n"
+        "Examples:\n\n"
+        "  vidfix verify out.mp4 --fps 60 --duration 30s --res 1280x720\n\n"
+        "  vidfix verify out.mp4 --fps 29.97 --codec h264 --json"
+    )
+)
+def verify(
+    input: Annotated[Path, typer.Argument(help="Media file to verify.")],
+    fps: Annotated[
+        str | None, typer.Option(help="Expected frame rate: 30, 59.94, or 30000/1001.")
+    ] = None,
+    duration: Annotated[
+        str | None, typer.Option(help="Expected duration: '30s', '1:30', or '90'.")
+    ] = None,
+    res: Annotated[
+        str | None, typer.Option(help="Expected resolution: '1280x720', '720p', '4k'.")
+    ] = None,
+    codec: Annotated[
+        str | None, typer.Option(help="Expected video codec: h264, h265, prores, vp9.")
+    ] = None,
+    fps_tolerance: Annotated[
+        float, typer.Option(help="Allowed fps deviation.")
+    ] = verify_mod.DEFAULT_FPS_TOLERANCE,
+    duration_tolerance: Annotated[
+        float, typer.Option(help="Allowed duration deviation in seconds.")
+    ] = verify_mod.DEFAULT_DURATION_TOLERANCE,
+    json_out: Annotated[
+        bool, typer.Option("--json", help="Emit machine-readable JSON instead of a table.")
+    ] = False,
+) -> None:
+    """Assert a file matches specs; exit 0 on pass, 1 on fail (designed for CI)."""
+    if fps is None and duration is None and res is None and codec is None:
+        _fail(ValueError("Nothing to verify: pass at least one of --fps/--duration/--res/--codec."))
+        return
+    try:
+        result = verify_mod.verify(
+            input,
+            fps=parse_fps(fps) if fps else None,
+            duration=parse_duration(duration) if duration else None,
+            res=parse_resolution(res) if res else None,
+            codec=codec,
+            fps_tolerance=fps_tolerance,
+            duration_tolerance=duration_tolerance,
+        )
+    except VidfixError as exc:
+        _fail(exc)
+        return
+
+    if json_out:
+        console.print_json(result.model_dump_json())
+    else:
+        table = Table(title=str(input))
+        table.add_column("property", style="bold cyan")
+        table.add_column("expected")
+        table.add_column("actual")
+        table.add_column("result")
+        for check in result.checks:
+            mark = "[green]PASS[/green]" if check.passed else "[red]FAIL[/red]"
+            table.add_row(check.name, check.expected, check.actual, mark)
+        console.print(table)
+    raise typer.Exit(code=0 if result.passed else 1)
+
+
+@app.command(
+    name="info",
+    epilog="Examples:\n\n  vidfix info clip.mp4\n\n  vidfix info clip.mp4 --json | jq .fps",
+)
+def probe(
+    input: Annotated[Path, typer.Argument(help="Media file to inspect.")],
+    json_out: Annotated[
+        bool, typer.Option("--json", help="Emit machine-readable JSON (jq-friendly).")
+    ] = False,
+) -> None:
+    """Pretty-print media metadata: container, duration, fps, resolution, codecs."""
+    try:
+        info = probe_mod.probe(input)
+    except VidfixError as exc:
+        _fail(exc)
+        return
+
+    if json_out:
+        console.print_json(info.model_dump_json())
+        return
+
+    table = Table(title=str(input), show_header=False)
+    table.add_column(style="bold cyan")
+    table.add_column()
+    table.add_row("container", info.container)
+    table.add_row("duration", f"{format_seconds(info.duration)} ({info.duration:.3f}s)")
+    table.add_row("resolution", info.resolution)
+    table.add_row("fps", info.fps_display)
+    table.add_row("video codec", info.video_codec)
+    table.add_row("pixel format", info.pix_fmt or "-")
+    table.add_row("bitrate", f"{info.bitrate // 1000} kb/s" if info.bitrate else "-")
+    if info.audio:
+        rate = f"{info.audio.sample_rate} Hz" if info.audio.sample_rate else "?"
+        channels = f"{info.audio.channels}ch" if info.audio.channels else "?"
+        table.add_row("audio", f"{info.audio.codec} {rate} {channels}")
+    else:
+        table.add_row("audio", "none")
+    console.print(table)
+
+
+app.command(name="probe", hidden=True)(probe)  # pre-rename alias
+
+
+@app.command(
+    name="variants",
+    epilog=(
+        "Examples:\n\n"
+        "  vidfix variants in.mp4 --fps 30,60 --res 720p,1080p -o variants/\n\n"
+        "  vidfix variants in.mp4 --fps 29.97,59.94 --res 480p -o out/ --jobs 8"
+    ),
+)
+def matrix(
+    input: Annotated[Path, typer.Argument(help="Source video file.")],
+    outdir: Annotated[Path, typer.Option("-o", "--output", help="Output directory.")],
+    fps: Annotated[str, typer.Option(help="Comma-separated frame rates, e.g. '30,60'.")],
+    res: Annotated[str, typer.Option(help="Comma-separated resolutions, e.g. '720p,1080p'.")],
+    codec: Annotated[str, typer.Option(help="Video codec for all variants.")] = "h264",
+    jobs: Annotated[
+        int | None, typer.Option(help="Parallel FFmpeg processes (default: min(4, cpus)).")
+    ] = None,
+) -> None:
+    """Generate the cartesian product of fps x resolution variants."""
+    from rich.progress import BarColumn, Progress, TextColumn
+
+    try:
+        fps_list = matrix_mod.parse_list(fps, "fps")
+        res_list = matrix_mod.parse_list(res, "resolution")
+        total = len(fps_list) * len(res_list)
+        progress = Progress(
+            TextColumn("[bold blue]matrix"),
+            BarColumn(),
+            TextColumn("{task.completed}/{task.total}"),
+            console=console,
+        )
+        with progress:
+            task = progress.add_task("matrix", total=total)
+            results = matrix_mod.run_matrix(
+                input,
+                outdir,
+                fps_list,
+                res_list,
+                codec=codec,
+                jobs=jobs,
+                on_result=lambda _: progress.advance(task),
+            )
+    except VidfixError as exc:
+        _fail(exc)
+        return
+
+    table = Table(title=f"{input} → {outdir}")
+    table.add_column("fps", style="bold cyan")
+    table.add_column("res")
+    table.add_column("output")
+    table.add_column("result")
+    for r in results:
+        mark = "[green]OK[/green]" if r.ok else f"[red]FAIL[/red] {r.error}"
+        table.add_row(r.job.fps, r.job.res, r.job.output.name, mark)
+    console.print(table)
+    if not all(r.ok for r in results):
+        raise typer.Exit(code=1)
+
+
+app.command(name="matrix", hidden=True)(matrix)  # pre-rename alias
+
+
+preset_app = typer.Typer(help="Inspect built-in and user presets.", no_args_is_help=True)
+app.add_typer(preset_app, name="preset")
+
+
+@preset_app.command("list")
+def preset_list() -> None:
+    """List all presets (built-in + ~/.config/vidfix/presets.yaml)."""
+    try:
+        presets = presets_mod.load_presets()
+    except VidfixError as exc:
+        _fail(exc)
+        return
+    table = Table()
+    table.add_column("name", style="bold cyan")
+    table.add_column("description")
+    table.add_column("settings")
+    for name, settings in sorted(presets.items()):
+        description = settings.get("description", "")
+        rest = ", ".join(f"{k}={v}" for k, v in settings.items() if k != "description")
+        table.add_row(name, description, rest)
+    console.print(table)
+
+
+@preset_app.command("show")
+def preset_show(name: Annotated[str, typer.Argument(help="Preset name.")]) -> None:
+    """Show one preset's settings."""
+    try:
+        settings = presets_mod.get_preset(name)
+    except VidfixError as exc:
+        _fail(exc)
+        return
+    table = Table(title=name, show_header=False)
+    table.add_column(style="bold cyan")
+    table.add_column()
+    for key, value in settings.items():
+        table.add_row(key, value)
+    console.print(table)
+
+
+if __name__ == "__main__":
+    app()

vidfix/core/caption.py

@@ -0,0 +1,96 @@
+"""Burn text captions into videos (existing files or freshly generated ones).
+
+Caption text goes through drawtext's ``textfile=`` option — writing the text to
+a temp file sidesteps every filter-graph escaping rule for user content.
+"""
+
+from __future__ import annotations
+
+import tempfile
+from pathlib import Path
+
+from vidfix.core.ffmpeg import FFmpegRunner, ProgressCallback, video_codec_args
+from vidfix.core.generate import drawtext_runner, escape_filter_path, find_font
+from vidfix.exceptions import InvalidSpecError
+
+#: Caption placement -> drawtext x/y expressions (centered horizontally).
+POSITIONS: dict[str, str] = {
+    "top": "x=(w-text_w)/2:y=h/20",
+    "center": "x=(w-text_w)/2:y=(h-text_h)/2",
+    "bottom": "x=(w-text_w)/2:y=h-text_h-h/20",
+}
+
+
+def caption_filter(
+    textfile: str,
+    position: str = "bottom",
+    size: str = "h/12",
+    color: str = "white",
+    font: str | None = None,
+    start: float | None = None,
+    end: float | None = None,
+) -> str:
+    """Pure builder for a caption drawtext filter."""
+    if position not in POSITIONS:
+        raise InvalidSpecError(
+            f"Unknown position {position!r}; expected one of: {', '.join(POSITIONS)}."
+        )
+    parts = [f"textfile='{escape_filter_path(textfile)}'"]
+    if font:
+        parts.append(f"fontfile='{escape_filter_path(font)}'")
+    parts += [
+        f"fontsize={size}",
+        f"fontcolor={color}",
+        "box=1",
+        "boxcolor=black@0.5",
+        "boxborderw=8",
+        POSITIONS[position],
+    ]
+    if start is not None or end is not None:
+        lo = start if start is not None else 0
+        hi = end if end is not None else 10**9
+        parts.append(f"enable='between(t,{lo},{hi})'")
+    return "drawtext=" + ":".join(parts)
+
+
+def write_caption_file(text: str) -> str:
+    """Write caption text to a temp file and return its path."""
+    if not text.strip():
+        raise InvalidSpecError("Caption text is empty.")
+    with tempfile.NamedTemporaryFile(
+        mode="w", suffix=".txt", prefix="vidfix-caption-", delete=False, encoding="utf-8"
+    ) as handle:
+        handle.write(text)
+        return handle.name
+
+
+def caption(
+    input_path: str | Path,
+    output: str | Path,
+    text: str,
+    position: str = "bottom",
+    size: str = "h/12",
+    color: str = "white",
+    start: float | None = None,
+    end: float | None = None,
+    runner: FFmpegRunner | None = None,
+    on_progress: ProgressCallback | None = None,
+) -> Path:
+    """Burn a caption into an existing video (audio is stream-copied)."""
+    runner = drawtext_runner(runner or FFmpegRunner())
+    textfile = write_caption_file(text)
+    try:
+        vf = caption_filter(
+            textfile,
+            position=position,
+            size=size,
+            color=color,
+            font=find_font(),
+            start=start,
+            end=end,
+        )
+        args = ["-i", str(input_path), "-vf", vf, *video_codec_args("h264"), "-c:a", "copy"]
+        runner.run([*args, str(output)], on_progress=on_progress)
+    finally:
+        Path(textfile).unlink(missing_ok=True)
+    return Path(output)