หน้านี้ได้รับการแปลโดย Cloud Translation API

YouTube Player API Reference for iframe Embeds

IFrame Player API ช่วยให้คุณฝังวิดีโอเพลเยอร์ของ YouTube บนเว็บไซต์และควบคุมเพลเยอร์ได้โดยใช้ JavaScript

เมื่อใช้ฟังก์ชัน JavaScript ของ API คุณจะจัดคิววิดีโอเพื่อเล่น เล่น หยุดชั่วคราว หรือหยุดวิดีโอเหล่านั้น ปรับระดับเสียงของโปรแกรมเล่น หรือดึงข้อมูลเกี่ยวกับวิดีโอที่เล่นอยู่ได้ นอกจากนี้ คุณยังเพิ่มโปรแกรมรับเหตุการณ์ที่จะดำเนินการตามเหตุการณ์บางอย่างของโปรแกรมเล่น เช่น การเปลี่ยนแปลงสถานะของโปรแกรมเล่น

คู่มือนี้จะอธิบายวิธีใช้ IFrame API โดยจะระบุเหตุการณ์ประเภทต่างๆ ที่ API สามารถส่งได้ และอธิบายวิธีเขียนโปรแกรมฟังเหตุการณ์เพื่อตอบสนองต่อเหตุการณ์เหล่านั้น นอกจากนี้ ยังมีรายละเอียดฟังก์ชัน JavaScript ต่างๆ ที่คุณเรียกใช้เพื่อควบคุมโปรแกรมเล่นวิดีโอ รวมถึงพารามิเตอร์ของโปรแกรมเล่นที่คุณสามารถใช้เพื่อปรับแต่งโปรแกรมเล่นเพิ่มเติม

ข้อกำหนด

เบราว์เซอร์ของผู้ใช้ต้องรองรับฟีเจอร์ postMessage ของ HTML5 เบราว์เซอร์สมัยใหม่ส่วนใหญ่รองรับ postMessage

โปรแกรมเล่นที่ฝังต้องมีวิวพอร์ตที่มีขนาดอย่างน้อย 200 x 200 พิกเซล หากเพลเยอร์แสดงตัวควบคุม เพลเยอร์ต้องมีขนาดพอที่จะแสดงตัวควบคุมได้ทั้งหมดโดยไม่ทำให้วิวพอร์ตเล็กลงต่ำกว่าขนาดขั้นต่ำ เราขอแนะนำให้โปรแกรมเล่นขนาด 16:9 มีความกว้างอย่างน้อย 480 พิกเซลและสูงอย่างน้อย 270 พิกเซล

เว็บเพจที่ใช้ IFrame API ต้องใช้ฟังก์ชัน JavaScript ต่อไปนี้ด้วย

onYouTubeIframeAPIReady – API จะเรียกใช้ฟังก์ชันนี้เมื่อหน้าเว็บดาวน์โหลด JavaScript สําหรับ Player API เสร็จแล้ว ซึ่งจะช่วยให้คุณใช้ API ในหน้าเว็บได้ ดังนั้น ฟังก์ชันนี้อาจสร้างออบเจ็กต์ผู้เล่นที่คุณต้องการแสดงเมื่อโหลดหน้าเว็บ

เริ่มต้นใช้งาน

หน้า HTML ตัวอย่างด้านล่างสร้างโปรแกรมเล่นที่ฝังไว้ซึ่งจะโหลดวิดีโอ เล่นวิดีโอเป็นเวลา 6 วินาที แล้วหยุดเล่น ความคิดเห็นที่มีหมายเลขใน HTML จะอธิบายไว้ในรายการด้านล่างตัวอย่าง

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

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

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

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

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

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

รายการต่อไปนี้แสดงรายละเอียดเพิ่มเติมเกี่ยวกับตัวอย่างข้างต้น

แท็ก <div> ในส่วนนี้จะระบุตําแหน่งในหน้าเว็บที่ IFrame API จะวางโปรแกรมเล่นวิดีโอ ตัวสร้างออบเจ็กต์โปรแกรมเล่น ซึ่งอธิบายไว้ในส่วนการโหลดโปรแกรมเล่นวิดีโอ จะระบุแท็ก <div> ตาม id เพื่อให้มั่นใจว่า API จะวาง <iframe> ในตำแหน่งที่เหมาะสม กล่าวโดยละเอียดคือ IFrame API จะแทนที่แท็ก <div> ด้วยแท็ก <iframe>

หรือจะวางองค์ประกอบ <iframe> ไว้ในหน้าเว็บโดยตรงก็ได้ ส่วนการโหลดวิดีโอเพลเยอร์จะอธิบายวิธีดำเนินการ
โค้ดในส่วนนี้จะโหลดโค้ด JavaScript ของ IFrame Player API ตัวอย่างนี้ใช้การแก้ไข DOM เพื่อดาวน์โหลดโค้ด API เพื่อให้แน่ใจว่าระบบจะดึงข้อมูลโค้ดแบบไม่พร้อมกัน (เบราว์เซอร์สมัยใหม่บางรุ่นยังไม่รองรับแอตทริบิวต์ async ของแท็ก <script> ซึ่งเปิดใช้การดาวน์โหลดแบบไม่พร้อมกันด้วย ตามที่อธิบายไว้ในคำตอบใน Stack Overflow นี้
ฟังก์ชัน onYouTubeIframeAPIReady จะทำงานทันทีที่ดาวน์โหลดโค้ด API ของโปรแกรมเล่น ส่วนนี้ของโค้ดจะกำหนดตัวแปรส่วนกลาง player ซึ่งหมายถึงโปรแกรมเล่นวิดีโอที่คุณฝัง จากนั้นฟังก์ชันจะสร้างออบเจ็กต์โปรแกรมเล่นวิดีโอ
ฟังก์ชัน onPlayerReady จะทำงานเมื่อเหตุการณ์ onReady เริ่มทำงาน ในตัวอย่างนี้ ฟังก์ชันจะระบุว่าเมื่อวิดีโอเพลเยอร์พร้อมแล้ว ก็ควรเริ่มเล่น
API จะเรียกใช้ฟังก์ชัน onPlayerStateChange เมื่อสถานะของโปรแกรมเล่นมีการเปลี่ยนแปลง ซึ่งอาจบ่งบอกว่าโปรแกรมเล่นกำลังเล่น หยุดชั่วคราว เล่นจบแล้ว และอื่นๆ ฟังก์ชันนี้ระบุว่าเมื่อสถานะโปรแกรมเล่นเป็น 1 (เล่น) โปรแกรมเล่นควรเล่นเป็นเวลา 6 วินาที จากนั้นเรียกใช้ฟังก์ชัน stopVideo เพื่อหยุดวิดีโอ

กำลังโหลดโปรแกรมเล่นวิดีโอ

หลังจากโหลดโค้ด JavaScript ของ API แล้ว API จะเรียกใช้ฟังก์ชัน onYouTubeIframeAPIReady ซึ่งคุณจะสร้างออบเจ็กต์ YT.Player เพื่อแทรกวิดีโอเพลเยอร์ในหน้าเว็บได้ ตัวอย่าง HTML ด้านล่างแสดงฟังก์ชัน onYouTubeIframeAPIReady จากตัวอย่างด้านบน

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

ตัวสร้างสำหรับโปรแกรมเล่นวิดีโอจะระบุพารามิเตอร์ต่อไปนี้

พารามิเตอร์แรกจะระบุองค์ประกอบ DOM หรือ id ขององค์ประกอบ HTML ที่ API จะแทรกแท็ก <iframe> ที่มีโปรแกรมเล่น

IFrame API จะแทนที่องค์ประกอบที่ระบุด้วยองค์ประกอบ <iframe> ที่มีโปรแกรมเล่น ซึ่งอาจส่งผลต่อเลย์เอาต์ของหน้าเว็บหากองค์ประกอบที่จะแทนที่มีลักษณะการแสดงผลแตกต่างจากองค์ประกอบ <iframe> ที่แทรก โดยค่าเริ่มต้น <iframe> จะแสดงเป็นองค์ประกอบ inline-block
พารามิเตอร์ที่ 2 คือออบเจ็กต์ที่ระบุตัวเลือกของโปรแกรมเล่น ออบเจ็กต์นี้มีพร็อพเพอร์ตี้ต่อไปนี้
- width (ตัวเลข) – ความกว้างของวิดีโอเพลเยอร์ ค่าเริ่มต้นคือ 640
- height (ตัวเลข) – ความสูงของวิดีโอเพลเยอร์ ค่าเริ่มต้นคือ 390
- videoId (สตริง) – รหัสวิดีโอ YouTube ที่ระบุวิดีโอที่โปรแกรมเล่นจะโหลด
- playerVars (ออบเจ็กต์) – พร็อพเพอร์ตี้ของออบเจ็กต์จะระบุพารามิเตอร์ของโปรแกรมเล่นที่ใช้ปรับแต่งโปรแกรมเล่นได้
- events (ออบเจ็กต์) – พร็อพเพอร์ตี้ของออบเจ็กต์จะระบุเหตุการณ์ที่ API เรียกให้แสดงและฟังก์ชัน (โปรแกรมรับเหตุการณ์) ที่ API จะเรียกใช้เมื่อเกิดเหตุการณ์เหล่านั้น ในตัวอย่างนี้ ตัวสร้างจะระบุว่าฟังก์ชัน onPlayerReady จะทำงานเมื่อเหตุการณ์ onReady เริ่มทํางาน และฟังก์ชัน onPlayerStateChange จะทำงานเมื่อเหตุการณ์ onStateChange เริ่มทํางาน

ดังที่กล่าวไว้ในส่วนเริ่มต้นใช้งาน คุณสามารถสร้างแท็ก <iframe> เองได้แทนการเขียนองค์ประกอบ <div> ว่างเปล่าในหน้าเว็บ ซึ่งโค้ด JavaScript ของ Player API จะแทนที่ด้วยองค์ประกอบ <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 จะไม่ใช่ตัวเลือกบังคับ แต่การรวม origin ไว้จะช่วยป้องกันไม่ให้มีการแทรก JavaScript ที่เป็นอันตรายของบุคคลที่สามลงในหน้าเว็บและการลักลอบควบคุมโปรแกรมเล่น YouTube

ดูตัวอย่างอื่นๆ ในการสร้างออบเจ็กต์วิดีโอเพลเยอร์ได้ที่ตัวอย่าง

การดำเนินการ

หากต้องการเรียกใช้เมธอด player API คุณต้องอ้างอิงออบเจ็กต์เพลเยอร์ที่ต้องการควบคุมก่อน คุณรับข้อมูลอ้างอิงได้โดยการสร้างออบเจ็กต์ YT.Player ตามที่อธิบายไว้ในส่วนเริ่มต้นใช้งานและการโหลดวิดีโอเพลเยอร์ของเอกสารนี้

ฟังก์ชัน

ฟังก์ชันการจัดคิว

ฟังก์ชันการจัดคิวช่วยให้คุณโหลดและเล่นวิดีโอ เพลย์ลิสต์ หรือรายการวิดีโออื่นๆ ได้ หากใช้ไวยากรณ์ออบเจ็กต์ที่อธิบายไว้ด้านล่างเพื่อเรียกใช้ฟังก์ชันเหล่านี้ คุณจะจัดคิวหรือโหลดรายการวิดีโอที่ผู้ใช้อัปโหลดไว้ได้ด้วย

API รองรับไวยากรณ์ 2 แบบสำหรับการเรียกใช้ฟังก์ชันการจัดคิว

ไวยากรณ์อาร์กิวเมนต์กำหนดให้ต้องแสดงอาร์กิวเมนต์ของฟังก์ชันตามลำดับที่กำหนด
ไวยากรณ์ออบเจ็กต์ช่วยให้คุณส่งออบเจ็กต์เป็นพารามิเตอร์เดียวและกำหนดพร็อพเพอร์ตี้ออบเจ็กต์สำหรับอาร์กิวเมนต์ของฟังก์ชันที่ต้องการตั้งค่าได้ นอกจากนี้ API อาจรองรับฟังก์ชันการทำงานเพิ่มเติมที่ไวยากรณ์อาร์กิวเมนต์ไม่รองรับ

เช่น เรียกใช้ฟังก์ชัน loadVideoById ได้ 2 วิธีดังนี้ โปรดทราบว่าไวยากรณ์ออบเจ็กต์รองรับพร็อพเพอร์ตี้ 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 ช่วยให้คุณโหลดและเล่นเพลย์ลิสต์ได้ หากใช้ไวยากรณ์ออบเจ็กต์เพื่อเรียกใช้ฟังก์ชันเหล่านี้ คุณจะจัดคิว (หรือโหลด) รายการวิดีโอที่ผู้ใช้อัปโหลดไว้ได้ด้วย

เนื่องจากฟังก์ชันจะทํางานแตกต่างกันไปโดยขึ้นอยู่กับว่ามีการเรียกใช้โดยใช้ไวยากรณ์อาร์กิวเมนต์หรือไวยากรณ์ออบเจ็กต์ วิธีการเรียกใช้ทั้ง 2 แบบจึงมีการบันทึกไว้ด้านล่าง

cuePlaylist

ไวยากรณ์ของอาร์กิวเมนต์
```
player.cuePlaylist(playlist:String|Array,
                   index:Number,
                   startSeconds:Number):Void
```
จัดคิวเพลย์ลิสต์ที่ระบุ เมื่อเพลย์ลิสต์กรอพร้อมเล่นแล้ว เครื่องเล่นจะออกอากาศเหตุการณ์ video cued (5)
- พารามิเตอร์ playlist ที่ต้องระบุจะระบุอาร์เรย์ของรหัสวิดีโอ YouTube ใน YouTube Data API พร็อพเพอร์ตี้ id ของvideo ทรัพยากรจะระบุรหัสของวิดีโอนั้น
- พารามิเตอร์ index (ไม่บังคับ) จะระบุดัชนีของวิดีโอแรกในเพลย์ลิสต์ที่จะเล่น พารามิเตอร์นี้ใช้ดัชนีฐาน 0 และค่าพารามิเตอร์เริ่มต้นคือ 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 และค่าพารามิเตอร์เริ่มต้นคือ 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 และค่าพารามิเตอร์เริ่มต้นคือ 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 และค่าพารามิเตอร์เริ่มต้นคือ 0 ดังนั้นลักษณะการทํางานเริ่มต้นคือการโหลดและเล่นวิดีโอแรกในรายการ
- พร็อพเพอร์ตี้ startSeconds (ไม่บังคับ) จะยอมรับค่าลอย/จำนวนเต็มและระบุเวลาที่วิดีโอแรกในรายการควรเริ่มเล่น

ตัวควบคุมการเล่นและการตั้งค่าวิดีโอเพลเยอร์

การเล่นวิดีโอ

player.playVideo():Void: เล่นวิดีโอที่กรอ/โหลดไว้ในปัจจุบัน สถานะสุดท้ายของโปรแกรมเล่นหลังจากฟังก์ชันนี้ทำงานจะเป็น playing (1)

หมายเหตุ: การเล่นจะนับรวมในยอดดูอย่างเป็นทางการของวิดีโอก็ต่อเมื่อเริ่มต้นผ่านปุ่มเล่นในตัวในโปรแกรมเล่นเท่านั้น

player.pauseVideo():Void: หยุดวิดีโอที่เล่นอยู่ชั่วคราว สถานะสุดท้ายของโปรแกรมเล่นหลังจากเรียกใช้ฟังก์ชันนี้จะเท่ากับ paused (2) เว้นแต่ว่าโปรแกรมเล่นจะอยู่ในสถานะ ended (0) เมื่อมีการเรียกใช้ฟังก์ชัน ซึ่งในกรณีนี้ สถานะของโปรแกรมเล่นจะไม่เปลี่ยนแปลง

player.stopVideo():Void: หยุดและยกเลิกการโหลดวิดีโอปัจจุบัน ฟังก์ชันนี้ควรสงวนไว้สําหรับกรณีที่พบไม่บ่อยนักเมื่อคุณทราบว่าผู้ใช้จะไม่ดูวิดีโอเพิ่มเติมในโปรแกรมเล่น หากต้องการหยุดวิดีโอชั่วคราว คุณควรเรียกใช้ฟังก์ชัน pauseVideo หากต้องการเปลี่ยนวิดีโอที่โปรแกรมเล่นกำลังเล่นอยู่ คุณสามารถเรียกใช้ฟังก์ชันการจัดคิวรายการใดรายการหนึ่งได้โดยไม่ต้องเรียกใช้ stopVideo ก่อน

สำคัญ: ฟังก์ชัน stopVideo ต่างจากฟังก์ชัน pauseVideo ตรงที่ stopVideo จะตั้งค่าเพลเยอร์ให้อยู่ในสถานะใดก็ได้ที่ไม่ได้เล่น ซึ่งรวมถึง ended (0), paused (2), video cued (5) หรือ unstarted (-1) ต่างจากฟังก์ชัน pauseVideo ที่ปล่อยให้เพลเยอร์อยู่ในสถานะ paused (2)

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

กรอไปยังเวลาที่ระบุในวิดีโอ หากเพลเยอร์หยุดชั่วคราวเมื่อเรียกใช้ฟังก์ชัน เพลเยอร์จะยังคงหยุดชั่วคราว หากเรียกใช้ฟังก์ชันจากสถานะอื่น (playing, video cued ฯลฯ) เพลเยอร์จะเล่นวิดีโอ

พารามิเตอร์ seconds จะระบุเวลาที่ผู้เล่นควรข้ามไป

โปรแกรมเล่นจะข้ามไปยังคีย์เฟรมที่ใกล้ที่สุดก่อนเวลาดังกล่าว เว้นแต่ว่าโปรแกรมเล่นจะดาวน์โหลดส่วนของวิดีโอที่ผู้ใช้กรอหาไว้แล้ว
พารามิเตอร์ allowSeekAhead จะกำหนดว่าโปรแกรมเล่นจะส่งคำขอใหม่ไปยังเซิร์ฟเวอร์หรือไม่ หากพารามิเตอร์ seconds ระบุเวลาที่อยู่นอกข้อมูลวิดีโอที่บัฟเฟอร์ไว้ในปัจจุบัน

เราขอแนะนำให้คุณตั้งค่าพารามิเตอร์นี้เป็น false ขณะที่ผู้ใช้ลากเมาส์ไปตามแถบความคืบหน้าของวิดีโอ จากนั้นตั้งค่าเป็น true เมื่อผู้ใช้ปล่อยเมาส์ วิธีนี้ช่วยให้ผู้ใช้เลื่อนไปยังจุดต่างๆ ของวิดีโอได้โดยไม่ต้องขอสตรีมวิดีโอใหม่โดยการเลื่อนผ่านจุดที่ไม่ได้บัฟเฟอร์ในวิดีโอ เมื่อผู้ใช้ปล่อยปุ่มเมาส์ วิดีโอเพลเยอร์จะข้ามไปยังจุดที่ต้องการในวิดีโอและขอสตรีมวิดีโอใหม่ หากจำเป็น

การควบคุมการเล่นวิดีโอ 360 องศา

หมายเหตุ: ประสบการณ์การเล่นวิดีโอ 360° รองรับการใช้งานในอุปกรณ์เคลื่อนที่อย่างจำกัด ในอุปกรณ์ที่ไม่รองรับ วิดีโอ 360 องศาจะบิดเบี้ยวและไม่มีวิธีเปลี่ยนมุมมองการดูเลย ซึ่งรวมถึงผ่าน API, การใช้เซ็นเซอร์การวางแนว หรือตอบสนองต่อการแตะ/ลากบนหน้าจอของอุปกรณ์

player.getSphericalProperties():Object

ดึงข้อมูลพร็อพเพอร์ตี้ที่อธิบายมุมมองหรือมุมมองปัจจุบันของผู้ชมสำหรับการเล่นวิดีโอ นอกจากนี้

ระบบจะสร้างออบเจ็กต์นี้สำหรับวิดีโอ 360° หรือที่เรียกว่าวิดีโอทรงกลมเท่านั้น
หากวิดีโอปัจจุบันไม่ใช่วิดีโอ 360° หรือมีการเรียกใช้ฟังก์ชันจากอุปกรณ์ที่ไม่รองรับ ฟังก์ชันจะแสดงผลออบเจ็กต์ว่าง
ในอุปกรณ์เคลื่อนที่ที่รองรับ หากตั้งค่าพร็อพเพอร์ตี้ enableOrientationSensor เป็น true ฟังก์ชันนี้จะแสดงผลออบเจ็กต์ที่มีพร็อพเพอร์ตี้ fov ซึ่งมีค่าที่ถูกต้อง และตั้งค่าพร็อพเพอร์ตี้อื่นๆ เป็น 0

ออบเจ็กต์นี้มีพร็อพเพอร์ตี้ต่อไปนี้

พร็อพเพอร์ตี้
`yaw`	ตัวเลขในช่วง [0, 360) ที่แสดงมุมแนวนอนของมุมมองเป็นองศา ซึ่งแสดงถึงระดับที่ผู้ใช้หมุนมุมมองไปทางซ้ายหรือขวา ตำแหน่งที่เป็นกลางซึ่งหันหน้าไปยังกึ่งกลางของวิดีโอในภาพโปรเจ็กชันทรงกลมทรงรีแสดงค่า 0° และค่านี้จะเพิ่มขึ้นเมื่อผู้ชมหันไปทางซ้าย
`pitch`	ตัวเลขในช่วง [-90, 90] ที่แสดงมุมแนวตั้งของมุมมองเป็นองศา ซึ่งแสดงถึงระดับที่ผู้ใช้ปรับมุมมองเพื่อมองขึ้นหรือลง ตำแหน่งที่เป็นกลางซึ่งหันหน้าไปยังจุดศูนย์กลางของวิดีโอในภาพโปรเจ็กชันทรงกลมทรงรีแสดงค่า 0° และค่านี้จะเพิ่มขึ้นเมื่อผู้ชมมองขึ้น
`roll`	จํานวนในช่วง [-180, 180] ที่แสดงมุมการหมุนตามเข็มนาฬิกาหรือทวนเข็มนาฬิกาของมุมมองเป็นองศา ตำแหน่งที่เป็นกลางซึ่งแกนแนวนอนในการฉายภาพทรงกลมทรงรีขนานกับแกนแนวนอนของมุมมองจะแสดงค่า 0° ค่าจะเพิ่มขึ้นเมื่อมุมมองหมุนตามเข็มนาฬิกา และลดลงเมื่อมุมมองหมุนทวนเข็มนาฬิกา ทั้งนี้ โปรดทราบว่าโปรแกรมเล่นที่ฝังไว้จะไม่มีอินเทอร์เฟซผู้ใช้สำหรับปรับมุมมองการเลื่อน คุณปรับม้วนได้ด้วยวิธีใดวิธีหนึ่งต่อไปนี้ ซึ่งใช้ร่วมกันไม่ได้ ใช้เซ็นเซอร์การวางแนวในเบราว์เซอร์บนอุปกรณ์เคลื่อนที่เพื่อหมุนมุมมอง หากเปิดใช้เซ็นเซอร์การวางแนว ฟังก์ชัน `getSphericalProperties` จะแสดงผล `0` เป็นค่าของพร็อพเพอร์ตี้ `roll` เสมอ หากปิดใช้เซ็นเซอร์การวางแนว ให้ตั้งค่าการหมุนเป็นค่าที่ไม่ใช่ 0 โดยใช้ API นี้
`fov`	ตัวเลขในช่วง [30, 120] ที่แสดงมุมมองของมุมมองเป็นองศาที่วัดตามขอบที่ยาวกว่าของวิวพอร์ต ระบบจะปรับขอบที่สั้นกว่าโดยอัตโนมัติเพื่อให้สัดส่วนกับอัตราส่วนภาพของมุมมอง ค่าเริ่มต้นคือ 100 องศา การลดค่าจะเหมือนกับการซูมเข้าเนื้อหาวิดีโอ และการเพิ่มขึ้นของค่าจะเหมือนกับการซูมออก คุณปรับค่านี้ได้ด้วยการใช้ API หรือใช้ปุ่มลูกล้อของเม้าส์เมื่อวิดีโออยู่ในโหมดเต็มหน้าจอ

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` ผ่าน API ได้ และ API ยังเป็นวิธีเดียวที่จะเปลี่ยนพร็อพเพอร์ตี้ `fov` ในอุปกรณ์เคลื่อนที่ได้ นี่คือลักษณะการทำงานเริ่มต้น เมื่อค่าเป็น `false` การเคลื่อนไหวของอุปกรณ์จะไม่ส่งผลต่อประสบการณ์การรับชมแบบ 360° และต้องตั้งค่าพร็อพเพอร์ตี้ `yaw`, `pitch`, `roll` และ `fov` ทั้งหมดผ่าน API อุปกรณ์เคลื่อนที่ที่ไม่รองรับ ค่าพร็อพเพอร์ตี้ `enableOrientationSensor` ไม่มีผลต่อประสบการณ์การเล่น

การเล่นวิดีโอในเพลย์ลิสต์

player.nextVideo():Void

ฟังก์ชันนี้จะโหลดและเล่นวิดีโอถัดไปในเพลย์ลิสต์

หากมีการเรียกใช้ player.nextVideo() ขณะกำลังดูวิดีโอสุดท้ายในเพลย์ลิสต์ และเพลย์ลิสต์ได้รับการตั้งค่าให้เล่นอย่างต่อเนื่อง (loop) โปรแกรมเล่นจะโหลดและเล่นวิดีโอแรกในรายการ
หากมีการเรียก player.nextVideo() ขณะกำลังดูวิดีโอสุดท้ายในเพลย์ลิสต์ และไม่ได้ตั้งค่าเพลย์ลิสต์ให้เล่นต่อเนื่อง การเล่นจะสิ้นสุดลง

player.previousVideo():Void

ฟังก์ชันนี้จะโหลดและเล่นวิดีโอก่อนหน้าในเพลย์ลิสต์

หากมีการเรียก player.previousVideo() ขณะกำลังดูวิดีโอแรกในเพลย์ลิสต์ และเพลย์ลิสต์ได้รับการตั้งค่าให้เล่นอย่างต่อเนื่อง (loop) โปรแกรมเล่นจะโหลดและเล่นวิดีโอสุดท้ายในรายการ
หากมีการเรียก player.previousVideo() ขณะกำลังดูวิดีโอแรกในเพลย์ลิสต์ และไม่ได้ตั้งค่าให้เพลย์ลิสต์เล่นต่อเนื่อง โปรแกรมเล่นจะเล่นวิดีโอแรกในเพลย์ลิสต์อีกครั้งตั้งแต่ต้น

player.playVideoAt(index:Number):Void

ฟังก์ชันนี้จะโหลดและเล่นวิดีโอที่ระบุในเพลย์ลิสต์

พารามิเตอร์ index ที่ต้องระบุจะระบุดัชนีของวิดีโอที่ต้องการเล่นในเพลย์ลิสต์ พารามิเตอร์นี้ใช้ดัชนีฐาน 0 ดังนั้นค่า 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 ค่า (1) เสมอ

การตั้งค่าลักษณะการเล่นสำหรับเพลย์ลิสต์

player.setLoop(loopPlaylists:Boolean):Void

ฟังก์ชันนี้จะระบุว่าวิดีโอเพลเยอร์ควรเล่นเพลย์ลิสต์อย่างต่อเนื่องหรือควรหยุดเล่นหลังจากวิดีโอสุดท้ายในเพลย์ลิสต์จบลง ลักษณะการทำงานเริ่มต้นคือเพลย์ลิสต์จะไม่เล่นซ้ำ

การตั้งค่านี้จะยังคงอยู่แม้ว่าคุณจะโหลดหรือกรอเพลย์ลิสต์อื่นก็ตาม ซึ่งหมายความว่าหากคุณโหลดเพลย์ลิสต์ เรียกใช้ฟังก์ชัน setLoop ที่มีค่าเป็น true แล้วโหลดเพลย์ลิสต์ที่ 2 เพลย์ลิสต์ที่ 2 ก็จะเล่นวนด้วย

พารามิเตอร์ loopPlaylists ที่ต้องระบุจะระบุลักษณะการทำงานแบบวนซ้ำ

หากค่าพารามิเตอร์คือ true วิดีโอเพลเยอร์จะเล่นเพลย์ลิสต์อย่างต่อเนื่อง หลังจากเล่นวิดีโอสุดท้ายในเพลย์ลิสต์แล้ว วิดีโอเพลเยอร์จะกลับไปที่จุดเริ่มต้นของเพลย์ลิสต์และเล่นอีกครั้ง
หากค่าพารามิเตอร์คือ false การเล่นจะสิ้นสุดลงหลังจากที่โปรแกรมเล่นวิดีโอเล่นวิดีโอสุดท้ายในเพลย์ลิสต์

player.setShuffle(shufflePlaylist:Boolean):Void

ฟังก์ชันนี้จะระบุว่าควรสับวิดีโอของเพลย์ลิสต์เพื่อให้เล่นตามลำดับที่แตกต่างจากที่ผู้สร้างเพลย์ลิสต์กำหนดไว้หรือไม่ หากคุณสับเปลี่ยนเพลย์ลิสต์หลังจากที่เพลย์ลิสต์เริ่มเล่นแล้ว ระบบจะจัดเรียงเพลย์ลิสต์ใหม่ขณะที่วิดีโอที่เล่นอยู่เล่นต่อไป จากนั้นระบบจะเลือกวิดีโอถัดไปที่จะเล่นตามรายการที่จัดเรียงใหม่

การตั้งค่านี้จะหายไปหากคุณโหลดหรือกรอเพลย์ลิสต์อื่น ซึ่งหมายความว่าหากคุณโหลดเพลย์ลิสต์ เรียกใช้ฟังก์ชัน setShuffle แล้วโหลดเพลย์ลิสต์ที่ 2 ระบบจะไม่สับเพลย์ลิสต์ที่ 2

พารามิเตอร์ 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 ดังนั้นค่า 0 จะระบุวิดีโอแรกในเพลย์ลิสต์
หากคุณสับเปลี่ยนเพลย์ลิสต์ ค่าที่แสดงผลจะระบุลำดับของวิดีโอภายในเพลย์ลิสต์ที่สับเปลี่ยน

การเพิ่มหรือนํา Listener เหตุการณ์ออก

player.addEventListener(event:String, listener:String):Void: เพิ่มฟังก์ชัน Listener สําหรับ event ที่ระบุ ส่วนเหตุการณ์ด้านล่างจะระบุเหตุการณ์ต่างๆ ที่โปรแกรมเล่นอาจเรียกให้แสดง Listener คือสตริงที่ระบุฟังก์ชันที่จะดำเนินการเมื่อเหตุการณ์ที่ระบุเริ่มทำงาน

player.removeEventListener(event:String, listener:String):Void: นําฟังก์ชัน Listener ของ event ที่ระบุออก listener คือสตริงที่ระบุฟังก์ชันที่จะไม่ทํางานอีกต่อไปเมื่อเหตุการณ์ที่ระบุเริ่มทํางาน

การเข้าถึงและการแก้ไขโหนด DOM

player.getIframe():Object: เมธอดนี้จะแสดงผลโหนด DOM สำหรับ <iframe> ที่ฝัง

player.destroy():Void: นำ <iframe> ที่มีโปรแกรมเล่นออก

กิจกรรม

API จะเรียกเหตุการณ์เพื่อแจ้งให้แอปพลิเคชันทราบถึงการเปลี่ยนแปลงในโปรแกรมเล่นที่ฝัง ดังที่ระบุไว้ในส่วนก่อนหน้า คุณสามารถสมัครรับเหตุการณ์ได้โดยเพิ่มโปรแกรมรับเหตุการณ์เมื่อสร้างออบเจ็กต์ YT.Player และคุณยังใช้ฟังก์ชัน addEventListener ได้ด้วย

API จะส่งออบเจ็กต์เหตุการณ์เป็นอาร์กิวเมนต์เดียวไปยังฟังก์ชันแต่ละรายการ ออบเจ็กต์เหตุการณ์มีพร็อพเพอร์ตี้ต่อไปนี้

target ของเหตุการณ์จะระบุวิดีโอเพลเยอร์ที่เกี่ยวข้องกับเหตุการณ์
data ของเหตุการณ์จะระบุค่าที่เกี่ยวข้องกับเหตุการณ์ โปรดทราบว่าเหตุการณ์ onReady และ onAutoplayBlocked ไม่ได้ระบุพร็อพเพอร์ตี้ data

รายการต่อไปนี้จะกําหนดเหตุการณ์ที่ API เรียกให้แสดง

onReady

เหตุการณ์นี้จะทริกเกอร์เมื่อใดก็ตามที่ผู้เล่นโหลดเสร็จแล้วและพร้อมที่จะเริ่มรับการเรียก API แอปพลิเคชันควรใช้ฟังก์ชันนี้หากคุณต้องการดำเนินการบางอย่างโดยอัตโนมัติ เช่น เล่นวิดีโอหรือแสดงข้อมูลเกี่ยวกับวิดีโอทันทีที่โปรแกรมเล่นพร้อม

ตัวอย่างด้านล่างแสดงฟังก์ชันตัวอย่างสำหรับการจัดการเหตุการณ์นี้ ออบเจ็กต์เหตุการณ์ที่ API ส่งไปยังฟังก์ชันมีพร็อพเพอร์ตี้ target ซึ่งระบุโปรแกรมเล่น ฟังก์ชันนี้จะดึงข้อมูลโค้ดฝังสำหรับวิดีโอที่โหลดอยู่ในปัจจุบัน เริ่มเล่นวิดีโอ และแสดงโค้ดฝังในองค์ประกอบหน้าเว็บที่มีค่า id เป็น embed-code

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

onStateChange

เหตุการณ์นี้จะทริกเกอร์เมื่อใดก็ตามที่สถานะของผู้เล่นเปลี่ยนแปลง พร็อพเพอร์ตี้ data ของออบเจ็กต์เหตุการณ์ที่ API ส่งไปยังฟังก์ชัน Listener ของเหตุการณ์จะระบุจำนวนเต็มที่สอดคล้องกับสถานะโปรแกรมเล่นใหม่ ค่าที่เป็นไปได้มีดังนี้

-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 ของออบเจ็กต์เหตุการณ์ที่ API ส่งไปยังฟังก์ชัน Listener ของเหตุการณ์จะเป็นสตริงที่ระบุคุณภาพการเล่นใหม่ ค่าที่เป็นไปได้มีดังนี้

small
medium
large
hd720
hd1080
highres

onPlaybackRateChange: เหตุการณ์นี้จะทริกเกอร์ทุกครั้งที่อัตราการเล่นวิดีโอเปลี่ยนแปลง เช่น หากคุณเรียกใช้ฟังก์ชัน setPlaybackRate(suggestedRate) เหตุการณ์นี้จะทํางานหากอัตราการเล่นมีการเปลี่ยนแปลงจริง แอปพลิเคชันควรตอบสนองต่อเหตุการณ์และไม่ควรถือว่าอัตราการเล่นจะเปลี่ยนแปลงโดยอัตโนมัติเมื่อเรียกใช้ฟังก์ชัน setPlaybackRate(suggestedRate) ในทํานองเดียวกัน โค้ดของคุณไม่ควรถือว่าอัตราการเล่นวิดีโอจะเปลี่ยนแปลงเฉพาะจากการเรียกใช้ setPlaybackRate อย่างชัดแจ้งเท่านั้น

ค่าพร็อพเพอร์ตี้ data ของออบเจ็กต์เหตุการณ์ที่ API ส่งไปยังฟังก์ชัน Listener ของเหตุการณ์จะเป็นตัวเลขที่ระบุอัตราการเล่นใหม่ เมธอด getAvailablePlaybackRates จะแสดงรายการอัตราการเล่นที่ถูกต้องสำหรับวิดีโอที่กรอหรือกำลังเล่นอยู่

onError

เหตุการณ์นี้จะทริกเกอร์หากเกิดข้อผิดพลาดในโปรแกรมเล่น API จะส่งออบเจ็กต์ event ไปยังฟังก์ชัน Listener เหตุการณ์ พร็อพเพอร์ตี้ data ของออบเจ็กต์นั้นจะระบุจำนวนเต็มที่ระบุประเภทของข้อผิดพลาดที่เกิดขึ้น ค่าที่เป็นไปได้มีดังนี้

2 – คำขอมีค่าพารามิเตอร์ที่ไม่ถูกต้อง ตัวอย่างเช่น ข้อผิดพลาดนี้จะเกิดขึ้นหากคุณระบุรหัสวิดีโอที่มีอักขระไม่ครบ 11 ตัว หรือหากรหัสวิดีโอมีอักขระที่ไม่ถูกต้อง เช่น เครื่องหมายตกใจหรือเครื่องหมายดอกจัน
5 – เล่นเนื้อหาที่ขอในโปรแกรมเล่น HTML5 ไม่ได้ หรือเกิดข้อผิดพลาดอื่นที่เกี่ยวข้องกับโปรแกรมเล่น HTML5
100 – ไม่พบวิดีโอที่ขอ ข้อผิดพลาดนี้เกิดขึ้นเมื่อวิดีโอถูกนำออก (ไม่ว่าด้วยเหตุผลใดก็ตาม) หรือมีการทําเครื่องหมายว่าเป็นส่วนตัว
101 – เจ้าของวิดีโอที่ขอไม่อนุญาตให้เล่นวิดีโอในโปรแกรมเล่นที่ฝัง
150 – ข้อผิดพลาดนี้เหมือนกับ 101 นี่เป็นข้อผิดพลาด 101 ในรูปแบบอื่น

onApiChange

ระบบจะเรียกเหตุการณ์นี้เพื่อระบุว่าโปรแกรมเล่นได้โหลด (หรือยกเลิกการโหลด) โมดูลที่มีเมธอด API ที่แสดง แอปพลิเคชันสามารถฟังเหตุการณ์นี้ จากนั้นทำการสำรวจเพลเยอร์เพื่อดูว่าตัวเลือกใดแสดงสำหรับโมดูลที่โหลดล่าสุด จากนั้นแอปพลิเคชันจะดึงข้อมูลหรืออัปเดตการตั้งค่าที่มีอยู่สําหรับตัวเลือกเหล่านั้นได้

คําสั่งต่อไปนี้จะดึงข้อมูลอาร์เรย์ของชื่อโมดูลที่คุณตั้งค่าตัวเลือกโปรแกรมเล่นได้

player.getOptions();

ปัจจุบัน โมดูลเดียวที่คุณตั้งค่าตัวเลือกได้คือโมดูล captions ซึ่งจัดการคำบรรยายแทนเสียงในโปรแกรมเล่น เมื่อได้รับเหตุการณ์ onApiChange แอปพลิเคชันจะใช้คําสั่งต่อไปนี้เพื่อระบุตัวเลือกที่ตั้งค่าสําหรับโมดูล captions ได้

player.getOptions('captions');

การสำรวจเพลเยอร์ด้วยคําสั่งนี้จะช่วยให้คุณยืนยันว่าเข้าถึงตัวเลือกที่ต้องการได้จริง คำสั่งต่อไปนี้จะดึงข้อมูลและอัปเดตตัวเลือกของโมดูล

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

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

ตารางด้านล่างแสดงตัวเลือกที่ API รองรับ

โมดูล	ตัวเลือก	คำอธิบาย
คำบรรยายวิดีโอ	fontSize	ตัวเลือกนี้จะปรับขนาดแบบอักษรของคำบรรยายแทนเสียงที่แสดงในเพลเยอร์ ค่าที่ถูกต้องคือ `-1`, `0`, `1`, `2` และ `3` ขนาดเริ่มต้นคือ `0` และขนาดที่เล็กที่สุดคือ `-1` การตั้งค่าตัวเลือกนี้เป็นจำนวนเต็มต่ำกว่า `-1` จะทำให้คำบรรยายแทนเสียงแสดงในขนาดที่เล็กที่สุด ส่วนการตั้งค่าตัวเลือกนี้เป็นจำนวนเต็มสูงกว่า `3` จะทำให้คำบรรยายแทนเสียงแสดงในขนาดที่ใหญ่ที่สุด
คำบรรยายวิดีโอ	โหลดซ้ำ	ตัวเลือกนี้จะโหลดข้อมูลคำบรรยายแทนเสียงของวิดีโอที่เล่นอยู่อีกครั้ง ค่าจะเป็น `null` หากคุณดึงค่าของตัวเลือก ตั้งค่าเป็น `true` เพื่อโหลดข้อมูลคำบรรยายแทนเสียงซ้ำ

onAutoplayBlocked

เหตุการณ์นี้จะทํางานทุกครั้งที่เบราว์เซอร์บล็อกฟีเจอร์การเล่นวิดีโอแบบเล่นอัตโนมัติหรือแบบสคริปต์ ซึ่งเรียกรวมกันว่า "เล่นอัตโนมัติ" ซึ่งรวมถึงการเล่นที่พยายามทำกับ API โปรแกรมเล่นต่อไปนี้

พารามิเตอร์ autoplay
ฟังก์ชัน loadPlaylist
ฟังก์ชัน loadVideoById
ฟังก์ชัน loadVideoByUrl
ฟังก์ชัน playVideo

เบราว์เซอร์ส่วนใหญ่มีนโยบายที่สามารถบล็อกการเล่นอัตโนมัติในเดสก์ท็อป อุปกรณ์เคลื่อนที่ และสภาพแวดล้อมอื่นๆ ได้หากเงื่อนไขบางอย่างเป็นจริง กรณีที่อาจมีการเรียกใช้นโยบายนี้ ได้แก่ การเล่นที่เปิดเสียงโดยไม่ได้รับการโต้ตอบจากผู้ใช้ หรือเมื่อไม่ได้ตั้งค่านโยบายสิทธิ์เพื่ออนุญาตให้เล่นอัตโนมัติใน iframe ข้ามแหล่งที่มา

ดูรายละเอียดทั้งหมดได้ในนโยบายเฉพาะเบราว์เซอร์ (Apple Safari / Webkit, Google Chrome, Mozilla Firefox) และคำแนะนำเกี่ยวกับการเล่นอัตโนมัติของ Mozilla

ตัวอย่าง

การสร้างออบเจ็กต์ `YT.Player`

ตัวอย่างที่ 1: ใช้ API กับ <iframe> ที่มีอยู่

ในตัวอย่างนี้ องค์ประกอบ <iframe> ในหน้าเว็บได้กําหนดโปรแกรมเล่นที่จะใช้ API ไว้แล้ว โปรดทราบว่า 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 x 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: ตัวอย่างนี้จะตั้งค่าพารามิเตอร์ของเพลเยอร์ให้เล่นวิดีโอโดยอัตโนมัติเมื่อโหลด และซ่อนตัวควบคุมของวิดีโอเพลเยอร์ รวมถึงเพิ่ม Listener เหตุการณ์สําหรับเหตุการณ์หลายรายการที่ API ออกอากาศ
```
function onYouTubeIframeAPIReady() {
  var player;
  player = new YT.Player('player', {
    videoId: 'M7lc1UVf-VE',
    playerVars: { 'autoplay': 1, 'controls': 0 },
    events: {
      'onReady': onPlayerReady,
      'onStateChange': onPlayerStateChange,
      'onError': onPlayerError
    }
  });
}
```

การควบคุมวิดีโอ 360°

ตัวอย่างนี้ใช้โค้ดต่อไปนี้

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

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

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

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

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

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

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

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

การผสานรวม Android WebView Media Integrity API

YouTube ได้ขยายAndroid WebView Media Integrity API เพื่อเปิดใช้โปรแกรมเล่นสื่อที่ฝัง ซึ่งรวมถึงการฝังโปรแกรมเล่น YouTube ในแอปพลิเคชัน Android เพื่อยืนยันความถูกต้องของแอปที่ฝัง การเปลี่ยนแปลงนี้จะทำให้แอปที่ฝังส่งรหัสแอปที่ได้รับการรับรองไปยัง YouTube โดยอัตโนมัติ ข้อมูลที่เก็บรวบรวมผ่านการใช้ API นี้คือข้อมูลเมตาของแอป (ชื่อแพ็กเกจ หมายเลขเวอร์ชัน และใบรับรองการรับรอง) และโทเค็นการรับรองอุปกรณ์ที่บริการ 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 องศา

การเล่นวิดีโอในเพลย์ลิสต์

การเปลี่ยนระดับเสียงของเพลเยอร์

การตั้งค่าขนาดโปรแกรมเล่น

การตั้งค่าอัตราการเล่น

การตั้งค่าลักษณะการเล่นสำหรับเพลย์ลิสต์

สถานะการเล่น

กำลังดึงข้อมูลวิดีโอ

กำลังดึงข้อมูลเพลย์ลิสต์

การเพิ่มหรือนํา Listener เหตุการณ์ออก

การเข้าถึงและการแก้ไขโหนด 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`