alecs5am/ralphy

Manuel de l'éditeur

À lire quand : « composer la vidéo », « faire le rendu », « rendu », « prévisualiser », « corriger les sous-titres », « mixage audio », « montage final », « resserrer les transitions ».

Compositeur + moteur de rendu. Je prends scenario.json + asset-manifest.json, assemble une composition HTML avec GSAP, et produis un MP4 via HyperFrames. Je ne génère pas de média — c'est le rôle du directeur artistique. Je raccorde, je chronomètre, je transitionne, je sous-titre, je mixe, je vérifie la cohérence.

Règle STOP. Rendu uniquement via ralphy render. FFmpeg uniquement via ralphy audio / ralphy video. Pas de bunx hyperframes render direct en dehors du débogage, pas de shell ffmpeg ad-hoc — chaque recette est une commande qui s'enregistre automatiquement. Invariant AGENTS #2.

Moteur

HyperFrames est le seul moteur de rendu. Chaque projet doit livrer .ralphy/workspaces/<ws>/projects/<id>/index.html. Voir hyperframes pour les règles de composition, les timelines GSAP, les blocs de registre, les sous-titres, les transitions, le mixage audio.

Livre de recettes CLI

Rendu uniquement via ralphy render. FFmpeg uniquement via ralphy audio / ralphy video. N'appelez jamais bunx hyperframes render directement en dehors du débogage, et ne lancez jamais de ffmpeg ad-hoc en ligne de commande — chaque recette ci-dessous est une commande qui s'enregistre automatiquement.

# Rendu final
ralphy render <project-id> [--loudnorm]
ralphy render <project-id> --fps 60 --quality high

# Sous-titres
ralphy generate captions --project <id> --audio <vo.mp3>     # → captions.json (Caption[])
# HyperFrames embarque également un transcripteur mot-à-mot intégré :
bunx hyperframes transcribe --in <vo.wav> -o captions.json

# Recettes audio — encapsule cli/lib/ffmpeg-recipes.ts
ralphy audio loudnorm  --in <vo.mp3>  --out <vo-norm.mp3>           # -16 LUFS pour TikTok / Reels
ralphy audio sidechain --voice <vo>   --music <m> --out <mix.mp3>   # ducking de la musique sous la VO
ralphy audio concat    --files a.mp3,b.mp3,c.mp3 --out concat.mp3   # concaténation sans perte

# Recettes vidéo
ralphy video extract-segment --in <src.mp4> --start 1.2 --end 4.5 --out <seg.mp4>
ralphy video burn-subs       --in <src.mp4> --srt <subs.srt> --out <final.mp4>   # dernière étape
ralphy video tonemap-hdr     --in <hdr.mp4> --out <sdr.mp4>                       # HDR → Rec.709
ralphy video concat          --files a.mp4,b.mp4 --out concat.mp4

# Boucle d'itération HyperFrames (premier plan uniquement — pas de Studio automatique)
bunx hyperframes preview .ralphy/workspaces/<ws>/projects/<id>
bunx hyperframes lint    .ralphy/workspaces/<ws>/projects/<id>
bunx hyperframes inspect .ralphy/workspaces/<ws>/projects/<id>
bunx hyperframes add <block-slug> .ralphy/workspaces/<ws>/projects/<id>

# Inspecter les entrées / sorties
ralphy project show <id> --assets        # asset-manifest avant composition
ralphy project show <id> --status        # ce qui est fait / manquant
ralphy project log <id> --type generations --limit 50    # entrées ffmpeg + rendu

Pour les spécificités de l'API HyperFrames (règles de composition, timelines GSAP, sous-titres, transitions, blocs de registre), lisez hyperframes — c'est le manuel de référence, pas ce manuel.

Prolonger un clip stylisé (ancrage i2v sur la dernière image + blocs complets de 15 s)

Lorsque l'utilisateur demande de « prolonger » / allonger un clip stylisé existant (toon, pictural, registre Spider-Verse / Arcane), ne générez pas un nouveau clip déconnecté — ancrez un nouveau clip i2v à partir de la dernière image du clip existant afin que la jonction soit invisible :

1. Extrayez l'image finale : ralphy video extract-segment (ou une capture de la dernière ~0,15 s via ffmpeg -sseof avec une recette ralphy video) → un PNG.
2. Fournissez ce PNG comme --first-frame d'un nouvel appel ralphy generate video i2v sur bytedance/seedance-2.0. Le nouveau clip commence sur la vraie dernière image, donc la coupure est invisible. (Les ancres stylisées/picturales ne déclenchent pas le filtre de confidentialité des humains photoréalistes de seedance — ce filtre ne s'active que sur les visages humains photoréalistes, voir feedback_seedance_rejects_realistic_people.)
3. Par défaut, l'extension est un bloc complet de 15 s, pas de 5 s. Les extensions courtes donnent une impression de précipitation et perdent en dynamique ; un bloc de 15 s laisse la place à un vrai mouvement (ex. solo → caméra orbitale révélant la foule → finale) et le registre stylisé ressort mieux sur des blocs longs avec de l'action que sur des plans larges statiques. Mettez l'accent sur une caméra mobile (orbite / grue) pour la dynamique. Gardez les blocs de prompt SUJET / STYLE / POLITIQUE-AUDIO à l'identique entre les blocs.
4. ralphy video concat les blocs, régénérez un fond musical adapté à la NOUVELLE longueur totale avec l'apogée alignée sur la finale, puis ralphy audio sidechain (ducking de la musique sous la VO) et copiez vers render/final.mp4.

Ne s'applique PAS à : clips photoréalistes humains (seedance rejette l'ancre — prolongez via kwaivgi/kling-v3.0-pro à la place) ; plans lents/statiques ou à dominante dialoguée où une extension de 5 s est la bonne longueur ; cas où le nouveau mouvement est un changement de scène brutal plutôt qu'une continuation (alors c'est une nouvelle scène, pas une prolongation, et l'ancrage sur la dernière image est inutile).

Sous-documents (lire à la demande)

Fichier	Quand le lire
editor/render-pipeline.md	Pré-vol, création de la composition, prévisualisation, rendu final
editor/vo-sync.md	Coupures alignées sur la VO — stitch → scribe → slice ; reverse-areverse + concat demuxer (Invariant AGENTS #16)
editor/captions.md	Câblage de captions.json dans un composant de sous-titres ; sous-titres d'abord avant d'écrire les constantes de timing
editor/transitions.md	Motifs de fondu / poussée / volet
editor/audio-mixing.md	Niveaux VO + musique + SFX, ducking, fondus
editor/green-zone.md	Placement du texte/overlay dans la zone de sécurité 1080×1920
editor/hard-rules.md	Checklist de 12 éléments ffmpeg / discipline de coupe pour les versions finales

Sous-tâches

Sous-tâche	Quand	Sous-docs
preflight	« prêt pour le rendu ? »	render-pipeline
generate-captions	VO prête, pas de captions.json	captions + vo-sync (pour les coupures alignées sur la VO)
author-composition	manifeste complet, composition manquante	render-pipeline + transitions + hyperframes
preview	« regarder dans le navigateur »	render-pipeline + bunx hyperframes preview
final-render	composition approuvée	render-pipeline + hard-rules

Ce que je lis au démarrage

1. Exécutez ralphy editor preflight <id> en premier. Vérification canonique unique des durées, fps, codec, pistes audio, écart musique vs longueur totale du clip, et complétude scénario-vers-disque. Sortie 1 en cas de rouge — corrigez avant de composer. Remplace toute boucle ffprobe ad-hoc des projets. (#034)
2. Ensuite ralphy editor trim-analyze <id>. Passe vision batch gemini-3.1-pro-preview sur artifacts/videos/ pour détecter les temps morts / moments chauds / suggestions trim_in_s / trim_out_s par clip. Agrège dans artifacts/analysis/summary.json (idempotent via mtime — ne ré-analyse que les clips modifiés). Utilisez --dry-run pour prévisualiser le plan + l'état du cache. Solveur canonique pour le dépassement ~1s de kling/seedance (#042). (#034)
3. AGENTS.md — invariants (pas de Studio automatique, pas de scripts, ralphy render).
4. hyperframes playbook — manuel de référence pour la composition / sous-titres / transitions / GSAP / registre HyperFrames.
5. art-director/pre-render-checklist.md — GATE stricte de révision des snapshots que le directeur artistique doit valider avant de passer la main. Si vous êtes arrivé ici sans snapshots sur le disque, rebroussez chemin vers le directeur artistique.
6. .ralphy/workspaces/<ws>/projects/<id>/scenario.json — structure et timings.
7. .ralphy/workspaces/<ws>/projects/<id>/asset-manifest.json — chemins des assets.

• .ralphy/workspaces/<ws>/projects/<id>/index.html — la composition.
• .ralphy/workspaces/<ws>/projects/<id>/design.md — source de vérité de la marque (porte d'entrée du skill HyperFrames).
• docs/green-zone.md pour le positionnement du texte.

Règles strictes (héritées de AGENTS.md)

1. ralphy render <id> — le seul chemin de rendu. N'appelez pas bunx hyperframes render directement (sauf pour le débogage).
2. Pas de prévisualisation / Studio lancé automatiquement. Ne lancez pas hyperframes preview en arrière-plan. Si l'utilisateur veut une prévisualisation — dites-lui clairement de la lancer au premier plan.
3. Sous-titres via ralphy generate captions (whisper-1 OpenRouter) ou bunx hyperframes transcribe pour les horodatages mot-à-mot. Exécutez-le AVANT d'écrire des constantes de timing HF / Remotion lorsque la composition comporte des superpositions de sous-titres (Invariant AGENTS #16). Pour les coupures globales alignées sur la VO, utilisez d'abord la transcription via editor/vo-sync.md. Voir editor/captions.md.
4. Contrôle qualité avant le rendu final — chaque emplacement du manifeste doit avoir score >= 7 ou un consentement de contournement explicite.
5. Post-traitement FFmpeg — uniquement via cli/lib/ffmpeg-recipes.ts. Voir editor/hard-rules.md (12 éléments).
6. Motion design → code de composition, jamais modèles vidéo (04.0A.02). Voir l'arbre de décision ci-dessous — texte animé, typographie cinétique, tiers inférieurs, graphiques animés, maquettes d'interface animées, volets de transition sont tous composés en HyperFrames HTML + GSAP. Ils ne sont PAS générés via ralphy generate video ; ce chemin est réservé aux scènes live-action / illustration / photoréalistes — contenu pixel que le modèle produit, et non du motion composé par code.
7. DOIT enregistrer chaque tour de feedback utilisateur sur le rendu via ralphy project log-prompt <id> --text "<texte exact>" --stage <feedback|approval|critique|rejection> — opposition sur une coupe, correction de sous-titres, nouveau mixage audio, approbation « c'est bon », critique fatale au rendu. Même discipline d'enregistrement obligatoire que le manuel du scénariste (voir scenarist.md → « Enregistrement des prompts utilisateur »). Des logs peu nombreux laissent l'étape post-mortem dans l'incertitude quant à la version du rendu que l'utilisateur a réellement approuvée.
8. Kling + seedance dépassent --duration d'environ 1 s. Chaque clip de kwaivgi/kling-v3.0-pro et bytedance/seedance-2.0 arrive environ 1 s plus long que la durée demandée (tokyo-y2k-001 a mesuré 5s/4s/9s → 6.04/5.04/10.04). Avant de composer un montage multi-clips, soit (a) demandez --duration 1 s plus court à l'étape du directeur artistique, soit (b) prévoyez une passe de rognage vision par clip. Recette complète + chiffres dans editor/render-pipeline.md → Dépassement de durée des clips sources. La solution structurelle réside dans la future commande ralphy editor trim-analyze (issue 034).

Pixels vs code — l'arbre de décision du motion design (04.0A.02)

Avant d'orienter une scène vers ralphy generate video, classifiez le résultat :

Type	Chemin	Pourquoi
Scène live-action (personne, pièce, action, météo, capture de jeu vidéo)	ralphy generate video (i2v / t2v)	Le modèle produit des pixels que le code ne peut pas simuler
Image fixe photoréaliste + parallaxe	ralphy generate image + interpolation GSAP HyperFrames	L'image est l'asset ; le mouvement est la composition
Texte animé / typographie cinétique / « LES MOTS S'EFFRACTIONNENT »	Composant HyperFrames + timeline GSAP	Le code contrôle le timing et l'orthographe exacte ; le modèle vidéo va baver sur les lettres et dériver les polices
Tiers inférieur / carte de nom / chyron	HTML HyperFrames + GSAP	Trivialement paramétrable ; la voie pixel régénérerait les polices à chaque génération
Graphique animé / dataviz	HTML HyperFrames + GSAP / Three.js	Le code est la source de vérité des données ; la voie pixel hallucinerait les valeurs
Maquette d'interface animée / écran d'appli	HTML HyperFrames + GSAP	La voie pixel invente des affordances d'interface ; le résultat ressemble à de l'IA bâclée
Transition entre deux clips	Bloc de registre shader/fondu HyperFrames	Les deux clips sont les assets ; la transition est une recette de code
Superposition de particules / FX	HyperFrames CSS/SVG/Canvas/WebGPU	Reproductible ; la voie pixel est non déterministe
Insertion d'animation Lottie	Adaptateur lottie HyperFrames	Le fichier Lottie est l'asset ; le runtime le joue de manière déterministe

Signes révélateurs (le lint bun run lint:templates signale les contrevenants connus dans prompts.json) : « texte animé », « typographie cinétique », « tiers inférieur s'anime », « graphique s'anime », « logo glisse », « volet de transition » → ces éléments vont du côté HTML+GSAP, pas du modèle vidéo. Si vous vous surprenez à écrire l'une de ces phrases comme --prompt de ralphy generate video, arrêtez-vous et composez le composant à la place.

Lien croisé : lisez hyperframes pour les spécificités de l'API.

Annexe historique (Remotion). Si vous explorez une branche antérieure au commit 92ef823 ou un post-mortem qui mentionne STATIC_ROOT / composition-props.json, la convention Remotion héritée est documentée dans editor/render-pipeline.md → Legacy : recette STATIC_ROOT Remotion. Sans pertinence pour le travail HyperFrames actuel.

Passage de relais

• preflight a trouvé des assets manquants → manuel du directeur artistique pour régénérer.
• Les timings ont dérivé (VO ≠ scenario.duration) → manuel du scénariste pour re-chronométrer les scènes.
• Après final-render, si cela fait partie d'un lot → manuel du producteur.
• Nouveau motif HyperFrames → hyperframes playbook + corps de skill pertinent (gsap, lottie, animejs, ...) avant d'écrire du code.
• Une scène échoue deux fois sur le même axe lors d'une recomposition / regénération — voir manuel du directeur artistique → Split-scene-instead-of-regen. Arrêtez de re-prompter ; découpez en micro-plans à l'intérieur du même budget d'emplacement.