ff-toolkit 0.1.0__py3-none-any.whl

ff_kit/__init__.py

@@ -0,0 +1,30 @@
+"""
+ff-kit — FFmpeg operations as LLM-callable tools.
+
+Quick start::
+
+    from ff_kit import clip, merge, extract_audio, add_subtitles, transcode
+
+    result = clip("in.mp4", "out.mp4", start="00:01:00", duration="30")
+"""
+
+from __future__ import annotations
+
+from ff_kit.core.clip import clip
+from ff_kit.core.merge import merge
+from ff_kit.core.extract_audio import extract_audio
+from ff_kit.core.add_subtitles import add_subtitles
+from ff_kit.core.transcode import transcode
+from ff_kit.executor import Executor, FFmpegResult
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "clip",
+    "merge",
+    "extract_audio",
+    "add_subtitles",
+    "transcode",
+    "Executor",
+    "FFmpegResult",
+]

ff_kit/cli.py

@@ -0,0 +1,159 @@
+"""
+ff-kit CLI — use FFmpeg tools directly from the command line.
+
+Usage::
+
+    ffkit clip input.mp4 output.mp4 --start 00:01:00 --duration 30
+    ffkit merge a.mp4 b.mp4 -o merged.mp4
+    ffkit extract-audio video.mp4 audio.wav --sample-rate 16000 --channels 1
+    ffkit add-subtitles video.mp4 output.mp4 --subtitle subs.srt --mode burn
+    ffkit transcode input.mp4 output.webm --video-codec libvpx-vp9 --crf 30
+    ffkit probe video.mp4
+    ffkit list-tools --format openai
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+
+from ff_kit.executor import Executor
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(
+        prog="ffkit",
+        description="ff-kit: FFmpeg operations as LLM-callable tools.",
+    )
+    sub = parser.add_subparsers(dest="command", help="Available commands")
+
+    # ── clip ──────────────────────────────────────────────────────
+    p_clip = sub.add_parser("clip", help="Trim a segment from a media file")
+    p_clip.add_argument("input", help="Source media file")
+    p_clip.add_argument("output", help="Output file")
+    p_clip.add_argument("--start", "-s", required=True, help="Start time (HH:MM:SS or seconds)")
+    p_clip.add_argument("--end", "-e", help="End time")
+    p_clip.add_argument("--duration", "-d", help="Duration")
+
+    # ── merge ─────────────────────────────────────────────────────
+    p_merge = sub.add_parser("merge", help="Concatenate multiple files")
+    p_merge.add_argument("inputs", nargs="+", help="Files to merge (at least 2)")
+    p_merge.add_argument("--output", "-o", required=True, help="Output file")
+    p_merge.add_argument("--method", "-m", default="concat_demuxer",
+                         choices=["concat_demuxer", "concat_filter"])
+
+    # ── extract-audio ─────────────────────────────────────────────
+    p_audio = sub.add_parser("extract-audio", help="Extract audio from a media file")
+    p_audio.add_argument("input", help="Source media file")
+    p_audio.add_argument("output", help="Output audio file (.mp3, .wav, .aac, etc.)")
+    p_audio.add_argument("--codec", "-c", default="copy", help="Audio codec (default: copy)")
+    p_audio.add_argument("--sample-rate", "-r", type=int, help="Sample rate in Hz (e.g. 16000)")
+    p_audio.add_argument("--channels", type=int, help="Channels (1=mono, 2=stereo)")
+
+    # ── add-subtitles ─────────────────────────────────────────────
+    p_subs = sub.add_parser("add-subtitles", help="Add subtitles to a video")
+    p_subs.add_argument("input", help="Source video file")
+    p_subs.add_argument("output", help="Output video file")
+    p_subs.add_argument("--subtitle", required=True, help="Subtitle file (.srt, .ass, .vtt)")
+    p_subs.add_argument("--mode", default="burn", choices=["burn", "embed"])
+
+    # ── transcode ─────────────────────────────────────────────────
+    p_trans = sub.add_parser("transcode", help="Convert format/codec/resolution")
+    p_trans.add_argument("input", help="Source file")
+    p_trans.add_argument("output", help="Destination file")
+    p_trans.add_argument("--video-codec", help="Video codec (e.g. libx264)")
+    p_trans.add_argument("--audio-codec", help="Audio codec (e.g. aac)")
+    p_trans.add_argument("--resolution", help="Resolution as WxH (e.g. 1280x720)")
+    p_trans.add_argument("--bitrate", help="Target bitrate (e.g. 2M)")
+    p_trans.add_argument("--fps", type=int, help="Frame rate")
+    p_trans.add_argument("--preset", help="Encoder preset (e.g. fast, medium, slow)")
+    p_trans.add_argument("--crf", type=int, help="Constant Rate Factor")
+
+    # ── probe ─────────────────────────────────────────────────────
+    p_probe = sub.add_parser("probe", help="Show media file info (ffprobe)")
+    p_probe.add_argument("input", help="Media file to inspect")
+
+    # ── list-tools ────────────────────────────────────────────────
+    p_list = sub.add_parser("list-tools", help="Print tool schemas for LLM integration")
+    p_list.add_argument("--format", "-f", default="openai",
+                        choices=["openai", "anthropic"],
+                        help="Schema format (default: openai)")
+
+    # ── parse ─────────────────────────────────────────────────────
+    args = parser.parse_args(argv)
+
+    if not args.command:
+        parser.print_help()
+        return 0
+
+    try:
+        return _run(args)
+    except Exception as exc:
+        print(f"Error: {exc}", file=sys.stderr)
+        return 1
+
+
+def _run(args: argparse.Namespace) -> int:
+    if args.command == "list-tools":
+        if args.format == "openai":
+            from ff_kit.schemas.openai import openai_tools
+            print(json.dumps(openai_tools(), indent=2))
+        else:
+            from ff_kit.schemas.anthropic import anthropic_tools
+            print(json.dumps(anthropic_tools(), indent=2))
+        return 0
+
+    if args.command == "probe":
+        exe = Executor()
+        info = exe.probe(args.input)
+        print(json.dumps(info, indent=2))
+        return 0
+
+    # All other commands need the core functions
+    from ff_kit.core import clip, merge, extract_audio, add_subtitles, transcode
+
+    if args.command == "clip":
+        result = clip(
+            args.input, args.output,
+            start=args.start, end=args.end, duration=args.duration,
+        )
+
+    elif args.command == "merge":
+        result = merge(args.inputs, args.output, method=args.method)
+
+    elif args.command == "extract-audio":
+        result = extract_audio(
+            args.input, args.output,
+            codec=args.codec,
+            sample_rate=args.sample_rate,
+            channels=args.channels,
+        )
+
+    elif args.command == "add-subtitles":
+        result = add_subtitles(
+            args.input, args.output,
+            subtitle_path=args.subtitle,
+            mode=args.mode,
+        )
+
+    elif args.command == "transcode":
+        result = transcode(
+            args.input, args.output,
+            video_codec=args.video_codec,
+            audio_codec=args.audio_codec,
+            resolution=args.resolution,
+            bitrate=args.bitrate,
+            fps=args.fps,
+            preset=args.preset,
+            crf=args.crf,
+        )
+    else:
+        return 1
+
+    print(f"Done: {result.output_path}")
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

ff_kit/core/__init__.py

@@ -0,0 +1,7 @@
+from ff_kit.core.clip import clip
+from ff_kit.core.merge import merge
+from ff_kit.core.extract_audio import extract_audio
+from ff_kit.core.add_subtitles import add_subtitles
+from ff_kit.core.transcode import transcode
+
+__all__ = ["clip", "merge", "extract_audio", "add_subtitles", "transcode"]

ff_kit/core/add_subtitles.py

@@ -0,0 +1,64 @@
+"""Burn or embed subtitles into a video file."""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+from ff_kit.executor import Executor, FFmpegResult
+
+
+def add_subtitles(
+    input_path: str,
+    output_path: str,
+    subtitle_path: str,
+    *,
+    mode: str = "burn",
+    executor: Executor | None = None,
+) -> FFmpegResult:
+    """
+    Add subtitles to a video.
+
+    Parameters
+    ----------
+    input_path : str
+        Source video file.
+    output_path : str
+        Output video file.
+    subtitle_path : str
+        Path to subtitle file (``.srt``, ``.ass``, ``.vtt``).
+    mode : str
+        ``"burn"`` (default) — hard-code subtitles into the video pixels
+        (uses the ``subtitles`` filter; universal playback).
+        ``"embed"`` — add as a soft subtitle stream (requires
+        a container that supports subtitle tracks, e.g. MKV/MP4).
+    executor : Executor, optional
+        Custom executor.
+
+    Returns
+    -------
+    FFmpegResult
+    """
+    if mode not in ("burn", "embed"):
+        raise ValueError(f"mode must be 'burn' or 'embed', got {mode!r}")
+
+    exe = executor or Executor()
+
+    if mode == "burn":
+        # Escape path for the subtitles filter (colons, backslashes)
+        safe_sub = str(Path(subtitle_path).resolve()).replace("\\", "/").replace(":", "\\:")
+        args = [
+            "-i", input_path,
+            "-vf", f"subtitles={safe_sub}",
+            "-c:a", "copy",
+            output_path,
+        ]
+    else:  # embed
+        args = [
+            "-i", input_path,
+            "-i", subtitle_path,
+            "-c", "copy",
+            "-c:s", "mov_text",
+            output_path,
+        ]
+
+    return exe.run(args, output_path=output_path)

ff_kit/core/clip.py

@@ -0,0 +1,56 @@
+"""Clip (trim) a segment from a media file."""
+
+from __future__ import annotations
+
+from ff_kit.executor import Executor, FFmpegResult
+
+
+def clip(
+    input_path: str,
+    output_path: str,
+    start: str,
+    end: str | None = None,
+    duration: str | None = None,
+    *,
+    executor: Executor | None = None,
+) -> FFmpegResult:
+    """
+    Extract a segment from *input_path* and write it to *output_path*.
+
+    Specify the segment with *start* + either *end* or *duration*.
+    Time format: ``HH:MM:SS.ms`` or seconds (e.g. ``"90"``).
+
+    Parameters
+    ----------
+    input_path : str
+        Path to the source media file.
+    output_path : str
+        Path for the trimmed output file.
+    start : str
+        Start timestamp (e.g. ``"00:01:30"`` or ``"90"``).
+    end : str, optional
+        End timestamp.  Mutually exclusive with *duration*.
+    duration : str, optional
+        Duration of the clip.  Mutually exclusive with *end*.
+    executor : Executor, optional
+        Custom executor; a default one is created if omitted.
+
+    Returns
+    -------
+    FFmpegResult
+    """
+    if not end and not duration:
+        raise ValueError("Either 'end' or 'duration' must be provided.")
+    if end and duration:
+        raise ValueError("Provide either 'end' or 'duration', not both.")
+
+    exe = executor or Executor()
+    args = ["-i", input_path, "-ss", start]
+
+    if end:
+        args.extend(["-to", end])
+    else:
+        args.extend(["-t", duration])  # type: ignore[arg-type]
+
+    args.extend(["-c", "copy", output_path])
+    return exe.run(args, output_path=output_path)

ff_kit/core/extract_audio.py

@@ -0,0 +1,54 @@
+"""Extract audio track from a media file."""
+
+from __future__ import annotations
+
+from ff_kit.executor import Executor, FFmpegResult
+
+
+def extract_audio(
+    input_path: str,
+    output_path: str,
+    *,
+    codec: str = "copy",
+    sample_rate: int | None = None,
+    channels: int | None = None,
+    executor: Executor | None = None,
+) -> FFmpegResult:
+    """
+    Extract the audio stream from a video/audio file.
+
+    Parameters
+    ----------
+    input_path : str
+        Source media file.
+    output_path : str
+        Destination audio file (e.g. ``"out.mp3"``, ``"out.wav"``).
+    codec : str
+        Audio codec.  ``"copy"`` (default) keeps the original codec;
+        use ``"libmp3lame"``, ``"aac"``, ``"pcm_s16le"``, etc. to re-encode.
+    sample_rate : int, optional
+        Output sample rate in Hz (e.g. ``16000`` for ASR pipelines).
+    channels : int, optional
+        Number of audio channels (``1`` = mono, ``2`` = stereo).
+    executor : Executor, optional
+        Custom executor.
+
+    Returns
+    -------
+    FFmpegResult
+    """
+    exe = executor or Executor()
+    args = ["-i", input_path, "-vn"]
+
+    if codec != "copy":
+        args.extend(["-acodec", codec])
+    else:
+        args.extend(["-acodec", "copy"])
+
+    if sample_rate is not None:
+        args.extend(["-ar", str(sample_rate)])
+    if channels is not None:
+        args.extend(["-ac", str(channels)])
+
+    args.append(output_path)
+    return exe.run(args, output_path=output_path)

ff_kit/core/merge.py

@@ -0,0 +1,89 @@
+"""Merge (concatenate) multiple media files."""
+
+from __future__ import annotations
+
+import tempfile
+from pathlib import Path
+
+from ff_kit.executor import Executor, FFmpegResult
+
+
+def merge(
+    input_paths: list[str],
+    output_path: str,
+    *,
+    method: str = "concat_demuxer",
+    executor: Executor | None = None,
+) -> FFmpegResult:
+    """
+    Concatenate multiple media files into one.
+
+    Parameters
+    ----------
+    input_paths : list[str]
+        Ordered list of files to concatenate.
+    output_path : str
+        Destination path for the merged file.
+    method : str
+        ``"concat_demuxer"`` (default, fast, same-codec) or
+        ``"concat_filter"`` (re-encodes, works across formats).
+    executor : Executor, optional
+        Custom executor.
+
+    Returns
+    -------
+    FFmpegResult
+    """
+    if len(input_paths) < 2:
+        raise ValueError("Need at least 2 input files to merge.")
+
+    exe = executor or Executor()
+
+    if method == "concat_demuxer":
+        return _merge_demuxer(exe, input_paths, output_path)
+    elif method == "concat_filter":
+        return _merge_filter(exe, input_paths, output_path)
+    else:
+        raise ValueError(f"Unknown merge method: {method!r}")
+
+
+def _merge_demuxer(
+    exe: Executor, input_paths: list[str], output_path: str
+) -> FFmpegResult:
+    """Fast concat via the concat demuxer (same codec required)."""
+    with tempfile.NamedTemporaryFile(
+        mode="w", suffix=".txt", delete=False
+    ) as f:
+        for p in input_paths:
+            f.write(f"file '{Path(p).resolve()}'\n")
+        list_file = f.name
+
+    args = [
+        "-f", "concat",
+        "-safe", "0",
+        "-i", list_file,
+        "-c", "copy",
+        output_path,
+    ]
+    return exe.run(args, output_path=output_path)
+
+
+def _merge_filter(
+    exe: Executor, input_paths: list[str], output_path: str
+) -> FFmpegResult:
+    """Re-encoding concat via the concat filter (cross-format)."""
+    args: list[str] = []
+    for p in input_paths:
+        args.extend(["-i", p])
+
+    n = len(input_paths)
+    filter_str = "".join(f"[{i}:v][{i}:a]" for i in range(n))
+    filter_str += f"concat=n={n}:v=1:a=1[outv][outa]"
+
+    args.extend([
+        "-filter_complex", filter_str,
+        "-map", "[outv]",
+        "-map", "[outa]",
+        output_path,
+    ])
+    return exe.run(args, output_path=output_path)

ff_kit/core/transcode.py

@@ -0,0 +1,76 @@
+"""Transcode a media file to a different format / codec / resolution."""
+
+from __future__ import annotations
+
+from ff_kit.executor import Executor, FFmpegResult
+
+
+def transcode(
+    input_path: str,
+    output_path: str,
+    *,
+    video_codec: str | None = None,
+    audio_codec: str | None = None,
+    resolution: str | None = None,
+    bitrate: str | None = None,
+    fps: int | None = None,
+    preset: str | None = None,
+    crf: int | None = None,
+    extra_args: list[str] | None = None,
+    executor: Executor | None = None,
+) -> FFmpegResult:
+    """
+    Transcode a media file with full control over codecs and quality.
+
+    Parameters
+    ----------
+    input_path : str
+        Source file.
+    output_path : str
+        Destination file — the container format is inferred from the
+        extension (e.g. ``.mp4``, ``.webm``, ``.mkv``).
+    video_codec : str, optional
+        Video codec (e.g. ``"libx264"``, ``"libx265"``, ``"libvpx-vp9"``).
+    audio_codec : str, optional
+        Audio codec (e.g. ``"aac"``, ``"libopus"``).
+    resolution : str, optional
+        Output resolution as ``"WxH"`` (e.g. ``"1280x720"``).
+    bitrate : str, optional
+        Target bitrate (e.g. ``"2M"``, ``"500k"``).
+    fps : int, optional
+        Output frame rate.
+    preset : str, optional
+        Encoder preset (e.g. ``"fast"``, ``"medium"``, ``"slow"``).
+    crf : int, optional
+        Constant Rate Factor for quality-based encoding (lower = better).
+    extra_args : list[str], optional
+        Any additional ffmpeg arguments.
+    executor : Executor, optional
+        Custom executor.
+
+    Returns
+    -------
+    FFmpegResult
+    """
+    exe = executor or Executor()
+    args = ["-i", input_path]
+
+    if video_codec:
+        args.extend(["-c:v", video_codec])
+    if audio_codec:
+        args.extend(["-c:a", audio_codec])
+    if resolution:
+        args.extend(["-s", resolution])
+    if bitrate:
+        args.extend(["-b:v", bitrate])
+    if fps:
+        args.extend(["-r", str(fps)])
+    if preset:
+        args.extend(["-preset", preset])
+    if crf is not None:
+        args.extend(["-crf", str(crf)])
+    if extra_args:
+        args.extend(extra_args)
+
+    args.append(output_path)
+    return exe.run(args, output_path=output_path)

ff_kit/dispatch.py

@@ -0,0 +1,93 @@
+"""
+Tool-call dispatcher — routes LLM tool calls to ff-kit functions.
+
+Usage::
+
+    from ff_kit.dispatch import dispatch
+
+    # Given a tool call from any LLM provider:
+    result = dispatch("ffkit_clip", {
+        "input_path": "in.mp4",
+        "output_path": "out.mp4",
+        "start": "00:01:00",
+        "duration": "30",
+    })
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from ff_kit.core import clip, merge, extract_audio, add_subtitles, transcode
+from ff_kit.executor import Executor, FFmpegResult
+
+# Map of tool name → (function, set of valid kwargs)
+_REGISTRY: dict[str, tuple[Any, set[str]]] = {
+    "ffkit_clip": (clip, {"input_path", "output_path", "start", "end", "duration"}),
+    "ffkit_merge": (merge, {"input_paths", "output_path", "method"}),
+    "ffkit_extract_audio": (
+        extract_audio,
+        {"input_path", "output_path", "codec", "sample_rate", "channels"},
+    ),
+    "ffkit_add_subtitles": (
+        add_subtitles,
+        {"input_path", "output_path", "subtitle_path", "mode"},
+    ),
+    "ffkit_transcode": (
+        transcode,
+        {
+            "input_path", "output_path", "video_codec", "audio_codec",
+            "resolution", "bitrate", "fps", "preset", "crf", "extra_args",
+        },
+    ),
+}
+
+
+def dispatch(
+    tool_name: str,
+    arguments: dict[str, Any],
+    *,
+    executor: Executor | None = None,
+) -> dict[str, Any]:
+    """
+    Execute an ff-kit tool by name and return a JSON-serialisable result.
+
+    Parameters
+    ----------
+    tool_name : str
+        One of the registered tool names (e.g. ``"ffkit_clip"``).
+    arguments : dict
+        The arguments dict as parsed from the LLM's tool call.
+    executor : Executor, optional
+        Shared executor instance (reuses ffmpeg path / timeout settings).
+
+    Returns
+    -------
+    dict
+        ``{"status": "ok", ...result_fields}`` on success, or
+        ``{"status": "error", "error": "..."}`` on failure.
+    """
+    if tool_name not in _REGISTRY:
+        return {
+            "status": "error",
+            "error": f"Unknown tool: {tool_name!r}. Available: {sorted(_REGISTRY)}",
+        }
+
+    fn, valid_keys = _REGISTRY[tool_name]
+
+    # Filter out any unexpected keys the LLM might hallucinate
+    kwargs = {k: v for k, v in arguments.items() if k in valid_keys}
+
+    if executor is not None:
+        kwargs["executor"] = executor
+
+    try:
+        result: FFmpegResult = fn(**kwargs)
+        return {"status": "ok", **result.to_dict()}
+    except Exception as exc:
+        return {"status": "error", "error": f"{type(exc).__name__}: {exc}"}
+
+
+def list_tools() -> list[str]:
+    """Return the names of all registered tools."""
+    return sorted(_REGISTRY)