YouTube Player API Reference for iframe Embeds

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

API'nın JavaScript işlevlerini kullanarak videoları oynatma için sıraya koyabilir, videoları oynatabilir, duraklatabilir veya durdurabilir, oynatıcı ses düzeyini ayarlayabilir ya da oynatılan video hakkında bilgi alabilirsiniz. Oyuncu durumu değişikliği gibi belirli oynatıcı 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şlevlerinin yanı sıra oynatıcıyı daha fazla özelleştirmek için kullanabileceğiniz oynatıcı parametrelerini de ayrıntılı olarak sağlar.

Koşullar

Kullanıcının tarayıcısı, HTML5 postMessage özelliğini desteklemelidir. Modern tarayıcıların çoğu postMessage özelliğini 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 web sayfaları aşağıdaki JavaScript işlevini de uygulamalıdır:

  • onYouTubeIframeAPIReady – API, sayfada oynatıcı API'si için JavaScript'in indirilmesi tamamlandığında bu işlevi çağırır. Bu işlev daha sonra sayfanızda API'yi kullanmanıza olanak tanır. Dolayısıyla, bu işlev sayfa yüklendiğinde görüntülenmesini istediğiniz oynatıcı nesnelerini oluşturabilir.

Başlarken

Aşağıdaki örnek HTML sayfası, bir videoyu yükleyen, altı saniye boyunca oynatan ve ardından oynatmayı durduran yerleşik bir oynatıcı oluşturur. HTML'deki numaralandırılmış 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 örnek hakkında daha ayrıntılı bilgi verilmektedir:

  1. Bu bölümdeki <div> etiketi, IFrame API'sinin video oynatıcıyı sayfada yerleştireceği 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ştirdiğinden emin olmak için <div> etiketini id değerine göre tanımlar. Özellikle, IFrame API'si <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. Bu örnekte, kodun eşzamansız olarak alındığından emin olmak için API kodunu indirmek için DOM değişikliği kullanılmaktadı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 indirilir indirmez yürütülür. Kodun bu bölümü, yerleştirdiğiniz video oynatıcıyı ifade eden bir genel değişken (player) tanımlar ve ardından işlev 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 oynatılmaya 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 oynadığını, duraklatıldığını, bitirdiğini vb. belirtebilir. Bu işlev, oynatıcı durumu 1 (oynatılıyor) olduğunda, oynatıcının altı saniye boyunca oynatması ve ardından videoyu durdurmak için stopVideo işlevini çağırması 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 bir video oynatıcı eklemek için bir YT.Player nesnesi oluşturabilirsiniz. Aşağıdaki HTML alıntısı, yukarıdaki örnekte bulunan 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ı oluşturucusu, aşağıdaki parametreleri belirtir:

  1. İlk parametre, ya DOM öğesini ya da API'nin oynatıcıyı içeren <iframe> etiketini ekleyacağı HTML öğesinin id öğ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 değeridir.
    • height (sayı) – Video oynatıcının yüksekliği. Varsayılan değer 390 değeridir.
    • 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 ve onStateChange etkinliği tetiklendiğinde 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 bir <iframe> öğesiyle değiştirilecektir. Bunun yerine <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 değerlerini belirtmenize gerek olmadığını 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 origin parametresini de URL'ye eklemeniz gerekir. origin isteğe bağlı olsa da, 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.

Örnekler bölümünde, video oynatıcı nesneleri oluşturmak için birkaç örnek daha gösterilmektedir.

İşlemler

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

İşlevler

Sıraya ekleme işlevleri

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ının yüklediği videoları sıraya ekleyebilir veya bu videoları liste halinde yükleyebilirsiniz.

API, sıraya alma 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 belirli bir 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. Buna ek olarak API, bağımsız değişken söz diziminin desteklemediği ek işlevleri destekleyebilir.

Örneğin, loadVideoById işlevi aşağıdaki yollardan 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ıraya ekleme 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 nokta/tam sayı kabul eder ve playVideo() çağrıldığında videonun oynatılmaya başlayacağı zamanı belirtir. startSeconds değeri belirtip seekTo() çağrısı yaparsanız oynatıcı, seekTo() çağrısında belirtilen zamandan itibaren oynatılır. 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, bir kayan/tamsayı kabul eder ve playVideo() çağrıldığında videonun oynatılmasının ne zaman durması gerektiğini belirtir. Bir endSeconds değeri belirleyip seekTo() yöntemini ç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, kayan noktalı/tamsayı kabul eder. Belirtilmişse video, belirtilen zamana en yakın animasyon karesinden başlar.
  • İsteğe bağlı endSeconds parametresi, kayan noktalı/tamsayı kabul eder. Politika belirtilirse video belirtilen zamanda 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.

  • Gerekli mediaContentUrl parametresi, tam nitelikli bir YouTube oynatıcı URL'sini http://www.youtube.com/v/VIDEO_ID?version=3 biçiminde 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 öğesini belirleyip seekTo() çağrısında bulunursanız oynatıcı, seekTo() görüşmesinde belirtilen zamandan itibaren oynatılır. 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, bir kayan/tamsayı kabul eder ve playVideo() çağrıldığında videonun oynatılmasının ne zaman durması gerektiğini belirtir. Bir endSeconds değeri belirleyip seekTo() yöntemini ç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, tam nitelikli bir YouTube oynatıcı URL'sini http://www.youtube.com/v/VIDEO_ID?version=3 biçiminde belirtir.
  • İsteğe bağlı startSeconds parametresi, kayan nokta/tam sayı kabul eder ve videonun oynatılmaya başlaması gereken zamanı belirtir. startSeconds (sayı, kayan noktalı olabilir) belirtilirse video, belirtilen zamana en yakın animasyon karesinden 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 ne zaman durması gerektiğini belirtir.

Listeler için sıraya ekleme işlevleri

cuePlaylist ve loadPlaylist işlevleri, oynatma listesini yükleyip oynatmanı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 sıraya da ekleyebilirsiniz (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 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şaretlendiğinde ve oynatılmaya hazır olduğunda oynatıcı bir video cued etkinliği (5) yayınlar.

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

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

    • İsteğe bağlı startSeconds parametresi, kayan/tamsayı kabul eder ve playVideo() işlevi çağrıldığında, oynatma listesindeki ilk videonun oynatılmaya başlayacağı zamanı belirtir. startSeconds değeri belirtip seekTo() çağrısı yaparsanız oynatıcı, seekTo() çağrısında belirtilen zamandan itibaren oynatılır. Bir oynatma listesini işaretleyip 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 ekler. Liste, bir oynatma listesi veya kullanıcının yüklediği videolar feed'i olabilir. Arama sonuçlarını sıraya ekleme özelliği kullanımdan kaldırıldı ve 15 Kasım 2020 itibarıyla artık desteklenmeyecek.

    Liste işaretlendiğinde ve oynatılmaya 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 değerleridir. Desteği sonlandırılan search değeri, 15 Kasım 2020 itibarıyla artık desteklenmeyecektir. Varsayılan değer playlist değeridir.

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

      • listType özelliğinin 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ğini belirtir.
      • listType özelliğinin değeri user_uploads ise list özelliği, yüklenen videoları döndürülecek kullanıcıyı tanımlar.
      • listType özelliğinin 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 itibarıyla artık 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 şeklindedir. Bu nedenle varsayılan davranış, listedeki ilk videonun yüklenip oynatılmasıdır.

    • İsteğe bağlı startSeconds özelliği, bir kayan/tamsayı kabul eder ve playVideo() işlevi çağrıldığında, listedeki ilk videonun oynatılmaya başlayacağı zamanı belirtir. startSeconds değeri belirtip seekTo() çağrısı yaparsanız oynatıcı, seekTo() çağrısında belirtilen zamandan itibaren oynatılır. Bir listeyi işaretleyip 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 kimlikleri dizisini belirtir. YouTube Data API'de, video kaynağının id özelliği bir video kimliğini belirtir.

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

    • İsteğe bağlı startSeconds parametresi, kayan/tamsayı kabul eder ve oynatma listesindeki ilk videonun oynatılmaya başlayacağı 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. 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 tarihinden itibaren 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 değerleridir. Desteği sonlandırılan search değeri, 15 Kasım 2020 itibarıyla artık desteklenmeyecektir. Varsayılan değer playlist değeridir.

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

      • listType özelliğinin değeri playlist ise list özelliği, oynatma listesi kimliğini veya video kimlikleri dizisi belirtir. YouTube Data API'de, playlist kaynağının id özelliği bir oynatma listesi kimliğini belirtir ve video kaynağının id özelliği de bir video kimliğini belirtir.
      • listType özelliğinin değeri user_uploads ise list özelliği, yüklenen videoları döndürülecek kullanıcıyı tanımlar.
      • listType özelliğinin 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 itibarıyla artık 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 şeklindedir. Bu nedenle varsayılan davranış, listedeki ilk videonun yüklenip oynatılmasıdır.

    • İsteğe bağlı startSeconds özelliği, bir kayan/tamsayı kabul eder ve listedeki ilk videonun oynatılmaya başlayacağı zamanı belirtir.

Oynatma kontrolleri ve oynatıcı ayarları

Video oynatma

player.playVideo():Void
Seçilmiş/yüklenen geçerli videoyu oynatır. Bu işlev yürütüldükten sonraki son oynatıcı durumu playing (1) olacaktır.

Not: Bir oynatma, yalnızca oynatıcıdaki yerel oynatma düğmesiyle başlatıldığında videonun resmi görüntüleme sayısına dahil edilir.
player.pauseVideo():Void
Oynatılan videoyu duraklatır. İşlev çağrıldığında, oynatıcı ended (0) durumunda değilse bu işlev yürütüldükten sonraki son oynatıcı durumu paused (2) olur. Bu durumda oynatıcı durumu değişmez.
player.stopVideo():Void
Geçerli videonun yüklenmesini durdurur ve iptal eder. Bu işlev, kullanıcının oynatıcıdaki başka bir videoyu 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 istiyorsanız önce stopVideo öğesini çağırmadan sıraya ekleme işlevlerinden birini çağırabilirsiniz.

Önemli: Oynatıcıyı paused (2) durumunda bırakan pauseVideo işlevinden farklı olarak stopVideo işlevi, oynatıcıyı ended (0), paused (2), video cued (5) veya unstarted (-1) dahil olmak üzere herhangi bir oynatılmama durumuna alabilir.
player.seekTo(seconds:Number, allowSeekAhead:Boolean):Void
Videoda belirli bir zamana arama yapar. İşlev çağrıldığında 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.

    Kullanıcının aradığı videoyu indirmediği takdirde oynatıcı, bu zamandan önceki en yakın animasyon karesine ilerler.

  • allowSeekAhead parametresi, seconds parametresi arabelleğe alınmış video verilerinin dışında bir zaman belirtiyorsa oynatıcının sunucuya yeni bir istek yapıp yapmayacağını belirler.

    Kullanıcı fareyi video ilerleme çubuğu boyunca sürüklerken bu parametreyi false olarak ayarlamanızı ve ardından kullanıcı fareyi bıraktığında true olarak ayarlamanızı öneririz. Bu yaklaşım, kullanıcının yeni video akışı isteğinde bulunmadan videodaki arabelleğe alınmamış noktaları kaydırarak videonun farklı noktalarına ulaşmasına 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 derecelik videoların oynatılmasını kontrol etme

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

player.getSphericalProperties():Object
Videoyu oynatmayla ilgili izleyicinin o andaki bakış açısını veya görünümünü açıklayan özellikleri getirir. Ayrıca:
  • Bu nesne yalnızca, küresel 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 olarak 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, [0, 360) aralığında yer alan ve kullanıcının görünümü ne kadar sola veya sağa doğru döndürdüğünü yansıtan sayı. Eş dikdörtgen projeksiyonunda videonun merkezine bakan nötr konum 0°'yi temsil eder ve izleyici sola döndüğünde bu değer artar.
pitch [-90, 90] aralığında, görünümün dikey açısını derece cinsinden temsil eden ve kullanıcının görünümü yukarı veya aşağı bakacak şekilde ne ölçüde ayarladığını yansıtan sayı. Eş dikdörtgen projeksiyonunda videonun merkezine bakan nötr konum 0°'yi temsil eder ve izleyici yukarı doğru baktığında bu değer artar.
roll [-180, 180] aralığında, 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 sayı. Eş dikdörtgen projeksiyondaki yatay eksen, görünümün yatay eksenine paralel olduğu nötr konum 0°'yi gösterir. Görünüm saat yönünde döndüğünde değer artar ve görünüm saat yönünün tersine döndüğünde azalır.

Yerleşik oynatıcının, görünümün rulosunu ayarlamak için bir kullanıcı arayüzü sunmadığını unutmayın. Rulo, karşılıklı olarak birbirini dışlayan ş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ışıysa bu API'yi kullanarak ruloyu sıfır dışında bir değere ayarlayın.
fov Görüntü alanının uzun kenarı boyunca ölçülen görünümün görüş alanını derece cinsinden temsil eden, [30, 120] aralığında yer alan 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ırmaya, değeri artırmak ise uzaklaştırmaya benzer. 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. (Geçerli video küresel değilse yöntem, girişten bağımsız olarak işlemsizdir.)

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

Buna ek olarak:
  • Nesne, bilinmeyen ve/veya beklenmeyen özellikler içeriyorsa oynatıcı bunları yoksayar.
  • Bu bölümün başında belirtildiği gibi, 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 ve 360 derece video oynatmalar için yaw, pitch ve roll özelliklerini etkilemez. Daha fazla bilgi 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 derecelik görüntüleme deneyimini etkiler.IFrame yerleştirmesi, desteklenen bir cihazın yönünde yapılan değişikliklere (ör. mobil tarayıcıda DeviceOrientationEvent) işaret eden etkinliklere yanıt verip vermeyeceğini belirten boole değeridir. Varsayılan parametre değeri: true.

Desteklenen mobil cihazlar
  • Değer true olduğunda yerleşik oynatıcı, 360 derece video oynatmaları için yaw, pitch ve roll özelliklerini ayarlamak üzere yalnızca cihazın hareketlerine güvenir. Ancak fov özelliği API aracılığıyla hâlâ değiştirilebilir. Mobil cihazlarda fov özelliğini değiştirmenin tek yolu API'dir. Bu, varsayılan davranıştır.
  • Değer false olduğunda cihazın hareketi 360° görüntüleme deneyimini etkilemez. yaw, pitch, roll ve fov özelliklerinin tümü API aracılığıyla ayarlanmalıdır.

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

Oynatma listesinde video oynatma

player.nextVideo():Void
Bu işlev yükler ve oynatma listesindeki sonraki videoyu oynatır.

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

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

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

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

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

player.playVideoAt(index:Number):Void
Bu işlev, belirtilen videoyu yükleyip oynatma listesinde 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 düzeyini 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, değilse 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 düzeyini döndürür (0 ile 100 arasında bir tam sayı). Oynatıcının sesi kapalı olsa bile getVolume() işlevinin ses düzeyini döndüreceğini unutmayın.

Oynatıcı boyutunu ayarlama

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

Oynatma hızını ayarlama

player.getPlaybackRate():Number
Bu işlev, o anda oynatılan videonun oynatma hızını getirir. Varsayılan oynatma hızı 1, videonun normal hızda oynatıldığını gösterir. 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, geçerli video için önerilen oynatma hızını ayarlar. Oynatma hızı değişirse yalnızca halihazırda işaretli olan veya oynatılan video için değişir. İşaretlenmiş bir video için oynatma hızını ayarlarsanız playVideo işlevi çağrıldığında veya kullanıcı doğrudan oynatıcı kontrolleri aracılığıyla oynatmayı başlattığında bu hız geçerli olmaya devam eder. Ayrıca videoları veya oynatma listelerini işaretleme ya da yükleme işlevlerinin (cueVideoById, loadVideoById vb.) çağrılması, oynatma hızını 1 olarak sıfırlar.

Bu işlevin çağrılması, oynatma hızının 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ığı gerçeği yerine etkinliğe yanıt vermelidir.

getAvailablePlaybackRates yöntemi, o 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 noktalı 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 bulunduğu oynatma hızları grubunu döndürür. Varsayılan değer 1, videonun normal hızda oynatıldığını gösterir.

İş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 mı oynatması gerektiğini yoksa oynatma listesindeki son video sona erdikten sonra oynatmayı durdurması gerektiğini mi gösterir. Varsayılan davranış, oynatma listelerinin döngü halinde olmamasıdır.

Farklı bir oynatma listesi yükleseniz veya işaretleseniz bile bu ayar geçerliliğini korur. Yani bir oynatma listesi yüklediğinizde setLoop işlevini true değeriyle çağırıp ikinci bir oynatma listesi yüklerseniz ikinci oynatma listesi de döngüye alınacaktı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. Bir oynatma listesindeki son video oynatıldıktan sonra video oynatıcı, oynatma listesinin başına geri döner ve oynatma listesini 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şturucunun belirttiğinden farklı bir sırada oynatılacak şekilde karıştırılıp oynatılmayacağını belirtir. Bir oynatma listesini, oynatılmaya 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 işaretlerseniz bu ayar kalıcı olmaz. Yani bir oynatma listesi yüklerseniz setShuffle işlevini çağırıp ardından ikinci bir oynatma listesi yüklerseniz ikinci oynatma listesi karıştırılmaz.

Zorunlu shufflePlaylist parametresi, YouTube'un oynatma listesini karışık çalması gerekip gerekmediğini belirtir.

  • Parametre değeri true ise YouTube, oynatma listesi sırasını karıştırır. İşleve, önceden karıştırılmış bir oynatma listesini karıştırması talimatını verirseniz YouTube sırayı 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 bir sayı döndürür. Bu sayı, oynatıcının arabelleğe alınmış olarak gösterdiği video yüzdesini belirtir. Bu yöntem, desteği sonlandırılan getVideoBytesLoaded ve getVideoBytesTotal yöntemlerine göre daha güvenilir bir sayı döndürür.
player.getPlayerState():Number
Oynatıcının 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 işaretli
player.getCurrentTime():Number
Videonun oynatılmaya başlamasından bu yana geçen süreyi saniye cinsinden döndürür.
player.getVideoStartBytes():Number
31 Ekim 2012 itibarıyla kullanımdan kaldı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 doğru ilerler ve oynatıcı, videonun henüz yüklenmemiş bir bölümünü oynatmak için yeni bir istekte bulunur.
player.getVideoBytesLoaded():Number
18 Temmuz 2012 itibarıyla kullanımdan kaldırıldı. 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ıldı. Bunun yerine, videonun arabelleğe alınan yüzdesini belirlemek için getVideoLoadedFraction yöntemini kullanın.

Yüklenmekte olan/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 bilgileri alınıyor

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

Oynatılan video canlı etkinlik ise getDuration() işlevi, canlı video yayını başladıktan sonra geçen süreyi döndürür. Bu, videonun sıfırlanmadan veya kesintiye uğratılmadan izlendiği süredir. Ayrıca, akış etkinliğin başlangıç saatinden önce başlayabileceği için bu süre genellikle gerçek etkinlik zamanından daha uzundur.
player.getVideoUrl():String
Geçerli olarak yüklenen/oynatılan videonun YouTube.com URL'sini döndürür.
player.getVideoEmbedCode():String
Geçerli olarak yüklenen/oynatılan videonun yerleştirme kodunu döndürür.

Oynatma listesi bilgileri alınıyor

player.getPlaylist():Array
Bu işlev, oynatma listesindeki video kimliklerinin halihazırda sıralandığı diziyi 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ılmış sırayı yansıtır.
player.getPlaylistIndex():Number
Bu işlev, oynatılmakta olan 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 belirler. Döndürülen değer, sıfır tabanlı bir dizin kullandığından 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 işleyici işlevi ekler. Aşağıdaki Etkinlikler bölümü, oynatıcının 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 işleyici işlevini kaldırır. listener, belirtilen etkinlik etkinleştiğinde artık yürütülemeyecek işlevi tanımlayan bir dizedir.

DOM düğümlerine erişme ve bu 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, yerleşik oynatıcıdaki değişiklikleri uygulamanıza 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, bu işlevlerin her birine tek bağımsız değişken olarak bir etkinlik nesnesi iletir. Etkinlik nesnesi aşağıdaki özelliklere sahiptir:

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

Aşağıdaki liste, API'nin tetiklediği etkinlikleri tanımlar:

onReady
Bu etkinlik, oynatıcı yüklemeyi tamamlayıp API çağrıları almaya hazır olduğunda tetiklenir. Video oynatma veya video hakkındaki bilgileri 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ği işlemek için kullanılan örnek bir işlev gösterilmektedir. API'nin işleve aktardığı etkinlik nesnesi, oynatıcıyı tanımlayan bir target özelliğine sahiptir. İşlev, o anda yüklü 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, oynatıcının durumu her değiştiğinde tetiklenir. API'nin etkinlik işleyici işlevinize aktardığı 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 (oynanıyor)
  • 2 (duraklatıldı)
  • 3 (arabelleğe alınıyor)
  • 5 (video işaretli).

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ğuna işaret edebilir. 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 göz atın.

API'nin etkinlik işleyici işlevine aktardığı 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 oynatma hızı gerçekten değişirse bu etkinlik 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 açık bir setPlaybackRate çağrısı sonucunda değişeceğini varsaymamalıdır.

API'nin etkinlik işleyici işlevine aktardığı etkinlik nesnesinin data özellik değeri, yeni oynatma hızını tanımlayan bir sayı olacaktır. getAvailablePlaybackRates yöntemi, geçerli olarak işaretli veya oynatılan video için geçerli oynatma hızlarının listesini döndürür.
onError
Bu etkinlik, oynatıcıda bir hata oluşursa 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, 11 karakter içermeyen 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 oluşur.
  • 5 – İstenen içerik HTML5 oynatıcısında oynatılamıyor veya HTML5 oynatıcıyla ilgili başka bir hata oluştu.
  • 100 – İstenen video bulunamadı. Bu hata, bir video kaldırıldığında (herhangi bir nedenle) veya gizli 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. Yalnızca 101 hatası gibi bir şey gizlenmiş!
onApiChange
Bu etkinlik, oynatıcının açık API yöntemlerine sahip bir modülü yüklediğini (veya kaldırdığını) belirtmek için tetiklenir. Uygulamanız bu etkinliği dinleyebilir ve son yüklenen modül için hangi seçeneklerin sunulduğunu belirlemek için oynatıcıyı yoklayabilir. Uygulamanız, bu seçeneklere ilişkin mevcut ayarları alabilir veya güncelleyebilir.

Aşağıdaki komut, oynatıcı seçeneklerini ayarlayabileceğiniz bir modül adları dizisini getirir:
player.getOptions();
Şu anda seçenekleri ayarlayabileceğiniz tek modül, oynatıcıdaki altyazıları işleyen captions modülüdür. Bir onApiChange etkinliği aldıktan sonra, uygulamanız captions modülü için hangi seçeneklerin ayarlanabileceğini belirlemek için aşağıdaki komutu kullanabilir:
player.getOptions('captions');
Bu komutla oynatıcıyı yoklayarak erişmek istediğiniz seçeneklerin 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. Bu seçeneğin -1 değerinden küçük bir tam sayıya ayarlanması en küçük altyazı boyutunun gösterilmesine neden olurken, 3 değerinin ü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 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ıyla video oynatma özelliklerini (topluca "otomatik oynatma" olarak adlandırılır) engellediğinde tetiklenir. Buna, aşağıdaki oynatıcı API'lerinden herhangi biriyle çalma denemesi dahildir:

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

Tüm ayrıntılar 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

  • 1. Örnek: Mevcut <iframe> ile API kullanma

    Bu örnekte, sayfadaki bir <iframe> öğesi API'nin kullanılacağı oynatıcıyı zaten tanımlamaktadır. Oynatıcının src URL'sinin enablejsapi parametresini 1 olarak ayarlaması 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 etrafındaki kenarlığın rengini turuncuya dönüştürür. onPlayerStateChange işlevi daha sonra geçerli oynatıcı durumuna göre oynatıcının etrafındaki kenarlığın rengini değiştirir. Örneğin, oynatıcı oynarken yeşil, duraklatıldığında kırmızı, arabelleğe alırken renk mavidir.

    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 örnek, 1280 x 720 piksel boyutunda bir video oynatıcı oluşturur. Ardından, onReady etkinliğinin etkinlik işleyicisi, 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 örnek, oynatıcı parametrelerini, video yüklendiğinde otomatik olarak oynatacak ve video oynatıcının kontrollerini gizleyecek şekilde ayarlar. 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 derecelik 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, yerleştirilmiş uygulamanın orijinalliğini doğrulayabilmek için Android WebView Media Integrity API'nin kapsamını genişleterek, Android uygulamalarındaki yerleşik YouTube oynatıcıları da dahil olmak üzere yerleşik medya oynatıcıları etkinleştirdi. Bu değişiklikle birlikte, yerleşik uygulamalar YouTube'a otomatik olarak onaylanmış bir uygulama kimliği gönderecek. Bu API'nin kullanımı sırasında toplanan veriler, Google Play Hizmetleri tarafından oluşturulan uygulama meta verileri (paket adı, sürüm numarası ve imzalama sertifikası) ve cihaz onay jetonudur.

Veriler, uygulamayı 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.