تمت ترجمة هذه الصفحة بواسطة Cloud Translation API‏.

YouTube Player API Reference for iframe Embeds

تتيح لك واجهة برمجة تطبيقات مشغّل IFrame تضمين مشغّل فيديو YouTube على موقعك الإلكتروني والتحكم في المشغّل باستخدام JavaScript.

باستخدام وظائف JavaScript لواجهة برمجة التطبيقات، يمكنك وضع الفيديوهات في قائمة انتظار للتشغيل أو تشغيلها أو إيقافها مؤقتًا أو إيقافها أو ضبط مستوى صوت المشغّل أو استرداد معلومات حول الفيديو الذي يتم تشغيله. ويمكنك أيضًا إضافة أدوات معالجة الأحداث التي سيتم تنفيذها استجابةً لأحداث معيّنة خاصة باللاعب، مثل تغيير حالة اللاعب.

يشرح هذا الدليل كيفية استخدام واجهة برمجة تطبيقات IFrame. وتحدِّد الأنواع المختلفة من الأحداث التي يمكن لواجهة برمجة التطبيقات إرسالها وتوضّح كيفية كتابة أدوات معالجة الأحداث للاستجابة لهذه الأحداث. ويوضّح أيضًا وظائف JavaScript المختلفة التي يمكنك طلبها للتحكّم في مشغّل الفيديو، بالإضافة إلى معلَمات المشغّل التي يمكنك استخدامها لتخصيص المشغّل بشكل أكبر.

المتطلّبات

يجب أن يتيح متصفّح المستخدم ميزة postMessage HTML5. تتيح معظم المتصفحات الحديثة استخدام postMessage.

يجب أن تحتوي المشغّلات المضمّنة على إطار عرض أبعاده 200 × 200 بكسل على الأقل. إذا كان المشغّل يعرض عناصر التحكّم، يجب أن يكون كبيرًا بما يكفي لعرض عناصر التحكّم بالكامل بدون تقليص إطار العرض إلى ما يقلّ عن الحد الأدنى للحجم. نوصي بأن تكون المشغّلات بنسبة 16:9 بعرض 480 بكسل وبطول 270 بكسل على الأقل.

يجب أيضًا على أي صفحة ويب تستخدم واجهة برمجة تطبيقات IFrame تنفيذ وظيفة JavaScript التالية:

onYouTubeIframeAPIReady – ستستدعي واجهة برمجة التطبيقات هذه الوظيفة عند انتهاء الصفحة من تنزيل JavaScript لواجهة برمجة تطبيقات المشغّل، والتي تمكّنك بعد ذلك من استخدام واجهة برمجة التطبيقات على صفحتك. وبالتالي، قد تنشئ هذه الدالة كائنات المشغّل التي تريد عرضها عند تحميل الصفحة.

البدء

تعمل صفحة نموذج 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. تحدد الدالة الإنشائية لكائن المشغِّل، الموضحة في القسم تحميل مشغّل فيديو، العلامة <div> من خلال id لضمان أن واجهة برمجة التطبيقات تضع <iframe> في المكان الصحيح. وعلى وجه التحديد، ستستبدل واجهة برمجة التطبيقات IFrame العلامة <div> بالعلامة <iframe>.

يمكنك بدلاً من ذلك وضع العنصر <iframe> مباشرةً على الصفحة. ويوضّح القسم تحميل مشغّل فيديو كيفية إجراء ذلك.
يحمِّل الرمز في هذا القسم رمز JavaScript لواجهة برمجة تطبيقات IFrame Player. يستخدم المثال تعديل DOM لتنزيل رمز واجهة برمجة التطبيقات لضمان استرداد الرمز بشكل غير متزامن. (إنّ السمة async للعلامة <script>، والتي تتيح أيضًا عمليات التنزيل غير المتزامنة، غير متاحة حتى الآن في جميع المتصفحات الحديثة، كما هو موضّح في إجابة Stack Overflow هذه.
سيتم تنفيذ الدالة onYouTubeIframeAPIReady فور تنزيل رمز واجهة برمجة تطبيقات المشغّل. يحدّد هذا الجزء من الرمز المتغيّر العام player الذي يشير إلى مشغّل الفيديو الذي تريد تضمينه، ثم تنشئ الدالة كائن مشغّل الفيديو.
سيتم تنفيذ الدالة onPlayerReady عند تنشيط حدث onReady. في هذا المثال، تشير الدالة إلى أنّه عندما يكون مشغّل الفيديو جاهزًا، يجب أن يبدأ تشغيله.
ستستدعي واجهة برمجة التطبيقات الوظيفة onPlayerStateChange عندما تتغيّر حالة المشغّل، ما قد يشير إلى أنّ المشغّل قيد التشغيل أو متوقف مؤقتًا أو انتهى، وما إلى ذلك. وتشير الدالة إلى أنه عندما تكون حالة المشغّل 1 (قيد التشغيل)، يجب أن يتم تشغيل المشغّل لمدة ست ثوانٍ، ثم يستدعي وظيفة stopVideo لإيقاف الفيديو.

تحميل مشغّل فيديو

بعد تحميل رمز JavaScript لواجهة برمجة التطبيقات، ستستدعي واجهة برمجة التطبيقات الوظيفة 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 حيث ستُدرج واجهة برمجة التطبيقات العلامة <iframe> التي تحتوي على المشغّل.

ستستبدل واجهة برمجة تطبيقات IFrame العنصر المحدد بالعنصر <iframe> الذي يشتمل على المشغّل. قد يؤثر ذلك في تنسيق صفحتك إذا كان العنصر الذي يتم استبداله له نمط عرض مختلف عن عنصر <iframe> المدرج. يتم عرض <iframe> تلقائيًا كعنصر inline-block.
المعلمة الثانية عبارة عن كائن يحدد خيارات المشغّل. يحتوي الكائن على السمات التالية:
- width (رقم) – عرض مشغّل الفيديو القيمة التلقائية هي 640.
- height (رقم) – ارتفاع مشغّل الفيديو القيمة التلقائية هي 390.
- videoId (سلسلة) – معرّف فيديو YouTube الذي يحدد الفيديو الذي سيحمّله المشغّل.
- playerVars (كائن) – تحدد خصائص الكائن معلَمات المشغّل التي يمكن استخدامها لتخصيص المشغّل.
- events (الكائن) – تحدد خصائص العنصر الأحداث التي تنشطها واجهة برمجة التطبيقات والوظائف (أدوات معالجة الأحداث) التي ستستدعيها واجهة برمجة التطبيقات عند وقوع هذه الأحداث. في المثال، تشير الدالة الإنشائية إلى أنه سيتم تنفيذ الدالة onPlayerReady عند تنشيط الحدث onReady وأنّ الدالة onPlayerStateChange سيتم تنفيذها عند تنشيط حدث onStateChange.

كما هو مذكور في قسم البدء، يمكنك إنشاء علامة <iframe> بنفسك بدلاً من كتابة عنصر <div> فارغ على صفحتك ليتم بعد ذلك استبدال رمز JavaScript لواجهة برمجة تطبيقات المشغّل بعنصر <iframe>. يوضح المثال الأول في قسم الأمثلة كيفية إجراء ذلك.

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

يُرجى العِلم أنّه إذا كتبت العلامة <iframe>، لن تحتاج عند إنشاء الكائن YT.Player إلى تحديد قيم للسمة width وheight التي يتم تحديدها كسمات للعلامة <iframe>، أو معلَمتَي videoId ومشغّل التطبيقات المحدّدة في عنوان URL للسمة src. كإجراء أمني إضافي، يجب أيضًا تضمين المَعلمة origin في عنوان URL، مع تحديد مخطط عنوان URL (http:// أو https://) والنطاق الكامل لصفحة المضيف كقيمة المَعلمة. إنّ origin اختيارية، إلا أنّها تحمي مشغِّلها من محتوى JavaScript ضار من جهة خارجية يتم تضمينها في صفحتك ومن إمكانية اختراق مشغِّل YouTube.

يعرض قسم الأمثلة أيضًا أمثلة أخرى لإنشاء كائنات مشغّل الفيديو.

العمليات

لاستدعاء طرق واجهة برمجة تطبيقات المشغّل، يجب أولاً الحصول على مرجع لكائن المشغّل الذي تريد التحكّم فيه. ويمكنك الحصول على المرجع من خلال إنشاء عنصر YT.Player كما هو موضّح في القسمين البدء وتحميل مشغّل فيديو من هذا المستند.

الدوال

دوال الإضافة في قائمة المحتوى التالي

تتيح لك وظائف الإضافة إلى قائمة المحتوى التالي تحميل فيديو أو قائمة تشغيل أو قائمة أخرى من الفيديوهات وتشغيلها. إذا كنت تستخدم بنية الكائن الموضحة أدناه لاستدعاء هذه الدوال، يمكنك أيضًا وضع قائمة انتظار أو تحميل قائمة بالفيديوهات التي حمّلها المستخدم.

تدعم واجهة برمجة التطبيقات بناءي جملة مختلفين لاستدعاء دوال قائمة الانتظار.

يتطلب بناء جملة الوسيطة أن يتم إدراج وسيطات الدوال بترتيب محدد.
تتيح لك بنية الكائن تمرير كائن كمعلمة واحدة وتحديد خصائص الكائن لوسيطات الدالة التي تريد تعيينها. وبالإضافة إلى ذلك، قد توفّر واجهة برمجة التطبيقات وظائف إضافية لا تتوافق معها بنية الوسيطة.

على سبيل المثال، يمكن استدعاء الدالة loadVideoById بإحدى الطريقتين التاليتين. يُرجى العِلم أنّ بنية الكائن تتوافق مع السمة endSeconds، والتي لا تتيحها بنية الوسيطة.

بنية الوسيطة

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

بنية الكائن

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

دوالّ إضافة الفيديوهات إلى "قائمة المحتوى التالي"

cueVideoById

بنية الوسيطة

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

بنية الكائن

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

تعمل هذه الوظيفة على تحميل الصورة المصغّرة للفيديو المحدد وإعداد المشغّل لتشغيل الفيديو. لا يطلب المشغّل FLV حتى يتم استدعاء playVideo() أو seekTo().

تحدد معلمة videoId المطلوبة معرّف فيديو YouTube للفيديو الذي سيتم تشغيله. في YouTube Data API، تحدّد السمة id لمورد video المعرّف.
تقبل المعلمة startSeconds الاختيارية عددًا عائمًا/عددًا صحيحًا وتحدد الوقت الذي يجب أن يبدأ فيه تشغيل الفيديو عند استدعاء playVideo(). إذا حدّدت قيمة startSeconds ثم طلبت seekTo()، سيتم تشغيل المشغّل من الوقت المحدّد في مكالمة seekTo(). عندما يتم اختيار الفيديو ليكون جاهزًا للتشغيل، سيبث المشغّل حدث video cued (5).
تقبل المعلَمة الاختيارية endSeconds، والمتاحة فقط في بنية الكائن، عددًا عائمًا/عددًا صحيحًا وتحدّد الوقت الذي يجب أن يتوقّف فيه تشغيل الفيديو عند استدعاء playVideo(). إذا حدّدت قيمة endSeconds ثم طلبت seekTo()، لن تسري قيمة endSeconds بعد ذلك.

loadVideoById

بنية الوسيطة

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

بنية الكائن

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

تعمل هذه الدالة على تحميل الفيديو المحدّد وتشغيله.

تحدد معلمة videoId المطلوبة معرّف فيديو YouTube للفيديو الذي سيتم تشغيله. في YouTube Data API، تحدّد السمة id لمورد video المعرّف.
تقبل المعلَمة startSeconds الاختيارية عددًا عشريًا/عددًا صحيحًا. وفي حال تحديد ذلك، سيبدأ الفيديو من أقرب إطار رئيسي إلى الوقت المحدد.
تقبل المعلَمة endSeconds الاختيارية عددًا عشريًا/عددًا صحيحًا. وإذا تم تحديد هذه السياسة، فسيتوقف تشغيل الفيديو في الوقت المحدد.

cueVideoByUrl

بنية الوسيطة

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

بنية الكائن

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

تحدّد المعلَمة mediaContentUrl المطلوبة عنوان URL لمشغّل YouTube المؤهل بالكامل بالتنسيق http://www.youtube.com/v/VIDEO_ID?version=3.
تقبل المعلمة startSeconds الاختيارية عددًا عائمًا/عددًا صحيحًا وتحدد الوقت الذي يجب أن يبدأ فيه تشغيل الفيديو عند استدعاء playVideo(). إذا حدّدت startSeconds ثم طلبت seekTo()، سيتم تشغيل المشغّل من الوقت المحدّد في مكالمة seekTo(). عندما يتم اختيار الفيديو ليكون جاهزًا للتشغيل، سيبث المشغّل حدث video cued (5).
تقبل المعلَمة الاختيارية endSeconds، والمتاحة فقط في بنية الكائن، عددًا عائمًا/عددًا صحيحًا وتحدّد الوقت الذي يجب أن يتوقّف فيه تشغيل الفيديو عند استدعاء playVideo(). إذا حدّدت قيمة endSeconds ثم طلبت seekTo()، لن تسري قيمة endSeconds بعد ذلك.

loadVideoByUrl

بنية الوسيطة

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

بنية الكائن

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

تعمل هذه الدالة على تحميل الفيديو المحدّد وتشغيله.

تحدّد المعلَمة mediaContentUrl المطلوبة عنوان URL لمشغّل YouTube المؤهل بالكامل بالتنسيق http://www.youtube.com/v/VIDEO_ID?version=3.
تقبل المعلمة startSeconds الاختيارية عددًا عشريًا/عددًا صحيحًا وتحدد الوقت الذي يجب بدء تشغيل الفيديو منه. إذا تم تحديد startSeconds (يمكن أن يكون الرقم عددًا عشريًا)، سيبدأ الفيديو من أقرب إطار رئيسي إلى الوقت المحدد.
تقبل المعلمة endSeconds الاختيارية، والمتاحة فقط في بنية الكائن، عددًا عائمًا/عددًا صحيحًا وتحدد الوقت الذي يجب أن يتوقّف فيه تشغيل الفيديو.

دوال قائمة المحتوى التالي للقوائم

تتيح لك الدالتان cuePlaylist وloadPlaylist تحميل قائمة تشغيل وتشغيلها. إذا كنت تستخدم بنية كائن لاستدعاء هذه الدوال، يمكنك أيضًا وضع قائمة (أو تحميل) قائمة بالفيديوهات التي حمّلها المستخدم إلى قائمة الانتظار.

نظرًا لأن الدوال تعمل بشكل مختلف اعتمادًا على ما إذا كان يتم استدعاؤها باستخدام بناء جملة الوسيطة أو بناء جملة الكائن، فسيتم توثيق كلتا طريقتي الاستدعاء أدناه.

cuePlaylist

بنية الوسيطة
```
player.cuePlaylist(playlist:String|Array,
                   index:Number,
                   startSeconds:Number):Void
```
يضع قائمة التشغيل المحددة في قائمة الانتظار. عندما يتم إعداد قائمة التشغيل وتكون جاهزة للتشغيل، سيبث المشغّل حدث video cued (5).
- تحدّد المعلَمة playlist المطلوبة مجموعة من معرّفات الفيديوهات على YouTube. في YouTube Data API، تحدّد السمة id لمورد video معرّف الفيديو.
- تحدد المعلمة index الاختيارية فهرس أول فيديو في قائمة التشغيل التي سيتم تشغيلها. تستخدم المعلمة فهرسًا مستندًا إلى صفر، وقيمة المعلمة التلقائية هي 0، لذلك يكون السلوك التلقائي هو تحميل أول فيديو في قائمة التشغيل وتشغيله.
- تقبل المعلمة startSeconds الاختيارية عددًا عائمًا/عددًا صحيحًا وتحدد الوقت الذي يجب أن يبدأ فيه أول فيديو في قائمة التشغيل عند استدعاء الدالة playVideo(). إذا حدّدت قيمة startSeconds ثم طلبت seekTo()، سيتم تشغيل المشغّل من الوقت المحدّد في مكالمة seekTo(). إذا أرسلت قائمة تشغيل ثم طلبت الدالة playVideoAt()، سيبدأ المشغّل في التشغيل في بداية الفيديو المحدّد.
بنية الكائن
يضيف
```
player.cuePlaylist({listType:String,
                    list:String,
                    index:Number,
                    startSeconds:Number}):Void
```
قائمة الفيديوهات المحددة إلى قائمة المحتوى التالي. ويمكن أن تكون القائمة قائمة تشغيل أو خلاصة فيديوهات حمّلها مستخدم. إنّ إمكانية إضافة قائمة نتائج البحث إلى قائمة المحتوى التالي متوقّفة ولن تعود متاحة اعتبارًا من 15 تشرين الثاني (نوفمبر) 2020.
عندما يتم إعداد القائمة وتكون جاهزة للتشغيل، سيبث المشغّل حدث video cued (5).
- تحدّد السمة listType الاختيارية نوع خلاصة النتائج التي تريد استردادها. القيمتان الصالحتان هما playlist وuser_uploads. لن تتوفّر القيمة المتوقّفة نهائيًا، 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 عددًا عشريًا/عددًا صحيحًا وتحدد الوقت الذي يجب أن يبدأ فيه أول فيديو في القائمة عند استدعاء الدالة playVideo(). إذا حدّدت قيمة startSeconds ثم طلبت seekTo()، سيتم تشغيل المشغّل من الوقت المحدّد في مكالمة seekTo(). إذا أرسلت قائمة ثم طلبت الدالة playVideoAt()، سيبدأ المشغّل في التشغيل في بداية الفيديو المحدّد.

loadPlaylist

بنية الوسيطة
```
player.loadPlaylist(playlist:String|Array,
                    index:Number,
                    startSeconds:Number):Void
```
تُحمِّل هذه الدالة قائمة التشغيل المحدّدة وتشغِّلها.
- تحدّد المعلَمة playlist المطلوبة مجموعة من معرّفات الفيديوهات على YouTube. في YouTube Data API، تحدّد السمة id لمورد video معرّف الفيديو.
- تحدد المعلمة index الاختيارية فهرس أول فيديو في قائمة التشغيل التي سيتم تشغيلها. تستخدم المعلمة فهرسًا مستندًا إلى صفر، وقيمة المعلمة التلقائية هي 0، لذلك يكون السلوك التلقائي هو تحميل أول فيديو في قائمة التشغيل وتشغيله.
- تقبل المعلمة startSeconds الاختيارية عددًا عائمًا/عددًا صحيحًا وتحدد الوقت الذي يجب أن يبدأ فيه تشغيل أول فيديو في قائمة التشغيل.
بنية الكائن
```
player.loadPlaylist({list:String,
                     listType:String,
                     index:Number,
                     startSeconds:Number}):Void
```
تُحمِّل هذه الدالة القائمة المحدَّدة وتشغِّلها. ويمكن أن تكون القائمة قائمة تشغيل أو خلاصة فيديوهات حمّلها مستخدم. إنّ إمكانية تحميل قائمة نتائج البحث متوقّفة ولن تتوفّر اعتبارًا من 15 تشرين الثاني (نوفمبر) 2020.
- تحدّد السمة listType الاختيارية نوع خلاصة النتائج التي تريد استردادها. القيمتان الصالحتان هما playlist وuser_uploads. لن تتوفّر القيمة المتوقّفة نهائيًا، 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 عددًا عشريًا/عددًا صحيحًا وتحدّد الوقت الذي يجب أن يبدأ فيه تشغيل أول فيديو في القائمة.

عناصر التحكّم في التشغيل وإعدادات المشغّل

تشغيل فيديو

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 درجة مشوهة ولا تتوفّر طريقة متاحة لتغيير منظور العرض على الإطلاق، بما في ذلك من خلال واجهة برمجة التطبيقات أو استخدام أدوات استشعار الاتجاه أو الاستجابة لإجراءات اللمس/السحب على شاشة الجهاز.

player.getSphericalProperties():Object

استرداد الخصائص التي تصف وجهة نظر المُشاهد الحالية أو طريقة المشاهدة الحالية لتشغيل فيديو بالإضافة إلى ذلك:

وتتم تعبئة هذا العنصر للفيديوهات بنطاق 360 درجة فقط، والتي تُسمّى أيضًا الفيديوهات بنطاق كروي.
إذا لم يكن الفيديو الحالي فيديو بنطاق 360 درجة أو إذا تم استدعاء الوظيفة من جهاز غير متوافق، تعرِض الدالة عنصرًا فارغًا.
على الأجهزة الجوّالة المتوافقة، إذا تم ضبط السمة enableOrientationSensor على true، تعرض هذه الدالة عنصرًا حيث تحتوي السمة fov على القيمة الصحيحة ويتم ضبط السمات الأخرى على 0.

يحتوي الكائن على السمات التالية:

أماكن إقامة
`yaw`	رقم في النطاق [0، 360) يمثل الزاوية الأفقية للعرض بالدرجات، والتي تعكس مدى تدوير المستخدم للعرض باتجاه اليسار أو اليمين أكثر. يمثل الموضع المحايد، المواجه لمركز الفيديو بإسقاطه المتساوي المستطيلات، 0 درجة وتزداد هذه القيمة كلما اتّجه المشاهد إلى اليسار.
`pitch`	رقم في النطاق [-90، 90] يمثل الزاوية الرأسية للعرض بالدرجات، ويعكس مدى تعديل المستخدم للعرض لينظر لأعلى أو لأسفل. يمثل الموضع المحايد، المواجه لمركز الفيديو بإسقاطه المتساوي المستطيلات، 0 درجة وتزداد هذه القيمة عندما ينظر المشاهد إلى الأعلى.
`roll`	رقم في النطاق [-180، 180] يمثل زاوية الدوران في اتجاه عقارب الساعة أو عكس اتجاه عقارب الساعة للعرض بالدرجات. يمثل الموضع المحايد 0 درجة، مع تدوير المحور الأفقي في الإسقاط المتساوي المستطيلات للمحور الأفقي للعرض. وتزيد القيمة كلما دورت العرض في اتجاه عقارب الساعة وتنخفض مع تدوير العرض عكس اتجاه عقارب الساعة. تجدر الإشارة إلى أنّ المشغّل المضمّن لا يقدّم واجهة مستخدم لضبط قائمة التشغيل في قسم العرض. يمكن تعديل قائمة التشغيل باستخدام إحدى الطريقتَين التاليتَين التبادليتَين: استخدم أداة استشعار الاتجاه في متصفح الجوال لتوفير العرض. إذا تم تفعيل أداة استشعار الاتجاه، تعرض الدالة `getSphericalProperties` دائمًا القيمة `0` كقيمة للسمة `roll`. إذا تم إيقاف أداة استشعار الاتجاه، اضبط اللفة على قيمة غير صفرية باستخدام واجهة برمجة التطبيقات هذه.
`fov`	رقم في النطاق [30، 120] يمثل مجال رؤية العرض بالدرجات كما يتم قياسه على طول الحافة الأطول لإطار العرض. ويتم ضبط الحافة الأقصر تلقائيًا لتصبح متناسبة مع نسبة العرض إلى الارتفاع للعرض. القيمة التلقائية هي 100 درجة. إنّ تقليل القيمة يشبه تكبير محتوى الفيديو، وتشبه زيادة القيمة ميزة التصغير. يمكن تعديل هذه القيمة إما باستخدام واجهة برمجة التطبيقات أو باستخدام عجلة الماوس عندما يكون الفيديو في وضع ملء الشاشة.

player.setSphericalProperties(properties:Object):Void

يضبط هذا الخيار اتجاه الفيديو لتشغيل فيديو بنطاق 360 درجة. (إذا لم يكن الفيديو الحالي كرويًا، تكون الطريقة عبارة عن بيئة مستقلة بغض النظر عن الإدخال.)

تستجيب طريقة عرض المشغّل لاستدعاء هذه الطريقة من خلال إجراء تعديل عليها لتعكس قيم أي خصائص معروفة في الكائن properties. ويحتفظ الملف الشخصي بقيم أي سمات معروفة أخرى غير مضمّنة في هذا الكائن.

بالإضافة إلى ذلك:

إذا كان الكائن يحتوي على خصائص غير معروفة و/أو غير متوقعة، سيتجاهلها المشغّل.
كما هو موضّح في بداية هذا القسم، إنّ تجربة تشغيل الفيديو بنطاق 360 درجة لا تتوفّر على كلّ الأجهزة الجوّالة.
تضبط هذه الدالة السمة fov فقط على الأجهزة الجوّالة المتوافقة ولا تؤثر في السمات yaw وpitch وroll لتشغيل الفيديوهات بنطاق 360 درجة. اطّلِع على سمة "enableOrientationSensor" أدناه لمعرفة المزيد من التفاصيل.

يحتوي الكائن properties الذي تم تمريره إلى الدالة على السمات التالية:

أماكن إقامة
`yaw`	اطّلِع على التعريف أعلاه.
`pitch`	اطّلِع على التعريف أعلاه.
`roll`	اطّلِع على التعريف أعلاه.
`fov`	اطّلِع على التعريف أعلاه.
`enableOrientationSensor`	ملاحظة: تؤثر هذه السمة في تجربة العرض بزاوية 360 درجة على الأجهزة المتوافقة فقط.قيمة منطقية تشير إلى ما إذا كان يجب أن يستجيب تضمين IFrame للأحداث التي تشير إلى تغييرات في اتجاه الجهاز المتوافق، مثل `DeviceOrientationEvent` لمتصفِّح الأجهزة الجوّالة. قيمة المَعلمة التلقائية هي `true`. الأجهزة الجوّالة المتوافقة عندما تكون القيمة `true`، يعتمد المشغّل المضمّن فقط على حركة الجهاز لضبط السمات `yaw` و`pitch` و`roll` لتشغيل الفيديوهات بنطاق 360 درجة. في المقابل، ما زال بإمكانك تغيير سمة `fov` من خلال واجهة برمجة التطبيقات، علمًا بأنّ هذه الواجهة هي في الواقع الطريقة الوحيدة لتغيير سمة `fov` على جهاز جوّال. وهذا هو الخيار التلقائي. وعندما تكون القيمة `false`، لن تؤثر حركة الجهاز في تجربة العرض بزاوية 360 درجة، ويجب ضبط جميع الخصائص `yaw` و`pitch` و`roll` و`fov` من خلال واجهة برمجة التطبيقات. الأجهزة الجوّالة غير المتوافقة لن يكون لقيمة السمة `enableOrientationSensor` أي تأثير في تجربة التشغيل.

تشغيل فيديو في قائمة تشغيل

player.nextVideo():Void

تعمل هذه الدالة على تحميل الفيديو التالي في قائمة التشغيل وتشغيله.

إذا تم استدعاء player.nextVideo() أثناء مشاهدة آخر فيديو في قائمة التشغيل، وتم ضبط قائمة التشغيل على التشغيل المستمر (loop)، سيحمّل المشغّل أول فيديو في القائمة ويشغّله.
إذا تم الاتصال بـ player.nextVideo() أثناء مشاهدة آخر فيديو في قائمة التشغيل، ولم يتم ضبط قائمة التشغيل على التشغيل بشكل مستمر، ستنتهي عملية التشغيل.

player.previousVideo():Void

تعمل هذه الدالة على تحميل الفيديو السابق في قائمة التشغيل وتشغيله.

إذا تم استدعاء player.previousVideo() أثناء مشاهدة أول فيديو في قائمة التشغيل، وتم ضبط قائمة التشغيل على التشغيل المستمر (loop)، سيحمّل المشغّل آخر فيديو في القائمة ويشغّله.
وإذا استدعيت player.previousVideo() أثناء مشاهدة أول فيديو في قائمة التشغيل ولم يتم ضبط قائمة التشغيل لتشغيلها بشكل مستمر، سيعيد المشغّل تشغيل فيديو قائمة التشغيل الأول من البداية.

player.playVideoAt(index:Number):Void

تعمل هذه الدالة على تحميل الفيديو المحدّد في قائمة التشغيل وتشغيله.

تحدد معلمة index المطلوبة فهرس الفيديو الذي تريد تشغيله في قائمة التشغيل. تستخدم المعلمة فهرسًا مستندًا إلى صفر، لذلك تحدد القيمة 0 أول فيديو في القائمة. إذا أجريت ترتيبًا عشوائيًا لقائمة التشغيل، ستشغّل هذه الدالة الفيديو في الموضع المحدد في قائمة التشغيل التي تم ترتيبها عشوائيًا.

تغيير مستوى صوت المشغّل

player.mute():Void: كتم صوت المشغّل.

player.unMute():Void: إعادة صوت المشغّل.

player.isMuted():Boolean: يتم عرض true إذا تم كتم صوت المشغّل، وfalse إذا لم يتم كتم الصوت.

player.setVolume(volume:Number):Void: لضبط مستوى الصوت. تقبل عددًا صحيحًا بين 0 و100.

player.getVolume():Number: لعرض مستوى الصوت الحالي للمشغّل، وهو عدد صحيح بين 0 و100. تجدر الإشارة إلى أنّ "getVolume()" سيعرض مستوى الصوت حتى إذا تم كتم صوت المشغّل.

ضبط حجم المشغّل

player.setSize(width:Number, height:Number):Object: تضبط حجم الصورة <iframe> التي تتضمّن المشغّل بالبكسل.

ضبط معدل التشغيل

player.getPlaybackRate():Number: تسترد هذه الدالة معدل تشغيل الفيديو الذي يتم تشغيله حاليًا. إنّ معدل التشغيل التلقائي هو 1، ما يشير إلى أنّه يتم تشغيل الفيديو بالسرعة العادية. قد تشمل معدّلات التشغيل قيمًا مثل 0.25 و0.5 و1 و1.5 و2.

player.setPlaybackRate(suggestedRate:Number):Void: تضبط هذه الدالة معدّل التشغيل المقترَح للفيديو الحالي. وإذا تغيّر معدّل التشغيل، سيتغير معدّل التشغيل فقط للفيديو الذي تم تشغيله أو الذي يتم تشغيله. وإذا حددت معدل التشغيل لفيديو مميز، فسيظل هذا المعدل ساريًا عند طلب الوظيفة playVideo أو عند بدء المستخدم للتشغيل مباشرةً من خلال عناصر التحكم في المشغّل. بالإضافة إلى ذلك، عند استدعاء دوال إنشاء الفيديوهات أو قوائم التشغيل أو تحميلها (cueVideoById أو loadVideoById أو غير ذلك)، ستتم إعادة ضبط معدل التشغيل على 1.

لا يضمن طلب هذه الدالة تغيير معدل التشغيل فعليًا. ومع ذلك، إذا تغيّر معدل التشغيل، سيتم تنشيط الحدث onPlaybackRateChange، ومن المفترض أن يستجيب الرمز للحدث بدلاً من استدعائه للدالة setPlaybackRate.

ستعرض الطريقة getAvailablePlaybackRates معدلات التشغيل المحتمَلة للفيديو الذي يتم تشغيله حاليًا. ومع ذلك، إذا ضبطت المَعلمة suggestedRate على عدد صحيح أو قيمة عائمة غير متوافقة، سيقرّب المشغّل هذه القيمة إلى أقرب قيمة مسموح بها باتجاه 1.

player.getAvailablePlaybackRates():Array: تعرض هذه الدالة مجموعة معدلات التشغيل التي يتوفّر بها الفيديو الحالي. إنّ القيمة التلقائية هي 1، ما يعني أنّه يتم تشغيل الفيديو بالسرعة العادية.

تعرض الدالة صفيفًا من الأرقام مرتبة من الأبطأ إلى أسرع سرعة تشغيل. حتى إذا كان المشغّل لا يتيح استخدام سرعات تشغيل متغيّرة، يجب أن تحتوي المصفوفة دائمًا على قيمة واحدة على الأقل (1).

ضبط سلوك التشغيل لقوائم التشغيل

player.setLoop(loopPlaylists:Boolean):Void

وتشير هذه الوظيفة إلى ما إذا كان يجب أن يشغّل مشغّل الفيديو قائمة تشغيل بشكل متواصل أو سيتوقف عن التشغيل بعد انتهاء آخر فيديو في قائمة التشغيل. السلوك الافتراضي هو أن قوائم التشغيل لا تتكرر.

سيستمر هذا الإعداد حتى في حال تحميل قائمة تشغيل مختلفة أو الإشارة إليها، ما يعني أنّه في حال تحميل قائمة تشغيل، واستدعيت الدالة setLoop بقيمة true، ثم حمَّلت قائمة تشغيل ثانية، سيتم أيضًا تكرار قائمة التشغيل الثانية.

تُحدِّد المَعلمة loopPlaylists المطلوبة سلوك التكرار.

إذا كانت قيمة المَعلمة هي true، سيشغّل مشغّل الفيديو قوائم التشغيل باستمرار. بعد تشغيل آخر فيديو في قائمة تشغيل، سيعود مشغّل الفيديو إلى بداية قائمة التشغيل ويشغّلها من جديد.
إذا كانت قيمة المَعلمة false، ستنتهي عمليات التشغيل بعد أن يشغّل مشغّل الفيديو آخر فيديو في قائمة التشغيل.

player.setShuffle(shufflePlaylist:Boolean):Void

تشير هذه الدالة إلى ما إذا كان يجب ترتيب مقاطع الفيديو في قائمة التشغيل عشوائيًا بحيث يتم تشغيلها بترتيب مختلف عن الترتيب الذي حدده منشئ قائمة التشغيل. إذا شغّلت قائمة تشغيل بشكل عشوائي بعد بدء تشغيلها، ستتم إعادة ترتيب القائمة أثناء مواصلة تشغيل الفيديو قيد التشغيل. وسيتم بعد ذلك اختيار الفيديو التالي الذي يتم تشغيله استنادًا إلى القائمة المُعاد ترتيبها.

لن يتم تطبيق هذا الإعداد في حال تحميل قائمة تشغيل مختلفة أو الإشارة إليها، ما يعني أنّه لن يتمّ ترتيب قائمة التشغيل الثانية عشوائيًا إذا حمَّلت قائمة تشغيل واستدعيت وظيفة setShuffle ثم حمَّلت قائمة تشغيل ثانية.

توضّح المَعلمة shufflePlaylist المطلوبة ما إذا كان يجب ترتيب قائمة التشغيل على YouTube بشكل عشوائي.

إذا كانت قيمة المَعلمة هي true، سترتب منصة YouTube ترتيب قائمة التشغيل عشوائيًا. إذا طلبت من الدالة ترتيب قائمة تشغيل تم ترتيبها عشوائيًا، سيجري YouTube ترتيبًا عشوائيًا مرة أخرى.
إذا كانت قيمة المَعلمة هي false، سيعيد YouTube ترتيب قائمة التشغيل إلى ترتيبها الأصلي.

حالة التشغيل

player.getVideoLoadedFraction():Float: تعرض رقمًا بين 0 و1 يحدد النسبة المئوية للفيديو التي يعرضها المشغّل على أنّها مخزَّنة مؤقتًا. تعرض هذه الطريقة رقمًا أكثر موثوقية من الطريقتين getVideoBytesLoaded وgetVideoBytesTotal المتوقّفة حاليًا.

player.getPlayerState():Number

لعرض حالة المشغّل. القيم المحتمَلة هي:

-1 - لم يتم البدء
0 – منتهية
1 – قيد التشغيل
2 – تم الإيقاف مؤقتًا
3 – جارٍ التخزين مؤقتًا
5 – تم اختيار الفيديو

player.getCurrentTime():Number: عرض الوقت المنقضي بالثواني منذ بدء تشغيل الفيديو.

player.getVideoStartBytes():Number: تم إيقافها اعتبارًا من 31 تشرين الأول (أكتوبر) 2012. لعرض عدد وحدات البايت التي بدأ تحميل ملف الفيديو منها. (تعرض هذه الطريقة دائمًا القيمة 0.) مثال لسيناريو: يتقدم المستخدم إلى نقطة لم يتم تحميلها بعد، ويقدم المشغّل طلبًا جديدًا لتشغيل مقطع من الفيديو لم يتم تحميله بعد.

player.getVideoBytesLoaded():Number: تم إيقافها اعتبارًا من 18 تموز (يوليو) 2012. بدلاً من ذلك، استخدِم الطريقة getVideoLoadedFraction لتحديد النسبة المئوية للفيديو الذي تم تخزينه مؤقتًا.

تعرض هذه الطريقة قيمة تتراوح بين 0 و1000 تمثّل تقريبًا مقدار تحميل الفيديو الذي تم تحميله. يمكنك احتساب المقدار الذي تم تحميله من الفيديو من خلال قسمة القيمة getVideoBytesLoaded على القيمة getVideoBytesTotal.

player.getVideoBytesTotal():Number: تم إيقافها اعتبارًا من 18 تموز (يوليو) 2012. بدلاً من ذلك، استخدِم الطريقة getVideoLoadedFraction لتحديد النسبة المئوية للفيديو الذي تم تخزينه مؤقتًا.

لعرض حجم الفيديو بالبايت الذي يتم تحميله/تشغيله حاليًا أو عرض تقريبي لحجم الفيديو.

تعرِض هذه الطريقة دائمًا قيمة 1000. يمكنك احتساب المقدار الذي تم تحميله من الفيديو من خلال قسمة القيمة getVideoBytesLoaded على القيمة getVideoBytesTotal.

استرداد معلومات الفيديو

player.getDuration():Number: عرض المدة بالثواني للفيديو الذي يتم تشغيله حاليًا. يُرجى العِلم أنّ getDuration() ستعرض 0 إلى أن يتم تحميل البيانات الوصفية للفيديو، وهو ما يحدث عادةً بعد بدء تشغيل الفيديو مباشرةً.

إذا كان الفيديو الذي يتم تشغيله حاليًا هو حدث مباشر، ستعرض الدالة getDuration() الوقت المنقضي منذ بدء بث الفيديو المباشر. على وجه التحديد، هي مقدار الوقت الذي يستغرقه بث الفيديو بدون إعادة ضبطه أو مقاطعته. بالإضافة إلى ذلك، تكون هذه المدة عادةً أطول من وقت الحدث الفعلي، إذ قد يبدأ البث قبل وقت بدئه.

player.getVideoUrl():String: عرض عنوان 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> التي تتضمّن المشغّل.

فعاليات

تنشط واجهة برمجة التطبيقات الأحداث لإشعار التطبيق بحدوث التغييرات في المشغّل المضمَّن. كما هو موضّح في القسم السابق، يمكنك الاشتراك في الأحداث من خلال إضافة أداة معالجة حدث عند إنشاء الكائن YT.Player، ويمكنك أيضًا استخدام الدالة addEventListener.

ستمرر واجهة برمجة التطبيقات كائن حدث باعتباره الوسيطة الوحيدة لكل دالة من هذه الدوال. يحتوي كائن الحدث على السمات التالية:

وتحدّد سمة target للحدث مشغّل الفيديو المقابل للحدث.
وتحدّد الخاصية data للحدث قيمة ذات صلة بالحدث. وتجدر الإشارة إلى أنّ الحدثَين onReady وonAutoplayBlocked لا يحدّدان السمة data.

تحدّد القائمة التالية الأحداث التي تنشطها واجهة برمجة التطبيقات:

onReady

يتم تنشيط هذا الحدث عندما ينتهي اللاعب من التحميل ويكون جاهزًا لبدء تلقّي طلبات البيانات من واجهة برمجة التطبيقات. يجب أن ينفِّذ تطبيقك هذه الوظيفة إذا كنت تريد تنفيذ عمليات معيّنة تلقائيًا، مثل تشغيل الفيديو أو عرض معلومات عن الفيديو عندما يصبح المشغّل جاهزًا.

يعرض المثال أدناه نموذجًا لدالة للتعامل مع هذا الحدث. يحتوي كائن الحدث الذي تمرِّره واجهة برمجة التطبيقات إلى الدالة على السمة 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 لكائن الحدث الذي تمرِّره واجهة برمجة التطبيقات إلى وظيفة أداة معالجة الحدث عددًا صحيحًا يتوافق مع حالة المشغّل الجديدة. القيم المتاحة هي:

-1 (لم تبدأ)
0 (منتهية)
1 (قيد التشغيل)
2 (موقوفة مؤقتًا)
3 (جارٍ التخزين مؤقتًا)
5 (تم اقتراح الفيديو).

عندما يحمّل المشغّل فيديو للمرة الأولى، سيبثّ حدث unstarted (-1). عندما يتم اختيار فيديو ويصبح جاهزًا للتشغيل، سيبثّ المشغّل حدث video cued (5). في التعليمات البرمجية، يمكنك تحديد قيم العدد الصحيح أو يمكنك استخدام أحد متغيرات مساحات الاسم التالية:

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

onPlaybackQualityChange

يتم تنشيط هذا الحدث كلما تغيّرت جودة تشغيل الفيديو. وقد يشير ذلك إلى تغيير في بيئة التشغيل لدى المُشاهد. يمكنك زيارة مركز مساعدة YouTube للحصول على مزيد من المعلومات حول العوامل التي تؤثّر في ظروف التشغيل أو التي قد تؤدي إلى نشوب الحدث.

ستكون قيمة السمة data لكائن الحدث الذي تمرِّره واجهة برمجة التطبيقات إلى وظيفة استماع الحدث عبارة عن سلسلة تحدِّد جودة التشغيل الجديدة. القيم المتاحة هي:

small
medium
large
hd720
hd1080
highres

onPlaybackRateChange: يتم تنشيط هذا الحدث كلما تغيّر معدّل تشغيل الفيديو. على سبيل المثال، إذا استدعيت الدالة setPlaybackRate(suggestedRate)، سيتم تنشيط هذا الحدث إذا تغيّر معدّل التشغيل فعليًا. يجب أن يستجيب التطبيق للحدث، ويجب ألا يفترض أن معدل التشغيل سيتغير تلقائيًا عند استدعاء الدالة setPlaybackRate(suggestedRate). وبالمثل، يجب ألا يفترض الرمز أن معدل تشغيل الفيديو سيتغير فقط نتيجة لاستدعاء صريح إلى setPlaybackRate.

ستكون قيمة السمة data لكائن الحدث الذي تمرِّره واجهة برمجة التطبيقات إلى وظيفة استماع الحدث رقمًا يُحدِّد معدل التشغيل الجديد. تعرض الطريقة getAvailablePlaybackRates قائمة بمعدلات التشغيل الصالحة للفيديو الذي يتم تشغيله أو الذي يتم تشغيله حاليًا.

onError

يتم تنشيط هذا الحدث في حال حدوث خطأ في المشغّل. ستمرِّر واجهة برمجة التطبيقات العنصر event إلى دالة أداة معالجة الحدث. ستحدِّد السمة data في ذلك الكائن عددًا صحيحًا يحدّد نوع الخطأ الذي حدث. القيم المتاحة هي:

2 – يحتوي الطلب على قيمة معلمة غير صالحة. على سبيل المثال، يحدث هذا الخطأ إذا حددت معرّف فيديو لا يحتوي على 11 حرفًا، أو إذا كان معرّف الفيديو يحتوي على أحرف غير صالحة، مثل علامات التعجب أو العلامات النجمية.
5 – لا يمكن تشغيل المحتوى المطلوب في مشغّل HTML5 أو حدث خطأ آخر متعلق بمشغّل HTML5.
100 – لم يتم العثور على الفيديو المطلوب. يحدث هذا الخطأ عند إزالة فيديو (لأي سبب) أو عند وضع علامة "خاص" عليه.
101 – لا يسمح مالك الفيديو المطلوب بتشغيله في المشغّلات المضمّنة.
150 – هذا الخطأ هو نفسه الخطأ 101. إنّه مجرد خطأ 101 متخفي.

onApiChange

يتم تنشيط هذا الحدث للإشارة إلى أنّ المشغّل قد حمّل (أو ألغى تحميل) وحدة تتضمّن طُرقًا مكشوفة من واجهة برمجة التطبيقات. يمكن لتطبيقك رصد هذا الحدث ثم استطلاع رأي المشغّل لتحديد الخيارات المعروضة للوحدة التي تم تحميلها مؤخرًا. ويمكن للتطبيق بعد ذلك استرداد الإعدادات الحالية لهذه الخيارات أو تحديثها.

يسترد الأمر التالي مصفوفة من أسماء الوحدات التي يمكنك ضبط خيارات المشغّل لها:

player.getOptions();

في الوقت الحالي، الوحدة الوحيدة التي يمكنك ضبط خيارات لها هي وحدة captions التي تعالج الترجمة والشرح في المشغّل. عند استلام حدث onApiChange، يمكن لتطبيقك استخدام الأمر التالي لتحديد الخيارات التي يمكن ضبطها لوحدة captions:

player.getOptions('captions');

من خلال استطلاع رأي المشغِّل باستخدام هذا الأمر، يمكنك التأكد من إمكانية الوصول إلى الخيارات التي تريد الوصول إليها. تعمل الأوامر التالية على استرداد خيارات الوحدات وتعديلها:

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

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

يعرض الجدول أدناه الخيارات المتوافقة مع واجهة برمجة التطبيقات:

الوحدة	Option	الوصف
ترجمة وشرح	fontSize	يضبط هذا الخيار حجم خط الترجمة المعروضة في المشغّل. القيم الصالحة هي `-1` و`0` و`1` و`2` و`3`. الحجم التلقائي هو `0`، وأصغر حجم هو `-1`. عند ضبط هذا الخيار على عدد صحيح أقل من `-1`، سيتم عرض أصغر حجم للتسمية التوضيحية، في حين سيؤدي ضبط هذا الخيار على عدد صحيح أعلى من `3` إلى عرض أكبر حجم للشرح.
ترجمة وشرح	إعادة التحميل	يؤدي هذا الخيار إلى إعادة تحميل بيانات الترجمة والشرح للفيديو الذي يتم تشغيله. ستكون القيمة `null` في حال استرداد قيمة الخيار. اضبط القيمة على `true` لإعادة تحميل بيانات الترجمة والشرح.

onAutoplayBlocked

يتم تنشيط هذا الحدث عندما يحظر المتصفّح ميزات التشغيل التلقائي أو تشغيل الفيديوهات النصية، ويُشار إليها مجتمعةً باسم "التشغيل التلقائي". ويتضمن ذلك محاولة التشغيل باستخدام أي من واجهات برمجة تطبيقات المشغّل التالية:

مَعلمة autoplay
دالة loadPlaylist
دالة loadVideoById
دالة loadVideoByUrl
دالة playVideo

تتضمّن معظم المتصفّحات سياسات يمكنها حظر التشغيل التلقائي على أجهزة الكمبيوتر المكتبي والأجهزة الجوّالة وغيرها من البيئات إذا توفرت شروط معيّنة. تشمل الحالات التي قد يتم فيها تفعيل هذه السياسة التشغيل بدون صوت بدون تفاعل المستخدم، أو عندما لا يتم ضبط سياسة الأذونات للسماح بالتشغيل التلقائي على إطار iframe من مصادر متعددة.

للحصول على التفاصيل الكاملة، يُرجى الاطّلاع على السياسات الخاصة بالمتصفّح (Apple Safari أو Webkit وGoogle Chrome وMozilla Firefox) ودليل التشغيل التلقائي في Mozilla.

أمثلة

جارٍ إنشاء كائنات `YT.Player`

المثال 1: استخدام واجهة برمجة التطبيقات مع إطار <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: التشغيل بصوت مرتفع

ينشئ هذا المثال مشغّل فيديو بحجم 1280 × 720 بكسل. بعد ذلك، تستدعي أداة معالجة الحدث للحدث onReady الدالة setVolume لضبط مستوى الصوت على أعلى خيار.

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

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

المثال 3: يحدّد هذا المثال معلَمات المشغّل لتشغيل الفيديو تلقائيًا عند تحميله وإخفاء عناصر التحكّم في مشغّل الفيديو. وتضيف أيضًا أدوات معالجة الأحداث لعدة أحداث تبثّها واجهة برمجة التطبيقات.
```
function onYouTubeIframeAPIReady() {
  var player;
  player = new YT.Player('player', {
    videoId: 'M7lc1UVf-VE',
    playerVars: { 'autoplay': 1, 'controls': 0 },
    events: {
      'onReady': onPlayerReady,
      'onStateChange': onPlayerStateChange,
      'onError': onPlayerError
    }
  });
}
```

التحكم في الفيديوهات بنطاق 360 درجة

يستخدم هذا المثال الرمز التالي:

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

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

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

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

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

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

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

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

تاريخ المراجعة

November 20, 2023

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

April 27, 2021

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

October 13, 2020

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

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

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

October 24, 2019

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

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

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

May 16, 2018

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

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

This example demonstrates and lets you test these new features.

June 19, 2017

This update contains the following changes:

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

August 11, 2016

This update contains the following changes:

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

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

June 29, 2016

This update contains the following changes:

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

June 24, 2016

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

January 6, 2016

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

December 18, 2015

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

April 28, 2014

This update contains the following changes:

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

March 25, 2014

This update contains the following changes:

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

July 23, 2013

This update contains the following changes:

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

October 31, 2012

This update contains the following changes:

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

In addition, the descriptions and examples for each of the video queueing functions have been updated to reflect the newly added support for object syntax. (The API's playlist queueing functions already supported object syntax.)
When called using object syntax, each of the video queueing functions supports an endSeconds property, which accepts a float/integer and specifies the time when the video should stop playing when playVideo() is called.
The getVideoStartBytes method has been deprecated. The method now always returns a value of 0.

August 22, 2012

This update contains the following changes:

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

August 6, 2012

This update contains the following changes:

The Operations section has been expanded to list all of the supported API functions rather than linking to the JavaScript Player API Reference for that list.
The API supports several new functions and one new event that can be used to control the video playback speed:
- Functions
  - getAvailablePlaybackRates – Retrieve the supported playback rates for the cued or playing video. Note that variable playback rates are currently only supported in the HTML5 player.
  - getPlaybackRate – Retrieve the playback rate for the cued or playing video.
  - setPlaybackRate – Set the playback rate for the cued or playing video.
- Events
  - onPlaybackRateChange – This event fires when the video's playback rate changes.

July 19, 2012

This update contains the following changes:

The new getVideoLoadedFraction method replaces the now-deprecated getVideoBytesLoaded and getVideoBytesTotal methods. The new method returns the percentage of the video that the player shows as buffered.
The onError event may now return an error code of 5, which indicates that the requested content cannot be played in an HTML5 player or another error related to the HTML5 player has occurred.
The Requirements section has been updated to indicate that any web page using the IFrame API must also implement the onYouTubeIframeAPIReady function. Previously, the section indicated that the required function was named onYouTubePlayerAPIReady. Code samples throughout the document have also been updated to use the new name.

Note: To ensure that this change does not break existing implementations, both names will work. If, for some reason, your page has an onYouTubeIframeAPIReady function and an onYouTubePlayerAPIReady function, both functions will be called, and the onYouTubeIframeAPIReady function will be called first.
The code sample in the Getting started section has been updated to reflect that the URL for the IFrame Player API code has changed to http://www.youtube.com/iframe_api. To ensure that this change does not affect existing implementations, the old URL (http://www.youtube.com/player_api) will continue to work.

July 16, 2012

This update contains the following changes:

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

June 6, 2012

This update contains the following changes:

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

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

March 30, 2012

This update contains the following changes:

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

March 26, 2012

This update contains the following changes:

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

YouTube Player API Reference for iframe Embeds

المتطلّبات

البدء

تحميل مشغّل فيديو

العمليات

الدوال

دوال الإضافة في قائمة المحتوى التالي

دوالّ إضافة الفيديوهات إلى "قائمة المحتوى التالي"

دوال قائمة المحتوى التالي للقوائم

عناصر التحكّم في التشغيل وإعدادات المشغّل

تشغيل فيديو

التحكم في تشغيل فيديوهات بنطاق 360 درجة

تشغيل فيديو في قائمة تشغيل

تغيير مستوى صوت المشغّل

ضبط حجم المشغّل

ضبط معدل التشغيل

ضبط سلوك التشغيل لقوائم التشغيل

حالة التشغيل

استرداد معلومات الفيديو

استرداد معلومات قائمة التشغيل

إضافة أداة معالجة حدث أو إزالتها

الوصول إلى عُقد DOM وتعديلها

فعاليات

أمثلة

جارٍ إنشاء كائنات YT.Player

التحكم في الفيديوهات بنطاق 360 درجة

تاريخ المراجعة

November 20, 2023

April 27, 2021

October 13, 2020

October 24, 2019

May 16, 2018

June 19, 2017

August 11, 2016

June 29, 2016

June 24, 2016

January 6, 2016

December 18, 2015

April 28, 2014

March 25, 2014

July 23, 2013

October 31, 2012

August 22, 2012

August 6, 2012

July 19, 2012

July 16, 2012

June 6, 2012

March 30, 2012

March 26, 2012

جارٍ إنشاء كائنات `YT.Player`