Ako vložiť HLS video na svoj web (iframe a hls.js)

HLS (HTTP Live Streaming) je formát, ktorý dnes väčšina webov používa pre video na požiadanie. Namiesto jedného obrovského súboru MP4 video popisuje malý textový playlist, ktorý odkazuje na niekoľko verzií toho istého videa, každú rozdelenú na krátke segmenty. Prehrávač si stiahne niekoľko segmentov dopredu, zmeria, ako rýchlo prichádzajú, a za chodu prepína medzi verziami. Diváci na mobilnom pripojení dostanú ľahkú verziu, diváci na optike ostrú a nikto nečaká na stiahnutie celého súboru, kým sa objaví prvý snímok.

Tento návod ukazuje dva spôsoby, ako umiestniť HLS video z UFOLOAD na vlastnú webovú stránku: hotový prehrávač v iframe, čo trvá asi minútu, a vlastný prvok <video> riadený knižnicou hls.js, ktorý vám dáva plnú kontrolu nad stránkou. Oba používajú ten istý stream, takže môžete začať s iframe a neskôr prejsť na hls.js bez opätovného nahrávania.

Ako vyzerá HLS stream z UFOLOAD

Po nahratí súboru ho konvertor zakóduje s videom H.264 a stereo zvukom AAC do jednej až štyroch verzií: 360p, 720p, 1080p a 2160p (4K). Verzia nikdy nie je väčšia ako váš zdroj, takže z nahratia v 720p vznikne 720p a 360p, nikdy nie zväčšené 1080p. Najvyššia verzia, ktorú naozaj dostanete, závisí aj od plánu; aktuálne limity uvádza stránka Cenník. Ak chcete podrobné pozadie toho, ako sa stupne vyberajú, prečítajte si článok adaptívne rebríky dátového toku.

Každá verzia sa ukladá ako bežné MP4 s indexom na začiatku súboru. Keď divák spustí prehrávanie, vrstva úložiska tieto súbory MP4 za chodu zabalí do HLS: hlavný playlist (master.m3u8) uvádza každú verziu s jej špičkovým dátovým tokom, rozlíšením a kodekmi a každá verzia má vlastný playlist štvorsekundových segmentov. Kľúčové snímky sú umiestnené tak, aby sa zhodovali s hranicami segmentov, a práve vďaka tomu môže prehrávač čisto prepnúť kvalitu uprostred videa.

Playlist aj segmenty sa doručujú z cache uzlov s hlavičkou Access-Control-Allow-Origin: *, takže prehrávač bežiaci na vašej doméne si ich môže vyžiadať priamo. Každá URL je podpísaná a má čas platnosti, čo bude dôležité neskôr pri prístupe s hls.js.

Krok 1: nahrajte video a počkajte, kým bude pripravené

Nahrávajte z prehľadu pretiahnutím súboru alebo vložením priameho odkazu, prípadne cez FTP, WebDAV alebo API (príklady v curl, Python a Node.js nájdete v článku nahrávanie videí cez API). Súbor prechádza stavmi uploading, queued, processing a ready; stav failed sa hlási s dôvodom a v prehľade ho možno skúsiť znova. Krátke klipy sú hotové do niekoľkých minút, dlhé filmy trvajú dlhšie a platené plány majú prioritný front kódovania.

Na dokončenie spracovania nemusíte čakať. Ak niekto otvorí prehrávač, kým sa súbor ešte spracúva, zobrazí sa oznámenie o spracovaní s priebehom a po dokončení sa prehrávač sám prepne na video. Napriek tomu pred zverejnením stránky skontrolujte, že stav je ready, aby prví návštevníci nevideli ukazovateľ priebehu.

Budete potrebovať identifikátor videa. Prehľad ho zobrazuje v paneli zdieľania a API ho vracia ako public_id, krátky kód s 11 znakmi. Práve tento kód patrí do adresy vloženia.

Krok 2: vložte prehrávač cez iframe

Prehľad vám dá kód iframe hneď po nahratí a aj v paneli zdieľania každého videa. Vyzerá ako prvý blok nižšie. VIDEO_ID nahraďte identifikátorom svojho videa. Samotnú stránku prehrávača vyhľadávače neindexujú, čo je pri vkladaní žiaduce: vo výsledkoch sa umiestňuje vaša stránka, nie rám prehrávača.

<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é rozmery v pixeloch sa na telefónoch rozbijú. Na responzívnej stránke obaľte iframe do boxu, ktorý drží pomer 16:9, a nechajte rám, nech ho vyplní. Prehrávač vyplní celý rám, takže sa video čisto prispô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>

Parametre, ktoré môžete pridať do adresy

• autoplay=1 spustí prehrávanie po načítaní prehrávača. Prehliadače vo väčšine prípadov blokujú automatické prehrávanie so zvukom, preto ho kombinujte s mute=1.
• mute=1 spustí video stlmené; divák môže zvuk kedykoľvek zapnúť.
• loop=1 spustí video po skončení odznova.
• t=30 začne prehrávanie od 30. sekundy, čo sa hodí na priame odkazy na konkrétny moment dlhšieho videa.

Parameter v adrese má vždy prednosť pred rovnakým nastavením v Štúdiu prehrávača. Štúdio prehrávača používajte na predvolené nastavenia platné všade, ako vzhľad, farbu zvýraznenia, logo a rozloženie tlačidiel, a parametre vtedy, keď sa jedna stránka má správať inak. Pre každú doménu vloženia si dokonca môžete ponechať samostatný profil prehrávača.

Krok 3 (voliteľný): prehrávajte stream cez hls.js

Iframe je najkratšia cesta, no niekedy chcete vlastné značky: vlastný ovládací panel, video v karuseli, analytické udalosti z vlastného kódu. Potom potrebujete adresu playlistu a knižnicu prehrávača. Prehliadače okrem Safari nevedia HLS prehrávať natívne, preto sa zvyčajne volí hls.js, knižnica JavaScriptu, ktorá posiela segmenty HLS do štandardného prvku <video>. Safari a iOS prehrávajú HLS natívne a knižnicu nepotrebujú.

Adresa playlistu je pole links.playback objektu videa. Vyžiadajte si ju zo svojho servera s kľúčom API, pretože kľúč sa nikdy nesmie objaviť v kóde prehliadača. To isté volanie vráti links.expires_at a odkazy sú podpísané a časovo obmedzené, takže si pri každom vykreslení stránky vyžiadajte nový odkaz namiesto ukladania jedného do databázy.

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
}

Ak potrebujete inú platnosť ako predvolenú, POST /files/{id}/links prijíma ttl od 60 sekúnd do 30 dní a môže odkaz viazať na IP adresu alebo cookie. Úplný popis nájdete v dokumentácii API. Existuje aj verejný endpoint GET /api/v1/public/files/{id}, ktorý nepotrebuje kľúč; používajú ho stránky na sledovanie a vloženie a jeho odkazy platia šesť hodín.

Na stránke vytvorte prehrávač. Blok nižšie používa hls.js tam, kde je podporovaná, v Safari prejde na natívne prehrávanie a inak zobrazí jednoduchú správu. Súbor knižnice hostujte sami alebo pripnite verziu namiesto načítavania tej najnovšej.

<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 aj links.poster pre obrázok obálky a links.sprite pre náhľady pri prejdení myšou, ktoré môžete využiť, ak si staviate vlastnú časovú os. S hls.js sa vzdávate toho, čo za vás robí prehrávač UFOLOAD: ponuky kvality, kapitol, výberu titulkov, prekrytia logom a, ak sú dostupné, reklám. To je skutočný kompromis a tabuľka nižšie ho zhŕňa.

Iframe alebo hls.js: čo použiť

Kontrolný zoznam pri problémoch

• Čierny obraz alebo nekonečné koliesko. Otvorte sieťový panel prehliadača a hľadajte master.m3u8. Kód 403 znamená, že odkaz vypršal alebo diváka blokuje pravidlo pre krajinu či IP; vyžiadajte si nový odkaz.
• Prehliadač blokuje obsah na stránke s HTTPS. Všetko musí bežať cez HTTPS. Nikdy nevkladajte adresu http:// do iframe ani do hls.js.
• Automatické prehrávanie nič nerobí. Prehliadače blokujú automatické prehrávanie so zvukom. Pridajte mute=1 alebo v hls.js nastavte video.muted = true pred volaním play().
• Namiesto videa oznámenie o spracovaní. Súbor ešte nie je pripravený. Dotazujte sa na GET /files/{id}, kým status nebude ready.
• Prehráva sa len nízka kvalita. Prehrávač začína opatrne a stúpa, hneď ako zmeria priepustnosť. Najvyššiu verziu obmedzuje aj váš plán a zdroj; porovnajte s cenníkom a stránkou Funkcie.

Keď vaša stránka funguje, možno ju budete chcieť chrániť pred hotlinkovaním alebo na nej, ak sú reklamy dostupné, zarábať. Obe témy pokrývajú ďalšie návody: obmedzte, kde možno vaše video vložiť a monetizujte svoj videoweb reklamami v prehrávači. Ak sa ešte rozhodujete, kde hostovať, kontrolný zoznam pre výber videohostingu uvádza, čo porovnávať.