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 |
|---|---|---|
integer, 1–100000 |
Declares a reference for later commands in this transaction. |
|
object |
Properties to store with the video. |
|
object or array |
Connections to objects referenced earlier in the transaction. |
|
array expression |
Inserts only when no existing video matches. A match returns status 2 and makes the matching videos available through _ref. |
|
xvid, h263, h264 |
Video codec for uploaded content. Defaults to the input codec. |
|
mp4, avi, mov |
Container for uploaded content. Defaults to the input container. |
|
|
boolean |
Defaults to true. Preserves existing audio tracks. Set false to store the uploaded video without audio. |
array |
Applies resize, crop, threshold, transpose, interval, or preview in order before storage. |
|
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
}
}]