ExtractFrames

Retrieve selected frames from referenced videos as encoded image blobs.

Requires objects.read permission. This command takes no input blob and returns one output blob for each extracted frame.

Parameters

Parameter	Type / required	Default and behavior
video_ref	integer / required	A prior video reference in this query (AddVideo or FindVideo); no default.
frame_spec	integer, array, or object / required	No default. A nonnegative frame number, nonempty array of frame numbers, or a start/stop/step range; see below.
as_format	string / optional	Defaults to png. Allowed values: jpg, png, tif.
operations	array of objects / optional	Omitted or empty: no image transformations. Apply the supported operations to extracted frames.

Details

Frame numbers start at zero. A range object requires integer start and stop, both nonnegative; step is a positive integer defaulting to 1. The stop frame is included. Validation also requires step <= stop - start; use a single frame number or a one-element array for one frame. The runtime limits range extraction to prevent excessive frame requests.

Frame indexes must be within every referenced video. Explicit indexes are sorted and deduplicated for each video, so repeated indexes do not produce duplicate blobs. For multiple videos, each video contributes its selected frames. No database Frame objects are created.

Response and recovery

A successful response has status: 0. When frames are returned, returned is their total count and blobs_start is the first index in the response blob array. The JSON response contains no frame byte data. Returned blobs use the indexing described in Reading results.

Failure or empty result	Cause and recovery
Video not found or Error retrieving video object	Ensure video_ref selects a stored or accessible video.
Frame index or stop outside video	Check the selected videos’ lengths and reduce the requested indexes.
Too many Frames requested	Split the extraction into smaller ranges.
Media read or transformation error	Check source access, image format, and the requested operations.

See Responses for validation, authentication, and permission error envelopes. Command errors use a negative status and an info message.

Examples

Find the video with the “name” property equal to “my_video_1”, and return its 1st, 10th, and 100th frames:

[{
    "FindVideo": {
        "_ref": 1,
        "constraints": ["$name", "==", "my_video_1"]
    }
}, {
    "ExtractFrames": {
        "video_ref": 1,
        "frame_spec": [0, 9, 99]
    }
}]

Successful response:

[{
    "FindVideo": {
        "status": 0,
        "returned": 0
    }
}, {
    "ExtractFrames": {
        "status": 0,
        "returned": 3,
        "blobs_start": 0
    }
}]

Find the video with the “name” property equal to “Family Guy”, and return 1 every 5 frames in the range between the 1st and the 100th frame with 1080p resolution as “PNG”:

[{
    "FindVideo": {
        "_ref": 1,
        "constraints": ["$name", "==", "Family Guy"],
        "unique": true
    }
}, {
    "ExtractFrames": {
        "video_ref": 1,
        "as_format": "png",
        "frame_spec": {
            "start": 0,
            "stop": 99,
            "step": 5
        },
        "operations": [{
            "type": "resize",
            "width": 1920,
            "height": 1080
        }]
    }
}]

Successful response:

[{
    "FindVideo": {
        "status": 0,
        "returned": 0
    }
}, {
    "ExtractFrames": {
        "status": 0,
        "returned": 20,
        "blobs_start": 0
    }
}]