.. _ExtractFrames: 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 ---------- .. list-table:: :header-rows: 1 :widths: 22 22 56 * - 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 :ref:`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 :doc:`../ReadingResults`. .. list-table:: :header-rows: 1 :widths: 48 52 * - 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 :doc:`../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: .. TESTED_EXAMPLE: ExtractFrames_1 .. code-block:: json [{ "FindVideo": { "_ref": 1, "constraints": ["$name", "==", "my_video_1"] } }, { "ExtractFrames": { "video_ref": 1, "frame_spec": [0, 9, 99] } }] Successful response: .. TESTED_EXAMPLE: ExtractFrames_1_response .. code-block:: json [{ "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": .. TESTED_EXAMPLE: ExtractFrames_2 .. code-block:: json [{ "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: .. TESTED_EXAMPLE: ExtractFrames_2_response .. code-block:: json [{ "FindVideo": { "status": 0, "returned": 0 } }, { "ExtractFrames": { "status": 0, "returned": 20, "blobs_start": 0 } }]