> ## 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.

# Latency and Cost

> Trade-offs between indexing speed, search performance, and API costs

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.

<CodeGroup>
  ```python Python theme={null}
  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"
  )
  ```

  ```javascript Node.js theme={null}
  // 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"
  });
  ```
</CodeGroup>

| 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.

<CodeGroup>
  ```python Python theme={null}
  # 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"
  )
  ```

  ```javascript Node.js theme={null}
  // 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"
  });
  ```
</CodeGroup>

***

## 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:

<CodeGroup>
  ```python Python theme={null}
  # 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"
  ```

  ```javascript Node.js theme={null}
  // 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"
  ```
</CodeGroup>

***

## 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:

<CodeGroup>
  ```python Python theme={null}
  # Slower: search everything
  results = coll.search("product demo")

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

  ```javascript Node.js theme={null}
  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" }]
  );
  ```
</CodeGroup>

### Limit Results

<CodeGroup>
  ```python Python theme={null}
  # Return fewer results for faster response
  results = video.search(
      query="highlights",
      result_threshold=5  # Only top 5
  )
  ```

  ```javascript Node.js theme={null}
  // Return fewer results for faster response
  const results = await video.search(
      "highlights",
      SearchTypeValues.semantic,
      IndexTypeValues.spoken,
      5  // Only top 5
  );
  ```
</CodeGroup>

***

## Optimization Strategies

### Tiered Indexing

Create multiple indexes at different quality levels:

<CodeGroup>
  ```python Python theme={null}
  # 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"
  )
  ```

  ```javascript Node.js theme={null}
  // 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"
  });
  ```
</CodeGroup>

### Index on Demand

Only index what you need:

```python theme={null}
# 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:

```python theme={null}
# 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

1. **Video duration** - Longer = more scenes
2. **Frame extraction** - More frames = more API calls
3. **Scene interval** - Shorter = more scenes
4. **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)

```python theme={null}
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)

```python theme={null}
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)

```python theme={null}
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:

```python theme={null}
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")
```

***

## Next Steps

<CardGroup cols={2}>
  <Card icon="target" title="Accuracy Tips" href="/pages/understand/quality-and-evaluation/accuracy-tips">
    Improve search precision
  </Card>

  <Card icon="link" title="Create an Index" href="/pages/understand/indexing-pipelines/create-an-index">
    Get started with indexing
  </Card>
</CardGroup>