Sådan indlejrer du en HLS-video på dit website (iframe og hls.js)

HLS (HTTP Live Streaming) er det format, de fleste websites bruger i dag til on-demand-video. I stedet for én stor MP4-fil beskrives videoen af en lille tekstbaseret playliste, der peger på flere versioner af den samme video, hver skåret op i korte segmenter. Afspilleren henter et par segmenter forud, måler, hvor hurtigt de kommer, og skifter mellem versionerne undervejs. Seere på en mobilforbindelse får en let version, seere på fiber får den skarpe, og ingen venter på, at en hel fil er hentet, før det første billede vises.

Denne guide viser to måder at sætte en HLS-video fra UFOLOAD ind på din egen webside: den færdige afspiller i en iframe, som tager omkring et minut, og dit eget <video>-element drevet af hls.js, som giver dig fuld kontrol over siden. Begge bruger den samme stream, så du kan starte med iframen og skifte til hls.js senere uden at uploade noget igen.

Sådan ser en HLS-stream fra UFOLOAD ud

Når du har uploadet en fil, koder konverteren den med H.264-video og AAC-stereolyd i én til fire versioner, kaldet renditions: 360p, 720p, 1080p og 2160p (4K). En version er aldrig større end din kilde, så en 720p-upload giver 720p og 360p, aldrig en opskaleret 1080p. Den højeste version, du faktisk får, afhænger også af din plan; prissiden viser de aktuelle grænser. Vil du have hele baggrunden for, hvordan trinnene vælges, så læs adaptive bitrate-stiger forklaret.

Hver version gemmes som en almindelig MP4 med indekset forrest i filen. Når en seer starter afspilningen, pakker lagerlaget disse MP4-filer til HLS i farten: En master-playliste (master.m3u8) angiver hver version med dens spidsbåndbredde, opløsning og codecs, og hver version har sin egen playliste med segmenter på fire sekunder. Keyframes placeres, så de flugter med segmentgrænserne, og det er det, der lader afspilleren skifte kvalitet rent midt i en video.

Playlisten og segmenterne leveres fra cache-noder med headeren Access-Control-Allow-Origin: *, så en afspiller, der kører på dit domæne, kan hente dem direkte. Hver URL er signeret og har et udløbstidspunkt, hvilket får betydning senere, når vi taler om tilgangen med hls.js.

Trin 1: upload videoen, og vent, til den er klar

Upload fra dashboardet ved at trække filen ind eller indsætte et direkte link, eller brug FTP, WebDAV eller API'et (se upload af videoer via API for eksempler i curl, Python og Node.js). En fil går gennem statusserne uploading, queued, processing og ready; failed meldes med en årsag og kan prøves igen fra dashboardet. Korte klip er klar inden for få minutter, lange film tager længere tid, og betalte planer har en prioriteret kodningskø.

Du behøver ikke vente med siden. Åbner nogen afspilleren, mens filen stadig behandles, viser den en behandlingsbesked med fremskridtet og skifter selv til videoen, når behandlingen er færdig. Tjek alligevel, at statussen er ready, før du udgiver siden, så du ikke lancerer en side, hvor de første besøgende ser en statuslinje.

Du skal bruge videoens id. Dashboardet viser det i delingspanelet, og API'et returnerer det som public_id, en kort kode på 11 tegn. Det er den kode, der indgår i indlejringsadressen.

Trin 2: indlejr afspilleren med en iframe

Dashboardet giver dig et iframe-uddrag lige efter en upload og i delingspanelet for hver video. Det ligner den første blok nedenfor. Erstat VIDEO_ID med din videos id. Selve afspillersiden indekseres ikke af søgemaskiner, og det er præcis, hvad du vil have ved en indlejring: Det er din side, der rangerer, ikke afspillerens frame.

<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 pixelstørrelser går i stykker på telefoner. Til en responsiv side pakker du iframen ind i en boks, der bevarer forholdet 16:9, og lader framen fylde den ud. Afspilleren fylder hele framen, så videoen skaleres pænt.

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

Parametre, du kan tilføje til adressen

• autoplay=1 starter afspilningen, når afspilleren indlæses. Browsere blokerer i de fleste tilfælde autoplay med lyd, så kombiner den med mute=1.
• mute=1 starter videoen uden lyd; seeren kan slå lyden til når som helst.
• loop=1 starter videoen forfra, når den slutter.
• t=30 starter afspilningen 30 sekunder inde, praktisk til dybe links til et bestemt øjeblik i en længere video.

En parameter i adressen vinder altid over den samme indstilling i Afspillerstudiet. Brug Afspillerstudiet til standarder, der gælder overalt, som skin, accentfarve, logo og knaplayout, og brug parametre, når én side skal opføre sig anderledes. Du kan endda have en separat afspillerprofil for hvert indlejringsdomæne.

Trin 3 (valgfrit): afspil streamen med hls.js

Iframen er den korteste vej, men nogle gange vil du have din egen markup: en tilpasset kontrolbjælke, videoen i en karrusel, analysehændelser fra din egen kode. Så har du brug for playlistens adresse og et afspillerbibliotek. Andre browsere end Safari kan ikke afspille HLS indbygget, så det almindelige valg er hls.js, et JavaScript-bibliotek, der fører HLS-segmenter ind i et standard <video>-element. Safari og iOS afspiller HLS indbygget og har ikke brug for det.

Playlistens adresse er feltet links.playback i videoobjektet. Hent den fra din server med en API-nøgle, for nøglen må aldrig optræde i browserkode. Det samme kald returnerer links.expires_at, og links er signerede og tidsbegrænsede, så bed om et frisk link, hver gang du genererer siden, i stedet for at gemme et i din database.

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
}

Har du brug for en anden levetid end standarden, accepterer POST /files/{id}/links en ttl fra 60 sekunder til 30 dage og kan binde linket til en IP-adresse eller en cookie. API-dokumentationen beskriver det i detaljer. Der findes også et offentligt endpoint, GET /api/v1/public/files/{id}, som ikke kræver nøgle; afspilnings- og indlejringssiderne bruger det, og dets links er gyldige i seks timer.

Opret afspilleren på siden. Blokken nedenfor bruger hls.js, hvor det understøttes, falder tilbage til indbygget afspilning i Safari og viser ellers en simpel besked. Host selv biblioteksfilen, eller lås en version fast i stedet for at indlæse den nyeste.

<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 til coverbilledet og links.sprite til miniaturer ved hover, som du kan bruge, hvis du bygger din egen tidslinje. Med hls.js giver du afkald på det, UFOLOAD-afspilleren gør for dig: kvalitetsmenuen, kapitler, valg af undertekster, logo-overlayet og, når annoncer er tilgængelige, annoncerne. Det er den reelle afvejning, og tabellen nedenfor opsummerer den.

iframe eller hls.js: hvad skal du bruge?

Tjekliste til fejlfinding

• Sort billede eller uendeligt snurrende hjul. Åbn browserens netværkspanel, og kig efter master.m3u8. En 403 betyder, at linket er udløbet, eller at seeren er blokeret af en lande- eller IP-regel; hent et frisk link.
• Blokeret af browseren på en HTTPS-side. Alt skal være HTTPS. Indsæt aldrig en http://-adresse i iframen eller i hls.js.
• Autoplay gør ingenting. Autoplay med lyd blokeres af browsere. Tilføj mute=1, eller sæt i hls.js video.muted = true, før du kalder play().
• Behandlingsbesked i stedet for video. Filen er ikke klar endnu. Spørg GET /files/{id} jævnligt, indtil status er ready.
• Kun lav kvalitet afspilles. Afspilleren starter forsigtigt og stiger, så snart den har målt gennemstrømningen. Din plan og din kilde sætter også loft over den øverste version; sammenlign med priser og siden funktioner.

Når din side virker, vil du måske beskytte den mod hotlinking eller, når annoncer er tilgængelige, tjene penge på den. Begge dele dækkes i de næste guides: begræns, hvor din video kan indlejres og tjen penge på dit videowebsite med annoncer i afspilleren. Hvis du stadig overvejer, hvor du skal hoste, viser tjeklisten til videohosting, hvad du skal sammenligne.