YouTube Player API Reference for iframe Embeds

IFrame Player API'sı, web sitenize bir YouTube video oynatıcı yerleştirmenize ve JavaScript kullanarak oynatıcıyı kontrol etmenize olanak tanır.

API'nin JavaScript işlevlerini kullanarak videoları oynatma için sıraya koyabilir, oynatabilir, duraklatabilir veya durdurabilir, oynatıcı ses düzeyini ayarlayabilir ya da oynatılan videoyla ilgili bilgileri alabilirsiniz. Ayrıca, oynatıcı durumu değişikliği gibi belirli oyuncu etkinliklerine yanıt olarak yürütülecek etkinlik işleyiciler de ekleyebilirsiniz.

Bu kılavuzda, IFrame API'nin nasıl kullanılacağı açıklanmaktadır. API'nin gönderebileceği farklı etkinlik türlerini tanımlar ve bu etkinliklere yanıt vermek için etkinlik işleyicilerin nasıl yazılacağını açıklar. Ayrıca, video oynatıcıyı kontrol etmek için çağırabileceğiniz farklı JavaScript işlevleri ve oynatıcıyı daha da özelleştirmek için kullanabileceğiniz oynatıcı parametreleri de ayrıntılı bir şekilde açıklanmaktadır.

Koşullar

Kullanıcının tarayıcısı HTML5 postMessage özelliğini desteklemelidir. Modern tarayıcıların çoğu postMessage'yi destekler.

Yerleşik oynatıcıların en az 200 piksele 200 piksel değerinde bir görünüme sahip olması gerekir. Oynatıcı kontrolleri gösterirse görünümün minimum boyutun altına düşürmeksizin kontrolleri tamamen gösterecek kadar geniş olması gerekir. En az 480 piksel genişlik, 270 piksel uzunluğa sahip 16:9 oynatıcıları öneririz.

IFrame API'sını kullanan tüm web sayfaları da aşağıdaki JavaScript işlevini uygulamalıdır:

  • onYouTubeIframeAPIReady – Sayfa, oynatıcı API'si için JavaScript'i indirmeyi tamamladığında API bu işlevi çağırır. Böylece, sayfanızda API'yi kullanabilirsiniz. Bu nedenle, bu işlev sayfa yüklendiğinde görüntülenmesini istediğiniz oynatıcı nesnelerini oluşturabilir.

Kullanmaya başlama

Aşağıdaki örnek HTML sayfası, bir videoyu yükleyecek, altı saniye boyunca oynatacak ve ardından oynatmayı durduracak yerleşik bir oynatıcı oluşturur. HTML'deki numaralı açıklamalar, örneğin altındaki listede açıklanmıştır.

<!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>

Aşağıdaki listede, yukarıdaki örnekle ilgili daha fazla ayrıntı verilmiştir:

  1. Bu bölümdeki <div> etiketi, IFrame API'sinin video oynatıcıyı yerleştireceği sayfada konumu tanımlar. Video oynatıcı yükleme bölümünde açıklanan oynatıcı nesnesinin oluşturucusu, API'nin <iframe> öğesini doğru konuma yerleştirmesini sağlamak için <div> etiketini id öğesine göre tanımlar. IFrame API'si özellikle <div> etiketini <iframe> etiketiyle değiştirir.

    Alternatif olarak, <iframe> öğesini doğrudan sayfaya da yerleştirebilirsiniz. Video oynatıcı yükleme bölümünde bunun nasıl yapılacağı açıklanmaktadır.

  2. Bu bölümdeki kod, IFrame Player API'sı JavaScript kodunu yükler. Örnekte, kodun eşzamansız olarak alındığından emin olmak için API kodunu indirmek için DOM değişikliği kullanılır. (<script> etiketinin, eşzamansız indirmeleri de etkinleştiren async özelliği, bu Stack Overflow yanıtında açıklandığı gibi henüz tüm modern tarayıcılarda desteklenmemektedir.

  3. onYouTubeIframeAPIReady işlevi, oynatıcı API kodu indirildiği anda yürütülür. Kodun bu bölümü, yerleştirdiğiniz video oynatıcıyı ifade eden genel bir değişkeni (player) tanımlar ve işlev daha sonra video oynatıcı nesnesini oluşturur.

  4. onReady etkinliği tetiklendiğinde onPlayerReady işlevi yürütülür. Bu örnekte işlev, video oynatıcının hazır olduğunda oynatılmaya başlaması gerektiğini belirtir.

  5. Oynatıcının durumu değiştiğinde API, onPlayerStateChange işlevini çağırır. Bu durum, oynatıcının oynadığını, duraklatıldığını, tamamlandığını vb. gösterebilir. İşlev, oynatıcı durumu 1 (oynatılıyor) olduğunda oynatıcının altı saniye boyunca oynatılması gerektiğini ve ardından videoyu durdurmak için stopVideo işlevini çağırmasını belirtir.

Video oynatıcı yükleniyor

API'nin JavaScript kodu yüklendikten sonra API, onYouTubeIframeAPIReady işlevini çağırır. Bu noktada, sayfanıza video oynatıcı eklemek için bir YT.Player nesnesi oluşturabilirsiniz. Aşağıdaki HTML alıntısı, yukarıdaki örnekten alınan onYouTubeIframeAPIReady işlevini gösterir:

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

Video oynatıcısını oluşturan oluşturucu, aşağıdaki parametreleri belirtir:

  1. İlk parametre, API'nin oynatıcıyı içeren <iframe> etiketini yerleştireceği HTML öğesinin id veya DOM öğesini belirtir.

    IFrame API'si, belirtilen öğeyi oynatıcıyı içeren <iframe> öğesiyle değiştirir. Değiştirilen öğe, eklenen <iframe> öğesinden farklı bir görüntüleme stiline sahipse bu durum sayfanızın düzenini etkileyebilir. <iframe>, varsayılan olarak inline-block öğesi olarak gösterilir.

  2. İkinci parametre, oynatıcı seçeneklerini belirten bir nesnedir. Nesne aşağıdaki özellikleri içerir:
    • width (sayı) – Video oynatıcının genişliği. Varsayılan değer 640 olarak ayarlanmıştır.
    • height (sayı) – Video oynatıcının yüksekliği. Varsayılan değer 390 olarak ayarlanmıştır.
    • videoId (dize) – Oynatıcının yükleyeceği videoyu tanımlayan YouTube video kimliği.
    • playerVars (nesne) – Nesnenin özellikleri, oynatıcıyı özelleştirmek için kullanılabilecek oynatıcı parametrelerini tanımlar.
    • events (nesne) – Nesnenin özellikleri, API'nin tetiklediği etkinlikleri ve bu etkinlikler gerçekleştiğinde API'nin çağıracağı işlevleri (etkinlik işleyiciler) tanımlar. Örnekte kurucu, onReady etkinliği tetiklendiğinde onPlayerReady işlevinin yürütüleceğini, onStateChange etkinliği tetiklendiğinde ise onPlayerStateChange işlevinin yürütüleceğini belirtir.

Başlarken bölümünde belirtildiği gibi, sayfanıza boş bir <div> öğesi yazmak yerine, oynatıcı API'sinin JavaScript kodu daha sonra bu öğeyi <iframe> öğesiyle değiştirir. Bu durumda <iframe> etiketini kendiniz oluşturabilirsiniz. Örnekler bölümündeki ilk örnekte bunun nasıl yapılacağı gösterilmektedir.

<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> etiketini yazarsanız YT.Player nesnesini oluştururken YT.Player nesnesini oluştururken <iframe> etiketinin özellikleri olarak belirtilen width ve height değerlerini veya src URL'sinde belirtilen videoId ve oynatıcı parametrelerini belirtmenizin gerekmediğini unutmayın. Ek bir güvenlik önlemi olarak, parametre değeri olarak URL şemasını (http:// veya https://) ve ana makine sayfanızın tam alan adını belirterek URL'ye origin parametresini de eklemeniz gerekir. origin isteğe bağlıdır. Bununla birlikte, sayfanıza kötü amaçlı üçüncü taraf JavaScript yerleştirilmesine ve YouTube oynatıcınızın ele geçirilmesine karşı koruma sağlar.

Örnekler bölümünde, video oynatıcı nesneleri oluşturmaya ilişkin birkaç örnek daha gösterilmektedir.

İşlemler

Oynatıcı API yöntemlerini çağırmak için öncelikle kontrol etmek istediğiniz oynatıcı nesnesine bir referans almanız gerekir. Referansı, bu dokümanın Başlarken ve Video oynatıcı yükleme bölümlerinde açıklandığı gibi bir YT.Player nesnesi oluşturarak edinebilirsiniz.

İşlevler

İşlevleri sıraya ekleme

Sıraya ekleme işlevleri video, oynatma listesi veya başka bir video listesi yükleyip oynatmanıza olanak tanır. Bu işlevleri çağırmak için aşağıda açıklanan nesne söz dizimini kullanıyorsanız kullanıcıların yüklediği videoların listesini de sıraya koyabilir veya yükleyebilirsiniz.

API, sıralama işlevlerini çağırmak için iki farklı söz dizimini destekler.

  • Bağımsız değişken söz dizimi, işlev bağımsız değişkenlerinin belirtilen sırada listelenmesini gerektirir.

  • Nesne söz dizimi, bir nesneyi tek bir parametre olarak iletmenizi ve ayarlamak istediğiniz işlev bağımsız değişkenleri için nesne özellikleri tanımlamanızı sağlar. Ayrıca API, bağımsız değişken söz diziminin desteklemediği ek işlevleri destekleyebilir.

Örneğin, loadVideoById işlevi aşağıdaki yöntemlerden biriyle çağrılabilir. Nesne söz diziminin, bağımsız değişken söz diziminin desteklemediği endSeconds özelliğini desteklediğini unutmayın.

  • Bağımsız değişken söz dizimi

    loadVideoById("bHQqvYy5KYo", 5, "large")
  • Nesne söz dizimi

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

Videolar için sıralama işlevleri

cueVideoById
  • Bağımsız değişken söz dizimi

    player.cueVideoById(videoId:String,
                        startSeconds:Number):Void
  • Nesne söz dizimi

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

Bu işlev, belirtilen videonun küçük resmini yükler ve oynatıcıyı videoyu oynatmaya hazırlar. Oynatıcı, playVideo() veya seekTo() çağrılana kadar FLV'yi istemez.

  • Gerekli videoId parametresi, oynatılacak videonun YouTube Video Kimliği'ni belirtir. YouTube Data API'de bir video kaynağının id özelliği kimliği belirtir.
  • İsteğe bağlı startSeconds parametresi, kayan değeri/tam sayıyı kabul eder ve playVideo() çağrıldığında videonun oynatılmaya başlayacağı zamanı belirtir. Bir startSeconds değeri belirtir ve ardından seekTo() çağırırsanız oynatıcı seekTo() çağrısında belirtilen zamandan itibaren oynar. Video işaretlenip oynatılmaya hazır olduğunda oynatıcı bir video cued etkinliği (5) yayınlar.
  • Yalnızca nesne söz diziminde desteklenen isteğe bağlı endSeconds parametresi, kayan/tam sayıyı kabul eder ve playVideo() çağrıldığında videonun oynatılmasının ne zaman durması gerektiğini belirtir. Bir endSeconds değeri belirleyip ardından seekTo() öğesini çağırırsanız endSeconds değeri artık geçerli olmaz.

loadVideoById

  • Bağımsız değişken söz dizimi

    player.loadVideoById(videoId:String,
                         startSeconds:Number):Void
  • Nesne söz dizimi

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

Bu işlev, belirtilen videoyu yükler ve oynatır.

  • Gerekli videoId parametresi, oynatılacak videonun YouTube Video Kimliği'ni belirtir. YouTube Data API'de bir video kaynağının id özelliği kimliği belirtir.
  • İsteğe bağlı startSeconds parametresi bir kayan sayı/tamsayı kabul eder. Belirtilmişse video, belirtilen zamana en yakın animasyon karesinden başlar.
  • İsteğe bağlı endSeconds parametresi bir kayan sayı/tamsayı kabul eder. Politika belirtildiyse videonun oynatılması belirtilen zamanda durur.

cueVideoByUrl

  • Bağımsız değişken söz dizimi

    player.cueVideoByUrl(mediaContentUrl:String,
                         startSeconds:Number):Void
  • Nesne söz dizimi

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

Bu işlev, belirtilen videonun küçük resmini yükler ve oynatıcıyı videoyu oynatmaya hazırlar. Oynatıcı, playVideo() veya seekTo() çağrılana kadar FLV'yi istemez.

  • Gerekli mediaContentUrl parametresi, http://www.youtube.com/v/VIDEO_ID?version=3 biçiminde tam nitelikli bir YouTube oynatıcı URL'si belirtir.
  • İsteğe bağlı startSeconds parametresi, kayan değeri/tam sayıyı kabul eder ve playVideo() çağrıldığında videonun oynatılmaya başlayacağı zamanı belirtir. startSeconds öğesini belirtir ve ardından seekTo() öğesini çağırırsanız oynatıcı, seekTo() çağrısında belirtilen zamandan itibaren oynar. Video işaretlenip oynatılmaya hazır olduğunda oynatıcı bir video cued etkinliği (5) yayınlar.
  • Yalnızca nesne söz diziminde desteklenen isteğe bağlı endSeconds parametresi, kayan/tam sayıyı kabul eder ve playVideo() çağrıldığında videonun oynatılmasının ne zaman durması gerektiğini belirtir. Bir endSeconds değeri belirleyip ardından seekTo() öğesini çağırırsanız endSeconds değeri artık geçerli olmaz.

loadVideoByUrl

  • Bağımsız değişken söz dizimi

    player.loadVideoByUrl(mediaContentUrl:String,
                          startSeconds:Number):Void
  • Nesne söz dizimi

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

Bu işlev, belirtilen videoyu yükler ve oynatır.

  • Gerekli mediaContentUrl parametresi, http://www.youtube.com/v/VIDEO_ID?version=3 biçiminde tam nitelikli bir YouTube oynatıcı URL'si belirtir.
  • İsteğe bağlı startSeconds parametresi, kayan değeri/tam sayıyı kabul eder ve videonun oynatılmaya başlaması gereken zamanı belirtir. startSeconds (sayı, kayan nokta olabilir) belirtilmişse video, belirtilen zamana en yakın animasyon karesinden başlar.
  • Yalnızca nesne söz diziminde desteklenen isteğe bağlı endSeconds parametresi, kayan/tam sayıyı kabul eder ve videonun oynatılmasının ne zaman durması gerektiğini belirtir.

Listeler için sıralama işlevleri

cuePlaylist ve loadPlaylist işlevleri, bir oynatma listesi yükleyip oynatmanıza olanak tanır. Bu işlevleri çağırmak için nesne söz dizimi kullanıyorsanız bir kullanıcının yüklediği videoların listesini de sıraya koyabilirsiniz (veya yükleyebilirsiniz).

İşlevler, bağımsız değişken söz dizimi veya nesne söz dizimi kullanılarak çağrılmalarına bağlı olarak farklı şekilde çalıştığından, her iki çağrı yöntemi aşağıda açıklanmıştır.

cuePlaylist
  • Bağımsız değişken söz dizimi

    player.cuePlaylist(playlist:String|Array,
                       index:Number,
                       startSeconds:Number):Void
    Belirtilen oynatma listesini sıraya alır. Şarkı listesi seçildiğinde ve oynatılmaya hazır olduğunda oynatıcı bir video cued etkinliği (5) yayınlar.
    • Gerekli playlist parametresi, bir YouTube video kimliği dizisi belirtir. YouTube Data API'de video kaynağının id özelliği bu videonun kimliğini tanımlar.

    • İsteğe bağlı index parametresi, oynatma listesindeki oynatılacak ilk videonun dizinini belirtir. Parametre, sıfır tabanlı bir dizin kullanır ve varsayılan parametre değeri 0'dir. Bu nedenle, varsayılan davranış, oynatma listesindeki ilk videoyu yükleyip oynatmaktır.

    • İsteğe bağlı startSeconds parametresi, kayan değeri/tam sayıyı kabul eder ve playVideo() işlevi çağrıldığında, oynatma listesindeki ilk videonun oynatılmaya başlayacağı zamanı belirtir. Bir startSeconds değeri belirtir ve ardından seekTo() çağırırsanız oynatıcı seekTo() çağrısında belirtilen zamandan itibaren oynar. Bir oynatma listesini gösterir ve daha sonra playVideoAt() işlevini çağırırsanız oynatıcı, belirtilen videonun başında oynatılmaya başlar.

  • Nesne söz dizimi

    player.cuePlaylist({listType:String,
                        list:String,
                        index:Number,
                        startSeconds:Number}):Void
    Belirtilen video listesini sıraya alır. Bu liste, bir oynatma listesi veya kullanıcının yüklediği videolar feed'i olabilir. Arama sonuçları listesini sıraya ekleme özelliği kullanımdan kaldırılmıştır ve 15 Kasım 2020'den itibaren desteklenmeyecektir.

    Liste işaretlenip oynamaya hazır olduğunda, oynatıcı bir video cued etkinliği (5) yayınlar.

    • İsteğe bağlı listType özelliği, aldığınız sonuç feed'inin türünü belirtir. Geçerli değerler playlist ve user_uploads'dir. 15 Kasım 2020 tarihinden itibaren kullanımdan kaldırılmış bir değer olan search artık desteklenmeyecektir. Varsayılan değer playlist olarak ayarlanmıştır.

    • Gerekli list özelliği, YouTube'un döndürmesi gereken belirli bir video listesini tanımlayan bir anahtar içerir.

      • listType özellik değeri playlist ise list özelliği, oynatma listesi kimliğini veya video kimlikleri dizisini belirtir. YouTube Data API'de playlist kaynağının id özelliği bir oynatma listesinin kimliğini tanımlar ve video kaynağının id özelliği bir video kimliği belirtir.
      • listType özellik değeri user_uploads ise list özelliği, yüklenmiş videoları döndürülecek kullanıcıyı tanımlar.
      • listType özellik değeri search ise list özelliği arama sorgusunu belirtir. Not: Bu işlev kullanımdan kaldırılmıştır ve 15 Kasım 2020 tarihinden itibaren desteklenmeyecektir.

    • İsteğe bağlı index özelliği, listedeki oynatılacak ilk videonun dizinini belirtir. Parametre, sıfır tabanlı bir dizin kullanır ve varsayılan parametre değeri 0 olduğundan, varsayılan davranış listedeki ilk videoyu yükleyip oynatmaktır.

    • İsteğe bağlı startSeconds özelliği kayan değeri/tam sayıyı kabul eder ve playVideo() işlevi çağrıldığında, listedeki ilk videonun oynatılmaya başlayacağı zamanı belirtir. Bir startSeconds değeri belirtir ve ardından seekTo() çağırırsanız oynatıcı seekTo() çağrısında belirtilen zamandan itibaren oynar. Bir listeyi işaretler ve daha sonra playVideoAt() işlevini çağırırsanız oynatıcı, belirtilen videonun başında oynatılmaya başlar.

loadPlaylist
  • Bağımsız değişken söz dizimi

    player.loadPlaylist(playlist:String|Array,
                        index:Number,
                        startSeconds:Number):Void
    Bu işlev, belirtilen oynatma listesini yükler ve oynatır.
    • Gerekli playlist parametresi, bir YouTube video kimliği dizisi belirtir. YouTube Data API'de video kaynağının id özelliği bir video kimliği belirtir.

    • İsteğe bağlı index parametresi, oynatma listesindeki oynatılacak ilk videonun dizinini belirtir. Parametre, sıfır tabanlı bir dizin kullanır ve varsayılan parametre değeri 0'dir. Bu nedenle, varsayılan davranış, oynatma listesindeki ilk videoyu yükleyip oynatmaktır.

    • İsteğe bağlı startSeconds parametresi, kayan değeri/tam sayıyı kabul eder ve oynatma listesindeki ilk videonun oynatılmaya başlaması gereken zamanı belirtir.

  • Nesne söz dizimi

    player.loadPlaylist({list:String,
                         listType:String,
                         index:Number,
                         startSeconds:Number}):Void
    Bu işlev, belirtilen listeyi yükler ve oynatır. Bu liste, bir oynatma listesi veya kullanıcının yüklediği videolar feed'i olabilir. Arama sonuçları listesi yükleme özelliği kullanımdan kaldırılmıştır ve 15 Kasım 2020'den itibaren artık desteklenmeyecektir.
    • İsteğe bağlı listType özelliği, aldığınız sonuç feed'inin türünü belirtir. Geçerli değerler playlist ve user_uploads'dir. 15 Kasım 2020 tarihinden itibaren kullanımdan kaldırılmış bir değer olan search artık desteklenmeyecektir. Varsayılan değer playlist olarak ayarlanmıştır.

    • Gerekli list özelliği, YouTube'un döndürmesi gereken belirli bir video listesini tanımlayan bir anahtar içerir.

      • listType özellik değeri playlist ise list özelliği, bir oynatma listesi kimliği veya video kimlikleri dizisi belirtir. YouTube Data API'de playlist kaynağının id özelliği bir oynatma listesinin kimliğini belirtirken video kaynağının id özelliği bir video kimliği belirtir.
      • listType özellik değeri user_uploads ise list özelliği, yüklenmiş videoları döndürülecek kullanıcıyı tanımlar.
      • listType özellik değeri search ise list özelliği arama sorgusunu belirtir. Not: Bu işlev kullanımdan kaldırılmıştır ve 15 Kasım 2020 tarihinden itibaren desteklenmeyecektir.

    • İsteğe bağlı index özelliği, listedeki oynatılacak ilk videonun dizinini belirtir. Parametre, sıfır tabanlı bir dizin kullanır ve varsayılan parametre değeri 0 olduğundan, varsayılan davranış listedeki ilk videoyu yükleyip oynatmaktır.

    • İsteğe bağlı startSeconds özelliği, kayan değeri/tam sayıyı kabul eder ve listedeki ilk videonun oynatılmaya başlaması gereken zamanı belirtir.

Oynatma kontrolleri ve oynatıcı ayarları

Video oynatma

player.playVideo():Void
Şu anda seçilmiş/yüklenmiş videoyu oynatır. Bu işlev yürütüldükten sonraki son oynatıcı durumu playing (1) olur.

Not: Bir videonun oynatması, yalnızca oynatıcıdaki yerel oynatma düğmesiyle başlatıldığında resmi görüntüleme sayısına dahil edilir.
player.pauseVideo():Void
Şu anda oynatılan videoyu duraklatır. İşlev çağrıldığında oynatıcı ended (0) durumunda değilse oynatıcı durumu değişmez. Bu durumda, bu işlev yürütüldükten sonraki son oynatıcı durumu paused (2) olur.
player.stopVideo():Void
Geçerli videonun yüklenmesini durdurur ve yüklemeyi iptal eder. Bu işlev, kullanıcının oynatıcıda ek video izlemeyeceğini bildiğiniz nadir durumlar için ayrılmalıdır. Videoyu duraklatmak istiyorsanız pauseVideo işlevini çağırmanız yeterlidir. Oynatıcının oynattığı videoyu değiştirmek isterseniz önce stopVideo işlevini çağırmadan sıralama işlevlerinden birini çağırabilirsiniz.

Önemli: Oynatıcıyı paused (2) durumunda bırakan pauseVideo işlevinin aksine stopVideo işlevi, oynatıcıyı ended (0), paused (2), video cued (5) veya unstarted (-1) dahil olmak üzere herhangi bir oynamıyor durumuna alabilir.
player.seekTo(seconds:Number, allowSeekAhead:Boolean):Void
Videodaki belirli bir zamanı arar. İşlev çağrıldığında oynatıcı duraklatılmışsa, oynatıcı duraklatılmış olarak kalır. İşlev başka bir durumdan (playing, video cued vb.) çağrılırsa oynatıcı videoyu oynatır.
  • seconds parametresi, oynatıcının ne kadar ilerlemesi gerektiğini tanımlar.

    Oynatıcı videonun kullanıcının aradığı bölümünü zaten indirmediyse oynatıcı bu zamandan önce en yakın animasyon karesine ilerler.

  • seconds parametresi, arabelleğe alınmış olan video verilerinin dışında bir zaman belirtiyorsa allowSeekAhead parametresi, oynatıcının sunucuya yeni bir istek gönderip göndermeyeceğini belirler.

    Kullanıcı fareyi video ilerleme çubuğu boyunca sürüklerken bu parametreyi false olarak ayarlamanızı ve kullanıcı fareyi bıraktığında true olarak ayarlamanızı öneririz. Bu yaklaşım, kullanıcının videodaki arabelleğe alınmamış noktaları geçerek yeni video akışları istemeden videonun farklı noktalarına gitmesine olanak tanır. Kullanıcı fare düğmesini serbest bıraktığında, oynatıcı videoda istenen noktaya ilerler ve gerekirse yeni bir video akışı ister.

360 derece videoların oynatılmasını kontrol etme

Not: 360 derece video oynatma deneyimi, mobil cihazlarda sınırlı şekilde desteklenmektedir. Desteklenmeyen cihazlarda 360 derecelik videolar bozuk görünür. API aracılığıyla, yön sensörlerini kullanmak veya cihaz ekranındaki dokunma/sürükleme işlemlerine yanıt verme de dahil olmak üzere görüntüleme perspektifini değiştirmenin desteklenen bir yolu yoktur.

player.getSphericalProperties():Object
Bir video oynatma için izleyicinin o anki perspektifini veya görünümünü açıklayan özellikleri getirir. Ayrıca:
  • Bu nesne yalnızca, küre şeklinde videolar olarak da adlandırılan 360 derecelik videolar için doldurulur.
  • Geçerli video 360 derecelik bir video değilse veya işlev desteklenmeyen bir cihazdan çağrılırsa işlev boş bir nesne döndürür.
  • Desteklenen mobil cihazlarda enableOrientationSensor özelliği true değerine ayarlanırsa bu işlev, fov özelliğinin doğru değeri içerdiği ve diğer özelliklerin 0 değerine ayarlandığı bir nesne döndürür.
Nesne aşağıdaki özellikleri içerir:
Özellikler
yaw Görünümün yatay açısını derece cinsinden temsil eden ve kullanıcının görünümü ne ölçüde sola veya sağa çevirdiğini yansıtan, [0, 360) aralığında bir sayı. Eşkenar dörtgen projeksiyonunda videonun merkezine bakan nötr konum, 0°'yi temsil eder ve izleyici sola döndükçe bu değer artar.
pitch Derece cinsinden görünümün dikey açısını temsil eden ve kullanıcının görünümü yukarı veya aşağı doğru ne ölçüde ayarladığını yansıtan, [-90, 90] aralığında bir sayı. Eşkenar dörtgen projeksiyonunda videonun merkezine bakan nötr konum, 0°'yi temsil eder ve izleyici yukarıya baktığında bu değer artar.
roll Görünümün saat yönünde veya saat yönünün tersine dönme açısını derece cinsinden temsil eden [-180, 180] aralığında bir sayı. Eşkenar dörtgen projeksiyondaki yatay ekseni görünümün yatay eksenine paralel olacak şekilde nötr konum, 0°'yi temsil eder. Görünüm saat yönünde döndükçe değer artar ve görünüm saat yönünün tersine döndürüldükçe değer azalır.

Yerleşik oynatıcının, görüntüleme rulosunu ayarlamak için bir kullanıcı arayüzü sunmadığını unutmayın. Zar atışı, karşılıklı olarak devre dışı bırakılan şu yöntemlerden biriyle ayarlanabilir:
  1. Görünümü yuvarlamak için mobil tarayıcıda yön sensörünü kullanın. Yön sensörü etkinse getSphericalProperties işlevi, roll özelliğinin değeri olarak her zaman 0 değerini döndürür.
  2. Yön sensörü devre dışı bırakıldıysa bu API'yi kullanarak yuvarlamayı sıfır dışında bir değere ayarlayın.
fov Görüntünün görüş alanını, görüntü alanının uzun kenarı boyunca ölçülen, derece cinsinden temsil eden, [30, 120] aralığında bir sayı. Kısa kenar, görünümün en boy oranıyla orantılı olacak şekilde otomatik olarak ayarlanır.

Varsayılan değer 100 derecedir. Değeri azaltmak video içeriğini yakınlaştırmak, artırmak ise uzaklaştırmak gibidir. Bu değer, API veya video tam ekran modundayken fare tekerleği kullanılarak ayarlanabilir.
player.setSphericalProperties(properties:Object):Void
360 derecelik videonun oynatılacağı video yönünü ayarlar. (Mevcut video küre değilse yöntem, girişten bağımsız olarak işlemsizdir.)

Oynatıcı görünümü, bu yönteme yapılan çağrılara yanıt verirken properties nesnesindeki bilinen özelliklerin değerlerini yansıtacak şekilde güncellenir. Görünüm, söz konusu nesnede yer almayan diğer bilinen özelliklerin değerlerini korur.

Ek olarak:
  • Nesne bilinmeyen ve/veya beklenmeyen özellikler içeriyorsa oynatıcı bunları yoksayar.
  • Bu bölümün başında belirtildiği üzere 360 derece video oynatma deneyimi tüm mobil cihazlarda desteklenmez.
  • Varsayılan olarak, desteklenen mobil cihazlarda bu işlev yalnızca fov özelliğini ayarlar. 360° video oynatmaları için yaw, pitch ve roll özelliklerini etkilemez. Daha fazla ayrıntı için aşağıdaki enableOrientationSensor özelliğine bakın.
İşleve iletilen properties nesnesi aşağıdaki özellikleri içerir:
Özellikler
yaw Yukarıdaki tanımı inceleyin.
pitch Yukarıdaki tanımı inceleyin.
roll Yukarıdaki tanımı inceleyin.
fov Yukarıdaki tanımı inceleyin.
enableOrientationSensor Not: Bu özellik, yalnızca desteklenen cihazlarda 360 derece görüntüleme deneyimini etkiler.IFrame yerleştirmesinin, desteklenen bir cihazın yönünde değişiklik sinyali veren etkinliklere (ör. mobil tarayıcının DeviceOrientationEvent) yanıt vermesi gerekip gerekmediğini belirten boole değeridir. Varsayılan parametre değeri: true.

Desteklenen mobil cihazlar
  • Değer true olduğunda, yerleştirilmiş oynatıcı 360° video oynatmaları için yaw, pitch ve roll özelliklerini ayarlamak üzere yalnızca cihazın hareketine dayanır. Ancak fov özelliği yine de API aracılığıyla değiştirilebilir. Aslında bir mobil cihazda fov özelliğini değiştirmenin tek yolu API'dir. Bu, varsayılan davranıştır.
  • Değer false olduğunda cihazın hareketleri 360 derece görüntüleme deneyimini etkilemez ve yaw, pitch, roll ve fov özelliklerinin tamamı API aracılığıyla ayarlanmalıdır.

Desteklenmeyen mobil cihazlar
enableOrientationSensor özellik değerinin, oynatma deneyimi üzerinde herhangi bir etkisi yoktur.

Oynatma listesinde video oynatma

player.nextVideo():Void
Bu işlev, oynatma listesindeki bir sonraki videoyu yükleyip oynatır.
  • Oynatma listesindeki son video izlenirken player.nextVideo() çağrılırsa ve oynatma listesi sürekli oynatılacak şekilde (loop) ayarlanırsa oynatıcı, listedeki ilk videoyu yükler ve oynatır.

  • Oynatma listesindeki son video izlenirken player.nextVideo() çağrılırsa ve oynatma listesi sürekli oynatılacak şekilde ayarlanmadıysa oynatma işlemi sona erer.

player.previousVideo():Void
Bu işlev, oynatma listesindeki önceki videoyu yükleyip oynatır.
  • Oynatma listesindeki ilk video izlenirken player.previousVideo() çağrılırsa ve oynatma listesi sürekli oynatılacak şekilde (loop) ayarlanırsa oynatıcı, listedeki son videoyu yükleyip oynatır.

  • Oynatma listesindeki ilk video izlenirken player.previousVideo() çağrılırsa ve oynatma listesi sürekli oynatılacak şekilde ayarlanmadıysa oynatıcı, ilk oynatma listesi videosunu baştan başlatır.

player.playVideoAt(index:Number):Void
Bu işlev, oynatma listesinde belirtilen videoyu yükleyip oynatır.
  • Gerekli index parametresi, oynatma listesinde oynatmak istediğiniz videonun dizinini belirtir. Parametre, sıfır tabanlı bir dizin kullandığından 0 değeri, listedeki ilk videoyu tanımlar. Oynatma listesini karıştırdıysanız bu işlev, videoyu karıştırılmış oynatma listesinde belirtilen konumda oynatır.

Oynatıcının ses seviyesini değiştirme

player.mute():Void
Oynatıcının sesini kapatır.
player.unMute():Void
Oyuncunun sesini açar.
player.isMuted():Boolean
Oynatıcının sesi kapalıysa true, kapalıysa false değerini döndürür.
player.setVolume(volume:Number):Void
Ses seviyesini ayarlar. 0 ile 100 arasında bir tam sayı kabul eder.
player.getVolume():Number
Oynatıcının mevcut ses seviyesini döndürür (0 ile 100 arasında bir tam sayı). Oynatıcının sesi kapalı olsa bile getVolume() cihazının sesi tekrar vereceğini unutmayın.

Oynatıcı boyutunu ayarlama

player.setSize(width:Number, height:Number):Object
Oynatıcıyı içeren <iframe> öğesinin piksel cinsinden boyutunu ayarlar.

Oynatma hızını ayarlama

player.getPlaybackRate():Number
Bu işlev, şu anda oynatılan videonun oynatma hızını getirir. Varsayılan oynatma hızı 1, videonun normal hızda oynatıldığını belirtir. Oynatma hızları 0.25, 0.5, 1, 1.5 ve 2 gibi değerleri içerebilir.
player.setPlaybackRate(suggestedRate:Number):Void
Bu işlev, mevcut video için önerilen oynatma hızını ayarlar. Oynatma hızı değişirse yalnızca seçilen veya oynatılan video için değişir. İşaretlenmiş bir video için oynatma hızını ayarlarsanız bu hız, playVideo işlevi çağrıldığında veya kullanıcı doğrudan oynatıcı kontrolleri aracılığıyla oynatmayı başlattığında geçerli olur. Ayrıca, videoları veya oynatma listelerini işaretlemek ya da yüklemek için işlevleri çağırmak (cueVideoById, loadVideoById vb.) oynatma hızını 1 olarak sıfırlar.

Bu işlevin çağrılması, oynatma hızının gerçekten değişeceğini garanti etmez. Bununla birlikte, oynatma hızı değişirse onPlaybackRateChange etkinliği tetiklenir ve kodunuz, setPlaybackRate işlevini çağırdığı için değil, etkinliğe yanıt vermelidir.

getAvailablePlaybackRates yöntemi, şu anda oynatılan video için olası oynatma hızlarını döndürür. Bununla birlikte, suggestedRate parametresini desteklenmeyen bir tam sayı veya kayan bir değere ayarlarsanız oynatıcı bu değeri, 1 yönünde desteklenen en yakın değere yuvarlar.
player.getAvailablePlaybackRates():Array
Bu işlev, geçerli videonun sunulduğu oynatma hızlarını döndürür. Varsayılan değer olan 1, videonun normal hızda oynatıldığını ifade eder.

İşlev, en yavaş oynatma hızından en hızlı oynatma hızına doğru sıralanmış bir sayı dizisi döndürür. Oynatıcı değişken oynatma hızlarını desteklemese bile dizi her zaman en az bir değer (1) içermelidir.

Oynatma listeleri için oynatma davranışını ayarlama

player.setLoop(loopPlaylists:Boolean):Void

Bu işlev, video oynatıcının bir oynatma listesini sürekli olarak oynatmasını veya oynatma listesindeki son video bittikten sonra oynatmayı durdurmasını belirtir. Varsayılan davranış, oynatma listelerinin döngüye alınmamasıdır.

Bu ayar, farklı bir oynatma listesi yükleseniz veya işaret etseniz bile devam eder. Diğer bir deyişle, bir şarkı listesi yüklerseniz true değeriyle setLoop işlevini çağırır ve ardından ikinci bir oynatma listesi yüklerseniz ikinci oynatma listesi de döngüye alınır.

Gerekli loopPlaylists parametresi, döngü davranışını tanımlar.

  • Parametre değeri true ise video oynatıcı, oynatma listelerini sürekli olarak oynatır. Oynatma listesindeki son video oynatıldıktan sonra video oynatıcı, oynatma listesinin başına geri döner ve videoyu tekrar oynatır.

  • Parametre değeri false ise video oynatıcı, oynatma listesindeki son videoyu oynattıktan sonra oynatmalar sona erer.

player.setShuffle(shufflePlaylist:Boolean):Void

Bu işlev, oynatma listesindeki videoların, oynatma listesi oluşturucusunun belirlediğinden farklı bir sırada oynatılacak şekilde karıştırılıp karıştırılmayacağını belirtir. Bir oynatma listesini oynatmaya başladıktan sonra karıştırırsanız oynatılan video oynatılmaya devam ederken liste yeniden sıralanır. Oynatılacak bir sonraki video, yeniden sıralanan listeye göre seçilir.

Farklı bir oynatma listesi yükler veya gösterirseniz bu ayar devam etmez. Diğer bir deyişle, bir oynatma listesi yükler, setShuffle işlevini çağırır ve ardından ikinci bir oynatma listesi yüklerseniz ikinci oynatma listesi karıştırılmaz.

Gerekli shufflePlaylist parametresi, YouTube'un oynatma listesini karıştırıp karıştırmayacağını ifade eder.

  • Parametre değeri true ise YouTube, oynatma listesi sırasını karıştırır. Fonksiyona, daha önce karıştırılmış bir oynatma listesini karıştırma talimatı verirseniz YouTube sıralamayı tekrar karıştırır.

  • Parametre değeri false ise YouTube, oynatma listesi sırasını orijinal sırasına geri döndürür.

Oynatma durumu

player.getVideoLoadedFraction():Float
0 ile 1 arasında, oynatıcının arabelleğe alınmış olarak gösterdiği videonun yüzdesini belirten bir sayı döndürür. Bu yöntem, kullanımdan kaldırılan getVideoBytesLoaded ve getVideoBytesTotal yöntemlerinden daha güvenilir bir sayı döndürür.
player.getPlayerState():Number
Oyuncunun durumunu döndürür. Olası değerler:
  • -1 – başlamadı
  • 0 – sona erdi
  • 1 - oynatılıyor
  • 2 - duraklatıldı
  • 3 - arabelleğe alınıyor
  • 5 – video seçildi
player.getCurrentTime():Number
Videonun oynatılmaya başlamasından itibaren geçen süreyi saniye cinsinden döndürür.
player.getVideoStartBytes():Number
31 Ekim 2012 itibarıyla kullanımdan kaldırılmıştır. Video dosyasının yüklenmeye başladığı bayt sayısını döndürür. (Bu yöntem artık her zaman 0 değerini döndürür.) Örnek senaryo: Kullanıcı henüz yüklenmemiş bir noktaya doğru ilerler ve oynatıcı, videonun henüz yüklenmeyen bir segmentini oynatmak için yeni bir istekte bulunur.
player.getVideoBytesLoaded():Number
18 Temmuz 2012 itibarıyla kullanımdan kaldırılmıştır. Bunun yerine, videonun arabelleğe alınan yüzdesini belirlemek için getVideoLoadedFraction yöntemini kullanın.

Bu yöntem, 0 ile 1000 arasında, yüklenen videonun miktarını yaklaşık olarak belirten bir değer döndürür. getVideoBytesLoaded değerini getVideoBytesTotal değerine bölerek videonun yüklenen oranını hesaplayabilirsiniz.
player.getVideoBytesTotal():Number
18 Temmuz 2012 itibarıyla kullanımdan kaldırılmıştır. Bunun yerine, videonun arabelleğe alınan yüzdesini belirlemek için getVideoLoadedFraction yöntemini kullanın.

Yüklenen/oynatılan videonun bayt cinsinden boyutunu veya yaklaşık video boyutunu döndürür.

Bu yöntem her zaman 1000 değerini döndürür. getVideoBytesLoaded değerini getVideoBytesTotal değerine bölerek videonun yüklenen oranını hesaplayabilirsiniz.

Video bilgilerini alma

player.getDuration():Number
Şu anda oynatılan videonun süresini saniye cinsinden döndürür. getDuration() işlevinin, videonun meta verileri yüklenene kadar (genellikle video oynatılmaya başladıktan hemen sonra gerçekleşir) 0 değerini döndüreceğini unutmayın.

Şu anda oynatılan video bir canlı etkinlik ise getDuration() işlevi, canlı video akışının başlamasından itibaren geçen süreyi döndürür. Daha ayrıntılı belirtmek gerekirse bu, videonun sıfırlanmadan veya kesintiye uğramadan yayınlandığı süredir. Ayrıca akış etkinliğin başlangıç zamanından önce başlayabileceği için bu süre genellikle gerçek etkinlik zamanından daha uzundur.
player.getVideoUrl():String
Şu anda yüklü olan/oynatılan videonun YouTube.com URL'sini döndürür.
player.getVideoEmbedCode():String
Şu anda yüklü olan/oynatılan videoya ilişkin yerleştirme kodunu döndürür.

Oynatma listesi bilgilerini alma

player.getPlaylist():Array
Bu işlev, oynatma listesindeki video kimlikleri dizisini şu anda sıralanmış şekilde döndürür. Varsayılan olarak bu işlev, video kimliklerini oynatma listesi sahibi tarafından belirlenen sırada döndürür. Bununla birlikte, oynatma listesi sırasını karıştırmak için setShuffle işlevini çağırdıysanız getPlaylist() işlevinin döndürülen değeri karıştırılan sırayı yansıtır.
player.getPlaylistIndex():Number
Bu işlev, oynatılan oynatma listesi videosunun dizinini döndürür.
  • Oynatma listesini karıştırmadıysanız döndürülen değer, oynatma listesi oluşturucunun videoyu yerleştirdiği konumu tanımlar. Döndürülen değer sıfır tabanlı bir dizin kullanır, dolayısıyla 0 değeri oynatma listesindeki ilk videoyu tanımlar.

  • Oynatma listesini karıştırdıysanız döndürülen değer, videonun karıştırılmış oynatma listesindeki sırasını tanımlar.

Etkinlik işleyici ekleme veya kaldırma

player.addEventListener(event:String, listener:String):Void
Belirtilen event için bir işleyici işlevi ekler. Aşağıdaki Etkinlikler bölümü, oyuncunun tetikleyebileceği farklı etkinlikleri tanımlar. İşleyici, belirtilen etkinlik tetiklendiğinde yürütülecek işlevi belirten bir dizedir.
player.removeEventListener(event:String, listener:String):Void
Belirtilen event için bir işleyici işlevini kaldırır. listener, belirtilen etkinlik tetiklendiğinde artık yürütülmeyecek işlevi tanımlayan bir dizedir.

DOM düğümlerine erişme ve bunları değiştirme

player.getIframe():Object
Bu yöntem, yerleştirilmiş <iframe> için DOM düğümünü döndürür.
player.destroy():Void
Oynatıcıyı içeren <iframe> öğesini kaldırır.

Etkinlikler

API, yerleştirilmiş oynatıcıda yapılan değişiklikleri uygulamanızı bildirmek için etkinlikleri tetikler. Önceki bölümde belirtildiği gibi, YT.Player nesnesini oluştururken bir etkinlik işleyici ekleyerek etkinliklere abone olabilir ve addEventListener işlevini de kullanabilirsiniz.

API, bir etkinlik nesnesini bu işlevlerin her birine tek bağımsız değişken olarak iletir. Etkinlik nesnesi aşağıdaki özelliklere sahiptir:

  • Etkinliğin target öğesi, etkinliğe karşılık gelen video oynatıcıyı tanımlar.
  • Etkinliğin data özelliği, etkinlikle ilgili bir değeri belirtiyor. onReady ve onAutoplayBlocked etkinliklerinin bir data özelliği belirtmediğini unutmayın.

Aşağıdaki listede API'nin tetiklediği etkinlikler tanımlanmaktadır:

onReady
Bu etkinlik, oynatıcının yüklenmesi tamamlandığında ve API çağrıları almaya hazır olduğunda tetiklenir. Video oynatma veya video hakkında bilgi görüntüleme gibi belirli işlemleri oynatıcı hazır olur olmaz otomatik olarak yürütmek istiyorsanız uygulamanız bu işlevi uygulamalıdır.

Aşağıdaki örnekte, bu etkinliğin işlenmesine yönelik bir örnek işlev gösterilmektedir. API'nin işleve gönderdiği etkinlik nesnesi, oynatıcıyı tanımlayan bir target özelliğine sahiptir. İşlev, yüklenmiş olan videonun yerleştirme kodunu alır, videoyu oynatmaya başlar ve yerleştirme kodunu, id değeri embed-code olan sayfa öğesinde gösterir.
function onPlayerReady(event) {
  var embedCode = event.target.getVideoEmbedCode();
  event.target.playVideo();
  if (document.getElementById('embed-code')) {
    document.getElementById('embed-code').innerHTML = embedCode;
  }
}
onStateChange
Bu etkinlik, oyuncunun durumu her değiştiğinde tetiklenir. API'nin etkinlik işleyici işlevinize ilettiği etkinlik nesnesinin data özelliği, yeni oynatıcı durumuna karşılık gelen bir tam sayı belirtir. Olası değerler:

  • -1 (başlamadı)
  • 0 (sona erdi)
  • 1 (oynuyor)
  • 2 (duraklatıldı)
  • 3 (arabelleğe alınıyor)
  • 5 (video seçme).

Oynatıcı bir videoyu ilk kez yüklediğinde bir unstarted (-1) etkinliği yayınlar. Bir video işaretlenip oynatılmaya hazır olduğunda oynatıcı bir video cued (5) etkinliği yayınlar. Kodunuzda tam sayı değerlerini belirtebilir veya aşağıdaki ad alanı değişkenlerinden birini kullanabilirsiniz:

  • YT.PlayerState.ENDED
  • YT.PlayerState.PLAYING
  • YT.PlayerState.PAUSED
  • YT.PlayerState.BUFFERING
  • YT.PlayerState.CUED

onPlaybackQualityChange
Bu etkinlik, video oynatma kalitesi her değiştiğinde tetiklenir. İzleyicinin oynatma ortamında bir değişiklik olduğunu gösterebilir. Oynatma koşullarını etkileyen veya etkinliğin tetiklenmesine neden olabilecek faktörler hakkında daha fazla bilgi için YouTube Yardım Merkezi'ne bakın.

API'nin etkinlik işleyici işlevine gönderdiği etkinlik nesnesinin data özellik değeri, yeni oynatma kalitesini tanımlayan bir dize olur. Olası değerler:

  • small
  • medium
  • large
  • hd720
  • hd1080
  • highres

onPlaybackRateChange
Bu etkinlik, video oynatma hızı her değiştiğinde tetiklenir. Örneğin, setPlaybackRate(suggestedRate) işlevini çağırırsanız bu etkinlik, oynatma hızı gerçekten değişirse tetiklenir. Uygulamanız etkinliğe yanıt vermeli ve setPlaybackRate(suggestedRate) işlevi çağrıldığında oynatma hızının otomatik olarak değişeceğini varsaymamalıdır. Benzer şekilde, kodunuz, video oynatma hızının yalnızca setPlaybackRate öğesine açık bir çağrının sonucu olarak değişeceğini varsaymamalıdır.

API'nin etkinlik işleyici işlevine ilettiği etkinlik nesnesinin data özellik değeri, yeni oynatma hızını tanımlayan bir sayı olur. getAvailablePlaybackRates yöntemi, geçerli olarak seçilmiş veya oynatılan video için geçerli oynatma hızlarının listesini döndürür.
onError
Oynatıcıda bir hata oluşursa bu etkinlik tetiklenir. API, etkinlik işleyici işlevine bir event nesnesi iletir. Bu nesnenin data özelliği, oluşan hatanın türünü tanımlayan bir tam sayı belirtir. Olası değerler:

  • 2 – İstek geçersiz bir parametre değeri içeriyor. Örneğin bu hata, 11 karakteri olmayan bir video kimliği belirtirseniz veya video kimliği ünlem işaretleri ya da yıldız işaretleri gibi geçersiz karakterler içeriyorsa ortaya çıkar.
  • 5 – İstenen içerik bir HTML5 oynatıcısında oynatılamıyor veya HTML5 oynatıcısıyla ilgili başka bir hata oluştu.
  • 100 – İstenen video bulunamadı. Bu hata, bir video kaldırıldığında (herhangi bir nedenle) veya özel olarak işaretlendiğinde ortaya çıkar.
  • 101: İstenen videonun sahibi, videonun yerleşik oynatıcılarda oynatılmasına izin vermiyor.
  • 150 – Bu hata 101 ile aynıdır. Bu sadece 101 gizlenmiş bir hata.
onApiChange
Bu etkinlik, oynatıcının açık API yöntemleriyle bir modül yüklediğini (veya kaldırdığını) göstermek için tetiklenir. Uygulamanız bu etkinliği dinleyebilir ve ardından son yüklenen modül için hangi seçeneklerin gösterileceğini belirlemek üzere oynatıcıyı yoklayabilir. Daha sonra uygulamanız bu seçenekler için mevcut ayarları alabilir veya güncelleyebilir.

Aşağıdaki komut, oynatıcı seçeneklerini ayarlayabileceğiniz bir modül adları dizisi alır:
player.getOptions();
Şu anda seçenekleri ayarlayabileceğiniz tek modül, oynatıcıda altyazı işleyen captions modülüdür. Uygulamanız, bir onApiChange etkinliği aldıktan sonra captions modülü için hangi seçeneklerin ayarlanabileceğini belirlemek üzere aşağıdaki komutu kullanabilir:
player.getOptions('captions');
Oynatıcıyı bu komutla yoklayarak erişmek istediğiniz seçeneklerin gerçekten erişilebilir olduğunu onaylayabilirsiniz. Aşağıdaki komutlar modül seçeneklerini alır ve günceller:
Retrieving an option:
player.getOption(module, option);

Setting an option
player.setOption(module, option, value);
Aşağıdaki tabloda API'nin desteklediği seçenekler listelenmiştir:

Modül Option Açıklama
captions fontSize Bu seçenek, oynatıcıda gösterilen altyazıların yazı tipi boyutunu ayarlar.

Geçerli değerler: -1, 0, 1, 2 ve 3. Varsayılan boyut 0, en küçük boyut ise -1'dir. Bu seçeneğin -1 değerinin altında bir tam sayı olarak ayarlanması en küçük altyazı boyutunun gösterilmesine neden olurken, bu seçeneğin 3 üzerinde bir tam sayı olarak ayarlanması en büyük altyazı boyutunun gösterilmesine neden olur.
captions yeniden yükleme Bu seçenek, oynatılan videoya ilişkin altyazı verilerini yeniden yükler. Seçeneğin değerini alırsanız değer null olur. Altyazı verilerini yeniden yüklemek için değeri true olarak ayarlayın.
onAutoplayBlocked
Bu etkinlik, tarayıcı otomatik oynatmayı veya komut dosyası tabanlı video oynatma özelliklerini engellediğinde tetiklenir. Bunlara toplu olarak "otomatik oynatma" denir. Buna, aşağıdaki oynatıcı API'lerinden herhangi biriyle denenen oynatmalar da dahildir:

Çoğu tarayıcının, belirli koşullar doğru olması halinde masaüstü, mobil ve diğer ortamlarda otomatik oynatmayı engelleyebilecek politikaları vardır. Bu politikanın tetiklenebileceği örnekler arasında kullanıcı etkileşimi olmadan sesi açılmış oynatma veya kaynaklar arası iframe'de otomatik oynatmaya izin veren bir İzin Politikası ayarlanmadığı durumlar yer alır.

Ayrıntıların tamamı için tarayıcıya özel politikaları (Apple Safari / Webkit, Google Chrome, Mozilla Firefox) ve Mozilla'nın otomatik oynatma kılavuzunu inceleyin.

Örnekler

YT.Player nesne oluşturuluyor

  • Örnek 1: API'yi mevcut <iframe> ile kullanma

    Bu örnekte, sayfadaki <iframe> öğesi, API'nin birlikte kullanılacağı oynatıcıyı zaten tanımlıyor. Oynatıcının src URL'sinin enablejsapi parametresinin 1 olarak ayarlanması veya <iframe> öğesinin enablejsapi özelliğinin true olarak ayarlanması gerektiğini unutmayın.

    onPlayerReady işlevi, oynatıcı hazır olduğunda oynatıcının çevresindeki kenarlığın rengini turuncuya dönüştürür. onPlayerStateChange işlevi daha sonra, mevcut oynatıcı durumuna göre oynatıcının çevresindeki kenarlığın rengini değiştirir. Örneğin, renk oynatıcı oynarken yeşil, duraklatıldığında kırmızı, arabelleğe alırken mavi vb.

    Bu örnekte aşağıdaki kod kullanılmaktadır:

    <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. Örnek: Yüksek sesli oynatma

    Bu örnekte 1280 piksele 720 piksel boyutunda bir video oynatıcı oluşturulur. Ardından onReady etkinliğinin etkinlik işleyici ses düzeyini en yüksek ayara ayarlamak için setVolume işlevini çağırır.

    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. Örnek: Bu örnekte, oynatıcı parametreleri, videoyu yüklendiğinde otomatik olarak oynatacak ve video oynatıcının kontrollerini gizleyecek şekilde ayarlanmıştır. Ayrıca, API'nin yayınladığı çeşitli etkinlikler için etkinlik işleyiciler de ekler.

    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 derece videoları kontrol etme

Bu örnekte aşağıdaki kod kullanılmaktadır:

<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>

Düzeltme geçmişi

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.