### Install Project Dependencies

Source: https://github.com/bartwojtowicz/videopython/blob/main/DEVELOPMENT.md

Installs all project dependencies, including optional extras, using uv.

```bash
uv sync --all-extras
```

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

### Basic videopython Installation

Source: https://github.com/bartwojtowicz/videopython/blob/main/docs/getting-started/installation.md

Install the core videopython package for basic video handling.

```bash
pip install videopython
```

```bash
# Or with uv
uv add videopython
```

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

### Install videopython with All AI Features

Source: https://github.com/bartwojtowicz/videopython/blob/main/docs/getting-started/installation.md

Install videopython with all AI-powered features enabled.

```bash
pip install "videopython[ai]"
```

```bash
# Or with uv
uv add videopython --extra ai
```

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

### Install FFmpeg on Windows

Source: https://github.com/bartwojtowicz/videopython/blob/main/docs/getting-started/installation.md

Install FFmpeg on Windows using Chocolatey.

```bash
# Windows (with Chocolatey)
choco install ffmpeg
```

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

### Install FFmpeg on Ubuntu/Debian

Source: https://github.com/bartwojtowicz/videopython/blob/main/docs/getting-started/installation.md

Install FFmpeg using apt-get on Ubuntu or Debian systems.

```bash
# Ubuntu/Debian
sudo apt-get install ffmpeg
```

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

### Install videopython Core and AI Features

Source: https://github.com/bartwojtowicz/videopython/blob/main/README.md

Install the core video/audio editing library. Use the '[ai]' extra for all local AI features, which recommends a GPU. AI dependencies are split into granular extras like '[asr]', '[vision]', '[separation]', '[translation]', '[tts]', '[generation]', and '[dub]'.

```bash
# Install FFmpeg first (macOS: brew install ffmpeg | Debian: apt-get install ffmpeg)
pip install videopython          # core video/audio editing
pip install "videopython[ai]"    # + ALL local AI features (GPU recommended)
```

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

### JSON Plan Format Example

Source: https://github.com/bartwojtowicz/videopython/blob/main/docs/api/editing.md

An example illustrating the structure of a JSON plan for video editing. It shows how to specify video segments, operations within segments, and post-operations. Note the rules for required fields, operation discriminators, and strict top-level keys.

```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
}
```

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

### Install VideoPython Core and AI Features

Source: https://github.com/bartwojtowicz/videopython/blob/main/docs/index.md

Install the core editing package or the full package including all local AI features. GPU is recommended for AI features.

```bash
pip install videopython          # core editing
pip install "videopython[ai]"    # + ALL local AI features (GPU recommended)
```

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

### Install FFmpeg on macOS

Source: https://github.com/bartwojtowicz/videopython/blob/main/docs/getting-started/installation.md

Install FFmpeg using Homebrew on macOS.

```bash
# macOS
brew install ffmpeg
```

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

### Initialize AI Components with GPU

Source: https://github.com/bartwojtowicz/videopython/blob/main/docs/getting-started/installation.md

Example of initializing AI components like TextToSpeech and ImageToVideo, specifying the CUDA device for potential GPU acceleration.

```python
from videopython.ai import TextToSpeech, ImageToVideo

tts = TextToSpeech(device="cuda")
video_gen = ImageToVideo()
```

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

### Usage Example with Transforms

Source: https://github.com/bartwojtowicz/videopython/blob/main/docs/api/transforms.md

Demonstrates how to use various transforms like CutSeconds, Crop, and Resize within a VideoEdit operation and run it to a file.

```APIDOC
## Usage Example with Transforms

### Description
This example shows how to apply multiple transforms to a video segment. Transforms are added to a `VideoEdit` object and then rendered using `run_to_file`.

### Method
N/A (Python SDK)

### Endpoint
N/A (Python SDK)

### Parameters
N/A (Python SDK)

### Request Example
```python
from videopython.editing import VideoEdit, SegmentConfig, Resize, Crop, CutSeconds

edit = VideoEdit(segments=[SegmentConfig(source="input.mp4", start=0, end=10, operations=[
    CutSeconds(start=0.0, end=10.0),
    Crop(width=0.5, height=0.5),        # 50% center crop
    Resize(width=1280, height=720),
])])
edit.run_to_file("output.mp4")
```

### Response
N/A (Python SDK)
```

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

### Install VideoPython with Dubbing Extras

Source: https://github.com/bartwojtowicz/videopython/blob/main/docs/api/ai/dubbing.md

Install the VideoPython package with the necessary extras for dubbing, including transcription, source separation, translation, and loudness matching. Use the `[tts]` extra for default local voice synthesis.

```bash
pip install "videopython[dub]"        # pipeline WITHOUT local TTS
pip install "videopython[dub,tts]"    # + default local voice synthesis
```

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

### Smooth Speed Ramping Example

Source: https://github.com/bartwojtowicz/videopython/blob/main/RELEASE_NOTES.md

Illustrates creating cinematic effects by smoothly ramping the video playback speed.

```python
from videopython.video.transforms import SpeedChange

video = SpeedChange(speed_ramp=[(0, 1.0), (5, 2.0), (10, 0.5)]) # Speed changes over time
```

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

### Example of providing per-source runtime context

Source: https://github.com/bartwojtowicz/videopython/blob/main/RELEASE_NOTES.md

Demonstrates how to supply a dictionary of context data, where each key corresponds to a source file, allowing for source-specific runtime information. This is useful for multi-clip plans where different sources require unique data, such as transcriptions.

```python
edit.run_to_file(out, context={"transcription": {"a.mp4": tx_a, "b.mp4": tx_b}})
```

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

### Inline Dictionary Plan Example

Source: https://github.com/bartwojtowicz/videopython/blob/main/docs/api/transforms.md

Illustrates how to define video editing plans, including transforms, using an inline dictionary format.

```APIDOC
## Inline Dictionary Plan Example

### Description
This example shows an alternative way to define video editing operations, including transforms like crop and resize, using a structured dictionary format.

### Method
N/A (Python SDK)

### Endpoint
N/A (Python SDK)

### Parameters
N/A (Python SDK)

### Request Example
```python
plan = {
    "segments": [{
        "source": "input.mp4",
        "start": 0,
        "end": 10,
        "operations": [
            {"op": "crop", "width": 0.5, "height": 0.5},
            {"op": "resize", "width": 1280, "height": 720},
        ],
    }]
}
```

### Response
N/A (Python SDK)
```

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

### Install videopython with Specific AI Features

Source: https://github.com/bartwojtowicz/videopython/blob/main/docs/getting-started/installation.md

Install videopython with specific AI feature sets like ASR or dubbing with TTS.

```bash
pip install "videopython[asr]"          # just transcription
```

```bash
pip install "videopython[dub,tts]"      # dubbing with local TTS
```

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

### Constant Speed Change Example

Source: https://github.com/bartwojtowicz/videopython/blob/main/RELEASE_NOTES.md

Demonstrates how to change a video's playback speed to a constant value, such as making it twice as fast.

```python
from videopython.video.transforms import SpeedChange

video = SpeedChange(speed=2.0) # 2x faster
# or
video = SpeedChange(speed=0.5) # 0.5x slower
```

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

### Programmatic Video Editing with JSON Plan

Source: https://github.com/bartwojtowicz/videopython/blob/main/docs/index.md

Create and run a video editing plan defined in a JSON-like structure. This example demonstrates segmenting, resizing, and applying fade-in effects.

```python
from videopython.editing import VideoEdit

edit = VideoEdit.from_dict({
    "segments": [
        {"source": "intro.mp4", "start": 0, "end": 3,
         "operations": [{"op": "resize", "width": 1080, "height": 1920}]},
        {"source": "raw.mp4", "start": 10, "end": 25,
         "operations": [
             {"op": "resize", "width": 1080, "height": 1920},
             {"op": "resample_fps", "fps": 30},
             {"op": "fade", "mode": "in", "duration": 0.5},
         ]},
    ],
})
edit.run_to_file("output.mp4")
```

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

### Install Git Pre-commit Hook

Source: https://github.com/bartwojtowicz/videopython/blob/main/DEVELOPMENT.md

Installs the git pre-commit hook to automatically run linters and type checkers before commits.

```bash
uv run pre-commit install
```

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

### Create Vertical Social Media Clip from Dictionary Plan

Source: https://github.com/bartwojtowicz/videopython/blob/main/docs/examples/social-clip.md

Builds the same video editing plan as the previous example but uses a dictionary representation, suitable for programmatic generation or data-driven edits. Use this when the edit plan is defined in a JSON-like structure.

```python
from videopython.editing import VideoEdit

plan = {
    "segments": [{
        "source": "raw_footage.mp4",
        "start": 30.0,
        "end": 45.0,
        "operations": [
            {"op": "resample_fps", "fps": 30},
            {"op": "resize", "height": 1920},
            {"op": "crop", "width": 1080, "height": 1920, "mode": "center"},
            {"op": "fade", "mode": "in", "duration": 0.5},
        ],
    }],
}

edit = VideoEdit.from_dict(plan)
edit.validate()      # dry run using VideoMetadata
edit.run_to_file("social_clip.mp4")   # streams to disk
```

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

### ObjectDetectionOverlay Configuration in JSON Plan

Source: https://github.com/bartwojtowicz/videopython/blob/main/docs/api/ai/effects.md

Example of how to configure the object detection overlay operation within a JSON editing plan, including class filtering and confidence thresholds.

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

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

### Analyze Audio Levels

Source: https://github.com/bartwojtowicz/videopython/blob/main/docs/api/core/audio.md

Shows how to get overall audio levels, levels for a specific segment, and levels over time using a sliding window analysis. Requires loading an audio file first.

```python
from videopython.audio import Audio

audio = Audio.from_path("audio.mp3")

# Get overall levels
levels = audio.get_levels()
print(f"Peak: {levels.db_peak:.1f} dB, RMS: {levels.db_rms:.1f} dB")

# Get levels for a specific segment
segment_levels = audio.get_levels(start_seconds=1.0, end_seconds=3.0)

# Get levels over time (sliding window analysis)
levels_over_time = audio.get_levels_over_time(window_seconds=0.1)
for timestamp, levels in levels_over_time:
    print(f"{timestamp:.2f}s: {levels.db_rms:.1f} dB")
```

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

### Get Supported Languages

Source: https://github.com/bartwojtowicz/videopython/blob/main/docs/api/ai/dubbing.md

Retrieve a dictionary of supported languages for video dubbing. The keys are language codes and values are full language names.

```python
languages = VideoDubber.get_supported_languages()
# {'en': 'English', 'es': 'Spanish', 'fr': 'French', ...}
```

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

### Full AI Video Generation Example

Source: https://github.com/bartwojtowicz/videopython/blob/main/docs/examples/ai-video.md

This function generates a video from text prompts. It creates images, animates them into video segments, adds AI-generated speech, and combines these scenes with transitions. Each scene is processed individually and then assembled into a final video file.

```python
from pathlib import Path

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


def create_ai_video(output_path: str, workdir: str = "scenes"):
    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 = TextToImage()
    video_gen = ImageToVideo()
    speech_gen = TextToSpeech()

    # Generate each scene with narration and save it to disk.
    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)

    # Assemble every scene into one streaming plan. Resize standardizes each
    # scene to 1080p; a 1s dissolve crossfades each follow-on scene in (the
    # first scene has no predecessor, so it carries no transition_in).
    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),
        ))

    edit = VideoEdit(segments=segments)
    edit.run_to_file(output_path)


create_ai_video("ai_generated.mp4")

```

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

### Build Static Documentation

Source: https://github.com/bartwojtowicz/videopython/blob/main/DEVELOPMENT.md

Renders the static HTML site for the documentation into the ./site directory.

```bash
uv run mkdocs build
```

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

### Serve Documentation Locally

Source: https://github.com/bartwojtowicz/videopython/blob/main/DEVELOPMENT.md

Builds and serves the documentation site locally using MkDocs Material, providing a live preview.

```bash
uv run mkdocs serve
```

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

### Create and Run a Video Edit Plan

Source: https://github.com/bartwojtowicz/videopython/blob/main/docs/api/editing.md

Demonstrates how to define a video editing plan using a dictionary and execute it. This plan includes segment selection, operations like crop and resize, and post-operations for color adjustment. The `validate()` method performs a dry-run, while `run_to_file()` streams the output directly to disk.

```python
from videopython.editing import VideoEdit

plan = {
    "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},
    ],
}

edit = VideoEdit.from_dict(plan)
predicted = edit.validate()        # dry-run via VideoMetadata
edit.run_to_file("output.mp4", crf=20, preset="medium")  # streams to disk (constant memory, any video length)
```

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

### Initialize VideoDubber with DubbingConfig

Source: https://github.com/bartwojtowicz/videopython/blob/main/docs/api/ai/dubbing.md

Demonstrates two ways to initialize VideoDubber: using flat keyword arguments for ad-hoc calls or passing an explicit DubbingConfig object for reusable presets. Ensure necessary imports are present.

```python
from videopython.ai.dubbing import DubbingConfig, VideoDubber

# Flat kwargs (recommended for ad-hoc calls)
dubber = VideoDubber(device="cuda", low_memory=True, whisper_model="large")

# Explicit config (recommended for reusable presets)
config = DubbingConfig(
    device="cuda",
    low_memory=True,
    whisper_model="large",
    translator="qwen3",
    vocabulary=["Klarna", "Allegro"],
)
dubber = VideoDubber(config=config)
```

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

### VideoDubber Initialization

Source: https://github.com/bartwojtowicz/videopython/blob/main/docs/api/ai/dubbing.md

Demonstrates how to initialize the VideoDubber class using either flat keyword arguments or an explicit DubbingConfig object. This is the primary way to set up the dubbing service with various AI models and configurations.

```APIDOC
## VideoDubber Initialization

### Description
Initializes the `VideoDubber` with configuration options. You can pass configuration knobs as flat keyword arguments or as a `DubbingConfig` object. The `VideoDubber` constructor will build a `DubbingConfig` internally if flat arguments are provided.

### Method
`__init__`

### Parameters
#### Keyword Arguments (for flat kwargs)
- **device** (str) - Optional - The device to run the models on (e.g., 'cuda', 'cpu').
- **low_memory** (bool) - Optional - Whether to use low memory mode.
- **whisper_model** (str) - Optional - The Whisper model to use for speech-to-text (e.g., 'large').
- **translator** (str) - Optional - The translation model to use (e.g., 'qwen3').
- **vocabulary** (list[str]) - Optional - A list of specific words or phrases to prioritize during translation.

#### `config` Parameter (for explicit config)
- **config** (DubbingConfig) - Optional - An instance of `DubbingConfig` containing all dubbing settings.

### Request Example
```python
from videopython.ai.dubbing import DubbingConfig, VideoDubber

# Using flat kwargs (recommended for ad-hoc calls)
dubber_flat = VideoDubber(device="cuda", low_memory=True, whisper_model="large")

# Using explicit DubbingConfig (recommended for reusable presets)
config = DubbingConfig(
    device="cuda",
    low_memory=True,
    whisper_model="large",
    translator="qwen3",
    vocabulary=["Klarna", "Allegro"],
)
dubber_config = VideoDubber(config=config)
```

### Response
An initialized `VideoDubber` instance.
```

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

### Iterate Through Transcription Segments and Words

Source: https://github.com/bartwojtowicz/videopython/blob/main/docs/examples/auto-subtitles.md

Iterates through the transcribed segments and words of a video, printing their start and end times and the text content. This provides word-level timestamp information.

```python
for segment in transcription.segments:
    print(f"{segment.start:.2f}-{segment.end:.2f}: {segment.text}")
    for word in segment.words:
        print(f
```

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

### Basic LLM Video Editing Workflow

Source: https://github.com/bartwojtowicz/videopython/blob/main/docs/guides/llm-integration.md

Demonstrates the core workflow of generating an editing plan with an LLM, validating it, and running it to a file. Ensure you have a function `call_your_llm` defined to interact with your chosen LLM.

```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)
predicted = edit.validate()           # catches bad plans before any I/O
print(predicted)
edit.run_to_file("output.mp4")
```

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

### Get Operation JSON Schemas

Source: https://github.com/bartwojtowicz/videopython/blob/main/docs/guides/llm-integration.md

Retrieves the full Pydantic JSON schema for an operation and the LLM-facing variant, which omits advanced fields. Prefer `llm_json_schema()` for LLM tool definitions.

```python
# Per-op JSON Schema: model_json_schema() is the full Pydantic schema;
# llm_json_schema() is the LLM-facing variant (drops `llm_hidden` advanced
# fields like raw font paths), so prefer it for tool/function definitions.
Operation.get("color_adjust").model_json_schema()
Operation.get("text_overlay").llm_json_schema()
```

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

### Get VideoEdit JSON Schema

Source: https://github.com/bartwojtowicz/videopython/blob/main/docs/examples/social-clip.md

Retrieves the JSON schema for the VideoEdit plan. This is useful for validating or generating edit plans programmatically, especially when working with external tools or APIs.

```python
schema = VideoEdit.json_schema()
```

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

### Running with Contextual Data

Source: https://github.com/bartwojtowicz/videopython/blob/main/docs/examples/large-videos.md

Demonstrates how to pass contextual data, such as transcriptions, to `run_to_file` for effects that require additional information during streaming.

```python
edit.run_to_file("output.mp4", context={"transcription": transcription})
```

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

### Get Video Metadata

Source: https://github.com/bartwojtowicz/videopython/blob/main/docs/api/core/video.md

Retrieve video metadata such as duration, resolution, FPS, and frame count without loading frames into memory. Useful for quick inspection of video properties.

```python
from videopython.base import VideoMetadata

metadata = VideoMetadata.from_path("video.mp4")
print(f"Duration: {metadata.total_seconds}s")
print(f"Resolution: {metadata.width}x{metadata.height}")
print(f"FPS: {metadata.fps}")
print(f"Total frames: {metadata.frame_count}")
```

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

### Get Streamability Report

Source: https://github.com/bartwojtowicz/videopython/blob/main/docs/api/editing.md

Classifies operations by streaming class without disk access. Use `report.streamable` to check if the plan will run, `report.unstreamable` for offending operations, and `report.errors()` for structured errors.

```python
report = edit.streamability()
report.streamable        # will the plan run?
report.unstreamable      # the offending ops, with reasons
report.errors()          # the same as structured STREAMING_UNSUPPORTED PlanErrors
```

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

### Load, Create, Manipulate, and Save Audio

Source: https://github.com/bartwojtowicz/videopython/blob/main/docs/api/core/audio.md

Demonstrates loading audio from a file, creating a silent track, performing basic manipulations like converting to mono, resampling, and slicing, combining audio tracks, and saving the result.

```python
from videopython.audio import Audio

# Load from file
audio = Audio.from_path("music.mp3")

# Create silent track
silent = Audio.create_silent(duration_seconds=5.0, stereo=True)

# Basic operations
mono = audio.to_mono()
resampled = audio.resample(16000)
segment = audio.slice(start_seconds=1.0, end_seconds=5.0)

# Combine audio
combined = audio1.concat(audio2, crossfade=0.5)
mixed = audio1.overlay(audio2, position=2.0)

# Save
audio.save("output.wav")
```

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

### Select Translation Backend

Source: https://github.com/bartwojtowicz/videopython/blob/main/docs/api/ai/dubbing.md

Configure the translation backend for the dubbing pipeline. Options include 'auto' (defaults to Qwen3 on GPU, MarianMT on CPU), 'marian' (Helsinki-NLP), or 'qwen3' (Qwen3-4B-Instruct).

```python
# Auto resolver: Qwen3 on GPU when supported, MarianMT on CPU.
dubber = VideoDubber(translator="auto")

# Force MarianMT (e.g. CPU machines where Qwen3 wall time is impractical).
dubber = VideoDubber(translator="marian")

# Force Qwen3. Logs a WARNING on CPU because Qwen3-4B Q4_K_M runs ~10-15x
# slower than Marian without GPU acceleration.
dubber = VideoDubber(translator="qwen3")
```

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

### Generating Per-Operation JSON Schema

Source: https://github.com/bartwojtowicz/videopython/blob/main/docs/api/operations.md

Retrieve the JSON schema for a specific operation's fields using `model_json_schema()`. Use `llm_json_schema()` to get a schema suitable for LLM interaction, with `llm_hidden` fields removed.

```python
from videopython.editing import Operation

cls = Operation.get("blur_effect")
schema = cls.model_json_schema()         # full (all fields)
llm_schema = cls.llm_json_schema()       # LLM-facing (llm_hidden dropped)
# {
#   "properties": {
#     "op": {"const": "blur_effect", ...},
#     "mode": {"enum": ["constant", "ascending", "descending"], ...},
#     "iterations": {"type": "integer", "minimum": 1, ...},
#     "window": {"anyOf": [{"$": "..."}, {"type": "null"}], ...},
#     ...
#   },
#   ...
# }
```

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

### Full Video Edit Refine Loop

Source: https://github.com/bartwojtowicz/videopython/blob/main/docs/guides/llm-integration.md

This loop demonstrates a comprehensive video editing refinement process. It starts with parsing the plan, repairing mechanical issues, normalizing dimensions, and finally checking for any remaining errors.

```python
edit = VideoEdit.from_dict(plan)                       # permissive parse
edit, repairs = edit.repair(source_metadata)           # clamp the mechanical ones
edit, dim_repairs = edit.normalize_dimensions(source_metadata, "largest")
errors = edit.check(source_metadata)                   # whatever's left, all at once
if errors:
    ...  # re-prompt with the previous plan + the full structured error list
```

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

### Initialize AudioToText with Default Anti-hallucination Settings

Source: https://github.com/bartwojtowicz/videopython/blob/main/docs/api/ai/understanding.md

Instantiate the AudioToText class with default anti-hallucination parameters. These defaults are suitable for most use cases.

```python
from videopython.ai import AudioToText

# Defaults: condition_on_previous_text=False (the cascading-hallucination fix),
# no_speech_threshold=0.6, logprob_threshold=-1.0.
transcriber = AudioToText()
```

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

### Bias Vocabulary for Brand Names

Source: https://github.com/bartwojtowicz/videopython/blob/main/docs/api/ai/dubbing.md

Provide a list of brand names or proper nouns to bias Whisper's decoder. This helps recover near-mishears by using `initial_prompt` to guide the model's understanding of specific terms.

```python
dubber = VideoDubber(vocabulary=["Klarna", "Allegro", "InPost"])
```

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

### Create and Run a Video Edit Plan

Source: https://github.com/bartwojtowicz/videopython/blob/main/README.md

Defines a video editing plan using segments, operations like resize and color adjustment, validates it, and runs it to an output file. This is useful for programmatic video manipulation.

```python
from videopython.editing import VideoEdit

edit = VideoEdit.from_dict({
    "segments": [{"source": "raw.mp4", "start": 10.0, "end": 20.0, "operations": [
            {"op": "resize", "width": 1080, "height": 1920},
            {"op": "color_adjust", "saturation": 1.15, "contrast": 1.05},
            {"op": "fade", "mode": "in", "duration": 0.5},
        ] }],
})
edit.validate()                  # dry-run via metadata, no frames loaded
edit.run_to_file("output.mp4")   # streams ffmpeg decode → effects → encode
```

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

### Python Registry API Usage

Source: https://github.com/bartwojtowicz/videopython/blob/main/docs/api/operations.md

Demonstrates how to use the `Operation` registry API in Python. This includes getting a snapshot of all registered operations, accessing LLM-exposed operations, looking up a specific operation by ID, and generating JSON schemas for operations.

```python
from videopython.editing import Operation

# Snapshot of {op_id: subclass} for every registered operation:
Operation.registry()

# LLM-safe subset: only ops with llm_exposed=True (omits server-only ops):
Operation.llm_registry()

# Look up by op_id (raises KeyError if unknown):
cls = Operation.get("resize")

# Discriminated-union JSON Schema over the LLM-exposed ops:
schema = Operation.json_schema()
# ...or over every registered op (worker / from_dict path):
full = Operation.json_schema(include_server_only=True)
```

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

### AudioToText Initialization with Anti-hallucination Knobs

Source: https://github.com/bartwojtowicz/videopython/blob/main/docs/api/ai/understanding.md

Demonstrates how to initialize the AudioToText class with different anti-hallucination parameters for Whisper. These parameters help tune the transcription process for noisy or sparse-speech audio.

```APIDOC
## AudioToText Initialization with Anti-hallucination Knobs

### Description
Initialize the `AudioToText` class with options to control Whisper's decoder behavior, specifically for handling noisy or sparse-speech audio by adjusting hallucination-related parameters.

### Method
```python
AudioToText(no_speech_threshold: float = 0.6, logprob_threshold: float = -1.0, condition_on_previous_text: bool = False)
```

### Parameters
#### Constructor Parameters
- **no_speech_threshold** (float) - Optional - Threshold to gate out non-speech segments. Defaults to 0.6.
- **logprob_threshold** (float) - Optional - Threshold for average log probability to consider a segment as valid speech. Defaults to -1.0.
- **condition_on_previous_text** (bool) - Optional - Whether to condition the decoder on previous text, useful for disambiguating homophones in clean audio. Defaults to False.

### Request Example
```python
from videopython.ai import AudioToText

# Default initialization
transcriber_default = AudioToText()

# Tighter no-speech gate for ambient music
transcriber_noisy = AudioToText(no_speech_threshold=0.85)

# Conditioning on previous text for clean audio
transcriber_conditioned = AudioToText(condition_on_previous_text=True)
```
```

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

### Run Full AI Test Suite

Source: https://github.com/bartwojtowicz/videopython/blob/main/DEVELOPMENT.md

Executes all AI tests, including those that download model weights. Recommended for local development.

```bash
uv run pytest src/tests/ai
```

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

### Import AI Classes

Source: https://github.com/bartwojtowicz/videopython/blob/main/docs/api/index.md

Import AI-powered generation classes like TextToVideo, TextToImage, and AudioToText from the videopython.ai module.

```python
from videopython.ai import (
    TextToVideo,
    TextToImage,
    AudioToText,
)
```

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

### Import Audio Classes

Source: https://github.com/bartwojtowicz/videopython/blob/main/docs/api/index.md

Import the Audio data container and its metadata class from the videopython.audio module.

```python
from videopython.audio import (
    Audio,
    AudioMetadata,
)
```

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

### Apply Basic Transformations with VideoEdit

Source: https://github.com/bartwojtowicz/videopython/blob/main/docs/getting-started/quickstart.md

Assemble editing operations like resizing and frame rate resampling into a VideoEdit plan. Execute the plan to save the transformed video.

```python
from videopython.editing import VideoEdit, SegmentConfig
from videopython.editing.transforms import Resize, ResampleFPS

edit = VideoEdit(segments=[
    SegmentConfig(
        source="input.mp4",
        start=0,    # cut the first 10 seconds...
        end=10,     # ...via the segment range, not a cut operation
        operations=[
            Resize(width=1280, height=720),
            ResampleFPS(fps=30),
        ],
    )
])
edit.run_to_file("output.mp4")
```

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

### Load Videos from File, Image, or Segment

Source: https://github.com/bartwojtowicz/videopython/blob/main/docs/getting-started/quickstart.md

Load videos from a file path, a specific time segment, or create one from a static image. Inspect video properties like metadata, duration, and frame shape.

```python
from videopython.base import Video

# Load from file
video = Video.from_path("input.mp4")

# Load a specific segment (more efficient for long videos)
video = Video.from_path("input.mp4", start_second=10, end_second=20)

# Create from a static image
import numpy as np
image = np.zeros((1080, 1920, 3), dtype=np.uint8)  # Black frame
video = Video.from_image(image, fps=24, length_seconds=3.0)

# Check video properties
print(video.metadata)  # 1920x1080 @ 30fps, 10.5 seconds
print(video.total_seconds)
print(video.frame_shape)  # (height, width, channels)
```

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

### Execute Video Edit to File and Load into Memory

Source: https://github.com/bartwojtowicz/videopython/blob/main/RELEASE_NOTES.md

Use `run_to_file` to process video edits and then load the output file into a `Video` object if in-memory access is required. This is the only remaining execution engine.

```python
from videopython.base.video import Video

out = edit.run_to_file("output.mp4")
video = Video.from_path(str(out))   # only when you actually need frames in memory
```

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

### Applying Blur and Windowed Blur Effects

Source: https://github.com/bartwojtowicz/videopython/blob/main/docs/api/effects.md

Demonstrates how to apply a blur effect across an entire video segment and a specific time window within a segment. Requires importing necessary classes from `videopython.base` and `videopython.editing`.

```python
from videopython.base import BoundingBox
from videopython.editing import (
    VideoEdit, SegmentConfig,
    Blur, Zoom, ColorGrading, Vignette, KenBurns,
    Fade, VolumeAdjust, TextOverlay, TimeRange,
)

edit = VideoEdit(segments=[SegmentConfig(source="input.mp4", start=0, end=5, operations=[
    # Effect across the full segment:
    Blur(mode="constant", iterations=50),
    # Effect on a sub-range via the `window` field:
    Blur(mode="constant", iterations=50, window=TimeRange(start=0.0, stop=2.0)),
])])
edit.run_to_file("output.mp4")
```

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

### Generate LLM Tools from Operations

Source: https://github.com/bartwojtowicz/videopython/blob/main/docs/guides/llm-integration.md

Enumerates LLM-registry operations, filters for transformations, and constructs tool definitions including name, description, and input schema. This prepares operations for use by an LLM.

```python
tools = []
for op_id, cls in Operation.llm_registry().items():
    if cls.category is not OpCategory.TRANSFORM:
        continue
    tools.append({
        "name": f"transform_{op_id}",
        "description": (cls.__doc__ or "").splitlines()[0],
        "input_schema": cls.llm_json_schema(),   # drops llm_hidden advanced fields
    })
```

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

### AudioToText Initialization with Brand-name Vocabulary Biasing

Source: https://github.com/bartwojtowicz/videopython/blob/main/docs/api/ai/understanding.md

Shows how to bias Whisper's transcription towards a specific list of brand names or proper nouns using the `initial_prompt` feature. This helps in accurately transcribing terms that Whisper might otherwise mishear.

```APIDOC
## AudioToText Initialization with Brand-name Vocabulary Biasing

### Description
Bias Whisper's transcription decoder towards a provided list of brand names, product names, or proper nouns using the `vocabulary` parameter. This helps recover near-mishears and improves accuracy for specific terminology.

### Method
```python
AudioToText(vocabulary: list[str])
```

### Parameters
#### Constructor Parameters
- **vocabulary** (list[str]) - Optional - A list of terms to bias the transcription towards. The list is normalized (whitespace stripped, case-insensitive dedup, casing of the first occurrence preserved). Lists longer than Whisper's prompt capacity will be trimmed.

### Request Example
```python
from videopython.ai import AudioToText

# Constructor default vocabulary
transcriber = AudioToText(vocabulary=["Klarna", "Allegro", "InPost"])
result = transcriber.transcribe(video)

# Per-call override for vocabulary
result = transcriber.transcribe(video, vocabulary=["Pyszne", "Wolt"])
```

### Usage with Other Classes
`VideoDubber` and `LocalDubbingPipeline` also accept the `vocabulary` kwarg. For `VideoAnalyzer`, pass it via `analyzer_params`.

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

config = VideoAnalysisConfig(
    analyzer_params={"audio_to_text": {"vocabulary": ["Klarna", "Allegro"]}}
)
analysis = VideoAnalyzer(config=config).analyze_path("brand_review.mp4")
```
```

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

### Define Video Edit Plan with Dictionary

Source: https://github.com/bartwojtowicz/videopython/blob/main/docs/api/transforms.md

Configure video editing segments and operations using a dictionary structure, including inline transform definitions. This is an alternative to using Python objects for configuration.

```python
plan = {
    "segments": [{
        "source": "input.mp4",
        "start": 0,
        "end": 10,
        "operations": [
            {"op": "crop", "width": 0.5, "height": 0.5},
            {"op": "resize", "width": 1280, "height": 720},
        ],
    }]
}
```

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

### Import Operation Foundation Classes

Source: https://github.com/bartwojtowicz/videopython/blob/main/docs/api/index.md

Import foundational classes for defining editing operations, including Operation, Effect, TimeRange, and OpCategory, from videopython.editing.

```python
from videopython.editing import (
    Operation,
    Effect,
    TimeRange,
    OpCategory,
)
```