رسیدگی به فراداده زمان‌بندی‌شده

پلاتفرم را انتخاب کنید: HTML5 Roku

کیت توسعه نرم‌افزار (SDK) «درج آگهی پویا» (DAI) در «آگهی‌های رسانه‌ای تعاملی» (IMA) برای ردیابی موقعیت بینندگان و رویدادهای آگهی سمت کارخواه، به اطلاعات فراداده جاسازی‌شده در بخش‌های رسانه‌ای جاری‌سازی (فراداده درون‌باند) یا در فایل مانیفست جاری‌سازی (فراداده درون‌مانیفست) متکی است. فراداده در قالب‌های مختلفی ارسال می‌شود، که به نوع جاری‌سازی درحال پخش بستگی دارد.

پخش‌کننده ویدیو فراداده زمان‌بندی‌شده را به‌صورت دسته‌ای دریافت می‌کند. بسته به پخش‌کننده، فراداده می‌تواند در زمان زمان‌بندی‌شده یا به‌صورت دسته‌ای نمایش داده شود. هر رشته فراداده دارای یک مُهر زمان ارائه (PTS) مرتبط است که زمان فعال شدن آن را مشخص می‌کند.

برنامه شما مسئول ضبط فراداده و ارسال آن به IMA DAI SDK است. کیت توسعه نرم‌افزار روش‌های زیر را برای ارسال این اطلاعات ارائه می‌دهد:

onTimedMetadata

این روش رشته‌های فراداده را که آماده پردازش هستند به کیت توسعه نرم‌افزار بازارسال می‌کند. یک آرگومان می‌گیرد:

  • ‫metadata: شیئی که حاوی کلید TXXX با مقدار رشته‌ای مرتبط است که پیشوند google_ دارد.
processMetadata

این روش رشته‌های فراداده را برای پردازش توسط کیت توسعه نرم‌افزار پس‌از PTS مشخص‌شده زمان‌بندی می‌کند. این تابع آرگومان‌های زیر را می‌گیرد:

  • ‫type: رشته‌ای حاوی نوع رویدادی که درحال پردازش است. مقادیر پذیرفته‌شده عبارتند از ID3 برای HLS یا urn:google:dai:2018 برای DASH
  • data: یا مقدار رشته‌ای با پیشوند google_ یا آرایه بایتی که از این قالب پیروی می‌کند ID3:u\0004u\000u\000u\0000TXXXu\0004u\000u\000u\0000google_xxxxxxxx.
  • timestamp: مُهر زمان برحسب ثانیه که داده‌ها باید پردازش شوند.

هر نوع جاری‌سازی که IMA DAI SDK از آن پشتیبانی می‌کند از شکل منحصربه‌فردی از فراداده زمان‌بندی‌شده استفاده می‌کند، همان‌طور که در بخش‌های زیر شرح داده شده است.

جاری‌سازی‌های HLS MPEG2TS

جاری‌سازی‌های HLS درج آگهی پویای خطی بااستفاده از بخش‌های MPEG2TS فراداده زمان‌بندی‌شده را ازطریق برچسب‌های 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 برچسب‌های ID3 را به‌صورت دسته‌ای ازطریق رویداد FRAG_PARSING_METADATA، به‌عنوان آرایه‌ای از نمونه‌ها ارائه می‌دهد. ‫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

جاری‌سازی‌های HLS درج آگهی پویا خطی بااستفاده از «چارچوب برنامه رسانه مشترک» (CMAF) فراداده زمان‌بندی‌شده را ازطریق جعبه‌های eMSGv1 درون‌باندی طبق استاندارد ID3 ازطریق CMAF منتقل می‌کنند. این جعبه‌های eMSG در ابتدای هر بخش رسانه جاسازی شده‌اند و هر ID3 eMSG حاوی یک PTS نسبت‌به آخرین ناپیوستگی در جاری‌سازی است.

از زمان انتشار نسخه ۱.۲.۰ از HLS.js، هر دو پخش‌کننده پیشنهادی ما ID3 را ازطریق CMAF به کاربر منتقل می‌کنند، گویی که برچسب‌های ID3 هستند. به همین دلیل، نمونه‌های زیر مشابه جاری‌سازی‌های HLS MPEG2TS است. بااین‌حال، ممکن است این موضوع برای همه پخش‌کننده‌ها صادق نباشد، بنابراین پیاده‌سازی پشتیبانی از جاری‌سازی‌های HLS CMAF می‌تواند به کد منحصربه‌فردی برای تجزیه ID3 ازطریق eMSG نیاز داشته باشد.

بازپخش در 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

از نسخه ۱.۲.۰،‏ 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 می‌تواند این کار را بااستفاده از روش 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، مقدار فراداده باید به‌صورت خام ازطریق ویژگی جزئیات eventNode.attributes['messageData'] بازیابی شود.

مثالی در اینجا ارائه شده است:

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، پیکربندی‌های مختلفی برای انتقال فراداده زمان‌بندی‌شده وجود دارد که به معیارهای زیر بستگی دارد:

  • نوع جاری‌سازی زنده یا VOD
  • قالب جاری‌سازی HLS یا DASH
  • نوع پخش‌کننده‌ای که استفاده می‌شود
  • نوع زیرینه DAI که استفاده می‌شود

قالب جاری‌سازی HLS (جاری‌سازی‌های زنده و ویدیو به‌درخواست، پخش‌کننده HLS.js)

اگر از پخش‌کننده HLS.js استفاده می‌کنید، به رویداد HLS.js FRAG_PARSING_METADATA گوش دهید تا فراداده ID3 را دریافت کنید و آن را با StreamManager.processMetadata() به کیت توسعه نرم‌افزار ارسال کنید.

برای پخش خودکار ویدیو پس‌از بار شدن و آماده شدن همه چیز، به رویداد 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 استفاده می‌کنید، باید از رشته‌های مختلفی برای گوش دادن به فراداده ID3 برای جاری‌سازی‌های زنده یا ویدیو به‌درخواست استفاده کنید:

  • جاری‌سازی‌های زنده: 'https://developer.apple.com/streaming/emsg-id3'
  • جاری‌سازی‌های ویدیو به‌درخواست: 'urn:google:dai:2018'

فراداده ID3 را با StreamManager.processMetadata() به کیت توسعه نرم‌افزار ارسال کنید.

برای نمایش خودکار کنترل‌های ویدیو پس‌از بار شدن و آماده شدن همه چیز، به رویداد 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 player برای بازپخش جاری‌سازی زنده استفاده می‌کنید، از رشته '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});
}

Shaka Player با جاری‌سازی‌های «ویدیو به‌درخواست» (قالب جاری‌سازی‌های DASH)

اگر از Shaka player برای بازپخش جاری‌سازی 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);
       }
}