reel-subs

reel-subs — sous-titres et animations pour reels

Vous transformez un montage talking-head terminé (exporté depuis CapCut / Premiere / téléphone) en un reel avec sous-titres phrase par phrase et animations graphiques propres. Tout s'exécute localement sur la machine de l'utilisateur.

Comment ça marche : parole → mots avec timings (sherpa-onnx, hors ligne) → vous écrivez edit.json (sous-titres + éléments graphiques) → Remotion rend UNIQUEMENT une couche graphique transparente → ffmpeg la superpose à la source intacte en conservant ses propres tags de couleur. Ne rendez jamais la vidéo entière via Remotion : cela ré-encode avec une matrice de couleurs différente et les tons de peau se décalent.

SKILL_DIR ci-dessous = le dossier contenant ce fichier. ENGINE = ~/.reel-subs/engine (sur Windows %USERPROFILE%\.reel-subs\engine ; ou $REELS_HOME/engine si cette variable d'environnement est définie). Tous les scripts sont du Node simple — exécutez-les avec node, de la même façon sur macOS, Windows et Linux.

Parlez à l'utilisateur dans sa langue. Répondez dans la langue que l'utilisateur utilise pour vous écrire (généralement le russe), même si ce fichier est en anglais : lignes de progression, questions, erreurs, résumé final. Les commandes, chemins et clés JSON restent tels quels.

Lisez d'abord les préférences de l'utilisateur. Si ~/.reel-subs/preferences.md existe (ou $REELS_HOME/preferences.md), lisez-le avant l'étape 1 et suivez-le : il contient ce que l'utilisateur a demandé lors de sessions précédentes et il remplace les valeurs par défaut de ce fichier. Voir "Apprendre les goûts de l'utilisateur" ci-dessous.

0. Configuration (première fois, ou quand doctor dit PAS PRÊT)

node SKILL_DIR/scripts/setup.mjs            # Modèle vocal russe (par défaut)
node SKILL_DIR/scripts/setup.mjs --lang multi   # Anglais + 24 langues européennes

Nécessite uniquement Node.js 18+. Si node est manquant, dites à l'utilisateur d'installer la LTS depuis nodejs.org (macOS : brew install node fonctionne aussi ; Windows : winget install OpenJS.NodeJS.LTS) et arrêtez. La configuration copie le moteur vers ENGINE, exécute npm install (Remotion, binaires ffmpeg/ffprobe, sherpa-onnx), télécharge le modèle vocal (~170 Mo ru / ~490 Mo multi) et Chrome sans tête. Elle est idempotente. Prend 2 à 5 minutes la première fois — dites-le en une ligne. Elle se termine par PRÊT.

Si elle affiche ✗ navigateur sans tête : le téléchargement de Chrome par Remotion est bloqué sur ce réseau et aucun Chrome/Edge installé n'a été trouvé → demandez à l'utilisateur d'installer Google Chrome, puis relancez la configuration.

1. Préparation

node ENGINE/scripts/prepare.mjs "<video>" [--lang ru|multi] [--audio clean_voice.wav]

• --lang : ru (GigaAM, meilleur pour le russe) ou multi (anglais, allemand, espagnol, français, ukrainien…). Choisissez selon la langue parlée dans la vidéo ; ne demandez que si ce n'est pas clair. Les modèles manquants se téléchargent automatiquement.
• --audio : si l'utilisateur a une piste vocale nettoyée (Auphonic, Adobe Podcast…), utilisez-la — meilleure reconnaissance, et le rendu l'intègre dans la vidéo finale.
• Crée <nom vidéo>.reels/ à côté de la vidéo : transcript.txt, words.json, edit.json (brouillon).
• S'arrête sur une vidéo HDR avec une explication (superposer sur du HDR décale les couleurs) — transmettez-la à l'utilisateur.

2. Comprendre la vidéo

1. Lisez transcript.txt (phrases avec timecodes) et parcourez words.json pour les temps exacts des mots.
2. Regardez les images : node ENGINE/scripts/look.mjs "<video>" --every 1 → ouvrez l'image de la planche. Notez où se trouve le visage (haut / milieu), où les mains gestuent, où un écran / produit est montré, où se produisent les coupes. Pour une vidéo longue, faites la planche par parties (--from 0 --to 30).

3. Corriger les sous-titres (edit.json → captions)

Les pages du brouillon sont déjà divisées par phrase (~2 s, ≤ 32 caractères). Votre travail :

• Corriger les erreurs de reconnaissance : noms de produits, termes anglais, nombres (четыре бакса → $4), orthographe des marques. La reconnaissance n'a pas de ponctuation — n'ajoutez que ce qui aide à la lecture, surtout rien.
• Gardez les propres mots et la langue du locuteur ; ne traduisez pas sauf demande.
• Fusionnez/divisez les pages pour que chacune soit une phrase naturelle. Gardez startMs/endMs alignés sur words.json.
• Balisage dans le texte des sous-titres : *mot* → couleur d'accent (rarement, pour le mot clé), ~mot~ → rouge (un lapsus que le locuteur souligne).
• Listez les mots dont vous n'étiez pas sûr dans votre message final plutôt que de deviner en silence.

4. Planifier les graphiques (edit.json → items)

Référence complète des champs avec exemples : SKILL_DIR/reference/edit-schema.md — lisez-la avant d'écrire les éléments.

• hook — les 2 à 4 premières secondes, jusqu'à la première coupe ou blague : l'essence de la vidéo en une courte ligne, dans la langue du locuteur. Les sous-titres se cachent automatiquement pendant qu'il est affiché.
• card — un point clé : label (petites majuscules) + title et/ou chips qui apparaissent sur les mots qu'ils illustrent (at), on: true pour la puce résultat, strikeAt pour barrer quelque chose.
• big — un nombre ou un mot que le locuteur souligne ("1$", "5000").
• terminal — seulement quand on parle de code, d'agents, de commandes.
• punch — une blague / auto-dérision : a est barré, b apparaît en grand. Les sous-titres se cachent automatiquement.
• pop — petits widgets HUD qui apparaissent à côté des mains quand le locuteur fait un geste ("et ces animations vont…"). Placez-les ~0,3 s avant le mot : les timings reconnus ont un décalage.
• badge — une étiquette persistante en haut à gauche (numéro d'épisode, etc.), seulement si l'utilisateur en veut un.

Règles :

• Ne couvrez jamais le visage. Les fiches sont par défaut dans le tiers supérieur (top: 260). Si le visage est dans la moitié supérieure du cadre, utilisez top: 1110 (bas). Ne couvrez pas non plus ce que le locuteur montre du doigt.
• Tout reste dans la zone de sécurité (les fiches font 840 px de large, centrées) — ne déplacez pas les choses vers les bords.
• Densité : en moyenne un graphique toutes les 5 à 10 secondes, synchronisé avec les mots. Pas de sous-titres dans des boîtes qui répètent ce qui est dit, pas d'explication de l'évidence, pas de mouvement sautillant/enfantin.
• Première mention d'un produit/projet : la fiche doit dire ce que c'est en quelques mots — les spectateurs sont nouveaux.
• Les temps sont en secondes dans la vidéo source. Les éléments peuvent chevaucher les sous-titres ; hook/punch les cachent.
• N'inventez pas de faits : les chips et fiches disent exactement ce que dit le locuteur.

5. Prévisualisation — regardez toujours avant le rendu complet

node ENGINE/scripts/preview.mjs "<work>/edit.json"            # une image dans chaque élément
node ENGINE/scripts/preview.mjs "<work>/edit.json" --at 1.2,7,15

Ouvrez previews/sheet.jpg (et les at_<t>.jpg individuelles si nécessaire). Vérifiez : visage dégagé, texte adapté, rien ne touche les bords, sous-titres lisibles. Corrigez edit.json et prévisualisez à nouveau. ~10–30 s par exécution.

6. Rendu

node ENGINE/scripts/render.mjs "<work>/edit.json" [--out file.mp4]

~1–4 min par minute de vidéo. La sortie par défaut est <nom vidéo>_final.mp4 à côté de la source. Il affiche le nombre d'images de sortie par rapport à la source — si ça indique DÉCALAGE, dites-le à l'utilisateur. Ensuite, donnez à l'utilisateur : le chemin de sortie, un résumé de 2–3 lignes de ce que vous avez ajouté, les mots douteux.

Révisions

Modifiez edit.json → prévisualisez les moments modifiés → rendez à nouveau. Ne relancez jamais prepare.mjs --force après que l'utilisateur a approuvé les sous-titres (cela les réinitialiserait). Copiez edit.json avant les gros changements.

Apprendre les goûts de l'utilisateur

La compétence doit s'améliorer pour cet utilisateur à chaque fois. Ses notes se trouvent dans ~/.reel-subs/preferences.md ($REELS_HOME/preferences.md si défini) — en dehors du dossier de la compétence et en dehors de ENGINE, de sorte que la mise à jour de la compétence ou la réexécution de la configuration ne les efface jamais.

Quand proposer d'enregistrer :

• L'utilisateur corrige deux fois le même type de chose (police, couleurs, taille ou position des sous-titres, quantité de graphiques, formulation de l'accroche, quels mots reçoivent l'accent…).
• L'utilisateur dit quelque chose comme « запомни », « в следующий раз делай так », « мне так больше нравится ».
• À la fin d'une session avec révisions : listez les corrections en 2–4 courtes lignes et demandez une fois s'il faut les enregistrer pour la prochaine fois.

Comment :

• Demandez toujours d'abord, montrez exactement ce que vous allez écrire, n'écrivez qu'après un oui. N'enregistrez jamais tout seul.
• Écrivez des règles, pas un historique : « Taille des sous-titres plus grande : captionSize 60 », « Accroche sans emoji », « Pas plus d'une fiche toutes les 10 s ». Regroupez-les sous de courts titres (Style, Sous-titres, Graphiques, Formulation). Mettez à jour ou supprimez une ancienne règle plutôt que d'en ajouter une contradictoire.
• Les valeurs de style que edit.json → style prend en charge doivent être mises en tant que valeurs exactes, afin que vous puissiez les copier dans chaque nouveau edit.json.
• Si un souhait nécessite une modification de code (une nouvelle police, une nouvelle animation, un aspect de fiche différent), faites-la dans ENGINE/src/ et enregistrez-la également sous Modifications du moteur dans preferences.md : quel fichier, quoi a changé, pourquoi. La configuration copie à nouveau le moteur et écrase les fichiers modifiés (les nouveaux fichiers survivent), donc après chaque exécution de configuration, vérifiez cette liste et réappliquez ce qui manque.
• L'utilisateur peut aussi modifier preferences.md manuellement ou simplement vous dire quoi y changer.

Personnalisation

• Couleurs / tailles : edit.json → style (accent, captionSize, captionTop, font).
• Nouveaux types de graphiques : ajoutez un composant dans ENGINE/src/components/, un type dans src/types.ts et un cas dans src/Overlay.tsx — le bundle se reconstruit automatiquement à la prochaine prévisualisation. Gardez la couche transparente (pas d'arrière-plan, pas de vidéo dans Remotion).
• npm run studio dans ENGINE ouvre Remotion Studio pour des réglages en direct.

Dépannage

• doctor : node ENGINE/scripts/doctor.mjs — affiche ✓/✗ pour chaque dépendance.
• Avertissement de fréquence d'images variable → demandez à l'utilisateur d'exporter à 30 ou 60 ips constantes.
• Pas du 9:16 → les graphiques sont conçus pour une vidéo verticale ; ils sont mis à l'échelle pour s'adapter, mais dites-le.
• Windows : utilisez les mêmes commandes ; mettez les chemins avec espaces entre guillemets. PowerShell et cmd fonctionnent tous les deux.
• Rien n'est téléchargé nulle part : les modèles et Chrome sont téléchargés une fois, puis tout s'exécute hors ligne.