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 สำหรับ 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>

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

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

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

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

  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 และโปรแกรมเล่นตามที่ระบุไว้ใน URL src เพื่อเพิ่มมาตรการรักษาความปลอดภัย คุณควรใส่พารามิเตอร์ origin ลงใน URL ด้วย โดยระบุรูปแบบ URL (http:// หรือ https://) และโดเมนแบบเต็มของหน้าโฮสต์เป็นค่าพารามิเตอร์ origin เป็นตัวเลือกที่ไม่บังคับ แต่จะป้องกันไม่ให้เกิดการแทรก JavaScript ของบุคคลที่สามที่เป็นอันตรายในหน้าเว็บและการลักลอบใช้บัญชีของโปรแกรมเล่นวิดีโอ YouTube

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

การทำงาน

หากต้องการเรียกใช้เมธอด 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 ของวิดีโอที่จะเล่น ใน 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

ฟังก์ชันนี้จะโหลดภาพขนาดย่อของวิดีโอที่ระบุและเตรียมโปรแกรมเล่นในการเล่นวิดีโอ โปรแกรมเล่นจะไม่ขอ 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 ใน 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 สามารถกำหนดให้โปรแกรมเล่นอยู่ในสถานะไม่เล่น ซึ่งรวมถึง ended (0), paused (2), video cued (5) หรือ unstarted (-1) ซึ่งต่างจากฟังก์ชัน pauseVideo ตรงที่
paused2
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 จะระบุวิดีโอแรกในรายการ หากคุณสุ่มเพลย์ลิสต์ ฟังก์ชันนี้จะเล่นวิดีโอในตำแหน่งที่ระบุไว้ในเพลย์ลิสต์แบบสุ่ม

กำลังเปลี่ยนระดับเสียงโปรแกรมเล่น

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 จะระบุวิดีโอแรกในเพลย์ลิสต์

  • หากคุณสุ่มเล่นเพลย์ลิสต์ ค่าการแสดงผลจะระบุลำดับของวิดีโอภายในเพลย์ลิสต์แบบสุ่ม

การเพิ่มหรือนำ 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>

ประวัติการแก้ไข

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.