Obsługa metadanych czasowych w liniowych strumieniach DAI

Działanie pakietu SDK interaktywnych reklam medialnych (IMA) do dynamicznego wstawiania reklam (DAI) wymaga informacje o metadanych umieszczone w segmentach multimediów strumienia (metadane w paśmie), lub w pliku manifestu strumieniowego przesyłania danych (metadane w pliku manifestu), aby monitorować i zdarzeniami reklamowymi po stronie klienta. Metadane są przesyłane w różnych formatach, w zależności od typu transmisji.

Odtwarzacz otrzymuje zbiorcze metadane z ograniczonym czasem trwania. W zależności od odtwarzacza mogą pojawiać się o zaplanowanym czasie lub partiami. Wszystkie metadane ciąg ma powiązaną sygnaturę czasową prezentacji (PTS), która określa, kiedy powinien .

Twoja aplikacja odpowiada za rejestrowanie metadanych i przekazywanie ich do pakietu IMA DAI SDK. Pakiet SDK umożliwia przekazywanie tych informacji za pomocą tych metod:

onTimedMetadata

Ta metoda przekazuje ciągi metadanych, które są gotowe do przetworzenia, do SDK. Przyjmuje jeden argument:

  • metadata: obiekt zawierający klucz TXXX z powiązanym ciągiem znaków. poprzedzone google_.
processMetadata

Ta metoda planuje przetwarzanie ciągów metadanych przez pakiet SDK po określony punkt PTS. Przyjmuje następujące argumenty:

  • type: ciąg znaków zawierający typ przetwarzanego zdarzenia. Zaakceptowano wartości to ID3 w przypadku HLS lub urn:google:dai:2018 w przypadku DASH
  • data: ciąg znaków zawierający prefiks google_ lub tablica bajtów ma ten format ID3:u\0004u\000u\000u\0000TXXXu\0004u\000u\000u\0000google_xxxxxxxx
  • timestamp: sygnatura czasowa w sekundach, kiedy dane mają zostać przetworzone.

Każdy typ strumienia obsługiwany przez pakiet IMA DAI SDK używa unikalnej formy metadanych zgodnie z opisem w kolejnych sekcjach.

Strumienie HLS MPEG2TS

Liniowe strumienie DAI HLS korzystające z segmentów MPEG2TS przekazują metadane ograniczone czasowo do za pomocą tagów ID3 w paśmie. Tagi ID3 są umieszczone w sekcji segmentom MPEG2TS z nazwą pola TXXX (w przypadku niestandardowego tekstu zdefiniowanego przez użytkownika) treści).

Odtwarzanie w Safari

Safari automatycznie przetwarza tagi ID3 jako ukrytą ścieżkę, aby zapewnić zdarzenia zmiany sygnału. w odpowiednim momencie do przetworzenia każdego fragmentu metadanych. Można z tobą wszystkie metadane do pakietu IMA DAI SDK niezależnie od treści i typu. Są nie na temat są automatycznie odfiltrowywane.

Oto przykład:

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 udostępnia tagi ID3 partiami za pomocą zdarzenia FRAG_PARSING_METADATA, w postaci tablicy przykładów. HLS.js nie tłumaczy danych ID3 z tablic bajtów do ciągów znaków i nie kompensuje zdarzeń do odpowiadającego im PTS. Nie niezbędne do zdekodowania przykładowych danych z tablicy bajtów do ciągu znaków lub odfiltrowania nietrafne tagi ID3, ponieważ pakiet IMA DAI SDK dekoduje i filtruje automatycznie.

Oto przykład:

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

Strumienie HLS CMAF

Liniowe strumienie DAI HLS korzystające z karty Common Media Application Framework (CMAF) metadanych z sygnaturą czasową poprzez pola eMSGv1 w paśmie po ciągu ID3 do CMAF. Te pudełka eMSG są umieszczone na początku każdego segmentu multimediów, przy czym każda wiadomość eMSG o identyfikatorze ID3 zawiera PTS względem ostatniej nieciągłości w strumieniu.

Od wersji 1.2.0 pliku HLS.js oba proponowane przez nas odtwarzacze mają już kod ID3 za pomocą CMAF, tak jakby były to tagi ID3. Z tego powodu poniższe przykłady są takie same jak w przypadku strumieni HLS MPEG2TS. Może to jednak spowodować Nie dotyczy to wszystkich graczy, dlatego warto wdrożyć obsługę HLS CMAF. strumienie mogą wymagać unikalnego kodu do analizy ID3 przez eMSG.

Odtwarzanie w Safari

Safari traktuje metadane ID3 przez eMSG jako pseudo zdarzenia ID3, udostępniając je w grupowane automatycznie jako ukrytą ścieżkę, np. zdarzenia cuechange. w odpowiednim momencie do przetworzenia każdego fragmentu metadanych. Można przekazują wszystkie metadane do pakietu IMA DAI SDK, niezależnie od tego, czy są istotne, czy związane z czasem. Dowolne metadane niezwiązane z DAI są automatycznie odfiltrowywane.

Oto przykład:

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

Od wersji 1.2.0 HLS.js traktuje identyfikator ID3 przez metadane eMSG jako pseudo ID3 zdarzeń, przesyłając je partiami za pomocą zdarzenia FRAG_PARSING_METADATA, w postaci tablicy przykładów. HLS.js nie tłumaczy danych ID3 z tablic bajtów do ciągów znaków i nie kompensuje zdarzeń do odpowiadającego im PTS. Nie niezbędne do zdekodowania przykładowych danych z tablicy bajtów do ciągu znaków, ponieważ pakiet IMA DAI SDK wykonuje dekodowanie automatycznie.

Oto przykład:

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

Strumienie DASH

Liniowe strumienie DASH z dynamicznym wstawianiem reklam przekazują metadane jako zdarzenia w pliku manifestu w strumieniu zdarzeń, niestandardową wartość schemeIdUri urn:google:dai:2018. Każde zdarzenie w tych strumienie zawierają ładunek tekstowy i PTS.

DASH.js

Dash.js udostępnia niestandardowe moduły obsługi zdarzeń o nazwach odpowiadających wartości schemaIdUri każdego z nich . Moduły obsługi niestandardowych uruchamiają się partiami, od Ciebie zależy przetwarza wartość PTS, aby odpowiednio ustawić czas zdarzenia. Pakiet IMA DAI SDK obsługuje to za pomocą metody streamManager: processMetadata().

Oto przykład:

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);
});
...

Gracz Shaka

Shaka Player wyświetla wydarzenia w ramach swojego wydarzenia timelineregionenter. Termin na niezgodność formatu z Shaka Player, wartość metadanych musi być pobrano nieprzetworzone dane za pomocą właściwości details eventElement.attributes['messageData'].value

Oto przykład:

player.addEventListener('timelineregionenter', function(event) {
  const detail = event.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;
    streamManager.processMetadata("urn:google:dai:2018", mediaId, pts);
  }
});
...

Blok reklamowy

W przypadku obsługi podów istnieją różne konfiguracje przekazywania w czasie metadanych w zależności od tych kryteriów:

  • Typ transmisji na żywo lub VOD
  • Format strumienia HLS lub DASH
  • typ używanego odtwarzacza;
  • Typ używanego backendu DAI

Format strumienia HLS (strumienie na żywo i VOD, odtwarzacz HLS.js)

Jeśli korzystasz z odtwarzacza HLS.js, posłuchaj w zdarzeniu FRAG_PARSING_METADATA HLS.js, by pobrać metadane ID3 i przekazać je do Pakiet SDK z StreamManager.processMetadata().

Aby automatycznie odtworzyć film, gdy wszystko będzie wczytane i gotowe, posłuchaj: zdarzenie MANIFEST_PARSED HLS.js, które aktywuje odtwarzanie.

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 (format strumieni DASH oraz typ strumienia Na żywo i VOD)

Jeśli korzystasz z odtwarzacza DASH.js, musisz użyć różnych ciągów znaków, aby nasłuchiwać metadanych ID3 w przypadku transmisji na żywo lub VOD. strumienie:

  • Transmisje na żywo: 'https://developer.apple.com/streaming/emsg-id3'
  • Strumienie VOD: 'urn:google:dai:2018'

Przekaż metadane ID3 do pakietu SDK za pomocą StreamManager.processMetadata().

Aby automatycznie wyświetlać elementy sterujące odtwarzaniem po załadowaniu wszystkich elementów: nasłuchuje zdarzenia MANIFEST_LOADED DASH.js.

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 z transmisjami na żywo (format DASH)

Jeśli używasz odtwarzacza Shaki do odtwarzania na żywo, użyj ciągu 'emsg', aby nasłuchiwać zdarzeń metadanych. Następnie użyj danych komunikatu o zdarzeniu w wywołaniu pod numerem 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});
}

Odtwarzacz Shaka ze strumieniami VOD (format strumieni DASH)

Jeśli używasz odtwarzacza Shaki do Odtwarzanie strumienia VOD, aby nasłuchiwać, użyj ciągu 'timelineregionenter' zdarzenia związane z metadanymi. Następnie użyj danych komunikatu o zdarzeniu w rozmowie, StreamManager.processMetadata() ciągiem '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);
       }
}