HLS-videó beágyazása a weboldaladba (iframe és hls.js)

A HLS (HTTP Live Streaming) ma a legtöbb weboldal által használt formátum a lekérhető videókhoz. Egyetlen hatalmas MP4-fájl helyett a videót egy kis szöveges playlist írja le, amely ugyanannak a videónak több változatára mutat, mindegyiket rövid szegmensekre vágva. A lejátszó néhány szegmenssel előre letölt, méri, milyen gyorsan érkeznek, és menet közben vált a változatok között. A mobilneten nézők könnyű változatot kapnak, az optikai kapcsolaton nézők az élesebbet, és senkinek sem kell megvárnia egy teljes fájl letöltését az első képkocka előtt.

Ez az útmutató két módot mutat be arra, hogyan teheted az UFOLOAD egy HLS-videóját a saját weboldaladra: a kész lejátszót iframe-ben, ami körülbelül egy percet vesz igénybe, és egy saját, hls.js által vezérelt <video> elemet, amely teljes kontrollt ad az oldal felett. Mindkettő ugyanazt a streamet használja, így kezdheted az iframe-mel, és később áttérhetsz a hls.js-re anélkül, hogy bármit újra fel kellene töltened.

Hogyan néz ki egy UFOLOAD HLS-stream

Feltöltés után a konverter H.264 videóval és AAC sztereó hanggal egy–négy változatba, úgynevezett renditionökbe kódolja a fájlt: 360p, 720p, 1080p és 2160p (4K). Egy változat sosem nagyobb a forrásnál, így egy 720p-s feltöltésből 720p és 360p lesz, soha nem felskálázott 1080p. Hogy ténylegesen mi a legmagasabb változat, az a csomagodtól is függ; az aktuális korlátokat az Árak oldal sorolja fel. Ha részletesen érdekel, hogyan választjuk ki a szinteket, olvasd el az adaptív bitrátalétrákról szóló cikket.

Minden változatot hagyományos MP4-ként tárolunk, az indexszel a fájl elején. Amikor a néző elindítja a lejátszást, a tárolási réteg menet közben HLS-be csomagolja ezeket az MP4-fájlokat: a master playlist (master.m3u8) felsorolja az összes változatot a csúcs-sávszélességükkel, felbontásukkal és kodekjeikkel, és minden változatnak saját, négymásodperces szegmensekből álló playlistje van. A kulcskockák a szegmenshatárokhoz igazodnak – ez teszi lehetővé, hogy a lejátszó a videó közepén is tisztán váltson minőséget.

A playlistet és a szegmenseket gyorsítótár-csomópontok szolgálják ki Access-Control-Allow-Origin: * fejléccel, így a domaineden futó lejátszó közvetlenül lekérheti őket. Minden URL alá van írva, és lejárati ideje van – ez később, a hls.js-es megoldásnál lesz fontos.

1. lépés: töltsd fel a videót, és várd meg, amíg elkészül

Tölts fel a vezérlőpultról a fájl behúzásával vagy egy közvetlen link beillesztésével, vagy használd az FTP-t, a WebDAV-ot vagy az API-t (curl-, Python- és Node.js-példákat a videók API-n keresztüli feltöltéséről szóló cikkben találsz). A fájl az uploading, queued, processing és ready állapotokon halad végig; a failed állapotot indoklással jelezzük, és a vezérlőpultról újrapróbálható. A rövid klipek perceken belül elkészülnek, a hosszú filmek tovább tartanak, a fizetős csomagok pedig elsőbbségi kódolási sort kapnak.

Nem kell megvárnod, amíg a feldolgozás véget ér. Ha valaki megnyitja a lejátszót, miközben a fájl még feldolgozás alatt áll, egy feldolgozási értesítést lát a folyamat állásával, és a lejátszó magától átvált a videóra, amint a feldolgozás befejeződik. Mégis ellenőrizd, hogy az állapot ready, mielőtt közzéteszed az oldalt, nehogy az első látogatók egy folyamatjelzőt lássanak.

Szükséged lesz a videó azonosítójára. A vezérlőpult a megosztási panelen mutatja, az API pedig public_id néven adja vissza – ez egy 11 karakteres rövid kód. Ez kerül a beágyazási címbe.

2. lépés: ágyazd be a lejátszót iframe-mel

A vezérlőpult közvetlenül a feltöltés után, valamint minden videó megosztási paneljén ad egy iframe-kódrészletet. Úgy néz ki, mint az alábbi első blokk. Cseréld le a VIDEO_ID részt a videód azonosítójára. Magát a lejátszóoldalt a keresőmotorok nem indexelik, és beágyazásnál épp ez a cél: a te oldalad rangsorolódjon, ne a lejátszó kerete.

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

A rögzített pixelméretek telefonon szétesnek. Reszponzív oldalhoz tedd az iframe-et egy 16:9-es arányt tartó dobozba, és hagyd, hogy a keret kitöltse. A lejátszó a teljes keretet kitölti, így a videó szépen skálázódik.

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

A címhez adható paraméterek

• Az autoplay=1 a lejátszó betöltésekor elindítja a lejátszást. A böngészők a legtöbb esetben tiltják a hangos automatikus lejátszást, ezért használd együtt a mute=1 paraméterrel.
• A mute=1 némítva indítja a videót; a néző bármikor visszakapcsolhatja a hangot.
• A loop=1 a végén újraindítja a videót.
• A t=30 a 30. másodperctől indítja a lejátszást – hasznos, ha egy hosszabb videó adott pillanatára mutató mélylinket készítesz.

A címben megadott paraméter mindig felülírja ugyanazt a beállítást a Lejátszóstúdióban. A Lejátszóstúdiót a mindenhol érvényes alapértékekhez használd, például a skinhez, a kiemelőszínhez, a logóhoz és a gombelrendezéshez, a paramétereket pedig akkor, ha egy oldalnak másként kell viselkednie. Akár beágyazási domainenként külön lejátszóprofilt is tarthatsz.

3. lépés (opcionális): a stream lejátszása hls.js-sel

Az iframe a legrövidebb út, de néha saját markupra van szükség: egyedi vezérlősávra, körhintába (carousel) helyezett videóra, saját kódból küldött analitikai eseményekre. Ilyenkor szükséged van a playlist címére és egy lejátszókönyvtárra. A Safarin kívüli böngészők natívan nem tudnak HLS-t lejátszani, ezért a szokásos választás a hls.js, egy JavaScript-könyvtár, amely a HLS-szegmenseket egy szabványos <video> elembe tölti. A Safari és az iOS natívan lejátssza a HLS-t, nekik nincs rá szükségük.

A playlist címe a videóobjektum links.playback mezője. Kérd le a szerveredről API-kulccsal, mert a kulcs soha nem kerülhet a böngészőben futó kódba. Ugyanez a hívás visszaadja a links.expires_at mezőt is; a linkek aláírtak és időkorlátosak, ezért minden oldalmegjelenítéskor kérj friss linket, ahelyett hogy egyet az adatbázisodban tárolnál.

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
}

Ha az alapértelmezettől eltérő élettartamra van szükséged, a POST /files/{id}/links 60 másodperc és 30 nap közötti ttl értéket fogad el, és a linket IP-címhez vagy sütihez is kötheti. Az API-dokumentáció ezt részletesen leírja. Létezik egy nyilvános végpont is, a GET /api/v1/public/files/{id}, amelyhez nem kell kulcs; ezt használják a lejátszó- és beágyazási oldalak, és az általa adott linkek hat óráig érvényesek.

Az oldalon hozd létre a lejátszót. Az alábbi blokk ott, ahol támogatott, hls.js-t használ, Safarin natív lejátszásra vált, egyébként pedig egy egyszerű üzenetet mutat. A könyvtárfájlt tárold a saját szervereden, vagy rögzíts egy verziót, ahelyett hogy mindig a legfrissebbet töltenéd be.

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

A videóobjektum tartalmazza a borítóképhez tartozó links.poster és a rámutatáskor megjelenő előnézeti bélyegképekhez tartozó links.sprite mezőt is, amelyeket saját idősáv építésekor használhatsz. A hls.js-sel lemondasz azokról a dolgokról, amelyeket az UFOLOAD lejátszó elvégez helyetted: a minőségmenüről, a fejezetekről, a feliratválasztásról, a logórátétről, és – ha elérhetők – a hirdetésekről. Ez a valódi kompromisszum, és az alábbi táblázat összefoglalja.

iframe vagy hls.js: melyiket válaszd

Hibaelhárítási ellenőrzőlista

• Fekete kép vagy végtelen töltésjelző. Nyisd meg a böngésző hálózati paneljét, és keresd a master.m3u8 kérést. A 403 azt jelenti, hogy a link lejárt, vagy a nézőt egy ország- vagy IP-szabály tiltja; kérj friss linket.
• A böngésző blokkolja egy HTTPS-oldalon. Mindennek HTTPS-en kell mennie. Soha ne illessz http:// címet az iframe-be vagy a hls.js-be.
• Az automatikus lejátszás nem csinál semmit. A böngészők tiltják a hangos automatikus lejátszást. Add hozzá a mute=1 paramétert, vagy hls.js esetén állítsd be a video.muted = true értéket a play() hívása előtt.
• Feldolgozási értesítés a videó helyett. A fájl még nincs kész. Kérdezd le a GET /files/{id} végpontot újra és újra, amíg a status értéke ready nem lesz.
• Csak alacsony minőség játszódik le. A lejátszó óvatosan indul, és amint lemérte az átviteli sebességet, feljebb lép. A legfelső változatot a csomagod és a forrásod is korlátozza; vesd össze az Árak és a Funkciók oldallal.

Ha az oldalad működik, érdemes lehet megvédeni a hotlinkeléstől, vagy – ha elérhetők hirdetések – bevételt szerezni vele. Mindkettőről a következő útmutatók szólnak: korlátozd, hová ágyazható be a videód és szerezz bevételt a videós oldaladból a lejátszóban megjelenő hirdetésekkel. Ha még azon gondolkodsz, hol tárold a videóidat, a videotárhely-ellenőrzőlista felsorolja, mit érdemes összehasonlítani.