このページは Cloud Translation API によって翻訳されました。

リニア DAI ストリームで時間指定メタデータを処理する

Interactive Media Ads（IMA）ダイナミック広告挿入（DAI）SDK は、ストリームのメディアセグメント（インバンドメタデータ）またはストリーミングマニフェストファイル（マニフェスト内メタデータ）に埋め込まれたメタデータ情報を利用して、視聴者の現在地とクライアントサイドの広告イベントを追跡します。メタデータは、再生されるストリームのタイプに応じて異なる形式で送信されます。

動画プレーヤーは、時間制限付きメタデータをバッチで受け取ります。プレーヤーに応じて、メタデータはスケジュールされた時刻に、または一括して表示できます。各メタデータ文字列には、トリガーされるタイミングのプレゼンテーションタイムスタンプ（PTS）が関連付けられています。

メタデータの取得と IMA DAI SDK への転送はアプリ側で行います。SDK には、この情報を渡すための次のメソッドが用意されています。

onTimedMetadata

このメソッドは、処理可能なメタデータ文字列を SDK に転送します。単一の引数を取ります。

metadata: TXXX のキーと、接頭辞 google_ が付いた文字列値が関連付けられたオブジェクト。

processMetadata

このメソッドは、指定した PTS の後に SDK がメタデータ文字列を処理するようにスケジュールします。次の引数を取ります。

type: 処理されるイベントのタイプを含む文字列。指定できる値は、HLS では ID3、DASH では urn:google:dai:2018 です。
data: google_ の接頭辞が付いた文字列値、またはこのような文字列にデコードするバイト配列。
timestamp: データを処理するタイムスタンプ（秒単位）。

IMA DAI SDK でサポートされる各ストリームタイプでは、以降のセクションで説明するように、固有の形式の時間指定メタデータが使用されます。

HLS MPEG2TS ストリーム

MPEG2TS セグメントを使用するリニア DAI HLS ストリームは、インバンド ID3 タグを通じて時間指定メタデータを動画プレーヤーに渡します。これらの ID3 タグは MPEG2TS セグメントに埋め込まれ、TXXX フィールド名（ユーザー定義のカスタムテキストコンテンツ用）が付けられます。

Safari での再生

Safari は ID3 タグを隠しトラックとして自動的に処理します。そのため、cuechange イベントが適切なタイミングで配信され、各メタデータが処理されます。コンテンツやタイプに関係なく、すべてのメタデータを IMA DAI SDK に渡しても問題ありません。無関係なメタデータは自動的に除外されます。

次の例をご覧ください。

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 では、FRAG_PARSING_METADATA イベントを通じて、サンプルの配列として ID3 タグを一括で提供します。HLS.js は、ID3 データをバイト配列から文字列に変換せず、イベントを対応する PTS にオフセットしません。IMA DAI SDK ではデコードとフィルタリングが自動的に行われるため、サンプルデータをバイト配列から文字列にデコードしたり、無関係な ID3 タグを除外したりする必要はありません。

次の例をご覧ください。

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 ストリーム

Common Media Application Framework（CMAF）を使用するリニア DAI HLS ストリームでは、ID3 から CMAF 標準に準拠したインバンド eMSGv1 ボックスを通じて時間指定メタデータを渡します。これらの eMSG ボックスは各メディアセグメントの最初に埋め込まれ、各 ID3 eMSG にはストリーム内の最後の不連続性に対する PTS が含まれます。

HLS.js 1.2.0 リリースの時点では、どちらのプレーヤーも、CMAF を通じて ID3 を ID3 タグのようにユーザーに渡します。このため、次の例は HLS MPEG2TS ストリームの場合と同じです。ただし、すべてのプレーヤーに当てはまるわけではないため、HLS CMAF ストリームのサポートを実装するには、eMSG を使用して ID3 を解析するために一意のコードが必要になる場合があります。

Safari での再生

Safari は、ID3 から eMSG メタデータを疑似 ID3 イベントとして扱い、自動的にバッチで隠しトラックとして提供します。これにより、各メタデータを処理する cuechange イベントが適切なタイミングで呼び出されるようにします。タイミングに関連するかどうかにかかわらず、すべてのメタデータを IMA DAI SDK に渡しても問題ありません。DAI 関連以外のメタデータは自動的に除外されます。

次の例をご覧ください。

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

バージョン 1.2.0 では、HLS.js は ID3 から eMSG メタデータを疑似 ID3 イベントとして扱い、FRAG_PARSING_METADATA イベントを通じてサンプルの配列として一括で提供します。HLS.js は、ID3 データをバイト配列から文字列に変換せず、イベントを対応する PTS にオフセットしません。IMA DAI SDK ではデコードが自動的に行われるため、サンプルデータをバイト配列から文字列にデコードする必要はありません。

次の例をご覧ください。

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

DASH ストリーム

リニア DAI DASH ストリームは、カスタム schemeIdUri 値 urn:google:dai:2018 を使用して、イベントストリームでマニフェストイベントとしてメタデータを渡します。これらのストリームの各イベントには、テキストペイロードと PTS が含まれます。

DASH.js

Dash.js には、各イベントストリームの schemeIdUri 値に基づいて名前が付けられたカスタムイベントハンドラが用意されています。これらのカスタムハンドラはバッチで起動され、PTS 値を処理してイベントの適切なタイミングをデベロッパーが処理する必要があります。IMA DAI SDK では、streamManager メソッドの processMetadata() を使用してこの処理が行われます。

次の例をご覧ください。

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 は timelineregionenter イベントの一部としてイベントを表示します。Shaka Player はフォーマットに互換性がないため、メタデータ値は詳細プロパティ eventElement.attributes['messageData'].value を使用して未加工から取得する必要があります。

次の例をご覧ください。

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

連続配信広告

Pod Serving では、次の条件に応じて時間付きメタデータを渡すための構成が異なります。

ライブまたは VOD のストリームタイプ
HLS または DASH ストリーム形式
使用するプレーヤーのタイプ
使用する DAI バックエンドのタイプ

HLS ストリーム形式（ライブと VOD ストリーム、HLS.js プレーヤー）

HLS.js プレーヤーを使用している場合は、HLS.js の FRAG_PARSING_METADATA イベントをリッスンして ID3 メタデータを取得し、StreamManager.processMetadata() を使用して SDK に渡します。

すべてが読み込まれて準備ができた後、動画を自動的に再生するには、HLS.js MANIFEST_PARSED イベントをリッスンして再生をトリガーします。

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 ストリーム形式、ライブ、VOD ストリームタイプ）

DASH.js プレーヤーを使用している場合、ライブストリームまたは VOD ストリームの ID3 メタデータをリッスンするには、次のように異なる文字列を使用する必要があります。

ライブ配信: 'https://developer.apple.com/streaming/emsg-id3'
VOD ストリーム: 'urn:google:dai:2018'

StreamManager.processMetadata() を使用して、ID3 メタデータを SDK に渡します。

すべてが読み込まれて準備ができた後に動画コントロールを自動的に表示するには、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);
}

ライブ配信対応の Shaka プレーヤー（DASH ストリーム形式）

ライブ配信再生に Shaka プレーヤーを使用している場合は、文字列 'emsg' を使用してメタデータイベントをリッスンします。次に、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});
}

VOD ストリームのある Shaka Player（DASH ストリーム形式）

VOD ストリームの再生に Shaka プレーヤーを使用している場合は、文字列 'timelineregionenter' を使用してメタデータイベントをリッスンします。次に、StreamManager.processMetadata() の呼び出しで、文字列 '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);
       }
}

リニア DAI ストリームで時間指定メタデータを処理する

HLS MPEG2TS ストリーム

Safari での再生

HLS.js

HLS CMAF ストリーム

Safari での再生

HLS.js

DASH ストリーム

DASH.js

Shaka Player

連続配信広告

HLS ストリーム形式（ライブと VOD ストリーム、HLS.js プレーヤー）

DASH.js（DASH ストリーム形式、ライブ、VOD ストリーム タイプ）

ライブ配信対応の Shaka プレーヤー（DASH ストリーム形式）

VOD ストリームのある Shaka Player（DASH ストリーム形式）

DASH.js（DASH ストリーム形式、ライブ、VOD ストリームタイプ）