Kako vdelati video HLS na spletno stran (iframe in hls.js)

HLS (HTTP Live Streaming) je format, ki ga danes za video na zahtevo uporablja večina spletnih strani. Namesto ene ogromne datoteke MP4 video opisuje majhen besedilni seznam predvajanja, ki kaže na več različic istega videa, vsaka pa je razrezana na kratke segmente. Predvajalnik vnaprej prenese nekaj segmentov, izmeri, kako hitro prihajajo, in sproti preklaplja med različicami. Gledalci na mobilni povezavi dobijo lahko različico, gledalci na optiki ostro, in nihče ne čaka, da se prenese cela datoteka, preden se prikaže prva sličica.

Ta vodnik prikazuje dva načina, kako video HLS iz UFOLOAD postaviti na svojo spletno stran: pripravljen predvajalnik v iframe, ki vzame približno minuto, in lasten element <video>, ki ga poganja hls.js in vam daje popoln nadzor nad stranjo. Oba uporabljata isti tok, zato lahko začnete z iframe in pozneje preidete na hls.js, ne da bi karkoli ponovno nalagali.

Kako je videti tok HLS iz UFOLOAD

Ko naložite datoteko, jo kodirnik z videom H.264 in stereo zvokom AAC kodira v eno do štiri različice: 360p, 720p, 1080p in 2160p (4K). Različica ni nikoli večja od vira, zato nalaganje 720p ustvari 720p in 360p, nikoli povečanega 1080p. Najvišja različica, ki jo dejansko dobite, je odvisna tudi od vašega paketa; stran Cenik navaja trenutne omejitve. Če želite celotno ozadje o tem, kako se izberejo stopnje, preberite razlago lestvic prilagodljive bitne hitrosti.

Vsaka različica je shranjena kot običajen MP4 z indeksom na začetku datoteke. Ko gledalec začne predvajanje, plast za shranjevanje te datoteke MP4 sproti zapakira v HLS: glavni seznam predvajanja (master.m3u8) navaja vse različice z največjo pasovno širino, ločljivostjo in kodeki, vsaka različica pa ima svoj seznam predvajanja s štirisekundnimi segmenti. Ključne sličice so postavljene tako, da se ujemajo z mejami segmentov, kar predvajalniku omogoča čist preklop kakovosti sredi videa.

Seznam predvajanja in segmenti se strežejo s predpomnilniških vozlišč z glavo Access-Control-Allow-Origin: *, zato jih lahko predvajalnik, ki teče na vaši domeni, zahteva neposredno. Vsak URL je podpisan in ima čas poteka, kar bo pomembno pozneje, ko bomo govorili o pristopu s hls.js.

1. korak: naložite video in počakajte, da je pripravljen

Naložite ga z nadzorne plošče tako, da datoteko spustite ali prilepite neposredno povezavo, ali pa uporabite FTP, WebDAV ali API (primere za curl, Python in Node.js najdete v članku nalaganje videov prek API). Datoteka gre skozi stanja uploading, queued, processing in ready; failed se sporoči z razlogom in ga je mogoče ponovno poskusiti z nadzorne plošče. Kratki posnetki so pripravljeni v nekaj minutah, dolgi filmi trajajo dlje, plačljivi paketi pa imajo prednostno čakalno vrsto za kodiranje.

S stranjo vam ni treba čakati. Če nekdo odpre predvajalnik, medtem ko se datoteka še obdeluje, ta prikaže obvestilo o obdelavi z napredkom in ob koncu obdelave sam preklopi na video. Kljub temu pred objavo strani preverite, ali je stanje ready, da ne objavite strani, na kateri prvi obiskovalci vidijo vrstico napredka.

Potrebovali boste identifikator videa. Nadzorna plošča ga prikaže v plošči za deljenje, API pa ga vrne kot public_id, kratko kodo z 11 znaki. Ta koda gre v naslov za vdelavo.

2. korak: vdelajte predvajalnik z iframe

Nadzorna plošča izdelek iframe ponudi takoj po nalaganju in v plošči za deljenje vsakega videa. Videti je kot prvi spodnji blok. VIDEO_ID zamenjajte z identifikatorjem svojega videa. Same strani predvajalnika iskalniki ne indeksirajo, kar je pri vdelavi zaželeno: uvrsti se vaša stran, ne okvir predvajalnika.

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

Fiksne velikosti v slikovnih točkah se na telefonih pokvarijo. Za odzivno stran iframe ovijte v okvir, ki ohranja razmerje 16:9, in pustite, da ga okvir zapolni. Predvajalnik zapolni celoten okvir, zato se video čisto prilagaja.

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

Parametri, ki jih lahko dodate naslovu

• autoplay=1 začne predvajanje, ko se predvajalnik naloži. Brskalniki v večini primerov blokirajo samodejno predvajanje z zvokom, zato ga kombinirajte z mute=1.
• mute=1 začne video brez zvoka; gledalec lahko zvok kadar koli vklopi.
• loop=1 ob koncu video začne znova.
• t=30 začne predvajanje pri 30. sekundi, kar je priročno za povezave na določen trenutek v daljšem videu.

Parameter v naslovu ima vedno prednost pred isto nastavitvijo v studiu predvajalnika. Studio predvajalnika uporabite za privzete vrednosti, ki veljajo povsod, kot so preobleka, barva poudarka, logotip in razporeditev gumbov, parametre pa takrat, ko se mora ena stran vesti drugače. Za vsako domeno vdelave lahko imate celo ločen profil predvajalnika.

3. korak (neobvezno): tok predvajajte s hls.js

Iframe je najkrajša pot, včasih pa želite lastno oznako: prilagojeno vrstico kontrolnikov, video v vrtiljaku, analitične dogodke iz lastne kode. Takrat potrebujete naslov seznama predvajanja in knjižnico predvajalnika. Brskalniki razen Safarija HLS ne znajo predvajati izvorno, zato je običajna izbira hls.js, knjižnica JavaScript, ki segmente HLS podaja standardnemu elementu <video>. Safari in iOS predvajata HLS izvorno in je ne potrebujeta.

Naslov seznama predvajanja je polje links.playback objekta videa. Zahtevajte ga s svojega strežnika s ključem API, ker se ključ nikoli ne sme pojaviti v kodi brskalnika. Isti klic vrne links.expires_at, povezave pa so podpisane in časovno omejene, zato ob vsakem izrisu strani zahtevajte svežo povezavo, namesto da jo shranite v bazo podatkov.

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
}

Če potrebujete življenjsko dobo, drugačno od privzete, POST /files/{id}/links sprejme ttl od 60 sekund do 30 dni in lahko povezavo veže na naslov IP ali piškotek. Dokumentacija API to pokriva v celoti. Obstaja tudi javna končna točka GET /api/v1/public/files/{id}, ki ne potrebuje ključa; uporabljata jo strani za ogled in vdelavo, njene povezave pa veljajo šest ur.

Na strani ustvarite predvajalnik. Spodnji blok uporabi hls.js, kjer je podprt, v Safariju preide na izvorno predvajanje, sicer pa prikaže preprosto sporočilo. Datoteko knjižnice gostite sami ali zaklenite različico, namesto da nalagate vsakokratno najnovejšo.

<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 vsebuje tudi links.poster za naslovno sliko in links.sprite za sličice predogleda ob prehodu z miško, ki jih lahko uporabite, če gradite lastno vrstico za iskanje. S hls.js se odpoveste temu, kar za vas naredi predvajalnik UFOLOAD: meniju kakovosti, poglavjem, izbiri podnapisov, prekrivnemu logotipu in, kadar so oglasi na voljo, oglasom. To je pravi kompromis, spodnja tabela pa ga povzame.

Iframe ali hls.js: kaj uporabiti

Kontrolni seznam za odpravljanje težav

• Črna slika ali neskončna vrtavka. Odprite zavihek omrežja v brskalniku in poiščite master.m3u8. Napaka 403 pomeni, da je povezava potekla ali da gledalca blokira pravilo za državo ali IP; zahtevajte svežo povezavo.
• Brskalnik blokira na strani HTTPS. Vse mora biti HTTPS. V iframe ali hls.js nikoli ne prilepite naslova http://.
• Samodejno predvajanje ne naredi ničesar. Brskalniki blokirajo samodejno predvajanje z zvokom. Dodajte mute=1 ali v hls.js nastavite video.muted = true, preden pokličete play().
• Obvestilo o obdelavi namesto videa. Datoteka še ni pripravljena. Pozivajte GET /files/{id}, dokler status ni ready.
• Predvaja se le nizka kakovost. Predvajalnik začne previdno in se dvigne, takoj ko izmeri prepustnost. Najvišjo različico omejujeta tudi vaš paket in vir; primerjajte s cenikom in stranjo s funkcijami.

Ko vaša stran deluje, jo boste morda želeli zaščititi pred hotlinkanjem ali, kadar so oglasi na voljo, z njo zaslužiti. Oboje pokrivata naslednja vodnika: omejite, kje je mogoče vdelati vaš video in monetizirajte svojo video stran z oglasi v predvajalniku. Če se še odločate, kje gostovati, kontrolni seznam za video gostovanje navaja, kaj primerjati.