Communitygithub.com

daniela-socoloski/raiz-engine

Montagem de vídeo orientada por conversa para vídeos verticais curtos (Reels, TikTok, Shorts) e horizontais longos. Use quando for 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, depois construa as Fases 2/3 com visuais e áudio do Remotion.

Qu'est-ce que raiz-engine ?

O **Cena Raiz** é uma skill de IA agêntica especializada em edição de vídeo conversacional, projetada para fluxos de trabalho de curta duração (Reels, TikTok, Shorts) e longa duração. Ela opera em duas fases rigorosas: a **Fase 1** realiza um corte limpo guiado por áudio com correção de cor por segmento, usando transcrições localizadas (WhisperX com alinhamento forçado) para garantir que os cortes respeitem os limites das palavras e o silêncio, resultando em um `cut.mp4` para aprovação do usuário. A **Fase 2** constrói sobre esse corte aprovado com legendas, gráficos e faixas de áudio exclusivamente através do Remotion, garantindo que nenhum texto ou sobreposição seja queimado com ffmpeg/PIL. A skill impõe regras rígidas e não negociáveis, como verificação numérica primeiro (via `verify_cut.py`), cache de transcrições por fonte e nunca ler dados brutos de máquina (JSON de transcrições, etc.) no contexto — apenas o resumo `takes_packed.md`. Ela suporta edição local via pipeline ffmpeg/Remotion ou através de MCPs Adobe (Premiere Pro, After Effects), com uma interface de pré-visualização padrão que exibe uma linha do tempo do editor. O processo é centrado no usuário: perguntar → confirmar → executar → iterar → persistir, garantindo que nenhum corte seja feito sem aprovação explícita da estratégia.

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

Demander à votre IA préférée

Ouvre une nouvelle conversation avec cette compétence d'agent déjà préchargée.

Documentation

Cena Raiz

Princípio

  1. 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.)
  2. 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.
  3. O áudio é primário, os visuais seguem. Os candidatos a corte vêm dos limites da fala e das pausas 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. Observe 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 práticos, não mandamentos. Apenas as Regras Fortes são obrigatórias.
  7. 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)

  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 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.)
  3. Fades de áudio de 30ms em cada limite de segmento (codificado no render.py).
  4. Nunca corte dentro de uma palavra — ajuste-se aos limites das palavras da transcrição.
  5. 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.
  6. Armazene em cache as 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 pós-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 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.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 verificação de múltiplos quadros em uma montagem 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 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 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 do próprio decodificador — aproximados e não seguros para legendas de karaokê da Fase 2. Informe se isso acontecer.
  • ffmpeg + ffprobe no PATH; dependências Python (uv sync); Node 18+ para 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 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. --section baixa 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. --simulate imprime 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 --language quando 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 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 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 enviá-lo de volta 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 o fps do edit-data.json 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 por faixa (RMS de cada faixa vs a faixa mediana; LOW-LEVEL abaixo 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 de 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 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 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 referência 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 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á 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 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):

  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 existirem; a guia 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 tomada; awaitingStyle/style controlam a guia Estilo abaixo.)

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

    • Claude Code: garanta que .claude/launch.json tenha a configuração (ajuste --root por sessão). O servidor aceita 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 vez.
    • 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 guia 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 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...

Skills associés