Latency and Cost

Indexing and search have trade-offs between speed, quality, and cost. This guide helps you optimize for your priorities.

Quick Reference

Factor	Lower Cost	Higher Quality
Frame count	1 frame/scene	3-5 frames/scene
Scene interval	30+ seconds	5-10 seconds
Extraction type	Time-based	Shot-based
Prompt complexity	Simple	Detailed

Indexing Cost Factors

Frame Count

More frames = more vision API calls = higher cost.

from videodb import SceneExtractionType

# Economical: 1 frame per scene
video.index_scenes(
    extraction_type=SceneExtractionType.time_based,
    extraction_config={"time": 30, "frame_count": 1},
    prompt="Describe the scene"
)

# Premium: 5 frames per scene
video.index_scenes(
    extraction_type=SceneExtractionType.time_based,
    extraction_config={"time": 10, "frame_count": 5},
    prompt="Describe the activity and how it progresses"
)

// Economical: 1 frame per scene
await video.indexScenes({
    extractionType: 'time',
    extractionConfig: { time: 30, frame_count: 1 },
    prompt: "Describe the scene"
});

// Premium: 5 frames per scene
await video.indexScenes({
    extractionType: 'time',
    extractionConfig: { time: 10, frame_count: 5 },
    prompt: "Describe the activity and how it progresses"
});

Config	Scenes/hour	Frames/hour	Relative Cost
30s, 1 frame	120	120	1x
10s, 1 frame	360	360	3x
10s, 3 frames	360	1,080	9x
5s, 5 frames	720	3,600	30x

Scene Interval

Shorter intervals = more scenes = more processing.

# Long interval: fewer scenes, lower cost
video.index_scenes(
    extraction_type=SceneExtractionType.time_based,
    extraction_config={"time": 60},  # 1 scene per minute
    prompt="Describe the main topic"
)

# Short interval: more scenes, higher cost
video.index_scenes(
    extraction_type=SceneExtractionType.time_based,
    extraction_config={"time": 5},  # 12 scenes per minute
    prompt="Describe what's happening"
)

// Long interval: fewer scenes, lower cost
await video.indexScenes({
    extractionType: 'time',
    extractionConfig: { time: 60 },  // 1 scene per minute
    prompt: "Describe the main topic"
});

// Short interval: more scenes, higher cost
await video.indexScenes({
    extractionType: 'time',
    extractionConfig: { time: 5 },  // 12 scenes per minute
    prompt: "Describe what's happening"
});

Indexing Latency

Time-Based vs Shot-Based

Method	Latency	Best For
Time-based	Predictable	Long-form content
Shot-based	Variable	Edited content

Shot-based detection adds processing overhead but produces more natural boundaries.

Async Processing

For long videos, use callbacks to avoid blocking:

# Non-blocking with callback
scene_index_id = video.index_scenes(
    prompt="Describe the scene",
    callback_url="https://your-backend.com/webhooks/index-complete"
)

# Check status later
scene_index = video.get_scene_index(scene_index_id)
print(scene_index.status)  # "processing" or "completed"

// Non-blocking with callback
const sceneIndexId = await video.indexScenes({
    prompt: "Describe the scene",
    callbackUrl: "https://your-backend.com/webhooks/index-complete"
});

// Check status later
const sceneIndex = await video.getSceneIndex(sceneIndexId);
console.log(sceneIndex.status);  // "processing" or "completed"

Search Latency

Single Video vs Collection

Scope	Latency	Use Case
`video.search()`	Faster	Known video
`coll.search()`	Slower	Discovery

Reduce Search Space

Metadata filters improve performance:

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

# Faster: filtered search
results = coll.search(
    query="product demo",
    filter=[{"category": "marketing"}]
)

import { IndexTypeValues, SearchTypeValues } from 'videodb';

// Slower: search everything
const results = await coll.search("product demo");

// Faster: filtered search
const results = await coll.search(
    "product demo",
    SearchTypeValues.semantic,
    IndexTypeValues.scene,
    [{ category: "marketing" }]
);

Limit Results

# Return fewer results for faster response
results = video.search(
    query="highlights",
    result_threshold=5  # Only top 5
)

// Return fewer results for faster response
const results = await video.search(
    "highlights",
    SearchTypeValues.semantic,
    IndexTypeValues.spoken,
    5  // Only top 5
);

Optimization Strategies

Tiered Indexing

Create multiple indexes at different quality levels:

# Fast, cheap index for preview/discovery
preview_index = video.index_scenes(
    extraction_type=SceneExtractionType.time_based,
    extraction_config={"time": 60, "frame_count": 1},
    prompt="What is the main topic?",
    name="preview"
)

# Detailed index for deep search
detailed_index = video.index_scenes(
    extraction_type=SceneExtractionType.time_based,
    extraction_config={"time": 10, "frame_count": 3},
    prompt="Describe people, objects, and actions in detail",
    name="detailed"
)

// Fast, cheap index for preview/discovery
const previewIndex = await video.indexScenes({
    extractionType: 'time',
    extractionConfig: { time: 60, frame_count: 1 },
    prompt: "What is the main topic?",
    name: "preview"
});

// Detailed index for deep search
const detailedIndex = await video.indexScenes({
    extractionType: 'time',
    extractionConfig: { time: 10, frame_count: 3 },
    prompt: "Describe people, objects, and actions in detail",
    name: "detailed"
});

Index on Demand

Only index what you need:

# Index spoken content immediately (cheap)
video.index_spoken_words()

# Index visuals only when needed (expensive)
if user_requests_visual_search:
    video.index_scenes(prompt="Describe the scene")

Batch Processing

For large libraries, process during off-peak hours:

# Queue videos for background indexing
for video in coll.get_videos():
    video.index_scenes(
        prompt="Describe the scene",
        callback_url="https://your-backend.com/webhooks"
    )

Cost Estimation

Factors

Video duration - Longer = more scenes
Frame extraction - More frames = more API calls
Scene interval - Shorter = more scenes
Collection size - More videos = more processing

Example Calculations

Video	Config	Scenes	Frames	Cost Factor
1 hour	60s, 1 frame	60	60	1x
1 hour	30s, 1 frame	120	120	2x
1 hour	10s, 3 frames	360	1,080	18x

Recommendations by Use Case

Media Archive (Cost-Sensitive)

video.index_spoken_words()  # Always index speech (cheap)

video.index_scenes(
    extraction_type=SceneExtractionType.time_based,
    extraction_config={"time": 60, "frame_count": 1},
    prompt="Describe the main content"
)

Security Monitoring (Quality-First)

video.index_scenes(
    extraction_type=SceneExtractionType.time_based,
    extraction_config={"time": 5, "frame_count": 3},
    prompt="Identify all people, vehicles, and suspicious activity"
)

E-commerce (Balanced)

video.index_scenes(
    extraction_type=SceneExtractionType.shot_based,
    extraction_config={"threshold": 20, "frame_count": 2},
    prompt="Identify products, brands, and pricing"
)

Monitoring

Track indexing and search metrics:

import time

# Measure indexing time
start = time.time()
video.index_scenes(prompt="Describe the scene")
indexing_time = time.time() - start
print(f"Indexing took {indexing_time:.2f}s")

# Measure search time
start = time.time()
results = video.search("query")
search_time = time.time() - start
print(f"Search took {search_time:.3f}s, found {len(results.get_shots())} results")

Start Here

Core Concepts

Ingest

Understand

Act

Automate

Open Source Frameworks

Quick Reference

Indexing Cost Factors

Frame Count

Scene Interval

Indexing Latency

Time-Based vs Shot-Based

Async Processing

Search Latency

Single Video vs Collection

Reduce Search Space

Limit Results

Optimization Strategies

Tiered Indexing

Index on Demand

Batch Processing

Cost Estimation

Factors

Example Calculations

Recommendations by Use Case

Media Archive (Cost-Sensitive)

Security Monitoring (Quality-First)

E-commerce (Balanced)

Monitoring

Next Steps

Accuracy Tips

Create an Index

​Quick Reference

​Indexing Cost Factors

​Frame Count

​Scene Interval

​Indexing Latency

​Time-Based vs Shot-Based

​Async Processing

​Search Latency

​Single Video vs Collection

​Reduce Search Space

​Limit Results

​Optimization Strategies

​Tiered Indexing

​Index on Demand

​Batch Processing

​Cost Estimation

​Factors

​Example Calculations

​Recommendations by Use Case

​Media Archive (Cost-Sensitive)

​Security Monitoring (Quality-First)

​E-commerce (Balanced)

​Monitoring

​Next Steps

Accuracy Tips

Create an Index

Quick Reference

Indexing Cost Factors

Frame Count

Scene Interval

Indexing Latency

Time-Based vs Shot-Based

Async Processing

Search Latency

Single Video vs Collection

Reduce Search Space

Limit Results

Optimization Strategies

Tiered Indexing

Index on Demand

Batch Processing

Cost Estimation

Factors

Example Calculations

Recommendations by Use Case

Media Archive (Cost-Sensitive)

Security Monitoring (Quality-First)

E-commerce (Balanced)

Monitoring

Next Steps