Kuidas manustada HLS-video oma veebisaidile (iframe ja hls.js)

HLS (HTTP Live Streaming) on vorming, mida enamik veebisaite tänapäeval tellitava video jaoks kasutab. Ühe hiiglasliku MP4-faili asemel kirjeldab videot väike tekstiline esitusloend, mis viitab sama video mitmele versioonile, millest igaüks on lõigatud lühikesteks segmentideks. Mängija laadib mõned segmendid ette, mõõdab, kui kiiresti need saabuvad, ja vahetab versioone lennult. Mobiiliühendusega vaatajad saavad kerge versiooni, valguskaabliga vaatajad terava, ja keegi ei pea enne esimese kaadri ilmumist ootama terve faili allalaadimist.

See juhend näitab kahte viisi UFOLOADi HLS-video lisamiseks oma veebilehele: valmis mängija iframe'is, mis võtab umbes minuti, ja oma <video> element hls.js-i juhtimisel, mis annab sulle lehe üle täieliku kontrolli. Mõlemad kasutavad sama voogu, nii et võid alustada iframe'iga ja minna hiljem üle hls.js-ile ilma midagi uuesti üles laadimata.

Milline näeb välja UFOLOADi HLS-voog

Pärast faili üleslaadimist kodeerib konverter selle H.264 video ja AAC stereoheliga ühte kuni nelja versiooni: 360p, 720p, 1080p ja 2160p (4K). Versioon ei ole kunagi suurem kui allikas, nii et 720p üleslaadimisest tehakse 720p ja 360p, mitte kunagi üleskaleeritud 1080p. Kõrgeim versioon, mille tegelikult saad, sõltub ka sinu paketist; kehtivad piirangud on toodud hinnalehel. Kui soovid täit tausta selle kohta, kuidas astmeid valitakse, loe artiklit adaptiivse bitikiiruse redel.

Iga versioon salvestatakse tavalise MP4-na, mille indeks on faili alguses. Kui vaataja taasesituse käivitab, pakendab salvestuskiht need MP4-failid lennult HLS-iks: põhiesitusloend (master.m3u8) loetleb kõik versioonid koos nende tippribalaiuse, eraldusvõime ja koodekitega ning igal versioonil on oma neljasekundiliste segmentide esitusloend. Võtmekaadrid paigutatakse nii, et need langeksid kokku segmentide piiridega – just see võimaldab mängijal video keskel kvaliteeti puhtalt vahetada.

Esitusloendit ja segmente serveeritakse vahemälusõlmedest päisega Access-Control-Allow-Origin: *, nii et sinu domeenil töötav mängija saab neid otse küsida. Iga URL on allkirjastatud ja aegumisajaga, mis on oluline hiljem, kui räägime hls.js-i lähenemisest.

1. samm: laadi video üles ja oota, kuni see on valmis

Laadi üles juhtpaneelilt, lohistades faili või kleepides otselingi, või kasuta FTP-d, WebDAVi või API-t (curl-i, Pythoni ja Node.js-i näited leiad artiklist videote üleslaadimine API kaudu). Fail liigub läbi olekute uploading, queued, processing ja ready; olekust failed teatatakse koos põhjusega ja seda saab juhtpaneelilt uuesti proovida. Lühikesed klipid on valmis mõne minutiga, pikad filmid võtavad kauem ning tasulistel pakettidel on prioriteetne kodeerimisjärjekord.

Sa ei pea ootama, kuni leht valmis saab. Kui keegi avab mängija ajal, mil faili veel töödeldakse, näitab see töötlemisteadet koos edenemisega ja lülitub töötlemise lõppedes ise videole. Siiski kontrolli enne lehe avaldamist, et olek oleks ready, et su lehe esimesed külastajad ei näeks edenemisriba.

Sul on vaja video identifikaatorit. Juhtpaneel näitab seda jagamispaneelis ja API tagastab selle väljana public_id – see on 11-märgiline lühikood. Just see kood läheb manustamisaadressi.

2. samm: manusta mängija iframe'iga

Juhtpaneel annab iframe-koodi kohe pärast üleslaadimist ja iga video jagamispaneelis. See näeb välja nagu allolev esimene plokk. Asenda VIDEO_ID oma video identifikaatoriga. Mängija lehte ennast otsingumootorid ei indekseeri, ja manustuse puhul just seda soovidki: järjestusse jõuab sinu leht, mitte mängija raam.

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

Fikseeritud pikslisuurused lähevad telefonides katki. Kohanduva lehe jaoks mähi iframe kasti, mis hoiab kuvasuhet 16:9, ja lase raamil seda täita. Mängija täidab kogu raami, nii et video skaleerub puhtalt.

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

Parameetrid, mida saad aadressile lisada

• autoplay=1 käivitab taasesituse mängija laadimisel. Brauserid blokeerivad heliga automaatesituse enamasti, seega kombineeri see parameetriga mute=1.
• mute=1 käivitab video vaigistatult; vaataja saab heli igal hetkel sisse lülitada.
• loop=1 alustab video lõppedes uuesti algusest.
• t=30 alustab taasesitust 30. sekundist – mugav süvalinkide jaoks pikema video kindlale hetkele.

Aadressis olev parameeter on alati ülimuslik sama seade ees mängijastuudios. Kasuta mängijastuudiot vaikeseadete jaoks, mis kehtivad kõikjal, näiteks kujundus, aktsentvärv, logo ja nuppude paigutus, ning parameetreid siis, kui üks leht peab käituma teisiti. Võid isegi hoida iga manustamisdomeeni jaoks eraldi mängijaprofiili.

3. samm (valikuline): esita voogu hls.js-iga

Iframe on lühim tee, kuid mõnikord soovid oma märgistust: kohandatud juhtriba, videot karussellis, analüütikasündmusi oma koodist. Siis vajad esitusloendi aadressi ja mängijateeki. Muud brauserid peale Safari ei suuda HLS-i omal jõul esitada, seega on tavaline valik hls.js – JavaScripti teek, mis söödab HLS-segmente tavalisse <video> elementi. Safari ja iOS esitavad HLS-i omal jõul ega vaja seda.

Esitusloendi aadress on videoobjekti väli links.playback. Küsi seda oma serverist API võtmega, sest võti ei tohi kunagi brauseri koodis näha olla. Sama päring tagastab välja links.expires_at ning lingid on allkirjastatud ja ajaliselt piiratud, seega küsi lehe iga renderdamise ajal värske link, selle asemel et ühte andmebaasi salvestada.

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
}

Kui vajad vaikimisi kehtivusajast erinevat aega, aktsepteerib POST /files/{id}/links parameetrit ttl vahemikus 60 sekundit kuni 30 päeva ning saab siduda lingi IP-aadressi või küpsisega. API dokumentatsioon käsitleb seda täielikult. On ka avalik lõpp-punkt GET /api/v1/public/files/{id}, mis ei vaja võtit; seda kasutavad vaatamis- ja manustamislehed ning selle lingid kehtivad kuus tundi.

Loo lehel mängija. Allolev plokk kasutab hls.js-i seal, kus seda toetatakse, kasutab Safaris varuvariandina sisseehitatud taasesitust ja näitab muul juhul lihtsat teadet. Majuta teegifail ise või kinnita versioon, selle asemel et laadida alati uusim.

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

Videoobjektil on ka links.poster kaanepildi jaoks ja links.sprite hõljumiseelvaate pisipiltide jaoks, mida saad kasutada, kui ehitad oma kerimisriba. hls.js-iga loobud asjadest, mida UFOLOADi mängija sinu eest teeb: kvaliteedimenüü, peatükid, subtiitrite valik, logo ülekate ja reklaamide saadavuse korral ka reklaamid. See ongi tegelik kompromiss ja allolev tabel võtab selle kokku.

Iframe või hls.js: kumba kasutada

Tõrkeotsingu kontrollnimekiri

• Must kaader või lõputu laadimisikoon. Ava brauseri võrgupaneel ja otsi master.m3u8. Vastus 403 tähendab, et link on aegunud või vaataja on riigi- või IP-reegliga blokeeritud; küsi värske link.
• Brauser blokeerib HTTPS-lehel. Kõik peab olema HTTPS. Ära kunagi kleebi http:// aadressi iframe'i ega hls.js-i.
• Automaatesitus ei tee midagi. Brauserid blokeerivad heliga automaatesituse. Lisa mute=1 või määra hls.js-is enne play() kutsumist video.muted = true.
• Video asemel töötlemisteade. Fail pole veel valmis. Küsi GET /files/{id} korduvalt, kuni status on ready.
• Mängib ainult madal kvaliteet. Mängija alustab ettevaatlikult ja tõuseb kohe, kui on läbilaskevõime mõõtnud. Ülemist versiooni piiravad ka sinu pakett ja allikas; võrdle hindade ja võimaluste lehega.

Kui su leht töötab, võid soovida seda hotlinkimise eest kaitsta või reklaamide saadavuse korral sellega teenida. Mõlemat käsitlevad järgmised juhendid: piira, kuhu sinu videot saab manustada ja monetiseeri oma videosaiti mängijasiseste reklaamidega. Kui alles otsustad, kus majutada, loetleb videomajutuse kontrollnimekiri, mida võrrelda.