PyVideoKit-Libs 0.2.0__py3-none-any.whl

pyvideokit_libs/__init__.py

@@ -0,0 +1,55 @@
+from .ffmpeg_utils import (
+    FFmpegError,
+    validate_input_file,
+    require_tools,
+    require_video_codec,
+    require_audio_stream,
+    probe_duration,
+    probe_stream_props,
+    probe_video_codec,
+    probe_has_audio,
+    parse_time_to_seconds,
+    seconds_to_hms,
+    make_output_path,
+    resolve_output_path,
+    which,
+    run_command,
+    run_ffmpeg_with_progress,
+)
+from .apply_vhs_effect import apply_vhs_effect, build_vhs_filter
+from .concat_videos import join_videos, check_stream_compatibility
+from .convert_to_ffv1 import convert_to_ffv1
+from .extract_audio import extract_audio
+from .fade_video import fade_video
+from .prepare_youtube import prepare_youtube
+from .trim_video import trim_video
+
+__version__ = "0.2.0"
+
+__all__ = [
+    "FFmpegError",
+    "validate_input_file",
+    "require_tools",
+    "require_video_codec",
+    "require_audio_stream",
+    "probe_duration",
+    "probe_stream_props",
+    "probe_video_codec",
+    "probe_has_audio",
+    "parse_time_to_seconds",
+    "seconds_to_hms",
+    "make_output_path",
+    "resolve_output_path",
+    "which",
+    "run_command",
+    "run_ffmpeg_with_progress",
+    "apply_vhs_effect",
+    "build_vhs_filter",
+    "join_videos",
+    "check_stream_compatibility",
+    "convert_to_ffv1",
+    "extract_audio",
+    "fade_video",
+    "prepare_youtube",
+    "trim_video",
+]

pyvideokit_libs/apply_vhs_effect.py

@@ -0,0 +1,144 @@
+#!/usr/bin/env python3
+
+import math
+import tempfile
+from collections.abc import Callable
+from dataclasses import dataclass
+from pathlib import Path
+from . import ffmpeg_utils as utils
+
+
+SAMPLE_RATE   = 48000
+BIT_DEPTH     = 32
+CHANNELS      = 2
+LOW_PASS_FREQ = 4000
+IN_VOL        = 1.0
+OUT_VOL       = 0.077
+DB_VOLUME     = math.pow(10, -22.75 / 20.0)
+
+V_CODEC        = "ffv1"
+A_CODEC        = "pcm_s16le"
+PIX_FMT        = "yuv420p"
+VID_COLORSPACE = "bt709"
+
+
+def build_vhs_filter(width: int, height: int) -> str:
+    """Build a resolution-independent VHS filtergraph preserving the original aspect ratio."""
+    chroma_w  = width // 2
+    chroma_h  = height // 2
+    luma_sq   = max(2, round(width * 0.4) // 2 * 2)
+    chroma_sq = max(2, round(chroma_w * 0.125) // 2 * 2)
+    return (
+        f"format=yuv420p, split=3 [a][b][c]; "
+        f"[a] extractplanes=y [y]; "
+        f"[b] extractplanes=u [u]; "
+        f"[c] extractplanes=v [v]; "
+        f"[y] scale={luma_sq}:{height}, scale={width}:{height} [luma_scaled]; "
+        f"[u] scale={chroma_sq}:{chroma_h}, scale={chroma_w}:{chroma_h} [u_scaled]; "
+        f"[v] scale={chroma_sq}:{chroma_h}, scale={chroma_w}:{chroma_h} [v_scaled]; "
+        f"[luma_scaled][u_scaled][v_scaled] mergeplanes=0x001020:yuv420p [merged]; "
+        f"[merged] eq=saturation=0.75, noise=alls=5:allf=t, "
+        f"geq='lum(X+5.5*(random(floor(Y/96))-0.5),Y)':cb='cb(X,Y)':cr='cr(X,Y)' [outv]"
+    )
+
+
+@dataclass
+class TempFiles:
+    vhs:    Path
+    wav:    Path
+    wav_fx: Path
+    noise:  Path
+    mix:    Path
+
+    @classmethod
+    def from_dir(cls, d: Path) -> "TempFiles":
+        def mktmp(suffix: str) -> Path:
+            with tempfile.NamedTemporaryFile(delete=False, suffix=suffix, dir=d) as f:
+                return Path(f.name)
+        return cls(
+            vhs=mktmp(".mkv"),
+            wav=mktmp(".wav"),
+            wav_fx=mktmp(".wav"),
+            noise=mktmp(".wav"),
+            mix=mktmp(".wav"),
+        )
+
+    def cleanup(self) -> None:
+        for f in (self.noise, self.mix, self.vhs, self.wav_fx, self.wav):
+            try:
+                f.unlink(missing_ok=True)
+            except Exception:
+                pass
+
+
+def _step_0_vhs_fx(
+    input_path: Path,
+    tmp: TempFiles,
+    props: dict,
+    on_progress: Callable[[float], None] | None = None,
+) -> None:
+    vhs_filter = build_vhs_filter(props["width"], props["height"])
+    cmd = [
+        "ffmpeg", "-hide_banner", "-y",
+        "-i", str(input_path),
+        "-filter_complex", vhs_filter,
+        "-c:v", V_CODEC, "-pix_fmt", PIX_FMT,
+        "-colorspace", VID_COLORSPACE,
+        "-color_primaries", VID_COLORSPACE,
+        "-color_trc", VID_COLORSPACE,
+        "-map", "[outv]", str(tmp.vhs),
+        "-map", "a", "-c:a", A_CODEC, str(tmp.wav),
+    ]
+    utils.run_ffmpeg_with_progress(cmd, duration=props.get("duration", 0.0), on_progress=on_progress)
+
+
+def _step_1_audio_fx(tmp: TempFiles, duration: float) -> None:
+    utils.run_command([
+        "sox", "-n",
+        "-r", str(SAMPLE_RATE), "-b", str(BIT_DEPTH),
+        "-e", "floating-point", "-c", str(CHANNELS),
+        str(tmp.noise), "synth", str(duration), "brownnoise", "vol", f"{DB_VOLUME}",
+    ])
+    utils.run_command([
+        "sox", "-m",
+        "-v", f"{IN_VOL}", str(tmp.wav),
+        "-v", f"{OUT_VOL}", str(tmp.noise),
+        str(tmp.mix),
+    ])
+    utils.run_command([
+        "sox", str(tmp.mix), str(tmp.wav_fx), "lowpass", str(LOW_PASS_FREQ),
+    ])
+
+
+def _step_2_map_inputs(input_path: Path, tmp: TempFiles, duration: float, output: str | None = None) -> Path:
+    base_name = input_path.stem
+    for ch in ':*?"<>|':
+        base_name = base_name.replace(ch, "-")
+    default_path = tmp.vhs.parent / f"{base_name}.mkv"
+    final_path = utils.resolve_output_path(default_path, output)
+    cmd = [
+        "ffmpeg", "-hide_banner", "-y",
+        "-i", str(tmp.vhs),
+        "-i", str(tmp.wav_fx),
+        "-map", "0:v", "-map", "1:a",
+        "-c", "copy",
+        str(final_path),
+    ]
+    utils.run_ffmpeg_with_progress(cmd, duration=duration)
+    return final_path
+
+
+def apply_vhs_effect(
+    input_path: Path,
+    output: str | None = None,
+    on_progress: Callable[[float], None] | None = None,
+) -> Path:
+    utils.require_audio_stream(input_path)
+    props = utils.probe_stream_props(input_path)
+    tmp = TempFiles.from_dir(input_path.parent)
+    try:
+        _step_0_vhs_fx(input_path, tmp, props, on_progress)
+        _step_1_audio_fx(tmp, props.get("duration", 0.0))
+        return _step_2_map_inputs(input_path, tmp, props.get("duration", 0.0), output)
+    finally:
+        tmp.cleanup()

pyvideokit_libs/concat_videos.py

@@ -0,0 +1,65 @@
+#!/usr/bin/env python3
+
+import tempfile
+from collections.abc import Callable
+from datetime import datetime
+from pathlib import Path
+from . import ffmpeg_utils as utils
+
+
+def _build_concat_file(video_paths: list[Path]) -> Path:
+    tmp = tempfile.NamedTemporaryFile(mode="w", suffix=".txt", delete=False, encoding="utf-8")
+    with tmp as f:
+        for p in video_paths:
+            # Escape single quotes for ffmpeg concat file format
+            path_str = str(p.resolve()).replace("'", r"'\''")
+            f.write(f"file '{path_str}'\n")
+    return Path(tmp.name)
+
+
+def _build_output_path(first_video: Path) -> Path:
+    timestamp = datetime.now().strftime("%Y%m%d-%H%M%S")
+    ext = first_video.suffix or ".mkv"
+    return first_video.with_name(f"joined_{timestamp}{ext}")
+
+
+def check_stream_compatibility(video_paths: list[Path], all_props: list[dict]) -> None:
+    """Raise ValueError if files have incompatible streams for stream-copy concat."""
+    ref = all_props[0]
+    if not ref:
+        return
+    keys = ("vcodec", "width", "height", "fps", "acodec", "sample_rate", "channels")
+    for path, props in zip(video_paths[1:], all_props[1:]):
+        mismatches = [
+            f"  {k}: {video_paths[0].name}={ref[k]!r} vs {path.name}={props.get(k)!r}"
+            for k in keys
+            if k in ref and props.get(k) != ref[k]
+        ]
+        if mismatches:
+            raise ValueError(
+                "Incompatible streams for lossless concat:\n" + "\n".join(mismatches)
+            )
+
+
+def join_videos(
+    video_paths: list[Path],
+    output: str | None = None,
+    on_progress: Callable[[float], None] | None = None,
+) -> Path:
+    if len(video_paths) < 2:
+        raise ValueError("Need at least two input videos.")
+    all_props = [utils.probe_stream_props(p) for p in video_paths]
+    check_stream_compatibility(video_paths, all_props)
+    total = sum(p.get("duration", 0.0) for p in all_props)
+    concat_file = _build_concat_file(video_paths)
+    output_path = utils.resolve_output_path(_build_output_path(video_paths[0]), output)
+    cmd = [
+        "ffmpeg", "-f", "concat", "-safe", "0",
+        "-i", str(concat_file),
+        "-c", "copy", str(output_path),
+    ]
+    try:
+        utils.run_ffmpeg_with_progress(cmd, duration=total, on_progress=on_progress)
+    finally:
+        concat_file.unlink(missing_ok=True)
+    return output_path

pyvideokit_libs/convert_to_ffv1.py

@@ -0,0 +1,28 @@
+#!/usr/bin/env python3
+
+from collections.abc import Callable
+from pathlib import Path
+from . import ffmpeg_utils as utils
+
+
+def convert_to_ffv1(
+    input_path: Path,
+    fps: int = 60,
+    output: str | None = None,
+    on_progress: Callable[[float], None] | None = None,
+) -> Path:
+    duration = utils.probe_duration(input_path)
+    output_path = utils.resolve_output_path(
+        utils.make_output_path(input_path, suffix="_ffv1", ext=".mkv"), output
+    )
+    cmd = [
+        "ffmpeg", "-hide_banner", "-y",
+        "-i", str(input_path),
+        "-map", "0",
+        "-c:v", "ffv1",
+        "-r", str(fps),
+        "-c:a", "pcm_s16le",
+        str(output_path),
+    ]
+    utils.run_ffmpeg_with_progress(cmd, duration=duration, on_progress=on_progress)
+    return output_path

pyvideokit_libs/extract_audio.py

@@ -0,0 +1,25 @@
+#!/usr/bin/env python3
+
+from collections.abc import Callable
+from pathlib import Path
+from . import ffmpeg_utils as utils
+
+
+def extract_audio(
+    input_path: Path,
+    output: str | None = None,
+    on_progress: Callable[[float], None] | None = None,
+) -> Path:
+    duration = utils.probe_duration(input_path)
+    output_path = utils.resolve_output_path(
+        utils.make_output_path(input_path, ext=".wav"), output
+    )
+    cmd = [
+        "ffmpeg", "-hide_banner", "-y",
+        "-i", str(input_path),
+        "-vn",
+        "-c:a", "pcm_s16le",
+        str(output_path),
+    ]
+    utils.run_ffmpeg_with_progress(cmd, duration=duration, on_progress=on_progress)
+    return output_path

pyvideokit_libs/fade_video.py

@@ -0,0 +1,71 @@
+#!/usr/bin/env python3
+
+from collections.abc import Callable
+from pathlib import Path
+from . import ffmpeg_utils as utils
+
+
+def _build_fade_cmd(
+    input_path: Path,
+    fade_in: float | None,
+    fade_out: float | None,
+    total_duration: float,
+    output_path: Path,
+    fps: int,
+) -> list[str]:
+    v_filters = [f"fps={fps}"]
+    if fade_in is not None:
+        v_filters.append(f"fade=t=in:st=0:d={fade_in:.3f}")
+    if fade_out is not None:
+        start_out = max(0.0, total_duration - fade_out)
+        v_filters.append(f"fade=t=out:st={start_out:.3f}:d={fade_out:.3f}")
+    v_filters.append("format=yuv420p")
+
+    a_filters = []
+    if fade_in is not None:
+        a_filters.append(f"afade=t=in:st=0:d={fade_in:.3f}")
+    if fade_out is not None:
+        a_start_out = max(0.0, total_duration - fade_out)
+        a_filters.append(f"afade=t=out:st={a_start_out:.3f}:d={fade_out:.3f}")
+    af_chain = ",".join(a_filters) if a_filters else None
+
+    cmd = [
+        "ffmpeg", "-hide_banner", "-y",
+        "-i", str(input_path),
+        "-c:v", "ffv1",
+        "-pix_fmt", "yuv420p",
+        "-r", str(fps),
+        "-vf", ",".join(v_filters),
+    ]
+    if af_chain:
+        cmd += ["-c:a", "pcm_s16le", "-af", af_chain]
+    else:
+        cmd += ["-c:a", "pcm_s16le"]
+    cmd.append(str(output_path))
+    return cmd
+
+
+def fade_video(
+    input_path: Path,
+    fade_in: float | None = None,
+    fade_out: float | None = None,
+    fps: int = 60,
+    output: str | None = None,
+    on_progress: Callable[[float], None] | None = None,
+) -> Path:
+    utils.require_video_codec(
+        input_path, "ffv1",
+        hint="Run convert_to_ffv1() on the source file first.",
+    )
+    utils.require_audio_stream(input_path)
+    if fade_in is None and fade_out is None:
+        raise ValueError("Specify at least one of fade_in or fade_out.")
+    total_duration = utils.probe_duration(input_path)
+    if total_duration <= 0:
+        raise ValueError("Could not determine video duration.")
+    output_path = utils.resolve_output_path(
+        utils.make_output_path(input_path, suffix="_fade"), output
+    )
+    cmd = _build_fade_cmd(input_path, fade_in, fade_out, total_duration, output_path, fps)
+    utils.run_ffmpeg_with_progress(cmd, duration=total_duration, on_progress=on_progress)
+    return output_path

pyvideokit_libs/ffmpeg_utils.py

@@ -0,0 +1,233 @@
+#!/usr/bin/env python3
+
+import json
+import shutil
+import subprocess
+from collections.abc import Callable
+from pathlib import Path
+
+
+class FFmpegError(Exception):
+    def __init__(self, returncode: int, error_lines: list[str]) -> None:
+        self.returncode = returncode
+        self.error_lines = error_lines
+        super().__init__(f"FFmpeg exited with code {returncode}")
+
+
+def which(cmd: str) -> str | None:
+    return shutil.which(cmd)
+
+
+def has_ffprobe() -> bool:
+    return which("ffprobe") is not None
+
+
+def parse_time_to_seconds(ts: str) -> float | None:
+    """Parse SS, MM:SS, or HH:MM:SS(.ms) into total seconds; returns None for empty input."""
+    ts = (ts or "").strip()
+    if ts == "":
+        return None
+    if ts.count(":") == 0:
+        return float(ts)
+    parts = [float(p) for p in ts.split(":")]
+    if len(parts) == 2:
+        mm, ss = parts
+        return mm * 60 + ss
+    if len(parts) == 3:
+        hh, mm, ss = parts
+        return hh * 3600 + mm * 60 + ss
+    raise ValueError(f"Invalid time format: {ts}")
+
+
+def seconds_to_hms(seconds: float) -> str:
+    """Convert seconds to HH:MM:SS.mmm string."""
+    seconds = max(0.0, float(seconds))
+    hh = int(seconds // 3600)
+    mm = int((seconds % 3600) // 60)
+    ss = seconds - (hh * 3600 + mm * 60)
+    return f"{hh:02d}:{mm:02d}:{ss:06.3f}"
+
+
+def probe_video_codec(path: Path) -> str:
+    """Return the codec name of the first video stream, or '' if none."""
+    if not has_ffprobe():
+        return ""
+    try:
+        out = subprocess.check_output(
+            ["ffprobe", "-v", "error", "-select_streams", "v:0",
+             "-show_entries", "stream=codec_name",
+             "-of", "default=nk=1:nw=1", str(path)],
+            stderr=subprocess.DEVNULL,
+        ).decode().strip()
+        return out
+    except Exception:
+        return ""
+
+
+def probe_has_audio(path: Path) -> bool:
+    """Return True if the file has at least one audio stream."""
+    if not has_ffprobe():
+        return False
+    try:
+        out = subprocess.check_output(
+            ["ffprobe", "-v", "error", "-select_streams", "a:0",
+             "-show_entries", "stream=codec_name",
+             "-of", "default=nk=1:nw=1", str(path)],
+            stderr=subprocess.DEVNULL,
+        ).decode().strip()
+        return bool(out)
+    except Exception:
+        return False
+
+
+def probe_stream_props(path: Path) -> dict:
+    """Return stream properties and duration in a single ffprobe call."""
+    if not has_ffprobe():
+        return {}
+    try:
+        out = subprocess.check_output(
+            ["ffprobe", "-v", "error",
+             "-show_entries",
+             "format=duration:stream=codec_name,width,height,r_frame_rate,sample_rate,channels",
+             "-of", "json", str(path)],
+            stderr=subprocess.DEVNULL,
+        ).decode()
+        data = json.loads(out)
+        props: dict = {}
+        for stream in data.get("streams", []):
+            if "width" in stream:
+                props["vcodec"] = stream.get("codec_name", "")
+                props["width"]  = stream.get("width")
+                props["height"] = stream.get("height")
+                props["fps"]    = stream.get("r_frame_rate", "")
+            elif "sample_rate" in stream:
+                props["acodec"]      = stream.get("codec_name", "")
+                props["sample_rate"] = stream.get("sample_rate")
+                props["channels"]    = stream.get("channels")
+        duration_str = data.get("format", {}).get("duration")
+        if duration_str:
+            props["duration"] = float(duration_str)
+        return props
+    except Exception:
+        return {}
+
+
+def probe_duration(path: Path) -> float:
+    """Return the duration of a media file in seconds, or 0.0 on failure."""
+    if not has_ffprobe():
+        return 0.0
+    try:
+        out = subprocess.check_output(
+            ["ffprobe", "-v", "error", "-show_entries", "format=duration",
+             "-of", "default=nk=1:nw=1", str(path)],
+            stderr=subprocess.DEVNULL,
+        ).decode().strip()
+        return float(out)
+    except Exception:
+        return 0.0
+
+
+def validate_input_file(path: str | Path) -> Path:
+    """Resolve and validate that an input file exists; raise FileNotFoundError if not."""
+    p = Path(path).expanduser().resolve()
+    if not p.exists():
+        raise FileNotFoundError(f"File not found: {p}")
+    return p
+
+
+def require_tools(*names: str) -> None:
+    """Check that all required external tools are in PATH; raise RuntimeError if any are missing."""
+    missing = [n for n in names if which(n) is None]
+    if missing:
+        raise RuntimeError(f"Required tools not found in PATH: {', '.join(missing)}")
+
+
+def require_video_codec(path: Path, codec: str, hint: str = "") -> None:
+    """Raise ValueError if the file's video codec doesn't match the expected one."""
+    actual = probe_video_codec(path)
+    if actual != codec:
+        msg = f"'{path.name}' has codec '{actual or 'none'}', expected '{codec}'."
+        if hint:
+            msg += f" {hint}"
+        raise ValueError(msg)
+
+
+def require_audio_stream(path: Path) -> None:
+    """Raise ValueError if the file has no audio stream."""
+    if not probe_has_audio(path):
+        raise ValueError(f"'{path.name}' has no audio stream.")
+
+
+def resolve_output_path(default: Path, output: str | None) -> Path:
+    """Return default if output is None, place inside dir if dir, else treat as explicit path."""
+    if output is None:
+        return default
+    out = Path(output).expanduser()
+    if out.is_dir():
+        return out / default.name
+    return out
+
+
+def make_output_path(input_path: Path, suffix: str = "", ext: str | None = None) -> Path:
+    """Build an output path in the same directory as input with optional suffix/extension."""
+    name = input_path.stem + suffix
+    extension = ext if ext is not None else input_path.suffix
+    return input_path.with_name(name + extension)
+
+
+def run_command(cmd: list[str]) -> None:
+    """Run a subprocess command; raises CalledProcessError on failure."""
+    subprocess.run(cmd, check=True)
+
+
+def run_ffmpeg_with_progress(
+    cmd: list[str],
+    duration: float = 0.0,
+    on_progress: Callable[[float], None] | None = None,
+) -> None:
+    """Run an FFmpeg command, calling on_progress(pct) as it encodes. Raises FFmpegError on failure."""
+    if "-progress" not in cmd:
+        full_cmd = cmd[:1] + ["-progress", "pipe:1", "-nostats", "-loglevel", "error"] + cmd[1:]
+    else:
+        full_cmd = cmd
+
+    try:
+        proc = subprocess.Popen(
+            full_cmd,
+            stdout=subprocess.PIPE,
+            stderr=subprocess.STDOUT,
+            bufsize=1,
+            universal_newlines=True,
+        )
+    except FileNotFoundError:
+        raise RuntimeError("ffmpeg not found in PATH")
+
+    last_pct = -1.0
+    error_lines: list[str] = []
+
+    for line in proc.stdout or []:
+        line = line.strip()
+        if not line:
+            continue
+        if line.startswith("out_time_ms="):
+            try:
+                ms = int(line.split("=", 1)[1])
+                out_time_sec = ms / 1_000_000.0
+                if duration > 0:
+                    pct = min(100.0, (out_time_sec / duration) * 100.0)
+                else:
+                    pct = min(100.0, (out_time_sec % 10) * 10.0)
+                if on_progress and (pct - last_pct >= 1.0 or pct >= 100.0):
+                    last_pct = pct
+                    on_progress(pct)
+            except ValueError:
+                pass
+        elif line.startswith("progress=end"):
+            break
+        elif " " in line or line.startswith("["):
+            # FFmpeg error/warning messages contain spaces or start with [codec @ addr]
+            error_lines.append(line)
+
+    rc = proc.wait()
+    if rc != 0:
+        raise FFmpegError(rc, error_lines)

pyvideokit_libs/prepare_youtube.py

@@ -0,0 +1,33 @@
+#!/usr/bin/env python3
+
+from collections.abc import Callable
+from pathlib import Path
+from . import ffmpeg_utils as utils
+
+
+def prepare_youtube(
+    input_path: Path,
+    output: str | None = None,
+    on_progress: Callable[[float], None] | None = None,
+) -> Path:
+    utils.require_video_codec(
+        input_path, "ffv1",
+        hint="Run convert_to_ffv1() on the source file first.",
+    )
+    duration = utils.probe_duration(input_path)
+    output_path = utils.resolve_output_path(
+        utils.make_output_path(input_path, suffix="_youtube", ext=".mov"), output
+    )
+    cmd = [
+        "ffmpeg", "-hide_banner", "-y",
+        "-i", str(input_path),
+        "-map", "0",
+        "-vf", "scale=-1:2160",     # YouTube gives better bitrate to 4K uploads
+        "-c:v", "prores_ks",
+        "-profile:v", "3",          # ProRes 422 HQ
+        "-pix_fmt", "yuv422p10le",
+        "-c:a", "pcm_s16le",
+        str(output_path),
+    ]
+    utils.run_ffmpeg_with_progress(cmd, duration=duration, on_progress=on_progress)
+    return output_path

pyvideokit_libs/trim_video.py

@@ -0,0 +1,37 @@
+#!/usr/bin/env python3
+
+from collections.abc import Callable
+from datetime import datetime
+from pathlib import Path
+from . import ffmpeg_utils as utils
+
+
+def _build_output_path(input_path: Path) -> Path:
+    ts = datetime.now().strftime("%Y%m%d_%H%M%S")
+    return input_path.with_name(f"{ts}{input_path.suffix}")
+
+
+def trim_video(
+    input_path: Path,
+    start: float,
+    end: float,
+    output: str | None = None,
+    on_progress: Callable[[float], None] | None = None,
+) -> Path:
+    if end <= start:
+        raise ValueError("end time must be greater than start time.")
+    file_dur = utils.probe_duration(input_path)
+    if file_dur > 0 and start > file_dur:
+        raise ValueError(f"start ({start:.3f}s) exceeds input duration ({file_dur:.3f}s).")
+    duration = end - start
+    output_path = utils.resolve_output_path(_build_output_path(input_path), output)
+    cmd = [
+        "ffmpeg", "-hide_banner", "-y",
+        "-ss", utils.seconds_to_hms(start),
+        "-i", str(input_path),
+        "-t", utils.seconds_to_hms(duration),
+        "-c", "copy",
+        str(output_path),
+    ]
+    utils.run_ffmpeg_with_progress(cmd, duration=duration, on_progress=on_progress)
+    return output_path