Communitygithub.com

Invokard Studio

Crie vídeos de curta duração (reels) escrevendo um arquivo Python. A engine compõe cada quadro com Pillow, codifica com ffmpeg e mixa o áudio — sem edição em timeline, sem IA gerando texto ou layouts. Ideal para criadores que querem controle pixel-perfeito sobre cada frame.

O que é Invokard Studio?

O Invokard Studio é uma skill técnica que transforma descrições Python em vídeos MP4 completos, combinando composição de imagens com Pillow, animação de componentes React em navegador headless e mixagem de áudio via ffmpeg. Diferente de ferramentas tradicionais de edição de vídeo, ela não usa timeline ou geração de imagens com IA para texto e layouts — tudo é renderizado pela engine, garantindo nitidez, consistência de marca e temporização exata. A skill oferece suporte a múltiplos fluxos de trabalho: geração completa (roteiro, voz, ilustrações e clipes), uso de filmagens ou fotos do cliente, narração gravada ou músicas próprias, e animação desenhada com React. Cada fluxo é detalhado em uma referência dedicada, e a skill inclui verificações automáticas de saúde do ambiente (`python scripts/media.py doctor`), estimativas de custo antes de gerar vídeos (`providers/costs.py`) e validação final de loudness e especificações. O processo é modular e repetível: o engenheiro escreve um arquivo `reel.py` que descreve a sequência de cenas, camadas e efeitos, executa comandos para gerar imagens e clipes, e renderiza o resultado. A skill também gerencia animações React (via suíte Remotion) e integra provedores de voz, música e efeitos, permitindo orquestrar toda a produção de um reel sem sair do terminal. Compatível com sistemas que possuam Python, ffmpeg e Node.js, a skill funciona em qualquer plataforma onde esses componentes estejam disponíveis, sendo ideal para desenvolvedores que desejam automatizar a criação de conteúdo visual com controle absoluto sobre cada pixel e timeline.

Funciona com~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/Octonove/invokard-studio/tree/main/skills/invokard-studio

Perguntar na sua IA favorita

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

Documentação

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 é…RotaReferência
Ainda nada: um tópico, um artigo, um carrosselA · Gerado: roteiro → voz (um arquivo por frase) → ilustrações com IA → clipes → legendasreferences/production.md
Clipes ou fotos do próprio clienteB · Filmagem: planilhas de contato → selecionar segmentos → cortar no ritmo → antes/depois → cartão finalreferences/footage.md
Uma narração gravada, uma entrevista, uma músicaC · Áudio próprio: align.py fornece tempos das palavras → legendas a partir das palavrasreferences/production.md § Legendas
Um anúncio, um título, um gráfico, um produto para mostrar, sem necessidade de filmagemD · Desenhado: um projeto de animação (React) → still do quadro-chave → quadros → renderizaçãoreferences/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

  1. Pasta de trabalho — python scripts/new_reel.py <folder> --brand studio|lime|forest|mono --title "…" [--format 16:9|1:1]. Ela cria img/ vid/ frames/ vo/ music/ sfx/ ref/ out/ review/ e um reel.py a partir do modelo; o formato (9:16 a menos que solicitado) é definido no topo com rk.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).
  2. 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).
  3. Voz — uma chamada por frase para que cada frase tenha seu próprio arquivo e tempo: vo/v01.mp3, v02…. Provedores em references/providers.md (Magnific MCP audio_tts, Magnific REST providers/magnific.py voice, ElevenLabs providers/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.
  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 VEJA review/imgs.jpg: estilo consistente, sem letras soltas, o logotipo é o correto.
  5. Edite com stills primeiro — escreva reel.py usando pieces.source(name, 'img/x.png') (ele usa o still até que o clipe exista) e execute python reel.py --preview. Olhe review/preview.jpg. Ajuste ritmo, enquadramento e camadas ANTES de gastar com vídeo. Este passo é onde o reel é feito; não o apresse.
  6. 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_cost em references/production.md § Vídeo. Baixe para vid/<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.
  7. 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.
  8. Renderize e verifique — python reel.py, depois python 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.
  9. 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/; nunca frames/). 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.py ou simulate_cost do 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 de verify. 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 de media.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 um Still da 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') (ou REELKIT_FORMAT=16:9) vem primeiro, antes de from reelkit import W, H e 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.mp4 está 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.py ou simulate_cost do MCP)
  • Informe ao cliente o custo estimado e obtenha aprovação
  • Inclua o custo real no relatório de entrega

Habilidades Relacionadas