support Contact Support | system status System Status
Page Contents

    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 http://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.

    Page last updated on 09 Jun 2020