Requirements
- The Live API key for your account.
- Your live account must have the scheduler override enabled.
Create a Clip scheduler workflow
When creating a clip, you must specify both the clip time boundary (in the output field), and a scheduled time (time_utc field) to make the clip request.
The output field in the request body supports all the same fields of the outputs field in the standard VOD endpoint. However, scheduled clips only support a single output rather than a list. See VOD clipping support docs for details about available fields.
Typically, you would set time_utc to match the end boundary of your clip. The scheduled time MUST be after the end boundary of the clip, otherwise the clip request will fail at the scheduled time.
Timestamps for the time_utc field must be in UTC formatted as unix timestamp in seconds. You can use https://www.unixtimestamp.com/ for conversion.
Let's say we want to schedule a 15 min clip that will start at 2021-02-09T13:55:00+00:00. We can use the output.start_time and output.end_time to specify our clip boundary as unix time in seconds. (Again, see VOD clipping support docs for details about available fields).
start_time:
2021-02-09T13:55:00+00:00 = 1612878900
end_time:
2021-02-09T14:10:00+00:00 = 1612879800
Since the scheduler will also require a time to schedule the clip request, we can use the same value as end_time since it is also unix time in seconds.
We also want to create a Videocloud Video for the clip, so we include that in the output. A Videocloud Video will be created at the time of scheduling the workflow and its ID will be returned in the response so that you can know the video ID before the clip is made. If you later cancel the clip request or it fails at its scheduled time, the Videocloud Video will NOT be removed from your account.
Request
To create the workflow, make the following POST request:
https://api.bcovlive.io/v1/scheduler/clipHeaders
Content-Type: application/json
X-API-KEY: your API KeyRequest body
{
"job_id": "your Job ID",
"description": "My Scheduled Clip",
"clip": {
"output": {
"label": "My Scheduled Clip",
"start_time": 1612878900,
"end_time": 1612879800,
"videocloud": {
"video": {
"name": "My Scheduled Clip"
}
}
},
"time_utc": 1612879800
}
}Sample response
{
"account_id": "your Account ID",
"description": "My Tuesday Clip",
"type": "clip",
"job_id": "your Job ID",
"clip": {
"state": "pending",
"output": {
"label": "My Scheduled Clip",
"start_time": 1612878900,
"end_time": 1612879800,
"videocloud": {
"video": {
"id": "70702010152202",
"name": "My Scheduled Clip"
}
}
},
"time_utc": 1612879800
}
"workflow_id": "d44cf29f4f184757ac0995beb8a0097e",
}Note that clip.output.videocloud.video.id contains the ID of the newly created Videocloud Video. At time_utc the video source will be updated with the ingested clip.
Update a Clip scheduler workflow
You can update both the output and time_utc of your clip. These can only be updated if the job is in a pending state: "state": "pending".
Following the previous example, we want the clip to be 5 minutes shorter than planned. When updating the output field, you must provide the full object, not just the changes being made. This includes the Videocloud Video ID returned by the create call above.
Note in this example, we updated both end_time and time_utc to reflect the 5 minute reduction.
Request
To update the workflow, make the following PUT request:
https://api.bcovlive.io/v1/scheduler/clip/{workflow_id}Headers
Content-Type: application/json
X-API-KEY: your API KeyRequest body
{
"clip": {
"output": {
"label": "My Scheduled Clip",
"start_time": 1612878900,
"end_time": 1612879500,
"videocloud": {
"video": {
"id": "70702010152202",
"name": "My Scheduled Clip"
}
}
},
"time_utc": 1612879500
}
}Sample response
{
"account_id": "your Account ID",
"description": "My Tuesday Clip",
"type": "clip",
"job_id": "your Job ID",
"clip": {
"state": "pending",
"output": {
"label": "My Scheduled Clip",
"start_time": 1612878900,
"end_time": 1612879500,
"videocloud": {
"video": {
"id": "70702010152202",
"name": "My Scheduled Clip"
}
}
},
"time_utc": 1612879500
}
"workflow_id": "d44cf29f4f184757ac0995beb8a0097e",
}Cancel a Clip scheduler workflow
You can cancel the clip with a DELETE request.
Note when cancelling a Clip workflow, any Videocloud Video created at time of scheduling will NOT be removed by the backend. You must remove orphaned videos from your Videocloud account manually.
Request
To update the workflow, make the following DELETE request:
https://api.bcovlive.io/v1/scheduler/clip/{workflow_id}Headers
X-API-KEY: your API KeyRequest body
There is no request body for this request.
Sample response
{
"account_id": "your Account ID",
"description": "My Tuesday Clip",
"type": "clip",
"job_id": "your Job ID",
"clip": {
"state": "cancelled",
"output": {
"label": "My Scheduled Clip",
"start_time": 1612878900,
"end_time": 1612879500,
"videocloud": {
"video": {
"id": "70702010152202",
"name": "My Scheduled Clip"
}
}
},
"time_utc": 1612879500
}
"workflow_id": "d44cf29f4f184757ac0995beb8a0097e",
}Notifications
You can optionally configure notifications when creating the workflow. You need to provide a URL for our service to POST to. We will send a notification when the scheduler makes the clip call. You can also configure to receive a notification n seconds before the clip. See the Live Scheduler Notifications for more details.
Sample request body
{
"job_id": "your Job ID",
"description": "My Scheduled Clip",
"notification_url": "https://example.com/live/clip/callbacks",
"clip": {
"output": {
"label": "My Scheduled Clip",
"start_time": 1612878900,
"end_time": 1612879800,
"videocloud": {
"video": {
"name": "My Scheduled Clip"
}
}
},
"time_utc": 1612879800,
"notification": 600
}
}