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.

Open In Colab VideoDB Editor uses two separate “start” parameters that control different aspects of video composition. This trips up almost everyone at first - you set start=10 and expect the video to play 10 seconds into your timeline, but it actually just skips the first 10 seconds of the source video. Understanding these two parameters is key to controlling both what plays and when it plays.

​
The Two Start Parameters

​
Asset.start - Source Trimming

VideoAsset(start=…) skips the beginning of the source file. 
asset = VideoAsset(
    id=video.id,
    start=10  # Skip first 10 seconds of source video
)
This controls which part of your source material gets used. Think of it like fast-forwarding to a specific timestamp before hitting play - you’re extracting a segment from your original video.

​
track.add_clip(start=…) - Timeline Positioning

Positions when the clip appears in the final timeline. 
track.add_clip(
    start=5,  # Place clip at 5-second mark in final video
    clip=clip
)
This controls when your clip plays in the composed output - like dragging a clip to a specific position on an editing timeline. It’s completely independent of what part of the source is playing.

​
Key Concept: Independent Control

These parameters are completely independent, operating in two different coordinate systems. Asset.start works in “source video time” (which part of the original file), while track.add_clip(start=…) works in “output timeline time” (when it appears in the final video). You can extract any segment from your source and place it anywhere on your timeline. 
# Extract seconds 10-20 from source, place at 5-second mark in timeline
clip = Clip(
    asset=VideoAsset(id=video.id, start=10),  # TRIMMING: skip first 10s
    duration=10  # Play for 10 seconds
)

track = Track()
track.add_clip(start=5, clip=clip)  # TIMING: appears at 5s in final
Timeline structure:
  • 0-5 seconds: Blank (background color)
  • 5-15 seconds: Video plays (showing seconds 10-20 from source)

​
Asset Parameters

​
VideoAsset

ParameterTypeDescription
idstrVideo ID from VideoDB collection
startintTimestamp (seconds) where playback begins in source file. Default: 0
volumefloatAudio volume multiplier. 1.0 = original, 0.0 = mute, 2.0 = double
cropCropCrop edges of source video

​
AudioAsset

ParameterTypeDescription
idstrAudio ID from VideoDB collection
startintTimestamp (seconds) where playback begins in source file
volumefloatAudio volume multiplier (0.0 - 2.0)

​
Common Patterns

​
Sequential Clips (No Gaps)

# Clips play one after another
track.add_clip(0, clip1)   # 0-10s
track.add_clip(10, clip2)  # 10-20s
track.add_clip(20, clip3)  # 20-30s

​
Clips with Gaps

# Intentional pauses between clips
track.add_clip(0, clip1)    # 0-10s
track.add_clip(15, clip2)   # 15-25s (5s gap)
track.add_clip(35, clip3)   # 35-45s (10s gap)

​
Overlapping Clips (Different Tracks)

main_track = Track()
main_track.add_clip(0, main_clip)

# Overlay appears at specific time
overlay_track = Track()
overlay_track.add_clip(20, overlay_clip)  # Appears at 20s

timeline.add_track(main_track)
timeline.add_track(overlay_track)

​
Complete Example

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

timeline = Timeline(conn)

# Extract 15 seconds starting at 30s from source
clip1 = Clip(
    asset=VideoAsset(
        id=video.id,
        start=30  # Skip first 30s of source
    ),
    duration=15  # Play for 15 seconds (shows 30s-45s of source)
)

track = Track()
track.add_clip(start=10, clip=clip1)  # Place at 10s in final timeline

timeline.add_track(track)
stream_url = timeline.generate_stream()
Result: Final video has blank 0-10s, then shows seconds 30-45 from source at 10-25s position.

​
Next Steps

Trimming vs Timing

Hands-on practice with trimming and timing patterns, multi-clip workflows, and timing precision.