AddFrame

Adds a frame to a referenced video.

Frame is defined as a position in the video. The position can be specified in terms of (i) frame number, (ii) time offset of the frame since the beginning of the video, or (iii) fractional offset of the frame in the video, with zero being the start and one being the end of the video.

Parameters

Parameter	JSON type	Behavior
_ref	integer, 1 through 100000	Optional. Declares a unique reference for later commands in this transaction. When omitted, no reference is available to later commands. If conditional insertion finds existing objects, the reference names those matches.
connect	connection object or array of connection objects	Optional. When omitted, no additional user connections are created. Each object requires an earlier node ref. Optional class chooses a connection class; direction is in or out (default out); properties sets connection properties. Omitted class uses this command’s default connection class. Connections are created only for a newly inserted object.
frame_number	integer, 0 through 9007199254740992	Optional. Exactly one position field is required. Zero-based frame position. Do not combine position fields. Storage does not check video boundaries; retrieving an out-of-range frame can fail.
if_not_found	array expression	Optional. Checks existing objects of this type before insertion. When omitted, no duplicate lookup is performed. A match skips creation, properties, and new connections; status is 2 and _ref names all matches. An empty expression array is invalid.
label	string	Optional. Stored as “None”. Sets the object’s label independently of user properties.
properties	object mapping property names to values	Optional. When omitted, no user properties are added. Stores booleans, numbers, strings, supported arrays, or single-key _date, _blob, and _json wrappers. Bare null is rejected; property names and wrapped values are validated. See the properties reference for nested value rules.
time_fraction	number, 0 through 1 inclusive	Optional. Exactly one position field is required. Fraction of the video duration; 0 is the start and 1 the end. Do not combine position fields. Storage does not check video boundaries; retrieving an out-of-range frame can fail.
time_offset	time string: SS[.ffffff], MM:SS[.ffffff], or HH:MM:SS[.ffffff]	Optional. Exactly one position field is required. Offset from the video start. Do not combine position fields. Each colon-delimited component has one or two digits and the optional fractional part has one through six digits. Storage does not check video boundaries; retrieving an out-of-range frame can fail.
video_ref	integer, 1 through 100000	Required. Uses an earlier compatible video reference in this transaction; forward references, wrong types, and undeclared references are rejected. Creates the parent-video connection. Insertion does not check single-video cardinality or that the requested position lies inside the video.

Details

One of frame_number, time_offset or time_fraction must be specified.

Parameters time_offset or time_fraction are stored without conversion to frame number. When a retrieval of a frame is requested, e.g. via FindFrame command with "blobs": true, the time parameter is converted to a frame number by finding the latest frame that existed at the specified time.

Referenced video must be specified by the video_ref.

Response and errors

An authenticated session with the objects create permission is required.

The response is an object under AddFrame with integer status. Status 0 means creation succeeded; status 2 means conditional insertion found existing objects. No output blob or created-object count is returned.

Invalid field types, missing required fields, malformed expressions, and invalid references fail validation. Execution failures include a nonzero status and an info message; inspect the transaction response before assuming a mutation succeeded.

Example

Find the video with the “name” property equal to “my_video_1”, add frame 99 (zero-based), and add a property to the frame with key “scene” and value “main character image”:

[{
    "FindVideo": {
        "_ref": 1,
        "unique": true,
        "blobs": false,
        "constraints": ["$name", "==", "my_video_1"]
    }
}, {
    "AddFrame": {
        "video_ref": 1,
        "frame_number": 99,
        "properties": {
            "scene": "main character image"
        }
    }
}]

Successful response:

[{
    "FindVideo": {
        "status": 0,
        "returned": 0
    }
}, {
    "AddFrame": {
        "status": 0
    }
}]

Find the video with the “name” property equal to “my_video_2”, add frame at time 1h 22min 10.000sec since the start of the video, and add a property to the frame with key “scene” and value “main character image”:

[{
    "FindVideo": {
        "_ref": 1,
        "unique": true,
        "blobs": false,
        "constraints": ["$name", "==", "my_video_2"]
    }
}, {
    "AddFrame": {
        "video_ref": 1,
        "time_offset": "01:22:10.000",
        "properties": {
            "scene": "main character image"
        }
    }
}]

Successful response:

[{
    "FindVideo": {
        "status": 0,
        "returned": 0
    }
}, {
    "AddFrame": {
        "status": 0
    }
}]

Find the video with the “name” property equal to “my_video_3”, add frame at the middle of the movie, and add a property to the frame with key “scene” and value “mid-movie frame”:

[{
    "FindVideo": {
        "_ref": 1,
        "unique": true,
        "blobs": false,
        "constraints": ["$name", "==", "my_video_3"]
    }
}, {
    "AddFrame": {
        "video_ref": 1,
        "time_fraction": 0.5,
        "properties": {
            "scene": "main character image"
        }
    }
}]

[{
    "FindVideo": {
        "status": 0,
        "returned": 0
    }
}, {
    "AddFrame": {
        "status": 0
    }
}]