Contador de histórias automático animado
Forneça um arquivo de voz e um roteiro. Ele finaliza o filme inteiro: temporização, layout, renderização, cortes, legendas, som, mixagem e QA. Sem storyboard manual, sem código de cena, sem timeline de edição.
python scripts/run.py --project meu-filme --voice voz.mp3 --script roteiro.md
Esse único comando executa o pipeline completo e gera meu-filme/out/FILME.mp4, meu-filme/out/FILME.srt (ao lado de captioned.mp4), credits.md, beats.json, plan.json, beats.md, imagens de revisão em out/qa/ e todos os intermediários.
Antes de começar — a verificação de pré-requisitos (automática)
Toda execução começa com check_requirements.py, antes de qualquer outra coisa. Se todas as ferramentas disponíveis estiverem instaladas, a produção continua imediatamente — sem necessidade de configuração. Se algo estiver faltando, é baixado/instalado automaticamente, e então a produção continua.
Ela verifica, em ordem:
- Python 3.8+
- Pacotes Python — numpy, skia-python, Pillow, faster-whisper — instalados via pip automaticamente se ausentes
- ffmpeg + ffprobe no PATH — instalado automaticamente via
winget(Windows),brew(macOS) ouapt-get(Linux) se ausente - cinematic-film ao lado desta habilidade (ou
CINEMATIC_SCRIPTS=<caminho para seus scripts>)
Se tudo estiver presente: uma linha — requirements: ok — e a construção começa. Se um pacote Python não puder ser instalado, o script imprime o comando exato para corrigi-lo e encerra, em vez de iniciar uma construção condenada. Se o cinematic-film não for encontrado, o mesmo — você recebe exatamente o que está faltando e o que configurar.
O que ele faz (o visual)
Duas linguagens visuais que alternam rigorosamente a cada 3-10 segundos, decididas por bloco pelo diretor:
- Board - uma folha de blueprint em tela cheia. As palavras aparecem como tipografia de giz desenhada à mão em uma grade azul escura, com caixas de chamada de esboço retangulares, traços oscilantes, janelas de código rabiscado, marcas de verificação, divisores e ícones neon (dois passes de brilho + núcleo quente) que são desenhados em código.
- Photo - a parede de evidências noturna do cinematic-film: fotos reais licenciadas do Wikimedia Commons fixadas com sombra e alfinete, documentos de papel datilografados, regras de destaque irregulares, ícones neon brilhantes, todos creditados em
credits.md.
As legendas são centralizadas na parte inferior e rentes à borda inferior (6 px em 720p, escalando com a resolução), em maiúsculas, uma de nove tintas doces definidas por semente, com entrada suave (subir/pular/deslizar/inclinar/desvanecer/limpar/avançar) e saída (desvanecer/cair/sair/encolher), halo de flor três passagens, um gradiente arco-íris na palavra falada (traço branco de tubo neon). Um gradiente atrás da faixa mantém a legibilidade em qualquer fundo. O texto espelha a voz exatamente.
Começar do zero vs. retomar
- Novo projeto: forneça a voz e o roteiro; a habilidade constrói tudo.
python scripts/run.py --project meu-filme --voice voz.mp3 --script roteiro.md - Retomando: reexecutar em um projeto que já tem
out/FILME.mp4(e o plano/fotos) reverifica apenas com QA — nada é baixado ou renderizado novamente. Adicione--forcepara reconstruir do zero.
Entradas
--voice: qualquer arquivo de áudio que o ffmpeg leia (mp3/wav/m4a...). Melhores resultados de uma narração limpa em uma única tomada. É usado como está, apenas convertido para AAC estéreo 48 kHz.--script:.md/.txt/.srt/.json. Cabeçalhos Markdown se tornam indicadores de seção na tela; linhas em branco e parágrafos são divididos em frases, depois em blocos de legenda (<= 9 palavras / <= 64 caracteres). O texto na tela é o texto no arquivo, literalmente.script.jsoncom{"title": ..., "takes": [...]}é respeitado quando presente.
Opções
| Flag | Efeito |
|---|---|
--size 1920x1080 | tamanho de renderização (padrão 1920x1080) |
--crf 16 | qualidade (menor = melhor; 16 filme, 26 visualização) |
| `--photos auto | existing |
| `--music auto | none |
--model tiny.en | tamanho do faster-whisper para alinhamento (base.en/small.en são mais precisos) |
--preview | renderizar apenas blocos 0-1 em 640x360 para uma olhada rápida |
--skip-render | apenas replanejar (sem renderização) |
--workers WORKERS | trabalhadores de renderização + legenda (0 = todos os núcleos menos um) |
--force | reconstruir mesmo se um out/FILME.mp4 finalizado já existir |
Desempenho e segurança
- Cache de produção em
E:\Storyteller catche files(substitua comSTORYTELLER_CACHE). Todo artefato pesado é armazenado em cache sob um hash de conteúdo, então reexecutar ou ajustar estágios posteriores refaz apenas o que mudou:
| Pasta | O que é armazenado em cache | Chave |
|---|---|---|
whisper/ | temporizações de palavras do faster-whisper | arquivo de voz + modelo + dispositivo |
commons_search/ | conjuntos de resultados de pesquisa do Commons | consulta + limite |
commons_files/ | originais do Commons baixados + sidecars de crédito | título do Commons |
blocks/ | blocos de estilo renderizados | cena + beats + geometria do bloco + tamanho + CRF |
silent/ | filme silencioso costurado | arquivos de bloco + CRF + fps |
captioned/ | filme legendado + SRT | vídeo + temporização + código de legenda + CRF |
sfx/ | barramento SFX sintetizado | folha de dicas + build_sfx.py |
music/ | base de trilha sonora em loop | arquivo de trilha + duração do filme |
mix/ | mixagem de áudio finalizada | voz + dicas + música + níveis + LUFS |
Os arquivos são nomeados <label>-<hash12>.<ext> e classificados por tipo (uma listagem sort lê naturalmente), com um manifesto index.jsonl somente anexação e um README.txt na raiz. Erros de cache reconstroem automaticamente; excluir o cache é sempre seguro. Uma reexecução completa de estágios inalterados leva segundos (whisper/blocos/costura/legendas/sfx/mixagem todos acertam).
- Cada bloco é renderizado separadamente, depois os blocos são costurados com um filtro
concatpreciso por quadro. Reexecutar após uma edição de roteiro apenas re-renderiza blocos cujo plano mudou (render_blocks.pyreutiliza arquivos de bloco atualizados, mais o cache de produção como segunda camada). - 12 núcleos / bastante RAM: use
--workers 6. Um filme de 3 minutos em 1080p leva aproximadamente 15-30 min. - Nunca renderize o filme final sem que o usuário peça: use
--previewou um--sizepequeno primeiro, mostre-o, e só então produzaFILME.mp4no tamanho completo. - Whisper tiny.en é aproximadamente 1x o tempo real na CPU; use
--model base.ense as temporizações se desviarem em linhas longas.
O que o diretor faz
Cada linha de legenda se torna um beat. Um beat recebe exatamente um layout escolhido de suas palavras:
| Layout | Gatilho | Desenho |
|---|---|---|
title / end | primeiras 2 / últimas 2 linhas | ícone neon + título grande em giz (título = título em maiúsculas das palavras de conteúdo da linha) |
chain | primeiro/segundo/então/processo/pipeline | 3 caixas de esboço com setas |
split | antes/depois/versus/comparado/em vez de | dois quadros rotulados de cada lado de um divisor rasgado |
window | código/script/terminal/agente/modelo/servidor | janela de terminal desenhada à mão com linhas rabiscadas + linha destacada |
check | proteger/remendar/assegurar/prevenir/nunca | marcas de verificação em giz descendo uma lista |
stat | qualquer número | numeral enorme brilhante |
quote | todo o resto / perguntas | citação destacada em giz |
| variantes de foto | todo outro bloco | station (foto + cartão), doc (documento de papel + selo), stat |
Linhas consecutivas (1-4, máx ~9 s, cortadas em finais de frase) agrupam-se em blocos; blocos alternam board/foto ao longo do filme. Primeiro e último blocos são sempre board.
Arquivos escritos
audio/narration.m4a voz normalizada
audio/timing.json início/fim por linha (esquema do mecanismo)
script.json takes em ordem de fala, ordem de id preservada
beats.json por linha: início/fim/layout/kicker/headline/pontos/número/ícone/tinta/foto/x
plan.json blocos (estilo, intervalo de quadros, mundo x), fps, duração
beats.md tabela legível de todo o plano
sfx_cues.json efeitos sintetizados para build_sfx.py
photos.json seleções do Commons com licença/crédito/fonte
out/blocks/bNNN.mp4 um clipe por bloco de estilo
out/silent.mp4 imagem costurada
out/captioned.mp4 + legendas neon gravadas (+ .srt)
out/FILME.mp4 final, com áudio mixado
out/qa/*.png imagens de revisão
credits.md créditos de imagem + música
Portões de QA (scripts/qa.py, executado automaticamente pelo run.py)
Falha na construção em: incompatibilidade de contagem de quadros vs timing.total_duration * fps, fluxo de áudio ausente/!áudio, volume fora de -15 +/- 1.5 LUFS, pico verdadeiro > -0.8 dBTP, um bloco de legenda não visível, ou uma linha de base de legenda a mais de 8.5 % da altura do quadro acima da borda inferior.
Habilidades complementares (como uma produção realmente é concluída)
Esta habilidade é a orquestradora dedicada para o fluxo de trabalho de filme educacional/explicativo ("vídeo como o filme do agente de exploração de IA"). Ela aciona duas habilidades complementares para finalizar uma produção, exatamente como os filmes anteriores foram feitos — você nunca as chama diretamente; run.py e qa.py fazem isso. A regra é absoluta: nunca edite uma habilidade complementar — ou qualquer outro projeto (ex.: C:\remotion-build\dark-reality-explainer) — para fazer esta funcionar; acione-as como elas são fornecidas. Toda a lógica de orquestração, cache, QA e decisões de estilo residem aqui nesta habilidade.
1. cinematic-film — o mundo, as fotos, o som (obrigatório, dependência rígida)
Localizado ao lado desta habilidade (substitua com CINEMATIC_SCRIPTS=<caminho para seu diretório de scripts>). Chamado por:
| Script | Usado por | O que faz para este filme |
|---|---|---|
prep_assets.py | estágio prep | classifica as fotos do Commons para o visual preto-e-branco (`--grade bw |
fetch_commons.py | fetch_photos.py | baixa os originais licenciados (get), preenche arquivo/crédito/licença, e escreve credits.md (credits) |
render.py | render_blocks.py | renderiza cada bloco de estilo com --t0/--t1; desenha o mundo board/foto, a câmera e cada item por quadro |
engine.py | storyboard.py, cada renderização | o modelo de mundo: Film, chaves de câmera, Board, PaperDoc, StylePanel, a câmera spline |
captions.py | captions_burn.py | o relógio de palavras (words_with_times) usado para temporizar a palavra quente |
build_sfx.py | audio_finish.py | sintetiza o barramento de efeitos a partir de sfx_cues.json (sem biblioteca de samples para licenciar) |
mix_soundtrack.py | audio_finish.py | voz + SFX + trilha: SFX -19 dB, música -18 dB, redução 4:1, master -15 LUFS / -1.5 dBTP |
Regras de engajamento: não edite seus scripts para esta habilidade — mudanças de comportamento pertencem a storyboard.py / render_blocks.py / aqui. Seus contratos CLI (--t0/--t1, fetch_commons get|credits, mix_soundtrack --lufs) são o que o cache de produção hasheia; se o cinematic-film mudar um, atualize o estágio aqui e exclua E:\Storyteller catche files para que nenhum resultado obsoleto sobreviva.
2. remotion-studio — visualização no navegador / direção (opcional, apenas revisão)
npx remotion studio (abra a URL impressa; ou --no-open e abra a URL você mesmo).
Escopo honesto, para que ninguém perca tempo: Studio apenas visualiza composições Remotion — componentes React registrados em um projeto Remotion. Ele não pode reproduzir o mestre finalizado desta habilidade (out/FILME.mp4 é uma renderização skia/ffmpeg, não um projeto Remotion; nem o filme do ataque de IA era). Use quando o entregável também existir como um projeto Remotion e você quiser a experiência de visualização enquanto edita (ou para dirigir uma variante baseada em Remotion). Para revisar a saída desta habilidade, use out/FILME.mp4 / out/preview_captioned.mp4 mais as imagens de out/qa/ — Studio não tem nada a anexar.
A receita de produção (como todas as três habilidades completam um filme, como da última vez)
- Voz + roteiro ->
run.py --preview(2 blocos, 640x360, ~2 min). Verifique o visual, o ritmo board/foto, o tamanho da legenda e a posição rente à borda inferior, e queqa.pydiga PASS. - Plano completo — ingestão (alinhamento whisper) -> diretor (beats, layouts, alternância de estilo) -> fotos do Commons (licença gratuita, créditos em
credits.md) -> preparação (classificação pb) -> cena -> dicas. - Renderização — cada bloco separadamente em 1080p; reutilize via cache de produção em
E:\Storyteller catche files. - Finalização — costura (filtro concat) -> legendas neon rentes à borda inferior -> SFX
-19 dB/ trilha-18 dB, com redução, master-15 LUFS. - Revisão —
out/FILME.mp4é reproduzido;out/qa/contém as imagens fixas. Se uma etapa de empacotamento/revisão Remotion for desejada, abra esse projeto Remotion comremotion studioe verifique se ele carrega lá. - Entrega —
FILME.mp4+FILME.srt+credits.md. Upload/exportação ocorre fora desta habilidade.
Lado SRT / distribuição da produção
Após qa PASS: out/captioned.srt fica ao lado de out/captioned.mp4 (a etapa de finalização pode copiá-lo ao lado de FILME.mp4). Para variantes sociais (recortes 9:16, exportações para plataformas, preparação de miniaturas), use uma habilidade de distribuição em vez de re-renderizar nesta — esta habilidade produz apenas o mestre 16:9.
Requisitos
Veja Antes de começar — a verificação de pré-requisitos acima: Python 3.8+, numpy, skia-python, Pillow, faster-whisper, ffmpeg/ffprobe no PATH, e a habilidade cinematic-film ao lado desta (substitua com CINEMATIC_SCRIPTS). A verificação é executada automaticamente no início de cada execução.
Limitações conhecidas
- O alinhamento usa whisper tiny.en por padrão; uma tomada murmurando pode se desviar durante...
[truncado para tradução]