Cara Menyematkan Video HLS di Situs Web Anda (iframe dan hls.js)

HLS (HTTP Live Streaming) adalah format yang kini dipakai sebagian besar situs web untuk video sesuai permintaan. Alih-alih satu file MP4 yang sangat besar, video dijelaskan oleh playlist teks kecil yang menunjuk ke beberapa versi video yang sama, masing-masing dipotong menjadi segmen-segmen pendek. Pemutar mengunduh beberapa segmen di depan, mengukur seberapa cepat segmen itu tiba, dan berpindah antarversi secara langsung. Penonton dengan koneksi ponsel mendapat versi ringan, penonton dengan fiber mendapat versi yang tajam, dan tidak ada yang perlu menunggu seluruh file terunduh sebelum frame pertama muncul.

Panduan ini menunjukkan dua cara menampilkan video HLS dari UFOLOAD di halaman web Anda sendiri: pemutar siap pakai dalam iframe, yang hanya butuh sekitar satu menit, dan elemen <video> Anda sendiri yang digerakkan oleh hls.js, yang memberi Anda kendali penuh atas halaman. Keduanya memakai stream yang sama, sehingga Anda dapat memulai dengan iframe dan beralih ke hls.js nanti tanpa mengunggah ulang apa pun.

Seperti apa stream HLS dari UFOLOAD

Setelah Anda mengunggah file, konverter meng-encode-nya dengan video H.264 dan audio stereo AAC menjadi satu hingga empat versi (rendisi): 360p, 720p, 1080p, dan 2160p (4K). Sebuah versi tidak pernah lebih besar dari sumber Anda, sehingga unggahan 720p menghasilkan 720p dan 360p, tidak pernah 1080p hasil upscaling. Versi tertinggi yang benar-benar Anda dapatkan juga bergantung pada paket Anda; halaman harga mencantumkan batas terkini. Jika Anda ingin latar belakang lengkap tentang cara tingkat-tingkat itu dipilih, baca penjelasan tangga bitrate adaptif.

Setiap versi disimpan sebagai MP4 biasa dengan indeks di awal file. Saat penonton mulai memutar, lapisan penyimpanan mengemas file MP4 tersebut menjadi HLS secara langsung: master playlist (master.m3u8) mencantumkan setiap versi beserta bandwidth puncak, resolusi, dan codec-nya, dan setiap versi memiliki playlist sendiri berisi segmen empat detik. Keyframe ditempatkan sejajar dengan batas segmen, dan itulah yang memungkinkan pemutar berganti kualitas dengan mulus di tengah video.

Playlist dan segmen disajikan dari node cache dengan header Access-Control-Allow-Origin: *, sehingga pemutar yang berjalan di domain Anda dapat memintanya secara langsung. Setiap URL bertanda tangan dan memiliki waktu kedaluwarsa, yang akan penting nanti saat kita membahas pendekatan hls.js.

Langkah 1: unggah video dan tunggu hingga siap

Unggah dari dasbor dengan menyeret file atau menempelkan tautan langsung, atau gunakan FTP, WebDAV, atau API (lihat mengunggah video lewat API untuk contoh curl, Python, dan Node.js). File melewati status uploading, queued, processing, dan ready; failed dilaporkan beserta alasannya dan dapat dicoba ulang dari dasbor. Klip pendek siap dalam hitungan menit, film panjang butuh waktu lebih lama, dan paket berbayar memiliki antrean encoding prioritas.

Anda tidak harus menunggu hingga halaman selesai. Jika seseorang membuka pemutar saat file masih diproses, pemutar menampilkan pemberitahuan pemrosesan beserta progresnya dan otomatis beralih ke video begitu pemrosesan selesai. Meski begitu, pastikan statusnya ready sebelum Anda memublikasikan halaman, agar pengunjung pertama tidak disambut bilah progres.

Anda memerlukan pengenal video. Dasbor menampilkannya di panel berbagi, dan API mengembalikannya sebagai public_id, kode pendek 11 karakter. Kode itulah yang dimasukkan ke alamat sematan.

Langkah 2: sematkan pemutar dengan iframe

Dasbor memberikan potongan kode iframe segera setelah unggahan dan di panel berbagi setiap video. Bentuknya seperti blok pertama di bawah. Ganti VIDEO_ID dengan pengenal video Anda. Halaman pemutar itu sendiri tidak diindeks oleh mesin pencari, dan memang itu yang Anda inginkan untuk sematan: halaman Anda yang mendapat peringkat, bukan frame pemutarnya.

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

Ukuran piksel tetap akan berantakan di ponsel. Untuk halaman responsif, bungkus iframe dalam kotak yang mempertahankan rasio 16:9 dan biarkan frame mengisinya. Pemutar mengisi seluruh frame, sehingga video menyesuaikan ukuran dengan rapi.

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

Parameter yang dapat ditambahkan ke alamat

• autoplay=1 memulai pemutaran saat pemutar dimuat. Browser memblokir autoplay bersuara dalam sebagian besar kasus, jadi gabungkan dengan mute=1.
• mute=1 memulai video tanpa suara; penonton dapat menyalakan suara kapan saja.
• loop=1 memutar ulang video dari awal saat selesai.
• t=30 memulai pemutaran dari detik ke-30, berguna untuk tautan langsung ke momen tertentu dalam video yang lebih panjang.

Parameter di alamat selalu mengalahkan pengaturan yang sama di Studio pemutar. Gunakan Studio pemutar untuk pengaturan bawaan yang berlaku di mana-mana, seperti skin, warna aksen, logo, dan tata letak tombol, dan gunakan parameter ketika satu halaman perlu berperilaku berbeda. Anda bahkan dapat menyimpan profil pemutar terpisah untuk setiap domain sematan.

Langkah 3 (opsional): putar stream dengan hls.js

iframe adalah jalur terpendek, tetapi terkadang Anda menginginkan markup sendiri: bilah kontrol kustom, video di dalam carousel, peristiwa analitik dari kode Anda sendiri. Untuk itu Anda membutuhkan alamat playlist dan pustaka pemutar. Browser selain Safari tidak dapat memutar HLS secara native, sehingga pilihan yang umum adalah hls.js, pustaka JavaScript yang memasukkan segmen HLS ke elemen <video> standar. Safari dan iOS memutar HLS secara native dan tidak memerlukannya.

Alamat playlist adalah field links.playback pada objek video. Mintalah dari server Anda dengan kunci API, karena kunci tidak boleh muncul di kode browser. Panggilan yang sama mengembalikan links.expires_at, dan tautan bertanda tangan serta berbatas waktu, jadi mintalah tautan baru setiap kali Anda merender halaman alih-alih menyimpannya di basis data.

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
}

Jika Anda memerlukan masa berlaku selain bawaan, POST /files/{id}/links menerima ttl dari 60 detik hingga 30 hari dan dapat mengikat tautan ke alamat IP atau cookie. Dokumentasi API membahasnya secara lengkap. Ada juga endpoint publik, GET /api/v1/public/files/{id}, yang tidak memerlukan kunci; halaman tontonan dan sematan memakainya, dan tautannya berlaku selama enam jam.

Di halaman, buat pemutarnya. Blok di bawah memakai hls.js jika didukung, beralih ke pemutaran native di Safari, dan menampilkan pesan sederhana jika keduanya tidak tersedia. Hosting sendiri file pustakanya atau kunci versinya, alih-alih memuat versi terbaru apa pun.

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

Objek video juga memuat links.poster untuk gambar sampul dan links.sprite untuk thumbnail pratinjau saat kursor diarahkan, yang dapat Anda pakai jika membangun bilah pencarian sendiri. Dengan hls.js Anda melepaskan hal-hal yang dikerjakan pemutar UFOLOAD untuk Anda: menu kualitas, bab, pilihan subtitle, overlay logo, dan, saat iklan tersedia, iklan. Itulah kompromi yang sebenarnya, dan tabel di bawah merangkumnya.

iframe atau hls.js: mana yang dipakai

Daftar periksa pemecahan masalah

• Frame hitam atau ikon memuat tanpa henti. Buka panel jaringan browser dan cari master.m3u8. Kode 403 berarti tautan sudah kedaluwarsa atau penonton diblokir oleh aturan negara atau IP; minta tautan baru.
• Diblokir browser di halaman HTTPS. Semuanya harus HTTPS. Jangan pernah menempelkan alamat http:// ke iframe atau ke hls.js.
• Autoplay tidak berfungsi. Autoplay bersuara diblokir oleh browser. Tambahkan mute=1, atau di hls.js setel video.muted = true sebelum memanggil play().
• Pemberitahuan pemrosesan alih-alih video. File belum siap. Lakukan polling GET /files/{id} hingga status bernilai ready.
• Hanya kualitas rendah yang diputar. Pemutar memulai dengan hati-hati dan naik begitu throughput selesai diukur. Paket dan sumber Anda juga membatasi versi teratas; bandingkan dengan halaman harga dan fitur.

Setelah halaman Anda berfungsi, Anda mungkin ingin melindunginya dari hotlinking atau, saat iklan tersedia, memperoleh pendapatan darinya. Keduanya dibahas dalam panduan berikutnya: batasi tempat video Anda dapat disematkan dan monetisasi situs video Anda dengan iklan di pemutar. Jika Anda masih menimbang tempat hosting, daftar periksa hosting video mencantumkan hal-hal yang perlu dibandingkan.