videopython

https://videopython.com
Admin
videopython is a minimal, LLM-friendly Python library for programmatic video editing, processing,...
Tokens:214,134
Snippets:1,224
Trust Score:4.6
Update:2 months ago
Show doc for...
Tokens:
Raw
### Install and start the MCP server

Source: https://videopython.com/how-to/mcp-server

Commands to install the package, start the local vision model service, and launch the MCP server.

```bash
pip install "videopython[ai,mcp]"
ollama serve              # scene captioning still uses a local vision model
ollama pull qwen3.6:27b
videopython-mcp           # stdio server
```

--------------------------------

### Install videopython package

Source: https://videopython.com/install

Install the core library or specific extras using pip or uv.

```bash
pip install videopython             # core editing, no ML dependencies
pip install "videopython[ai]"       # + every AI capability
pip install "videopython[ai,mcp]"   # + the videopython-mcp server

uv add videopython                  # or with uv
uv add videopython --extra ai
```

--------------------------------

### Install videopython

Source: https://videopython.com/

Installation commands for core functionality, AI features, and MCP server support.

```bash
pip install videopython              # core editing
pip install "videopython[ai]"        # + all local AI features (GPU recommended)
pip install "videopython[ai,mcp]"    # + the MCP server
```

--------------------------------

### Install FFmpeg

Source: https://videopython.com/install

Install the required FFmpeg dependency for video decoding and encoding.

```bash
brew install ffmpeg                 # macOS
sudo apt-get install ffmpeg         # Ubuntu / Debian
choco install ffmpeg                # Windows (Chocolatey)
```

--------------------------------

### Start Ollama server

Source: https://videopython.com/install

Initialize the local Ollama daemon and pull the required vision model for LLM-backed features.

```bash
ollama serve                # start the local daemon
ollama pull qwen3.6:27b     # the default vision / translation model
```

--------------------------------

### Initialize VideoAnalysisConfig

Source: https://videopython.com/reference/ai/video-analysis

Example of configuring analyzer parameters by forwarding keyword arguments to specific predictor constructors.

```python
VideoAnalysisConfig(
    analyzer_params={
        "audio_to_text": {"model_name": "large"},
        "scene_vlm": {"model": "qwen3.6:27b"},
    }
)
```

--------------------------------

### Verify installation

Source: https://videopython.com/install

Check if FFmpeg and videopython are correctly configured by reading video metadata.

```python
from videopython.base import Video, VideoMetadata

print(VideoMetadata.from_path("some_video.mp4"))
```

--------------------------------

### Manipulate Video Objects

Source: https://videopython.com/reference/video

Examples of loading, concatenating, modifying audio, and saving video files using the Video class.

```python
from videopython.base import Video

video = Video.from_path("input.mp4")
video = Video.from_path("input.mp4", start_second=10, end_second=20)   # bounded load

import numpy as np
video = Video.from_image(np.zeros((1080, 1920, 3), dtype=np.uint8), fps=24, length_seconds=3.0)

combined = video_a + video_b        # concat; requires matching fps and dimensions

video = video.add_audio_from_file("music.mp3")               # overlays existing audio
video = video.add_audio_from_file("narration.mp3", overlay=False)   # replaces it

video.save("output.mp4")
video.save("output.webm", format="webm")     # mp4 | avi | mov | mkv | webm
video.save("output.mp4", preset="slow", crf=18)
```

--------------------------------

### Initialize and execute a VideoEdit plan

Source: https://videopython.com/reference/video-edit

Create a VideoEdit instance from a dictionary, validate the plan, and render the output to a file.

```python
from videopython.editing import VideoEdit

edit = VideoEdit.from_dict({
    "segments": [
        {
            "source": "input.mp4",
            "start": 5.0,
            "end": 12.0,
            "operations": [
                {"op": "crop", "width": 0.5, "height": 1.0, "mode": "center"},
                {"op": "resize", "width": 1080, "height": 1920},
                {"op": "blur_effect", "mode": "constant", "iterations": 1,
                 "window": {"start": 0.0, "stop": 1.0}},
            ],
        },
        {"source": "input.mp4", "start": 20.0, "end": 28.0},
    ],
    "post_operations": [{"op": "color_adjust", "brightness": 0.05}],
})

predicted = edit.validate()
edit.run_to_file("output.mp4", crf=20, preset="medium")
```

--------------------------------

### Video.__init__

Source: https://videopython.com/reference/video

Initializes a new Video instance with frames, frame rate, and optional audio.

```APIDOC
## __init__(frames: ndarray, fps: int | float, audio: Audio | None = None)

### Description
Initializes a new Video object. If no audio is provided, a silent audio track is generated based on the video duration.

### Parameters
- **frames** (ndarray) - Required - The video frames as a numpy array.
- **fps** (int | float) - Required - The frames per second of the video.
- **audio** (Audio | None) - Optional - The audio track associated with the video.
```

--------------------------------

### Get Video Shape

Source: https://videopython.com/reference/video

Returns the full shape of the video.

```python
def get_video_shape(self) -> np.ndarray:
    """Returns video shape."""
    return np.array((self.frame_count, self.height, self.width, 3))
```

--------------------------------

### Get Frame Shape

Source: https://videopython.com/reference/video

Returns the shape of the video frames.

```python
def get_frame_shape(self) -> np.ndarray:
    """Returns frame shape."""
    return np.array((self.height, self.width, 3))
```

--------------------------------

### Audio.__init__

Source: https://videopython.com/reference/audio

Initializes a new Audio object with provided data and metadata.

```APIDOC
## __init__(data: ndarray, metadata: AudioMetadata)

### Description
Initialize a new Audio object.

### Parameters
- **data** (ndarray) - Required - Audio data as numpy array, normalized between -1 and 1.
- **metadata** (AudioMetadata) - Required - AudioMetadata object containing audio properties.
```

--------------------------------

### FaceSmoothingTracker.reset

Source: https://videopython.com/reference/ai/understanding

Resets the internal state of the tracker, useful when starting a new video.

```APIDOC
## reset()

### Description
Resets the tracker state, clearing last position and smoothed position data for a new video sequence.
```

--------------------------------

### Get Audio Length

Source: https://videopython.com/reference/audio

Returns the total number of samples in the audio object.

```python
def __len__(self) -> int:
    """Returns the number of samples"""
    return self.metadata.frame_count
```

--------------------------------

### Manual catalog and plan resolution

Source: https://videopython.com/how-to/auto-editing

Demonstrates how to manually build a catalog from analyses and resolve a custom EditPlan.

```python
from videopython.ai import VideoAnalyzer, build_catalog
from videopython.ai.auto_edit import EditPlan, resolve_plan

analyses = [VideoAnalyzer().analyze_path("a.mp4")]
bundle = build_catalog(analyses)                 # bundle.catalog + bundle.keyframes

plan = EditPlan.model_validate({"segments": [{"scene_id": bundle.catalog.scenes[0].id}]})
edit = resolve_plan(plan, bundle.catalog)        # -> VideoEdit
edit.run_to_file("out.mp4")
```

--------------------------------

### Effect constructor examples

Source: https://videopython.com/reference/effects

Common effect constructors available in the videopython.editing module.

```python
from videopython.base import BoundingBox
from videopython.editing import (
    Blur, ChromaticAberration, ColorGrading, Fade, FilmGrain, Flash, Glitch,
    Kaleidoscope, KenBurns, MirrorFlip, Pixelate, PunchIn, Shake, Sharpen,
    TextOverlay, TimeRange, Vignette, VolumeAdjust, Zoom,
)

Zoom(zoom_factor=1.5, mode="in")
ColorGrading(brightness=0.1, contrast=1.2, saturation=1.1)
Vignette(strength=0.5, radius=0.8)
KenBurns(start_region=BoundingBox(x=0.0, y=0.0, width=0.5, height=0.5),
         end_region=BoundingBox(x=0.5, y=0.5, width=0.5, height=0.5),
         easing="ease_in_out")

Fade(mode="in", duration=1.0)
VolumeAdjust(volume=0.0, window=TimeRange(stop=2.0))          # mute the first 2s
TextOverlay(text="Hello World", position=(0.5, 0.9), font_size=48)

Shake(intensity_px=6, mode="rhythmic", frequency_hz=4)
PunchIn(zoom_factor=1.5, attack_frames=3, release_frames=0)
Flash(color=(255, 255, 255), peak_alpha=1.0, attack_frames=2, decay_frames=4,
      window=TimeRange(start=1.0, stop=1.3))
ChromaticAberration(shift_px=4, mode="radial")
Glitch(intensity=0.4, slice_count=12, seed=42)
FilmGrain(intensity=0.08, monochrome=True)
Sharpen(amount=1.0, kernel_size=5)
Pixelate(block_size=24, region=BoundingBox(x=0.4, y=0.2, width=0.2, height=0.2))
MirrorFlip(mode="mirror_left")
Kaleidoscope(segments=6)
```

--------------------------------

### Execute a video edit plan loop

Source: https://videopython.com/how-to/llm-plans

Demonstrates the basic workflow of generating a plan from a schema and executing it using VideoEdit.

```python
from videopython.editing import VideoEdit

schema = VideoEdit.json_schema()
plan = call_your_llm(schema=schema, prompt="Create a 15s highlight reel from input.mp4")

edit = VideoEdit.from_dict(plan)
edit.validate()                 # dry run over metadata; no frames touched
edit.run_to_file("output.mp4")
```

--------------------------------

### Initialize Audio Object

Source: https://videopython.com/reference/audio

Constructor for the Audio class.

```python
__init__(data: ndarray, metadata: AudioMetadata)
```

```python
def __init__(self, data: np.ndarray, metadata: AudioMetadata):
    """
    Initialize Audio object

    Args:
        data: Audio data as numpy array, normalized between -1 and 1
        metadata: AudioMetadata object containing audio properties
    """
    self.data = data
    self.metadata = metadata
```

--------------------------------

### Get segments by speaker

Source: https://videopython.com/reference/ai/dubbing

Groups translated segments into a dictionary keyed by speaker ID.

```python
def get_segments_by_speaker(self) -> dict[str, list[TranslatedSegment]]:
    """Group translated segments by speaker.

    Returns:
        Dictionary mapping speaker IDs to their segments.
    """
    segments_by_speaker: dict[str, list[TranslatedSegment]] = {}
    for segment in self.translated_segments:
        speaker = segment.speaker or "unknown"
        if speaker not in segments_by_speaker:
            segments_by_speaker[speaker] = []
        segments_by_speaker[speaker].append(segment)
    return segments_by_speaker
```

--------------------------------

### Normalize Audio Methods

Source: https://videopython.com/reference/audio

Examples of normalizing audio using peak or RMS methods.

```python
normalized = audio.normalize(target_db=-3.0, method="peak")     # default
normalized = audio.normalize(target_db=-18.0, method="rms")
```

--------------------------------

### Initialize Video Instance

Source: https://videopython.com/reference/video

Constructor for the Video class, which handles frame data, frame rate, and optional audio.

```python
__init__(
    frames: ndarray,
    fps: int | float,
    audio: Audio | None = None,
)
```

```python
def __init__(self, frames: np.ndarray, fps: int | float, audio: Audio | None = None):
    self.frames = frames
    self.fps = fps
    if audio:
        self.audio = audio
    else:
        self.audio = Audio.create_silent(
            duration_seconds=round(self.total_seconds, 2), stereo=True, sample_rate=44100
        )
```

--------------------------------

### Filtering Operations by Category

Source: https://videopython.com/reference/operations

Example of filtering the registry to retrieve only operations belonging to a specific category.

```python
transforms = {k: v for k, v in Operation.registry().items()
              if v.category is OpCategory.TRANSFORM}
```

--------------------------------

### VideoAnalyzer.__init__

Source: https://videopython.com/reference/ai/video-analysis

Initializes the VideoAnalyzer with an optional configuration and a sampling preset.

```APIDOC
## __init__(config: VideoAnalysisConfig | None = None, *, sampling: SamplingPreset = DEFAULT_SAMPLING_PRESET)

### Description
Initializes the analyzer. The `sampling` parameter controls the aggressiveness of frame sampling per scene (e.g., 'low', 'medium', 'high').

### Parameters
- **config** (VideoAnalysisConfig | None) - Optional - Configuration object for the analyzer.
- **sampling** (SamplingPreset) - Optional - Preset defining frame sampling behavior.
```

--------------------------------

### Audio.slice(start_seconds, end_seconds)

Source: https://videopython.com/reference/audio

Extracts a specific portion of the audio based on start and end time markers.

```APIDOC
## slice(start_seconds: float = 0.0, end_seconds: float | None = None) -> Audio

### Description
Extract a portion of the audio between start_seconds and end_seconds.

### Parameters
- **start_seconds** (float) - Optional - Start time in seconds (default: 0.0)
- **end_seconds** (float | None) - Optional - End time in seconds (default: None, meaning end of audio)

### Returns
- **Audio** - New Audio instance with the extracted portion

### Raises
- **ValueError** - If start_seconds or end_seconds are invalid
```

--------------------------------

### __init__

Source: https://videopython.com/reference/ai/understanding

Initializes the FaceShotTracker instance with configuration parameters for face detection and tracking.

```APIDOC
## __init__(min_face_size: int = 30, batch_size: int = 16, iou_match_threshold: float = DEFAULT_IOU_MATCH_THRESHOLD, max_missed_frames: int = DEFAULT_MAX_MISSED_FRAMES)

### Description
Initializes the per-shot tracker with specific thresholds for face detection and tracking logic.

### Parameters
- **min_face_size** (int) - Optional - Minimum face size in pixels for detection. Default is 30.
- **batch_size** (int) - Optional - Batch size for detection. Default is 16.
- **iou_match_threshold** (float) - Optional - Minimum IoU between consecutive detections to continue an existing track.
- **max_missed_frames** (int) - Optional - Consecutive frames a track may go without a detection before it is closed.
```

--------------------------------

### Add audio from file

Source: https://videopython.com/reference/video

Loads an audio file from a path and adds it to the video instance.

```python
def add_audio_from_file(self, path: str, overlay: bool = True) -> Video:
    """Add audio from file, returning a new Video instance.

    Args:
        path: Path to audio file
        overlay: If True, overlay on existing audio; if False, replace it

    Returns:
        New Video with the audio added

    Raises:
        AudioLoadError: If audio file cannot be loaded
        FileNotFoundError: If audio file does not exist
    """
    new_audio = Audio.from_path(path)
    return self.add_audio(new_audio, overlay)
```

--------------------------------

### ObjectDetectionOverlay JSON Configuration

Source: https://videopython.com/reference/ai/operations

Example of the JSON structure used for configuring the overlay effect in an LLM-exposed plan.

```json
{"op": "object_detection_overlay", "class_filter": ["person", "car", "dog"],
 "confidence_threshold": 0.4, "detection_interval": 2,
 "window": {"start": 0, "stop": 5}}
```

--------------------------------

### Load audio from file using from_path

Source: https://videopython.com/reference/audio

This class method loads audio from a specified file path, converts it to WAV format via ffmpeg, and returns an initialized Audio instance.

```python
@classmethod
def from_path(cls, file_path: str | Path) -> Audio:
    """
    Load audio from a file using ffmpeg

    Args:
        file_path: Path to the audio file

    Returns:
        Audio: New Audio instance

    Raises:
        FileNotFoundError: If the file doesn't exist
        AudioLoadError: If there's an error loading the audio
    """
    file_path = Path(file_path)
    if not file_path.exists():
        raise FileNotFoundError(f"File not found: {file_path}")

    # Get audio info
    info = cls._get_ffmpeg_info(file_path)

    # Convert to WAV using ffmpeg
    cmd = [
        "ffmpeg",
        "-i",
        str(file_path),
        "-f",
        "wav",
        "-ar",
        str(info["sample_rate"]),  # sample rate
        "-ac",
        str(info["channels"]),  # channels
        "-bits_per_raw_sample",
        str(info["bit_depth"]),
        "-",  # Output to stdout
    ]

    try:
        process = subprocess.Popen(cmd, stdout=subprocess.PIPE, stderr=subprocess.PIPE)
        wav_data, stderr = process.communicate()

        if process.returncode != 0:
            raise AudioLoadError(f"FFmpeg error: {stderr.decode()}")

        # Read WAV data
        with io.BytesIO(wav_data) as wav_io:
            with wave.open(wav_io, "rb") as wav_file:
                # Get WAV metadata
                sample_width = wav_file.getsampwidth()
                channels = wav_file.getnchannels()
                sample_rate = wav_file.getframerate()
                n_frames = wav_file.getnframes()

                # Read raw audio data
                raw_data = wav_file.readframes(n_frames)

                # Convert bytes to numpy array based on sample width
                dtype_map = {1: np.int8, 2: np.int16, 4: np.int32}
                dtype = dtype_map.get(sample_width)
                if dtype is None:
                    raise AudioLoadError(f"Unsupported sample width: {sample_width}")

                # Explicitly annotated: numpy>=2.5 shape-types ndarray, so the
                # 1-D frombuffer result cannot be rebound to a 2-D view below.
                data: np.ndarray[Any, np.dtype[np.float32]]
                data = np.frombuffer(raw_data, dtype=dtype).astype(np.float32)

                # Reshape to (frames, channels) if stereo
                if channels == 2:
                    data = data.reshape(-1, 2)

                # Normalize to float between -1 and 1
                max_value = float(np.iinfo(dtype).max)  # type: ignore
                data = data / max_value

                # Ensure normalization is within bounds due to floating point precision
                data = np.clip(data, -1.0, 1.0)

                # Calculate frame count from actual data length
                # For stereo, len(data) is already correct after reshape
                frame_count = len(data)

                metadata = AudioMetadata(
                    sample_rate=sample_rate,
                    channels=channels,
                    sample_width=sample_width,
                    duration_seconds=info["duration"],
                    frame_count=frame_count,
                )

                return cls(data, metadata)

    except subprocess.CalledProcessError as e:
        raise AudioLoadError(f"Error running ffmpeg: {e}")
```

--------------------------------

### Create an AI-generated video assembly

Source: https://videopython.com/how-to/ai-generated-video

Demonstrates the full pipeline of generating scenes with images, video, and audio, then assembling them into a single file with crossfade transitions.

```python
from pathlib import Path

from videopython.ai import TextToImage, ImageToVideo, TextToSpeech
from videopython.base.video import VideoMetadata
from videopython.editing import VideoEdit, SegmentConfig, TransitionSpec, Resize


def create_ai_video(output_path: str, workdir: str = "scenes") -> None:
    scenes = [
        {"image_prompt": "A serene mountain landscape at sunrise, photorealistic",
         "narration": "In the mountains, every sunrise brings new possibilities."},
        {"image_prompt": "A flowing river through a forest, cinematic lighting",
         "narration": "Nature flows with endless energy and grace."},
        {"image_prompt": "A starry night sky over a calm lake, dramatic",
         "narration": "And when night falls, the universe reveals its wonders."},
    ]

    image_gen, video_gen, speech_gen = TextToImage(), ImageToVideo(), TextToSpeech()

    Path(workdir).mkdir(parents=True, exist_ok=True)
    scene_paths = []
    for i, scene in enumerate(scenes):
        image = image_gen.generate_image(scene["image_prompt"])
        video = video_gen.generate_video(image=image)
        audio = speech_gen.generate_audio(scene["narration"])
        path = f"{workdir}/scene_{i}.mp4"
        video.add_audio(audio).save(path)
        scene_paths.append(path)

    # One segment per scene. Resize standardizes to 1080p; a 1s dissolve crossfades
    # each follow-on scene in (the first has no predecessor, so it carries none).
    segments = []
    for i, path in enumerate(scene_paths):
        meta = VideoMetadata.from_path(path)
        segments.append(SegmentConfig(
            source=path,
            start=0,
            end=meta.total_seconds,
            operations=[Resize(width=1920, height=1080)],
            transition_in=None if i == 0 else TransitionSpec(type="dissolve", duration=1.0),
        ))

    VideoEdit(segments=segments).run_to_file(output_path)


create_ai_video("ai_generated.mp4")
```

--------------------------------

### Get Audio Representation

Source: https://videopython.com/reference/audio

Returns a string representation of the Audio object including channels, sample rate, and duration.

```python
def __repr__(self) -> str:
    """String representation of the Audio object"""
    return (
        f"Audio(channels={self.metadata.channels}, "
        f"sample_rate={self.metadata.sample_rate}Hz, "
        f"duration={self.metadata.duration_seconds:.2f}s)"
    )
```

--------------------------------

### Initialize internal models

Source: https://videopython.com/reference/ai/understanding

Methods for loading Whisper, pyannote diarization, and Silero VAD models.

```python
def _init_local(self) -> None:
    """Initialize local Whisper model."""
    from videopython.ai._optional import require

    whisper = require("whisper", feature="AudioToText")

    # No revision pin: openai-whisper downloads weights by name from OpenAI's
    # own CDN, not via a HF from_pretrained repo, so there is no HF commit
    # SHA to pin (see videopython.ai._revisions module docstring).
    self._model = whisper.load_model(name=self.model_name, device=self.device)
```

```python
def _init_diarization(self) -> None:
    """Initialize pyannote speaker diarization pipeline."""
    import torch

    from videopython.ai._optional import require

    Pipeline = require("pyannote.audio", feature="AudioToText diarization").Pipeline

    self._diarization_pipeline = Pipeline.from_pretrained(
        self.PYANNOTE_DIARIZATION_MODEL, revision=pinned(self.PYANNOTE_DIARIZATION_MODEL)
    )
    self._diarization_pipeline.to(torch.device(self.device))
```

```python
def _init_vad(self) -> None:
    """Initialize Silero VAD model.

    The model is ~2 MB and CPU-fast (~5-15s for a 90 min movie); we keep
    it on CPU regardless of ``self.device`` since dispatch overhead would
    outweigh inference cost.
    """
    from videopython.ai._optional import require

    load_silero_vad = require("silero_vad", feature="AudioToText VAD").load_silero_vad

    self._vad_model = load_silero_vad()
```

--------------------------------

### Define an Effect with Windowing

Source: https://videopython.com/reference/operations

Example of an effect configuration using a time window to restrict the operation to a specific segment.

```json
{"op": "blur_effect", "mode": "constant", "iterations": 2,
 "window": {"start": 1.0, "stop": 3.0}}
```

--------------------------------

### Integrate VideoEdit with LLM tool calling

Source: https://videopython.com/how-to/llm-plans

Examples of passing the VideoEdit schema as a tool to Anthropic and OpenAI models.

```python
import anthropic
from videopython.editing import VideoEdit

client = anthropic.Anthropic()

response = client.messages.create(
    model="claude-sonnet-5",
    max_tokens=1024,
    tools=[{
        "name": "create_video_edit",
        "description": "Create a video editing plan",
        "input_schema": VideoEdit.json_schema(),
    }],
    messages=[{"role": "user", "content":
               "Cut input.mp4 to the first 10 seconds, resize to 1080x1920, fade in."}],
)

tool_block = next(b for b in response.content if b.type == "tool_use")
edit = VideoEdit.from_dict(tool_block.input)
edit.validate()
edit.run_to_file("output.mp4")
```

```python
import json
from openai import OpenAI
from videopython.editing import VideoEdit

client = OpenAI()

response = client.chat.completions.create(
    model="gpt-4o",
    messages=[
        {"role": "system", "content": "You are a video editor."},
        {"role": "user", "content":
         "Cut input.mp4 to the first 10 seconds, resize to 1080x1920, fade in."},
    ],
    tools=[{
        "type": "function",
        "function": {
            "name": "create_video_edit",
            "description": "Create a video editing plan",
            "parameters": VideoEdit.json_schema(),
        },
    }],
)

plan = json.loads(response.choices[0].message.tool_calls[0].function.arguments)
edit = VideoEdit.from_dict(plan)
edit.validate()
edit.run_to_file("output.mp4")
```

--------------------------------

### Slice Audio Data

Source: https://videopython.com/reference/audio

Extracts a specific segment of audio based on start and end times, updating metadata accordingly.

```python
        if end_seconds is not None:
            if end_seconds < start_seconds:
                raise ValueError("end_seconds must be greater than start_seconds")
            if end_seconds > duration_seconds + duration_tolerance:
                raise ValueError("end_seconds cannot exceed audio duration")
            end_seconds = min(end_seconds, duration_seconds)
        else:
            end_seconds = duration_seconds

        # Convert seconds to sample indices
        start_idx = int(start_seconds * self.metadata.sample_rate)
        end_idx = int(end_seconds * self.metadata.sample_rate)

        # Extract the portion of audio data
        sliced_data = self.data[start_idx:end_idx]

        # Calculate new duration
        new_duration = (end_idx - start_idx) / self.metadata.sample_rate

        # Create new metadata
        new_metadata = AudioMetadata(
            sample_rate=self.metadata.sample_rate,
            channels=self.metadata.channels,
            sample_width=self.metadata.sample_width,
            duration_seconds=new_duration,
            frame_count=len(sliced_data) if self.metadata.channels == 1 else len(sliced_data),
        )

        return Audio(sliced_data, new_metadata)
```

--------------------------------

### Cataloging and Resolving Video Edits

Source: https://videopython.com/reference/ai/auto-edit

Demonstrates how to build a catalog from video analysis and resolve an EditPlan into a runnable VideoEdit.

```python
from videopython.ai import VideoAnalyzer, build_catalog
from videopython.ai.auto_edit import EditPlan, resolve_plan

analyses = [VideoAnalyzer().analyze_path("a.mp4")]
bundle = build_catalog(analyses)              # bundle.catalog + bundle.keyframes

plan = EditPlan.model_validate({"segments": [{"scene_id": bundle.catalog.scenes[0].id}]})
edit = resolve_plan(plan, bundle.catalog)     # -> VideoEdit
```

--------------------------------

### TranscriptionSegment.from_words

Source: https://videopython.com/reference/transcription

Creates a new TranscriptionSegment instance from a list of TranscriptionWord objects, automatically deriving start, end, and text properties.

```APIDOC
## TranscriptionSegment.from_words

### Description
Builds a segment spanning the provided words, deriving start, end, and text from them. The words list is copied to prevent aliasing.

### Parameters
- **words** (list[TranscriptionWord]) - Required - A non-empty list of words.
- **speaker** (str | None) - Optional - Speaker identifier.
- **avg_logprob** (float | None) - Optional - Average log probability.
- **no_speech_prob** (float | None) - Optional - Probability of no speech.
- **compression_ratio** (float | None) - Optional - Compression ratio.
```

--------------------------------

### Configure and Run Video Analysis

Source: https://videopython.com/reference/ai/video-analysis

Initializes the VideoAnalyzer with specific enabled analyzers and custom parameters for models.

```python
from videopython.ai import VideoAnalysisConfig, VideoAnalyzer

config = VideoAnalysisConfig(
    enabled_analyzers={"audio_to_text", "semantic_scene_detector", "scene_vlm", "face_tracker"},
    analyzer_params={
        "scene_vlm": {"model": "qwen3.6:27b"},
        "audio_to_text": {"model_name": "large", "vocabulary": ["Klarna", "Allegro"]},
    },
)
analysis = VideoAnalyzer(config=config, sampling="medium").analyze_path("video.mp4")
```

--------------------------------

### Slice Transcription by Time

Source: https://videopython.com/reference/transcription

Extracts a subset of a transcription based on a start and end time, reconstructing segments from overlapping words.

```python
def slice(self, start: float, end: float) -> Transcription | None:
        """Return a new Transcription containing only words within the time range.

        Slices at word-level granularity: words that overlap with the time range
        are included, and new segments are reconstructed from the included words.

        Args:
            start: Start time in seconds (inclusive)
            end: End time in seconds (exclusive)

        Returns:
            New Transcription with words/segments in the time range, or None if no words overlap
        """
        if start >= end:
            return None

        # Collect all words that overlap with the time range
        overlapping_words: list[TranscriptionWord] = []
        for segment in self.segments:
            for word in segment.words:
                # Include word if it overlaps with our time range
                if word.end > start and word.start < end:
                    overlapping_words.append(word)

        if not overlapping_words:
            return None

        # Reconstruct segments from the overlapping words
        # Group consecutive words by speaker to form segments
        sliced_segments: list[TranscriptionSegment] = []
        current_speaker = overlapping_words[0].speaker
        current_words: list[TranscriptionWord] = []

        for word in overlapping_words:
            if word.speaker == current_speaker:
                current_words.append(word)
            else:
                # Finish current segment (speaker is ambiguous across the
                # original segments these words came from -- confidence omitted)
                if current_words:
                    sliced_segments.append(TranscriptionSegment.from_words(current_words, speaker=current_speaker))
                # Start new segment
                current_speaker = word.speaker
                current_words = [word]
```

--------------------------------

### Add audio from file

Source: https://videopython.com/reference/video

Loads audio from a file path and adds it to the video instance.

```python
def add_audio_from_file(self, path: str, overlay: bool = True) -> Video:
        """Add audio from file, returning a new Video instance.

        Args:
            path: Path to audio file
            overlay: If True, overlay on existing audio; if False, replace it

        Returns:
            New Video with the audio added

        Raises:
            AudioLoadError: If audio file cannot be loaded
            FileNotFoundError: If audio file does not exist
        """
        new_audio = Audio.from_path(path)
        return self.add_audio(new_audio, overlay)
```

--------------------------------

### VideoEdit JSON wire format structure

Source: https://videopython.com/reference/video-edit

Example of the required JSON structure for defining segments, operations, and global settings.

```json
{
  "segments": [
    {
      "source": "path/to/video.mp4",
      "start": 5.0,
      "end": 15.0,
      "operations": [
        {"op": "resize", "width": 1080, "height": 1920},
        {"op": "blur_effect", "mode": "constant", "iterations": 2,
         "window": {"start": 0.0, "stop": 3.0}}
      ]
    }
  ],
  "post_operations": [
    {"op": "color_adjust", "brightness": 0.05}
  ],
  "match_to_lowest_fps": true,
  "match_to_lowest_resolution": true
}
```

--------------------------------

### Load audio from path

Source: https://videopython.com/reference/audio

Signature for the class method used to initialize an Audio instance from a file path.

```python
from_path(file_path: str | Path) -> Audio
```

--------------------------------

### SemanticSceneDetector.__init__

Source: https://videopython.com/reference/ai/understanding

Initializes a new instance of the SemanticSceneDetector.

```APIDOC
## __init__(threshold: float = 0.5, min_scene_length: float = 0.5, device: str | None = None)

### Description
Initializes the detector with specific configuration parameters for scene boundary detection.

### Parameters
- **threshold** (float) - Optional - Scene boundary threshold (0.0-1.0). Default is 0.5.
- **min_scene_length** (float) - Optional - Minimum scene duration in seconds. Default is 0.5.
- **device** (str | None) - Optional - The device to run the model on.
```

--------------------------------

### CutSeconds Operation Implementation

Source: https://videopython.com/reference/transforms

Defines an operation to cut video based on start and end times in seconds, including metadata validation.

```python
class CutSeconds(Operation):
    """Cuts video to a specific time range in seconds."""

    op: Literal["cut"] = "cut"
    category: ClassVar[OpCategory] = OpCategory.TRANSFORM
    internal_only: ClassVar[bool] = True

    start: float = Field(ge=0, description="Start time in seconds.")
    end: float = Field(ge=0, description="End time in seconds.")

    @model_validator(mode="after")
    def _validate_range(self) -> CutSeconds:
        if self.end <= self.start:
            raise ValueError(f"end ({self.end}) must be greater than start ({self.start})")
        return self

    def predict_metadata(self, meta: VideoMetadata) -> VideoMetadata:
        if self.end > meta.total_seconds + DURATION_EPS:
            message = f"end time ({self.end}) exceeds video duration ({meta.total_seconds})"
            raise PlanValidationError(
                message,
                [
                    PlanError(
                        code=PlanErrorCode.CUT_EXCEEDS_DURATION,
                        op=self.op,
                        field="end",
                        value=self.end,
                        limit=meta.total_seconds,
                    )
                ],
            )
        # Round both endpoints to frames before computing the duration, matching
        # the frame-accurate cut the compiled filter performs.
        start_f = round(self.start * meta.fps)
        end_f = round(self.end * meta.fps)
        duration = round((end_f - start_f) / meta.fps, 4)
        return meta.with_duration(duration)
```

--------------------------------

### AudioClassifier.__init__

Source: https://videopython.com/reference/ai/understanding

Initializes the AudioClassifier with model configuration and device settings.

```APIDOC
## AudioClassifier(model_name, confidence_threshold, top_k, device)

### Description
Initializes the AudioClassifier instance for audio event and sound classification.

### Parameters
- **model_name** (str) - Optional - The HuggingFace model name to use. Defaults to "MIT/ast-finetuned-audioset-10-10-0.4593".
- **confidence_threshold** (float) - Optional - The minimum confidence score required for a classification to be returned. Defaults to 0.3.
- **top_k** (int) - Optional - The number of top predictions to return. Defaults to 10.
- **device** (str | None) - Optional - The device to run the model on (e.g., 'cpu', 'cuda').
```

--------------------------------

### Implement FaceTrackingCrop in VideoEdit

Source: https://videopython.com/reference/ai/operations

Example of using FaceTrackingCrop within a VideoEdit pipeline to reframe video and configure specific framing rules.

```python
from videopython.ai import FaceTrackingCrop
from videopython.editing import VideoEdit, SegmentConfig

# Horizontal source to vertical, following the subject
edit = VideoEdit(segments=[SegmentConfig(source="input.mp4", start=0, end=5, operations=[
    FaceTrackingCrop(target_aspect=(9, 16)),
])])
edit.run_to_file("vertical.mp4")

# Headroom framing with a bounded camera speed
FaceTrackingCrop(framing_rule="headroom", max_speed=0.1)
```

--------------------------------

### Create VideoMetadata from Video instance

Source: https://videopython.com/reference/video

Initializes a VideoMetadata object directly from an existing Video instance.

```python
from_video(video: Video) -> VideoMetadata
```

```python
@classmethod
def from_video(cls, video: Video) -> VideoMetadata:
    """Creates VideoMetadata object from Video instance."""
    frame_count, height, width, _ = video.frames.shape
    total_seconds = round(frame_count / video.fps, 4)

    return cls(height=height, width=width, fps=video.fps, frame_count=frame_count, total_seconds=total_seconds)
```

--------------------------------

### Extract thumbnails at intervals

Source: https://videopython.com/how-to/long-videos

A practical example demonstrating how to iterate through frames and save thumbnails at specific time intervals using PIL.

```python
import os

from PIL import Image

from videopython.base import FrameIterator, VideoMetadata


def extract_thumbnails(video_path: str, output_dir: str, interval_seconds: float = 60.0):
    os.makedirs(output_dir, exist_ok=True)
    fps = VideoMetadata.from_path(video_path).fps
    interval_frames = int(interval_seconds * fps)

    with FrameIterator(video_path) as frames:
        for frame_idx, frame in frames:
            if frame_idx % interval_frames == 0:
                img = Image.fromarray(frame)
                img.thumbnail((320, 180))
                img.save(f"{output_dir}/thumb_{frame_idx / fps:.0f}s.jpg")
```

--------------------------------

### Create Video from Path

Source: https://videopython.com/reference/video

Factory method to load a video from a file path with optional decoding parameters.

```python
from_path(
    path: str,
    read_batch_size: int = 100,
    start_second: float | None = None,
    end_second: float | None = None,
    fps: float | None = None,
    width: int | None = None,
    height: int | None = None,
) -> Video
```

```python
@classmethod
def from_path(
    cls,
    path: str,
    read_batch_size: int = 100,
    start_second: float | None = None,
    end_second: float | None = None,
    fps: float | None = None,
    width: int | None = None,
    height: int | None = None,
) -> Video:
    frames, out_fps, audio = _video_io.decode_video(
        path,
        read_batch_size=read_batch_size,
        start_second=start_second,
        end_second=end_second,
        fps=fps,
        width=width,
        height=height,
    )
    return cls(frames=frames, fps=out_fps, audio=audio)
```

--------------------------------

### Video.from_path

Source: https://videopython.com/reference/video

Creates a Video instance by loading and decoding a video file from a specified path.

```APIDOC
## from_path(path: str, read_batch_size: int = 100, start_second: float | None = None, end_second: float | None = None, fps: float | None = None, width: int | None = None, height: int | None = None) -> Video

### Description
Loads a video from the filesystem and returns a Video instance.

### Parameters
- **path** (str) - Required - Path to the video file.
- **read_batch_size** (int) - Optional - Batch size for reading frames.
- **start_second** (float | None) - Optional - Start time in seconds.
- **end_second** (float | None) - Optional - End time in seconds.
- **fps** (float | None) - Optional - Target frame rate.
- **width** (int | None) - Optional - Target width.
- **height** (int | None) - Optional - Target height.
```

--------------------------------

### SegmentConfig

Source: https://videopython.com/reference/video-edit

A configuration model representing a single source video segment, including its start and end times, operations, and optional transition specifications.

```APIDOC
## SegmentConfig

### Description
A data model representing a single source video segment with its associated operation chain.

### Fields
- **source** (Path) - Required - Path to the source video file.
- **start** (float) - Required - Segment start time in seconds.
- **end** (float) - Required - Segment end time in seconds.
- **operations** (list[OperationInput]) - Optional - Ordered list of operations to run against this segment.
- **transition_in** (TransitionSpec | None) - Optional - Optional crossfade from the previous segment into this one.

### Methods
#### load(fps: float | None = None, width: int | None = None, height: int | None = None) -> Video
Loads the raw segment from disk with optional decode-time matching.
```

--------------------------------

### Video.from_path

Source: https://videopython.com/reference/video

Creates a Video instance by loading a video file from the specified path.

```APIDOC
## Video.from_path(path, read_batch_size=100, start_second=None, end_second=None, fps=None, width=None, height=None)

### Description
Loads a video from a file path into memory as a Video object.

### Parameters
- **path** (str) - Required - The file path to the video.
- **read_batch_size** (int) - Optional - Batch size for decoding (default: 100).
- **start_second** (float) - Optional - Start time for bounded loading.
- **end_second** (float) - Optional - End time for bounded loading.
- **fps** (float) - Optional - Target frame rate.
- **width** (int) - Optional - Target width.
- **height** (int) - Optional - Target height.
```

--------------------------------

### Define AudioEvent dataclass

Source: https://videopython.com/reference/ai/understanding

Defines the AudioEvent structure with start, end, label, and confidence attributes, including helper methods for duration calculation and serialization.

```python
@dataclass
class AudioEvent:
    """A detected audio event with timestamp.

    Attributes:
        start: Start time in seconds
        end: End time in seconds
        label: Name of the detected sound (e.g., "Music", "Speech", "Dog bark")
        confidence: Detection confidence score between 0 and 1
    """

    start: float
    end: float
    label: str
    confidence: float

    @property
    def duration(self) -> float:
        """Duration of the audio event in seconds."""
        return self.end - self.start

    def to_dict(self) -> dict[str, Any]:
        """Convert to dictionary for JSON serialization."""
        return {
            "start": self.start,
            "end": self.end,
            "label": self.label,
            "confidence": self.confidence,
        }

    @classmethod
    def from_dict(cls, data: dict[str, Any]) -> AudioEvent:
        """Create AudioEvent from dictionary."""
        return cls(
            start=data["start"],
            end=data["end"],
            label=data["label"],
            confidence=data["confidence"],
        )
```

--------------------------------

### Initialize AudioToText class

Source: https://videopython.com/reference/ai/understanding

Constructor for configuring the transcription model, diarization, and VAD settings.

```python
PYANNOTE_DIARIZATION_MODEL = "pyannote/speaker-diarization-community-1"
_model_attrs = ("_model", "_diarization_pipeline", "_vad_model")

def __init__(
    self,
    model_name: Literal["tiny", "base", "small", "medium", "large", "turbo"] = "turbo",
    enable_diarization: bool = False,
    enable_vad: bool = True,
    condition_on_previous_text: bool = False,
    no_speech_threshold: float = 0.6,
    logprob_threshold: float | None = -1.0,
    vocabulary: list[str] | None = None,
    device: str | None = None,
):
    self.model_name = model_name
    self.enable_diarization = enable_diarization
    self.enable_vad = enable_vad
    self.condition_on_previous_text = condition_on_previous_text
    self.no_speech_threshold = no_speech_threshold
    self.logprob_threshold = logprob_threshold
    self.vocabulary = _normalize_vocabulary(vocabulary)
    self.device = select_device(device, mps_allowed=False)
    log_device_initialization(
        "AudioToText",
        requested_device=device,
        resolved_device=self.device,
    )
    self._model: Any = None
    self._diarization_pipeline: Any = None
    self._vad_model: Any = None
```

--------------------------------

### Overlay audio

Source: https://videopython.com/reference/audio

Mixes another audio segment onto the current one starting at a specified position. Automatically handles mono-to-stereo conversion if necessary.

```python
overlay(other: Audio, position: float = 0.0) -> Audio
```

```python
def overlay(self, other: Audio, position: float = 0.0) -> Audio:
    """
    Overlay another audio segment on top of this one, mixing both signals.
    If mixing mono and stereo, converts mono to stereo.

    Args:
        other: Another Audio object to overlay
        position: Start position in seconds for the overlay (default: 0.0)

    Returns:
        Audio: New Audio object with mixed audio
```

--------------------------------

### Audio.from_path

Source: https://videopython.com/reference/audio

Creates an Audio instance by loading audio data from a specified file path.

```APIDOC
## Audio.from_path

### Description
Loads audio data from a file path to create an Audio instance.

### Parameters
- **file_path** (str | Path) - Required - The path to the audio file.
```

--------------------------------

### slice(start_seconds: float = 0.0, end_seconds: float | None = None) -> Audio

Source: https://videopython.com/reference/audio

Extracts a specific portion of the audio between the provided start and end times.

```APIDOC
## slice(start_seconds, end_seconds)

### Description
Extract a portion of the audio between start_seconds and end_seconds.

### Parameters
- **start_seconds** (float) - Optional - Start time in seconds (default: 0.0)
- **end_seconds** (float | None) - Optional - End time in seconds (default: None, meaning end of audio)

### Returns
- **Audio** (Audio) - New Audio instance with the extracted portion

### Raises
- **ValueError** - If start_seconds or end_seconds are invalid
```
Tokens:
Raw