Estudio de Video Tutorial Automatizado
Dada una dirección web o un nombre de software, y un esquema aproximado de capítulos, este skill se encarga de:
Operar la aplicación real → Notificar al usuario para grabar → Importar el material grabado → Construir un índice de búsqueda → Sincronizar cada frase con la toma → Añadir animaciones y transiciones → Verificar fotograma a fotograma → Exportar el video final
División del trabajo: qué hace el skill y qué hace el usuario
| Quién lo hace | Descripción | |
|---|---|---|
| Grabar la pantalla | Usuario | El usuario graba con herramientas externas como OBS / ShareX / grabador de pantalla del sistema. El skill no graba la pantalla. La grabación externa conserva la resolución y claridad originales, y también puede capturar el audio del sistema. |
| Operar la aplicación real | Skill | El skill completa cada paso usando CDP del navegador o automatización de ventanas, y registra la posición de la operación. |
| Edición, locución, animaciones, verificación | Skill | Todo automatizado, con compuertas de control. |
| Ingresar el material | Usuario | Después de la operación, el usuario entrega el video grabado al skill (solo la ruta del archivo). |
El skill no ocupa el ratón físico del usuario: las operaciones del navegador se realizan mediante clics en elementos CDP, sin mover el puntero real.
Siete reglas de oro
- La captura es responsabilidad del usuario, el skill no graba la pantalla. El skill solo se encarga de la operación y la postproducción. El usuario debe entregar el archivo grabado al skill.
- La operación es responsabilidad del skill, la ventana de grabación es responsabilidad del usuario. El skill solo actúa después de que el usuario anuncie "iniciar grabación", y notifica al usuario que detenga la grabación inmediatamente después de terminar la operación.
- No debe haber consolas en la pantalla durante la grabación. Cada comando del skill debe ejecutarse sin ventana,
y debe activar
guardpara ocultar inmediatamente cualquier consola o superposición que aparezca — todo eso se grabaría. - Solo ocultar ventanas, no cerrarlas. Usar
SW_HIDE, yguard stoppara restaurarlas todas. - Cada toma debe estar vinculada a una frase de la locución. En
plan.json, cada beat declara a qué frase de la locución sirve. La duración total del capítulo debe ser igual a la duración total de la locución de ese capítulo. - Los números pronunciados deben leerse de la interfaz real. El número de vértices, el precio, el número de versión, todo debe basarse en la interfaz.
- La auditoría de oclusión es una compuerta, no un informe. Antes de la construcción, se realiza OCR fotograma a fotograma de la ventana de salida. Si se detectan consolas / notificaciones / pantallas de inicio, se rechaza la salida. La música de fondo debe ceder paso a la voz humana. El video final debe tener −16 LUFS y un pico real ≤ −1.5 dBFS.
Fase 0 · Inicio del proyecto
Confirmar tres cosas, imprescindibles:
- Objetivo: dirección web o nombre del software de escritorio, versión.
- Esquema: orden de los capítulos (el usuario proporciona uno aproximado, el skill lo completa).
- Plan de grabación: qué herramienta de grabación de pantalla usa el usuario, qué monitor graba, si graba audio del sistema, formato de salida y resolución.
También determinar el alcance de la captura (pantalla completa o una ventana específica) y si se grabará por segmentos. Grabar por segmentos, una función por vez, es más fácil de mantener; grabar todo el flujo de una vez también es posible, apoyándose en el índice para localizar.
Fase 1 · Redacción del guion
build/script.md, cada capítulo con un título ## , formato ## <ID del capítulo> | <Título a mostrar>:
## ch00 | Introducción
Primero, mira lo que he creado.
Esta figura se generó a partir de una imagen.
## ch01 | Registro e inicio de sesión
El sitio web oficial es hi3d.ai, ábrelo en el navegador y ya puedes usarlo.
- ID del capítulo: solo caracteres en minúsculas, números, guiones bajos y guiones (requisito de la lista de TTS). Debe coincidir exactamente con el
iddel capítulo enplan.json. Los segmentos múltiples del mismo capítulo se generan automáticamente comoch01,ch01_1,ch01_2. - Título a mostrar: para la tarjeta del capítulo, puede estar en español.
- Los ID de los capítulos no deben ser prefijos entre sí (
ch0ych01pueden confundirse). Se recomienda usar uniformementechNN. - Comienza con el resultado final (la imagen más reconocible), luego vuelve a la operación.
- Las funciones secundarias se mencionan brevemente. El espacio se dedica a "los parámetros que determinan el resultado" y "cómo verificar que se hizo correctamente".
- Los prompts, código y configuraciones se guardan en bloques de código con ``` — los bloques de código no se leerán en voz alta, solo sirven como imagen de pantalla.
- Cada segmento de locución debe tener una imagen de pantalla real correspondiente; los párrafos sin imagen de pantalla por el momento deben reescribirse como frases que la imagen pueda probar.
Fase 2 · Locución
python scripts/studio.py voice --project <proyecto>
Se divide por capítulos ## <ID del capítulo> | <Título>, se separan por líneas en blanco, se omiten los bloques de código y las notas >, y se produce build/audio_map.json, cada segmento con su duración real medida.
Presta atención a chars/s en la salida: los segmentos por debajo de 3.0 son anomalías de TTS (una síntesis que se alargó). Reescíbelo y regenéralo, no lo lleves a la edición.
Fase 3 · Operación real y grabación externa ★
Este es el núcleo del skill.
3.1 Preparar el entorno de grabación
python scripts/studio.py windows # Encontrar la ventana objetivo
python scripts/studio.py prep --project <proyecto> \
--keep-title "Chrome" --maximize-title "Chrome" # Ocultar ventanas irrelevantes, maximizar la ventana objetivo
prep nunca oculta la propia terminal del skill (se excluye por PID ancestro).
3.2 Iniciar el guardián de pantalla ★
Este paso no se puede omitir. El skill ejecutará comandos (ffmpeg, ffprobe, subprocesos de Python) durante la operación, cada uno de los cuales puede abrir una ventana de consola que caería justo en la pantalla de captura del usuario y se grabaría.
python scripts/studio.py guard start --project <proyecto> \
--protect "DeepSeek Harness" --protect "Chrome"
El guardián es un proceso de fondo independiente que escanea la lista de ventanas cada 0.25 segundos, y oculta inmediatamente (SW_HIDE) las ventanas de consola recién aparecidas
(ConsoleWindowClass, cmd, PowerShell, terminal, xshell, etc.) y las superposiciones de entrada / notificación.
Recuerda qué ventanas ha ocultado y las restaura tal cual al ejecutar guard stop.
--protectprotege los programas que se están demostrando (coincide por título, obligatorio).- Por defecto, solo oculta las ventanas de consola del propio árbol de procesos del skill, no las GUI — la interfaz de sesión del usuario permanece visible.
- Si es necesario ocultar también la GUI, añade
--hide-own-gui. - El criterio del guardián es "superposición real": las ventanas que solo se superponen unos pocos píxeles en el área de captura (en otro monitor) no se ocultan por error.
3.3 Notificar al usuario para comenzar
Indica claramente al usuario: Por favor, comienza la grabación. Cuando termines, responde "grabado". No actúes antes de que el usuario confirme — de lo contrario, esta preparación se grabará.
3.4 Realizar la operación real
Opera en orden de capítulos, cada paso:
- Navegador: usar CDP para hacer clic en elementos, sin mover el ratón real.
Antes de hacer clic, registra las coordenadas para usarlas después en las anotaciones:
python scripts/studio.py aim <proyecto> <x> <y> --note "Formato de exportación". - Software de escritorio: activar la ventana + priorizar el teclado; si es necesario hacer clic, usar el ratón real, pero advertir al usuario que no mueva el ratón durante la grabación.
- Si es necesario confirmar el estado, no es necesario interrumpir al usuario — captura un fotograma y míralo:
python scripts/studio.py shot --out <proyecto>/build/check.png
- Inicio de sesión, autorización, código de verificación: mantén la grabación, el usuario los completa por sí mismo. El skill solo confirma si la operación fue exitosa. Corta las credenciales, códigos de verificación y claves — puedes grabar en segmentos antes y después del inicio de sesión, y luego unirlos según el orden de dependencia.
- Cada comando del skill debe ejecutarse sin ventana:
scripts/h.ps1inicia subprocesos conCreateNoWindow, y los subprocesos internos del skill siempre llevanCREATE_NO_WINDOW.
3.5 Notificar al usuario para detener
Después de completar todas las operaciones, dile inmediatamente al usuario: Operación terminada. Por favor, detén la grabación y dame la ruta del archivo de video. Espera a que el usuario devuelva la ruta. No busques ni elimines ningún archivo de grabación por tu cuenta.
3.6 Finalización
python scripts/studio.py guard stop --project <proyecto> # Detener el guardián y restaurar ventanas
python scripts/studio.py guard status --project <proyecto> # Confirmar que no quedan consolas en la pantalla de captura
guard status lista las ventanas de consola aún visibles en el área de captura — debe estar vacío para considerarse limpio.
Si hay residuos, significa que algún programa está abriendo ventanas repetidamente. Haz que el usuario regrabe ese segmento.
Fase 4 · Importar material y construir índice
python scripts/studio.py import --project <proyecto> --file "D:\video\rec.mp4"
python scripts/studio.py index --project <proyecto> --clip rec.mp4 --step 2
index escanea todo el video grabado con un paso fijo, realiza OCR fotograma a fotograma y registra:
- Qué texto hay en la pantalla en cada momento (para saber qué está pasando en un segundo determinado);
- Puntos de cambio visual (puntos de corte naturales);
- Intervalos de contaminación (consolas / burbujas de notificación / pantallas de inicio, que deben evitarse).
Produce build/index_<nombre>.txt (búsqueda directa) y .json (estructurado).
Antes de organizar las tomas, lee primero el índice. No adivines los códigos de tiempo basándote en la memoria.
Fase 5 · Organizar tomas
build/plan.json:
{
"display": {"region": [0, 0, 1920, 1080]},
"voice": {"voice": "es-ES-ElviraNeural", "rate": "+5%"},
"chapters": [
{
"id": "ch02", "num": "02", "title": "Generación de imagen a partir de texto", "sub": "Prompt de tres partes, determina la fidelidad",
"beats": [
{"seg": 0, "src": "rec.mp4", "in": 120, "out": 134},
{"seg": 1, "src": "rec.mp4", "in": 136, "out": 152, "zoom": 1.0}
],
"callouts": [
{"seg": 1, "offset": 1.0, "text": "Prompt de tres partes\nPersonaje → Material → Composición",
"x": 120, "y": 680, "pointer": "up"}
]
}
]
}
srces el nombre del archivo enraw/(grabación del usuario importada porimport),in/outson segundos.seges a qué frase de la locución sirve esta toma, contado dentro del capítulo, comenzando desde 0.zoom> 1 hace un acercamiento (recorte estático ampliado).calloutsusaseg+offsetpara posicionar el momento de la anotación, siguiendo la locución;x/yes la posición de la anotación (se pueden usar las coordenadas registradas poraim).- El
iddel capítulo debe ser igual al ID del capítulo enscript.md, y también debe ser igual al prefijo del segmento enaudio_map.json. - Ver el ejemplo completo en
assets/plan.example.json.
Reglas para organizar tomas:
- Una toma sirve a un punto operativo clave. La duración de la toma está determinada por esa frase de la locución.
- El nombre debe aparecer antes o al mismo tiempo que el control correspondiente; al aparecer una retroalimentación clave, deja tiempo para leer.
- Los controles adyacentes deben compartir una sola toma cuando sea posible, no cambies con frecuencia.
- Comprime razonablemente las esperas reales, pero conserva el tiempo reconocible entre "activar acción → procesar retroalimentación".
- Los párrafos sin imagen de pantalla deben reescribirse como frases que la imagen pueda probar, o regrabarse.
- Evita los intervalos de contaminación marcados por el índice.
Fase 6 · Edición, verificación, entrega
python scripts/studio.py build --project <proyecto>
python scripts/studio.py verify --video <proyecto>/final.mp4 --expect-duration <duración total de la locución>
build hace automáticamente: sincronizar cada frase con su toma → tarjeta de título de capítulo → superposición de anotaciones → árbol de transiciones de disolución cruzada → reducción de volumen de la música de fondo mediante sidechain → normalización de sonoridad.
Música de fondo: coloca la música en build/bgm.wav (o build/bgm_final.wav), y el constructor calcula la curva de reducción de volumen según la envolvente de la voz humana y la mezcla.
Si no hay este archivo, se puede generar el video igual, pero sin música de fondo.
Cuando la auditoría falla: según el código de tiempo en build/audit.txt, cambia la ventana o regraba. Modifica plan.json y vuelve a ejecutar.
La práctica común es mover los in/out contaminados a un intervalo limpio, o pedir al usuario que regrabe ese segmento.
Autocomprobación antes de la entrega:
- El archivo se reproduce completamente, las pistas de video y audio están completas, la duración se aproxima a la duración total de la locución.
- Auditoría OCR fotograma a fotograma sin problemas.
- Mira y escucha todo el video a velocidad normal. Revisa los puntos clave: los primeros 3–10 segundos, cada cambio de función, envíos y resultados, números y nombres propios, segmentos de espera, y el final.
- Cada punto explicado tiene un punto de cursor correspondiente; no hay grandes fragmentos estáticos de imágenes, no hay pausas sin contenido, la música de fondo no tapa la voz humana.
Referencia rápida de comandos
studio init <proyecto> # Crear la estructura del proyecto
studio windows # Listar ventanas, buscar objetivo
studio prep --project <proyecto> --maximize-title "Chrome"
studio guard start --project <proyecto> --protect "Chrome" # ★ Mantener la pantalla de captura limpia durante la grabación
studio shot --out check.png # Capturar un fotograma para confirmar el estado
studio aim --project <proyecto> 1001 720 --note "Formato de exportación"
studio guard stop --project <proyecto> # Detener el guardián y restaurar ventanas
studio guard status --project <proyecto> # Confirmar que no hay consolas residuales
studio import --project <proyecto> --file rec.mp4
studio index --project <proyecto> --clip rec.mp4
studio voice --project <proyecto>
studio build --project <proyecto>
studio audit --project <proyecto>
studio verify --video final.mp4
studio status --project <proyecto>
Referencias
references/production.md— Detalles sobre grabación de pantalla, locución, edición, mezcla de audio y verificaciónreferences/troubleshooting.md— Síntomas → Causas raíz → Solucionesassets/plan.example.json— Ejemplo completo de un plan de tomas