.. _FindVideo: 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 ---------- .. include:: find_parameters.rst .. list-table:: :header-rows: 1 :widths: 20 25 55 * - 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. * - :ref:`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. * - :ref:`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. .. include:: url_updates_retention.rst .. include:: group_by_source_details.rst 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 :doc:`../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 :doc:`../Responses`. Examples -------- Retrieve the properties for a video: .. TESTED_EXAMPLE: FindVideo_1 .. code-block:: json [{ "FindVideo": { "constraints": ["$name", "==", "Big Buck Bunny Trailer"], "blobs": false, "results": { "all_properties": true } } }] .. TESTED_EXAMPLE: FindVideo_1_response .. code-block:: json [{ "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: .. TESTED_EXAMPLE: FindVideo_2 .. code-block:: json [{ "FindVideo": { "constraints": ["$duration_min", "<=", 5], "as_codec": "h264", "as_container": "mp4", "blobs": true, "operations": [{ "type": "resize", "width": 1920, "height": 1080 }] } }] Successful response: .. TESTED_EXAMPLE: FindVideo_2_response .. code-block:: json [{ "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: .. TESTED_EXAMPLE: FindVideo_3 .. code-block:: json [{ "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: .. TESTED_EXAMPLE: FindVideo_3_response .. code-block:: json [{ "FindEntity": { "returned": 0, "status": 0 } }, { "FindVideo": { "entities": [{ "_class": "Videos", "_blob_index": 0 }], "returned": 1, "blobs_start": 0, "status": 0 } }]