How does frame iterator work?

You choose frames per second. Each frame is a row of a view over the video. Models and embedding indexes run on the frame column.

Video

What is a frame iterator?

A frame iterator walks a video at a chosen rate and emits one row per frame, with an index and a timestamp on the source clip.

Updated 2026-09-29 · Part of What is an iterator?

How it works

You choose frames per second.
Each frame is a row of a view over the video.
Models and embedding indexes run on the frame column.

What it is not

It is not an ffmpeg command you cron and never reattach to the parent video.

frame iterator: this, and the thing it is confused with

frame iterator: this, and the thing it is confused with
	This	Not this
Rate	You set it	Every encoded frame, always
Parent	The video row	A folder of JPEGs
Position	Frame index and timestamp	Lost after extraction

Where Pixeltable fits

Pixeltable’s view sets iterator=frame_iterator(video=Videos.video, fps=1). The frame column is what later columns read.

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

TableModel = pxt.model_base()

class Videos(TableModel, name='videos'):
    video: pxt.Video

class Frames(
    TableModel,
    name='frames',
    base=Videos,
    iterator=frame_iterator(video=Videos.video, fps=1),
):
    pass

Questions

How does frame iterator work?: You choose frames per second. Each frame is a row of a view over the video. Models and embedding indexes run on the frame column.
What is frame iterator often confused with?: It is not an ffmpeg command you cron and never reattach to the parent video.