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
The frame_number parameter is the position in a video defined by zero-based frame number. The type is a nonnegative integer.
Example
[{
"AddVideo": {
"_ref": 1,
"properties": {
"name": "my_video"
}
}
}, {
"AddFrame": {
"video_ref": 1,
"frame_number": 99,
"properties": {
"source": "main character image"
}
}
}]
Successful response:
[{
"AddVideo": {
"status": 0
}
}, {
"AddFrame": {
"status": 0
}
}]
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.
Field | Type / required | Behavior |
|---|---|---|
| nonnegative integer / optional | Inclusive lower bound; omitted leaves that side unrestricted. |
| 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.
[{
"FindVideo": {
"_ref": 1,
"constraints": ["$year_captured", "==", 1990]
}
}, {
"FindFrame": {
"in_frame_number_range": {
"start": 0,
"stop": 33
},
"is_connected_to": {
"ref": 1
},
"results": {
"list": ["source"]
},
"blobs": false
}
}]
Successful response:
[{
"FindVideo": {
"returned": 0,
"status": 0
}
}, {
"FindFrame": {
"returned": 1,
"status": 0,
"entities": [{
"source": "my_model"
}]
}
}]
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.
Field | Type / required | Behavior |
|---|---|---|
| nonnegative integer / required | First frame in an object range; must be less than stop. |
| nonnegative integer / required | Last frame, inclusive; must be within the video. |
| 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:
[{
"FindVideo": {
"_ref": 1,
"constraints": ["$name", "==", "my_video"],
"blobs": false
}
}, {
"ExtractFrames": {
"video_ref": 1,
"frame_spec": [0, 50, 100, 150],
"as_format": "jpg"
}
}]
Successful response:
[{
"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:
[{
"FindVideo": {
"_ref": 1,
"constraints": ["$name", "==", "my_video"],
"blobs": false
}
}, {
"ExtractFrames": {
"video_ref": 1,
"frame_spec": {
"start": 0,
"stop": 33
},
"as_format": "jpg"
}
}]
Successful response:
[{
"FindVideo": {
"status": 0,
"returned": 0
}
}, {
"ExtractFrames": {
"status": 0,
"returned": 34,
"blobs_start": 0
}
}]
A step of 3 selects 12 frames from 0 through 33:
[{
"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:
[{
"FindVideo": {
"status": 0,
"returned": 0
}
}, {
"ExtractFrames": {
"status": 0,
"returned": 12,
"blobs_start": 0
}
}]
The following frame spec is equivalent to the one above:
[{
"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:
[{
"FindVideo": {
"status": 0,
"returned": 0
}
}, {
"ExtractFrames": {
"status": 0,
"returned": 12,
"blobs_start": 0
}
}]
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:
[{
"AddVideo": {
"_ref": 1,
"codec": "h264",
"container": "mp4",
"properties": {
"year_captured": 1991
}
}
}, {
"AddFrame": {
"video_ref": 1,
"time_fraction": 0.375,
"properties": {
"source": "my_model"
}
}
}]
Successful response:
[{
"AddVideo": {
"status": 0
}
}, {
"AddFrame": {
"status": 0
}
}]
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.
Field | Type / required | Behavior |
|---|---|---|
| number in [0, 1] / optional | Inclusive lower bound; omitted leaves that side unrestricted. |
| 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):
[{
"FindVideo": {
"_ref": 1,
"constraints": ["$year_captured", "==", 1992]
}
}, {
"FindFrame": {
"in_time_fraction_range": {
"start": 0.25,
"stop": 0.5
},
"is_connected_to": {
"ref": 1
},
"results": {
"list": ["source"]
},
"blobs": false
}
}]
Successful response:
[{
"FindVideo": {
"returned": 0,
"status": 0
}
}, {
"FindFrame": {
"returned": 1,
"status": 0,
"entities": [{
"source": "my_model"
}]
}
}]
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:
[{
"AddVideo": {
"_ref": 1,
"codec": "h264",
"container": "mp4",
"properties": {
"year_captured": 1993
}
}
}, {
"AddFrame": {
"video_ref": 1,
"time_offset": "00:00:05.125",
"properties": {
"source": "my_model"
}
}
}]
Successful response:
[{
"AddVideo": {
"status": 0
}
}, {
"AddFrame": {
"status": 0
}
}]
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.
Field | Type / required | Behavior |
|---|---|---|
| string / optional | Inclusive lower bound; omitted leaves that side unrestricted. |
| 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:
[{
"FindVideo": {
"_ref": 1,
"constraints": ["$year_captured", "==", 1994]
}
}, {
"FindFrame": {
"in_time_offset_range": {
"start": "00:00:05.1",
"stop": "00:00:05.2"
},
"is_connected_to": {
"ref": 1
},
"results": {
"list": ["source"]
},
"blobs": false
}
}]
Successful response:
[{
"FindVideo": {
"returned": 0,
"status": 0
}
}, {
"FindFrame": {
"returned": 1,
"status": 0,
"entities": [{
"source": "my_model"
}]
}
}]
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 AddClip, FindClip, and UpdateClip for how omitted endpoints are handled by each command.
Field | Type / required | Behavior |
|---|---|---|
| object | start/stop are nonnegative zero-based integers that must be exactly representable as binary64. |
| object | start/stop are strings of seconds, minutes:seconds, or hours:minutes:seconds, with an optional fractional second. |
| object | start/stop are numeric fractions in the inclusive range [0, 1]. |