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"
 }
}

Note:

Only id3_tag object may be submitted in a request
If you use the timecode property, the job only stores the most recent request for insertion
If you use the timecode property, the encoder must be sending SMPTE-formatted (HH:MM:SS:FF) timecode stored in the tc property via OnFI
For TS inputs (RTP or SRT), the timecode is read from SEI picture timing messages which are part of the H.264 video stream. Those messages have separate hours, minutes, seconds, and frames fields. Therefore the values are not parsed in the SMPTE-formatted string.
Software encoders such as Wirecast and OBS do not support the sending timecode via OnFI packets in the RTMP stream
Elemental hardware encoders do support the sending timecode via OnFI packets in the RTMP stream
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.

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:

You could do a "curl" command. Example:


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

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.

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".
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.