Come incorporare un video HLS nel tuo sito (iframe e hls.js)

HLS (HTTP Live Streaming) è il formato che oggi la maggior parte dei siti usa per i video on demand. Invece di un enorme file MP4, il video è descritto da una piccola playlist testuale che punta a più versioni dello stesso video, ciascuna suddivisa in brevi segmenti. Il player scarica alcuni segmenti in anticipo, misura quanto velocemente arrivano e passa da una versione all'altra al volo. Chi guarda con una connessione mobile riceve una versione leggera, chi ha la fibra quella nitida, e nessuno deve aspettare il download di un intero file prima che compaia il primo fotogramma.

Questa guida mostra due modi per mettere un video HLS di UFOLOAD nella tua pagina web: il player pronto all'uso in un iframe, che richiede circa un minuto, e un tuo elemento <video> gestito da hls.js, che ti dà il pieno controllo sulla pagina. Entrambi usano lo stesso stream, quindi puoi iniziare con l'iframe e passare a hls.js in seguito senza ricaricare nulla.

Com'è fatto uno stream HLS di UFOLOAD

Dopo il caricamento di un file, il convertitore lo codifica con video H.264 e audio AAC stereo in una fino a quattro versioni, chiamate rendition: 360p, 720p, 1080p e 2160p (4K). Una rendition non è mai più grande dell'originale, quindi un caricamento a 720p produce 720p e 360p, mai un 1080p ingrandito. La rendition più alta che ottieni davvero dipende anche dal tuo piano; la pagina dei prezzi elenca i limiti attuali. Per tutti i dettagli su come vengono scelti i gradini, leggi le scale di bitrate adattivo spiegate.

Ogni rendition è memorizzata come un normale MP4 con l'indice all'inizio del file. Quando uno spettatore avvia la riproduzione, il livello di archiviazione impacchetta al volo quei file MP4 in HLS: una master playlist (master.m3u8) elenca ogni rendition con banda di picco, risoluzione e codec, e ogni rendition ha la propria playlist di segmenti da quattro secondi. I keyframe sono posizionati in modo da coincidere con i confini dei segmenti, ed è questo che permette al player di cambiare qualità in modo pulito a metà di un video.

La playlist e i segmenti vengono serviti dai nodi di cache con un'intestazione Access-Control-Allow-Origin: *, quindi un player in esecuzione sul tuo dominio può richiederli direttamente. Ogni URL è firmato e ha una scadenza, cosa che conterà più avanti quando parleremo dell'approccio con hls.js.

Passo 1: carica il video e attendi che sia pronto

Carica dalla dashboard trascinando il file o incollando un link diretto, oppure usa FTP, WebDAV o l'API (vedi caricare video tramite API per esempi in curl, Python e Node.js). Un file passa per gli stati uploading, queued, processing e ready; failed viene segnalato con un motivo e si può riprovare dalla dashboard. Le clip brevi sono pronte in pochi minuti, i film lunghi richiedono più tempo e i piani a pagamento hanno una coda di codifica prioritaria.

Non devi aspettare che la pagina sia finita. Se qualcuno apre il player mentre il file è ancora in elaborazione, viene mostrato un avviso di elaborazione con l'avanzamento e il player passa da solo al video quando l'elaborazione termina. Controlla comunque che lo stato sia ready prima di pubblicare la pagina, per non mettere online una pagina i cui primi visitatori vedono una barra di avanzamento.

Ti servirà l'identificatore del video. La dashboard lo mostra nel pannello di condivisione e l'API lo restituisce come public_id, un codice breve di 11 caratteri. È questo codice che va inserito nell'indirizzo di incorporamento.

Passo 2: incorpora il player con un iframe

La dashboard fornisce uno snippet iframe subito dopo un caricamento e nel pannello di condivisione di ogni video. Ha l'aspetto del primo blocco qui sotto. Sostituisci VIDEO_ID con l'identificatore del tuo video. La pagina del player in sé non è indicizzata dai motori di ricerca, ed è ciò che vuoi per un incorporamento: a posizionarsi è la tua pagina, non il frame del player.

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

Le dimensioni fisse in pixel non funzionano sui telefoni. Per una pagina responsive, racchiudi l'iframe in un contenitore che mantiene il rapporto 16:9 e lascia che il frame lo riempia. Il player occupa l'intero frame, quindi il video si ridimensiona in modo pulito.

<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 che puoi aggiungere all'indirizzo

• autoplay=1 avvia la riproduzione al caricamento del player. Nella maggior parte dei casi i browser bloccano l'autoplay con audio, quindi combinalo con mute=1.
• mute=1 avvia il video senza audio; lo spettatore può riattivarlo in qualsiasi momento.
• loop=1 fa ripartire il video quando finisce.
• t=30 avvia la riproduzione dal secondo 30, utile per i link diretti a un momento preciso di un video lungo.

Un parametro nell'indirizzo ha sempre la precedenza sulla stessa impostazione nello studio del player. Usa lo studio del player per i valori predefiniti validi ovunque, come skin, colore principale, logo e disposizione dei pulsanti, e usa i parametri quando una pagina deve comportarsi diversamente. Puoi anche tenere un profilo del player separato per ogni dominio di incorporamento.

Passo 3 (facoltativo): riproduci lo stream con hls.js

L'iframe è la strada più breve, ma a volte vuoi un markup tuo: una barra dei controlli personalizzata, il video dentro un carosello, eventi di analytics dal tuo codice. In quel caso ti servono l'indirizzo della playlist e una libreria per il player. I browser diversi da Safari non riproducono HLS in modo nativo, quindi la scelta abituale è hls.js, una libreria JavaScript che alimenta un normale elemento <video> con i segmenti HLS. Safari e iOS riproducono HLS in modo nativo e non ne hanno bisogno.

L'indirizzo della playlist è il campo links.playback dell'oggetto video. Richiedilo dal tuo server con una chiave API, perché la chiave non deve mai comparire nel codice del browser. La stessa chiamata restituisce links.expires_at, e i link sono firmati e a tempo limitato, quindi chiedi un link nuovo ogni volta che generi la pagina invece di salvarne uno nel database.

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
}

Se ti serve una durata diversa da quella predefinita, POST /files/{id}/links accetta un ttl da 60 secondi a 30 giorni e può legare il link a un indirizzo IP o a un cookie. La documentazione API lo descrive per intero. Esiste anche un endpoint pubblico, GET /api/v1/public/files/{id}, che non richiede chiave; lo usano le pagine di visione e di incorporamento, e i suoi link sono validi per sei ore.

Nella pagina, crea il player. Il blocco qui sotto usa hls.js dove è supportato, ripiega sulla riproduzione nativa in Safari e altrimenti mostra un semplice messaggio. Ospita tu stesso il file della libreria o fissa una versione invece di caricare sempre l'ultima disponibile.

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

L'oggetto video contiene anche links.poster per l'immagine di copertina e links.sprite per le miniature di anteprima al passaggio del mouse, utili se costruisci una tua barra di avanzamento. Con hls.js rinunci a ciò che il player UFOLOAD fa per te: menu della qualità, capitoli, scelta dei sottotitoli, logo in sovrimpressione e, quando disponibili, gli annunci. È questo il vero compromesso, e la tabella qui sotto lo riassume.

iframe o hls.js: quale usare

Checklist per la risoluzione dei problemi

• Schermo nero o caricamento infinito. Apri il pannello di rete del browser e cerca master.m3u8. Un 403 significa che il link è scaduto o che lo spettatore è bloccato da una regola per Paese o IP; richiedi un link nuovo.
• Bloccato dal browser in una pagina HTTPS. Tutto deve essere HTTPS. Non incollare mai un indirizzo http:// nell'iframe o in hls.js.
• L'autoplay non fa nulla. L'autoplay con audio è bloccato dai browser. Aggiungi mute=1, oppure in hls.js imposta video.muted = true prima di chiamare play().
• Avviso di elaborazione invece del video. Il file non è ancora pronto. Interroga GET /files/{id} finché status non è ready.
• Viene riprodotta solo una qualità bassa. Il player parte in modo prudente e sale non appena ha misurato la velocità. Anche il piano e l'originale limitano la rendition più alta; confronta con i prezzi e la pagina delle funzioni.

Quando la pagina funziona, potresti volerla proteggere dall'hotlinking o, quando gli annunci sono disponibili, guadagnarci. Entrambi gli argomenti sono trattati nelle prossime guide: limitare dove il tuo video può essere incorporato e monetizzare il tuo sito video con annunci nel player. Se stai ancora decidendo dove ospitare i video, la checklist per l'hosting video elenca cosa confrontare.