L’encodage vidéo, distribué sur vos machines Distributed video transcoding, on your own machines

RoutageRouting

Une ferme d’encodage n’est pas une file d’attente An encode farm is not a queue

Une déclaration de capacité est un résultat de sonde, jamais une promesse. A capability declaration is a probe result, never a promise.

Un agent ne promet rien. En se connectant, il sonde son propre hôte et déclare ce qu’il a observé : les codecs que son ffmpeg sait produire, les formats qu’il sait ouvrir, les opérations qu’il sait exécuter, les stockages qu’il atteint réellement. An agent promises nothing. On connecting it probes its own host and declares what it observed: the codecs its ffmpeg can produce, the formats it can open, the operations it can perform, the storages it actually reaches.

Les jokers (*) sont refusés à la connexion. Un axe manquant est refusé lui aussi. Wildcards (*) are refused at connection. A missing axis is refused too.

Vous n’écrivez jamais « envoie ça sur le Mac de montage ». Vous décrivez le travail, et il part là où il peut être fait. You never write “send that to the edit Mac”. You describe the work, and it goes where it can be done.

Un stockage qui n’est pas monté fait disparaître son identifiant à la connexion, et l’agent n’est plus servi dessus. L’erreur apparaît au démarrage, pas au milieu d’un encodage. A storage that is not mounted makes its identifier disappear at connection, and the agent is never served on it again. The error surfaces at startup, not halfway through an encode.

OpérationsOperations

Cinq opérations Five operations

Les vignettes sont produites pendant l’encodage, pas après. Sur un RED de 41 minutes, la fiche reçoit ses images dans la première minute. Stills are produced while the encode runs, not after it. On a 41-minute RED clip, the item page has its thumbnails within the first minute.

Un job porte de 1 à 10 jeux d’images : placement par every_seconds, count ou times explicites ; cadrage contain, letterbox, crop ou stretch ; sortie jpeg ou png, en fichiers séparés ou en planche contact. A job carries 1 to 10 still sets: placement by every_seconds, count or explicit times; framing contain, letterbox, crop or stretch; jpeg or png output, as separate files or as one contact-sheet grid.

Modèle de soumissionSubmission model

Vous dites quel flux alimente quelle piste You say which stream feeds which track

Vous déclarez chaque fichier une fois, puis vous dites quel flux de quel fichier alimente quelle piste de sortie. Comme les -map de ffmpeg. You declare each file once, then say which stream of which file feeds which output track. Like ffmpeg’s -map.

Il n’y a aucune règle implicite : le premier fichier n’est pas « la vidéo ». Rien n’est deviné. There is no implicit rule such as “the first file is the video”. Nothing is guessed.

Un job est une chaîne d’opérations ordonnée par un entier — le step — et non un graphe. Les steps 10 / 20 / 30 sont le cas courant. La requête complète est plus bas. A job is a chain of operations ordered by an integer — the step — not a graph. Steps 10 / 20 / 30 are the common case. The full request is further down.

ArchitectureArchitecture

Le média ne passe jamais par le serveur Media never passes through the server

Le média ne passe jamais par le serveur. L’orchestrateur tient l’état et distribue des références ; les agents lisent et écrivent le stockage directement. Media never passes through the server. The orchestrator holds state and dispatches references; agents read and write shared storage directly.

1. Un média est adressé par identifiant de stockage et chemin relatif, jamais par un chemin absolu. C’est ce qui permet à des agents macOS, Linux et Windows de partager une même file. Media is addressed by storage identifier plus relative path, never an absolute path. That is what lets macOS, Linux and Windows agents share one queue.
2. Une déclaration de capacité est un résultat de sonde, jamais une promesse. A capability declaration is a probe result, never a promise.
3. Une tâche par agent à la fois. One task per agent at a time.
4. La politique de sélection tient derrière une seule couture : pour un transcode, la déclaration la plus étroite gagne — le spécialiste ; pour toute autre opération, la plus large gagne, sinon une simple copie de flux monopoliserait la seule machine capable de décoder du RED. Selection policy sits behind a single seam: for a transcode the narrowest declaration wins — the specialist; for any other operation the broadest wins, otherwise a plain stream copy would monopolise the only machine that can decode RED.

Une ligne pour laquelle aucun agent capable n’est connecté est garée — WAITING, parked_reason: no_capable_agent — et re-proposée dès qu’un agent capable se connecte. Une tâche garée n’est pas une tâche en échec. A line with no capable agent connected is parked — WAITING, parked_reason: no_capable_agent — and re-offered as soon as a capable agent connects. A parked task is not a failed task.

Le décodage RED, et pourquoi il vit dans son propre processus RED decoding, and why it lives in its own process

ffmpeg annonce un démuxeur r3d mais ne porte aucun décodeur REDCODE. Le SDK de RED est une bibliothèque statique propriétaire : la lier dans un ffmpeg GPL/LGPL produirait un binaire non redistribuable. Forge met donc le décodage dans son propre processus, r3ddump, et garde un ffmpeg d’origine. La frontière de licence est la raison d’être de ce composant. ffmpeg lists an r3d demuxer but carries no REDCODE decoder. RED’s SDK is a proprietary static library: linking it into a GPL/LGPL ffmpeg would produce a non-redistributable binary. Forge therefore puts decoding in its own process, r3ddump, and keeps a stock ffmpeg. The licence boundary is the reason this component exists.

Le SDK RED n’est pas dans le dépôt et n’y sera jamais : la licence de RED interdit d’en redistribuer les en-têtes et les bibliothèques. Un intégrateur doit en obtenir une copie auprès de RED et pointer la compilation dessus. The RED SDK is not in the repository and never will be: RED’s licence forbids redistributing its headers and libraries. An integrator must obtain a copy from RED and point the build at it.

MesuresNumbers

Mesuré, pas estimé Measured, not estimated

Les chiffres viennent de travaux réels, datés, sur du matériel nommé. Sur un même clip, le décodage RED passe de sept minutes à quarante-deux secondes dès que Metal prend la main. These figures come from real jobs, dated, on named hardware. On the same clip, RED decoding goes from seven minutes to forty-two seconds once Metal takes over.

Aucun chiffre ne sort d’ici sans sa date et ses conditions. C’est la seule liste publiée : le projet mesure au lieu de supposer, et cinq lignes suffisent à le montrer. No figure leaves this table without its date and its conditions. It is the only published list: the project measures instead of assuming, and five rows are enough to show it.

Tolérance aux pannesFault tolerance

Une machine qui tombe ne coûte rien A machine that dies costs nothing

Le travail est tenu sous bail, pas assigné. Une machine qui s’éteint rend sa tâche à la file toute seule — et aucun fichier incomplet n’apparaît jamais au chemin final. Work is held under a lease, not assigned. A machine that goes down returns its task to the queue on its own — and no partial file ever appears at the final output path.

1. Le bail expire. Une tâche n’est jamais la propriété d’une machine : elle lui est prêtée pour un temps. The lease expires. A task is never a machine’s property: it is lent to it for a while.
2. La tâche retourne à la file d’elle-même, sans intervention et sans qu’un opérateur ait à constater la panne. The task returns to the queue on its own, with no intervention and with no operator having to notice the failure.
3. Rien n’est écrit au chemin final avant d’être complet : un encodage interrompu ne laisse pas un prores tronqué là où un monteur attend un livrable. Nothing is written to the final path before it is complete: an interrupted encode does not leave a truncated prores where an editor expects a deliverable.

IntégrationIntegrating

Une requête HTTP One HTTP request

Soumettre un travail, c’est un POST et un corps JSON. Vous déclarez les fichiers, vous dites quel flux alimente quelle piste, et la file s’occupe du reste. Handing work to Forge is one POST and a JSON body. You declare the files, you say which stream feeds which track, and the queue takes it from there.

curl -X POST http://<hôte>:8000/api/tasks/ \
  -H "Authorization: Bearer $PAD_FORGE_CLIENT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "inputs": {"interview": {"storage": "rushes", "path": "footage/interview.mov"}},
    "video": [{"v": "interview:v:0", "a": ["interview:a:0"]}],
    "output_settings": {
      "storage": "proxies",
      "path": "interview_1080p.mp4",
      "codec": "h264",
      "container": "mp4",
      "resolution": "1920x1080",
      "bitrate": 5000
    }
  }'

{
  "inputs": {
    "v1":  {"storage": "rushes", "path": "day1/clip1.mov"},
    "a11": {"storage": "rushes", "path": "day1/clip1_ch1.wav"},
    "a12": {"storage": "rushes", "path": "day1/clip1_ch2.wav"},
    "v2":  {"storage": "rushes", "path": "day1/clip2.mov"},
    "a21": {"storage": "rushes", "path": "day1/clip2_ch1.wav"},
    "a22": {"storage": "rushes", "path": "day1/clip2_ch2.wav"},
    "mix": {"storage": "rushes", "path": "sound/mix.wav"}
  },
  "video": [
    {"v": "v1:v:0", "a": ["a11:a:0", "a12:a:0"]},
    {"v": "v2:v:0", "a": ["a21:a:0", "a22:a:0"]}
  ],
  "audio": [["mix:a:0"]],
  "output_settings": {
    "storage": "proxies", "path": "out/day1.mp4",
    "codec": "h264", "container": "mp4", "resolution": "1920x1080"
  }
}

Les hôtes s’écrivent <hôte> ou localhost : aucune adresse réelle n’apparaît ici. Hosts are written <hôte> or localhost: no real address appears here.

• L’authentification est un jeton partagé porté par Authorization: Bearer — un jeton d’agent pour la connexion WebSocket, un jeton de client pour les écritures via l’API. Une connexion WebSocket sans jeton est refusée avant qu’un état d’agent n’existe. Authentication is a shared token carried as Authorization: Bearer — an agent token for the WebSocket connection, a client token for writes through the API. A WebSocket connection with no token is refused before any agent state exists.
• client_ref est la référence du système appelant, stockée telle quelle sur chaque ligne du job. C’est la clé de relecture et d’idempotence côté intégrateur. client_ref is the calling system’s own reference, stored verbatim on every row of the job. It is the read-back and idempotency key on the integrator’s side.
• Ni bitrate ni crf n’a de valeur par défaut : sans l’un des deux, c’est le défaut de l’encodeur qui s’applique. C’est une décision, pas un oubli. Neither bitrate nor crf has a default: without one of the two, the encoder’s own default runs. That is a decision, not an oversight.
• Le contrat complet est docs/client-protocol.md, en français, environ 1 700 lignes, vérifié contre le code — et son client de référence est exécuté à chaque make test. The full contract is docs/client-protocol.md, in French, around 1,700 lines, verified against the code — and its reference client is executed on every make test.
• Forge est intégré à l’écosystème de PAD par un plugin côté MAM : Cantemo, édité par Codemill. C’est un fait côté PAD, pas une fonctionnalité supportée de Forge. Forge is integrated into PAD’s ecosystem through a plugin on the MAM side: Cantemo, published by Codemill. That is a fact on PAD’s side, not a supported Forge feature.

DéploiementDeploying

Un git push pour le serveur, un launchd par machine One git push for the server, one launchd per machine

Les agents de production ne tournent pas dans Docker. Docker Compose est le chemin de développement : il lève l’orchestrateur, le dashboard et trois agents d’un coup. En production, l’agent est un LaunchAgent natif, parce qu’un conteneur entre l’encodeur et le NAS coûte du débit. Production agents do not run in Docker. Docker Compose is the development path: it brings up the orchestrator, the dashboard and three agents at once. In production the agent is a native LaunchAgent, because a container between the encoder and the NAS costs throughput.

État du projetProject status

Où en est Forge Project status

Ouvrir le code est envisagé. Rien n’est arrêté : ni les modalités, ni le calendrier. Opening the code up is being considered. Nothing is settled: neither the terms nor the timing.