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

YouTube Player API Reference for iframe Embeds

تتيح لك واجهة برمجة التطبيقات IFrame Player API تضمين مشغّل فيديو 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>

دمج واجهة برمجة التطبيقات Android WebView Media Integrity API

وسّعت منصة YouTube نطاق واجهة برمجة التطبيقات Android WebView Media Integrity API لإتاحة إمكانية التحقّق من أصالة تطبيق التضمين. مع هذا التغيير، ترسل التطبيقات المضمّنة تلقائيًا رقم تعريف تطبيق تم التصديق عليه إلى YouTube. البيانات التي يتم جمعها من خلال استخدام واجهة برمجة التطبيقات هذه هي البيانات الوصفية للتطبيق (اسم الحزمة ورقم الإصدار وشهادة التوقيع) والرمز المميز لتصديق الجهاز الذي تم إنشاؤه من خلال "خدمات Google Play".

ويتم استخدام البيانات للتحقق من سلامة التطبيق والجهاز. ويتم تشفير هذه البيانات ولا تتم مشاركتها مع جهات خارجية، كما يتم حذفها بعد فترة احتفاظ بالبيانات ثابتة. يمكن لمطوّري التطبيقات ضبط هوية تطبيقاتهم في واجهة برمجة التطبيقات WebView Media Integrity API. تتيح الإعدادات خيار إيقاف عرض المحتوى.

سجلّ النُّسخ السابقة

June 24, 2024

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

November 20, 2023

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

April 27, 2021

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

October 13, 2020

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

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

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

October 24, 2019

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

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

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

May 16, 2018

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

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

This example demonstrates and lets you test these new features.

June 19, 2017

This update contains the following changes:

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

August 11, 2016

This update contains the following changes:

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

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

June 29, 2016

This update contains the following changes:

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

June 24, 2016

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

January 6, 2016

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

December 18, 2015

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

April 28, 2014

This update contains the following changes:

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

March 25, 2014

This update contains the following changes:

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

July 23, 2013

This update contains the following changes:

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

October 31, 2012

This update contains the following changes:

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

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

August 22, 2012

This update contains the following changes:

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

August 6, 2012

This update contains the following changes:

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

July 19, 2012

This update contains the following changes:

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

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

July 16, 2012

This update contains the following changes:

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

June 6, 2012

This update contains the following changes:

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

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

March 30, 2012

This update contains the following changes:

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

March 26, 2012

This update contains the following changes:

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

YouTube Player API Reference for iframe Embeds

الشروط

الخطوات الأولى

جارٍ تحميل مشغّل فيديو

العمليات

الدوال

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

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

دوال الوضع في قائمة الانتظار للقوائم

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

تشغيل فيديو

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

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

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

تعيين حجم المشغّل

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

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

حالة التشغيل

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

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

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

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

فعاليات

أمثلة

جارٍ إنشاء YT.Player عنصر

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

دمج واجهة برمجة التطبيقات Android WebView Media Integrity API

سجلّ النُّسخ السابقة

June 24, 2024

November 20, 2023

April 27, 2021

October 13, 2020

October 24, 2019

May 16, 2018

June 19, 2017

August 11, 2016

June 29, 2016

June 24, 2016

January 6, 2016

December 18, 2015

April 28, 2014

March 25, 2014

July 23, 2013

October 31, 2012

August 22, 2012

August 6, 2012

July 19, 2012

July 16, 2012

June 6, 2012

March 30, 2012

March 26, 2012

جارٍ إنشاء `YT.Player` عنصر