> ## 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.

# Programmable Editing

> VideoDB Editor lets you create videos programmatically using code instead of clicking timelines. Build videos using the 4-layer architecture: Asset → Clip → Track → Timeline.

## 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

```python theme={null}
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

<CardGroup cols={2}>
  <Card icon="film" title="Timeline Architecture" href="/pages/act/programmable-editing/timeline-architecture">
    Complete guide to the 4-layer architecture
  </Card>

  <Card icon="film" title="Clip Parameters" href="/pages/act/programmable-editing/clip-parameters">
    Filters, transitions, and effects
  </Card>
</CardGroup>

***

## 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.

```python theme={null}
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.

```python theme={null}
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.

```python theme={null}
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:

```python theme={null}
track.add_clip(0, clip1)   # 0s-5s
track.add_clip(5, clip2)   # 5s-10s
```

**Different tracks** = simultaneous playback (layered):

```python theme={null}
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:

```python theme={null}
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.

```python theme={null}
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

```python theme={null}
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

```python theme={null}
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

```python theme={null}
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

<CardGroup cols={2}>
  <Card title="TikTok Lyric Videos" icon="music" href="/examples-and-tutorials/content-factory/tiktok-lyric-video">
    Vertical videos with synced lyrics and AI backgrounds
  </Card>

  <Card title="Faceless Video Creator" icon="film" href="/examples-and-tutorials/content-factory/faceless-video-creator">
    Complete AI-generated videos with scripts and voiceovers
  </Card>

  <Card title="Intro & Outro Automation" icon="play" href="/examples-and-tutorials/programmatic-editing/intro-outro">
    Add branded intros and outros to all videos automatically
  </Card>

  <Card title="Brand Elements" icon="image" href="/examples-and-tutorials/programmatic-editing/brand-elements">
    Overlay logos, watermarks, and lower thirds programmatically
  </Card>
</CardGroup>

***

## 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