FindClip

Find clips and optionally retrieve their video data. A clip identifies a range of its parent video; retrieval applies that range and any requested operations without changing the parent video.

Requires an authenticated user with objects.read permission.

Parameters

Parameter	Type / required	Default and behavior
_ref	integer / optional	Omitted: do not retain a reference for later commands in this query.
unique	Boolean / optional	false; require exactly one match when true.
constraints	expression / optional	Omitted: no property filter; other restrictions still apply.
is_connected_to	object / optional	Omitted: no graph-neighbor restriction.
is_endpoint_of	object / optional	Omitted: no connection-endpoint restriction.
group_by_source	Boolean / optional	false; group matches by the source of a relationship lookup.
per_group	Boolean / optional	false; true requires group_by_source: true and applies sort, offset and limit within each source group.
results	object / optional	Omitted: no requested property projection or aggregate. Select output or retain a reference as described below.
batch	object / optional	Omitted: no distributed result batching.
sort	string, object, or array / optional	Omitted: no explicit property ordering; nearest-neighbor commands have their own distance ordering.
limit	integer 0–2147483647 / optional	Omitted: no explicit result-count limit.
offset	integer 0–2147483647 / optional	0; skip this many matches after sorting.
uniqueids	Boolean / optional	false; include object identifiers when true.

Parameter	Type	Behavior
video_ref	integer, 1–100000	Restricts results to videos referenced earlier in the query. Cannot accompany is_connected_to.
with_label	string	Matches the clip label exactly.
blobs	boolean	Defaults to false. Set true to retrieve each selected clip as a video blob.
with_audio	boolean	Defaults to true. Includes audio from the selected timeline. Set false to return clips without audio.
as_codec	xvid, h263, h264	Video codec for returned clips. Defaults to the parent video’s codec.
as_container	mp4, avi, mov	Container for returned clips. Defaults to the parent video’s container.
fast_cut	boolean	Defaults to false. Allows a faster cut at suitable keyframe boundaries. Exact processing is used when the requested cut or transformations require it.
operations	array	Applies resize, crop, threshold, transpose, interval, or preview in order after selecting the clip.
limit	integer, 0–2147483647	Limits matches after sorting and offset.
offset	integer, 0–2147483647	Defaults to zero. Skips sorted matches before applying limit.
in_frame_number_range	object with optional integer start/stop, each 0–9007199254740992 / optional	Omitted: no restriction in this position format. Supplied endpoints are inclusive; missing endpoints are unbounded. Only one range kind is allowed and at least one endpoint is required; start must not exceed stop when both are supplied. Select clips stored in this range kind whose full range is contained by the supplied bounds; no cross-kind conversion.
in_time_offset_range	object with optional time-string start/stop / optional	Omitted: no restriction in this position format. Supplied endpoints are inclusive; missing endpoints are unbounded. Only one range kind is allowed and at least one endpoint is required; start must not exceed stop when both are supplied. Select clips stored in this range kind whose full range is contained by the supplied bounds; no cross-kind conversion.
in_time_fraction_range	object with optional numeric start/stop, each 0–1 / optional	Omitted: no restriction in this position format. Supplied endpoints are inclusive; missing endpoints are unbounded. Only one range kind is allowed and at least one endpoint is required; start must not exceed stop when both are supplied. Select clips stored in this range kind whose full range is contained by the supplied bounds; no cross-kind conversion.

Selecting and retrieving clips

Supply at most one in_..._range filter, with start, stop, or both. A match must use that position format and lie entirely within the requested range. Frame, time-offset, and fractional ranges are not converted during matching.

Retrieval selects the clip’s video frames and matching audio. Visual operations preserve their timing; interval sampling and previews select a shorter timeline. Container conversion preserves compatible audio or converts it as needed. Silent parent videos produce silent clips.

Partial retrieval uses the source’s seeking capabilities. Formats or remote sources without suitable seek support may require reading additional data.

per_group is not accepted. Limit and offset apply across query matches.

If only one ref parameter is used in the is_connected_to array, the resulting objects obtained after traversing the given connection can be associated with their source objects by specifying the parameter group_by_source as true. Similarly, if the video_ref parameter is used, the results can be grouped by the source video. The parameter is ignored if neither is_connected_to nor video_ref is used. It is set to false by default.

Response and errors

A successful response includes status:0 and returned. Requested metadata appears in entities. results.all_properties:true includes the clip’s range in its stored position format. Use results.count to count matches; a reference-only lookup may return no metadata.

With blobs:true, clips appear in the output blob array in result order, starting at blobs_start. Clip entities do not include _blob_index. See API Description for query-wide blob ordering. This command consumes no input blobs.

Invalid parameters, missing parent videos, invalid extraction ranges, and media processing failures return status:-1 with info. An unmet unique:true expectation returns status 3. A response exceeding the message limit can return status 4; reduce the result count or requested data.

Examples

Finds clips based on scene names for given video, returning the duration of the clip:

[{
    "FindVideo": {
        "_ref": 1,
        "constraints": ["$name", "==", "The Shining"]
    }
}, {
    "FindClip": {
        "video_ref": 1,
        "constraints": ["$name", "==", "Girls In Blue"],
        "results": {
            "all_properties": true
        }
    }
}]

Successful response:

[{
    "FindVideo": {
        "returned": 0,
        "status": 0
    }
}, {
    "FindClip": {
        "status": 0,
        "returned": 1,
        "entities": [{
            "_range_type": 3,
            "_range_start": 1283000000,
            "_range_stop": 1330000000,
            "_time_offset_range": {
                "start": "21:23.0",
                "stop": "22:10.0"
            },
            "name": "Girls In Blue",
            "_uniqueid": "2.0.42"
        }]
    }
}]

Find multiple clips based on the time that they are within the video, return the name of matching clips ( assuming the clips have a property, name )

[{
    "FindVideo": {
        "_ref": 1,
        "constraints": ["$name", "==", "The Shining"]
    }
}, {
    "FindClip": {
        "video_ref": 1,
        "in_time_offset_range": {
            "start": "28:00",
            "stop": "36:00"
        },
        "results": {
            "list": ["name"]
        }
    }
}]

Successful response:

[{
    "FindVideo": {
        "returned": 0,
        "status": 0
    }
}, {
    "FindClip": {
        "status": 0,
        "returned": 1,
        "entities": [{
            "name": "Room 237"
        }]
    }
}]

Find multiple clips based on the time fraction that they are within the video, return the name of matching clips ( assuming the clips have a property, name ). This example gets all clips in the first 35% ( regardless of frame count ) of the video.

[{
    "FindVideo": {
        "_ref": 1,
        "constraints": ["$name", "==", "The Shining"]
    }
}, {
    "FindClip": {
        "video_ref": 1,
        "in_time_fraction_range": {
            "start": 0,
            "stop": 0.35
        },
        "results": {
            "list": ["name"]
        }
    }
}]

Successful response:

[{
    "FindVideo": {
        "returned": 0,
        "status": 0
    }
}, {
    "FindClip": {
        "status": 0,
        "returned": 2,
        "entities": [{
            "name": "Isolated Island"
        }, {
            "name": "The Lodge"
        }]
    }
}]