YouTube Player API Reference for iframe Embeds

IFrame player API به شما امکان می دهد یک پخش کننده ویدیوی YouTube را در وب سایت خود جاسازی کنید و پخش کننده را با استفاده از جاوا اسکریپت کنترل کنید.

با استفاده از توابع جاوا اسکریپت API، می توانید ویدیوها را برای پخش در صف قرار دهید. پخش، مکث یا توقف آن ویدیوها؛ تنظیم صدای پخش کننده؛ یا اطلاعات مربوط به ویدیوی در حال پخش را بازیابی کنید. همچنین می‌توانید شنونده‌های رویدادی را اضافه کنید که در پاسخ به رویدادهای پخش کننده خاص، مانند تغییر وضعیت پخش، اجرا می‌شوند.

این راهنما نحوه استفاده از IFrame API را توضیح می دهد. انواع مختلف رویدادهایی را که API می‌تواند ارسال کند را شناسایی می‌کند و نحوه نوشتن شنوندگان رویداد برای پاسخ به آن رویدادها را توضیح می‌دهد. همچنین توابع مختلف جاوا اسکریپت را که می‌توانید برای کنترل پخش‌کننده ویدیو فراخوانی کنید و همچنین پارامترهای پخش‌کننده‌ای را که می‌توانید برای سفارشی‌سازی بیشتر پخش‌کننده استفاده کنید، توضیح می‌دهد.

الزامات

مرورگر کاربر باید از ویژگی postMessage HTML5 پشتیبانی کند. اکثر مرورگرهای مدرن از postMessage پشتیبانی می کنند.

Embedded players must have a viewport that is at least 200px by 200px. If the 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.

هر صفحه وب که از API IFrame استفاده می کند باید تابع جاوا اسکریپت زیر را نیز پیاده سازی کند:

  • onYouTubeIframeAPIReady – وقتی صفحه دانلود جاوا اسکریپت برای API پخش کننده تمام شد، 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>

لیست زیر جزئیات بیشتری در مورد نمونه بالا ارائه می دهد:

  1. تگ <div> در این بخش مکانی را در صفحه ای که API IFrame پخش کننده ویدیو را در آن قرار می دهد، مشخص می کند. سازنده شی پخش کننده، که در بخش Loading a video player توضیح داده شده است، تگ <div> را با id خود شناسایی می کند تا مطمئن شود که API <iframe> را در مکان مناسب قرار می دهد. به طور خاص، IFrame API تگ <div> را با تگ <iframe> جایگزین می کند.

    به عنوان جایگزین، می‌توانید عنصر <iframe> را مستقیماً در صفحه قرار دهید. بخش Loading a video player نحوه انجام این کار را توضیح می دهد.

  2. کد موجود در این بخش کد جاوا اسکریپت API IFrame Player را بارگیری می کند. مثال از اصلاح DOM برای دانلود کد API استفاده می کند تا اطمینان حاصل شود که کد به صورت ناهمزمان بازیابی می شود. (ویژگی async تگ <script> ، که دانلودهای ناهمزمان را نیز فعال می کند، هنوز در همه مرورگرهای مدرن پشتیبانی نمی شود، همانطور که در این پاسخ Stack Overflow بحث شد.

  3. عملکرد onYouTubeIframeAPIReady به محض دانلود کد API پخش کننده اجرا می شود. این بخش از کد یک متغیر سراسری، player تعریف می کند، که به پخش کننده ویدیویی که در حال تعبیه آن هستید اشاره دارد و سپس تابع، شی پخش کننده ویدیو را می سازد.

  4. تابع onPlayerReady زمانی اجرا می شود که رویداد onReady فعال شود. در این مثال، عملکرد نشان می دهد که وقتی پخش کننده ویدیو آماده است، باید شروع به پخش کند.

  5. API تابع onPlayerStateChange را هنگامی که وضعیت بازیکن تغییر می‌کند، فراخوانی می‌کند، که ممکن است نشان‌دهنده این باشد که پخش‌کننده در حال بازی کردن، توقف، تمام شدن و غیره است. این عملکرد نشان می دهد که وقتی وضعیت پخش 1 است (در حال پخش)، پخش کننده باید به مدت شش ثانیه پخش شود و سپس تابع stopVideo را فراخوانی کند تا ویدیو متوقف شود.

در حال بارگیری یک پخش کننده ویدیو

پس از بارگیری کد جاوا اسکریپت 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
    }
  });
}

سازنده برای پخش کننده ویدیو پارامترهای زیر را مشخص می کند:

  1. پارامتر اول یا عنصر DOM یا id عنصر HTML را مشخص می کند که در آن API تگ <iframe> حاوی پخش کننده را درج می کند.

    IFrame API عنصر مشخص شده را با عنصر <iframe> حاوی پخش کننده جایگزین می کند. اگر عنصری که جایگزین می شود سبک نمایش متفاوتی نسبت به عنصر درج شده <iframe> داشته باشد، می تواند روی طرح بندی صفحه شما تأثیر بگذارد. به طور پیش‌فرض، یک <iframe> به عنوان یک عنصر inline-block نمایش داده می‌شود.

  2. پارامتر دوم یک شی است که گزینه های پخش کننده را مشخص می کند. شی شامل ویژگی های زیر است:
    • width (عدد) - عرض پخش کننده ویدیو. مقدار پیش فرض 640 است.
    • height (تعداد) - ارتفاع پخش کننده ویدیو. مقدار پیش فرض 390 است.
    • videoId (رشته) - شناسه ویدیوی YouTube که ویدیویی را که پخش کننده بارگذاری می کند، مشخص می کند.
    • playerVars (شیء) - ویژگی های شیء پارامترهای پخش کننده را شناسایی می کند که می توان از آنها برای سفارشی کردن پخش کننده استفاده کرد.
    • events (شیء) - ویژگی های شیء رویدادهایی را که API اجرا می کند و توابع (شنونده های رویداد) را که API هنگام وقوع آن رویدادها فراخوانی می کند، مشخص می کند. در مثال، سازنده نشان می‌دهد که تابع onPlayerReady زمانی اجرا می‌شود که رویداد onReady فعال می‌شود و تابع onPlayerStateChange زمانی که رویداد onStateChange فعال می‌شود، اجرا می‌شود.

همانطور که در بخش شروع به کار ذکر شد، به جای نوشتن یک عنصر خالی <div> در صفحه خود، که کد جاوا اسکریپت API پخش کننده با عنصر <iframe> جایگزین می شود، می توانید تگ <iframe> را خودتان ایجاد کنید. اولین مثال در بخش Examples نحوه انجام این کار را نشان می دهد.

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

توجه داشته باشید که اگر تگ <iframe> را می‌نویسید، وقتی شی YT.Player را می‌سازید، نیازی به تعیین مقادیر برای width و height ندارید که به عنوان ویژگی‌های تگ <iframe> یا videoId مشخص می‌شوند. و پارامترهای پخش کننده، که در URL src مشخص شده اند. به عنوان یک اقدام امنیتی اضافی، باید پارامتر origin را نیز به URL وارد کنید و طرح URL ( http:// یا https:// ) و دامنه کامل صفحه میزبان خود را به عنوان مقدار پارامتر مشخص کنید. در حالی که origin اختیاری است، از جمله در برابر تزریق جاوا اسکریپت شخص ثالث مخرب به صفحه شما و ربودن کنترل پخش کننده YouTube شما محافظت می کند.

بخش Examples همچنین چند مثال دیگر را برای ساخت اشیاء پخش کننده ویدیو نشان می دهد.

عملیات

برای فراخوانی متدهای پخش کننده 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

این عملکرد تصویر کوچک ویدیوی مشخص شده را بارگیری می کند و پخش کننده را برای پخش ویدیو آماده می کند. پخش کننده تا زمانی که playVideo() یا seekTo() فراخوانی نشود، FLV را درخواست نمی کند.

  • پارامتر videoId مورد نیاز، شناسه ویدیوی YouTube را برای پخش مشخص می کند. در YouTube Data API، ویژگی id یک منبع video ، شناسه را مشخص می‌کند.
  • پارامتر اختیاری startSeconds یک float/integer را می‌پذیرد و زمانی را مشخص می‌کند که پس از فراخوانی playVideo() باید پخش ویدیو شروع شود. اگر مقدار startSeconds را مشخص کنید و سپس seekTo() را فراخوانی کنید، پخش کننده از زمان مشخص شده در فراخوان seekTo() بازی می کند. هنگامی که ویدیو آماده شد و برای پخش آماده شد، پخش کننده یک رویداد video cued پخش خواهد کرد ( 5 ).
  • پارامتر اختیاری endSeconds ، که فقط در نحو شی پشتیبانی می‌شود، یک عدد float/integer را می‌پذیرد و زمانی را مشخص می‌کند که پخش ویدیو با فراخوانی 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/integer را می پذیرد. اگر مشخص باشد، ویدئو از نزدیکترین فریم کلیدی به زمان مشخص شده شروع می شود.
  • پارامتر اختیاری endSeconds یک float/integer را می پذیرد. اگر مشخص شده باشد، پخش ویدیو در زمان مشخص شده متوقف می شود.

cueVideoByUrl

  • نحو آرگومان

    player.cueVideoByUrl(mediaContentUrl:String,
                         startSeconds:Number):Void
  • نحو شی

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

این عملکرد تصویر کوچک ویدیوی مشخص شده را بارگیری می کند و پخش کننده را برای پخش ویدیو آماده می کند. پخش کننده تا زمانی که playVideo() یا seekTo() فراخوانی نشود، FLV را درخواست نمی کند.

  • پارامتر mediaContentUrl مورد نیاز یک URL پخش کننده YouTube کاملا واجد شرایط را در قالب http://www.youtube.com/v/VIDEO_ID?version=3 مشخص می کند.
  • پارامتر اختیاری startSeconds یک float/integer را می‌پذیرد و زمانی را مشخص می‌کند که پس از فراخوانی playVideo() باید پخش ویدیو شروع شود. اگر startSeconds مشخص کنید و سپس seekTo() را فراخوانی کنید، سپس پخش کننده از زمان مشخص شده در فراخوان seekTo() پخش می شود. هنگامی که ویدئو آماده شد و برای پخش آماده شد، پخش کننده یک رویداد video cued (5) را پخش خواهد کرد.
  • پارامتر اختیاری endSeconds ، که فقط در نحو شی پشتیبانی می‌شود، یک عدد float/integer را می‌پذیرد و زمانی را مشخص می‌کند که پخش ویدیو با فراخوانی 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/integer را می‌پذیرد و زمان شروع پخش ویدیو را مشخص می‌کند. اگر startSeconds (عدد می تواند شناور باشد) مشخص شده باشد، ویدیو از نزدیکترین فریم کلیدی به زمان مشخص شده شروع می شود.
  • پارامتر اختیاری endSeconds ، که فقط در نحو شی پشتیبانی می‌شود، یک عدد شناور/صحیح را می‌پذیرد و زمان توقف پخش ویدیو را مشخص می‌کند.

توابع صف برای لیست ها

توابع cuePlaylist و loadPlaylist به شما این امکان را می دهند که یک لیست پخش را بارگیری و پخش کنید. اگر از دستور شی برای فراخوانی این توابع استفاده می کنید، می توانید لیستی از ویدیوهای آپلود شده کاربر را نیز در صف قرار دهید (یا بارگذاری کنید).

از آنجایی که توابع بسته به اینکه با استفاده از نحو آرگومان فراخوانی شوند یا نحو شیء متفاوت عمل می کنند، هر دو روش فراخوانی در زیر مستند شده اند.

cuePlaylist
  • نحو آرگومان

    player.cuePlaylist(playlist:String|Array,
                       index:Number,
                       startSeconds:Number):Void
    لیست پخش مشخص شده را در صف قرار می دهد. وقتی لیست پخش آماده شد و برای پخش آماده شد، پخش کننده یک رویداد video cued را پخش می کند ( 5 ).
    • پارامتر playlist مورد نیاز آرایه ای از شناسه های ویدیوی YouTube را مشخص می کند. در YouTube Data API، ویژگی id منبع video ، شناسه آن ویدیو را مشخص می‌کند.

    • پارامتر index اختیاری، نمایه اولین ویدیویی را که در لیست پخش پخش می‌شود، مشخص می‌کند. این پارامتر از یک شاخص مبتنی بر صفر استفاده می کند و مقدار پارامتر پیش فرض 0 است، بنابراین رفتار پیش فرض بارگیری و پخش اولین ویدیو در لیست پخش است.

    • پارامتر اختیاری startSeconds یک عدد float/integer را می‌پذیرد و زمانی را مشخص می‌کند که اولین ویدیو در لیست پخش با فراخوانی تابع 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 هستند. یک مقدار منسوخ، search ، از 15 نوامبر 2020 دیگر پشتیبانی نخواهد شد. مقدار پیش فرض 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/integer را می‌پذیرد و زمانی را مشخص می‌کند که اولین ویدیوی لیست باید از آن زمان شروع به پخش کند که تابع 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/integer را می‌پذیرد و زمانی را مشخص می‌کند که اولین ویدیو در لیست پخش باید از آن زمان شروع به پخش کند.

  • نحو شی

    player.loadPlaylist({list:String,
                         listType:String,
                         index:Number,
                         startSeconds:Number}):Void
    این تابع لیست مشخص شده را بارگیری می کند و آن را پخش می کند. این لیست می تواند یک لیست پخش یا فید ویدیوهای آپلود شده کاربر باشد. امکان بارگیری فهرستی از نتایج جستجو منسوخ شده است و از 15 نوامبر 2020 دیگر پشتیبانی نخواهد شد.
    • ویژگی اختیاری listType نوع فید نتایجی را که بازیابی می کنید مشخص می کند. مقادیر معتبر playlist و user_uploads هستند. یک مقدار منسوخ، search ، از 15 نوامبر 2020 دیگر پشتیبانی نخواهد شد. مقدار پیش فرض 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/integer را می‌پذیرد و زمانی را مشخص می‌کند که اولین ویدیوی فهرست باید پخش شود.

کنترل های پخش و تنظیمات پخش کننده

پخش یک ویدیو

player. playVideo ():Void
ویدیوی نمایش داده شده/بارگذاری شده فعلی را پخش می کند. حالت نهایی پخش کننده پس از اجرای این تابع playing (1) خواهد بود.

توجه: بازپخش تنها در صورتی در تعداد بازدیدهای رسمی ویدیو به حساب می آید که از طریق دکمه پخش بومی در پخش کننده شروع شود.
player. pauseVideo ():Void
ویدیوی در حال پخش را متوقف می کند. حالت نهایی پخش کننده پس از اجرای این تابع paused می شود ( 2 ) مگر اینکه هنگام فراخوانی تابع، پخش کننده در حالت ended ( 0 ) باشد، در این صورت وضعیت پخش تغییر نخواهد کرد.
player. stopVideo ():Void
بارگیری ویدیوی فعلی را متوقف و لغو می کند. این عملکرد باید برای موقعیت‌های نادری که می‌دانید کاربر ویدیوی اضافی را در پخش‌کننده تماشا نخواهد کرد، رزرو شود. اگر قصد شما توقف موقت ویدیو است، فقط باید تابع pauseVideo فراخوانی کنید. اگر می‌خواهید ویدیویی را که پخش‌کننده در حال پخش است تغییر دهید، می‌توانید بدون تماس با stopVideo ابتدا یکی از عملکردهای صف را فراخوانی کنید.

مهم: برخلاف عملکرد pauseVideo که پخش کننده را در حالت paused ( 2 ) قرار می دهد، عملکرد stopVideo می تواند پخش کننده را در حالت عدم پخش قرار دهد، از جمله ended ( 0paused ( 2video cued ( 5 ) یا unstarted ( -1 ).
player. seekTo (seconds:Number, allowSeekAhead:Boolean):Void
به دنبال زمان مشخصی در ویدیو است. اگر پخش کننده هنگام فراخوانی عملکرد متوقف شود، متوقف می شود. اگر عملکرد از حالت دیگری فراخوانی شود (در حال playing ، video cued ، و غیره)، پخش کننده ویدیو را پخش می کند.
  • پارامتر seconds زمانی را مشخص می کند که بازیکن باید تا آن پیش برود.

    پخش‌کننده قبل از آن زمان به نزدیک‌ترین فریم کلیدی می‌رود، مگر اینکه پخش‌کننده قبلاً بخشی از ویدیویی را که کاربر به دنبال آن است دانلود کرده باشد.

  • پارامتر allowSeekAhead تعیین می‌کند که اگر پارامتر seconds زمانی خارج از داده‌های ویدئویی بافر فعلی را مشخص کند، پخش‌کننده درخواست جدیدی به سرور ارسال کند یا خیر.

    توصیه می‌کنیم زمانی که کاربر ماوس را در نوار پیشرفت ویدیو می‌کشد، این پارامتر را روی false تنظیم کنید و زمانی که کاربر ماوس را رها کرد، آن را روی true تنظیم کنید. این رویکرد به کاربر اجازه می‌دهد تا با پیمایش نقاط بافر نشده در ویدیو، به نقاط مختلف ویدیو بدون درخواست پخش جریانی جدید ویدیو پیمایش کند. هنگامی که کاربر دکمه ماوس را رها می کند، پخش کننده به نقطه مورد نظر در ویدیو پیش می رود و در صورت لزوم درخواست پخش ویدیوی جدید می کند.

کنترل پخش ویدیوهای 360 درجه

توجه: تجربه پخش ویدیوی 360 درجه در دستگاه های تلفن همراه پشتیبانی محدودی دارد. در دستگاه‌های پشتیبانی‌نشده، ویدیوهای 360 درجه تحریف شده به نظر می‌رسند و اصلاً هیچ روش پشتیبانی‌شده‌ای برای تغییر زاویه دید وجود ندارد، از جمله از طریق API، استفاده از حسگرهای جهت‌یابی، یا پاسخ به اقدامات لمسی/کشیدن روی صفحه‌نمایش دستگاه.

player. getSphericalProperties ():Object
ویژگی هایی را بازیابی می کند که دیدگاه یا نمای فعلی بیننده را برای پخش ویدیو توصیف می کند. علاوه بر این:
  • این شی فقط برای ویدیوهای 360 درجه پر شده است که به آنها ویدیوهای کروی نیز می گویند.
  • اگر ویدیوی فعلی یک ویدیوی 360 درجه نیست یا اگر عملکرد از یک دستگاه پشتیبانی نشده فراخوانی شود، تابع یک شی خالی را برمی‌گرداند.
  • در دستگاه‌های تلفن همراه پشتیبانی‌شده، اگر ویژگی enableOrientationSensor روی true تنظیم شود، این تابع یک شی را برمی‌گرداند که در آن ویژگی fov حاوی مقدار صحیح است و سایر ویژگی‌ها روی 0 تنظیم شده‌اند.
شی شامل ویژگی های زیر است:
خواص
yaw عددی در محدوده [0، 360) که زاویه افقی دید را بر حسب درجه نشان می‌دهد، که نشان‌دهنده میزان چرخش کاربر به سمت چپ یا راست است. موقعیت خنثی، رو به مرکز ویدیو در نمای مستطیلی آن، نشان دهنده 0 درجه است، و این مقدار با چرخش بیننده به چپ افزایش می یابد.
pitch عددی در محدوده [90-، 90] که زاویه عمودی دید را بر حسب درجه نشان می‌دهد، که نشان‌دهنده میزانی است که کاربر نما را برای نگاه کردن به بالا یا پایین تنظیم می‌کند. موقعیت خنثی، رو به مرکز ویدیو در طرح ریزی مستطیل شکل آن، نشان دهنده 0 درجه است، و این مقدار با نگاه کردن بیننده به بالا افزایش می یابد.
roll عددی در محدوده [-180، 180] که زاویه چرخش در جهت عقربه‌های ساعت یا خلاف جهت عقربه‌های ساعت را بر حسب درجه نشان می‌دهد. موقعیت خنثی، با محور افقی در برآمدگی مستطیل شکل موازی با محور افقی نما، نشان دهنده 0 درجه است. با چرخش نما در جهت عقربه‌های ساعت، مقدار افزایش می‌یابد و با چرخش نما در خلاف جهت عقربه‌های ساعت، مقدار آن کاهش می‌یابد.

توجه داشته باشید که پخش کننده تعبیه شده یک رابط کاربری برای تنظیم رول نمایش ارائه نمی دهد. رول را می توان به یکی از این روش های متقابل منحصر به فرد تنظیم کرد:
  1. از حسگر جهت یابی در مرورگر تلفن همراه برای ارائه رول برای نما استفاده کنید. اگر سنسور جهت گیری فعال باشد، تابع getSphericalProperties همیشه 0 به عنوان مقدار ویژگی roll برمی گرداند.
  2. اگر سنسور جهت غیرفعال است، با استفاده از این API، رول را روی یک مقدار غیر صفر تنظیم کنید.
fov عددی در محدوده [30، 120] که میدان دید نمای را بر حسب درجه نشان می‌دهد که در امتداد لبه بلندتر نمای درگاه اندازه‌گیری می‌شود. لبه کوتاه‌تر به‌طور خودکار تنظیم می‌شود تا متناسب با نسبت تصویر باشد.

مقدار پیش فرض 100 درجه است. کاهش مقدار مانند بزرگنمایی محتوای ویدیویی است و افزایش مقدار مانند بزرگنمایی است. این مقدار را می توان با استفاده از API یا با استفاده از چرخ ماوس هنگامی که ویدیو در حالت تمام صفحه است تنظیم کرد.
player. setSphericalProperties (properties:Object):Void
جهت ویدیو را برای پخش یک ویدیوی 360 درجه تنظیم می کند. (اگر ویدیوی فعلی کروی نباشد، روش بدون در نظر گرفتن ورودی، بدون عملیات است.)

نمای پخش کننده با به روز رسانی به فراخوانی های این روش پاسخ می دهد تا مقادیر هر ویژگی شناخته شده در شیء properties را منعکس کند. این view مقادیری را برای هر ویژگی شناخته شده دیگری که در آن شی گنجانده نشده است حفظ می کند.

علاوه بر این:
  • اگر شی حاوی ویژگی های ناشناخته و/یا غیرمنتظره باشد، بازیکن آنها را نادیده می گیرد.
  • همانطور که در ابتدای این بخش ذکر شد، تجربه پخش ویدیوی 360 درجه در همه دستگاه های تلفن همراه پشتیبانی نمی شود.
  • به‌طور پیش‌فرض، در دستگاه‌های تلفن همراه پشتیبانی‌شده، این تابع مجموعه‌ها فقط ویژگی fov را تنظیم می‌کند و بر ویژگی‌های yaw ، pitch و roll برای پخش ویدیوی 360 درجه تأثیر نمی‌گذارد. برای جزئیات بیشتر به ویژگی enableOrientationSensor در زیر مراجعه کنید.
شیء properties ارسال شده به تابع حاوی ویژگی های زیر است:
خواص
yaw به تعریف بالا مراجعه کنید.
pitch به تعریف بالا مراجعه کنید.
roll به تعریف بالا مراجعه کنید.
fov به تعریف بالا مراجعه کنید.
enableOrientationSensor توجه: این ویژگی فقط بر روی تجربه مشاهده 360 درجه در دستگاه های پشتیبانی شده تأثیر می گذارد. یک مقدار بولی که نشان می‌دهد آیا تعبیه‌شده IFrame باید به رویدادهایی که سیگنال تغییرات در جهت دستگاه پشتیبانی‌شده را نشان می‌دهند، مانند DeviceOrientationEvent مرورگر تلفن همراه پاسخ دهد. مقدار پارامتر پیش فرض true است.

دستگاه های تلفن همراه پشتیبانی شده
  • وقتی مقدار true باشد، پخش‌کننده تعبیه‌شده تنها به حرکت دستگاه تکیه می‌کند تا ویژگی‌های yaw ، pitch و roll برای پخش ویدیوی 360 درجه تنظیم کند. با این حال، ویژگی fov را هنوز می توان از طریق API تغییر داد، و API در واقع تنها راه برای تغییر ویژگی fov در یک دستگاه تلفن همراه است. این رفتار به طور پیش فرض است.
  • وقتی مقدار false است، حرکت دستگاه بر تجربه مشاهده 360 درجه تأثیر نمی‌گذارد و ویژگی‌های yaw ، pitch ، roll و fov همگی باید از طریق API تنظیم شوند.

دستگاه های تلفن همراه پشتیبانی نشده
مقدار ویژگی enableOrientationSensor هیچ تاثیری بر تجربه پخش ندارد.

پخش یک ویدیو در لیست پخش

player. nextVideo ():Void
این تابع ویدیوی بعدی را در لیست پخش بارگیری و پخش می کند.
  • اگر player.nextVideo() در حالی که آخرین ویدیو در لیست پخش در حال مشاهده است فراخوانی شود، و لیست پخش برای پخش مداوم ( loop ) تنظیم شده باشد، پخش کننده اولین ویدیوی لیست را بارگیری و پخش می کند.

  • اگر player.nextVideo() در حالی که آخرین ویدیو در لیست پخش در حال مشاهده است فراخوانی شود و لیست پخش برای پخش مداوم تنظیم نشده باشد، پخش به پایان می رسد.

player. previousVideo ():Void
این عملکرد ویدیوی قبلی را در لیست پخش بارگیری و پخش می کند.
  • اگر player.previousVideo() در حالی که اولین ویدیو در لیست پخش در حال تماشا است فراخوانی شود، و لیست پخش به طور مداوم پخش شود ( loop )، پخش کننده آخرین ویدیوی لیست را بارگیری و پخش می کند.

  • اگر player.previousVideo() در حالی که اولین ویدیو در لیست پخش در حال مشاهده است فراخوانی شود و لیست پخش برای پخش مداوم تنظیم نشده باشد، پخش کننده اولین ویدیوی لیست پخش را از ابتدا مجدداً راه اندازی می کند.

player. playVideoAt (index:Number):Void
این عملکرد ویدیوی مشخص شده را در لیست پخش بارگیری و پخش می کند.
  • پارامتر index مورد نیاز نمایه ویدیویی را که می خواهید در لیست پخش پخش کنید مشخص می کند. این پارامتر از یک شاخص مبتنی بر صفر استفاده می کند، بنابراین مقدار 0 اولین ویدیو را در لیست مشخص می کند. اگر لیست پخش را به هم ریخته باشید، این عملکرد ویدیو را در موقعیت مشخص شده در لیست پخش به هم ریخته پخش می کند.

تغییر صدای پخش کننده

player. mute ():Void
پخش کننده را بی صدا می کند.
player. unMute ():Void
صدای پخش کننده را لغو می کند.
player. isMuted ():Boolean
اگر پخش کننده بی صدا باشد true ، در غیر این صورت false برمی گرداند.
player. setVolume (volume:Number):Void
میزان صدا را تنظیم می کند. عدد صحیح بین 0 تا 100 را می پذیرد.
player. getVolume ():Number
حجم فعلی پخش کننده، عددی صحیح بین 0 تا 100 را برمی گرداند. توجه داشته باشید که getVolume() حجم صدا را برمی گرداند حتی اگر پخش کننده بی صدا باشد.

تنظیم اندازه پخش کننده

player.setSize(width:Number, height:Number):Object
اندازه <iframe> را که حاوی پخش کننده است بر حسب پیکسل تنظیم می کند.

تنظیم نرخ پخش

player. getPlaybackRate ():Number
این عملکرد نرخ پخش ویدیوی در حال پخش را بازیابی می کند. نرخ پخش پیش‌فرض 1 است که نشان می‌دهد ویدیو با سرعت عادی پخش می‌شود. نرخ پخش ممکن است شامل مقادیری مانند 0.25 ، 0.5 ، 1 ، 1.5 ، و 2 باشد.
player. setPlaybackRate (suggestedRate:Number):Void
این تابع نرخ پخش پیشنهادی را برای ویدیوی فعلی تنظیم می کند. اگر نرخ پخش تغییر کند، فقط برای ویدیویی که قبلاً نمایش داده شده یا در حال پخش است تغییر می کند. اگر نرخ پخش را برای یک ویدیوی نمایشی تنظیم کنید، زمانی که عملکرد playVideo فراخوانی می شود یا کاربر پخش را مستقیماً از طریق کنترل های پخش کننده شروع می کند، این نرخ همچنان فعال خواهد بود. علاوه بر این، فراخوانی توابع برای نمایش یا بارگیری ویدیوها یا لیست‌های پخش ( cueVideoById ، loadVideoById ، و غیره) نرخ پخش را به 1 بازنشانی می‌کند.

فراخوانی این عملکرد تضمین نمی کند که نرخ پخش واقعاً تغییر کند. با این حال، اگر نرخ پخش تغییر کند، رویداد onPlaybackRateChange فعال می‌شود و کد شما باید به رویداد پاسخ دهد نه اینکه تابع setPlaybackRate را فراخوانی کند.

روش getAvailablePlaybackRates نرخ پخش احتمالی ویدیوی در حال پخش را برمی گرداند. با این حال، اگر پارامتر suggestedRate را روی یک عدد صحیح یا مقدار شناور غیرپشتیبانی‌نشده تنظیم کنید، بازیکن آن مقدار را به نزدیک‌ترین مقدار پشتیبانی شده در جهت 1 گرد می‌کند.
player. getAvailablePlaybackRates ():Array
این تابع مجموعه نرخ‌های پخشی را که ویدیوی فعلی در آن موجود است را برمی‌گرداند. مقدار پیش فرض 1 است که نشان می دهد ویدیو با سرعت عادی پخش می شود.

این تابع آرایه ای از اعداد مرتب شده از کندترین به سریعترین سرعت پخش را برمی گرداند. حتی اگر پخش کننده از سرعت پخش متغیر پشتیبانی نکند، آرایه همیشه باید حداقل یک مقدار ( 1 ) داشته باشد.

تنظیم رفتار پخش برای لیست های پخش

player. setLoop (loopPlaylists:Boolean):Void

این عملکرد نشان می دهد که آیا پخش کننده ویدیو باید به طور مداوم یک لیست پخش را پخش کند یا اینکه پس از پایان آخرین ویدیو در لیست پخش، پخش آن متوقف شود. رفتار پیش فرض این است که لیست های پخش حلقه نمی شوند.

این تنظیم حتی اگر یک لیست پخش متفاوت را بارگیری یا نشانه گذاری کنید، ادامه خواهد داشت، به این معنی که اگر یک لیست پخش را بارگیری کنید، تابع setLoop را با مقدار true فراخوانی کنید و سپس لیست پخش دوم را بارگیری کنید، لیست پخش دوم نیز حلقه خواهد شد.

پارامتر loopPlaylists مورد نیاز رفتار حلقه را مشخص می کند.

  • اگر مقدار پارامتر true باشد، پخش کننده ویدیو به طور مداوم لیست های پخش را پخش می کند. پس از پخش آخرین ویدیو در یک لیست پخش، پخش کننده ویدیو به ابتدای لیست پخش برمی گردد و دوباره آن را پخش می کند.

  • اگر مقدار پارامتر false باشد، پس از اینکه پخش کننده ویدیو آخرین ویدیو را در یک لیست پخش پخش کرد، بازپخش پایان می یابد.

player. setShuffle (shufflePlaylist:Boolean):Void

این عملکرد نشان می دهد که آیا ویدیوهای یک لیست پخش باید به هم ریخته شوند تا به ترتیبی متفاوت از ترتیبی که سازنده لیست پخش تعیین کرده پخش شوند. اگر یک لیست پخش را بعد از شروع پخش آن به هم بزنید، تا زمانی که ویدیوی در حال پخش به پخش ادامه می‌دهد، فهرست دوباره مرتب می‌شود. سپس ویدیوی بعدی که پخش می‌شود بر اساس فهرستی که مرتب شده است انتخاب می‌شود.

اگر لیست پخش دیگری را بارگیری کنید یا علامت بزنید، این تنظیم ادامه نخواهد داشت، به این معنی که اگر یک لیست پخش را بارگیری کنید، تابع setShuffle را فراخوانی کنید و سپس لیست پخش دوم را بارگیری کنید، لیست پخش دوم به هم ریخته نخواهد شد.

پارامتر shufflePlaylist مورد نیاز نشان می دهد که آیا YouTube باید لیست پخش را به هم بزند یا خیر.

  • اگر مقدار پارامتر true باشد، YouTube ترتیب لیست پخش را تغییر می دهد. اگر به این تابع دستور دهید تا لیست پخشی را که قبلاً به هم ریخته شده است به هم بزند، YouTube دوباره ترتیب را به هم می‌زند.

  • اگر مقدار پارامتر false باشد، YouTube ترتیب لیست پخش را به ترتیب اصلی خود تغییر خواهد داد.

وضعیت پخش

player. getVideoLoadedFraction ():Float
عددی بین 0 و 1 را برمی‌گرداند که درصد ویدیویی را که پخش‌کننده به‌عنوان بافر نشان می‌دهد، مشخص می‌کند. این روش عدد قابل اعتمادتری را نسبت به متدهای getVideoBytesLoaded و getVideoBytesTotal که اکنون منسوخ شده اند، برمی گرداند.
player.getPlayerState():Number
وضعیت بازیکن را برمی‌گرداند. مقادیر ممکن عبارتند از:
  • -1 - شروع نشده است
  • 0 - پایان یافت
  • 1 - بازی کردن
  • 2 مکث کرد
  • 3 بافر کردن
  • 5 - تصویری cued
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 مشخص اضافه می کند. بخش وقایع زیر وقایع مختلفی را که ممکن است بازیکن آتش سوزی کند مشخص می کند. شنونده رشته ای است که عملکردی را که هنگام آتش سوزی رویداد مشخص شده انجام می دهد ، مشخص می کند.
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 و 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 (ویدیو cued).

هنگامی که پخش کننده اولین بار یک ویدیو را بارگیری می کند ، یک رویداد 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 لیستی از نرخ پخش معتبر را برای فیلم Cust یا Clued یا Playing بازگرداند.
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 پشتیبانی می کند ذکر کرده است:

مدول گزینه شرح
captionsfontSize این گزینه اندازه قلم زیرنویس های نمایش داده شده در پخش کننده را تنظیم می کند.

مقادیر معتبر -1 ، 0 ، 1 ، 2 و 3 هستند. اندازه پیش فرض 0 و کوچکترین اندازه -1 است. تنظیم این گزینه در یک عدد صحیح زیر -1 باعث می شود کوچکترین اندازه زیرنویس نمایش داده شود ، در حالی که تنظیم این گزینه روی یک عدد صحیح بالاتر از 3 باعث می شود بزرگترین اندازه زیرنویس نمایش داده شود.
captionsreload این گزینه داده های زیرنویس بسته را برای ویدئویی که در حال پخش است بارگیری می کند. اگر مقدار گزینه را بازیابی کنید ، مقدار null خواهد بود. برای بارگیری مجدد داده های زیرنویس بسته ، مقدار را روی true تنظیم کنید.
onAutoplayBlocked
این رویداد هر بار که مرورگر ویژگی های پخش ویدیویی را به صورت جمعی به عنوان "AutoPlay" مسدود می کند ، از آن استفاده می کند. این شامل تلاش برای پخش با هر یک از API های بازیکن زیر است:

بیشتر مرورگرها خط مشی دارند که در صورت صحت شرایط خاص ، می توانند اتوپل را در دسک تاپ ، موبایل و سایر محیط ها مسدود کنند. مواردی که ممکن است این خط مشی ایجاد شود شامل پخش بدون تعامل بدون تعامل کاربر است ، یا هنگامی که یک سیاست مجوز برای اجازه دادن به اتوپل در یک IFRAME متقاطع تنظیم نشده است.

برای جزئیات کامل ، به خط مشی های خاص مرورگر ( Apple Safari / WebKit ، Google Chrome ، Mozilla Firefox ) و راهنمای خودکار موزیلا مراجعه کنید.

مثال ها

ایجاد اشیاء YT.Player

  • مثال 1: از API با <iframe> موجود استفاده کنید

    در این مثال ، یک عنصر <iframe> در صفحه قبلاً بازیکنی را که از آن استفاده می شود تعریف می کند. توجه داشته باشید که یا 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: پخش با صدای بلند

    این مثال یک پخش کننده ویدیویی 1280px با 720px ایجاد می کند. شنونده رویداد برای رویداد 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: این مثال پارامترهای پخش کننده را تنظیم می کند تا هنگام بارگذاری به طور خودکار ویدیو را پخش کند و کنترل های پخش کننده ویدیو را پنهان کند. همچنین شنوندگان رویداد را برای چندین رویداد که 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>

ادغام API یکپارچگی رسانه Android WebView

YouTube Android WebView Media API را گسترش داده است تا بازیکنان رسانه ای تعبیه شده از جمله تعبیه کننده YouTube Player در برنامه های Android را فعال کنند تا صحت برنامه تعبیه را تأیید کنند. با این تغییر ، برنامه ها به طور خودکار یک شناسه برنامه تأیید شده را به YouTube ارسال می کنند. داده های جمع آوری شده از طریق استفاده از این API ، ابرداده برنامه (نام بسته ، شماره نسخه و گواهی امضای) و یک نشانه تأیید دستگاه تولید شده توسط Google Play Services است.

از داده ها برای تأیید یکپارچگی برنامه و دستگاه استفاده می شود. رمزگذاری شده است ، با اشخاص ثالث به اشتراک گذاشته نمی شود و به دنبال یک دوره نگهداری ثابت حذف می شود. توسعه دهندگان برنامه می توانند هویت برنامه خود را در API یکپارچگی رسانه WebView پیکربندی کنند . پیکربندی از یک گزینه امتناع پشتیبانی می کند.

تاریخچه ویرایشهای

June 24, 2024

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

November 20, 2023

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

April 27, 2021

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

October 13, 2020

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

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

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

October 24, 2019

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

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

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

May 16, 2018

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

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

This example demonstrates and lets you test these new features.

June 19, 2017

This update contains the following changes:

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

August 11, 2016

This update contains the following changes:

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

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

June 29, 2016

This update contains the following changes:

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

June 24, 2016

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

January 6, 2016

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

December 18, 2015

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

April 28, 2014

This update contains the following changes:

March 25, 2014

This update contains the following changes:

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

July 23, 2013

This update contains the following changes:

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

October 31, 2012

This update contains the following changes:

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

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

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

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

August 22, 2012

This update contains the following changes:

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

August 6, 2012

This update contains the following changes:

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

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

    • Functions

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

    • Events

July 19, 2012

This update contains the following changes:

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

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

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

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

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

July 16, 2012

This update contains the following changes:

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

June 6, 2012

This update contains the following changes:

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

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

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

March 30, 2012

This update contains the following changes:

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

March 26, 2012

This update contains the following changes:

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