Een HLS-video op je website insluiten (iframe en hls.js)

HLS (HTTP Live Streaming) is het formaat dat de meeste websites vandaag gebruiken voor video op aanvraag. In plaats van één enorm MP4-bestand wordt de video beschreven door een kleine tekstplaylist die verwijst naar meerdere versies van dezelfde video, elk opgeknipt in korte segmenten. De speler downloadt een paar segmenten vooruit, meet hoe snel ze binnenkomen en wisselt onderweg tussen versies. Kijkers op een mobiele verbinding krijgen een lichte versie, kijkers op glasvezel de scherpe, en niemand hoeft te wachten tot een heel bestand is gedownload voordat het eerste beeld verschijnt.

Deze gids laat twee manieren zien om een HLS-video van UFOLOAD op je eigen webpagina te zetten: de kant-en-klare speler in een iframe, wat ongeveer een minuut kost, en je eigen <video>-element aangestuurd door hls.js, wat je volledige controle over de pagina geeft. Beide gebruiken dezelfde stream, dus je kunt met de iframe beginnen en later overstappen op hls.js zonder iets opnieuw te uploaden.

Hoe een HLS-stream van UFOLOAD eruitziet

Nadat je een bestand hebt geüpload, codeert de converter het met H.264-video en AAC-stereoaudio in één tot vier versies, renditions genoemd: 360p, 720p, 1080p en 2160p (4K). Een versie is nooit groter dan je bron, dus een 720p-upload levert 720p en 360p op, nooit een opgeschaalde 1080p. Welke hoogste versie je echt krijgt, hangt ook af van je abonnement; de prijspagina toont de actuele limieten. Wil je de volledige achtergrond over hoe de treden worden gekozen, lees dan adaptieve bitrateladders uitgelegd.

Elke versie wordt opgeslagen als een gewone MP4 met de index vooraan in het bestand. Wanneer een kijker het afspelen start, verpakt de opslaglaag die MP4-bestanden direct als HLS: een master-playlist (master.m3u8) somt elke versie op met haar piekbandbreedte, resolutie en codecs, en elke versie heeft haar eigen playlist met segmenten van vier seconden. Keyframes worden zo geplaatst dat ze samenvallen met de segmentgrenzen, en daardoor kan de speler midden in een video netjes van kwaliteit wisselen.

De playlist en de segmenten worden geserveerd vanaf cache-nodes met een header Access-Control-Allow-Origin: *, zodat een speler op jouw domein ze rechtstreeks kan opvragen. Elke URL is ondertekend en heeft een vervaltijd, wat later belangrijk wordt als we het over de aanpak met hls.js hebben.

Stap 1: upload de video en wacht tot hij klaar is

Upload vanuit het dashboard door het bestand erin te slepen of een directe link te plakken, of gebruik FTP, WebDAV of de API (zie video's uploaden via API voor voorbeelden in curl, Python en Node.js). Een bestand doorloopt de statussen uploading, queued, processing en ready; failed wordt gemeld met een reden en kan vanuit het dashboard opnieuw worden geprobeerd. Korte clips zijn binnen enkele minuten klaar, lange films duren langer, en betaalde abonnementen hebben een coderingswachtrij met voorrang.

Je hoeft niet te wachten tot de verwerking klaar is. Opent iemand de speler terwijl het bestand nog wordt verwerkt, dan toont die een verwerkingsmelding met de voortgang en schakelt hij vanzelf over naar de video zodra de verwerking klaar is. Controleer toch of de status ready is voordat je de pagina publiceert, zodat de eerste bezoekers geen voortgangsbalk te zien krijgen.

Je hebt de video-ID nodig. Het dashboard toont die in het deelpaneel, en de API geeft hem terug als public_id, een korte code van 11 tekens. Die code komt in het insluitadres.

Stap 2: sluit de speler in met een iframe

Het dashboard geeft direct na een upload en in het deelpaneel van elke video een iframe-fragment. Het ziet eruit als het eerste blok hieronder. Vervang VIDEO_ID door de ID van je video. De spelerpagina zelf wordt niet door zoekmachines geïndexeerd, en dat wil je ook bij een insluiting: jouw pagina scoort, niet het spelerframe.

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

Vaste pixelmaten werken niet op telefoons. Zet de iframe voor een responsieve pagina in een kader dat de verhouding 16:9 aanhoudt en laat het frame dat kader vullen. De speler vult het hele frame, dus de video schaalt netjes mee.

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

Parameters die je aan het adres kunt toevoegen

• autoplay=1 start het afspelen zodra de speler laadt. Browsers blokkeren autoplay met geluid in de meeste gevallen, dus combineer het met mute=1.
• mute=1 start de video zonder geluid; de kijker kan het geluid op elk moment aanzetten.
• loop=1 start de video opnieuw als hij afgelopen is.
• t=30 start het afspelen na 30 seconden, handig voor deeplinks naar een moment in een langere video.

Een parameter in het adres wint altijd van dezelfde instelling in Player studio. Gebruik Player studio voor standaarden die overal gelden, zoals de skin, accentkleur, het logo en de knopindeling, en gebruik parameters als één pagina zich anders moet gedragen. Je kunt zelfs per insluitdomein een apart spelerprofiel aanhouden.

Stap 3 (optioneel): speel de stream af met hls.js

De iframe is de kortste weg, maar soms wil je je eigen markup: een eigen bedieningsbalk, de video in een carrousel, analytics-events vanuit je eigen code. Dan heb je het playlistadres en een spelerbibliotheek nodig. Andere browsers dan Safari kunnen HLS niet zelf afspelen, dus de gebruikelijke keuze is hls.js, een JavaScript-bibliotheek die HLS-segmenten aan een standaard <video>-element voert. Safari en iOS spelen HLS zelf af en hebben hem niet nodig.

Het playlistadres is het veld links.playback van het video-object. Vraag het op vanaf je server met een API-sleutel, want de sleutel mag nooit in browsercode terechtkomen. Dezelfde aanroep geeft links.expires_at terug, en links zijn ondertekend en in tijd beperkt, dus vraag bij elke weergave van de pagina een verse link op in plaats van er een in je database op te slaan.

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
}

Heb je een andere levensduur nodig dan de standaard, dan accepteert POST /files/{id}/links een ttl van 60 seconden tot 30 dagen en kan het de link koppelen aan een IP-adres of een cookie. De API-documentatie beschrijft dit volledig. Er is ook een openbaar endpoint, GET /api/v1/public/files/{id}, waarvoor geen sleutel nodig is; de kijk- en insluitpagina's gebruiken het, en de links ervan zijn zes uur geldig.

Maak op de pagina de speler aan. Het blok hieronder gebruikt hls.js waar dat wordt ondersteund, valt op Safari terug op native afspelen en toont anders een eenvoudige melding. Host het bibliotheekbestand zelf of zet een vaste versie vast in plaats van steeds de nieuwste te laden.

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

Het video-object bevat ook links.poster voor de omslagafbeelding en links.sprite voor voorbeeldminiaturen bij hover, die je kunt gebruiken als je je eigen zoekbalk bouwt. Met hls.js geef je op wat de UFOLOAD-speler voor je doet: het kwaliteitsmenu, hoofdstukken, de keuze van ondertitels, de logo-overlay en, als advertenties beschikbaar zijn, de advertenties. Dat is de echte afweging, en de tabel hieronder vat die samen.

iframe of hls.js: welke kies je?

Checklist voor probleemoplossing

• Zwart beeld of eindeloos laadrondje. Open het netwerkpaneel van de browser en zoek naar master.m3u8. Een 403 betekent dat de link is verlopen of dat de kijker wordt geblokkeerd door een land- of IP-regel; vraag een verse link op.
• Geblokkeerd door de browser op een HTTPS-pagina. Alles moet via HTTPS. Plak nooit een http://-adres in de iframe of in hls.js.
• Autoplay doet niets. Autoplay met geluid wordt door browsers geblokkeerd. Voeg mute=1 toe, of zet in hls.js video.muted = true voordat je play() aanroept.
• Verwerkingsmelding in plaats van video. Het bestand is nog niet klaar. Vraag GET /files/{id} periodiek op tot status gelijk is aan ready.
• Alleen een lage kwaliteit speelt af. De speler begint voorzichtig en klimt zodra hij de doorvoer heeft gemeten. Je abonnement en je bron begrenzen ook de hoogste versie; vergelijk met prijzen en de functiepagina.

Zodra je pagina werkt, wil je haar misschien beschermen tegen hotlinken of er, als advertenties beschikbaar zijn, aan verdienen. Beide komen aan bod in de volgende gidsen: beperk waar je video kan worden ingesloten en verdien aan je videosite met advertenties in de speler. Twijfel je nog waar je wilt hosten, dan somt de checklist voor videohosting op wat je moet vergelijken.