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 |
|---|---|---|
integer / optional |
Omitted: do not retain a reference for later commands in this query. |
|
|
string / optional |
Omitted: all classes of this command’s object type. Otherwise restrict to that exact class before other filtering or top-k. |
Boolean / optional |
|
|
expression / optional |
Omitted: no property filter; other restrictions still apply. |
|
object / optional |
Omitted: no graph-neighbor restriction. |
|
object / optional |
Omitted: no connection-endpoint restriction. |
|
Boolean / optional |
|
|
Boolean / optional |
|
|
object / optional |
Omitted: no requested property projection or aggregate. Select output or retain a reference as described below. |
|
string, object, or array / optional |
Omitted: no explicit property ordering; nearest-neighbor commands have their own distance ordering. |
|
integer 0–2147483647 / optional |
Omitted: no explicit result-count limit. |
|
integer 0–2147483647 / optional |
|
|
Boolean / optional |
|
Parameter |
Type |
Behavior |
|---|---|---|
|
integer 1–100000 |
Select the parent videos of frames referenced earlier in the query. |
|
integer 1–100000 |
Select the parent videos of clips referenced earlier in the query. |
boolean |
Defaults to false. Set true to retrieve video data in the output blob array. |
|
|
boolean |
Defaults to false. With blobs:true, includes the original remote URL in returned metadata. A locally stored video has an empty URL. |
|
string |
Matches the stored remote URL exactly. |
|
xvid, h263, h264 |
Video codec for returned blobs. Defaults to the source codec. |
|
mp4, avi, mov |
Container for returned blobs. Defaults to the source container. |
|
boolean |
Defaults to true. Preserves existing audio tracks in returned blobs. Set false to return video without audio. |
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
}
}]