Communitygithub.com

barefootford/buttercut

Procédure interne (non un point d'entrée autonome) — le pipeline partagé d'analyse de séquences qui produit des transcriptions audio, des planches-contacts et des résumés rédigés par Sonnet. Invoqué de bout en bout par les compétences process-library et reprocess-with-contact-sheets ; ne pas le lancer seul.

Qu'est-ce que buttercut ?

Cette compétence interne, `barefootford/buttercut`, implémente le pipeline complet d'analyse vidéo partagé par d'autres compétences de l'écosystème Buttercut. Elle n'est pas destinée à être invoquée directement, mais sert de sous-procédure pour `process-library` et `reprocess-with-contact-sheets`. Le pipeline produit trois artefacts par clip : une transcription audio via WhisperX, une planche-contact visuelle (contact sheet) via ffmpeg, et un résumé en markdown généré par Claude Sonnet. Conçue pour être robuste et reproductible, elle exécute les étapes de transcription et de planches-contacts de manière séquentielle pour éviter les problèmes de mémoire, chaque étape étant idempotente. Un raffinement optionnel des transcriptions est possible via des sous-agents si le paramètre `transcript_refinement` est activé. Les résumés sont produits par lots de 10 clips via des sous-agents utilisant Sonnet, qui analysent simultanément la planche-contact et la transcription. La compétence inclut également une étape de confirmation avec l'utilisateur pour valider la compréhension du contenu et met à jour les métadonnées de la bibliothèque en conséquence.

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

Demander à votre IA préférée

Ouvre une nouvelle conversation avec cette compétence d'agent déjà préchargée.

Documentation

Compétence : Analyser la Vidéo (brief parent)

Ceci est le playbook du thread principal pour l'étape du workflow Analyser la Vidéo. Exécutez-le après la configuration de la bibliothèque, avant tout travail de coupe. Il couvre les trois artefacts produits par clip : transcript audio, contact_sheet, et summary en markdown. L'agent de roughcut lit le dialogue à la demande en exécutant script_extractor.rb sur le JSON de transcription — pas d'artefact de script séparé.

SKILL.md est le brief de dispatch du parent. Le prompt de travail du sous-agent se trouve dans agent_prompt.md — incluez son contenu en ligne lors du lancement d'un agent Task. Ne passez pas SKILL.md.

Terminologie

  • Face à l'utilisateur : appelez-le "analyse des séquences" ou "analyser les séquences".
  • Noms internes/fichiers : "transcription" (champ transcript dans library.yaml, etc.).

Prérequis

  • La configuration de la bibliothèque est terminée (library.yaml existe, le schéma est à jour — exécutez les migrations depuis AGENTS.md si ce n'est pas le cas).
  • Lisez libraries/settings.yaml directement pour whisper_model. Pour les champs de la bibliothèque, lisez l'instantané via ruby lib/buttercut/library.rb <nom> summary et extrayez les valeurs dont vous avez besoin depuis le JSON — ne parsez pas library.yaml en ligne.

À ce stade, créez une liste de tâches, visible pour l'utilisateur, avec des étapes de haut niveau et non techniques afin qu'il puisse suivre le plan général de traitement de la bibliothèque. Incluez des étapes de caffeination uniquement s'il a opté pour. Par exemple :

- [ ] Garder l'ordinateur éveillé
- [ ] Créer les transcriptions (0/30)
- [ ] Analyser les séquences (0/30)
- [ ] Laisser l'ordinateur se rendormir
- [ ] Revoir les séquences ensemble

Ces tâches publiques correspondent aux étapes ci-dessous : "Garder l'ordinateur éveillé" correspond à l'Étape 1 et "Laisser l'ordinateur se rendormir" à l'Étape 6 ; "Créer les transcriptions" couvre l'exécution mécanique de l'Étape 2 plus le passage de raffinement optionnel de l'Étape 3 (avancez son compteur à partir des lignes de progression [transcript …] de l'Étape 2 ; maintenez-le en cours jusqu'à l'Étape 3 lorsque le raffinement est activé) ; "Analyser les séquences" suit les résumés de l'Étape 4 (avancez son compteur au fur et à mesure que les clips sont résumés, pas après les planches-contacts) ; "Revoir les séquences ensemble" correspond à l'Étape 5.

Dans le chat public, référez-vous à ces étapes non techniques. Gardez le travail technique (WhisperX, génération de planches-contacts, résumés Sonnet) en coulisses.

Étape 1 — Empêcher la mise en veille pendant le traitement

Avant de commencer l'analyse, demandez à l'utilisateur (via AskUserQuestion) : "Le traitement peut prendre un certain temps — voulez-vous que je garde votre ordinateur éveillé jusqu'à la fin ?" Options : "Oui (Recommandé)" et "Non".

Si oui, démarrez l'assistant de maintien en éveil de la plateforme en arrière-plan et stockez le PID — vous le tuerez à l'Étape 6 une fois l'analyse terminée. (La sauvegarde est gérée par la compétence appelante — process-library — après le retour de cette compétence.)

macOS :

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

Windows (Git Bash) :

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

Les deux empêchent la mise en veille pendant le traitement des séquences (l'écran peut encore s'éteindre, ce qui est acceptable).

Étape 2 — Traiter les séquences (transcriptions, puis planches-contacts)

(Si vous avez atteint cette compétence directement plutôt que via process-library, dites d'abord à l'utilisateur : "Trouvé [N] vidéos ([taille totale]). Démarrage de l'analyse des séquences...")

Ce sont deux commandes mécaniques que vous exécutez l'une après l'autre — les transcriptions d'abord, les planches-contacts ensuite. Ne les exécutez jamais en même temps : WhisperX est gourmand en RAM, et c'est ce chevauchement que nous évitons. Ne les faites pas vous-même avec des sous-agents ; chacune s'exécute à l'identique à chaque fois, ~2 clips à la fois, en enregistrant chaque clip dans library.yaml dès qu'il est terminé. Les deux sont idempotentes — elles ne touchent que les clips auxquels il manque encore cet artefact — donc une ré-exécution ne termine que ce qui reste. Elles s'exécuteront dans un service de tâches miniature de type Sidekiq. Vous exécuterez la commande, puis surveillerez le fichier journal qui sera renvoyé pour suivre la progression.

Étape 2a — Transcriptions. Si vous utilisez Claude Code, exécutez avec run_in_background: true sur l'outil Bash. Sinon, utilisez l'outil/l'argument correct pour exécuter en arrière-plan.

ruby lib/buttercut/process_footage.rb transcripts <nom-bibliothèque>

Immédiatement après le lancement, configurez un Monitor ou équivalent sur le fichier journal pour recevoir une notification pour chaque clip terminé ou en échec :

tail -f tmp/logs/processing/<nom-bibliothèque>/$(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 <nom> pending transcript   # Liste JSON ; fait = N − sa longueur

Mettez à jour "Créer les transcriptions 5/20", c'est-à-dire nombre_de_clips_terminés/nombre_total_de_clips, au fur et à mesure que les clips se terminent afin que l'utilisateur puisse voir la progression. Lorsque la tâche en arrière-plan se termine, elle sort avec un code non nul si un clip a échoué. En cas d'échec, ré-exécutez une fois. Si elle échoue à nouveau, enquêtez puis soit créez un correctif pour gérer le problème élégamment, soit informez l'utilisateur du problème avec le clip et retirez-le potentiellement de la bibliothèque.

Attendez la fin de l'étape 2a avant de commencer l'étape 2b.

Étape 2b — Planches-contacts. Une fois les transcriptions terminées, construisez les planches (un passage rapide ffmpeg — au premier plan, c'est acceptable) :

ruby lib/buttercut/process_footage.rb contact-sheets <nom-bibliothèque>

Les planches-contacts restent en coulisses — ne les présentez pas comme un compteur public. Marquez "Créer les transcriptions" comme terminé une fois l'étape 2a finie et tout raffinement (Étape 3) achevé.

Réglage (optionnel) : les deux étapes lisent parallel_jobs depuis libraries/settings.yaml (valeur par défaut 2) ; remplacez pour une exécution avec --jobs N. Chacune écrit un journal horodaté sous tmp/logs/processing/<bibliothèque>/ pour une révision ultérieure.

Retraitement. Chaque étape ignore les clips qui possèdent déjà son artefact. Pour en refaire un — par exemple une transcription qui a mal compris un nom — ré-exécutez cette étape avec --force --clips NOM.mov. --force seul reconstruit chaque clip.

Étape 3 — Raffiner les transcriptions (jugement — seulement si transcript_refinement: true)

Le raffinement est la seule partie de la transcription qui est un jugement — corriger les noms propres mal entendus à partir du contexte de la bibliothèque — donc cela reste une étape de modèle, exécutée après le passage mécanique. Sautez toute cette étape si transcript_refinement de la bibliothèque est false.

Lorsqu'il est true, dispatchez des sous-agents de raffinement (2-4 en parallèle, déroulement) sur les transcriptions que l'Étape 2a vient d'écrire. Incluez en ligne skills/transcribe-audio/refine_instructions.md comme prompt de chaque sous-agent et passez en ligne :

  • transcript_path — chemin absolu vers le JSON de transcription du clip sous libraries/<bibliothèque>/transcripts/
  • user_context et footage_summary — valeurs actuelles de ruby lib/buttercut/library.rb <nom> summary (les chaînes vides sont acceptables ; le raffinement capture toujours les corrections de tokens absurdes et d'auto-témoignage)

Les sous-agents modifient le JSON de transcription sur place et renvoient une courte liste de corrections. Ils NE touchent PAS à library.yaml — l'Étape 2a a déjà défini le champ transcript. Marquez la tâche publique "Créer les transcriptions" comme terminée une fois le raffinement achevé.

Étape 4 — Résumés (sous-agents Sonnet, par lots, déroulement)

Dispatchez des sous-agents analyze-video sur le modèle Sonnet. Sonnet lit la planche-contact avec une spécificité visuelle nettement supérieure à Haiku (capte les vêtements, l'architecture, le cadrage de la caméra) — cela en vaut la peine puisque les résumés alimentent toutes les décisions de coupe ultérieures.

Lot de 10 clips par sous-agent, jusqu'à 10 sous-agents en parallèle, avec déroulement. Chaque sous-agent traite ses 10 clips séquentiellement ; le regroupement amortit le surcoût d'environ 5 à 10 s par dispatch d'agent. Pour une bibliothèque de 93 clips, cela représente ~10 sous-agents au total au lieu de 93. Lancez le sous-agent suivant dès que l'un d'eux revient — n'attendez pas que la vague entière de 10 soit terminée, sinon vous perdez ~30% du temps réel à cause de l'agent le plus lent de la vague.

Pour chaque sous-agent, passez une liste de 10 enregistrements de clips en ligne. Chaque enregistrement de clip a besoin de :

  • video_filename — nom de base de la vidéo (utilisé dans l'en-tête du résumé et la ligne de réponse)
  • duration — chaîne de durée depuis library.yaml (par exemple 00:01:19) ; l'agent le rend dans l'en-tête du résumé
  • contact_sheet_path — chemin absolu vers le _full.jpg (de l'étape 2)
  • transcript_path — chemin absolu vers le JSON de transcription audio (de l'étape 2) ; le sous-agent extrait le dialogue à la demande via script_extractor.rb
  • summary_output_path — chemin absolu où l'agent doit écrire le markdown du résumé. Ne construisez pas ce nom de fichier vous-même ; demandez à la bibliothèque le chemin canonique : ruby lib/buttercut/library.rb <nom> field_path summary <clip> (gère la convention summaries/summary_<clip>.md pour vous, avec ou sans extension de fichier)

Au fur et à mesure que chaque sous-agent retourne son lot, mettez à jour library.yaml avec summary pour chaque clip de ce lot :

ruby lib/buttercut/library.rb <nom> complete summary <fichier> [<fichier>...]

Le champ contact_sheet a déjà été renseigné à l'étape 2, donc le retour du sous-agent ne contribue que les résumés.

Si un sous-agent renvoie les résumés en ligne au lieu de les écrire sur le disque (parfois Sonnet hallucine "l'outil Write est bloqué" et déverse le markdown dans sa réponse), ne réessayez pas aveuglément — extrayez simplement chaque résumé de la réponse de l'agent et Write-le vers le summary_output_path correspondant depuis le thread parent. Exécutez ensuite la commande complete summary comme d'habitude. Plus rapide qu'un redispatch, et le contenu est déjà là.

(Les planches-contacts par segment générées pour les longs clips coexistent avec la planche _full sur le disque et sont découvrables par convention — elles ne sont pas listées dans library.yaml.)

N'avancez pas avant que les résumés soient terminés. Avancez le compteur "Analyser les séquences" au fur et à mesure que les clips sont résumés ; marquez-le comme terminé quand c'est fini.

Images. Les images fixes sautent entièrement les Étapes 2–3 (pas d'audio à transcrire, pas de planche-contact à construire) — un summary est le seul artefact dont elles ont besoin, et elles apparaissent dans ruby lib/buttercut/library.rb <nom> pending summary aux côtés des vidéos. L'image est la chose à regarder, donc résumez-la directement : lisez le fichier image (il est petit) depuis le thread principal ou un sous-agent Sonnet et écrivez une description de 3 à 4 phrases — sujets, décor, composition, tout texte sur l'image — vers le chemin canonique depuis ruby lib/buttercut/library.rb <nom> field_path summary <nom-image>. Notez que les clés des clips image incluent l'extension (title-card.png → summaries/summary_title-card_png.md), ce que field_path gère pour vous. Ensuite, enregistrez-le de la même manière : ruby lib/buttercut/library.rb <nom> complete summary <nom-image>.

Étape 5 — Confirmer la compréhension des séquences avec l'utilisateur

(C'est la tâche "Revoir les séquences ensemble".) Une fois que chaque résumé est écrit, discutez de ce que les séquences montrent réellement — confirmez les noms des personnages, les lieux, le fil narratif, les clips aberrants ou hors sujet, et l'intention créative de l'utilisateur pour cette bibliothèque. Utilisez une conversation simple ; n'utilisez AskUserQuestion que pour proposer un choix discret. Au fur et à mesure que vous apprenez des choses, mettez à jour :

  • footage_summary et user_context via ruby lib/buttercut/library.rb <nom> update_metadata footage_summary "..." (et de même avec user_context)
  • les fichiers summary_*.md individuels lorsqu'un résumé identifie mal quelqu'un ou manque un détail clé (par exemple, "un homme en veste beige" → le nom de l'utilisateur)

C'est le seul endroit pour effectuer ce passage approfondi. Chaque planification ultérieure de roughcut hérite du contexte résultant plutôt que de ré-interroger la bibliothèque.

Étape 6 — Arrêter l'assistant de maintien en éveil

Si vous en avez démarré un à l'Étape 1, tuez-le maintenant (les deux plateformes) :

kill $KEEPAWAKE_PID 2>/dev/null

Modèle de sous-agent parallèle (référence)

Utilisé aux étapes 3 et 4.

Responsabilités de l'agent parent :

  • Lire library.yaml et settings.yaml une fois pour rassembler toutes les valeurs nécessaires aux sous-agents.
  • Lancer les agents Task en passant toutes les valeurs nécessaires en ligne dans le prompt.
  • Mettre à jour library.yaml séquentiellement au fur et à mesure que les agents se terminent (via l'API Library — voir AGENTS.md).
  • Gérer les erreurs et les tentatives.

Responsabilités de l'agent enfant :

  • Traiter le(s) clip(s) assigné(s) en utilisant uniquement les entrées passées en ligne par le parent.
  • Raffiner un JSON de transcription sur place (raffinement) ou lire la planche-contact pré-générée, extraire le dialogue de la transcription via script_extractor.rb, et écrire le markdown du résumé en un seul appel Write (analyze-video). (WhisperX n'est plus un sous-agent — process_footage.rb transcripts l'exécute à l'Étape 2a.)
  • Renvoyer une réponse courte et structurée avec les chemins de fichiers.

Le agent_prompt.md de chaque compétence documente son propre contrat d'E/S — y compris si le sous-agent lit ou écrit library.yaml. (Spoiler : il n'écrit jamais library.yaml. Seul le parent écrit, via l'API Library.)

Si l'utilisateur demande une coupe brute avant la fin de l'analyse

Avertissez : "Je peux créer une coupe brute maintenant, mais je ferai un meilleur travail après avoir analysé toutes les séquences. Continuer quand même ?" Si l'utilisateur confirme, procédez. Sinon, attendez la fin de l'analyse.

Skills associés