Transcodage

Le transcodage transforme un fichier uploadé en plusieurs renditions MP4 adaptées au web, offrant aux spectateurs un menu de qualité, une lecture qui démarre rapidement et un codec cohérent quelle que soit la source. Il intègre également des options supplémentaires — filigranes et clips d'intro/outro — et génère les sprites de prévisualisation utilisés par le lecteur.

Tout est configuré sous /admin/settings?tab=transcode, réparti dans les sous-onglets Formats, Queue, Servers, Watermark, Intros et Timeline. Le transcodage peut s'exécuter sur le serveur CMS lui-même ou être distribué à des workers dédiés.

Pourquoi transcoder

Un fichier brut uploadé peut avoir n'importe quelle résolution, codec ou conteneur. Le transcodage le normalise en renditions MP4/H.264 avec +faststart afin que la lecture commence avant que le fichier soit entièrement téléchargé, et produit plusieurs tailles (par exemple 720p et 480p) pour que le lecteur puisse proposer un sélecteur de qualité et servir des fichiers plus légers sur les petits écrans. C'est également lors de cette passe que les filigranes et les clips pre/post-roll sont appliqués, car ils doivent être encodés dans chaque rendition.

Le pipeline de transcodage

Lorsqu'une vidéo est prête à être traitée, TubePress ajoute un job par sortie dans la table transcode_jobs et les traite dans l'ordre :

1. File d'attente. Un job est créé pour la résolution source maximale et pour chaque format actif en dessous de la hauteur source, plus un job de timeline si les aperçus sont activés.
2. Prise en charge. Un worker — ce serveur ou un distant — prend le prochain job en attente, en commençant par la résolution source.
3. Téléchargement. Un worker distant récupère la source via HTTP (une URL directe authentifiée par clé qui contourne les liens médias signés).
4. Transcodage. FFmpeg encode la rendition, en appliquant la coupe, le filigrane et les intros selon la configuration, tout en rapportant la progression en pourcentage.
5. Upload & callback. Le résultat est renvoyé par blocs et un callback marque le job comme terminé.

Le statut de la vidéo suit cette progression : il reste à processing pendant l'exécution des jobs, passe à published dès que la résolution source est terminée, et devient error uniquement si la résolution source ne peut jamais être produite. Les renditions inférieures continuent de se compléter après la publication.

Renditions & formats

Les formats de sortie sont entièrement éditables dans l'onglet Formats et stockés dans la table video_formats. Chaque format possède un nom, un suffixe de fichier (par exemple _720p.mp4), une résolution cible, des options FFmpeg brutes, un indicateur conserver le ratio d'aspect et une bascule d'activation. Les valeurs par défaut intégrées sont :

Deux règles garantissent la qualité. TubePress ne fait jamais de mise à l'échelle supérieure : tout format à hauteur égale ou supérieure à la source est ignoré. Et la qualité source maximale est toujours conservée — si un filigrane ou une coupe est actif, il est réencodé dans une rendition source en pleine résolution (affichée avec une étoile dans la file d'attente) ; sinon, le fichier source est servi tel quel. L'option Trim start (0–300 secondes) permet de supprimer les premières secondes de chaque vidéo ; comme le filigrane, elle s'applique à tous les formats, y compris la source.

La file de jobs

L'onglet Queue (/admin/settings?tab=transcode&sub=queue) regroupe les jobs par vidéo et permet de filtrer par All / Pending / Processing / Completed / Failed. Chaque vidéo affiche un badge par niveau — le niveau source étoilé, puis chaque résolution, puis TIMELINE — coloré selon le statut du job :

Une console par vidéo (l'icône de terminal) diffuse la liste de jobs en direct, le worker traitant chaque niveau, le temps écoulé et tout message d'erreur. Un bouton Retry failed jobs remet en file d'attente tout ce qui est actuellement en échec en un seul clic.

Serveurs de transcodage distants

Le transcodage est gourmand en CPU ; vous pouvez donc le déléguer hors du serveur web. Dans l'onglet Servers, This Server définit le nombre de jobs FFmpeg exécutés localement en parallèle (1–4, ou 0 pour utiliser uniquement des workers distants) et permet de remplacer le chemin FFmpeg. En dessous, vous enregistrez des workers distants ; les jobs se répartissent automatiquement sur le moins chargé, et chacun possède une limite max concurrent jobs (une bonne règle est un job par deux cœurs CPU).

1. Ajouter le serveur. Cliquez sur Add Server, donnez-lui un nom et une URL telle que http://YOUR-IP:8090, puis enregistrez. Une clé API et la commande de démarrage sont affichées immédiatement.
2. Installer FFmpeg + PHP. Sur la machine worker, exécutez sudo apt install ffmpeg php-cli php-curl.
3. Déployer le worker. Téléchargez transcode-worker.php (depuis /api/transcode-worker-download ou un lien wget temporaire), uploadez-le, et ouvrez le port avec sudo ufw allow 8090/tcp.
4. Le démarrer. Lancez le worker avec votre clé :

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

1. Vérifier. Cliquez sur Check ; un worker opérationnel affiche Online avec son encodeur détecté et l'utilisation en direct du CPU/GPU.

L'accélération GPU (NVIDIA, AMD, Intel ou Apple) est détectée et utilisée automatiquement. Le worker récupère la source, transcode, rapporte la progression et uploade les résultats par blocs vers le CMS — l'upload par blocs est ce qui maintient chaque requête sous la limite de 100 Mo de Cloudflare. Pour les hôtes sans surveillance, le guide d'installation inclut une unité systemd afin que le worker redémarre au démarrage.

Surveillance & tentatives

Le système est conçu pour qu'une vidéo ne soit jamais abandonnée silencieusement. Un encodage échoué est automatiquement retenté avec un délai croissant — d'environ une demi-minute jusqu'à plusieurs heures — car la plupart des échecs sont transitoires (un CDN lent ou instable). De plus, une tâche de récupération horaire remet en file d'attente tout job encore marqué comme échoué, de sorte qu'il continue d'essayer jusqu'à ce que la rendition aboutisse. Aucun clic manuel n'est nécessaire, mais le bouton Retry failed jobs est disponible si vous souhaitez forcer la chose.

Si le niveau source lui-même échoue de façon permanente, les jobs de sous-formats dépendants sont annulés (ils ne peuvent pas avancer sans source) et la vidéo est marquée error ; la récupération tentera tout de même de la relancer. Lorsque le niveau source se termine enfin, la vidéo est publiée automatiquement.

Prérequis

FFmpeg doit être disponible partout où le transcodage s'exécute :

• Traitement local : installez FFmpeg sur le serveur CMS (sudo apt install ffmpeg). La page Transcode affiche la version détectée une fois installé.
• Traitement distant : chaque worker a besoin de FFmpeg ainsi que de php-cli et php-curl, d'au moins 2 cœurs CPU et 2 Go de RAM, et d'un port worker ouvert.

Prochaines étapes