Skip to main content
Search returns structured results with timestamps, descriptions, and relevance scores. Generate playable clips or stream URLs from any result.

​
Quick Example

results = video.search("car chase scene")

# Access individual shots
for shot in results.get_shots():
    print(f"{shot.start}s - {shot.end}s: {shot.text}")
    print(f"Score: {shot.search_score}")

# Play all matching segments
results.play()

# Generate a stream URL
stream_url = video.generate_stream(results)
print(stream_url)

​
Search Result Structure

Each search returns a SearchResult object containing matching shots:

​
Shot Attributes

AttributeTypeDescription
startfloatStart timestamp in seconds
endfloatEnd timestamp in seconds
textstrContent description or transcript
search_scorefloatRelevance score (0-1)
stream_urlstrDirect playback URL

​
Accessing Results

results = video.search("introduction to the topic")

# Get all shots
shots = results.get_shots()

# Access first result
first_shot = shots[0]
print(f"Starts at: {first_shot.start}")
print(f"Ends at: {first_shot.end}")
print(f"Content: {first_shot.text}")
print(f"Relevance: {first_shot.search_score}")

​
Playback Options

​
Play in Browser

Opens the matching segments in your default browser: 
results = video.search("product demo")
results.play()

​
Play Individual Shot

results = video.search("funny moments")
shots = results.get_shots()

# Play just the first match
shots[0].play()

​
Generate Stream URLs

Create playable URLs for embedding or sharing.

​
From Search Results

results = video.search("highlight reel")
stream_url = video.generate_stream(results)
# Returns: https://stream.videodb.io/v3/...

​
From Custom Timestamps

# Generate stream from specific time ranges
timestamps = [
    (10.5, 25.0),   # First segment
    (45.0, 60.0),   # Second segment
    (120.0, 135.5)  # Third segment
]

stream_url = video.generate_stream(timestamps)

​
Stream URL Format

Generated URLs are HLS streams that work in any video player: 
https://stream.videodb.io/v3/published/manifests/{manifest-id}.m3u8

​
Working with Timestamps

​
Extract Timestamps from Results

results = video.search("key moments")

# Get as list of tuples
timestamps = [(shot.start, shot.end) for shot in results.get_shots()]
# [(5.2, 15.0), (45.5, 52.3), (120.0, 145.8)]

​
Merge Overlapping Segments

def merge_timestamps(timestamps):
    """Merge overlapping time ranges"""
    if not timestamps:
        return []

    sorted_ts = sorted(timestamps)
    merged = [list(sorted_ts[0])]

    for start, end in sorted_ts[1:]:
        if start <= merged[-1][1]:
            merged[-1][1] = max(merged[-1][1], end)
        else:
            merged.append([start, end])

    return merged

# Merge results from multiple searches
ts1 = [(10, 20), (15, 25)]
ts2 = [(22, 30), (50, 60)]
merged = merge_timestamps(ts1 + ts2)
# [[10, 30], [50, 60]]

​
Embedding Streams

​
HTML Embed

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

​
React Component

import Hls from 'hls.js';

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

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

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

​
VideoDB Player

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

​
Filter and Sort Results

​
By Score

results = video.search("important moments")

# Get high-confidence results only
shots = results.get_shots()
high_confidence = [s for s in shots if s.search_score > 0.5]

​
By Duration

results = video.search("long segments")

# Get segments longer than 10 seconds
shots = results.get_shots()
long_segments = [s for s in shots if (s.end - s.start) > 10]

​
Next Steps

Collection Search

Search across your entire library

Accuracy Tips

Improve search precision