Metadaten mit Zeitstempel verarbeiten

Plattform auswählen:HTML5 Roku

Das IMA DAI SDK (Interactive Media Ads Dynamic Ad Insertion 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 unterschiedlichen Formaten gesendet.

Der Videoplayer empfängt zeitgesteuerte Metadaten in Batches. Je nach Player können Metadaten zur geplanten Zeit 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 für das Erfassen von Metadaten und das Weiterleiten an das IMA DAI SDK verantwortlich. Das SDK bietet die folgenden Methoden zum Übergeben dieser Informationen:

onTimedMetadata

Mit dieser Methode werden Metadaten-Strings, die zur Verarbeitung bereit sind, an das SDK weitergeleitet. Die Funktion verwendet ein einzelnes Argument:

  • metadata: ein Objekt mit dem Schlüssel TXXX und einem zugehörigen Stringwert, dem google_ vorangestellt ist.
processMetadata

Mit dieser Methode werden Metadaten-Strings für die Verarbeitung durch das SDK nach dem angegebenen PTS geplant. Sie akzeptiert die folgenden Argumente:

  • type: Ein String mit dem Typ des Ereignisses, das verarbeitet wird. Zulässige 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 entspricht: ID3:u\0004u\000u\000u\0000TXXXu\0004u\000u\000u\0000google_xxxxxxxx.
  • timestamp: Der Zeitstempel in Sekunden, zu dem die Daten verarbeitet werden sollen.

Für jeden vom IMA DAI SDK unterstützten Streamtyp wird eine eindeutige Form von zeitgesteuerten Metadaten verwendet, wie in den folgenden Abschnitten beschrieben.

HLS MPEG2TS-Streams

Bei linearen DAI-HLS-Streams mit MPEG2TS-Segmenten werden zeitgesteuerte Metadaten über In-Band-ID3-Tags an den Videoplayer übergeben. Diese ID3-Tags sind in die MPEG2TS-Segmente eingebettet und haben den Feldnamen „TXXX“ (für benutzerdefinierten, vom Nutzer definierten Textinhalt).

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. Es ist in Ordnung, alle Metadaten an das IMA DAI SDK zu übergeben, unabhängig von Inhalt oder Typ. 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 FRAG_PARSING_METADATA-Ereignis als Array von Samples bereit. HLS.js übersetzt die ID3-Daten nicht von Byte-Arrays in Strings und gleicht Ereignisse nicht mit dem entsprechenden PTS ab. Es ist nicht erforderlich, die Beispieldaten aus dem Byte-Array in einen String zu decodieren oder irrelevante ID3-Tags herauszufiltern, da das IMA DAI SDK diese Decodierung und Filterung automatisch vornimmt.

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

Bei linearen DAI-HLS-Streams mit dem Common Media Application Framework (CMAF) werden Zeitmetadaten in In-Band-eMSGv1-Feldern gemäß dem ID3-über-CMAF-Standard übergeben. Diese eMSG-Felder sind am Anfang jedes Media-Segments eingebettet. Jedes ID3-eMSG enthält einen PTS relativ zur letzten Unterbrechung im Stream.

Ab Version 1.2.0 von HLS.js werden ID3-Tags von beiden empfohlenen Playern über CMAF an den Nutzer weitergeleitet, als wären es ID3-Tags. Aus diesem Grund sind die folgenden Beispiele dieselben wie für HLS-MPEG2TS-Streams. Das 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 über eMSG.

Wiedergabe in Safari

Safari behandelt ID3- und 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. Es ist in Ordnung, alle Metadaten an das IMA DAI SDK zu übergeben, unabhängig davon, ob sie für das Timing relevant sind. Alle Metadaten, die nicht mit DAI zusammenhängen, 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-Metadaten über eMSG als Pseudo-ID3-Ereignisse und stellt sie in Batches über das FRAG_PARSING_METADATA-Ereignis als Array von Samples bereit. HLS.js übersetzt die ID3-Daten nicht von Byte-Arrays in Strings und gleicht Ereignisse nicht an den entsprechenden PTS an. Es ist nicht erforderlich, die Beispieldaten vom Byte-Array in einen String zu decodieren, da das IMA DAI SDK diese Decodierung automatisch ausfü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

Bei linearen DAI-DASH-Streams werden Metadaten als Manifest-Ereignisse in einem Ereignisstream mit dem benutzerdefinierten schemeIdUri-Wert urn:google:dai:2018 übergeben. 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 Eventstreams 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 erledigen.

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 gibt Ereignisse als Teil des timelineregionenter-Ereignisses aus. Aufgrund einer Formatierungsinkompatibilität mit Shaka Player muss der Metadatenwert über das Attribut „detail“ eventNode.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 Bereitstellung von Pods gibt es verschiedene Konfigurationen für die Weitergabe von zeitbezogenen Metadaten, die von den folgenden Kriterien abhängen:

  • Livestream- oder VOD-Streamtyp
  • HLS- oder DASH-Streamformat
  • Der verwendete Player
  • Der Typ des verwendeten DAI-Back-Ends

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

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

Wenn das Video automatisch abgespielt werden soll, sobald alles geladen und bereit ist, müssen Sie auf das MANIFEST_PARSED-Ereignis von HLS.js warten, 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, Livestream- und VOD-Streamtyp)

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

  • 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, müssen Sie auf das MANIFEST_LOADED-Ereignis von DASH.js warten.

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 Livestream-Wiedergabe verwenden, können Sie mit dem String 'emsg' auf Metadatenereignisse warten. Verwenden Sie dann die Daten der Ereignisnachricht 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-Stream-Format)

Wenn Sie Shaka Player für die Wiedergabe von VOD-Streams verwenden, verwenden Sie den String 'timelineregionenter', um auf Metadatenereignisse zu warten. Verwenden Sie dann die Daten der Ereignisbenachrichtigung 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);
       }
}