Programmable Editing

When to Use Programmable Editing

Use the editor when you need to:

Generate personalized videos at scale
Build automated content pipelines
Create video variations for A/B testing
Compose clips from search results
Add overlays, captions, and effects programmatically

Quick Example

from videodb.editor import Timeline, Track, Clip, VideoAsset

# 1. Asset - your raw content
video_asset = VideoAsset(id=video.id, start=0)

# 2. Clip - how it appears
clip = Clip(asset=video_asset, duration=10)

# 3. Track - when it plays
track = Track()
track.add_clip(0, clip)

# 4. Timeline - the final canvas
timeline = Timeline(conn)
timeline.add_track(track)
stream_url = timeline.generate_stream()

Next Steps

Timeline Architecture

Complete guide to the 4-layer architecture

Clip Parameters

Filters, transitions, and effects

The 4-Layer Architecture

Think of video composition like building with LEGO:

Asset → Clip → Track → Timeline

Layer	Purpose	Example
Asset	Raw content (what)	`VideoAsset(id=video.id)`
Clip	Presentation (how)	`Clip(asset=..., duration=10)`
Track	Sequencing (when)	`track.add_clip(0, clip)`
Timeline	Canvas (output)	`timeline.generate_stream()`

Layer 1: Assets

Assets reference your content but don’t define timing or effects.

from videodb.editor import VideoAsset, AudioAsset, ImageAsset, TextAsset

# Video content
video_asset = VideoAsset(id=video.id, start=0, volume=1.0)

# Audio (music, voiceover)
audio_asset = AudioAsset(id=audio.id, start=0, volume=0.8)

# Images (logos, watermarks)
image_asset = ImageAsset(id=image.id)

# Custom text
text_asset = TextAsset(text="Hello World")

Key parameters:

id - The VideoDB media ID
start - Trim point in source (skip first N seconds)
volume - Audio level (0.0 to 2.0)

Layer 2: Clips

Clips wrap assets and define how and how long they appear.

from videodb.editor import Clip, Fit, Position

clip = Clip(
    asset=video_asset,
    duration=10,           # How long it plays
    fit=Fit.crop,          # How it scales to canvas
    position=Position.center,  # Where it appears
    scale=1.0,             # Size multiplier
    opacity=1.0            # Transparency (0-1)
)

Fit modes:

Fit.crop - Fill canvas, crop edges if needed
Fit.contain - Fit inside, add bars if needed
Fit.cover - Stretch to fill (may distort)

Position options:

9-zone grid: top_left, top, top_right, center_left, center, center_right, bottom_left, bottom, bottom_right

Layer 3: Tracks

Tracks are timeline lanes that control when clips play.

from videodb.editor import Track

track = Track()
track.add_clip(0, clip1)    # Starts at 0s
track.add_clip(10, clip2)   # Starts at 10s

Sequencing Rules

Same track = sequential playback:

track.add_clip(0, clip1)   # 0s-5s
track.add_clip(5, clip2)   # 5s-10s

Different tracks = simultaneous playback (layered):

track1.add_clip(0, video_clip)   # Background
track2.add_clip(0, logo_clip)    # Overlay (on top)

Z-Order

Later tracks render on top of earlier tracks:

timeline.add_track(background_track)  # Bottom layer
timeline.add_track(overlay_track)     # Renders above
timeline.add_track(caption_track)     # Top layer

Layer 4: Timeline

Timeline is your final canvas and export settings.

from videodb.editor import Timeline

timeline = Timeline(conn)
timeline.resolution = "1280x720"    # WIDTHxHEIGHT
timeline.background = "#000000"     # Hex color

timeline.add_track(track)
stream_url = timeline.generate_stream()

Common resolutions:

"1280x720" - 16:9 landscape (YouTube)
"608x1080" - 9:16 vertical (TikTok, Reels)
"1080x1080" - 1:1 square (Instagram)

Common Patterns

Highlight Reel from Search Results

from videodb.editor import Timeline, Track, Clip, VideoAsset

# Search for moments
results = video.search("key announcement")

# Build highlight reel
timeline = Timeline(conn)
track = Track()
current_time = 0

for shot in results.shots[:5]:
    asset = VideoAsset(id=video.id, start=shot.start)
    clip = Clip(asset=asset, duration=shot.end - shot.start)
    track.add_clip(current_time, clip)
    current_time += shot.end - shot.start

timeline.add_track(track)
highlights = timeline.generate_stream()

Video with Logo Overlay

from videodb.editor import Timeline, Track, Clip, VideoAsset, ImageAsset, Position

# Main video
video_asset = VideoAsset(id=video.id)
video_clip = Clip(asset=video_asset, duration=30)
video_track = Track()
video_track.add_clip(0, video_clip)

# Logo overlay
logo_asset = ImageAsset(id=logo.id)
logo_clip = Clip(
    asset=logo_asset,
    duration=30,
    position=Position.top_right,
    scale=0.2,
    opacity=0.8
)
logo_track = Track()
logo_track.add_clip(0, logo_clip)

# Combine (video first, logo on top)
timeline = Timeline(conn)
timeline.add_track(video_track)
timeline.add_track(logo_track)
output = timeline.generate_stream()

Timed Captioned Video

import base64
from videodb.editor import CaptionAnimation, Timeline, Track, Clip, VideoAsset, CaptionAsset

# Build this base64 SRT from your timed caption workflow.
srt = """1
00:00:00,000 --> 00:00:02,000
Captioned with explicit timing.
"""
srt_src = base64.b64encode(srt.encode()).decode()

# Video track
video_asset = VideoAsset(id=video.id)
video_clip = Clip(asset=video_asset, duration=60)
video_track = Track()
video_track.add_clip(0, video_clip)

# Caption track
caption_asset = CaptionAsset(src=srt_src, animation=CaptionAnimation.karaoke)
caption_clip = Clip(asset=caption_asset, duration=60)
caption_track = Track()
caption_track.add_clip(0, caption_clip)

# Combine
timeline = Timeline(conn)
timeline.add_track(video_track)
timeline.add_track(caption_track)
output = timeline.generate_stream()

See Track Layering for the timed SRT construction flow.

What You Can Build

TikTok Lyric Videos

Vertical videos with synced lyrics and AI backgrounds

Faceless Video Creator

Complete AI-generated videos with scripts and voiceovers

Intro & Outro Automation

Add branded intros and outros to all videos automatically

Brand Elements

Overlay logos, watermarks, and lower thirds programmatically

Best Practices

Think in layers - Background video first, overlays on top
Use Asset.start for trimming - Skip to the interesting part of source media
Match clip durations - Overlays should match or exceed video duration
Test with generate_stream() - Preview before expensive exports
Reuse assets - One VideoAsset can be used in multiple clips

Start Here

Core Concepts

Ingest

Understand

Act

Automate

MCP Server

Open Source Frameworks

When to Use Programmable Editing

Quick Example

Next Steps

Timeline Architecture

Clip Parameters

The 4-Layer Architecture

Layer 1: Assets

Layer 2: Clips

Layer 3: Tracks

Sequencing Rules

Z-Order

Layer 4: Timeline

Common Patterns

Highlight Reel from Search Results

Video with Logo Overlay

Timed Captioned Video

What You Can Build

TikTok Lyric Videos

Faceless Video Creator

Intro & Outro Automation

Brand Elements

Best Practices

​When to Use Programmable Editing

​Quick Example

​Next Steps

Timeline Architecture

Clip Parameters

​The 4-Layer Architecture

​Layer 1: Assets

​Layer 2: Clips

​Layer 3: Tracks

​Sequencing Rules

​Z-Order

​Layer 4: Timeline

​Common Patterns

​Highlight Reel from Search Results

​Video with Logo Overlay

​Timed Captioned Video

​What You Can Build

TikTok Lyric Videos

Faceless Video Creator

Intro & Outro Automation

Brand Elements

​Best Practices

When to Use Programmable Editing

Quick Example

Next Steps

The 4-Layer Architecture

Layer 1: Assets

Layer 2: Clips

Layer 3: Tracks

Sequencing Rules

Z-Order

Layer 4: Timeline

Common Patterns

Highlight Reel from Search Results

Video with Logo Overlay

Timed Captioned Video

What You Can Build

Best Practices