Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.videodb.io/llms.txt

Use this file to discover all available pages before exploring further.

​
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
LayerPurposeExample
AssetRaw content (what)VideoAsset(id=video.id)
ClipPresentation (how)Clip(asset=..., duration=10)
TrackSequencing (when)track.add_clip(0, clip)
TimelineCanvas (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()

​
Auto-Captioned Video

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

# Index speech first (required for auto-captions)
video.index_spoken_words()

# 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="auto", animation="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()

​
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

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