Communitygithub.com

barefootford/buttercut

Procedimiento interno (no es un punto de entrada independiente): el pipeline compartido de análisis de metraje que produce transcripciones de audio, hojas de contacto y resúmenes escritos por Sonnet. Se invoca de principio a fin mediante las habilidades process-library y reprocess-with-contact-sheets; no lo actives por tu cuenta.

¿Qué es buttercut?

Esta habilidad interna (`barefootford/buttercut`) es el núcleo del pipeline de análisis de metraje para agentes de IA como Claude Code, Cursor o Codex. No es un punto de entrada independiente, sino un subprocedimiento invocado por habilidades de nivel superior como `process-library`. Su función es procesar cada clip de vídeo de una biblioteca generando tres artefactos: una transcripción de audio (mediante WhisperX), una hoja de contacto (con ffmpeg) y un resumen en markdown redactado por el modelo Sonnet de Anthropic. El flujo comienza evitando que el ordenador entre en suspensión durante el procesamiento, luego ejecuta secuencialmente la transcripción y la generación de hojas de contacto (nunca en paralelo para evitar saturar la RAM), y opcionalmente refina las transcripciones con contexto del usuario. Finalmente, lanza múltiples subagentes Sonnet en lotes de 10 clips para redactar resúmenes visualmente detallados. Tras completar el análisis, mantiene una conversación con el usuario para confirmar la comprensión del metraje, actualizando los metadatos de la biblioteca. La habilidad también maneja imágenes fijas (que solo requieren resumen) y ofrece un mecanismo para detener el helper anti-sueño al finalizar.

Compatible con✓Claude Code~Codex CLI~Cursor
npx skills add https://github.com/barefootford/buttercut/tree/HEAD/skills/analyze-video

Preguntar en tu IA favorita

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

Documentación

Habilidad: Analizar Video (instrucciones principales)

Este es el manual del hilo principal para el paso de flujo de trabajo Analizar Video. Ejecútalo después de la configuración de la biblioteca, antes de cualquier trabajo de corte. Cubre los tres artefactos producidos por clip: transcripción de audio, hoja_contacto y resumen en markdown. El agente de corte preliminar lee el diálogo bajo demanda ejecutando script_extractor.rb sobre el JSON de la transcripción; no hay un artefacto de guión separado.

SKILL.md es el documento de instrucciones del hilo principal. La instrucción de trabajo del subagente reside en agent_prompt.md: incluye su contenido al lanzar un agente Task. No pases SKILL.md.

Terminología

  • De cara al usuario: llámalo "análisis de metraje" o "analizando metraje".
  • Interno/nombres de archivo: "transcripción" (campo transcript en library.yaml, etc.).

Prerrequisitos

  • La configuración de la biblioteca está completa (library.yaml existe, el esquema está actualizado; ejecuta las migraciones desde AGENTS.md si no es así).
  • Lee libraries/settings.yaml directamente para whisper_model. Para los campos de la biblioteca, lee la instantánea mediante ruby lib/buttercut/library.rb <nombre> summary y extrae los valores que necesites del JSON; no analices library.yaml directamente.

En este punto, crea una lista de tareas, visible para el usuario, con pasos de alto nivel y no técnicos para que puedan seguir el plan general de procesamiento de la biblioteca. Incluye pasos de cafeína solo si han optado por ello. Por ejemplo:

- [ ] Mantener el ordenador despierto
- [ ] Crear transcripciones (0/30)
- [ ] Analizar metraje (0/30)
- [ ] Dejar que el ordenador vuelva a dormir
- [ ] Revisar el metraje juntos

Estas tareas públicas se corresponden con los pasos siguientes: "Mantener el ordenador despierto" es el Paso 1 y "Dejar que el ordenador vuelva a dormir" es el Paso 6; "Crear transcripciones" cubre la ejecución mecánica del Paso 2 más el paso opcional de refinamiento del Paso 3 (avanza su contador desde las líneas de progreso [transcript …] del Paso 2; mantenlo en progreso durante el Paso 3 cuando el refinamiento esté activado); "Analizar metraje" sigue los resúmenes del Paso 4 (avanza su contador a medida que se resumen los clips, no después de las hojas de contacto); "Revisar el metraje juntos" es el Paso 5.

En el chat público, refiérete a estos pasos no técnicos. Mantén el trabajo técnico (WhisperX, generación de hojas de contacto, resúmenes Sonnet) entre bastidores.

Paso 1 — Evitar suspensión durante el procesamiento

Antes de comenzar el análisis, pregunta al usuario (mediante AskUserQuestion): "El procesamiento puede llevar un tiempo — ¿quieres que mantenga tu ordenador despierto hasta que termine?" Opciones: "Sí (Recomendado)" y "No".

Si es sí, inicia el helper antisupeño de la plataforma en segundo plano y almacena el PID; lo matarás en el Paso 6 una vez que el análisis haya terminado. (El respaldo lo maneja la habilidad invocadora — process-library — después de que esta habilidad finalice).

macOS:

caffeinate -i -w $$ &
KEEPAWAKE_PID=$!

Windows (Git Bash):

powershell -NoProfile -ExecutionPolicy Bypass -File scripts/keep_awake.ps1 &
KEEPAWAKE_PID=$!

Ambos evitan la suspensión por inactividad mientras se procesa el metraje (la pantalla puede apagarse, lo cual está bien).

Paso 2 — Procesar metraje (transcripciones, luego hojas de contacto)

(Si llegaste a esta habilidad directamente en lugar de a través de process-library, primero dile al usuario: "Encontrados [N] vídeos ([tamaño total]). Iniciando análisis de metraje...")

Son dos comandos mecánicos que ejecutas uno después del otro — primero las transcripciones, luego las hojas de contacto. No los ejecutes nunca a la vez: WhisperX consume mucha RAM, y superponerlos es lo que estamos evitando. No los implementes manualmente con subagentes; cada uno se ejecuta de forma idéntica cada vez, ~2 clips a la vez, registrando cada clip en library.yaml en el momento en que termina. Ambos son idempotentes — solo tocan los clips que aún carecen de ese artefacto — por lo que una re-ejecución solo completa lo que falta. Se ejecutarán en un servicio de trabajos similar a Sidekiq en miniatura. Ejecutarás el comando y luego vigilarás el archivo de registro que se devolverá para seguir el progreso.

Paso 2a — Transcripciones. Si usas Claude Code, ejecuta con run_in_background: true en la herramienta Bash. De lo contrario, usa la herramienta/argumento correcto para ejecutar en segundo plano.

ruby lib/buttercut/process_footage.rb transcripts <nombre-biblioteca>

Inmediatamente después de lanzarlo, configura un Monitor o equivalente en el archivo de registro para recibir una notificación por cada clip completado o fallido:

tail -f tmp/logs/processing/<nombre-biblioteca>/$(date +%Y-%m-%d).log | grep --line-buffered -E "TranscribeJob  (done|error)|transcript: [0-9]+/[0-9]+|Error|error:|failed|Traceback"
ruby lib/buttercut/library.rb <nombre> pending transcript   # lista JSON; hecho = N − su longitud

Actualiza "Crear transcripciones 5/20", es decir, número_de_clips_completados/total_de_clips a medida que los clips terminan para que el usuario pueda ver el progreso. Cuando la tarea en segundo plano se completa, sale con código distinto de cero si algún clip falló. En caso de fallo, vuelve a ejecutarlo una vez. Si vuelve a fallar, investiga y luego crea una solución para manejarlo elegantemente o informa al usuario sobre el problema con el clip y potencialmente elimínalo de la biblioteca.

Espera a que 2a termine antes de comenzar 2b.

Paso 2b — Hojas de contacto. Una vez que las transcripciones estén listas, construye las hojas (un pase rápido de ffmpeg — en primer plano está bien):

ruby lib/buttercut/process_footage.rb contact-sheets <nombre-biblioteca>

Las hojas de contacto permanecen entre bastidores — no las muestres como un contador público. Marca "Crear transcripciones" como completado una vez que 2a haya terminado y cualquier refinamiento (Paso 3) esté completo.

Ajuste (opcional): ambos pasos leen parallel_jobs de libraries/settings.yaml (por defecto 2); sobrescribe para una ejecución con --jobs N. Cada uno escribe un registro con marca de tiempo en tmp/logs/processing/<biblioteca>/ para su revisión posterior.

Re-procesamiento. Cada paso omite los clips que ya tienen su artefacto. Para rehacer uno — por ejemplo, una transcripción que malinterpretó un nombre — vuelve a ejecutar ese paso con --force --clips NOMBRE.mov. --force solo reconstruye cada clip.

Paso 3 — Refinar transcripciones (juicio — solo si transcript_refinement: true)

El refinamiento es la única parte de la transcripción que es un juicio — corregir nombres propios malinterpretados del contexto de la biblioteca — por lo que sigue siendo un paso del modelo, ejecutado después del pase mecánico. Omitir todo este paso si el transcript_refinement de la biblioteca es false.

Cuando es true, despacha subagentes de refinamiento (2-4 en paralelo, rotativos) sobre las transcripciones que el Paso 2a acaba de escribir. Incluye skills/transcribe-audio/refine_instructions.md como la instrucción de cada subagente y pasa, en línea:

  • transcript_path — ruta absoluta al JSON de la transcripción del clip en libraries/<biblioteca>/transcripts/
  • user_context y footage_summary — valores actuales de ruby lib/buttercut/library.rb <nombre> summary (las cadenas vacías están bien; el refinamiento aún detecta correcciones de tokens sin sentido y auto-referencias)

Los subagentes editan el JSON de la transcripción in situ y devuelven una lista corta de correcciones. NO tocan library.yaml — el Paso 2a ya estableció el campo transcript. Marca la tarea pública "Crear transcripciones" como completada una vez que el refinamiento termine.

Paso 4 — Resúmenes (subagentes Sonnet, por lotes, rotativos)

Despacha subagentes analyze-video en el modelo Sonnet. Sonnet lee la hoja de contacto con una especificidad visual notablemente mayor que Haiku (capta ropa, arquitectura, encuadre de cámara) — vale la pena ya que los resúmenes alimentan cada decisión de corte posterior.

Lote de 10 clips por subagente, hasta 10 subagentes en paralelo, con despacho rotativo. Cada subagente procesa sus 10 clips secuencialmente; el agrupamiento amortiza la sobrecarga de ~5–10s por agente. Para una biblioteca de 93 clips, eso es ~10 subagentes en total en lugar de 93. Inicia el siguiente subagente tan pronto como uno regrese — no esperes a que termine toda la tanda de 10, o perderás ~30% del tiempo de pared al agente más lento de la tanda.

Para cada subagente, pasa una lista de 10 registros de clip en línea. Cada registro de clip necesita:

  • video_filename — nombre base del vídeo (usado en el encabezado del resumen y la línea de respuesta)
  • duration — cadena de duración de library.yaml (ej. 00:01:19); el agente lo renderiza en el encabezado del resumen
  • contact_sheet_path — ruta absoluta al _full.jpg (del paso 2)
  • transcript_path — ruta absoluta al JSON de la transcripción de audio (del paso 2); el subagente extrae el diálogo bajo demanda mediante script_extractor.rb
  • summary_output_path — ruta absoluta donde el agente debe escribir el resumen en markdown. No construyas este nombre de archivo manualmente; pregunta a la biblioteca por la ruta canónica: ruby lib/buttercut/library.rb <nombre> field_path summary <clip> (maneja la convención summaries/summary_<clip>.md por ti, con o sin la extensión de archivo)

A medida que cada subagente devuelve su lote, actualiza library.yaml con summary para cada clip de ese lote:

ruby lib/buttercut/library.rb <nombre> complete summary <archivo> [<archivo>...]

El campo contact_sheet ya se pobló en el paso 2, por lo que el retorno del subagente solo contribuye con resúmenes.

Si un subagente devuelve resúmenes en línea en lugar de escribirlos en disco (a veces Sonnet alucina que "la herramienta Write está bloqueada" y vuelca el markdown en su respuesta), no reintentes ciegamente — simplemente extrae cada resumen de la respuesta del agente y Write (escribe) en el summary_output_path correspondiente desde el hilo principal. Luego ejecuta el comando complete summary como de costumbre. Más rápido que redespachar, y el contenido ya está ahí.

(Las hojas de contacto por segmento generadas para clips largos viven junto a la hoja _full en disco y son descubribles por convención — no están listadas en library.yaml).

No avances hasta que los resúmenes estén completos. Avanza el contador "Analizar metraje" a medida que se resumen los clips; márcalo como completado cuando termine.

Imágenes. Las imágenes fijas omiten los Pasos 2–3 por completo (sin audio que transcribir, sin hoja de contacto que construir) — un summary es el único artefacto que necesitan, y aparecen en ruby lib/buttercut/library.rb <nombre> pending summary junto a los vídeos. La imagen es lo que hay que mirar, así que resúmela directamente: lee el archivo de imagen (es pequeño) desde el hilo principal o un subagente Sonnet y escribe una descripción de 3–4 frases — sujetos, entorno, composición, cualquier texto en la imagen — en la ruta canónica de ruby lib/buttercut/library.rb <nombre> field_path summary <nombre-imagen>. Ten en cuenta que las claves de clips de imagen incluyen la extensión (title-card.png → summaries/summary_title-card_png.md), que field_path maneja por ti. Luego regístralo de la misma manera: ruby lib/buttercut/library.rb <nombre> complete summary <nombre-imagen>.

Paso 5 — Confirmar la comprensión del metraje con el usuario

(Esta es la tarea "Revisar el metraje juntos"). Una vez que cada resumen esté escrito, habla sobre lo que realmente muestra el metraje — confirma nombres de personajes, ubicaciones, el hilo narrativo, cualquier clip fuera de lugar o fuera de tema, y la intención creativa del usuario para esta biblioteca. Usa una conversación natural; solo recurre a AskUserQuestion cuando ofrezcas una elección discreta. A medida que aprendas cosas, actualiza:

  • footage_summary y user_context mediante ruby lib/buttercut/library.rb <nombre> update_metadata footage_summary "..." (y lo mismo con user_context)
  • archivos summary_*.md individuales cuando un resumen etiquete mal a alguien o se pierda un detalle clave (ej., "un hombre con chaqueta color canela" → el nombre del usuario)

Este es el único lugar para hacer este pase exhaustivo. Cada planificación posterior de corte preliminar hereda el contexto resultante en lugar de volver a interrogar la biblioteca.

Paso 6 — Detener el helper antisupeño

Si iniciaste uno en el Paso 1, mátalo ahora (ambas plataformas):

kill $KEEPAWAKE_PID 2>/dev/null

Patrón de subagentes paralelos (referencia)

Usado en los pasos 3 y 4.

Responsabilidades del agente principal:

  • Leer library.yaml y settings.yaml una vez para recopilar todos los valores necesarios para los subagentes.
  • Lanzar agentes Task pasando todos los valores necesarios en línea en la instrucción.
  • Actualizar library.yaml secuencialmente a medida que los agentes se completan (a través de la API Library — consulta AGENTS.md).
  • Manejar errores y reintentos.

Responsabilidades del agente hijo:

  • Procesar el/los clips asignados usando solo las entradas pasadas en línea por el principal.
  • Refinar un JSON de transcripción in situ (refinamiento) o leer la hoja de contacto pregenerada, extraer el diálogo de la transcripción mediante script_extractor.rb, y escribir el resumen en markdown en una sola llamada Write (analyze-video). (WhisperX ya no es un subagente — process_footage.rb transcripts lo ejecuta en el Paso 2a).
  • Devolver una respuesta estructurada corta con las rutas de archivo.

El agent_prompt.md de cada habilidad documenta su propio contrato de E/S — incluyendo si el subagente lee o escribe en library.yaml. (Spoiler: nunca escribe en library.yaml. Solo el principal escribe, a través de la API Library).

Si el usuario solicita un corte preliminar antes de que el análisis esté completo

Advierte: "Puedo crear un corte preliminar ahora, pero lo haré mejor después de analizar todo el metraje. ¿Continuar de todas formas?" Si el usuario confirma, procede. De lo contrario, espera a que el análisis se complete.

Skills relacionados