Recomendado: Carregar Remotion Best Practices
Esta skill se beneficia de
remotion-best-practices(não incluído) para a biblioteca completa de padrões do Remotion. É opcional — as regras mínimas estão abaixo se ausente.
- Pi: leia a skill carregada em
remotion-best-practices(listada nas skills disponíveis).- Claude Code: invoque a skill/ferramenta
remotion-best-practicesantes de prosseguir.Não instalado? Obtenha em remotion-dev/skills (docs: remotion.dev/docs/ai/skills).
Se
remotion-best-practicesnão estiver instalado, regras mínimas: chromium deve estar disponível, sempre envolva conteúdo 4K em<Scale4K>, use<TransitionSeries>comlinearTiminge trate o áudio como clock mestre.
Video Podcast Maker
Pipeline automatizado para vídeos de conhecimento horizontais 4K para Bilibili a partir de um tópico. Agente de codificação + backend TTS + Remotion + FFmpeg.
Conteúdo
- Bootstrap — pré-requisitos (execute antes do Passo 1)
- Modos de Execução — Automático vs Interativo → references/workflow-script.md
- Regenerando um Vídeo Existente — iterar sobre um vídeo finalizado
- Fluxo de Trabalho — o pipeline de 11 passos + ponteiros de arquivos de fase + paradas obrigatórias
- Regras Rígidas — restrições de produção inegociáveis
- Clock Mestre de Áudio e Sincronia
- Estrutura por Vídeo
- Recursos Adicionais — quando carregar cada arquivo
references/ - Preferências do Usuário
- Solução de Problemas
Bootstrap
Resolva SKILL_DIR para o diretório que contém este SKILL.md:
- Pi: o agente conhece o caminho da skill a partir da lista de skills carregadas — defina
SKILL_DIRpara esse diretório antes de executar comandos. - Claude Code:
${CLAUDE_SKILL_DIR}é preenchido automaticamente.
SKILL_DIR="${SKILL_DIR:-${CLAUDE_SKILL_DIR}}"
# Pré-requisitos (CLIs + variáveis de ambiente do backend)
python3 "${SKILL_DIR}/scripts/check_prereqs.py"
As atualizações são feitas através do CLI de skills (npx skills update video-podcast-maker -g); instalações diretas via git-clone usam git pull conforme o README. Esta skill não realiza verificações de atualização.
Falhas de pré-requisitos — veja o README.md para configuração. A verificação é consciente do backend (resolve TTS_BACKEND env → user_prefs.json global.tts.backend → edge padrão), portanto apenas as variáveis de ambiente exigidas pelo backend ativo são validadas.
Primeiro vídeo em um novo projeto? Prefira reutilizar um projeto Remotion existente com node_modules/ já instalado — criar um novo projeto baixa ~2.2 GB de pacotes npm mais um shell headless Chrome de 90 MB (uma vez por projeto). Se o usuário tiver um projeto de um vídeo anterior, use-o. Se um novo projeto for necessário, execute npm install em segundo plano enquanto você faz os Passos 1-4 (pesquisa do tópico e escrita do roteiro).
Toda renderização vai para videos/{name}/ — cada output.mp4, final_video.mp4 e thumbnail_*.png vai diretamente para o diretório por vídeo. Nunca renderize para um diretório out/ ou dist/; a convenção --public-dir videos/{name}/ mantém tudo autocontido.
Mecanismo TTS — dois backends locais, sem skill externa:
edge(padrão) — gratuito, sem chave, via edge-tts.azure— precisa deAZURE_SPEECH_KEY+AZURE_SPEECH_REGION(Microsoft Speech SDK).
Cada um sintetiza internamente (scripts/tts/backends/native.py) — pronúncia
(exibição → falado → de volta para exibição para legendas) e aplicação de fonemas são
integrados. check_prereqs.py valida as variáveis de ambiente do backend ativo.
TTS multiplataforma? A antiga skill de componente ttscn que fornecia a matriz de 9 backends não é mais uma dependência desta skill. Se você quiser essas plataformas, instale Agents365-ai/ttsCN separadamente e chame-a diretamente — esta skill fornece apenas edge + azure.
Atalho de Aprendizagem de Design: Se o usuário fornecer um vídeo/imagem de referência ou pedir para salvar/listar/excluir perfis de estilo, veja references/design-learning.md em vez de executar o fluxo de trabalho abaixo.
Modos de Execução
Detecte o Modo Automático (padrão) vs Modo Interativo no início do fluxo de trabalho — a tabela de decisão padrão Automático e as substituições por solicitação estão em references/workflow-script.md.
Regenerando um Vídeo Existente
Se videos/{name}/ já existe e o usuário está iterando sobre um vídeo finalizado ou em andamento, reutilize esse diretório. NÃO inicie um novo projeto ou um novo videos/{newnome}/.
Escolha a menor reexecução para o que realmente mudou:
| Mudou | Reexecutar | Reutilizar (não refaça) |
|---|---|---|
Roteiro de narração (podcast.txt) | Passo 7 (TTS) → Passo 8 pré-visualização → renderizar+mix | pesquisa do tópico + design das seções |
| Apenas visuais (componentes, layout, cores) | Passo 8 pré-visualização → renderizar+mix | áudio (podcast_audio.wav / timing.json) |
| Apenas música de fundo | Remixar BGM | output.mp4 (sem re-renderizar) |
| Apenas legendas | Passo 10.1 finalizar | output.mp4 / video_with_bgm.mp4 |
Qualquer reexecução que altere o que o espectador vê ou ouve reentra na barreira do Passo 8: aplique a mudança, deixe o Studio recarregar a quente e aguarde uma nova confirmação explícita "renderizar 4K" — a confirmação anterior não é válida. Uma alteração de roteiro desloca todos os timestamps downstream, então sempre regenere timing.json através do TTS — nunca edite manualmente. Após qualquer reexecução, verifique novamente:
python3 ${SKILL_DIR}/scripts/verify_output.py videos/{name}/
Fluxo de Trabalho
Iterando sobre um vídeo finalizado? Se
videos/{name}/já existe, veja Regenerando um Vídeo Existente acima para a reexecução mínima — NÃO comece no Passo 1.
No início do Passo 1, crie uma tarefa para cada passo no seu rastreador de agente. Marque in_progress no início, completed ao finalizar. Os arquivos em videos/{name}/ são o registro durável — se interrompido, inspecione o diretório para determinar onde retomar.
| # | Passo | Saída | Arquivo de fase |
|---|---|---|---|
| 1 | Definir direção do tópico | topic_definition.md | workflow-script.md |
| 2 | Pesquisar tópico | topic_research.md | workflow-script.md |
| 3 | Projetar 5-7 seções | (em memória) | workflow-script.md |
| 4 | Escrever roteiro de narração | podcast.txt | workflow-script.md |
| 4.5 | Pré-verificação de pronúncia (zh-CN) | phonemes.json | workflow-script.md |
| 5 | Plano de ativos e resolução | assets/manifest.json | workflow-assets.md |
| 6 | Gerar miniaturas (16:9 + 4:3) | thumbnail_*.png | workflow-production.md |
| 7 | Gerar áudio TTS | podcast_audio.wav, timing.json | workflow-production.md |
| 8 | Composição Remotion + pré-visualização Studio | — | workflow-production.md |
| 9 | Renderizar 4K + mix BGM | output.mp4, video_with_bgm.mp4 | workflow-production.md |
| 10 | Informações de publicação + verificar saída | publish_info.md, final_video.mp4 | workflow-publish.md |
| 11 | Gerar verticais curtas (opcional) | shorts/ | workflow-publish.md |
Paradas obrigatórias (linhas em negrito acima):
- Passo 8 — Revisão Studio. DEVE lançar
npx remotion studioe aguardar feedback do usuário antes de renderizar. NUNCA renderize 4K até que o usuário confirme explicitamente ("renderizar 4K" / "renderizar final"). Uma resposta contendo solicitações de ajuste não é confirmação — aplique as alterações, deixe o Studio recarregar a quente e pergunte novamente. Cada rodada de ajustes precisa de sua própria confirmação antes do Passo 9. - Passo 10 —
verify_output.py. DEVE passar antes de declarar o vídeo concluído. Saída 0 = verde; saída 2 = avisos ainda publicáveis. Corrige automaticamente omissões comuns (criafinal_video.mp4se ausente). Valida informações de publicação (título, descrição, tags, capítulos) em relação à matriz de plataformas — gere-as nos Passos 5.5 e 10.2. Para saída legível por máquina, adicione--format json.
Auditoria pré-renderização (recomendada) — antes do Passo 8:
python3 ${SKILL_DIR}/scripts/audit_beat_sync.py <Video.tsx> <timing.json>
Sinaliza batidas que desviam > 1.5s da narração.
Modo Automático: auto-revisão visual. Ao executar no Modo Automático (sem usuário assistindo Studio), renderize 3-5 quadros-chave estáticos antes de pedir confirmação de renderização:
npx remotion still src/remotion/index.ts <CompositionId> videos/{name}/_review_001.png --public-dir videos/{name}/ --frame=<midpoint_frame>
Escolha quadros em: título principal (~10% de início), meio de uma seção densa e final. Leia os quadros estáticos como imagens e execute as listas de verificação de design-guide.md e visual-taste.md contra a saída renderizada real. Capture transbordamento, contraste e regressões de layout antes da renderização 4K. Exclua _review_*.png após a revisão.
Pontos de Verificação de Validação
| Após Passo | Verificar |
|---|---|
| 7 (TTS) | podcast_audio.wav toca · timing.json cobre todas as seções · SRT é UTF-8 |
| 9 (Render) | output.mp4 é 3840×2160 · sincronia áudio-vídeo · sem quadros pretos |
| 10 (Verificar) | verify_output.py saída 0 (ou 2 com avisos revisados) |
Regras Rígidas
| Regra | Requisito |
|---|---|
| Projeto Único | Todos os vídeos em videos/{name}/ no projeto Remotion do usuário. NUNCA crie um novo projeto por vídeo. |
| Saída 4K | 3840×2160 (ou 2160×3840 vertical), use wrapper scale(2) sobre espaço de design 1920×1080 |
| Sincronia de Áudio | Áudio (podcast_audio.wav + podcast_audio.srt) é o clock mestre. timing.json DEVE ser gerado a partir da saída TTS real, nunca estimado manualmente. Antes de renderizar, a duração do vídeo final deve corresponder ao áudio dentro de ±0.5s. Veja Clock Mestre de Áudio e Sincronia. |
| Miniatura | DEVE gerar ambos 16:9 (1920×1080) E 4:3 (1200×900) — veja design-guide.md |
| Studio Antes de Renderizar | DEVE lançar remotion studio para revisão. NUNCA renderize 4K até que o usuário confirme explicitamente. Feedback de ajuste ≠ confirmação — aplique, recarregue a quente, pergunte novamente. |
--public-dir | Todo comando Remotion usa --public-dir videos/{name}/. Todos os arquivos de saída (output.mp4, final_video.mp4, miniaturas) vão diretamente para videos/{name}/ — nunca para um diretório out/ ou dist/. |
Mínimos visuais (tamanhos de texto, largura de conteúdo, zonas seguras, segurança de animação) estão em references/design-guide.md. DEVE carregar antes do Passo 8.
Clock Mestre de Áudio e Sincronia
Regras de ouro
- Áudio é o clock mestre. Cada início de slide, legenda, capítulo e batida de animação é derivado de
podcast_audio.wavepodcast_audio.srt. - Gere temporização a partir do TTS, não de estimativas de texto. Pipeline:
podcast.txt→generate_tts.py→podcast_audio.wav+podcast_audio.srt+timing.json→ composição → renderizar. - Nunca escreva
timing.jsonmanualmente antes do áudio existir. Se você já tiver slides curados, executealign_timing_from_srt.pypara ancorá-los ao SRT real. - Compense a sobreposição do TransitionSeries.
TransitionSeriesrenderizasum(section.duration_frames) - (N-1) * transitionFramesquadros. Escale cada seção proporcionalmente para manter o comprimento renderizado igual atiming.total_frames. Não coloque todos os quadros de sobreposição na primeira seção. O padrão corrigido está emtemplates/Video.tsx.
Pontos de verificação de sincronia obrigatórios
| Quando | Verificar |
|---|---|
| Após Passo 7 (TTS) | timing.json.total_duration corresponde a podcast_audio.wav dentro de ±0.5s |
| Antes de renderizar | Video.tsx escala todas as seções para sobreposição de transição |
| Após renderizar | final_video.mp4 duração corresponde a podcast_audio.wav dentro de ±0.5s |
| Passo 10 (verificar) | verify_output.py saída 0 e relata verde em áudio/temporização |
Se qualquer ponto de verificação falhar, pare. Não publique.
Especificações de Saída
| Parâmetro | Horizontal (16:9) | Vertical (9:16) |
|---|---|---|
| Resolução | 3840×2160 (4K) | 2160×3840 (4K) |
| Taxa de quadros | 30 fps | 30 fps |
| Codificação | H.264, 16Mbps | H.264, 16Mbps |
| Áudio | AAC, 192kbps | AAC, 192kbps |
| Duração | 1-15 min | 60-90s (destaque) |
Estrutura por Vídeo
project-root/ # Raiz do projeto Remotion
├── src/remotion/ # Código fonte Remotion (Root.tsx, composições, index.ts)
├── videos/{video-name}/ # Diretório por vídeo
│ ├── topic_definition.md # Passo 1
│ ├── topic_research.md # Passo 2
│ ├── podcast.txt # Passo 4: roteiro de narração
│ ├── phonemes.json # Passo 4.5: substituições de pronúncia zh-CN
│ ├── assets/manifest.json # Passo 5: registro de ativos por seção
│ ├── publish_info.md # Passo 10: título/descrição/tags
│ ├── podcast_audio.wav # Passo 7: áudio TTS
│ ├── podcast_audio.srt # Passo 7: legendas
│ ├── timing.json # Passo 7: linha do tempo (direciona animações)
│ ├── thumbnail_*.png # Passo 6
│ ├── output.mp4 # Passo 9: renderização 4K
│ ├── video_with_bgm.mp4 # Passo 9: com BGM
│ ├── final_video.mp4 # Passo 10: saída final
│ └── bgm.mp3 # Música de fundo
└── remotion.config.ts
--public-dir por vídeo
Todo comando Remotion usa --public-dir videos/{name}/ — os ativos de cada vídeo permanecem em seu próprio diretório, permitindo renderizações paralelas:
npx remotion studio src/remotion/index.ts --public-dir videos/{name}/
npx remotion render ... videos/{name}/output.mp4 --public-dir videos/{name}/ --video-bi
…
[truncado para tradução]
Recursos Adicionais
| Fase | Arquivo | Quando carregar |
|---|---|---|
| Modos de execução | references/workflow-script.md | Antes do Passo 1 |
| Plano de ativos | references/workflow-assets.md | Antes do Passo 5 |
| Produção & Remotion | references/workflow-production.md | Antes do Passo 7 |
| Publicação | references/workflow-publish.md | Antes do Passo 10 |
| Guia de design | references/design-guide.md | Antes do Passo 8 |
| Paleta visual | references/visual-taste.md | Antes do Passo 8 |
| Aprendizagem de design | references/design-learning.md | Quando o usuário fornecer referência visual |
| Modelos de componentes | templates/ | Ao projetar composições Remotion específicas |
Preferências do Usuário
As preferências são armazenadas em user_prefs.json na raiz do projeto. Este skill as aplica silenciosamente:
global.tts.backend:"edge"|"azure"— o backendcheck_prereqs.pyvalidaglobal.tts.voice: string de voz (ex.:"zh-CN-XiaoxiaoNeural")global.bgm.path: caminho personalizado para BGM padrão (ex.:"/music/bgm.mp3")global.output.platform: string de plataforma padrão ("bilibili"|"youtube")global.output.resolution:"3840x2160"ou"2160x3840"global.subtitle.enabled: booleano — ativar/desativar legendas queimadasglobal.subtitle.language: para seleção de idioma de legenda TTS- Por projeto:
videos/{name}/.prefs.jsonsubstitui chaves globais para aquele vídeo.
Solução de Problemas
"Falha no check_prereqs"
- Verifique
TTS_BACKENDem.envouuser_prefs.json→global.tts.backend. - Certifique-se de que
edge-ttsouazure-cognitiveservices-speechestá instalado (pip list | grep tts). - Para Azure: confirme
AZURE_SPEECH_KEYeAZURE_SPEECH_REGION.
Renderização falha com erro de memória
- Reduza
concurrencyPerFrameemremotion.config.ts. - Feche outros aplicativos pesados (navegador, IDE).
Dessincronia áudio-vídeo
- Execute
audit_beat_sync.py— veja Clock Mestre de Áudio e Sincronia. - Verifique se
timing.jsonfoi gerado a partir do TTS real, não de estimativa textual. - Certifique-se de que
--public-direstá definido e os caminhos dos recursos estão corretos.
"verify_output.py" reporta falha
- Leia a saída — ela geralmente indica o arquivo exato e o problema (ex.:
final_video.mp4ausente). - Se saída 2 com aviso que você revisou, publique mesmo assim.
- Execute com
--format jsonpara análise programática.