Skip to main content
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 = results.compile()

# 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