YouTube Player API Reference for iframe Embeds

API โปรแกรมเล่น iframe ช่วยให้คุณสามารถฝังโปรแกรมเล่นวิดีโอ YouTube ในเว็บไซต์ของคุณและควบคุมโปรแกรมเล่นโดยใช้ JavaScript

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

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

ข้อกำหนด

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

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

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

  • onYouTubeIframeAPIReady – API จะเรียกใช้ฟังก์ชันนี้เมื่อดาวน์โหลด JavaScript สำหรับ 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>

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

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

    หรือคุณจะวางองค์ประกอบ <iframe> ไว้ในหน้าโดยตรงก็ได้ ส่วนการโหลดวิดีโอเพลเยอร์จะอธิบายวิธีการดำเนินการ

  2. โค้ดในส่วนนี้จะโหลดโค้ด JavaScript ของ IFrame Player API ตัวอย่างนี้ใช้การแก้ไข DOM เพื่อดาวน์โหลดโค้ด API เพื่อให้แน่ใจว่ามีการเรียกโค้ดแบบไม่พร้อมกัน (ระบบยังไม่รองรับแอตทริบิวต์ async ของแท็ก <script> ซึ่งเปิดใช้การดาวน์โหลดแบบอะซิงโครนัสด้วยเช่นกัน ในเบราว์เซอร์สมัยใหม่ทั้งหมดที่กล่าวถึงในคําตอบของ Stack Overflow

  3. ฟังก์ชัน onYouTubeIframeAPIReady จะทำงานทันทีที่ดาวน์โหลดโค้ด API โปรแกรมเล่น โค้ดส่วนนี้จะระบุตัวแปรร่วม ซึ่งก็คือ player ซึ่งหมายถึงโปรแกรมเล่นวิดีโอที่คุณกำลังฝัง จากนั้นฟังก์ชันนี้จะสร้างออบเจ็กต์โปรแกรมเล่นวิดีโอ

  4. ฟังก์ชัน onPlayerReady จะทำงานเมื่อเหตุการณ์ onReady เริ่มทำงาน ในตัวอย่างนี้ ฟังก์ชันระบุว่าเมื่อวิดีโอเพลเยอร์พร้อมแล้ว วิดีโอควรเริ่มเล่น

  5. 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
    }
  });
}

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

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

    IFrame API จะแทนที่องค์ประกอบที่ระบุด้วยองค์ประกอบ <iframe> ที่มีโปรแกรมเล่น การทำเช่นนี้อาจส่งผลต่อเลย์เอาต์ของหน้าเว็บหากองค์ประกอบที่จะถูกแทนที่มีรูปแบบการแสดงผลต่างจากองค์ประกอบ <iframe> ที่แทรกไว้ โดยค่าเริ่มต้น <iframe> จะแสดงเป็นองค์ประกอบ inline-block

  2. พารามิเตอร์ที่ 2 คือออบเจ็กต์ที่ระบุตัวเลือกโปรแกรมเล่น ออบเจ็กต์มีพร็อพเพอร์ตี้ต่อไปนี้
    • width (ตัวเลข) – ความกว้างของวิดีโอเพลเยอร์ ค่าเริ่มต้นคือ 640
    • height (ตัวเลข) – ความสูงของวิดีโอเพลเยอร์ ค่าเริ่มต้นคือ 390
    • videoId (สตริง) – รหัสวิดีโอ YouTube ที่ระบุวิดีโอที่โปรแกรมเล่นจะโหลด
    • playerVars (วัตถุ) – คุณสมบัติของออบเจ็กต์ระบุพารามิเตอร์โปรแกรมเล่น ที่สามารถใช้เพื่อปรับแต่งโปรแกรมเล่น
    • events (ออบเจ็กต์) – พร็อพเพอร์ตี้ของออบเจ็กต์ระบุเหตุการณ์ที่ API เริ่มทำงานและฟังก์ชัน (Listener เหตุการณ์) ที่ API จะเรียกเมื่อเหตุการณ์เหล่านั้นเกิดขึ้น ในตัวอย่างนี้ เครื่องมือสร้างระบุว่าฟังก์ชัน onPlayerReady จะทำงานเมื่อเหตุการณ์ onReady เริ่มทำงาน และฟังก์ชัน onPlayerStateChange จะทำงานเมื่อเหตุการณ์ onStateChange เริ่มทำงาน

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

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

โปรดทราบว่าหากคุณเขียนแท็ก <iframe> เมื่อสร้างออบเจ็กต์ YT.Player คุณไม่จำเป็นต้องระบุค่าสำหรับ width และ height ซึ่งระบุเป็นแอตทริบิวต์ของแท็ก <iframe> หรือ videoId และพารามิเตอร์ Player ซึ่งระบุอยู่ใน URL ของ src เพื่อเพิ่มมาตรการรักษาความปลอดภัย คุณควรใส่พารามิเตอร์ origin ลงใน URL ด้วย โดยระบุชุดรูปแบบ URL (http:// หรือ https://) และโดเมนแบบเต็มของหน้าโฮสต์เป็นค่าพารามิเตอร์ แม้ว่าคุณจะใช้ origin หรือไม่ก็ได้ แต่ระบบจะช่วยป้องกันการแทรก JavaScript ของบุคคลที่สามที่เป็นอันตรายลงในหน้าเว็บและการควบคุมการลักลอบใช้บัญชีโปรแกรมเล่น YouTube ของคุณ

ส่วนตัวอย่างจะแสดงตัวอย่างอื่นๆ อีก 2 รายการสำหรับการสร้างออบเจ็กต์วิดีโอเพลเยอร์

การทำงาน

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

ฟังก์ชัน

ฟังก์ชันในคิว

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

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

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

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

ตัวอย่างเช่น สามารถเรียกฟังก์ชัน loadVideoById ด้วยวิธีใดก็ได้ต่อไปนี้ โปรดทราบว่าไวยากรณ์ของออบเจ็กต์รองรับพร็อพเพอร์ตี้ endSeconds ซึ่งไวยากรณ์อาร์กิวเมนต์ไม่รองรับ

  • ไวยากรณ์อาร์กิวเมนต์

    loadVideoById("bHQqvYy5KYo", 5, "large")
  • ไวยากรณ์ของออบเจ็กต์

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

ฟังก์ชันการจัดคิวสำหรับวิดีโอ

cueVideoById
  • ไวยากรณ์อาร์กิวเมนต์

    player.cueVideoById(videoId:String,
                        startSeconds:Number):Void
  • ไวยากรณ์ของออบเจ็กต์

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

ฟังก์ชันนี้จะโหลดภาพขนาดย่อของวิดีโอที่ระบุ และเตรียมโปรแกรมเล่นให้พร้อมเล่นวิดีโอ โปรแกรมเล่นจะไม่ขอ FLV จนกว่าจะมีการเรียกใช้ playVideo() หรือ seekTo()

  • พารามิเตอร์ videoId ที่จำเป็นจะระบุรหัสวิดีโอ YouTube ของวิดีโอที่จะเล่น ใน API ข้อมูลของ YouTube พร็อพเพอร์ตี้ id ของทรัพยากร video จะระบุรหัส
  • พารามิเตอร์ startSeconds ที่ไม่บังคับจะยอมรับจำนวนลอยตัว/จำนวนเต็มและระบุเวลาที่วิดีโอควรเริ่มเล่นเมื่อมีการเรียกใช้ playVideo() หากคุณระบุค่า startSeconds แล้วเรียก seekTo() โปรแกรมเล่นจะเล่นจากเวลาที่ระบุไว้ในการเรียก seekTo() เมื่อระบบแนะนำวิดีโอและพร้อมเล่นแล้ว โปรแกรมเล่นจะประกาศเหตุการณ์ video cued (5)
  • พารามิเตอร์ endSeconds ที่ไม่บังคับ ซึ่งรองรับเฉพาะในไวยากรณ์ของออบเจ็กต์ ยอมรับจำนวนลอย/จำนวนเต็มและระบุเวลาที่วิดีโอควรหยุดเล่นเมื่อมีการเรียก playVideo() หากคุณระบุค่า endSeconds แล้วเรียกใช้ seekTo() ค่า endSeconds จะไม่มีผลอีกต่อไป

loadVideoById

  • ไวยากรณ์อาร์กิวเมนต์

    player.loadVideoById(videoId:String,
                         startSeconds:Number):Void
  • ไวยากรณ์ของออบเจ็กต์

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

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

  • พารามิเตอร์ videoId ที่จำเป็นจะระบุรหัสวิดีโอ YouTube ของวิดีโอที่จะเล่น ใน API ข้อมูลของ YouTube พร็อพเพอร์ตี้ id ของทรัพยากร video จะระบุรหัส
  • พารามิเตอร์ startSeconds ที่ไม่บังคับจะยอมรับจำนวนลอยตัว/จำนวนเต็ม หากมีการระบุ วิดีโอจะเริ่มต้นจากคีย์เฟรมที่ใกล้กับเวลาที่ระบุไว้มากที่สุด
  • พารามิเตอร์ endSeconds ที่ไม่บังคับจะยอมรับจำนวนลอยตัว/จำนวนเต็ม หากระบุไว้ วิดีโอจะหยุดเล่นตามเวลาที่กำหนด

cueVideoByUrl

  • ไวยากรณ์อาร์กิวเมนต์

    player.cueVideoByUrl(mediaContentUrl:String,
                         startSeconds:Number):Void
  • ไวยากรณ์ของออบเจ็กต์

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

ฟังก์ชันนี้จะโหลดภาพขนาดย่อของวิดีโอที่ระบุ และเตรียมโปรแกรมเล่นให้พร้อมเล่นวิดีโอ โปรแกรมเล่นจะไม่ขอ FLV จนกว่าจะมีการเรียกใช้ playVideo() หรือ seekTo()

  • พารามิเตอร์ 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 ใน API ข้อมูลของ YouTube พร็อพเพอร์ตี้ 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 จะระบุรหัสเพลย์ลิสต์หรืออาร์เรย์ของรหัสวิดีโอ ใน API ข้อมูลของ YouTube พร็อพเพอร์ตี้ 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 ใน API ข้อมูลของ YouTube พร็อพเพอร์ตี้ 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 จะระบุรหัสเพลย์ลิสต์หรืออาร์เรย์ของรหัสวิดีโอ ใน API ข้อมูลของ YouTube พร็อพเพอร์ตี้ 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 ซึ่งปล่อยให้โปรแกรมเล่นอยู่ในสถานะ paused (2) ตรงที่สามารถทำให้โปรแกรมเล่นอยู่ในสถานะที่ไม่ได้เล่น ซึ่งรวมถึง ended (0), paused (2), video cued (5) หรือ unstarted (-1)
player.seekTo(seconds:Number, allowSeekAhead:Boolean):Void
กรอไปยังเวลาที่ระบุไว้ในวิดีโอ แต่หากเครื่องเล่นหยุดชั่วคราวเมื่อมีการเรียกใช้ฟังก์ชัน โปรแกรมเล่นก็จะหยุดชั่วคราวตามปกติ หากมีการเรียกฟังก์ชันจากสถานะอื่น (playing, video cued ฯลฯ) โปรแกรมเล่นจะเล่นวิดีโอ
  • พารามิเตอร์ seconds ระบุเวลาที่โปรแกรมเล่นควรเล่นต่อ

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

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

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

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

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

player.getSphericalProperties():Object
เรียกข้อมูลพร็อพเพอร์ตี้ที่อธิบายมุมมองหรือมุมมองปัจจุบันของผู้ชมสำหรับการเล่นวิดีโอ นอกจากนี้
  • ออบเจ็กต์นี้สร้างขึ้นสำหรับวิดีโอ 360 องศาเท่านั้น ซึ่งเรียกอีกอย่างว่าวิดีโอ 360 องศา
  • หากวิดีโอปัจจุบันไม่ใช่วิดีโอ 360° หรือหากมีการเรียกฟังก์ชันจากอุปกรณ์ที่ไม่รองรับ ฟังก์ชันจะแสดงผลเป็นวัตถุเปล่า
  • ในอุปกรณ์เคลื่อนที่ที่รองรับ หากตั้งค่าพร็อพเพอร์ตี้ enableOrientationSensor เป็น true ฟังก์ชันนี้จะแสดงออบเจ็กต์ที่พร็อพเพอร์ตี้ fov มีค่าที่ถูกต้อง และมีการตั้งค่าพร็อพเพอร์ตี้อื่นๆ เป็น 0
ออบเจ็กต์มีพร็อพเพอร์ตี้ต่อไปนี้
พร็อพเพอร์ตี้
yaw ตัวเลขในช่วง [0, 360) ที่แสดงมุมแนวนอนของมุมมองเป็นองศา ซึ่งแสดงถึงขอบเขตที่ผู้ใช้หันมุมมองไปทางด้านซ้ายหรือขวา ตำแหน่งที่เป็นกลางซึ่งหันเข้าหากึ่งกลางของวิดีโอในเส้นโครงแบบทรงกลมจะแสดงถึง 0° และค่านี้จะเพิ่มขึ้นเมื่อผู้ชมหันไปทางซ้าย
pitch ตัวเลขในช่วง [-90, 90] แสดงมุมแนวตั้งของมุมมองเป็นองศา ซึ่งแสดงถึงขอบเขตที่ผู้ใช้ปรับมุมมองให้มองขึ้นหรือลง ตำแหน่งที่เป็นกลางซึ่งหันเข้าหากึ่งกลางของวิดีโอในเส้นโครงแบบทรงกลมจะแสดงถึง 0° และค่านี้จะเพิ่มขึ้นเมื่อผู้ชมมองขึ้น
roll ตัวเลขในช่วง [-180, 180] ที่แสดงมุมหมุนตามเข็มนาฬิกาหรือทวนเข็มนาฬิกาของมุมมองเป็นองศา ตำแหน่งที่เป็นกลางซึ่งมีแกนแนวนอนในเส้นโครงทรงกลมเป็นแนวขนานกับแกนแนวนอนของมุมมอง ค่าจะแสดงเป็น 0° ค่าจะเพิ่มขึ้นเมื่อมุมมองหมุนตามเข็มนาฬิกาและลดลงเมื่อมุมมองหมุนทวนเข็มนาฬิกา

โปรดทราบว่าโปรแกรมเล่นแบบฝังจะไม่แสดงอินเทอร์เฟซผู้ใช้สำหรับการปรับการหมุนของมุมมอง คุณปรับเปลี่ยนม้วนโฆษณาด้วยวิธีใดวิธีหนึ่งต่อไปนี้ไม่ได้
  1. ใช้เซ็นเซอร์การวางแนวในเบราว์เซอร์บนอุปกรณ์เคลื่อนที่เพื่อหมุนมุมมอง หากเปิดใช้เซ็นเซอร์การวางแนว ฟังก์ชัน getSphericalProperties จะแสดงผล 0 เป็นค่าของพร็อพเพอร์ตี้ roll เสมอ
  2. หากเซ็นเซอร์การวางแนวปิดอยู่ ให้ตั้งค่าการหมุนเป็นค่าที่ไม่ใช่ 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 จะเริ่มการทำงานของเหตุการณ์เพื่อแจ้งเตือนการใช้การเปลี่ยนแปลงของคุณกับโปรแกรมเล่นที่ฝัง ดังที่ระบุไว้ในส่วนก่อนหน้า คุณติดตามเหตุการณ์ได้โดยการเพิ่ม Listener เหตุการณ์เมื่อสร้างออบเจ็กต์ 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 รองรับ

โมดูล ตัวเลือก คำอธิบาย
captions fontSize ตัวเลือกนี้จะปรับขนาดแบบอักษรของคำบรรยายที่แสดงในโปรแกรมเล่น

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

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

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

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.