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
- 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).
- Initialisation :
beatcut.py init <dossier des clips> --music <fichier audio>. La commande affichecreated: <dossier>et copie le fichier audio dans le projet. Si elle indiqueproject.json already exists, le projet existe déjà ; utilisez-le et ne relancez pasinit. Modifiezproject.jsonsi les dimensions,fill,fps,encoder,exclude_prefixou desprofilespersonnalisés doivent être changés (voir les règles ci-dessous). - Temps forts :
beatcut.py beats <projet>. Elle afficheperiod,t0etbpmet les écrit dansshots.json. La détection suppose un tempo stable et peut être décalée de quelques centièmes de seconde surt0. Si elle se termine avec le code 1 et le messagefewer than 4 beats were detected, définissezperiodett0manuellement (period = 60 / BPM ; t0 = seconde du premier temps fort). Indiquez les valeurs à l'utilisateur ; il pourra les corriger dans le sélecteur. - 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 lisezshots.json. Ne modifiez passhots.jsonpendant 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.
- Sélecteur (par défaut). Lancez
- Vérification :
beatcut.py check <projet>. Un code de sortie 0 et le messageok: <n> shots, <s> ssignifient qu'il n'y a pas d'erreur ; lisez également les avertissements (stderr). Corrigez toutes les erreurs avant de lancer le rendu. - Brouillon :
beatcut.py draft <projet>. Elle afficheencoder: ...,segment i/npuis le chemin deout/<nom_sortie>_draft.mp4. - 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--outen dehors du dossier des clips, par exemple un dossier temporaire. - 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": ""}avecb > 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 dansclips_diret correspondre àextensions.in(0 ou plus) etout(supérieur àin) : secondes dans le clip source.beats: entier de 1 à 512.- Optionnel, avec valeurs par défaut :
fit(fitoucut; par défautfit),interp(oflow,blend,none; omettez-le pour automatique),prof(un nom intégréneutral,warm,cool,contrast,golden, ou un nom défini dansproject.jsonprofiles; par défautneutral),tin(cut,fade,fadewhite; par défautcut),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
beatstemps sur la grille à partir det0 + period * (somme des temps précédents). Le premier plan commence à l'image vidéo 0 à son pointin, donc il couvre aussi le temps avant le premier temps fort et lit au-delà de sonout. fit: vitesse =(out - in) / (beats * period). Une vitesse comprise entre 0,015 de 1 est considérée comme 1.checkrejette les vitesses en dehors de 0,1× à 8×. Pour conserver une vitesse normale avecfit, définissezout = in + beats * period.cut: joue à 1× ;outn'est pas utilisé pour la vitesse (le sélecteur écritout = in + beats * period). Faites de même.- Le dernier plan est prolongé de
tailsecondes et l'image s'estompe surtail. 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
tailet le préambule du premier plan) avec 0,1 seconde de marge avant la fin du clip. Une transitionfadeoufadewhiteemprunte la moitié de sa durée à chaque voisin, donc le plan précédent a besoin de source au-delà de sonoutet le suivant de source avant sonin. - Une transition doit être plus courte que les plans qui l'entourent.
tdurest 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 (
blendpour les brouillons,oflowpour les finals). Ne définissez pasinterpsauf demande de l'utilisateur. - Choisissez
in/outde manière à ce que la plage ne chevauche pas une plagebad;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.
musicest relatif au dossier du projet, sans.., non absolu.draftetfinalsont des{"width": n, "height": n}avec des entiers pairs positifs.fpsest une chaîne comme"25"ou"30000/1001".fill:coveroublur.encoder:auto,cpuounvenc.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.
| Message | Signification 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 shots | shots est vide. Ajoutez des plans (via le sélecteur ou manuellement). |
shot N (clip): clip not found in the clips folder | Le 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 long | La 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` later | Un 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.0x | La 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 s | Supprimez 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 chain | Un profil personnalisé est erroné. Corrigez sa chaîne dans project.json. |
too many shots to assemble in one pass (N); split the edit | Le 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 again | Le 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
beatcutcréé parinit. Tout ce que l'outil écrit se trouve à l'intérieur du dossier du projet. - Ne supprimez pas
project.json,shots.jsonou le fichier audio. Ne relancez pasinitsur un projet existant. - Ne lancez pas
finalsans 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.1et 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 passhots.jsonpendant 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.