makevideo

makevideo

Geração de vídeo rápida e padronizada para agentes de IA. Um script JSON de entrada, um MP4 finalizado de saída, renderizado da mesma forma todas as vezes. Você escreve cenas, cada uma com uma frase para ser dita. makevideo as narra com uma voz neural consistente, cronometra cada cena de acordo com o áudio real, adiciona legendas e renderiza um MP4 com um ffmpeg incluso. Ele roda apenas na CPU: sem navegador, sem GPU, sem chave de API e sem nuvem.

▶ Seu agente pode criar vídeos agora (1:39, escrito, narrado e renderizado por um agente a partir de um arquivo JSON) · ▶ Assista à demonstração de 87 segundos, renderizada a partir de examples/showcase.json na CPU de um laptop, mais rápido do que o tempo de reprodução.

Formato curto também: "format": "shorts" oferece 1080×1920 com legendas grandes palavra por palavra. ▶ Assista à demonstração estilo TikTok (examples/tiktok.json): 23 s de vídeo renderizados em 15 s, além de um GIF exportado automaticamente.

Mais exemplos, todos feitos com makevideo: ▶ Demonstração de 59 segundos (especificação) · ▶ A voz da casa · ▶ Resumo de distribuição · ▶ O que há de novo na 0.4: mais próximo de cada agente (especificação) · ▶ O que há de novo na 0.3: velocidade (especificação) · ▶ O que há de novo na 0.2 (feito a partir de um arquivo Markdown) · ▶ Por que usar makevideo em vez de construir do zero (especificação) · ▶ Vídeo de changelog para v0.1 (especificação): vídeos de changelog e resumo são um caso de uso central.

O que ele faz: slides narrados · transições automáticas (empurrar, deslizar, zoom, cortina) · declarações cinéticas · gráficos animados · mídia dividida + texto · escreva Markdown, obtenha um vídeo · capturas de tela · clipes de gameplay/vídeo · GIFs de entrada e saída · código · estatísticas · citações · antes/depois · legendas TikTok/Reels/Shorts · fontes personalizadas · música de fundo · gravação de tela para trailers · legendas .srt · quadros de pôster.

npm i github:random00000000/makevideo
npx makevideo init            # writes video.json
npx makevideo video.json      # → video.mp4 + video.srt + video.report.json + video.jpg
npx makevideo video.json --fast   # same, about 3x faster on a first render

import { video } from 'makevideo';

await video({
  title: 'Patch notes 1.2',
  scenes: [
    { type: 'title',   title: 'Patch 1.2', subtitle: 'Siege update', say: 'Here is what is new in patch one point two.' },
    { type: 'clip',    src: 'siege.mp4', title: 'Rams breach gates', say: 'Rams can now breach wooden gates.' },
    { type: 'bullets', title: 'Also new', items: ['Faster pathing', 'New HUD'], say: 'Also new. Pathing is faster. And the HUD is redesigned.' },
    { type: 'decisions', items: ['Ship Friday?'], say: 'One decision for you. Do we ship on Friday?' },
  ],
});

---

Por quê

Os agentes recebem pedidos de vídeos o tempo todo, e cada agente os cria de uma forma diferente. Cada vídeo acaba com um novo pipeline, uma voz diferente, sem narração a menos que alguém peça, e uma renderização que pode levar dez minutos. makevideo torna isso um padrão único:

	vídeos ad-hoc de agentes	makevideo
Formato	um script novo a cada vez	uma especificação JSON (esquema)
Voz	TTS aleatório, às vezes nenhum	Kokoro-82M, mesma voz sempre (af_heart)
Narração	deve ser solicitada	ativada por padrão: toda cena tem say
Cronometragem	adivinhada	medida a partir do áudio gerado, por frase
Legendas	raramente	incorporadas, além de um sidecar .srt
Velocidade	minutos	mais rápido que o tempo real na CPU (veja Desempenho)
Verificação	assistir tudo	makevideo preview cria uma folha de contato em cerca de 1 s

Premium por padrão

O objetivo é que a primeira tentativa de um agente pareça finalizada. Sem nenhuma configuração extra, você obtém:

• Transições que misturam quadros reais. Cada cena flui a partir do último quadro real da cena anterior. auto escolhe empurrar, zoom, cortina ou desvanecer com base no que é cortado para quê. Substitua com "transition" globalmente ou por cena.
• Tipografia que acompanha o pacote. Inter, Montserrat e JetBrains Mono (OFL) estão incluídas, então uma máquina Linux básica na nuvem renderiza exatamente como seu laptop.
• Profundidade: gradiente de luz principal, vinheta e sombras suaves de painel em todos os temas.
• Limpeza de fala: escreva naturalmente. 42%, v1.2, $3M, 4.6x, 35 s, e.g. e -> são todos falados corretamente, e as legendas mantêm o que você escreveu.
• Lint: check sinaliza paredes de texto, excesso de marcadores, listas dessincronizadas, declarações longas demais, cenas densas em retrato e ritmo repetitivo, e diz como corrigir cada um.

Escreva Markdown, obtenha um vídeo

---
theme: midnight
brand: My Game
---
# Patch 1.2
The siege update
> Here is what changed in patch one point two.

## Rams breach gates
![](captures/ram.mp4)
- Wooden gates break in 3 hits
- Stone gates still hold
> Rams now breach wooden gates. Three hits and they are down. Stone gates still hold.

## Load time
<!-- highlight: Now -->
- Before: 12 s
- Now: 3 s

## Decisions
- Ship Friday?

npx makevideo patch-notes.md

Cada título #/## inicia uma cena, e seu corpo decide o tipo: uma lista gera marcadores/etapas/decisões, itens label: number geram um gráfico, uma imagem ou vídeo gera imagem/clipe (ou dividido, quando há texto também), um bloco de código gera código, **42%** label gera uma estatística, e um parágrafo gera uma declaração. Linhas que começam com > são a narração. Quando uma cena não tem nenhuma, seu texto visível é lido em voz alta, porque a narração é o padrão. <!-- key: value --> define opções de cena. Veja examples/whats-new-0.2.md; o vídeo de lançamento da 0.2 é esse único arquivo.

Use com Claude Code (plugin)

/plugin marketplace add random00000000/makevideo
/plugin install makevideo@makevideo

Depois é só dizer "faça um vídeo sobre…". Claude escreve a especificação, visualiza, renderiza e entrega o MP4.

O plugin inclui tanto a habilidade quanto o servidor MCP.

Use com qualquer cliente MCP

Claude Desktop, Cursor, VS Code, Codex, Windsurf e outros clientes MCP:

{ "mcpServers": { "makevideo": { "command": "npx", "args": ["-y", "github:random00000000/makevideo", "mcp"] } } }

Ele está listado no Registro MCP oficial como io.github.random00000000/makevideo, como uma imagem Docker (ghcr.io/random00000000/makevideo). Sem Node, execute docker run -i --rm -v "$PWD:/work" -w /work ghcr.io/random00000000/makevideo mcp.

As ferramentas são make_video (Markdown ou JSON de entrada, MP4 de saída, com notificações de progresso), preview_video (retorna a folha de contato como uma imagem que o modelo pode olhar), check_video e video_reference. Veja o guia MCP.

Ensine cada agente em um repositório

npx -y github:random00000000/makevideo agents --all     # AGENTS.md, CLAUDE.md, Cursor rules, Copilot instructions
npx -y github:random00000000/makevideo agents --global  # this machine: Claude Code skill + Codex AGENTS.md

Isso escreve um bloco curto e idempotente "use makevideo para vídeos", para que todo agente que trabalhe no projeto use a mesma ferramenta.

Guias: agentes · texto para vídeo na CPU · Markdown para vídeo · TikTok/Shorts · trailers de jogos · MCP · vs Remotion/MoviePy/ffmpeg

Para agentes de IA (comece aqui)

Se você é um agente LLM e o usuário pediu um vídeo, explicação, passo a passo, devlog, demonstração, trailer, resumo, notas de patch ou apresentação com narração, use esta biblioteca:

1. Escreva uma especificação: um array scenes onde cada cena tem uma string type e uma say (a narração).
2. npx makevideo check spec.json --json valida e estima a duração (instantâneo).
3. npx makevideo preview spec.json: abra a folha de contato PNG e verifique o layout (cerca de 1 s, sem áudio).
4. npx makevideo spec.json --json renderiza e imprime { output, srt, report, poster, duration, seconds }.
5. Entregue o .mp4 ao usuário. Termine vídeos informativos com uma cena decisions listando o que só o usuário pode decidir.

Regras práticas: cerca de 1–3 frases por cena. Escreva say do jeito que deve ser falado: soletre números e símbolos ("quarenta e dois por cento", não "42%") e use pronounce para nomes. Coloque o texto na tela em title/items; ele não precisa corresponder palavra por palavra à narração. Reutilize o mesmo voice e theme em um projeto para que todos os seus vídeos combinem.

Há também AGENTS.md, llms.txt, um JSON Schema em schema.json e uma habilidade Claude Code pronta para uso em skills/makevideo/SKILL.md. Copie essa pasta para ~/.claude/skills/ e o Claude usará makevideo sempre que você pedir um vídeo.

Especificação

{
  "title": "My video",              // used for default output name
  "output": "out/my-video.mp4",     // default: <title-slug>.mp4 (relative to spec file)
  "format": "landscape",            // landscape 1920x1080 | portrait/shorts 1080x1920 | square | 720p
  "theme": "midnight",              // midnight | forge | paper | terminal | { ...color overrides }
  "voice": "af_heart",              // the default house voice (warm female); "fast" = ~10x real-time Piper voice (male); false = silent
  "speed": 1,                       // speech rate
  "brand": "My Project",            // small label top-right
  "captions": true,                 // burned-in captions (an .srt is always written)
  "progressBar": true,              // chapter bar along the bottom
  "music": "bed.mp3",               // optional background music, looped, faded out
  "musicVolume": 0.12,
  "pronounce": { "Hacksilver": "Hack silver" },  // TTS-only substitutions (merged over built-ins for JSON, MP4, GPU, ...); captions keep originals
  "quality": "standard",            // draft | standard | high
  "transition": "auto",             // auto | push | slide | zoom | wipe | fade | dip | cut (also per scene)
  "captionStyle": "classic",        // classic (subtitle box) | bold (TikTok word-by-word, default for portrait) | none
  "font": "fonts/Anton.ttf",        // display font: a .ttf/.otf path or an installed family name
  "gif": { "width": 480, "fps": 12, "duration": 8 },  // also export an animated GIF (true = defaults)
  "scenes": [ /* see below */ ]
}

Cada cena aceita say (narração) e um duration opcional (segundos mínimos; obrigatório se não houver say). As cenas duram o tempo da narração mais um pequeno intervalo.

tipo	campos	notas
title	title, subtitle?, kicker?	cartão de abertura; outro é um alias para encerramentos
bullets	title?, items[], highlight?	os itens aparecem em sincronia com as frases: N itens + 1 frase de introdução funciona melhor
steps	title?, items[]	marcadores numerados
decisions	title?, items[]	numerados, para "o que o usuário deve decidir"
image	src, title?, subtitle?, fit?, zoom?	aproximação lenta; fit: "contain" mantém a imagem inteira com um fundo desfocado
clip	src, start?, title?, subtitle?, fit?	qualquer mp4/webm/mov; cortado para preencher, em loop se curto; áudio original descartado
code	code, title?, highlight? ([3, [5,8]])	com realce de sintaxe, números de linha
stat	value, label?	números contam para cima ("42%", "$1.2", "3x")
quote	text, by?
compare	title?, left: {title, items}, right: {title, items}	empilha verticalmente em retrato
statement	text, kicker?, align?	tipografia cinética grande; palavras aparecem com a voz; *stars* marcam palavras de destaque
chart	bars: [{label, value}] (ou {label: value}), title?, unit?, prefix?, highlight?, note?	barras crescem conforme a voz as alcança; valores contam para cima
split	src (imagem ou vídeo), title?, items? ou text?, side? (left/right)	mídia ao lado de pontos sincronizados; vídeo reproduz dentro do quadro

O type da cena é inferido quando omitido (src + items/text → dividido, src → imagem/clipe, bars → gráfico, items → marcadores, code → código, value → estatística, text → declaração).

CLI

makevideo <spec.json|spec.js>      render (mp4 + srt + json report + jpg poster)
makevideo check <spec>             validate, estimate duration (instant)
makevideo preview <spec>           contact-sheet PNG of every scene (about 1 s)
makevideo init [file]              starter spec
makevideo record <out.mp4> --seconds 10 [--window "Game"]   record screen/window for clip scenes
makevideo agents [--all|--global]   tell agents to use makevideo for videos
makevideo mcp                       MCP server (stdio)
makevideo setup                     pre-download voice models
makevideo voices | themes | types | transitions | formats
  -o <file>  --draft  --format <f>  --voice <id>  --theme <name>  --json

Uma especificação .js pode export default { ... } (ou uma função assíncrona que retorna a especificação), o que é útil para gerar cenas a partir de dados.

API

import { video, check, preview, VOICES, THEMES, SCENE_TYPES } from 'makevideo';

const r = await video(spec, { baseDir, onProgress: (e) => console.log(e.stage, e.message) });
// r = { output, srt, report, poster, duration, seconds, scenes: [{ index, type, title, start, duration, say }] }

check(spec)      // { ok, problems[], estimatedSeconds }
await preview(spec) // { output: '...preview.png' }

Os erros são escritos para que um agente possa agir sobre eles. Eles nomeiam a cena e incluem um exemplo funcional:

makevideo: invalid spec
  - scenes[2] (clip) is missing "src". Example: {"type":"clip","src":"gameplay.mp4","start":2,...}
  - scenes[4] has no "say" (narration) and no "duration". Narration is the default in makevideo: ...

Trailers de jogos e gravações de tela

npx makevideo record captures/siege.mp4 --seconds 12 --window "Hacksilver"   # one window (Windows)
npx makevideo record captures/menu.mp4 --seconds 8                           # whole screen (Win/macOS/Linux)

import { record, video } from 'makevideo';
await record({ output: 'captures/boss.mp4', seconds: 10, window: 'My Game' });
await video({ format: 'shorts', theme: 'forge', scenes: [
  { type: 'clip', src: 'captures/boss.mp4', title: 'New boss', say: 'Meet the new boss.' },
] });

Desempenho

makevideo é feito para rodar na CPU, porque a maioria dos sandboxes de agentes e runners de nuvem não têm GPU.

Precisa de velocidade? Adicione --fast (ou "voice": "fast"). Isso muda para uma voz Piper que fala a cerca de 10× o tempo real em 2 threads de CPU. Kokoro, o padrão, é cerca de 2× o tempo real usando todos os núcleos. A voz rápida soa menos natural, então é melhor para rascunhos, vídeos longos e iteração rápida.

npx makevideo video.md --fast   # fastest: Piper voice + quick encode
npx makevideo setup             # once per machine/image: pre-download voice models

Medido com o mesmo vídeo de 74 s e 8 cenas (examples/whats-new-0.2.md) em um laptop i7-10750H (6 núcleos, sem GPU), com a máquina cerca de 35% ocupada com outros trabalhos. Ambas as versões rodaram em sequência:

	v0.2.0	v0.3.0
primeira renderização (sem fala em cache)	119,9 s	81,0 s
primeira renderização com voz --fast	n/a	36,3 s
re-renderização (fala em cache)	41,0 s	28,4 s

Como ele chega lá:

• Segurar quadros. Slides ficam parados na maior parte do tempo. Apenas quadros que podem mudar são desenhados. Cada tipo de cena sabe exatamente quanto tempo dura sua entrada, então uma cena típica tem cerca de 30% de quadros "vivos" em vez de 50%. Quadros segurados são repetidos dentro do ffmpeg após a conversão de cor, onde custam quase nada.
• Processos de renderização. As cenas são desenhadas e codificadas em um pool de processos de trabalho (um canvas e um ffmpeg cada), então o desenho usa muitos núcleos em vez do único thread principal do Node. Os trabalhadores iniciam enquanto a fala ainda está sendo gerada.
• Fala ajustada. Kokoro roda como 1–3 processos com threads ONNX fixados em núcleos/2/N, porque processos que pegam todos os núcleos brigam entre si. Threads ONNX ociosos dormem em vez de girar, deixando a CPU para o renderizador.
• Pipeline sobreposto. Cada cena renderiza assim que sua própria narração existe. O pôster, o GIF e a multiplexação final rodam lado a lado.
• Cache. O áudio de cada frase é armazenado em cache por (engine, voz, velocidade, texto) em ~/.cache/makevideo (substituível com MAKEVIDEO_CACHE). Re-renderizações após um ajuste de layout pulam a voz completamente.
• Medido, não adivinhado. Cada um desses veio de um perfil. Algumas ideias perderam: granulação de filme (preenchimentos de padrão custam 80 ms por quadro), camadas de conteúdo transparentes (mais lentas no Skia) e mais threads x264 (2 por cena vence 4).

Controles: --fast, quality: "draft", format: "720p", MAKEVIDEO_THREADS (threads x264 por cena, padrão 2), video(spec, { concurrency, ttsWorkers, ttsThreads }) e MAKEVIDEO_DEBUG=1 para perfis por cena.

Como funciona

spec ─► validate ─► split narration into sentences ─► Kokoro TTS pool (cached)
                                     │ per scene, as soon as its audio is ready
                                     ▼
            measure audio → scene duration, caption cues, reveal times
                                     ▼
       Skia canvas draws only frames that change ─► ffmpeg (loop holds, x264)
                                     ▼
        concat segments + narration WAV (+ music) ─► .mp4  .srt  .json  .jpg

Requisitos

Node 18+. Todo o resto instala via npm: ffmpeg-static inclui ffmpeg, @napi-rs/canvas inclui Skia pré-compilado e kokoro-js roda a voz localmente via ONNX Runtime. CI renderiza vídeos de teste em Linux, macOS e Windows (Node 20 e 22) a cada push.

Créditos e licença

MIT. A voz é Kokoro-82M (Apache-2.0) via kokoro-js. O vídeo é codificado com FFmpeg (via ffmpeg-static).

_{Palavras-chave: gerador de vídeo com IA, texto para vídeo, fazer um vídeo, vídeo narrado, geração rápida de vídeo, narração, vídeo com TTS, gerador de vídeo explicativo, vídeo programático, biblioteca de vídeo Node.js, vídeo ffmpeg a partir de JSON, apresentação de slides com narração, legendas automáticas, subtítulos, SRT, ferramentas de agente, vídeo Claude Code, vídeo Codex, geração de vídeo com LLM, vídeo de devlog, vídeo de notas de patch, narração de trailer de gameplay, alternativa ao Remotion sem navegador.}