ה-SDK של Cast כולל ממשקי API מובנים לתמיכה בתוכן בשידור חי. ממשק המשתמש כולל ממשק משתמש גמיש ובשילוב עם ממשקי API שמאפשרים למפתחים ליצור חוויית משתמש עשירה באמצעות כמה שורות קוד בלבד. ב-Live API יש תמיכה בהצגת זמני התחלה וסיום, מטא-נתונים של התוכנית, פקדי DVR וחלונות שניתנים לחיפוש.
במדריך הזה נדגים איך להגדיר שידור לממשקי API חיים, כולל דוגמאות קוד ומטא-נתונים להגדרת תרחישים עיקריים בשידור חי, וגם צילומי מסך שמדגימים איך נראה כל תרחיש.
דרישות מוקדמות
נדרשת היכרות בסיסית עם הטמעת מקלט אינטרנט לפני שתקראו את המדריך הזה. בנוסף, כדי להריץ את דגימות הקוד, נדרשת גישה לשידור חי שתואם לאחד מסוגי המדיה הנתמכים ל-Cast. באופן כללי, התכונה 'שידור חי' תומכת בתצורות טיפוסיות של שידור חי במדיה נתמכת.
המונחים הבאים מופיעים במדריך:
- חלון חיפוש – הטווח של שידור חי שהמשתמשים יכולים לחפש בו.
- Live Edge – החלק החדש ביותר של השידור החי שזמין לנגן.
- Play Head – חותמת זמן של ממשק המשתמש של מיקום ההפעלה הנוכחי.
העברה (cast) של שידור חי
יש שתי דרכים להגדיר את Web קבלת ה-SDK לשימוש ב-Live API בשביל תוכן:
- באמצעות כלי יירוט ההודעות של
LOADבאפליקציה 'מקלט אינטרנט'. (מומלץ) - באמצעות בקשת טעינה בצד השולח או בצד המקבל.
היירוט מספק אובייקט LoadRequestData שמכיל את כל המטא-נתונים החשובים לגבי בקשת טעינה. כדי לציין שבקשת טעינה היא לשידור חי, פשוט מגדירים את התפקיד streamType לאובייקט mediaInformation בתור StreamType.LIVE.
הערך MediaInformation.duration צריך להיות -1, כי מופעי הנגן אחראיים לחישוב שלו כשהתוכן הוא LIVE.
/*
* This interceptor is called before your content is loaded by a Cast device
*/
playerManager.setMessageInterceptor(
cast.framework.messages.MessageType.LOAD,
request => { /* cast.framework.messages.LoadRequestData */
request.media.streamType = cast.framework.messages.StreamType.LIVE;
return request;
});
הוספת נתוני מדריך תוכניות
בשידורים חיים, במיוחד בשידורים חיים ארוכים, כמו ערוץ טלוויזיה, אפשר להציג מטא-נתונים על התוכנית או על לוח השידורים על סמך מיקום ההפעלה הנוכחי בשידור החי. מומלץ מאוד לספקי תוכן לכלול מטא-נתונים של תכנות באפליקציות מקלט האינטרנט שלהם, כדי ליהנות מחוויה משופרת.
ניתן להגדיר את נתוני המדריך הראשוניים עבור מקור נתונים ביישומון ההודעות של LOAD, באותו אופן שבו ציינו שהשידור היה שידור חי בדוגמה הקודמת. תוכניות או קטעים מסוימים בשידור החי מיוצגים כאובייקטים MediaMetadata, שמאוחסנות בתור.
יש מחלקות MediaMetadata שונות לסוגים שונים של תוכניות – למשל, TvShowMediaMetadata,
MovieMediaMetadata,
MusicTrackMediaMetadata ועוד.
בקטע הקוד הבא, אנחנו משתמשים באובייקט MediaMetadata כדי לציין את שעת ההתחלה של כל תוכנית באמצעות חותמת זמן UnIX עם המאפיין sectionStartAbsoluteTime. משך התוכנית מיוצג בשניות.
// The metadata for a single TV show
const currentShow = new cast.framework.messages.TvShowMediaMetadata();
currentShow.episode = 15;
currentShow.seriesTitle = 'The Odyssey';
currentShow.title = 'Scylla and Charybdis';
currentShow.sectionStartAbsoluteTime = toUnixTimestamp('9:00 PM');
currentShow.sectionDuration = HOUR_IN_SECONDS;
const previousShow = new ...;
const nextShow = new ...;
const containerMetadata = new cast.framework.messages.ContainerMetadata();
containerMetadata.title = 'My TV Channel';
containerMetadata.sections = [previousShow, currentShow, nextShow];
playerManager.getQueueManager().setContainerMetadata(containerMetadata);
טווח זמין לחיפוש
ה-Cast SDK כולל אלמנטים ופקדים בממשק המשתמש שמאפשרים למשתמשים להזיז את המיקום הנוכחי שלהם במהלך הסטרימינג באמצעות בקר מורחב או באמצעות פקדי מגע במכשירים עם יכולת מגע.
הסמל LiveSeekableRange מייצג את טווח הזמן בזרם שבו משתמש יכול לחפש. במקלט האינטרנט אפשר לגשת למידע על הטווח הרלוונטי באמצעות PlayerManager.getLiveSeekableRange(), שמחזיר אובייקט LiveSeekableRange. המאפיינים העיקריים באובייקט שיש לשים לב אליהם:
- start — שעת ההתחלה (בשניות) של הטווח ביחס לתחילת הסטרימינג בשניות.
- end – הזמן המקסימלי (בשניות) שהשחקן יכול לחפש, על סמך הקטעים הזמינים, ביחס לתחילת השידור.
- isMovingWindow – ערך בוליאני שמציין אם הטווח הרלוונטי נע (כלומר פלחים ישנים יותר הוסרו מהמניפסט) עם אותו מקור נתונים. הערך צריך להיות true בכל השידורים החיים.
- isLiveDone – ערך בוליאני שמציין אם השידור החי הסתיים, כלומר לא נוצרים פלחים חדשים.
הגודל של הטווח הניתן לחיפוש, שמיוצג לפי הזמן בין start ל-end, נקבע לפי מספר הפלחים הזמינים בזרם וינוע עם השידור. לדוגמה, אם השידור מתחיל, בטווח המיועד הוא {start:0, end: 600, isMovingWindow: false, isLiveDone: false}, עשר שניות אחרי תחילת הסטרימינג, הוא יכול להפוך ל-{start: 10, end: 610,
isMovingWindow: true, isLiveDone: false}. חשוב לזכור ששעות ההתחלה והסיום בטווח הנתון מתעדכנות בהתאם לזמן שלוקח ליצור פלח חדש. לכן, אם משך הזמן הטיפוסי של קטע במהלך השידור הוא 10 שניות, שעות ההתחלה והסיום יעודכנו גם הן בערך כל 10 שניות.
השבתת הדילוג
כדי להשבית את החיפוש בתוך מקור הנתונים, צריך להסיר את פונקציונליות החיפוש מפקודות המדיה הנתמכות במקלט האינטרנט:
// disable seeking in the LOAD messageInterceptor
playerManager.removeSupportedMediaCommands(cast.framework.messages.Command.SEEK, true);
הסרה של פקודת המדיה הנתמכת SEEKאותות לאפליקציות שולח ונגיעה במסכים כדי להשבית את החיפוש, אבל לא משביתה פקודות קוליות כמו Ok Google, דילוג לאחור 30 שניות'. עיינו במדריך הנחיות למדיה נתמכת באמצעות הקול
לקבלת פרטים על השבתת פקודות מדיה עבור קול.
אירועים של framework בשידור חי
שני אירועים, LIVE_ENDED ו-LIVE_IS_MOVING_WINDOW_CHANGED, כלולים ב-Live API. שני האירועים מועברים דרך אובייקט LiveStatusEvent, שמכיל את הטווח הנוכחי הזמין לחיפוש.
| אירוע | תיאור |
|---|---|
LIVE_ENDED |
מופעל כששידור חי מסתיים. בשלב זה, הערך end ב-LiveSeekableRange יפסיק להתעדכן. המשתמשים עדיין יוכלו לצפות בתוכן בטווח הזמין בזמן אמת. |
LIVE_IS_MOVING_WINDOW_CHANGED |
מופעל כאשר טווח החיפוש של השידור החי משתנה מחלון קבוע לחלון קופץ, או להיפך. עבור שידור חי, זה יקרה כשהנגן יזהה שהמניפסט מסיר פלחים מוקדמים יותר. |
תרחישי סטרימינג בשידור חי
יש שמונה סוגים אפשריים של תרחישים לסטרימינג בשידור חי, וכל אחד מהם מוגדר על ידי הגדרת שלוש הגדרות עיקריות:
- יש שעת התחלה לשידור
- שעת הסיום זמינה
- המשתמשים יכולים לדלג לחלון שמאפשר חיפוש במהלך השידור החי
כדי להגדיר את הערכים האלו, עיינו בקטע הוספת נתונים ממדריך התוכניות.
בהמשך מופיעים תיאורים וצילומי מסך של התרחישים הנתמכים על ידי Live API. המשתנים T1 ו-T2 משמשים לייצוג חותמת הזמן בצד שמאל ובצד ימין של ממשק המשתמש, בהתאמה.
| שעת התחלה | שעת סיום | אפשר לחפש | T1 | T2 | |
|---|---|---|---|---|---|
| תרחיש 1 | לא | לא | לא | ראש משחק | לא מוצג |
| תרחיש 7 | כן | כן | לא | הצגת שעת ההתחלה | הצגת שעת הסיום |
| תרחיש 8 | כן | כן | כן | הצגת שעת ההתחלה | הצגת שעת הסיום |
תרחיש ראשון
| שעת התחלה | שעת סיום | אפשר לחפש | T1 | T2 |
|---|---|---|---|---|
| לא | לא | לא | ראש משחקים | לא מוצג |
לתרחיש הראשון אין זמן התחלה או סיום, והמשתמשים לא יכולים לחפש בתוך השידור. כשמשתמשים מפסיקים את השידור, הוא יופעל מההתחלה בשידור חי במקום במקום שבו השידור הושהה.
תרחיש שבע
| שעת התחלה | שעת סיום | אפשר לחפש | T1 | T2 |
|---|---|---|---|---|
| כן | כן | לא | ראש משחק | משך התוכנית |
לתרחיש שבע יש שעת התחלה ושעת סיום, אך לא ניתן לחפש אותו. שתי חותמות הזמן בממשק המשתמש, T1 ו-T2, מייצגות את משך הזמן הנוכחי של ההפעלה ואת משך הזמן הכולל של התוכנית, בהתאמה. אם משתמש ישהה/ימשיך את ההפעלה, השידור ימשיך בקצה השידור החי. בדוגמה שלמעלה, הקטע האדום בסרגל ההרצה מייצג את החלק מהשידור מאז שהמשתמש התחיל לצפות.
התרחיש שמונה
| שעת התחלה | שעת סיום | אפשר לחפש | T1 | T2 |
|---|---|---|---|---|
| כן | כן | כן | ראש משחק | משך התוכנית |
בתרחיש שבע יש שעת התחלה ושעת סיום, וניתן לחפש אותו. שתי חותמות הזמן בממשק המשתמש, T1 ו-T2, מייצגות את משך זמן ההפעלה הנוכחי ואת משך הזמן הכולל של התוכנית, בהתאמה. אם משתמש משהה או ממשיך הפעלה, השידור ימשיך בזמן שהוא מושהה אם הוא נמצא בחלון שניתן לחיפוש. האזור באדום בסרגל ההרצה מייצג את הנקודה שבה המשתמש יכול לחזור לאחור והאזור בלבן מציין לאן הוא יכול להריץ את הסרטון.
הגדרת תרחיש
תהליך ההגדרה של תרחיש בשידור חי מתבצע בשלושה חלקים:
- הגדרת סוג השידור – מסמנים את השידור כשידור חי.
- הוספת נתונים של מדריך תוכניות – מגדירים שעת התחלה ומשך זמן לאובייקט
MediaMetadata. - הגדרת פונקציונליות לחיפוש – הפעלה או השבתה של החיפוש.
התנהגות ההפעלה
בזמן ההשהיה, הממשק של המטא-נתונים ימשיך להתעדכן, כולל נתוני הפעלה ושידורים חיים. לאחר המשך הסטרימינג, יש כמה התנהגויות שצריך להיות מודעים להן בהתאם להגדרות הסטרימינג.
מקורות נתונים זמינים
לאחר הפעלה מחדש של זרם שניתן לדלג עליו:
- הקצה בשידור חי יעודכן בהתאם למיקום הפעיל, והטווח שאליו רוצים לבצע את השינוי ישתנה בהתאם.
- אם סמן המיקום ידלג אחרי התוכנית הנוכחית, סרגל הצצה יתעדכן עם המטא-נתונים מהתוכנית החדשה (כולל שעת ההתחלה ושעת הסיום, אם יש כזו).
- אם האורך של חלון שניתן לדלג עליו הוא באורך 'X', הטווח לחיפוש יהיה בטווח של עד 'X', או בתחילת התוכנית, הקטן מביניהם.
- אם המשתמש היה מושהה מספיק זמן כדי שהשעה הנוכחית לא תהיה עוד בחלון המיועד, השידור יחזור בנקודה המוקדמת ביותר (השמאלית ביותר) בחלון הרלוונטי.
כדאי לנסות ללחוץ על LiveSeekableRange.end כדי להמשיך את ההפעלה בקצה השידור החי לאחר ביטול ההשהיה.
let playerManager = cast.framework.CastReceiverContext.getInstance().getPlayerManager();
// Intercept the message to PLAY
playerManager.setMessageInterceptor(cast.framework.messages.MessageType.PLAY, (requestData) => {
...
if (playerManager.getLiveSeekableRange()) {
// Resume playback at the live edge
playerManager.seek(playerManager.getLiveSeekableRange().end);
} else {
return requestData;
}
...
});
שידורים שלא ניתנים לחיפוש
כשמחדשים את השידור שלא ניתן לדלג עליו:
- במקרה כזה, ההפעלה תמשיך בקצה הפעיל.
- אם קצה השידור החי ידלג אחרי התוכנית הנוכחית, צריך לעדכן את סרגל הצצה עם המטא-נתונים של התוכנית החדשה (כולל שעת ההתחלה ושעת הסיום, אם יש).
ממשק API להצגת שינויים והתאמה אישית של ממשק המשתמש הפעיל
ל-Cast SDK יש תמיכה מובנית ביצירה של ממשקי משתמש מותאמים אישית במקום שימוש בממשק משתמש ייחודי. עם זאת, חשוב להתאים אותה לרשימת המשימות לעיצוב של חוויית המשתמש כשמתאימים אישית את הממשק.
מקלט אינטרנט
במקלט האינטרנט, השדה PlayerData כולל את השדות הבאים, כדי לאפשר למפתחים להרחיב את הממשקים המותאמים אישית שלהם לשידורים חיים:
- isLive – סימון שמציין אם השידור הנוכחי הוא שידור חי, בניגוד ל-VOD.
- liveSeekableRange – הטווח המיועד להצגה במסך המסמן את חלון ה-DVR.
- mediaStartAbsoluteTime – כשהקטע התחיל בזמן מוחלט (UNIX Epoch).
- sectionStartTimeInMedia - שעת ההתחלה של הקטע בשניות, ביחס לשעת ההתחלה של המדיה.
- sectionduration – משך הקטע בשניות.
כמו כן, חשוב להביא בחשבון את שני האירועים החיים בעת התאמה אישית של ממשק המשתמש.
Android SDK
כחלק מהפונקציונליות של Live, הוצאנו משימוש את ה-Widget של Android Seekbar ב-UIMediaController. במקום זאת, יש להשתמש ב-CastSeekBar.