You can use the Brightcove Media Write API to add cue points to a video. A cue point is a marker at a precise time point in the duration of a video. You can use cue points to trigger mid-roll ads or to separate chapters or scenes in a long-form video.
The Media Write APIs are available only for Brightcove Pro and Enterprise customers. If you are interested in upgrading your Brightcove account, please contact Brightcove for more information.
You can also add cue points using the Brightcove Advertising module or FTP batch provisioning, using the <cuepoint> XML element in your batch provisioning manifest. For more information on the different methods to add cue points, see Adding Cue Points to Videos.
You create a cue point using the create_video method of the Media API. The create_video method has this signature:
create_video(token:String, video:Video, filename:String, maxsize:Long, file:InputStream, file_checksum:String, create_multiple_renditions:Boolean, cuePoints:List):Long
To use the create_video method, pass:
| name | required? | description |
|---|---|---|
| name | Required | A name for the cue point, so that you can refer to it. |
| time | Required | The time of the cue point, measured in milliseconds from the beginning of the video. |
| forceStop | Optional | If true, the video stops playback at the cue point. This setting is valid only for AD type cue points. |
| type | Required | An integer code corresponding to the type of cue point. One of 0 (AD), 1 (CODE), or 2 (CHAPTER). An AD cue point is used to trigger mid-roll ad requests. A CHAPTER cue point indicates a chapter or scene break in the video. A CODE cue point causes an event that you can listen for and respond to. |
| metadata | Optional | A string that can be passed along with a CODE cue point. |
For example, for a video with the ID 123, to set a CHAPTER cue point 1 second into the video, a CODE cue point 48 seconds into the video, and an AD cue point 120 seconds into the video, you could post something like this to http://api.brightcove.com/services/:
{"method": "create_video",
"params": {
"token": "riBRb-rHGiBBouSAXs-Q8Nmz04kE.",
"video": {
"name": "The name is required.",
"shortDescription": "So is the shortDescription",
"cuePoints": [
{"name": "cp_chapter_1", "time": 1000, "type": 2},
{"name": "cp_code_1", "time": 48000, "type": 1, "metadata": "some data"},
{"name": "cp_ad_1", "time": 120000, "type": 0, "forceStop": "true"}
]
}
}
}
You can update or delete an existing cue point using the update_video method of the Media API. When you use the optional cuePoints parameter with the update_video method, you overwrite all of the existing cue points for the affected video. Any cue points you do not explicitly include in the cuePoints parameter will be removed.
For example, assuming you had already set cue points for the video with the ID 123, you could post something like this to http://api.brightcove.com/services/ to set an additional CHAPTER cue point 360 seconds into the video and delete the CODE cue point 48 seconds into the video:
{"method": "update_video",
"params": {
"token" : "riBRb-rHGiBBouSAXs-Q8Nmz04kE.",
"video" : {
"id": 123,
"cuePoints":[
{"name": "cp_chapter_1", "time": 1000, "type": 2},
{"name": "cp_chapter_2", "time": 360000, "type": 2},
{"name": "cp_ad_1", "time": 120000, "type": 0, "forceStop": "true"}
]
}
}
}