Transcodifica

Il transcoding converte un singolo file caricato in più versioni MP4 ottimizzate per il web, offrendo agli spettatori un menu di qualità, una riproduzione rapida e un codec coerente indipendentemente dal file originale. Integra inoltre elementi opzionali — filigrane e clip introduttive/finali — e genera gli sprite di anteprima di scorrimento utilizzati dal player.

Tutto si configura in /admin/settings?tab=transcode, suddiviso nelle sotto-schede Formati, Coda, Server, Filigrana, Intro e Timeline. Il transcoding può essere eseguito direttamente sul server CMS oppure distribuito a worker dedicati.

Perché effettuare il transcoding

Un file caricato senza elaborazione può avere qualsiasi risoluzione, codec o contenitore. Il transcoding lo standardizza in versioni MP4/H.264 con +faststart affinché la riproduzione inizi prima che il file sia completamente scaricato, e produce più formati (ad esempio 720p e 480p) in modo che il player possa offrire un selettore di qualità e file più leggeri per schermi più piccoli. Durante la stessa fase vengono applicate le filigrane e i clip pre/post-roll, poiché devono essere codificati in ogni versione.

La pipeline di transcoding

Quando un video è pronto per essere elaborato, TubePress accoda un job per ogni output nella tabella transcode_jobs e li processa nell'ordine:

1. Coda. Viene creato un job per la versione sorgente a piena risoluzione e per ogni formato attivo al di sotto dell'altezza sorgente, più un job timeline se le anteprime sono abilitate.
2. Acquisizione. Un worker — questo server o uno remoto — prende in carico il prossimo job in attesa, iniziando dalla versione sorgente.
3. Download. Un worker remoto scarica il sorgente via HTTP (un URL diretto autenticato con chiave che bypassa i link multimediali firmati).
4. Transcoding. FFmpeg codifica la versione, applicando il ritaglio, la filigrana e gli intro come configurato, riportando la percentuale di avanzamento.
5. Upload & callback. Il risultato viene caricato in blocchi e un callback segna il job come completato.

Lo stato del video segue questo processo: rimane in elaborazione durante l'esecuzione dei job, passa a pubblicato non appena la versione sorgente è completata, e diventa errore solo se la versione sorgente non può mai essere prodotta. Le versioni di qualità inferiore continuano a essere generate dopo la pubblicazione.

Versioni & formati

I formati di output sono completamente modificabili nella scheda Formati e memorizzati nella tabella video_formats. Ogni formato ha un nome, un suffisso file (ad esempio _720p.mp4), una risoluzione di destinazione, opzioni FFmpeg grezze, un flag mantieni proporzioni e un'attivazione. I valori predefiniti sono:

Due regole garantiscono la qualità. TubePress non scala mai verso l'alto: qualsiasi formato con risoluzione uguale o superiore all'altezza sorgente viene ignorato. E la qualità originale massima è sempre mantenuta — se è attiva una filigrana o un ritaglio, viene ricodificata in una versione sorgente a piena risoluzione (mostrata con una stella nella coda), altrimenti il file sorgente viene servito com'è. Un'opzione Ritaglio iniziale (0–300 secondi) può eliminare i primi secondi di ogni video; come la filigrana, si applica a ogni formato incluso il sorgente.

La coda dei job

La scheda Coda (/admin/settings?tab=transcode&sub=queue) raggruppa i job per video e consente di filtrare per Tutti / In attesa / In elaborazione / Completati / Falliti. Ogni video mostra un badge per ogni livello — il livello sorgente con stella, poi ogni risoluzione, poi TIMELINE — colorato in base allo stato del job:

Una console per video (l'icona del terminale) mostra in tempo reale l'elenco dei job, il worker che gestisce ogni livello, il tempo trascorso e qualsiasi messaggio di errore. Un pulsante Riprova job falliti rimette in coda tutto ciò che è attualmente fallito con un clic.

Server di transcoding remoti

Il transcoding è intensivo per la CPU, quindi è possibile spostarlo fuori dal server web. Nella scheda Server, Questo Server imposta quanti job FFmpeg vengono eseguiti localmente in contemporanea (1–4, oppure 0 per usare solo worker remoti) e consente di sovrascrivere il percorso di FFmpeg. Qui sotto si registrano i worker remoti; i job vengono distribuiti automaticamente a quello meno carico, e ciascuno ha un limite di job simultanei massimi (una buona regola è un job ogni due core CPU).

1. Aggiungi il server. Fai clic su Aggiungi Server, assegna un nome e un URL come http://YOUR-IP:8090, e salva. Vengono mostrati immediatamente una chiave API e il comando di avvio.
2. Installa FFmpeg + PHP. Sul server worker esegui sudo apt install ffmpeg php-cli php-curl.
3. Distribuisci il worker. Scarica transcode-worker.php (da /api/transcode-worker-download o tramite un link wget temporaneo), caricalo e apri la porta con sudo ufw allow 8090/tcp.
4. Avvialo. Esegui il worker con la tua chiave:

php transcode-worker.php --port=8090 --key=YOUR_API_KEY

1. Verifica. Fai clic su Controlla; un worker funzionante riporta Online con il codec rilevato e l'utilizzo in tempo reale di CPU/GPU.

L'accelerazione GPU (NVIDIA, AMD, Intel o Apple) viene rilevata e usata automaticamente. Il worker scarica il sorgente, esegue il transcoding, segnala lo stato di avanzamento e carica i risultati a blocchi nel CMS — l'upload a blocchi è ciò che mantiene ogni richiesta entro il limite di 100 MB di Cloudflare. Per i server non presidiati, la guida di configurazione include un'unità systemd affinché il worker si riavvii all'avvio.

Monitoraggio & tentativi

Il sistema è costruito in modo che un video non venga mai abbandonato silenziosamente. Una codifica fallita viene riprovata automaticamente con un intervallo crescente — da circa mezz'ora a qualche ora — perché la maggior parte degli errori è transitoria (un CDN lento o instabile). Inoltre, un'attività di ripristino oraria rimette in coda qualsiasi job ancora contrassegnato come fallito, continuando a riprovare finché la versione non è prodotta. Non è richiesto alcun intervento manuale, sebbene il pulsante Riprova job falliti sia disponibile se si desidera forzarlo.

Se il livello sorgente stesso fallisce definitivamente, i job dei sotto-formati dipendenti vengono annullati (non possono procedere senza un sorgente) e il video viene contrassegnato come errore; il ripristino continuerà comunque a tentare di recuperarlo. Quando il livello sorgente viene finalmente completato, il video viene pubblicato automaticamente.

Requisiti

FFmpeg deve essere disponibile ovunque venga eseguito il transcoding:

• Elaborazione locale: installa FFmpeg sul server CMS (sudo apt install ffmpeg). La pagina Transcoding mostra la versione rilevata una volta installata.
• Elaborazione remota: ogni worker richiede FFmpeg più php-cli e php-curl, almeno 2 core CPU e 2 GB di RAM, e una porta worker aperta.

Passi successivi