Live API: Creating VOD Clips

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
• With start_time and/or end_time defined in Epoch (Unix) time (in seconds)
• With duration
• Both the the Live API and the Live Module support creating clips from encrypted or DRM-protected jobs.

Notes

1. To make clips available as quickly as possible, a segment-accurate clip is first created, and then replaced by a frame-accurate clip as soon as it is available.
2. If you specify duration, the resulting clip will be as follows:
   • If the job is active and still live: (request time - duration) to (request time)
   • If the job is finished: ( finished_at - duration) to ( finished_at)
3. If you specify both start_time AND end_time:
   • If the job is active and still live: as long as the Epoch time window falls entirely within created_at and the request time, the clip will be made
   • If the job is finished: as long as the Epoch time window falls entirely within created_at and finished_at, the clip will be made
4. Clips of live streams using SSAI will not include ads.
5. Clips can be created up to 7 days after an event. For SEP, they can be created up until the next activation or 7 days (whichever is shorter).
6. 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.
7. 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 7 days after the event is over.
8. 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.

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

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:

{
  "live_job_id":"PUT-LIVE-JOB-ID-HERE",
  "outputs":[
    {
      "label": "60 secs by stream from min 2 to min 3",
      "stream_start_time": 120,
      "stream_end_time": 180,
      "credentials": "USER_VIDEOCLOUD_CREDENTIAL_LABEL",
      "videocloud": {
        "video": {
        "name": "One Minute Clip",
        "tags": ["live", "clip"]
        },
          "ingest": {
            "capture-images": true
        }
      }
    }
  ]
}

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:

{
  "live_job_id":"PUT-LIVE-JOB-ID-HERE",
    "outputs":[
      {
        "label": "60 secs - epoch time",
        "start_time": 1516652694,
        "end_time": 1516652754,
        "credentials": "USER_VIDEOCLOUD_CREDENTIAL_LABEL",
        "videocloud": {
          "video": {
          "name": "One Minute Clip",
          "tags": ["live", "clip"]
          },
            "ingest": {
            "capture-images": true
        }
      }
    }
  ]
}

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:

{
  "live_job_id":"PUT-LIVE-JOB-ID-HERE",
  "outputs":[
    {
      "label": "60 secs from start time",
      "stream_start_time": 300,
      "duration": 60,
      "credentials": "USER_VIDEOCLOUD_CREDENTIAL_LABEL",
      "videocloud": {
        "video": {
        "name": "One Minute Clip",
        "tags": ["live", "clip"]
        },
        "ingest": {
        "capture-images": true,
        "profile": "valid-ingest-profile-name"
        }
      }
    }
  ]
}

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:

{
  "live_job_id":"PUT-LIVE-JOB-ID-HERE",
  "outputs":[
    {
      "label": "60 secs - duration",
      "duration": 60,
      "credentials": "USER_VIDEOCLOUD_CREDENTIAL_LABEL",
      "videocloud": {
        "video": {
        "name": "One Minute Clip",
        "tags": ["live", "clip"]
        },
        "ingest": {
          "capture-images": true
        }
      },
      "notifications": ["https://myserver.com/api/notification_listener?type=jvod"]
    }
  ]
}

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:

{
  "live_job_id":"PUT-LIVE-JOB-ID-HERE",
  "outputs":[
    {
      "label": "Clipping using Timecode from-01:10:18:15 to-01:11:08:15",
      "stream_start_timecode": "01:10:18:15",
      "stream_end_timecode": "01:11:08:15",
      "credentials": "USER_VIDEOCLOUD_CREDENTIAL_LABEL",
      "videocloud": {
        "video": {
          "name": "Fifty Minute Clip",
          "tags": ["live", "clip"]
        },
        "ingest": {
        "capture-images": true
        }
      }
    },
    "notifications": ["https://myserver.com/api/notification_listener?type=jvod"]
  ]
}

General information about sending clips to Video Cloud

To see what fields can be included in the video and ingest objects, see the Dynamic Ingest API Reference.

{
  "live_job_id":"",
  "outputs":[
    {
      "label": "last_30",
      "duration": 30,
      "url": "s3://YOUR_BUCKET_NAME/file_name.mp4",
      "credentials": "s3-credentials",
      "notifications": ["https://myserver.com/api/notification_listener?type=jvod"]
    }
  ],
}

{
  "vod_jobs": [
    {
      "jvod_id": "9582606c50d84be5ad4bc104f2aa3360",
      "label": "last 60 secs of live job"
    }
  ],
  "live_job_id": "88ba5d87b61a4ef3a6dddabd0c38d319"
}