YouTube Player API Reference for iframe Embeds

ה-API של נגן ה-IFrame מאפשר לכם להטמיע נגן וידאו של YouTube באתר שלכם ולשלוט בנגן באמצעות JavaScript.

באמצעות פונקציות ה-JavaScript של ממשק ה-API, תוכלו להוסיף סרטונים לתור להפעלה, להפעיל, להשהות או לעצור את הסרטונים האלה, לכוונן את עוצמת הקול בנגן או לאחזר מידע על הסרטון שהופעל. אפשר גם להוסיף פונקציות event listener שיופעלו בתגובה לאירועי נגנים מסוימים, כמו שינוי במצב הנגן.

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

דרישות

הדפדפן של המשתמש חייב לתמוך בתכונה postMessage HTML5. רוב הדפדפנים המודרניים תומכים ב-postMessage.

נגנים מוטמעים חייבים להשתמש באזור תצוגה של לפחות 200 פיקסלים על 200 פיקסלים. אם בנגן מוצגים פקדים, הוא צריך להיות גדול מספיק כדי להציג את הפקדים במלואם בלי לכווץ את אזור התצוגה מתחת לגודל המינימלי. מומלץ שנגנים עם יחס גובה-רוחב של 16:9 יהיו לפחות ברוחב של 480 פיקסלים ובאורך של 270 פיקסלים.

כל דף אינטרנט שמשתמש ב-IFrame API חייב לכלול גם את פונקציית JavaScript הבאה:

  • onYouTubeIframeAPIReady – ה-API יקרא לפונקציה הזו כשהדף יסיים להוריד את ה-JavaScript של ה-API של הנגן, כדי שתוכלו להשתמש ב-API בדף. לכן, הפונקציה הזו עשויה ליצור את האובייקטים של הנגן שרוצים להציג כשהדף נטען.

איך מתחילים

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

<!DOCTYPE html>
<html>
  <body>
    <!-- 1. The <iframe> (and video player) will replace this <div> tag. -->
    <div id="player"></div>

    <script>
      // 2. This code loads the IFrame Player API code asynchronously.
      var tag = document.createElement('script');

      tag.src = "https://www.youtube.com/iframe_api";
      var firstScriptTag = document.getElementsByTagName('script')[0];
      firstScriptTag.parentNode.insertBefore(tag, firstScriptTag);

      // 3. This function creates an <iframe> (and YouTube player)
      //    after the API code downloads.
      var player;
      function onYouTubeIframeAPIReady() {
        player = new YT.Player('player', {
          height: '390',
          width: '640',
          videoId: 'M7lc1UVf-VE',
          playerVars: {
            'playsinline': 1
          },
          events: {
            'onReady': onPlayerReady,
            'onStateChange': onPlayerStateChange
          }
        });
      }

      // 4. The API will call this function when the video player is ready.
      function onPlayerReady(event) {
        event.target.playVideo();
      }

      // 5. The API calls this function when the player's state changes.
      //    The function indicates that when playing a video (state=1),
      //    the player should play for six seconds and then stop.
      var done = false;
      function onPlayerStateChange(event) {
        if (event.data == YT.PlayerState.PLAYING && !done) {
          setTimeout(stopVideo, 6000);
          done = true;
        }
      }
      function stopVideo() {
        player.stopVideo();
      }
    </script>
  </body>
</html>

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

  1. התג <div> בקטע הזה מזהה את המיקום בדף שבו ממשק ה-API של IFrame ימקם את נגן הווידאו. ה-constructor של אובייקט הנגן, שמתואר בקטע טעינת נגן וידאו, מזהה את התג <div> לפי ה-id שלו, כדי לוודא שה-API ממקם את <iframe> במיקום הנכון. באופן ספציפי, iFrame API יחליף את התג <div> בתג <iframe>.

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

  2. הקוד בקטע הזה טוען את קוד ה-JavaScript של IFrame Player API. בדוגמה נעשה שימוש בשינוי DOM כדי להוריד את קוד ה-API ולוודא שהקוד מאוחזר באופן אסינכרוני. (המאפיין async של התג <script>, שמאפשר גם הורדות אסינכרוניות, אינו נתמך עדיין בכל הדפדפנים המתקדמים, כפי שמתואר בתשובה של Stack Overflow זו.

  3. הפונקציה onYouTubeIframeAPIReady תופעל מיד לאחר הורדת קוד ה-API של הנגן. החלק הזה של הקוד מגדיר משתנה גלובלי, player, שמתייחס לנגן הווידאו שאתם מטמיעים, והפונקציה בונה את האובייקט של נגן הווידאו.

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

  5. ה-API יקרא לפונקציה onPlayerStateChange כשמצב הנגן משתנה. פעולה זו עשויה להעיד על כך שהנגן פועל, מושהה, הסתיים וכן הלאה. הפונקציה מציינת שכשמצב הנגן הוא 1 (מופעל), הנגן צריך לפעול במשך שש שניות ואז להפעיל את הפונקציה stopVideo כדי להפסיק את הסרטון.

נגן וידאו בטעינה

אחרי שקוד ה-JavaScript של ה-API ייטען, ה-API יקרא לפונקציה onYouTubeIframeAPIReady ואז תוכלו לבנות אובייקט YT.Player כדי להוסיף נגן וידאו לדף שלכם. בקטע ה-HTML הבא מוצגת הפונקציה onYouTubeIframeAPIReady מהדוגמה שלמעלה:

var player;
function onYouTubeIframeAPIReady() {
  player = new YT.Player('player', {
    height: '390',
    width: '640',
    videoId: 'M7lc1UVf-VE',
    playerVars: {
      'playsinline': 1
    },
    events: {
      'onReady': onPlayerReady,
      'onStateChange': onPlayerStateChange
    }
  });
}

ה-constructor של נגן הווידאו מציין את הפרמטרים הבאים:

  1. הפרמטר הראשון מציין את רכיב ה-DOM או את ה-id של רכיב ה-HTML שבו ה-API יוסיף את התג <iframe> שמכיל את הנגן.

    ה-iFrame API יחליף את הרכיב שצוין ברכיב <iframe> שמכיל את הנגן. אם לרכיב שהוחלף יש סגנון תצוגה שונה מסגנון התצוגה של הרכיב <iframe> שנוסף, יכולה להיות לכך השפעה על פריסת הדף. כברירת מחדל, <iframe> מוצג כרכיב inline-block.

  2. הפרמטר השני הוא אובייקט שמציין את אפשרויות הנגן. האובייקט מכיל את המאפיינים (properties) הבאים:
    • width (מספר) – הרוחב של נגן הווידאו. ערך ברירת המחדל הוא 640.
    • height (מספר) – הגובה של נגן הווידאו. ערך ברירת המחדל הוא 390.
    • videoId (מחרוזת) – מזהה הסרטון ב-YouTube שמזהה את הסרטון שהנגן יטען.
    • playerVars (אובייקט) – מאפייני האובייקט מזהים פרמטרים של נגן שבהם אפשר להשתמש כדי להתאים אישית את הנגן.
    • events (אובייקט) – המאפיינים של האובייקט מזהים את האירועים שה-API מפעיל ואת הפונקציות (פונקציות event listener) שה-API יקרא להן כשהאירועים האלה יתרחשו. בדוגמה, ה-constructor מציין שהפונקציה onPlayerReady תופעל כשהאירוע onReady מופעל, ושהפונקציה onPlayerStateChange תפעל כשהאירוע onStateChange מופעל.

כפי שצוין בקטע תחילת העבודה, במקום לכתוב רכיב <div> ריק בדף, שאותו קוד ה-JavaScript של ה-API של הנגן יחליף לאחר מכן ברכיב <iframe>, אתם יכולים ליצור את התג <iframe> בעצמכם. הדוגמה הראשונה בקטע דוגמאות ממחישה איך לעשות את זה.

<iframe id="player" type="text/html" width="640" height="390"
  src="http://www.youtube.com/embed/M7lc1UVf-VE?enablejsapi=1&origin=http://example.com"
  frameborder="0"></iframe>

שימו לב שאם בכל זאת כותבים את התג <iframe>, אז כשיוצרים את האובייקט YT.Player, אין צורך לציין ערכים ל-width ול-height, המוגדרים כמאפיינים של התג <iframe>, או של הפרמטרים videoId ושל הנגן, שצוינו בכתובת ה-URL src. כאמצעי אבטחה נוסף, צריך לכלול בכתובת ה-URL גם את הפרמטר origin, ולציין את סכמת כתובת ה-URL (http:// או https://) ואת הדומיין המלא של הדף המארח כערך הפרמטר. אמנם origin הוא אופציונלי, אך כולל הגנה מפני JavaScript זדוני של צד שלישי שמחדירים לדף שלך ואפשרות לפריצת מחשבים בנגן YouTube שלך.

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

פעולות

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

פונקציות

פונקציות נוספות לתור

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

ה-API תומך בשני תחבירים שונים לקריאה לפונקציות של הוספה לתור.

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

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

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

  • תחביר של ארגומנטים

    loadVideoById("bHQqvYy5KYo", 5, "large")
  • תחביר אובייקטים

    loadVideoById({'videoId': 'bHQqvYy5KYo',
                   'startSeconds': 5,
                   'endSeconds': 60});

פונקציות שמוסיפים לרשימת 'הבאים בתור' לסרטונים

cueVideoById
  • תחביר של ארגומנטים

    player.cueVideoById(videoId:String,
                        startSeconds:Number):Void
  • תחביר אובייקטים

    player.cueVideoById({videoId:String,
                         startSeconds:Number,
                         endSeconds:Number}):Void

הפונקציה הזו טוענת את התמונה הממוזערת של הסרטון שצוין ומכינה את הנגן להפעלת הסרטון. הנגן לא מבקש את קובץ ה-FLV עד שמתבצעת קריאה ל-playVideo() או ל-seekTo().

  • הפרמטר videoId הנדרש מציין את מזהה הסרטון ב-YouTube של הסרטון שרוצים להפעיל. ב-YouTube Data API, המאפיין id של משאב video מציין את המזהה.
  • הפרמטר האופציונלי startSeconds מקבל ערך של מספר ממשי (float)/שלם ומציין את השעה שבה צריך להתחיל הסרטון כאשר מופעל playVideo(). אם מציינים ערך של startSeconds ואז קוראים ל-seekTo(), הנגן יתחיל לפעול מהשעה שצוינה בקריאה seekTo(). כשמסמנים את הסרטון ומוכן להפעלה, הנגן ישדר אירוע אחד (video cued) (5).
  • הפרמטר האופציונלי endSeconds, שנתמך בתחביר אובייקט בלבד, מקבל ערך של מספר ממשי (float)/שלם ומציין את השעה שבה הסרטון אמור להפסיק לפעול, כאשר מתבצעת קריאה ל-playVideo(). אם מציינים ערך מסוג endSeconds ואז קוראים לפונקציה seekTo(), הערך של endSeconds לא יהיה בתוקף.

loadVideoById

  • תחביר של ארגומנטים

    player.loadVideoById(videoId:String,
                         startSeconds:Number):Void
  • תחביר אובייקטים

    player.loadVideoById({videoId:String,
                          startSeconds:Number,
                          endSeconds:Number}):Void

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

  • הפרמטר videoId הנדרש מציין את מזהה הסרטון ב-YouTube של הסרטון שרוצים להפעיל. ב-YouTube Data API, המאפיין id של משאב video מציין את המזהה.
  • הפרמטר האופציונלי startSeconds מקבל ערך של מספר ממשי (float)/מספר שלם. אם צוין, הסרטון יתחיל בתמונת המפתח הקרובה ביותר לזמן שצוין.
  • הפרמטר האופציונלי endSeconds מקבל ערך של מספר ממשי (float)/מספר שלם. אם צוין, הסרטון יפסיק לפעול בשעה שצוינה.

cueVideoByUrl

  • תחביר של ארגומנטים

    player.cueVideoByUrl(mediaContentUrl:String,
                         startSeconds:Number):Void
  • תחביר אובייקטים

    player.cueVideoByUrl({mediaContentUrl:String,
                          startSeconds:Number,
                          endSeconds:Number}):Void

הפונקציה הזו טוענת את התמונה הממוזערת של הסרטון שצוין ומכינה את הנגן להפעלת הסרטון. הנגן לא מבקש את קובץ ה-FLV עד שמתבצעת קריאה ל-playVideo() או ל-seekTo().

  • הפרמטר הנדרש mediaContentUrl מציין כתובת URL מלאה של נגן YouTube בפורמט http://www.youtube.com/v/VIDEO_ID?version=3.
  • הפרמטר האופציונלי startSeconds מקבל ערך של מספר ממשי (float)/שלם ומציין את השעה שבה צריך להתחיל הסרטון כאשר מופעל playVideo(). אם מציינים את הערך startSeconds ואז קוראים לפונקציה seekTo(), הנגן יתחיל לפעול מהשעה שצוינה בקריאה seekTo(). כשהסרטון מסומן ומוכן להפעלה, הנגן ישדר אירוע אחד (video cued) (5).
  • הפרמטר האופציונלי endSeconds, שנתמך בתחביר אובייקט בלבד, מקבל ערך של מספר ממשי (float)/שלם ומציין את השעה שבה הסרטון אמור להפסיק לפעול, כאשר מתבצעת קריאה ל-playVideo(). אם מציינים ערך מסוג endSeconds ואז קוראים לפונקציה seekTo(), הערך של endSeconds לא יהיה בתוקף.

loadVideoByUrl

  • תחביר של ארגומנטים

    player.loadVideoByUrl(mediaContentUrl:String,
                          startSeconds:Number):Void
  • תחביר אובייקטים

    player.loadVideoByUrl({mediaContentUrl:String,
                           startSeconds:Number,
                           endSeconds:Number}):Void

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

  • הפרמטר הנדרש mediaContentUrl מציין כתובת URL מלאה של נגן YouTube בפורמט http://www.youtube.com/v/VIDEO_ID?version=3.
  • הפרמטר האופציונלי startSeconds מקבל ערך של מספר ממשי (float)/שלם ומציין את השעה שממנה יש להתחיל את הסרטון. אם צוין startSeconds (המספר יכול להיות מספר ממשי (float)), הסרטון יתחיל מתמונת המפתח הקרובה ביותר לזמן שצוין.
  • הפרמטר האופציונלי endSeconds, שנתמך בתחביר אובייקט בלבד, מקבל ערך של מספר ממשי (float)/שלם ומציין את השעה שבה הסרטון אמור להפסיק לפעול.

פונקציות נוספות לתור לרשימות

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

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

cuePlaylist
  • תחביר של ארגומנטים

    player.cuePlaylist(playlist:String|Array,
                       index:Number,
                       startSeconds:Number):Void
    מוסיפים את הפלייליסט שצוין לרשימת 'הבאים בתור'. כשמסמנים את הפלייליסט ומוכן להפעלה, הנגן ישדר אירוע אחד (video cued) (5).
    • הפרמטר playlist הנדרש מציין מערך של מזהי סרטונים ב-YouTube. ב-YouTube Data API, הנכס id של המשאב video מזהה את מזהה הסרטון הזה.

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

    • הפרמטר האופציונלי startSeconds מקבל ערך של מספר ממשי (float)/שלם ומציין את השעה שבה מתחיל הסרטון הראשון בפלייליסט, כאשר מופעלת הפונקציה playVideo(). אם מציינים ערך של startSeconds ואז קוראים ל-seekTo(), הנגן יתחיל לפעול מהשעה שצוינה בקריאה seekTo(). אם מסמנים פלייליסט ואז מפעילים את הפונקציה playVideoAt(), הנגן יתחיל לפעול בתחילת הסרטון שצוין.

  • תחביר אובייקטים

    player.cuePlaylist({listType:String,
                        list:String,
                        index:Number,
                        startSeconds:Number}):Void
    הוספת רשימת הסרטונים שצוינה לתור אחר. הרשימה יכולה להיות פלייליסט או פיד סרטונים שהועלו על ידי משתמש. החל מ-15 בנובמבר 2020 לא תהיה אפשרות להוסיף לרשימה של תוצאות חיפוש הוצאה משימוש.

    לאחר סימון הרשימה והיא מוכנה להפעלה, השחקן ישדר אירוע אחד (video cued) (5).

    • המאפיין האופציונלי listType מציין את סוג פיד התוצאות שאתם מאחזרים. הערכים החוקיים הם playlist ו-user_uploads. החל מ-15 בנובמבר 2020 לא תהיה יותר תמיכה בערך שהוצא משימוש, search. ערך ברירת המחדל הוא playlist.

    • מאפיין החובה list מכיל מפתח שמזהה את רשימת הסרטונים הספציפית שמערכת YouTube אמורה להחזיר.

      • אם ערך המאפיין listType הוא playlist, המאפיין list מציין את מזהה הפלייליסט או מערך של מזהי סרטונים. ב-YouTube Data API, המאפיין id של המשאב playlist מזהה את מזהה הפלייליסט, והמאפיין id של המשאב video מציין מזהה סרטון.
      • אם ערך המאפיין listType הוא user_uploads, הנכס list מזהה את המשתמש שהסרטונים שהועלו שלו יוחזרו.
      • אם הערך של המאפיין listType הוא search, המאפיין list מציין את שאילתת החיפוש. הערה: ב-15 בנובמבר 2020 הפונקציונליות הזו הוצאה משימוש והתמיכה בה תיפסק.

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

    • המאפיין האופציונלי startSeconds מקבל ערך של מספר ממשי (float)/שלם ומציין את השעה שבה מתחיל הסרטון הראשון ברשימה, כשמופעלת הפונקציה playVideo(). אם מציינים ערך של startSeconds ואז קוראים ל-seekTo(), הנגן יתחיל לפעול מהשעה שצוינה בקריאה seekTo(). אם מסמנים רשימה ולאחר מכן קוראים לפונקציה playVideoAt(), הנגן יתחיל לפעול בתחילת הסרטון שצוין.

loadPlaylist
  • תחביר של ארגומנטים

    player.loadPlaylist(playlist:String|Array,
                        index:Number,
                        startSeconds:Number):Void
    הפונקציה הזו טוענת את הפלייליסט שצוין ומפעילה אותו.
    • הפרמטר playlist הנדרש מציין מערך של מזהי סרטונים ב-YouTube. ב-YouTube Data API, המאפיין id של המשאב video מציין מזהה סרטון.

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

    • הפרמטר האופציונלי startSeconds מקבל ערך של מספר ממשי (float)/שלם ומציין את השעה שבה יתחיל הסרטון הראשון בפלייליסט.

  • תחביר אובייקטים

    player.loadPlaylist({list:String,
                         listType:String,
                         index:Number,
                         startSeconds:Number}):Void
    הפונקציה הזו טוענת את הרשימה שצוינה ומפעילה אותה. הרשימה יכולה להיות פלייליסט או פיד סרטונים שהועלו על ידי משתמש. האפשרות לטעון רשימה של תוצאות חיפוש הוצאה משימוש ולא תהיה יותר תמיכה החל מ-15 בנובמבר 2020.
    • המאפיין האופציונלי listType מציין את סוג פיד התוצאות שאתם מאחזרים. הערכים החוקיים הם playlist ו-user_uploads. החל מ-15 בנובמבר 2020 לא תהיה יותר תמיכה בערך שהוצא משימוש, search. ערך ברירת המחדל הוא playlist.

    • מאפיין החובה list מכיל מפתח שמזהה את רשימת הסרטונים הספציפית שמערכת YouTube אמורה להחזיר.

      • אם ערך המאפיין listType הוא playlist, המאפיין list מציין מזהה פלייליסט או מערך של מזהי סרטונים. ב-YouTube Data API, המאפיין id של המשאב playlist מציין מזהה של פלייליסט, והמאפיין id של המשאב video מציין מזהה סרטון.
      • אם ערך המאפיין listType הוא user_uploads, הנכס list מזהה את המשתמש שהסרטונים שהועלו שלו יוחזרו.
      • אם הערך של המאפיין listType הוא search, המאפיין list מציין את שאילתת החיפוש. הערה: ב-15 בנובמבר 2020 הפונקציונליות הזו הוצאה משימוש והתמיכה בה תיפסק.

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

    • המאפיין האופציונלי startSeconds מקבל ערך של מספר ממשי (float)/שלם ומציין את השעה שבה יתחיל הסרטון הראשון ברשימה לפעול.

לחצני ההפעלה והגדרות הנגן

הפעלת סרטון

player.playVideo():Void
הפעלת הסרטון שסומן/שנטענו כרגע. מצב הנגן הסופי לאחר שהפונקציה הזו מופעלת יהיה playing (1).

הערה: הפעלה נספרת רק אם היא מופעלת באמצעות לחצן הפעלה מקורי בנגן.
player.pauseVideo():Void
השהיית הסרטון שפועל עכשיו. מצב הנגן הסופי לאחר הפעלת הפונקציה הזו יהיה paused (2), אלא אם הוא במצב ended (0) כשמתבצעת קריאה לפונקציה. במקרה כזה, מצב הנגן לא ישתנה.
player.stopVideo():Void
עצירה וביטול הטעינה של הסרטון הנוכחי. כדאי לשמור את הפונקציה הזו למצבים נדירים שבהם יודעים שהמשתמש לא יצפה בסרטונים נוספים בנגן. אם המטרה שלכם היא להשהות את הסרטון, עליכם פשוט להפעיל את הפונקציה pauseVideo. כדי לשנות את הסרטון שמופעל בנגן, אפשר להפעיל אחת מהפונקציות של הוספה לתור בלי להתקשר קודם אל stopVideo.

חשוב: בשונה מהפונקציה pauseVideo, שמשאירה את הנגן במצב paused (2), הפונקציה stopVideo יכולה להעביר את הנגן לכל מצב של אי-הפעלה, כולל ended (0), paused (2), video cued (5) או unstarted (-1).
player.seekTo(seconds:Number, allowSeekAhead:Boolean):Void
דילוג לנקודת זמן ספציפית בסרטון. אם הנגן מושהה כשמפעילים את הפונקציה, הוא יישאר מושהה. אם בוצעה קריאה לפונקציה ממצב אחר (playing, video cued וכו'), הנגן יפעיל את הסרטון.
  • הפרמטר seconds מזהה את השעה שבה השחקן צריך להתקדם.

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

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

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

שליטה בהפעלה של סרטונים ב-360°

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

player.getSphericalProperties():Object
אחזור מאפיינים שמתארים את נקודת המבט או את התצוגה הנוכחית של הצופה בזמן הפעלת סרטון. כמו כן:
  • האובייקט הזה מאוכלס רק בסרטונים ב-360°, שנקראים גם סרטונים כדוריים.
  • אם הסרטון הנוכחי אינו סרטון ב-360° או אם קוראים לפונקציה ממכשיר שאינו נתמך, הפונקציה תחזיר אובייקט ריק.
  • במכשירים ניידים נתמכים, אם המאפיין enableOrientationSensor מוגדר ל-true, הפונקציה הזו מחזירה אובייקט שבו המאפיין fov מכיל את הערך הנכון והמאפיינים האחרים מוגדרים להיות 0.
האובייקט מכיל את המאפיינים הבאים:
תכונות
yaw מספר בטווח [0, 360) שמייצג את הזווית האופקית של התצוגה במעלות, המשקף את המידה שבה המשתמש מסובב את התצוגה לפניה שמאלה או ימינה. המיקום הניטרלי, כלפי מרכז הסרטון בהקרנה המלבנית שלו, מייצג 0°, והערך הזה גדל ככל שהצופה פונה שמאלה.
pitch מספר בטווח [-90, 90] שמייצג את הזווית האנכית של התצוגה במעלות, המשקף את המידה שבה המשתמש משנה את התצוגה כך שהיא תסתכל למעלה או למטה. המיקום הניטרלי, כלפי מרכז הסרטון בהקרנה המלבנית שלו, מייצג 0°, והערך הזה גדל ככל שהצופה מסתכל.
roll מספר בטווח [ -180, 180] שמייצג את זווית הסיבוב של התצוגה במעלות או בכיוון השעון. המיקום הניטרלי, שבו הציר האופקי בהיטל המלבני מקביל לציר האופקי של התצוגה, מייצג 0°. הערך גדל ככל שהתצוגה מסתובבת בכיוון השעון וקטן ככל שהתצוגה מסתובבת נגד כיוון השעון.

חשוב לשים לב שהנגן המוטמע לא מציג ממשק משתמש לכוונון סבב התצוגה. אפשר לשנות את היעד באחת מהדרכים הבאות:
  1. יש להשתמש בחיישן הכיוון בדפדפן בנייד כדי לספק רול לתצוגה. אם חיישן הכיוון מופעל, הפונקציה getSphericalProperties תמיד תחזיר 0 כערך של המאפיין roll.
  2. אם חיישן הכיוון מושבת, צריך להגדיר את הטלת הערך לערך שאינו אפס באמצעות ה-API הזה.
fov מספר בטווח [30, 120] שמייצג את שדה הראייה של התצוגה במעלות, כפי שנמדד לאורך הקצה הארוך יותר של אזור התצוגה. הקצה הקצר יותר מותאם אוטומטית ליחס הגובה-רוחב של התצוגה.

ערך ברירת המחדל הוא 100 מעלות. הקטנת הערך דומה להגדלה של תוכן הווידאו, והגדלת הערך דומה להקטנה של התצוגה. אפשר לשנות את הערך הזה באמצעות ה-API או באמצעות גלגל העכבר כשהסרטון במצב מסך מלא.
player.setSphericalProperties(properties:Object):Void
הגדרת הכיוון של הסרטון ב-360°. (אם הסרטון הנוכחי הוא לא כדורי, השיטה היא ללא אופציה ללא קשר לקלט).

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

בנוסף:
  • אם האובייקט מכיל מאפיינים לא ידועים או לא צפויים, הנגן מתעלם מהם.
  • כפי שצוין בתחילת הקטע הזה, חוויית ההפעלה של סרטונים ב-360° לא נתמכת בכל המכשירים הניידים.
  • כברירת מחדל, במכשירים ניידים נתמכים, הפונקציה הזו מגדירה רק את המאפיין fov ולא משפיעה על המאפיינים yaw, pitch ו-roll של הפעלת סרטונים ב-360°. פרטים נוספים זמינים במאפיין enableOrientationSensor שבהמשך.
האובייקט properties שמועבר לפונקציה מכיל את המאפיינים הבאים:
תכונות
yaw פרטים נוספים מופיעים בקטע הגדרה למעלה.
pitch פרטים נוספים מופיעים בקטע הגדרה למעלה.
roll פרטים נוספים מופיעים בקטע הגדרה למעלה.
fov פרטים נוספים מופיעים בקטע הגדרה למעלה.
enableOrientationSensor הערה: המאפיין הזה משפיע על חוויית צפייה ב-360° במכשירים נתמכים בלבד.ערך בוליאני שמציין אם הטמעת ה-IFrame צריכה להגיב לאירועים שמסמנים שינויים בכיוון של מכשיר נתמך, כמו DeviceOrientationEvent של דפדפן בנייד. ערך ברירת המחדל של הפרמטר הוא true.

מכשירים ניידים נתמכים
  • כשהערך הוא true, נגן מוטמע מסתמך רק על תנועת המכשיר כדי להתאים את המאפיינים yaw, pitch ו-roll להפעלת סרטונים ב-360°. עם זאת, עדיין אפשר לשנות את המאפיין fov דרך ה-API, ולמעשה ה-API הוא הדרך היחידה לשנות את המאפיין fov במכשיר נייד. זאת התנהגות ברירת המחדל.
  • כשהערך הוא false, תנועת המכשיר לא משפיעה על חוויית הצפייה ב-360°. צריך להגדיר את כל המאפיינים של yaw, pitch, roll ו-fov באמצעות ה-API.

מכשירים ניידים לא נתמכים
הערך של המאפיין enableOrientationSensor לא משפיע על חוויית ההפעלה.

הפעלת סרטון בפלייליסט

player.nextVideo():Void
הפונקציה הזו טוענת ומפעילה את הסרטון הבא בפלייליסט.
  • אם מתבצעת הפעלה של player.nextVideo() בזמן הצפייה בסרטון האחרון בפלייליסט, והפלייליסט מוגדר להפעלה רציפה (loop), הנגן ייטען ויופעל בסרטון הראשון ברשימה.

  • אם מתבצעת קריאה לפעולה player.nextVideo() בזמן הצפייה בסרטון האחרון בפלייליסט, והפלייליסט לא מוגדר להפעלה רציפה, ההפעלה תסתיים.

player.previousVideo():Void
הפונקציה הזו טוענת ומפעילים את הסרטון הקודם בפלייליסט.
  • אם מתבצעת הפעלה של player.previousVideo() בזמן הצפייה בסרטון הראשון בפלייליסט, והפלייליסט מוגדר להפעלה רציפה (loop), הנגן ייטען ויופעל בסרטון האחרון ברשימה.

  • אם מתבצעת הפעלה של player.previousVideo() בזמן הצפייה בסרטון הראשון בפלייליסט, והפלייליסט לא מוגדר להפעלה רציפה, הנגן יפעיל מחדש את סרטון הפלייליסט הראשון מההתחלה.

player.playVideoAt(index:Number):Void
הפונקציה הזו טוענת ומפעילים את הסרטון שצוין בפלייליסט.
  • פרמטר החובה index מציין את האינדקס של הסרטון שרוצים להפעיל בפלייליסט. הפרמטר משתמש באינדקס שמבוסס על אפס, ולכן הערך 0 מזהה את הסרטון הראשון ברשימה. אם סדרתם את הפלייליסט בצורה אקראית, הפונקציה הזו תפעיל את הסרטון במיקום שצוין בפלייליסט המושמע בסדר אקראי.

שינוי עוצמת הקול בנגן

player.mute():Void
השתקת השחקן.
player.unMute():Void
ביטול ההשתקה של השחקן.
player.isMuted():Boolean
מחזיר true אם הנגן מושתק, false אם לא.
player.setVolume(volume:Number):Void
הגדרת עוצמת הקול. אפשר להזין מספר שלם בין 0 ל-100.
player.getVolume():Number
מחזירה את עוצמת הקול הנוכחית של השחקן, מספר שלם בין 0 ל-100. לתשומת ליבכם: getVolume() יחזיר את עוצמת הקול גם אם הנגן מושתק.

הגדרת גודל הנגן

player.setSize(width:Number, height:Number):Object
מגדירים את הגודל בפיקסלים של <iframe> שמכיל את הנגן.

הגדרת קצב ההפעלה

player.getPlaybackRate():Number
הפונקציה הזו מאחזרת את קצב ההפעלה של הסרטון שמופעל באותו רגע. קצב ההפעלה שמוגדר כברירת מחדל הוא 1. ערך זה מציין שהסרטון מופעל במהירות רגילה. קצב ההפעלה עשוי לכלול ערכים כמו 0.25, 0.5, 1, 1.5 ו-2.
player.setPlaybackRate(suggestedRate:Number):Void
הפונקציה הזו קובעת את קצב ההפעלה המוצע לסרטון הנוכחי. אם קצב ההפעלה משתנה, הוא ישתנה רק לגבי הסרטון שכבר סומן או מופעל. אם מגדירים את קצב ההפעלה של סרטון שקיבל סימון, קצב ההפעלה ימשיך לחול כשתתבצע קריאה לפונקציה playVideo או כשהמשתמש יפעיל את הסרטון ישירות דרך לחצני הנגן. בנוסף, קריאה לפונקציות לסמן או לטעון סרטונים או פלייליסטים (cueVideoById, loadVideoById וכו') תאפס את קצב ההפעלה ל-1.

הפעלה של הפונקציה הזו לא מבטיחה שקצב ההפעלה ישתנה בפועל. עם זאת, אם קצב ההפעלה ישתנה, האירוע onPlaybackRateChange יופעל והקוד אמור להגיב לאירוע ולא לעובדה שהוא קרא לפונקציה setPlaybackRate.

השיטה getAvailablePlaybackRates תחזיר את קצבי ההפעלה האפשריים בסרטון שמופעל כרגע. עם זאת, אם תגדירו את הפרמטר suggestedRate לערך מסוג מספר שלם או מספר ממשי (float) שאינם נתמכים, הנגן יעגל את הערך למטה לערך הנתמך הקרוב ביותר לכיוון 1.
player.getAvailablePlaybackRates():Array
הפונקציה הזו מחזירה את סדרת קצבי ההפעלה שבהם הסרטון הנוכחי זמין. ערך ברירת המחדל הוא 1, שמציין שהסרטון מופעל במהירות רגילה.

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

הגדרת התנהגות ההפעלה של פלייליסטים

player.setLoop(loopPlaylists:Boolean):Void

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

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

פרמטר החובה loopPlaylists מזהה את התנהגות הלולאה.

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

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

player.setShuffle(shufflePlaylist:Boolean):Void

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

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

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

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

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

סטטוס הפעלה

player.getVideoLoadedFraction():Float
מחזיר מספר בין 0 ל-1 שמציין את האחוז מהסרטון שהנגן מציג במאגר נתונים זמני. השיטה הזו מחזירה מספר מהימן יותר מה-methods getVideoBytesLoaded ו-getVideoBytesTotal שהוצאו משימוש.
player.getPlayerState():Number
מחזירה את המצב של השחקן. הערכים האפשריים הם:
  • -1 – לא התחיל
  • 0 - הסתיים
  • 1 – פועל
  • 2 – מושהה
  • 3 – בתהליך אגירת נתונים
  • 5 – סימון סרטון
player.getCurrentTime():Number
מחזירה את הזמן שחלף בשניות מאז תחילת הפעלת הסרטון.
player.getVideoStartBytes():Number
תכונות שיוצאו משימוש ב-31 באוקטובר 2012. הפונקציה מחזירה את מספר הבייטים שממנו התחיל קובץ הסרטון להיטען. (השיטה הזו תמיד מחזירה את הערך 0). תרחיש לדוגמה: המשתמש מחפש קדימה לנקודה שעדיין לא נטענה, והנגן שולח בקשה חדשה להפעיל קטע מהסרטון שעדיין לא נטען.
player.getVideoBytesLoaded():Number
הוצא משימוש החל מ-18 ביולי 2012. במקום זאת, כדאי להשתמש בשיטה getVideoLoadedFraction כדי לקבוע את אחוז הסרטון שנשמר במאגר נתונים זמני.

השיטה הזו מחזירה ערך בין 0 ל-1000 שמייצג את כמות הסרטונים שנטען. כדי לחשב את החלק מתוך הסרטון שנטען, צריך לחלק את הערך של getVideoBytesLoaded בערך של getVideoBytesTotal.
player.getVideoBytesTotal():Number
הוצא משימוש החל מ-18 ביולי 2012. במקום זאת, כדאי להשתמש בשיטה getVideoLoadedFraction כדי לקבוע את אחוז הסרטון שנשמר במאגר נתונים זמני.

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

השיטה הזו תמיד מחזירה את הערך 1000. כדי לחשב את החלק מתוך הסרטון שנטען, צריך לחלק את הערך של getVideoBytesLoaded בערך של getVideoBytesTotal.

מתבצע אחזור של פרטי הסרטון

player.getDuration():Number
מחזירה את משך הזמן בשניות של הסרטון שפועל כרגע. הערה: הפונקציה getDuration() תחזיר את הערך 0 עד שהמטא-נתונים של הסרטון נטענים. מצב כזה בדרך כלל קורה מיד לאחר הפעלת הסרטון.

אם הסרטון שמופעל כרגע הוא אירוע בשידור חי, הפונקציה getDuration() תחזיר את הזמן שחלף מאז תחילת השידור החי. באופן ספציפי, זהו משך הזמן שהסרטון שודר ללא איפוס או הפרעה. בנוסף, משך הזמן הזה בדרך כלל ארוך יותר ממשך האירוע בפועל, כי השידור עשוי להתחיל לפני שעת ההתחלה של האירוע.
player.getVideoUrl():String
מחזירה את כתובת ה-URL של YouTube.com עבור הסרטון שנטען/מופעל כרגע.
player.getVideoEmbedCode():String
מחזירה את קוד ההטמעה של הסרטון שנטען/מופעל כרגע.

מתבצע אחזור של פרטי הפלייליסט

player.getPlaylist():Array
הפונקציה הזו מחזירה מערך של מזהי הסרטונים בפלייליסט לפי הסדר הנוכחי שלהם. כברירת מחדל, הפונקציה הזו תחזיר את מזהי הסרטונים לפי הסדר שנקבע על ידי הבעלים של הפלייליסט. עם זאת, אם נתתם לפונקציה setShuffle קריאה אקראית של סדר הפלייליסט, הערך המוחזר של הפונקציה getPlaylist() ישקף את הסדר השגוי.
player.getPlaylistIndex():Number
פונקציה זו מחזירה את האינדקס של סרטון הפלייליסט שמופעל עכשיו.
  • אם לא ערבתם את הפלייליסט, הערך המוחזר יזהה את המיקום שבו יוצר הפלייליסט הציב את הסרטון. הערך המוחזר משתמש באינדקס שמבוסס על אפס, כך שהערך של 0 מזהה את הסרטון הראשון בפלייליסט.

  • אם ערבתם את הפלייליסט, הערך המוחזר יזהה את סדר הסרטון בפלייליסט המושמע.

הוספה או הסרה של האזנה לאירועים

player.addEventListener(event:String, listener:String):Void
מוסיפה פונקציית האזנה ל-event שצוין. בקטע אירועים שבהמשך מפורטים האירועים השונים שהנגן עשוי להפעיל. ה-listener הוא מחרוזת שמציינת את הפונקציה שתופעל כשהאירוע שצוין יופעל.
player.removeEventListener(event:String, listener:String):Void
הסרה של פונקציית האזנה ל-event שצוין. listener היא מחרוזת שמזהה את הפונקציה שלא תפעל יותר כשהאירוע שצוין יופעל.

גישה לצומתי DOM ושינוי שלהם

player.getIframe():Object
השיטה הזו מחזירה את צומת ה-DOM של <iframe> המוטמע.
player.destroy():Void
מסיר את <iframe> שמכיל את הנגן.

אירועים

ה-API מפעיל אירועים כדי להודיע לאפליקציה על שינויים בנגן המוטמע. כמו שצוין בקטע הקודם, אפשר להירשם לאירועים על ידי הוספת האזנה לאירועים כשיוצרים את האובייקט YT.Player, ואפשר גם להשתמש בפונקציה addEventListener.

ה-API יעביר אובייקט אירוע כארגומנט היחיד לכל אחת מהפונקציות האלה. אובייקט האירוע כולל את המאפיינים (properties) הבאים:

  • המאפיין target של האירוע מזהה את נגן הווידאו שמתאים לאירוע.
  • המאפיין data של האירוע מציין ערך שרלוונטי לאירוע. לתשומת ליבכם: האירועים onReady ו-onAutoplayBlocked לא מציינים מאפיין data.

ברשימה הבאה מוגדרים האירועים שה-API מפעיל:

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

בדוגמה שלמטה מוצגת פונקציה לדוגמה לטיפול באירוע הזה. לאובייקט האירוע שה-API מעביר לפונקציה יש מאפיין target שמזהה את הנגן. הפונקציה מאחזרת את קוד ההטמעה של הסרטון הנוכחי שנטען, מתחילה להפעיל את הסרטון ומציגה את קוד ההטמעה ברכיב הדף שערך ה-id שלו הוא embed-code.
function onPlayerReady(event) {
  var embedCode = event.target.getVideoEmbedCode();
  event.target.playVideo();
  if (document.getElementById('embed-code')) {
    document.getElementById('embed-code').innerHTML = embedCode;
  }
}
onStateChange
האירוע הזה מופעל בכל פעם שמצב השחקן משתנה. המאפיין data של אובייקט האירוע שה-API מעביר לפונקציית האזנה לאירועים יציין מספר שלם שתואם למצב החדש בנגן. הערכים האפשריים הם:

  • -1 (לא התחילה)
  • 0 (הסתיים)
  • 1 (במצב פעיל)
  • 2 (מושהה)
  • 3 (בתהליך אגירת נתונים)
  • 5 (סימן סרטון).

כשהנגן יטען סרטון בפעם הראשונה, הוא ישדר אירוע unstarted (-1). לאחר סימון סרטון מסוים ומוכן להפעלה, הנגן ישדר אירוע מסוג video cued (5). בקוד שלכם, אתם יכולים לציין את ערכי המספרים השלמים או להשתמש באחד מהמשתנים הבאים עם מרחב השמות:

  • YT.PlayerState.ENDED
  • YT.PlayerState.PLAYING
  • YT.PlayerState.PAUSED
  • YT.PlayerState.BUFFERING
  • YT.PlayerState.CUED

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

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

  • small
  • medium
  • large
  • hd720
  • hd1080
  • highres

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

ערך המאפיין data של אובייקט האירוע שה-API מעביר לפונקציית האזנה לאירועים יהיה מספר שמזהה את קצב ההפעלה החדש. השיטה getAvailablePlaybackRates מחזירה רשימה של קצבי ההפעלה התקינים עבור הסרטון שסומן או מופעל כרגע.
onError
האירוע הזה מופעל אם מתרחשת שגיאה בנגן. ה-API יעביר אובייקט event אל הפונקציה event listener. המאפיין data של האובייקט הזה יציין מספר שלם שמזהה את סוג השגיאה שהתרחשה. הערכים האפשריים הם:

  • 2 – הבקשה מכילה ערך פרמטר לא חוקי. לדוגמה, השגיאה הזו מתקבלת אם מציינים מזהה סרטון שלא מכיל 11 תווים, או אם מזהה הסרטון מכיל תווים לא חוקיים, כמו סימני קריאה או כוכביות.
  • 5 – לא ניתן להפעיל את התוכן המבוקש בנגן HTML5 או שאירעה שגיאה אחרת שקשורה לנגן HTML5.
  • 100 – הסרטון המבוקש לא נמצא. שגיאה זו מתרחשת כאשר סרטון הוסר (מכל סיבה) או סומן כפרטי.
  • 101 – הבעלים של הסרטון המבוקש לא מאפשר להפעיל אותו בנגנים מוטמעים.
  • 150 – השגיאה הזו זהה לשגיאה 101. זו רק שגיאה מסוג 101.
onApiChange
האירוע הזה מופעל כדי לציין שהנגן טען (או הסיר) מודול עם methods של API חשוף. האפליקציה יכולה להאזין לאירוע הזה ולאחר מכן לדגום את הנגן כדי לקבוע אילו אפשרויות נחשפות למודול שנטען לאחרונה. לאחר מכן האפליקציה תוכל לאחזר או לעדכן את ההגדרות הקיימות עבור האפשרויות האלה.

הפקודה הבאה מאחזרת מערך של שמות מודולים שעבורם אפשר להגדיר אפשרויות נגן:
player.getOptions();
בשלב זה, המודול היחיד שאפשר להגדיר אפשרויות עבורו הוא המודול captions, שמטפל בכתוביות בנגן. אחרי קבלת אירוע onApiChange, האפליקציה יכולה להשתמש בפקודה הבאה כדי לקבוע אילו אפשרויות ניתן להגדיר במודול captions:
player.getOptions('captions');
דגימת הנגן באמצעות הפקודה הזו מאפשרת לוודא שהאפשרויות שאליהן רוצים לגשת אכן נגישות. באמצעות הפקודות הבאות אפשר לאחזר ולעדכן את אפשרויות המודול:
Retrieving an option:
player.getOption(module, option);

Setting an option
player.setOption(module, option, value);
בטבלה הבאה מפורטות האפשרויות שנתמכות ב-API:

מודול אפשרות תיאור
כתוביות fontSize האפשרות הזו מתאימה את גודל הגופן של הכתוביות שמוצגות בנגן.

הערכים החוקיים הם -1, 0, 1, 2 ו3. גודל ברירת המחדל הוא 0, והגודל הקטן ביותר הוא -1. אם מגדירים את האפשרות הזו כמספר שלם מתחת ל--1, יוצג הכיתוב הקטן ביותר. לעומת זאת, הגדרת האפשרות הזו למספר שלם מעל 3 תגרום להצגת הכיתוב הגדול ביותר.
כתוביות reload האפשרות הזו טוענת מחדש את נתוני הכתוביות עבור הסרטון שמופעל. אם מאחזרים את הערך של האפשרות, הערך יהיה null. כדי לטעון מחדש את נתוני הכתוביות, צריך להגדיר את הערך כ-true.
onAutoplayBlocked
האירוע הזה מופעל בכל פעם שהדפדפן חוסם תכונות של הפעלה אוטומטית או הפעלת סרטונים שכוללים סקריפטים, שנקראות ביחד 'הפעלה אוטומטית'. האיסור הזה כולל ניסיון הפעלה באמצעות אחד מממשקי ה-API הבאים של הנגן:

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

לפרטים מלאים, ניתן לעיין במדיניות ספציפית לדפדפן (Apple Safari / Webkit, Google Chrome, Mozilla Firefox) ובמדריך ההפעלה האוטומטית של Mozilla.

דוגמאות

יצירת YT.Player אובייקטים

  • דוגמה 1: שימוש ב-API עם רכיב <iframe> קיים

    בדוגמה הזו, רכיב <iframe> בדף כבר מגדיר את הנגן שאיתו ייעשה שימוש ב-API. חשוב לשים לב שכתובת ה-URL של הנגן src חייבת להגדיר את הפרמטר enablejsapi כ-1 או שהמאפיין enablejsapi של הרכיב <iframe> צריך להיות מוגדר כ-true.

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

    בדוגמה הזו נשתמש בקוד הבא:

    <iframe id="existing-iframe-example"
            width="640" height="360"
            src="https://www.youtube.com/embed/M7lc1UVf-VE?enablejsapi=1"
            frameborder="0"
            style="border: solid 4px #37474F"
    ></iframe>
    
    <script type="text/javascript">
      var tag = document.createElement('script');
      tag.id = 'iframe-demo';
      tag.src = 'https://www.youtube.com/iframe_api';
      var firstScriptTag = document.getElementsByTagName('script')[0];
      firstScriptTag.parentNode.insertBefore(tag, firstScriptTag);
    
      var player;
      function onYouTubeIframeAPIReady() {
        player = new YT.Player('existing-iframe-example', {
            events: {
              'onReady': onPlayerReady,
              'onStateChange': onPlayerStateChange
            }
        });
      }
      function onPlayerReady(event) {
        document.getElementById('existing-iframe-example').style.borderColor = '#FF6D00';
      }
      function changeBorderColor(playerStatus) {
        var color;
        if (playerStatus == -1) {
          color = "#37474F"; // unstarted = gray
        } else if (playerStatus == 0) {
          color = "#FFFF00"; // ended = yellow
        } else if (playerStatus == 1) {
          color = "#33691E"; // playing = green
        } else if (playerStatus == 2) {
          color = "#DD2C00"; // paused = red
        } else if (playerStatus == 3) {
          color = "#AA00FF"; // buffering = purple
        } else if (playerStatus == 5) {
          color = "#FF6DOO"; // video cued = orange
        }
        if (color) {
          document.getElementById('existing-iframe-example').style.borderColor = color;
        }
      }
      function onPlayerStateChange(event) {
        changeBorderColor(event.data);
      }
    </script>
    
  • דוגמה 2: הפעלה בקול

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

    function onYouTubeIframeAPIReady() {
      var player;
      player = new YT.Player('player', {
        width: 1280,
        height: 720,
        videoId: 'M7lc1UVf-VE',
        events: {
          'onReady': onPlayerReady,
          'onStateChange': onPlayerStateChange,
          'onError': onPlayerError
        }
      });
    }
    
    function onPlayerReady(event) {
      event.target.setVolume(100);
      event.target.playVideo();
    }
    
  • דוגמה 3: בדוגמה הזו, הפרמטרים של הנגן מפעילים את הסרטון באופן אוטומטי כשהוא נטען ומסתירים את הפקדים של נגן הווידאו. הוא גם מוסיף פונקציות event listener למספר אירועים שה-API משדר.

    function onYouTubeIframeAPIReady() {
      var player;
      player = new YT.Player('player', {
        videoId: 'M7lc1UVf-VE',
        playerVars: { 'autoplay': 1, 'controls': 0 },
        events: {
          'onReady': onPlayerReady,
          'onStateChange': onPlayerStateChange,
          'onError': onPlayerError
        }
      });
    }

שליטה בסרטונים ב-360°

בדוגמה הזו נשתמש בקוד הבא:

<style>
  .current-values {
    color: #666;
    font-size: 12px;
  }
</style>
<!-- The player is inserted in the following div element -->
<div id="spherical-video-player"></div>

<!-- Display spherical property values and enable user to update them. -->
<table style="border: 0; width: 640px;">
  <tr style="background: #fff;">
    <td>
      <label for="yaw-property">yaw: </label>
      <input type="text" id="yaw-property" style="width: 80px"><br>
      <div id="yaw-current-value" class="current-values"> </div>
    </td>
    <td>
      <label for="pitch-property">pitch: </label>
      <input type="text" id="pitch-property" style="width: 80px"><br>
      <div id="pitch-current-value" class="current-values"> </div>
    </td>
    <td>
      <label for="roll-property">roll: </label>
      <input type="text" id="roll-property" style="width: 80px"><br>
      <div id="roll-current-value" class="current-values"> </div>
    </td>
    <td>
      <label for="fov-property">fov: </label>
      <input type="text" id="fov-property" style="width: 80px"><br>
      <div id="fov-current-value" class="current-values"> </div>
    </td>
    <td style="vertical-align: bottom;">
      <button id="spherical-properties-button">Update properties</button>
    </td>
  </tr>
</table>

<script type="text/javascript">
  var tag = document.createElement('script');
  tag.id = 'iframe-demo';
  tag.src = 'https://www.youtube.com/iframe_api';
  var firstScriptTag = document.getElementsByTagName('script')[0];
  firstScriptTag.parentNode.insertBefore(tag, firstScriptTag);

  var PROPERTIES = ['yaw', 'pitch', 'roll', 'fov'];
  var updateButton = document.getElementById('spherical-properties-button');

  // Create the YouTube Player.
  var ytplayer;
  function onYouTubeIframeAPIReady() {
    ytplayer = new YT.Player('spherical-video-player', {
        height: '360',
        width: '640',
        videoId: 'FAtdv94yzp4',
    });
  }

  // Don't display current spherical settings because there aren't any.
  function hideCurrentSettings() {
    for (var p = 0; p < PROPERTIES.length; p++) {
      document.getElementById(PROPERTIES[p] + '-current-value').innerHTML = '';
    }
  }

  // Retrieve current spherical property values from the API and display them.
  function updateSetting() {
    if (!ytplayer || !ytplayer.getSphericalProperties) {
      hideCurrentSettings();
    } else {
      let newSettings = ytplayer.getSphericalProperties();
      if (Object.keys(newSettings).length === 0) {
        hideCurrentSettings();
      } else {
        for (var p = 0; p < PROPERTIES.length; p++) {
          if (newSettings.hasOwnProperty(PROPERTIES[p])) {
            currentValueNode = document.getElementById(PROPERTIES[p] +
                                                       '-current-value');
            currentValueNode.innerHTML = ('current: ' +
                newSettings[PROPERTIES[p]].toFixed(4));
          }
        }
      }
    }
    requestAnimationFrame(updateSetting);
  }
  updateSetting();

  // Call the API to update spherical property values.
  updateButton.onclick = function() {
    var sphericalProperties = {};
    for (var p = 0; p < PROPERTIES.length; p++) {
      var propertyInput = document.getElementById(PROPERTIES[p] + '-property');
      sphericalProperties[PROPERTIES[p]] = parseFloat(propertyInput.value);
    }
    ytplayer.setSphericalProperties(sphericalProperties);
  }
</script>

שילוב של Android WebView Media Integrity API

הרחבנו את Android WebView Media Integrity API כדי לאפשר הפעלה של נגני מדיה מוטמעים, כולל הטמעות של נגן YouTube באפליקציות ל-Android, כדי לאמת את האותנטיות של אפליקציית ההטמעה. לאחר השינוי, אפליקציות מוטמעות שולחות באופן אוטומטי מזהה אפליקציה מאומת ל-YouTube. הנתונים שנאספים באמצעות השימוש ב-API הזה הם המטא-נתונים של האפליקציה (שם החבילה, מספר הגרסה ואישור החתימה) ואסימון האימות של המכשיר שנוצר על ידי Google Play Services.

הנתונים משמשים לאימות התקינות של האפליקציה והמכשיר. הוא מוצפן, לא משותף עם צדדים שלישיים, ונמחק לאחר תקופת שמירה קבועה. מפתחי אפליקציות יכולים להגדיר את זהות האפליקציה שלהם ב-WebView Media Integrity API. ההגדרה תומכת באפשרות לביטול הסכמה.

היסטוריית גרסאות

June 24, 2024

The documentation has been updated to note that YouTube has extended the Android WebView Media Integrity API to enable embedded media players, including YouTube player embeds in Android applications, to verify the embedding app's authenticity. With this change, embedding apps automatically send an attested app ID to YouTube.

November 20, 2023

The new onAutoplayBlocked event API is now available. This event notifies your application if the browser blocks autoplay or scripted playback. Verification of autoplay success or failure is an established paradigm for HTMLMediaElements, and the onAutoplayBlocked event now provides similar functionality for the IFrame Player API.

April 27, 2021

The Getting Started and Loading a Video Player sections have been updated to include examples of using a playerVars object to customize the player.

October 13, 2020

Note: This is a deprecation announcement for the embedded player functionality that lets you configure the player to load search results. This announcement affects the IFrame Player API's queueing functions for lists, cuePlaylist and loadPlaylist.

This change will become effective on or after 15 November 2020. After that time, calls to the cuePlaylist or loadPlaylist functions that set the listType property to search will generate a 4xx response code, such as 404 (Not Found) or 410 (Gone). This change also affects the list property for those functions as that property no longer supports the ability to specify a search query.

As an alternative, you can use the YouTube Data API's search.list method to retrieve search results and then load selected videos in the player.

October 24, 2019

The documentation has been updated to reflect the fact that the API no longer supports functions for setting or retrieving playback quality. As explained in this YouTube Help Center article, to give you the best viewing experience, YouTube adjusts the quality of your video stream based on your viewing conditions.

The changes explained below have been in effect for more than one year. This update merely aligns the documentation with current functionality:

  • The getPlaybackQuality, setPlaybackQuality, and getAvailableQualityLevels functions are no longer supported. In particular, calls to setPlaybackQuality will be no-op functions, meaning they will not actually have any impact on the viewer's playback experience.
  • The queueing functions for videos and playlists -- cueVideoById, loadVideoById, etc. -- no longer support the suggestedQuality argument. Similarly, if you call those functions using object syntax, the suggestedQuality field is no longer supported. If suggestedQuality is specified, it will be ignored when the request is handled. It will not generate any warnings or errors.
  • The onPlaybackQualityChange event is still supported and might signal a change in the viewer's playback environment. See the Help Center article referenced above for more information about factors that affect playback conditions or that might cause the event to fire.

May 16, 2018

The API now supports features that allow users (or embedders) to control the viewing perspective for 360° videos:

  • The getSphericalProperties function retrieves the current orientation for the video playback. The orientation includes the following data:
    • yaw - represents the horizontal angle of the view in degrees, which reflects the extent to which the user turns the view to face further left or right
    • pitch - represents the vertical angle of the view in degrees, which reflects the extent to which the user adjusts the view to look up or down
    • roll - represents the rotational angle (clockwise or counterclockwise) of the view in degrees.
    • fov - represents the field-of-view of the view in degrees, which reflects the extent to which the user zooms in or out on the video.
  • The setSphericalProperties function modifies the view to match the submitted property values. In addition to the orientation values described above, this function supports a Boolean field that indicates whether the IFrame embed should respond to DeviceOrientationEvents on supported mobile devices.

This example demonstrates and lets you test these new features.

June 19, 2017

This update contains the following changes:

  • Documentation for the YouTube Flash Player API and YouTube JavaScript Player API has been removed and redirected to this document. The deprecation announcement for the Flash and JavaScript players was made on January 27, 2015. If you haven't done so already, please migrate your applications to use IFrame embeds and the IFrame Player API.

August 11, 2016

This update contains the following changes:

  • The newly published YouTube API Services Terms of Service ("the Updated Terms"), discussed in detail on the YouTube Engineering and Developers Blog, provides a rich set of updates to the current Terms of Service. In addition to the Updated Terms, which will go into effect as of February 10, 2017, this update includes several supporting documents to help explain the policies that developers must follow.

    The full set of new documents is described in the revision history for the Updated Terms. In addition, future changes to the Updated Terms or to those supporting documents will also be explained in that revision history. You can subscribe to an RSS feed listing changes in that revision history from a link in that document.

June 29, 2016

This update contains the following changes:

  • The documentation has been corrected to note that the onApiChange method provides access to the captions module and not the cc module.

June 24, 2016

The Examples section has been updated to include an example that demonstrates how to use the API with an existing <iframe> element.

January 6, 2016

The clearVideo function has been deprecated and removed from the documentation. The function no longer has any effect in the YouTube player.

December 18, 2015

European Union (EU) laws require that certain disclosures must be given to and consents obtained from end users in the EU. Therefore, for end users in the European Union, you must comply with the EU User Consent Policy. We have added a notice of this requirement in our YouTube API Terms of Service.

April 28, 2014

This update contains the following changes:

March 25, 2014

This update contains the following changes:

  • The Requirements section has been updated to note that embedded players must have a viewport that is at least 200px by 200px. If a player displays controls, it must be large enough to fully display the controls without shrinking the viewport below the minimum size. We recommend 16:9 players be at least 480 pixels wide and 270 pixels tall.

July 23, 2013

This update contains the following changes:

  • The Overview now includes a video of a 2011 Google I/O presentation that discusses the iframe player.

October 31, 2012

This update contains the following changes:

  • The Queueing functions section has been updated to explain that you can use either argument syntax or object syntax to call all of those functions. Note that the API may support additional functionality in object syntax that the argument syntax does not support.

    In addition, the descriptions and examples for each of the video queueing functions have been updated to reflect the newly added support for object syntax. (The API's playlist queueing functions already supported object syntax.)

  • When called using object syntax, each of the video queueing functions supports an endSeconds property, which accepts a float/integer and specifies the time when the video should stop playing when playVideo() is called.

  • The getVideoStartBytes method has been deprecated. The method now always returns a value of 0.

August 22, 2012

This update contains the following changes:

  • The example in the Loading a video player section that demonstrates how to manually create the <iframe> tag has been updated to include a closing </iframe> tag since the onYouTubeIframeAPIReady function is only called if the closing </iframe> element is present.

August 6, 2012

This update contains the following changes:

  • The Operations section has been expanded to list all of the supported API functions rather than linking to the JavaScript Player API Reference for that list.

  • The API supports several new functions and one new event that can be used to control the video playback speed:

    • Functions

      • getAvailablePlaybackRates – Retrieve the supported playback rates for the cued or playing video. Note that variable playback rates are currently only supported in the HTML5 player.
      • getPlaybackRate – Retrieve the playback rate for the cued or playing video.
      • setPlaybackRate – Set the playback rate for the cued or playing video.

    • Events

July 19, 2012

This update contains the following changes:

  • The new getVideoLoadedFraction method replaces the now-deprecated getVideoBytesLoaded and getVideoBytesTotal methods. The new method returns the percentage of the video that the player shows as buffered.

  • The onError event may now return an error code of 5, which indicates that the requested content cannot be played in an HTML5 player or another error related to the HTML5 player has occurred.

  • The Requirements section has been updated to indicate that any web page using the IFrame API must also implement the onYouTubeIframeAPIReady function. Previously, the section indicated that the required function was named onYouTubePlayerAPIReady. Code samples throughout the document have also been updated to use the new name.

    Note: To ensure that this change does not break existing implementations, both names will work. If, for some reason, your page has an onYouTubeIframeAPIReady function and an onYouTubePlayerAPIReady function, both functions will be called, and the onYouTubeIframeAPIReady function will be called first.

  • The code sample in the Getting started section has been updated to reflect that the URL for the IFrame Player API code has changed to http://www.youtube.com/iframe_api. To ensure that this change does not affect existing implementations, the old URL (http://www.youtube.com/player_api) will continue to work.

July 16, 2012

This update contains the following changes:

  • The Operations section now explains that the API supports the setSize() and destroy() methods. The setSize() method sets the size in pixels of the <iframe> that contains the player and the destroy() method removes the <iframe>.

June 6, 2012

This update contains the following changes:

  • We have removed the experimental status from the IFrame Player API.

  • The Loading a video player section has been updated to point out that when inserting the <iframe> element that will contain the YouTube player, the IFrame API replaces the element specified in the constructor for the YouTube player. This documentation change does not reflect a change in the API and is intended solely to clarify existing behavior.

    In addition, that section now notes that the insertion of the <iframe> element could affect the layout of your page if the element being replaced has a different display style than the inserted <iframe> element. By default, an <iframe> displays as an inline-block element.

March 30, 2012

This update contains the following changes:

  • The Operations section has been updated to explain that the IFrame API supports a new method, getIframe(), which returns the DOM node for the IFrame embed.

March 26, 2012

This update contains the following changes:

  • The Requirements section has been updated to note the minimum player size.