מחזור החיים של שידור

מבוא

במסמך הזה מוסבר על מחזור החיים של שידור חי ב-YouTube שנוצר ומנוהל באמצעות YouTube Live Streaming API ו-YouTube Content ID API.

משאבים וסוגי משאבים

כמו שמוסבר במדריך תחילת העבודה, משאב הוא ישות נתונים פרטנית עם מזהה ייחודי. כדי ליצור אירועים בשידור חי ב-YouTube ולנהל אותם, תצטרכו להשתמש בכמה סוגים שונים של מקורות מידע שמוגדרים כחלק מ-YouTube Data API או מ-YouTube Content ID API. המשאבים שמפורטים בכותרת YouTube Live Streaming API מוגדרים טכנית בממשקי ה-API האחרים האלה, אבל הם מפורטים בנפרד כי הם משמשים רק לשידורים חיים.

מקורות מידע בנושא YouTube Live Streaming API

מקורות מידע בנושא YouTube Data API

מקורות מידע על YouTube Content ID API

יצירה וניהול של שידור חי

בשלבים הבאים מוסבר איך ליצור אירוע בשידור חי ב-YouTube ואיך לנהל אותו. השלבים מחולקים לשלבים הבאים:

  1. הגדרת השידור
  2. תביעה על תוכן
  3. בדיקה
  4. שידור
  5. סיום השידור
  6. יצירת קובץ עזר

שלב 1: הגדרת השידור

שלב 1.1: יצירת השידור

מתקשרים לשיטה liveBroadcasts.insert כדי להוסיף את השידור ללוח הזמנים של אירועים בשידור חי ב-YouTube. במשאב liveBroadcast שמוסיפים צריך להגדיר ערכים למאפיינים שמפורטים בהמשך.

חשוב לפעול בהתאם להנחיות הבאות כשמגדירים את השידור:

  • אם רוצים להגדיר שלב בדיקה לשידור, שבו אפשר לצפות בשידור הווידאו בלי שצופים אחרים יוכלו לצפות בו, צריך להגדיר את המאפיין contentDetails.monitorStream.enableMonitorStream לערך true ואת המאפיין contentDetails.enableAutoStart לערך false. אלה ערכי ברירת המחדל של שני המאפיינים.

  • אם רוצים ליצור הפניה מהשידור המוקלט, צריך להגדיר את המאפיין contentDetails.recordFromStart של השידור לערך true. אם רוצים שהסרטון המוקלט יהיה זמין להפעלה מיד אחרי סיום השידור, צריך להגדיר את המאפיין contentDetails.enableDvr לערך true. (לשני הנכסים האלה יש ערך ברירת מחדל של true).

  • אתם יכולים לעדכן כל אחד מהמאפיינים של contentDetails כל עוד הסטטוס של השידור הוא created או ready.

  • אפשר לעדכן את שעת ההתחלה המתוזמנת ואת שעת הסיום המתוזמנת של השידור כל עוד הסטטוס שלו הוא created, ready או testing.

  • אפשר לעדכן בכל שלב את השם, התיאור וסטטוס הפרטיות של השידור, וגם שדות אחרים של מטא-נתונים שכלולים במשאב video של השידור.

    הערה: אם אתם רוצים שהסרטון יהיה זמין רק למשתמשים ספציפיים ב-YouTube, צריך להגדיר את ערך המאפיין status.privacyStatus ל-unlisted או ל-private, בהתאם לצרכים שלכם.

עיבוד התגובה מה-API

כשקוראים ל-method ‏liveBroadcasts.insert, התשובה של ה-API מכילה את המשאב liveBroadcast שיצרתם. הקוד צריך לחלץ ולאחסן את id מהמשאב הזה. תצטרכו את הערך הזה כדי לזהות את השידור בבקשות API עתידיות. (אפשר גם לזהות את משאב video שמתאים למשאב liveBroadcast באמצעות אותו מזהה).

שלב 1.2: יצירת הזרם

משאב liveStream מאפשר לכם להעביר את הסרטון ל-YouTube, והוא מתאר את התוכן שאתם מעבירים. כל שידור צריך להיות משויך לשידור חי אחד בלבד.

קוראים לשיטה liveStreams.insert כדי ליצור את זרם הווידאו של האירוע. כשיוצרים את הסטרימינג, צריך להגדיר ערכים למאפיינים שמפורטים בהמשך:

חוץ משם השידור, אי אפשר לעדכן את הערכים האלה אחרי שהשידור נוצר. אם אתם צריכים לשנות אותם, אתם צריכים ליצור סטרימינג אחר על ידי חזרה על השלב הזה. התהליך הזה מוסבר בפירוט רב יותר בשלב 3.5 בהמשך המאמר.

יש לכם גם אפשרות להגדיר ערכים למאפיינים הבאים:

  • ‫snippet.description – אפשר לעדכן את תיאור השידור אחרי שיוצרים אותו, כמו את שם השידור. הכותרת והתיאור לא גלויים למשתמשי YouTube.

  • ‫contentDetails.isReusable - מציין אם אפשר להשתמש בסטרימינג שוב, כלומר אם אפשר לשייך אותו לכמה שידורים. הערך של המאפיין הזה קובע למעשה אם יש קשר מסוג 'רבים לאחד' או 'אחד לאחד' בין מקורות liveBroadcast ו-liveStream בערוץ:

    • אם משתמשים בערך ברירת המחדל של המאפיין, שהוא true, אפשר להשתמש באותו מקור liveStream לכל השידורים של הערוץ. כלומר, לא צריך לחזור על השלב הזה (1.2) לכל שידור. במקום זאת, אפשר פשוט להשתמש שוב במזהה מקור הנתונים לשידורים הבאים.
    • אם מגדירים את ערך המאפיין ל-false, צריך ליצור שידור חדש לכל שידור.

אחרי ששולחים את בקשת ה-API ליצירת מקור הנתונים, תגובת ה-API מכילה את משאב liveStream שיצרתם. הקוד צריך לחלץ את id מהמשאב הזה ולאחסן אותו. תצטרכו את הערך הזה כדי לזהות את הסטרים בבקשות API עתידיות.

שלב 1.3: קישור השידור לסטרימינג

אחרי שיצרתם את המשאבים liveBroadcast ו-liveStream, אתם צריכים לקשר ביניהם באמצעות השיטה liveBroadcasts.bind. הפעולה הזו מקשרת את חלקי הווידאו שתשדרו ל-YouTube לשידור האירוע של הסרטון הזה.

כשקוראים ל-method ‏liveBroadcasts.bind, מגדירים את הפרמטר id למזהה השידור שהתקבל בשלב 1.1 ואת הפרמטר streamId למזהה הסטרימינג שהתקבל בשלב 1.2.

שלב 2: שליחת תביעה על התוכן

אם רוצים להציג מודעות במהלך השידור, צריך לשלוח תביעת זכויות יוצרים על סרטון השידור לפני שהאירוע מתחיל. השלבים הבאים מסבירים את התהליך הזה. שימו לב: כל הקריאות ל-API שמוזכרות בשלב הזה מוגדרות ב-YouTube Content ID API.

שלב 2.1: יצירת נכס

משאב asset מייצג פריט של קניין רוחני. במקרה הזה, הנכס הוא השידור שלכם. מתקשרים אל השיטה assets.insert כדי ליצור את הנכס.

תגובת ה-API תכיל את המשאב asset שיצרתם. הקוד צריך לחלץ ולאחסן את id מהמשאב הזה, כי תצטרכו את הערך הזה כדי לזהות את הנכס בבקשות עתידיות ל-API.

שלב 2.2: הגדרת הבעלות על הנכס

נתוני הבעלות של נכס מזהים את הבעלים של הנכס ואת האזורים שבהם הם הבעלים של הנכס. הנתונים האלה משמשים את YouTube כדי לקבוע איפה בעל התוכן יכול להגדיר את המדיניות לגבי סרטון שהוגשה לגביו תלונה על הפרת זכויות יוצרים.

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

כדי להגדיר את האזורים שבהם אתם הבעלים של הנכס, צריך להפעיל את השיטה ownership.update. בבקשה הזו, מגדירים את הפרמטר assetId לערך id ששמרתם בשלב 2.1.

שלב 2.3: הגדרת מדיניות ההתאמה של הנכס

מדיניות ההתאמה של נכס מסבירה מה מערכת YouTube צריכה לעשות כשמשתמש מעלה סרטון שתואם לקובץ עזר שמשויך לנכס. במקרה כזה, מדיניות ההתאמה תציין איך מערכת YouTube צריכה לטפל בסרטון שהועלה וזהה לשידור החי שלכם.

הערה: כדאי להגדיר מדיניות התאמה אם אתם מתכננים ליצור קובץ עזר מהשידור שלכם ולהשתמש בו כדי לזהות סרטונים שהועלו על ידי משתמשים ושיש בהם התאמה לשידור שלכם. אם לא, אפשר לדלג על השלב הזה.

כדי להגדיר את מדיניות ההתאמה, קודם צריך לזהות את המדיניות שרוצים להחיל. אפשר לאחזר רשימה של מדיניות קיימת באמצעות קריאה לשיטה policies.list, או להגדיר מדיניות חדשה באמצעות קריאה לשיטה policies.insert. בכל מקרה, צריך לתעד את id של המדיניות שרוצים להחיל.

אחרי שמזהים את המדיניות, מפעילים את השיטה assetMatchPolicy.update. בבקשה הזו, מגדירים את הפרמטר assetId לערך id ששמרתם בשלב 2.1.

שלב 2.4: הצהרה על זכויות יוצרים בסרטון

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

כדי ליצור תביעה, קוראים ל-method‏ claims.insert. במשאב claim שמוסיפים, צריך להגדיר ערכים למאפיינים הבאים:

  • ‫assetId – הערך הזה התקבל בשלב 2.1.
  • ‫videoId – זהו מזהה השידור שהשגתם בשלב 1.1.
  • ‫policy – זהו משאב policy. כדי להחיל מדיניות קיימת, מגדירים את המאפיין id של המשאב למזהה של המדיניות הקיימת. בשלב הקודם מוסבר איך מאחזרים את המזהה של מדיניות קיימת.
  • ‫contentType – מגדירים את הערך הזה כ-audiovisual.

עיבוד התגובה מה-API

כשמוסיפים את התלונה, תגובת ה-API תכיל את משאב claim שיצרתם. הקוד צריך לחלץ את id מהמשאב הזה ולאחסן אותו. תשתמשו בערך הזה בהמשך כדי ליצור הפניה מהסרטון המעובד.

שלב 2.5: עדכון הגדרות המודעות לשידור

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

  • אם מפעילים מודעות לפני תחילת התוכן בשידור, כל הצופים יראו מודעה כשהם יתחילו לצפות בשידור, גם אם הם יתחילו לצפות באמצע השידור.
  • אם תפעילו מודעות באמצע הסרטון בשידור, תוכלו להוסיף נקודות לציון הפסקות למודעות במהלך השידור.

כדי להפעיל מודעות, קוראים לשיטה videoAdvertisingOptions.update. בבקשה, מגדירים את הפרמטר videoId לערך השידור id שהתקבל בשלב 1.1. כדי לזהות את פורמטי המודעות (preroll, ‏ midroll או postroll) שרוצים להפעיל, משתמשים במאפיין adFormats[] של רכיב videoAdvertisingOption.

שלב 3: בדיקה

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

שימו לב שאפשר לבדוק את שידור הסרטון רק אם הפעלתם את שידור הבקרה שלו. כברירת מחדל, הזרמות לניטור של שידורים מופעלות. כדי להשבית את שידור המעקב של שידור, צריך להגדיר את המאפיין contentDetails.monitorStream.enableMonitorStream לערך false כשיוצרים או מעדכנים את השידור.

שלב 3.1: הטמעת נגן של שידור ממצלמה

מאחזרים את השידור באמצעות השיטה liveBroadcasts.list ומחלצים את הערך של המאפיין contentDetails.streamDetails.monitorStreamEmbedHtml. הערך הזה כולל את קוד ה-HTML שנדרש להטמעת נגן YouTube שמציג את השידור של המסך.

שלב 3.2: מתחילים את הסרטון

מתחילים לשדר את הווידאו בשידור הווידאו.

שלב 3.3: מוודאים שזרם הווידאו פעיל

מפעילים את ה-method‏ liveStreams.list כדי לאחזר את המשאב liveStream שמשויך לשידור. מוודאים שהערך של המאפיין status.streamStatus הוא active, מה שמציין שהשרתים של YouTube מקבלים נתונים מהמקודד שלכם בצורה תקינה.

שלב 3.4: מעבירים את סטטוס השידור לבדיקה

קוראים לשיטה liveBroadcasts.transition כדי לעדכן את הסטטוס של השידור. מגדירים את ערך הפרמטר id למזהה השידור שהתקבל בשלב 1.1, ואת ערך הפרמטר broadcastStatus ל-testing.

אחרי שמפעילים את השיטה liveBroadcasts.transition, יכול להיות שיעברו כמה שניות, או אפילו עד דקה, עד שהמעבר יסתיים. במהלך הזמן הזה, צריך לשלוח בקשות ל-API כדי לבדוק את סטטוס השידור. עד שהמעבר יסתיים, הסטטוס של השידור יהיה testStarting. הסטטוס יהיה testing כשהמעבר יסתיים.

שלב 3.5: השלמת הבדיקה

אם הבדיקה עברה בצורה חלקה, אפשר לעבור אל שלב 4. עם זאת, במקרים מסוימים, יכול להיות שתצטרכו לבצע בדיקות נוספות. לדוגמה, אם הבדיקה מגלה ששידור הווידאו לא מוגדר בצורה נכונה, צריך לתקן את זה לפני שממשיכים בשידור.

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

  1. כדי לבטל את הקישור של שידור הווידאו, צריך לבצע קריאה ל-method‏ liveBroadcasts.bind משלב 1.3. בבקשת ה-API, מגדירים את הפרמטר id לערך id שהתקבל בשלב 1.1. אל תכללו את הפרמטר streamId בבקשה.

  2. כדי למחוק את זרם הווידאו, צריך לבצע קריאה ל-method‏ liveStreams.delete. בבקשה, מגדירים את הפרמטר id לערך id שהתקבל בשלב 1.2.

  3. חוזרים על שלב 1.2 כדי ליצור משאב liveStream חדש שמוגדר בצורה נכונה. לאחר מכן חוזרים על שלב 1.3 כדי לקשר את הסטרימינג החדש לשידור, ועל שלבים 3.1 עד 3.3 כדי לבדוק את הסטרימינג החדש.

שלב 3.6: הפעלת המאפיינים autoStart ו-autoStop

אחרי שתסיימו את שלב הבדיקה בהצלחה, תוכלו להגדיר את המאפיינים של השידור contentDetails.enableAutoStart וcontentDetails.enableAutoStop לערך true לפני שהשידור עצמו יתחיל. אי אפשר להגדיר את המאפיינים האלה לערך true לפני שלב הבדיקה, כי הבדיקה תגרום בפועל להתחלת השידור.

שלב 4: שידור

בשלב הזה, הקהל יכול לצפות בסרטון השידור.

שלב 4.1: מתחילים את הסרטון

מתחילים לשדר את הווידאו בשידור הווידאו.

שלב 4.2: מוודאים שזרם הווידאו פעיל

מפעילים את ה-method‏ liveStreams.list כדי לאחזר את המשאב liveStream שמשויך לשידור. מוודאים שהערך של המאפיין status.streamStatus הוא active, מה שמציין שהשרתים של YouTube מקבלים נתונים מהמקודד שלכם בצורה תקינה.

שלב 4.3: מעבירים את הסטטוס של השידור לשידור חי

חשוב: אחרי השלב הזה, הקהל יוכל לראות את הסרטון.

קוראים לשיטה liveBroadcasts.transition כדי לעדכן את הסטטוס של השידור. מגדירים את ערך הפרמטר id למזהה השידור שהתקבל בשלב 1.1, ואת ערך הפרמטר broadcastStatus ל-live.

אם מגדירים את המאפיין contentDetails.enableAutoStart של משאב liveBroadcast לערך true, לא צריך להפעיל את השיטה liveBroadcasts.transition.

אחרי שמבצעים את הקריאה הזו ל-API – או אם הגדרתם את המאפיין contentDetails.enableAutoStart לערך true, אחרי שמתחילים את השידור – בדרך כלל צריך להמתין 5 עד 10 שניות עד שהמעבר הזה יסתיים. יכול להיות שיחלפו עד דקה עד שהמעבר יסתיים. במהלך הזמן הזה, כדאי לשלוח בקשות ל-API כדי לבדוק את סטטוס השידור. עד שהמעבר יסתיים, הסטטוס של השידור יהיה liveStarting. הסטטוס יהיה live כשהמעבר יסתיים והצופים יוכלו לצפות בשידור שלכם מהנקודה הזו בשידור המוניטור.

חשוב לשים לב להשפעות הבאות של הפקודה הזו:

  • אם הפעלתם את שידור הבקרה לשידור שלכם – ראו שלב 3.1 – תוכלו לראות את שידור הבקרה בנגן מוטמע.
  • אם הגדרתם ערך למאפיין contentDetails.streamDetails.broadcastStreamDelayMs של השידור, יהיה עיכוב של פרק הזמן הזה בשידור, שגלוי לצופים אחרים.

שלב 4.4: הוספת הפסקות לפרסום לשידור

מפעילים את method‏ liveBroadcasts.cuepoint כדי להוסיף cuepoint. יכול להיות שנקודת ה-cue תפעיל הפסקה למודעה. במשאב cuepoint שמופיע בגוף הבקשה, מגדירים את המאפיין durationSecs למשך ההפסקה הרצוי (בשניות) שרוצים להציג. (ערך ברירת המחדל הוא 30).

בשלב הזה, מערכת YouTube מנסה להפעיל מודעה בנגן הווידאו לכל הצופים שצפו בשידור כשהוכנס סימן המודעה. הצגת המודעה תלויה במגוון גורמים, כמו זמינות המודעה והיסטוריית הצפייה של הצופה במודעות. צופים שיוצגו להם הפסקות לפרסום יחזרו לשידור שלכם כשההפסקות יסתיימו, ואילו צופים שלא יוצגו להם מודעות ימשיכו לצפות בשידור במהלך ההפסקות.

במדריך תחילת העבודה יש מידע נוסף על חוויית הצפייה במהלך הפסקת פרסומות בשידור חי.

שלב 5: סיום השידור

שלב 5.1: הפסקת השידור

בזה מסתיימת הבדיקה של מערכת השידור החי ב-YouTube.

שלב 5.2: מעבירים את סטטוס השידור ל'הושלם'

כשרוצים להפסיק את השידור, קוראים לשיטה liveBroadcasts.transition של ה-API כדי לעדכן את סטטוס השידור. מגדירים את הערך של הפרמטר id למזהה השידור שהתקבל בשלב 1.1, ואת הערך של הפרמטר broadcastStatus ל-complete.

אם הגדרתם את המאפיינים contentDetails.recordFromStart וcontentDetails.enableDvr של השידור לערך true, הקהל יוכל לצפות מיד בהפעלה של האירוע החי כשהוא יסתיים.

שלב 6: יצירת קובץ עזר

אחרי שהצילום בזמן אמת מסתיים, אפשר ליצור קובץ עזר מהסרטון שצולם. הפעולה הזו מורה ל-YouTube לחפש סרטונים שהועלו על ידי משתמשים ותואמים לשידור, ולטפל בהם בהתאם למדיניות ההתאמה שהגדרתם בשלב 2.3.

חשוב: כדי ליצור את ההפניה, צריך להגדיר את המאפיין contentDetails.recordFromStart של השידור לערך true.

שלב 6.1: שולחים שאילתה ל-Data API כדי לקבל את הסטטוס של הסרטון

כדי ליצור הפניה מסרטון, צריך להמתין עד ש-YouTube יסיים לעבד את השידור או את הסרטון שהועלה. כדי לקבוע אם הסרטון סיים את העיבוד, צריך להפעיל את השיטה videos.list של YouTube Data API, להגדיר את הפרמטר part לערך status ואת הפרמטר id למזהה השידור ששמרתם בשלב 1.1.

תשובת ה-API לבקשת הבדיקה שלכם תכיל משאב video. אם הערך של מאפיין status.uploadStatus במשאב הזה הוא processed, ממשיכים לשלב 6.2.

שלב 6.2: יצירת קובץ עזר מהסרטון שעבר עיבוד

כדי ליצור את ההפניה, קוראים לשיטה references.insert של Content ID API ומגדירים את הפרמטר claimId למזהה התביעה ששמרתם בשלב 2.4.

שליחת תוכן לשידור חי במערכת Content ID

חלק מהשותפים של YouTube יכולים ליצור עותק להשוואה לפני שהשידור שלהם עובר למצב testing, אבל התכונה הזו לא זמינה לכל השותפים. במהלך השידור, YouTube יוצר ומעדכן באופן שוטף את ההפניה משידור האירוע בשידור חי. בנוסף, מערכת YouTube מחפשת סרטונים תואמים שהועלו על ידי משתמשים בזמן שהשידור עדיין מתבצע. שימו לב שאם יוצרים עותק לצורך השוואה לפני תחילת השידור, ההקלטה של השידור מופעלת באופן אוטומטי, ואי אפשר להשבית אותה אחרי יצירת העותק.

כדי להפעיל את השידור שלכם למסירת תוצאות של Content ID בשידור חי, נסו לבצע את הפעולות שמתוארות בשלב 6.2 אחרי שליחת הצהרה על זכויות יוצרים לגבי הסרטון בשלב 2.4. אם החשבון של השותף לא אושר ליצירת הפניה לשידור חי לפני שהשידור מתרחש, ה-API יחזיר שגיאה fingerprintingNotAllowed. במקרה כזה, צריך לחכות עד שהשידור יסתיים, כמו שמתואר בשלבים 6.1 ו-6.2 למעלה, לפני שיוצרים את קובץ העזר.