CutCraft

O que CutCraft faz?

Transforme filmagens brutas e uma conversa em um vídeo final óbvio. Mantenha cada projeto dentro de um workspace nomeado CutCraft, mostre opções visuais de legenda antes de editar, faça as perguntas criativas uma vez e torne as correções de transcrição imediatamente reversíveis.

Contrato inegociável

1. Execute a verificação de prontidão primeiro. Na primeira utilização e após mudanças no ambiente, execute python3 helpers/check_environment.py. Se uma dependência obrigatória ou condicional estiver faltando, pause a edição, mostre ao usuário a URL oficial do script e as instruções exatas de configuração, e peça apenas a aprovação ou credencial faltante. Leia references/onboarding.md para orientação sobre chaves e plataforma.
2. Nunca armazene segredos neste pacote ou em um projeto. Armazene chaves da ElevenLabs em ~/.config/cutcraft/.env com modo 600, ou use Whisper local para que nenhuma chave ou upload de transcrição seja necessário. Nunca coloque uma chave em um argumento de comando, log, transcrição, captura de tela, repositório, cache de plugin ou pasta de projeto.
3. Crie o workspace antes de gerar qualquer coisa. Infira um nome curto de projeto a partir da descrição do usuário e das filmagens inspecionadas. Confirme apenas quando dois nomes materialmente diferentes forem plausíveis. Execute helpers/project_workspace.py --name "<nome>" e use seus caminhos retornados.
4. Inspecione primeiro, pergunte uma vez, edite após aprovação. Inventarie e transcreva as fontes, inspecione visuais representativos, crie imagens de prévia de legenda reais, então faça todas as perguntas criativas restantes em um único ponto de verificação consolidado. Não comece a cortar antes que o usuário escolha ou aceite os padrões recomendados.
5. Mostre escolhas visualmente. Gere três imagens de prévia de legenda com consciência de material (recomendado, limpo/narrativo e ousado/redes sociais, a menos que as filmagens exijam escolhas diferentes). Informe fonte, tamanho, posicionamento, fundo, idioma e ritmo de fala sob cada imagem. O usuário pode responder com um número de opção ou ajustes como 往下 4% ou 字大 15%.
6. Mantenha o final óbvio. Coloque apenas artefatos de entrega em 成品/. O vídeo principal deve ser nomeado <projeto>_final.mp4. Coloque prévias, clipes, transcrições, EDLs, downloads, ativos gerados e relatórios em 過程/.
7. Exporte texto editável com cada entrega legendada. Entregue <projeto>_逐字稿.md e <projeto>.srt ao lado do vídeo final. Use IDs de fala e timestamps estáveis para que o usuário possa dizer, por exemplo, 第 18 句改成…….
8. Aplique correções de transcrição imediatamente. Resolva as falas solicitadas, execute helpers/apply_transcript_corrections.py contra 過程/master.srt, reexecute a validação, re-renderize o vídeo final com o SRT corrigido, regenere a transcrição e substitua os artefatos de entrega. Preserve os tempos, a menos que o usuário relate um problema de sincronia. Não retranscreva mídia fonte inalterada.
9. Sem front-end de revisão. Não inicie um servidor ou crie arquivos de UI no navegador. Toda revisão acontece através de arquivos de vídeo/imagem entregues e correções conversacionais.
10. Torne o trabalho retomável. Atualize cutcraft.project.json a cada ponto de verificação. Preserve assinaturas de fonte, estado de aprovação, revisões, caminhos finais e proveniência de ativos. Use proxies apenas para inspeção; sempre renderize a partir dos originais.
11. Verifique antes da entrega. Execute a verificação pré-voo determinística e quality_report.py, inspecione a saída renderizada nos limites de corte e em momentos representativos de legenda, ouça a mixagem final e verifique duração/fluxos de saída. Se um corte removeu uma gagueira ou falso início, retranscreva a seção renderizada para provar que foi removida.

Layout do projeto

Raiz padrão: ~/Documents/Codex/CutCraft/ (visível no Finder; mantenha a habilidade instalável em si sob ~/.codex).

CutCraft/
└── <projeto>/
    ├── cutcraft.project.json
    ├── 成品/
    │   ├── <projeto>_final.mp4
    │   ├── <projeto>_逐字稿.md
    │   └── <projeto>.srt
    └── 過程/
        ├── project.md
        ├── creative_brief.json
        ├── inventory.json
        ├── takes_packed.md
        ├── edl.json
        ├── master.srt
        ├── transcript_corrections.json
        ├── asset_registry.json
        ├── transcripts/
        ├── clips/ and clips_*/
        ├── assets/
        ├── animations/
        ├── proxies/
        ├── downloads/
        └── verify/

Nunca duplique as filmagens fonte do usuário para dentro do projeto, a menos que o usuário peça. Registre caminhos absolutos das fontes em edl.json e deixe os originais intocados.

Um ponto de verificação consolidado

Inspecione material suficiente para fazer recomendações, renderize as imagens de comparação de legenda e então faça todas as perguntas aplicáveis juntas:

• Objetivo, público-alvo, plataforma, proporção de tela, resolução, duração alvo, formato sensível a prazo.
• História/ordem, falas que devem ficar, material que deve ser cortado, nomes/termos que o ASR deve soletrar exatamente.
• Ritmo, corte/reenquadramento, clima de cor, transições, efeitos, sobreposições, B-roll, censura/privacidade.
• Legendas: queimada/sidecar/ambos, idioma ou modo bilíngue, literal/limpa, fonte, tamanho, posição, fundo, ritmo de fala, zonas seguras de UI na tela.
• Áudio: limpeza, volume, música/SFX/narração fornecidos, ou clima e intensidade desejados.
• Fonte de ativos: arquivos fornecidos pelo usuário, ativos gerados ou bibliotecas livres específicas. Se material gratuito for solicitado, ofereça as escolhas adequadas em references/free-assets.md, peça ao usuário para escolher e registre o item, criador, URL, licença, atribuição e soma de verificação com asset_registry.py.
• Privacidade de transcrição: recomende Whisper local quando a privacidade for importante; caso contrário, ofereça ElevenLabs para diarização gerenciada. Explique o comportamento de upload antes de enviar mídia para qualquer provedor em nuvem.
• Autonomia editorial e tudo o que for explicitamente proibido.

Anexe as imagens de prévia neste ponto de verificação. Dê um padrão recomendado para cada escolha e inclua 全部用建議值 como uma resposta válida. Persista a resposta em 過程/creative_brief.json; não reabra perguntas já resolvidas no meio da edição.

Fluxo de trabalho

1. Execute verificações de prontidão e resolva apenas os requisitos faltantes.
2. Inspecione nomes de arquivo e a descrição do usuário; infira um nome de projeto e crie o workspace.
3. Execute inventory.py --work-dir <過程> <diretório_das_fontes>. Para fontes longas ou 4K, crie proxies em cache para inspeção. Execute analyze_media.py para localizar mudanças de cena, silêncio, quadros pretos e intervalos congelados.
4. Transcreva para <過程>/transcripts/ com o provedor de nuvem/local aprovado, depois empacote as transcrições. Leia a transcrição empacotada, amostre quadros do início/meio/fim e pontos de edição ambíguos, e observe riscos de soletração do ASR.
5. Gere três prévias de estilo de legenda a partir de quadros representativos. Pergunte o ponto de verificação consolidado e salve o resumo aprovado.
6. Construa edl.json, forneça ou gere ativos aprovados e edite sem alimentar perguntas comuns de gosto.
7. Construa legendas. Para chinês, use build_cn_subtitles.py; para outros idiomas, use render.py --build-subtitles. Siga references/subtitles.md.
8. Execute validate_project.py, renderize uma prévia avaliável em 過程/verify/ e faça a auto-revisão. Limite os ciclos de correção/re-renderização a três antes de relatar um problema persistente.
9. Renderize <成品>/<projeto>_final.mp4 a partir das fontes originais, copie o SRT final para <成品>/<projeto>.srt e gere <成品>/<projeto>_逐字稿.md com export_transcript.py.
10. Execute quality_report.py, resolva todos os erros, revise visual e auditivamente os avisos, então marque o manifesto como entregue com project_state.py.
11. Entregue os três caminhos explícitos, relatório de QC, resumo de edição conciso e proveniência de ativos. Nunca faça o usuário procurar por final entre intermediários.

Correção de produção

• Aplique legendas por último, após cada sobreposição e corte.
• Derive candidatos a corte de limites de palavras e silêncio; nunca corte dentro de uma palavra. Use padding de 30–200 ms apropriado ao ritmo.
• Aplique fades de áudio curtos nos limites de segmento para evitar cliques.
• Normalize canvas, taxa de quadros, formato de pixel, espaço de cor, taxa de amostragem e layout de canal antes de juntar clipes.
• Armazene em cache transcrições e proxies por caminho de fonte, tamanho e hora de modificação; reexecute apenas quando essa assinatura mudar.
• Calcule timestamps de legenda na linha do tempo de saída, não na linha do tempo de origem.
• Garanta falas de linha única com segurança de pixels quando a linha única for aprovada; valide contra a fonte e o canvas reais.
• Use apenas ativos fornecidos pelo usuário, gerados, de domínio público ou compatíveis com licença. Registre título, criador, URL de origem, licença, data de download e atribuição necessária.
• Misture diálogo primeiro. Abafe a música sob a fala e ouça; a normalização de volume não pode salvar uma mixagem ruim.
• Mantenha o agente principal como proprietário do resumo criativo, EDL, temporização de legenda, linha do tempo final, mixagem e QC. Paralelize apenas trabalhos de entrada imutável que escrevam caminhos únicos.

Leia references/editorial-craft.md quando o projeto precisar de seleção multi-take, transições, gradação, animação, rampas de velocidade ou edição guiada por música. Leia references/edl.md antes de criar ou estender o EDL.

Helpers

• check_environment.py — dependência obrigatória/condicional e prontidão de credencial com URLs oficiais de configuração.
• project_workspace.py — criar ou reutilizar o projeto nomeado com pastas 成品/ + 過程/.
• project_state.py — registrar atomicamente pontos de verificação retomáveis, aprovações, revisões e caminhos de saída.
• inventory.py — sondar formatos de fonte e riscos de normalização.
• analyze_media.py — detectar mudanças de cena, silêncio, quadros pretos e quadros congelados.
• create_proxy.py — proxies leves de inspeção em cache mapeados para originais imutáveis.
• transcribe.py, transcribe_batch.py — transcrição em nível de palavra em cache com ElevenLabs ou Whisper local.
• pack_transcripts.py — visão compacta de edição em nível de frase.
• timeline_view.py — inspeção de tira de filme, forma de onda, palavras e pontos de corte.
• subtitle_style_preview.py — prévia exata de estilo/posicionamento libass em quadros reais.
• build_cn_subtitles.py — construção de falas com largura de pixel consciente para chinês.
• render.py — normalizar, cortar, juntar, sobrepor, mixar e então legendar por último.
• validate_project.py — verificações rápidas de falha de EDL, ativo, temporização e legenda.
• asset_registry.py — registro de licença, atribuição e soma de verificação de ativo com falha fechada.
• quality_report.py — relatório final de fluxo, duração, preto/congelado/silêncio e evidência de QC.
• build_cut_report.py — resumo de corte categorizado.
• apply_transcript_corrections.py — correções de fala/texto com falha fechada, log de auditoria e backup.
• export_transcript.py — transcrição legível e endereçável por fala para entrega.
• cleanup_session.py — limpeza opcional apenas após o usuário pedir explicitamente para deletar arquivos de processo; nunca interprete 完成 como deleção.

Resolva todos os helpers e referências relativamente ao diretório que contém este SKILL.md.

Comportamento de revisão

Trate a transcrição entregue pelo usuário como a fonte de verdade das palavras após ele corrigi-la. Para correções apenas de texto, mantenha a temporização das falas e as decisões de edição, corrija o SRT, valide e re-renderize. Para relatos de sincronia, inspecione a janela renderizada afetada e ajuste apenas os limites daquelas falas. Para mudanças editoriais, atualize o EDL e o relatório de corte, então execute todo o caminho de renderização/QC afetado.

Anexe cada sessão a 過程/project.md com estratégia, decisões aprovadas, proveniência de ativos, revisões, evidência de QC e problemas pendentes. Preserve 過程/ por padrão para que revisões futuras permaneçam baratas e rastreáveis.