On This Page

Live API: Creating VOD Clips

Product(s)

Live

Role(s)

API Developer

Topic(s)

Live Streaming

API(s)

Live API

This topic shows you how to create video-on-demand (VOD) clips from your live streams.

Overview

Clips are videos extracted from a live stream. They can be sent to an S3 bucket, an FTP site, or a Video Cloud account. The clip is created as an MP4 video, and that is what is sent to the destination in all cases. In the case of Video Cloud, the MP4 will be transcoded by the ingest system, and what kinds of renditions are created for the video will depend on the ingest profile used.

Definitions for clips are created using the /vods endpoint.

Clips can be created in several ways:

With stream_start_timecode and/or stream_end_timecode defined in SMPTE timecodes for the live stream event - note that this requires that the encoder be sending timecode information

With start_time and/or end_time defined relative to the start time ( stream_start_time) of the whole live stream event

Clips can be created up to 24 hours after an event. For SEP, they can be created up until the next activation or 24 hours (whichever is shorter).

The VOD API will not add any content outside of what is present in the stream. If you specify 350 on a 300 seconds long live stream, the output will be 300 seconds long.

You do not have to use a DVR-enabled live stream for clipping to work, because the live stream is stored as it is broadcast and is available immediately and for 24 hours after the event is over.

Brightcove Live clipping will only produce a clip that is the same resolution as the highest resolution output. It will not match the source input resolution (unless that is the same as the highest resolution output).

Clips can also be sent to multiple destinations:

A Video Cloud account

An FTP server

An S3 bucket

When you specify a clip, the output must contain either a url destination or a videocloud object to detail the creation of the video and ingestion of the clip in Video Cloud.

Note: clips can be created while the live stream is running. To do this, you will need to define the start and end times of the clip in Epoch time or relative to start time of the live stream.

Fast VOD option

Fast VOD clipping uses the segments from the live stream itself, and so eliminates the need and time for transcoding. Be aware, though, that Fast VOD clips will be segment-accurate, not frame-accurate.

The the output fields for fast VOD clipping are:

mode (required for fast VOD) - for fast VOD, the value will be instant

playlist_label (optional) - Only applicable for instant mode VODs. Indicates which playlist to use to create a VOD output (from the live job). Only necessary if custom playlists were defined at live job creation.

An example of Fast VOD clipping is included in the samples below.

Credentials

If the destination you are sending the clip to requires credentials to access, you can create these using the credentials operations of the Live API. See Managing Credentials for the Live API for more details.

Endpoint

Clips are created by sending a POST request to:

https://api.bcovlive.io/v1/vods

Request body - Video Cloud

Note: we strongly recommend not specifying ingest profile that should be used for transcoding the clip, and instead use the account default profile. This will reduce the chance of errors in creating the clip in Video Cloud

Example 1: start/end times relative to stream start

The request body includes start and end times, and details about where to send the clip. Here is a sample request body that creates a clip of the third minute of a stream and sends it to a Video Cloud account:

In this example, we are creating a clip of one-minute duration and sending it to Video Cloud . We're giving the clip a name and a couple of tags, not specifying the ingest profile for retranscoding, so that the account default will be used, and instructing Video Cloud to capture thumbnail and poster images from the clip during transcoding.

Example 2: start/end times in Epoch time

The request body includes start and end times in Epoch time, and details about where to send the clip. Here is a sample request body that creates a clip of the third minute of a stream and sends it to a Video Cloud account:

In this example, we are creating a clip of one-minute duration at a specific Epoch time (in this case 22 Jan 2018 at 08:24:54 GMT).

Example 3: duration with start time relative to stream start

The request body includes the duration and stream_start_time, and details about where to send the clip. Here is a sample request body that creates a clip of the third minute of a stream and sends it to a Video Cloud account:

In this example, we are creating a clip of one-minute duration starting 5 minutes after the start of the live stream.

Example 4: duration with no start or end time

The request body includes start and end times in Epoch time, and details about where to send the clip. Here is a sample request body that creates a clip of the third minute of a stream and sends it to a Video Cloud account:

In this example, we are creating a clip of one-minute duration. Since we are not specifying a start or end time, the clip will be taken from the last 60 seconds of the live stream.

Example 5: using stream_start_timecode and stream_end_timecode

The request body includes start and end times/frames in HH:MM:SS:FF timecodes, and details about where to send the clip. Note that to use timecodes, the encoder must be sending timecodes. Here is a sample request body that creates a clip of the 50 minutes of a stream and sends it to a Video Cloud account:

The request body includes start and end times/frames in HH:MM:SS:FF timecodes, and details about where to send the clip. Note that to use timecodes, the encoder must be sending timecodes. The mode:instant field is included to specify fast VOD clipping. Here is a sample request body that creates a clip of the 50 minutes of a stream and sends it to a Video Cloud account:

In this example, we are creating a clip of 30 second duration and sending it to an S3 bucket. We provide the bucket URL including the file name for clip, and a string that is the name of saved S3 bucket credentials - the credentials can be set up for your account by Brightcove Support.

Request body fields

Here is a full table of the request body fields.

Request Body Fields

Field

Type

Description

live_job_id

String

The id of Live Stream job to create the VOD clip from.

outputs

Object[]

Array of VOD outputs

outputs.label

String

Label for the output

outputs.duration

Number

Duration of the clip in seconds. The duration can be used alone to define a clip that will be made of the final {duration} seconds of the stream. duration can also be use with any one ofstream_start_time, stream_end_time, start_time, end_time, stream_end_timecode, or stream_start_timecode.

outputs.stream_start_time

Number

Start time in seconds for the clip relative to the start time of the live stream, stream_start_time must be used with eitherstream_end_time or duration.

outputs.stream_end_time

Number

End time in seconds for the clip relative to the start time of the live stream, stream_end_time must be used with eitherstream_start_time or duration.

outputs.start_time

Number

Start time for the clip in Epoch (Unix) time (seconds), start_time must be used with eitherend_time or duration.

outputs.end_time

Number

End time for the clip in Epoch (Unix) time (seconds), end_time must be used with eitherstart_time or duration.

outputs.stream_start_timecode

Number

Start time for the clip in an SMPTE-formatted (HH:MM:SS:FF) timecode from the start of the stream, stream_start_timecode must be used with eitherstream_end_timecode or duration.

outputs.stream_end_timecode

Number

End time for the clip in an SMPTE-formatted (HH:MM:SS:FF) timecode from the end of the stream, outputs.stream_end_timecode must be used with eitherstream_start_timecode or duration.

outputs.url

String

Destination URL for the clip, note that the output must contain either this url field or a videocloud object defining the video properties and ingest options for Video Cloud.

outputs.credentials

String

The name of the credentials configured in your account for this address

An object containing inputs for Video Cloud video ingestion - see the Dynamic Ingest Reference - do not include the master field, as that information will be provided by the Live API. If no ingest profile is specified, the account default profile will be used.

Custom fieldname:value sets for the video - note that custom field that do not have a value for this video are not included in this map; custom field values have a maximum length of 1024 single-byte characters

description

String; takes the place of the old shortDescription

Short description of the video (maximum length: 248 single-byte characters)

The name of the video (maximum length: 248 single-byte characters) required

offline_enabled

Boolean

Whether the video is enabled for offline playback

projection

String

The mapping projection for 360° videos, e.g. "equirectangular"

reference_id

String

A user-specified id that uniquely identifies the video, limited to 150 characters. A referenceId can be used as a foreign-key to identify this video in another system. The reference id should not contain spaces, commas, or special characters.

whether poster and thumbnail should be captured during transcoding; defaults to true if the profile has image renditions, false if it does not - see Images and the Dynamic Ingest API for more information