.. _AddVideo: AddVideo ======== Store a video with properties and optional connections. Supply one encoded video blob, or use ``url`` to register a reference to externally stored video. Each video stores a read-only ``_mime_type`` property detected from the stored content: for example, ``video/mp4``, ``video/quicktime`` (MOV), or ``video/x-msvideo`` (AVI). When ingestion operations transcode the video, the property describes the converted bytes. Remote detection uses the content, not the URL extension. Unrecognized content uses ``application/octet-stream``. Parameters ---------- ``class`` is required; it names this object's application class within its type. .. list-table:: :header-rows: 1 :widths: 20 25 55 * - Parameter - Type - Behavior * - :ref:`_ref ` - integer, 1–100000 - Declares a reference for later commands in this transaction. * - :ref:`properties ` - object - Properties to store with the video. * - :ref:`connect ` - object or array - Connections to objects referenced earlier in the transaction. * - :ref:`if_not_found ` - array expression - Inserts only when no existing video matches. A match returns status 2 and makes the matching videos available through _ref. * - :ref:`codec ` - xvid, h263, h264 - Video codec for uploaded content. Defaults to the input codec. * - :ref:`container ` - mp4, avi, mov - Container for uploaded content. Defaults to the input container. * - ``with_audio`` - boolean - Defaults to true. Preserves existing audio tracks. Set false to store the uploaded video without audio. * - :ref:`operations ` - array - Applies resize, crop, threshold, transpose, interval, or preview in order before storage. * - :ref:`url ` - string - Registers an accessible remote video. Consumes no input blob. Cannot accompany codec, container, operations, or with_audio:false. Stored content -------------- .. include:: add_details.rst Visual operations preserve video timing and audio. Previews and interval sampling retain the corresponding audio. Silent inputs remain silent. Container conversion preserves compatible audio or converts it to a format supported by the requested container. Video properties describe the stored result, including its frame count, dimensions, frame rate, and duration. A preview size limit includes audio and the complete video container. The command fails if the limit cannot hold a valid video. A URL registers a reference without copying content into managed storage. Transformations can be requested when retrieving that video with :ref:`FindVideo`. .. include:: url_updates_retention.rst Response and errors ------------------- Requires an authenticated user with ``objects.create`` permission. ``status: 0`` indicates insertion; ``status: 2`` indicates an existing match for ``if_not_found``. The command returns no output blob. Check the transaction response before assuming insertion succeeded. Invalid parameters, unreadable content, unsupported media combinations, and storage failures return a nonzero status with an ``info`` message. The input blob array must contain one blob for each AddVideo command that does not use ``url``. Examples -------- Insert a video with properties, resize to 1080p resolution, and transcode to H.264 before persisting it: .. TESTED_EXAMPLE: AddVideo_1 .. code-block:: json [{ "AddVideo": { "codec": "h264", "container": "mp4", "properties": { "name": "The Shinning", "length": 186 }, "operations": [{ "type": "resize", "width": 1920, "height": 1080 }], "class": "Videos" } }] Pass an encoded video blob with the query. Successful response: .. TESTED_EXAMPLE: AddVideo_1_response .. code-block:: json [{ "AddVideo": { "status": 0 } }] Insert a new video with properties, resize to 1080p resolution, and create a connection between the new video and an Entity of the class "Category" where the "name" property is "Comedy": .. TESTED_EXAMPLE: AddVideo_2 .. code-block:: json [{ "FindEntity": { "with_class": "Category", "_ref": 1, "unique": true, "constraints": ["$name", "==", "Comedy"] } }, { "AddVideo": { "properties": { "name": "Mean Girls", "length": 97 }, "operations": [{ "type": "resize", "width": 1920, "height": 1080 }], "connect": { "ref": 1, "class": "IsOfCategory" }, "class": "Videos" } }] Pass an encoded video blob with the query. Successful response: .. TESTED_EXAMPLE: AddVideo_2_response .. code-block:: json [{ "FindEntity": { "returned": 0, "status": 0 } }, { "AddVideo": { "status": 0 } }]