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:
-
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>
etiketiniid
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. -
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ş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 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. -
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. -
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ı durumu1
(oynatılıyor) olduğunda, oynatıcının altı saniye boyunca oynatması ve ardından videoyu durdurmak içinstopVideo
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:
-
İlk parametre, ya DOM öğesini ya da API'nin oynatıcıyı içeren
<iframe>
etiketini ekleyacağı HTML öğesininid
öğ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
değeridir.height
(sayı) – Video oynatıcının yüksekliği. Varsayılan değer390
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ğindeonPlayerReady
işlevinin yürütüleceğini veonStateChange
etkinliği tetiklendiğindeonPlayerStateChange
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()
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 nokta/tam sayı kabul eder veplayVideo()
çağrıldığında videonun oynatılmaya başlayacağı zamanı belirtir.startSeconds
değeri belirtipseekTo()
ç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ı birvideo cued
etkinliği (5
) yayınlar. - Yalnızca nesne söz diziminde desteklenen isteğe bağlı
endSeconds
parametresi, bir kayan/tamsayı kabul eder veplayVideo()
çağrıldığında videonun oynatılmasının ne zaman durması gerektiğini belirtir. BirendSeconds
değeri belirleyipseekTo()
yöntemini ç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, 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()
veyaseekTo()
çağrılana kadar FLV'yi istemez.- Gerekli
mediaContentUrl
parametresi, tam nitelikli bir YouTube oynatıcı URL'sinihttp://www.youtube.com/v/VIDEO_ID?version=3
biçiminde belirtir. - İsteğe bağlı
startSeconds
parametresi, kayan nokta/tam sayı kabul eder veplayVideo()
çağrıldığında videonun oynatılmaya başlayacağı zamanı belirtir.startSeconds
öğesini belirleyipseekTo()
ç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ı birvideo cued
etkinliği (5) yayınlar. - Yalnızca nesne söz diziminde desteklenen isteğe bağlı
endSeconds
parametresi, bir kayan/tamsayı kabul eder veplayVideo()
çağrıldığında videonun oynatılmasının ne zaman durması gerektiğini belirtir. BirendSeconds
değeri belirleyipseekTo()
yöntemini ç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, tam nitelikli bir YouTube oynatıcı URL'sinihttp://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ı birvideo cued
etkinliği (5
) yayınlar.-
Gerekli
playlist
parametresi, bir YouTube video kimlikleri dizisini belirtir. YouTube Data API'de,video
kaynağınınid
ö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ğeri0
ş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 veplayVideo()
işlevi çağrıldığında, oynatma listesindeki ilk videonun oynatılmaya başlayacağı zamanı belirtir.startSeconds
değeri belirtipseekTo()
çağrısı yaparsanız oynatıcı,seekTo()
çağrısında belirtilen zamandan itibaren oynatılır. Bir oynatma listesini işaretleyipplayVideoAt()
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ı ve15 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ğerlerplaylist
veuser_uploads
değerleridir. Desteği sonlandırılansearch
değeri,15 Kasım 2020 itibarıyla artık desteklenmeyecektir. Varsayılan değerplaylist
değeridir. -
Gerekli
list
özelliği, YouTube'un döndürmesi gereken video listesini tanımlayan bir anahtar içerir.listType
özelliğinin değeriplaylist
iselist
özelliği, oynatma listesi kimliğini veya video kimlikleri dizisini belirtir. YouTube Data API'de,playlist
kaynağınınid
özelliği bir oynatma listesinin kimliğini tanımlar vevideo
kaynağınınid
özelliği bir video kimliğini belirtir.listType
özelliğinin değeriuser_uploads
iselist
özelliği, yüklenen videoları döndürülecek kullanıcıyı tanımlar.listType
özelliğinin değerisearch
iselist
özelliği arama sorgusunu belirtir. Not: Bu işlev kullanımdan kaldırılmıştır ve15 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ğeri0
ş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 veplayVideo()
işlevi çağrıldığında, listedeki ilk videonun oynatılmaya başlayacağı zamanı belirtir.startSeconds
değeri belirtipseekTo()
çağrısı yaparsanız oynatıcı,seekTo()
çağrısında belirtilen zamandan itibaren oynatılır. Bir listeyi işaretleyipplayVideoAt()
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ınid
ö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ğeri0
ş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 ve15 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ğerlerplaylist
veuser_uploads
değerleridir. Desteği sonlandırılansearch
değeri,15 Kasım 2020 itibarıyla artık desteklenmeyecektir. Varsayılan değerplaylist
değeridir. -
Gerekli
list
özelliği, YouTube'un döndürmesi gereken video listesini tanımlayan bir anahtar içerir.listType
özelliğinin değeriplaylist
iselist
özelliği, oynatma listesi kimliğini veya video kimlikleri dizisi belirtir. YouTube Data API'de,playlist
kaynağınınid
özelliği bir oynatma listesi kimliğini belirtir vevideo
kaynağınınid
özelliği de bir video kimliğini belirtir.listType
özelliğinin değeriuser_uploads
iselist
özelliği, yüklenen videoları döndürülecek kullanıcıyı tanımlar.listType
özelliğinin değerisearch
iselist
özelliği arama sorgusunu belirtir. Not: Bu işlev kullanımdan kaldırılmıştır ve15 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ğeri0
ş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ı durumupaused
(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 öncestopVideo
öğesini çağırmadan sıraya ekleme işlevlerinden birini çağırabilirsiniz.
Önemli: Oynatıcıyıpaused
(2
) durumunda bırakanpauseVideo
işlevinden farklı olarakstopVideo
işlevi, oynatıcıyıended
(0
),paused
(2
),video cued
(5
) veyaunstarted
(-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ığındatrue
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ğitrue
değerine ayarlanırsa bu işlev,fov
özelliğinin doğru değeri içerdiği ve diğer özelliklerin0
olarak ayarlandığı bir nesne döndürür.
Ö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:- 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ışı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çinyaw
,pitch
veroll
özelliklerini etkilemez. Daha fazla bilgi 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 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çinyaw
,pitch
veroll
özelliklerini ayarlamak üzere yalnızca cihazın hareketlerine güvenir. Ancakfov
özelliği API aracılığıyla hâlâ değiştirilebilir. Mobil cihazlardafov
ö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
vefov
ö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ığı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 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ğilsefalse
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 düzeyini döndürür (
0
ile100
arasında bir tam sayı). Oynatıcının sesi kapalı olsa bilegetVolume()
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
ve2
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şirseonPlaybackRateChange
etkinliği tetiklenir ve kodunuzsetPlaybackRate
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ğeri1
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şlevinitrue
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
ile1
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ılangetVideoBytesLoaded
vegetVideoBytesTotal
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 erdi1
- oynatılıyor2
- duraklatıldı3
– arabelleğe alınıyor5
- 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
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ı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 zaman1000
değerini döndürür.getVideoBytesLoaded
değerinigetVideoBytesTotal
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 kadar0
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 isegetDuration()
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ızgetPlaylist()
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
veonAutoplayBlocked
etkinliklerinin birdata
ö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 birtarget
ö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ğ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, 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).
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ğ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 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 oynatma hızı gerçekten değişirse bu etkinlik 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ızca açık birsetPlaybackRate
çağrısı sonucunda değişeceğini varsaymamalıdır.
API'nin etkinlik işleyici işlevine aktardığı etkinlik nesnesinindata
ö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 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, 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ızca101
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şleyencaptions
modülüdür. BironApiChange
etkinliği aldıktan sonra, uygulamanızcaptions
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
ve3
. Varsayılan boyut0
, 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ğeritrue
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:
autoplay
parametresiloadPlaylist
işleviloadVideoById
işleviloadVideoByUrl
işleviplayVideo
işlevi
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ınsrc
URL'sininenablejsapi
parametresini1
olarak ayarlaması veya<iframe>
öğesininenablejsapi
özelliğinintrue
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ç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 ö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 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.