Communitygithub.com

beatcut

Erstellt aus einem Ordner mit Videoclips und einer Musikdatei einen beat-synchronisierten Kurzfilm – inklusive Beat-Erkennung, manueller oder visueller Schnittauswahl und ffmpeg-Rendering.

Was ist beatcut?

beatcut ist ein KI-gestütztes Tool, das aus einem Ordner von Videoclips und einer Musikdatei einen beat-genauen Kurzfilm erstellt. Es erkennt automatisch das Beat-Gitter der Musik und erlaubt es, Schnittpunkte entweder über einen visuellen Picker (Web-Oberfläche) oder durch manuelle Bearbeitung einer `shots.json`-Datei festzulegen. Der Arbeitsablauf umfasst die gesamte Pipeline: Initialisierung eines Projekts, Beat-Erkennung, Schnittauswahl, Prüfung auf Fehler, Rendern einer Vorabversion (Draft), Betrachtung des Ergebnisses über ein Kontaktblatt und schließlich das finale Rendern nur nach ausdrücklicher Benutzerfreundlichen Genehmigung. Unterstützt werden ffmpeg-basierte Ausgabe, benutzerdefinierte Profile für Farbe und Interpolation sowie flexible Anpassungen von Bildgröße, Seitenverhältnis und Übergängen.

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

In Ihrer bevorzugten KI fragen

Öffnet einen neuen Chat, in dem dieser Agent-Skill bereits geladen ist.

Dokumentation

Was macht beatcut?

beatcut erstellt aus einem Ordner mit Videoclips und einer Musikdatei ein Video, dessen Schnitte frame-genau auf den Beats liegen. Der Zustand wird in zwei Dateien im Projektordner gespeichert: project.json (Einstellungen) und shots.json (der Schnitt). Das Kommandozeilenwerkzeug heißt beatcut.py.

Pfade

Führen Sie die Befehle mit dem Python aus, das die erforderlichen Pakete installiert hat (pip install -r requirements.txt; ffmpeg und ffprobe müssen sich im PATH befinden). Verwenden Sie den Ordner, in dem dieses Skill installiert ist, als Repository-Ordner:

python <skill-Ordner>/beatcut.py <Befehl> ...

Im Folgenden steht beatcut.py für den vollständigen Pfad. Pfade zu Clips und Projekten können überall liegen; setzen Sie sie in Anführungszeichen, wenn sie Leerzeichen enthalten. Ein Projekt ist immer <Clips-Ordner>/beatcut; jeder Befehl außer init und sheet erwartet diesen Projektordner.

Arbeitsablauf

  1. Fragen, was fehlt: Den Ordner mit den Clips, die Musikdatei und die Ausgabeabmessungen (Standard: 1920x1080 für Draft, 3840x2160 für Final; vertikale Maße wie 1080x1920 sind in Ordnung).
  2. Initialisieren: beatcut.py init <Clips-Ordner> --music <Musikdatei>. Es gibt erstellt: <Ordner> aus und kopiert die Musik in das Projekt. Wenn es project.json existiert bereits meldet, existiert das Projekt; verwenden Sie es und initialisieren Sie nicht neu. Bearbeiten Sie project.json, wenn Größen, fill, fps, encoder, exclude_prefix oder benutzerdefinierte profiles geändert werden müssen (siehe Regeln unten).
  3. Beats: beatcut.py beats <Projekt>. Es gibt period, t0 und bpm aus und schreibt sie in shots.json. Die Erkennung geht von einem gleichmäßigen Tempo aus und kann bei t0 um einige Hundertstelsekunden abweichen. Wenn es mit weniger als 4 Beats erkannt beendet wird (Exit 1), setzen Sie period und t0 von Hand (period = 60 / BPM; t0 = Sekunde des ersten Beats). Teilen Sie dem Benutzer die Zahlen mit; er kann sie im Picker korrigieren.
  4. Schnitte auswählen, auf zwei Arten:
    • Picker (Standard). Starten Sie beatcut.py pick <Projekt> im Hintergrund (es blockiert bis zum Stopp; es öffnet den Browser, es sei denn, Sie fügen --no-open hinzu; Standardport 8765, ändern mit --port N). Teilen Sie dem Benutzer die ausgegebene URL mit, http://127.0.0.1:<port>/, und dass die Seite automatisch speichert. Warten Sie, bis der Benutzer sagt, dass er fertig ist, stoppen Sie dann den Server (Strg+C oder Hintergrundprozess beenden) und lesen Sie shots.json. Bearbeiten Sie shots.json nicht, während der Picker geöffnet ist: Die Seite würde Ihre Änderungen überschreiben.
    • Von Hand, wenn der Benutzer Sie bittet, den Schnitt zu erstellen oder genaue Zeiten angibt. Befolgen Sie die Regeln unten und führen Sie dann check aus.
  5. Prüfen: beatcut.py check <Projekt>. Exit 0 und ok: <n> Schnitte, <s> s bedeutet keine Fehler; lesen Sie auch die Warnungen (stderr). Beheben Sie jeden Fehler vor dem Rendern.
  6. Draft: beatcut.py draft <Projekt>. Es gibt encoder: ..., Segment i/n und schließlich den Pfad von out/<out_name>_draft.mp4 aus.
  7. Anschauen: beatcut.py sheet <Video> --out <irgendein .jpg-Pfad> erstellt ein 5-mal-4-Kontaktblatt; öffnen Sie dieses Bild und beschreiben Sie dem Benutzer das Ergebnis (Reihenfolge der Schnitte, Farbe, Überblendungen, schwarze Frames, falsche Zuschnitte). Wählen Sie einen --out-Pfad außerhalb des Clips-Ordners, z. B. einen Scratch-Ordner.
  8. Final, nur mit Zustimmung des Benutzers: Nachdem Sie den Draft gezeigt haben, fragen Sie, ob das Finale gerendert werden soll. Führen Sie beatcut.py final <Projekt> nur nach einem eindeutigen Ja aus. Das Finale ist langsamer und größer. Melden Sie den Ausgabepfad.

Wenn der Benutzer den Schnitt danach ändert, gehen Sie zurück zu Schritt 4. Rendervorgänge verwenden zwischengespeicherte Segmente, sodass ein zweiter Draft schneller ist.

Bearbeiten von shots.json von Hand

Halten Sie die Datei als gültiges JSON (UTF-8). check meldet jeden Verstoß gegen diese Regeln.

Oberste Ebene:

  • version: 1. period: Zahl, größer als 0,05 und kleiner als 10. t0: Zahl, 0 oder größer. tail: 0 bis 30 (Standard 1,5). shots: Liste, höchstens 2000.
  • Optional: bad (Clipname zu Liste von {"a": s, "b": s, "note": ""} mit b > a >= 0), clipnotes (Clipname zu Text), markers ({"beat": int >= 0, "title": Text}; nur im Picker angezeigt). Behalten Sie Schlüssel, die Sie nicht kennen; die Werkzeuge bewahren sie.

Jeder Schnitt:

  • clip: Dateiname mit Erweiterung, wie er im Clips-Ordner erscheint. Kein / oder \, kein :. Muss eine Datei direkt in clips_dir sein und mit extensions übereinstimmen.
  • in (0 oder mehr) und out (größer als in): Sekunden im Quellclip.
  • beats: Ganzzahl von 1 bis 512.
  • Optional, mit Standardwerten: fit (fit oder cut; Standard fit), interp (oflow, blend, none; lassen Sie es für automatische Entscheidung weg), prof (ein eingebauter Name neutral, warm, cool, contrast, golden oder ein in project.json unter profiles definierter Name; Standard neutral), tin (cut, fade, fadewhite; Standard cut), tdur (0 bis 5 Sekunden, Standard 0,5), note (Text, höchstens 2000 Zeichen).

Wie die Zahlen verwendet werden:

  • Schnitte werden nacheinander abgespielt; Schnitt N belegt beats Beats im Raster beginnend bei t0 + period * (Summe der vorherigen Beats). Der erste Schnitt beginnt bei Videoframe 0 an seinem in-Punkt, deckt also auch die Zeit vor dem ersten Beat ab und liest über sein out hinaus.
  • fit: Geschwindigkeit = (out - in) / (beats * period). Eine Geschwindigkeit innerhalb von 0,015 von 1 gilt als 1. check lehnt Geschwindigkeiten außerhalb von 0,1x bis 8x ab. Um einen Schnitt bei normaler Geschwindigkeit mit fit zu halten, setzen Sie out = in + beats * period.
  • cut: Spielt mit 1x ab; out wird nicht für die Geschwindigkeit verwendet (der Picker schreibt out = in + beats * period). Machen Sie dasselbe.
  • Der letzte Schnitt wird um tail Sekunden verlängert, und das Bild blendet über tail aus. Der gesamte Schnitt darf nicht länger als die Musik sein.
  • Jeder Schnitt benötigt Quellmaterial bis zu seinem Ende (einschließlich tail und Vorlauf des ersten Schnitts) mit 0,1 s Spielraum vor dem Ende des Clips. Ein fade- oder fadewhite-Übergang leiht sich die Hälfte seiner Länge von jedem Nachbarn, sodass der frühere Schnitt Quellmaterial über sein out hinaus benötigt und der spätere Schnitt Quellmaterial vor seinem in benötigt.
  • Ein Übergang muss kürzer sein als die Schnitte um ihn herum. tdur wird auf eine gerade Anzahl von Frames gerundet; unter 2 Frames bedeutet einen reinen Schnitt (Cut).
  • Zeitlupe: Automatische Interpolation erfolgt nur, wenn der Schnitt langsamer als 0,97x läuft und die Quellbildrate mal der Geschwindigkeit unter der Ausgabebildrate liegt (blend bei Drafts, oflow bei Finals). Setzen Sie interp nur, wenn der Benutzer darum bittet.
  • Wählen Sie in/out so, dass der Bereich keinen bad-Bereich überlappt; check warnt, wenn doch.

project.json-Regeln (wenn Sie sie ändern):

  • Unbekannte Schlüssel sind ein Fehler. music ist relativ zum Projektordner, kein .., kein absoluter Pfad. draft und final sind {"width": n, "height": n} mit positiven geraden ganzen Zahlen. fps ist ein String wie "25" oder "30000/1001". fill: cover oder blur. encoder: auto, cpu oder nvenc. loudness: -40 bis -5.
  • profiles: Name ([a-z0-9_-], 1 bis 32 Zeichen) zu einer ffmpeg-Filterkette, ohne ;, [ oder ]. Schnitte verweisen nur über den Namen auf Profile.

Meldungen und was zu tun ist

Warnungen beginnen mit warning: und stoppen einen Rendervorgang nicht. Fehler beginnen mit error: und gehen nach stderr.

MeldungBedeutung und Aktion
ffmpeg was not found on PATH; install FFmpeg and try again (Exit 2)ffmpeg oder ffprobe ist nicht im PATH. Bitten Sie den Benutzer, FFmpeg zu installieren; installieren Sie es nicht selbst, es sei denn, der Benutzer bittet darum.
no project.json in <folder> (did you mean <folder>\beatcut?) (Exit 1)Sie haben den Clips-Ordner übergeben. Verwenden Sie den Ordner beatcut darin.
unknown key(s): ..., <field>: muss ... seinEin Feld in project.json ist ungültig. Korrigieren Sie dieses Feld.
<path>: invalid JSON (...) (<path> ist der vollständige Pfad von shots.json)Syntaxfehler in der Datei. Beheben Sie ihn; die vorherige Version befindet sich möglicherweise in shots.json.bak.
shots[i].<field>: muss ... seinEin Schnitt verstößt gegen die obigen Regeln (i zählt ab 0). Korrigieren Sie ihn.
no shotsshots ist leer. Fügen Sie Schnitte hinzu (Picker oder von Hand).
shot N (clip): clip not found in the clips folderDer Dateiname ist falsch oder die Datei fehlt oder wird durch extensions oder exclude_prefix ausgeschlossen. Überprüfen Sie die Schreibweise; erstellen oder kopieren Sie niemals Dateien in den Clips-Ordner, um dies zu beheben.
shot N (clip): needs source up to X s but the clip is Y s longDer Bereich plus Vorlauf, Tail oder Übergang reicht über den Clip hinaus. Verschieben Sie in nach vorne, verwenden Sie weniger Beats, verwenden Sie fit mit einem kürzeren out oder verkürzen Sie den Übergang.
shot N (clip): needs X s before the start of the clip; move in laterEin Vorlauf des ersten Schnitts oder ein Übergang erreicht den Punkt vor 0. Erhöhen Sie in oder verkürzen Sie den Übergang.
shot N (clip): shorter than its transitions; ...Übergang länger als der Schnitt. Verringern Sie tdur oder fügen Sie Beats hinzu.
shot N (clip): speed X is outside 0.1x-8.0xBereich und Beat-Anzahl passen nicht. Ändern Sie beats oder den Bereich.
the edit is X s long but the music is only Y sEntfernen Sie Beats oder Schnitte, verringern Sie tail oder verwenden Sie eine längere Musikdatei.
warning: shot N (clip): uses a range marked bad (...)Der Schnitt überlappt einen bad-Bereich. Verschieben Sie ihn oder informieren Sie den Benutzer.
warning: <clip>: HDR source (...); colours will look washed out ...HDR-Clip; beatcut führt kein Tone-Mapping durch. Informieren Sie den Benutzer; schlagen Sie SDR-Clips vor.
warning: <clip>: cannot be read (...)ffprobe kann den Clip nicht lesen. Informieren Sie den Benutzer.
music file not found: <name>Die music-Datei fehlt im Projektordner.
profile <name>: ffmpeg rejects the filter chainEin benutzerdefiniertes Profil ist falsch. Korrigieren Sie seine Filterkette in project.json.
too many shots to assemble in one pass (N); split the editDer Schnitt ist zu lang für einen Render-Durchgang. Informieren Sie den Benutzer; teilen Sie ihn in mehrere Projekte oder weniger Schnitte auf.
another render is already running for this project (Exit 2)Ein Rendervorgang (möglicherweise vom Picker gestartet) läuft bereits. Warten Sie; löschen Sie nicht work/.
cannot write <file>; close it in any player and try againDie Ausgabe ist anderswo geöffnet. Bitten Sie den Benutzer, sie zu schließen.
fewer than 4 beats were detected; set period and t0 by hand (Exit 1)Siehe Schritt 3.

Exit-Codes: 0 Erfolg, 1 ein Problem mit der Benutzereingabe (beheben und erneut ausführen), 2 Umgebungs- oder Laufzeitfehler.

Nicht tun

  • Ändern, verschieben, umbenennen oder löschen Sie nicht die Quellclips, und schreiben Sie nichts in den Clips-Ordner außer dem von init erstellten beatcut-Projektordner. Alles, was das Werkzeug schreibt, befindet sich im Projektordner.
  • Löschen Sie nicht project.json, shots.json oder die Musikdatei. Führen Sie init nicht erneut über ein bestehendes Projekt aus.
  • Führen Sie final nicht ohne Zustimmung des Benutzers aus, nachdem dieser den Draft gesehen hat.
  • Setzen Sie den Picker keinem Netzwerk aus: keine Portweiterleitung, Tunnel, Reverse-Proxies, und versuchen Sie nicht, ihn an eine andere Adresse zu binden. Er hört nur auf 127.0.0.1 und ist nicht vor anderen Programmen auf demselben Computer geschützt.
  • Fügen Sie keine Filterketten in shots.json ein, und bearbeiten Sie shots.json nicht, während der Picker läuft.
  • Behaupten Sie nicht, dass das Ergebnis gut ist, ohne den Draft (Kontaktblatt oder das Video selbst) anzusehen.
  • Versprechen Sie keine Funktionen, die das Werkzeug nicht hat: kein HDR-Tone-Mapping, keine Gesichtserkennung, kein CapCut-Export, keine Soundeffekte. Linux und macOS sind nicht getestet; Windows ist die getestete Plattform.

Verwandte Skills