Communitygithub.com

daniel-video-annotate

Convierte una grabación de pantalla en una versión explicada eliminando las pausas estáticas, pausando en cada acción clave, resaltando el control y añadiendo subtítulos que indican qué se hace y por qué.

¿Qué es daniel-video-annotate?

Esta habilidad transforma una grabación de pantalla en un video explicado y anotado. Su propósito es ayudar a desarrolladores y usuarios técnicos a documentar visualmente procesos, tickets o merge requests, ofreciendo una versión recortada y otra comentada del video original. Funciona eliminando tramos estáticos prolongados (manteniendo el primer segundo de cada pausa), luego el usuario selecciona los momentos clave (cada acción deliberada como un clic, cambio de valor o resultado relevante) y la herramienta dibuja un recuadro alrededor del control correspondiente, oscurece el resto de la pantalla y muestra un subtítulo explicativo (máximo ~180 caracteres). Compatible con cualquier sistema que tenga ffmpeg, ffprobe y Python estándar; no requiere dependencias externas. El flujo incluye pasos para elegir la velocidad de lectura, generar hojas de contacto para inspeccionar fotogramas, escribir el archivo de especificaciones JSON con coordenadas y subtítulos, renderizar el video final y verificar cada pausa automáticamente. El resultado se entrega como `<nombre>-explained.mp4` junto al archivo recortado `<nombre>-trimmed.mp4`, sin modificar el original. La herramienta también ofrece opciones de posición del subtítulo (superior o inferior) y tolerancia de ruido para el recorte.

Compatible con✓Claude Code~Codex CLI✓Cursor
npx skills add https://github.com/dancodes/skills-agents/tree/HEAD/skills/daniel-video-annotate

Preguntar en tu IA favorita

Abre un nuevo chat con esta habilidad de agente ya precargada.

Documentación

/daniel-video-annotate

Entrada: un archivo de video, más lo que explique por qué se da cada paso (un ticket, una solicitud de fusión, el mensaje del usuario). Salida, junto a la entrada: <nombre>-trimmed.mp4 y <nombre>-explained.mp4. El archivo de entrada nunca se modifica.

El video explicado reproduce la grabación, y en cada pausa mantiene un fotograma durante el tiempo de retención, oscurece la pantalla alrededor de un control resaltado, y muestra un subtítulo de una oración en una barra negra debajo o encima de la grabación. La barra hace que el video sea más alto, por lo que la grabación nunca queda cubierta.

annotate.py se encuentra junto a este archivo. En los comandos siguientes, A representa python3 "${CLAUDE_CONFIG_DIR:-$HOME/.claude}/skills/daniel-video-annotate/annotate.py". Solo necesita ffmpeg, ffprobe y la biblioteca estándar de Python. <trabajo> es una carpeta temporal: el bloc de notas de la sesión cuando exista, de lo contrario ${TMPDIR:-/tmp}/video-annotate/<nombre>/.

Si el video está en la VM de desarrollo, cópielo primero con dvm get <ruta remota> <directorio local>.

0. Elegir la velocidad de lectura

La retención es cuánto tiempo permanece legible cada subtítulo en pantalla. Cada pausa dura 1.5 s más el tiempo para leer su subtítulo a la velocidad de lectura, y al menos 2.5 s. Usa la velocidad en palabras por minuto que el usuario haya indicado; si no, 350 ppm. No preguntes. Cuando el usuario haya dado una retención fija en segundos, úsala para cada pausa.

Terminado cuando tengas una velocidad de lectura o una retención fija.

1. Recortar las pausas

A trim <video> <nombre>-trimmed.mp4

Encuentra cada tramo donde la imagen permanece quieta durante 1.5 s o más, conserva el primer segundo de cada uno y recorta el resto. Imprime el número de tramos y la duración antes y después. Omite este paso cuando el usuario quiera mantener las pausas y usa el original como <recortado> a continuación.

Cada tiempo en los pasos posteriores es un tiempo en `. Recortar de nuevo mueve cada tiempo, por lo que debes repetir los pasos 2 a 6 después de cualquier nuevo recorte.

2. Conocer la historia

A sheets <recortado> <trabajo>/sheets

Escribe hojas de contacto de seis fotogramas cada una, un fotograma por segundo, con la hora exacta marcada en cada fotograma. Lee cada hoja. Lee el ticket u otra fuente para conocer la razón detrás de cada paso.

Terminado cuando puedas decir, en orden, qué hace la persona en pantalla, qué valor establece cada acción, y qué resultado demuestra el objetivo de la grabación.

3. Elegir las pausas

Pausa una vez por cada elección (un valor seleccionado, un botón presionado, una página abierta intencionalmente) y una vez por cada resultado que demuestre el objetivo. Omite la navegación que no implique una decisión.

Para cada pausa, encuentra el fotograma y el recuadro:

A frames <recortado> <trabajo>/frames 23.0 23.2 23.4 23.6

Escribe un PNG de tamaño completo por cada instante, nombrado por su hora exacta, con una cuadrícula roja cada 100 px y las coordenadas de píxeles etiquetadas a lo largo del borde superior e izquierdo.

  • Elige un fotograma estable. Las grabaciones contienen fotogramas a medio renderizar, como un panel que está en blanco durante unos fotogramas después de un clic. Avanza de 0.2 s en 0.2 s hasta que el control y su entorno estén completamente dibujados.
  • Para una elección de una lista, prefiere el fotograma donde la lista esté abierta y el cursor esté sobre la opción. Si ese fotograma está a medio renderizar, usa el fotograma justo después, donde el campo muestre el nuevo valor.
  • Lee el recuadro como [x, y, ancho, alto] a partir de las etiquetas de la cuadrícula, en píxeles de origen. La herramienta Leer reduce las imágenes grandes, por lo que las posiciones medidas en la imagen mostrada son incorrectas; las etiquetas siguen siendo correctas.
  • Enmarca el control único del que habla el subtítulo, con unos pocos píxeles de margen. Una pausa puede omitir el recuadro, y entonces no se oscurece nada.

Terminado cuando cada pausa tenga una hora cuyo fotograma hayas mirado, y un recuadro leído de ese mismo fotograma.

4. Escribir los subtítulos

Una oración por pausa. Indica qué hacemos y por qué, o qué muestra ahora la pantalla y por qué. Nombra la cosa concreta: la fila, el campo, el valor antiguo y el nuevo valor.

Toma el "por qué" de la fuente. Cuando la fuente no dé la razón de un paso, escribe lo que sea visible, y enumera ese subtítulo como inferido en el informe. Aplica la habilidad writing-tics a los subtítulos. Mantén cada uno por debajo de aproximadamente 180 caracteres, porque la barra es tan alta como el subtítulo más largo.

5. Renderizar

Escribe <trabajo>/spec.json, una lista en orden de tiempo:

[
  {"at": 12.0, "box": [399, 569, 180, 29], "caption": "Cambiamos el Tamaño del Elemento 1 de M a L en la tabla, lo que guarda L en el servidor."},
  {"at": 23.6, "box": [659, 500, 192, 24], "caption": "..."}
]

at está en segundos dentro de <recortado>. Luego establece hold` en cada pausa:

A holds <trabajo>/spec.json [--wpm <velocidad>]

Escribe la retención de cada pausa en la especificación y la imprime junto al recuento de palabras. Con una retención fija, establece hold en cada pausa tú mismo. Una pausa sin hold dura 6 segundos.

A annotate <recortado> <trabajo>/spec.json <nombre>-explained.mp4 [--position top|bottom] [--clearance <líneas>]

La barra de subtítulos va donde el usuario haya solicitado. Si no hay solicitud, va en la parte inferior.

  • --position bottom es el valor por defecto. Los reproductores de video dibujan sus controles sobre el borde inferior, por lo que la barra tiene espacio vacío debajo del subtítulo: --clearance líneas de ese espacio, 3 por defecto, lo que limpia los controles de un reproductor pequeño incrustado.
  • --position top coloca la barra encima de la grabación, donde ningún reproductor dibuja controles. No necesita espacio de separación.

Los recuadros permanecen en las coordenadas de <recortado> para ambas posiciones.

6. Verificar cada pausa

A check <nombre>-explained.mp4 <trabajo>/spec.json <trabajo>/check

Escribe un fotograma de la mitad de cada pausa. Lee cada uno. El recuadro debe estar sobre el control, el subtítulo debe estar completo y no cortado en el borde derecho, y el fotograma debe ser el estable que elegiste. Corrige la especificación y renderiza de nuevo hasta que cada pausa pase la verificación.

7. Informe

Indica la ruta, el tamaño y la duración del video explicado, luego los subtítulos en orden, cada uno con el control que recuadra. Menciona qué subtítulos son inferidos. Indica que verificaste un fotograma por pausa y que no viste la reproducción completa.

Límites

  • La salida no tiene audio. Informa al usuario cuando la entrada tuviera una pista de voz.
  • La velocidad de fotogramas es la velocidad media de la entrada, redondeada y mantenida entre 5 y 30 fotogramas por segundo.
  • trim solo corta una imagen que esté completamente quieta. Un spinner, una barra de progreso, un cursor parpadeante o un reloj mantienen la imagen en movimiento, por lo que esas pausas permanecen. Una pausa rota por un pequeño cambio se mantiene como varias piezas de un segundo.
  • trim solo corta fotogramas dentro de un tramo de quietud, y conserva el primer fotograma de cada cambio. Un cambio menor que la tolerancia --noise (por defecto 0.003), como un solo carácter pequeño, cuenta como quieto y puede ser cortado. El paso 2 es la verificación: cada acción debe aparecer en las hojas. Reduce --noise a 0.001 cuando falte una.

Errores

Lo que vesCausaSolución
this ffmpeg build has no drawtext filterffmpeg se compiló sin libfreetypeInstala una compilación completa, por ejemplo brew install ffmpeg
no font file foundNo existe ninguna de las rutas de fuentes conocidas de macOS o LinuxPasa --font /ruta/a/fuente.ttf a sheets, frames y annotate
Unrecognized option 'fps_mode'ffmpeg es anterior a 5.1Actualiza ffmpeg
no still stretches found, nothing writtenLa imagen nunca permanece quieta durante 1.5 sUsa el original como <recortado>, o reduce --min-freeze
El video recortado aún se siente lentoLas pausas animadas se conservaron, o un segundo por tramo de quietud se acumulaReduce --keep a 0.5
El video recortado salta demasiado rápido para seguirUn segundo por pantalla es demasiado corto para esta grabaciónAumenta --keep a 2 y --min-freeze a 3
pause N at Ts is past the end of the videoLos tiempos provenían del original y no de <recortado>Lee los tiempos de nuevo de sheets y frames de <recortado>
pause N box ... is outside the frame, o el recuadro falla el control en checkEl recuadro se midió en una imagen reducidaLée las etiquetas de la cuadrícula del PNG de frames
El subtítulo se corta en el borde derechoLa fuente es más ancha de lo que supone el scriptPasa --wrap 80, o un número más bajo, a annotate
Los controles del reproductor cubren el subtítuloEl espacio debajo del subtítulo es más corto que los controlesAumenta --clearance a 5, o pasa --position top
pause N would sit at ..., past the endA check se le dio el video recortadoDale el video explicado
Cualquier otro ffmpeg failedDesconocidoEjecuta A selftest. Recorta y anota un clip generado, por lo que si pasa significa que ffmpeg funciona y que la entrada o la especificación tienen la culpa
dvm get --help falla con un error de scpdvm get pasa cada argumento a scpEjecuta dvm help

macOS no tiene el comando timeout. Un video de 720p de un minuto se renderiza en unos segundos, así que ejecuta los comandos de forma directa.

Skills relacionados