AnayDhawan/openvidstudio

O que openvidstudio faz?

Construa um vídeo de demonstração a partir do aplicativo real em execução de um projeto. Cada tela vem do produto real; nada é gerado.

Antes de qualquer coisa

Execute preflight. Ele verifica node, ffmpeg, Chromium do Playwright, se o aplicativo está realmente respondendo e se existe um mecanismo de narração. Cada falha nomeia a correção. Pular isso significa que uma dependência ausente só aparecerá após uma renderização longa.

Se as ferramentas não estiverem registradas, o servidor não está instalado. Aponte o usuário para isso na configuração MCP dele, depois reinicie o cliente:

{ "mcpServers": { "openvidstudio": { "command": "npx", "args": ["-y", "@openvidstudio/mcp-server"] } } }

A ordem

preflight -> extract_brand -> plan_beats -> [escrever VO] -> validate_beats -> PORTAO DE APROVACAO
  -> write_beats_file -> capture_screenshot -> scaffold_scene -> validate_scenes
  -> [plan_sound_effects] -> generate_narration -> stitch_composition -> contact_sheet
  -> render_video -> qc_extract_frames

1. Coleta de informações

Resolva antes de perguntar. O pedido usual é "criar um vídeo de demonstração deste projeto" e nada mais. Essa é a solicitação completa, e é suficiente.

Comece lendo o repositório em vez de entrevistar o usuário:

• README.md diz o que é o produto e frequentemente o que é importante sobre ele
• package.json scripts dizem como iniciá-lo, e o script de desenvolvimento geralmente nomeia a porta
• as rotas ou páginas dizem o que há para filmar

Em seguida, inicie o aplicativo você mesmo e confirme que ele responde. Não pergunte ao usuário por uma URL que ele tenha que procurar; encontre o comando de desenvolvimento, execute-o e verifique. Pergunte apenas se iniciá-lo precisar de algo que você não possa saber, como um .env ausente ou um banco de dados que não esteja ativo.

O que vale genuinamente a pena perguntar, porque o repositório não pode dizer:

• quanto tempo o vídeo deve ter
• quais duas ou três coisas ele deve mostrar, se o repositório tiver muitas
• para quem é, um visitante da página de destino ou alguém já instalando

Uma pergunta de cada vez, e apenas perguntas que o repositório não pode responder. Uma parede de seis perguntas no início é a maneira mais rápida de fazer isso parecer trabalho. docs/PLANNING.md tem a árvore de decisão completa se um caso não estiver claro.

Termine o trabalho mostrando o resultado: o caminho do mp4, sua duração e uma contact_sheet ou alguns stills de qc_extract_frames. Uma renderização que ninguém vê não é um vídeo entregue.

1b. Vista a marca do repositório

extract_brand com sourceRepo definido para o repositório que está sendo filmado. Ele lê blocos @theme do Tailwind v4 e propriedades customizadas :root, seleciona fontes de imports next/font, copia o melhor logotipo que encontrar e escreve src/brand.ts.

Execute-o antes de scaffold_scene. Um vídeo temático após o fato significa re-andaimar.

Verifique a lista unresolved que ele retorna e preencha manualmente qualquer coisa que importar. Ele relata apenas o que realmente pode encontrar, em vez de inventar uma cor plausível, portanto um token não resolvido é uma lacuna real, não uma falha.

Uma regra que isso impõe em cenas escritas à mão: leia tokens dentro do componente, não no escopo do módulo. applyBrand muta os objetos de token compartilhados, então const MONO = \"${font.mono}"`no topo de um arquivo captura o padrão e nunca vê a marca. UsemonoStack()euiStack()` em vez disso.

2. Planeje as batidas

plan_beats com a duração alvo e os recursos. Retorna um esqueleto contíguo com um método de captura e um orçamento de palavras por batida.

Escreva a narração para esse orçamento. validate_beats impõe 2,3 a 2,9 palavras por segundo como um piso e teto rígidos por batida, então uma linha pode ser rejeitada por ser muito esparsa. Escrever para o número informado evita a ida e volta.

Cada batida screenshot também precisa de visual.url e visual.interactions (um array, possivelmente vazio). Nenhum outro documento afirma isso antecipadamente.

3. O portão de aprovação

Mostre ao usuário o arquivo de batidas completo, não um resumo, e aguarde um sim explícito. Nada vai para o disco antes disso. Esta é uma regra de protocolo, não uma sugestão, e é o ponto onde um vídeo errado custa uma frase em vez de uma hora.

Depois write_beats_file.

4. Captura

capture_screenshot por batida de screenshot. Compensa uma dessincronização de zoom do Chrome por origem que, de outra forma, produz capturas pequenas, suaves ou mal enquadradas.

Passe uma interação wait se a página tiver animações de entrada, ou a captura as pegará no meio do voo e parecerá quebrada em vez de obviamente errada.

5. Cenas

scaffold_scene por batida. Emite uma cena que renderiza como está, usando a própria cópia e duração daquela batida. Edite o conteúdo; não reconstrua a estrutura.

Depois validate_scenes. Captura a falha que renderiza com sucesso e está simplesmente errada: conteúdo disposto na largura total do palco será cortado quando a câmera se aproximar, porque a área visível é o palco dividido pela escala da câmera. Também sinaliza câmeras estáticas, ativos ausentes e batidas sem narração.

Leia docs/API.md para props. Não leia o código-fonte da biblioteca.

6. Narração

generate_narration. Escreve um clipe por batida onde stitch_composition procura, e limita o alongamento de tempo a um intervalo que permanece natural em vez de ajustar clipes às batidas a qualquer custo. Quando disser que uma batida não cabe, corrija o script ou a duração da batida; não alongue mais.

6b. Som, apenas se os embutidos não cobrirem

O pacote sintetizado já inclui cliques, teclas, um sino, um bip, um tom de sucesso, um whoosh e uma base musical, e não carrega direitos de terceiros porque o ffmpeg o gera. Prefira-o.

Se o vídeo genuinamente precisar de outra coisa, pergunte ao usuário quais sons ele deseja, então plan_sound_effects com uma entrada por som. Informa quais solicitações os embutidos já cobrem e retorna um link de pesquisa do Pixabay mais um caminho de salvamento exato para o restante.

Ele não baixa do Pixabay, e você também não deveria. Os termos do Pixabay proíbem coleta automatizada e dizem que a API é para solicitações humanas reais, e eles não publicam nenhum endpoint de efeitos sonoros. O usuário baixa; você verifica. Chame a ferramenta novamente com verify: true depois para confirmar que cada arquivo é áudio real e normalizar os formatos.

provider: "freesound" busca automaticamente em vez disso, mas apenas com o token de API do próprio usuário, e cada clipe que ele usa é registrado em ATTRIBUTION.md. Qualquer coisa nesse arquivo precisa chegar à descrição do vídeo ou a licença é violada.

Música é a exceção a tudo isso. find_music_bed pesquisa dois catálogos de domínio público CC0 (~9.400 faixas) e import_music_bed corta, desvanece e iguala o volume da que o usuário escolher em public/audio/music-bed.mp3. Nada lá precisa de créditos. O skill bgmusic tem os detalhes; recorra a ele quando as bases sintetizadas forem muito simples para uma peça de lançamento ou promoção.

7. Monte e verifique

stitch_composition, depois contact_sheet antes de renderizar. A contact sheet são dois quadros por batida em uma imagem e leva uma fração de uma renderização completa, o que importa porque um vídeo de cinco minutos tem 9000 quadros.

render_video com draft: true primeiro. Qualidade total apenas quando o rascunho parecer correto.

Depois qc_extract_frames e trabalhe a lista de verificação de docs/PIPELINE.md.

Regras que reprovam no QC

De docs/STYLE.md, reafirmadas porque são as mais frequentemente quebradas:

• Sem easing linear. Use os presets E.*.
• Toda cena dentro de CinematicScene.
• O movimento nunca para. Um quadro estático é uma falha.
• Sem travessões, na tela ou na narração.
• Legendas vão em overlay, não em children, ou elas flutuam para fora da tela conforme a câmera se move.
• Screenshots apenas dentro de BrowserFrame. Gravações e clipes de IA não devem estar, ou a filmagem gerada adquire a assinatura visual de uma captura real.

O que não afirmar

UI de produto real, seja renderizada por DOM, capturada como screenshot ou gravada, é verdade fundamental. Clipes gerados por IA são atmosfera apenas e nunca carregam texto do produto. Se a narração afirmar algo, o visual tem que mostrar; se não puder, reescreva a linha.