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.
- 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.
- 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.
- Mecanismo. Ofereça o que esta máquina realmente pode fazer — execute
python3 scripts/demo_env.pyprimeiro 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.
- Voz, se o mecanismo tiver opções: ofereça 3–5 vozes com uma linha cada (ex.: Qwen
serena/ryan, Kokorozf_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
- 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. - Verifique por números, não assistindo a imagens.
demo_render.py --checkedemo_voice.py checksão a fonte da verdade. Não afirme que um vídeo está pronto enquanto algum deles relatar problemas注意:. - 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.
- 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:
| Nome | O que é |
|---|---|
TITLE, SUBTITLE, CHAPTERS | texto na faixa superior; capítulos também são desenhados na página |
LANGUAGE | o idioma das legendas e da narração (zh, en, ja, ko, de, fr, es, it, pt, ru) |
VIEW, DENSITY | tamanho da página em pixels CSS e escala do dispositivo; largura/altura deve ser 64:31 |
PORT | porta da instância descartável |
LOOK | {'accent': '#2f6fed', 'note': '#ee5c18', 'fast': '快进'} — fast no idioma da faixa de legenda |
VOICE | narração: engine, speaker, e para um serviço remoto model / base_url (nunca a chave); veja references/engines.md |
READING | velocidade 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 ded.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
缺 …→ executepython3 scripts/demo_env.pye siga a linha→.- Porta já em uso → altere
PORTna 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; ajusteVIEWou 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 aVOICE['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_*(vejareferences/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.