Kaip įterpti HLS vaizdo įrašą į svetainę (iframe ir hls.js)

HLS (HTTP Live Streaming) – formatas, kurį šiandien dauguma svetainių naudoja vaizdo įrašams pagal pareikalavimą. Vietoj vieno didžiulio MP4 failo vaizdo įrašą aprašo nedidelis tekstinis grojaraštis, nurodantis kelias to paties vaizdo įrašo versijas, kurių kiekviena supjaustyta į trumpus segmentus. Grotuvas atsisiunčia kelis segmentus į priekį, matuoja, kaip greitai jie atkeliauja, ir keičia versijas skrydžio metu. Žiūrovai su telefono ryšiu gauna lengvą versiją, šviesolaidžio naudotojai – ryškią, ir niekas nelaukia, kol atsisiųs visas failas, kad pasirodytų pirmasis kadras.

Šiame vadove parodyti du būdai, kaip HLS vaizdo įrašą iš UFOLOAD įdėti į savo tinklalapį: paruoštas grotuvas iframe, kuriam reikia maždaug minutės, ir jūsų pačių <video> elementas, valdomas hls.js, kuris suteikia visišką puslapio kontrolę. Abu naudoja tą patį srautą, todėl galite pradėti nuo iframe ir vėliau pereiti prie hls.js nieko iš naujo neįkeldami.

Kaip atrodo UFOLOAD HLS srautas

Įkėlus failą, konverteris jį užkoduoja H.264 vaizdu ir AAC stereo garsu į nuo vienos iki keturių versijų: 360p, 720p, 1080p ir 2160p (4K). Versija niekada nebūna didesnė už šaltinį, todėl iš 720p įkėlimo gaunamos 720p ir 360p versijos, bet ne padidinta 1080p. Aukščiausia versija, kurią iš tikrųjų gaunate, priklauso ir nuo plano; aktualūs limitai pateikti kainų puslapyje. Jei norite išsamiau sužinoti, kaip parenkamos pakopos, skaitykite adaptyvaus bitų srauto kopėčios.

Kiekviena versija saugoma kaip įprastas MP4 su indeksu failo pradžioje. Žiūrovui pradėjus atkūrimą, saugyklos lygmuo tuos MP4 failus skrydžio metu supakuoja į HLS: pagrindinis grojaraštis (master.m3u8) išvardija kiekvieną versiją su jos didžiausiu pralaidumu, raiška ir kodekais, o kiekviena versija turi savo keturių sekundžių segmentų grojaraštį. Rakto kadrai išdėstyti taip, kad sutaptų su segmentų ribomis – būtent tai leidžia grotuvui sklandžiai keisti kokybę vaizdo įrašo viduryje.

Grojaraštis ir segmentai teikiami iš podėlio mazgų su antrašte Access-Control-Allow-Origin: *, todėl jūsų domene veikiantis grotuvas gali jų prašyti tiesiogiai. Kiekvienas URL yra pasirašytas ir turi galiojimo laiką – tai svarbu vėliau, kai kalbėsime apie hls.js būdą.

1 žingsnis: įkelkite vaizdo įrašą ir palaukite, kol jis bus paruoštas

Įkelkite iš valdymo skydelio nutempdami failą arba įklijuodami tiesioginę nuorodą, arba naudokite FTP, WebDAV ar API (curl, Python ir Node.js pavyzdžių rasite straipsnyje vaizdo įrašų įkėlimas per API). Failas pereina būsenas uploading, queued, processing ir ready; failed pranešama su priežastimi, o veiksmą galima pakartoti iš skydelio. Trumpi klipai paruošiami per kelias minutes, ilgi filmai užtrunka ilgiau, o mokami planai turi prioritetinę kodavimo eilę.

Nebūtina laukti, kol puslapis bus baigtas. Jei kas nors atidaro grotuvą, kol failas dar apdorojamas, rodomas pranešimas apie apdorojimą su eiga, o baigus apdorojimą grotuvas pats perjungia į vaizdo įrašą. Vis dėlto prieš publikuodami puslapį patikrinkite, ar būsena yra ready, kad pirmieji lankytojai neišvystų eigos juostos.

Jums reikės vaizdo įrašo identifikatoriaus. Valdymo skydelis jį rodo dalijimosi skydelyje, o API grąžina kaip public_id – trumpą 11 simbolių kodą. Būtent šis kodas įrašomas į įterpimo adresą.

2 žingsnis: įterpkite grotuvą su iframe

Valdymo skydelis iframe fragmentą pateikia iškart po įkėlimo ir kiekvieno vaizdo įrašo dalijimosi skydelyje. Jis atrodo kaip pirmasis toliau pateiktas blokas. Pakeiskite VIDEO_ID savo vaizdo įrašo identifikatoriumi. Pats grotuvo puslapis paieškos sistemų neindeksuojamas – to ir reikia įterpimui: reitinguojamas jūsų puslapis, o ne grotuvo rėmelis.

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

Fiksuoti dydžiai pikseliais telefonuose sugenda. Prisitaikančiame puslapyje apgaubkite iframe dėžute, išlaikančia 16:9 santykį, ir leiskite rėmeliui ją užpildyti. Grotuvas užpildo visą rėmelį, todėl vaizdo įrašas mastelį keičia tvarkingai.

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

Parametrai, kuriuos galima pridėti prie adreso

• autoplay=1 pradeda atkūrimą įsikėlus grotuvui. Daugeliu atvejų naršyklės blokuoja automatinį paleidimą su garsu, todėl derinkite jį su mute=1.
• mute=1 paleidžia vaizdo įrašą be garso; žiūrovas gali bet kada jį įjungti.
• loop=1 pasibaigus vaizdo įrašui paleidžia jį iš naujo.
• t=30 pradeda atkūrimą nuo 30-os sekundės – patogu nuorodoms į konkretų ilgesnio vaizdo įrašo momentą.

Parametras adrese visada nusveria tą patį nustatymą grotuvo studijoje. Grotuvo studiją naudokite numatytiesiems nustatymams, taikomiems visur, pavyzdžiui, apvalkalui, akcento spalvai, logotipui ir mygtukų išdėstymui, o parametrus – kai vienas puslapis turi elgtis kitaip. Kiekvienam įterpimo domenui galite turėti net atskirą grotuvo profilį.

3 žingsnis (nebūtinas): atkurkite srautą su hls.js

iframe yra trumpiausias kelias, tačiau kartais norisi savo maketo: savos valdymo juostos, vaizdo įrašo karuselėje, analitikos įvykių iš jūsų kodo. Tada reikia grojaraščio adreso ir grotuvo bibliotekos. Naršyklės, išskyrus Safari, negali atkurti HLS savaime, todėl įprastas pasirinkimas yra hls.js – JavaScript biblioteka, perduodanti HLS segmentus standartiniam <video> elementui. Safari ir iOS HLS atkuria savaime, todėl jos nereikia.

Grojaraščio adresas yra vaizdo įrašo objekto laukas links.playback. Jo prašykite iš savo serverio su API raktu, nes raktas niekada neturi atsidurti naršyklės kode. Tas pats kvietinys grąžina links.expires_at, o nuorodos pasirašytos ir ribotos laiko, todėl šviežios nuorodos prašykite kiekvieną kartą generuodami puslapį, užuot saugoję ją duomenų bazėje.

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
}

Jei reikia kito nei numatytasis galiojimo laiko, POST /files/{id}/links priima ttl nuo 60 sekundžių iki 30 dienų ir gali susieti nuorodą su IP adresu ar slapuku. Visa tai išsamiai aprašyta API dokumentacijoje. Taip pat yra viešas galinis taškas GET /api/v1/public/files/{id}, kuriam rakto nereikia; jį naudoja žiūrėjimo ir įterpimo puslapiai, o jo nuorodos galioja šešias valandas.

Puslapyje sukurkite grotuvą. Toliau pateiktas blokas naudoja hls.js ten, kur ji palaikoma, Safari naršyklėje grįžta prie savaiminio atkūrimo, o kitais atvejais rodo paprastą pranešimą. Bibliotekos failą talpinkite patys arba užfiksuokite versiją, užuot įkėlę bet kokią naujausią.

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

Vaizdo įrašo objekte taip pat yra links.poster viršelio paveikslėliui ir links.sprite peržiūros miniatiūroms užvedus pelę – jas galite naudoti, jei kuriate savo slinkties juostą. Su hls.js atsisakote to, ką už jus daro UFOLOAD grotuvas: kokybės meniu, skyrių, subtitrų pasirinkimo, logotipo uždangos ir, kai reklama prieinama, reklamos. Tai ir yra tikrasis kompromisas, o toliau pateikta lentelė jį apibendrina.

iframe ar hls.js: ką naudoti

Trikčių šalinimo sąrašas

• Juodas kadras arba nesibaigiantis ratukas. Atidarykite naršyklės tinklo skydelį ir ieškokite master.m3u8. 403 reiškia, kad nuorodos galiojimas baigėsi arba žiūrovą blokuoja šalies ar IP taisyklė; paprašykite šviežios nuorodos.
• Naršyklė blokuoja HTTPS puslapyje. Viskas turi būti HTTPS. Niekada neįklijuokite http:// adreso į iframe ar hls.js.
• Automatinis paleidimas neveikia. Naršyklės blokuoja automatinį paleidimą su garsu. Pridėkite mute=1 arba hls.js atveju prieš kviesdami play() nustatykite video.muted = true.
• Vietoj vaizdo įrašo – pranešimas apie apdorojimą. Failas dar neparuoštas. Kartokite GET /files/{id}, kol status taps ready.
• Atkuriama tik žema kokybė. Grotuvas pradeda atsargiai ir kyla aukštyn, kai tik išmatuoja pralaidumą. Viršutinę versiją taip pat riboja jūsų planas ir šaltinis; palyginkite su kainomis ir funkcijų puslapiu.

Kai puslapis veikia, galbūt norėsite apsaugoti jį nuo hotlinking arba, kai reklama prieinama, iš jo uždirbti. Abu dalykai aprašyti kituose vadovuose: apribokite, kur galima įterpti jūsų vaizdo įrašą ir monetizuokite savo vaizdo svetainę reklama grotuve. Jei dar renkatės, kur talpinti, vaizdo įrašų talpinimo kontroliniame sąraše išvardyta, ką palyginti.