videokit 0.1.0__py3-none-any.whl

videokit/__init__.py

@@ -0,0 +1,20 @@
+"""A beginner-friendly Python interface for basic video editing."""
+
+from .audio import Audio, AudioClip
+from .exceptions import FFmpegError, MediaError, VideoKitError
+from .render import RenderSettings
+from .timeline import Timeline
+from .video import Clip, Video
+
+__all__ = [
+    "Audio",
+    "AudioClip",
+    "Clip",
+    "FFmpegError",
+    "MediaError",
+    "RenderSettings",
+    "Timeline",
+    "Video",
+    "VideoKitError",
+]
+__version__ = "0.1.0"

videokit/_ffmpeg.py

@@ -0,0 +1,61 @@
+"""Small, safe wrappers around the FFmpeg command-line tools."""
+
+from __future__ import annotations
+
+import json
+import shutil
+import subprocess
+from pathlib import Path
+from typing import Any
+
+from .exceptions import FFmpegError, MediaError
+
+
+def _tool_path(name: str) -> str:
+    executable = shutil.which(name)
+    if executable is None:
+        raise FFmpegError(
+            f"{name} was not found. Install FFmpeg and make sure its bin folder "
+            "is on your PATH."
+        )
+    return executable
+
+
+def probe(path: Path) -> dict[str, Any]:
+    command = [
+        _tool_path("ffprobe"),
+        "-v",
+        "error",
+        "-show_streams",
+        "-show_format",
+        "-of",
+        "json",
+        str(path),
+    ]
+    try:
+        result = subprocess.run(
+            command, capture_output=True, text=True, check=False
+        )
+    except OSError as error:
+        raise FFmpegError(f"Could not start ffprobe: {error}") from error
+    if result.returncode:
+        details = result.stderr.strip() or "ffprobe could not read this file."
+        raise MediaError(f"Could not read video '{path}': {details}")
+    try:
+        return json.loads(result.stdout)
+    except json.JSONDecodeError as error:
+        raise FFmpegError("ffprobe returned invalid metadata.") from error
+
+
+def run_ffmpeg(command: list[str], output_path: Path) -> None:
+    try:
+        result = subprocess.run(
+            command, capture_output=True, text=True, check=False
+        )
+    except OSError as error:
+        raise FFmpegError(f"Could not start FFmpeg: {error}") from error
+    if result.returncode:
+        details = result.stderr.strip() or "FFmpeg returned an unknown error."
+        raise FFmpegError(
+            f"Could not export '{output_path}': {details}"
+        )

videokit/_vscode.py

@@ -0,0 +1,288 @@
+"""Small JSON helper used by the optional VS Code extension."""
+
+from __future__ import annotations
+
+import ast
+import base64
+import inspect
+import json
+import os
+import sys
+import tempfile
+from pathlib import Path
+from typing import Any
+
+from . import Audio, AudioClip, Clip, Timeline, Video
+from . import __version__
+from .exceptions import VideoKitError
+from .render import RenderSettings
+
+_CLASSES = (Video, Clip, Audio, AudioClip, Timeline, RenderSettings)
+_CLASS_BY_NAME = {item.__name__: item for item in _CLASSES}
+
+
+def _annotation_name(annotation: Any) -> str | None:
+    if annotation is inspect.Signature.empty:
+        return None
+    value = getattr(annotation, "__name__", None)
+    if value:
+        return value
+    text = str(annotation).strip("'\"")
+    return text.split("|", 1)[0].strip().split(".")[-1]
+
+
+def _parameters(callable_object: Any) -> list[dict[str, Any]]:
+    try:
+        signature = inspect.signature(callable_object)
+    except (TypeError, ValueError):
+        return []
+    parameters = []
+    for parameter in signature.parameters.values():
+        if parameter.name in {"self", "cls"}:
+            continue
+        default = None
+        has_default = parameter.default is not inspect.Parameter.empty
+        if has_default:
+            default = repr(parameter.default)
+        parameters.append(
+            {
+                "name": parameter.name,
+                "kind": parameter.kind.name,
+                "type": _annotation_name(parameter.annotation),
+                "has_default": has_default,
+                "default": default,
+            }
+        )
+    return parameters
+
+
+def api_description() -> dict[str, Any]:
+    """Describe the real public methods, docstrings, and signatures."""
+    classes: dict[str, Any] = {}
+    for cls in _CLASSES:
+        methods = {}
+        for name, member in inspect.getmembers(cls, predicate=inspect.isfunction):
+            if name.startswith("_") or member.__module__ != cls.__module__:
+                continue
+            signature = inspect.signature(member)
+            methods[name] = {
+                "parameters": _parameters(member),
+                "return_type": _annotation_name(signature.return_annotation),
+                "documentation": inspect.getdoc(member) or "",
+            }
+        attributes = {
+            name: _annotation_name(annotation)
+            for name, annotation in getattr(cls, "__annotations__", {}).items()
+            if not name.startswith("_")
+        }
+        for name, member in inspect.getmembers(cls, predicate=lambda item: isinstance(item, property)):
+            if not name.startswith("_"):
+                attributes[name] = _annotation_name(member.fget.__annotations__.get("return"))
+        classes[cls.__name__] = {
+            "documentation": inspect.getdoc(cls) or "",
+            "parameters": _parameters(cls),
+            "methods": methods,
+            "attributes": attributes,
+        }
+    return {"version": __version__, "classes": classes}
+
+
+def _expression_type(node: ast.AST, variables: dict[str, str], api: dict[str, Any]) -> str | None:
+    if isinstance(node, ast.Name):
+        return variables.get(node.id)
+    if isinstance(node, ast.Call):
+        if isinstance(node.func, ast.Name):
+            if node.func.id in _CLASS_BY_NAME:
+                return node.func.id
+            alias_type = variables.get(node.func.id)
+            if alias_type in _CLASS_BY_NAME:
+                return alias_type
+        if isinstance(node.func, ast.Attribute):
+            receiver = _expression_type(node.func.value, variables, api)
+            method = api["classes"].get(receiver or "", {}).get("methods", {}).get(
+                node.func.attr
+            )
+            result = method.get("return_type") if method else None
+            return result if result in _CLASS_BY_NAME else None
+    return None
+
+
+def _walk_statements(
+    statements: list[ast.stmt], variables: dict[str, str], api: dict[str, Any]
+) -> None:
+    for statement in statements:
+        if isinstance(statement, ast.ImportFrom) and statement.module == "videokit":
+            for item in statement.names:
+                if item.name in _CLASS_BY_NAME:
+                    variables[item.asname or item.name] = item.name
+        elif isinstance(statement, (ast.Assign, ast.AnnAssign)):
+            targets = statement.targets if isinstance(statement, ast.Assign) else [statement.target]
+            value = _expression_type(statement.value, variables, api) if statement.value else None
+            for target in targets:
+                if isinstance(target, ast.Name):
+                    if value:
+                        variables[target.id] = value
+                    else:
+                        variables.pop(target.id, None)
+        elif isinstance(statement, (ast.FunctionDef, ast.AsyncFunctionDef)):
+            local = dict(variables)
+            _walk_statements(statement.body, local, api)
+        elif isinstance(statement, (ast.For, ast.AsyncFor, ast.While, ast.If, ast.With)):
+            _walk_statements(statement.body, variables, api)
+            _walk_statements(statement.orelse, variables, api)
+
+
+def infer_variables(source: str) -> dict[str, str]:
+    """Infer simple VideoKit variables in valid Python source using the AST."""
+    api = api_description()
+    try:
+        tree = ast.parse(source)
+    except SyntaxError:
+        return {}
+    variables: dict[str, str] = {}
+    _walk_statements(tree.body, variables, api)
+    return variables
+
+
+def infer_expression(expression: str, source: str = "") -> str | None:
+    """Infer a simple VideoKit expression using names found in Python source."""
+    variables = infer_variables(source)
+    try:
+        node = ast.parse(expression, mode="eval").body
+    except SyntaxError:
+        return None
+    return _expression_type(node, variables, api_description())
+
+
+def _python_to_utf16_column(line: str, byte_column: int) -> int:
+    prefix = line.encode("utf-8")[:byte_column].decode("utf-8", errors="ignore")
+    return len(prefix.encode("utf-16-le")) // 2
+
+
+def _video_string_target(
+    source: str, line_number: int, character: int
+) -> tuple[str, dict[str, int]] | None:
+    try:
+        tree = ast.parse(source)
+    except SyntaxError:
+        return None
+
+    video_names = {"Video"}
+    for node in ast.walk(tree):
+        if isinstance(node, ast.ImportFrom) and node.module == "videokit":
+            for alias in node.names:
+                if alias.name == "Video":
+                    video_names.add(alias.asname or alias.name)
+
+    lines = source.splitlines()
+    for node in ast.walk(tree):
+        if not isinstance(node, ast.Call) or not isinstance(node.func, ast.Name):
+            continue
+        if node.func.id not in video_names or not node.args:
+            continue
+        value = node.args[0]
+        if not isinstance(value, ast.Constant) or not isinstance(value.value, str):
+            continue
+        start_line = getattr(value, "lineno", 0)
+        end_line = getattr(value, "end_lineno", start_line)
+        if not start_line <= line_number <= end_line:
+            continue
+        start_column = _python_to_utf16_column(
+            lines[start_line - 1], value.col_offset
+        )
+        end_column = _python_to_utf16_column(
+            lines[end_line - 1], value.end_col_offset
+        )
+        if start_line == end_line and start_column <= character <= end_column:
+            return value.value, {
+                "line": start_line - 1,
+                "start_column": start_column,
+                "end_column": end_column,
+            }
+    return None
+
+
+def preview_at(
+    source: str,
+    source_path: str,
+    workspace_path: str,
+    line: int,
+    character: int,
+) -> dict[str, Any] | None:
+    """Return media details and a small frame for a hovered Video path literal."""
+    target = _video_string_target(source, line, character)
+    if target is None:
+        return None
+    relative_path, location = target
+
+    raw_path = Path(os.path.expandvars(relative_path)).expanduser()
+    if raw_path.is_absolute():
+        media_path = raw_path.resolve()
+    else:
+        candidates = []
+        if workspace_path:
+            candidates.append(Path(workspace_path) / raw_path)
+        if source_path:
+            candidates.append(Path(source_path).parent / raw_path)
+        media_path = next(
+            (candidate.resolve() for candidate in candidates if candidate.is_file()),
+            candidates[0].resolve() if candidates else raw_path.resolve(),
+        )
+
+    try:
+        video = Video(media_path)
+        with tempfile.TemporaryDirectory(prefix="videokit-preview-") as directory:
+            thumbnail_path = Path(directory) / "preview.jpg"
+            video.thumbnail(thumbnail_path, max_width=360, max_height=203)
+            thumbnail = base64.b64encode(thumbnail_path.read_bytes()).decode("ascii")
+    except (OSError, VideoKitError) as error:
+        return {**location, "path": str(media_path), "error": str(error)}
+
+    return {
+        **location,
+        "path": str(video.path),
+        "name": video.path.name,
+        "duration": video.duration,
+        "width": video.width,
+        "height": video.height,
+        "fps": video.fps,
+        "thumbnail": thumbnail,
+    }
+
+
+def main() -> None:
+    """Read one JSON request from stdin and write one JSON response to stdout."""
+    try:
+        request = json.load(sys.stdin)
+        command = request.get("command")
+        if command == "api":
+            response: Any = api_description()
+        elif command == "infer":
+            response = infer_variables(request.get("source", ""))
+        elif command == "infer_expression":
+            response = infer_expression(
+                request.get("expression", ""), request.get("source", "")
+            )
+        elif command == "preview":
+            try:
+                response = preview_at(
+                    request.get("source", ""),
+                    request.get("source_path", ""),
+                    request.get("workspace_path", ""),
+                    int(request.get("line", "-1")),
+                    int(request.get("character", "-1")),
+                )
+            except (OSError, ValueError, VideoKitError) as error:
+                response = {"error": str(error)}
+        else:
+            raise ValueError("Unknown request command.")
+        json.dump(response, sys.stdout)
+        sys.stdout.write("\n")
+    except (OSError, ValueError, TypeError, VideoKitError) as error:
+        json.dump({"error": str(error)}, sys.stdout)
+        sys.stdout.write("\n")
+        raise SystemExit(1) from error
+
+
+if __name__ == "__main__":
+    main()

videokit/audio.py

@@ -0,0 +1,156 @@
+"""Audio metadata and non-destructive audio clips."""
+
+from __future__ import annotations
+
+import math
+import shutil
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any
+
+from ._ffmpeg import probe, run_ffmpeg
+from .exceptions import MediaError
+from .video import _atempo, _check_destination, _seconds
+
+
+@dataclass(frozen=True)
+class AudioClip:
+    """A selected audio range with optional volume, speed, and fades."""
+
+    _source: Path
+    start: float
+    end: float
+    _speed: float = 1
+    _volume: float = 1
+    _filters: tuple[str, ...] = ()
+
+    @property
+    def duration(self) -> float:
+        """Playback duration in seconds."""
+        return (self.end - self.start) / self._speed
+
+    def speed(self, factor: float) -> AudioClip:
+        """Change playback speed by a positive multiplier without pitch correction."""
+        value = _seconds(factor, "factor")
+        if value <= 0 or value > 100:
+            raise ValueError("factor must be greater than 0 and no more than 100.")
+        return AudioClip(
+            self._source, self.start, self.end,
+            self._speed * value, self._volume, self._filters,
+        )
+
+    def volume(self, level: float) -> AudioClip:
+        """Set volume from 0 (silent) to 4 (four times as loud)."""
+        value = _seconds(level, "level")
+        if not 0 <= value <= 4:
+            raise ValueError("level must be between 0 and 4.")
+        return AudioClip(
+            self._source, self.start, self.end, self._speed, value, self._filters
+        )
+
+    def fade_in(self, duration: float) -> AudioClip:
+        """Fade audio in from silence."""
+        seconds = _seconds(duration, "duration")
+        if seconds <= 0 or seconds > self.duration:
+            raise ValueError("duration must be positive and no longer than the clip.")
+        return AudioClip(
+            self._source, self.start, self.end, self._speed, self._volume,
+            self._filters + (f"afade=t=in:st=0:d={seconds:.9g}",),
+        )
+
+    def fade_out(self, duration: float) -> AudioClip:
+        """Fade audio out at the end of the clip."""
+        seconds = _seconds(duration, "duration")
+        if seconds <= 0 or seconds > self.duration:
+            raise ValueError("duration must be positive and no longer than the clip.")
+        start = self.duration - seconds
+        return AudioClip(
+            self._source, self.start, self.end, self._speed, self._volume,
+            self._filters + (f"afade=t=out:st={start:.9g}:d={seconds:.9g}",),
+        )
+
+    def export(
+        self, output_path: str | Path, *, overwrite: bool = False
+    ) -> Path:
+        """Export this selection as AAC, MP3, or PCM audio based on its extension."""
+        destination = _check_destination(output_path, self._source, overwrite)
+        command = [
+            shutil.which("ffmpeg") or "ffmpeg",
+            "-hide_banner",
+            "-loglevel",
+            "error",
+            "-y" if overwrite else "-n",
+            "-ss",
+            f"{self.start:.9f}",
+            "-t",
+            f"{self.end - self.start:.9f}",
+            "-i",
+            str(self._source),
+            "-vn",
+        ]
+        filters = [*_atempo(self._speed), f"volume={self._volume:.9g}"]
+        filters.extend(self._filters)
+        command.extend(["-af", ",".join(filters)])
+        suffix = destination.suffix.lower()
+        if suffix == ".wav":
+            command.extend(["-c:a", "pcm_s16le"])
+        elif suffix == ".mp3":
+            command.extend(["-c:a", "libmp3lame"])
+        else:
+            command.extend(["-c:a", "aac"])
+        command.append(str(destination))
+        run_ffmpeg(command, destination)
+        return destination
+
+
+class Audio:
+    """An audio file with basic metadata and time-range selection."""
+
+    path: Path
+    duration: float
+    codec: str | None
+    sample_rate: int | None
+    channels: int | None
+
+    def __init__(self, path: str | Path) -> None:
+        self.path = Path(path).expanduser().resolve()
+        if not self.path.is_file():
+            raise MediaError(f"Audio file does not exist: '{self.path}'.")
+        metadata = probe(self.path)
+        streams: list[dict[str, Any]] = metadata.get("streams", [])
+        stream = next(
+            (item for item in streams if item.get("codec_type") == "audio"), None
+        )
+        if stream is None:
+            raise MediaError(f"No audio stream was found in '{self.path}'.")
+        duration_value = stream.get("duration") or metadata.get("format", {}).get(
+            "duration"
+        )
+        try:
+            self.duration = float(duration_value)
+        except (TypeError, ValueError) as error:
+            raise MediaError(f"Audio duration is unavailable for '{self.path}'.") from error
+        if not math.isfinite(self.duration) or self.duration <= 0:
+            raise MediaError(f"Audio duration is invalid for '{self.path}'.")
+        self.codec = stream.get("codec_name")
+        try:
+            self.sample_rate = (
+                int(stream["sample_rate"]) if stream.get("sample_rate") else None
+            )
+            self.channels = int(stream["channels"]) if stream.get("channels") else None
+        except (TypeError, ValueError) as error:
+            raise MediaError(f"Audio metadata is invalid for '{self.path}'.") from error
+
+    def cut(self, start: float, end: float) -> AudioClip:
+        """Select audio from ``start`` up to (but not including) ``end`` seconds."""
+        first = _seconds(start, "start")
+        last = _seconds(end, "end")
+        if first < 0:
+            raise ValueError("start cannot be negative.")
+        if last <= first:
+            raise ValueError("end must be greater than start.")
+        if last > self.duration:
+            raise ValueError(
+                f"end ({last:g}s) exceeds audio duration ({self.duration:g}s)."
+            )
+        return AudioClip(self.path, first, last)

videokit/exceptions.py

@@ -0,0 +1,13 @@
+"""Exceptions raised by VideoKit."""
+
+
+class VideoKitError(Exception):
+    """Base exception for VideoKit errors."""
+
+
+class MediaError(VideoKitError):
+    """Raised when a media file is missing, invalid, or unsupported."""
+
+
+class FFmpegError(VideoKitError):
+    """Raised when FFmpeg cannot complete a requested operation."""

videokit/render.py

@@ -0,0 +1,51 @@
+"""Output-quality choices shared by final video renders."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Literal
+
+Quality = Literal["draft", "balanced", "high"]
+
+_QUALITY_SETTINGS: dict[Quality, tuple[str, int]] = {
+    "draft": ("veryfast", 28),
+    "balanced": ("medium", 22),
+    "high": ("slow", 18),
+}
+
+
+@dataclass(frozen=True)
+class RenderSettings:
+    """Simple, reusable quality settings for final video output.
+
+    ``draft`` renders faster with lower image quality; ``balanced`` is the
+    everyday default; ``high`` prioritizes image quality at the cost of longer
+    render time and larger files.
+
+    Example:
+        settings = RenderSettings(quality="high")
+        timeline.export("final.mp4", settings=settings)
+        timeline.render("quick-check.mp4", quality="draft")
+    """
+
+    quality: Quality = "balanced"
+
+    def __post_init__(self) -> None:
+        if not isinstance(self.quality, str) or self.quality not in _QUALITY_SETTINGS:
+            choices = ", ".join(_QUALITY_SETTINGS)
+            raise ValueError(f"quality must be one of: {choices}.")
+
+    @property
+    def preset(self) -> str:
+        """FFmpeg x264 speed preset selected for this quality level."""
+        return _QUALITY_SETTINGS[self.quality][0]
+
+    @property
+    def crf(self) -> int:
+        """FFmpeg constant-rate-factor value; lower means higher quality."""
+        return _QUALITY_SETTINGS[self.quality][1]
+
+    @property
+    def audio_bitrate(self) -> str:
+        """AAC bitrate used for final renders."""
+        return "192k"