Handle timed metadata in linear DAI streams

The Interactive Media Ads (IMA) Dynamic Ad Insertion SDK (DAI) relies on metadata information embedded in the stream's media segments (in-band metadata), or in the streaming manifest file (in-manifest metadata) to track viewers' positions and client-side ad events. Metadata is available from the DAI stream in different formats, depending on the type of stream being played. The IMA DAI SDK handles all metadata formats through a single API.

Your app is responsible for capturing metadata and forwarding it to the IMA DAI SDK. The SDK offers the StreamManager.onMessage() method to pass this information. This method forwards metadata in the form of a msg object provided by the roVideo port. These objects are then processed by the IMA DAI SDK to establish the timing for ad events. It takes a single argument:

• msg : a msg type object provided by the roVideo port.

Metadata sample code

Here's an example of how to handle the metadata from the roVideo port and pass it to the IMA DAI SDK through StreamManager.onMessage() .

  Sub 
  
 runLoop 
 () 
  
 ' 
  
 Forward 
  
 all 
  
 timed 
  
 metadata 
  
 events 
  
 to 
  
 IMA 
 . 
  
 m 
 . 
 top 
 . 
 video 
 . 
 timedMetaDataSelectionKeys 
  
 = 
  
 [ 
 "*" 
 ] 
  
 ' 
  
 Cycle 
  
 through 
  
 all 
  
 the 
  
 fields 
  
 and 
  
 set 
  
 listeners 
 . 
  
 ' 
  
 IMPORTANT 
 : 
  
 Failure 
  
 to 
  
 listen 
  
 to 
  
 the 
  
 position 
  
 and 
  
 timedmetadata 
  
 fields 
  
 could 
  
 ' 
  
 result 
  
 in 
  
 ad 
  
 impressions 
  
 not 
  
 being 
  
 reported 
 . 
  
 m 
 . 
 port 
  
 = 
  
 CreateObject 
 ( 
 "roMessagePort" 
 ) 
  
 fields 
  
 = 
  
 m 
 . 
 top 
 . 
 video 
 . 
 getFields 
 () 
  
 for 
  
 each 
  
 field 
  
 in 
  
 fields 
  
 m 
 . 
 top 
 . 
 video 
 . 
 observeField 
 ( 
 field 
 , 
  
 m 
 . 
 port 
 ) 
  
 end 
  
 for 
  
 while 
  
 True 
  
 msg 
  
 = 
  
 wait 
 ( 
 1000 
 , 
  
 m 
 . 
 port 
 ) 
  
 if 
  
 m 
 . 
 top 
 . 
 video 
  
 = 
  
 invalid 
  
 print 
  
 "exiting" 
  
 exit 
  
 while 
  
 end 
  
 if 
  
 m 
 . 
 streamManager 
 . 
 onMessage 
 ( 
 msg 
 ) 
  
 currentTime 
  
 = 
  
 m 
 . 
 top 
 . 
 video 
 . 
 position 
  
 If 
  
 currentTime 
 > 
 3 
  
 And 
  
 not 
  
 m 
 . 
 top 
 . 
 adPlaying 
  
 m 
 . 
 top 
 . 
 video 
 . 
 enableTrickPlay 
  
 = 
  
 true 
  
 End 
  
 If 
  
 end 
  
 while 
 End 
  
 Sub 
 

For more information on how to incorporate the loop handling stream metadata into your app, see the IMA Roku getting started guide . The event listener and stream start section of the guide contains the metadata handling loop.

HLS CMAF streams

Linear DAI HLS streams using the Common Media Application Framework (CMAF) pass timed metadata through in-band eMSGv1 boxes following the ID3 through CMAF standard. These eMSG boxes are embedded at the beginning of each media segment, with each ID3 eMSG containing a PTS relative to the last discontinuity in the stream.

For IMA Roku, all HLS CMAF streams send in-band ID3 data using the eMSGv0 format. IMA combines information provided by the eMSGv0 format with information from the video object.

To enable proper parsing of HLS CMAF stream ID3 events, you must send your video object in the stream request using StreamRequest.videoObject .