Så bäddar du in en HLS-video på din webbplats (iframe och hls.js)

HLS (HTTP Live Streaming) är det format som de flesta webbplatser i dag använder för video på begäran. I stället för en enda stor MP4-fil beskrivs videon av en liten textbaserad spellista som pekar på flera versioner av samma video, var och en uppdelad i korta segment. Spelaren laddar ner några segment i förväg, mäter hur snabbt de kommer fram och växlar mellan versionerna i farten. Tittare på en mobilanslutning får en lätt version, tittare på fiber får den skarpa, och ingen behöver vänta på att en hel fil laddas ner innan den första bildrutan visas.

Den här guiden visar två sätt att lägga en HLS-video från UFOLOAD på din egen webbsida: den färdiga spelaren i en iframe, som tar ungefär en minut, och ditt eget <video>-element som drivs av hls.js, som ger dig full kontroll över sidan. Båda använder samma ström, så du kan börja med iframe och gå över till hls.js senare utan att ladda upp något på nytt.

Så ser en HLS-ström från UFOLOAD ut

När du har laddat upp en fil kodar konverteraren den med H.264-video och AAC-ljud i stereo till en till fyra versioner: 360p, 720p, 1080p och 2160p (4K). En version blir aldrig större än källan, så en uppladdning i 720p ger 720p och 360p, aldrig en uppskalad 1080p. Den högsta version du faktiskt får beror också på din plan; prissidan listar de aktuella gränserna. Om du vill ha hela bakgrunden till hur stegen väljs, läs adaptiva bithastighetsstegar förklarade.

Varje version lagras som en vanlig MP4 med indexet i början av filen. När en tittare startar uppspelningen paketerar lagringslagret dessa MP4-filer till HLS i farten: en huvudspellista (master.m3u8) listar varje version med dess toppbandbredd, upplösning och codecs, och varje version har sin egen spellista med segment på fyra sekunder. Nyckelbildrutorna placeras så att de sammanfaller med segmentgränserna, vilket är det som låter spelaren byta kvalitet smidigt mitt i en video.

Spellistan och segmenten levereras från cachenoder med huvudet Access-Control-Allow-Origin: *, så en spelare som körs på din domän kan begära dem direkt. Varje URL är signerad och har en utgångstid, vilket blir viktigt längre fram när vi går igenom upplägget med hls.js.

Steg 1: ladda upp videon och vänta tills den är klar

Ladda upp från instrumentpanelen genom att släppa filen där eller klistra in en direktlänk, eller använd FTP, WebDAV eller API:et (se ladda upp videor via API för exempel i curl, Python och Node.js). En fil går igenom statusarna uploading, queued, processing och ready; failed rapporteras med en orsak och kan försökas igen från instrumentpanelen. Korta klipp är klara inom några minuter, långa filmer tar längre tid, och betalplaner har en prioriterad kodningskö.

Du behöver inte vänta tills sidan är färdig. Om någon öppnar spelaren medan filen fortfarande bearbetas visas ett meddelande om bearbetning med förloppet, och spelaren växlar själv till videon när bearbetningen är klar. Kontrollera ändå att statusen är ready innan du publicerar sidan, så att du inte lanserar en sida där de första besökarna ser en förloppsindikator.

Du behöver videons identifierare. Instrumentpanelen visar den i delningspanelen, och API:et returnerar den som public_id, en kort kod på 11 tecken. Det är den koden som ska in i inbäddningsadressen.

Steg 2: bädda in spelaren med en iframe

Instrumentpanelen ger dig ett iframe-kodavsnitt direkt efter en uppladdning och i delningspanelen för varje video. Det ser ut som det första blocket nedan. Ersätt VIDEO_ID med din videos identifierare. Själva spelarsidan indexeras inte av sökmotorer, vilket är precis vad du vill för en inbäddning: det är din sida som rankas, inte spelarramen.

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

Fasta pixelstorlekar fungerar dåligt på mobiler. För en responsiv sida lägger du iframen i en ruta som behåller förhållandet 16:9 och låter ramen fylla den. Spelaren fyller hela ramen, så videon skalas snyggt.

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

Parametrar du kan lägga till i adressen

• autoplay=1 startar uppspelningen när spelaren laddas. Webbläsare blockerar i de flesta fall autouppspelning med ljud, så kombinera den med mute=1.
• mute=1 startar videon utan ljud; tittaren kan slå på ljudet när som helst.
• loop=1 startar om videon när den tar slut.
• t=30 startar uppspelningen 30 sekunder in, praktiskt för djuplänkar till ett visst ögonblick i en längre video.

En parameter i adressen går alltid före samma inställning i Spelarstudion. Använd Spelarstudion för standardvärden som gäller överallt, som skal, accentfärg, logotyp och knapplayout, och använd parametrar när en enskild sida behöver bete sig annorlunda. Du kan till och med ha en separat spelarprofil per inbäddningsdomän.

Steg 3 (valfritt): spela upp strömmen med hls.js

En iframe är den kortaste vägen, men ibland vill du ha din egen kod: ett eget kontrollfält, videon i en karusell, analyshändelser från din egen kod. Då behöver du spellistans adress och ett spelarbibliotek. Andra webbläsare än Safari kan inte spela upp HLS inbyggt, så det vanliga valet är hls.js, ett JavaScript-bibliotek som matar in HLS-segment i ett vanligt <video>-element. Safari och iOS spelar upp HLS inbyggt och behöver det inte.

Spellistans adress är fältet links.playback i videoobjektet. Hämta den från din server med en API-nyckel, eftersom nyckeln aldrig får förekomma i kod i webbläsaren. Samma anrop returnerar links.expires_at, och länkarna är signerade och tidsbegränsade, så begär en ny länk varje gång du renderar sidan i stället för att spara en 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
}

Om du behöver en annan livslängd än standardvärdet tar POST /files/{id}/links emot en ttl från 60 sekunder till 30 dagar och kan binda länken till en IP-adress eller en cookie. API-dokumentationen beskriver det i detalj. Det finns också en offentlig endpoint, GET /api/v1/public/files/{id}, som inte kräver någon nyckel; visnings- och inbäddningssidorna använder den, och dess länkar är giltiga i sex timmar.

Skapa sedan spelaren på sidan. Blocket nedan använder hls.js där det stöds, faller tillbaka på inbyggd uppspelning i Safari och visar annars ett enkelt meddelande. Hosta biblioteksfilen själv eller lås en version i stället för att ladda den senaste, vilken den än är.

<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 innehåller också links.poster för omslagsbilden och links.sprite för miniatyrer vid hovring, som du kan använda om du bygger ett eget sökfält. Med hls.js avstår du från det som UFOLOAD-spelaren gör åt dig: kvalitetsmenyn, kapitel, val av undertexter, logotypöverlägget och, när annonser är tillgängliga, annonserna. Det är den verkliga avvägningen, och tabellen nedan sammanfattar den.

iframe eller hls.js: vilket ska du välja

Checklista för felsökning

• Svart bild eller en laddningsikon som aldrig slutar snurra. Öppna webbläsarens nätverkspanel och leta efter master.m3u8. En 403 betyder att länken har gått ut eller att tittaren spärras av en lands- eller IP-regel; begär en ny länk.
• Blockeras av webbläsaren på en HTTPS-sida. Allt måste vara HTTPS. Klistra aldrig in en http://-adress i iframen eller i hls.js.
• Autouppspelning gör ingenting. Autouppspelning med ljud blockeras av webbläsare. Lägg till mute=1, eller sätt video.muted = true i hls.js innan du anropar play().
• Meddelande om bearbetning i stället för video. Filen är inte klar än. Fråga GET /files/{id} regelbundet tills status är ready.
• Bara låg kvalitet spelas upp. Spelaren startar försiktigt och klättrar uppåt så snart den har mätt genomströmningen. Din plan och din källa begränsar också den högsta versionen; jämför med priser och funktionssidan.

När sidan fungerar kanske du vill skydda den mot hotlinking eller, när annonser är tillgängliga, tjäna pengar på den. Båda delarna tas upp i nästa guider: begränsa var din video kan bäddas in och tjäna pengar på din videosajt med annonser i spelaren. Om du fortfarande funderar på var du ska hosta listar checklistan för videohosting vad du bör jämföra.