Communitygithub.com

Cena Raiz

Edição de vídeo orientada por conversa para vídeos verticais curtos (Reels, TikTok, Shorts) e vídeos horizontais longos. Use quando solicitado a cortar, corrigir cor, adicionar legendas, gráficos, criar trilha sonora, transcrever ou preparar edições de vídeo. Execute a Fase 1 (corte limpo guiado por áudio e correção de cor), obtenha aprovação e, em seguida, construa os visuais e áudio da Fase 2/3 com Remotion.

O que é Cena Raiz?

Cena Raiz é uma skill para agentes de IA (como Claude Code, Codex CLI e Codex Desktop) que transforma a edição de vídeo em um processo conversacional e orientado por áudio. A skill segue um princípio de duas fases com um portão rígido entre elas: a Fase 1 realiza um corte limpo e correção de cor por segmento usando FFmpeg, extraindo cada take individualmente com fades de áudio de 30ms e concatenação sem perdas (-c copy), evitando cortes no meio de palavras e sempre cortando em silêncio quando possível. A Fase 2 é exclusivamente baseada em Remotion, adicionando legendas, gráficos e imagens de forma orientada por dados, sem jamais modificar o código do template TSX, exceto o CustomGraphics.tsx para gráficos personalizados. A transcrição é local via WhisperX com alinhamento forçado (wav2vec2), não requer chave de API e fornece tempos de palavra precisos. A skill inclui diversos helpers para ingestão de URLs, transcrição em lote, detecção de cor (LOG vs NORMAL), verificação numérica do corte (verificando pops, palavras cortadas, silêncio, quadros pretos e equilíbrio de nível entre segmentos) e uma interface de pré-visualização padrão com timeline, playhead e trilhas de legenda. As regras rígidas garantem correção de produção: verificação numérica antes da inspeção visual, nunca ler dados brutos de máquina (JSON) no contexto do agente, e usar a interface de pré-visualização para interação visual, não construindo uma UI por sessão. A skill suporta tanto o pipeline local FFmpeg/Remotion quanto o Adobe MCP (Premiere Pro / After Effects) para edição controlada.

Funciona com✓Claude Code✓Codex CLI~Cursor
npx skills add https://github.com/daniela-socoloski/raiz-engine/tree/HEAD/skills/cena-raiz

Perguntar na sua IA favorita

Abre um novo chat com esta habilidade de agente já pré-carregada.

Documentação

O que Cena Raiz faz?

Princípio

  1. 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.)
  2. 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.
  3. O áudio é primário, os visuais seguem. Os candidatos a corte vêm dos limites da fala e das lacunas de silêncio.
  4. Pergunte → confirme → execute → itere → persista. Nunca toque no corte até que o usuário confirme a estratégia em português claro.
  5. Generalize. Olhe o material, pergunte ao usuário, depois edite — nunca presuma que tipo de vídeo é.
  6. 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.
  7. 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)

  1. O portão de fase é real. Nenhum trabalho da Fase 2 antes do corte ser aprovado.
  2. 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.)
  3. Fades de áudio de 30ms em cada limite de segmento (codificado no render.py).
  4. Nunca corte dentro de uma palavra — ajuste aos limites de palavra da transcrição.
  5. 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.
  6. Armazenar em cache transcrições por fonte. Nunca retranscreva a menos que a fonte tenha mudado.
  7. Correção de cor por segmento durante a extração, nunca após a concatenação.
  8. Confirmação da estratégia antes da execução.
  9. Todas as saídas da sessão em <videos_dir>/edit/ — nunca dentro do repositório cena-raiz.
  10. FASE 2 é exclusivamente Remotion — sem texto ou sobreposições queimadas com ffmpeg/PIL.
  11. 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.tsx etc.) — o único arquivo de código editável é src/CustomGraphics.tsx, apenas para gráficos personalizados.
  12. Verifique numericamente primeiro. Execute verify_cut.py em cada corte renderizado; abra imagens apenas para junções sinalizadas. Agrupe qualquer inspeção de múltiplos quadros em um único mosaico contact_sheet.py / grade.py --candidates.
  13. Nunca leia dados de máquina no contexto: transcripts/*.json (bruto), captions.json, track.json, segments.json, binários de matte/faixa. Leia takes_packed.md e 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 contra speech_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 /UNALIGNED em _transcription_backend significa 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 + ffprobe no PATH; dependências Python (uv sync); Node 18+ para a Fase 2. yt-dlp vem com as dependências Python, então fontes de URL não precisam de instalação extra.
  • A skill remotion-best-practices para 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. --section baixa 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. --simulate imprime 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 --language quando 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 um gain_db. Ele pega o que mais nada pega: um sussurro à parte onde a transcrição está perfeita, speech_regions diz "fala" e verify_cut nã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 o grade a ser aplicado. Apenas confidence: low deve fazer você retornar ao usuário; o detalhe da identificação está em references/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. Escreve jcut_timeline no 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 edit-data.json fps para corresponder ao cut.mp4 resultante.
  • 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-LEVEL abaixo 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ção gain_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.png renderiza 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 em edit/verify/watch_<stem>/, uma Leitura por folha. Para inventário visual de material desconhecido e para inspecionar cut.mp4 além dos números do verify_cut. --times fixa quadros de sugestão de transcrição: momentos déiticos de takes_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á em assets/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):

  1. 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/finalVideo apenas quando existem; a aba Fase 2 reproduz finalVideo — a renderização COM legendas/inserções — enquanto a Fase 1 reproduz o corte limpo; sourceDurations permite que a UI limite as extensões de take; awaitingStyle/style conduzem a aba Estilo abaixo.)

  2. Selecione o adaptador de tempo de execução; nunca invoque ferramentas de outro host.

    • Claude Code: garanta que .claude/launch.json tenha a configuração (ajuste --root por sessão). O servidor recebe a porta apenas por flag, então passe o $PORT atribuído pelo harness e defina autoPort: {"name": "cena-raiz-preview", "runtimeExecutable": "sh", "runtimeArgs": ["-c", "exec python3 <skill>/helpers/preview_server.py --root '<edit>' --port \"$PORT\""], "autoPort": true, "port": 4820}. Execute preview_start com o nome cena-raiz-preview, então arme Monitor(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 4820 como um processo local em segundo plano quando o ambiente puder mantê-lo ativo. Assim que responder, use a skill control-in-app-browser para abrir http://127.0.0.1:4820 no Navegador no aplicativo automaticamente e deixe essa aba na pré-visualização. Não presuma que preview_start, Monitor ou .claude/launch.json existem. 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...

... [truncado para tradução]

Habilidades Relacionadas