/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 bottomes 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:--clearancelíneas de ese espacio, 3 por defecto, lo que limpia los controles de un reproductor pequeño incrustado.--position topcoloca 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.
trimsolo 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.trimsolo 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--noisea 0.001 cuando falte una.
Errores
| Lo que ves | Causa | Solución |
|---|---|---|
this ffmpeg build has no drawtext filter | ffmpeg se compiló sin libfreetype | Instala una compilación completa, por ejemplo brew install ffmpeg |
no font file found | No existe ninguna de las rutas de fuentes conocidas de macOS o Linux | Pasa --font /ruta/a/fuente.ttf a sheets, frames y annotate |
Unrecognized option 'fps_mode' | ffmpeg es anterior a 5.1 | Actualiza ffmpeg |
no still stretches found, nothing written | La imagen nunca permanece quieta durante 1.5 s | Usa el original como <recortado>, o reduce --min-freeze |
| El video recortado aún se siente lento | Las pausas animadas se conservaron, o un segundo por tramo de quietud se acumula | Reduce --keep a 0.5 |
| El video recortado salta demasiado rápido para seguir | Un segundo por pantalla es demasiado corto para esta grabación | Aumenta --keep a 2 y --min-freeze a 3 |
pause N at Ts is past the end of the video | Los 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 check | El recuadro se midió en una imagen reducida | Lée las etiquetas de la cuadrícula del PNG de frames |
| El subtítulo se corta en el borde derecho | La fuente es más ancha de lo que supone el script | Pasa --wrap 80, o un número más bajo, a annotate |
| Los controles del reproductor cubren el subtítulo | El espacio debajo del subtítulo es más corto que los controles | Aumenta --clearance a 5, o pasa --position top |
pause N would sit at ..., past the end | A check se le dio el video recortado | Dale el video explicado |
Cualquier otro ffmpeg failed | Desconocido | Ejecuta 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 scp | dvm get pasa cada argumento a scp | Ejecuta 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.