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.

Parameter

Type

Behavior

_ref

integer, 1–100000

Declares a reference for later commands in this transaction.

properties

object

Properties to store with the video.

connect

object or array

Connections to objects referenced earlier in the transaction.

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.

codec

xvid, h263, h264

Video codec for uploaded content. Defaults to the input codec.

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.

operations

array

Applies resize, crop, threshold, transpose, interval, or preview in order before storage.

url

string

Registers an accessible remote video. Consumes no input blob. Cannot accompany codec, container, operations, or with_audio:false.

Stored content

The properties object stores key-value pairs on the new object.

The if_not_found condition inserts the object only when no existing object matches the condition.

The connect parameter creates connections between the new object and objects referenced earlier in the transaction.

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 FindVideo.

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.

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:

[{
    "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:

[{
    "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”:

[{
    "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:

[{
    "FindEntity": {
        "returned": 0,
        "status": 0
    }
}, {
    "AddVideo": {
        "status": 0
    }
}]