O que Cena Raiz faz?
Princípio
- Duas fases, um portão entre elas. FASE 1 é o corte limpo + correção de cor; FASE 2 são legendas, gráficos e imagens. (Regra Rígida 1 impõe o portão.)
- O LLM raciocina a partir da transcrição bruta + visuais sob demanda. O único artefato derivado que se mantém útil é o transcripto compactado por frase (
takes_packed.md). Todo o resto é derivado no momento da decisão. - O áudio é primário, os visuais seguem. Os candidatos a corte vêm dos limites da fala e das lacunas de silêncio.
- Pergunte → confirme → execute → itere → persista. Nunca toque no corte até que o usuário confirme a estratégia em português claro.
- Generalize. Olhe o material, pergunte ao usuário, depois edite — nunca presuma que tipo de vídeo é.
- Liberdade artística é o padrão. Valores específicos aqui são exemplos trabalhados, não mandamentos. Apenas as Regras Rígidas são obrigatórias.
- Gaste tokens onde o gosto vive. Dados de máquina são para programas, não para leitura; a verificação é numérica antes de ser visual. Sua atenção é o recurso escasso — coloque-a na edição, não em analisar JSON. (As Regras Rígidas 12 e 13 dizem o que isso proíbe.)
Regras Rígidas (correção de produção — inegociáveis)
- O portão de fase é real. Nenhum trabalho da Fase 2 antes do corte ser aprovado.
- Extração por segmento → concatenação sem perdas
-c copy, nunca um filtergraph de passagem única. (Sob o J-cut padrão, a imagem e o som de um take são extraídos como intervalos separados e as faixas de áudio são somadas — essa é a única mixagem sancionada, e o caminho de vídeo ainda é por segmento + concatenação sem perdas.) - Fades de áudio de 30ms em cada limite de segmento (codificado no render.py).
- Nunca corte dentro de uma palavra — ajuste aos limites de palavra da transcrição.
- Acolchoar cada borda de corte (janela de 30–200ms; a cauda ligeiramente mais longa que a liderança). Corte em silêncio sempre que possível.
- Armazenar em cache transcrições por fonte. Nunca retranscreva a menos que a fonte tenha mudado.
- Correção de cor por segmento durante a extração, nunca após a concatenação.
- Confirmação da estratégia antes da execução.
- Todas as saídas da sessão em
<videos_dir>/edit/— nunca dentro do repositório cena-raiz. - FASE 2 é exclusivamente Remotion — sem texto ou sobreposições queimadas com ffmpeg/PIL.
- FASE 2 é orientada por dados. Estruture copiando o modelo de faixa; descreva o vídeo em
public/edit-data.json. Nunca leia ou edite o TSX do modelo (src/Main.tsxetc.) — o único arquivo de código editável ésrc/CustomGraphics.tsx, apenas para gráficos personalizados. - Verifique numericamente primeiro. Execute
verify_cut.pyem cada corte renderizado; abra imagens apenas para junções sinalizadas. Agrupe qualquer inspeção de múltiplos quadros em um único mosaicocontact_sheet.py/grade.py --candidates. - Nunca leia dados de máquina no contexto:
transcripts/*.json(bruto),captions.json,track.json,segments.json, binários de matte/faixa. Leiatakes_packed.mde saída padrão dos helpers.
Meio de execução — pipeline local vs Adobe MCP
O mecanismo padrão é o pipeline ffmpeg/Remotion abaixo. Para conexão,
diagnóstico, descoberta de capacidade ou trabalho controlado através dos MCPs
Adobe locais, leia references/adobe-mcp.md primeiro. Ele é neutro em relação ao cliente: o mesmo procedimento
se aplica ao Codex e Claude Code.
Se o usuário pedir a edição dentro do Adobe Premiere Pro via MCP premiere-pro
("edite a sequência no Premiere", "corte via MCP"), também leia
references/premiere-mcp.md. O MÉTODO não muda — áudio primário, corte em
silêncio, portão de fase, correção de cor com bom gosto — mas as ferramentas mudam. A transcrição e
edl.json são idênticos e armazenados em cache, então reutilize um EDL aprovado e pule
cut.mp4/pré-visualização. As gravações do After Effects permanecem sujeitas à
fase Adobe controlada do repositório; a disponibilidade do MCP por si só não autoriza mutação.
Estrutura de diretórios
<videos_dir>/
├── <arquivos fonte, intocados>
└── edit/
├── project.md ← memória; anexado a cada sessão
├── takes_packed.md ← transcrições por frase, a principal visão de leitura
├── edl.json ← decisões de corte (Fase 1)
├── transcripts/<nome>.json ← transcrições em cache no nível de palavra (WhisperX, local)
├── clips_graded/ ← extratos por segmento com correção de cor + fades
├── cut.mp4 ← saída da FASE 1: corte limpo corrigido (artefato de aprovação)
├── verify/ ← mosaicos / visualizações de limites sinalizados
├── captions.srt + chapters.txt ← entregáveis de formato longo
├── final.mp4 ← renderização entregue (Fase 2 + 3, com loudnorm)
└── remotion/ ← projeto Remotion (Fase 2 + 3)
├── public/ ← cut.mp4, edit-data.json (A edição), captions.json,
│ track.json, segments.json, pexels/ web/ brand/, sfx/, trilha.mp3
└── src/ ← código de modelo imutável + CustomGraphics.tsx
Configuração
A instalação inicial está em install.md. Na inicialização a frio, apenas verifique:
- A transcrição NÃO precisa de chave de API. WhisperX vem como dependência:
uv syncé toda a instalação. Ele transcreve com Whisper e depois executa ALINHAMENTO FORÇADO (wav2vec2) contra a forma de onda, então os tempos das palavras são medidos, não inferidos — 93% das palavras caem dentro de uma região real de fala e o final da fala é colocado dentro de 10ms (medido contraspeech_regions.py). Os modelos são baixados uma vez na primeira execução e armazenados em cache. A velocidade é ~tempo real e melhora com a duração (carregar o modelo é um custo fixo de ~18s: um clipe de 16s levou 23s, uma fonte de 166s levou 109s). - Um sufixo
/UNALIGNEDem_transcription_backendsignifica que nenhum modelo wav2vec2 existia para o idioma detectado, então os tempos das palavras são os próprios do decodificador — grosseiros e não seguros para legendas de karaokê da Fase 2. Avise se isso acontecer. ffmpeg+ffprobeno PATH; dependências Python (uv sync); Node 18+ para a Fase 2.yt-dlpvem com as dependências Python, então fontes de URL não precisam de instalação extra.- A skill
remotion-best-practicespara conhecimento de domínio da Fase 2 (instale de https://github.com/remotion-dev/skills se estiver faltando). - A Fase 2/3 pode usar chaves de API opcionais (imagens ilustrativas, trilha sonora de IA). Elas estão listadas na referência de faixa, solicitadas preguiçosamente quando o recurso é usado pela primeira vez e nunca no momento da instalação. Nada na Fase 1 precisa de chave.
Os helpers estão em helpers/, resolvidos em relação a este SKILL.md (geralmente ~/.claude/skills/cena-raiz/ ou ~/.codex/skills/cena-raiz/, ou um link simbólico/junção apontando para lá). Execute-os como uv run python helpers/<nome>.py — um python simples perde o .venv que uv sync constrói.
Helpers
Fase 1:
ingest_url.py <url> --dest <videos_dir> [--section 12:00-25:30] [--max-height 1080]— editar a partir de um link: yt-dlp → MP4 (≤1080p) diretamente no diretório de vídeos; a partir daí é uma fonte como qualquer outra.--sectionbaixa APENAS um intervalo de tempo de uma fonte de formato longo (precisão de keyframe) — a maneira barata de recortar os minutos 12–25 de um vídeo de 1h.--simulateimprime título/duração/resolução sem baixar (confirme antes de grandes downloads; execute-os em segundo plano).transcribe.py <video> --edit-dir <edit> [--language pt] [--model large-v3-turbo]— nível de palavra, em cache, local (WhisperX + alinhamento forçado). Sem limite, sem fragmentação. Passe--languagequando souber — a detecção automática custa uma passagem e pode escolher errado em um clipe curto.transcribe_batch.py <videos_dir>— cada fonte em um diretório, uma de cada vez (inferência local já usa todos os núcleos). Armazenado em cache por arquivo, e uma falha em uma fonte não perde as já concluídas.pack_transcripts.py --edit-dir <dir>— transcrições →takes_packed.md(nível de frase, quebra em ≥0,5s de silêncio). A visão de leitura: 1/10 dos tokens do JSON bruto.speech_regions.py <video>— intervalos de fala acústicos via silencedetect. A fonte da verdade para as BORDAS de corte (os tempos do Whisper flutuam/distorcem). Responde onde a fala está — nunca quão alto está.voice_levels.py <video> [--edit-dir <dir>] [--edl edl.json] [--drop-db 5]— a fonte da verdade para o NÍVEL de fala. Sinaliza cada frase, executa e intervalo EDL ≥5 dB abaixo da própria mediana do falante e dimensiona umgain_db. Ele pega o que mais nada pega: um sussurro à parte onde a transcrição está perfeita,speech_regionsdiz "fala" everify_cutnão encontra falha — e o espectador ainda não consegue ouvir. Execute-o antes de escrever o EDL.detect_color.py <video> [--json]— resolve NORMAL vs LOG a partir do arquivo em vez de perguntar — metadados primeiro, estatísticas de imagem quando os metadados estão silenciosos (comum: uma transcodificação remove as tags). Retorna perfil, confiança, evidência e ogradea ser aplicado. Apenasconfidence: lowdeve fazer você retornar ao usuário; o detalhe da identificação está emreferences/log-grade.md.render.py <edl.json> -o cut.mp4 --no-subtitles [--voice-master] [--keep-resolution] [--jobs N] [--no-jcut] [--jcut-lead N] [--jcut-tail-trim N]— extração por segmento (correção de cor + fades, paralela) → montagem de sobreposição J-cut (padrão) ou concatenação sem perdas → master de voz opcional → loudnorm. Escrevejcut_timelineno EDL: as posições reais de saída, que é o que tudo downstream deve indexar. O fps de formato curto é automático: 30fps para fontes de 30fps+, senão 24 (formato longo mantém o fps da fonte via--keep-resolution). Definaedit-data.jsonfpspara corresponder aocut.mp4resultante.verify_cut.py <edl.json> <cut.mp4> [--min-silence 1.2]— autoavaliação numérica: duração, sondas de pop/palavra cortada por junção, ar morto, quadros pretos, clipping, e equilíbrio de nível de intervalo (RMS de cada intervalo vs o intervalo mediano;LOW-LEVELabaixo de −4 dB). ~350 tokens de texto em vez de N imagens. A linha de equilíbrio de intervalo é o teste de convergência para uma correçãogain_db.grade.py <in> -o <out>— predefinições de correção de cor/filtros brutos.--candidates "a=<filtro>;b=<predefinição>;original=" --frame <t> -o cmp.pngrenderiza N looks no MESMO quadro em um único mosaico rotulado.timeline_view.py <video> <start> <end>— PNG de tira de filme+forma de onda para UM ponto sinalizado, não uma ferramenta de varredura.contact_sheet.py <video> --times t1 t2 … -o sheet.png— N quadros em uma única grade rotulada; a maneira de examinar vários momentos que você já conhece.watch_video.py <video> [--mode scene|keyframe|uniform] [--times t1 t2 …] [--start/--end] [--max-frames 24]— "o que TEM nesta filmagem?" quando você não sabe onde olhar: detecção de cena + dedup perceptual → folhas de contato rotuladas emedit/verify/watch_<stem>/, uma Leitura por folha. Para inventário visual de material desconhecido e para inspecionarcut.mp4além dos números do verify_cut.--timesfixa quadros de sugestão de transcrição: momentos déiticos detakes_packed.md("olha isso", "como você pode ver") são de BAIXA mudança visual e invisíveis para a detecção de cena — fixe-os para decidir a colocação de B-roll/chamada/zoom na Fase 2.
Os helpers da Fase 2/3 (legendas, rastreamento facial, pesquisa de imagens, música) estão listados na referência de faixa que você carrega após o portão.
Interface:
preview_server.py --root <edit> [--port 4820]— serve a interface de pré-visualização padrão (veja a seção Interface de pré-visualização). O código do aplicativo está emassets/preview/e é IMUTÁVEL.
Interface de pré-visualização (padrão — inicie-a no início de cada edição)
Cada sessão de edição obtém a mesma interface interativa no painel de pré-visualização do usuário: uma linha do tempo de editor de vídeo (faixa de vídeo com tira de filme + faixa de áudio com forma de onda), um cabeçote de reprodução ativo que percorre a renderização em tempo real, alças de ajuste de take por take e remoção de take, e — a partir da Fase 2 — faixas de legenda e inserção. O layout segue a proporção da fonte por conta própria: fontes verticais colocam um player alto à direita com o transporte + linha do tempo à esquerda; fontes horizontais mantêm o player empilhado acima da linha do tempo. Vidro escuro, marca Cena Raiz. Nunca construa uma UI por sessão — alimente a interface padrão com state.json. Editar assets/preview/ é permitido apenas quando o usuário pedir uma alteração na UI; é compartilhado, então a melhoria vale para todos os projetos.
Inicialização (faça isso quando uma sessão começar, mesmo antes da primeira renderização — a UI mostra um estado de espera):
-
Escreva
<edit>/state.json:{"project": "Nome — C0000", "phase": 1, "video": "cut.mp4", "edl": "edl.json", "captions": "remotion/public/captions.json", "editData": "remotion/public/edit-data.json", "finalVideo": "final.mp4", "fps": 24, "message": "Fase 1 — cortando", "sourceDurations": {"C0000": 1038.5}, "awaitingStyle": false, "style": {"edit": "split", "captions": "karaoke", "elements": {"tracking": false, "zoomAuto": true, "zoomCuts": true, "musicAI": false}}}(
captions/editData/finalVideoapenas quando existem; a aba Fase 2 reproduzfinalVideo— a renderização COM legendas/inserções — enquanto a Fase 1 reproduz o corte limpo;sourceDurationspermite que a UI limite as extensões de take;awaitingStyle/styleconduzem a aba Estilo abaixo.) -
Selecione o adaptador de tempo de execução; nunca invoque ferramentas de outro host.
- Claude Code: garanta que
.claude/launch.jsontenha a configuração (ajuste--rootpor sessão). O servidor recebe a porta apenas por flag, então passe o$PORTatribuído pelo harness e definaautoPort:{"name": "cena-raiz-preview", "runtimeExecutable": "sh", "runtimeArgs": ["-c", "exec python3 <skill>/helpers/preview_server.py --root '<edit>' --port \"$PORT\""], "autoPort": true, "port": 4820}. Executepreview_startcom o nomecena-raiz-preview, então armeMonitor(command="python3 <skill>/helpers/watch_edits.py '<edit>'", description="escolhas e marcações salvas no preview", persistent=true)na mesma volta. - Codex desktop / CLI: inicie
uv run python helpers/preview_server.py --root '<edit>' --port 4820como um processo local em segundo plano quando o ambiente puder mantê-lo ativo. Assim que responder, use a skillcontrol-in-app-browserpara abrirhttp://127.0.0.1:4820no Navegador no aplicativo automaticamente e deixe essa aba na pré-visualização. Não presuma quepreview_start,Monitorou.claude/launch.jsonexistem. Se a capacidade do Navegador ou um processo local persistente estiver indisponível, forneça ao usuário o comando e o URL local. Após mostrar a pré-visualização, diga ao usuário para salvar e recarregar...
- Claude Code: garanta que
... [truncado para tradução]