Seagey/edit-reel

Editar um reel

Tudo roda no próprio Mac do usuário. Nenhum serviço pago. O script que faz o trabalho é scripts/edit.sh na raiz do repositório, que chama scripts/edit_reel.py ao lado deste arquivo.

O usuário não é técnico. Fale em português claro, frases curtas, sem jargão. Diga o que você vai fazer antes de fazer, depois diga o que aconteceu. Nunca use travessões ou hífens.

Conteúdo

• Caminho rápido
• Obtendo o vídeo
• O que uma edição faz
• Configurações que o usuário pode pedir para alterar
• Antes de entregar: as verificações
• Lendo o resultado de volta para eles
• Coisas que dão errado
• Regras rígidas

Caminho rápido

1. Verifique se a configuração está pronta: scripts/setup.sh --check. Se disser NÃO PRONTO, siga CLAUDE.md (a integração), não improvise instalações.
2. Obtenha o vídeo (veja abaixo), depois execute:
   • um arquivo nomeado: scripts/edit.sh "<caminho para o vídeo>"
   • os N mais recentes na pasta Inbox: scripts/edit.sh --latest 3
3. Execute as verificações abaixo, olhe as imagens, leia as legendas, depois relate.

Um clipe de 30 a 60 segundos leva cerca de um a dois minutos em um Mac com chip Apple, mais tempo em um mais antigo.

Obtendo o vídeo

Nesta ordem, parando no primeiro que funcionar:

1. Um arquivo que eles nomearem ou arrastarem. Use-o onde está. Nunca mova ou apague o original deles.
2. A pasta Inbox. Qualquer coisa que tenham enviado via AirDrop ou colocado em Inbox/ (na pasta do repositório).
3. Fotos do iCloud. Apenas se o iCloud foi configurado (docs/ICLOUD.md). O e-mail Apple ID deles está em config.json sob icloud_apple_id. Execute scripts/icloud-fetch.sh <apple id> 30.
   • Ele imprime ICLOUD_FETCH_OK quando funcionar. Os vídeos mais novos vão para Inbox/.
   • Ele imprime ICLOUD_FETCH_FAILED quando o login expirou (dura cerca de dois meses) ou nunca foi feito. Não tente consertar sozinho: avise e guie-os pelo passo "Fazendo login novamente" em docs/ICLOUD.md. Eles digitam a senha e o código de 6 dígitos no próprio Terminal, nunca no chat.
   • "Mais novos" significa os filmados mais recentemente. Vídeos acabados de filmar podem levar alguns minutos para chegar ao iCloud; se o que eles querem estiver faltando, avise e ofereça tentar novamente em um minuto.
4. Nada funciona. Ofereça a alternativa: enviar o vídeo via AirDrop para o Mac, ou arrastá-lo para a pasta Inbox.

O que uma edição faz

Em ordem:

1. Corta, pelo som. Encontra onde a voz realmente começa e termina pela altura do áudio, não pelos tempos das legendas (tempos de fala para texto no início de um clipe podem estar dentro do silêncio e esconder pausas). Remove o silêncio no início e no fim e encurta pausas longas. Os cortes são feitos no momento mais silencioso próximo e cada emenda tem um fade de 15 ms, então nenhuma palavra é cortada. Frases são mantidas inteiras; nada é removido que não seja silêncio.
2. Verificação de espelhamento. Clipes da câmera frontal geralmente estão espelhados. Lê qualquer texto no quadro (placas, telas, camisetas) normal e invertido com OCR e inverte o vídeo apenas se palavras reais forem lidas corretamente invertidas. Nunca julgado visualmente. Se não houver texto legível, deixa o vídeo como está e informa no relatório.
3. Corta para 9:16 e redimensiona para 1080x1920 (clipes paisagem são cortados no meio).
4. Cor. Mede alguns quadros e aplica uma pequena correção de exposição, contraste e saturação, limitada para nunca parecer exagerada, com uma folha de antes/depois. Clipes HDR do iPhone são mapeados para cor padrão primeiro.
5. Som de estúdio. Remoção de ruído, equalização de voz, de-esser, compressor, limitador, depois volume para -14 LUFS. Isso foi ajustado por medição. Ouvidos decidem: se soar áspero, fino ou excessivamente processado, mude audio.strength para light.
6. Legendas. Transcreve o som limpo, depois desenha as legendas com Pillow. Dentro das zonas seguras do celular (x 90 a 960, y 250 a 1520 em um quadro 1080x1920) para que botões e o texto do aplicativo não as cubram. A palavra ativa muda de cor. O contorno permanece escuro. Sem caixas coloridas atrás das palavras, porque ficam suaves sobre o rosto.
7. Saídas. Edited/<nome>-editado.mp4 e, em Edited/checks/<nome>/: contact-sheet.jpg, colour-before-after.jpg (cor antes-depois), caption-frame.png (quadro-legenda), captions-words.txt (palavras-legendas), report.json (relatório.json).

Configurações que o usuário pode pedir para alterar

Tudo em config.json na raiz do repositório (criado a partir de config.default.json, que nunca é editado). O usuário nunca toca no arquivo. Eles dizem em palavras simples e você altera, executa a edição novamente e mostra. Tabela completa de palavra para configuração: docs/STYLE.md.

Exemplos:

• "Deixe as legendas amarelas" define captions.highlight_color (a palavra ativa) ou captions.color (todas as palavras). Pergunte qual se não estiver claro.
• "Legendas maiores" aumenta captions.size em cerca de 12 (padrão 78). Mantenha o resultado dentro da zona segura: o script informa inside_safe_zone.
• "Mova as legendas para cima" define captions.position para middle ou upper.
• "Uma palavra de cada vez" define captions.style para word. "Linhas" volta para line.
• "Sem legendas" define captions.enabled como false.
• "Menos cor" diminui grade.strength em 0.2. "Sem correção de cor" define grade.enabled como false.
• "Corte mais apertado" define cuts.tightness para tight. "Deixe mais espaço para respirar": gentle.
• "Som muito processado": audio.strength para light.
• "Mais próximo do meu rosto": framing.zoom 1.15 (máximo sensato 1.4).
• Nome errado nas legendas: adicione ao vocabulary (ajuda o reconhecedor a acertar) e, se ainda sair errado, em replacements como {"ouvido": "Soletração Correta"}.

Após uma alteração, execute a edição novamente no mesmo vídeo e mostre o novo resultado. Use os arquivos em Edited/; reexecutar substitui a edição anterior do mesmo nome.

Antes de entregar: as verificações

O script imprime um resumo e escreve report.json. Você ainda precisa olhar.

1. Números. loudness_ok, start_ok, end_ok devem ser todos verdadeiros. O silêncio no início deve ser de 0,45 s ou menos e no final de 0,75 s ou menos. Se não, avise e execute novamente com --tightness tight.
2. Olhe as imagens com a ferramenta de leitura: contact-sheet.jpg (o rosto está no quadro, a imagem parece natural, as legendas estão dentro da tela), colour-before-after.jpg (esquerda é o original, direita é a correção: pele natural, não laranja ou cinza, brancos não estourados, pretos não esmagados) e caption-frame.png (leia cada palavra em tamanho real, consegue ler cada uma contra o fundo).
3. Leia as legendas. Abra captions-words.txt. A fala para texto erra nomes e palavras locais (por exemplo, um nome de marca). Corrija com vocabulary e replacements, depois execute novamente. Verifique caption_vs_sound_match no relatório: abaixo de 0,9 significa que algo está errado, investigue.
4. Espelhamento. Olhe report.json mirror. Se decision for unknown e houver texto no quadro (uma placa, uma tela), olhe um quadro e verifique se o texto está legível. Se estiver invertido, defina framing.mirror_fix para always e execute novamente.
5. Silêncio pelo som. O script executa silencedetect na mixagem final. Não confie nos tempos das legendas para isso.

Você não pode ouvir. Diga honestamente: o som foi ajustado e medido, mas os ouvidos deles decidem.

Lendo o resultado de volta para eles

Curto, simples, neste formato:

• Onde o arquivo está e como abri-lo (Finder, pasta Edited dentro da pasta do editor de reels).
• O que foi cortado ("removeu 1,1 segundos de silêncio do início, encurtou duas pausas longas, de 36 segundos para 33").
• Se a imagem foi invertida e por quê.
• O que o som agora mede ("cerca de -14, o nível usual para Instagram e TikTok").
• Legendas: fonte, cores, alguma palavra que você alterou.
• Qualquer coisa que você não conseguiu corrigir e o que eles podem dizer para mudar.

Depois pergunte o que eles querem mudar e ofereça uma ou duas ideias da lista de configurações acima.

Coisas que dão errado

• "Nenhuma fala encontrada": o clipe está silencioso ou só com música. Avise-os.
• Legendas no lugar errado ou cortadas: verifique inside_safe_zone no relatório; diminua size.
• Fonte não encontrada: o script cai para Arial Black e imprime um aviso. Ofereça uma das fontes integradas (docs/STYLE.md), ou baixe uma fonte gratuita (um .ttf de fonts.google.com) em ~/.reel-editor/fonts/ e defina captions.font para o nome do arquivo sem .ttf.
• Uma ferramenta de configuração está faltando: execute scripts/setup.sh. Se Homebrew estiver faltando, siga CLAUDE.md.
• Edição demora muito: clipes 4K com mais de 3 minutos são pesados. Avise e deixe rodar.

Regras rígidas

• Nunca apague ou altere o vídeo original do usuário.
• Nunca peça ou aceite uma senha ou código de 6 dígitos no chat.
• Nenhum serviço pago e nenhum upload do vídeo para qualquer lugar. Tudo permanece neste Mac, exceto o download do iCloud.
• Nenhum prompt de rolagem ou sobreposições "siga-me" a menos que o usuário peça.
• Não adicione nada que o usuário não disse: as legendas mostram apenas o que foi falado.