FindVideo

Find videos by properties, connections, or URL. Request metadata, video blobs, or both. Transformations apply to returned blobs and leave stored content unchanged.

The read-only _mime_type property identifies stored video content. Request it with results.list or results.all_properties, use it in constraints, or create a property index on it. Retrieval-time as_container, as_codec, or operations do not change this stored value.

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.

with_class

string / optional

Omitted: all classes of this command’s object type. Otherwise restrict to that exact class before other filtering or top-k.

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.

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

frame_ref

integer 1–100000

Select the parent videos of frames referenced earlier in the query.

clip_ref

integer 1–100000

Select the parent videos of clips referenced earlier in the query.

blobs

boolean

Defaults to false. Set true to retrieve video data in the output blob array.

urls

boolean

Defaults to false. With blobs:true, includes the original remote URL in returned metadata. A locally stored video has an empty URL.

with_url

string

Matches the stored remote URL exactly.

as_codec

xvid, h263, h264

Video codec for returned blobs. Defaults to the source codec.

as_container

mp4, avi, mov

Container for returned blobs. Defaults to the source container.

with_audio

boolean

Defaults to true. Preserves existing audio tracks in returned blobs. Set false to return video without audio.

operations

array

Applies resize, crop, threshold, transpose, interval, or preview in order to returned blobs.

Retrieving content

Ownership is separate from customer connections. Use frame_ref or clip_ref for parent-video traversal; is_connected_to follows customer connections. Ownership selectors intersect other supplied filters.

Specify results, _ref, uniqueids:true, or blobs:true. urls:true alone does not request output. To retrieve a remote video’s URL, use urls:true with blobs:true; a metadata-only request can return an empty URL. Returned URLs identify the original content, including when the returned blobs have been transformed.

Visual transformations preserve video timing and audio. Interval sampling and previews retain audio from the selected timeline. Container conversion may convert audio to a compatible format. Inputs without audio remain silent. Set with_audio:false to omit audio from the response.

For partial results, the amount of source data read depends on the video format, its seek information, and the remote source’s support for partial reads. A small result can still require reading a larger part of the source.

Content referenced by url can change outside ApertureDB or expire under the remote storage service’s retention policy. A Find* command returns an error if the remote content is no longer accessible.

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. The parameter is ignored if is_connected_to is absent. It is set to false by default.

Response and errors

Successful responses include status:0 and returned. Requested metadata appears in entities and describes the stored video. blobs_start identifies the first returned blob; _blob_index associates an entity with its blob. See API Description for blob ordering.

Use results.count for the number of matches. returned describes delivered objects or blobs; a reference-only lookup can match videos without returning metadata. This command consumes no input blobs.

Invalid parameters, inaccessible sources, and media processing failures return status:-1 with info. An unmet unique:true expectation returns status 3. A response exceeding the configured message limit can return status 4; reduce the result count or request a smaller preview. See Responses.

Examples

Retrieve the properties for a video:

[{
    "FindVideo": {
        "constraints": ["$name", "==", "Big Buck Bunny Trailer"],
        "blobs": false,
        "results": {
            "all_properties": true
        }
    }
}]
[{
    "FindVideo": {
        "returned": 1,
        "status": 0,
        "entities": [{
            "_class": "Videos",
            "_mime_type": "video/mp4",
            "_fps": 25,
            "_frame_count": 813,
            "_frame_height": 400,
            "_frame_width": 720,
            "_duration_us": 32520000,
            "_uniqueid": "3.1.1",
            "name": "Big Buck Bunny Trailer"
        }]
    }
}]

Retrieve all videos with a “duration_min” less that “5”, in 1080p resolution. Encode the videos using H.264 and a MP4 container:

[{
    "FindVideo": {
        "constraints": ["$duration_min", "<=", 5],
        "as_codec": "h264",
        "as_container": "mp4",
        "blobs": true,
        "operations": [{
            "type": "resize",
            "width": 1920,
            "height": 1080
        }]
    }
}]

Successful response:

[{
    "FindVideo": {
        "entities": [{
            "_class": "Videos",
            "_blob_index": 0
        }],
        "returned": 1,
        "blobs_start": 0,
        "status": 0
    }
}]

Retrieve the first 100 frames of all videos that have a connection to an Entity of the class “Category” where the “name” property is “Comedy”, in 1080p resolution. Encode the videos using H.264 and a MP4 container:

[{
    "FindEntity": {
        "with_class": "Category",
        "_ref": 1,
        "unique": true,
        "constraints": ["$name", "==", "Comedy"]
    }
}, {
    "FindVideo": {
        "as_codec": "h264",
        "as_container": "mp4",
        "is_connected_to": {
            "ref": 1
        },
        "blobs": true,
        "operations": [{
            "type": "interval",
            "start": 0,
            "stop": 100,
            "step": 1
        }, {
            "type": "resize",
            "width": 1920,
            "height": 1080
        }]
    }
}]

Successful response:

[{
    "FindEntity": {
        "returned": 0,
        "status": 0
    }
}, {
    "FindVideo": {
        "entities": [{
            "_class": "Videos",
            "_blob_index": 0
        }],
        "returned": 1,
        "blobs_start": 0,
        "status": 0
    }
}]