Communitygithub.com

scripted-video

Planeje, pesquise, escreva, revise e exporte vídeos que são escritos como scripts (dados e código, não edição de linha do tempo) e renderizados para mp4.

O que é scripted-video?

Esta skill permite a criação de vídeos totalmente baseados em texto, usando um formato de script estruturado que é processado por um motor para gerar imagens em um navegador e exportá-las como arquivos `.mp4` com som, legendas e capítulos. O foco principal não é a edição de vídeo tradicional, mas sim o processo de pesquisa, planejamento e escrita de um roteiro que conta uma história verdadeira e ensina algo de forma clara. A skill é ideal para criar tutoriais, explicações, aulas, demonstrações de produtos, apresentações animadas, vídeos para YouTube, clipes verticais curtos ou tutoriais em aplicativos. A skill é suportada em plataformas como Claude Code, Cursor, Codex e outros agentes de IA que podem seguir um processo detalhado. O processo é dividido em estágios que vão desde a definição do briefing, passando pela pesquisa em várias rodadas, criação de um mapa mental, storyboard, escrita do script, revisões de precisão e compreensão, revisão visual, adição de voz e som, exportação e entrega final. O motor usa Node.js e `ffmpeg` para gerar os vídeos, e todo o trabalho é baseado em arquivos de texto que podem ser revisados e corrigidos sem a necessidade de re-edição visual, tornando o processo eficiente e auditável.

Funciona com~Claude Code✓Codex CLI~Cursor
npx skills add https://github.com/utoappia/skill-tutorial_video_creation/tree/HEAD/skills/scripted-video

Perguntar na sua IA favorita

Abre um novo chat com esta habilidade de agente já pré-carregada.

Documentação

Vídeo roteirizado

Aqui, um vídeo é um script: um arquivo que diz o que é falado, o que está na tela e quando. Um motor pequeno (em starter/) transforma isso em imagens em um navegador e em um .mp4 com som, legendas e capítulos. Como o vídeo é texto, você pode escrevê-lo, verificá-lo, revisá-lo linha por linha, olhar cada quadro, traduzi-lo e corrigir uma palavra sem re-editar nada.

O motor é a metade fácil. Um vídeo que ensina precisa de uma história verdadeira, contada em uma ordem que o espectador possa seguir, com palavras que ele conheça, com imagens que apontem para o que a voz nomeia. A maior parte desta skill é sobre essa metade. Siga os estágios em ordem; cada um deixa um arquivo que o próximo lê, para que o trabalho sobreviva a uma sessão longa e um segundo agente possa retomá-lo.

Objetivo: entregar um vídeo que o solicitante não precise corrigir. O tempo dele é o custo que você está economizando. Então: decida o que puder decidir e escreva a decisão; use todos os serviços, chaves e fatos que ele ofereceu; antes de entregar, veja o vídeo como ele verá (veja "Antes de entregar"). As primeiras coisas que um solicitante percebe quase nunca são violações de regras que um verificador pode encontrar. São uma suposição que o vídeo nunca respondeu, um assunto sem nada real nele e um vídeo que soa inacabado.

Três princípios valem para todos os vídeos sobre o mundo. Cada um é declarado aqui uma vez; os estágios abaixo os aplicam e references/research.md fornece o método.

  • Conte na profundidade central; pesquise um nível mais fundo. O vídeo que você entrega é o núcleo: a narração mais curta que mantém a promessa e é verdadeira e justa: cerca de 10 a 20 minutos para um assunto com histórias reais, menos para um mecanismo único. Um comprimento que o solicitante nomeia é um limite e vence; a profundidade da pesquisa então encolhe com ele. A pesquisa vai um nível além, até a profundidade de um detalhe (as pessoas, os dias decisivos, os meios exatos, as figuras rivais, o que as investigações encontraram), para que o núcleo seja escolhido com conhecimento, e para que assuntos vizinhos apareçam: um evento, uma instituição ou uma ideia que toca o tópico principal e tem sua própria história. Cada um se torna uma linha de research/next-videos.md com o que já é conhecido, e não é pesquisado mais. Abaixo de um detalhe (a vida posterior de cada pessoa, cada documento na íntegra, toda a história de uma instituição) está a pesquisa de outro vídeo: em um trabalho, ir até lá cresceu o vídeo para seis horas quando o núcleo de 18 minutos era o que o solicitante queria. Versões mais longas são feitas apenas mediante solicitação.
  • Todo exemplo real mostra o tópico principal em ação. Uma história real entra no vídeo apenas se a coisa sobre a qual o vídeo trata realmente acontece nela, conforme as fontes contam: para um vídeo sobre mercados futuros, contratos futuros negociados em uma bolsa, margem chamada, um contrato liquidado. Uma história que é apenas próxima (os mesmos anos, um nome famoso, uma aposta que parece semelhante, mas foi feita de outra forma) fica de fora, por mais famosa que seja e mesmo que o solicitante a tenha sugerido. Verifique isso nas fontes na rodada 1, antes que qualquer profundidade seja gasta nela. Em um trabalho, a história mais famosa oferecida para um vídeo sobre futuros acabou sendo uma aposta feita através de acordos privados com bancos; foi retirada depois que duas edições a contaram. Curto não é superficial, no entanto: no núcleo, cada exemplo real é contado com suas pessoas, sua data, os meios exatos, os valores, como poderia ter ido para o outro lado, como terminou e o que mostra sobre o tópico principal.
  • A pesquisa tem uma borda e um fim. Cada lead é testado contra o tópico principal antes que uma busca seja gasta nele; um que falha é escrito em uma linha e deixado de lado ("interessante" não o abre). Existem três rodadas planejadas (o esboço, o detalhe e uma dupla verificação, nas fontes, de tudo que o vídeo dirá) e uma quarta curta apenas para itens nomeados que o núcleo precisa. Mais é decisão do solicitante.

Espectador padrão: alguém encontrando o assunto pela primeira vez. Escreva de forma que uma criança de 8 anos pudesse acompanhar, em uma linguagem calma e profissional que um adulto não consideraria infantil. Simples não é o mesmo que infantil: frases curtas, palavras do dia a dia, uma ideia de cada vez, sem baby talk. Mude isso apenas se o briefing nomear um espectador diferente.

Configuração

Copie a pasta starter/ desta skill para o projeto do usuário (por exemplo, como video/), depois:

cd video
npm install            # uma pequena dependência; usa o Chrome já na máquina
node tools/check.mjs   # o vídeo de exemplo deve passar

Precisa de: Node 18 ou mais recente; Chrome, Edge ou Chromium (para desenhar imagens); ffmpeg (para gravar a voz e exportar). Se algum estiver faltando, veja references/troubleshooting.md. Não trabalhe dentro da própria pasta da skill; trabalhe na cópia.

A cópia contém um exemplo, videos/hello.json: quinze segundos em dados simples, com uma tradução e um layout vertical, usado para verificar se a configuração funciona. O que cada estágio deve produzir está nos arquivos que node tools/new.mjs cria: cada um começa com sua própria lista de verificação. Exclua o exemplo quando o próprio vídeo do usuário estiver em andamento.

Os estágios

Inicie todo vídeo com node tools/new.mjs <id> "<Título>". Ele cria notes/<id>/ (os arquivos nomeados abaixo, com suas listas de verificação) e um esqueleto de script em videos/<id>.mjs.

#EstágioVocê produzFeito quandoLeia
0Briefingnotes/<id>/brief.mdO espectador, a promessa ("após assistir, o espectador pode …"), a duração, a forma e o idioma estão escritos, com tudo o que o solicitante pediu pelo nome.abaixo
1Método de pesquisaresearch/00-how-to-research.mdVocê sabe como as pessoas que conhecem este campo descobrem coisas e onde os iniciantes erram.references/research.md
2Pesquisa, em três rodadasresearch/NN-name.md, research/leads.md, research/next-videos.md, research/index.mdTodo lead em leads.md está encerrado (pesquisado, não encontrado, próximo vídeo, fora do tópico ou aberto); cada exemplo real passa no teste de exemplo e é conhecido até a profundidade de um detalhe; outras visões e mitos são pesquisados; a rodada 3 releu em sua fonte cada afirmação destinada ao vídeo, e cada uma tem uma fonte e um rótulo de confiança; o que o solicitante lembra tem um veredito. A lista completa: references/research.md, seção 11.references/research.md
3Mapa mentalmindmap.jsonToda ideia pesquisada é core (no vídeo), support (pesquisada e verdadeira, mantida fora do núcleo) ou cut (não confirmada, injusta ou fora do tópico); as ideias core sozinhas mantêm a promessa; node tools/mindmap.mjs <id> não relata erros.references/planning.md
4Storyboardstoryboard.md, assets.mdCada batida tem uma imagem, uma essência, um componente e um som (geralmente nenhum); as verificações no final estão marcadas.references/planning.md
5Scriptvideos/<id>.mjsnode tools/check.mjs <id> não relata erros e você leu todos os avisos. O script está no comprimento do núcleo.references/authoring-kit.md, references/components.md
6Revisão de precisãoreview/accuracy.md, research/index.md (review/coverage.md apenas para um relato completo)Cada linha de dump --claims tem um veredito e uma fonte; para cada história real, um revisor que não a escreveu comparou script, notas e fontes (ou, sem um segundo agente, você o fez, e o arquivo diz "não independente"); a pesquisa foi relida contra o script, e o que o núcleo precisava e faltava agora está nela; as correções são escritas de volta nas notas.references/script-review.md
7Revisão de compreensãoreview/WhatIHaveLearned.md, review/lost-points.mdO diário atinge a promessa sem lacunas, e toda maneira de se perder tem uma correção ou uma razão.references/script-review.md
8Revisão visualreview/visual.mdVocê olhou para todos os quadros e nada está cortado, coberto, vazio ou ilegível.references/visual-review.md
9Voz e somlinhas gravadas em out/tts/, sons em assets/<id>/O script passou pelos estágios 6 a 8 e a voz está gravada; o tempo agora segue a voz real. Os sons de eventos estão definidos; a música, se houver, fica apenas sob as partes da história.references/voice-and-assets.md
10Exportar e assistir finalout/<id>.mp4, .srt, .vtt, .chapters.txtVocê olhou para os quadros do próprio arquivo exportado e verificou seu som.references/export-and-publish.md
11Outros idiomas e formatos (se solicitado)videos/i18n/<id>.<lang>.jsonCada idioma passa em check, e seus quadros foram examinados.references/localization.md
12Kit de publicaçãopublish.mdTítulo, descrição, capítulos, legendas, miniatura, fontes e créditos estão prontos.references/export-and-publish.md
13Entregaa mensagem para o solicitanteA verificação com os olhos do solicitante está feita; a mensagem diz o que foi decidido, o que foi corrigido e o que ainda está em aberto.references/finishing-and-revising.md

As regras de escrita que se aplicam a partir do estágio 4 estão em references/writing-for-everyone.md (palavras e frases) e references/teaching-techniques.md (como fazer uma ideia ser compreendida). references/visual-design.md cobre layout, cor e movimento. Leia esses três antes de escrever seu primeiro script.

Estágio 0: o briefing

Preencha brief.md a partir do que o usuário disse. Para todo o resto, escreva sua melhor suposição e marque-a como "(assumido)"; não pare para perguntar (veja "Decida, registre, continue"). A linha mais importante é a promessa: uma frase começando com "Após assistir, o espectador pode …". Toda decisão posterior (o que pesquisar, o que cortar, quando o vídeo está pronto) é testada contra ela. Registre também o que o espectador já sabe, porque é aí que o vídeo começa.

Copie para o briefing, nas próprias palavras do solicitante, tudo o que ele pediu pelo nome: um serviço a ser usado, uma chave e onde ela está, um exemplo ou evento a incluir, um fato que ele lembra, uma parte que ele achou confusa, um limite ("a maior parte sem música"). Cada um desses é uma linha a ser marcada antes de você entregar. Um serviço nomeado é verificado quanto à acessibilidade agora, não no estágio 9; um fato que ele lembra vai para a pesquisa como algo a verificar, não como algo a repetir.

Decida aqui se a pesquisa é necessária. Pule os estágios 1 e 2 apenas quando o conteúdo for totalmente fornecido (o próprio produto do usuário, um script que ele escreveu, um processo que ele descreveu) e você não adicionar fatos próprios. Se você adicionar mesmo um número, data, nome ou "porque", pesquise.

Estágios 1 e 2: pesquisa

Antes de pesquisar o assunto, pesquise como pesquisá-lo: duas ou três buscas sobre como as pessoas aprendem e investigam este campo, e um nível acima (para o mercado de títulos: "como entender o mercado de títulos", depois "como aprender sobre a economia"). Elas dizem quais fontes contam, quais números importam e onde os iniciantes erram. Depois, três rodadas:

  1. O esboço. Uma nota por tópico, com um resumo no topo: fatos com fontes, eventos reais (cada um testado primeiro pelo teste de exemplo), comparações cotidianas e as opiniões e mitos contrários mais fortes, pesquisados com tanto cuidado quanto a linha principal.
  2. O detalhe. Liste cada pessoa, lugar, data, número, termo, mecanismo, causa e citação que as notas mencionam sem explicar, em research/leads.md. Pesquise aqueles que dizem respeito ao tópico principal, uma vez, até a profundidade de um detalhe. Assuntos vizinhos vão para next-videos.md; o restante é marcado como fora do tópico.
  3. A dupla verificação. Nenhum novo assunto. Leia novamente, em sua fonte, tudo o que o vídeo dirá; encontre uma segunda fonte independente para as afirmações surpreendentes, os números que dão a magnitude da história, as citações e qualquer coisa que reflita mal sobre uma pessoa nomeada.

Planeje as buscas antes de começar e guarde um terço para a rodada 3. Se você puder iniciar outros agentes, dê a cada evento real seu próprio agente, e a dupla verificação para um que não escreveu a nota.

Duas coisas que o vídeo finalizado deve ser capaz de usar:

  • Eventos reais, conhecidos até a profundidade de um detalhe. Uma pessoa inventada torna uma ideia fácil de seguir; um evento real faz o espectador acreditar e lembrar. Para um assunto com uma história (um mercado, uma tecnologia, uma instituição), pesquise pelo menos dois. Se um mostra alguém ganhando, pesquise como poderia ter falhado e encontre um onde alguém perdeu: uma vitória sozinha ensina a lição errada. Para um mecanismo da natureza ou um método (por que o céu é azul, como dar um nó), uma observação real, medição ou descoberta é suficiente, ou nenhuma: escreva "nenhum, porque …" no briefing.
  • O que o solicitante lembra, verificado. É um lead, e muitas vezes parcialmente errado. Verifique cada parte, use o que for válido e diga a ele o que você corrigiu e por que; nunca repita uma afirmação porque "o solicitante disse", e nunca a descarte silenciosamente.

Detalhes: references/research.md.

Estágio 3: o mapa mental

mindmap.json é uma árvore curta de cada ideia que o vídeo poderia conter (os tipos de nós estão listados em references/planning.md seção 1; node tools/mindmap.mjs os nomeia quando um está errado). Cada nó diz em algumas palavras qual é a ideia, onde seus detalhes estão na pesquisa ("file.md#Heading"), quais ideias o espectador precisa primeiro e a quais outras ideias ela se conecta. Cada ideia é core (no vídeo: a promessa precisa dela, uma história real não pode ser contada sem ela, ou a justiça precisa dela), support (pesquisada e verdadeira, mantida fora do núcleo: material para a descrição, uma versão mais longa se o solicitante pedir, ou um próximo vídeo) ou cut (não confirmada, não pode ser contada de forma justa, ou não diz respeito ao tópico principal; uma história real que falha no teste de exemplo é cut). A ferramenta verifica se todo ponteiro leva a algum lugar e se nada é ensinado antes do que precisa. Detalhes: references/planning.md.

Estágio 4: o storyboard

Uma tabela, uma linha por batida: o que o espectador vê, a essência do que a voz diz, qual componente desenha, se uma nova palavra chega e o que é ouvido além da voz (para música, efeitos sonoros, silêncio). A batida é a menor unidade que avança a compreensão: uma imagem e o que ela significa, uma ação que o espectador vê, uma palavra-chave explicada. O storyboard verifica se a ordem funciona antes de escrever qualquer script. Detalhes: references/planning.md.

Estágio 5: o script

videos/<id>.mjs é um arquivo JavaScript que exporta uma estrutura de dados de cada cena, com texto da voz, descrições visuais, componentes e metadados. O motor interpreta isso para renderizar cada quadro com base nos componentes e no layout escolhido. Escreva na profundidade do núcleo; a ferramenta check verifica erros de sintaxe e avisa sobre exageros comuns (por exemplo, uma cena com mais de 60 segundos). A voz vai primeiro: escreva o que será dito, depois encontre a imagem que mostra enquanto é dito. As regras de escrita estão em references/writing-for-everyone.md (evite jargão, voz passiva, frases longas; use exemplos que o espectador já conhece). Detalhes: references/authoring-kit.md e references/components.md.

Estágio 6: revisão de precisão

Execute node tools/dump.mjs <id> --claims para extrair cada afirmação factual do script. Verifique cada uma em sua fonte e marque-a como correta, incorreta ou não verificada. Para cada história real, alguém que não escreveu a história compara o script, as notas de pesquisa e as fontes. Se não houver um segundo agente, você mesmo faz, mas escreve "não independente" no arquivo de revisão. Qualquer correção é escrita de volta nas notas de pesquisa; o script não é alterado até que a revisão esteja completa e o "índice" de pesquisa seja atualizado com quaisquer novas fontes.

Estágio 7: revisão de compreensão

Escreva WhatIHaveLearned.md: finja que você acabou de assistir ao vídeo e escreva tudo o que aprendeu, como se fosse o espectador. Depois, compare-o com a promessa. Se houver uma lacuna (a promessa não foi cumprida), o script precisa de mais conteúdo. Também liste em lost-points.md quaisquer lugares onde um espectador poderia ficar confuso e como você corrigiu isso (ou por que você não corrigiu). Isso testa se o roteiro realmente ensina, não apenas declara.

Estágio 8: revisão visual

Renderize cada quadro do script (o motor já pode fazer isso no navegador) e olhe para cada um. Nada deve estar cortado, coberto por outro elemento, vazio (uma tela em branco onde algo deveria estar) ou ilegível (fonte muito pequena, baixo contraste, sobreposto ao fundo). Corrija quaisquer problemas atualizando o script ou os ativos; se um ativo estiver faltando, crie-o.

Estágio 9: voz e som

Grave as falas da voz usando o TTS integrado (Text-to-Speech). O mecanismo pode cronometrar cada linha com base na duração da fala. Depois que a voz estiver gravada, os tempos (quando uma cena muda, quando o texto aparece) devem coincidir com a voz real, não com uma estimativa. Adicione sons de eventos (cliques, notificações, efeitos sonoros que correspondam às imagens), mas não os exagere. A música, se usada, fica apenas sob as partes da história (não durante a explicação principal). Onde a música deve aparecer e desaparecer é definido no script.

Estágio 10: exportar e assistir final

Renderize o arquivo .mp4 final (com som). Verifique o .srt (legendas) e o .chapters.txt para garantir que estejam sincronizados. Assista a alguns quadros do próprio arquivo exportado (não apenas da visualização do navegador) e verifique o som em um player normal. A exportação também produz arquivos .vtt para legendas em navegadores.

Estágios 11 a 13: outros formatos, publicação, entrega

Se for solicitada uma tradução ou um formato diferente (por exemplo, vertical para celular), crie um arquivo de tradução JSON em videos/i18n/. Para publicação, escreva publish.md com o título final e a descrição do vídeo, os capítulos com carimbos de data/hora, o arquivo de legendas, uma miniatura (criada a partir de um quadro ou gerada com IA), e uma lista de fontes e créditos que o solicitante pode usar. Na entrega, escreva uma mensagem para o solicitante resumindo o que foi decidido, quaisquer correções feitas e quaisquer problemas em aberto que precisem da entrada dele.

Antes de entregar

Veja o vídeo como o solicitante verá, uma vez, sem pausar nem tomar notas. Anote três coisas:

  1. O vídeo responde à pergunta que o solicitante não disse em voz alta? (Geralmente: "por que devo saber disso?")
  2. O vídeo mostra algo real (um evento, uma pessoa, um número, uma citação) que me faz acreditar? Se não, a promessa não foi cumprida.
  3. O vídeo soa completo? (O final não parece abrupto; a última sentença conclui a promessa.)

Não entregue se a resposta a qualquer uma delas for "não". Corrija primeiro. O tempo que você gasta aqui é o tempo que o solicitante não gastará corrigindo.

Habilidades Relacionadas