Communitygithub.com

JacobLinCool/video-studio-mlx

Produza um vídeo demo/promo polido e narrado de QUALQUER aplicativo ou site. A filmagem é uma gravação de tela real do produto que você está demonstrando; a narração é gerada e validada por ASR pela High Level Studio API (/studio/tts, clonagem de voz opcional) do video-studio-mlx — essa API é a única dependência fixa, não o assunto. Abrange script focado na narração, gravação do alvo (app macOS via AppleScript, ou site via Playwright), composição com ffmpeg (palco emoldurado, legendas PNG, zoom hero, foco+anel ancorados na narração) e verificação de quadro + ASR. Use quando o usuário deseja um vídeo demo, um tour/promo narrado ou narração sincronizada com a filmagem. Não é para gravações de tela sem narração ou capturas de tela simples.

O que é video-studio-mlx?

Este skill permite que um agente de IA produza vídeos de demonstração polidos e narrados de qualquer aplicativo ou site. O processo é orientado pela narração: primeiro, gera-se um roteiro e a narração usando a API Studio do video-studio-mlx (que clona a voz e fornece timestamps por palavra). Depois, grava-se a tela do alvo (apps macOS via AppleScript, sites via Playwright) e compõe-se o vídeo final com ffmpeg, que aplica legendas, zooms, transições e efeitos de foco sincronizados com as palavras da narração. O skill é útil para criar vídeos de demonstração, tutoriais narrados ou apresentações de produtos, garantindo que a narração dite o ritmo e as animações do vídeo. Suporta macOS e sites, e inclui scripts para geração de narração, gravação, composição e verificação (extração de quadros e ASR para confirmar sincronia).

Funciona com~Claude Code~Codex CLI✓Cursor
npx skills add https://github.com/JacobLinCool/video-studio-mlx/tree/HEAD/.agents/skills/studio-demo-video

Perguntar na sua IA favorita

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

Documentação

Vídeo Demo de Estúdio

Crie uma demo narrada de ~90–180s de qualquer produto que o usuário nomear — um app macOS, um site, uma CLI, qualquer coisa que você possa gravar a tela. A única peça fixa é o backend de narração: a video-studio-mlx Studio API (POST /studio/tts), que clona uma voz e valida cada linha. O assunto da demo é arbitrário e muda a cada vez. Mantenha essa separação em mente: não presuma que o alvo da demo é o próprio video-studio-mlx (isso é apenas o exemplo em references/).

Princípio central: narração primeiro, ancoragem de duração exata

Gere a narração antes de qualquer filmagem. /studio/tts retorna a duração exata de cada segmento e timestamps por palavra — esses dados orientam toda a linha do tempo e todos os efeitos de foco. Em seguida, grave a filmagem generosamente e ajuste cada clipe ao seu segmento. Cortar primeiro e gravar a voz depois força um reajuste frágil do tempo.

Você geralmente não pode reproduzir ou ouvir a saída. Trate isso como uma restrição rígida: verifique o vídeo extraindo quadros e verifique o conteúdo/áudio sincronizado executando ASR em partes do arquivo final. Construa tudo para que possa ser verificado dessa forma.

Pipeline

  1. Escreva um storyboard por cena — texto da narração, ação na tela, legenda e (por cena) quais elementos a narração nomeia para que o foco possa apontar para eles. Aponte para ~2.1 palavras/seg (≈170 palavras ≈ 80s). Copie references/storyboard.example.json para <work>/storyboard.json. Formule a narração de modo que cada elemento nomeado esteja realmente visível e em ordem na filmagem daquela cena. Escreva para o ouvido: soletre as palavras como são faladas, não escritas — expanda abreviações e siglas ("expressão regular", não "regex"; "versão três", não "v3"), evite símbolos simples (~, /, &) e escreva números/unidades por extenso quando não tiver certeza. O TTS lê o texto literal e o ASR valida em relação a ele, então abreviações escritas tanto são mal pronunciadas quanto distorcem o WER.
  2. Gere a narração — scripts/generate_narration.py <storyboard.json>. Envia cada cena para /studio/tts, clonando cada cena a partir de uma única voz fixa (o ref_audio do usuário, ou uma instrução voice que ele projeta uma vez — veja abaixo), valida com ASR e escreve narration/manifest.json com duration_s, wer e words por segmento. (Veja references/studio-api.md.)
  3. Grave o alvo — um clipe por cena do aplicativo/site (veja Gravação), além de um mapa nomeado de retângulos de elementos para os elementos aos quais o foco apontará.
  4. Componha — scripts/compose.py <storyboard.json>: emoldura a filmagem em um palco com gradiente, queima legendas com Pillow, aplica zoom lento em cenas hero, aplica foco ancorado na narração (zoom + anel), transições com xfade, sobrepõe a narração na linha do tempo calculada e multiplexa.
  5. Verifique — extraia um quadro de cada cena; extraia um quadro no momento da palavra falada de cada foco e confirme que o destaque está no elemento nomeado; execute ASR em duas ou três partes para confirmar que a linha certa está na cena certa.

Pré-requisitos

  • A Studio API acessível (padrão http://127.0.0.1:8100). Configuração, clonagem e o contrato de alinhamento/timestamp de palavras estão em references/studio-api.md.
  • Um wav de referência de 3–15s (mono 24 kHz) mais sua transcrição exata para clonagem — confirme a transcrição com /asr primeiro (a qualidade da clonagem depende do alinhamento áudio↔texto, não de um comprimento "recomendado").
  • Uma voz para o vídeo inteiro. Cada cena é uma chamada separada /studio/tts, então a voz só permanece consistente se cada chamada clonar uma referência compartilhada. Se o usuário fornecer uma referência, clone a partir dela; caso contrário, defina uma instrução de design voice no storyboard e o generate_narration.py projeta um clipe inicial e clona cada cena a partir dele (em cache, para que reexecuções mantenham a mesma voz). Sem nenhum dos dois, cada cena é sintetizada independentemente e o timbre varia entre as cenas — evite isso para vídeos reais.
  • ffmpeg com avfoundation (captura macOS), zoompan, xfade, gblur. drawtext geralmente está ausente (sem libfreetype) — as legendas são renderizadas com Pillow.
  • Para alvos de site: Playwright (ou Puppeteer) para gravação determinística + caixas de elementos.

Gravando o alvo

Cada cena precisa de duas coisas do produto alvo:

  1. um clipe gravado da tela (grave por mais tempo que a narração — resultados e spinners aparecem segundos após um clique), e
  2. um mapa nomeado de retângulos de elementos: para cada elemento que a narração nomeará, seu retângulo em pixels da filmagem (o espaço de coordenadas que o clipe composto usa).

O toolkit de interface do alvo decide como você obtém essas coisas. Dois backends:

Um app macOS — AppleScript + ffmpeg avfoundation

  • Grave avfoundation "Capture screen N" e recorte em tempo real para a janela do app. Faça uma sondagem uma vez (grave ~1.5s, extraia um quadro, confirme crop=W:H:X:Y). A tela é Retina, então corte físico = DPR × lógico (DPR geralmente é 2).
  • Conduza com System Events. Encontre as primitivas confiáveis para o toolkit deste app — elas diferem por app. Cuidados gerais que se repetem:
    • Cliques coordenados geralmente não funcionam em listas SwiftUI/AppKit; use select/AXPress do AX no elemento.
    • Controles segmentados são expostos como AXRadioButtons; consulte-os por função.
    • Consultas AX logo após uma troca de visualização podem competir (resultados vazios) — tente novamente ou evite navegação dentro da sessão completamente.
    • Se a navegação for instável, reinicie o app já no estado necessário (via argumentos de inicialização / variáveis de ambiente / um esquema de URL que o app suporta) e acione apenas a única ação em câmera. Barato e determinístico.
  • -capture_cursor 0 (ações AX não movem o ponteiro, então o cursor fica fora do quadro). Para um cursor visível, sintetize um na pós-produção (veja Foco).
  • Mapa de elementos: consulte position+size do AX de cada elemento e converta para pixels da filmagem: (global − window_origin) × DPR. Se o toolkit ocultar retângulos de campos, meça a partir de um quadro gradeado da filmagem. Confie no quadro da filmagem em vez de números AX desatualizados se eles discordarem (o estado de rolagem difere); verifique cada quadro de foco.

Um site — Playwright (recomendado em vez de captura de tela)

  • Grave com recordVideo; defina recordVideo.size igual ao viewport e normalize o webm para seu fps antes de compor.
  • Espaço de coordenadas (a armadilha #1): Playwright grava no tamanho do viewport, então quando recordVideo.size == viewport, px da filmagem == px CSS. deviceScaleFactor: 2 apenas melhora a renderização — NÃO escala o vídeo gravado, e um recordVideo.size maior que o viewport apenas preenche a área extra de preto (a página permanece no canto superior esquerdo em 1×, NÃO é escalada para preencher). Portanto, boundingBox() dá px da filmagem diretamente — NÃO multiplique por DPR. (Se você gravar em um tamanho diferente, escale os retângulos por recordedSize / viewport.) Sempre verifique sobrepondo um retângulo conhecido em um quadro extraído antes de gravar todas as cenas — uma suposição errada de DPR coloca silenciosamente todo anel de foco no lugar errado.
  • Capture cada retângulo em uma posição de rolagem fixa: faça toda a rolagem primeiro, deixe estabilizar, então leia todos os boundingBox()es, então segure. Os anéis vivem em coordenadas da filmagem e devem permanecer fixos enquanto a câmera amplia/desloca. Emita a trilha de interação a partir do relógio da página se você quiser foco automático.
  • Estabilize a página primeiro: desabilite animações CSS / prefers-reduced-motion, dispense banners de cookies, oculte a barra de rolagem e waitForLoadState('networkidle') para que nada apareça na câmera. Autenticação automática via um addInitScript que semeia localStorage antes da navegação, quando o app suportar.
  • Movimento: para páginas longas, capture uma captura de tela de página inteira e desloque-a (um efeito Ken-Burns vertical) em vez de gravar rolagem ao vivo instável.

Filmagem de modelo real — mostre a saída genuína, esconda a espera. Quando uma cena precisa executar um modelo lento ao vivo (legendas/chat/inferência reais), grave o fluxo real, mas comprima o tempo das esperas: marque cada janela clique → resultado (um relógio monotônico desde o início da página), então comprima APENAS essas janelas com ffmpeg (trim+setpts+concat; a ação permanece em 1×) e congele o último quadro (tpad=stop_mode=clone) para que qualquer duração da cena se desenrole no resultado. Aqueça o modelo com uma solicitação descartável primeiro — uma carga a frio pode ser 10–40× uma chamada quente (por exemplo, um modelo de visão: ~38s frio → ~5s quente). Formule e temporize a narração sobre o clipe com tempo comprimido; mantenha essas cenas em reprodução simples (a ação carrega o movimento). Receita completa + trechos: references/playwright-recording.md.

Um exemplo macOS totalmente funcional (seletores exatos, hooks de ambiente, retângulo de corte, retângulos de elementos e um gravador chave na mão) está em references/video-studio-mlx-app.md — esse exemplo demonstra o mesmo app que hospeda a Studio API, mas trate seus específicos como ilustrativos; seu alvo terá os seus próprios.

Composição (scripts/compose.py)

Orientado por configuração, agnóstico ao alvo. Cada cena se torna um clipe 1080p normalizado: a filmagem é escalada dentro de um cartão emoldurado em um palco com gradiente escuro (sombra suave), uma legenda Pillow (pílula no terço inferior para etapas, grande título+subtítulo com scrim para hero), transições de clipe + legenda, depois uma classificação de acabamento compartilhada (cor + curva S + sombras frias + vinheta + grão de filme + anti-banding) para que capturas díspares sejam lidas como um filme dirigido ("grade": false desativa, ou passe um bloco para ajustar strength/tint). Cenas hero recebem um tratamento cinematográfico: um empurrão Ken Burns suave (ease-out) na imagem parada, uma placa de fundo escurecida e fosca atrás do cartão e um fade-in escalonado de título e subtítulo. Os clipes se encadeiam com transições xfade por cena (padrão fade; defina transition/xfade_dur por cena — fadeblack funciona bem em uma hero). Áudio: a narração é colocada com adelay na linha do tempo mestre e mixada com amix (normalize=0); uma faixa opcional de music é comprimida porducking sob a narração e a mixagem final é masterizada com loudnorm para −16 LUFS (apenas narração ainda é masterizada).

Efeitos de foco — ancorados na narração (zoom + anel seguem as palavras)

O foco deve apontar para o que a narração está nomeando, exatamente quando ela diz — então é criado como frase → elemento, temporizado a partir dos timestamps das palavras, nunca colocado manualmente em segundos e nunca fixado em um elemento por uma cena inteira. Uma cena declara um view (qual mapa de retângulos de elementos) e uma lista de focus (os nomes de elementos/visualizações são o que seu app alvo tiver):

"view": "main",
"focus": [
  { "say": "search",   "element": "search_field" },
  { "say": "results",  "element": "result_list" },
  { "say": "generate", "element": "primary_button", "zoom": 1.7 }
]

Como o compose resolve:

  • Quando — resolve_phrase encontra a execução contígua de palavras correspondentes a say no words do segmento e retorna [início,fim]. Palavras repetidas não são ambíguas: a lista de palavras é posicional — escolha por occurrence (padrão: primeira). Toca no tempo do clipe lead + word_start.
  • Onde — element é um retângulo em elements.json sob o view da cena (ou um map:key para referenciar um mapa compartilhado, por exemplo, uma barra lateral persistente).
  • Câmera — zoompan multi-keyframe (focus_camera), smoothstep absoluto baseado em on. Entre dois focos, ela desliza diretamente alvo→alvo por padrão; ela só retorna à visão completa quando o próximo alvo está AMBOS longe (fora do viewport ampliado anterior) E o intervalo é longo (focus_gap_full, ~2.2s) — então um elemento adjacente/já visível apenas desloca um pouco em vez de um zoom out/zoom in abrupto. Os deslocamentos são em velocidade constante (duração = distância ÷ focus_pan_speed px/s, limitado por focus_move_min): a câmera mantém o enquadramento anterior, então desliza a um px/s fixo chegando quando a próxima palavra começa — deslocamentos próximos e distantes parecem iguais, não "lento e depois rápido". "focus_pan": true força deslizamento direto em todos os lugares.
  • Anel — desenhado em coordenadas da filmagem antes da câmera, para que permaneça fixo no elemento enquanto amplia/desloca; fade in/out ao redor da frase.
  • Zoom e anel são desacoplados e o zoom se auto-limita para caber (fit_zoom): o zoom é reduzido para que o elemento destacado permaneça totalmente enquadrado, e um alvo largo cai para apenas anel (z=1) para que não seja cortado. Não os emparelhe por padrão — ambos existem apenas para apontar o olhar; escolha o que se ajusta ao tamanho do alvo. ring:false dá um zoom suave sem anel.

Dados de suporte e extensões:

  • Mapa de elementos (elements.json): retângulos nomeados por visualização em px da filmagem. Veja Gravação para como obtê-los; verifique verificando cada quadro de foco.
  • Capture maior do que você apresenta para que o zoom permaneça nítido — a câmera corta a filmagem nativa para o tamanho no palco, então ~1.7× ainda tem pixels reais. No macOS, a captura Retina já superamostra. Na web, deviceScaleFactor NÃO amplia o vídeo gravado (veja Gravação) — para obter superamostragem, grave em um viewport/recordVideo.size maior que o cartão no palco (por exemplo, capture 1920 de largura, apresente em um cartão de ~1456), não aumentando o DPR.
  • O gravador pode emitir uma trilha de interação (emit_track.py) para que track_to_effects derive automaticamente um zoom+anel por clique; focus inline é o caminho preciso. A estrutura está aberta para sobreposições de cursor/spotlight usando os mesmos retângulos + tempos de palavras.

Nota de design (por que frase→elemento, não marcadores de cue do lado da API): timestamps de palavras já são uma lista posicional, então o compositor possui "qual elemento / qual ocorrência" — a Studio API permanece uma primitiva limpa (áudio + tempos de palavras) utilizável para demonstrar qualquer produto. A filmagem deve realmente mostrar o elemento nomeado (não rolado/estático) naquele momento; formule a narração para que isso aconteça.

Matemática da linha do tempo (mantenha vídeo e áudio consistentes)

  • duração da cena d_i = narration_i + pad_i (pad ≈ 2 passo / 3.4 hero).
  • início da cena no mestre é acumulado por transição: start_0 = 0, start_i = start_(i−1) + d_(i−1) − T_i, onde T_i é a duração do xfade DENTRO de cena i (por cena xfade_dur, padrão xfade; limitado abaixo de ambos os clipes adjacentes). Com todo T_i = T isso reduz para Σ d_(<i) − i·T.
  • coloque a narração i em start_i + lead (lead ≈ 0.8, após o fade de entrada) — o mesmo start_i recalculado, então o áudio permanece sincronizado. Certifique-se tin_i + d_i ≤ comprimento do clipe de origem.

Verificação (você não pode ouvir o vídeo — use ASR + quadros)

A saída é um vídeo sem áudio que você pode inspecionar. A narração está lá, mas você não pode reproduzi-la. Use essas verificações:

  • Tira de quadros — extraia um quadro a cada 2s (ffmpeg -i out.mp4 -vf "fps=0.5" frames/%04d.png) e inspecione visualmente: o enquadramento, legendas, anéis de foco, transições. Aparência de filme.
  • Verificação de foco — para cada foco no storyboard, extraia o quadro no word_start e sobreponha o retângulo do elemento (do elements.json escalado para o palco). Eles devem corresponder. Se não, ajuste os retângulos (provavelmente estão errados) e recomponha.
  • ASR slice — fatie o vídeo em torno de uma cena (ffmpeg -i out.mp4 -ss <scene_start> -t <scene_dur> scene.wav) e execute /asr nele. A transcrição deve corresponder ao texto da narração daquela cena. Se não, a narração não foi colocada corretamente. Isso é surpreendentemente raro quando a matemática da linha do tempo está correta (ela acerta) mas pega o erro óbvio de um narração de 40s em um clipe de 20s.
  • Sincronização lipped — extraia um par de quadros em duas palavras consecutivas; meça o deslocamento do mesmo elemento (por exemplo, um botão) e confirme que a diferença de pixels por diferença de tempo corresponde a focus_pan_speed.

Scripts de referência

scripts/generate_narration.py e scripts/compose.py são canônicos — o pipeline os chama como subprocessos. Eles são a autoridade final sobre os formatos de entrada/saída. A configuração para ambientes de desenvolvimento remoto está em reference/setup-docs/; scripts ad-hoc de conveniência (local runner, launchd agent) são descartáveis.

generate_narration.py

Lê storyboard.json e gera narration/manifest.json, wavs/ (narração por cena) e acredita tracks/ (mono flacs de faixas de interação). Aceita --voice (instrução de design) e --ref-audio (caminho para clonagem) — apenas um, e com --ref-audio o storyboard pode sobrescrever por cena. O trabalho real acontece no pacote video_studio que ele importa:

  • Cada cena é enviada para /studio/tts. Resposta: segments[].{duration_s,words,wer}, escrita como um array paralelo a narration do storyboard.
  • ASR pós-geração é executado para validar — se wer > 0.10 o script registra o problema e para (nunca corrija a saída do TTS).
  • Os wavs de narração são cortados dos segmentos combinados do TTS (positional, concatenados com ffmpeg) ou baixados de um URL audio na resposta.

compose.py

Lê o storyboard, os wavs de narração, os clipes gravados e o mapa de retângulos. A saída é out/video.mp4. A lógica de composição core é em video_studio/editor/: composer.py (timeline, efeitos, transições), framer.py (estágio, empurrão Ken Burns, moldura, sombra, placa de fundo), caption.py (Pillow, grade na tela), focus.py (zoompan, resolução de alvo, anel), audio.py (colocação da narração, ducking de música, masterização loudnorm), grade.py (cor).

Guia de início rápido (para um agente que executa este pipeline)

  1. Escreva storyboard.json — matriz de cenas, cada uma com narration (texto a ser falado), action (descrição da gravação), type ("step"|"hero"), duration_s (opcional — deixa o script definir a partir da narração + paddings padrão), caption (opcional — texto da legenda; padrão para a primeira frase da narração se omitido para step, em branco para hero).
  2. Execute generate_narration.py para obter o tempo e os wavs.
  3. Grave cada clipe — veja Recording para seu alvo. Produza mapas de elementos.
  4. Execute compose.py.
  5. Verifique, ajuste parâmetros (paddings, zooms, posições de legenda, etc.) e recomponha.

O storyboard pode ser re-gerado e a narração re-gerada independentemente — mantenha os clipes gravados até que a narração pareça boa. A pós-produção (composição) é o loop mais rápido; foque em deixar a narração certa primeiro.

Configuração de desenvolvimento remoto

reference/setup-docs/ contém:`

  • setup-mac-remote.sh — configura um Mac mini como um executor remoto ffmpeg + Studio API.
  • no-machine-setup.md — instruções para configurar uma VM Linux para desenvolvimento (sem tela, usando Playwright + captura de tela completa + rolagem Ken Burns para gravação).

Mais documentação detalhada para cada subsistema está em references/, destilada do código-fonte. Não a invente; está toda documentada.

Habilidades Relacionadas