این صفحه به‌وسیله ‏Cloud Translation API‏ ترجمه شده است.

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>

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

تگ <div> در این بخش مکانی را در صفحه ای که API IFrame پخش کننده ویدیو را در آن قرار می دهد، مشخص می کند. سازنده شی پخش کننده، که در بخش Loading a video player توضیح داده شده است، تگ <div> را با id خود شناسایی می کند تا مطمئن شود که API <iframe> را در مکان مناسب قرار می دهد. به طور خاص، IFrame API تگ <div> را با تگ <iframe> جایگزین می کند.
به عنوان جایگزین، می‌توانید عنصر <iframe> را مستقیماً در صفحه قرار دهید. بخش Loading a video player نحوه انجام این کار را توضیح می دهد.
کد موجود در این بخش کد جاوا اسکریپت API IFrame Player را بارگیری می کند. مثال از اصلاح DOM برای دانلود کد API استفاده می کند تا اطمینان حاصل شود که کد به صورت ناهمزمان بازیابی می شود. (ویژگی async تگ <script> ، که دانلودهای ناهمزمان را نیز فعال می کند، هنوز در همه مرورگرهای مدرن پشتیبانی نمی شود، همانطور که در این پاسخ Stack Overflow بحث شد.
عملکرد onYouTubeIframeAPIReady به محض دانلود کد API پخش کننده اجرا می شود. این بخش از کد یک متغیر سراسری، player را تعریف می کند، که به پخش کننده ویدیویی که در حال تعبیه آن هستید اشاره دارد و سپس تابع، شی پخش کننده ویدیو را می سازد.
تابع onPlayerReady زمانی اجرا می شود که رویداد onReady فعال شود. در این مثال، عملکرد نشان می دهد که وقتی پخش کننده ویدیو آماده است، باید شروع به پخش کند.
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
    }
  });
}

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

پارامتر اول یا عنصر DOM یا id عنصر HTML را مشخص می کند که در آن API تگ <iframe> حاوی پخش کننده را درج می کند.
IFrame API عنصر مشخص شده را با عنصر <iframe> حاوی پخش کننده جایگزین می کند. اگر عنصری که جایگزین می شود سبک نمایش متفاوتی نسبت به عنصر درج شده <iframe> داشته باشد، می تواند روی طرح بندی صفحه شما تأثیر بگذارد. به طور پیش‌فرض، یک <iframe> به عنوان یک عنصر inline-block نمایش داده می‌شود.
پارامتر دوم یک شی است که گزینه های پخش کننده را مشخص می کند. شی شامل ویژگی های زیر است:
- 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 شما محافظت می کند.

برای مثال‌های دیگر در مورد ساخت اشیاء پخش‌کننده ویدیو، به مثال‌ها مراجعه کنید.

عملیات

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

پارامتر 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 ( 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 را منعکس کند. این 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 از آن پشتیبانی می کند را نشان می دهد:

ماژول	گزینه	توضیحات
captions	fontSize	این گزینه اندازه قلم زیرنویس های نمایش داده شده در پخش کننده را تنظیم می کند. مقادیر معتبر `-1` ، `0` ، `1` ، `2` و `3` هستند. اندازه پیش فرض `0` و کوچکترین اندازه `-1` است. تنظیم این گزینه در یک عدد صحیح زیر `-1` باعث می شود کوچکترین اندازه زیرنویس نمایش داده شود ، در حالی که تنظیم این گزینه روی یک عدد صحیح بالاتر از `3` باعث می شود بزرگترین اندازه زیرنویس نمایش داده شود.
captions	reload	این گزینه داده های زیرنویس بسته را برای ویدئویی که در حال پخش است بارگیری می کند. اگر مقدار گزینه را بازیابی کنید ، مقدار `null` خواهد بود. برای بارگیری مجدد داده های زیرنویس بسته ، مقدار را روی `true` تنظیم کنید.

onAutoplayBlocked

این رویداد هر بار که مرورگر ویژگی های پخش ویدیویی را به صورت جمعی به عنوان "AutoPlay" مسدود می کند ، از آن استفاده می کند. این شامل تلاش برای پخش با هر یک از API های بازیکن زیر است:

پارامتر autoplay
تابع loadPlaylist
عملکرد loadVideoById
عملکرد loadVideoByUrl
عملکرد playVideo

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

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.

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

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

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

الزامات

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

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

onYouTubeIframeAPIReady - API وقتی صفحه بارگیری JavaScript را برای API Player به پایان رساند ، این عملکرد را با این عملکرد فراخوانی می کند ، که به شما امکان می دهد از API در صفحه خود استفاده کنید. بنابراین ، این عملکرد ممکن است اشیاء پخش کننده را که می خواهید هنگام بارگیری صفحه نمایش دهید ، ایجاد کند.

شروع کردن

صفحه نمونه HTML در زیر یک پخش کننده تعبیه شده ایجاد می کند که یک فیلم را بارگیری می کند ، آن را به مدت شش ثانیه پخش می کند و سپس پخش را متوقف می کند. نظرات شماره گذاری شده در HTML در لیست زیر مثال توضیح داده شده است.

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

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

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

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

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

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

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

برچسب <div> در این بخش مکان را در صفحه ای که Iframe API پخش کننده ویدیو را قرار می دهد ، مشخص می کند. سازنده شیء پخش کننده ، که در بارگیری یک پخش کننده ویدیویی شرح داده شده است ، برچسب <div> را توسط id خود مشخص می کند تا اطمینان حاصل شود که API <iframe> را در مکان مناسب قرار می دهد. به طور خاص ، Iframe API برچسب <div> را با برچسب <iframe> جایگزین می کند.
به عنوان یک گزینه دیگر ، می توانید عنصر <iframe> را مستقیماً در صفحه قرار دهید. بخش بارگیری یک پخش کننده ویدیویی نحوه انجام این کار را توضیح می دهد.
کد موجود در این بخش کد API JavaScript Iframe Player را بارگیری می کند. مثال از اصلاح DOM برای بارگیری کد API استفاده می کند تا اطمینان حاصل شود که کد به صورت غیر همزمان بازیابی می شود. <script> async
عملکرد onYouTubeIframeAPIReady به محض بارگیری کد API پخش کننده اجرا می شود. این بخش از کد یک متغیر جهانی ، player را تعریف می کند ، که به پخش کننده ویدیویی که در آن تعبیه شده است ، اشاره دارد و عملکرد سپس شیء پخش کننده ویدیو را ایجاد می کند.
عملکرد onPlayerReady هنگام آتش سوزی رویداد onReady اجرا می شود. در این مثال ، عملکرد نشان می دهد که وقتی پخش کننده ویدیو آماده است ، باید شروع به بازی کند.
API وقتی وضعیت بازیکن را تغییر می دهد ، عملکرد onPlayerStateChange را فراخوانی می کند ، که ممکن است نشان دهد بازیکن در حال بازی ، مکث ، به پایان رساندن و غیره است. این عملکرد نشان می دهد که وقتی حالت بازیکن 1 (بازی) است ، بازیکن باید شش ثانیه بازی کند و سپس با عملکرد stopVideo تماس بگیرد تا فیلم را متوقف کند.

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

پس از بارگذاری کد JavaScript API ، API با عملکرد onYouTubeIframeAPIReady تماس می گیرد ، در این مرحله می توانید یک شی YT.Player را بسازید تا یک پخش کننده ویدیویی را در صفحه خود وارد کنید. گزیده HTML در زیر عملکرد onYouTubeIframeAPIReady را از مثال بالا نشان می دهد:

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

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

پارامتر اول یا عنصر DOM یا id عنصر HTML را مشخص می کند که در آن API برچسب <iframe> حاوی پخش کننده را وارد می کند.
IFRAME API عنصر مشخص شده را با عنصر <iframe> حاوی پخش کننده جایگزین می کند. اگر عنصر جایگزین شده دارای سبک نمایش متفاوتی نسبت به عنصر درج شده <iframe> باشد ، می تواند در چیدمان صفحه شما تأثیر بگذارد. به طور پیش فرض ، یک <iframe> به عنوان یک عنصر inline-block نمایش داده می شود.
پارامتر دوم شیئی است که گزینه های پخش کننده را مشخص می کند. شی حاوی خصوصیات زیر است:
- width (شماره) - عرض پخش کننده ویدیو. مقدار پیش فرض 640 است.
- height (شماره) - ارتفاع پخش کننده ویدیو. مقدار پیش فرض 390 است.
- videoId (String) - شناسه ویدیوی YouTube که ویدئویی را که پخش کننده بارگذاری می کند مشخص می کند.
- playerVars (Object) - خصوصیات شیء پارامترهای پخش کننده را شناسایی می کند که می تواند برای سفارشی کردن پخش کننده استفاده شود.
- events (شی) - خصوصیات شیء وقایعی را که API آتش می گیرد و توابع (شنوندگان رویداد) که API هنگام وقوع آن با آن تماس می گیرند ، مشخص می کند. به عنوان مثال ، سازنده نشان می دهد که هنگامی که رویداد onReady آتش می گیرد و عملکرد onPlayerReady هنگام آتش سوزی رویداد onStateChange اجرا می شود ، عملکرد onPlayerStateChange اجرا خواهد شد.

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

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

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

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

عملیات

برای تماس با روشهای API پخش کننده ، ابتدا باید به شیء بازیکن مورد نظر برای کنترل مراجعه کنید. شما با ایجاد یک شیء YT.Player همانطور که در شروع کار و بارگذاری بخش های پخش کننده ویدیویی از این سند مورد بحث قرار گرفته است ، مرجع را بدست می آورید.

توابع

توابع صف

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

API از دو نحو مختلف برای فراخوانی توابع صف پشتیبانی می کند.

نحو آرگومان مستلزم آرگومان های عملکردی است که به ترتیب مقرر ذکر شده است.
نحو شی به شما امکان می دهد یک شی را به عنوان یک پارامتر واحد منتقل کنید و ویژگی های شیء را برای آرگومان های عملکردی که می خواهید تنظیم کنید تعریف کنید. علاوه بر این ، API ممکن است از عملکردهای اضافی پشتیبانی کند که نحو آرگومان از آن پشتیبانی نمی کند.

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

نحو بحث

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

نحو شی

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

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

cueVideoById

نحو بحث

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

نحو شی

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

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

پارامتر videoId مورد نیاز شناسه ویدیوی YouTube از ویدئویی را که باید پخش شود مشخص می کند. در API Data YouTube ، ویژگی id یک منبع video شناسه را مشخص می کند.
پارامتر اختیاری startSeconds یک شناور/عدد صحیح را می پذیرد و زمان فراخوانی playVideo() را شروع می کند. اگر مقدار startSeconds را مشخص کنید و سپس seekTo() تماس بگیرید ، بازیکن از زمان مشخص شده در تماس seekTo() بازی می کند. هنگامی که این ویدئو مورد استفاده قرار می گیرد و آماده پخش است ، پخش کننده یک رویداد video cued ( 5 ) را پخش می کند.
پارامتر اختیاری endSeconds ، که فقط در نحو شیء پشتیبانی می شود ، یک شناور/عدد صحیح را می پذیرد و زمان فراخوانی playVideo() را متوقف می کند. اگر مقدار endSeconds را مشخص کنید و سپس با seekTo() تماس بگیرید ، مقدار endSeconds دیگر عملی نخواهد شد.

loadVideoById

نحو بحث

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

نحو شی

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

این عملکرد فیلم مشخص شده را بارگیری و پخش می کند.

پارامتر videoId مورد نیاز شناسه ویدیوی YouTube از ویدئویی را که باید پخش شود مشخص می کند. در API Data YouTube ، ویژگی id یک منبع video شناسه را مشخص می کند.
پارامتر اختیاری startSeconds یک شناور/عدد صحیح را می پذیرد. در صورت مشخص شدن ، این فیلم از نزدیکترین قاب کلید تا زمان مشخص شروع می شود.
پارامتر اختیاری endSeconds یک شناور/عدد صحیح را می پذیرد. در صورت مشخص شدن ، این فیلم در زمان مشخص شده متوقف می شود.

cueVideoByUrl

نحو بحث

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

نحو شی

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

پارامتر مورد نیاز mediaContentUrl یک URL کاملاً واجد شرایط YouTube Player را در قالب http://www.youtube.com/v/VIDEO_ID?version=3 مشخص می کند.
پارامتر اختیاری startSeconds یک شناور/عدد صحیح را می پذیرد و زمان فراخوانی playVideo() را شروع می کند. اگر startSeconds مشخص کنید و سپس seekTo() تماس بگیرید ، بازیکن از زمان مشخص شده در تماس seekTo() بازی می کند. هنگامی که این ویدئو مورد استفاده قرار می گیرد و آماده پخش است ، پخش کننده یک رویداد video cued (5) را پخش می کند.
پارامتر اختیاری endSeconds ، که فقط در نحو شیء پشتیبانی می شود ، یک شناور/عدد صحیح را می پذیرد و زمان فراخوانی playVideo() را متوقف می کند. اگر مقدار endSeconds را مشخص کنید و سپس با seekTo() تماس بگیرید ، مقدار endSeconds دیگر عملی نخواهد شد.

loadVideoByUrl

نحو بحث

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

نحو شی

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

این عملکرد فیلم مشخص شده را بارگیری و پخش می کند.

پارامتر مورد نیاز mediaContentUrl یک URL کاملاً واجد شرایط YouTube Player را در قالب http://www.youtube.com/v/VIDEO_ID?version=3 مشخص می کند.
پارامتر اختیاری startSeconds یک شناور/عدد صحیح را می پذیرد و زمانی را که از آن باید شروع به پخش کند ، مشخص می کند. اگر startSeconds (شماره می تواند شناور باشد) مشخص شود ، این فیلم از نزدیکترین قاب کلید تا زمان مشخص شروع می شود.
پارامتر اختیاری endSeconds ، که فقط در نحو شیء پشتیبانی می شود ، یک شناور/عدد صحیح را می پذیرد و زمانی را مشخص می کند که فیلم باید از پخش متوقف شود.

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

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

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

cuePlaylist

نحو بحث
```
player.cuePlaylist(playlist:String|Array,
                   index:Number,
                   startSeconds:Number):Void
```
لیست پخش مشخص شده را صف می کند. هنگامی که لیست پخش و آماده بازی است ، بازیکن یک رویداد video cued ( 5 ) را پخش می کند.
- پارامتر playlist مورد نیاز مجموعه ای از شناسه های ویدیویی YouTube را مشخص می کند. در API Data YouTube ، ویژگی id منبع video شناسه آن ویدیو را مشخص می کند.
- پارامتر index اختیاری شاخص اولین فیلم در لیست پخش را نشان می دهد. این پارامتر از یک شاخص مبتنی بر صفر استفاده می کند و مقدار پارامتر پیش فرض 0 است ، بنابراین رفتار پیش فرض بارگیری و پخش اولین ویدیوی در لیست پخش است.
- پارامتر اختیاری startSeconds یک شناور/عدد صحیح را می پذیرد و زمانی را مشخص می کند که اولین فیلم در لیست پخش باید هنگام استفاده از عملکرد playVideo() شروع به پخش کند. اگر مقدار startSeconds را مشخص کنید و سپس seekTo() تماس بگیرید ، بازیکن از زمان مشخص شده در تماس seekTo() بازی می کند. اگر یک لیست پخش را نشانه گذاری کنید و سپس با عملکرد playVideoAt() تماس بگیرید ، بازیکن در ابتدای فیلم مشخص شروع به پخش می کند.
نحو شی
```
player.cuePlaylist({listType:String,
                    list:String,
                    index:Number,
                    startSeconds:Number}):Void
```
لیست های مشخص شده فیلم ها را صف می کند. این لیست می تواند یک لیست پخش یا فید فیلم های بارگذاری شده کاربر باشد. توانایی صف لیست از نتایج جستجو کاهش می یابد و از 15 نوامبر 2020 دیگر پشتیبانی نمی شود.
هنگامی که این لیست کاشته شده و آماده بازی است ، پخش کننده یک رویداد video cued ( 5 ) را پخش می کند.
- ویژگی listType اختیاری نوع فید نتایج را که بازیابی می کنید مشخص می کند. مقادیر معتبر playlist و user_uploads هستند. یک ارزش مستهلک ، search ، دیگر از 15 نوامبر 2020 پشتیبانی نمی شود. مقدار پیش فرض playlist است.
- ویژگی list مورد نیاز حاوی یک کلید است که لیست خاصی از فیلم هایی را که YouTube باید برگرداند ، مشخص می کند.
  - اگر مقدار ویژگی listType playlist است ، ویژگی list لیست پخش یا مجموعه ای از شناسه های ویدیویی را مشخص می کند. در API Data YouTube ، ویژگی id Resource playlist شناسه لیست پخش را مشخص می کند ، و ویژگی id منبع video یک شناسه ویدیویی را مشخص می کند.
  - اگر مقدار خاصیت listType user_uploads باشد ، ویژگی list کاربر را مشخص می کند که فیلم های بارگذاری شده آن بازگردانده می شود.
  - اگر مقدار ویژگی listType search است ، پس ویژگی list و جو جستجو را مشخص می کند. توجه: این عملکرد مستهلک می شود و از 15 نوامبر 2020 دیگر پشتیبانی نمی شود.
- ویژگی index اختیاری شاخص اولین ویدیوی موجود در لیستی را که پخش می کند مشخص می کند. این پارامتر از یک شاخص مبتنی بر صفر استفاده می کند و مقدار پارامتر پیش فرض 0 است ، بنابراین رفتار پیش فرض بارگیری و پخش اولین ویدیوی در لیست است.
- ویژگی startSeconds اختیاری یک شناور/عدد صحیح را می پذیرد و زمانی را که اولین ویدیوی موجود در لیست باید هنگام استفاده از عملکرد playVideo() شروع به پخش کند ، مشخص می کند. اگر مقدار startSeconds را مشخص کنید و سپس seekTo() تماس بگیرید ، بازیکن از زمان مشخص شده در تماس seekTo() بازی می کند. اگر لیستی را نشان می دهید و سپس با عملکرد playVideoAt() تماس می گیرید ، بازیکن در ابتدای فیلم مشخص شروع به پخش می کند.

loadPlaylist

نحو بحث
```
player.loadPlaylist(playlist:String|Array,
                    index:Number,
                    startSeconds:Number):Void
```
این عملکرد لیست پخش مشخص شده را بار می کند و آن را بازی می کند.
- پارامتر playlist مورد نیاز مجموعه ای از شناسه های ویدیویی YouTube را مشخص می کند. در API Data YouTube ، ویژگی id منبع video یک شناسه ویدیویی را مشخص می کند.
- پارامتر index اختیاری شاخص اولین فیلم در لیست پخش را نشان می دهد. این پارامتر از یک شاخص مبتنی بر صفر استفاده می کند و مقدار پارامتر پیش فرض 0 است ، بنابراین رفتار پیش فرض بارگیری و پخش اولین ویدیوی در لیست پخش است.
- پارامتر اختیاری startSeconds یک شناور/عدد صحیح را می پذیرد و زمانی را که اولین ویدیوی در لیست پخش باید شروع به پخش کند ، مشخص می کند.
نحو شی
```
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 یک شناسه لیست پخش یا مجموعه ای از شناسه های ویدیویی را مشخص می کند. در API Data YouTube ، ویژگی id Resource playlist ID شناسه لیست پخش را مشخص می کند ، و ویژگی id منبع video یک شناسه ویدیویی را مشخص می کند.
  - اگر مقدار خاصیت listType user_uploads باشد ، ویژگی list کاربر را مشخص می کند که فیلم های بارگذاری شده آن بازگردانده می شود.
  - اگر مقدار ویژگی listType search است ، پس ویژگی list و جو جستجو را مشخص می کند. توجه: این عملکرد مستهلک می شود و از 15 نوامبر 2020 دیگر پشتیبانی نمی شود.
- ویژگی index اختیاری شاخص اولین ویدیوی موجود در لیستی را که پخش می کند مشخص می کند. این پارامتر از یک شاخص مبتنی بر صفر استفاده می کند و مقدار پارامتر پیش فرض 0 است ، بنابراین رفتار پیش فرض بارگیری و پخش اولین ویدیوی در لیست است.
- ویژگی startSeconds اختیاری یک شناور/عدد صحیح را می پذیرد و زمانی را که اولین ویدیوی موجود در لیست باید شروع به پخش کند ، مشخص می کند.

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

پخش یک ویدیو

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

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

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

player. stopVideo ():Void: بارگیری و لغو بارگذاری ویدیوی فعلی. این عملکرد باید برای موقعیت های نادر محفوظ باشد وقتی می دانید کاربر در حال تماشای فیلم اضافی در پخش کننده نیست. اگر هدف شما مکث ویدیو است ، فقط باید با عملکرد pauseVideo تماس بگیرید. اگر می خواهید ویدیویی را که پخش کننده پخش می کند تغییر دهید ، می توانید بدون تماس با stopVideo ابتدا با یکی از توابع صف تماس بگیرید.

نکته مهم: بر خلاف عملکرد pauseVideo ، که بازیکن را در حالت paused ( 2 ) قرار می دهد ، عملکرد stopVideo می تواند بازیکن را در هر حالت بازی ناگفته قرار دهد ، از جمله ended ( 0 ) ، paused ( 2 ) ، video cued ( 5 ) یا unstarted ( -1 ).

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

به دنبال یک زمان مشخص در فیلم است. اگر بازیکن در هنگام فراخوانی عملکرد متوقف شود ، مکث می شود. اگر این عملکرد از حالت دیگری ( playing ، video cued و غیره) خوانده شود ، پخش کننده فیلم را پخش می کند.

پارامتر seconds زمان پیشرفت بازیکن را مشخص می کند.
بازیکن قبل از آن زمان به نزدیکترین کلید اصلی پیش می رود ، مگر اینکه پخش کننده بخشی از ویدیویی را که کاربر به دنبال آن است بارگیری کرده است.
پارامتر allowSeekAhead تعیین می کند که آیا بازیکن اگر پارامتر seconds زمان خارج از داده های ویدیویی بافر در حال حاضر را مشخص کند ، درخواست جدیدی را به سرور ارائه می دهد.
توصیه می کنیم این پارامتر را روی false تنظیم کنید در حالی که کاربر ماوس را در امتداد نوار پیشرفت ویدیویی می کشد و هنگام انتشار کاربر ماوس را به true تنظیم می کند. این رویکرد به کاربر امکان می دهد بدون درخواست جریان های ویدیویی جدید با پیمایش نقاط گذشته در این ویدئو ، به نقاط مختلف یک ویدیو بپردازید. هنگامی که کاربر دکمه ماوس را آزاد می کند ، پخش کننده به نقطه مورد نظر در فیلم پیشرفت می کند و در صورت لزوم درخواست جریان ویدیویی جدید می کند.

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

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

player. getSphericalProperties ():Object

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

این شیء فقط برای فیلم های 360 درجه جمع می شود ، که به آنها فیلم های کروی نیز گفته می شود.
اگر ویدیوی فعلی یک فیلم 360 درجه نیست یا اگر عملکرد از یک دستگاه بدون پشتیبانی خوانده شود ، عملکرد یک شیء خالی را برمی گرداند.
در دستگاه های تلفن همراه پشتیبانی شده ، اگر ویژگی enableOrientationSensor روی true تنظیم شده باشد ، این عملکرد شیئی را برمی گرداند که در آن ویژگی fov حاوی مقدار صحیح و سایر خصوصیات روی 0 تنظیم شده است.

شی حاوی خصوصیات زیر است:

خواص
`yaw`	یک عدد در محدوده [0 ، 360) که نشان دهنده زاویه افقی نمای در درجه ها است ، که نشان دهنده میزان اینکه کاربر تا چه اندازه نمای را به سمت چپ یا راست تبدیل می کند ، نشان می دهد. موقعیت خنثی ، روبروی مرکز فیلم در پیش بینی مساوی خود ، 0 درجه را نشان می دهد و با چرخش بیننده این مقدار افزایش می یابد.
`pitch`	تعدادی در محدوده [-90 ، 90] که نشان دهنده زاویه عمودی نمای در درجه است ، که نشان دهنده میزان تنظیم کاربر برای جستجوی بالا یا پایین است. موقعیت خنثی ، روبروی مرکز فیلم در پیش بینی مساوی خود ، 0 درجه را نشان می دهد و با نگاه بیننده این مقدار افزایش می یابد.
`roll`	یک عدد در محدوده [-180 ، 180] که نشان دهنده زاویه چرخشی جهت عقربه های ساعت یا خلاف جهت عقربه های ساعت نمای در درجه است. موقعیت خنثی ، با محور افقی در طرح ریزی مساوی موازی با محور افقی نمای ، 0 درجه را نشان می دهد. با چرخش در جهت عقربه های ساعت و با چرخش نمای در جهت عقربه های ساعت ، مقدار افزایش می یابد. توجه داشته باشید که پخش کننده تعبیه شده یک رابط کاربری برای تنظیم رول نمای ارائه نمی دهد. رول را می توان به هر یک از این روشهای منحصر به فرد تنظیم کرد: از سنسور جهت گیری در یک مرورگر موبایل استفاده کنید تا رول برای نمای فراهم شود. اگر سنسور جهت گیری فعال باشد ، عملکرد `getSphericalProperties` همیشه `0` به عنوان مقدار خاصیت `roll` باز می گرداند. اگر سنسور جهت یابی غیرفعال است ، با استفاده از این API ، رول را روی یک مقدار nonzero تنظیم کنید.
`fov`	تعدادی در محدوده [30 ، 120] که نشان دهنده میدان دید از نمای در درجه ها است که در امتداد لبه طولانی تر نمای اندازه گیری می شود. لبه کوتاه تر به طور خودکار تنظیم می شود تا متناسب با نسبت ابعاد نمای باشد. مقدار پیش فرض 100 درجه است. کاهش ارزش مانند بزرگنمایی در محتوای ویدیویی است و افزایش مقدار مانند بزرگنمایی است. این مقدار را می توان با استفاده از API یا با استفاده از ماوس چرخ هنگامی که فیلم در حالت تمام صفحه قرار دارد تنظیم کرد.

player. setSphericalProperties (properties:Object):Void

جهت گیری ویدیویی را برای پخش یک فیلم 360 درجه تنظیم می کند. (اگر ویدیوی فعلی کروی نیست ، روش بدون توجه به ورودی ، یک OP است.)

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

علاوه بر این:

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

شیء properties که به عملکرد منتقل می شود شامل خواص زیر است:

خواص
`yaw`	تعریف را در بالا مشاهده کنید.
`pitch`	تعریف را در بالا مشاهده کنید.
`roll`	تعریف را در بالا مشاهده کنید.
`fov`	See definition above.
`enableOrientationSensor`	Note: This property affects the 360° viewing experience on supported devices only. A boolean value that indicates whether the IFrame embed should respond to events that signal changes in a supported device's orientation, such as a mobile browser's `DeviceOrientationEvent` . The default parameter value is `true` . دستگاه های تلفن همراه پشتیبانی شده When the value is `true` , an embedded player relies only on the device's movement to adjust the `yaw` , `pitch` , and `roll` properties for 360° video playbacks. However, the `fov` property can still be changed via the API, and the API is, in fact, the only way to change the `fov` property on a mobile device. این رفتار پیش فرض است. When the value is `false` , then the device's movement does not affect the 360° viewing experience, and the `yaw` , `pitch` , `roll` , and `fov` properties must all be set via the API. Unsupported mobile devices The `enableOrientationSensor` property value does not have any effect on the playback experience.

Playing a video in a playlist

player. nextVideo ():Void

This function loads and plays the next video in the playlist.

If player.nextVideo() is called while the last video in the playlist is being watched, and the playlist is set to play continuously ( loop ), then the player will load and play the first video in the list.
If player.nextVideo() is called while the last video in the playlist is being watched, and the playlist is not set to play continuously, then playback will end.

player. previousVideo ():Void

This function loads and plays the previous video in the playlist.

If player.previousVideo() is called while the first video in the playlist is being watched, and the playlist is set to play continuously ( loop ), then the player will load and play the last video in the list.
If player.previousVideo() is called while the first video in the playlist is being watched, and the playlist is not set to play continuously, then the player will restart the first playlist video from the beginning.

player. playVideoAt (index:Number):Void

This function loads and plays the specified video in the playlist.

The required index parameter specifies the index of the video that you want to play in the playlist. The parameter uses a zero-based index, so a value of 0 identifies the first video in the list. If you have shuffled the playlist, this function will play the video at the specified position in the shuffled playlist.

Changing the player volume

player. mute ():Void: Mutes the player.

player. unMute ():Void: Unmutes the player.

player. isMuted ():Boolean: Returns true if the player is muted, false if not.

player. setVolume (volume:Number):Void: Sets the volume. عدد صحیح بین 0 تا 100 را می پذیرد.

player. getVolume ():Number: Returns the player's current volume, an integer between 0 and 100 . Note that getVolume() will return the volume even if the player is muted.

Setting the player size

player.setSize(width:Number, height:Number):Object: Sets the size in pixels of the <iframe> that contains the player.

Setting the playback rate

player. getPlaybackRate ():Number: This function retrieves the playback rate of the currently playing video. The default playback rate is 1 , which indicates that the video is playing at normal speed. Playback rates may include values like 0.25 , 0.5 , 1 , 1.5 , and 2 .

player. setPlaybackRate (suggestedRate:Number):Void: This function sets the suggested playback rate for the current video. If the playback rate changes, it will only change for the video that is already cued or being played. If you set the playback rate for a cued video, that rate will still be in effect when the playVideo function is called or the user initiates playback directly through the player controls. In addition, calling functions to cue or load videos or playlists ( cueVideoById , loadVideoById , etc.) will reset the playback rate to 1 .

Calling this function does not guarantee that the playback rate will actually change. However, if the playback rate does change, the onPlaybackRateChange event will fire, and your code should respond to the event rather than the fact that it called the setPlaybackRate function.

The getAvailablePlaybackRates method will return the possible playback rates for the currently playing video. However, if you set the suggestedRate parameter to a non-supported integer or float value, the player will round that value down to the nearest supported value in the direction of 1 .

player. getAvailablePlaybackRates ():Array: This function returns the set of playback rates in which the current video is available. The default value is 1 , which indicates that the video is playing in normal speed.

The function returns an array of numbers ordered from slowest to fastest playback speed. Even if the player does not support variable playback speeds, the array should always contain at least one value ( 1 ).

Setting playback behavior for playlists

player. setLoop (loopPlaylists:Boolean):Void

This function indicates whether the video player should continuously play a playlist or if it should stop playing after the last video in the playlist ends. The default behavior is that playlists do not loop.

This setting will persist even if you load or cue a different playlist, which means that if you load a playlist, call the setLoop function with a value of true , and then load a second playlist, the second playlist will also loop.

The required loopPlaylists parameter identifies the looping behavior.

If the parameter value is true , then the video player will continuously play playlists. After playing the last video in a playlist, the video player will go back to the beginning of the playlist and play it again.
If the parameter value is false , then playbacks will end after the video player plays the last video in a playlist.

player. setShuffle (shufflePlaylist:Boolean):Void

This function indicates whether a playlist's videos should be shuffled so that they play back in an order different from the one that the playlist creator designated. If you shuffle a playlist after it has already started playing, the list will be reordered while the video that is playing continues to play. The next video that plays will then be selected based on the reordered list.

This setting will not persist if you load or cue a different playlist, which means that if you load a playlist, call the setShuffle function, and then load a second playlist, the second playlist will not be shuffled.

The required shufflePlaylist parameter indicates whether YouTube should shuffle the playlist.

If the parameter value is true , then YouTube will shuffle the playlist order. If you instruct the function to shuffle a playlist that has already been shuffled, YouTube will shuffle the order again.
If the parameter value is false , then YouTube will change the playlist order back to its original order.

Playback status

player. getVideoLoadedFraction ():Float: Returns a number between 0 and 1 that specifies the percentage of the video that the player shows as buffered. This method returns a more reliable number than the now-deprecated getVideoBytesLoaded and getVideoBytesTotal methods.

player.getPlayerState():Number

Returns the state of the player. مقادیر ممکن عبارتند از:

-1 – unstarted
0 – ended
1 – playing
2 – paused
3 – buffering
5 – video cued

player. getCurrentTime ():Number: Returns the elapsed time in seconds since the video started playing.

player. getVideoStartBytes ():Number: Deprecated as of October 31, 2012. Returns the number of bytes the video file started loading from. (This method now always returns a value of 0 .) Example scenario: the user seeks ahead to a point that hasn't loaded yet, and the player makes a new request to play a segment of the video that hasn't loaded yet.

player. getVideoBytesLoaded ():Number: Deprecated as of July 18, 2012. Instead, use the getVideoLoadedFraction method to determine the percentage of the video that has buffered.

This method returns a value between 0 and 1000 that approximates the amount of the video that has been loaded. You could calculate the fraction of the video that has been loaded by dividing the getVideoBytesLoaded value by the getVideoBytesTotal value.

player. getVideoBytesTotal ():Number: Deprecated as of July 18, 2012. Instead, use the getVideoLoadedFraction method to determine the percentage of the video that has buffered.

Returns the size in bytes of the currently loaded/playing video or an approximation of the video's size.

This method always returns a value of 1000 . You could calculate the fraction of the video that has been loaded by dividing the getVideoBytesLoaded value by the getVideoBytesTotal value.

Retrieving video information

player. getDuration ():Number: Returns the duration in seconds of the currently playing video. Note that getDuration() will return 0 until the video's metadata is loaded, which normally happens just after the video starts playing.

If the currently playing video is a live event , the getDuration() function will return the elapsed time since the live video stream began. Specifically, this is the amount of time that the video has streamed without being reset or interrupted. In addition, this duration is commonly longer than the actual event time since streaming may begin before the event's start time.

player. getVideoUrl ():String: Returns the YouTube.com URL for the currently loaded/playing video.

player. getVideoEmbedCode ():String: Returns the embed code for the currently loaded/playing video.

Retrieving playlist information

player. getPlaylist ():Array: This function returns an array of the video IDs in the playlist as they are currently ordered. By default, this function will return video IDs in the order designated by the playlist owner. However, if you have called the setShuffle function to shuffle the playlist order, then the getPlaylist() function's return value will reflect the shuffled order.

player. getPlaylistIndex ():Number

This function returns the index of the playlist video that is currently playing.

If you have not shuffled the playlist, the return value will identify the position where the playlist creator placed the video. The return value uses a zero-based index, so a value of 0 identifies the first video in the playlist.
If you have shuffled the playlist, the return value will identify the video's order within the shuffled playlist.

Adding or removing an event listener

player. addEventListener (event:String, listener:String):Void: Adds a listener function for the specified event . The Events section below identifies the different events that the player might fire. The listener is a string that specifies the function that will execute when the specified event fires.

player. removeEventListener (event:String, listener:String):Void: Removes a listener function for the specified event . The listener is a string that identifies the function that will no longer execute when the specified event fires.

Accessing and modifying DOM nodes

player. getIframe ():Object: This method returns the DOM node for the embedded <iframe> .

player. destroy ():Void: Removes the <iframe> containing the player.

رویدادها

The API fires events to notify your application of changes to the embedded player. As noted in the previous section, you can subscribe to events by adding an event listener when constructing the YT.Player object , and you can also use the addEventListener function.

The API will pass an event object as the sole argument to each of those functions. The event object has the following properties:

The event's target identifies the video player that corresponds to the event.
The event's data specifies a value relevant to the event. Note that the onReady and onAutoplayBlocked events do not specify a data property.

The following list defines the events that the API fires:

onReady

This event fires whenever a player has finished loading and is ready to begin receiving API calls. Your application should implement this function if you want to automatically execute certain operations, such as playing the video or displaying information about the video, as soon as the player is ready.

The example below shows a sample function for handling this event. The event object that the API passes to the function has a target property, which identifies the player. The function retrieves the embed code for the currently loaded video, starts to play the video, and displays the embed code in the page element that has an id value of 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

This event fires whenever the player's state changes. The data property of the event object that the API passes to your event listener function will specify an integer that corresponds to the new player state. مقادیر ممکن عبارتند از:

-1 (unstarted)
0 (ended)
1 (playing)
2 (paused)
3 (buffering)
5 (video cued).

When the player first loads a video, it will broadcast an unstarted ( -1 ) event. When a video is cued and ready to play, the player will broadcast a video cued ( 5 ) event. In your code, you can specify the integer values or you can use one of the following namespaced variables:

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

onPlaybackQualityChange

This event fires whenever the video playback quality changes. It might signal a change in the viewer's playback environment. See the YouTube Help Center for more information about factors that affect playback conditions or that might cause the event to fire.

The data property value of the event object that the API passes to the event listener function will be a string that identifies the new playback quality. مقادیر ممکن عبارتند از:

small
medium
large
hd720
hd1080
highres

onPlaybackRateChange: This event fires whenever the video playback rate changes. For example, if you call the setPlaybackRate(suggestedRate) function, this event will fire if the playback rate actually changes. Your application should respond to the event and should not assume that the playback rate will automatically change when the setPlaybackRate(suggestedRate) function is called. Similarly, your code should not assume that the video playback rate will only change as a result of an explicit call to setPlaybackRate .

The data property value of the event object that the API passes to the event listener function will be a number that identifies the new playback rate. The getAvailablePlaybackRates method returns a list of the valid playback rates for the currently cued or playing video.

onError

This event fires if an error occurs in the player. The API will pass an event object to the event listener function. That object's data property will specify an integer that identifies the type of error that occurred. مقادیر ممکن عبارتند از:

2 – The request contains an invalid parameter value. For example, this error occurs if you specify a video ID that does not have 11 characters, or if the video ID contains invalid characters, such as exclamation points or asterisks.
5 – The requested content cannot be played in an HTML5 player or another error related to the HTML5 player has occurred.
100 – The video requested was not found. This error occurs when a video has been removed (for any reason) or has been marked as private.
101 – The owner of the requested video does not allow it to be played in embedded players.
150 – This error is the same as 101 . It's just a 101 error in disguise!

onApiChange

This event is fired to indicate that the player has loaded (or unloaded) a module with exposed API methods. Your application can listen for this event and then poll the player to determine which options are exposed for the recently loaded module. Your application can then retrieve or update the existing settings for those options.

The following command retrieves an array of module names for which you can set player options:

player.getOptions();

Currently, the only module that you can set options for is the captions module, which handles closed captioning in the player. Upon receiving an onApiChange event, your application can use the following command to determine which options can be set for the captions module:

player.getOptions('captions');

By polling the player with this command, you can confirm that the options you want to access are, indeed, accessible. The following commands retrieve and update module options:

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

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

The table below lists the options that the API supports:

ماژول	گزینه	توضیحات
captions	fontSize	This option adjusts the font size of the captions displayed in the player. Valid values are `-1` , `0` , `1` , `2` , and `3` . The default size is `0` , and the smallest size is `-1` . Setting this option to an integer below `-1` will cause the smallest caption size to display, while setting this option to an integer above `3` will cause the largest caption size to display.
captions	reload	This option reloads the closed caption data for the video that is playing. The value will be `null` if you retrieve the option's value. Set the value to `true` to reload the closed caption data.

onAutoplayBlocked

This event fires any time the browser blocks autoplay or scripted video playback features, collectively referred to as "autoplay". This includes playback attempted with any of the following player APIs:

autoplay parameter
loadPlaylist function
loadVideoById function
loadVideoByUrl function
playVideo function

Most browsers have policies that can block autoplay in desktop, mobile, and other environments if certain conditions are true. Instances where this policy may be triggered include unmuted playback without user interaction, or when a Permissions Policy to permit autoplay on a cross-origin iframe has not been set.

For complete details, refer to browser-specific policies ( Apple Safari / Webkit , Google Chrome , Mozilla Firefox ) and Mozilla's autoplay guide .

نمونه ها

Creating `YT.Player` objects

Example 1: Use API with existing <iframe>

In this example, an <iframe> element on the page already defines the player with which the API will be used. Note that either the player's src URL must set the enablejsapi parameter to 1 or the <iframe> element's enablejsapi attribute must be set to true .

The onPlayerReady function changes the color of the border around the player to orange when the player is ready. The onPlayerStateChange function then changes the color of the border around the player based on the current player status. For example, the color is green when the player is playing, red when paused, blue when buffering, and so forth.

This example uses the following code:

<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>

Example 2: Loud playback

This example creates a 1280px by 720px video player. The event listener for the onReady event then calls the setVolume function to adjust the volume to the highest setting.

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();
}

Example 3: This example sets player parameters to automatically play the video when it loads and to hide the video player's controls. It also adds event listeners for several events that the API broadcasts.

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

Controlling 360° videos

This example uses the following code:

<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 integration

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. The data collected through usage of this API is the app metadata (the package name, version number, and signing certificate) and a device attestation token generated by Google Play services.

The data is used to verify the application and device integrity. It is encrypted, not shared with third parties, and deleted following a fixed retention period. App developers can configure their app identity in the WebView Media Integrity API. The configuration supports an opt-out option.

تاریخچه تجدید نظر

June 24, 2024

November 20, 2023

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

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 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

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.

The IFrame player API lets you embed a YouTube video player on your website and control the player using JavaScript.

Using the API's JavaScript functions, you can queue videos for playback; play, pause, or stop those videos; adjust the player volume; or retrieve information about the video being played. You can also add event listeners that will execute in response to certain player events, such as a player state change.

This guide explains how to use the IFrame API. It identifies the different types of events that the API can send and explains how to write event listeners to respond to those events. It also details the different JavaScript functions that you can call to control the video player as well as the player parameters you can use to further customize the player.

الزامات

The user's browser must support the HTML5 postMessage feature. Most modern browsers support postMessage .

Any web page that uses the IFrame API must also implement the following JavaScript function:

onYouTubeIframeAPIReady – The API will call this function when the page has finished downloading the JavaScript for the player API, which enables you to then use the API on your page. Thus, this function might create the player objects that you want to display when the page loads.

شروع کردن

The sample HTML page below creates an embedded player that will load a video, play it for six seconds, and then stop the playback. The numbered comments in the HTML are explained in the list below the example.

<!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>

The following list provides more details about the sample above:

The <div> tag in this section identifies the location on the page where the IFrame API will place the video player. The constructor for the player object, which is described in the Loading a video player section, identifies the <div> tag by its id to ensure that the API places the <iframe> in the proper location. Specifically, the IFrame API will replace the <div> tag with the <iframe> tag.
As an alternative, you could also put the <iframe> element directly on the page. The Loading a video player section explains how to do so.
The code in this section loads the IFrame Player API JavaScript code. The example uses DOM modification to download the API code to ensure that the code is retrieved asynchronously. (The <script> tag's async attribute, which also enables asynchronous downloads, is not yet supported in all modern browsers as discussed in this Stack Overflow answer .
The onYouTubeIframeAPIReady function will execute as soon as the player API code downloads. This portion of the code defines a global variable, player , which refers to the video player you are embedding, and the function then constructs the video player object.
The onPlayerReady function will execute when the onReady event fires. In this example, the function indicates that when the video player is ready, it should begin to play.
The API will call the onPlayerStateChange function when the player's state changes, which may indicate that the player is playing, paused, finished, and so forth. The function indicates that when the player state is 1 (playing), the player should play for six seconds and then call the stopVideo function to stop the video.

Loading a video player

After the API's JavaScript code loads, the API will call the onYouTubeIframeAPIReady function, at which point you can construct a YT.Player object to insert a video player on your page. The HTML excerpt below shows the onYouTubeIframeAPIReady function from the example above:

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

The constructor for the video player specifies the following parameters:

The first parameter specifies either the DOM element or the id of the HTML element where the API will insert the <iframe> tag containing the player.
The IFrame API will replace the specified element with the <iframe> element containing the player. This 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.
The second parameter is an object that specifies player options. The object contains the following properties:
- width (number) – The width of the video player. The default value is 640 .
- height (number) – The height of the video player. The default value is 390 .
- videoId (string) – The YouTube video ID that identifies the video that the player will load.
- playerVars (object) – The object's properties identify player parameters that can be used to customize the player.
- events (object) – The object's properties identify the events that the API fires and the functions (event listeners) that the API will call when those events occur. In the example, the constructor indicates that the onPlayerReady function will execute when the onReady event fires and that the onPlayerStateChange function will execute when the onStateChange event fires.

As mentioned in the Getting started section, instead of writing an empty <div> element on your page, which the player API's JavaScript code will then replace with an <iframe> element, you could create the <iframe> tag yourself. The first example in the Examples section shows how to do this.

<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>

Note that if you do write the <iframe> tag, then when you construct the YT.Player object, you do not need to specify values for the width and height , which are specified as attributes of the <iframe> tag, or the videoId and player parameters, which are are specified in the src URL. As an extra security measure, you should also include the origin parameter to the URL, specifying the URL scheme ( http:// or https:// ) and full domain of your host page as the parameter value. While origin is optional, including it protects against malicious third-party JavaScript being injected into your page and hijacking control of your YouTube player.

For other examples on constructing video player objects, see Examples .

عملیات

To call the player API methods, you must first get a reference to the player object you wish to control. You obtain the reference by creating a YT.Player object as discussed in the Getting started and Loading a video player sections of this document.

توابع

Queueing functions

Queueing functions allow you to load and play a video, a playlist, or another list of videos. If you are using the object syntax described below to call these functions, then you can also queue or load a list of a user's uploaded videos.

The API supports two different syntaxes for calling the queueing functions.

The argument syntax requires function arguments to be listed in a prescribed order.
The object syntax lets you pass an object as a single parameter and to define object properties for the function arguments that you wish to set. In addition, the API may support additional functionality that the argument syntax does not support.

For example, the loadVideoById function can be called in either of the following ways. Note that the object syntax supports the endSeconds property, which the argument syntax does not support.

Argument syntax

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

نحو شی

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

Queueing functions for videos

cueVideoById

Argument syntax

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

نحو شی

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

This function loads the specified video's thumbnail and prepares the player to play the video. The player does not request the FLV until playVideo() or seekTo() is called.

The required videoId parameter specifies the YouTube Video ID of the video to be played. In the YouTube Data API, a video resource's id property specifies the ID.
The optional startSeconds parameter accepts a float/integer and specifies the time from which the video should start playing when playVideo() is called. If you specify a startSeconds value and then call seekTo() , then the player plays from the time specified in the seekTo() call. When the video is cued and ready to play, the player will broadcast a video cued event ( 5 ).
The optional endSeconds parameter, which is only supported in object syntax, accepts a float/integer and specifies the time when the video should stop playing when playVideo() is called. If you specify an endSeconds value and then call seekTo() , the endSeconds value will no longer be in effect.

loadVideoById

Argument syntax

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

نحو شی

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

This function loads and plays the specified video.

The required videoId parameter specifies the YouTube Video ID of the video to be played. In the YouTube Data API, a video resource's id property specifies the ID.
The optional startSeconds parameter accepts a float/integer. If it is specified, then the video will start from the closest keyframe to the specified time.
The optional endSeconds parameter accepts a float/integer. If it is specified, then the video will stop playing at the specified time.

cueVideoByUrl

Argument syntax

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

نحو شی

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

This function loads the specified video's thumbnail and prepares the player to play the video. The player does not request the FLV until playVideo() or seekTo() is called.

The required mediaContentUrl parameter specifies a fully qualified YouTube player URL in the format http://www.youtube.com/v/VIDEO_ID?version=3 .
The optional startSeconds parameter accepts a float/integer and specifies the time from which the video should start playing when playVideo() is called. If you specify startSeconds and then call seekTo() , then the player plays from the time specified in the seekTo() call. When the video is cued and ready to play, the player will broadcast a video cued event (5).
The optional endSeconds parameter, which is only supported in object syntax, accepts a float/integer and specifies the time when the video should stop playing when playVideo() is called. If you specify an endSeconds value and then call seekTo() , the endSeconds value will no longer be in effect.

loadVideoByUrl

Argument syntax

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

نحو شی

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

This function loads and plays the specified video.

The required mediaContentUrl parameter specifies a fully qualified YouTube player URL in the format http://www.youtube.com/v/VIDEO_ID?version=3 .
The optional startSeconds parameter accepts a float/integer and specifies the time from which the video should start playing. If startSeconds (number can be a float) is specified, the video will start from the closest keyframe to the specified time.
The optional endSeconds parameter, which is only supported in object syntax, accepts a float/integer and specifies the time when the video should stop playing.

Queueing functions for lists

The cuePlaylist and loadPlaylist functions allow you to load and play a playlist. If you are using object syntax to call these functions, you can also queue (or load) a list of a user's uploaded videos.

Since the functions work differently depending on whether they are called using the argument syntax or the object syntax, both calling methods are documented below.

cuePlaylist

Argument syntax
```
player.cuePlaylist(playlist:String|Array,
                   index:Number,
                   startSeconds:Number):Void
```
Queues the specified playlist. When the playlist is cued and ready to play, the player will broadcast a video cued event ( 5 ).
- The required playlist parameter specifies an array of YouTube video IDs. In the YouTube Data API, the video resource's id property identifies that video's ID.
- The optional index parameter specifies the index of the first video in the playlist that will play. The parameter uses a zero-based index, and the default parameter value is 0 , so the default behavior is to load and play the first video in the playlist.
- The optional startSeconds parameter accepts a float/integer and specifies the time from which the first video in the playlist should start playing when the playVideo() function is called. If you specify a startSeconds value and then call seekTo() , then the player plays from the time specified in the seekTo() call. If you cue a playlist and then call the playVideoAt() function, the player will start playing at the beginning of the specified video.
نحو شی
```
player.cuePlaylist({listType:String,
                    list:String,
                    index:Number,
                    startSeconds:Number}):Void
```
Queues the specified list of videos. The list can be a playlist or a user's uploaded videos feed. The ability to queue a list of search results is deprecated and will no longer be supported as of 15 November 2020 .
When the list is cued and ready to play, the player will broadcast a video cued event ( 5 ).
- The optional listType property specifies the type of results feed that you are retrieving. Valid values are playlist and user_uploads . A deprecated value, search , will no longer be supported as of 15 November 2020 . The default value is playlist .
- The required list property contains a key that identifies the particular list of videos that YouTube should return.
  - If the listType property value is playlist , then the list property specifies the playlist ID or an array of video IDs. In the YouTube Data API, the playlist resource's id property identifies a playlist's ID, and the video resource's id property specifies a video ID.
  - If the listType property value is user_uploads , then the list property identifies the user whose uploaded videos will be returned.
  - If the listType property value is search , then the list property specifies the search query. Note: This functionality is deprecated and will no longer be supported as of 15 November 2020 .
- The optional index property specifies the index of the first video in the list that will play. The parameter uses a zero-based index, and the default parameter value is 0 , so the default behavior is to load and play the first video in the list.
- The optional startSeconds property accepts a float/integer and specifies the time from which the first video in the list should start playing when the playVideo() function is called. If you specify a startSeconds value and then call seekTo() , then the player plays from the time specified in the seekTo() call. If you cue a list and then call the playVideoAt() function, the player will start playing at the beginning of the specified video.

loadPlaylist

Argument syntax
```
player.loadPlaylist(playlist:String|Array,
                    index:Number,
                    startSeconds:Number):Void
```
This function loads the specified playlist and plays it.
- The required playlist parameter specifies an array of YouTube video IDs. In the YouTube Data API, the video resource's id property specifies a video ID.
- The optional index parameter specifies the index of the first video in the playlist that will play. The parameter uses a zero-based index, and the default parameter value is 0 , so the default behavior is to load and play the first video in the playlist.
- The optional startSeconds parameter accepts a float/integer and specifies the time from which the first video in the playlist should start playing.
نحو شی
```
player.loadPlaylist({list:String,
                     listType:String,
                     index:Number,
                     startSeconds:Number}):Void
```
This function loads the specified list and plays it. The list can be a playlist or a user's uploaded videos feed. The ability to load a list of search results is deprecated and will no longer be supported as of 15 November 2020 .
- The optional listType property specifies the type of results feed that you are retrieving. Valid values are playlist and user_uploads . A deprecated value, search , will no longer be supported as of 15 November 2020 . The default value is playlist .
- The required list property contains a key that identifies the particular list of videos that YouTube should return.
  - If the listType property value is playlist , then the list property specifies a playlist ID or an array of video IDs. In the YouTube Data API, the playlist resource's id property specifies a playlist's ID, and the video resource's id property specifies a video ID.
  - If the listType property value is user_uploads , then the list property identifies the user whose uploaded videos will be returned.
  - If the listType property value is search , then the list property specifies the search query. Note: This functionality is deprecated and will no longer be supported as of 15 November 2020 .
- The optional index property specifies the index of the first video in the list that will play. The parameter uses a zero-based index, and the default parameter value is 0 , so the default behavior is to load and play the first video in the list.
- The optional startSeconds property accepts a float/integer and specifies the time from which the first video in the list should start playing.

Playback controls and player settings

پخش یک ویدیو

player. playVideo ():Void: Plays the currently cued/loaded video. The final player state after this function executes will be playing (1).

Note: A playback only counts toward a video's official view count if it is initiated via a native play button in the player.

player. pauseVideo ():Void: Pauses the currently playing video. The final player state after this function executes will be paused ( 2 ) unless the player is in the ended ( 0 ) state when the function is called, in which case the player state will not change.

player. stopVideo ():Void: Stops and cancels loading of the current video. This function should be reserved for rare situations when you know that the user will not be watching additional video in the player. If your intent is to pause the video, you should just call the pauseVideo function. If you want to change the video that the player is playing, you can call one of the queueing functions without calling stopVideo first.

Important: Unlike the pauseVideo function, which leaves the player in the paused ( 2 ) state, the stopVideo function could put the player into any not-playing state, including ended ( 0 ), paused ( 2 ), video cued ( 5 ) or unstarted ( -1 ).

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

Seeks to a specified time in the video. If the player is paused when the function is called, it will remain paused. If the function is called from another state ( playing , video cued , etc.), the player will play the video.

The seconds parameter identifies the time to which the player should advance.
The player will advance to the closest keyframe before that time unless the player has already downloaded the portion of the video to which the user is seeking.
The allowSeekAhead parameter determines whether the player will make a new request to the server if the seconds parameter specifies a time outside of the currently buffered video data.
We recommend that you set this parameter to false while the user drags the mouse along a video progress bar and then set it to true when the user releases the mouse. This approach lets a user scroll to different points of a video without requesting new video streams by scrolling past unbuffered points in the video. When the user releases the mouse button, the player advances to the desired point in the video and requests a new video stream if necessary.

Controlling playback of 360° videos

Note: The 360° video playback experience has limited support on mobile devices. On unsupported devices, 360° videos appear distorted and there is no supported way to change the viewing perspective at all, including through the API, using orientation sensors, or responding to touch/drag actions on the device's screen.

player. getSphericalProperties ():Object

Retrieves properties that describe the viewer's current perspective, or view, for a video playback. علاوه بر این:

This object is only populated for 360° videos, which are also called spherical videos.
If the current video is not a 360° video or if the function is called from a non-supported device, then the function returns an empty object.
On supported mobile devices, if the enableOrientationSensor property is set to true , then this function returns an object in which the fov property contains the correct value and the other properties are set to 0 .

The object contains the following properties:

خواص
`yaw`	A number in the range [0, 360) that 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. The neutral position, facing the center of the video in its equirectangular projection, represents 0°, and this value increases as the viewer turns left.
`pitch`	A number in the range [-90, 90] that 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. The neutral position, facing the center of the video in its equirectangular projection, represents 0°, and this value increases as the viewer looks up.
`roll`	A number in the range [-180, 180] that represents the clockwise or counterclockwise rotational angle of the view in degrees. The neutral position, with the horizontal axis in the equirectangular projection being parallel to the horizontal axis of the view, represents 0°. The value increases as the view rotates clockwise and decreases as the view rotates counterclockwise. Note that the embedded player does not present a user interface for adjusting the roll of the view. The roll can be adjusted in either of these mutually exclusive ways: Use the orientation sensor in a mobile browser to provide roll for the view. If the orientation sensor is enabled, then the `getSphericalProperties` function always returns `0` as the value of the `roll` property. If the orientation sensor is disabled, set the roll to a nonzero value using this API.
`fov`	A number in the range [30, 120] that represents the field-of-view of the view in degrees as measured along the longer edge of the viewport. The shorter edge is automatically adjusted to be proportional to the aspect ratio of the view. The default value is 100 degrees. Decreasing the value is like zooming in on the video content, and increasing the value is like zooming out. This value can be adjusted either by using the API or by using the mousewheel when the video is in fullscreen mode.

player. setSphericalProperties (properties:Object):Void

Sets the video orientation for playback of a 360° video. (If the current video is not spherical, the method is a no-op regardless of the input.)

The player view responds to calls to this method by updating to reflect the values of any known properties in the properties object. The view persists values for any other known properties not included in that object.

علاوه بر این:

If the object contains unknown and/or unexpected properties, the player ignores them.
As noted at the beginning of this section, the 360° video playback experience is not supported on all mobile devices.
By default, on supported mobile devices, this function sets only sets the fov property and does not affect the yaw , pitch , and roll properties for 360° video playbacks. See the enableOrientationSensor property below for more detail.

The properties object passed to the function contains the following properties:

خواص
`yaw`	See definition above.
`pitch`	See definition above.
`roll`	See definition above.
`fov`	See definition above.
`enableOrientationSensor`	Note: This property affects the 360° viewing experience on supported devices only. A boolean value that indicates whether the IFrame embed should respond to events that signal changes in a supported device's orientation, such as a mobile browser's `DeviceOrientationEvent` . The default parameter value is `true` . دستگاه های تلفن همراه پشتیبانی شده When the value is `true` , an embedded player relies only on the device's movement to adjust the `yaw` , `pitch` , and `roll` properties for 360° video playbacks. However, the `fov` property can still be changed via the API, and the API is, in fact, the only way to change the `fov` property on a mobile device. این رفتار پیش فرض است. When the value is `false` , then the device's movement does not affect the 360° viewing experience, and the `yaw` , `pitch` , `roll` , and `fov` properties must all be set via the API. Unsupported mobile devices The `enableOrientationSensor` property value does not have any effect on the playback experience.

Playing a video in a playlist

player. nextVideo ():Void

This function loads and plays the next video in the playlist.

If player.nextVideo() is called while the last video in the playlist is being watched, and the playlist is set to play continuously ( loop ), then the player will load and play the first video in the list.
If player.nextVideo() is called while the last video in the playlist is being watched, and the playlist is not set to play continuously, then playback will end.

player. previousVideo ():Void

This function loads and plays the previous video in the playlist.

If player.previousVideo() is called while the first video in the playlist is being watched, and the playlist is set to play continuously ( loop ), then the player will load and play the last video in the list.
If player.previousVideo() is called while the first video in the playlist is being watched, and the playlist is not set to play continuously, then the player will restart the first playlist video from the beginning.

player. playVideoAt (index:Number):Void

This function loads and plays the specified video in the playlist.

The required index parameter specifies the index of the video that you want to play in the playlist. The parameter uses a zero-based index, so a value of 0 identifies the first video in the list. If you have shuffled the playlist, this function will play the video at the specified position in the shuffled playlist.

Changing the player volume

player. mute ():Void: Mutes the player.

player. unMute ():Void: Unmutes the player.

player. isMuted ():Boolean: Returns true if the player is muted, false if not.

player. setVolume (volume:Number):Void: Sets the volume. عدد صحیح بین 0 تا 100 را می پذیرد.

player. getVolume ():Number: Returns the player's current volume, an integer between 0 and 100 . Note that getVolume() will return the volume even if the player is muted.

Setting the player size

player.setSize(width:Number, height:Number):Object: Sets the size in pixels of the <iframe> that contains the player.

Setting the playback rate

player. getPlaybackRate ():Number: This function retrieves the playback rate of the currently playing video. The default playback rate is 1 , which indicates that the video is playing at normal speed. Playback rates may include values like 0.25 , 0.5 , 1 , 1.5 , and 2 .

player. setPlaybackRate (suggestedRate:Number):Void: This function sets the suggested playback rate for the current video. If the playback rate changes, it will only change for the video that is already cued or being played. If you set the playback rate for a cued video, that rate will still be in effect when the playVideo function is called or the user initiates playback directly through the player controls. In addition, calling functions to cue or load videos or playlists ( cueVideoById , loadVideoById , etc.) will reset the playback rate to 1 .

Calling this function does not guarantee that the playback rate will actually change. However, if the playback rate does change, the onPlaybackRateChange event will fire, and your code should respond to the event rather than the fact that it called the setPlaybackRate function.

The getAvailablePlaybackRates method will return the possible playback rates for the currently playing video. However, if you set the suggestedRate parameter to a non-supported integer or float value, the player will round that value down to the nearest supported value in the direction of 1 .

player. getAvailablePlaybackRates ():Array: This function returns the set of playback rates in which the current video is available. The default value is 1 , which indicates that the video is playing in normal speed.

The function returns an array of numbers ordered from slowest to fastest playback speed. Even if the player does not support variable playback speeds, the array should always contain at least one value ( 1 ).

Setting playback behavior for playlists

player. setLoop (loopPlaylists:Boolean):Void

The required loopPlaylists parameter identifies the looping behavior.

If the parameter value is true , then the video player will continuously play playlists. After playing the last video in a playlist, the video player will go back to the beginning of the playlist and play it again.
If the parameter value is false , then playbacks will end after the video player plays the last video in a playlist.

player. setShuffle (shufflePlaylist:Boolean):Void

The required shufflePlaylist parameter indicates whether YouTube should shuffle the playlist.

If the parameter value is true , then YouTube will shuffle the playlist order. If you instruct the function to shuffle a playlist that has already been shuffled, YouTube will shuffle the order again.
If the parameter value is false , then YouTube will change the playlist order back to its original order.

Playback status

player. getVideoLoadedFraction ():Float: Returns a number between 0 and 1 that specifies the percentage of the video that the player shows as buffered. This method returns a more reliable number than the now-deprecated getVideoBytesLoaded and getVideoBytesTotal methods.

player.getPlayerState():Number

Returns the state of the player. مقادیر ممکن عبارتند از:

-1 – unstarted
0 – ended
1 – playing
2 – paused
3 – buffering
5 – video cued

player. getCurrentTime ():Number: Returns the elapsed time in seconds since the video started playing.

player. getVideoStartBytes ():Number: Deprecated as of October 31, 2012. Returns the number of bytes the video file started loading from. (This method now always returns a value of 0 .) Example scenario: the user seeks ahead to a point that hasn't loaded yet, and the player makes a new request to play a segment of the video that hasn't loaded yet.

player. getVideoBytesLoaded ():Number: Deprecated as of July 18, 2012. Instead, use the getVideoLoadedFraction method to determine the percentage of the video that has buffered.

This method returns a value between 0 and 1000 that approximates the amount of the video that has been loaded. You could calculate the fraction of the video that has been loaded by dividing the getVideoBytesLoaded value by the getVideoBytesTotal value.

player. getVideoBytesTotal ():Number: Deprecated as of July 18, 2012. Instead, use the getVideoLoadedFraction method to determine the percentage of the video that has buffered.

Returns the size in bytes of the currently loaded/playing video or an approximation of the video's size.

This method always returns a value of 1000 . You could calculate the fraction of the video that has been loaded by dividing the getVideoBytesLoaded value by the getVideoBytesTotal value.

Retrieving video information

player. getDuration ():Number: Returns the duration in seconds of the currently playing video. Note that getDuration() will return 0 until the video's metadata is loaded, which normally happens just after the video starts playing.

If the currently playing video is a live event , the getDuration() function will return the elapsed time since the live video stream began. Specifically, this is the amount of time that the video has streamed without being reset or interrupted. In addition, this duration is commonly longer than the actual event time since streaming may begin before the event's start time.

player. getVideoUrl ():String: Returns the YouTube.com URL for the currently loaded/playing video.

player. getVideoEmbedCode ():String: Returns the embed code for the currently loaded/playing video.

Retrieving playlist information

player. getPlaylist ():Array: This function returns an array of the video IDs in the playlist as they are currently ordered. By default, this function will return video IDs in the order designated by the playlist owner. However, if you have called the setShuffle function to shuffle the playlist order, then the getPlaylist() function's return value will reflect the shuffled order.

player. getPlaylistIndex ():Number

This function returns the index of the playlist video that is currently playing.

If you have not shuffled the playlist, the return value will identify the position where the playlist creator placed the video. The return value uses a zero-based index, so a value of 0 identifies the first video in the playlist.
If you have shuffled the playlist, the return value will identify the video's order within the shuffled playlist.

Adding or removing an event listener

player. addEventListener (event:String, listener:String):Void: Adds a listener function for the specified event . The Events section below identifies the different events that the player might fire. The listener is a string that specifies the function that will execute when the specified event fires.

player. removeEventListener (event:String, listener:String):Void: Removes a listener function for the specified event . The listener is a string that identifies the function that will no longer execute when the specified event fires.

Accessing and modifying DOM nodes

player. getIframe ():Object: This method returns the DOM node for the embedded <iframe> .

player. destroy ():Void: Removes the <iframe> containing the player.

رویدادها

The API will pass an event object as the sole argument to each of those functions. The event object has the following properties:

The event's target identifies the video player that corresponds to the event.
The event's data specifies a value relevant to the event. Note that the onReady and onAutoplayBlocked events do not specify a data property.

The following list defines the events that the API fires:

onReady

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

onStateChange

-1 (unstarted)
0 (ended)
1 (playing)
2 (paused)
3 (buffering)
5 (video cued).

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

onPlaybackQualityChange

small
medium
large
hd720
hd1080
highres

onPlaybackRateChange: This event fires whenever the video playback rate changes. For example, if you call the setPlaybackRate(suggestedRate) function, this event will fire if the playback rate actually changes. Your application should respond to the event and should not assume that the playback rate will automatically change when the setPlaybackRate(suggestedRate) function is called. Similarly, your code should not assume that the video playback rate will only change as a result of an explicit call to setPlaybackRate .

The data property value of the event object that the API passes to the event listener function will be a number that identifies the new playback rate. The getAvailablePlaybackRates method returns a list of the valid playback rates for the currently cued or playing video.

onError

2 – The request contains an invalid parameter value. For example, this error occurs if you specify a video ID that does not have 11 characters, or if the video ID contains invalid characters, such as exclamation points or asterisks.
5 – The requested content cannot be played in an HTML5 player or another error related to the HTML5 player has occurred.
100 – The video requested was not found. This error occurs when a video has been removed (for any reason) or has been marked as private.
101 – The owner of the requested video does not allow it to be played in embedded players.
150 – This error is the same as 101 . It's just a 101 error in disguise!

onApiChange

player.getOptions();

player.getOptions('captions');

By polling the player with this command, you can confirm that the options you want to access are, indeed, accessible. The following commands retrieve and update module options:

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

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

The table below lists the options that the API supports:

ماژول	گزینه	توضیحات
captions	fontSize	This option adjusts the font size of the captions displayed in the player. Valid values are `-1` , `0` , `1` , `2` , and `3` . The default size is `0` , and the smallest size is `-1` . Setting this option to an integer below `-1` will cause the smallest caption size to display, while setting this option to an integer above `3` will cause the largest caption size to display.
captions	reload	This option reloads the closed caption data for the video that is playing. The value will be `null` if you retrieve the option's value. Set the value to `true` to reload the closed caption data.

onAutoplayBlocked

autoplay parameter
loadPlaylist function
loadVideoById function
loadVideoByUrl function
playVideo function

نمونه ها

Creating `YT.Player` objects

Example 1: Use API with existing <iframe>

This example uses the following code:

<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>

Example 2: Loud playback

This example creates a 1280px by 720px video player. The event listener for the onReady event then calls the setVolume function to adjust the volume to the highest setting.

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();
}

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

Controlling 360° videos

This example uses the following code:

<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 integration

تاریخچه تجدید نظر

June 24, 2024

November 20, 2023

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

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 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

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 درجه

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

تاریخچه تجدید نظر

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

الزامات

شروع کردن

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

عملیات

توابع

توابع صف

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

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

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

پخش یک ویدیو

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

Playing a video in a playlist

Changing the player volume

Setting the player size

Setting the playback rate

Setting playback behavior for playlists

Playback status

Retrieving video information

Retrieving playlist information

Adding or removing an event listener

Accessing and modifying DOM nodes

رویدادها

نمونه ها

Creating YT.Player objects

Controlling 360° videos

Android WebView Media Integrity API integration

تاریخچه تجدید نظر

June 24, 2024

November 20, 2023

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

Creating `YT.Player` objects

Creating `YT.Player` objects