Live API: Insert ID3 timed metadata

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

Overview

ID3 timed metadata is used to send data with a live stream at a specific point in time. To insert ID3 timed metadata for an ongoing job, make a POST request to:

https://api.bcovlive.io/v1/jobs/JOB_ID/id3tag

Sample request body

{
 "id3_tag": {
  "name": "cp1",
  "value": "Some information I want to send",
   "timecode": "15:50:49:16"
 }
}

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.

Analyze a Live Playlist to get the timecode

When you create a Brightcove Live job a default master playlist is returned. For example:

https://bcovlive-a.akamaihd.net/ade7a7b3aaea4a4d8107fb8bb262381e/eu-central-1/52725330351/playlist.m3u8

We will need the VOD master playlist for which we will need to add "_vod" at the last part of our URL extension as playlist_vod.m3u8

https://bcovlive-a.akamaihd.net/ade7a7b3aaea4a4d8107fb8bb262381e/eu-central-1/52725330351/playlist_vod.m3u8

The Playlist will be composed of several renditions/profiles, that if you "curl" the playlist, you will be able to see the renditions. Example:


curl -i "https://bcovlive-a.akamaihd.net/ade7a7b3aaea4a4d8107fb8bb262381e/eu-central-1/52725330351/playlist_vod.m3u8"

#EXTM3U
#EXT-X-VERSION:3
#EXT-X-STREAM-INF:BANDWIDTH=4292608,CODECS="avc1.100.41,mp4a.40.2",RESOLUTION=1920x1080
profile_0/chunklist_vod.m3u8
#EXT-X-STREAM-INF:BANDWIDTH=2654208,CODECS="avc1.100.41,mp4a.40.2",RESOLUTION=1280x720
profile_1/chunklist_vod.m3u8
#EXT-X-STREAM-INF:BANDWIDTH=1937408,CODECS="avc1.77.41,mp4a.40.2",RESOLUTION=960x540
profile_2/chunklist_vod.m3u8
#EXT-X-STREAM-INF:BANDWIDTH=1118208,CODECS="avc1.77.31,mp4a.40.2",RESOLUTION=640x360
profile_3/chunklist_vod.m3u8

The full list of rendition/profiles playlist will look like these "profile_0" and "profile_1" URLs:

https://bcovlive-a.akamaihd.net/ade7a7b3aaea4a4d8107fb8bb262381e/eu-central-1/52725330351/profile_0/chunklist_vod.m3u8
https://bcovlive-a.akamaihd.net/ade7a7b3aaea4a4d8107fb8bb262381e/eu-central-1/52725330351/profile_1/chunklist_vod.m3u8

    Now there are a few options to look at these VOD playlists to check the timecode:

  1. You could do a "curl" command. Example:
  2. 
    curl -i "https://bcovlive-a.akamaihd.net/ade7a7b3aaea4a4d8107fb8bb262381e/eu-central-1/52725330351/profile_0/chunklist_vod.m3u8"
    #EXTM3U
    #EXT-X-VERSION:3
    #EXT-X-TARGETDURATION:8
    #EXT-X-MEDIA-SEQUENCE:0
    #EXT-X-DISCONTINUITY-SEQUENCE:0
    #EXT-X-INDEPENDENT-SEGMENTS
    #BCOV-RENDITION-DATA-X-STREAM-INF:BANDWIDTH=4292608,RESOLUTION=1920x1080,FRAME-RATE=25.000,CODECS="mp4a.40.2,avc1.100.41"
    #VOD-STARTTIMESTAMP:1573207934483
    #VOD-MANIFESTSTARTTIME:1573207934483
    #VOD-TOTALDELETEDDURATION:0.0
    #VOD-FRAMERATE:25.0
    #VOD-TIMING:timecode=null,wallclock=1573207934483,tsvideo=3480040,tsaudio=3480007
    #EXT-X-PROGRAM-DATE-TIME:2019-11-08T10:12:11.871+00:00
    #EXTINF:7.2,
    2etzot2c_66e2f8bc56774f4b9a2e26adee46c5b3_media_2.ts
    #VOD-TIMING:timecode=null,wallclock=1573207941720,tsvideo=3487240,tsaudio=3487239
    #EXT-X-PROGRAM-DATE-TIME:2019-11-08T10:12:19.071+00:00
  3. If you use the Safari browser, you can play the master playlist or one of the chunklist. Then, open the developer network tab and search for "chunklist". Select one of them and look at the preview tab.
  4. If you do not have Safari, you can apply the same process in another browser using the Akamai player in https://players.akamai.com/hls/. Load the playlist in the Akamai Player, then open your browser network tab and search for the "chunklist".
  5. If you have a proxy, as "Charles", it is the same principle. Play one of the VOD playlists in the Safari or Akamai HLS player, and then filter the results in your proxy to look at one of the chunklist returned.