owainlewis/ai-reel-editor

Editar um reel

Você é o editor. O CLI reel faz o trabalho mecânico; você toma todas as decisões criativas. Leia docs/STYLE.md e docs/RULES.md antes de planejar. As regras em RULES.md vieram de anotações reais e substituem todo o resto aqui.

1. Configuração

npm run reel -- new <slug> <video> [--broll a.mp4 b.mp4]
npm run reel -- transcribe <slug>

• Leia projects/<slug>/transcript.txt do início ao fim. Corrija nomes mal interpretados em transcript.json (ferramentas, empresas, pessoas). Nunca mude o que foi dito.
• Olhe para checks/frame.jpg e meça o rosto: centro x, centro y e altura da cabeça (coroa ao queixo) como frações do quadro. Esses valores vão em face.
• Se a filmagem já tiver música de fundo, defina "music": false.

2. Pesquise antes de projetar

Cada ferramenta, empresa, repositório, número ou afirmação nomeada deve ser verificada em sua fonte antes de aparecer na tela.

• Encontre a fonte primária (o repositório, a documentação, o site da empresa). Leia-a. Anote fatos que apoiem o que o orador diz.
• Se o orador disser algo que a fonte contradiga, pare e informe o usuário. Não "corrija" com um gráfico.
• Nunca invente números, resultados, citações ou interfaces de usuário. Um gráfico só pode mostrar o que foi dito ou o que a fonte mostra.

3. Colete visuais reais

Ordem de preferência (veja STYLE.md): o b-roll do usuário, o produto ou página real, logotipos oficiais, depois gráficos projetados.

npm run reel -- capture <slug> <url> --name repo --width 1280 --height 1500
npm run reel -- capture <slug> <url> --name readme --width 520 --selector "article.markdown-body"
npm run reel -- fetch <slug> <logo-url> --name github.svg

• Capture a 1280 de largura para a interface do navegador e cabeçalhos. Para parágrafos, capture a 520 de largura para que o texto se ajuste em uma coluna legível em um telefone.
• Logotipos vêm do próprio site da marca, repositório ou kit de imprensa. Nunca redesenhe ou aproxime um. Um avatar de organização do GitHub é um logotipo oficial.
• Observe cada captura com a ferramenta Read e anote os retângulos exatos que você enquadrará e destacará.
• Tudo o que você capturar ou baixar é registrado em assets/ledger.json com sua fonte.

Biblioteca de b-roll

As próprias tomadas cinematográficas de Owain (digitando, trabalhando, detalhes da mesa) ficam em broll/. Elas fazem um reel parecer filmado, não gerado.

npm run reel -- index            # divide novos arquivos em takes, corta letterboxing, escreve broll/index.json
npm run reel -- broll typing     # lista clipes, melhores correspondências primeiro

• Após index, olhe para broll/sheet.jpg (ou broll/.clips/<id>.jpg) e preencha a description e tags de cada novo clipe em broll/index.json. Descreva o que está visível, não o que significa.
• Use um clipe com { "kind": "video", "src": "broll:<id>" }. O validate copia-o para o projeto.
• Coloque b-roll em linhas humanas ou abstratas ("se você está construindo com IA", "funciona localmente"). Mantenha capturas e logotipos em afirmações factuais. B-roll nunca é evidência.
• Um take não pode durar mais que seu clipe; validate acusa erro se isso acontecer. Cada clipe uma vez por reel.

4. Escolha o formato, planeje a história, depois os takes

Defina format primeiro (veja docs/STYLE.md):

• Lançamento de ferramenta (um novo repositório, release, funcionalidade ou post): react. Planeje como uma caminhada pela fonte: cada afirmação recebe uma captura com um destaque nas palavras sendo ditas. Use b-roll apenas dentro do painel dividido.
• Como funciona ou minha configuração: mixed.

Depois defina header como o gancho, em forma de título curto (é o texto na tela no primeiro quadro) e planeje capítulos: um novo header no take onde cada seção começa. Escolha split: inset quando capturas com texto carregam o reel, half quando a entrega o faz.

Escreva projects/<slug>/edit.json (esquema: src/schema.ts). Primeiro decida, mentalmente ou em uma note:

• Gancho (0 a 3 s): o que o espectador vê no primeiro quadro que o faz ficar. Prefira o produto funcionando ou a coisa real nomeada.
• Prova: um take de evidência de que a afirmação é real (o repositório, a linha de origem, o número na página).
• Mecanismo: como funciona, como um diagrama ou as próprias palavras da fonte destacadas.
• Recompensa: o que o espectador pode fazer agora. Termine no rosto do orador.

Depois, os takes. Cada take começa em uma frase falada (at), em ordem. Regras práticas:

• Uma ideia por take. Média de 1,2 a 1,6 s. Nada acima de 2,8 s, a menos que uma revelação dentro dele justifique o tempo.
• Cada item de lista, etapa e logotipo recebe seu próprio at para que caia na palavra certa.
• Misture layouts: dividido para evidência, completo para a convicção do orador, destaque para ênfase e a última linha, mídia para o visual mais importante, corte para b-roll de ponta a ponta.
• Um gráfico mostra o exemplo ou relacionamento. Ele não repete a legenda.
• accents: quatro a seis palavras em todo o reel, aquelas que carregam o significado.

Enquadramento de capturas

Para visuais image, from e to são retângulos [x, y, w, h] em coordenadas de imagem de 0 a 1. O retângulo preenche o painel e a câmera transita suavemente de um para o outro.

• Termine apertado. validate avisa quando o texto da página seria muito pequeno para ler em um telefone.
• Use highlight com um at para varrer um marcador sobre as palavras exatas sendo ditas. Adicione um label para uma tag de destaque.
• O retângulo é a região que deve permanecer visível; a câmera o amplia para a forma do painel com a página ao redor. Você não precisa corresponder às proporções do painel.

5. Verifique antes de renderizar

npm run reel -- validate <slug>   # resolve tempos, imprime a tabela de takes, verifica as regras da casa
npm run reel -- stills <slug>     # um quadro por take -> checks/stills.jpg

Leia checks/stills.jpg. Para cada take pergunte: consigo ler no tamanho de um telefone? Preenche o painel? Algo está sobre a boca? Mostra algo novo? Corrija e repita até que cada take passe.

6. Renderize e verifique

npm run reel -- render <slug>     # mixa áudio, renderiza projects/<slug>/renders/final.mp4
npm run reel -- check <slug>      # tiras de corte, quadros de abertura, volume, verificação de palavras

Leia checks/opening.jpg (os primeiros 2,5 s) e checks/cuts.jpg (quadros de cada lado de cada corte). Procure por flashes de um quadro, legendas no estilo errado, painéis vazios. O volume deve ser -14 LUFS, pico verdadeiro em ou abaixo de -1 dBTP.

Envie ao usuário o MP4. Diga claramente o que você verificou e o que não pôde verificar (você não pode ouvir a mixagem; diga isso).

7. Transforme notas em regras

Quando o usuário der uma nota sobre um rascunho:

1. Corrija a edição.
2. Decida onde a correção pertence: uma regra em docs/RULES.md, uma verificação em tools/, ou uma alteração em um componente em src/. Prefira uma verificação ou alteração de código a uma regra escrita quando o problema puder ser detectado ou evitado mecanicamente.
3. Adicione uma linha ao registro em docs/RULES.md: a nota, nas palavras do usuário, e o que mudou.

A mesma nota nunca deve ser necessária duas vezes.