Communitygithub.com

beatcut

Utilisez cette compétence pour découper une courte vidéo à partir d'un dossier de clips au rythme d'une piste musicale, construire ou modifier un montage synchrone (shots.json), choisir les points d'entrée/sortie des clips et les comptes de temps, ou générer un rendu brouillon ou final avec ffmpeg via l'outil en ligne de commande beatcut. Elle couvre tout le processus : initialisation du projet, détection de la grille de temps, sélection des plans dans le sélecteur local (ou édition manuelle de shots.json), vérification, rendu du brouillon, inspection avec une planche contact, et rendu final uniquement après approbation de l'utilisateur.

Qu'est-ce que beatcut ?

beatcut est un outil en ligne de commande (beatcut.py) qui permet de créer des vidéos montées au rythme d'une piste musicale, avec une précision à la trame près. Il fonctionne sur Windows (Linux et macOS non testés) et nécessite Python, ffmpeg et ffprobe. L'état du projet est stocké dans deux fichiers : project.json (paramètres) et shots.json (montage). Le flux de travail typique comprend : l'initialisation du projet avec un dossier de clips et un fichier audio, la détection automatique des temps (BPM), la sélection des plans via un sélecteur web local ou manuellement, la vérification des contraintes, le rendu d'un brouillon rapide, l'inspection via une planche contact, et le rendu final (plus lent et plus lourd) uniquement après approbation de l'utilisateur. Le brouillon peut être réutilisé pour accélérer les itérations suivantes. L'outil gère les transitions (fondu, fondu blanc), le recadrage (fit/cut), les profils de couleur, l'interpolation (pour le ralenti), et respecte des règles strictes pour éviter les erreurs de montage. Des vérifications exhaustives sont effectuées avant chaque rendu, et les erreurs sont clairement signalées avec des conseils de correction. Il est essentiel de ne pas modifier les fichiers sources, de ne pas exposer le sélecteur réseau, et de ne pas lancer le rendu final sans accord explicite de l'utilisateur après visualisation du brouillon.

Compatible avec~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/faruk76150/beatcut/tree/main

Demander à votre IA préférée

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

Documentation

Que fait beatcut ?

beatcut transforme un dossier de clips et un fichier audio en une vidéo dont les coupures tombent exactement sur les temps forts, à la trame près. L'état de votre projet est conservé dans deux fichiers situés dans le dossier du projet : project.json (paramètres) et shots.json (montage). L'outil en ligne de commande s'appelle beatcut.py.

Chemins d'accès

Exécutez les commandes avec l'interpréteur Python qui possède les dépendances installées (pip install -r requirements.txt ; ffmpeg et ffprobe doivent être disponibles dans le PATH). Utilisez le dossier dans lequel cette compétence est installée comme dossier du dépôt :

python <dossier de la compétence>/beatcut.py <commande> ...

Ci-dessous, beatcut.py désigne ce chemin complet. Les chemins vers les clips et les projets peuvent être quelconques ; mettez-les entre guillemets s'ils contiennent des espaces. Un projet se trouve toujours dans <dossier des clips>/beatcut ; toutes les commandes sauf init et sheet prennent ce dossier de projet en argument.

Flux de travail

  1. Demandez ce qui manque : le dossier des clips, le fichier audio, et les dimensions de sortie (par défaut 1920×1080 pour le brouillon, 3840×2160 pour le final ; les formats verticaux comme 1080×1920 fonctionnent aussi).
  2. Initialisation : beatcut.py init <dossier des clips> --music <fichier audio>. La commande affiche created: <dossier> et copie le fichier audio dans le projet. Si elle indique project.json already exists, le projet existe déjà ; utilisez-le et ne relancez pas init. Modifiez project.json si les dimensions, fill, fps, encoder, exclude_prefix ou des profiles personnalisés doivent être changés (voir les règles ci-dessous).
  3. Temps forts : beatcut.py beats <projet>. Elle affiche period, t0 et bpm et les écrit dans shots.json. La détection suppose un tempo stable et peut être décalée de quelques centièmes de seconde sur t0. Si elle se termine avec le code 1 et le message fewer than 4 beats were detected, définissez period et t0 manuellement (period = 60 / BPM ; t0 = seconde du premier temps fort). Indiquez les valeurs à l'utilisateur ; il pourra les corriger dans le sélecteur.
  4. Choisissez les plans, de l'une des deux manières suivantes :
    • Sélecteur (par défaut). Lancez beatcut.py pick <projet> en arrière-plan (il bloque jusqu'à son arrêt ; il ouvre le navigateur sauf si vous ajoutez --no-open ; port par défaut 8765, modifiable avec --port N). Communiquez à l'utilisateur l'URL affichée, http://127.0.0.1:<port>/, et précisez que la page enregistre automatiquement. Attendez que l'utilisateur vous indique qu'il a terminé, puis arrêtez le serveur (Ctrl+C ou terminez le processus en arrière-plan) et lisez shots.json. Ne modifiez pas shots.json pendant que le sélecteur est ouvert : la page écraserait vos changements.
    • Manuellement, lorsque l'utilisateur vous demande de construire le montage ou vous donne des temps précis. Suivez les règles ci-dessous, puis exécutez check.
  5. Vérification : beatcut.py check <projet>. Un code de sortie 0 et le message ok: <n> shots, <s> s signifient qu'il n'y a pas d'erreur ; lisez également les avertissements (stderr). Corrigez toutes les erreurs avant de lancer le rendu.
  6. Brouillon : beatcut.py draft <projet>. Elle affiche encoder: ..., segment i/n puis le chemin de out/<nom_sortie>_draft.mp4.
  7. Examinez le résultat : beatcut.py sheet <vidéo> --out <chemin .jpg> génère une planche contact de 5 × 4 images ; ouvrez cette image et décrivez le résultat à l'utilisateur (ordre des plans, couleur, fondus, images noires, mauvais recadrages). Choisissez un chemin --out en dehors du dossier des clips, par exemple un dossier temporaire.
  8. Final, uniquement avec l'approbation de l'utilisateur : après avoir montré le brouillon, demandez s'il souhaite effectuer le rendu final. Exécutez beatcut.py final <projet> uniquement après un oui clair. Le rendu final est plus lent et plus volumineux. Indiquez le chemin de sortie.

Si l'utilisateur modifie le montage par la suite, revenez à l'étape 4. Les rendus réutilisent les segments mis en cache, donc un second brouillon est plus rapide.

Modifier shots.json manuellement

Assurez-vous que le fichier reste un JSON valide (UTF-8). check signale toute violation des règles ci-dessous.

Niveau racine :

  • version : 1. period : nombre, supérieur à 0,05 et inférieur à 10. t0 : nombre, 0 ou plus. tail : de 0 à 30 (par défaut 1,5). shots : liste, au maximum 2000.
  • Optionnel : bad (nom du clip vers une liste de {"a": s, "b": s, "note": ""} avec b > a >= 0), clipnotes (nom du clip vers du texte), markers ({"beat": int >= 0, "title": texte} ; affiché uniquement dans le sélecteur). Conservez les clés que vous ne connaissez pas ; les outils les préservent.

Chaque plan :

  • clip : nom du fichier avec extension, tel qu'il apparaît dans le dossier des clips. Pas de / ni \, pas de :. Doit être un fichier directement présent dans clips_dir et correspondre à extensions.
  • in (0 ou plus) et out (supérieur à in) : secondes dans le clip source.
  • beats : entier de 1 à 512.
  • Optionnel, avec valeurs par défaut : fit (fit ou cut ; par défaut fit), interp (oflow, blend, none ; omettez-le pour automatique), prof (un nom intégré neutral, warm, cool, contrast, golden, ou un nom défini dans project.json profiles ; par défaut neutral), tin (cut, fade, fadewhite ; par défaut cut), tdur (de 0 à 5 secondes, par défaut 0,5), note (texte, au maximum 2000 caractères).

Comment les nombres sont utilisés :

  • Les plans se succèdent ; le plan N occupe beats temps sur la grille à partir de t0 + period * (somme des temps précédents). Le premier plan commence à l'image vidéo 0 à son point in, donc il couvre aussi le temps avant le premier temps fort et lit au-delà de son out.
  • fit : vitesse = (out - in) / (beats * period). Une vitesse comprise entre 0,015 de 1 est considérée comme 1. check rejette les vitesses en dehors de 0,1× à 8×. Pour conserver une vitesse normale avec fit, définissez out = in + beats * period.
  • cut : joue à 1× ; out n'est pas utilisé pour la vitesse (le sélecteur écrit out = in + beats * period). Faites de même.
  • Le dernier plan est prolongé de tail secondes et l'image s'estompe sur tail. La durée totale du montage ne doit pas dépasser celle de la musique.
  • Chaque plan nécessite de la matière source jusqu'à sa fin (y compris le tail et le préambule du premier plan) avec 0,1 seconde de marge avant la fin du clip. Une transition fade ou fadewhite emprunte la moitié de sa durée à chaque voisin, donc le plan précédent a besoin de source au-delà de son out et le suivant de source avant son in.
  • Une transition doit être plus courte que les plans qui l'entourent. tdur est arrondi à un nombre pair d'images ; en dessous de 2 images, cela correspond à une coupure nette.
  • Ralenti : l'interpolation automatique n'a lieu que lorsque le plan tourne à moins de 0,97× et que la cadence image source multipliée par la vitesse est inférieure à la cadence image de sortie (blend pour les brouillons, oflow pour les finals). Ne définissez pas interp sauf demande de l'utilisateur.
  • Choisissez in/out de manière à ce que la plage ne chevauche pas une plage bad ; check émet un avertissement si c'est le cas.

Règles de project.json (lorsque vous le modifiez) :

  • Les clés inconnues sont une erreur. music est relatif au dossier du projet, sans .., non absolu. draft et final sont des {"width": n, "height": n} avec des entiers pairs positifs. fps est une chaîne comme "25" ou "30000/1001". fill : cover ou blur. encoder : auto, cpu ou nvenc. loudness : de -40 à -5.
  • profiles : nom ([a-z0-9_-], de 1 à 32 caractères) vers une chaîne de filtre ffmpeg, sans ;, [ ou ]. Les plans se réfèrent aux profils uniquement par leur nom.

Messages et actions

Les avertissements commencent par warning: et n'empêchent pas un rendu. Les erreurs commencent par error: et sont envoyées sur stderr.

MessageSignification et action
ffmpeg was not found on PATH; install FFmpeg and try again (code 2)ffmpeg ou ffprobe n'est pas dans le PATH. Demandez à l'utilisateur d'installer FFmpeg ; ne l'installez pas vous-même sauf demande explicite.
no project.json in <folder> (did you mean <folder>\beatcut?) (code 1)Vous avez passé le dossier des clips. Utilisez le dossier beatcut à l'intérieur.
unknown key(s): ..., <field>: must be ...Un champ de project.json est invalide. Corrigez ce champ.
<path>: invalid JSON (...) (<path> est le chemin complet de shots.json)Erreur de syntaxe dans le fichier. Corrigez-le ; la version précédente peut se trouver dans shots.json.bak.
shots[i].<field>: must be ...Un plan ne respecte pas les règles ci-dessus (i commence à 0). Corrigez-le.
no shotsshots est vide. Ajoutez des plans (via le sélecteur ou manuellement).
shot N (clip): clip not found in the clips folderLe nom du fichier est incorrect ou le fichier est manquant ou exclu par extensions ou exclude_prefix. Vérifiez l'orthographe ; ne créez ni ne copiez jamais de fichiers dans le dossier des clips pour corriger cela.
shot N (clip): needs source up to X s but the clip is Y s longLa plage, plus le préambule, le tail ou la transition, dépasse la fin du clip. Avancez in, utilisez moins de temps, utilisez fit avec un out plus court, ou raccourcissez la transition.
shot N (clip): needs X s before the start of the clip; move `in` laterUn préambule du premier plan ou une transition atteint avant 0. Augmentez in ou raccourcissez la transition.
shot N (clip): shorter than its transitions; ...La transition est plus longue que le plan. Réduisez tdur ou ajoutez des temps.
shot N (clip): speed X is outside 0.1x-8.0xLa plage et le nombre de temps ne correspondent pas. Modifiez beats ou la plage.
the edit is X s long but the music is only Y sSupprimez des temps ou des plans, réduisez tail, ou utilisez un fichier audio plus long.
warning: shot N (clip): uses a range marked bad (...)Le plan chevauche une plage bad. Déplacez-le, ou informez l'utilisateur.
warning: <clip>: HDR source (...); colours will look washed out ...Clip HDR ; beatcut ne fait pas de mappage tonal. Informez l'utilisateur ; suggérez des clips SDR.
warning: <clip>: cannot be read (...)ffprobe ne peut pas lire le clip. Informez l'utilisateur.
music file not found: <name>Le fichier music est manquant dans le dossier du projet.
profile <name>: ffmpeg rejects the filter chainUn profil personnalisé est erroné. Corrigez sa chaîne dans project.json.
too many shots to assemble in one pass (N); split the editLe montage est trop long pour être rendu en une seule passe. Informez l'utilisateur ; divisez-le en plusieurs projets ou réduisez le nombre de plans.
another render is already running for this project (code 2)Un rendu (peut-être lancé depuis le sélecteur) est déjà en cours. Attendez sa fin ; ne supprimez pas work/.
cannot write <file>; close it in any player and try againLe fichier de sortie est ouvert ailleurs. Demandez à l'utilisateur de le fermer.
fewer than 4 beats were detected; set period and t0 by hand (code 1)Voir l'étape 3.

Codes de sortie : 0 succès, 1 problème lié à l'entrée utilisateur (corrigez et réexécutez), 2 erreur d'environnement ou d'exécution.

À ne pas faire

  • Ne modifiez pas, ne déplacez pas, ne renommez pas et ne supprimez pas les clips sources, et n'écrivez rien dans le dossier des clips en dehors du dossier de projet beatcut créé par init. Tout ce que l'outil écrit se trouve à l'intérieur du dossier du projet.
  • Ne supprimez pas project.json, shots.json ou le fichier audio. Ne relancez pas init sur un projet existant.
  • Ne lancez pas final sans l'approbation de l'utilisateur après qu'il a vu le brouillon.
  • N'exposez pas le sélecteur sur un réseau : pas de transfert de port, tunnels, proxys inversés, et n'essayez pas de le lier à une autre adresse. Il écoute uniquement sur 127.0.0.1 et n'est pas protégé contre d'autres programmes sur le même ordinateur.
  • Ne mettez pas de chaînes de filtre dans shots.json, et ne modifiez pas shots.json pendant que le sélecteur est en cours d'exécution.
  • N'affirmez pas que le résultat est bon sans avoir examiné le brouillon (planche contact ou la vidéo elle-même).
  • Ne promettez pas de fonctionnalités que l'outil ne possède pas : pas de mappage tonal HDR, pas de détection de visages, pas d'export CapCut, pas d'effets sonores. Linux et macOS ne sont pas testés ; Windows est la plateforme testée.

Skills associés