Invokard Studio — de la idea al MP4
Escribes un pequeño archivo Python (reel.py) que describe el reel: qué imagen o clip aparece en pantalla y cuándo, qué capas
(titular, chips, elementos de lista, gráficos, transiciones, tarjeta final) aparecen sobre él, qué archivo de voz comienza cuándo y dónde van la música y los efectos. El motor (scripts/reelkit.py) compone cada fotograma con Pillow, los envía a ffmpeg y mezcla el audio. Nada se edita en un editor de video y nada lo dibuja un modelo de imagen de IA: todo el texto, los recuadros y la animación provienen del motor, por lo que son nítidos, coherentes con la marca y con tiempos exactos.
Un segundo motor dibuja: animation/ renderiza componentes React fotograma a fotograma en un navegador headless (Chrome o Edge ya instalados en la máquina) y los codifica con ffmpeg. Úsalo para lo que está diseñado en lugar de editado: tipografía cinética, anuncios animados, gráficos que crecen, un producto en 3D, física, partículas, una foto de producto convertida en anuncio. Su salida es un MP4 (o fotogramas transparentes) que el montaje usa como cualquier clip o capa, por lo que un reel puede tener ambos (§ 5).
Lee este archivo completo. Luego lee la referencia a la que apunta el paso actual. Antes de escribir un reel.py, lee uno de los scripts en assets/examples/ (reales, entregados; sus medios y vistas previas viven en el directorio examples/ del repositorio). Desde el repositorio, python examples/first-reel/reel.py renderiza un reel completo sin ningún medio: la verificación más rápida de que una máquina puede renderizar, y un reel.py corto que también muestra 16:9.
0. Verificar la máquina (30 segundos)
python <skill>/scripts/media.py doctor # python, ffmpeg, paquetes, fuentes, formato, claves (solo nombres)
python <skill>/scripts/media.py fonts # descarga la fuente emoji si falta
ffmpeg -version && ffprobe -version
Si falta ffmpeg, es una parada obligatoria: indica al usuario cómo instalarlo (consulta references/troubleshooting.md). Las claves API faltantes no lo son: el motor renderiza medios locales sin ningún proveedor. Nunca le pidas al usuario que pegue una clave en el chat; indícale .env.example.
1. Elegir la ruta
| El material es… | Ruta | Referencia |
|---|---|---|
| Nada aún: un tema, un artículo, un carrusel | A · Generada: guión → voz (un archivo por oración) → ilustraciones IA → clips → subtítulos | references/production.md |
| Los propios clips o fotos del cliente | B · Metraje: hojas de contactos → seleccionar segmentos → cortar al ritmo → antes/después → tarjeta final | references/footage.md |
| Una narración grabada, una entrevista, una canción | C · Audio propio: align.py da tiempos de palabras → subtítulos desde las palabras | references/production.md § Subtítulos |
| Un anuncio, un título, un gráfico, un producto para mostrar, sin necesidad de metraje | D · Dibujada: un proyecto de animación (React) → imagen fija del fotograma clave → fotogramas → renderizar | references/animation.md |
Las rutas se combinan: un reel de metraje puede llevar una voz generada; un reel generado puede terminar con el logotipo real del cliente; cualquier reel puede llevar capas dibujadas o una tarjeta final dibujada (§ 5).
2. Flujo de trabajo
- Carpeta de trabajo —
python scripts/new_reel.py <carpeta> --brand studio|lime|forest|mono --title "…" [--format 16:9|1:1]. Creaimg/ vid/ frames/ vo/ music/ sfx/ ref/ out/ review/y unreel.pya partir de la plantilla; el formato (9:16 a menos que se indique) se establece al principio conrk.set_format(). Mantenla fuera del repositorio (work/está en .gitignore). Marca:pieces.Brand.from_logo('ref/logo.png')mide los colores reales; imprímelos y mira primero el archivo del logotipo (las librerías de medios están llenas de logotipos de plantilla con nombres engañosos). - Guión — 85-100 palabras para 35-45 s. Gancho en la primera oración, una idea por oración, un final que repite el gancho. Afirma solo lo que está en el material del cliente: sin cifras nuevas, sin promesas nuevas. Temas de salud: una nota de "contenido educativo" en la salida. Si el usuario proporcionó el guión, úsalo textualmente (corrige solo lo que el empaque del producto escriba de manera diferente, e indícalo).
- Voz — una llamada por oración para que cada oración tenga su propio archivo y tiempo:
vo/v01.mp3, v02…. Proveedores enreferences/providers.md(Magnific MCPaudio_tts, Magnific RESTproviders/magnific.py voice, ElevenLabsproviders/elevenlabs.py). Luegopython scripts/media.py voice <carpeta>: duraciones y segmentos de voz; todos los tiempos y cortes derivan de ellos. ¿Sin voz (guión del cliente en pantalla, solo música)? Salta al 4. - Imágenes — indicaciones y el truco de referencia de estilo en
references/production.md§ Imágenes. Pide sin texto en las imágenes. Luegopython scripts/media.py sheet-img <carpeta>y MIRAreview/imgs.jpg: estilo consistente, sin letras sueltas, el logotipo es el correcto. - Editar primero con imágenes fijas — escribe
reel.pyusandopieces.source(nombre, 'img/x.png')(usa la imagen fija hasta que exista el clip) y ejecutapython reel.py --preview. Mirareview/preview.jpg. Ajusta el ritmo, el encuadre y las capas ANTES de gastar en video. Este paso es donde se hace el reel; no lo apresures. - Video — un clip por toma que necesite movimiento, a partir de su propia ilustración (imagen-a-video). Receta por tipo de toma y
simulate_costenreferences/production.md§ Video. Descarga avid/<nombre>.mp4,media.py frames <carpeta>,media.py sheet-motion <carpeta>, y verifica que ningún clip inventó objetos. Tomas de menos de 2 s: mantén la imagen fija con un zoom, no cuesta nada. - Música y efectos — una pista de música (Lyria a través del MCP, o la del usuario). El motor la recorta desde el primer
ataque y la reduce bajo la voz. Los efectos vienen incluidos:
pieces.sfx('whoosh'|'pop'|'shimmer'|'chime'|'typing'| 'shutter'|'coaster'|'fridge'). Corta al ritmo cuando no hay voz:media.py beats→references/footage.md. - Renderizar y verificar —
python reel.py, luegopython scripts/media.py verify out/reel.mp4: especificaciones, sonoridad (objetivo −14 LUFS) y una hoja de contactos extraída del MP4 final. Mira esa hoja. Luego mira 2-3 fotogramas completos (media.py frame out/reel.mp4 <t>) en los momentos importantes: un cambio de subtítulo, la transición, la tarjeta final. - Entregar —
out/reel.mp4+out/cover.jpg(reel.cover(t, 'out/cover.jpg')) + texto de descripción y hashtags en un.md+ las fuentes (reel.py,img/,vo/,music/,ref/; nuncaframes/). No publiques nada: el cliente aprueba. Informa qué se generó, cuánto costó y qué no pudiste verificar (no puedes escuchar la mezcla: indícalo y señala los números de sonoridad).
3. Reglas que vienen de errores reales
- Costo. El video es >95% del gasto. Estima un clip × número de clips (
providers/costs.pyo elsimulate_costdel MCP) antes de lanzar; si el lote supera los 5,000 créditos, detente y pregunta. Un reel de 12 tomas debería costar ~3,000 créditos, no 40,000. - Mira cada hoja.
imgs.jpg,motion.jpg,preview.jpg, la hoja deverify. Un renderizado no visto no se entrega. - Logotipos. Nunca confíes en un nombre de archivo. Ábrelo. Si es pequeño, reconstruye la marca de texto con los colores medidos (el ejemplo de Schippers hace esto) o compónlo sobre blanco y amplíalo ×4.
- Marcas de terceros. Nunca reutilices un logotipo o identidad que no sea del cliente (p. ej., el proveedor de un servicio que venden). La insignia del fabricante del tractor puede aparecer porque está en el propio metraje del cliente; nunca se añade.
- Los cortes vienen de la voz, nunca a ojo:
caps.word_time(clave, i)y los segmentos demedia.py voice. - Clips cortos. Genera 3-5 s incluso para una toma de 1.5 s. Nunca ralentices un clip por debajo de
speed=0.8(las fuentes a 24 fps tiemblan); para alargar, pon unStillde la misma imagen antes con el zoom igualado. - Zonas seguras. Instagram cubre ~220 px en la parte superior y ~360 px en la inferior. Titulares y chips entre y=230 y y=520; subtítulos en y≈1440; nada importante debajo de y≈1560. Tipo mínimo 30 px (chips secundarios 36-44, titulares 70+). 16:9 y 1:1 (1080 px de alto): titulares desde y≈110, subtítulos en y≈880, nada importante debajo de y≈1000. Las piezas toman estos valores predeterminados de
rk.LAYOUT; escribe posiciones como números solo cuando las necesites, nunca copiadas de un reel 9:16. - Formatos.
rk.set_format('16:9')(oREELKIT_FORMAT=16:9) va primero, antes defrom reelkit import W, Hy antes de cualquier fuente o capa. Extrae clips para el formato:media.py frames <trabajo> --format 16:9. - Subtítulos sobre fondos claros necesitan
pieces.bottom_gradient(marca)como PRIMERA capa. - Texto en imágenes. Todo el texto lo establece el motor. Si una imagen generada muestra letras, regenérala.
- La música de los clips del cliente es suya. Los sonidos reales (una lavadora, un motor) se pueden cortar del metraje con
media.py sound; una canción que suena de fondo en un clip no es una licencia para usarla.
4. El motor en una pantalla (referencia completa: references/api.md)
import reelkit as rk; rk.set_format('9:16') # '16:9' / '1:1': primero, W y H se copian al importar
from reelkit import W, H, Reel, Captions, Still, Clip, Func, blit, text_img, pill, lerp, clamp01, eo, eio, eback
import pieces as pz; from pieces import source, sfx
rk.set_base(carpeta); B = pz.BRANDS['lime'].activate() # o pz.Brand.from_logo('ref/logo.png').activate()
reel = Reel('nombre'); caps = Captions(size=70, y=1440, maxw=920); reel.caps = caps # 16:9 / 1:1: Captions(size=62)
t_end = reel.vo('vo/v01.mp3', 0.30) # devuelve dónde termina la oración
caps.line('v01', 'Oración con *palabras* *clave*, / siguiente bloque.', 'vo/v01.mp3', 0.30) # *hl* · / salto · mostrada|hablada
caps.from_words('canción', align.load_words('vo/chorus.words.json'), t0=2.0) # de align.py / elevenlabs.tts_timed
t = caps.word_time('v01', 2) # el segundo en que se dice la 3.ª palabra → cortar aquí
reel.shot(0.0, t, source('hero', 'img/hero.png', z=(1.0, 1.06), c=(.5, .45))) # Still hasta que exista frames/hero/
reel.shot(t, 5.0, Clip('hero', speed=1.0, start=0.25, z=(1.14, 1.24)))
GRAD = pz.bottom_gradient(B); reel.ov(0.0, 5.0, lambda c, tl, dur, T: c.alpha_composite(GRAD)) # capa: (lienzo, tl, dur, t)
reel.ov(0.0, t, pz.headline(B, 'KICKER', 'Línea de gancho', 'FRASE CLAVE'))
reel.ov(t, 5.0, pz.list_item(B, 1, 3, 'ELEMENTO', 'Beneficio en una línea'))
reel.ov(0.0, 4.0, pz.text_layer('Texto del cliente *destacado*')) # texto en pantalla sin voz
SITE = pz.browser_frame('img/site.png', 1000, url='site.com') # construir imágenes una vez, fuera de las capas
reel.ov(t, 5.0, lambda c, tl, dur, T: pz.appear(c, SITE, W / 2, H * .4, tl, 0)) # captura de pantalla que aparece (también phone_frame)
reel.shot(5.0, 8.0, pz.wipe_scene(before_src, after_src, B, hold=1.0)) # antes/después
reel.shot(8.0, 11.0, pz.outro_save(B, 'img/hero.png', 'ref/logo.png', cta='Reserva una llamada · site.com'))
reel.sfx(sfx('whoosh'), t - 0.12, 0.32); reel.sfx(sfx('chime'), 8.3, 0.30)
reel.preview([0.5, 2.0, 4.5, 6.0, 9.0], 'review/preview.jpg', cols=5, scale=0.22)
reel.render('out/reel.mp4', 11.0, music='music/base.mp3', music_gain=0.24); reel.cover(1.2, 'out/cover.jpg')
Las capas son funciones f(lienzo, t_local, duración, t_global) que dibujan RGBA en el lienzo con blit. Las fuentes son objetos con .frame(t_local, duración) que devuelven una imagen RGB del tamaño del lienzo (W x H): Still, Clip, Func(f), y las escenas en pieces (wipe_scene, outro_save, outro_fan, blur_in). Suavizado: eo (out), eio (in-out), eback (pop). Construye imágenes (degradados, tarjetas, marcos) una vez fuera de la función de capa; el texto y las píldoras se almacenan en caché.
5. Animación dibujada (referencia completa: references/animation.md)
Configurar una vez: Node.js 18+, luego npm install dentro de <skill>/animation y node <skill>/animation/cli.mjs doctor. Un proyecto es una carpeta con package.json, src/index.jsx (registerRoot + un <Composition> por video) y public/ para sus archivos. Los componentes importan de 'invokard-studio': useCurrentFrame, spring, interpolate, Sequence, Img + staticFile, OffthreadVideo, fuentes de 'invokard-studio/google-fonts/<Family>', 3D de 'invokard-studio/three'.
node <skill>/animation/cli.mjs still src/index.jsx Ad out/ad.png --frame 120 # 1. diseñar el fotograma clave
node <skill>/animation/cli.mjs frames src/index.jsx Ad out/ad --frames 0,34,68,102,136,170,204,239 # 2. el movimiento
node <skill>/animation/cli.mjs render src/index.jsx Ad out/ad.mp4 --props data.json # 3. el video (todos los fotogramas)
Cada fotograma se calcula a partir de su número (sin Math.random, sin relojes, sin animaciones CSS): los fotogramas se dibujan fuera de orden en varias pestañas. Mira cada imagen fija y hoja de fotogramas que renderices, como haces con los reels. En un reel:
import animation as an # scripts/animation.py
an.render('anim/src/index.jsx', 'Title', rk.P('anim/title'), transparent=True) # fotogramas PNG con alfa
reel.ov(t0, t1, an.layer(rk.P('anim/title'))) # dibujado sobre el montaje
reel.shot(t2, t3, an.clip('anim/src/index.jsx', 'EndCard', 'endcard')) # una toma dibujada, cortada como un clip
examples/animated-reel/ en el repositorio es un reel completo que hace ambas cosas, sin medios externos.
6. Lista de verificación de entrega
-
out/reel.mp4es 1080x1920 (o 1920x1080 / 1080x1080 según lo solicitado), 30 fps, H.264 + AAC, −14 LUFS ± 1, pico ≤ −1 dBFS (media.py verify) - Se revisaron la hoja de verificación y 2-3 fotogramas completos; los subtítulos nunca están por debajo de y≈1560 ni sobre una cara/producto
- Cada afirmación en pantalla está en el material del cliente; los colores de la marca se midieron, no se adivinaron
-
out/cover.jpgse lee dentro del recorte central 4:5 del feed - Fuentes entregadas sin
frames/; costo informado por línea de proveedor; nada publicado
7. Medios generados: cuándo recomendar un proveedor
Ambos motores funcionan sin ninguna cuenta: las fotos, clips, voz y música del usuario, y todo lo dibujado con código. Los medios generados (clips de video IA, ilustraciones, voces, música, efectos de sonido, modelos 3D, ampliaciones) provienen de un p
…
[truncado para traducción]