sridhar-raj/video-craft

Artisanat vidéo

Deux métiers, un même standard. Montez des rushes enregistrés, ou créez un film à partir d'une charte graphique et d'un texte. Dans les deux cas, le travail est planifié avant d'être rendu, rendu par des scripts exacts, et vérifié par des mesures avant que quiconque soit informé qu'il est terminé.

Ce qui rend une vidéo professionnelle, dans l'ordre :

1. Structure. Un accroche dans les 3 premières secondes, une idée, rien qui ne mérite son temps.
2. Rythme. Les coupes et les mouvements tombent sur la parole et sur le temps ; rien n'est mort, rien ne précipite.
3. Détails techniques. Un filet d'air autour de chaque coupe, des sous-titres qui se lisent, des animations qui décélèrent en place, un son assez fort et qui n'écrête jamais.
4. Preuve. qa.py passe et la planche contact a été regardée.

Parcours rapide

La demande	Faire
"Resserrer / nettoyer cet enregistrement"	transcrire → plan_cuts → réviser EDL → rendre → qa
"Faire un Short/Reel/TikTok à partir de ça"	comme ci-dessus, plus captions.py --style punch, render.py --preset shorts --fit crop (ou blur pour les captures d'écran)
"Ajouter des sous-titres"	transcribe.py → captions.py → render.py --captions (ou livrer le .srt)
"Ajouter de la musique"	render.py --music bed.mp3 (automatiquement en fondu sous la voix)
"Rendre le son assez fort / corriger l'audio"	render.py --voice --denoise, cible dans platforms.md
"Intro de marque / logo animé / jingle"	copier films/brand-sting, remplir la charte, stills → brouillon → maître → qa
"Vidéo de lancement / promo / pub"	copier films/launch, écrire le texte, choisir les formats, stills → brouillon → maître → qa
"Vérifier cette vidéo"	qa.py video.mp4 --sheet sheet.jpg [--safe]
Projet déjà sur Remotion	references/remotion.md

Prérequis

ffmpeg 6+ et Python 3.9+ pour le montage. Transcription : pip install faster-whisper (ou openai-whisper, ou whisper.cpp). Films : Node 18+ et Playwright (npm i -D playwright && npx playwright install chromium). Les sous-titres sont gravés avec libass si ffmpeg le permet, sinon dessinés avec Pillow (pip install pillow). Lancez python3 scripts/doctor.py pour voir ce qui est installé.

Tous les scripts acceptent --help. Travaillez dans un dossier par projet : work/ pour les fichiers intermédiaires, out/ pour les livrables.

Montage de rushes

python3 scripts/transcribe.py raw.mp4 -o work/words.json            # transcription mot-à-mot
python3 scripts/plan_cuts.py raw.mp4 --words work/words.json -o work/edl.json
python3 scripts/captions.py work/words.json --edl work/edl.json --style clean -o work/cap
python3 scripts/render.py work/edl.json -o out/final.mp4 --preset youtube \
        --captions work/cap.cues.json --music bed.mp3 --voice --zoom auto
python3 scripts/qa.py out/final.mp4 --edl work/edl.json --sheet out/sheet.jpg \
        --words work/words.json --words-check

1. Lisez d'abord la transcription et décidez de la structure : ce qui part entièrement (les coupes entre sections se lisent proprement ; les coupes en milieu de phrase donnent une impression de nervosité), et ce qui est l'accroche. Placez les décisions de sections entières manuellement dans les segments de l'EDL si nécessaire.
2. plan_cuts.py supprime les silences (réduits à une respiration, pas à zéro), les tics et les reprises abandonnées (garde la dernière prise). Le silence est mesuré par enregistrement, chaque bord est aligné sur l'audio réel, le padding est asymétrique (80 ms avant, 140 ms après) et n'empiète jamais sur un mot supprimé. Lisez sa liste : une répétition emphatique peut ressembler à une reprise.
3. Faites un point avec la personne pour tout ce qui est long : durée avant/après, sections coupées, reprises supprimées. Ses remarques deviennent des modifications de l'EDL.
4. render.py fait tout en un seul graphe ffmpeg : coupes à la trame près, fondus de 8 ms à chaque coupe, fréquence d'images constante, incrustations, recadrage, sous-titres, polissage vocal, musique en fondu et loudness en deux passes.
5. qa.py, puis regardez la planche. --words-check retranscrit le résultat et signale tout mot qu'une coupe aurait avalé.

Jugement, chiffres et modes de défaillance : references/editing.md. Audio : references/sound.md.

Création de films (intros de marque, spots de lancement, pubs)

cp -r films/brand-sting mon-film && python3 scripts/sfx.py --out mon-film/sfx
# éditer PARAMS dans mon-film/index.html (ou passer --params '{"name": "...", ...}')
node scripts/render_film.mjs mon-film/index.html --stills 0.5,1.6,2.4,3.5 -o work/stills  # les regarder
node scripts/render_film.mjs mon-film/index.html --draft -o work/draft.mp4                 # juger le rythme
node scripts/render_film.mjs mon-film/index.html --blur 4 -o out/intro.mp4                 # maître
python3 scripts/qa.py out/intro.mp4 --no-gaps --sheet out/intro.sheet.jpg --safe

1. La charte graphique d'abord (references/brand-intro.md) : le fichier logo officiel, les couleurs hex, la police, les mots exacts, le registre, les formats, le son, et une source pour chaque chiffre. Ne jamais redessiner ou recolourer un logo ; ne jamais inventer de revendications, de clients ou d'UI produit.
2. Un story-board avant le code : chaque beat avec son temps, ce qui bouge, l'easing et le son. Choisissez un registre (premium, clean, tech, bold, playful) et mettez toute la timeline à l'échelle avec lui.
3. Construisez sur assets/film.js : chaque pixel est une fonction de t. Film.tween, Film.spring, Film.stagger, Film.random(seed) ; pas d'animations CSS, de timers ou de Date.now. Ouvrez le HTML dans un navigateur pour le défiler en temps réel.
4. Des stills à chaque beat, puis un brouillon, puis le maître. Corrigez ce que les stills montrent avant de rendre la vidéo. Les maîtres rendent ~2–5 images par seconde ; les brouillons sont 10× plus rapides.
5. Le son fait partie du film. scripts/sfx.py synthétise la banque sonore (hit, boom, whoosh ×3, riser, pop, tick, chime, fond) ; les repères sonores sont dans la config du film et sont mixés et mis au niveau loudness par le rendu. Le pic du hit tombe sur l'image de révélation.

Modèles : films/brand-sting (3–7 s de logo animé, cinq registres, 16:9 / 9:16 / 1:1) et films/launch (15 s accroche → problème → révélation → preuve → CTA, les trois formats, 9:16 dans la zone de sécurité des plateformes, emphase *mot*). Utilisez-les comme points de départ ; changez la structure quand le brief le demande.

Doctrine (temporisations, easing par rôle, stagger, tailles de police, couleur, transitions avec une raison, les looks génériques à éviter et les tests qui les détectent) : references/motion.md.

Règles toujours applicables

• Ré-encodez chaque coupe. Les coupes par stream-copy s'alignent sur les keyframes.
• Fréquence d'images constante dans tout ce qui est livré ; H.264 + yuv420p + AAC + +faststart.
• Loudness par mesure : -14 LUFS / ≤ -1 dBTP pour le web et les réseaux sociaux, -16 pour les podcasts.
• Texte dans les zones de sécurité : en 9:16 rien dans les 288 px du haut, 672 px du bas ou 192 px de droite (en 1080×1920). Police ≥ 28 px en 1080.
• Contenu honnête : logos réels, chiffres réels avec sources, UI produit réelle ; précisez si la musique, la voix ou les images sont générées.
• Musique sous licence uniquement. Ne jamais extraire l'audio de vidéos ou de services de streaming.
• Fini signifie vérifié : qa.py passe, la planche contact a été regardée, et tout ce qui n'a pas pu être vérifié est dit clairement.

Fichiers

Chemin	Quoi
scripts/transcribe.py	words.json avec les temps des mots (faster-whisper / whisper / whisper.cpp)
scripts/plan_cuts.py	EDL : silences, tics, reprises supprimés, avec raisons
scripts/captions.py	SRT, ASS stylisé et JSON de repères sur la timeline éditée
scripts/render.py	EDL → vidéo finie (presets, recadrage, sous-titres, musique, loudness)
scripts/qa.py	format, durée, noir, freeze, silence, loudness, mots, planche contact
scripts/sfx.py	banque sonore synthétisée
scripts/render_film.mjs	HTML film → MP4 (brouillon, maître avec flou de mouvement, stills, poster)
scripts/doctor.py	ce qui est installé et ce qui manque
assets/film.js	moteur de mouvement déterministe + aperçu navigateur avec curseur temporel
films/	modèles brand-sting et launch
references/	editing, motion, brand-intro, sound, platforms, ffmpeg, remotion