vulh1209/product-video-skill

product-video

Filmagens reais + um registro de eventos -> um plano declarativo (YAML) -> pvk render -> folha de contato -> final. Os scripts cuidam da sincronização, zooms, sobreposições e áudio; você faz o storyboard, escreve o plano e verifica os quadros.

PVK=~/.claude/skills/product-video/bin/pvk      # ou `pvk` após `pip install -e ~/.claude/skills/product-video`

Quando usar

O usuário deseja	Fazer	Leia primeiro
Usuários aprenderem um recurso ou um aplicativo inteiro ("video hướng dẫn", tutorial, integração)	tutorial: capítulos de 1 a 3 min, depois pvk join	references/storyboard.md
Atenção para um produto ou lançamento ("video quảng cáo", promo, lançamento, teaser)	promo: um corte 16:9 de 30 a 45 s no ritmo	references/storyboard.md
Uma demonstração curta de um aplicativo web ou um clipe de reprodução de bug	o skill web-video sozinho	-

Regras rígidas

1. Aplicativo real, dados de amostra. Filme o produto real com dados de amostra realistas e fictícios. Sem maquetes, e nunca dados reais de clientes, segredos ou contas de produção (references/privacy.md).
2. Storyboard primeiro, depois um sim. Escreva o storyboard em linguagem simples e obtenha aprovação antes de qualquer gravação.
3. O design do projeto. Execute theme init no projeto, verifique o resultado em relação ao seu guia de design.
4. Música e efeitos sonoros são obrigatórios. Todo vídeo recebe uma base e sons de interface; masterizar a -16 LUFS.
5. Rascunho, olhe, depois final. Renderize --draft --check, abra todas as folhas de contato, corrija, e só então --final.
6. Nada sai da máquina (uploads, posts, anexos de issues) sem a permissão do proprietário.
7. Nunca lidere diálogos de segurança, chaves ou login. Deixe isso para o usuário.

Passo 0. Configuração (uma vez por máquina)

$PVK doctor                 # ffmpeg, Python 3.11+, pacotes, Chromium, fontes, ferramentas opcionais
python3 -m pip install -r ~/.claude/skills/product-video/requirements.txt && python3 -m playwright install chromium
$PVK fonts                  # baixa Inter, Playfair Display, JetBrains Mono (OFL) para ~/.cache/product-video
$PVK sfx gen && $PVK music beds
$PVK selftest               # renderiza um capítulo curto e um promo da demonstração incluída (~1 min)

Ferramentas ausentes: imprima o comando de instalação e pergunte; não instale silenciosamente.

Passo 1. Tema a partir do projeto

cd <pasta-do-video>                          # ex. <projeto>/video (mantenha as saídas fora do git)
$PVK theme init --repo <projeto> --out theme.json
$PVK fonts --theme theme.json
$PVK overlay chapter title="Pré-visualização" --theme theme.json --out preview.png   # veja

Corrija cores, fontes, brand e logo no theme.json manualmente quando o guia de design disser mais (references/theme.md).

Passo 2. Storyboard

Tutorial: um capítulo por tarefa que o usuário precisa aprender; cada capítulo = cartão de capítulo, filmagens com 3 a 8 legendas numeradas, cartão de resumo. Promo: 5 a 8 destaques, cada um com um cartão de título curto + um momento de filmagem de 2 a 4 s, cartão final. Escreva como uma tabela (tempo, tela, legenda, som) e obtenha um sim. Detalhes: references/storyboard.md.

Passo 3. Captura

Produto	Como
Aplicativo nativo macOS	escreva scene.py (veja examples/scene_native.py), então $PVK capture native scene.py --app "App" --out takes/s1 --rehearse, depois sem --rehearse
Aplicativo web	grave com web-video (record.py --slug x), então $PVK capture import video-out/x/v1 --name w1
Qualquer outra coisa	coloque raw.mp4 e um events.json (veja references/plan-format.md) em takes/<nome>/
Ainda sem aplicativo / testando	$PVK demo --out takes/demo

Antes de cada gravação: dados de amostra carregados, notificações desligadas (Não Perturbe), notificações antigas fechadas, tamanho da janela fixo. Após cada gravação: $PVK check popups takes/s1 e $PVK check grab takes/s1 grab.png 1 5 9 para visualizar. Armadilhas do macOS (teclas Mission Control, Cmd vs Ctrl, ponteiro real, HUDs): references/pitfalls.md.

Passo 4. Plano

Copie examples/tutorial.yaml ou examples/promo.yaml para a pasta das gravações e edite-o. Os tempos nos clipes são em segundos da fonte a partir do events.json da gravação; as caixas são em pixels da fonte. Formato completo: references/plan-format.md.

$PVK render ch01.yaml --only-plan     # rápido: out/plan/ch01.md lista cada clipe, legenda, zoom, som, aviso

Corrija todos os avisos (legendas curtas, sobreposições, chamadas que abrangem um zoom, números de passo com 2 dígitos).

Passo 5. Rascunho e verificação

$PVK render ch01.yaml --draft --check            # 720p; out/drafts/ch01.mp4 + out/check/ch01/contact-*.png
$PVK render ch01.yaml --frames 3.2,7.5           # stills nos tempos de saída, para uma inspeção mais próxima
$PVK promo promo.yaml --draft --check            # promos: mesmo motor, cortes ajustados à grade de batidas

Abra todas as folhas de contato (Leia os PNGs). Verifique: legendas legíveis e sem cobrir a ação, zoom no lugar certo, sem pop-up do SO ou notificação remanescente, cursor onde está o clique, cartões escritos corretamente, loudness em cerca de -16 LUFS. Até 3 passes de correção, depois mostre ao usuário o rascunho e a folha.

Passo 6. Final e corte completo

$PVK render ch01.yaml --final                    # 1080p, out/final/ch01.mp4
$PVK join out/final/tutorial.mp4 out/final/ch0*.mp4
$PVK check out/final/tutorial.mp4

Relatório: caminhos dos arquivos, durações, loudness, o que não pôde ser verificado (você não pode ouvir a mixagem: diga isso).

Música e som

music: bed:soft-piano | bed:ambient | bed:promo são bases sintetizadas (trabalho próprio, gratuitas). Para faixas licenciadas: $PVK music fetch (onde obtê-las), então $PVK music add track.mp3 --title ... --author ... --source URL --license ... (normaliza para -20 LUFS e registra music/LICENSES.md). Nunca faça commit de faixas de terceiros. Mapa de efeitos sonoros, ducking e loudness: references/audio.md.

Referências

• references/storyboard.md: tutorial vs promo, estrutura de capítulo, escrita de legendas, cortes no ritmo
• references/plan-format.md: todas as chaves do plano, o formato events.json, a matemática da linha do tempo
• references/theme.md: theme.json, theme init, fontes (OFL), logo
• references/audio.md: bases, música licenciada, mapa de efeitos sonoros, alvos de loudness
• references/capture.md: captura nativa no macOS, importação web-video, layout das gravações
• references/pitfalls.md: tudo que deu errado em projetos reais e a correção
• references/privacy.md: regras de dados e compartilhamento