vulh1209/product-video-skill

product-video

Grabación real + un registro de eventos -> un plan declarativo (YAML) -> pvk render -> hoja de contactos -> resultado final. Los scripts se encargan de los tiempos, zooms, superposiciones y audio; tú haces el guion gráfico, escribes el plan y revisas los fotogramas.

PVK=~/.claude/skills/product-video/bin/pvk      # o `pvk` después de `pip install -e ~/.claude/skills/product-video`

Cuándo usarlo

El usuario quiere	Hacer	Leer primero
Que los usuarios aprendan una función o una aplicación completa ("video hướng dẫn", tutorial, onboarding)	tutorial: capítulos de 1-3 min, luego pvk join	references/storyboard.md
Atención para un producto o lanzamiento ("video quảng cáo", promo, lanzamiento, teaser)	promo: un corte 16:9 de 30-45 s al ritmo	references/storyboard.md
Una demo corta de una aplicación web o un clip de reproducción de error	solo el web-video skill	-

Reglas estrictas

1. Aplicación real, datos de ejemplo. Graba el producto real con datos de ejemplo realistas pero inventados. Nada de maquetas, y nunca datos reales de clientes, secretos o cuentas de producción (references/privacy.md).
2. Guion gráfico primero, luego aprobación. Escribe el guion gráfico en lenguaje sencillo y obtén aprobación antes de cualquier toma.
3. El diseño del proyecto. Ejecuta theme init en el proyecto, verifica el resultado con su guía de diseño.
4. Música y efectos de sonido obligatorios. Cada video recibe una base musical y sonidos de IU; masterizado a -16 LUFS.
5. Borrador, revisión, luego final. Renderiza --draft --check, abre cada hoja de contactos, corrige, y solo entonces --final.
6. Nada sale de la máquina (subidas, publicaciones, archivos adjuntos de incidencias) sin el permiso del propietario.
7. Nunca manejes diálogos de seguridad, llaveros o inicio de sesión. Déjaselos al usuario.

Paso 0. Configuración (una vez por máquina)

$PVK doctor                 # ffmpeg, Python 3.11+, paquetes, Chromium, fuentes, herramientas opcionales
python3 -m pip install -r ~/.claude/skills/product-video/requirements.txt && python3 -m playwright install chromium
$PVK fonts                  # descarga Inter, Playfair Display, JetBrains Mono (OFL) en ~/.cache/product-video
$PVK sfx gen && $PVK music beds
$PVK selftest               # renderiza un capítulo corto y un promo de la demo incluida (~1 min)

Herramientas faltantes: imprime el comando de instalación y pregunta; no instales en silencio.

Paso 1. Tema a partir del proyecto

cd <carpeta-del-video>                          # ej. <proyecto>/video (mantén los resultados fuera de git)
$PVK theme init --repo <proyecto> --out theme.json
$PVK fonts --theme theme.json
$PVK overlay chapter title="Vista previa" --theme theme.json --out preview.png   # míralo

Corrige colores, fuentes, brand y logo en theme.json manualmente cuando la guía de diseño lo especifique más (references/theme.md).

Paso 2. Guion gráfico

Tutorial: un capítulo por tarea que el usuario debe aprender; cada capítulo = tarjeta de capítulo, grabación con 3-8 leyendas numeradas, tarjeta de resumen. Promo: 5-8 destacados, cada uno una tarjeta de titular corta + un momento de grabación de 2-4 s, tarjeta final. Escríbelo como una tabla (tiempo, pantalla, leyenda, sonido) y obtén una aprobación. Detalles: references/storyboard.md.

Paso 3. Captura

Producto	Cómo
Aplicación nativa macOS	escribe scene.py (ver examples/scene_native.py), luego $PVK capture native scene.py --app "App" --out takes/s1 --rehearse, luego sin --rehearse
Aplicación web	graba con web-video (record.py --slug x), luego $PVK capture import video-out/x/v1 --name w1
Cualquier otra cosa	coloca raw.mp4 y un events.json (ver references/plan-format.md) en takes/<nombre>/
Sin app aún / probando	$PVK demo --out takes/demo

Antes de cada toma: datos de ejemplo cargados, notificaciones desactivadas (No Molestar), toasts antiguos cerrados, tamaño de ventana fijo. Después de cada toma: $PVK check popups takes/s1 y $PVK check grab takes/s1 grab.png 1 5 9 para examinarla. Errores comunes de macOS (teclas de Mission Control, Cmd vs Ctrl, el puntero real, HUDs): references/pitfalls.md.

Paso 4. Plan

Copia examples/tutorial.yaml o examples/promo.yaml junto a las tomas y edítalo. Los tiempos en los clips de grabación son segundos de origen del events.json de la toma; las cajas son píxeles de origen. Formato completo: references/plan-format.md.

$PVK render ch01.yaml --only-plan     # rápido: out/plan/ch01.md lista cada clip, leyenda, zoom, sonido, advertencia

Corrige cada advertencia (leyendas cortas, superposiciones, llamadas que abarcan un zoom, números de paso de 2 dígitos).

Paso 5. Borrador y revisión

$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           # fotogramas fijos en tiempos de salida, para una inspección más cercana
$PVK promo promo.yaml --draft --check            # promos: mismo motor, cortes ajustados a la cuadrícula del ritmo

Abre cada hoja de contactos (Lee los PNG). Verifica: leyendas legibles y que no cubren la acción, zoom en el lugar correcto, sin ventana emergente del SO ni toast sobrante, cursor donde está el clic, tarjetas escritas correctamente, sonoridad alrededor de -16 LUFS. Hasta 3 pasadas de corrección, luego muéstrale al usuario el borrador y la hoja.

Paso 6. Final y montaje 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

Informe: rutas de archivo, duraciones, sonoridad, lo que no pudiste verificar (no puedes escuchar la mezcla: dímelo).

Música y sonido

music: bed:soft-piano | bed:ambient | bed:promo son bases sintetizadas (trabajo propio, gratuito). Para pistas con licencia: $PVK music fetch (dónde obtenerlas), luego $PVK music add track.mp3 --title ... --author ... --source URL --license ... (normaliza a -20 LUFS y registra en music/LICENSES.md). Nunca subas pistas de terceros. Mapa de efectos de sonido, ducking y sonoridad: references/audio.md.

Referencias

• references/storyboard.md: tutorial vs promo, estructura de capítulos, escritura de leyendas, cortes al ritmo
• references/plan-format.md: cada clave del plan, el formato events.json, la matemática de la línea de tiempo
• references/theme.md: theme.json, theme init, fuentes (OFL), logo
• references/audio.md: bases, música con licencia, mapa de efectos de sonido, objetivos de sonoridad
• references/capture.md: captura nativa de macOS, importación web-video, estructura de tomas
• references/pitfalls.md: todo lo que salió mal en proyectos reales y la solución
• references/privacy.md: reglas de datos y uso compartido