YouTube Player API Reference for iframe Embeds

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

API'nin JavaScript işlevlerini kullanarak videoları oynatılmak üzere sıraya ekleyebilir, oynatabilir, duraklatabilir veya durdurabilir, oynatıcı sesini ayarlayabilir ya da oynatılan videoyla ilgili bilgileri alabilirsiniz. Ayrıca, oynatıcı durumu değişikliği gibi belirli oynatıcı etkinliklerine yanıt olarak çalışacak etkinlik dinleyicileri 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 dinleyicilerinin 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 ayrıntılı olarak açıklanmaktadır.

Şartlar

Kullanıcının tarayıcısı, HTML5 postMessage özelliğini desteklemelidir. Çoğu modern tarayıcı postMessage'ü 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'yi kullanan tüm web sayfaları aşağıdaki JavaScript işlevini de uygulamalıdır:

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

Başlarken

Aşağıdaki örnek HTML sayfası, bir videoyu yükleyip altı saniye boyunca oynatacak ve ardından oynatmayı durduracak yerleşik bir oynatıcı oluşturur. HTML'deki numaralı yorumlar, ö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'nin video oynatıcıyı yerleştireceği sayfadaki konumu tanımlar. Video oynatıcı yükleme bölümünde açıklanan oynatıcı nesnesinin kurucusu, API'nin <iframe> öğesini doğru konuma yerleştirmesini sağlamak için <div> etiketini id ile tanımlar. Daha açık belirtmek gerekirse IFrame API, <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 bu işlemi nasıl yapacağınız açıklanmaktadır.

  2. Bu bölümdeki kod, IFrame Player API JavaScript kodunu yükler. Örnekte, API kodunun ayarsız bir şekilde alınmasını sağlamak için DOM değişikliği kullanılarak API kodu indirilir. (<script> etiketinin, eşzamansız indirmeleri de etkinleştiren async özelliği, bu Stack Overflow yanıtında belirtildiği gibi henüz tüm modern tarayıcılarda desteklenmemektedir.

  3. onYouTubeIframeAPIReady işlevi, oynatıcı API kodu indirildikten hemen sonra yürütülür. Kodun bu kısmı, yerleştirdiğiniz video oynatıcıyı belirten player adlı bir genel değişken tanımlar ve işlev daha sonra video oynatıcı nesnesini oluşturur.

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

  5. API, oynatıcının durumu değiştiğinde onPlayerStateChange işlevini çağırır. Bu durum, oynatıcının oynatıldığını, duraklatıldığını, bittiğini vb. gösterebilir. İşlev, oynatıcı durumu 1 (oynatma) olduğunda oynatıcının altı saniye boyunca oynatılması ve ardından videoyu durdurmak için stopVideo işlevinin çağrılması gerektiğini 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ında, yukarıdaki örnekteki onYouTubeIframeAPIReady işlevi gösterilmektedir:

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ının kurucusu aşağıdaki parametreleri belirtir:

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

    IFrame API, belirtilen öğeyi oynatıcıyı içeren <iframe> öğesiyle değiştirir. Değiştirilen öğenin, eklenen <iframe> öğesinden farklı bir görüntüleme stili varsa bu durum sayfanızın düzenini etkileyebilir. Varsayılan olarak <iframe>, 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.
    • height (sayı) – Video oynatıcının yüksekliği. Varsayılan değer: 390.
    • 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 dinleyicileri) tanımlar. Örnekte, kurucu onPlayerReady işlevinin onReady etkinliği tetiklendiğinde ve onPlayerStateChange işlevinin onStateChange etkinliği tetiklendiğinde çalışacağını belirtir.

Başlangıç bölümünde belirtildiği gibi, sayfanıza boş bir <div> öğesi yazmak yerine (bu öğe, oynatıcı API'sinin JavaScript kodu tarafından <iframe> öğesiyle değiştirilir) <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 <iframe> etiketinin özellikleri olarak belirtilen width ve height için veya src URL'sinde belirtilen videoId ve oynatıcı parametreleri için değer belirtmeniz gerekmediğini unutmayın. Ek bir güvenlik önlemi olarak, URL şemasını (http:// veya https://) ve barındırma sayfanızı tam alan adını parametre değeri olarak belirterek URL'ye origin parametresini de eklemeniz gerekir. origin isteğe bağlı olsa da bu özelliği eklemek, sayfanıza kötü amaçlı üçüncü taraf JavaScript'in yerleştirilmesine ve YouTube oynatıcınızın kontrolünün ele geçirilmesine karşı koruma sağlar.

Video oynatıcı nesneleri oluşturmayla ilgili diğer örnekler için Örnekler bölümüne bakın.

İşlemler

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

İşlevler

İşlevleri sıraya ekleme

Sıraya ekleme işlevleri, video, oynatma listesi veya başka bir video listesi yüklemenize ve 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ının yüklediği videoların listesini de sıraya ekleyebilir veya yükleyebilirsiniz.

API, sıra işlevlerini çağırırken iki farklı söz dizimi destekler.

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

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

Örneğin, loadVideoById işlevi aşağıdaki yöntemlerden biriyle çağrılabilir. Nesne söz diziminde, bağımsız değişken söz diziminde desteklenmeyen endSeconds mülkünün desteklendiğ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ı sıraya alma 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.

  • Zorunlu videoId parametresi, oynatılacak videonun YouTube video kimliğini belirtir. YouTube Data API'de, video kaynağının id mülkü kimliği belirtir.
  • İsteğe bağlı startSeconds parametresi, kayan nokta/tam sayı kabul eder ve playVideo() çağrıldığında videonun oynatılmaya başlayacağı zamanı belirtir. Bir startSeconds değeri belirtip ardından seekTo() çağrısı yaparsanız oynatıcı, seekTo() çağrısında belirtilen zamandan itibaren oynatmaya başlar. 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 nokta/tam sayı kabul eder ve playVideo() çağrıldığında videonun oynatılmasının ne zaman durdurulması gerektiğini belirtir. Bir endSeconds değeri belirtip ardından seekTo() işlevini ç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.

  • Zorunlu videoId parametresi, oynatılacak videonun YouTube video kimliğini belirtir. YouTube Data API'de, video kaynağının id mülkü kimliği belirtir.
  • İsteğe bağlı startSeconds parametresi, kayan nokta/tam sayı kabul eder. Bu değer belirtilirse video, belirtilen zamana en yakın ana kareden başlar.
  • İsteğe bağlı endSeconds parametresi, kayan nokta/tam sayı kabul eder. Belirtilen süre dolduktan sonra videonun oynatılması durdurulur.

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.

  • Zorunlu mediaContentUrl parametresi, http://www.youtube.com/v/VIDEO_ID?version=3 biçiminde tam nitelikli bir YouTube oynatıcı URL'sini belirtir.
  • İsteğe bağlı startSeconds parametresi, kayan nokta/tam sayı kabul eder ve playVideo() çağrıldığında videonun oynatılmaya başlayacağı zamanı belirtir. startSeconds'ü belirtip ardından seekTo()'ü çağırırsanız oynatıcı, seekTo() çağrısında belirtilen zamandan itibaren oynatmaya başlar. 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 nokta/tam sayı kabul eder ve playVideo() çağrıldığında videonun oynatılmasının ne zaman durdurulması gerektiğini belirtir. Bir endSeconds değeri belirtip ardından seekTo() işlevini ç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.

  • Zorunlu mediaContentUrl parametresi, http://www.youtube.com/v/VIDEO_ID?version=3 biçiminde tam nitelikli bir YouTube oynatıcı URL'sini belirtir.
  • İsteğe bağlı startSeconds parametresi, kayan nokta/tam sayı kabul eder ve videonun oynatılmaya başlayacağı zamanı belirtir. startSeconds (sayı, kayan nokta olabilir) belirtilirse video, belirtilen zamana en yakın ana kareden başlar.
  • Yalnızca nesne söz diziminde desteklenen isteğe bağlı endSeconds parametresi, kayan nokta/tam sayı kabul eder ve videonun oynatılmasının durdurulacağı zamanı belirtir.

Listeler için işlevleri sıraya ekleme

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

İşlevler, bağımsız değişken söz dizimi mi yoksa nesne söz dizimi mi kullanılarak çağrıldıklarına bağlı olarak farklı şekilde çalıştığından, her iki çağrı yöntemi de 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 ekler. Oynatma listesi işaretlenip çalmaya hazır olduğunda oynatıcı bir video cued etkinliği (5) yayınlar.

    • Zorunlu playlist parametresi, bir YouTube video kimliği dizisi belirtir. YouTube Data API'de video kaynağının id özelliği, ilgili videonun kimliğini tanımlar.

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

    • İsteğe bağlı startSeconds parametresi, kayan nokta/tam sayı kabul eder ve playVideo() işlevi çağrıldığında oynatma listesindeki ilk videonun oynatılmaya başlama zamanını belirtir. Bir startSeconds değeri belirtip ardından seekTo() çağrısı yaparsanız oynatıcı, seekTo() çağrısında belirtilen zamandan itibaren oynatmaya başlar. Bir oynatma listesini işaretleyip playVideoAt() işlevini çağırırsanız oynatıcı, belirtilen videonun başından oynatmaya başlar.

  • Nesne söz dizimi

    player.cuePlaylist({listType:String,
                    list:String,
                    index:Number,
                    startSeconds:Number}):Void
     Belirtilen video listesini sıraya ekler. Liste, bir oynatma listesi veya kullanıcının yüklediği video feed'i olabilir. Arama sonuçları listesini sıraya ekleme özelliğinin desteği sonlandırılmıştır ve 15 Kasım 2020 itibarıyla artık desteklenmeyecektir.

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

    • İsteğe bağlı listType mülkü, aldığınız sonuç feed'inin türünü belirtir. Geçerli değerler playlist ve user_uploads'dir. Desteği sonlandırılan search değeri, 15 Kasım 2020 itibarıyla artık desteklenmeyecek. Varsayılan değer: playlist.

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

      • listType mülk değeri playlist ise list mülkü, oynatma listesi kimliğini veya bir video kimlikleri dizisini belirtir. YouTube Data API'de playlist kaynağının id özelliği bir oynatma listesinin kimliğini, video kaynağının id özelliği ise bir video kimliğini belirtir.
      • listType mülk değeri user_uploads ise list mülkü, yüklediği videoların döndürüleceği kullanıcıyı tanımlar.
      • listType mülk değeri search ise list mülkü arama sorgusunu belirtir. Not: Bu işlev desteği sonlandırılmış ve 15 Kasım 2020 itibarıyla artık desteklenmeyecek.

    • İsteğe bağlı index mülkü, listedeki oynatılacak ilk videonun dizesini 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 mülkü, kayan nokta/tam sayı kabul eder ve playVideo() işlevi çağrıldığında listedeki ilk videonun oynatılmaya başlama zamanını belirtir. Bir startSeconds değeri belirtip ardından seekTo() çağrısı yaparsanız oynatıcı, seekTo() çağrısında belirtilen zamandan itibaren oynatmaya başlar. Bir listeyi işaretleyip playVideoAt() işlevini çağırırsanız oynatıcı, belirtilen videonun başından oynatmaya 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 çalar.

    • Zorunlu playlist parametresi, bir YouTube video kimliği dizisi belirtir. YouTube Data API'de video kaynağının id mülkü bir video kimliği belirtir.

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

    • İsteğe bağlı startSeconds parametresi, kayan nokta/tam sayı kabul eder ve oynatma listesinde ilk videonun oynatılmaya başlama zamanını belirtir.

  • Nesne söz dizimi

    player.loadPlaylist({list:String,
                     listType:String,
                     index:Number,
                     startSeconds:Number}):Void
     Bu işlev, belirtilen listeyi yükler ve çalar. Liste, bir oynatma listesi veya kullanıcının yüklediği video feed'i olabilir. Arama sonuçlarının listesini yükleme özelliğinin desteği sonlandırılmıştır ve 15 Kasım 2020 itibarıyla artık desteklenmeyecektir.

    • İsteğe bağlı listType mülkü, aldığınız sonuç feed'inin türünü belirtir. Geçerli değerler playlist ve user_uploads'dir. Desteği sonlandırılan search değeri, 15 Kasım 2020 itibarıyla artık desteklenmeyecek. Varsayılan değer: playlist.

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

      • listType mülk değeri playlist ise list mülkü bir 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, video kaynağının id özelliği ise bir video kimliğini belirtir.
      • listType mülk değeri user_uploads ise list mülkü, yüklediği videoların döndürüleceği kullanıcıyı tanımlar.
      • listType mülk değeri search ise list mülkü arama sorgusunu belirtir. Not: Bu işlev desteği sonlandırılmış ve 15 Kasım 2020 itibarıyla artık desteklenmeyecek.

    • İsteğe bağlı index mülkü, listedeki oynatılacak ilk videonun dizesini 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 mülkü, kayan nokta/tam sayı kabul eder ve listedeki ilk videonun oynatılmaya başlama zamanını belirtir.

Oynatma kontrolleri ve oynatıcı ayarları

Video oynatma

player.playVideo():Void
Şu anda işaretlenmiş/yüklenmiş videoyu oynatır. Bu işlev çalıştırıldıktan sonra oynatıcının son durumu playing (1) olur.

Not: Bir oynatma işlemi, yalnızca oynatıcıdaki yerel bir oynat düğmesi aracılığıyla başlatılırsa videonun resmi görüntüleme sayısına dahil edilir.
player.pauseVideo():Void
Oynatılan videoyu duraklatır. Bu işlev çalıştırıldıktan sonra nihai oynatıcı durumu paused (2) olur. Ancak işlev çağrılırken oynatıcı ended (0) durumundaysa oynatıcı durumu değişmez.
player.stopVideo():Void
Mevcut videonun yüklenmesini durdurur ve iptal eder. Bu işlev, kullanıcının oynatıcıda başka video izleyeceğini bilmediğ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 istiyorsanız önce stopVideo işlevini çağırmadan sıraya ekleme 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 oynatılmayan duruma geçirebilir.
player.seekTo(seconds:Number, allowSeekAhead:Boolean):Void
Videoda belirtilen bir zamana gider. İşlev çağrılırken oynatıcı duraklatılmışsa 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 ilerlemesi gereken zamanı tanımlar.

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

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

    Kullanıcı fareyi video ilerleme çubuğunda sürüklerken bu parametreyi false olarak ayarlayıp 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 bıraktığında oynatıcı videoda istenen noktaya ilerler ve gerekirse yeni bir video akışı ister.

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

Not: 360° video oynatma deneyimi, mobil cihazlarda sınırlı destek alır. Desteklenmeyen cihazlarda 360° videolar bozuk görünür ve API üzerinden, yön sensörlerini kullanarak veya cihazın ekranındaki dokunma/sürükleme işlemlerine yanıt vererek görüntüleme perspektifini değiştirmenin hiçbir yolu desteklenmez.

player.getSphericalProperties():Object
Bir video oynatmanın izleyicinin mevcut bakış açısını veya görünümünü açıklayan özellikleri alır. Ayrıca:
  • Bu nesne yalnızca küresel videolar olarak da bilinen 360° videolar için doldurulur.
  • Geçerli video 360° 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 olarak ayarlanmışsa bu işlev, fov özelliğinin doğru değeri içerdiği ve diğer özelliklerin 0 olarak ayarlandığı bir nesne döndürür.
Nesne aşağıdaki özellikleri içerir:
Özellikler
yaw [0, 360) aralığında bir sayı. Görünümün yatay açısını derece cinsinden temsil eder. Kullanıcının görünümü daha sola veya sağa çevirme derecesini yansıtır. Eşit dikdörtgen projeksiyonda videonun merkezine bakan nötr konum 0°'yi temsil eder. İzleyici sola döndükçe bu değer artar.
pitch [-90, 90] aralığındaki bir sayı. Görüntünün dikey açısını derece cinsinden temsil eder. Kullanıcının görüntüyü yukarı veya aşağı bakacak şekilde ne kadar ayarladığını yansıtır. Eş dikdörtgensel projeksiyonda videonun merkezine bakan nötr konum 0°'yi temsil eder ve izleyici yukarı baktıkça bu değer artar.
roll Görüntünü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şit dikdörtgen projeksiyondaki yatay eksenin görünümün yatay eksenine paralel olduğu nötr konum 0°'yi temsil eder. Görünüm saat yönünde döndükçe değer artar, saat yönünün tersine döndükçe azalır.

Yerleştirilmiş oynatıcının, görüntünün eğimini ayarlamak için bir kullanıcı arayüzü sunmadığını unutmayın. Döndürme, birbirini dışlayan aşağıdaki yöntemlerden biriyle ayarlanabilir:
  1. Görüntü için yuvarlanma sağlamak üzere mobil tarayıcıda yön sensörünü kullanın. Yön sensörü etkinse getSphericalProperties işlevi, roll mülkünün değeri olarak her zaman 0 değerini döndürür.
  2. Yönlendirme sensörü devre dışıysa bu API'yi kullanarak ruloyu sıfır olmayan bir değere ayarlayın.
fov Görüntü alanının daha uzun kenarı boyunca ölçülen derece cinsinden görüntünün görüş alanını temsil eden [30, 120] aralığında bir sayı. Daha kısa kenar, görüntünün en boy oranına 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, değeri artırmak ise uzaklaştırmak gibidir. Bu değer, API kullanılarak veya video tam ekran modundayken fare tekerleği kullanılarak ayarlanabilir.
player.setSphericalProperties(properties:Object):Void
360° videonun oynatılması için video yönünü ayarlar. (Mevcut video küresel değilse yöntem, girişten bağımsız olarak hiçbir işlem yapmaz.)

Oynatıcı görünümü, properties nesnesinde bilinen tüm özelliklerin değerlerini yansıtacak şekilde güncellenerek bu yönteme yapılan çağrılara yanıt verir. Görünüm, söz konusu nesneye dahil edilmeyen bilinen diğer tüm özelliklerin değerlerini korur.

Ayrıca:
  • Nesne bilinmeyen ve/veya beklenmedik özellikler içeriyorsa oynatıcı bunları yoksayar.
  • Bu bölümün başında belirtildiği gibi, 360° video oynatma deneyimi tüm mobil cihazlarda desteklenmez.
  • Varsayılan olarak, desteklenen mobil cihazlarda bu işlev yalnızca fov mülkünü ayarlar ve 360° video oynatmalar için yaw, pitch ve roll mülklerini etkilemez. Daha fazla bilgi için aşağıdaki enableOrientationSensor mülküne bakın.
İşleve iletilen properties nesnesi aşağıdaki özellikleri içerir:
Özellikler
yaw Yukarıdaki tanıma bakın.
pitch Yukarıdaki tanıma bakın.
roll Yukarıdaki tanıma bakın.
fov Yukarıdaki tanıma bakın.
enableOrientationSensor Not: Bu özellik yalnızca desteklenen cihazlardaki 360° izleme deneyimini etkiler. IFrame yerleştirilmesinin, desteklenen bir cihazın yönelimindeki değişiklikleri (ör. mobil tarayıcının DeviceOrientationEvent) belirten olaylara yanıt verip vermeyeceğini belirten bir boole değeridir. Varsayılan parametre değeri true'tür.

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 hareketini kullanır. Ancak fov mülkü API aracılığıyla değiştirilmeye devam edebilir. Aslında API, fov mülkünü mobil cihazda değiştirmenin tek yoludur. Bu varsayılan davranıştır.
  • Değer false olduğunda cihazın hareketi 360° izleme deneyimini etkilemez ve yaw, pitch, roll ve fov özelliklerinin tümü API aracılığıyla ayarlanmalıdır.

Desteklenmeyen mobil cihazlar
enableOrientationSensor mülk değerinin oynatma deneyimi üzerinde herhangi bir etkisi yoktur.

Oynatma listesindeki bir videoyu oynatma

player.nextVideo():Void
Bu işlev, oynatma listesindeki bir sonraki 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 ayarlanmışsa (loop) 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 ayarlanmamışsa oynatma sona erer.

player.previousVideo():Void
Bu işlev, oynatma listesindeki bir önceki videoyu yükler ve oynatır.

  • Oynatma listesindeki ilk video izlenirken player.previousVideo() çağrılırsa ve oynatma listesi sürekli oynatılacak şekilde ayarlanmışsa (loop) oynatıcı, listedeki son videoyu yükler ve oynatır.

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

player.playVideoAt(index:Number):Void
Bu işlev, oynatma listesinde belirtilen videoyu yükler ve oynatır.

  • Zorunlu index parametresi, oynatma listesinde oynatmak istediğiniz videonun dizesini 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ışık 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
Oynatıcının sesini açar.
player.isMuted():Boolean
Oynatıcının sesi kapalıysa true, kapalı değilse false değerini döndürür.
player.setVolume(volume:Number):Void
Sesi ayarlar. 0 ile 100 arasında bir tam sayı kabul eder.
player.getVolume():Number
Oynatıcının mevcut ses seviyesini (0 ile 100 arasında bir tam sayı) döndürür. getVolume(), oynatıcı sessiz olsa bile ses seviyesini döndürür.

Oynatıcı boyutunu ayarlama

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

Oynatma hızını ayarlama

player.getPlaybackRate():Number
Bu işlev, oynatılmakta olan videonun oynatma hızını alır. Varsayılan oynatma hızı 1'tür. Bu, videonun normal hızda oynatıldığını gösterir. Oynatma hızları 0.25, 0.5, 1, 1.5 ve 2 gibi değerler içerebilir.
player.setPlaybackRate(suggestedRate:Number):Void
Bu işlev, mevcut video için önerilen oynatma hızını ayarlar. Oynatma hızı yalnızca işaretlenmiş veya oynatılan video için değişir. İşaretlenmiş bir videonun oynatma hızını ayarlarsanız playVideo işlevi çağrıldığında veya kullanıcı oynatmayı doğrudan oynatıcı kontrolleri aracılığıyla başlattığında bu hız geçerli olmaya devam eder. Ayrıca, videoları veya oynatma listelerini sıraya eklemek 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. Ancak oynatma hızı değişirse onPlaybackRateChange etkinliği tetiklenir ve kodunuz setPlaybackRate işlevini çağırması yerine etkinliğe yanıt vermelidir.

getAvailablePlaybackRates yöntemi, oynatılmakta olan videonun oynatma hızlarını döndürür. Ancak suggestedRate parametresini desteklenmeyen bir tam sayı veya kayan değere ayarlarsanız oynatıcı bu değeri 1 yönünde en yakın desteklenen değere yuvarlar.
player.getAvailablePlaybackRates():Array
Bu işlev, mevcut videonun oynatılabileceği oynatma hızlarını döndürür. Varsayılan değer 1'tür. Bu değer, videonun normal hızda oynatıldığını gösterir.

İşlev, en yavaştan en hızlıya 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 oynatıp oynatmayacağını veya oynatma listesindeki son video bittikten sonra oynatmayı durdurup durdurmayacağını belirtir. Varsayılan davranış, oynatma listelerinin tekrarlanmaması şeklindedir.

Bu ayar, farklı bir oynatma listesi yükleseniz veya sıraya ekleseniz bile geçerliliğini korur. Yani bir oynatma listesi yükler, setLoop işlevini true değeriyle çağırır ve ardından ikinci bir oynatma listesi yüklerseniz ikinci oynatma listesi de döngüde oynatılır.

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

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

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

player.setShuffle(shufflePlaylist:Boolean):Void

Bu işlev, oynatma listesindeki videoların oynatma listesi oluşturucusunun belirttiği sırayla değil de rastgele oynatılması gerekip gerekmediğini belirtir. Oynatma listesi oynatılmaya başladıktan sonra şarkıları karıştırırsanız oynatılan video oynatılmaya devam ederken liste yeniden sıralanır. Ardından, oynatılacak bir sonraki video yeniden sıralanan listeye göre seçilir.

Farklı bir oynatma listesi yüklerseniz veya sıraya eklerseniz bu ayar geçerliliğini yitirir. Yani bir oynatma listesi yükleyip setShuffle işlevini çağırdıktan sonra ikinci bir oynatma listesi yüklerseniz ikinci oynatma listesi karıştırılmaz.

Zorunlu shufflePlaylist parametresi, YouTube'un oynatma listesini karıştırıp karıştırmayacağını belirtir.

  • Parametre değeri true ise YouTube, oynatma listesi sırasını karıştırır. İşleve, daha önce karışık oynatılmış bir şarkı listesini karışık oynatmasını söylerseniz YouTube, sırayı tekrar karıştırır.

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

Oynatma durumu

player.getVideoLoadedFraction():Float
Oynatıcının arabelleğe alınmış olarak gösterdiği video yüzdesini belirten 0 ile 1 arasında bir sayı döndürür. Bu yöntem, desteği sonlandırılmış getVideoBytesLoaded ve getVideoBytesTotal yöntemlerine kıyasla daha güvenilir bir sayı döndürür.
player.getPlayerState():Number
Oyuncunun durumunu döndürür. Olası değerler:
  • -1 – başlatılmadı
  • 0 – sonlandırıldı
  • 1 – oynatılıyor
  • 2 – duraklatıldı
  • 3 – arabelleğe alma
  • 5 – video işaretlendi
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 desteği sonlandırıldı. 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 atlar ve oynatıcı, videonun henüz yüklenmemiş bir segmentini oynatmak için yeni bir istek gönderir.
player.getVideoBytesLoaded():Number
18 Temmuz 2012'den itibaren desteği sonlandırıldı. Bunun yerine, videonun arabelleğe alınan yüzdesini belirlemek için getVideoLoadedFraction yöntemini kullanın.

Bu yöntem, yüklenmiş videonun miktarına yaklaşık olarak 0 ile 1000 arasında bir değer döndürür. getVideoBytesLoaded değerini getVideoBytesTotal değerine bölerek videonun yüklenmiş kısmını hesaplayabilirsiniz.
player.getVideoBytesTotal():Number
18 Temmuz 2012'den itibaren desteği sonlandırıldı. Bunun yerine, videonun arabelleğe alınan yüzdesini belirlemek için getVideoLoadedFraction yöntemini kullanın.

Şu anda yüklü/oynatılan videonun bayt cinsinden boyutunu veya videonun boyutuna dair bir yaklaşık değeri 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üklenmiş kısmını hesaplayabilirsiniz.

Video bilgilerini alma

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

Şu anda oynatılan video canlı etkinlik ise getDuration() işlevi, canlı video yayınının başladığı andan itibaren geçen süreyi döndürür. Daha açık belirtmek gerekirse, bu değer videonun sıfırlanmadan veya kesintiye uğramadan oynatıldığı süredir. Ayrıca, yayın etkinliğin başlangıç zamanından önce başlayabileceğinden bu süre genellikle asıl etkinlik süresinden daha uzundur.
player.getVideoUrl():String
Şu anda yüklü/oynatılan videonun YouTube.com URL'sini döndürür.
player.getVideoEmbedCode():String
Şu anda yüklü/oynatılan videonun yerleştirme kodunu döndürür.

Oynatma listesi bilgilerini alma

player.getPlaylist():Array
Bu işlev, oynatma listesindeki video kimliklerini şu anda sıralandığı şekilde döndürür. Bu işlev varsayılan olarak video kimliklerini oynatma listesi sahibi tarafından belirlenen sırada döndürür. Ancak, oynatma listesi sırasını karıştırmak için setShuffle işlevini çağırdıysanız getPlaylist() işlevinin döndürdüğü değer, karıştırılan sırayı yansıtır.
player.getPlaylistIndex():Number
Bu işlev, şu anda 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şturucusunun videoyu yerleştirdiği konumu tanımlar. Döndürülen değer sıfır tabanlı bir dizin kullanır. Bu nedenle, 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 dinleyici işlevi ekler. Aşağıdaki Etkinlikler bölümünde, oyuncunun tetikleyebileceği farklı etkinlikler tanımlanmaktadır. Dinleyici, belirtilen etkinlik tetiklendiğinde çalışacak işlevi belirten bir dizedir.
player.removeEventListener(event:String, listener:String):Void
Belirtilen event için bir dinleyici 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 düğümleri 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, uygulamanızı yerleşik oynatıcıdaki değişikliklerden haberdar etmek için etkinlikler tetikler. Önceki bölümde belirtildiği gibi, YT.Player nesnesini oluştururken bir etkinlik dinleyicisi ekleyerek etkinliklere abone olabilir ve addEventListener işlevini de kullanabilirsiniz.

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

  • Etkinliğin target, etkinliğe karşılık gelen video oynatıcıyı tanımlar.
  • Etkinliğin data, etkinlikle ilgili bir değer belirtir. onReady ve onAutoplayBlocked etkinliklerinde data özelliğinin belirtilmediğini unutmayın.

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

onReady
Bu etkinlik, bir oynatıcı yüklemeyi tamamlayıp API çağrıları almaya hazır olduğunda tetiklenir. Oynatıcı hazır olur olmaz videoyu oynatma veya videoyla ilgili bilgileri görüntüleme gibi belirli işlemleri otomatik olarak yürütmek istiyorsanız uygulamanız bu işlevi uygulamalıdır.

Aşağıdaki örnekte, bu etkinliği işlemek için kullanılan örnek bir işlev gösterilmektedir. API'nin işleve ilettiği etkinlik nesnesinde, oynatıcıyı tanımlayan bir target mülkü bulunur. İşlev, şu anda yüklü olan videonun yerleştirilme kodunu alır, videoyu oynatmaya başlar ve id değeri embed-code olan sayfa öğesinde yerleştirilme kodunu 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, oynatıcının durumu her değiştiğinde tetiklenir. API'nin etkinlik dinleyici işlevinize ilettiği etkinlik nesnesinin data mülkü, yeni oynatıcı durumuna karşılık gelen bir tam sayı belirtir. Olası değerler:

  • -1 (başlanmadı)
  • 0 (sona erdi)
  • 1 (oynuyor)
  • 2 (duraklatıldı)
  • 3 (arabelleğe alma)
  • 5 (video işaretlendi).

Oynatıcı bir videoyu ilk kez yüklediğinde 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 alanlı değişkenlerden 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 yol açabilecek faktörler hakkında daha fazla bilgi için YouTube Yardım Merkezi'ne bakın.

API'nin etkinlik dinleyici işlevine ilettiği etkinlik nesnesinin data mülk 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 oynatma hızı gerçekten değişirse bu etkinlik tetiklenir. Uygulamanız etkinliğe yanıt vermelidir ve setPlaybackRate(suggestedRate) işlevi çağrıldığında oynatma hızının otomatik olarak değişeceğini varsayamaz. Benzer şekilde, kodunuz video oynatma hızının yalnızca setPlaybackRate çağrısı sonucunda değişeceğini varsayamaz.

API'nin etkinlik dinleyici işlevine ilettiği etkinlik nesnesinin data mülk değeri, yeni oynatma hızını tanımlayan bir sayı olacaktır. getAvailablePlaybackRates yöntemi, şu anda işaretlenmiş veya oynatılan video için geçerli oynatma hızlarının listesini döndürür.
onError
Bu etkinlik, oynatıcıda hata oluştuğunda tetiklenir. API, etkinlik dinleyici işlevine bir event nesnesi iletir. Bu nesnenin data mülkünde, oluşan hatanın türünü tanımlayan bir tam sayı belirtilir. Olası değerler:

  • 2: İstek geçersiz bir parametre değeri içeriyor. Örneğin, 11 karakterden oluşmayan bir video kimliği belirtirseniz veya video kimliği ünlem işareti ya da yıldız işareti gibi geçersiz karakterler içeriyorsa bu hata meydana gelir.
  • 5: İstenen içerik HTML5 oynatıcıda oynatılamaz veya HTML5 oynatıcıyla ilgili başka bir hata meydana gelmiştir.
  • 100: İstenen video bulunamadı. Bu hata, bir video herhangi bir nedenle kaldırıldığında veya gizli olarak işaretlendiğinde ortaya çıkar.
  • 101: İstenen videonun sahibi, videonun yerleştirilmiş oynatıcılarda oynatılmasına izin vermiyor.
  • 150: Bu hata, 101 ile aynıdır. Bu, 101 hatasının farklı bir şekilde gösterilmesidir.
onApiChange
Bu etkinlik, oynatıcının API yöntemlerinin kullanıma sunulduğu bir modülü yüklediğini (veya kaldırdığını) belirtmek için tetiklenir. Uygulamanız bu etkinliği dinleyebilir ve ardından en son yüklenen modül için hangi seçeneklerin gösterileceğini belirlemek üzere oynatıcıyı ankete tabi tutabilir. Ardından 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 adı dizisi getirir:
player.getOptions();
 Şu anda seçenek belirleyebileceğ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');
 Bu komutla oynatıcıyı yoklayarak erişmek istediğiniz seçeneklere gerçekten erişilebildiğini 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
altyazılar 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'dir. Varsayılan boyut 0, en küçük boyut ise -1'tür. Bu seçeneği -1'ün altında bir tam sayıya ayarlamak en küçük altyazı boyutunun gösterilmesine, 3'un üzerinde bir tam sayıya ayarlamak ise en büyük altyazı boyutunun gösterilmesine neden olur.
altyazılar yeniden yükle Bu seçenek, oynatılan videonun 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 oynatma veya komut dosyası içeren video oynatma özelliklerini (toplu olarak "otomatik oynatma" olarak adlandırılır) engellediğinde tetiklenir. Aşağıdaki oynatıcı API'lerinden herhangi biriyle oynatma denemesi de buna dahildir:

Çoğu tarayıcıda, belirli koşullar geçerli olduğunda masaüstü, mobil ve diğer ortamlarda otomatik oynatmayı engelleyebilecek politikalar bulunur. Bu politikanın tetiklenebileceği durumlar arasında, sessiz oynatmanın kullanıcı etkileşimi olmadan açılması veya kaynakta çapraz iframe'de otomatik oynatmaya izin veren bir İzin Politikası ayarlanmamış olması yer alır.

Ayrıntılı bilgi için tarayıcıya özgü politikalara (Apple Safari / Webkit, Google Chrome, Mozilla Firefox) ve Mozilla'nın otomatik oynatma kılavuzuna bakın.

Örnekler

YT.Player nesneleri oluşturma

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

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

    onPlayerReady işlevi, oyuncu hazır olduğunda oyuncunun etrafındaki kenarlığın rengini turuncuya değiştirir. Ardından onPlayerStateChange işlevi, oyuncunun etrafındaki kenarlığın rengini mevcut oyuncu durumuna göre değiştirir. Örneğin, oynatıcı oynatırken renk yeşil, duraklatıldığında kırmızı, arabelleğe alırken mavi olur.

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

    Bu örnekte 1.280 piksel x 720 piksel boyutunda bir video oynatıcı oluşturulur. Ardından onReady etkinliğinin dinleyicisi, sesi en yüksek ayarda 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 video yüklendiğinde videonun otomatik olarak oynatılması ve video oynatıcının kontrollerinin gizlenmesi için ayarlanır. Ayrıca API'nin yayınladığı çeşitli etkinlikler için etkinlik işleyicileri 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>

Android WebView Media Integrity API entegrasyonu

YouTube, Android uygulamalarında YouTube oynatıcı yerleşimleri dahil olmak üzere yerleşik medya oynatıcıların, yerleşik uygulamanın özgünlüğünü doğrulamasını sağlamak için Android WebView Media Integrity API'yi genişletti. Bu değişiklikle birlikte, yerleştirilen uygulamalar YouTube'a otomatik olarak onaylı bir uygulama kimliği gönderir. Bu API'nin kullanımıyla toplanan veriler, uygulama meta verileri (paket adı, sürüm numarası ve imzalama sertifikası) ve Google Play Hizmetleri tarafından oluşturulan bir cihaz tasdik jetonudur.

Veriler, uygulama ve cihaz bütünlüğünü doğrulamak için kullanılır. Bu veriler şifrelenir, üçüncü taraflarla paylaşılmaz ve sabit bir saklama süresinin ardından silinir. Uygulama geliştiriciler, WebView Media Integrity API'de uygulama kimliklerini yapılandırabilir. Yapılandırma, kapsam dışında kalma seçeneğini destekler.

Düzeltme geçmişi

June 24, 2024

The documentation has been updated to note that YouTube has extended the Android WebView Media Integrity API to enable embedded media players, including YouTube player embeds in Android applications, to verify the embedding app's authenticity. With this change, embedding apps automatically send an attested app ID to YouTube.

November 20, 2023

The new onAutoplayBlocked event API is now available. This event notifies your application if the browser blocks autoplay or scripted playback. Verification of autoplay success or failure is an established paradigm for HTMLMediaElements, and the onAutoplayBlocked event now provides similar functionality for the IFrame Player API.

April 27, 2021

The Getting Started and Loading a Video Player sections have been updated to include examples of using a playerVars object to customize the player.

October 13, 2020

Note: This is a deprecation announcement for the embedded player functionality that lets you configure the player to load search results. This announcement affects the IFrame Player API's queueing functions for lists, cuePlaylist and loadPlaylist.

This change will become effective on or after 15 November 2020. After that time, calls to the cuePlaylist or loadPlaylist functions that set the listType property to search will generate a 4xx response code, such as 404 (Not Found) or 410 (Gone). This change also affects the list property for those functions as that property no longer supports the ability to specify a search query.

As an alternative, you can use the YouTube Data API's search.list method to retrieve search results and then load selected videos in the player.

October 24, 2019

The documentation has been updated to reflect the fact that the API no longer supports functions for setting or retrieving playback quality. As explained in this YouTube Help Center article, to give you the best viewing experience, YouTube adjusts the quality of your video stream based on your viewing conditions.

The changes explained below have been in effect for more than one year. This update merely aligns the documentation with current functionality:

  • The getPlaybackQuality, setPlaybackQuality, and getAvailableQualityLevels functions are no longer supported. In particular, calls to setPlaybackQuality will be no-op functions, meaning they will not actually have any impact on the viewer's playback experience.
  • The queueing functions for videos and playlists -- cueVideoById, loadVideoById, etc. -- no longer support the suggestedQuality argument. Similarly, if you call those functions using object syntax, the suggestedQuality field is no longer supported. If suggestedQuality is specified, it will be ignored when the request is handled. It will not generate any warnings or errors.
  • The onPlaybackQualityChange event is still supported and might signal a change in the viewer's playback environment. See the Help Center article referenced above for more information about factors that affect playback conditions or that might cause the event to fire.

May 16, 2018

The API now supports features that allow users (or embedders) to control the viewing perspective for 360° videos:

  • The getSphericalProperties function retrieves the current orientation for the video playback. The orientation includes the following data:
    • yaw - represents the horizontal angle of the view in degrees, which reflects the extent to which the user turns the view to face further left or right
    • pitch - represents the vertical angle of the view in degrees, which reflects the extent to which the user adjusts the view to look up or down
    • roll - represents the rotational angle (clockwise or counterclockwise) of the view in degrees.
    • fov - represents the field-of-view of the view in degrees, which reflects the extent to which the user zooms in or out on the video.
  • The setSphericalProperties function modifies the view to match the submitted property values. In addition to the orientation values described above, this function supports a Boolean field that indicates whether the IFrame embed should respond to DeviceOrientationEvents on supported mobile devices.

This example demonstrates and lets you test these new features.

June 19, 2017

This update contains the following changes:

  • Documentation for the YouTube Flash Player API and YouTube JavaScript Player API has been removed and redirected to this document. The deprecation announcement for the Flash and JavaScript players was made on January 27, 2015. If you haven't done so already, please migrate your applications to use IFrame embeds and the IFrame Player API.

August 11, 2016

This update contains the following changes:

  • The newly published YouTube API Services Terms of Service ("the Updated Terms"), discussed in detail on the YouTube Engineering and Developers Blog, provides a rich set of updates to the current Terms of Service. In addition to the Updated Terms, which will go into effect as of February 10, 2017, this update includes several supporting documents to help explain the policies that developers must follow.

    The full set of new documents is described in the revision history for the Updated Terms. In addition, future changes to the Updated Terms or to those supporting documents will also be explained in that revision history. You can subscribe to an RSS feed listing changes in that revision history from a link in that document.

June 29, 2016

This update contains the following changes:

  • The documentation has been corrected to note that the onApiChange method provides access to the captions module and not the cc module.

June 24, 2016

The Examples section has been updated to include an example that demonstrates how to use the API with an existing <iframe> element.

January 6, 2016

The clearVideo function has been deprecated and removed from the documentation. The function no longer has any effect in the YouTube player.

December 18, 2015

European Union (EU) laws require that certain disclosures must be given to and consents obtained from end users in the EU. Therefore, for end users in the European Union, you must comply with the EU User Consent Policy. We have added a notice of this requirement in our YouTube API Terms of Service.

April 28, 2014

This update contains the following changes:

March 25, 2014

This update contains the following changes:

  • The Requirements section has been updated to note that embedded players must have a viewport that is at least 200px by 200px. If a player displays controls, it must be large enough to fully display the controls without shrinking the viewport below the minimum size. We recommend 16:9 players be at least 480 pixels wide and 270 pixels tall.

July 23, 2013

This update contains the following changes:

  • The Overview now includes a video of a 2011 Google I/O presentation that discusses the iframe player.

October 31, 2012

This update contains the following changes:

  • The Queueing functions section has been updated to explain that you can use either argument syntax or object syntax to call all of those functions. Note that the API may support additional functionality in object syntax that the argument syntax does not support.

    In addition, the descriptions and examples for each of the video queueing functions have been updated to reflect the newly added support for object syntax. (The API's playlist queueing functions already supported object syntax.)

  • When called using object syntax, each of the video queueing functions supports an endSeconds property, which accepts a float/integer and specifies the time when the video should stop playing when playVideo() is called.

  • The getVideoStartBytes method has been deprecated. The method now always returns a value of 0.

August 22, 2012

This update contains the following changes:

  • The example in the Loading a video player section that demonstrates how to manually create the <iframe> tag has been updated to include a closing </iframe> tag since the onYouTubeIframeAPIReady function is only called if the closing </iframe> element is present.

August 6, 2012

This update contains the following changes:

  • The Operations section has been expanded to list all of the supported API functions rather than linking to the JavaScript Player API Reference for that list.

  • The API supports several new functions and one new event that can be used to control the video playback speed:

    • Functions

      • getAvailablePlaybackRates – Retrieve the supported playback rates for the cued or playing video. Note that variable playback rates are currently only supported in the HTML5 player.
      • getPlaybackRate – Retrieve the playback rate for the cued or playing video.
      • setPlaybackRate – Set the playback rate for the cued or playing video.

    • Events

July 19, 2012

This update contains the following changes:

  • The new getVideoLoadedFraction method replaces the now-deprecated getVideoBytesLoaded and getVideoBytesTotal methods. The new method returns the percentage of the video that the player shows as buffered.

  • The onError event may now return an error code of 5, which indicates that the requested content cannot be played in an HTML5 player or another error related to the HTML5 player has occurred.

  • The Requirements section has been updated to indicate that any web page using the IFrame API must also implement the onYouTubeIframeAPIReady function. Previously, the section indicated that the required function was named onYouTubePlayerAPIReady. Code samples throughout the document have also been updated to use the new name.

    Note: To ensure that this change does not break existing implementations, both names will work. If, for some reason, your page has an onYouTubeIframeAPIReady function and an onYouTubePlayerAPIReady function, both functions will be called, and the onYouTubeIframeAPIReady function will be called first.

  • The code sample in the Getting started section has been updated to reflect that the URL for the IFrame Player API code has changed to http://www.youtube.com/iframe_api. To ensure that this change does not affect existing implementations, the old URL (http://www.youtube.com/player_api) will continue to work.

July 16, 2012

This update contains the following changes:

  • The Operations section now explains that the API supports the setSize() and destroy() methods. The setSize() method sets the size in pixels of the <iframe> that contains the player and the destroy() method removes the <iframe>.

June 6, 2012

This update contains the following changes:

  • We have removed the experimental status from the IFrame Player API.

  • The Loading a video player section has been updated to point out that when inserting the <iframe> element that will contain the YouTube player, the IFrame API replaces the element specified in the constructor for the YouTube player. This documentation change does not reflect a change in the API and is intended solely to clarify existing behavior.

    In addition, that section now notes that the insertion of the <iframe> element could affect the layout of your page if the element being replaced has a different display style than the inserted <iframe> element. By default, an <iframe> displays as an inline-block element.

March 30, 2012

This update contains the following changes:

  • The Operations section has been updated to explain that the IFrame API supports a new method, getIframe(), which returns the DOM node for the IFrame embed.

March 26, 2012

This update contains the following changes:

  • The Requirements section has been updated to note the minimum player size.