Slik bygger du inn en HLS-video på nettsiden (iframe og hls.js)

HLS (HTTP Live Streaming) er formatet de fleste nettsteder bruker for video på forespørsel i dag. I stedet for én enorm MP4-fil beskrives videoen av en liten tekstbasert spilleliste som peker på flere versjoner av den samme videoen, hver delt opp i korte segmenter. Spilleren laster ned noen segmenter i forkant, måler hvor raskt de kommer og bytter mellom versjonene underveis. Seere på mobilnett får en lett versjon, seere på fiber får den skarpe, og ingen må vente på at en hel fil lastes ned før det første bildet vises.

Denne guiden viser to måter å legge en HLS-video fra UFOLOAD på din egen nettside: den ferdige spilleren i en iframe, som tar omtrent ett minutt, og ditt eget <video>-element styrt av hls.js, som gir deg full kontroll over siden. Begge bruker den samme strømmen, så du kan starte med iframen og gå over til hls.js senere uten å laste opp noe på nytt.

Slik ser en HLS-strøm fra UFOLOAD ut

Når du har lastet opp en fil, koder konvertereren den med H.264-video og AAC-stereolyd til én til fire versjoner: 360p, 720p, 1080p og 2160p (4K). En versjon blir aldri større enn kilden, så en opplasting i 720p gir 720p og 360p, aldri en oppskalert 1080p. Den høyeste versjonen du faktisk får, avhenger også av planen din; prissiden viser de gjeldende grensene. Vil du ha hele bakgrunnen for hvordan trinnene velges, kan du lese adaptive bitrate-stiger forklart.

Hver versjon lagres som en vanlig MP4 med indeksen først i filen. Når en seer starter avspillingen, pakker lagringslaget disse MP4-filene om til HLS i sanntid: en master-spilleliste (master.m3u8) lister opp hver versjon med toppbåndbredde, oppløsning og kodeker, og hver versjon har sin egen spilleliste med segmenter på fire sekunder. Nøkkelrammene plasseres slik at de faller sammen med segmentgrensene, og det er dette som lar spilleren bytte kvalitet rent midt i en video.

Spillelisten og segmentene leveres fra hurtigbuffernoder med headeren Access-Control-Allow-Origin: *, så en spiller som kjører på domenet ditt, kan hente dem direkte. Hver URL er signert og har en utløpstid, noe som blir viktig senere når vi ser på hls.js-løsningen.

Steg 1: last opp videoen og vent til den er klar

Last opp fra dashbordet ved å slippe filen der eller lime inn en direkte lenke, eller bruk FTP, WebDAV eller API-et (se opplasting av videoer via API for eksempler i curl, Python og Node.js). En fil går gjennom statusene uploading, queued, processing og ready; failed meldes med en årsak og kan prøves på nytt fra dashbordet. Korte klipp er klare i løpet av minutter, lange filmer tar lengre tid, og betalte planer har en prioritert kodekø.

Du trenger ikke vente til siden er ferdig. Åpner noen spilleren mens filen fortsatt behandles, viser den et behandlingsvarsel med fremdriften og bytter selv til videoen når behandlingen er ferdig. Sjekk likevel at statusen er ready før du publiserer siden, slik at du ikke lanserer en side der de første besøkende ser en fremdriftslinje.

Du trenger video-ID-en. Dashbordet viser den i delingspanelet, og API-et returnerer den som public_id, en kort kode på 11 tegn. Det er den koden som går inn i innbyggingsadressen.

Steg 2: bygg inn spilleren med en iframe

Dashbordet gir deg en iframe-kodebit rett etter en opplasting og i delingspanelet for hver video. Den ser ut som den første blokken nedenfor. Erstatt VIDEO_ID med ID-en til videoen din. Selve spillersiden indekseres ikke av søkemotorer, og det er det du vil ha for en innbygging: det er siden din som rangeres, ikke spillerrammen.

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

Faste pikselstørrelser fungerer dårlig på mobil. For en responsiv side pakker du iframen inn i en boks som holder forholdet 16:9, og lar rammen fylle den. Spilleren fyller hele rammen, så videoen skaleres pent.

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

Parametere du kan legge til i adressen

• autoplay=1 starter avspillingen når spilleren lastes. Nettlesere blokkerer i de fleste tilfeller autoavspilling med lyd, så kombiner den med mute=1.
• mute=1 starter videoen uten lyd; seeren kan slå på lyden når som helst.
• loop=1 starter videoen på nytt når den er ferdig.
• t=30 starter avspillingen 30 sekunder inn, nyttig for direktelenker til et bestemt øyeblikk i en lengre video.

En parameter i adressen vinner alltid over den samme innstillingen i spillerstudioet. Bruk spillerstudioet til standarder som skal gjelde overalt, som skall, aksentfarge, logo og knappeoppsett, og bruk parametere når én side skal oppføre seg annerledes. Du kan til og med ha en egen spillerprofil per innbyggingsdomene.

Steg 3 (valgfritt): spill av strømmen med hls.js

Iframen er den korteste veien, men noen ganger vil du ha din egen markup: en egen kontrollinje, videoen inne i en karusell, analysehendelser fra din egen kode. Da trenger du adressen til spillelisten og et spillerbibliotek. Andre nettlesere enn Safari kan ikke spille av HLS innebygd, så det vanlige valget er hls.js, et JavaScript-bibliotek som mater HLS-segmenter inn i et vanlig <video>-element. Safari og iOS spiller av HLS innebygd og trenger det ikke.

Adressen til spillelisten er feltet links.playback i videoobjektet. Hent den fra serveren din med en API-nøkkel, fordi nøkkelen aldri må havne i nettleserkoden. Det samme kallet returnerer links.expires_at, og lenkene er signerte og tidsbegrensede, så be om en ny lenke hver gang du gjengir siden i stedet for å lagre én i databasen.

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
}

Trenger du en annen levetid enn standarden, godtar POST /files/{id}/links en ttl fra 60 sekunder til 30 dager og kan binde lenken til en IP-adresse eller en informasjonskapsel. API-dokumentasjonen beskriver dette i sin helhet. Det finnes også et offentlig endepunkt, GET /api/v1/public/files/{id}, som ikke krever nøkkel; avspillings- og innbyggingssidene bruker det, og lenkene derfra er gyldige i seks timer.

Opprett spilleren på siden. Blokken nedenfor bruker hls.js der det støttes, faller tilbake til innebygd avspilling i Safari og viser ellers en enkel melding. Host bibliotekfilen selv eller lås en versjon i stedet for å laste inn den nyeste, hva den enn måtte være.

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

Videoobjektet har også links.poster for forsidebildet og links.sprite for miniatyrbilder ved hover, som du kan bruke hvis du bygger din egen søkelinje. Med hls.js gir du fra deg det UFOLOAD-spilleren gjør for deg: kvalitetsmenyen, kapitler, valg av undertekster, logooverlegget og, når annonser er tilgjengelige, annonsene. Det er den reelle avveiningen, og tabellen nedenfor oppsummerer den.

iframe eller hls.js: hva bør du velge?

Sjekkliste for feilsøking

• Svart bilde eller lastehjul uten ende. Åpne nettverkspanelet i nettleseren og se etter master.m3u8. En 403 betyr at lenken er utløpt eller at seeren er blokkert av en land- eller IP-regel; be om en ny lenke.
• Blokkert av nettleseren på en HTTPS-side. Alt må gå over HTTPS. Lim aldri inn en http://-adresse i iframen eller i hls.js.
• Autoavspilling gjør ingenting. Nettlesere blokkerer autoavspilling med lyd. Legg til mute=1, eller sett video.muted = true i hls.js før du kaller play().
• Behandlingsvarsel i stedet for video. Filen er ikke klar ennå. Spør GET /files/{id} jevnlig til status er ready.
• Bare lav kvalitet spilles av. Spilleren starter forsiktig og klatrer så snart den har målt gjennomstrømningen. Planen din og kilden setter også et tak for den øverste versjonen; sammenlign med priser og funksjonssiden.

Når siden din fungerer, vil du kanskje beskytte den mot hotlinking eller, når annonser er tilgjengelige, tjene penger på den. Begge deler dekkes i de neste guidene: begrens hvor videoen din kan bygges inn og tjen penger på videonettstedet ditt med annonser i spilleren. Har du ennå ikke bestemt deg for hvor du skal hoste, viser sjekklisten for videohosting hva du bør sammenligne.