Live API: Insert ID3 timed metadata

Video Cloud
API Developer
Live API

This topic explains how to insert ID3 timed metadata into your Live stream using the Live API.

Insert ID3 timed metadata

ID3 timed metadata is used to send data with a live stream at a specific point in time. A typical use for ID3 is to added captions or subtitles on the fly. To insert ID3 timed metadata for an ongoing job, make a POST request to:

Sample request body

      "id3_tag": {
        "name": "cc1",
        "value": "We will now look at",
        "timecode": "15:50:49:16"
      "id3_tag": {
        "name": "cc2",
        "value": "developments in live technology",
        "timecode": "15:50:50:16"


  • ID3v2 states tag name can be up to 4 characters
  • value can be up to 256KB
  • timecode is optional - when omitted, insertion will be immediate

Sample response

      "id": "JOB_ID",
      "id3_tag": {
        "tag_name": "BCOV",
        "tag_value": "my value"

Do SMPTE timecodes exist in the input?

Not all encoders send SMPTE timecodes. To check if they exist in your input, one way to check is to look at the VOD chunklist for tags like #VOD-TIMING:timecode=15:18:36:01,wallclock=1549047672441,tsvideo=25400,tsaudio=-1. The vod chunklist URL should be available on output_media_files[0].playback_url_vod when you retrieve the Job information.