Quick Start

This guide covers the essential operations in videopython.

Follow Along

All examples assume you have videos to work with. You can use any .mp4 file, or download sample videos from sites like Pexels.

Loading Videos

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)

Basic Transformations

Every editing primitive is an Operation. Operations run only through the streaming engine, so you assemble them into a VideoEdit plan and execute it with run_to_file. A time cut is expressed as the segment's start/end, while resizing, fps resampling, and effects go in the segment's operations list:

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")

Resize preserves aspect ratio when only one dimension is set (e.g. Resize(width=1280)).

VideoEdit also gives you a dry-run via .validate(), and accepts a plain dict (the JSON wire format) instead of operation objects:

from videopython.editing import VideoEdit

edit = VideoEdit.from_dict({
    "segments": [{
        "source": "input.mp4",
        "start": 0,
        "end": 10,
        "operations": [
            {"op": "resize", "width": 1280, "height": 720},
            {"op": "resample_fps", "fps": 30},
        ],
    }]
})
print(edit.validate())   # predicted VideoMetadata, no frames loaded
edit.run_to_file("output.mp4")

Combining Videos

Concatenate two videos with +. They must share fps and dimensions — align them with Resize / ResampleFPS first.

from videopython.base import Video

video1 = Video.from_path("clip1.mp4")
video2 = Video.from_path("clip2.mp4")
combined = video1 + video2

For multi-segment edits with auto-matching of fps/resolution, use VideoEdit (sets match_to_lowest_fps / match_to_lowest_resolution to true by default).

Working with Audio

from videopython.base import Video

video = Video.from_path("input.mp4")

# Add audio from file (overlays on existing audio)
video = video.add_audio_from_file("music.mp3")

# Add audio without overlay (replaces existing)
video = video.add_audio_from_file("narration.mp3", overlay=False)

# Save with audio
video.save("output.mp4")

Saving Videos

video.save("output.mp4")  # Default MP4
video.save("output.webm", format="webm")  # WebM format
video.save("output.mov", format="mov")  # QuickTime

# Supported formats: mp4, avi, mov, mkv, webm

# Control encoding quality and speed
video.save("output.mp4", preset="slow", crf=18)  # Higher quality, slower encoding
video.save("output.mp4", preset="ultrafast", crf=28)  # Faster encoding, lower quality

Encoding Options

• preset: Speed/compression tradeoff. Options: ultrafast, superfast, veryfast, faster, fast, medium (default), slow, slower, veryslow. Slower presets produce smaller files.
• crf: Quality level (0-51). Default is 23. Lower values = better quality, larger files. 18 is visually lossless.

AI Features (Quick Preview)

Local AI

AI features run locally and may download model weights on first use.

from videopython.ai import TextToImage, TextToSpeech

# Generate an image
generator = TextToImage()
image = generator.generate_image("A sunset over mountains")

# Generate speech
tts = TextToSpeech()
audio = tts.generate_audio("Welcome to videopython!")

See the API Reference for complete documentation.