Cum încorporezi un videoclip HLS pe site (iframe și hls.js)

HLS (HTTP Live Streaming) este formatul folosit astăzi de majoritatea site-urilor pentru video la cerere. În locul unui fișier MP4 uriaș, videoclipul este descris de un mic playlist text care indică mai multe versiuni ale aceluiași videoclip, fiecare tăiată în segmente scurte. Playerul descarcă câteva segmente în avans, măsoară cât de repede sosesc și comută între versiuni din mers. Spectatorii pe o conexiune de telefon primesc o versiune ușoară, cei pe fibră optică pe cea clară și nimeni nu așteaptă descărcarea unui fișier întreg înainte să apară primul cadru.

Acest ghid arată două moduri de a pune un videoclip HLS de pe UFOLOAD pe propria pagină web: playerul gata făcut într-un iframe, care durează cam un minut, și propriul element <video> controlat de hls.js, care îți dă control deplin asupra paginii. Ambele folosesc același flux, așa că poți începe cu iframe-ul și trece mai târziu la hls.js fără să reîncarci nimic.

Cum arată un flux HLS de la UFOLOAD

După ce încarci un fișier, convertorul îl codează cu video H.264 și audio stereo AAC în una până la patru versiuni, numite variante: 360p, 720p, 1080p și 2160p (4K). O variantă nu este niciodată mai mare decât sursa, așa că o încărcare 720p produce 720p și 360p, niciodată un 1080p mărit artificial. Varianta cea mai înaltă pe care o primești efectiv depinde și de plan; pagina de prețuri arată limitele actuale. Dacă vrei tot contextul despre cum sunt alese treptele, citește scările de bitrate adaptiv pe înțeles.

Fiecare variantă este stocată ca MP4 obișnuit, cu indexul la începutul fișierului. Când un spectator pornește redarea, nivelul de stocare împachetează din mers aceste fișiere MP4 în HLS: un playlist master (master.m3u8) enumeră fiecare variantă cu lățimea de bandă de vârf, rezoluția și codecurile, iar fiecare variantă are propriul playlist de segmente de patru secunde. Cadrele cheie sunt plasate astfel încât să coincidă cu granițele segmentelor, ceea ce îi permite playerului să schimbe curat calitatea în mijlocul unui videoclip.

Playlistul și segmentele sunt servite din noduri cache cu antetul Access-Control-Allow-Origin: *, așa că un player care rulează pe domeniul tău le poate cere direct. Fiecare URL este semnat și are o dată de expirare, ceea ce contează mai târziu, când vorbim despre varianta cu hls.js.

Pasul 1: încarcă videoclipul și așteaptă să fie gata

Încarcă din panou trăgând fișierul sau lipind un link direct ori folosește FTP, WebDAV sau API-ul (vezi încărcarea videoclipurilor prin API pentru exemple în curl, Python și Node.js). Un fișier trece prin stările uploading, queued, processing și ready; failed este raportat cu un motiv și poate fi reîncercat din panou. Clipurile scurte sunt gata în câteva minute, filmele lungi durează mai mult, iar planurile plătite au o coadă de codare prioritară.

Nu trebuie să aștepți ca pagina să fie terminată. Dacă cineva deschide playerul cât timp fișierul este încă în procesare, acesta afișează un anunț de procesare cu progresul și trece singur la videoclip când procesarea se încheie. Totuși, verifică dacă starea este ready înainte să publici pagina, ca primii vizitatori să nu vadă o bară de progres.

Vei avea nevoie de identificatorul videoclipului. Panoul îl afișează în panoul de partajare, iar API-ul îl returnează ca public_id, un cod scurt de 11 caractere. Acest cod intră în adresa de încorporare.

Pasul 2: încorporează playerul cu un iframe

Panoul îți oferă un fragment iframe imediat după încărcare și în panoul de partajare al fiecărui videoclip. Arată ca primul bloc de mai jos. Înlocuiește VIDEO_ID cu identificatorul videoclipului tău. Pagina playerului în sine nu este indexată de motoarele de căutare, exact ce îți dorești la o încorporare: în rezultate apare pagina ta, nu cadrul playerului.

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

Dimensiunile fixe în pixeli se strică pe telefoane. Pentru o pagină responsive, pune iframe-ul într-un container care păstrează raportul 16:9 și lasă cadrul să-l umple. Playerul umple întregul cadru, așa că videoclipul se scalează curat.

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

Parametri pe care îi poți adăuga la adresă

• autoplay=1 pornește redarea când se încarcă playerul. În majoritatea cazurilor browserele blochează redarea automată cu sunet, așa că folosește-l împreună cu mute=1.
• mute=1 pornește videoclipul fără sunet; spectatorul poate activa sunetul oricând.
• loop=1 reia videoclipul de la început când se termină.
• t=30 pornește redarea de la secunda 30, util pentru linkuri directe către un moment dintr-un videoclip mai lung.

Un parametru din adresă are mereu prioritate față de aceeași setare din studioul playerului. Folosește studioul playerului pentru valorile implicite valabile peste tot, precum tema, culoarea de accent, logoul și aranjarea butoanelor, și parametrii când o anumită pagină trebuie să se comporte altfel. Poți chiar păstra un profil de player separat pentru fiecare domeniu de încorporare.

Pasul 3 (opțional): redă fluxul cu hls.js

Iframe-ul este calea cea mai scurtă, dar uneori vrei propriul cod: o bară de control personalizată, videoclipul într-un carusel, evenimente de analiză din propriul cod. Atunci ai nevoie de adresa playlistului și de o bibliotecă de player. Browserele în afară de Safari nu pot reda HLS nativ, așa că alegerea obișnuită este hls.js, o bibliotecă JavaScript care alimentează un element <video> standard cu segmente HLS. Safari și iOS redau HLS nativ și nu au nevoie de ea.

Adresa playlistului este câmpul links.playback al obiectului video. Cere-o de pe serverul tău cu o cheie API, pentru că cheia nu trebuie să apară niciodată în codul din browser. Același apel returnează links.expires_at, iar linkurile sunt semnate și limitate în timp, așa că cere un link nou de fiecare dată când generezi pagina, în loc să salvezi unul în baza de date.

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
}

Dacă ai nevoie de altă valabilitate decât cea implicită, POST /files/{id}/links acceptă un ttl între 60 de secunde și 30 de zile și poate lega linkul de o adresă IP sau de un cookie. Documentația API îl descrie complet. Există și un endpoint public, GET /api/v1/public/files/{id}, care nu necesită cheie; îl folosesc paginile de vizionare și de încorporare, iar linkurile lui sunt valabile șase ore.

Pe pagină, creează playerul. Blocul de mai jos folosește hls.js acolo unde este suportat, trece la redarea nativă în Safari și altfel afișează un simplu mesaj. Găzduiește singur fișierul bibliotecii sau fixează o versiune, în loc să încarci ce e mai nou.

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

Obiectul video conține și links.poster pentru imaginea de copertă și links.sprite pentru miniaturile de previzualizare la hover, pe care le poți folosi dacă îți construiești propria bară de derulare. Cu hls.js renunți la ce face pentru tine playerul UFOLOAD: meniul de calitate, capitolele, alegerea subtitrărilor, logoul suprapus și, când reclamele sunt disponibile, reclamele. Acesta este compromisul real, iar tabelul de mai jos îl rezumă.

iframe sau hls.js: pe care să-l folosești

Listă de depanare

• Cadru negru sau cerc care se învârte la nesfârșit. Deschide panoul de rețea al browserului și caută master.m3u8. Un 403 înseamnă că linkul a expirat sau că spectatorul este blocat de o regulă pe țară sau IP; cere un link nou.
• Blocat de browser pe o pagină HTTPS. Totul trebuie să fie HTTPS. Nu lipi niciodată o adresă http:// în iframe sau în hls.js.
• Redarea automată nu face nimic. Browserele blochează redarea automată cu sunet. Adaugă mute=1 sau, în hls.js, setează video.muted = true înainte să apelezi play().
• Anunț de procesare în loc de videoclip. Fișierul nu este încă gata. Interoghează GET /files/{id} până când status devine ready.
• Se redă doar o calitate scăzută. Playerul pornește prudent și urcă de îndată ce a măsurat debitul. Planul și sursa limitează și ele varianta de sus; compară cu prețurile și cu pagina de funcții.

Odată ce pagina funcționează, poate vrei s-o protejezi de hotlinking sau, când reclamele sunt disponibile, să câștigi din ea. Ambele subiecte sunt tratate în ghidurile următoare: restricționează unde poate fi încorporat videoclipul și monetizează-ți site-ul video cu reclame în player. Dacă încă decizi unde să găzduiești, lista de verificare pentru găzduirea video enumeră ce să compari.