HLS-Video auf der eigenen Website einbetten (iframe und hls.js)

HLS (HTTP Live Streaming) ist das Format, das die meisten Websites heute für Video auf Abruf nutzen. Statt einer riesigen MP4-Datei wird das Video durch eine kleine Text-Playlist beschrieben, die auf mehrere Versionen desselben Videos verweist, jede in kurze Segmente zerlegt. Der Player lädt einige Segmente im Voraus, misst, wie schnell sie ankommen, und wechselt im laufenden Betrieb zwischen den Versionen. Zuschauer mit Mobilverbindung bekommen eine leichte Version, Zuschauer mit Glasfaser die scharfe, und niemand wartet, bis eine ganze Datei geladen ist, bevor das erste Bild erscheint.

Diese Anleitung zeigt zwei Wege, ein HLS-Video von UFOLOAD auf Ihrer eigenen Webseite einzubinden: den fertigen Player in einem iframe, was etwa eine Minute dauert, und Ihr eigenes <video>-Element, gesteuert von hls.js, das Ihnen volle Kontrolle über die Seite gibt. Beide nutzen denselben Stream, sodass Sie mit dem iframe beginnen und später zu hls.js wechseln können, ohne etwas neu hochzuladen.

Wie ein HLS-Stream von UFOLOAD aufgebaut ist

Nach dem Upload kodiert der Konverter die Datei mit H.264-Video und AAC-Stereo-Audio in eine bis vier Versionen, sogenannte Varianten: 360p, 720p, 1080p und 2160p (4K). Eine Variante ist nie größer als Ihre Quelle, ein 720p-Upload ergibt also 720p und 360p, niemals ein hochskaliertes 1080p. Welche höchste Variante Sie tatsächlich bekommen, hängt auch von Ihrem Tarif ab; die Preisseite nennt die aktuellen Limits. Wenn Sie alle Hintergründe zur Wahl der Stufen wissen möchten, lesen Sie Adaptive Bitrate-Leitern erklärt.

Jede Variante wird als normales MP4 mit dem Index am Dateianfang gespeichert. Startet ein Zuschauer die Wiedergabe, verpackt die Speicherebene diese MP4-Dateien im laufenden Betrieb in HLS: Eine Master-Playlist (master.m3u8) listet jede Variante mit Spitzenbandbreite, Auflösung und Codecs auf, und jede Variante hat ihre eigene Playlist aus Segmenten von vier Sekunden. Die Keyframes liegen so, dass sie mit den Segmentgrenzen übereinstimmen – deshalb kann der Player mitten im Video sauber die Qualität wechseln.

Playlist und Segmente werden von Cache-Knoten mit dem Header Access-Control-Allow-Origin: * ausgeliefert, sodass ein Player auf Ihrer Domain sie direkt anfordern kann. Jede URL ist signiert und hat ein Ablaufdatum, was später beim Ansatz mit hls.js wichtig wird.

Schritt 1: Video hochladen und warten, bis es fertig ist

Laden Sie im Dashboard hoch, indem Sie die Datei hineinziehen oder einen direkten Link einfügen, oder nutzen Sie FTP, WebDAV oder die API (Beispiele für curl, Python und Node.js finden Sie unter Videos per API hochladen). Eine Datei durchläuft die Status uploading, queued, processing und ready; failed wird mit einem Grund gemeldet und kann im Dashboard erneut versucht werden. Kurze Clips sind in wenigen Minuten fertig, lange Filme brauchen länger, und bezahlte Tarife haben eine Warteschlange mit priorisierter Kodierung.

Sie müssen nicht warten, bis die Seite fertig ist. Öffnet jemand den Player, während die Datei noch verarbeitet wird, zeigt er einen Verarbeitungshinweis mit Fortschritt und wechselt von selbst zum Video, sobald die Verarbeitung abgeschlossen ist. Prüfen Sie trotzdem, dass der Status ready ist, bevor Sie die Seite veröffentlichen, damit die ersten Besucher keinen Fortschrittsbalken sehen.

Sie brauchen die Kennung des Videos. Das Dashboard zeigt sie im Teilen-Bereich, und die API liefert sie als public_id, einen kurzen Code aus 11 Zeichen. Dieser Code kommt in die Einbettungsadresse.

Schritt 2: Player per iframe einbetten

Das Dashboard gibt direkt nach einem Upload und im Teilen-Bereich jedes Videos ein iframe-Snippet aus. Es sieht aus wie der erste Block unten. Ersetzen Sie VIDEO_ID durch die Kennung Ihres Videos. Die Player-Seite selbst wird von Suchmaschinen nicht indexiert, und genau das wollen Sie bei einer Einbettung: Ihre Seite rankt, nicht der Player-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>

Feste Pixelgrößen funktionieren auf Smartphones nicht. Für eine responsive Seite umschließen Sie das iframe mit einer Box, die das Seitenverhältnis 16:9 hält, und lassen den Frame sie ausfüllen. Der Player füllt den gesamten Frame, sodass das Video sauber skaliert.

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

Parameter, die Sie an die Adresse anhängen können

• autoplay=1 startet die Wiedergabe, sobald der Player geladen ist. Browser blockieren Autoplay mit Ton in den meisten Fällen, kombinieren Sie es also mit mute=1.
• mute=1 startet das Video stumm; der Zuschauer kann den Ton jederzeit einschalten.
• loop=1 startet das Video am Ende von vorn.
• t=30 startet die Wiedergabe bei Sekunde 30 – praktisch für Deep Links auf einen bestimmten Moment in einem längeren Video.

Ein Parameter in der Adresse hat immer Vorrang vor derselben Einstellung im Player-Studio. Nutzen Sie das Player-Studio für Standards, die überall gelten, etwa Skin, Akzentfarbe, Logo und Anordnung der Buttons, und Parameter, wenn sich eine einzelne Seite anders verhalten soll. Sie können sogar für jede Einbettungsdomain ein eigenes Player-Profil anlegen.

Schritt 3 (optional): Stream mit hls.js abspielen

Das iframe ist der kürzeste Weg, aber manchmal möchten Sie eigenes Markup: eine eigene Steuerleiste, das Video in einem Karussell, Analytics-Events aus Ihrem eigenen Code. Dann brauchen Sie die Playlist-Adresse und eine Player-Bibliothek. Browser außer Safari können HLS nicht nativ abspielen, daher fällt die Wahl meist auf hls.js, eine JavaScript-Bibliothek, die HLS-Segmente in ein normales <video>-Element einspeist. Safari und iOS spielen HLS nativ ab und brauchen sie nicht.

Die Playlist-Adresse steht im Feld links.playback des Videoobjekts. Fordern Sie sie von Ihrem Server aus mit einem API-Schlüssel an, denn der Schlüssel darf niemals im Browser-Code auftauchen. Derselbe Aufruf liefert links.expires_at, und Links sind signiert und zeitlich begrenzt – fordern Sie also bei jedem Rendern der Seite einen frischen Link an, statt einen in Ihrer Datenbank zu speichern.

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
}

Wenn Sie eine andere Gültigkeit als die Voreinstellung brauchen, akzeptiert POST /files/{id}/links einen ttl von 60 Sekunden bis 30 Tagen und kann den Link an eine IP-Adresse oder ein Cookie binden. Die API-Dokumentation beschreibt das vollständig. Es gibt außerdem einen öffentlichen Endpunkt, GET /api/v1/public/files/{id}, der keinen Schlüssel braucht; die Wiedergabe- und Einbettungsseiten nutzen ihn, und seine Links sind sechs Stunden gültig.

Erstellen Sie den Player auf der Seite. Der Block unten nutzt hls.js, wo es unterstützt wird, greift in Safari auf native Wiedergabe zurück und zeigt sonst eine einfache Meldung. Hosten Sie die Bibliotheksdatei selbst oder legen Sie eine Version fest, statt einfach die jeweils neueste zu 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>

Das Videoobjekt enthält außerdem links.poster für das Titelbild und links.sprite für Vorschaubilder beim Hovern, die Sie nutzen können, wenn Sie Ihre eigene Zeitleiste bauen. Mit hls.js verzichten Sie auf das, was der UFOLOAD-Player für Sie erledigt: Qualitätsmenü, Kapitel, Untertitelauswahl, Logo-Overlay und – sofern Werbung verfügbar ist – die Werbung. Das ist der eigentliche Kompromiss, und die Tabelle unten fasst ihn zusammen.

iframe oder hls.js: was Sie nutzen sollten

Checkliste zur Fehlersuche

• Schwarzes Bild oder endloser Ladekreis. Öffnen Sie den Netzwerk-Tab des Browsers und suchen Sie nach master.m3u8. Ein 403 bedeutet, dass der Link abgelaufen ist oder der Zuschauer durch eine Länder- oder IP-Regel gesperrt ist; fordern Sie einen frischen Link an.
• Vom Browser auf einer HTTPS-Seite blockiert. Alles muss über HTTPS laufen. Fügen Sie niemals eine http://-Adresse in das iframe oder in hls.js ein.
• Autoplay tut nichts. Autoplay mit Ton wird von Browsern blockiert. Fügen Sie mute=1 hinzu oder setzen Sie in hls.js video.muted = true, bevor Sie play() aufrufen.
• Verarbeitungshinweis statt Video. Die Datei ist noch nicht fertig. Fragen Sie GET /files/{id} ab, bis status den Wert ready hat.
• Es läuft nur eine niedrige Qualität. Der Player startet vorsichtig und steigt auf, sobald er den Durchsatz gemessen hat. Auch Ihr Tarif und Ihre Quelle begrenzen die oberste Variante; vergleichen Sie mit Preise und der Seite Funktionen.

Sobald Ihre Seite funktioniert, möchten Sie sie vielleicht vor Hotlinking schützen oder – sofern Werbung verfügbar ist – damit Geld verdienen. Beides behandeln die nächsten Anleitungen: einschränken, wo Ihr Video eingebettet werden kann und Ihre Videoseite mit Werbung im Player monetarisieren. Wenn Sie noch überlegen, wo Sie hosten, listet die Checkliste für Videohosting auf, was Sie vergleichen sollten.