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.

Generate playable HLS streams from search results, timestamps, or timeline compositions. Export clips for download or embed streams in your application.

​
Quick Example

import videodb

conn = videodb.connect()
coll = conn.get_collection()
video = coll.get_video("m-xxx")

# Stream from search results
results = video.search("product demo")
stream_url = video.generate_stream(results)

# Stream from timestamps
stream_url = video.generate_stream([(10, 30), (45, 60)])

# Get download URL
download_url = video.download(name="sample video")

​
Stream Generation

​
From Search Results

Search returns matching segments. Generate a stream to play them as a single video. 
# Search for content
results = video.search("key moments")

# Generate playable stream
stream_url = results.compile()
# https://stream.videodb.io/v3/published/manifests/{id}.m3u8

# Play in browser
results.play()

​
From Timestamps

Create streams from specific time ranges. 
# Define time segments (start, end) in seconds
timestamps = [
    (0, 15),      # Intro
    (120, 180),   # Main content
    (300, 330)    # Conclusion
]

stream_url = video.generate_stream(timestamps)

​
From Timeline

Export composed timelines as streams. 
from videodb.editor import Timeline, VideoAsset

# Build timeline
timeline = Timeline(conn)
timeline.add_inline(VideoAsset(video.id, start=10, end=30))
timeline.add_inline(VideoAsset(video.id, start=60, end=90))

# Generate stream
stream_url = timeline.generate_stream()

​
Stream URL Format

All generated streams use HLS format: 
https://stream.videodb.io/v3/published/manifests/{manifest-id}.m3u8
PropertyValue
FormatHLS (HTTP Live Streaming)
Container.m3u8 manifest with .ts segments
CompatibilityAll modern browsers, native apps

​
Download and Export

​
Get Video URL

# Full video download URL
download_url = video.download(name="sample video")
# https://cdn.videodb.io/v3/{collection}/{video}.mp4

​
Get Audio URL

# Audio-only download
audio_url = audio.generate_url()

​
Get Image URL

# Generated image URL
image_url = image.generate_url()

​
Embedding Streams

​
HTML5 Video

<video controls>
  <source
    src="https://stream.videodb.io/v3/published/manifests/{id}.m3u8"
    type="application/x-mpegURL"
  >
</video>

​
With HLS.js

<script src="https://cdn.jsdelivr.net/npm/hls.js@latest"></script>
<video id="video" controls></video>

<script>
const video = document.getElementById('video');
const streamUrl = 'https://stream.videodb.io/v3/...';

if (Hls.isSupported()) {
  const hls = new Hls();
  hls.loadSource(streamUrl);
  hls.attachMedia(video);
}
</script>

​
React Component

import Hls from 'hls.js';
import { useRef, useEffect } from 'react';

function VideoPlayer({ streamUrl }) {
  const videoRef = useRef(null);

  useEffect(() => {
    if (Hls.isSupported()) {
      const hls = new Hls();
      hls.loadSource(streamUrl);
      hls.attachMedia(videoRef.current);
      return () => hls.destroy();
    }
  }, [streamUrl]);

  return <video ref={videoRef} controls />;
}

​
VideoDB Console Player

Use the built-in player: 
https://console.videodb.io/player?url={encoded_stream_url}

​
Clip Export Patterns

​
Export Search Results as Clips

results = video.search("highlight moments")

# Export each match as separate stream
clips = []
for shot in results.get_shots():
    clip_url = shot.generate_stream()
    clips.append({
        "start": shot.start,
        "end": shot.end,
        "url": clip_url,
        "text": shot.text
    })

​
Batch Export

def export_clips(video, timestamps, prefix="clip"):
    """Export multiple clips from a video"""
    exports = []

    for i, (start, end) in enumerate(timestamps):
        stream_url = video.generate_stream([(start, end)])
        exports.append({
            "name": f"{prefix}_{i+1}",
            "start": start,
            "end": end,
            "duration": end - start,
            "url": stream_url
        })

    return exports

# Export intro, middle, outro
clips = export_clips(video, [
    (0, 30),
    (120, 180),
    (300, 330)
])

​
Combine Multiple Videos

​
Merge Clips from Different Videos

from videodb.editor import Timeline, VideoAsset

video1 = coll.get_video("m-first")
video2 = coll.get_video("m-second")
video3 = coll.get_video("m-third")

# Create combined timeline
timeline = Timeline(conn)
timeline.add_inline(VideoAsset(video1.id, start=0, end=30))
timeline.add_inline(VideoAsset(video2.id, start=10, end=40))
timeline.add_inline(VideoAsset(video3.id, start=0, end=20))

# Generate merged stream
merged_url = timeline.generate_stream()

​
Collection Highlights

from videodb.editor import Timeline, VideoAsset

# Search across collection
results = coll.search("best moments")

# Build highlight reel from top results
timeline = Timeline(conn)
for shot in results.get_shots()[:10]:  # Top 10
    video_asset = VideoAsset(id=shot.video_id, start=shot.start)
    clip = Clip(asset=video_asset, duration=shot.end - shot.start)
    track = Track()
    track.add_clip(0, clip)
    timeline.add_track(track)

highlight_url = timeline.generate_stream()

​
URL Lifecycle

StageDurationNotes
GenerationInstantStream URL returned immediately
Playback24 hoursURL valid for playback
RegenerationAnytimeCall generate_stream again for new URL

​
Refresh Expired URLs

def get_fresh_stream(video, timestamps, cache={}):
    """Get stream URL, regenerating if needed"""
    cache_key = f"{video.id}:{timestamps}"

    # Check cache and expiry
    if cache_key in cache:
        cached = cache[cache_key]
        if cached["expires"] > time.time():
            return cached["url"]

    # Generate fresh URL
    url = video.generate_stream(timestamps)
    cache[cache_key] = {
        "url": url,
        "expires": time.time() + 23 * 3600  # 23 hours
    }

    return url

​
Reframe and Aspect Ratio Conversion

​
reframe()

Convert a video to a different aspect ratio. Useful for repurposing landscape content to vertical formats for social media. 
# Reframe to vertical (9:16) for social media
vertical_video = video.reframe(target="vertical", mode="smart")

# Custom aspect ratio (square)
square_video = video.reframe(target={"width": 1, "height": 1})

# Reframe a specific time range
clip = video.reframe(start=10.0, end=60.0, target="vertical")

# Async with callback
video.reframe(
    start=10.0,
    end=60.0,
    target="vertical",
    callback_url="https://example.com/webhook"
)
ParameterTypeDescription
targetstr or dict"vertical", "square", "landscape", or {"width": int, "height": int}
modestr"simple" or "smart" (default). Smart mode uses object-aware tracking.
startfloatOptional start time in seconds
endfloatOptional end time in seconds
callback_urlstrOptional URL for async completion callback

​
smart_vertical_reframe()

Convenience method that reframes to vertical (9:16) with smart object tracking in a single call: 
vertical = video.smart_vertical_reframe()

​
Next Steps

Publishing Patterns

Embed players and share content

Timeline Architecture

Build complex compositions