Skip to main content

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​

Details​

properties are key-value pairs associated with the entity. Check properties for more details.

if_not_found can be used to turn this command into "conditional add". Check if_not_found for more details.

connect can be used to create a connection between the added object and other object(s). Check connect for more details.

One of frame_number_range, time_offset_range <time_offset_range> or time_fraction_range must be specified. Mulitple 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.

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.

As we can see in the following example, 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
        }
    }]