דף זה תורגם על ידי Cloud Translation API.

YouTube Player API Reference for iframe Embeds

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

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

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

דרישות

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

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

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

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

תחילת העבודה

דף ה-HTML לדוגמה הבא יוצר נגן מוטמע שיטען סרטון, יפעיל אותו למשך שש שניות ולאחר מכן יעצור את ההפעלה. ההערות הממוספרות ב-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>

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

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

לחלופין, אפשר גם למקם את האלמנט <iframe> ישירות בדף. בקטע טעינת נגן וידאו מוסבר איך עושים זאת.
הקוד בקטע הזה טוען את קוד ה-JavaScript של IFrame Player API. הדוגמה משתמשת בשינוי DOM כדי להוריד את קוד ה-API ולוודא שהקוד אוחזר באופן אסינכרוני. (המאפיין async של התג <script>, שמאפשר גם הורדות אסינכרוניות, לא נתמך עדיין בכל הדפדפנים המודרניים, כפי שמתואר בתשובה הזו על ידי Stack Overflow.
הפונקציה onYouTubeIframeAPIReady תופעל מיד לאחר ההורדה של קוד ה-API של הנגן. בחלק הזה של הקוד מוגדר משתנה גלובלי, player, שקשור לנגן הווידאו שאתם מטמיעים, והפונקציה יוצרת את האובייקט של נגן הווידאו.
הפונקציה onPlayerReady תפעל כשהאירוע onReady יופעל. בדוגמה הזו, הפונקציה מציינת שכאשר נגן הווידאו מוכן, הוא צריך להתחיל לפעול.
ה-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
    }
  });
}

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

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

ממשק IFrame API יחליף את הרכיב שצוין ברכיב <iframe> שמכיל את הנגן. מצב זה עשוי להשפיע על פריסת הדף אם לרכיב המוחלף יש סגנון תצוגה שונה מהסגנון של רכיב <iframe> שנוסף. כברירת מחדל, <iframe> מוצג כרכיב inline-block.
הפרמטר השני הוא אובייקט שמציין את אפשרויות הנגן. האובייקט מכיל את המאפיינים הבאים:
- width (מספר) – הרוחב של נגן הווידאו. ערך ברירת המחדל הוא 640.
- height (מספר) – הגובה של נגן הווידאו. ערך ברירת המחדל הוא 390.
- videoId (מחרוזת) – מזהה הווידאו ב-YouTube שמזהה את הסרטון שהנגן יטען.
- playerVars (אובייקט) – מאפייני האובייקט מזהים פרמטרים של הנגן שניתן להשתמש בהם כדי להתאים אישית את הנגן.
- events (אובייקט) – מאפייני האובייקט מזהים את האירועים שה-API מפעיל ואת הפונקציות (פונקציות event listener) שה-API יקרא כשהאירועים האלה יקרו. בדוגמה, הבונה מציין שהפונקציה 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. כאמצעי אבטחה נוסף, צריך לכלול גם את הפרמטר origin בכתובת ה-URL, ולציין את סכימת כתובת ה-URL (http:// או https://) ואת הדומיין המלא של הדף המארח כערך הפרמטר. origin הוא אופציונלי, אבל הוא מספק הגנה מפני JavaScript זדוני של צד שלישי שהוחדר לדף שלך והשתלטות על נגן YouTube שלך.

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

פעולות

כדי לקרוא לשיטות ה-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 האופציונלי מקבל מספר צף/מספר שלם ומציין את הזמן שבו הסרטון צריך להתחיל לפעול כאשר מופעלת קריאה ל-playVideo(). אם מזינים ערך של startSeconds ואז מפעילים את seekTo(), הנגן יופעל מהתקופה שצוינה בקריאה ל-seekTo(). לאחר רישום הסרטון ומוכן להפעלה, הנגן ישודר אירוע video cued (5).
הפרמטר endSeconds האופציונלי, שנתמך רק בתחביר אובייקטים, מקבל מספר צף/מספר שלם ומציין את הזמן שבו סרטון הווידאו אמור להפסיק לפעול לאחר קריאה ל-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 מקבל מספר שלם/צף. אם מציינים אפשרות כזו, הסרטון יתחיל מפריים המפתח הקרוב ביותר לזמן שצוין.
הפרמטר האופציונלי endSeconds מקבל מספר שלם/צף. אם צוין אחרת, הסרטון יפסיק לפעול בזמן שצוין.

cueVideoByUrl

תחביר הארגומנט

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

תחביר של אובייקטים

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

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

פונקציות לכתיבת רשימות

הפונקציות 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 האופציונלי מקבל מספר צף/מספר שלם ומציין את הזמן שבו הסרטון הראשון בפלייליסט צריך להתחיל לפעול כאשר מופעלת הפונקציה 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 מקבל מספר צף/מספר שלם ומציין את הזמן שבו סרטון הווידאו הראשון ברשימה יתחיל לפעול כאשר תופעל הפונקציה 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 האופציונלי מקבל מספר צף/מספר שלם ומציין את הזמן שבו הסרטון הראשון בפלייליסט צריך להתחיל לפעול.
תחביר של אובייקטים
```
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 מקבל מספר צף/מספר שלם ומציין את הזמן שבו הסרטון הראשון ברשימה צריך להתחיל לפעול.

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

הפעלת סרטון

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. הערך גדל ככל שהתצוגה מסתובבת בכיוון השעון והוא קטן ככל שהתצוגה מסתובבת נגד כיוון השעון. חשוב לדעת שהנגן המוטמע לא מציג ממשק משתמש לשינוי הסיבוב של התצוגה. ניתן להתאים את הסכום בכל אחת מהדרכים הבלעדיות הבאות: יש להשתמש בחיישן הכיוון בדפדפן לנייד כדי לבצע היפוך של התצוגה. אם חיישן הכיוון מופעל, הפונקציה `getSphericalProperties` תמיד מחזירה את `0` כערך של המאפיין `roll`. אם חיישן הכיוון מושבת, צריך להגדיר את הרוגלה לערך שאינו אפס באמצעות ה-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 לערך של מספר שלם או מספר ממשי שאינו נתמך, הנגן יעוגל כלפי מטה לערך הנתמך הקרוב ביותר בכיוון 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 שמציין את האחוז מהסרטון שהנגן מציג כמאוחסן במאגר נתונים זמני. השיטה הזו מחזירה מספר מהימן יותר מהשיטות 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: מחזיר את כתובת האתר YouTube.com של הסרטון שנטען/פועל כרגע.

player.getVideoEmbedCode():String: מחזיר את קוד ההטמעה של הסרטון שנטען/מופעל עכשיו.

המערכת מאחזרת את פרטי הפלייליסט

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

player.getPlaylistIndex():Number

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

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

הוספה או הסרה של event listener

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

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

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

player.getIframe():Object: השיטה הזו מחזירה את צומת ה-DOM עבור <iframe> המוטמע.

player.destroy():Void: הסרת <iframe> שמכיל את השחקן.

אירועים

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

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

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 מעביר אל פונקציית event listener יציין מספר שלם שתואם למצב הנגן החדש. הערכים האפשריים הם:

-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 מעביר לפונקציית event listener יהיה מחרוזת שמזהה את איכות ההפעלה החדשה. הערכים האפשריים הם:

small
medium
large
hd720
hd1080
highres

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

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

onError

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

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

onApiChange

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

פרמטר אחד (autoplay)
פונקציית loadPlaylist
פונקציית loadVideoById
פונקציית loadVideoByUrl
פונקציית playVideo

לרוב הדפדפנים יש כללי מדיניות שיכולים לחסום את ההפעלה האוטומטית במחשבים, בניידים ובסביבות אחרות אם מתקיימים תנאים מסוימים. מקרים שבהם המדיניות הזו תופעל כוללים הפעלה שלא מושתקת ללא אינטראקציה של המשתמש, או כאשר לא הוגדרה מדיניות הרשאות שמאפשרת הפעלה אוטומטית ב-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 פיקסלים. לאחר מכן, הפונקציה event listener של האירוע 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>

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

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:

The new removeEventListener function lets you remove a listener for a specified event.

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
  - onPlaybackRateChange – This event fires when the video's playback rate changes.

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.

YouTube Player API Reference for iframe Embeds

דרישות

תחילת העבודה

טעינת נגן וידאו

פעולות

פונקציות

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

פונקציות להוספת סרטונים לתור

פונקציות לכתיבת רשימות

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

הפעלת סרטון

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

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

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

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

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

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

סטטוס הפעלה

המערכת מאחזרת את פרטי הסרטון

המערכת מאחזרת את פרטי הפלייליסט

הוספה או הסרה של event listener

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

אירועים

דוגמאות

המערכת יוצרת YT.Player אובייקטים

שליטה בסרטונים ב-360 מעלות

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

November 20, 2023

April 27, 2021

October 13, 2020

October 24, 2019

May 16, 2018

June 19, 2017

August 11, 2016

June 29, 2016

June 24, 2016

January 6, 2016

December 18, 2015

April 28, 2014

March 25, 2014

July 23, 2013

October 31, 2012

August 22, 2012

August 6, 2012

July 19, 2012

July 16, 2012

June 6, 2012

March 30, 2012

March 26, 2012

המערכת יוצרת `YT.Player` אובייקטים