Communitygithub.com

autoDemoRecordingSkill

Grave automaticamente um vídeo de demonstração polido de uma aplicação web, com ou sem narração. Conduz a aplicação no Chromium headless a partir de um arquivo de história, grava cliques/teclas/rolagens, renderiza um vídeo 1920x1080 60fps com movimentos de câmera, destaques, etapas numeradas, legendas e capítulos, depois adiciona narração no idioma escolhido — via Qwen3-TTS local em GPU NVIDIA, Kokoro local em qualquer CPU, ou API remota (compatível com OpenAI, ElevenLabs, Alibaba DashScope) — e verifica imagem e som numericamente. Funciona em Linux, Windows e macOS, e sob Claude Code ou Codex. Use quando alguém pedir um vídeo de demonstração de produto, gravação de tela, passo a passo, tour de funcionalidades ou screencast narrado de uma aplicação web.

O que é autoDemoRecordingSkill?

A habilidade **autoDemoRecordingSkill** permite que agentes de IA (como Claude Code e Codex) transformem automaticamente uma aplicação web em um vídeo de demonstração profissional, completo e narrado. O fluxo de trabalho é iniciado a partir de um arquivo de história (`story.py`) que define as ações a serem realizadas na interface (cliques, digitação, rolagem) e os textos das legendas. Um script chamado `demo_record.py` utiliza o Chromium em modo headless para executar essas ações e capturar cada frame, gerando um arquivo de linha do tempo (`timeline.json`). Em seguida, o `demo_render.py` monta o vídeo sem narração em 1920x1080 a 60 fps, adicionando automaticamente movimentos de câmera, destaques, números de etapas e legendas. Opcionalmente, o `demo_voice.py` insere narração, lendo as legendas no idioma desejado (mandarim, inglês, japonês, coreano, alemão, francês, espanhol, italiano, português ou russo), utilizando mecanismos de TTS locais (Qwen3-TTS em GPU NVIDIA ou Kokoro em CPU) ou serviços remotos (via API compatível com OpenAI, ElevenLabs ou DashScope). A ferramenta inclui verificações numéricas rigorosas para garantir qualidade de áudio e vídeo antes da entrega final, suporta ambientes Windows, Linux e macOS, e é projetada para não interferir em serviços em execução, utilizando instâncias descartáveis da aplicação para proteção de dados reais.

Funciona com✓Claude Code✓Codex CLI~Cursor
npx skills add https://github.com/OrrrGE/autoRecording/tree/main

Perguntar na sua IA favorita

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

Documentação

autoRecording

Transforme uma aplicação web em um vídeo de demonstração finalizado. Você escreve um arquivo de história que diz o que mostrar e o que dizer; os scripts cuidam da gravação, desenho, codificação, narração e verificação. O vídeo pode ser silencioso ou narrado, em mandarim, inglês, japonês, coreano, alemão, francês, espanhol, italiano, português ou russo, falado por um modelo local (GPU ou CPU) ou um serviço remoto fornecido pelo usuário.

story.py ──demo_record.py──► timeline.json + frames/*.jpg
                                  │
                           demo_render.py ──► silent.mp4  (1920×1080, 60 fps)
                                  │
                           demo_voice.py  ──► silent-配音版.mp4 / silent-narrated.mp4   (opcional)

0. Pergunte antes de qualquer outra coisa

Não comece a gravar antes que estas perguntas sejam respondidas. No Claude Code use AskUserQuestion; no Codex ou qualquer outro agente, pergunte em palavras simples e aguarde a resposta.

  1. Narração? Vídeo silencioso, ou narração falada. Se o usuário não precisar de narração, pule todas as etapas de narração; o vídeo silencioso é a entrega.
  2. Idioma da narração (e das legendas, que são o texto lido): 普通话 / English / 日本語 / 한국어 / Deutsch / français / español / italiano / português / русский. Padrão: o idioma da aplicação e no qual o usuário escreve.
  3. Mecanismo. Ofereça o que esta máquina realmente pode fazer — execute python3 scripts/demo_env.py primeiro e ofereça apenas os mecanismos listados como disponíveis:
    • local Qwen3-TTS (本机 GPU): melhor qualidade; precisa de GPU NVIDIA com ~6 GB de VRAM livre e os modelos Qwen.
    • local Kokoro (本机 CPU): não precisa de GPU, funciona no Windows e macOS; bom mandarim e inglês; vozes são fixas (sem clonagem).
    • API remota: o usuário fornece o provedor (endpoint compatível com OpenAI, incluindo auto-hospedado, ElevenLabs ou Alibaba DashScope Qwen-TTS), a chave e, opcionalmente, uma URL base, modelo e ID de voz. Regra prática: um modelo local que está pronto → use-o; o usuário oferece uma chave de API → use a API; nenhum dos dois → pergunte se deseja instalar o Kokoro (download pequeno) ou prosseguir sem narração.
  4. Voz, se o mecanismo tiver opções: ofereça 3–5 vozes com uma linha cada (ex.: Qwen serena / ryan, Kokoro zf_039 / zm_013 / af_maple, um ID de voz OpenAI), com um padrão sensato.

Escreva as respostas no arquivo de história — LANGUAGE e VOICE = {'engine': …, 'speaker': …} — para que o mesmo vídeo possa ser feito novamente. Uma chave remota nunca é escrita na história: coloque-a no ambiente ou em demo_env.py key.

Itens inegociáveis

  1. Nunca grave o serviço ativo do usuário ou dados reais. Inicie uma instância descartável em outra porta com seu próprio diretório de dados (launch() no arquivo de história), ou um conjunto de dados de demonstração dedicado. Se a aplicação não puder ser isolada, pergunte.
  2. Verifique por números, não assistindo a imagens. demo_render.py --check e demo_voice.py check são a fonte da verdade. Não afirme que um vídeo está pronto enquanto algum deles relatar problemas 注意:.
  3. Não toque em um serviço em execução. Se a porta escolhida já estiver escutando, escolha outra porta; nunca pare o processo de outra pessoa.
  4. A narração é opcional e seu mecanismo é escolha do usuário. Qwen precisa de uma GPU NVIDIA; Kokoro roda em qualquer CPU; serviços remotos precisam de uma chave e enviam as legendas para esse serviço — diga isso antes de usar um.

Layout

SKILL.md                  este arquivo
scripts/demo_env.py       verificar a máquina; preparar o Python da habilidade; baixar modelos; lembrar chaves
scripts/demo_record.py    conduzir a aplicação e gravar frames + linha do tempo
scripts/demo_render.py    desenhar e codificar o vídeo silencioso; verificações numéricas
scripts/demo_voice.py     narração: linhas, âncora, takes, ouvir, construir, verificar
scripts/demo_tts.py       os mecanismos: Kokoro (CPU) e os serviços remotos
scripts/demo_text.py      como as legendas são ditas, contadas e comparadas, por idioma
scripts/demo_common.py    caminhos, configurações, navegadores, segredos compartilhados
story_template.py         copie este arquivo para escrever uma história para uma aplicação
examples/selftest/        uma página e duas histórias (história em mandarim story.py, história em inglês story-en.py)
references/               environment.md, director.md, narration.md, engines.md

Todos os comandos abaixo são relativos ao diretório desta habilidade; no Windows escreva py -3 (ou python) onde está escrito python3. Instale como uma habilidade pessoal clonando para ~/.claude/skills/autoDemoRecordingSkill (Claude Code) ou ~/.agents/skills/autoDemoRecordingSkill (Codex).

1. Verifique a máquina

cd ~/.claude/skills/autoDemoRecordingSkill
python3 scripts/demo_env.py            # somente leitura: o que existe, o que está faltando, como obter, quais mecanismos podem falar
python3 scripts/demo_env.py setup      # pacotes para gravar/renderizar/verificar (algumas centenas de MB)
python3 scripts/demo_env.py setup --models   # + Whisper large-v3 e verificações CAM++ (~3 GB)
python3 scripts/demo_env.py setup --kokoro   # + Kokoro, a voz em CPU (~400 MB)

Para o mecanismo Qwen, prepare também um Python com torch CUDA e faster-qwen3-tts, e os dois modelos Qwen3-TTS 1.7B; para um mecanismo remoto, lembre sua chave uma vez com python3 scripts/demo_env.py key openai=… (ou uma variável de ambiente). Grave cada local não padrão uma vez:

python3 scripts/demo_env.py set chromium=/caminho/para/chromium tts_python=/caminho/para/python \
    tts_custom=/caminho/para/Qwen3-TTS-12Hz-1.7B-CustomVoice tts_base=/caminho/para/Qwen3-TTS-12Hz-1.7B-Base

Os próprios arquivos da habilidade residem em ~/.cache/auto-demo-recording (substitua com AUTO_DEMO_HOME). references/environment.md tem os detalhes para Windows, macOS e Linux.

2. Valide a instalação com o autoteste

PY=~/.cache/auto-demo-recording/venv/bin/python
S=~/.claude/skills/autoDemoRecordingSkill
$PY $S/scripts/demo_record.py --story $S/examples/selftest/story.py --work /tmp/demo-selftest
$PY $S/scripts/demo_render.py --work /tmp/demo-selftest --check
$PY $S/scripts/demo_render.py --work /tmp/demo-selftest --out /tmp/demo-selftest/selftest.mp4
$PY $S/scripts/demo_voice.py --work /tmp/demo-selftest      # somente se uma narração for desejada

story-en.py é o mesmo teste com legendas em inglês e o caminho de narração em inglês. A gravação imprime um resumo JSON (duração, frames, navegador, erros). selftest.mp4 deve ser 1920×1080, 60 fps, cerca de 64 s.

3. Escreva a história

Copie story_template.py para perto da aplicação (ou em qualquer lugar) e preencha. O contrato:

NomeO que é
TITLE, SUBTITLE, CHAPTERStexto na faixa superior; capítulos também são desenhados na página
LANGUAGEo idioma das legendas e da narração (zh, en, ja, ko, de, fr, es, it, pt, ru)
VIEW, DENSITYtamanho da página em pixels CSS e escala do dispositivo; largura/altura deve ser 64:31
PORTporta da instância descartável
LOOK{'accent': '#2f6fed', 'note': '#ee5c18', 'fast': '快进'} — fast no idioma da faixa de legenda
VOICEnarração: engine, speaker, e para um serviço remoto model / base_url (nunca a chave); veja references/engines.md
READINGvelocidade de leitura para legendas; padrão: a do próprio idioma (5,5 caracteres/s para mandarim)
launch(work, port){'command': [...], 'url': ..., 'env': {...}, 'wipe': [...], 'cwd': ..., 'ready': ..., 'timeout': ...}; ou defina URL em vez disso
guard(d)opcional; falhe cedo se a página não estiver no estado inicial pretendido
story(d)a direção real: await d.say(...), await d.click(...), etc.

O objeto d é o diretor. Sua API completa, modelo de tempo, regras de marcação/localização e padrões comuns estão em references/director.md. Leia-o antes de escrever uma história; o resto deste arquivo é apenas o fluxo de trabalho.

Regras práticas para uma boa história:

  • Uma ideia por legenda; declare o que o espectador deve notar e os resultados que a página realmente mostra.
  • Prefira d.say() seguido de d.read() antes de prosseguir; as legendas também são o roteiro da narração.
  • Escreva as legendas em LANGUAGE. Para um vídeo silencioso, elas ainda são lidas na tela, então mantenha-as curtas.
  • Numere os cliques (await d.click(locator, '添加')) e marque apenas o que importa.
  • Acelere esperas longas (await d.until(..., speed=4)) em vez de cortá-las.

4. Grave

$PY $S/scripts/demo_record.py --story /caminho/para/story.py --work /tmp/demo-work --quick
$PY $S/scripts/demo_record.py --story /caminho/para/story.py --work /tmp/demo-work

--quick é um teste rápido: ele pula as pausas do espectador e espera apenas pela aplicação. Use-o para capturar erros de seletor e estado. Grave de verdade depois; work/timeline.json é sobrescrito e os frames antigos removidos.

Antes de gravar, o script limpa apenas frames e os caminhos listados em wipe, verifica se a porta está livre, inicia o comando da história e aguarda a resposta da aplicação. O log da aplicação é work/server.log. No Windows, a aplicação e tudo que ela inicia é parado com taskkill /T; em outros lugares, todo o grupo de processos é parado.

5. Verifique e renderize

$PY $S/scripts/demo_render.py --work /tmp/demo-work --check
$PY $S/scripts/demo_render.py --work /tmp/demo-work --out /tmp/demo-work/demo.mp4

--check verifica, sem olhar para imagens: regiões marcadas não estão vazias e correspondem às cores expect, rótulos não ficam sobre o conteúdo da página, caixas estão dentro da câmera, etapas/cliques estão visíveis, legendas cabem e os glifos existem na fonte. Corrija a história ou o tempo e grave novamente. A renderização também compara frames de saída amostrados com os frames que desenhou e escreve work/render.json.

Se o usuário não quiser narração, o vídeo silencioso é a entrega — pare aqui e relate.

6. Narre (apenas se solicitado)

$PY $S/scripts/demo_voice.py --work /tmp/demo-work            # todas as etapas
$PY $S/scripts/demo_voice.py lines --work /tmp/demo-work      # inspecione a pronúncia/tempo primeiro

Ele escreve o vídeo narrado ao lado do silencioso: <nome>-配音版.mp4 para mandarim, <nome>-narrated.mp4 para os outros idiomas. As etapas são retomáveis: clipe de referência → (Qwen: tentativa) → takes → verificações de fala/locutor → escolher/ajustar/misturar → verificar. Leia references/narration.md para configurações, correções de pronúncia e linhas apertadas, e references/engines.md para os mecanismos, suas vozes, chaves e custos. A verificação final deve dizer 没有发现问题; qualquer linha 听写有出入 significa que a voz disse outra coisa — corrija a legenda, adicione uma substituição say, refale essa linha ou escolha outra voz.

7. Relate

Forneça ao usuário o caminho de saída (silencioso e, se solicitado, narrado), duração, resolução/fps, número de legendas/marcações, o mecanismo e a voz de narração, e o resultado da verificação da narração. Mencione quaisquer avisos 注意: que permaneçam e nunca esconda uma verificação com falha.

Solução de problemas iniciais

  • 缺 … → execute python3 scripts/demo_env.py e siga a linha →.
  • Porta já em uso → altere PORT na história; não pare o serviço existente.
  • 点不到这个元素 → o elemento está coberto ou fora da tela; role/amplie primeiro, ou escolha outro alvo.
  • Incompatibilidade de largura da página → a página não é responsiva em VIEW; ajuste VIEW ou a página, mantenha a proporção 64:31.
  • Linha de narração muito apertada → encurte essa legenda ou dê mais tempo a ela, depois grave novamente.
  • Kokoro 的词表里没有这些词 → essas palavras são ignoradas pelo Kokoro; adicione-as a VOICE['say'] na grafia da legenda (ex.: "API": "A P I", "exported": "export ed"), ou use Qwen ou um mecanismo remoto para inglês.
  • Caixas de fonte (□□□) → no Linux instale Noto Sans CJK; Windows e macOS têm seus próprios rostos chineses; ou defina DEMO_FONT_* (veja references/environment.md).

Sob Codex

Codex carrega o mesmo SKILL.md. Ele não tem a ferramenta AskUserQuestion: faça as perguntas da etapa 0 em palavras simples. Ele pode executar com um PATH diferente — use py -3 ou o caminho completo do Python da habilidade. Instale a habilidade com git clone … ~/.agents/skills/autoDemoRecordingSkill (ou deixe o instalador de habilidades do Codex colocá-la em ~/.codex/skills); ambos são descobertos. agents/openai.yaml dá a ela um nome de exibição e um prompt inicial.

Privacidade

A pasta de trabalho contém capturas de tela do que a aplicação mostrou. Use uma instância descartável com dados de exemplo, nunca contas reais, clientes ou registros de produção. Não envie work/ ou vídeos renderizados sem revisá-los. timeline.json também registra o caminho do arquivo de história e o horário da captura. Um serviço de narração remoto recebe o texto da legenda de cada linha; um mecanismo local não envia nada.

Habilidades Relacionadas