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
- 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.jsonpara<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. - 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 (oref_audiodo usuário, ou uma instruçãovoiceque ele projeta uma vez — veja abaixo), valida com ASR e escrevenarration/manifest.jsoncomduration_s,werewordspor segmento. (Vejareferences/studio-api.md.) - 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á.
- 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. - 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 emreferences/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
/asrprimeiro (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 designvoiceno storyboard e ogenerate_narration.pyprojeta 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.drawtextgeralmente 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:
- um clipe gravado da tela (grave por mais tempo que a narração — resultados e spinners aparecem segundos após um clique), e
- 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, confirmecrop=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/AXPressdo 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.
- Cliques coordenados geralmente não funcionam em listas SwiftUI/AppKit; use
-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+sizedo 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; definarecordVideo.sizeigual aoviewporte 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: 2apenas melhora a renderização — NÃO escala o vídeo gravado, e umrecordVideo.sizemaior 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 porrecordedSize / 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 ewaitForLoadState('networkidle')para que nada apareça na câmera. Autenticação automática via umaddInitScriptque semeialocalStorageantes 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_phraseencontra a execução contígua de palavras correspondentes asaynowordsdo segmento e retorna [início,fim]. Palavras repetidas não são ambíguas: a lista de palavras é posicional — escolha poroccurrence(padrão: primeira). Toca no tempo do clipelead + word_start. - Onde —
elementé um retângulo emelements.jsonsob oviewda cena (ou ummap:keypara referenciar um mapa compartilhado, por exemplo, uma barra lateral persistente). - Câmera —
zoompanmulti-keyframe (focus_camera), smoothstep absoluto baseado emon. 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_speedpx/s, limitado porfocus_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": trueforç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:falsedá 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,
deviceScaleFactorNÃO amplia o vídeo gravado (veja Gravação) — para obter superamostragem, grave em umviewport/recordVideo.sizemaior 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 quetrack_to_effectsderive automaticamente um zoom+anel por clique;focusinline é o caminho preciso. A estrutura está aberta para sobreposições decursor/spotlightusando 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, ondeT_ié a duração do xfade DENTRO de cenai(por cenaxfade_dur, padrãoxfade; limitado abaixo de ambos os clipes adjacentes). Com todoT_i = Tisso reduz paraΣ d_(<i) − i·T. - coloque a narração
iemstart_i + lead(lead ≈ 0.8, após o fade de entrada) — o mesmostart_irecalculado, então o áudio permanece sincronizado. Certifique-setin_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_starte sobreponha o retângulo do elemento (doelements.jsonescalado 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/asrnele. 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 anarrationdo storyboard. - ASR pós-geração é executado para validar — se
wer > 0.10o 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
audiona 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)
- Escreva
storyboard.json— matriz de cenas, cada uma comnarration(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). - Execute
generate_narration.pypara obter o tempo e os wavs. - Grave cada clipe — veja Recording para seu alvo. Produza mapas de elementos.
- Execute
compose.py. - 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.