Ta strona została przetłumaczona przez Cloud Translation API.

Obsługa metadanych czasowych w liniowych strumieniach DAI

Pakiet SDK do dynamicznego wstawiania reklam (DAI) w interaktywnych reklamach medialnych (IMA) korzysta z informacji o metadanych zawartych w segmentach multimediów strumienia (metadane w paśmie) lub w pliku manifestu strumienia (metadane w manifeście), aby śledzić pozycje widzów i zdarzenia reklam po stronie klienta. Metadane są wysyłane w różnych formatach w zależności od typu odtwarzanego strumienia.

Odtwarzacz wideo otrzymuje metadanych zsynchronizowanych z czasem w partiach. W zależności od odtwarzacza metadane mogą być wyświetlane w zaplanowanym czasie lub partiami. Każdy ciąg znaków metadanych ma powiązany sygnaturę czasową prezentacji (PTS), która określa, kiedy powinien zostać uruchomiony.

Twoja aplikacja odpowiada za rejestrowanie metadanych i przekazywanie ich do pakietu IMA DAI SDK. Pakiet SDK udostępnia te metody przekazywania tych informacji:

onTimedMetadata

Ta metoda przekazuje do SDK gotowe do przetwarzania ciągi znaków metadanych. Wymaga ona podania 1 argumentu:

metadata: obiekt zawierający klucz TXXX z powiązaną wartością ciągu znaków z prefiksem google_.

processMetadata

Ta metoda planuje przetwarzanie przez pakiet SDK ciągów znaków metadanych po określonym punkcie czasowym PTS. Przyjmuje te argumenty:

type: ciąg tekstowy zawierający typ przetwarzanego zdarzenia. Dopuszczalne wartości to ID3 w przypadku HLS lub urn:google:dai:2018 w przypadku DASH.
data: wartość ciągu znaków z prefiksem google_ lub tablica bajtów o tym formacie: ID3:u\0004u\000u\000u\0000TXXXu\0004u\000u\000u\0000google_xxxxxxxx.
timestamp: sygnatura czasowa w sekundach, w których dane mają zostać przetworzone.

Każdy typ strumienia obsługiwany przez pakiet IMA DAI SDK używa unikalnej formy metadanych zsynchronizowanych czasowo, jak opisano w następnych sekcjach.

strumienie HLS MPEG2TS;

Strumienie osi czasu DAI HLS korzystające z segmentów MPEG2TS przekazują metadane zsynchronizowane czasowo do odtwarzacza za pomocą tagów ID3 w paśmie. Te tagi ID3 są umieszczane w segmentach MPEG2TS i mają nazwę pola TXXX (dla niestandardowych treści tekstowych zdefiniowanych przez użytkownika).

Odtwarzanie w Safari

Safari przetwarza tagi ID3 automatycznie jako ukryty utwór, więc zdarzenia cuechange są wywoływane we właściwym czasie, aby przetworzyć każdy element metadanych. Do pakietu IMA DAI SDK można przekazywać wszystkie metadane, niezależnie od typu treści. Nieistotne metadane 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 w partiach za pomocą zdarzenia FRAG_PARSING_METADATA w postaci tablicy próbek. HLS.js nie tłumaczy danych ID3 z tablic bajtów na ciągi znaków i nie przesuwa zdarzeń do odpowiadających im wartości PTS. Nie musisz dekodować próbnych danych z tablicy bajtów na ciąg znaków ani odfiltrowywać nieistotnych tagów ID3, ponieważ pakiet IMA DAI SDK wykonuje to 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.

Strumienie HLS DAI o charakterze liniowym korzystające z ramowego modelu aplikacji multimedialnych (CMAF) przesyłają metadanych oparte na czasie za pomocą pól eMSGv1 w paśmie zgodnie ze standardem ID3 przez CMAF. Te pola eMSG są osadzone na początku każdego segmentu multimediów, a każdy eMSG ID3 zawiera PTS względem ostatniej przerwy w strumieniu.

Od wersji HLS.js 1.2.0 oba sugerowane odtwarzacze przekazują użytkownikowi tagi 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. Nie dotyczy to jednak wszystkich odtwarzaczy, dlatego wdrożenie obsługi strumieni HLS CMAF może wymagać unikalnego kodu do analizowania ID3 za pomocą eMSG.

Odtwarzanie w Safari

Safari traktuje metadane ID3 jako pseudozdarzenia ID3, przesyłając je w partiach automatycznie jako ukryty utwór, tak aby zdarzenia cuechange były wywoływane we właściwym czasie w celu przetworzenia każdego elementu metadanych. Możesz przekazać wszystkie metadane do pakietu IMA DAI SDK, niezależnie od tego, czy są one istotne dla czasu wyświetlania. Wszystkie 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 metadane ID3 jako pseudozdarzenia ID3, przesyłając je partiami za pomocą zdarzenia FRAG_PARSING_METADATA jako tablicy próbek. HLS.js nie tłumaczy danych ID3 z tablic bajtów na ciągi znaków i nie przesuwa zdarzeń do odpowiadających im wartości PTS. Nie trzeba dekodować danych przykładowych z tablicy bajtów na ciąg znaków, ponieważ pakiet IMA DAI SDK wykonuje to 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

Strumienie danych linearnych DAI DASH przesyłają metadane jako zdarzenia manifestu w strumieniu zdarzeń z niestandardową wartością schemeIdUri urn:google:dai:2018. Każde zdarzenie w tych strumieniach zawiera ładunek tekstowy i wartość PTS.

DASH.js

Dash.js udostępnia niestandardowe moduły obsługi zdarzeń o nazwach pochodzących od wartości parametru schemeIdUri każdego strumienia zdarzeń. Te niestandardowe moduły obsługi są wywoływane partiami, więc to od Ciebie zależy, jak przetworzysz wartość PTS, aby odpowiednio dobrać czas zdarzenia. Pakiet IMA DAI SDK może za Ciebie wykonać tę czynność 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);
});
...

Shaka Player

Odtwarzacz Shaka udostępnia zdarzenia w ramach zdarzenia timelineregionenter. Ze względu na niezgodność formatu z odtwarzaczem Shaka wartość metadanych musi być pobierana w postaci surowej za pomocą właściwości szczegółów eventNode.attributes['messageData'].

Oto przykład:

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

Bloki reklamowe

W przypadku serwowania podcastów dostępne są różne konfiguracje przekazywania metadanych z opóźnieniem 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 (transmisje na żywo i VOD, odtwarzacz HLS.js)

Jeśli używasz odtwarzacza HLS.js, nasłuchuj zdarzenie HLS.js FRAG_PARSING_METADATA, aby pobrać metadane ID3 i przekazać je do pakietu SDK za pomocą StreamManager.processMetadata().

Aby automatycznie odtworzyć film po załadowaniu i przygotowaniu wszystkich elementów, przechwyć zdarzenie HLS.js MANIFEST_PARSED, aby wywołać 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, typ strumienia na żywo i VOD)

Jeśli używasz odtwarzacza DASH.js, musisz użyć różnych ciągów znaków, aby odsłuchać metadane ID3 w przypadku strumieni na żywo lub VOD:

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 filmem po załadowaniu i gotowości wszystkich elementów, nasłuchuj zdarzenia DASH.js 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);
}

Odtwarzacz Shaka z transmisjami na żywo (format strumieni DASH)

Jeśli do odtwarzania strumieniowego używasz odtwarzacza Shaka, użyj ciągu 'emsg', aby nasłuchiwać zdarzeń metadanych. Następnie użyj danych z wiadomości o zdarzeniu w wywołaniu do 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 z strumieniami VOD (w formacie strumieni DASH)

Jeśli do odtwarzania strumienia VOD używasz odtwarzacza Shaka, użyj ciągu 'timelineregionenter', aby nasłuchiwać zdarzeń metadanych. Następnie użyj danych wiadomości zdarzenia w wywołaniu do funkcji StreamManager.processMetadata() z ciągiem znaków '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);
       }
}