Metadaten mit Zeitstempel verarbeiten

Plattform auswählen: HTML5 Roku

Das Interactive Media Ads (IMA) Dynamic Ad Insertion (DAI) SDK verwendet Metadaten, die in die Media-Segmente des Streams (In-Band-Metadaten) oder in die Streaming-Manifestdatei (In-Manifest-Metadaten) eingebettet sind, um die Positionen der Zuschauer und clientseitige Anzeigenereignisse zu erfassen. Metadaten werden je nach Art des wiedergegebenen Streams in verschiedenen Formaten gesendet.

Der Videoplayer empfängt zeitgesteuerte Metadaten in Batches. Je nach Player können Metadaten zum geplanten Zeitpunkt oder in Batches angezeigt werden. Jeder Metadatenstring hat einen zugehörigen Präsentationszeitstempel (Presentation Timestamp, PTS), der angibt, wann er ausgelöst werden soll.

Ihre App ist dafür verantwortlich, Metadaten zu erfassen und an das IMA DAI SDK weiterzuleiten. Das SDK bietet die folgenden Methoden zum Übergeben dieser Informationen:

onTimedMetadata

Mit dieser Methode werden Metadatenstrings, die zur Verarbeitung bereit sind, an das SDK weitergeleitet. Sie verwendet ein einzelnes Argument:

  • metadata: ein Objekt mit einem Schlüssel von TXXX und einem zugehörigen Stringwert, der mit google_ beginnt.
processMetadata

Mit dieser Methode werden Metadatenstrings für die Verarbeitung durch das SDK nach dem angegebenen PTS geplant. Sie verwendet die folgenden Argumente:

  • type: ein String mit dem Typ des zu verarbeitenden Ereignisses. Akzeptierte Werte sind ID3 für HLS oder urn:google:dai:2018 für DASH.
  • data: entweder ein Stringwert mit dem Präfix google_ oder ein Byte-Array, das diesem Format folgt ID3:u\0004u\000u\000u\0000TXXXu\0004u\000u\000u\0000google_xxxxxxxx.
  • timestamp: der Zeitstempel in Sekunden, zu dem die Daten verarbeitet werden sollen.

Jeder vom IMA DAI SDK unterstützte Streamtyp verwendet eine eigene Form von zeitgesteuerten Metadaten, wie in den folgenden Abschnitten beschrieben.

HLS MPEG2TS-Streams

Lineare DAI HLS-Streams mit MPEG2TS-Segmenten übergeben zeitgesteuerte Metadaten über In-Band-ID3-Tags an den Videoplayer. Diese ID3-Tags sind in die MPEG2TS-Segmente eingebettet und haben den Feldnamen TXXX (für benutzerdefinierte Textinhalte).

Wiedergabe in Safari

Safari verarbeitet ID3-Tags automatisch als verborgenen Track, sodass Cuechange-Ereignisse zum richtigen Zeitpunkt ausgelöst werden, um die einzelnen Metadaten zu verarbeiten. Sie können alle Metadaten unabhängig von Inhalt oder Typ an das IMA DAI SDK übergeben. Irrelevante Metadaten werden automatisch herausgefiltert.

Beispiel:

videoElement.textTracks.addEventListener('addtrack', (e) => {
  const track = e.track;
  if (track.kind === 'metadata') {
    track.mode = 'hidden';
    track.addEventListener('cuechange', () => {
      for (const cue of track.activeCues) {
        const metadata = {};
        metadata[cue.value.key] = cue.value.data;
        streamManager.onTimedMetadata(metadata);
      }
    });
  }
});
...

HLS.js

HLS.js stellt ID3-Tags in Batches über das Ereignis FRAG_PARSING_METADATA als Array von Beispielen bereit. HLS.js übersetzt die ID3-Daten nicht von Byte-Arrays in Strings und verschiebt Ereignisse nicht auf den entsprechenden PTS. Es ist nicht erforderlich, die Beispieldaten von Byte-Arrays in Strings zu decodieren oder irrelevante ID3-Tags herauszufiltern, da das IMA DAI SDK diese Decodierung und Filterung automatisch durchführt.

Beispiel:

hls.on(Hls.Events.FRAG_PARSING_METADATA, (e, data) => {
  if (streamManager && data) {
    data.samples.forEach((sample) => {
      streamManager.processMetadata('ID3', sample.data, sample.pts);
    });
  }
});
...

HLS CMAF-Streams

Lineare DAI HLS-Streams mit dem Common Media Application Framework (CMAF) übergeben zeitgesteuerte Metadaten über In-Band-eMSGv1-Boxen gemäß dem ID3 through CMAF-Standard. Diese eMSG-Boxen sind am Anfang jedes Media-Segments eingebettet. Jede ID3-eMSG enthält einen PTS relativ zur letzten Unterbrechung im Stream.

Ab Version 1.2.0 von HLS.js übergeben beide von uns vorgeschlagenen Player ID3-through-CMAF an den Nutzer, als wären es ID3-Tags. Aus diesem Grund sind die folgenden Beispiele dieselben wie für HLS MPEG2TS-Streams. Dies ist jedoch möglicherweise nicht bei allen Playern der Fall. Die Implementierung der Unterstützung für HLS CMAF-Streams erfordert möglicherweise einen eindeutigen Code zum Parsen von ID3-through-eMSG.

Wiedergabe in Safari

Safari behandelt ID3-through-eMSG-Metadaten als Pseudo-ID3-Ereignisse und stellt sie automatisch in Batches als verborgenen Track bereit, sodass cuechange-Ereignisse zum richtigen Zeitpunkt ausgelöst werden, um die einzelnen Metadaten zu verarbeiten. Sie können alle Metadaten unabhängig davon, ob sie für das Timing relevant sind, an das IMA DAI SDK übergeben. Alle nicht DAI-bezogenen Metadaten werden automatisch herausgefiltert.

Beispiel:

videoElement.textTracks.addEventListener('addtrack', (e) => {
  const track = e.track;
  if (track.kind === 'metadata') {
    track.mode = 'hidden';
    track.addEventListener('cuechange', () => {
      for (const cue of track.activeCues) {
        const metadata = {};
        metadata[cue.value.key] = cue.value.data;
        streamManager.onTimedMetadata(metadata);
      }
    });
  }
});
...

HLS.js

Ab Version 1.2.0 behandelt HLS.js ID3-through-eMSG-Metadaten als Pseudo-ID3-Ereignisse und stellt sie in Batches über das Ereignis FRAG_PARSING_METADATA als Array von Beispielen bereit. HLS.js übersetzt die ID3-Daten nicht von Byte-Arrays in Strings und verschiebt Ereignisse nicht auf den entsprechenden PTS. Es ist nicht erforderlich, die Beispieldaten von Byte-Arrays in Strings zu decodieren, da das IMA DAI SDK diese Decodierung automatisch durchführt.

Beispiel:

hls.on(Hls.Events.FRAG_PARSING_METADATA, (e, data) => {
  if (streamManager && data) {
    data.samples.forEach((sample) => {
      streamManager.processMetadata('ID3', sample.data, sample.pts);
    });
  }
});
...

DASH-Streams

Lineare DAI DASH-Streams übergeben Metadaten als Manifest-Ereignisse in einem Ereignisstream mit dem benutzerdefinierten schemeIdUri-Wert urn:google:dai:2018. Jedes Ereignis in diesen Streams enthält eine Textnutzlast und den PTS.

DASH.js

Dash.js bietet benutzerdefinierte Ereignishandler, die nach dem schemeIdUri-Wert jedes Ereignisstreams benannt sind. Diese benutzerdefinierten Handler werden in Batches ausgelöst. Sie müssen den PTS-Wert verarbeiten, um das Ereignis richtig zu timen. Das IMA DAI SDK kann dies mit der StreamManager-Methode processMetadata() für Sie übernehmen.

Beispiel:

const dash = dashjs.MediaPlayer().create();
dash.on('urn:google:dai:2018', (payload) => {
  const mediaId = payload.event.messageData;
  const pts = payload.event.calculatedPresentationTime;
  streamManager.processMetadata('urn:google:dai:2018', mediaId, pts);
});
...

Shaka Player

Shaka Player stellt Ereignisse als Teil des Ereignisses timelineregionenter bereit. Aufgrund einer Formatierungsincompatibilität mit Shaka Player muss der Metadatenwert roh über die Detail-PropertyeventNode.attributes['messageData'] abgerufen werden.

Beispiel:

player.addEventListener('timelineregionenter', function(event) {
  const detail = event.detail;
  if ( detail.eventNode.attributes &&
       detail.eventNode.attributes['messageData']) {
    const mediaId = detail.eventNode.attributes['messageData'];
    const pts = detail.startTime;
    streamManager.processMetadata("urn:google:dai:2018", mediaId, pts);
  }
});
...

Pod-Auslieferung

Für die Pod-Auslieferung gibt es verschiedene Konfigurationen zum Übergeben von zeitgesteuerten Metadaten, die von den folgenden Kriterien abhängen:

  • Streamtyp (Live- oder VOD-Stream)
  • Streamformat (HLS oder DASH)
  • Verwendeter Player
  • Verwendetes DAI-Backend

HLS-Streamformat (Live- und VOD-Streams, HLS.js-Player)

Wenn Sie einen HLS.js-Player verwenden, warten Sie auf das HLS.js FRAG_PARSING_METADATA Ereignis, um ID3-Metadaten abzurufen, und übergeben Sie sie mit StreamManager.processMetadata() an das SDK.

Wenn das Video automatisch abgespielt werden soll, nachdem alles geladen und bereit ist, warten Sie auf das HLS.js-Ereignis MANIFEST_PARSED, um die Wiedergabe auszulösen.

function loadStream(streamID) {
  hls.loadSource(url);
  hls.attachMedia(videoElement);
  
  // Timed metadata is passed HLS stream events to the streamManager.
  hls.on(Hls.Events.FRAG_PARSING_METADATA, parseID3Events);
  hls.on(Hls.Events.MANIFEST_PARSED, startPlayback);
}

function parseID3Events(event, data) {
  if (streamManager && data) {
    // For each ID3 tag in the metadata, pass in the type - ID3, the
    // tag data (a byte array), and the presentation timestamp (PTS).
    data.samples.forEach((sample) => {
      streamManager.processMetadata('ID3', sample.data, sample.pts);
    });
  }
}

function startPlayback() {
  console.log('Video Play');
  videoElement.play();
}

DASH.js (DASH-Streamformat, Live- und VOD-Streamtyp)

Wenn Sie einen DASH.js-Player verwenden, müssen Sie verschiedene Strings verwenden, um auf ID3-Metadaten für Live- oder VOD -Streams zu warten:

  • Livestreams: 'https://developer.apple.com/streaming/emsg-id3'
  • VOD-Streams: 'urn:google:dai:2018'

Übergeben Sie die ID3-Metadaten mit StreamManager.processMetadata() an das SDK.

Wenn die Videosteuerung automatisch angezeigt werden soll, nachdem alles geladen und bereit ist, warten Sie auf das DASH.js-Ereignis MANIFEST_LOADED.

const googleLiveSchema = 'https://developer.apple.com/streaming/emsg-id3';
const googleVodSchema = 'urn:google:dai:2018';
dashPlayer.on(googleLiveSchema, processMetadata);
dashPlayer.on(googleVodSchema, processMetadata);
dashPlayer.on(dashjs.MediaPlayer.events.MANIFEST_LOADED, loadlistener);

function processMetadata(metadataEvent) {
  const messageData = metadataEvent.event.messageData;
  const timestamp = metadataEvent.event.calculatedPresentationTime;

  // Use StreamManager.processMetadata() if your video player provides raw
  // ID3 tags, as with dash.js.
  streamManager.processMetadata('ID3', messageData, timestamp);
}

function loadlistener() {
  showControls();

  // This listener must be removed, otherwise it triggers as addional
  // manifests are loaded. The manifest is loaded once for the content,
  // but additional manifests are loaded for upcoming ad breaks.
  dashPlayer.off(dashjs.MediaPlayer.events.MANIFEST_LOADED, loadlistener);
}

Shaka Player mit Livestreams (DASH-Streamformat)

Wenn Sie Shaka Player für die Livestreamwiedergabe verwenden, warten Sie mit dem String 'emsg' auf Metadatenereignisse. Verwenden Sie dann die Ereignisnachrichtendaten in Ihrem Aufruf von StreamManager.onTimedMetadata().

shakaPlayer.addEventListener('emsg', (event) => onEmsgEvent(event));

function onEmsgEvent(metadataEvent) {
  // Use StreamManager.onTimedMetadata() if your video player provides
  // processed metadata, as with Shaka player livestreams.
  streamManager.onTimedMetadata({'TXXX': metadataEvent.detail.messageData});
}

Shaka Player mit VOD-Streams (DASH-Streamformat)

Wenn Sie Shaka Player für die VOD-Streamwiedergabe verwenden, warten Sie mit dem String 'timelineregionenter' auf Metadatenereignisse. Verwenden Sie dann die Ereignisnachrichtendaten in Ihrem Aufruf von StreamManager.processMetadata() mit dem String 'urn:google:dai:2018'.

shakaPlayer.addEventListener('timelineregionenter', (event) => onTimelineEvent(event));

function onTimelineEvent(metadataEvent) {
  const detail = metadataEvent.detail;
  if ( detail.eventElement.attributes &&
       detail.eventElement.attributes['messageData'] &&
       detail.eventElement.attributes['messageData'].value ) {
        const mediaId = detail.eventElement.attributes['messageData'].value;
        const pts = detail.startTime;
        // Use StreamManager.processMetadata() if your video player provides raw
        // ID3 tags, as with Shaka player VOD streams.
        streamManager.processMetadata('urn:google:dai:2018', mediaId, pts);
       }
}