Parameters for Positional Media Access ====================================== Video positions can be expressed as frame numbers, elapsed time, or fractions of the video duration. The same units define individual positions and ranges. .. _frame_number: frame_number ------------ The **frame_number** parameter is the position in a video defined by zero-based frame number. The type is a nonnegative integer. **Example** .. TESTED_EXAMPLE: VideoPosition_1 .. code-block:: json [{ "AddVideo": { "class": "Videos", "_ref": 1, "properties": { "name": "my_video" } } }, { "AddFrame": { "class": "Frames", "video_ref": 1, "frame_number": 99, "properties": { "source": "main character image" } } }] Successful response: .. TESTED_EXAMPLE: VideoPosition_1_response .. code-block:: json [{ "AddVideo": { "status": 0 } }, { "AddFrame": { "status": 0 } }] .. _in_frame_number_range: in_frame_number_range --------------------- **in_frame_number_range** selects a range of zero-based frame numbers. The ``start`` and ``stop`` values are nonnegative integers, and both bounds are inclusive. .. list-table:: :header-rows: 1 :widths: 22 22 56 * - Field - Type / required - Behavior * - ``start`` - nonnegative integer / optional - Inclusive lower bound; omitted leaves that side unrestricted. * - ``stop`` - nonnegative integer / optional - Inclusive upper bound; omitted leaves that side unrestricted. **Example** This defines a frame range from frame 0 to frame 33, with total number of 34 frames. .. TESTED_EXAMPLE: VideoPosition_2 .. code-block:: json [{ "FindVideo": { "_ref": 1, "constraints": ["$year_captured", "==", 1990] } }, { "FindFrame": { "in_frame_number_range": { "start": 0, "stop": 33 }, "video_ref": 1, "results": { "list": ["source"] }, "blobs": false } }] Successful response: .. TESTED_EXAMPLE: VideoPosition_2_response .. code-block:: json [{ "FindVideo": { "returned": 0, "status": 0 } }, { "FindFrame": { "returned": 1, "status": 0, "entities": [{ "_class": "Frames", "source": "my_model" }] } }] .. _frame_spec: frame_spec ---------- **frame_spec** selects zero-based frame numbers to extract from a video. It accepts a single frame number, an array of frame numbers, or an object specifying ``start``, ``stop``, and an optional ``step``. The object form uses nonnegative integer frame numbers and includes ``stop``; ``step`` is a positive integer that defaults to 1. .. _frame-spec-fields: .. list-table:: :header-rows: 1 :widths: 22 22 56 * - Field - Type / required - Behavior * - ``start`` - nonnegative integer / required - First frame in an object range; must be less than stop. * - ``stop`` - nonnegative integer / required - Last frame, inclusive; must be within the video. * - ``step`` - positive integer / optional - Default 1; cannot exceed stop - start. Use an integer frame number to select one frame. **Example** This defines a frame sequence 0, 50, 100, and 150: .. TESTED_EXAMPLE: VideoPosition_3 .. code-block:: json [{ "FindVideo": { "_ref": 1, "constraints": ["$name", "==", "my_video"], "blobs": false } }, { "ExtractFrames": { "video_ref": 1, "frame_spec": [0, 50, 100, 150], "as_format": "jpg" } }] Successful response: .. TESTED_EXAMPLE: VideoPosition_3_response .. code-block:: json [{ "FindVideo": { "status": 0, "returned": 0 } }, { "ExtractFrames": { "status": 0, "returned": 4, "blobs_start": 0 } }] The default step of 1 selects all 34 frames from 0 through 33: .. TESTED_EXAMPLE: VideoPosition_4 .. code-block:: json [{ "FindVideo": { "_ref": 1, "constraints": ["$name", "==", "my_video"], "blobs": false } }, { "ExtractFrames": { "video_ref": 1, "frame_spec": { "start": 0, "stop": 33 }, "as_format": "jpg" } }] Successful response: .. TESTED_EXAMPLE: VideoPosition_4_response .. code-block:: json [{ "FindVideo": { "status": 0, "returned": 0 } }, { "ExtractFrames": { "status": 0, "returned": 34, "blobs_start": 0 } }] A step of 3 selects 12 frames from 0 through 33: .. TESTED_EXAMPLE: VideoPosition_5 .. code-block:: json [{ "FindVideo": { "_ref": 1, "constraints": ["$name", "==", "my_video"], "blobs": false } }, { "ExtractFrames": { "video_ref": 1, "frame_spec": { "start": 0, "stop": 33, "step": 3 }, "as_format": "jpg" } }] Successful response: .. TESTED_EXAMPLE: VideoPosition_5_response .. code-block:: json [{ "FindVideo": { "status": 0, "returned": 0 } }, { "ExtractFrames": { "status": 0, "returned": 12, "blobs_start": 0 } }] The following frame spec is equivalent to the one above: .. TESTED_EXAMPLE: VideoPosition_6 .. code-block:: json [{ "FindVideo": { "_ref": 1, "constraints": ["$name", "==", "my_video"], "blobs": false } }, { "ExtractFrames": { "video_ref": 1, "frame_spec": [ 0, 3, 6, 9, 12, 15, 18, 21, 24, 27, 30, 33 ], "as_format": "jpg" } }] Successful response: .. TESTED_EXAMPLE: VideoPosition_6_response .. code-block:: json [{ "FindVideo": { "status": 0, "returned": 0 } }, { "ExtractFrames": { "status": 0, "returned": 12, "blobs_start": 0 } }] .. _time_fraction: time_fraction ------------- The **time_fraction** is the position in a video defined by a fraction of video duration, with 0.0 being the beginning and 1.0 being the end of the video. Type is `float`. **Example** This defines a time frame at 0.375: .. TESTED_EXAMPLE: VideoPosition_7 .. code-block:: json [{ "AddVideo": { "class": "Videos", "_ref": 1, "codec": "h264", "container": "mp4", "properties": { "year_captured": 1991 } } }, { "AddFrame": { "class": "Frames", "video_ref": 1, "time_fraction": 0.375, "properties": { "source": "my_model" } } }] Successful response: .. TESTED_EXAMPLE: VideoPosition_7_response .. code-block:: json [{ "AddVideo": { "status": 0 } }, { "AddFrame": { "status": 0 } }] .. _in_time_fraction_range: in_time_fraction_range ---------------------- **in_time_fraction_range** selects a range using fractions of the video's duration. The ``start`` and ``stop`` values are numbers between 0 and 1, and both bounds are inclusive. .. list-table:: :header-rows: 1 :widths: 22 22 56 * - Field - Type / required - Behavior * - ``start`` - number in [0, 1] / optional - Inclusive lower bound; omitted leaves that side unrestricted. * - ``stop`` - number in [0, 1] / optional - Inclusive upper bound; omitted leaves that side unrestricted. **Example** This defines a time frame range from 0.250 (end of 1st quarter of the video) to 0.500 (the middle of the video): .. TESTED_EXAMPLE: VideoPosition_8 .. code-block:: json [{ "FindVideo": { "_ref": 1, "constraints": ["$year_captured", "==", 1992] } }, { "FindFrame": { "in_time_fraction_range": { "start": 0.25, "stop": 0.5 }, "video_ref": 1, "results": { "list": ["source"] }, "blobs": false } }] Successful response: .. TESTED_EXAMPLE: VideoPosition_8_response .. code-block:: json [{ "FindVideo": { "returned": 0, "status": 0 } }, { "FindFrame": { "returned": 1, "status": 0, "entities": [{ "_class": "Frames", "source": "my_model" }] } }] .. _time_offset: time_offset ----------- The **time_offset** parameter is the position in a video defined by the time since the beginning of the video. Type is string. Format is "[[HH:]MM:]SS[.n[n[...]]]", where square brackets indicate optional elements. **Example** This defines a time offset at "5 seconds and 125 milliseconds" after the beginning of the video: .. TESTED_EXAMPLE: VideoPosition_9 .. code-block:: json [{ "AddVideo": { "class": "Videos", "_ref": 1, "codec": "h264", "container": "mp4", "properties": { "year_captured": 1993 } } }, { "AddFrame": { "class": "Frames", "video_ref": 1, "time_offset": "00:00:05.125", "properties": { "source": "my_model" } } }] Successful response: .. TESTED_EXAMPLE: VideoPosition_9_response .. code-block:: json [{ "AddVideo": { "status": 0 } }, { "AddFrame": { "status": 0 } }] .. _in_time_offset_range: in_time_offset_range -------------------- **in_time_offset_range** selects a range using elapsed times since the beginning of the video. The ``start`` and ``stop`` values use the format ``[[HH:]MM:]SS[.n[n[...]]]``, where square brackets indicate optional elements. Both bounds are inclusive. .. list-table:: :header-rows: 1 :widths: 22 22 56 * - Field - Type / required - Behavior * - ``start`` - string / optional - Inclusive lower bound; omitted leaves that side unrestricted. * - ``stop`` - string / optional - Inclusive upper bound; omitted leaves that side unrestricted. **Example** This defines a time offset range from 5.1 sec to 5.2 sec: .. TESTED_EXAMPLE: VideoPosition_10 .. code-block:: json [{ "FindVideo": { "_ref": 1, "constraints": ["$year_captured", "==", 1994] } }, { "FindFrame": { "in_time_offset_range": { "start": "00:00:05.1", "stop": "00:00:05.2" }, "video_ref": 1, "results": { "list": ["source"] }, "blobs": false } }] Successful response: .. TESTED_EXAMPLE: VideoPosition_10_response .. code-block:: json [{ "FindVideo": { "returned": 0, "status": 0 } }, { "FindFrame": { "returned": 1, "status": 0, "entities": [{ "_class": "Frames", "source": "my_model" }] } }] .. _clip-range-fields: Clip range fields ----------------- Clip commands use ``frame_number_range``, ``time_offset_range``, or ``time_fraction_range``; FindClip prefixes these names with ``in_``. Each range is an object with ``start`` and ``stop`` in one of the units below. At least one endpoint must be present; AddClip requires both. When both are present, ``start`` must not exceed ``stop``. See :doc:`../commands/AddClip`, :doc:`../commands/FindClip`, and :doc:`../commands/UpdateClip` for how omitted endpoints are handled by each command. .. list-table:: :header-rows: 1 :widths: 22 22 56 * - Field - Type / required - Behavior * - ``frame_number_range`` - object - start/stop are nonnegative zero-based integers that must be exactly representable as binary64. * - ``time_offset_range`` - object - start/stop are strings of seconds, minutes:seconds, or hours:minutes:seconds, with an optional fractional second. * - ``time_fraction_range`` - object - start/stop are numeric fractions in the inclusive range [0, 1].