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.

Search across all videos in a collection with a single query. Apply metadata filters to narrow results.

​
Quick Example

import videodb

conn = videodb.connect()
coll = conn.get_collection()

# Search entire collection
results = coll.search("product announcement")

for shot in results.get_shots():
    print(f"Video: {shot.video_id}")
    print(f"Time: {shot.start}s - {shot.end}s")
    print(f"Content: {shot.text}")
ScopeMethodUse Case
Single videovideo.search()Find moments in a specific video
Entire librarycoll.search()Find content across all videos

​
Search All Videos

​
Spoken Content

# Search spoken content across all videos
results = coll.search("discusses artificial intelligence")

# Results include video IDs
for shot in results.get_shots():
    print(f"Found in video {shot.video_id} at {shot.start}s")

​
Visual Content

from videodb import IndexType

# Search scene indexes across collection
results = coll.search(
    query="person speaking at podium",
    index_type=IndexType.scene
)

​
Metadata Filtering

Narrow search to specific categories using metadata filters.

​
Index with Metadata

from videodb import SceneExtractionType

# Add metadata during indexing
video.index_scenes(
    extraction_type=SceneExtractionType.time_based,
    extraction_config={"time": 30},
    prompt="Describe the scene",
    metadata={"category": "news", "topic": "technology"}
)

​
Search with Filters

from videodb import IndexType

# Filter by metadata
results = coll.search(
    query="product launch",
    filter=[{"category": "news"}],
    index_type=IndexType.scene
)

# Multiple filters (AND logic)
results = coll.search(
    query="keynote speech",
    filter=[
        {"category": "conference"},
        {"year": "2024"}
    ],
    index_type=IndexType.scene
)

​
Metadata Guidelines

RuleLimit
Max key-value pairs5
Max key length20 characters
Max value length20 characters
Value typesstring or int

​
Scene-Level Metadata

Tag individual scenes for fine-grained filtering. 
from videodb.scene import Scene

# Create scenes with metadata
scenes = [
    Scene(
        video_id=video.id,
        start=0,
        end=60,
        description="Opening segment with logo",
        metadata={"segment_type": "intro"}
    ),
    Scene(
        video_id=video.id,
        start=60,
        end=300,
        description="Main presentation content",
        metadata={"segment_type": "content"}
    ),
    Scene(
        video_id=video.id,
        start=300,
        end=360,
        description="Q&A session",
        metadata={"segment_type": "qa"}
    )
]

# Index with scene-level metadata
video.index_scenes(scenes=scenes, name="segmented_index")

# Search only Q&A segments
results = video.search(
    query="questions about pricing",
    filter=[{"segment_type": "qa"}],
    index_type=IndexType.scene
)

​
Use Cases

​
Media Archive

# Tag videos by topic
for video in news_videos:
    video.index_scenes(
        prompt="Describe the news segment",
        metadata={"channel": "CNN", "category": "politics"}
    )

# Search political news only
results = coll.search(
    query="election coverage",
    filter=[{"category": "politics"}],
    index_type=IndexType.scene
)

​
Training Library

# Tag by skill level
beginner_videos.index_scenes(
    prompt="Describe the tutorial content",
    metadata={"level": "beginner", "topic": "python"}
)

# Find beginner Python content
results = coll.search(
    query="how to define a function",
    filter=[{"level": "beginner"}, {"topic": "python"}],
    index_type=IndexType.scene
)

​
Surveillance

# Tag by camera location
camera_footage.index_scenes(
    prompt="Identify people and vehicles",
    metadata={"location": "entrance", "camera_id": "cam_01"}
)

# Search specific camera
results = coll.search(
    query="person in red jacket",
    filter=[{"location": "entrance"}],
    index_type=IndexType.scene
)

​
Performance Considerations

​
Index Before Searching

Collection search only finds content that has been indexed: 
# Index all videos first
for video in coll.get_videos():
    video.index_spoken_words()
    video.index_scenes(prompt="Describe the scene")

# Now search across all
results = coll.search("quarterly results")

​
Use Metadata Filters

Filters reduce the search space and improve speed: 
# Fast: filtered search
results = coll.search(
    query="product demo",
    filter=[{"category": "marketing"}]
)

# Slower: unfiltered search across everything
results = coll.search("product demo")

​
Search Examples

Explore practical search implementations:

Character Clips

Extract specific characters or people from video collections

Multimodal Search

Combine text, visual, and audio search for powerful results

​
Next Steps

Accuracy Tips

Improve search precision and recall

Latency and Cost

Optimize for speed and efficiency