---
title: "Extract Video Keyframes 10x Faster with Pixeltable's frame_iterator"
date: "2025-12-09"
author: "Pixeltable Team"
tags:
  - Video Processing
  - Keyframes
  - Performance
  - Pixeltable
  - Computer Vision
  - Video Analysis
  - Optimization
  - frame_iterator
description: "Learn how to use Pixeltable's keyframes_only parameter to dramatically speed up video processing by extracting only the most important frames, reducing compute costs and processing time."
url: "https://pixeltable.com/blog/video-keyframe-extraction-pixeltable"
---

# Extract Video Keyframes 10x Faster with Pixeltable's frame_iterator

## The Hidden Cost of Processing Every Video Frame

 
Video processing is computationally expensive. A single minute of 30fps video contains 1,800 frames. When you're running object detection, embedding generation, or any AI model on video content, processing every single frame is often wasteful, since most adjacent frames are nearly identical.

 
With Pixeltable's `keyframes_only` parameter introduced in v0.5.0, you can now extract only the frames that matter: the keyframes that represent significant visual changes in your video content.

 
## What Are Keyframes and Why Do They Matter?

 
 
In video compression, **keyframes** (also called I-frames) are complete images that don't depend on other frames for decoding. They typically occur:

 
 

 - At scene changes

 - At regular intervals (every 1-5 seconds in most codecs)

 - When there's significant visual change

 

 
By processing only keyframes, you can often reduce the number of frames you need to analyze by **90% or more** while still capturing the essential content of your video.

 
## Basic Usage: Extracting Keyframes

 
 
Here's how simple it is to extract only keyframes with Pixeltable using `frame_iterator`:

 
```python

import pixeltable as pxt
from pixeltable.functions.video import frame_iterator

# Create a table for videos
videos = pxt.create_table('demo.videos', {'video': pxt.Video})

# Insert your video first
videos.insert([{'video': '/path/to/your/video.mp4'}])

# Extract only keyframes using frame_iterator (much faster for long videos!)
keyframes = pxt.create_view(
 'demo.keyframes',
 videos,
 iterator=frame_iterator(
 video=videos.video,
 keyframes_only=True
 )
)

# Check how many keyframes were extracted
print(f"Extracted {keyframes.count()} keyframes")
keyframes.select(keyframes.frame).head(3)
 
```

 
## Performance Comparison: All Frames vs Keyframes

 
 
Let's see the dramatic difference in a real scenario:

 
```python

import pixeltable as pxt
from pixeltable.functions.video import frame_iterator
import time

# Setup
pxt.drop_dir('perf_test', force=True)
pxt.create_dir('perf_test')

# Create base table and insert video
videos = pxt.create_table('perf_test.videos', {'video': pxt.Video})
videos.insert([{'video': '/path/to/test_video.mp4'}])

# View 1: Extract ALL frames (default behavior)
start = time.time()
all_frames = pxt.create_view(
 'perf_test.all_frames',
 videos,
 iterator=frame_iterator(video=videos.video) # All frames
)
all_frames_time = time.time() - start
all_count = all_frames.count()

# View 2: Extract ONLY keyframes
start = time.time()
keyframes = pxt.create_view(
 'perf_test.keyframes',
 videos,
 iterator=frame_iterator(
 video=videos.video,
 keyframes_only=True
 )
)
keyframes_time = time.time() - start
key_count = keyframes.count()

print(f"All frames: {all_count} frames in {all_frames_time:.2f}s")
print(f"Keyframes only: {key_count} frames in {keyframes_time:.2f}s")
print(f"Reduction: {(1 - key_count/all_count) * 100:.1f}% fewer frames")
print(f"Speedup: {all_frames_time/keyframes_time:.1f}x faster")
 
```

 
Typical results show **85-95% reduction** in frames and proportional speedup in downstream processing.

 
## Real-World Pipeline: Video Search with Keyframes

 
 
Here's a complete example building a video search system that processes only keyframes:

 
```python

import pixeltable as pxt
from pixeltable.functions.video import frame_iterator
from pixeltable.functions.huggingface import clip

# Create video library
pxt.drop_dir('video_search', force=True)
pxt.create_dir('video_search')

videos = pxt.create_table('video_search.library', {
 'video': pxt.Video,
 'title': pxt.String,
 'uploaded_at': pxt.Timestamp
})

# Insert videos first
videos.insert([
 {'video': 'video1.mp4', 'title': 'Product Demo', 'uploaded_at': '2025-01-01'},
 {'video': 'video2.mp4', 'title': 'Tutorial', 'uploaded_at': '2025-01-02'},
])

# Step 1: Extract keyframes only (10x fewer frames to process!)
keyframes_view = pxt.create_view(
 'video_search.keyframes',
 videos,
 iterator=frame_iterator(
 video=videos.video,
 keyframes_only=True
 )
)

# Step 2: Generate CLIP embeddings for each keyframe
keyframes_view.add_computed_column(
 embedding=clip.image_embed(keyframes_view.frame, model_id='openai/clip-vit-base-patch32')
)

# Step 3: Create embedding index for fast similarity search
keyframes_view.add_embedding_index('embedding_idx', column=keyframes_view.embedding)

# Search across all video keyframes
def search_videos(query_text: str, top_k: int = 5):
 """Find video moments matching a text query."""
 results = keyframes_view.order_by(
 keyframes_view.embedding.similarity(string=query_text, metric='cosine'),
 asc=False
 ).limit(top_k).select(
 keyframes_view.title,
 keyframes_view.frame,
 keyframes_view.pos_msec # Frame position in milliseconds
 ).collect()
 return results

# Find moments in your video library
search_videos("person presenting slides")
 
```

 
## When to Use Keyframes vs All Frames

 
 
### ✅ Use Keyframes For:

 

 - **Video search and retrieval** - Keyframes capture scene content

 - **Thumbnail generation** - Representative frames for previews

 - **Scene detection** - Keyframes often align with scene changes

 - **Content moderation** - Scan key moments efficiently

 - **Video cataloging** - Index large video libraries quickly

 

 
### ⚠️ Use All Frames For:

 

 - **Motion analysis** - Tracking movement between frames

 - **Action recognition** - Temporal patterns matter

 - **Precise timestamp extraction** - Frame-accurate detection

 - **Video quality analysis** - Artifacts between keyframes

 

 
## Advanced: frame_iterator Options

 
The `frame_iterator` supports multiple extraction strategies via its parameters:

 
```python

import pixeltable as pxt
from pixeltable.functions.video import frame_iterator

videos = pxt.create_table('demo.sampled', {'video': pxt.Video})
videos.insert([{'video': 'sample.mp4'}])

# Option 1: Keyframes only (fewest frames, fastest)
keyframes = pxt.create_view(
 'demo.keyframes',
 videos,
 iterator=frame_iterator(video=videos.video, keyframes_only=True)
)

# Option 2: Sample at 1 FPS (one frame per second)
fps_1 = pxt.create_view(
 'demo.fps_1',
 videos,
 iterator=frame_iterator(video=videos.video, fps=1)
)

# Option 3: Sample at 0.5 FPS (one frame every 2 seconds)
fps_half = pxt.create_view(
 'demo.fps_half',
 videos,
 iterator=frame_iterator(video=videos.video, fps=0.5)
)

# Option 4: Extract exactly N frames, evenly spaced
num_frames = pxt.create_view(
 'demo.num_frames',
 videos,
 iterator=frame_iterator(video=videos.video, num_frames=10)
)

# Compare frame counts
print(f"Keyframes: {keyframes.count()}")
print(f"1 FPS: {fps_1.count()}")
print(f"0.5 FPS: {fps_half.count()}")
print(f"10 frames: {num_frames.count()}")
 
```

 
 
Per the [frame_iterator documentation](https://docs.pixeltable.com/sdk/latest/video#iterator-frame-iterator), you can use:

 

 - `fps` - Extract frames at a specific rate (can be fractional like 0.5)

 - `num_frames` - Extract exactly N frames, evenly spaced

 - `keyframes_only` - Extract only I-frames (keyframes)

 - `all_frame_attrs` - Include detailed frame metadata from pyav

 

 
## Cost Savings Example

 
 
Let's calculate the savings for a real video processing workload:

 
| Metric | All Frames (30 FPS) | Keyframes Only | Savings |
| --- | --- | --- | --- |
| Frames per minute | 1,800 | ~30-60 | 97% |
| CLIP embeddings (100 videos, 10 min each) | 1,080,000 calls | ~36,000 calls | 97% |
| Storage for embeddings | ~4 GB | ~140 MB | 97% |
| Processing time | ~6 hours | ~12 minutes | 97% |

 
## Conclusion

 
 
Pixeltable's `keyframes_only` parameter is a game-changer for video processing workflows. By intelligently extracting only the frames that represent significant visual changes, you can:

 

 - Reduce processing time by 10x or more

 - Cut compute costs dramatically

 - Scale to larger video libraries

 - Still capture the essential content of your videos

 

 
Combined with Pixeltable's [incremental processing](/blog/incremental-embedding-indexes) and [embedding management](/blog/embedding-management-guide), you have a complete toolkit for building efficient video AI applications.

 
## Resources

 

 - [frame_iterator API Reference](https://docs.pixeltable.com/sdk/latest/video#iterator-frame-iterator)

 - [Pixeltable Documentation](https://docs.pixeltable.com)

 - [Video Similarity Search Guide](/blog/video-similarity-search)

 - [Object Detection in Videos with YOLOX](/blog/object-detection-videos-yolox)

 - [Pixeltable on GitHub](https://github.com/pixeltable/pixeltable)