Web Sitenize HLS Video Nasıl Yerleştirilir (iframe ve hls.js)

HLS (HTTP Live Streaming), bugün web sitelerinin çoğunun isteğe bağlı video için kullandığı formattır. Tek bir devasa MP4 dosyası yerine video, aynı videonun birkaç sürümünü gösteren küçük bir metin oynatma listesiyle tanımlanır; her sürüm kısa parçalara (segmentlere) bölünmüştür. Oynatıcı birkaç segmenti önceden indirir, ne kadar hızlı geldiklerini ölçer ve sürümler arasında anında geçiş yapar. Mobil bağlantıdaki izleyiciler hafif sürümü, fiber bağlantıdakiler ise net sürümü alır ve ilk kare görünmeden önce kimse dosyanın tamamının inmesini beklemez.

Bu rehber, UFOLOAD'daki bir HLS videoyu kendi web sayfanıza koymanın iki yolunu gösteriyor: yaklaşık bir dakika süren, iframe içindeki hazır oynatıcı ve sayfa üzerinde tam kontrol sağlayan, hls.js ile çalışan kendi <video> öğeniz. İkisi de aynı yayını kullanır; yani iframe ile başlayıp daha sonra hiçbir şeyi yeniden yüklemeden hls.js'e geçebilirsiniz.

UFOLOAD'dan gelen bir HLS yayını nasıl görünür

Bir dosya yükledikten sonra dönüştürücü onu H.264 video ve AAC stereo ses ile bir ila dört sürüme (rendition) kodlar: 360p, 720p, 1080p ve 2160p (4K). Bir sürüm hiçbir zaman kaynağınızdan büyük olmaz; 720p bir yükleme 720p ve 360p üretir, asla büyütülmüş bir 1080p üretmez. Gerçekte alacağınız en yüksek sürüm planınıza da bağlıdır; güncel limitler fiyatlandırma sayfasında listelenir. Basamakların nasıl seçildiğine dair ayrıntılı bilgi için uyarlanabilir bitrate merdivenleri rehberini okuyun.

Her sürüm, indeksi dosyanın başında olan normal bir MP4 olarak saklanır. Bir izleyici oynatmayı başlattığında depolama katmanı bu MP4 dosyalarını anında HLS olarak paketler: ana oynatma listesi (master.m3u8) her sürümü tepe bant genişliği, çözünürlüğü ve codec'leriyle listeler; her sürümün de dört saniyelik segmentlerden oluşan kendi oynatma listesi vardır. Anahtar kareler segment sınırlarıyla hizalanacak şekilde yerleştirilir; oynatıcının videonun ortasında kaliteyi sorunsuz değiştirebilmesini sağlayan da budur.

Oynatma listesi ve segmentler, Access-Control-Allow-Origin: * başlığıyla önbellek düğümlerinden sunulur; böylece alan adınızda çalışan bir oynatıcı bunları doğrudan isteyebilir. Her URL imzalıdır ve bir son kullanma süresi vardır; bu, ileride hls.js yaklaşımından bahsederken önem kazanacak.

Adım 1: videoyu yükleyin ve hazır olmasını bekleyin

Kontrol panelinden dosyayı sürükleyip bırakarak veya doğrudan bir bağlantı yapıştırarak yükleyin ya da FTP, WebDAV veya API kullanın (curl, Python ve Node.js örnekleri için API ile video yükleme yazısına bakın). Bir dosya sırasıyla uploading, queued, processing ve ready durumlarından geçer; failed durumu bir nedenle birlikte bildirilir ve kontrol panelinden yeniden denenebilir. Kısa klipler birkaç dakika içinde hazır olur, uzun filmler daha uzun sürer; ücretli planlarda öncelikli bir kodlama kuyruğu vardır.

Sayfanın tamamlanmasını beklemeniz gerekmez. Dosya hâlâ işlenirken biri oynatıcıyı açarsa, oynatıcı ilerlemeyle birlikte bir işleme bildirimi gösterir ve işlem bitince kendiliğinden videoya geçer. Yine de ilk ziyaretçilerin bir ilerleme çubuğu görmemesi için sayfayı yayınlamadan önce durumun ready olduğunu kontrol edin.

Videonun kimliğine ihtiyacınız olacak. Kontrol paneli bunu paylaşım panelinde gösterir, API ise 11 karakterlik kısa bir kod olan public_id olarak döndürür. Yerleştirme adresine giren de bu koddur.

Adım 2: oynatıcıyı iframe ile yerleştirin

Kontrol paneli, yüklemenin hemen ardından ve her videonun paylaşım panelinde bir iframe kodu verir. Aşağıdaki ilk bloğa benzer. VIDEO_ID değerini videonuzun kimliğiyle değiştirin. Oynatıcı sayfasının kendisi arama motorlarınca dizine eklenmez; bir yerleştirme için istediğiniz de budur: sıralamaya oynatıcı çerçevesi değil, sizin sayfanız girer.

<iframe width="640" height="360"
  src="https://iframe.andromedans.live/e/VIDEO_ID"
  title="My video"
  frameborder="0"
  allow="autoplay; fullscreen; picture-in-picture"
  allowfullscreen></iframe>

Sabit piksel boyutları telefonlarda bozulur. Duyarlı bir sayfa için iframe'i 16:9 oranını koruyan bir kutuya sarın ve çerçevenin kutuyu doldurmasını sağlayın. Oynatıcı tüm çerçeveyi kapladığı için video düzgün ölçeklenir.

<div style="position:relative;aspect-ratio:16/9;max-width:960px">
  <iframe src="https://iframe.andromedans.live/e/VIDEO_ID"
    title="My video"
    style="position:absolute;inset:0;width:100%;height:100%;border:0"
    loading="lazy"
    allow="autoplay; fullscreen; picture-in-picture"
    allowfullscreen></iframe>
</div>

Adrese ekleyebileceğiniz parametreler

• autoplay=1 oynatıcı yüklendiğinde oynatmayı başlatır. Tarayıcılar sesli otomatik oynatmayı çoğu durumda engeller, bu yüzden mute=1 ile birlikte kullanın.
• mute=1 videoyu sessiz başlatır; izleyici sesi istediği an açabilir.
• loop=1 video bittiğinde onu baştan başlatır.
• t=30 oynatmayı 30. saniyeden başlatır; uzun bir videodaki belirli bir ana doğrudan bağlantı vermek için kullanışlıdır.

Adresteki bir parametre, Player studio'daki aynı ayara her zaman üstün gelir. Görünüm, vurgu rengi, logo ve düğme düzeni gibi her yerde geçerli varsayılanlar için Player studio'yu, tek bir sayfanın farklı davranması gerektiğinde ise parametreleri kullanın. Hatta yerleştirme yapılan her alan adı için ayrı bir oynatıcı profili de tutabilirsiniz.

Adım 3 (isteğe bağlı): yayını hls.js ile oynatın

iframe en kısa yoldur, ancak bazen kendi işaretlemenizi istersiniz: özel bir kontrol çubuğu, bir karusel içindeki video, kendi kodunuzdan gelen analitik olayları. O zaman oynatma listesi adresine ve bir oynatıcı kütüphanesine ihtiyacınız olur. Safari dışındaki tarayıcılar HLS'i yerel olarak oynatamaz, bu yüzden olağan tercih HLS segmentlerini standart bir <video> öğesine aktaran JavaScript kütüphanesi hls.js olur. Safari ve iOS HLS'i yerel olarak oynatır ve buna ihtiyaç duymaz.

Oynatma listesi adresi, video nesnesindeki links.playback alanıdır. Bunu sunucunuzdan bir API anahtarıyla isteyin, çünkü anahtar asla tarayıcı kodunda görünmemelidir. Aynı çağrı links.expires_at değerini de döndürür; bağlantılar imzalı ve süre sınırlı olduğundan, bir bağlantıyı veritabanınızda saklamak yerine sayfayı her oluşturduğunuzda yeni bir bağlantı isteyin.

const BASE = 'https://ufoload.com/api/v1'

export async function playbackUrl(fileId) {
  const res = await fetch(`${BASE}/files/${fileId}`, {
    headers: { Authorization: `Bearer ${process.env.UFOLOAD_API_KEY}` },
  })
  if (!res.ok) throw new Error(`UFOLOAD API: ${res.status}`)
  const { file, links } = await res.json()
  if (file.status !== 'ready') return null // still processing
  return links.playback // signed master.m3u8 URL
}

Varsayılandan farklı bir geçerlilik süresine ihtiyacınız varsa, POST /files/{id}/links 60 saniyeden 30 güne kadar bir ttl kabul eder ve bağlantıyı bir IP adresine veya bir çereze bağlayabilir. API belgeleri bunu ayrıntılı olarak anlatır. Anahtar gerektirmeyen herkese açık bir uç nokta da vardır: GET /api/v1/public/files/{id}; izleme ve yerleştirme sayfaları bunu kullanır ve bağlantıları altı saat geçerlidir.

Sayfada oynatıcıyı oluşturun. Aşağıdaki blok, desteklendiği yerde hls.js kullanır, Safari'de yerel oynatmaya geri döner, aksi halde düz bir mesaj gösterir. Kütüphane dosyasını kendiniz barındırın ya da en son sürüm ne ise onu yüklemek yerine bir sürümü sabitleyin.

<video id="player" controls playsinline preload="metadata"
       poster="POSTER_URL" style="width:100%;aspect-ratio:16/9;background:#000"></video>
<script src="/vendor/hls.min.js"></script>
<script>
  const video = document.getElementById('player')
  const src = 'PLAYLIST_URL_FROM_YOUR_SERVER'

  if (window.Hls && Hls.isSupported()) {
    const hls = new Hls()
    hls.loadSource(src)
    hls.attachMedia(video)
    hls.on(Hls.Events.ERROR, (_, data) => {
      if (!data.fatal) return
      if (data.type === Hls.ErrorTypes.NETWORK_ERROR) hls.startLoad()
      else if (data.type === Hls.ErrorTypes.MEDIA_ERROR) hls.recoverMediaError()
      else hls.destroy()
    })
  } else if (video.canPlayType('application/vnd.apple.mpegurl')) {
    video.src = src // Safari, iOS
  } else {
    video.outerHTML = '<p>This browser cannot play HLS video.</p>'
  }
</script>

Video nesnesi ayrıca kapak görseli için links.poster ve üzerine gelindiğinde gösterilen önizleme küçük resimleri için links.sprite alanlarını da taşır; kendi ilerleme çubuğunuzu yaparsanız bunları kullanabilirsiniz. hls.js ile UFOLOAD oynatıcısının sizin için yaptığı şeylerden vazgeçersiniz: kalite menüsü, bölümler, altyazı seçimi, logo katmanı ve reklamlar kullanılabilir olduğunda reklamlar. Asıl ödünleşim budur ve aşağıdaki tablo bunu özetliyor.

iframe mi hls.js mi: hangisini kullanmalı

Sorun giderme kontrol listesi

• Siyah kare veya bitmeyen yükleme simgesi. Tarayıcının ağ panelini açın ve master.m3u8 isteğini arayın. 403, bağlantının süresinin dolduğu ya da izleyicinin bir ülke veya IP kuralıyla engellendiği anlamına gelir; yeni bir bağlantı isteyin.
• HTTPS sayfasında tarayıcı tarafından engelleniyor. Her şey HTTPS olmalıdır. iframe'e veya hls.js'e asla http:// ile başlayan bir adres yapıştırmayın.
• Otomatik oynatma çalışmıyor. Sesli otomatik oynatma tarayıcılar tarafından engellenir. mute=1 ekleyin ya da hls.js'te play() çağırmadan önce video.muted = true ayarlayın.
• Video yerine işleme bildirimi. Dosya henüz hazır değil. status değeri ready olana kadar GET /files/{id} ile sorgulayın.
• Yalnızca düşük kalite oynuyor. Oynatıcı temkinli başlar ve aktarım hızını ölçer ölçmez kaliteyi yükseltir. Planınız ve kaynağınız da en yüksek sürümü sınırlar; fiyatlandırma ve özellikler sayfasıyla karşılaştırın.

Sayfanız çalıştıktan sonra onu hotlink'e karşı korumak veya reklamlar kullanılabilir olduğunda ondan gelir elde etmek isteyebilirsiniz. Her ikisi de sonraki rehberlerde ele alınıyor: videonuzun nereye yerleştirilebileceğini kısıtlayın ve video sitenizden oynatıcıdaki reklamlarla para kazanın. Hâlâ nerede barındıracağınıza karar veriyorsanız, video barındırma kontrol listesi neleri karşılaştırmanız gerektiğini sıralıyor.