alecs5am/ralphy

Manual do editor

Leia isto quando: "compor o vídeo", "fazer a renderização", "renderizar", "pré-visualizar", "corrigir legendas", "mix de áudio", "corte final", "apertar as transições".

Compositor + renderizador. Eu pego scenario.json + asset-manifest.json, monto uma composição HTML com GSAP e renderizo um MP4 via HyperFrames. Não gero mídia — isso é papel do diretor de arte. Eu costuro, temporizo, faço transições, legendas, mixo e verifico sanidade.

Regra STOP. Renderize apenas via ralphy render. FFmpeg apenas via ralphy audio / ralphy video. Sem bunx hyperframes render direto fora de depuração, sem shells ffmpeg ad-hoc — toda receita é um verbo que faz auto-log. INVARIANTE DO AGENTE #2.

Engine

HyperFrames é o único motor de renderização. Todo projeto deve gerar .ralphy/workspaces/<ws>/projects/<id>/index.html. Consulte hyperframes para regras de composição, timelines GSAP, blocos de registro, legendas, transições, mixagem de áudio.

Livro de receitas CLI

Renderize apenas via ralphy render. FFmpeg apenas via ralphy audio / ralphy video. Nunca chame bunx hyperframes render diretamente fora de depuração, e nunca faça shell out para ffmpeg ad-hoc — toda receita abaixo é um verbo que faz auto-log.

# Renderização final
ralphy render <project-id> [--loudnorm]
ralphy render <project-id> --fps 60 --quality high

# Legendas
ralphy generate captions --project <id> --audio <vo.mp3>     # → captions.json (Caption[])
# HyperFrames também possui um transcriber interno em nível de palavra:
bunx hyperframes transcribe --in <vo.wav> -o captions.json

# Receitas de áudio — encapsulam 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 sob VO
ralphy audio concat    --files a.mp3,b.mp3,c.mp3 --out concat.mp3   # concat perda zero

# Receitas de vídeo
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>   # última etapa
ralphy video tonemap-hdr     --in <hdr.mp4> --out <sdr.mp4>                       # HDR → Rec.709
ralphy video concat          --files a.mp4,b.mp4 --out concat.mp4

# Loop de iteração HyperFrames (apenas em primeiro plano — sem 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>

# Inspecionar entradas / saídas
ralphy project show <id> --assets        # asset-manifest antes de compor
ralphy project show <id> --status        # o que está feito / faltando
ralphy project log <id> --type generations --limit 50    # entradas ffmpeg + render

Para detalhes específicos da API HyperFrames (regras de composição, timelines GSAP, legendas, transições, blocos de registro) leia hyperframes — esse é o manual de referência, não este manual.

Estender um clipe estilizado (âncora do último frame i2v + blocos completos de 15s)

Quando o usuário pedir para "estender" / alongar um clipe estilizado existente (toon, pictórico, registro Spider-Verse / Arcane), não gere um novo clipe desconectado — ancore um novo clipe i2v a partir do último frame do existente para que a junção seja invisível:

1. Extraia o frame final: ralphy video extract-segment (ou uma captura ffmpeg -sseof via uma receita ralphy video) dos últimos ~0.15s → um PNG.
2. Alimente esse PNG como --first-frame de uma nova chamada ralphy generate video i2v em bytedance/seedance-2.0. O novo clipe começa no frame real final, então o corte fica invisível. (Âncoras estilizadas/pictóricas não acionam o filtro de privacidade de humanos foto-realistas do seedance — esse filtro só é acionado em rostos humanos foto-realistas, veja feedback_seedance_rejects_realistic_people.)
3. O padrão da extensão deve ser um bloco completo de 15s, não 5s. Extensões curtas parecem apressadas e perdem dinâmica; um bloco de 15s tem espaço para uma batida real (ex.: solo → órbita de câmera revelando a multidão → finale) e o registro estilizado aparece mais forte em blocos longos e cheios de ação do que em planos abertos estáticos. Enfatize uma câmera em movimento (órbita / grua) para dinamismo. Mantenha os blocos de prompt SUBJECT / STYLE / AUDIO-POLICY idênticos entre blocos.
4. ralphy video concat os blocos, regenera uma base musical dimensionada para o NOVO comprimento total com o clímax alinhado ao finale, depois ralphy audio sidechain (duck música sob VO) e copie para render/final.mp4.

NÃO se aplica a: clipes com humanos foto-realistas (seedance rejeita a âncora — estenda via kwaivgi/kling-v3.0-pro); batidas lentas/estáticas ou movidas a diálogo onde uma extensão de 5s é o tamanho certo; casos onde a nova batida é uma mudança brusca de cena em vez de continuação (então é uma nova cena, não uma extensão, e a âncora do último frame é desnecessária).

Sub-docs (ler sob demanda)

Arquivo	Quando ler
editor/render-pipeline.md	Pré-voo, autoria de composição, pré-visualização, render final
editor/vo-sync.md	Cortes alinhados ao VO — costurar → transcrever → fatiar; reverse-areverse + concat demuxer (INVARIANTE DO AGENTE #16)
editor/captions.md	Conectar captions.json a um componente de legenda; legendas primeiro antes de escrever constantes de tempo
editor/transitions.md	Padrões crossfade / push / wipe
editor/audio-mixing.md	Níveis VO + música + SFX, ducking, fades
editor/green-zone.md	Posicionamento de texto/overlay dentro da zona segura 1080×1920
editor/hard-rules.md	Checklist de 12 itens de disciplina ffmpeg / corte para finais

Sub-tarefas

Sub-tarefa	Quando	Sub-docs
preflight	"pronto para renderizar?"	render-pipeline
generate-captions	VO pronto, sem captions.json	captions + vo-sync (para cortes alinhados ao VO)
author-composition	manifesto completo, composição faltando	render-pipeline + transitions + hyperframes
preview	"olhar no navegador"	render-pipeline + bunx hyperframes preview
final-render	composição aprovada	render-pipeline + hard-rules

O que leio ao iniciar

1. Execute ralphy editor preflight <id> primeiro. Única verificação canônica para durações, fps, codec, faixas de áudio, lacuna de música vs comprimento total do clipe e completude do cenário no disco. Sai com código 1 em vermelho — corrija antes de compor. Substitui o loop ffprobe ad-hoc de cada projeto. (#034)
2. Depois ralphy editor trim-analyze <id>. Passada de visão em lote gemini-3.1-pro-preview sobre artifacts/videos/ para tempo morto / momentos quentes / sugestões de trim_in_s / trim_out_s por clipe. Agrega em artifacts/analysis/summary.json (idempotente via mtime — reexecuta apenas clipes alterados). Use --dry-run para pré-visualizar o plano + estado do cache. Solucionador canônico para overshoot de ~1s do kling/seedance (#042). (#034)
3. AGENTS.md — invariantes (sem Studio automático, sem scripts, ralphy render).
4. hyperframes playbook — manual de referência para composição / legendas / transições / GSAP / registro HyperFrames.
5. art-director/pre-render-checklist.md — Portão de revisão de snapshot HARD que o diretor de arte deve limpar antes de entregar. Se você chegou aqui sem snapshots no disco, volte para o diretor de arte.
6. .ralphy/workspaces/<ws>/projects/<id>/scenario.json — estrutura e temporizações.
7. .ralphy/workspaces/<ws>/projects/<id>/asset-manifest.json — caminhos dos ativos.

• .ralphy/workspaces/<ws>/projects/<id>/index.html — a composição.
• .ralphy/workspaces/<ws>/projects/<id>/design.md — fonte da verdade da marca (portão de skill HyperFrames).
• docs/green-zone.md para posicionamento de texto.

Regras rígidas (herdadas de AGENTS.md)

1. ralphy render <id> — o único caminho de render. Não chame bunx hyperframes render diretamente (exceto para depuração).
2. Nenhuma pré-visualização / Studio lançado automaticamente. Não execute hyperframes preview em segundo plano. Se o usuário quiser uma prévia — diga claramente para executá-la em primeiro plano.
3. Legendas via ralphy generate captions (whisper-1 OpenRouter) ou bunx hyperframes transcribe para timestamps em nível de palavra. Execute ANTES de escrever qualquer constante de tempo HF / Remotion quando a composição tiver sobreposições de legenda (INVARIANTE DO AGENTE #16). Para cortes gerais alinhados ao VO, transcreva primeiro via editor/vo-sync.md. Veja editor/captions.md.
4. Portão de qualidade antes da render final — cada slot no manifesto deve ter score >= 7 ou consentimento explícito de bypass.
5. Pós-processamento FFmpeg — apenas via cli/lib/ffmpeg-recipes.ts. Veja editor/hard-rules.md (12 itens).
6. Motion graphics → código de composição, nunca modelos de vídeo (04.0A.02). Veja a árvore de decisão abaixo — texto animado, tipografia cinética, terços inferiores, gráficos animados, mocks de UI animados, wipes de transição são todos compostos como HyperFrames HTML + GSAP. Eles NÃO são gerados via ralphy generate video; esse caminho é reservado para cenas live-action / ilustração / foto-realistas — conteúdo de pixels que o modelo produz, não motion compostado por código.
7. DEVE registrar cada turno de feedback do usuário na render via ralphy project log-prompt <id> --text "<verbatim>" --stage <feedback|approval|critique|rejection> — discordância de um corte, correção de legenda, remix de áudio, aprovação "pode ir", crítica que mata a render. Mesma disciplina de MUST-log do manual do roteirista (veja scenarist.md → "Registro de prompt do usuário"). Logs esparsos deixam a camada de pós-mortem adivinhando qual versão da render o usuário realmente aprovou.
8. Kling + seedance ultrapassam --duration em ~1s. Cada clipe de kwaivgi/kling-v3.0-pro e bytedance/seedance-2.0 chega ~1s mais longo que a duração solicitada (tokyo-y2k-001 mediu 5s/4s/9s → 6.04/5.04/10.04). Antes de compor um corte com múltiplos clipes, (a) solicite --duration 1s menor na fase do diretor de arte, ou (b) reserve uma passada de visão de corte por clipe. Receita completa + números em editor/render-pipeline.md → Overshoot de duração de clipe fonte. A solução estrutural está no futuro verbo ralphy editor trim-analyze (issue 034).

Pixels vs código — a árvore de decisão de motion graphics (04.0A.02)

Antes de roteirizar uma cena para ralphy generate video, classifique a saída:

Padrão	Rota	Por quê
Cena live-action (pessoa, sala, ação, clima, captura de gameplay)	ralphy generate video (i2v / t2v)	Modelo produz pixels que o código não pode falsificar
Still foto-realista + paralaxe	ralphy generate image + HyperFrames GSAP tween	A imagem é o ativo; o movimento é a composição
Texto animado / tipografia cinética / "PALAVRAS ENTRAM COM FORÇA"	Componente HyperFrames + timeline GSAP	Código controla tempo e ortografia exata; modelo de vídeo borrará letras e desviará fontes
Terço inferior / cartão de nome / chyron	HyperFrames HTML + GSAP	Trivialmente parametrizável; rota de pixels renderizaria fontes a cada geração
Gráfico animado / visualização de dados	HyperFrames HTML + GSAP / Three.js	Código é a fonte da verdade para os dados; rota de pixels alucinaria valores
Mockup de UI animado / tela de app	HyperFrames HTML + GSAP	Rota de pixels inventa affordances de UI; o resultado parece IA genérica
Transição entre dois clipes	Bloco de registro shader/crossfade HyperFrames	Os dois clipes são os ativos; a transição é uma receita de código
Partícula / overlay de FX	HyperFrames CSS/SVG/Canvas/WebGPU	Repetível; rota de pixels é não-determinística
Inserção de animação Lottie	Adaptador lottie HyperFrames	O arquivo Lottie é o ativo; o runtime o reproduz deterministicamente

Sinais reveladores (o lint em bun run lint:templates sinaliza infratores conhecidos em prompts.json): "texto animado", "tipografia cinética", "terço inferior animado", "gráfico animado", "logotipo desliza", "wipe de transição" → estes vão para o lado HTML+GSAP, não para o modelo de vídeo. Se você se pegar escrevendo uma dessas frases como --prompt para ralphy generate video, pare e componha o componente.

Link cruzado: leia hyperframes para os detalhes da API.

Nota histórica (Remotion). Se você estiver explorando um branch anterior a 92ef823 ou um postmortem que mencione STATIC_ROOT / composition-props.json, a convenção legada do Remotion está documentada em editor/render-pipeline.md → Legado: Receita STATIC_ROOT do Remotion. Não é relevante para o trabalho atual com HyperFrames.

Passagem de bastão

• preflight encontrou ativos faltando → manual do diretor de arte para regenerar.
• Temporizações desalinhadas (VO ≠ scenario.duration) → manual do roteirista para re-temporizar cenas.
• Após final-render, se fizer parte de um lote → manual do produtor.
• Novo padrão HyperFrames → hyperframes playbook + corpo de skill relevante (gsap, lottie, animejs, …) antes de escrever código.
• Uma cena falha duas vezes no mesmo eixo durante recomposição/regeração — veja manual do diretor de arte → Dividir cena em vez de regerar. Pare de re-promptar; divida em micro-planos dentro do mesmo orçamento de slot.