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

YouTube Player API Reference for iframe Embeds

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

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

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

المتطلبات

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

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

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

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

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

يُرجى العلم أنّه في حال كتابة علامة <iframe>، عند إنشاء عنصر YT.Player، لن تحتاج إلى تحديد قيم لسمتَي width وheight اللتين تم تحديدهما كسمتَين لعلامة <iframe>، أو لمعلَمتَي videoId وplayer اللتين تم تحديدهما في عنوان 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 درجة. (إذا لم يكن الفيديو الحالي 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> على الصفحة اللاعب الذي سيتم استخدام واجهة برمجة التطبيقات معه. يُرجى العلم أنّه يجب ضبط المَعلمة enablejsapi على القيمة 1 في عنوان URL src الخاص باللاعب أو ضبط سمة 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>

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

وسعت YouTube نطاق استخدام Android WebView Media Integrity API لتتمكّن مشغّلات الوسائط المضمّنة، بما في ذلك مشغّل YouTube المضمّن في تطبيقات Android، من التحقّق من صحة التطبيق المضمّن. بفضل هذا التغيير، ترسل التطبيقات المضمّنة تلقائيًا معرّف تطبيق معتمَد إلى 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 درجة

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

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

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` عنصر