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

YouTube Player API Reference for iframe Embeds

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

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

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

דרישות

הדפדפן של המשתמש חייב לתמוך בתכונת ה-HTML5 postMessage. רוב הדפדפנים המודרניים תומכים ב-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
    }
  });
}

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

הפרמטר הראשון מציין את רכיב ה-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 בכתובת האתר, ולציין את סכימת כתובת האתר (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 מקבל מספר ממשי (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

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

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

ה-target של האירוע מזהה את נגן הווידאו המתאים לאירוע.
ה-data של האירוע מציין ערך הרלוונטי לאירוע. לתשומת לבך, באירוע onReady לא מצוין מאפיין 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 לפונקציית האזנה לאירוע. המאפיין 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:

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

שיקולים לגבי ניידים

הפעלה אוטומטית והפעלה באמצעות סקריפטים

רכיב ה-HTML5 <video> בדפדפנים מסוימים לנייד (כמו Chrome ו-Safari) מאפשר הפעלה רק אם הוא נוצר על ידי אינטראקציה של משתמש (כמו הקשה על הנגן). הנה קטע ממסמכי התיעוד של Apple:

"אזהרה: כדי למנוע הורדות לא רצויות ברשת הסלולרית על חשבונו של המשתמש, לא ניתן להפעיל באופן אוטומטי מדיה מוטמעת ב-Safari ב-iOS — המשתמש תמיד יוזם הפעלה".

בשל ההגבלה הזו, פונקציות ופרמטרים כמו autoplay, playVideo(), loadVideoById() לא יפעלו בכל הסביבות לנייד.

דוגמאות

יצירת `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: הפעלה רועשת

הדוגמה הזו יוצרת נגן וידאו בגודל 1280x720 פיקסלים. מאזין האירוע של 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>

היסטוריית מהדורות

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°

היסטוריית מהדורות

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` אובייקטים