处理线性 DAI 视频流中的定时元数据

互动式媒体广告 (IMA) 动态广告插播 (DAI) SDK 依赖于 流的媒体片段中嵌入的元数据信息(带内元数据); 也可以在流式传输清单文件(清单中元数据)中跟踪观看者 位置和客户端广告事件。元数据以不同的格式发送 具体取决于正在播放的视频流的类型

视频播放器批量接收定时元数据。根据不同的玩家, 元数据可以在预定时间显示,也可以批量显示。每个元数据 字符串具有关于何时应显示的关联呈现时间戳 (PTS) 触发。

您的应用负责捕获元数据并将其转发到 IMA DAI SDK。SDK 提供了以下方法来传递此信息:

onTimedMetadata

该方法将准备好处理的元数据字符串转发给 SDK。它只需要使用一个参数:

  • metadata:一个包含 TXXX 键及关联字符串的对象 以 google_ 为前缀的值。
processMetadata

此方法会安排 SDK 在调用 指定的 PTS。它采用以下参数:

  • type:包含要处理的事件类型的字符串。已接受 对于 HLS,值为 ID3;对于 DASH,值为 urn:google:dai:2018
  • data:以 google_ 为前缀的字符串值或符合以下条件的字节数组 遵循此格式 ID3:u\0004u\000u\000u\0000TXXXu\0004u\000u\000u\0000google_xxxxxxxx
  • timestamp:应处理数据的时间戳(以秒为单位)。

IMA DAI SDK 支持的每种视频流类型都使用独特的定时 元数据,如以下部分所述。

HLS MPEG2TS 流

使用 MPEG2TS 片段的线性 DAI HLS 流将定时元数据传递到 视频播放器。这些 ID3 代码已嵌入到 MPEG2TS 片段和 TXXX 字段名称(适用于自定义的用户定义文本) 内容)。

在 Safari 中播放

Safari 会自动处理 ID3 标记作为隐藏的轨道 在正确的时间触发以处理元数据。可以跳过 向 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。不是 将示例数据从字节数组解码为字符串,或过滤掉 不相关的 ID3 代码,因为 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);
    });
  }
});
...

HLS CMAF 视频流

使用通用媒体应用框架 (CMAF) 遍历的线性 DAI HLS 视频流 通过带内 eMSGv1 框进入 ID3 到 CMAF 标准。这些 eMSG 箱 嵌入在每个媒体段开头,其中每个 ID3 eMSG 包含 相对于视频流中最后一次不连续性的 PTS。

从 HLS.js 1.2.0 版本开始,我们两个建议的玩家都通过 ID3 通过 CMAF 向用户发送,就像它们是 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 流将元数据作为事件流中的清单事件传递 自定义 schemeIdUriurn: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 玩家

Shaka Player 会将事件作为其 timelineregionenter 事件的一部分显示。到期日 到与 Shaka Player 不兼容的格式,元数据值必须为 通过 details 属性获取原始版本, 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 服务,有不同的配置用于传递定时 元数据:

  • 直播或 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 Player(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 视频流格式)

如果您使用的是 Shaka 播放器 VOD 流播放,使用字符串 '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);
       }
}