Jak osadzić wideo HLS na swojej stronie (iframe i hls.js)

HLS (HTTP Live Streaming) to format, którego większość stron internetowych używa dziś do wideo na żądanie. Zamiast jednego ogromnego pliku MP4 wideo opisuje mała tekstowa playlista, która wskazuje kilka wersji tego samego filmu, każdą pociętą na krótkie segmenty. Odtwarzacz pobiera kilka segmentów z wyprzedzeniem, mierzy, jak szybko docierają, i w locie przełącza się między wersjami. Widzowie na łączu komórkowym dostają lekką wersję, widzowie na światłowodzie — ostrą, i nikt nie czeka na pobranie całego pliku, zanim pojawi się pierwsza klatka.

Ten poradnik pokazuje dwa sposoby umieszczenia wideo HLS z UFOLOAD na własnej stronie: gotowy odtwarzacz w iframe, co zajmuje około minuty, oraz własny element <video> sterowany przez hls.js, który daje pełną kontrolę nad stroną. Oba korzystają z tego samego strumienia, więc możesz zacząć od iframe i później przejść na hls.js bez ponownego przesyłania czegokolwiek.

Jak wygląda strumień HLS z UFOLOAD

Po przesłaniu pliku konwerter koduje go do wideo H.264 i dźwięku AAC stereo w jednej do czterech wersji: 360p, 720p, 1080p i 2160p (4K). Wersja nigdy nie jest większa od źródła, więc z pliku 720p powstają 720p i 360p, nigdy przeskalowane w górę 1080p. Najwyższa wersja, którą faktycznie dostajesz, zależy też od planu; aktualne limity podaje cennik. Jeśli chcesz poznać szczegóły doboru stopni, przeczytaj artykuł drabinki adaptacyjnego bitrate’u.

Każda wersja jest przechowywana jako zwykły plik MP4 z indeksem na początku pliku. Gdy widz rozpoczyna odtwarzanie, warstwa przechowywania pakuje te pliki MP4 do HLS w locie: główna playlista (master.m3u8) wymienia każdą wersję z jej szczytową przepustowością, rozdzielczością i kodekami, a każda wersja ma własną playlistę czterosekundowych segmentów. Klatki kluczowe są rozmieszczone tak, by pokrywały się z granicami segmentów — dzięki temu odtwarzacz może płynnie zmieniać jakość w środku filmu.

Playlista i segmenty są serwowane z węzłów cache z nagłówkiem Access-Control-Allow-Origin: *, więc odtwarzacz działający na Twojej domenie może pobierać je bezpośrednio. Każdy URL jest podpisany i ma czas wygaśnięcia, co będzie istotne później, przy podejściu z hls.js.

Krok 1: prześlij wideo i poczekaj, aż będzie gotowe

Prześlij plik w panelu, przeciągając go lub wklejając bezpośredni link, albo użyj FTP, WebDAV lub API (przykłady w curl, Python i Node.js znajdziesz w artykule przesyłanie wideo przez API). Plik przechodzi przez statusy uploading, queued, processing i ready; status failed jest zgłaszany z przyczyną, a przetwarzanie można ponowić z panelu. Krótkie klipy są gotowe w kilka minut, długie filmy trwają dłużej, a plany płatne mają priorytetową kolejkę kodowania.

Nie musisz czekać z gotową stroną. Jeśli ktoś otworzy odtwarzacz, gdy plik jest jeszcze przetwarzany, zobaczy komunikat o przetwarzaniu z postępem, a odtwarzacz sam przełączy się na wideo po zakończeniu. Mimo to przed publikacją strony sprawdź, czy status to ready, żeby pierwsi odwiedzający nie zobaczyli paska postępu.

Potrzebny będzie identyfikator wideo. Panel pokazuje go w panelu udostępniania, a API zwraca go jako public_id — krótki kod z 11 znaków. Właśnie ten kod trafia do adresu osadzenia.

Krok 2: osadź odtwarzacz za pomocą iframe

Panel podaje fragment kodu iframe zaraz po przesłaniu oraz w panelu udostępniania każdego filmu. Wygląda jak pierwszy blok poniżej. Zastąp VIDEO_ID identyfikatorem swojego filmu. Sama strona odtwarzacza nie jest indeksowana przez wyszukiwarki — i właśnie tego chcesz przy osadzaniu: pozycjonuje się Twoja strona, a nie ramka odtwarzacza.

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

Stałe rozmiary w pikselach psują się na telefonach. Na stronie responsywnej umieść iframe w kontenerze, który zachowuje proporcje 16:9, i pozwól ramce go wypełnić. Odtwarzacz wypełnia całą ramkę, więc wideo skaluje się bez problemu.

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

Parametry, które możesz dodać do adresu

• autoplay=1 uruchamia odtwarzanie po załadowaniu odtwarzacza. Przeglądarki w większości przypadków blokują autoodtwarzanie z dźwiękiem, więc łącz go z mute=1.
• mute=1 uruchamia wideo bez dźwięku; widz może włączyć dźwięk w dowolnej chwili.
• loop=1 uruchamia wideo od nowa po zakończeniu.
• t=30 rozpoczyna odtwarzanie od 30. sekundy — przydatne przy linkach do konkretnego momentu dłuższego filmu.

Parametr w adresie zawsze ma pierwszeństwo przed tym samym ustawieniem w studiu odtwarzacza. Studia odtwarzacza używaj do ustawień domyślnych obowiązujących wszędzie, takich jak skórka, kolor akcentu, logo i układ przycisków, a parametrów — gdy jedna strona ma działać inaczej. Możesz nawet utrzymywać osobny profil odtwarzacza dla każdej domeny osadzania.

Krok 3 (opcjonalny): odtwarzaj strumień przez hls.js

Iframe to najkrótsza droga, ale czasem potrzebny jest własny kod: niestandardowy pasek sterowania, wideo w karuzeli, zdarzenia analityczne z własnego kodu. Wtedy potrzebujesz adresu playlisty i biblioteki odtwarzacza. Przeglądarki inne niż Safari nie odtwarzają HLS natywnie, więc zwykle wybór pada na hls.js — bibliotekę JavaScript, która podaje segmenty HLS do standardowego elementu <video>. Safari i iOS odtwarzają HLS natywnie i jej nie potrzebują.

Adres playlisty to pole links.playback obiektu wideo. Pobieraj go po stronie serwera z kluczem API, bo klucz nigdy nie może pojawić się w kodzie przeglądarki. To samo wywołanie zwraca links.expires_at, a linki są podpisane i ograniczone w czasie, więc proś o świeży link przy każdym renderowaniu strony, zamiast zapisywać go w bazie danych.

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
}

Jeśli potrzebujesz innego czasu ważności niż domyślny, POST /files/{id}/links przyjmuje ttl od 60 sekund do 30 dni i może powiązać link z adresem IP lub ciasteczkiem. Pełny opis znajdziesz w dokumentacji API. Jest też publiczny endpoint GET /api/v1/public/files/{id}, który nie wymaga klucza; korzystają z niego strony odtwarzania i osadzenia, a jego linki są ważne przez sześć godzin.

Na stronie utwórz odtwarzacz. Poniższy blok używa hls.js tam, gdzie jest obsługiwany, w Safari przechodzi na natywne odtwarzanie, a w pozostałych przypadkach pokazuje prosty komunikat. Hostuj plik biblioteki u siebie lub przypnij konkretną wersję, zamiast ładować najnowszą, jaka akurat jest.

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

Obiekt wideo zawiera też links.poster z obrazem okładki i links.sprite z miniaturami podglądu po najechaniu, które przydadzą się, jeśli budujesz własny pasek przewijania. Z hls.js rezygnujesz z tego, co robi za Ciebie odtwarzacz UFOLOAD: menu jakości, rozdziałów, wyboru napisów, nakładki z logo oraz — gdy są dostępne — reklam. To jest prawdziwy kompromis, a tabela poniżej go podsumowuje.

iframe czy hls.js: co wybrać

Lista kontrolna rozwiązywania problemów

• Czarny ekran lub niekończące się kółko ładowania. Otwórz panel sieci w przeglądarce i znajdź master.m3u8. Kod 403 oznacza, że link wygasł albo widz jest blokowany przez regułę kraju lub IP; poproś o świeży link.
• Blokada przez przeglądarkę na stronie HTTPS. Wszystko musi działać po HTTPS. Nigdy nie wklejaj adresu http:// do iframe ani do hls.js.
• Autoodtwarzanie nie działa. Przeglądarki blokują autoodtwarzanie z dźwiękiem. Dodaj mute=1, a w hls.js ustaw video.muted = true przed wywołaniem play().
• Komunikat o przetwarzaniu zamiast wideo. Plik nie jest jeszcze gotowy. Odpytuj GET /files/{id}, aż status będzie równy ready.
• Odtwarza się tylko niska jakość. Odtwarzacz startuje ostrożnie i podnosi jakość, gdy tylko zmierzy przepustowość. Najwyższą wersję ograniczają też Twój plan i źródło; porównaj z cennikiem i stroną funkcji.

Gdy strona już działa, możesz chcieć chronić ją przed hotlinkingiem lub — gdy reklamy są dostępne — na niej zarabiać. Oba tematy omawiają kolejne poradniki: ogranicz, gdzie można osadzać Twoje wideo oraz zarabiaj na swojej stronie z wideo dzięki reklamom w odtwarzaczu. Jeśli wciąż wybierasz hosting, lista kontrolna wyboru hostingu wideo podpowiada, co porównać.