דף זה תורגם על ידי 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.

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

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

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

איך מתחילים

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

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

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

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

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

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

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

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

התג <div> בקטע הזה מזהה את המיקום בדף שבו ממשק ה-API של IFrame ימקם את נגן הווידאו. ה-constructor של אובייקט הנגן, שמתואר בקטע טעינת נגן וידאו, מזהה את התג <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
    }
  });
}

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

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

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

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

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

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

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

פעולות

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

פונקציות

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

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

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

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

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

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

loadVideoById("bHQqvYy5KYo", 5, "large")

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

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

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

cueVideoById

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

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

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

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

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

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

loadVideoById

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

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

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

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

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

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

cueVideoByUrl

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

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

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

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

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

loadVideoByUrl

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

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

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

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

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

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

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

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

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

cuePlaylist

תחביר של ארגומנטים
```
player.cuePlaylist(playlist:String|Array,
                   index:Number,
                   startSeconds:Number):Void
```
מוסיפים את הפלייליסט שצוין לרשימת 'הבאים בתור'. כשמסמנים את הפלייליסט ומוכן להפעלה, הנגן ישדר אירוע אחד (video cued) (5).
- הפרמטר playlist הנדרש מציין מערך של מזהי סרטונים ב-YouTube. ב-YouTube Data API, הנכס id של המשאב video מזהה את מזהה הסרטון הזה.
- הפרמטר האופציונלי index מציין את האינדקס של הסרטון הראשון בפלייליסט שיופעל. הפרמטר משתמש באינדקס שמבוסס על אפס, וערך הפרמטר שמוגדר כברירת מחדל הוא 0, כך שפעולת ברירת המחדל היא טעינה והפעלה של הסרטון הראשון בפלייליסט.
- הפרמטר האופציונלי startSeconds מקבל ערך של מספר ממשי (float)/שלם ומציין את השעה שבה מתחיל הסרטון הראשון בפלייליסט, כאשר מופעלת הפונקציה playVideo(). אם מציינים ערך של startSeconds ואז קוראים ל-seekTo(), הנגן יתחיל לפעול מהשעה שצוינה בקריאה seekTo(). אם מסמנים פלייליסט ואז מפעילים את הפונקציה playVideoAt(), הנגן יתחיל לפעול בתחילת הסרטון שצוין.
תחביר אובייקטים
```
player.cuePlaylist({listType:String,
                    list:String,
                    index:Number,
                    startSeconds:Number}):Void
```
הוספת רשימת הסרטונים שצוינה לתור אחר. הרשימה יכולה להיות פלייליסט או פיד סרטונים שהועלו על ידי משתמש. החל מ-15 בנובמבר 2020 לא תהיה אפשרות להוסיף לרשימה של תוצאות חיפוש הוצאה משימוש.
לאחר סימון הרשימה והיא מוכנה להפעלה, השחקן ישדר אירוע אחד (video cued) (5).
- המאפיין האופציונלי listType מציין את סוג פיד התוצאות שאתם מאחזרים. הערכים החוקיים הם playlist ו-user_uploads. החל מ-15 בנובמבר 2020 לא תהיה יותר תמיכה בערך שהוצא משימוש, search. ערך ברירת המחדל הוא playlist.
- מאפיין החובה list מכיל מפתח שמזהה את רשימת הסרטונים הספציפית שמערכת YouTube אמורה להחזיר.
  - אם ערך המאפיין listType הוא playlist, המאפיין list מציין את מזהה הפלייליסט או מערך של מזהי סרטונים. ב-YouTube Data API, המאפיין id של המשאב playlist מזהה את מזהה הפלייליסט, והמאפיין id של המשאב video מציין מזהה סרטון.
  - אם ערך המאפיין listType הוא user_uploads, הנכס list מזהה את המשתמש שהסרטונים שהועלו שלו יוחזרו.
  - אם הערך של המאפיין listType הוא search, המאפיין list מציין את שאילתת החיפוש. הערה: ב-15 בנובמבר 2020 הפונקציונליות הזו הוצאה משימוש והתמיכה בה תיפסק.
- המאפיין האופציונלי index מציין את האינדקס של הסרטון הראשון ברשימה שיופעל. הפרמטר משתמש באינדקס שמבוסס על אפס, וערך הפרמטר שמוגדר כברירת מחדל הוא 0, כך שפעולת ברירת המחדל היא טעינה והפעלה של הסרטון הראשון ברשימה.
- המאפיין האופציונלי startSeconds מקבל ערך של מספר ממשי (float)/שלם ומציין את השעה שבה מתחיל הסרטון הראשון ברשימה, כשמופעלת הפונקציה playVideo(). אם מציינים ערך של startSeconds ואז קוראים ל-seekTo(), הנגן יתחיל לפעול מהשעה שצוינה בקריאה seekTo(). אם מסמנים רשימה ולאחר מכן קוראים לפונקציה playVideoAt(), הנגן יתחיל לפעול בתחילת הסרטון שצוין.

loadPlaylist

תחביר של ארגומנטים
```
player.loadPlaylist(playlist:String|Array,
                    index:Number,
                    startSeconds:Number):Void
```
הפונקציה הזו טוענת את הפלייליסט שצוין ומפעילה אותו.
- הפרמטר playlist הנדרש מציין מערך של מזהי סרטונים ב-YouTube. ב-YouTube Data API, המאפיין id של המשאב video מציין מזהה סרטון.
- הפרמטר האופציונלי index מציין את האינדקס של הסרטון הראשון בפלייליסט שיופעל. הפרמטר משתמש באינדקס שמבוסס על אפס, וערך הפרמטר שמוגדר כברירת מחדל הוא 0, כך שפעולת ברירת המחדל היא טעינה והפעלה של הסרטון הראשון בפלייליסט.
- הפרמטר האופציונלי startSeconds מקבל ערך של מספר ממשי (float)/שלם ומציין את השעה שבה יתחיל הסרטון הראשון בפלייליסט.
תחביר אובייקטים
```
player.loadPlaylist({list:String,
                     listType:String,
                     index:Number,
                     startSeconds:Number}):Void
```
הפונקציה הזו טוענת את הרשימה שצוינה ומפעילה אותה. הרשימה יכולה להיות פלייליסט או פיד סרטונים שהועלו על ידי משתמש. האפשרות לטעון רשימה של תוצאות חיפוש הוצאה משימוש ולא תהיה יותר תמיכה החל מ-15 בנובמבר 2020.
- המאפיין האופציונלי listType מציין את סוג פיד התוצאות שאתם מאחזרים. הערכים החוקיים הם playlist ו-user_uploads. החל מ-15 בנובמבר 2020 לא תהיה יותר תמיכה בערך שהוצא משימוש, search. ערך ברירת המחדל הוא playlist.
- מאפיין החובה list מכיל מפתח שמזהה את רשימת הסרטונים הספציפית שמערכת YouTube אמורה להחזיר.
  - אם ערך המאפיין listType הוא playlist, המאפיין list מציין מזהה פלייליסט או מערך של מזהי סרטונים. ב-YouTube Data API, המאפיין id של המשאב playlist מציין מזהה של פלייליסט, והמאפיין id של המשאב video מציין מזהה סרטון.
  - אם ערך המאפיין listType הוא user_uploads, הנכס list מזהה את המשתמש שהסרטונים שהועלו שלו יוחזרו.
  - אם הערך של המאפיין listType הוא search, המאפיין list מציין את שאילתת החיפוש. הערה: ב-15 בנובמבר 2020 הפונקציונליות הזו הוצאה משימוש והתמיכה בה תיפסק.
- המאפיין האופציונלי index מציין את האינדקס של הסרטון הראשון ברשימה שיופעל. הפרמטר משתמש באינדקס שמבוסס על אפס, וערך הפרמטר שמוגדר כברירת מחדל הוא 0, כך שפעולת ברירת המחדל היא טעינה והפעלה של הסרטון הראשון ברשימה.
- המאפיין האופציונלי startSeconds מקבל ערך של מספר ממשי (float)/שלם ומציין את השעה שבה יתחיל הסרטון הראשון ברשימה לפעול.

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

הפעלת סרטון

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

הערה: הפעלה נספרת רק אם היא מופעלת באמצעות לחצן הפעלה מקורי בנגן.

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

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

חשוב: בשונה מהפונקציה pauseVideo, שמשאירה את הנגן במצב paused (2), הפונקציה stopVideo יכולה להעביר את הנגן לכל מצב של אי-הפעלה, כולל ended (0), paused (2), video cued (5) או unstarted (-1).

player.seekTo(seconds:Number, allowSeekAhead:Boolean):Void

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

הפרמטר seconds מזהה את השעה שבה השחקן צריך להתקדם.

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

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

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

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

player.getSphericalProperties():Object

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

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

האובייקט מכיל את המאפיינים הבאים:

תכונות
`yaw`	מספר בטווח [0, 360) שמייצג את הזווית האופקית של התצוגה במעלות, המשקף את המידה שבה המשתמש מסובב את התצוגה לפניה שמאלה או ימינה. המיקום הניטרלי, כלפי מרכז הסרטון בהקרנה המלבנית שלו, מייצג 0°, והערך הזה גדל ככל שהצופה פונה שמאלה.
`pitch`	מספר בטווח [-90, 90] שמייצג את הזווית האנכית של התצוגה במעלות, המשקף את המידה שבה המשתמש משנה את התצוגה כך שהיא תסתכל למעלה או למטה. המיקום הניטרלי, כלפי מרכז הסרטון בהקרנה המלבנית שלו, מייצג 0°, והערך הזה גדל ככל שהצופה מסתכל.
`roll`	מספר בטווח [ -180, 180] שמייצג את זווית הסיבוב של התצוגה במעלות או בכיוון השעון. המיקום הניטרלי, שבו הציר האופקי בהיטל המלבני מקביל לציר האופקי של התצוגה, מייצג 0°. הערך גדל ככל שהתצוגה מסתובבת בכיוון השעון וקטן ככל שהתצוגה מסתובבת נגד כיוון השעון. חשוב לשים לב שהנגן המוטמע לא מציג ממשק משתמש לכוונון סבב התצוגה. אפשר לשנות את היעד באחת מהדרכים הבאות: יש להשתמש בחיישן הכיוון בדפדפן בנייד כדי לספק רול לתצוגה. אם חיישן הכיוון מופעל, הפונקציה `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 לערך מסוג מספר שלם או מספר ממשי (float) שאינם נתמכים, הנגן יעגל את הערך למטה לערך הנתמך הקרוב ביותר לכיוון 1.

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

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

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

player.setLoop(loopPlaylists:Boolean):Void

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

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

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

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

player.setShuffle(shufflePlaylist:Boolean):Void

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

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

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

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

סטטוס הפעלה

player.getVideoLoadedFraction():Float: מחזיר מספר בין 0 ל-1 שמציין את האחוז מהסרטון שהנגן מציג במאגר נתונים זמני. השיטה הזו מחזירה מספר מהימן יותר מה-methods getVideoBytesLoaded ו-getVideoBytesTotal שהוצאו משימוש.

player.getPlayerState():Number

מחזירה את המצב של השחקן. הערכים האפשריים הם:

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

player.getCurrentTime():Number: מחזירה את הזמן שחלף בשניות מאז תחילת הפעלת הסרטון.

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

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

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

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

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

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

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

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

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

player.getVideoUrl():String: מחזירה את כתובת ה-URL של YouTube.com עבור הסרטון שנטען/מופעל כרגע.

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

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

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

player.getPlaylistIndex():Number

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

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

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

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

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

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

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

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

אירועים

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

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

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

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

onReady

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

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

function onPlayerReady(event) {
  var embedCode = event.target.getVideoEmbedCode();
  event.target.playVideo();
  if (document.getElementById('embed-code')) {
    document.getElementById('embed-code').innerHTML = embedCode;
  }
}

onStateChange

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

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

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

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

onPlaybackQualityChange

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

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

small
medium
large
hd720
hd1080
highres

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

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

onError

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

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

onApiChange

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

הפקודה הבאה מאחזרת מערך של שמות מודולים שעבורם אפשר להגדיר אפשרויות נגן:

player.getOptions();

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

player.getOptions('captions');

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

Retrieving an option:
player.getOption(module, option);

Setting an option
player.setOption(module, option, value);

בטבלה הבאה מפורטות האפשרויות שנתמכות ב-API:

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

onAutoplayBlocked

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

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

function onYouTubeIframeAPIReady() {
  var player;
  player = new YT.Player('player', {
    width: 1280,
    height: 720,
    videoId: 'M7lc1UVf-VE',
    events: {
      'onReady': onPlayerReady,
      'onStateChange': onPlayerStateChange,
      'onError': onPlayerError
    }
  });
}

function onPlayerReady(event) {
  event.target.setVolume(100);
  event.target.playVideo();
}

דוגמה 3: בדוגמה הזו, הפרמטרים של הנגן מפעילים את הסרטון באופן אוטומטי כשהוא נטען ומסתירים את הפקדים של נגן הווידאו. הוא גם מוסיף פונקציות event listener למספר אירועים שה-API משדר.
```
function onYouTubeIframeAPIReady() {
  var player;
  player = new YT.Player('player', {
    videoId: 'M7lc1UVf-VE',
    playerVars: { 'autoplay': 1, 'controls': 0 },
    events: {
      'onReady': onPlayerReady,
      'onStateChange': onPlayerStateChange,
      'onError': onPlayerError
    }
  });
}
```

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

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

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

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

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

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

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

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

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

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

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

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

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

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

June 24, 2024

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

November 20, 2023

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

April 27, 2021

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

October 13, 2020

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

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

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

October 24, 2019

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

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

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

May 16, 2018

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

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

This example demonstrates and lets you test these new features.

June 19, 2017

This update contains the following changes:

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

August 11, 2016

This update contains the following changes:

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

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

June 29, 2016

This update contains the following changes:

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

June 24, 2016

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

January 6, 2016

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

December 18, 2015

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

April 28, 2014

This update contains the following changes:

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°

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

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

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

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

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

סטטוס הפעלה

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

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

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

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

אירועים

דוגמאות

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

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

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

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

June 24, 2024

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