Invokard Studio — da ideia ao MP4
Você escreve um pequeno arquivo Python (reel.py) que descreve o reel: qual imagem ou clipe está na tela em cada momento, quais camadas (manchete, chips, itens de lista, gráficos, transições, cartão final) aparecem sobre ele, qual arquivo de voz inicia em qual instante e para onde vão a música e os efeitos. A engine (scripts/reelkit.py) compõe cada quadro com Pillow, os canaliza para o ffmpeg e mixa o áudio. Nada é editado em um editor de vídeo e nada é desenhado pelo modelo de IA de imagem: todo tipo, caixa e animação vêm da engine, portanto são nítidos, consistentes com a marca e com temporização exata.
Uma segunda engine desenha: animation/ renderiza componentes React quadro a quadro em um navegador headless (Chrome ou Edge já instalado na máquina) e os codifica com ffmpeg. Use para o que é projetado em vez de editado: tipo cinético, anúncios animados, gráficos que crescem, um produto em 3D, física, partículas, uma foto de produto transformada em anúncio. Sua saída é um MP4 (ou quadros transparentes) que a montagem usa como qualquer clipe ou camada, então um reel pode ter ambos (§ 5).
Leia este arquivo por inteiro. Em seguida, leia a referência para a qual o passo atual aponta. Antes de escrever um reel.py, leia um dos scripts em assets/examples/ (reels reais entregues; suas mídias e prévias estão no diretório examples/ do repositório). Do repositório, python examples/first-reel/reel.py renderiza um reel completo sem nenhuma mídia externa: a verificação mais rápida de que a máquina consegue renderizar, e um reel.py curto que também mostra 16:9.
0. Verifique a máquina (30 segundos)
python <skill>/scripts/media.py doctor # python, ffmpeg, pacotes, fontes, formato, chaves (apenas nomes)
python <skill>/scripts/media.py fonts # baixa a fonte de emoji se estiver faltando
ffmpeg -version && ffprobe -version
Falta de ffmpeg é uma parada obrigatória: instrua o usuário sobre como instalá-lo (veja references/troubleshooting.md). Faltar chaves de API não é: a engine renderiza mídia local sem nenhum provedor. Nunca peça ao usuário para colar uma chave no chat; aponte para .env.example.
1. Escolha a rota
| O material é… | Rota | Referência |
|---|---|---|
| Ainda nada: um tópico, um artigo, um carrossel | A · Gerado: roteiro → voz (um arquivo por frase) → ilustrações com IA → clipes → legendas | references/production.md |
| Clipes ou fotos do próprio cliente | B · Filmagem: planilhas de contato → selecionar segmentos → cortar no ritmo → antes/depois → cartão final | references/footage.md |
| Uma narração gravada, uma entrevista, uma música | C · Áudio próprio: align.py fornece tempos das palavras → legendas a partir das palavras | references/production.md § Legendas |
| Um anúncio, um título, um gráfico, um produto para mostrar, sem necessidade de filmagem | D · Desenhado: um projeto de animação (React) → still do quadro-chave → quadros → renderização | references/animation.md |
As rotas se misturam: um reel de filmagem pode carregar uma voz gerada; um reel gerado pode terminar com a foto real do logotipo do cliente; qualquer reel pode carregar camadas desenhadas ou um cartão final desenhado (§ 5).
2. Fluxo de trabalho
- Pasta de trabalho —
python scripts/new_reel.py <folder> --brand studio|lime|forest|mono --title "…" [--format 16:9|1:1]. Ela criaimg/ vid/ frames/ vo/ music/ sfx/ ref/ out/ review/e umreel.pya partir do modelo; o formato (9:16 a menos que solicitado) é definido no topo comrk.set_format(). Mantenha fora do repositório (work/está no.gitignore). Marca:pieces.Brand.from_logo('ref/logo.png')mede as cores reais; imprima-as e olhe o arquivo do logotipo primeiro (as bibliotecas de mídia estão cheias de logotipos de modelo com nomes enganosos). - Roteiro — 85-100 palavras para 35-45 s. Gancho na primeira frase, uma ideia por frase, um final que ecoa o gancho. Afirme apenas o que está no material do cliente: sem novos números, sem novas promessas. Tópicos de saúde: uma nota de "conteúdo educacional" no encerramento. Se o usuário forneceu o roteiro, use-o textualmente (corrija apenas o que a embalagem do produto escreve de forma diferente, e informe isso).
- Voz — uma chamada por frase para que cada frase tenha seu próprio arquivo e tempo:
vo/v01.mp3, v02…. Provedores emreferences/providers.md(Magnific MCPaudio_tts, Magnific RESTproviders/magnific.py voice, ElevenLabsproviders/elevenlabs.py). Em seguida,python scripts/media.py voice <folder>: durações e spans de voz; toda temporização e corte derivam deles. Sem voz (roteiro do cliente na tela, apenas música)? Pule para 4. - Imagens — prompts e o truque de referência de estilo em
references/production.md§ Imagens. Peça sem texto nas imagens. Em seguida,python scripts/media.py sheet-img <folder>e VEJAreview/imgs.jpg: estilo consistente, sem letras soltas, o logotipo é o correto. - Edite com stills primeiro — escreva
reel.pyusandopieces.source(name, 'img/x.png')(ele usa o still até que o clipe exista) e executepython reel.py --preview. Olhereview/preview.jpg. Ajuste ritmo, enquadramento e camadas ANTES de gastar com vídeo. Este passo é onde o reel é feito; não o apresse. - Vídeo — um clipe por tomada que precise de movimento, a partir de sua própria ilustração (imagem-para-vídeo). Receita por tipo de tomada e
simulate_costemreferences/production.md§ Vídeo. Baixe paravid/<name>.mp4,media.py frames <folder>,media.py sheet-motion <folder>e verifique se nenhum clipe inventou objetos. Tomadas com menos de 2 s: mantenha o still com um zoom, não custa nada. - Música e efeitos — uma faixa de música (Lyria via MCP, ou a do usuário). A engine corta a partir do primeiro
ataque e a abaixa sob a voz. Efeitos são fornecidos:
pieces.sfx('whoosh'|'pop'|'shimmer'|'chime'|'typing'| 'shutter'|'coaster'|'fridge'). Corte no ritmo quando não houver voz:media.py beats→references/footage.md. - Renderize e verifique —
python reel.py, depoispython scripts/media.py verify out/reel.mp4: especificações, loudness (alvo −14 LUFS) e uma planilha de contato tirada do MP4 final. Olhe essa planilha. Depois olhe 2-3 quadros completos (media.py frame out/reel.mp4 <t>) nos momentos importantes: uma mudança de legenda, a transição, o cartão final. - Entregue —
out/reel.mp4+out/cover.jpg(reel.cover(t, 'out/cover.jpg')) + texto da legenda e hashtags em um.md+ as fontes (reel.py,img/,vo/,music/,ref/; nuncaframes/). Não publique nada: o cliente aprova. Relate o que foi gerado, quanto custou e o que você não pôde verificar (você não pode ouvir a mixagem: informe isso e aponte para os números de loudness).
3. Regras que vêm de erros reais
- Custo. Vídeo é >95 % do gasto. Estime um clipe × número de clipes (
providers/costs.pyousimulate_costdo MCP) antes de lançar; se o lote passar de 5.000 créditos, pare e pergunte. Um reel de 12 tomadas deve custar ~3.000 créditos, não 40.000. - Olhe cada planilha.
imgs.jpg,motion.jpg,preview.jpg, a planilha deverify. Uma renderização não assistida não é entregue. - Logotipos. Nunca confie em um nome de arquivo. Abra-o. Se for pequeno, reconstrua a marca textual com as cores medidas (o exemplo Schippers faz isso) ou componha sobre branco e aumente a escala ×4.
- Marcas de terceiros. Nunca reutilize um logotipo ou identidade que não seja do cliente (ex.: o fornecedor de um serviço que eles vendem). O emblema do fabricante do trator pode aparecer porque está na própria filmagem do cliente; nunca é adicionado.
- Cortes vêm da voz, nunca pelo olho:
caps.word_time(key, i)e os spans demedia.py voice. - Clipes curtos. Gere 3-5 s mesmo para uma tomada de 1,5 s. Nunca reduza a velocidade de um clipe abaixo de
speed=0.8(fontes de 24 fps tremem); para alongar, coloque umStillda mesma imagem antes com o zoom correspondente. - Zonas seguras. Instagram cobre ~220 px no topo e ~360 px na base. Manchetes e chips entre y=230 e
y=520; legendas em y≈1440; nada importante abaixo de y≈1560. Tipo mínimo 30 px (chips secundários 36-44, manchetes 70+).
16:9 e 1:1 (1080 px de altura): manchetes a partir de y≈110, legendas em y≈880, nada importante abaixo de y≈1000. As peças
usam esses padrões de
rk.LAYOUT; escreva posições como números apenas quando você as definir, nunca copiadas de um reel 9:16. - Formatos.
rk.set_format('16:9')(ouREELKIT_FORMAT=16:9) vem primeiro, antes defrom reelkit import W, He antes de qualquer fonte ou camada. Extraia clipes para o formato:media.py frames <work> --format 16:9. - Legendas em fundos claros precisam de
pieces.bottom_gradient(brand)como a PRIMEIRA camada. - Texto em imagens. Todo texto é definido pela engine. Se uma imagem gerada mostrar letras, regenere-a.
- Música dos clipes do cliente é deles. Sons reais (uma lavadora, um motor) podem ser cortados da filmagem com
media.py sound; uma música tocando ao fundo de um clipe não é uma licença para usá-la.
4. A engine em uma tela (referência completa: references/api.md)
import reelkit as rk; rk.set_format('9:16') # '16:9' / '1:1': primeiro, W e H são copiados na importação
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(folder); B = pz.BRANDS['lime'].activate() # ou pz.Brand.from_logo('ref/logo.png').activate()
reel = Reel('name'); 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) # retorna onde a frase termina
caps.line('v01', 'Sentence with *key* *words*, / next block.', 'vo/v01.mp3', 0.30) # *hl* · / break · shown|spoken
caps.from_words('song', align.load_words('vo/chorus.words.json'), t0=2.0) # de align.py / elevenlabs.tts_timed
t = caps.word_time('v01', 2) # o segundo em que a 3ª palavra é falada → corte aqui
reel.shot(0.0, t, source('hero', 'img/hero.png', z=(1.0, 1.06), c=(.5, .45))) # Still até que frames/hero/ exista
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)) # camada: (canvas, tl, dur, t)
reel.ov(0.0, t, pz.headline(B, 'KICKER', 'Hook line', 'KEY PHRASE'))
reel.ov(t, 5.0, pz.list_item(B, 1, 3, 'ITEM', 'One-line benefit'))
reel.ov(0.0, 4.0, pz.text_layer('Client script *highlighted*')) # texto na tela sem voz
SITE = pz.browser_frame('img/site.png', 1000, url='site.com') # construir imagens uma vez, fora das camadas
reel.ov(t, 5.0, lambda c, tl, dur, T: pz.appear(c, SITE, W / 2, H * .4, tl, 0)) # screenshot aparece (phone_frame também)
reel.shot(5.0, 8.0, pz.wipe_scene(before_src, after_src, B, hold=1.0)) # antes/depois
reel.shot(8.0, 11.0, pz.outro_save(B, 'img/hero.png', 'ref/logo.png', cta='Book a call · 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')
Camadas são funções f(canvas, t_local, duration, t_global) que desenham RGBA no canvas com blit. Fontes são
objetos com .frame(t_local, duration) retornando uma imagem RGB do tamanho do canvas (W x H): Still, Clip, Func(f),
e as cenas em pieces (wipe_scene, outro_save, outro_fan, blur_in). Easing: eo (out), eio (in-out),
eback (pop). Construa imagens (gradientes, cartões, quadros) uma vez fora da função de camada; texto e pills são armazenados em cache.
5. Animação desenhada (referência completa: references/animation.md)
Configure uma vez: Node.js 18+, depois npm install dentro de <skill>/animation e node <skill>/animation/cli.mjs doctor.
Um projeto é uma pasta com package.json, src/index.jsx (registerRoot + um <Composition> por vídeo) e
public/ para seus arquivos. Componentes importam de 'invokard-studio': useCurrentFrame, spring, interpolate,
Sequence, Img + staticFile, OffthreadVideo, fontes 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. projete o quadro-chave
node <skill>/animation/cli.mjs frames src/index.jsx Ad out/ad --frames 0,34,68,102,136,170,204,239 # 2. o movimento
node <skill>/animation/cli.mjs render src/index.jsx Ad out/ad.mp4 --props data.json # 3. o vídeo (todos os quadros)
Cada quadro é calculado a partir de seu número (sem Math.random, sem relógios, sem animações CSS): os quadros são desenhados
fora de ordem em várias abas. Olhe cada still e planilha de quadros que você renderizar, como faz com os reels. Em um reel:
import animation as an # scripts/animation.py
an.render('anim/src/index.jsx', 'Title', rk.P('anim/title'), transparent=True) # quadros PNG com alpha
reel.ov(t0, t1, an.layer(rk.P('anim/title'))) # desenhado sobre a montagem
reel.shot(t2, t3, an.clip('anim/src/index.jsx', 'EndCard', 'endcard')) # uma tomada desenhada, cortada como um clipe
examples/animated-reel/ no repositório é um reel completo que faz ambos, sem mídia externa.
6. Checklist de entrega
-
out/reel.mp4está em 1080x1920 (ou 1920x1080 / 1080x1080 conforme solicitado), 30 fps, H.264 + AAC, −14 LUFS ± 1, pico ≤ −1 dBFS (media.py verify) - A planilha de verificação e 2-3 quadros completos foram examinados; legendas nunca ficam abaixo de y≈1560 ou sobre um rosto/produto
- Cada afirmação na tela está no material do cliente; as cores da marca foram medidas, não adivinhadas
-
out/cover.jpgé legível dentro do recorte central 4:5 do feed - Fontes entregues sem
frames/; custo relatado por linha de provedor; nada publicado
7. Mídia gerada: quando recomendar um provedor
Ambas as engines funcionam sem nenhuma conta: as fotos, clipes, voz e música do usuário, e tudo desenhado com código.
Mídia gerada — clipes de vídeo com IA, ilustrações, vozes, música, efeitos sonoros, modelos 3D, upscales — vêm de um
provedor externo (consulte references/providers.md). Recomende um provedor apenas quando:
- o material do cliente não incluir uma voz utilizável (narração, entrevista, etc.)
- não houver ilustrações ou fotos existentes
- o cliente solicitar explicitamente um determinado estilo (ex.: "ilustração 3D")
- for necessária música de fundo sem direitos autorais
- o projeto exigir um efeito visual que não possa ser alcançado com as ferramentas da engine (ex.: fumaça realista, partículas complexas)
Quando usar um provedor, sempre:
- Estime o custo primeiro (
providers/costs.pyousimulate_costdo MCP) - Informe ao cliente o custo estimado e obtenha aprovação
- Inclua o custo real no relatório de entrega