ralphy — Compositor y Renderizador

Manual del editor

Léelo cuando: "componer el video", "hacer el render", "renderizar", "previsualizar", "arreglar subtítulos", "mezcla de audio", "corte final", "apretar transiciones".

Compositor y renderizador. Tomo scenario.json + asset-manifest.json, ensamblo una composición HTML con GSAP y renderizo un MP4 mediante HyperFrames. No genero medios — eso es del director de arte. Empalmo, temporizo, transiciono, subtitulo, mezclo, hago sanity-check.

Regla STOP. Renderizar solo mediante ralphy render. FFmpeg solo mediante ralphy audio / ralphy video. Sin bunx hyperframes render directo fuera de depuración, sin shells ffmpeg ad-hoc — cada receta es un verbo que se autologgea. Invariante AGENTS #2.

Motor

HyperFrames es el único motor de render. Cada proyecto debe enviar .ralphy/workspaces/<ws>/projects/<id>/index.html. Consulta hyperframes para reglas de composición, timelines GSAP, bloques de registro, subtítulos, transiciones y mezcla de audio.

Recetario CLI

Renderizar solo mediante ralphy render. FFmpeg solo mediante ralphy audio / ralphy video. Nunca llamar a bunx hyperframes render directamente fuera de depuración, y nunca hacer shells a ffmpeg ad-hoc — cada receta a continuación es un verbo que se autologgea.

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

# Subtítulos
ralphy generate captions --project <id> --audio <vo.mp3>     # → captions.json (Caption[])
# HyperFrames también incluye un transcriptor integrado a nivel de palabra:
bunx hyperframes transcribe --in <vo.wav> -o captions.json

# Recetas de audio — envuelven cli/lib/ffmpeg-recipes.ts
ralphy audio loudnorm  --in <vo.mp3>  --out <vo-norm.mp3>           # -16 LUFS para TikTok / Reels
ralphy audio sidechain --voice <vo>   --music <m> --out <mix.mp3>   # duck música bajo VO
ralphy audio concat    --files a.mp3,b.mp3,c.mp3 --out concat.mp3   # concatenación sin pérdida

# Recetas de video
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>   # último paso
ralphy video tonemap-hdr     --in <hdr.mp4> --out <sdr.mp4>                       # HDR → Rec.709
ralphy video concat          --files a.mp4,b.mp4 --out concat.mp4

# Bucle de iteración HyperFrames (solo en primer plano — sin Studio automático)
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>

# Inspeccionar entradas / salidas
ralphy project show <id> --assets        # asset-manifest antes de componer
ralphy project show <id> --status        # qué está hecho / falta
ralphy project log <id> --type generations --limit 50    # entradas de ffmpeg + render

Para detalles específicos de la API de HyperFrames (reglas de composición, timelines GSAP, subtítulos, transiciones, bloques de registro) lee hyperframes — ese es el manual de referencia, no este manual.

Extender un clip estilizado (ancla i2v del último fotograma + bloques completos de 15s)

Cuando el usuario pida "extender" / alargar un clip estilizado existente (toon, pictórico, registro Spider-Verse / Arcane), no generes un clip nuevo desconectado — ancla un nuevo clip i2v desde el último fotograma del existente para que la unión sea invisible:

1. Extrae el fotograma final: ralphy video extract-segment (o una captura de cola ffmpeg -sseof mediante una receta ralphy video) de los últimos ~0.15s → un PNG.
2. Alimenta ese PNG como --first-frame de una nueva llamada ralphy generate video i2v en bytedance/seedance-2.0. El nuevo clip comienza en el fotograma real final, por lo que el corte es invisible. (Los anclajes estilizados/pictóricos no activan el filtro de privacidad de rostros fotorrealistas de seedance — ese filtro solo se activa en rostros humanos fotorrealistas, consulta feedback_seedance_rejects_realistic_people.)
3. Por defecto, la extensión debe ser un bloque completo de 15s, no 5s. Las extensiones cortas se sienten apresuradas y pierden dinámica; un bloque de 15s tiene espacio para un ritmo real (p. ej. solo → órbita de cámara revelando la multitud → final) y el registro estilizado se nota más en bloques largos con acción que en planos fijos amplios. Enfatiza una cámara en movimiento (órbita/grúa) para dar dinamismo. Mantén los bloques de prompt SUJETO / ESTILO / POLÍTICA DE AUDIO textuales entre bloques.
4. ralphy video concat los bloques, regenera una base musical ajustada a la NUEVA longitud completa con el clímax alineado al final, luego ralphy audio sidechain (duck música bajo VO) y copia a render/final.mp4.

NO aplica a: clips fotorrealistas de humanos (seedance rechaza el anclaje — extiende mediante kwaivgi/kling-v3.0-pro en su lugar); ritmos lentos estáticos / impulsados por diálogo donde una extensión de 5s es la longitud correcta; casos donde el nuevo ritmo es un cambio de escena brusco en lugar de una continuación (entonces es una nueva escena, no una extensión, y el anclaje del último fotograma es innecesario).

Subdocumentos (leer bajo demanda)

Archivo	Cuándo leerlo
editor/render-pipeline.md	Preflight, autoría de composición, previsualización, render final
editor/vo-sync.md	Cortes alineados a VO — empalmar → transcribir → segmentar; reverse-areverse + concat demuxer (invariante AGENTS #16)
editor/captions.md	Conectar captions.json a un componente de subtítulos; subtítulos primero antes de escribir constantes de temporización
editor/transitions.md	Patrones de crossfade/push/wipe
editor/audio-mixing.md	Niveles de VO + música + SFX, ducking, fundidos
editor/green-zone.md	Colocación de texto/superposiciones dentro de la zona segura 1080×1920
editor/hard-rules.md	Lista de verificación de 12 ítems de ffmpeg / disciplina de corte para finales

Subtareas

Subtarea	Cuándo	Subdocumentos
preflight	"¿listo para renderizar?"	render-pipeline
generate-captions	VO listo, sin captions.json	captions + vo-sync (para cortes alineados a VO)
author-composition	manifiesto completo, falta composición	render-pipeline + transitions + hyperframes
preview	"mirar en el navegador"	render-pipeline + bunx hyperframes preview
final-render	composición aprobada	render-pipeline + hard-rules

Lo que leo al inicio

1. Ejecutar ralphy editor preflight <id> primero. Única verificación canónica de duraciones, fps, codec, pistas de audio, brecha de música vs longitud total del clip e integridad escenario-a-disco. Sale con 1 en rojo — arreglar antes de componer. Reemplaza el bucle ffprobe ad-hoc de cada proyecto. (#034)
2. Luego ralphy editor trim-analyze <id>. Pase de visión batch gemini-3.1-pro-preview sobre artifacts/videos/ para tiempos muertos / momentos calientes / trim_in_s / trim_out_s sugeridos por clip. Agrega a artifacts/analysis/summary.json (idempotente mediante mtime — las re-ejecuciones solo reanalizan clips cambiados). Usa --dry-run para previsualizar el plan + el estado de caché. Solucionador canónico para el sobredesfase de ~1s de kling/seedance (#042). (#034)
3. AGENTS.md — invariantes (sin auto-Studio, sin scripts, ralphy render).
4. manual de hyperframes — manual de referencia para composición / subtítulos / transiciones / GSAP / registro de HyperFrames.
5. art-director/pre-render-checklist.md — compuerta de revisión de instantánea DURA que el director de arte debe superar antes de entregar. Si llegaste aquí sin instantáneas en disco, vuelve al director de arte.
6. .ralphy/workspaces/<ws>/projects/<id>/scenario.json — estructura y temporizaciones.
7. .ralphy/workspaces/<ws>/projects/<id>/asset-manifest.json — rutas de activos.

• .ralphy/workspaces/<ws>/projects/<id>/index.html — la composición.
• .ralphy/workspaces/<ws>/projects/<id>/design.md — fuente de verdad de la marca (compuerta de skill HyperFrames).
• docs/green-zone.md para posicionamiento de texto.

Reglas duras (heredadas de AGENTS.md)

1. ralphy render <id> — la única ruta de render. No llames a bunx hyperframes render directamente (excepto para depuración).
2. Sin preview / Studio auto-lanzado. No ejecutes hyperframes preview en segundo plano. Si el usuario quiere una previsualización, díselo claramente que la ejecute en primer plano.
3. Subtítulos mediante ralphy generate captions (whisper-1 OpenRouter) o bunx hyperframes transcribe para marcas de tiempo a nivel de palabra. Ejecútalo ANTES de escribir cualquier constante de temporización de HF / Remotion cuando la composición tenga superposiciones de subtítulos (invariante AGENTS #16). Para cortes alineados a VO en general, transcribe primero mediante editor/vo-sync.md. Consulta editor/captions.md.
4. Compuerta de calidad antes del render final — cada ranura en el manifiesto debe tener score >= 7 o consentimiento explícito de omisión.
5. Postprocesado FFmpeg — solo mediante cli/lib/ffmpeg-recipes.ts. Consulta editor/hard-rules.md (12 ítems).
6. Gráficos animados → código de composición, nunca modelos de video (04.0A.02). Consulta el árbol de decisión abajo — texto animado, tipografía cinética, tercios inferiores, gráficos animados, maquetas UI animadas, transiciones wipe se componen todas como HTML + GSAP de HyperFrames. NO se generan mediante ralphy generate video; esa ruta está reservada para escenas de acción real / ilustración / fotorrealistas — contenido de píxeles que el modelo produce, no movimiento compuesto por código.
7. DEBE registrar cada turno de feedback del usuario en el render mediante ralphy project log-prompt <id> --text "<textual>" --stage <feedback|approval|critique|rejection> — rechazo a un corte, arreglo de subtítulos, remezcla de audio, aprobación "enviar", crítica que mate el render. La misma disciplina de MUST-log que el manual del guionista (consulta scenarist.md → "Registro de prompts de usuario"). Los registros dispersos dejan a la capa de autopsia adivinando qué versión del render aprobó realmente el usuario.
8. Kling + seedance sobredesfasan --duration en ~1s. Cada clip de kwaivgi/kling-v3.0-pro y bytedance/seedance-2.0 aterriza ~1s más largo que la duración solicitada (tokyo-y2k-001 midió 5s/4s/9s → 6.04/5.04/10.04). Antes de componer un corte de varios clips, (a) solicita --duration 1s más corto en la etapa del director de arte, o (b) presupuesta un pase de recorte por clip con visión. Receta completa + números en editor/render-pipeline.md → Sobredesfase de duración de clip fuente. La solución estructural vive en el futuro verbo ralphy editor trim-analyze (issue 034).

Píxeles vs código — el árbol de decisión de gráficos animados (04.0A.02)

Antes de enrutar una escena a ralphy generate video, clasifica la salida:

Patrón	Ruta	Por qué
Escena de acción real (persona, habitación, acción, clima, captura de gameplay)	ralphy generate video (i2v / t2v)	El modelo produce píxeles que el código no puede falsificar
Fijo fotorrealista + paralaje	ralphy generate image + HyperFrames GSAP tween	La imagen es el activo; el movimiento es la composición
Texto animado / tipografía cinética / "PALABRAS IMPACTAN"	Componente HyperFrames + timeline GSAP	El código controla la temporización y la ortografía exacta; el modelo de video emborronará letras y desviará fuentes
Tercio inferior / tarjeta de nombre / chyrón	HTML + GSAP de HyperFrames	Trivialmente parametrizable; la ruta de píxeles rerenderizaría fuentes cada generación
Gráfico animado / visualización de datos	HTML + GSAP / Three.js de HyperFrames	El código es la fuente de verdad para los datos; la ruta de píxeles alucinaría valores
Maqueta UI animada / pantalla de app	HTML + GSAP de HyperFrames	La ruta de píxeles inventa prestaciones de UI; el resultado se lee como slop de IA
Transición entre dos clips	Bloque de registro de shader/crossfade de HyperFrames	Los dos clips son los activos; la transición es una receta de código
Superposición de partículas / FX	CSS/SVG/Canvas/WebGPU de HyperFrames	Repetible; la ruta de píxeles es no determinista
Inserción de animación Lottie	Adaptador lottie de HyperFrames	El archivo Lottie es el activo; el runtime lo reproduce determinísticamente

Señales reveladoras (el lint en bun run lint:templates marca infractores conocidos en prompts.json): "texto animado", "tipografía cinética", "tercio inferior anima", "gráfico anima", "logo se desliza", "transición wipe" → estos van al lado HTML+GSAP, no al modelo de video. Si te encuentras escribiendo una de esas frases como --prompt para ralphy generate video, detente y compón el componente en su lugar.

Enlace cruzado: lee hyperframes para los detalles de la API.

Nota histórica (Remotion). Si estás explorando una rama anterior a 92ef823 o una autopsia que menciona STATIC_ROOT / composition-props.json, la convención heredada de Remotion está documentada en editor/render-pipeline.md → Heredado: Receta STATIC_ROOT de Remotion. No relevante para el trabajo actual con HyperFrames.

Entrega

• preflight encontró activos faltantes → manual del director de arte para regenerar.
• Temporizaciones desviadas (VO ≠ duración del escenario) → manual del guionista para re-temporizar escenas.
• Después de final-render, si es parte de un lote → manual del productor.
• Nuevo patrón de HyperFrames → manual de hyperframes + cuerpo de skill relevante (gsap, lottie, animejs, …) antes de escribir código.
• Una escena falla dos veces en el mismo eje durante recomposición/regen — consulta manual del director de arte → Dividir escena en lugar de regen. Deja de re-promptear; divide en micro-planos dentro del mismo presupuesto de ranura.