Jak vložit video HLS na web (iframe a hls.js)

HLS (HTTP Live Streaming) je formát, který dnes většina webů používá pro video na vyžádání. Místo jednoho obrovského souboru MP4 popisuje video malý textový playlist, který odkazuje na několik verzí téhož videa, z nichž každá je rozdělena na krátké segmenty. Přehrávač stahuje několik segmentů dopředu, měří, jak rychle přicházejí, a za běhu přepíná mezi verzemi. Diváci na mobilním připojení dostanou lehkou verzi, diváci na optice tu ostrou a nikdo nečeká na stažení celého souboru, než se objeví první snímek.

Tento návod ukazuje dva způsoby, jak umístit video HLS z UFOLOAD na vlastní webovou stránku: hotový přehrávač v iframe, což zabere asi minutu, a vlastní prvek <video> řízený knihovnou hls.js, který vám dává plnou kontrolu nad stránkou. Oba používají stejný stream, takže můžete začít s iframe a později přejít na hls.js, aniž byste cokoli nahrávali znovu.

Jak vypadá stream HLS z UFOLOAD

Po nahrání souboru ho převodník zakóduje s videem H.264 a stereo zvukem AAC do jedné až čtyř verzí: 360p, 720p, 1080p a 2160p (4K). Verze nikdy není větší než zdroj, takže nahrání v 720p vytvoří 720p a 360p, nikdy zvětšené 1080p. Nejvyšší verze, kterou skutečně dostanete, závisí také na vašem tarifu; aktuální limity uvádí stránka Ceník. Pokud chcete vědět vše o tom, jak se stupně volí, přečtěte si článek žebříčky adaptivního datového toku.

Každá verze je uložena jako běžný soubor MP4 s indexem na začátku souboru. Když divák spustí přehrávání, vrstva úložiště tyto soubory MP4 za běhu zabalí do HLS: hlavní playlist (master.m3u8) uvádí každou verzi s její špičkovou šířkou pásma, rozlišením a kodeky a každá verze má vlastní playlist čtyřsekundových segmentů. Klíčové snímky jsou umístěny tak, aby lícovaly s hranicemi segmentů, a právě díky tomu může přehrávač čistě přepnout kvalitu uprostřed videa.

Playlist i segmenty se doručují z uzlů mezipaměti s hlavičkou Access-Control-Allow-Origin: *, takže přehrávač běžící na vaší doméně si je může vyžádat přímo. Každá adresa URL je podepsaná a má dobu platnosti, což bude důležité později, až se dostaneme k přístupu s hls.js.

Krok 1: nahrajte video a počkejte, až bude připravené

Nahrajte soubor v panelu přetažením nebo vložením přímého odkazu, případně použijte FTP, WebDAV nebo API (příklady v curl, Python a Node.js najdete v článku nahrávání videí přes API). Soubor prochází stavy uploading, queued, processing a ready; stav failed se hlásí s důvodem a nahrání lze z panelu zopakovat. Krátké klipy jsou připravené během několika minut, dlouhé filmy trvají déle a placené tarify mají prioritní frontu kódování.

Na dokončení stránky čekat nemusíte. Pokud někdo otevře přehrávač, zatímco se soubor ještě zpracovává, zobrazí se oznámení o zpracování s průběhem a po dokončení se přehrávač sám přepne na video. Přesto před zveřejněním stránky ověřte, že je stav ready, abyste nevydali stránku, jejíž první návštěvníci uvidí ukazatel průběhu.

Budete potřebovat identifikátor videa. Panel ho zobrazuje v panelu sdílení a API ho vrací jako public_id, krátký kód o 11 znacích. Právě tento kód patří do adresy pro vložení.

Krok 2: vložte přehrávač pomocí iframe

Panel nabízí úryvek kódu s iframe hned po nahrání a v panelu sdílení každého videa. Vypadá jako první blok níže. Nahraďte VIDEO_ID identifikátorem svého videa. Samotnou stránku přehrávače vyhledávače neindexují, což je pro vložení přesně to, co chcete: ve výsledcích se umisťuje vaše stránka, ne rám přehrávače.

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

Pevné rozměry v pixelech se na telefonech rozbijí. Pro responzivní stránku zabalte iframe do kontejneru, který drží poměr 16:9, a nechte rám, ať ho vyplní. Přehrávač vyplní celý rám, takže se video čistě přizpůsobí.

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

Parametry, které můžete přidat do adresy

• autoplay=1 spustí přehrávání po načtení přehrávače. Prohlížeče ve většině případů blokují automatické přehrávání se zvukem, proto ho kombinujte s mute=1.
• mute=1 spustí video ztlumené; divák může zvuk kdykoli zapnout.
• loop=1 spustí video po skončení znovu od začátku.
• t=30 spustí přehrávání od 30. sekundy, což se hodí pro přímé odkazy na určitý okamžik v delším videu.

Parametr v adrese má vždy přednost před stejným nastavením ve studiu přehrávače. Studio přehrávače použijte pro výchozí nastavení, která platí všude, jako je vzhled, barva zvýraznění, logo a rozložení tlačítek, a parametry použijte, když se jedna stránka má chovat jinak. Pro každou doménu, na které video vkládáte, můžete mít dokonce samostatný profil přehrávače.

Krok 3 (volitelný): přehrávejte stream pomocí hls.js

Iframe je nejkratší cesta, ale někdy chcete vlastní kód: vlastní ovládací lištu, video uvnitř karuselu, analytické události z vlastního kódu. Pak potřebujete adresu playlistu a knihovnu přehrávače. Jiné prohlížeče než Safari neumí HLS přehrávat nativně, takže obvyklou volbou je hls.js, knihovna JavaScriptu, která předává segmenty HLS standardnímu prvku <video>. Safari a iOS přehrávají HLS nativně a knihovnu nepotřebují.

Adresa playlistu je pole links.playback objektu videa. Vyžádejte si ji ze svého serveru pomocí klíče API, protože klíč se nikdy nesmí objevit v kódu v prohlížeči. Stejné volání vrací links.expires_at a odkazy jsou podepsané a časově omezené, takže si při každém vykreslení stránky vyžádejte nový odkaz, místo abyste ho ukládali do databáze.

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
}

Pokud potřebujete jinou platnost než výchozí, POST /files/{id}/links přijímá ttl od 60 sekund do 30 dnů a umí odkaz svázat s adresou IP nebo cookie. Podrobně to popisuje dokumentace API. K dispozici je také veřejný endpoint GET /api/v1/public/files/{id}, který nepotřebuje klíč; používají ho stránky pro sledování a vložení a jeho odkazy platí šest hodin.

Na stránce vytvořte přehrávač. Blok níže používá hls.js tam, kde je podporováno, v Safari přejde na nativní přehrávání a jinak zobrazí prostou zprávu. Soubor knihovny hostujte sami nebo připněte konkrétní verzi, místo abyste načítali tu nejnovější, ať je jakákoli.

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

Objekt videa obsahuje také links.poster pro titulní obrázek a links.sprite pro náhledy při najetí myší, které můžete použít, pokud si stavíte vlastní posuvník. S hls.js se vzdáváte toho, co za vás dělá přehrávač UFOLOAD: nabídky kvality, kapitol, výběru titulků, překryvného loga a, pokud jsou reklamy dostupné, i reklam. To je skutečný kompromis a tabulka níže ho shrnuje.

iframe, nebo hls.js: co použít

Kontrolní seznam při potížích

• Černý obraz nebo nekonečné kolečko. Otevřete v prohlížeči panel sítě a hledejte master.m3u8. Kód 403 znamená, že odkaz vypršel nebo je divák blokován pravidlem pro zemi či IP; vyžádejte si nový odkaz.
• Prohlížeč blokuje obsah na stránce HTTPS. Vše musí běžet přes HTTPS. Nikdy nevkládejte adresu http:// do iframe ani do hls.js.
• Automatické přehrávání nic nedělá. Prohlížeče blokují automatické přehrávání se zvukem. Přidejte mute=1, nebo v hls.js nastavte video.muted = true před voláním play().
• Místo videa oznámení o zpracování. Soubor ještě není připravený. Dotazujte se na GET /files/{id}, dokud status nebude ready.
• Přehrává se jen nízká kvalita. Přehrávač začíná opatrně a jakmile změří propustnost, kvalitu zvýší. Nejvyšší verzi omezuje také váš tarif a zdroj; porovnejte s ceníkem a stránkou Funkce.

Jakmile vaše stránka funguje, možná ji budete chtít chránit před hotlinkingem nebo na ní, pokud jsou reklamy dostupné, vydělávat. Obojí pokrývají další návody: omezte, kde lze vaše video vložit a monetizujte svůj videoweb reklamami v přehrávači. Pokud se teprve rozhodujete, kde hostovat, kontrolní seznam pro výběr videohostingu uvádí, co porovnávat.