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

מבוא

במסמך הזה נסביר על מחזור החיים של שידור חי ב-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: יצירת השידור

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

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

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

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

  • אם אתם רוצים להגביל את האזורים שבהם אפשר לצפות בשידור, אתם יכולים להגדיר את המאפיין contentDetails.availabilityConfig. המאפיין הזה מאפשר לחסום אזורים ספציפיים או להגביל את הזמינות לרשימה מוגדרת של אזורים. אפשר גם לציין חלונות זמן לזמינות אזורית.

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

  • אתם יכולים לעדכן כל אחד מהמאפיינים של 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](

    /youtube/data/live/reference/rest/v3/liveStreams#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 צריכה לטפל בסרטון שהועלה ותואם לשידור החי שלכם.

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

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

אחרי שמזהים את המדיניות, מפעילים את ה-method‏ 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. משתמשים במאפיין adFormats[] של המשאב videoAdvertisingOption כדי לזהות את פורמטי המודעות (preroll,‏ midroll או postroll) שרוצים להפעיל.

שלב 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. כדי למחוק את זרם הווידאו, צריך להריץ את שיטת 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, לא צריך להפעיל את ה-method‏ liveBroadcasts.transition.

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

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

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

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

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

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

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

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

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

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

שלב 5.2: מעבירים את סטטוס השידור ל-complete (הושלם)

כשתהיו מוכנים להפסיק את השידור, תצטרכו להפעיל את ה-method‏ 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 למעלה, ורק אז ליצור את קובץ העזר.