AddClip

Adds a Clip to a video.

A Clip is defined as a contiguous part of the video between its two positions. The two positions can be specified in terms of (i) frame numbers, (ii) time since the beginning of the video, or (iii) fraction of 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_range	object with nonnegative integer start/stop, at most 9007199254740992	Optional. Exactly one range field is required, with both start and stop. Both endpoints are required. When both endpoints are supplied, start must not exceed stop; equal endpoints are accepted. Supplied endpoints are checked against the linked video bounds.
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. No label is added. 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_range	object with numeric start/stop in [0, 1]	Optional. Exactly one range field is required, with both start and stop. Both endpoints are required. When both endpoints are supplied, start must not exceed stop; equal endpoints are accepted.
time_offset_range	object with time-string start/stop	Optional. Exactly one range field is required, with both start and stop. Both endpoints are required. When both endpoints are supplied, start must not exceed stop; equal endpoints are accepted. Time strings accept seconds, minutes:seconds, or hours:minutes:seconds with optional fractional seconds and unrestricted digit counts. Supplied endpoints are checked against the linked video bounds.
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. Exactly one matching video is required and clip endpoints must lie within its duration/frame count.

Details

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.

One of frame_number_range <frame_number_range>, time_offset_range <time_offset_range> or time_fraction_range <time_fraction_range> must be specified. Multiple range types are not supported. For adding a clip, both start and stop must be defined.

The referenced video must be specified in the video_ref. Exactly 1 video must be referenced, otherwise an error is generated.

Response and errors

An authenticated session with the objects create permission is required.

The response is an object under AddClip 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. A missing or nonunique video and a range beyond the video bounds fail the add.

Examples

frame_number_range

The frame_number_range parameter defines the clip by providing start frame number and stop frame number.

Example

The following query finds a video based on property name, and adds a clip to it. The newly created clip is defined in terms of a range of frame numbers (from 360 to 768 in this example) and adds property name to the clip.

[{
    "FindVideo": {
        "_ref": 1,
        "constraints": ["$name", "==", "The Shining"]
    }
}, {
    "AddClip": {
        "video_ref": 1,
        "frame_number_range": {
            "start": 360,
            "stop": 768
        },
        "properties": {
            "name": "Isolated Island"
        }
    }
}]

Successful response:

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

time_offset_range

The time_offset_range parameter defines the clip by providing start time and stop time. The format of start time and stop time is the standard timecode of hh:mm:ss.uuuuuu with u being microseconds. Both start and stop are time passed since the beginning of the video.

Example

This query finds a video by a property, and adds a clip. The Clip’s start and stop points are defined by the time from the beginning of the video. The time format is the standard timecode of hh:mm:ss.uuuuuu with u being microseconds.

The input does not need to include all portions; 19:35.125 is parsed as 19 minutes 35 seconds and 125ms.

[{
    "FindVideo": {
        "_ref": 1,
        "constraints": ["$name", "==", "The Shining"]
    }
}, {
    "AddClip": {
        "video_ref": 1,
        "time_offset_range": {
            "start": "19:31",
            "stop": "19:31.125"
        },
        "properties": {
            "name": "The Lodge"
        }
    }
}]

Successful response:

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

time_fraction_range

The time_fraction_range parameter defines the clip by providing start fraction and stop fraction. The fraction is expressed as a number in range of [0.0 and 1.0].

Example

This query finds a video and adds a Clip, except the Clip is defined in terms of time fraction range: the clip starts a 0.75 (i.e. 3/4) into the video, and extends to the end of the video (time fraction value 1.0).

[{
    "FindVideo": {
        "_ref": 1,
        "constraints": ["$name", "==", "The Shining"]
    }
}, {
    "AddClip": {
        "video_ref": 1,
        "time_fraction_range": {
            "start": 0.75,
            "stop": 1.0
        },
        "properties": {
            "name": "Last quarter of the film"
        }
    }
}]

Successful response:

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