Cena Raiz
Princípio
- Duas fases, um portão entre elas. A FASE 1 é o corte limpo + correção de cor; a FASE 2 são legendas, gráficos e imagens. (Regra Forte 1 impõe o portão.)
- O LLM raciocina a partir da transcrição bruta + visuais sob demanda. O único artefato derivado que realmente se justifica é a transcrição compactada em nível de frase (
takes_packed.md). Todo o resto você deriva no momento da decisão. - O áudio é primário, os visuais seguem. Os candidatos a corte vêm dos limites da fala e das pausas 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. Observe 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 práticos, não mandamentos. Apenas as Regras Fortes são obrigatórias.
- Gaste tokens onde o gosto mora. 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 na análise de JSON. (Regras Fortes 12 e 13 dizem o que isso proíbe.)
Regras Fortes (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 filtro de passagem única. (Sob o J-cut padrão, a imagem e o som de uma tomada são extraídos como faixas separadas e as trilhas de áudio são somadas — essa é a única mistura sancionada, e o caminho do 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-se aos limites das palavras da transcrição.
- Acrescente margem a cada borda de corte (janela de 30–200ms; a cauda ligeiramente maior que a cabeça). Corte no silêncio sempre que possível.
- Armazene em cache as transcrições por fonte. Nunca retranscreva a menos que a fonte tenha mudado.
- Correção de cor por segmento durante a extração, nunca pós-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 a 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 verificação de múltiplos quadros em uma montagemcontact_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 a saída padrão dos ajudantes.
Meio de execução — pipeline local vs Adobe MCP
O motor padrão é o pipeline ffmpeg/Remotion abaixo. Para conexão,
diagnóstico, descoberta de recursos ou trabalho controlado através dos MCPs
Adobe locais, leia references/adobe-mcp.md primeiro. É neutro em relação ao cliente: o mesmo procedimento
se aplica ao Codex e ao Claude Code.
Se o usuário pedir a edição dentro do Adobe Premiere Pro através do 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 no
silêncio, portão de fase, correção de cor com bom gosto — mas as ferramentas mudam. A transcrição e o
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 de origem, intactos>
└── edit/
├── project.md ← memória; anexado a cada sessão
├── takes_packed.md ← transcrições em nível de frase, a visão de leitura primária
├── edl.json ← decisões de corte (Fase 1)
├── transcripts/<nome>.json ← transcrições em nível de palavra em cache (WhisperX, local)
├── clips_graded/ ← extrações por segmento com correção de cor + fades
├── cut.mp4 ← saída da FASE 1: corte limpo com correção de cor (artefato de aprovação)
├── verify/ ← montagens / 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. O WhisperX vem como dependência:
uv syncé toda a instalação. Ele transcreve com Whisper e então 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 do próprio decodificador — aproximados e não seguros para legendas de karaokê da Fase 2. Informe se isso acontecer. ffmpeg+ffprobeno PATH; dependências Python (uv sync); Node 18+ para 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 da faixa, solicitadas apenas quando o recurso é usado pela primeira vez, e nunca no momento da instalação. Nada na Fase 1 precisa de chave.
Os ajudantes ficam em helpers/, resolvidos relativamente 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.
Ajudantes
Fase 1:
ingest_url.py <url> --dest <videos_dir> [--section 12:00-25:30] [--max-height 1080]— edite a partir de um link: yt-dlp → MP4 (≤1080p) direto 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 (preciso em keyframes) — 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 buscas; execute-as em segundo plano).transcribe.py <video> --edit-dir <edit> [--language pt] [--model large-v3-turbo]— em nível de palavra, em cache, local (WhisperX + alinhamento forçado). Sem limite, sem divisão em blocos. Passe--languagequando você souber — a detecção automática custa uma passada e pode escolher errado em um clipe curto.transcribe_batch.py <videos_dir>— cada fonte em um diretório, uma de cada vez (a 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/esticam). 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 de EDL ≥5 dB abaixo da própria mediana do locutor 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 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 enviá-lo de volta 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). Defina ofpsdoedit-data.jsonpara 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 por faixa (RMS de cada faixa vs a faixa mediana;LOW-LEVELabaixo de −4 dB). ~350 tokens de texto em vez de N imagens. A linha de equilíbrio de faixa é o teste de convergência para uma correção degain_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 uma montagem rotulada.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 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 neste material?" 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 referência 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 detecção de cena — fixe-os para decidir a colocação de B-roll/callout/zoom na Fase 2.
Ajudantes da Fase 2/3 (legendas, rastreamento facial, busca de imagens, música) estão listados na referência da 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 ao vivo que percorre a renderização em tempo real, alças de corte por tomada e remoção de tomada, 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 mudança na UI; é compartilhado, então a melhoria chega a 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 existirem; a guia 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 tomada;awaitingStyle/stylecontrolam a guia Estilo abaixo.) -
Selecione o adaptador de tempo de execução; nunca invoque as ferramentas de outro host.
- Claude Code: garanta que
.claude/launch.jsontenha a configuração (ajuste--rootpor sessão). O servidor aceita 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 vez. - 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 guia na pré-visualização. Não presuma quepreview_start,Monitorou.claude/launch.jsonexistem. Se a capacidade do Navegador ou um processo local persistente não estiver disponível, forneça ao usuário o comando e a URL local. Depois de mostrar a pré-visualização, diga ao usuário para salvar e re...
- Claude Code: garanta que