makevideo

makevideo

Generación de video rápida y estándar para agentes de IA. Un script JSON de entrada, un MP4 terminado de salida, renderizado de la misma manera cada vez. Escribes escenas, cada una con una línea para decir. makevideo las vocaliza con una voz neuronal consistente, sincroniza cada escena con el audio real, añade subtítulos y renderiza un MP4 con un ffmpeg incluido. Se ejecuta solo en CPU: sin navegador, sin GPU, sin clave de API y sin nube.

▶ Tu agente puede hacer videos ahora (1:39, escrito, vocalizado y renderizado por un agente desde un archivo JSON) · ▶ Mira el showcase de 87 segundos, renderizado desde examples/showcase.json en una CPU de laptop, más rápido de lo que se reproduce.

Formato corto también: "format": "shorts" ofrece 1080×1920 con subtítulos grandes palabra por palabra. ▶ Mira la demo estilo TikTok (examples/tiktok.json): 23 s de video renderizados en 15 s, más un GIF exportado automáticamente.

Más ejemplos, todos hechos con makevideo: ▶ Demo de 59 segundos (spec) · ▶ La voz de la casa · ▶ Resumen de distribución · ▶ Novedades en 0.4: más cerca de cada agente (spec) · ▶ Novedades en 0.3: velocidad (spec) · ▶ Novedades en 0.2 (hecho desde un archivo Markdown) · ▶ Por qué usar makevideo en lugar de construir desde cero (spec) · ▶ Video de changelog para v0.1 (spec): los videos de changelog y resumen son un caso de uso central.

Qué hace: diapositivas narradas · transiciones automáticas (push, slide, zoom, wipe) · declaraciones cinéticas · gráficos animados · división de medios + texto · escribe Markdown, obtén un video · capturas de pantalla · clips de gameplay/video · GIFs de entrada y salida · código · estadísticas · citas · antes/después · subtítulos TikTok/Reels/Shorts · fuentes personalizadas · música de fondo · grabación de pantalla para trailers · subtítulos .srt · fotogramas 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é

A los agentes se les piden videos todo el tiempo, y cada agente los construye de manera diferente. Cada video termina con un nuevo pipeline, una voz distinta, sin narración a menos que alguien la pida, y un render que puede tardar diez minutos. makevideo lo convierte en un estándar:

	videos de agente ad-hoc	makevideo
Formato	un script nuevo cada vez	un spec JSON (schema)
Voz	TTS aleatorio, a veces ninguno	Kokoro-82M, la misma voz cada vez (af_heart)
Narración	debe solicitarse	activada por defecto: cada escena tiene say
Sincronización	adivinada	medida desde el audio generado, por frase
Subtítulos	raramente	incrustados, más un sidecar .srt
Velocidad	minutos	más rápido que el tiempo real en CPU (ver Rendimiento)
Verificación	ver todo el video	makevideo preview crea una hoja de contactos en aproximadamente 1 s

Premium por defecto

El objetivo es que el primer intento de un agente se vea terminado. Sin configuración adicional obtienes:

• Transiciones que mezclan fotogramas reales. Cada escena fluye desde el último fotograma real de la escena anterior. auto elige push, zoom, wipe o fade según qué se corta a qué. Sobrescribe con "transition" globalmente o por escena.
• Tipografía que viene con el paquete. Inter, Montserrat y JetBrains Mono (OFL) están incluidos, así que una caja Linux en la nube renderiza exactamente como tu laptop.
• Profundidad: gradiente de luz clave, viñeta y sombras de panel suaves en cada tema.
• Limpieza de voz: escribe de forma natural. 42%, v1.2, $3M, 4.6x, 35 s, e.g. y -> se pronuncian correctamente, y los subtítulos conservan lo que escribiste.
• Lint: check señala muros de texto, demasiadas viñetas, listas desincronizadas, declaraciones demasiado largas, escenas densas en vertical y ritmo repetitivo, y dice cómo arreglar cada uno.

Escribe Markdown, obtén un video

---
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 encabezado #/## inicia una escena, y su cuerpo decide el tipo: una lista da viñetas/pasos/decisiones, los elementos label: number dan un gráfico, una imagen o video da imagen/clip (o división, cuando también hay texto), un bloque de código da código, **42%** label da una estadística, y un párrafo da una declaración. Las líneas que comienzan con > son la narración. Cuando una escena no tiene ninguna, su texto visible se lee en voz alta, porque la narración es el valor predeterminado. <!-- key: value --> establece opciones de escena. Ver examples/whats-new-0.2.md; el video de la versión 0.2 es ese único archivo.

Úsalo desde Claude Code (plugin)

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

Luego solo di "haz un video sobre…". Claude escribe el spec, lo previsualiza, lo renderiza y te entrega el MP4.

El plugin incluye tanto la skill como el servidor MCP.

Úsalo desde cualquier cliente MCP

Claude Desktop, Cursor, VS Code, Codex, Windsurf y otros clientes MCP:

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

Está listado en el Registro MCP oficial como io.github.random00000000/makevideo, como imagen Docker (ghcr.io/random00000000/makevideo). Sin Node, ejecuta docker run -i --rm -v "$PWD:/work" -w /work ghcr.io/random00000000/makevideo mcp.

Las herramientas son make_video (Markdown o JSON de entrada, MP4 de salida, con notificaciones de progreso), preview_video (devuelve la hoja de contactos como imagen que el modelo puede mirar), check_video y video_reference. Ver la guía MCP.

Enseña a cada agente en un repositorio

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

Esto escribe un bloque corto e idempotente "usa makevideo para videos", para que cada agente que trabaje en el proyecto recurra a la misma herramienta.

Guías: agentes · texto a video en CPU · Markdown a video · TikTok/Shorts · trailers de juegos · MCP · vs Remotion/MoviePy/ffmpeg

Para agentes de IA (empieza aquí)

Si eres un agente LLM y el usuario pidió un video, explicación, walkthrough, devlog, demo, trailer, resumen, notas de parche o presentación con voz en off, usa esta biblioteca:

1. Escribe un spec: un array scenes donde cada escena tiene una cadena type y una say (la narración).
2. npx makevideo check spec.json --json lo valida y estima la duración (instantáneo).
3. npx makevideo preview spec.json: abre la hoja de contactos PNG y verifica el diseño (aproximadamente 1 s, sin audio).
4. npx makevideo spec.json --json renderiza e imprime { output, srt, report, poster, duration, seconds }.
5. Entrega al usuario el .mp4. Termina los videos informativos con una escena decisions que liste lo que solo el usuario puede decidir.

Reglas prácticas: aproximadamente 1–3 frases por escena. Escribe say como debe hablarse: deletrea números y símbolos ("cuarenta y dos por ciento", no "42%") y usa pronounce para nombres. Pon el texto en pantalla en title/items; no tiene que coincidir palabra por palabra con la narración. Reutiliza el mismo voice y theme en un proyecto para que todos sus videos coincidan.

También hay AGENTS.md, llms.txt, un JSON Schema en schema.json, y una skill de Claude Code lista para usar en skills/makevideo/SKILL.md. Copia esa carpeta a ~/.claude/skills/ y Claude recurrirá a makevideo cada vez que pidas un video.

Spec

{
  "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 escena acepta say (narración) y un duration opcional (segundos mínimos; requerido si no hay say). Las escenas duran tanto como su narración más un pequeño margen.

tipo	campos	notas
title	title, subtitle?, kicker?	tarjeta de apertura; outro es un alias para cierres
bullets	title?, items[], highlight?	los elementos aparecen en sincronía con las frases: N elementos + 1 frase introductoria funciona mejor
steps	title?, items[]	viñetas numeradas
decisions	title?, items[]	numeradas, para "lo que el usuario debe decidir"
image	src, title?, subtitle?, fit?, zoom?	acercamiento lento; fit: "contain" mantiene la imagen completa con un fondo desenfocado
clip	src, start?, title?, subtitle?, fit?	cualquier mp4/webm/mov; recortado para llenar, en bucle si es corto; el audio original se descarta
code	code, title?, highlight? ([3, [5,8]])	resaltado de sintaxis, números de línea
stat	value, label?	los números cuentan hacia arriba ("42%", "$1.2", "3x")
quote	text, by?
compare	title?, left: {title, items}, right: {title, items}	se apila verticalmente en vertical
statement	text, kicker?, align?	tipografía cinética enorme; las palabras aparecen con la voz; *stars* marcan palabras de énfasis
chart	bars: [{label, value}] (o {label: value}), title?, unit?, prefix?, highlight?, note?	las barras crecen cuando la voz las alcanza; los valores cuentan hacia arriba
split	src (imagen o video), title?, items? o text?, side? (left/right)	medios junto a puntos sincronizados; el video se reproduce dentro del marco

El type de la escena se infiere cuando se omite (src + items/text → división, src → imagen/clip, bars → gráfico, items → viñetas, code → código, value → estadística, text → declaración).

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

Un spec .js puede export default { ... } (o una función asíncrona que devuelva el spec), lo cual es útil para generar escenas desde datos.

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' }

Los errores están escritos para que un agente pueda actuar sobre ellos. Nombran la escena e incluyen un ejemplo 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 juegos y grabaciones de pantalla

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.' },
] });

Rendimiento

makevideo está construido para ejecutarse en CPU, porque la mayoría de los sandboxes de agentes y runners en la nube no tienen GPU.

¿Lo necesitas rápido? Añade --fast (o "voice": "fast"). Eso cambia a una voz Piper que habla a aproximadamente 10× el tiempo real en 2 hilos de CPU. Kokoro, el valor predeterminado, es aproximadamente 2× el tiempo real usando todos los núcleos. La voz rápida suena menos natural, así que es mejor para borradores, videos largos e iteración rápida.

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

Medido con el mismo video de 74 s y 8 escenas (examples/whats-new-0.2.md) en una laptop i7-10750H (6 núcleos, sin GPU), con la máquina aproximadamente 35% ocupada con otro trabajo. Ambas versiones se ejecutaron consecutivamente:

	v0.2.0	v0.3.0
primer render (sin voz en caché)	119.9 s	81.0 s
primer render con voz --fast	n/a	36.3 s
re-render (voz en caché)	41.0 s	28.4 s

Cómo se logra:

• Retención de fotogramas. Las diapositivas permanecen estáticas la mayor parte del tiempo. Solo se dibujan los fotogramas que pueden cambiar. Cada tipo de escena sabe exactamente cuánto dura su entrada, por lo que una escena típica tiene alrededor del 30% de fotogramas "en vivo" en lugar del 50%. Los fotogramas retenidos se repiten dentro de ffmpeg después de la conversión de color, donde casi no cuestan nada.
• Procesos de renderizado. Las escenas se dibujan y codifican en un grupo de procesos de trabajo (un lienzo y un ffmpeg cada uno), por lo que el dibujo utiliza muchos núcleos en lugar del único hilo principal de Node. Los trabajadores se inician mientras aún se está generando el habla.
• Habla optimizada. Kokoro se ejecuta como 1–3 procesos con hilos ONNX fijados a núcleos/2/N, porque los procesos que cada uno toma todos los núcleos se pelean entre sí. Los hilos ONNX inactivos duermen en lugar de girar, dejando la CPU al renderizador.
• Canalización superpuesta. Cada escena se renderiza tan pronto como existe su propia narración. El póster, el GIF y el multiplexado final se ejecutan en paralelo.
• Caché. El audio de cada frase se almacena en caché por (motor, voz, velocidad, texto) en ~/.cache/makevideo (anular con MAKEVIDEO_CACHE). Los re-renderizados después de un ajuste de diseño omiten la voz por completo.
• Medido, no adivinado. Cada uno de estos proviene de un perfil. Algunas ideas se descartaron: grano de película (los rellenos de patrón cuestan 80 ms por fotograma), capas de contenido transparentes (más lentas en Skia) y más hilos x264 (2 por escena supera a 4).

Controles: --fast, quality: "draft", format: "720p", MAKEVIDEO_THREADS (hilos x264 por escena, predeterminado 2), video(spec, { concurrency, ttsWorkers, ttsThreads }) y MAKEVIDEO_DEBUG=1 para perfiles por escena.

Cómo 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 lo demás se instala desde npm: ffmpeg-static incluye ffmpeg, @napi-rs/canvas incluye Skia precompilado y kokoro-js ejecuta la voz localmente a través de ONNX Runtime. CI renderiza videos de prueba en Linux, macOS y Windows (Node 20 y 22) en cada push.

Créditos y licencia

MIT. La voz es Kokoro-82M (Apache-2.0) a través de kokoro-js. El video se codifica con FFmpeg (a través de ffmpeg-static).

_{Palabras clave: generador de video con IA, texto a video, hacer un video, video narrado, generación rápida de video, voz en off, video TTS, generador de video explicativo, video programático, biblioteca de video Node.js, video ffmpeg desde JSON, presentación de diapositivas con narración, subtítulos automáticos, subtítulos, SRT, herramientas de agente, video Claude Code, video Codex, generación de video LLM, video de registro de desarrollo, video de notas de parche, narración de tráiler de juego, alternativa a Remotion sin navegador.}