טיפול במטא-נתונים מתוזמנים בשידורים לינאריים של הטמעת מודעות דינמיות (DAI)

ה-SDK של מודעות מדיה אינטראקטיביות (IMA) מסתמך על מטא-נתונים שמוטמעים בקטעי המדיה של השידור (מטא-נתונים מסוג in-band), או בקובץ המניפסט בסטרימינג (מטא-נתונים במניפסט) כדי לעקוב אחרי מיקומי מודעות ואירועי מודעות בצד הלקוח. מטא-נתונים נשלחים בפורמטים שונים, בהתאם לסוג השידור המושמע.

נגן הווידאו מקבל מטא-נתונים מתוזמנים בקבוצות. בהתאם לשחקן, המטא-נתונים יכולים להופיע במועד שנקבע או בקבוצות. כל מטא-נתונים למחרוזת משויכת חותמת זמן של ההצגה (PTS) שבה היא צריכה להיות מופעל.

האפליקציה שלך אחראית לתיעוד מטא-נתונים ולהעברה שלהם אל IMA DAI SDK. ה-SDK מציע את השיטות הבאות להעברת מידע זה:

onTimedMetadata

השיטה הזו מעבירה מחרוזות מטא-נתונים שמוכנות לעיבוד אל SDK. הפונקציה מקבלת ארגומנט אחד:

• metadata: אובייקט שמכיל מפתח של TXXX עם מחרוזת משויכת ערך עם התחילית google_.

processMetadata

השיטה הזו מתזמנת מחרוזות מטא-נתונים לעיבוד על ידי ה-SDK אחרי את ה-PTS שצוינו. היא לוקחת את הארגומנטים הבאים:

• type: מחרוזת שמכילה את סוג האירוע שעובר עיבוד. ההזמנה אושרה הערכים הם ID3 ל-HLS או urn:google:dai:2018 ל-DASH.
• data: ערך מחרוזת עם התחילית google_ או מערך בייטים שמקודד למחרוזת כזו.
• timestamp: חותמת הזמן בשניות שבהן צריך לעבד את הנתונים.

כל סוג של מקור נתונים שנתמך על ידי IMA DAI SDK משתמש בפורמט ייחודי של מטא-נתונים, כפי שמתואר בסעיפים הבאים.

סטרימינג בפורמט HLS MPEG2TS

שידורים לינאריים של DAI HLS באמצעות קטעי MPEG2TS מעבירים מטא-נתונים מתוזמנים אל נגן וידאו באמצעות תגי ID3 in-band. תגי 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 מספק תגי 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

שידורים לינאריים של DAI HLS באמצעות אישור Common Media Application Framework (CMAF) מטא-נתונים מתוזמנים באמצעות תיבות eGSv1 בתוך רצועה אחרי ID3 עד תקן CMAF. תיבות ה-eGS האלה שמוטמע בתחילת כל קטע מדיה, כאשר כל e סשן ID3 מכיל PTS ביחס לאי הרציפות האחרון בזרם.

החל מגרסה 1.2.0 של HLS.js, שני השחקנים המוצעים שלנו עוברים את ID3 דרך CMAF למשתמש, כאילו הם תגי ID3. לכן, הדוגמאות הבאות זהות לשידורים של HLS MPEG2TS. אבל יכול להיות לא כך זה פועל אצל כל השחקנים, לכן יישום תמיכה ב-HLS CMAF שידורי סטרימינג עשויים לדרוש קוד ייחודי כדי לנתח את ID3 דרך eMSG.

הפעלה ב-Safari

Safari מתייחס למטא-נתונים של ID3 באמצעות eGS כאירועי 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 דרך מטא-נתונים של eGS כ-Puseudo 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

שידורים לינאריים של DASH ב-DASH מעבירים מטא-נתונים כאירועי מניפסט בסטרימינג של אירועים עם הערך המותאם אישית schemeIdUri, urn:google:dai:2018. כל אירוע בתרשימים האלה מכילים מטען ייעודי (payload) של טקסט ואת ה-PTS.

DASH.js

אפליקציית Dash.js מספקת גורמים מטפלים באירועים מותאמים אישית, ששמם מופיע על שם הערך schemeIdUri של כל אחד . ה-handlers המותאמים אישית האלה מופעלים באצוות, והשליטה בידיים שלכם לעבד את ערך ה-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 מוצגים כחלק מאירוע 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

להצגת Pod, יש הגדרות שונות להעברת הודעות מתוזמנות. מטא-נתונים, בהתאם לקריטריונים הבאים:

• סוג השידור החי או VOD
• פורמט שידור HLS או DASH
• סוג הנגן שבו משתמשים
• סוג DAI בקצה העורפי שבו משתמשים

פורמט שידור HLS (סטרימינג בשידור חי ו-VOD, נגן HLS.js)

אם משתמשים בנגן HLS.js, מאזינים ל: האירוע FRAG_PARSING_METADATA של HLS.js כדי לקבל את המטא-נתונים של ID3 ולהעביר אותם אל SDK עם StreamManager.processMetadata().

כדי להפעיל את הסרטון באופן אוטומטי אחרי שהכול נטען ומוכן, צריך להאזין ל אירוע MANIFEST_PARSED של HLS.js כדי להפעיל הפעלה.

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 בשידור חי או ב-VOD זרמים:

• שידורים חיים: 'https://developer.apple.com/streaming/emsg-id3'
• שידורי VOD: 'urn:google:dai:2018'

מעבירים את המטא-נתונים של המזהה 3 ל-SDK באמצעות StreamManager.processMetadata().

כדי להציג את לחצני הסרטונים באופן אוטומטי אחרי שהכול נטען ומוכן: להאזין לאירוע 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 עם שידורים חיים (פורמט שידורים של 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});
}

נגן Shaka עם שידורי VOD (פורמט שידורי 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);
       }
}