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": {
        "class": "Videos",
        "_ref": 1,
        "properties": {
            "name": "my_video"
        }
    }
}, {
    "AddFrame": {
        "class": "Frames",
        "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

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.

[{
    "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:

[{
    "FindVideo": {
        "returned": 0,
        "status": 0
    }
}, {
    "FindFrame": {
        "returned": 1,
        "status": 0,
        "entities": [{
            "_class": "Frames",
            "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

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:

[{
    "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": {
        "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:

[{
    "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

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):

[{
    "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:

[{
    "FindVideo": {
        "returned": 0,
        "status": 0
    }
}, {
    "FindFrame": {
        "returned": 1,
        "status": 0,
        "entities": [{
            "_class": "Frames",
            "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": {
        "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:

[{
    "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

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:

[{
    "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:

[{
    "FindVideo": {
        "returned": 0,
        "status": 0
    }
}, {
    "FindFrame": {
        "returned": 1,
        "status": 0,
        "entities": [{
            "_class": "Frames",
            "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

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].