HLS-videon upottaminen verkkosivulle (iframe ja hls.js)

HLS (HTTP Live Streaming) on muoto, jota useimmat verkkosivustot käyttävät nykyään tilausvideoon. Yhden valtavan MP4-tiedoston sijaan videota kuvaa pieni tekstimuotoinen soittolista, joka osoittaa saman videon useisiin versioihin, joista jokainen on pilkottu lyhyiksi segmenteiksi. Soitin lataa muutaman segmentin etukäteen, mittaa niiden saapumisnopeuden ja vaihtaa versioiden välillä lennossa. Mobiiliyhteydellä katsova saa kevyen version, valokuidulla katsova terävän, eikä kenenkään tarvitse odottaa koko tiedoston latautumista ennen ensimmäistä kuvaa.

Tämä opas näyttää kaksi tapaa lisätä UFOLOADin HLS-video omalle verkkosivullesi: valmis soitin iframessa, mihin kuluu noin minuutti, ja oma hls.js:n ohjaama <video>-elementti, joka antaa täyden hallinnan sivuun. Molemmat käyttävät samaa striimiä, joten voit aloittaa iframella ja siirtyä myöhemmin hls.js:ään lataamatta mitään uudelleen.

Millainen UFOLOADin HLS-striimi on

Kun lataat tiedoston, muunnin koodaa sen H.264-videoksi ja AAC-stereoääneksi yhdestä neljään versioon: 360p, 720p, 1080p ja 2160p (4K). Versio ei ole koskaan lähdettä suurempi, joten 720p-latauksesta syntyy 720p ja 360p, ei koskaan ylöspäin skaalattua 1080p:tä. Se, mikä on paras versio, jonka todella saat, riippuu myös paketistasi; hinnoittelusivu luettelee nykyiset rajat. Jos haluat kattavan taustan siitä, miten portaat valitaan, lue mukautuvan bittinopeuden portaikko.

Jokainen versio tallennetaan tavallisena MP4-tiedostona, jonka indeksi on tiedoston alussa. Kun katsoja aloittaa toiston, tallennuskerros paketoi nämä MP4-tiedostot HLS-muotoon lennossa: pääsoittolista (master.m3u8) luettelee jokaisen version huippukaistanleveyksineen, resoluutioineen ja koodekkeineen, ja jokaisella versiolla on oma soittolistansa neljän sekunnin segmenteistä. Avainruudut on sijoitettu segmenttien rajoille, minkä ansiosta soitin voi vaihtaa laatua siististi kesken videon.

Soittolista ja segmentit tarjoillaan välimuistisolmuista Access-Control-Allow-Origin: * -otsakkeella, joten verkkotunnuksellasi toimiva soitin voi pyytää niitä suoraan. Jokainen URL on allekirjoitettu ja sillä on vanhenemisaika, millä on merkitystä myöhemmin hls.js-lähestymistavan kohdalla.

Vaihe 1: lataa video ja odota, että se on valmis

Lataa hallintapaneelista pudottamalla tiedosto tai liittämällä suora linkki, tai käytä FTP:tä, WebDAVia tai API:a (katso curl-, Python- ja Node.js-esimerkit oppaasta videoiden lataus API:n kautta). Tiedosto kulkee tilojen uploading, queued, processing ja ready läpi; failed ilmoitetaan syyn kera, ja sen voi yrittää uudelleen hallintapaneelista. Lyhyet leikkeet ovat valmiina minuuteissa, pitkät elokuvat vievät kauemmin, ja maksullisissa paketeissa on etusijakoodausjono.

Sivun valmistumista ei tarvitse odottaa. Jos joku avaa soittimen tiedoston ollessa vielä käsittelyssä, se näyttää käsittelyilmoituksen edistymisineen ja siirtyy videoon itsestään, kun käsittely päättyy. Tarkista silti, että tila on ready, ennen kuin julkaiset sivun, jotta sivusi ensimmäiset vierailijat eivät näe edistymispalkkia.

Tarvitset videon tunnisteen. Hallintapaneeli näyttää sen jakopaneelissa, ja API palauttaa sen kenttänä public_id, 11 merkin lyhytkoodina. Tämä koodi tulee upotusosoitteeseen.

Vaihe 2: upota soitin iframella

Hallintapaneeli antaa iframe-koodinpätkän heti latauksen jälkeen ja jokaisen videon jakopaneelissa. Se näyttää alla olevalta ensimmäiseltä lohkolta. Korvaa VIDEO_ID videosi tunnisteella. Hakukoneet eivät indeksoi itse soitinsivua, mikä on upotukselle juuri oikein: sinun sivusi sijoittuu hakutuloksissa, ei soittimen kehys.

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

Kiinteät pikselikoot hajoavat puhelimissa. Responsiivisella sivulla kääri iframe laatikkoon, joka säilyttää 16:9-suhteen, ja anna kehyksen täyttää se. Soitin täyttää koko kehyksen, joten video skaalautuu siististi.

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

Osoitteeseen lisättävät parametrit

• autoplay=1 aloittaa toiston, kun soitin latautuu. Selaimet estävät useimmiten äänellisen automaattisen toiston, joten yhdistä se parametriin mute=1.
• mute=1 aloittaa videon mykistettynä; katsoja voi poistaa mykistyksen milloin tahansa.
• loop=1 aloittaa videon alusta, kun se päättyy.
• t=30 aloittaa toiston 30 sekunnin kohdalta, kätevä syvälinkeissä pidemmän videon tiettyyn hetkeen.

Osoitteen parametri voittaa aina saman asetuksen Soitinstudiossa. Käytä Soitinstudiota kaikkialla voimassa oleviin oletuksiin, kuten ulkoasuun, korostusväriin, logoon ja painikkeiden asetteluun, ja parametreja, kun yhden sivun pitää toimia toisin. Voit jopa pitää erillisen soitinprofiilin jokaiselle upottavalle verkkotunnukselle.

Vaihe 3 (valinnainen): toista striimi hls.js:llä

Iframe on lyhin tie, mutta joskus haluat oman merkinnän: mukautetun ohjauspalkin, videon karusellissa tai analytiikkatapahtumia omasta koodistasi. Silloin tarvitset soittolistan osoitteen ja soitinkirjaston. Muut selaimet kuin Safari eivät toista HLS:ää natiivisti, joten tavallinen valinta on hls.js, JavaScript-kirjasto, joka syöttää HLS-segmentit tavalliseen <video>-elementtiin. Safari ja iOS toistavat HLS:ää natiivisti eivätkä tarvitse sitä.

Soittolistan osoite on videon objektin kenttä links.playback. Pyydä se palvelimeltasi API-avaimella, koska avain ei saa koskaan näkyä selaimen koodissa. Sama kutsu palauttaa kentän links.expires_at, ja linkit ovat allekirjoitettuja ja aikarajoitettuja, joten pyydä tuore linkki aina sivua renderöidessäsi sen sijaan, että tallentaisit sen tietokantaan.

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
}

Jos tarvitset oletuksesta poikkeavan voimassaoloajan, POST /files/{id}/links hyväksyy ttl-arvon 60 sekunnista 30 päivään ja voi sitoa linkin IP-osoitteeseen tai evästeeseen. API-dokumentaatio kuvaa sen kokonaan. Lisäksi on julkinen päätepiste GET /api/v1/public/files/{id}, joka ei vaadi avainta; katselu- ja upotussivut käyttävät sitä, ja sen linkit ovat voimassa kuusi tuntia.

Luo sivulle soitin. Alla oleva lohko käyttää hls.js:ää siellä, missä sitä tuetaan, palaa Safarissa natiiviin toistoon ja näyttää muuten pelkän ilmoituksen. Isännöi kirjastotiedosto itse tai kiinnitä versio sen sijaan, että lataisit aina uusimman.

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

Videon objektissa on myös links.poster kansikuvaa varten ja links.sprite hiiren alla näkyviä esikatselukuvia varten, joita voit käyttää, jos rakennat oman aikajanan. Hls.js:n kanssa luovut asioista, jotka UFOLOAD-soitin tekee puolestasi: laatuvalikosta, kappaleista, tekstitysten valinnasta, logon päällyksestä ja, kun mainoksia on saatavilla, mainoksista. Se on todellinen kompromissi, ja alla oleva taulukko tiivistää sen.

Iframe vai hls.js: kumpaa käyttää

Vianmäärityksen tarkistuslista

• Musta kuva tai loputon latauskuvake. Avaa selaimen verkkopaneeli ja etsi master.m3u8. 403 tarkoittaa, että linkki on vanhentunut tai maa- tai IP-sääntö estää katsojan; pyydä tuore linkki.
• Selain estää HTTPS-sivulla. Kaiken on oltava HTTPS:ää. Älä koskaan liitä http://-osoitetta iframeen tai hls.js:ään.
• Automaattinen toisto ei tee mitään. Selaimet estävät äänellisen automaattisen toiston. Lisää mute=1 tai aseta hls.js:ssä video.muted = true ennen kutsua play().
• Käsittelyilmoitus videon sijaan. Tiedosto ei ole vielä valmis. Kysele GET /files/{id} kunnes status on ready.
• Vain heikko laatu toistuu. Soitin aloittaa varovasti ja nousee heti, kun se on mitannut läpäisykyvyn. Myös pakettisi ja lähteesi rajaavat parhaan version; vertaa hinnoitteluun ja ominaisuussivuun.

Kun sivusi toimii, saatat haluta suojata sen hotlinkkaukselta tai, kun mainoksia on saatavilla, ansaita sillä. Molemmat käsitellään seuraavissa oppaissa: rajoita, missä videosi voidaan upottaa ja ansaitse videosivustollasi soittimen mainoksilla. Jos vielä mietit, missä videoita isännöidään, videohostingin tarkistuslista luettelee, mitä kannattaa vertailla.