IFrame Player API'sı, web sitenize bir YouTube video oynatıcı yerleştirmenize ve JavaScript kullanarak oynatıcıyı kontrol etmenize olanak tanır.
API'nin JavaScript işlevlerini kullanarak videoları oynatma için sıraya koyabilir, oynatabilir, duraklatabilir veya durdurabilir, oynatıcı ses düzeyini ayarlayabilir ya da oynatılan videoyla ilgili bilgileri alabilirsiniz. Ayrıca, oynatıcı durumu değişikliği gibi belirli oyuncu etkinliklerine yanıt olarak yürütülecek etkinlik işleyiciler de ekleyebilirsiniz.
Bu kılavuzda, IFrame API'nin nasıl kullanılacağı açıklanmaktadır. API'nin gönderebileceği farklı etkinlik türlerini tanımlar ve bu etkinliklere yanıt vermek için etkinlik işleyicilerin nasıl yazılacağını açıklar. Ayrıca, video oynatıcıyı kontrol etmek için çağırabileceğiniz farklı JavaScript işlevleri ve oynatıcıyı daha da özelleştirmek için kullanabileceğiniz oynatıcı parametreleri de ayrıntılı bir şekilde açıklanmaktadır.
Koşullar
Kullanıcının tarayıcısı HTML5 postMessage
özelliğini desteklemelidir. Modern tarayıcıların çoğu postMessage
'yi destekler.
Yerleşik oynatıcıların en az 200 piksele 200 piksel değerinde bir görünüme sahip olması gerekir. Oynatıcı kontrolleri gösterirse görünümün minimum boyutun altına düşürmeksizin kontrolleri tamamen gösterecek kadar geniş olması gerekir. En az 480 piksel genişlik, 270 piksel uzunluğa sahip 16:9 oynatıcıları öneririz.
IFrame API'sını kullanan tüm web sayfaları da aşağıdaki JavaScript işlevini uygulamalıdır:
-
onYouTubeIframeAPIReady
– Sayfa, oynatıcı API'si için JavaScript'i indirmeyi tamamladığında API bu işlevi çağırır. Böylece, sayfanızda API'yi kullanabilirsiniz. Bu nedenle, bu işlev sayfa yüklendiğinde görüntülenmesini istediğiniz oynatıcı nesnelerini oluşturabilir.
Kullanmaya başlama
Aşağıdaki örnek HTML sayfası, bir videoyu yükleyecek, altı saniye boyunca oynatacak ve ardından oynatmayı durduracak yerleşik bir oynatıcı oluşturur. HTML'deki numaralı açıklamalar, örneğin altındaki listede açıklanmıştır.
<!DOCTYPE html> <html> <body> <!-- 1. The <iframe> (and video player) will replace this <div> tag. --> <div id="player"></div> <script> // 2. This code loads the IFrame Player API code asynchronously. var tag = document.createElement('script'); tag.src = "https://www.youtube.com/iframe_api"; var firstScriptTag = document.getElementsByTagName('script')[0]; firstScriptTag.parentNode.insertBefore(tag, firstScriptTag); // 3. This function creates an <iframe> (and YouTube player) // after the API code downloads. var player; function onYouTubeIframeAPIReady() { player = new YT.Player('player', { height: '390', width: '640', videoId: 'M7lc1UVf-VE', playerVars: { 'playsinline': 1 }, events: { 'onReady': onPlayerReady, 'onStateChange': onPlayerStateChange } }); } // 4. The API will call this function when the video player is ready. function onPlayerReady(event) { event.target.playVideo(); } // 5. The API calls this function when the player's state changes. // The function indicates that when playing a video (state=1), // the player should play for six seconds and then stop. var done = false; function onPlayerStateChange(event) { if (event.data == YT.PlayerState.PLAYING && !done) { setTimeout(stopVideo, 6000); done = true; } } function stopVideo() { player.stopVideo(); } </script> </body> </html>
Aşağıdaki listede, yukarıdaki örnekle ilgili daha fazla ayrıntı verilmiştir:
-
Bu bölümdeki
<div>
etiketi, IFrame API'sinin video oynatıcıyı yerleştireceği sayfada konumu tanımlar. Video oynatıcı yükleme bölümünde açıklanan oynatıcı nesnesinin oluşturucusu, API'nin<iframe>
öğesini doğru konuma yerleştirmesini sağlamak için<div>
etiketiniid
öğesine göre tanımlar. IFrame API'si özellikle<div>
etiketini<iframe>
etiketiyle değiştirir.Alternatif olarak,
<iframe>
öğesini doğrudan sayfaya da yerleştirebilirsiniz. Video oynatıcı yükleme bölümünde bunun nasıl yapılacağı açıklanmaktadır. -
Bu bölümdeki kod, IFrame Player API'sı JavaScript kodunu yükler. Örnekte, kodun eşzamansız olarak alındığından emin olmak için API kodunu indirmek için DOM değişikliği kullanılır. (
<script>
etiketinin, eşzamansız indirmeleri de etkinleştirenasync
özelliği, bu Stack Overflow yanıtında açıklandığı gibi henüz tüm modern tarayıcılarda desteklenmemektedir. -
onYouTubeIframeAPIReady
işlevi, oynatıcı API kodu indirildiği anda yürütülür. Kodun bu bölümü, yerleştirdiğiniz video oynatıcıyı ifade eden genel bir değişkeni (player
) tanımlar ve işlev daha sonra video oynatıcı nesnesini oluşturur. -
onReady
etkinliği tetiklendiğindeonPlayerReady
işlevi yürütülür. Bu örnekte işlev, video oynatıcının hazır olduğunda oynatılmaya başlaması gerektiğini belirtir. -
Oynatıcının durumu değiştiğinde API,
onPlayerStateChange
işlevini çağırır. Bu durum, oynatıcının oynadığını, duraklatıldığını, tamamlandığını vb. gösterebilir. İşlev, oynatıcı durumu1
(oynatılıyor) olduğunda oynatıcının altı saniye boyunca oynatılması gerektiğini ve ardından videoyu durdurmak içinstopVideo
işlevini çağırmasını belirtir.
Video oynatıcı yükleniyor
API'nin JavaScript kodu yüklendikten sonra API, onYouTubeIframeAPIReady
işlevini çağırır. Bu noktada, sayfanıza video oynatıcı eklemek için bir YT.Player
nesnesi oluşturabilirsiniz. Aşağıdaki HTML alıntısı, yukarıdaki örnekten alınan onYouTubeIframeAPIReady
işlevini gösterir:
var player; function onYouTubeIframeAPIReady() { player = new YT.Player('player', { height: '390', width: '640', videoId: 'M7lc1UVf-VE', playerVars: { 'playsinline': 1 }, events: { 'onReady': onPlayerReady, 'onStateChange': onPlayerStateChange } }); }
Video oynatıcısını oluşturan oluşturucu, aşağıdaki parametreleri belirtir:
-
İlk parametre, API'nin oynatıcıyı içeren
<iframe>
etiketini yerleştireceği HTML öğesininid
veya DOM öğesini belirtir.IFrame API'si, belirtilen öğeyi oynatıcıyı içeren
<iframe>
öğesiyle değiştirir. Değiştirilen öğe, eklenen<iframe>
öğesinden farklı bir görüntüleme stiline sahipse bu durum sayfanızın düzenini etkileyebilir.<iframe>
, varsayılan olarakinline-block
öğesi olarak gösterilir. - İ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ğer640
olarak ayarlanmıştır.height
(sayı) – Video oynatıcının yüksekliği. Varsayılan değer390
olarak ayarlanmıştır.videoId
(dize) – Oynatıcının yükleyeceği videoyu tanımlayan YouTube video kimliği.playerVars
(nesne) – Nesnenin özellikleri, oynatıcıyı özelleştirmek için kullanılabilecek oynatıcı parametrelerini tanımlar.events
(nesne) – Nesnenin özellikleri, API'nin tetiklediği etkinlikleri ve bu etkinlikler gerçekleştiğinde API'nin çağıracağı işlevleri (etkinlik işleyiciler) tanımlar. Örnekte kurucu,onReady
etkinliği tetiklendiğindeonPlayerReady
işlevinin yürütüleceğini,onStateChange
etkinliği tetiklendiğinde iseonPlayerStateChange
işlevinin yürütüleceğini belirtir.
Başlarken bölümünde belirtildiği gibi, sayfanıza boş bir <div>
öğesi yazmak yerine, oynatıcı API'sinin JavaScript kodu daha sonra bu öğeyi <iframe>
öğesiyle değiştirir. Bu durumda <iframe>
etiketini kendiniz oluşturabilirsiniz. Örnekler bölümündeki ilk örnekte bunun nasıl yapılacağı gösterilmektedir.
<iframe id="player" type="text/html" width="640" height="390" src="http://www.youtube.com/embed/M7lc1UVf-VE?enablejsapi=1&origin=http://example.com" frameborder="0"></iframe>
<iframe>
etiketini yazarsanız YT.Player
nesnesini oluştururken YT.Player
nesnesini oluştururken <iframe>
etiketinin özellikleri olarak belirtilen width
ve height
değerlerini veya src
URL'sinde belirtilen videoId
ve oynatıcı parametrelerini belirtmenizin gerekmediğini unutmayın. Ek bir güvenlik önlemi olarak, parametre değeri olarak URL şemasını (http://
veya https://
) ve ana makine sayfanızın tam alan adını belirterek URL'ye origin
parametresini de eklemeniz gerekir. origin
isteğe bağlıdır. Bununla birlikte, sayfanıza kötü amaçlı üçüncü taraf JavaScript yerleştirilmesine ve YouTube oynatıcınızın ele geçirilmesine karşı koruma sağlar.
Örnekler bölümünde, video oynatıcı nesneleri oluşturmaya ilişkin birkaç örnek daha gösterilmektedir.
İşlemler
Oynatıcı API yöntemlerini çağırmak için öncelikle kontrol etmek istediğiniz oynatıcı nesnesine bir referans almanız gerekir. Referansı, bu dokümanın Başlarken ve Video oynatıcı yükleme bölümlerinde açıklandığı gibi bir YT.Player
nesnesi oluşturarak edinebilirsiniz.
İşlevler
İşlevleri sıraya ekleme
Sıraya ekleme işlevleri video, oynatma listesi veya başka bir video listesi yükleyip oynatmanıza olanak tanır. Bu işlevleri çağırmak için aşağıda açıklanan nesne söz dizimini kullanıyorsanız kullanıcıların yüklediği videoların listesini de sıraya koyabilir veya yükleyebilirsiniz.
API, sıralama işlevlerini çağırmak için iki farklı söz dizimini destekler.
-
Bağımsız değişken söz dizimi, işlev bağımsız değişkenlerinin belirtilen sırada listelenmesini gerektirir.
-
Nesne söz dizimi, bir nesneyi tek bir parametre olarak iletmenizi ve ayarlamak istediğiniz işlev bağımsız değişkenleri için nesne özellikleri tanımlamanızı sağlar. Ayrıca API, bağımsız değişken söz diziminin desteklemediği ek işlevleri destekleyebilir.
Örneğin, loadVideoById
işlevi aşağıdaki yöntemlerden biriyle çağrılabilir. Nesne söz diziminin, bağımsız değişken söz diziminin desteklemediği endSeconds
özelliğini desteklediğini unutmayın.
-
Bağımsız değişken söz dizimi
loadVideoById("bHQqvYy5KYo", 5, "large")
-
Nesne söz dizimi
loadVideoById({'videoId': 'bHQqvYy5KYo', 'startSeconds': 5, 'endSeconds': 60});
Videolar için sıralama işlevleri
cueVideoById
-
-
Bağımsız değişken söz dizimi
player.cueVideoById(videoId:String, startSeconds:Number):Void
-
Nesne söz dizimi
player.cueVideoById({videoId:String, startSeconds:Number, endSeconds:Number}):Void
Bu işlev, belirtilen videonun küçük resmini yükler ve oynatıcıyı videoyu oynatmaya hazırlar. Oynatıcı,
playVideo()
veyaseekTo()
çağrılana kadar FLV'yi istemez.- Gerekli
videoId
parametresi, oynatılacak videonun YouTube Video Kimliği'ni belirtir. YouTube Data API'de birvideo
kaynağınınid
özelliği kimliği belirtir. - İsteğe bağlı
startSeconds
parametresi, kayan değeri/tam sayıyı kabul eder veplayVideo()
çağrıldığında videonun oynatılmaya başlayacağı zamanı belirtir. BirstartSeconds
değeri belirtir ve ardındanseekTo()
çağırırsanız oynatıcıseekTo()
çağrısında belirtilen zamandan itibaren oynar. Video işaretlenip oynatılmaya hazır olduğunda oynatıcı birvideo cued
etkinliği (5
) yayınlar. - Yalnızca nesne söz diziminde desteklenen isteğe bağlı
endSeconds
parametresi, kayan/tam sayıyı kabul eder veplayVideo()
çağrıldığında videonun oynatılmasının ne zaman durması gerektiğini belirtir. BirendSeconds
değeri belirleyip ardındanseekTo()
öğesini çağırırsanızendSeconds
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 birvideo
kaynağınınid
özelliği kimliği belirtir. - İsteğe bağlı
startSeconds
parametresi bir kayan sayı/tamsayı kabul eder. Belirtilmişse video, belirtilen zamana en yakın animasyon karesinden başlar. - İsteğe bağlı
endSeconds
parametresi bir kayan sayı/tamsayı kabul eder. Politika belirtildiyse videonun oynatılması belirtilen zamanda durur.
-
cueVideoByUrl
-
-
Bağımsız değişken söz dizimi
player.cueVideoByUrl(mediaContentUrl:String, startSeconds:Number):Void
-
Nesne söz dizimi
player.cueVideoByUrl({mediaContentUrl:String, startSeconds:Number, endSeconds:Number}):Void
Bu işlev, belirtilen videonun küçük resmini yükler ve oynatıcıyı videoyu oynatmaya hazırlar. Oynatıcı,
playVideo()
veyaseekTo()
çağrılana kadar FLV'yi istemez.- Gerekli
mediaContentUrl
parametresi,http://www.youtube.com/v/VIDEO_ID?version=3
biçiminde tam nitelikli bir YouTube oynatıcı URL'si belirtir. - İsteğe bağlı
startSeconds
parametresi, kayan değeri/tam sayıyı kabul eder veplayVideo()
çağrıldığında videonun oynatılmaya başlayacağı zamanı belirtir.startSeconds
öğesini belirtir ve ardındanseekTo()
öğesini çağırırsanız oynatıcı,seekTo()
çağrısında belirtilen zamandan itibaren oynar. Video işaretlenip oynatılmaya hazır olduğunda oynatıcı birvideo cued
etkinliği (5) yayınlar. - Yalnızca nesne söz diziminde desteklenen isteğe bağlı
endSeconds
parametresi, kayan/tam sayıyı kabul eder veplayVideo()
çağrıldığında videonun oynatılmasının ne zaman durması gerektiğini belirtir. BirendSeconds
değeri belirleyip ardındanseekTo()
öğesini çağırırsanızendSeconds
değeri artık geçerli olmaz.
-
loadVideoByUrl
-
-
Bağımsız değişken söz dizimi
player.loadVideoByUrl(mediaContentUrl:String, startSeconds:Number):Void
-
Nesne söz dizimi
player.loadVideoByUrl({mediaContentUrl:String, startSeconds:Number, endSeconds:Number}):Void
Bu işlev, belirtilen videoyu yükler ve oynatır.
- Gerekli
mediaContentUrl
parametresi,http://www.youtube.com/v/VIDEO_ID?version=3
biçiminde tam nitelikli bir YouTube oynatıcı URL'si belirtir. - İsteğe bağlı
startSeconds
parametresi, kayan değeri/tam sayıyı kabul eder ve videonun oynatılmaya başlaması gereken zamanı belirtir.startSeconds
(sayı, kayan nokta olabilir) belirtilmişse video, belirtilen zamana en yakın animasyon karesinden başlar. - Yalnızca nesne söz diziminde desteklenen isteğe bağlı
endSeconds
parametresi, kayan/tam sayıyı kabul eder ve videonun oynatılmasının ne zaman durması gerektiğini belirtir.
-
Listeler için sıralama işlevleri
cuePlaylist
ve loadPlaylist
işlevleri, bir oynatma listesi yükleyip oynatmanıza olanak tanır. Bu işlevleri çağırmak için nesne söz dizimi kullanıyorsanız bir kullanıcının yüklediği videoların listesini de sıraya koyabilirsiniz (veya yükleyebilirsiniz).
İşlevler, bağımsız değişken söz dizimi veya nesne söz dizimi kullanılarak çağrılmalarına bağlı olarak farklı şekilde çalıştığından, her iki çağrı yöntemi aşağıda açıklanmıştır.
cuePlaylist
-
-
Bağımsız değişken söz dizimi
player.cuePlaylist(playlist:String|Array, index:Number, startSeconds:Number):Void
Belirtilen oynatma listesini sıraya alır. Şarkı listesi seçildiğinde ve oynatılmaya hazır olduğunda oynatıcı birvideo cued
etkinliği (5
) yayınlar.-
Gerekli
playlist
parametresi, bir YouTube video kimliği dizisi belirtir. YouTube Data API'devideo
kaynağınınid
özelliği bu videonun kimliğini tanımlar. -
İsteğe bağlı
index
parametresi, oynatma listesindeki oynatılacak ilk videonun dizinini belirtir. Parametre, sıfır tabanlı bir dizin kullanır ve varsayılan parametre değeri0
'dir. Bu nedenle, varsayılan davranış, oynatma listesindeki ilk videoyu yükleyip oynatmaktır. -
İsteğe bağlı
startSeconds
parametresi, kayan değeri/tam sayıyı kabul eder veplayVideo()
işlevi çağrıldığında, oynatma listesindeki ilk videonun oynatılmaya başlayacağı zamanı belirtir. BirstartSeconds
değeri belirtir ve ardındanseekTo()
çağırırsanız oynatıcıseekTo()
çağrısında belirtilen zamandan itibaren oynar. Bir oynatma listesini gösterir ve daha sonraplayVideoAt()
işlevini çağırırsanız oynatıcı, belirtilen videonun başında oynatılmaya başlar.
-
-
Nesne söz dizimi
player.cuePlaylist({listType:String, list:String, index:Number, startSeconds:Number}):Void
Belirtilen video listesini sıraya alır. Bu liste, bir oynatma listesi veya kullanıcının yüklediği videolar feed'i olabilir. Arama sonuçları listesini sıraya ekleme özelliği kullanımdan kaldırılmıştır ve15 Kasım 2020 'den itibaren desteklenmeyecektir.Liste işaretlenip oynamaya hazır olduğunda, oynatıcı bir
video cued
etkinliği (5
) yayınlar.-
İsteğe bağlı
listType
özelliği, aldığınız sonuç feed'inin türünü belirtir. Geçerli değerlerplaylist
veuser_uploads
'dir.15 Kasım 2020 tarihinden itibaren kullanımdan kaldırılmış bir değer olansearch
artık desteklenmeyecektir. Varsayılan değerplaylist
olarak ayarlanmıştır. -
Gerekli
list
özelliği, YouTube'un döndürmesi gereken belirli bir video listesini tanımlayan bir anahtar içerir.listType
özellik değeriplaylist
iselist
özelliği, oynatma listesi kimliğini veya video kimlikleri dizisini belirtir. YouTube Data API'deplaylist
kaynağınınid
özelliği bir oynatma listesinin kimliğini tanımlar vevideo
kaynağınınid
özelliği bir video kimliği belirtir.listType
özellik değeriuser_uploads
iselist
özelliği, yüklenmiş videoları döndürülecek kullanıcıyı tanımlar.listType
özellik değerisearch
iselist
özelliği arama sorgusunu belirtir. Not: Bu işlev kullanımdan kaldırılmıştır ve15 Kasım 2020 tarihinden itibaren desteklenmeyecektir.
-
İsteğe bağlı
index
özelliği, listedeki oynatılacak ilk videonun dizinini belirtir. Parametre, sıfır tabanlı bir dizin kullanır ve varsayılan parametre değeri0
olduğundan, varsayılan davranış listedeki ilk videoyu yükleyip oynatmaktır. -
İsteğe bağlı
startSeconds
özelliği kayan değeri/tam sayıyı kabul eder veplayVideo()
işlevi çağrıldığında, listedeki ilk videonun oynatılmaya başlayacağı zamanı belirtir. BirstartSeconds
değeri belirtir ve ardındanseekTo()
çağırırsanız oynatıcıseekTo()
çağrısında belirtilen zamandan itibaren oynar. Bir listeyi işaretler ve daha sonraplayVideoAt()
işlevini çağırırsanız oynatıcı, belirtilen videonun başında oynatılmaya başlar.
-
-
loadPlaylist
-
-
Bağımsız değişken söz dizimi
player.loadPlaylist(playlist:String|Array, index:Number, startSeconds:Number):Void
Bu işlev, belirtilen oynatma listesini yükler ve oynatır.-
Gerekli
playlist
parametresi, bir YouTube video kimliği dizisi belirtir. YouTube Data API'devideo
kaynağınınid
özelliği bir video kimliği belirtir. -
İsteğe bağlı
index
parametresi, oynatma listesindeki oynatılacak ilk videonun dizinini belirtir. Parametre, sıfır tabanlı bir dizin kullanır ve varsayılan parametre değeri0
'dir. Bu nedenle, varsayılan davranış, oynatma listesindeki ilk videoyu yükleyip oynatmaktır. -
İsteğe bağlı
startSeconds
parametresi, kayan değeri/tam sayıyı kabul eder ve oynatma listesindeki ilk videonun oynatılmaya başlaması gereken zamanı belirtir.
-
-
Nesne söz dizimi
player.loadPlaylist({list:String, listType:String, index:Number, startSeconds:Number}):Void
Bu işlev, belirtilen listeyi yükler ve oynatır. Bu liste, bir oynatma listesi veya kullanıcının yüklediği videolar feed'i olabilir. Arama sonuçları listesi yükleme özelliği kullanımdan kaldırılmıştır ve15 Kasım 2020 'den itibaren artık desteklenmeyecektir.-
İsteğe bağlı
listType
özelliği, aldığınız sonuç feed'inin türünü belirtir. Geçerli değerlerplaylist
veuser_uploads
'dir.15 Kasım 2020 tarihinden itibaren kullanımdan kaldırılmış bir değer olansearch
artık desteklenmeyecektir. Varsayılan değerplaylist
olarak ayarlanmıştır. -
Gerekli
list
özelliği, YouTube'un döndürmesi gereken belirli bir video listesini tanımlayan bir anahtar içerir.listType
özellik değeriplaylist
iselist
özelliği, bir oynatma listesi kimliği veya video kimlikleri dizisi belirtir. YouTube Data API'deplaylist
kaynağınınid
özelliği bir oynatma listesinin kimliğini belirtirkenvideo
kaynağınınid
özelliği bir video kimliği belirtir.listType
özellik değeriuser_uploads
iselist
özelliği, yüklenmiş videoları döndürülecek kullanıcıyı tanımlar.listType
özellik değerisearch
iselist
özelliği arama sorgusunu belirtir. Not: Bu işlev kullanımdan kaldırılmıştır ve15 Kasım 2020 tarihinden itibaren desteklenmeyecektir.
-
İsteğe bağlı
index
özelliği, listedeki oynatılacak ilk videonun dizinini belirtir. Parametre, sıfır tabanlı bir dizin kullanır ve varsayılan parametre değeri0
olduğundan, varsayılan davranış listedeki ilk videoyu yükleyip oynatmaktır. -
İsteğe bağlı
startSeconds
özelliği, kayan değeri/tam sayıyı kabul eder ve listedeki ilk videonun oynatılmaya başlaması gereken zamanı belirtir.
-
-
Oynatma kontrolleri ve oynatıcı ayarları
Video oynatma
player.playVideo():Void
- Şu anda seçilmiş/yüklenmiş videoyu oynatır. Bu işlev yürütüldükten sonraki son oynatıcı durumu
playing
(1) olur.
Not: Bir videonun oynatması, yalnızca oynatıcıdaki yerel oynatma düğmesiyle başlatıldığında resmi görüntüleme sayısına dahil edilir.
player.pauseVideo():Void
- Şu anda oynatılan videoyu duraklatır. İşlev çağrıldığında oynatıcı
ended
(0
) durumunda değilse oynatıcı durumu değişmez. Bu durumda, bu işlev yürütüldükten sonraki son oynatıcı durumupaused
(2
) olur.
player.stopVideo():Void
- Geçerli videonun yüklenmesini durdurur ve yüklemeyi iptal eder. Bu işlev, kullanıcının oynatıcıda ek video izlemeyeceğini bildiğiniz nadir durumlar için ayrılmalıdır. Videoyu duraklatmak istiyorsanız
pauseVideo
işlevini çağırmanız yeterlidir. Oynatıcının oynattığı videoyu değiştirmek isterseniz öncestopVideo
işlevini çağırmadan sıralama işlevlerinden birini çağırabilirsiniz.
Önemli: Oynatıcıyıpaused
(2
) durumunda bırakanpauseVideo
işlevinin aksinestopVideo
işlevi, oynatıcıyıended
(0
),paused
(2
),video cued
(5
) veyaunstarted
(-1
) dahil olmak üzere herhangi bir oynamıyor durumuna alabilir.
player.seekTo(seconds:Number, allowSeekAhead:Boolean):Void
- Videodaki belirli bir zamanı arar. İşlev çağrıldığında oynatıcı duraklatılmışsa, oynatıcı duraklatılmış olarak kalır. İşlev başka bir durumdan (
playing
,video cued
vb.) çağrılırsa oynatıcı videoyu oynatır.-
seconds
parametresi, oynatıcının ne kadar ilerlemesi gerektiğini tanımlar.Oynatıcı videonun kullanıcının aradığı bölümünü zaten indirmediyse oynatıcı bu zamandan önce en yakın animasyon karesine ilerler.
-
seconds
parametresi, arabelleğe alınmış olan video verilerinin dışında bir zaman belirtiyorsaallowSeekAhead
parametresi, oynatıcının sunucuya yeni bir istek gönderip göndermeyeceğini belirler.Kullanıcı fareyi video ilerleme çubuğu boyunca sürüklerken bu parametreyi
false
olarak ayarlamanızı ve kullanıcı fareyi bıraktığındatrue
olarak ayarlamanızı öneririz. Bu yaklaşım, kullanıcının videodaki arabelleğe alınmamış noktaları geçerek yeni video akışları istemeden videonun farklı noktalarına gitmesine olanak tanır. Kullanıcı fare düğmesini serbest bıraktığında, oynatıcı videoda istenen noktaya ilerler ve gerekirse yeni bir video akışı ister.
-
360 derece videoların oynatılmasını kontrol etme
Not: 360 derece video oynatma deneyimi, mobil cihazlarda sınırlı şekilde desteklenmektedir. Desteklenmeyen cihazlarda 360 derecelik videolar bozuk görünür. API aracılığıyla, yön sensörlerini kullanmak veya cihaz ekranındaki dokunma/sürükleme işlemlerine yanıt verme de dahil olmak üzere görüntüleme perspektifini değiştirmenin desteklenen bir yolu yoktur.
player.getSphericalProperties():Object
- Bir video oynatma için izleyicinin o anki perspektifini veya görünümünü açıklayan özellikleri getirir. Ayrıca:
- Bu nesne yalnızca, küre şeklinde videolar olarak da adlandırılan 360 derecelik videolar için doldurulur.
- Geçerli video 360 derecelik bir video değilse veya işlev desteklenmeyen bir cihazdan çağrılırsa işlev boş bir nesne döndürür.
- Desteklenen mobil cihazlarda
enableOrientationSensor
özelliğitrue
değerine ayarlanırsa bu işlev,fov
özelliğinin doğru değeri içerdiği ve diğer özelliklerin0
değerine ayarlandığı bir nesne döndürür.
Özellikler yaw
Görünümün yatay açısını derece cinsinden temsil eden ve kullanıcının görünümü ne ölçüde sola veya sağa çevirdiğini yansıtan, [0, 360) aralığında bir sayı. Eşkenar dörtgen projeksiyonunda videonun merkezine bakan nötr konum, 0°'yi temsil eder ve izleyici sola döndükçe bu değer artar. pitch
Derece cinsinden görünümün dikey açısını temsil eden ve kullanıcının görünümü yukarı veya aşağı doğru ne ölçüde ayarladığını yansıtan, [-90, 90] aralığında bir sayı. Eşkenar dörtgen projeksiyonunda videonun merkezine bakan nötr konum, 0°'yi temsil eder ve izleyici yukarıya baktığında bu değer artar. roll
Görünümün saat yönünde veya saat yönünün tersine dönme açısını derece cinsinden temsil eden [-180, 180] aralığında bir sayı. Eşkenar dörtgen projeksiyondaki yatay ekseni görünümün yatay eksenine paralel olacak şekilde nötr konum, 0°'yi temsil eder. Görünüm saat yönünde döndükçe değer artar ve görünüm saat yönünün tersine döndürüldükçe değer azalır.
Yerleşik oynatıcının, görüntüleme rulosunu ayarlamak için bir kullanıcı arayüzü sunmadığını unutmayın. Zar atışı, karşılıklı olarak devre dışı bırakılan şu yöntemlerden biriyle ayarlanabilir:- 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 zaman0
değerini döndürür. - Yön sensörü devre dışı bırakıldıysa bu API'yi kullanarak yuvarlamayı sıfır dışında bir değere ayarlayın.
fov
Görüntünün görüş alanını, görüntü alanının uzun kenarı boyunca ölçülen, derece cinsinden temsil eden, [30, 120] aralığında bir sayı. Kısa kenar, görünümün en boy oranıyla orantılı olacak şekilde otomatik olarak ayarlanır.
Varsayılan değer 100 derecedir. Değeri azaltmak video içeriğini yakınlaştırmak, artırmak ise uzaklaştırmak gibidir. Bu değer, API veya video tam ekran modundayken fare tekerleği kullanılarak ayarlanabilir.
player.setSphericalProperties(properties:Object):Void
- 360 derecelik videonun oynatılacağı video yönünü ayarlar. (Mevcut video küre değilse yöntem, girişten bağımsız olarak işlemsizdir.)
Oynatıcı görünümü, bu yönteme yapılan çağrılara yanıt verirkenproperties
nesnesindeki bilinen özelliklerin değerlerini yansıtacak şekilde güncellenir. Görünüm, söz konusu nesnede yer almayan diğer bilinen özelliklerin değerlerini korur.
Ek olarak:- Nesne bilinmeyen ve/veya beklenmeyen özellikler içeriyorsa oynatıcı bunları yoksayar.
- Bu bölümün başında belirtildiği üzere 360 derece video oynatma deneyimi tüm mobil cihazlarda desteklenmez.
- Varsayılan olarak, desteklenen mobil cihazlarda bu işlev yalnızca
fov
özelliğini ayarlar. 360° video oynatmaları içinyaw
,pitch
veroll
özelliklerini etkilemez. Daha fazla ayrıntı için aşağıdakienableOrientationSensor
özelliğine bakın.
properties
nesnesi aşağıdaki özellikleri içerir:Özellikler yaw
Yukarıdaki tanımı inceleyin. pitch
Yukarıdaki tanımı inceleyin. roll
Yukarıdaki tanımı inceleyin. fov
Yukarıdaki tanımı inceleyin. enableOrientationSensor
Not: Bu özellik, yalnızca desteklenen cihazlarda 360 derece görüntüleme deneyimini etkiler.IFrame yerleştirmesinin, desteklenen bir cihazın yönünde değişiklik sinyali veren etkinliklere (ör. mobil tarayıcının DeviceOrientationEvent
) yanıt vermesi gerekip gerekmediğini belirten boole değeridir. Varsayılan parametre değeri:true
.
Desteklenen mobil cihazlar- Değer
true
olduğunda, yerleştirilmiş oynatıcı 360° video oynatmaları içinyaw
,pitch
veroll
özelliklerini ayarlamak üzere yalnızca cihazın hareketine dayanır. Ancakfov
özelliği yine de API aracılığıyla değiştirilebilir. Aslında bir mobil cihazdafov
özelliğini değiştirmenin tek yolu API'dir. Bu, varsayılan davranıştır. - Değer
false
olduğunda cihazın hareketleri 360 derece görüntüleme deneyimini etkilemez veyaw
,pitch
,roll
vefov
özelliklerinin tamamı API aracılığıyla ayarlanmalıdır.
Desteklenmeyen mobil cihazlar
enableOrientationSensor
özellik değerinin, oynatma deneyimi üzerinde herhangi bir etkisi yoktur.
Oynatma listesinde video oynatma
player.nextVideo():Void
- Bu işlev, oynatma listesindeki bir sonraki videoyu yükleyip oynatır.
-
Oynatma listesindeki son video izlenirken
player.nextVideo()
çağrılırsa ve oynatma listesi sürekli oynatılacak şekilde (loop
) ayarlanırsa oynatıcı, listedeki ilk videoyu yükler ve oynatır. -
Oynatma listesindeki son video izlenirken
player.nextVideo()
çağrılırsa ve oynatma listesi sürekli oynatılacak şekilde ayarlanmadıysa oynatma işlemi sona erer.
-
player.previousVideo():Void
- Bu işlev, oynatma listesindeki önceki videoyu yükleyip oynatır.
-
Oynatma listesindeki ilk video izlenirken
player.previousVideo()
çağrılırsa ve oynatma listesi sürekli oynatılacak şekilde (loop
) ayarlanırsa oynatıcı, listedeki son videoyu yükleyip oynatır. -
Oynatma listesindeki ilk video izlenirken
player.previousVideo()
çağrılırsa ve oynatma listesi sürekli oynatılacak şekilde ayarlanmadıysa oynatıcı, ilk oynatma listesi videosunu baştan başlatır.
-
player.playVideoAt(index:Number):Void
- Bu işlev, oynatma listesinde belirtilen videoyu yükleyip oynatır.
-
Gerekli
index
parametresi, oynatma listesinde oynatmak istediğiniz videonun dizinini belirtir. Parametre, sıfır tabanlı bir dizin kullandığından0
değeri, listedeki ilk videoyu tanımlar. Oynatma listesini karıştırdıysanız bu işlev, videoyu karıştırılmış oynatma listesinde belirtilen konumda oynatır.
-
Oynatıcının ses seviyesini değiştirme
player.mute():Void
- Oynatıcının sesini kapatır.
player.unMute():Void
- Oyuncunun sesini açar.
player.isMuted():Boolean
- Oynatıcının sesi kapalıysa
true
, kapalıysafalse
değerini döndürür.
player.setVolume(volume:Number):Void
- Ses seviyesini ayarlar.
0
ile100
arasında bir tam sayı kabul eder.
player.getVolume():Number
- Oynatıcının mevcut ses seviyesini döndürür (
0
ile100
arasında bir tam sayı). Oynatıcının sesi kapalı olsa bilegetVolume()
cihazının sesi tekrar vereceğini unutmayın.
Oynatıcı boyutunu ayarlama
player.setSize(width:Number, height:Number):Object
- Oynatıcıyı içeren
<iframe>
öğesinin piksel cinsinden boyutunu ayarlar.
Oynatma hızını ayarlama
player.getPlaybackRate():Number
- Bu işlev, şu anda oynatılan videonun oynatma hızını getirir. Varsayılan oynatma hızı
1
, videonun normal hızda oynatıldığını belirtir. Oynatma hızları0.25
,0.5
,1
,1.5
ve2
gibi değerleri içerebilir.
player.setPlaybackRate(suggestedRate:Number):Void
- Bu işlev, mevcut video için önerilen oynatma hızını ayarlar. Oynatma hızı değişirse yalnızca seçilen veya oynatılan video için değişir. İşaretlenmiş bir video için oynatma hızını ayarlarsanız bu hız,
playVideo
işlevi çağrıldığında veya kullanıcı doğrudan oynatıcı kontrolleri aracılığıyla oynatmayı başlattığında geçerli olur. Ayrıca, videoları veya oynatma listelerini işaretlemek ya da yüklemek için işlevleri çağırmak (cueVideoById
,loadVideoById
vb.) oynatma hızını1
olarak sıfırlar.
Bu işlevin çağrılması, oynatma hızının gerçekten değişeceğini garanti etmez. Bununla birlikte, oynatma hızı değişirseonPlaybackRateChange
etkinliği tetiklenir ve kodunuz,setPlaybackRate
işlevini çağırdığı için değil, etkinliğe yanıt vermelidir.
getAvailablePlaybackRates
yöntemi, şu anda oynatılan video için olası oynatma hızlarını döndürür. Bununla birlikte,suggestedRate
parametresini desteklenmeyen bir tam sayı veya kayan bir değere ayarlarsanız oynatıcı bu değeri,1
yönünde desteklenen en yakın değere yuvarlar.
player.getAvailablePlaybackRates():Array
- Bu işlev, geçerli videonun sunulduğu oynatma hızlarını döndürür. Varsayılan değer olan
1
, videonun normal hızda oynatıldığını ifade eder.
İşlev, en yavaş oynatma hızından en hızlı oynatma hızına doğru sıralanmış bir sayı dizisi döndürür. Oynatıcı değişken oynatma hızlarını desteklemese bile dizi her zaman en az bir değer (1
) içermelidir.
Oynatma listeleri için oynatma davranışını ayarlama
player.setLoop(loopPlaylists:Boolean):Void
-
Bu işlev, video oynatıcının bir oynatma listesini sürekli olarak oynatmasını veya oynatma listesindeki son video bittikten sonra oynatmayı durdurmasını belirtir. Varsayılan davranış, oynatma listelerinin döngüye alınmamasıdır.
Bu ayar, farklı bir oynatma listesi yükleseniz veya işaret etseniz bile devam eder. Diğer bir deyişle, bir şarkı listesi yüklerseniz
true
değeriylesetLoop
işlevini çağırır ve ardından ikinci bir oynatma listesi yüklerseniz ikinci oynatma listesi de döngüye alınır.Gerekli
loopPlaylists
parametresi, döngü davranışını tanımlar.-
Parametre değeri
true
ise video oynatıcı, oynatma listelerini sürekli olarak oynatır. Oynatma listesindeki son video oynatıldıktan sonra video oynatıcı, oynatma listesinin başına geri döner ve videoyu tekrar oynatır. -
Parametre değeri
false
ise video oynatıcı, oynatma listesindeki son videoyu oynattıktan sonra oynatmalar sona erer.
-
player.setShuffle(shufflePlaylist:Boolean):Void
-
Bu işlev, oynatma listesindeki videoların, oynatma listesi oluşturucusunun belirlediğinden farklı bir sırada oynatılacak şekilde karıştırılıp karıştırılmayacağını belirtir. Bir oynatma listesini oynatmaya başladıktan sonra karıştırırsanız oynatılan video oynatılmaya devam ederken liste yeniden sıralanır. Oynatılacak bir sonraki video, yeniden sıralanan listeye göre seçilir.
Farklı bir oynatma listesi yükler veya gösterirseniz bu ayar devam etmez. Diğer bir deyişle, bir oynatma listesi yükler,
setShuffle
işlevini çağırır ve ardından ikinci bir oynatma listesi yüklerseniz ikinci oynatma listesi karıştırılmaz.Gerekli
shufflePlaylist
parametresi, YouTube'un oynatma listesini karıştırıp karıştırmayacağını ifade eder.-
Parametre değeri
true
ise YouTube, oynatma listesi sırasını karıştırır. Fonksiyona, daha önce karıştırılmış bir oynatma listesini karıştırma talimatı verirseniz YouTube sıralamayı tekrar karıştırır. -
Parametre değeri
false
ise YouTube, oynatma listesi sırasını orijinal sırasına geri döndürür.
-
Oynatma durumu
player.getVideoLoadedFraction():Float
0
ile1
arasında, oynatıcının arabelleğe alınmış olarak gösterdiği videonun yüzdesini belirten bir sayı döndürür. Bu yöntem, kullanımdan kaldırılangetVideoBytesLoaded
vegetVideoBytesTotal
yöntemlerinden daha güvenilir bir sayı döndürür.
player.getPlayerState():Number
- Oyuncunun durumunu döndürür. Olası değerler:
-1
– başlamadı0
– sona erdi1
- oynatılıyor2
- duraklatıldı3
- arabelleğe alınıyor5
– video seçildi
player.getCurrentTime():Number
- Videonun oynatılmaya başlamasından itibaren geçen süreyi saniye cinsinden döndürür.
player.getVideoStartBytes():Number
- 31 Ekim 2012 itibarıyla kullanımdan kaldırılmıştır. Video dosyasının yüklenmeye başladığı bayt sayısını döndürür. (Bu yöntem artık her zaman
0
değerini döndürür.) Örnek senaryo: Kullanıcı henüz yüklenmemiş bir noktaya doğru ilerler ve oynatıcı, videonun henüz yüklenmeyen bir segmentini oynatmak için yeni bir istekte bulunur.
player.getVideoBytesLoaded():Number
-
18 Temmuz 2012 itibarıyla kullanımdan kaldırılmıştır. Bunun yerine, videonun arabelleğe alınan yüzdesini belirlemek için
getVideoLoadedFraction
yöntemini kullanın.
Bu yöntem,0
ile1000
arasında, yüklenen videonun miktarını yaklaşık olarak belirten bir değer döndürür.getVideoBytesLoaded
değerinigetVideoBytesTotal
değerine bölerek videonun yüklenen oranını hesaplayabilirsiniz.
player.getVideoBytesTotal():Number
-
18 Temmuz 2012 itibarıyla kullanımdan kaldırılmıştır. Bunun yerine, videonun arabelleğe alınan yüzdesini belirlemek için
getVideoLoadedFraction
yöntemini kullanın.
Yüklenen/oynatılan videonun bayt cinsinden boyutunu veya yaklaşık video boyutunu döndürür.
Bu yöntem her zaman1000
değerini döndürür.getVideoBytesLoaded
değerinigetVideoBytesTotal
değerine bölerek videonun yüklenen oranını hesaplayabilirsiniz.
Video bilgilerini alma
player.getDuration():Number
- Şu anda oynatılan videonun süresini saniye cinsinden döndürür.
getDuration()
işlevinin, videonun meta verileri yüklenene kadar (genellikle video oynatılmaya başladıktan hemen sonra gerçekleşir)0
değerini döndüreceğini unutmayın.
Şu anda oynatılan video bir canlı etkinlik isegetDuration()
işlevi, canlı video akışının başlamasından itibaren geçen süreyi döndürür. Daha ayrıntılı belirtmek gerekirse bu, videonun sıfırlanmadan veya kesintiye uğramadan yayınlandığı süredir. Ayrıca akış etkinliğin başlangıç zamanından önce başlayabileceği için bu süre genellikle gerçek etkinlik zamanından daha uzundur.
player.getVideoUrl():String
- Şu anda yüklü olan/oynatılan videonun YouTube.com URL'sini döndürür.
player.getVideoEmbedCode():String
- Şu anda yüklü olan/oynatılan videoya ilişkin yerleştirme kodunu döndürür.
Oynatma listesi bilgilerini alma
player.getPlaylist():Array
- Bu işlev, oynatma listesindeki video kimlikleri dizisini şu anda sıralanmış şekilde döndürür. Varsayılan olarak bu işlev, video kimliklerini oynatma listesi sahibi tarafından belirlenen sırada döndürür. Bununla birlikte, oynatma listesi sırasını karıştırmak için
setShuffle
işlevini çağırdıysanızgetPlaylist()
işlevinin döndürülen değeri karıştırılan sırayı yansıtır.
player.getPlaylistIndex():Number
- Bu işlev, oynatılan oynatma listesi videosunun dizinini döndürür.
-
Oynatma listesini karıştırmadıysanız döndürülen değer, oynatma listesi oluşturucunun videoyu yerleştirdiği konumu tanımlar. Döndürülen değer sıfır tabanlı bir dizin kullanır, dolayısıyla
0
değeri oynatma listesindeki ilk videoyu tanımlar. -
Oynatma listesini karıştırdıysanız döndürülen değer, videonun karıştırılmış oynatma listesindeki sırasını tanımlar.
-
Etkinlik işleyici ekleme veya kaldırma
player.addEventListener(event:String, listener:String):Void
- Belirtilen
event
için bir işleyici işlevi ekler. Aşağıdaki Etkinlikler bölümü, oyuncunun tetikleyebileceği farklı etkinlikleri tanımlar. İşleyici, belirtilen etkinlik tetiklendiğinde yürütülecek işlevi belirten bir dizedir.
player.removeEventListener(event:String, listener:String):Void
- Belirtilen
event
için bir işleyici işlevini kaldırır.listener
, belirtilen etkinlik tetiklendiğinde artık yürütülmeyecek işlevi tanımlayan bir dizedir.
DOM düğümlerine erişme ve bunları değiştirme
player.getIframe():Object
- Bu yöntem, yerleştirilmiş
<iframe>
için DOM düğümünü döndürür.
player.destroy():Void
- Oynatıcıyı içeren
<iframe>
öğesini kaldırır.
Etkinlikler
API, yerleştirilmiş oynatıcıda yapılan değişiklikleri uygulamanızı bildirmek için etkinlikleri tetikler. Önceki bölümde belirtildiği gibi, YT.Player
nesnesini oluştururken bir etkinlik işleyici ekleyerek etkinliklere abone olabilir ve addEventListener
işlevini de kullanabilirsiniz.
API, bir etkinlik nesnesini bu işlevlerin her birine tek bağımsız değişken olarak iletir. Etkinlik nesnesi aşağıdaki özelliklere sahiptir:
- Etkinliğin
target
öğesi, etkinliğe karşılık gelen video oynatıcıyı tanımlar. - Etkinliğin
data
özelliği, etkinlikle ilgili bir değeri belirtiyor.onReady
veonAutoplayBlocked
etkinliklerinin birdata
özelliği belirtmediğini unutmayın.
Aşağıdaki listede API'nin tetiklediği etkinlikler tanımlanmaktadır:
onReady
- Bu etkinlik, oynatıcının yüklenmesi tamamlandığında ve API çağrıları almaya hazır olduğunda tetiklenir. Video oynatma veya video hakkında bilgi görüntüleme gibi belirli işlemleri oynatıcı hazır olur olmaz otomatik olarak yürütmek istiyorsanız uygulamanız bu işlevi uygulamalıdır.
Aşağıdaki örnekte, bu etkinliğin işlenmesine yönelik bir örnek işlev gösterilmektedir. API'nin işleve gönderdiği etkinlik nesnesi, oynatıcıyı tanımlayan birtarget
özelliğine sahiptir. İşlev, yüklenmiş olan videonun yerleştirme kodunu alır, videoyu oynatmaya başlar ve yerleştirme kodunu,id
değeriembed-code
olan sayfa öğesinde gösterir.function onPlayerReady(event) { var embedCode = event.target.getVideoEmbedCode(); event.target.playVideo(); if (document.getElementById('embed-code')) { document.getElementById('embed-code').innerHTML = embedCode; } }
onStateChange
- Bu etkinlik, oyuncunun durumu her değiştiğinde tetiklenir.
API'nin etkinlik işleyici işlevinize ilettiği etkinlik nesnesinin
data
özelliği, yeni oynatıcı durumuna karşılık gelen bir tam sayı belirtir. Olası değerler:-1
(başlamadı)0
(sona erdi)1
(oynuyor)2
(duraklatıldı)3
(arabelleğe alınıyor)5
(video seçme).
unstarted
(-1
) etkinliği yayınlar. Bir video işaretlenip oynatılmaya hazır olduğunda oynatıcı birvideo cued
(5
) etkinliği yayınlar. Kodunuzda tam sayı değerlerini belirtebilir veya aşağıdaki ad alanı değişkenlerinden birini kullanabilirsiniz:YT.PlayerState.ENDED
YT.PlayerState.PLAYING
YT.PlayerState.PAUSED
YT.PlayerState.BUFFERING
YT.PlayerState.CUED
onPlaybackQualityChange
- Bu etkinlik, video oynatma kalitesi her değiştiğinde tetiklenir. İzleyicinin oynatma ortamında bir değişiklik olduğunu gösterebilir. Oynatma koşullarını etkileyen veya etkinliğin tetiklenmesine neden olabilecek faktörler hakkında daha fazla bilgi için YouTube Yardım Merkezi'ne bakın.
API'nin etkinlik işleyici işlevine gönderdiği etkinlik nesnesinindata
özellik değeri, yeni oynatma kalitesini tanımlayan bir dize olur. Olası değerler:small
medium
large
hd720
hd1080
highres
onPlaybackRateChange
- Bu etkinlik, video oynatma hızı her değiştiğinde tetiklenir. Örneğin,
setPlaybackRate(suggestedRate)
işlevini çağırırsanız bu etkinlik, oynatma hızı gerçekten değişirse tetiklenir. Uygulamanız etkinliğe yanıt vermeli vesetPlaybackRate(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ızcasetPlaybackRate
öğesine açık bir çağrının sonucu olarak değişeceğini varsaymamalıdır.
API'nin etkinlik işleyici işlevine ilettiği etkinlik nesnesinindata
özellik değeri, yeni oynatma hızını tanımlayan bir sayı olur.getAvailablePlaybackRates
yöntemi, geçerli olarak seçilmiş veya oynatılan video için geçerli oynatma hızlarının listesini döndürür.
onError
- Oynatıcıda bir hata oluşursa bu etkinlik tetiklenir.
API, etkinlik işleyici işlevine bir
event
nesnesi iletir. Bu nesnenindata
özelliği, oluşan hatanın türünü tanımlayan bir tam sayı belirtir. Olası değerler:2
– İstek geçersiz bir parametre değeri içeriyor. Örneğin bu hata, 11 karakteri olmayan bir video kimliği belirtirseniz veya video kimliği ünlem işaretleri ya da yıldız işaretleri gibi geçersiz karakterler içeriyorsa ortaya çıkar.5
– İstenen içerik bir HTML5 oynatıcısında oynatılamıyor veya HTML5 oynatıcısıyla ilgili başka bir hata oluştu.100
– İstenen video bulunamadı. Bu hata, bir video kaldırıldığında (herhangi bir nedenle) veya özel olarak işaretlendiğinde ortaya çıkar.101
: İstenen videonun sahibi, videonun yerleşik oynatıcılarda oynatılmasına izin vermiyor.150
– Bu hata101
ile aynıdır. Bu sadece101
gizlenmiş bir hata.
onApiChange
- Bu etkinlik, oynatıcının açık API yöntemleriyle bir modül yüklediğini (veya kaldırdığını) göstermek için tetiklenir. Uygulamanız bu etkinliği dinleyebilir ve ardından son yüklenen modül için hangi seçeneklerin gösterileceğini belirlemek üzere oynatıcıyı yoklayabilir. Daha sonra uygulamanız bu seçenekler için mevcut ayarları alabilir veya güncelleyebilir.
Aşağıdaki komut, oynatıcı seçeneklerini ayarlayabileceğiniz bir modül adları dizisi alır:
player.getOptions();
Şu anda seçenekleri ayarlayabileceğiniz tek modül, oynatıcıda altyazı işleyencaptions
modülüdür. Uygulamanız, bironApiChange
etkinliği aldıktan sonracaptions
modülü için hangi seçeneklerin ayarlanabileceğini belirlemek üzere aşağıdaki komutu kullanabilir:
player.getOptions('captions');
Oynatıcıyı bu komutla yoklayarak erişmek istediğiniz seçeneklerin gerçekten erişilebilir olduğunu onaylayabilirsiniz. Aşağıdaki komutlar modül seçeneklerini alır ve günceller:
Retrieving an option: player.getOption(module, option); Setting an option player.setOption(module, option, value);
Aşağıdaki tabloda API'nin desteklediği seçenekler listelenmiştir:
Modül Option Açıklama captions fontSize Bu seçenek, oynatıcıda gösterilen altyazıların yazı tipi boyutunu ayarlar.
Geçerli değerler:-1
,0
,1
,2
ve3
. Varsayılan boyut0
, en küçük boyut ise-1
'dir. Bu seçeneğin-1
değerinin altında bir tam sayı olarak ayarlanması en küçük altyazı boyutunun gösterilmesine neden olurken, bu seçeneğin3
üzerinde bir tam sayı olarak ayarlanması en büyük altyazı boyutunun gösterilmesine neden olur.captions yeniden yükleme Bu seçenek, oynatılan videoya ilişkin altyazı verilerini yeniden yükler. Seçeneğin değerini alırsanız değer null
olur. Altyazı verilerini yeniden yüklemek için değeritrue
olarak ayarlayın.
onAutoplayBlocked
- Bu etkinlik, tarayıcı otomatik oynatmayı veya komut dosyası tabanlı video oynatma özelliklerini engellediğinde tetiklenir. Bunlara toplu olarak "otomatik oynatma" denir. Buna, aşağıdaki oynatıcı API'lerinden herhangi biriyle denenen oynatmalar da dahildir:
autoplay
parametresiloadPlaylist
işleviloadVideoById
işleviloadVideoByUrl
işleviplayVideo
işlevi
Ayrıntıların tamamı için tarayıcıya özel politikaları (Apple Safari / Webkit, Google Chrome, Mozilla Firefox) ve Mozilla'nın otomatik oynatma kılavuzunu inceleyin.
Örnekler
YT.Player
nesne oluşturuluyor
-
Örnek 1: API'yi mevcut <iframe> ile kullanma
Bu örnekte, sayfadaki
<iframe>
öğesi, API'nin birlikte kullanılacağı oynatıcıyı zaten tanımlıyor. Oynatıcınınsrc
URL'sininenablejsapi
parametresinin1
olarak ayarlanması veya<iframe>
öğesininenablejsapi
özelliğinintrue
olarak ayarlanması gerektiğini unutmayın.onPlayerReady
işlevi, oynatıcı hazır olduğunda oynatıcının çevresindeki kenarlığın rengini turuncuya dönüştürür.onPlayerStateChange
işlevi daha sonra, mevcut oynatıcı durumuna göre oynatıcının çevresindeki kenarlığın rengini değiştirir. Örneğin, renk oynatıcı oynarken yeşil, duraklatıldığında kırmızı, arabelleğe alırken mavi vb.Bu örnekte aşağıdaki kod kullanılmaktadır:
<iframe id="existing-iframe-example" width="640" height="360" src="https://www.youtube.com/embed/M7lc1UVf-VE?enablejsapi=1" frameborder="0" style="border: solid 4px #37474F" ></iframe> <script type="text/javascript"> var tag = document.createElement('script'); tag.id = 'iframe-demo'; tag.src = 'https://www.youtube.com/iframe_api'; var firstScriptTag = document.getElementsByTagName('script')[0]; firstScriptTag.parentNode.insertBefore(tag, firstScriptTag); var player; function onYouTubeIframeAPIReady() { player = new YT.Player('existing-iframe-example', { events: { 'onReady': onPlayerReady, 'onStateChange': onPlayerStateChange } }); } function onPlayerReady(event) { document.getElementById('existing-iframe-example').style.borderColor = '#FF6D00'; } function changeBorderColor(playerStatus) { var color; if (playerStatus == -1) { color = "#37474F"; // unstarted = gray } else if (playerStatus == 0) { color = "#FFFF00"; // ended = yellow } else if (playerStatus == 1) { color = "#33691E"; // playing = green } else if (playerStatus == 2) { color = "#DD2C00"; // paused = red } else if (playerStatus == 3) { color = "#AA00FF"; // buffering = purple } else if (playerStatus == 5) { color = "#FF6DOO"; // video cued = orange } if (color) { document.getElementById('existing-iframe-example').style.borderColor = color; } } function onPlayerStateChange(event) { changeBorderColor(event.data); } </script>
-
2. Örnek: Yüksek sesli oynatma
Bu örnekte 1280 piksele 720 piksel boyutunda bir video oynatıcı oluşturulur. Ardından
onReady
etkinliğinin etkinlik işleyici ses düzeyini en yüksek ayara ayarlamak içinsetVolume
işlevini çağırır.function onYouTubeIframeAPIReady() { var player; player = new YT.Player('player', { width: 1280, height: 720, videoId: 'M7lc1UVf-VE', events: { 'onReady': onPlayerReady, 'onStateChange': onPlayerStateChange, 'onError': onPlayerError } }); } function onPlayerReady(event) { event.target.setVolume(100); event.target.playVideo(); }
-
3. Örnek: Bu örnekte, oynatıcı parametreleri, videoyu yüklendiğinde otomatik olarak oynatacak ve video oynatıcının kontrollerini gizleyecek şekilde ayarlanmıştır. Ayrıca, API'nin yayınladığı çeşitli etkinlikler için etkinlik işleyiciler de ekler.
function onYouTubeIframeAPIReady() { var player; player = new YT.Player('player', { videoId: 'M7lc1UVf-VE', playerVars: { 'autoplay': 1, 'controls': 0 }, events: { 'onReady': onPlayerReady, 'onStateChange': onPlayerStateChange, 'onError': onPlayerError } }); }
360 derece videoları kontrol etme
Bu örnekte aşağıdaki kod kullanılmaktadır:
<style> .current-values { color: #666; font-size: 12px; } </style> <!-- The player is inserted in the following div element --> <div id="spherical-video-player"></div> <!-- Display spherical property values and enable user to update them. --> <table style="border: 0; width: 640px;"> <tr style="background: #fff;"> <td> <label for="yaw-property">yaw: </label> <input type="text" id="yaw-property" style="width: 80px"><br> <div id="yaw-current-value" class="current-values"> </div> </td> <td> <label for="pitch-property">pitch: </label> <input type="text" id="pitch-property" style="width: 80px"><br> <div id="pitch-current-value" class="current-values"> </div> </td> <td> <label for="roll-property">roll: </label> <input type="text" id="roll-property" style="width: 80px"><br> <div id="roll-current-value" class="current-values"> </div> </td> <td> <label for="fov-property">fov: </label> <input type="text" id="fov-property" style="width: 80px"><br> <div id="fov-current-value" class="current-values"> </div> </td> <td style="vertical-align: bottom;"> <button id="spherical-properties-button">Update properties</button> </td> </tr> </table> <script type="text/javascript"> var tag = document.createElement('script'); tag.id = 'iframe-demo'; tag.src = 'https://www.youtube.com/iframe_api'; var firstScriptTag = document.getElementsByTagName('script')[0]; firstScriptTag.parentNode.insertBefore(tag, firstScriptTag); var PROPERTIES = ['yaw', 'pitch', 'roll', 'fov']; var updateButton = document.getElementById('spherical-properties-button'); // Create the YouTube Player. var ytplayer; function onYouTubeIframeAPIReady() { ytplayer = new YT.Player('spherical-video-player', { height: '360', width: '640', videoId: 'FAtdv94yzp4', }); } // Don't display current spherical settings because there aren't any. function hideCurrentSettings() { for (var p = 0; p < PROPERTIES.length; p++) { document.getElementById(PROPERTIES[p] + '-current-value').innerHTML = ''; } } // Retrieve current spherical property values from the API and display them. function updateSetting() { if (!ytplayer || !ytplayer.getSphericalProperties) { hideCurrentSettings(); } else { let newSettings = ytplayer.getSphericalProperties(); if (Object.keys(newSettings).length === 0) { hideCurrentSettings(); } else { for (var p = 0; p < PROPERTIES.length; p++) { if (newSettings.hasOwnProperty(PROPERTIES[p])) { currentValueNode = document.getElementById(PROPERTIES[p] + '-current-value'); currentValueNode.innerHTML = ('current: ' + newSettings[PROPERTIES[p]].toFixed(4)); } } } } requestAnimationFrame(updateSetting); } updateSetting(); // Call the API to update spherical property values. updateButton.onclick = function() { var sphericalProperties = {}; for (var p = 0; p < PROPERTIES.length; p++) { var propertyInput = document.getElementById(PROPERTIES[p] + '-property'); sphericalProperties[PROPERTIES[p]] = parseFloat(propertyInput.value); } ytplayer.setSphericalProperties(sphericalProperties); } </script>
Düzeltme geçmişi
November 20, 2023
The new onAutoplayBlocked
event API is now available.
This event notifies your application if the browser blocks autoplay or scripted playback.
Verification of autoplay success or failure is an
established paradigm
for HTMLMediaElements, and the onAutoplayBlocked
event now provides similar
functionality for the IFrame Player API.
April 27, 2021
The Getting Started and Loading a Video Player sections have been updated to include examples of using a playerVars
object to customize the player.
October 13, 2020
Note: This is a deprecation announcement for the embedded player
functionality that lets you configure the player to load search results. This announcement affects
the IFrame Player API's queueing functions for lists,
cuePlaylist
and
loadPlaylist
.
This change will become effective on or after 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
, andgetAvailableQualityLevels
functions are no longer supported. In particular, calls tosetPlaybackQuality
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 thesuggestedQuality
argument. Similarly, if you call those functions using object syntax, thesuggestedQuality
field is no longer supported. IfsuggestedQuality
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 toDeviceOrientationEvents
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 thecaptions
module and not thecc
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:
-
The new removeEventListener function lets you remove a listener for a specified event.
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 whenplayVideo()
is called. -
The
getVideoStartBytes
method has been deprecated. The method now always returns a value of0
.
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 theonYouTubeIframeAPIReady
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
onPlaybackRateChange
– This event fires when the video's playback rate changes.
-
July 19, 2012
This update contains the following changes:
-
The new
getVideoLoadedFraction
method replaces the now-deprecatedgetVideoBytesLoaded
andgetVideoBytesTotal
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 of5
, 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 namedonYouTubePlayerAPIReady
. 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 anonYouTubePlayerAPIReady
function, both functions will be called, and theonYouTubeIframeAPIReady
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()
anddestroy()
methods. ThesetSize()
method sets the size in pixels of the<iframe>
that contains the player and thedestroy()
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 aninline-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.