christoph/auto-video-cut
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
main
auto-video-cut/ANFORDERUNGEN.md
Christoph K. 267070ad52 Initial commit: auto-video-cut project 
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
2026-04-06 21:51:01 +02:00

26 KiB
Executable File
Raw Permalink Blame History

Anforderungen: auto-video-cut

Stand: 2026-03-20 (aktualisiert: KI-Features, Übergänge, Audio-Ducking)

1. Ziel

auto-video-cut ist ein vollständig automatisiertes Kommandozeilen-Tool für Videoschnitt, -zusammenführung und Musikunterlegung. Keine GUI, keine manuelle Timeline. Zielgruppe: technisch versierte Einzelnutzer mit wiederholenden Video-Workflows.

2. Systemvoraussetzungen

Anforderung Detail
Python >= 3.10
ffmpeg Im PATH verfügbar (für alle Video-/Audio-Operationen)
ffprobe Im PATH verfügbar (für Metadaten-Abfragen)
Betriebssystem Plattformunabhängig (getestet unter Linux/WSL, macOS, Windows)

3. Python-Abhängigkeiten

Paket Version Verwendung
typer >= 0.12 CLI-Framework
pyyaml >= 6.0 YAML-Konfiguration und Sequenz-Dateien
scenedetect[opencv] >= 0.6 Szenen-Erkennung via ContentDetector
ffmpeg-python >= 0.2 ffmpeg-Binding (Hilfsfunktionen)
discord.py >= 2.3 Discord-Bot für Fernsteuerung
rich >= 13.0 Fortschrittsanzeige und Terminal-UI

Optionale KI-Abhängigkeiten (pip install -e ".[ai]"):

Paket Version Verwendung
faster-whisper >= 1.0 Lokale Sprach-Transkription (Whisper)
anthropic >= 0.40 LLM-Anbindung für Auto-Kapitel, Highlights, Beschreibungen

Installation: pip install -e . CLI-Einstiegspunkt: video-cut

4. Funktionale Anforderungen

4.1 Stille-Erkennung und -Entfernung

  • F-01 Das Tool erkennt Stille-Abschnitte in einem Video via ffmpeg silencedetect.
  • F-02 Erkannte Stille-Abschnitte werden aus dem Video herausgeschnitten; die verbleibenden Ton-Abschnitte werden nahtlos zusammengefügt.
  • F-03 Konfigurierbare Parameter:
    • threshold_db — Schwelle in dB, ab der Stille erkannt wird (Standard: -40)
    • min_duration — Mindestdauer in Sekunden, ab der Stille als solche gilt (Standard: 0.5)
  • F-04 Stille-Erkennung ist pro Clip in der Sequenz-Datei einzeln aktivierbar (remove_silence: true / trim_silence: true).

4.2 Szenen-Erkennung

  • F-05 Das Tool erkennt Szenen-Grenzen via PySceneDetect (ContentDetector).
  • F-06 Das Video wird an erkannten Szenen-Grenzen in einzelne Clips aufgeteilt und in einen Ausgabe-Ordner gespeichert.
  • F-07 Konfigurierbare Parameter:
    • threshold — Empfindlichkeit der Szenen-Erkennung (Standard: 27.0)

4.3 Clips zusammenführen

  • F-08 Mehrere Video-Clips werden via ffmpeg concat zu einem einzigen Video zusammengeführt.
  • F-09 Vor dem Zusammenführen werden Clips optional auf ein einheitliches Format re-encodet (H.264, AAC, yuv420p, 25fps), um Kompatibilitätsprobleme zu vermeiden.
  • F-10 Optional: Intro-Clip vor dem ersten und Outro-Clip nach dem letzten Inhalt einfügen.

4.4 Hintergrundmusik

  • F-11 Musik-Dateien werden aus einem konfigurierbaren Ordner (resources/music/) gelesen.
  • F-12 Unterstützte Musikformate: .mp3, .wav, .flac, .aac, .ogg
  • F-13 Auswahlmodus für Musik:
    • random — zufällig aus dem Ordner
    • alphabetical — erste Datei alphabetisch
    • loop — erste Datei alphabetisch (wird geloopt)
  • F-14 Musik wird auf die Länge des Videos getrimmt (-shortest) oder geloopt (-stream_loop -1).
  • F-15 Original-Audio und Hintergrundmusik werden gemischt via ffmpeg amix mit konfigurierbaren Lautstärken:
    • volume_original — Lautstärke des Original-Tons (Standard: 1.0)
    • volume_music — Lautstärke der Hintergrundmusik (Standard: 0.3)
  • F-16 Hat das Video keinen Audio-Track, wird die Musik direkt als einziger Audio-Track eingefügt.
  • F-17 In der Sequenz-Datei kann eine konkrete Musikdatei oder "random" angegeben werden; Lautstärken sind pro Sequenz überschreibbar.

4.5 Text-Einblendungen

  • F-18 Text wird als Standbild-Clip auf einem konfigurierbaren Hintergrund (Farbe oder schwarz) gerendert via ffmpeg drawtext + lavfi color.
  • F-19 Text-Overlays können über laufende Video-Clips gelegt werden, mit optionaler Zeitbegrenzung (enable='between(t,0,N)').
  • F-20 Konfigurierbare Text-Optionen:
    • content — Text-Inhalt
    • duration — Anzeigedauer in Sekunden (für Standbild-Clips)
    • font_size — Schriftgröße (Standard: 72 für Clips, 48 für Overlays)
    • font_color — Schriftfarbe (Standard: "white")
    • background_color — Hintergrundfarbe oder "transparent" (Standard: "black")
    • position — center | top | bottom (Standard: "center")
  • F-21 Sonderzeichen im Text (', :, \) werden für ffmpeg korrekt escapt.

4.6 Bilder als Clips

  • F-22 Einzelne Bilder (.png, .jpg, .jpeg) werden in Video-Clips konvertiert (ffmpeg -loop 1).
  • F-23 Konfigurierbare Anzeigedauer in Sekunden.
  • F-24 Bilder werden auf die Zielauflösung skaliert und bei abweichendem Seitenverhältnis mit schwarzen Balken aufgefüllt (letterbox).
  • F-25 Standard-Auflösung: 1920×1080, 25fps.

4.7 Sequenz-Verarbeitung

  • F-26 Eine sequence.yaml-Datei definiert die Timeline des finalen Videos: Reihenfolge, Quellen und Verarbeitungsoptionen aller Elemente.
  • F-27 Unterstützte Sequenz-Typen:
Typ Beschreibung
video Einzelne Videodatei
image Standbild für konfigurierbare Dauer
text Text auf Hintergrundfarbe als Clip
folder Alle Medien in einem Ordner, sortierbar
  • F-28 Ordner-Einträge (type: folder) unterstützen Sortierung nach:
    • alphabetical — alphabetisch nach Dateiname
    • date — nach Änderungsdatum
  • F-29 Datei-Pfade in der Sequenz werden aufgelöst: absolut → relativ → aus resources/-Unterordner.
  • F-30 Musik-Konfiguration kann direkt in der sequence.yaml angegeben werden und überschreibt die globale config.yaml.

4.8 Batch-Verarbeitung

  • F-31 Alle Video-Dateien in einem Ordner werden sequenziell verarbeitet.
  • F-32 Unterstützte Video-Formate: .mp4, .mov, .avi, .mkv
  • F-33 Jede Verarbeitungs-Option (Stille entfernen, Szenen, Musik) ist einzeln für den Batch aktivierbar.
  • F-34 Ausgabe-Dateien werden in den konfigurierten Output-Ordner gespeichert.

5. Ressourcen-Struktur

resources/
├── music/      ← .mp3, .wav, .flac, .aac, .ogg
├── videos/     ← Intros, Outros, Übergänge (.mp4, .mov, .avi, .mkv)
└── images/     ← Titelkarten, Folien (.png, .jpg, .jpeg)
  • F-35 Der Ressourcen-Ordner ist über resources.folder in der Konfiguration frei wählbar.
  • F-36 Das Tool gibt eine Warnung aus, wenn der Ressourcen-Ordner oder der Musik-Unterordner nicht existiert oder leer ist — kein harter Abbruch.

6. Konfiguration (config.yaml)

Alle Parameter haben Standardwerte; eine Konfigurationsdatei ist optional.

Schlüssel Typ Standard Beschreibung
resources.folder string "./resources" Basis-Ordner für Ressourcen
music.mode string "random" Musik-Auswahlmodus
music.volume_original float 1.0 Lautstärke Original-Ton
music.volume_music float 0.3 Lautstärke Hintergrundmusik
videos.intro string null Dateiname des Intro-Clips
videos.outro string null Dateiname des Outro-Clips
videos.transitions bool false Übergangs-Clips einsetzen
images.title_card string null Dateiname der Titelkarte
images.duration int 3 Standard-Anzeigedauer für Bilder (s)
silence.threshold_db float -40 Stille-Schwelle in dB
silence.min_duration float 0.5 Minimale Stille-Dauer in Sekunden
scenes.threshold float 27.0 Szenen-Erkennungs-Schwelle
output.format string "mp4" Ausgabeformat
output.folder string "./output" Ausgabe-Ordner
  • F-37 Fehlende Schlüssel in der Konfigurationsdatei werden mit Standardwerten aufgefüllt (Deep-Merge).
  • F-38 Beim Laden der Konfiguration werden Warnungen für ungültige Lautstärke-Werte ausgegeben.

7. CLI-Befehle

video-cut cut

video-cut cut --input VIDEO [--output DATEI] [--config CONFIG]
              [--remove-silence] [--scene-detect]
Option Beschreibung
--input, -i Eingabe-Videodatei (Pflicht)
--output, -o Ausgabedatei (Standard: <stem>_no_silence.mp4)
--config, -c Konfigurationsdatei
--remove-silence Stille entfernen
--scene-detect Szenen erkennen und aufteilen

video-cut merge

video-cut merge --inputs CLIP1 CLIP2 [...] --output DATEI
               [--intro CLIP] [--outro CLIP] [--no-normalize]
Option Beschreibung
--inputs Eingabe-Clips (Pflicht, mehrfach)
--output, -o Ausgabedatei (Pflicht)
--intro Optionaler Intro-Clip
--outro Optionaler Outro-Clip
--no-normalize Re-Encoding überspringen

video-cut music

video-cut music --input VIDEO [--output DATEI] [--config CONFIG]
               [--music-file DATEI] [--vol-orig 1.0] [--vol-music 0.3]
Option Beschreibung
--input, -i Eingabe-Videodatei (Pflicht)
--output, -o Ausgabedatei (Standard: <stem>_music.mp4)
--config, -c Konfigurationsdatei
--music-file Direkte Musikdatei (überschreibt config)
--vol-orig Lautstärke Original (Standard: 1.0)
--vol-music Lautstärke Musik (Standard: 0.3)

video-cut batch

video-cut batch --input ORDNER [--config CONFIG]
               [--remove-silence] [--scene-detect] [--music]
Option Beschreibung
--input, -i Ordner mit Videos (Pflicht)
--config, -c Konfigurationsdatei
--remove-silence Stille aus allen Videos entfernen
--scene-detect Szenen in allen Videos erkennen
--music Musik zu allen Videos hinzufügen

video-cut sequence

video-cut sequence --seq SEQUENZ.yaml [--config CONFIG]
                  [--output DATEI] [--music/--no-music]
Option Beschreibung
--seq, -s Sequenz-Datei (Pflicht)
--config, -c Konfigurationsdatei
--output, -o Ausgabedatei (Standard: output/output.mp4)
--music / --no-music Musik hinzufügen oder nicht (Standard: an)

8. Discord-Integration (Fernsteuerung)

8.1 Überblick

Die Applikation soll über einen Discord-Bot ferngesteuert werden können. Der Bot läuft als Hintergrund-Prozess auf demselben Server wie auto-video-cut und empfängt Befehle über Discord-Slash-Commands. Ergebnisse und Fortschrittsmeldungen werden in den aufrufenden Discord-Kanal zurückgemeldet.

8.2 Architektur

Discord-Nutzer
     │  Slash-Command (/cut, /music, ...)
     ▼
Discord API
     │  discord.py Bot (auto_video_cut/bot.py)
     ▼
CLI-Logik (cutter, merger, audio, sequencer, ...)
     │  Ergebnis / Fortschritt
     ▼
Discord API → Antwort im Kanal

Der Bot ruft intern dieselben Python-Funktionen auf wie die CLI — kein separater Prozess, keine HTTP-API.

8.3 Konfiguration

Neue Schlüssel in config.yaml:

discord:
  token: "BOT_TOKEN"          # Discord-Bot-Token (Pflicht)
  allowed_channel_ids:        # Whitelist der erlaubten Kanal-IDs
    - 123456789012345678
  allowed_user_ids:           # Whitelist der erlaubten Nutzer-IDs (optional)
    - 987654321098765432
  upload_results: true        # Fertige Videos direkt in Discord hochladen (≤ 25 MB)
  notify_on_complete: true    # Abschluss-Meldung immer senden
  • F-39 Der Bot-Token wird aus der Konfigurationsdatei oder alternativ aus der Umgebungsvariable VIDEO_CUT_DISCORD_TOKEN gelesen.
  • F-40 Befehle werden nur in explizit erlaubten Kanälen akzeptiert; alle anderen Anfragen werden still ignoriert.
  • F-41 Optional: Whitelist auf bestimmte Discord-Nutzer-IDs einschränken.

8.4 Bot starten

video-cut bot --config config.yaml

Der Bot läuft als Langzeit-Prozess (Blocking Event Loop). Empfohlen: systemd-Service oder screen/tmux-Session.

8.5 Slash-Commands

Alle CLI-Befehle werden als Discord-Slash-Commands gespiegelt. Dateipfade beziehen sich immer auf den Server, auf dem der Bot läuft.

/cut

/cut input:<Pfad> [remove_silence:true|false] [scene_detect:true|false] [config:<Pfad>]
  • Schneidet ein Video (Stille entfernen und/oder Szenen aufteilen)
  • Antwort: Fortschritts-Embed → Abschluss-Embed mit Ausgabepfad

/merge

/merge inputs:<Pfad1,Pfad2,...> output:<Pfad> [intro:<Pfad>] [outro:<Pfad>]
  • Fügt mehrere Clips zusammen

/music

/music input:<Pfad> [config:<Pfad>] [music_file:<Pfad>] [vol_orig:1.0] [vol_music:0.3]
  • Legt Hintergrundmusik unter ein Video

/batch

/batch input:<Ordner> [config:<Pfad>] [remove_silence:true] [music:true]
  • Verarbeitet alle Videos in einem Ordner

/sequence

/sequence seq:<Pfad> [config:<Pfad>] [output:<Pfad>] [music:true|false]
  • Rendert ein Video aus einer sequence.yaml

/status

/status
  • Zeigt laufende Jobs, Warteschlange und System-Status (ffmpeg vorhanden, Ressourcen-Ordner erreichbar)

/cancel

/cancel [job_id:<ID>]
  • Bricht den aktuellen oder einen bestimmten Job ab

8.6 Antwort-Format

  • F-42 Jeder Befehl wird mit einem Discord-Embed bestätigt: Job-ID, Eingabe-Parameter, Startzeitpunkt.
  • F-43 Während der Verarbeitung werden Fortschritts-Updates als bearbeitete Embed-Nachricht gesendet (alle ~10 Sekunden oder bei Meilenstein: Stille erkannt, Clips zusammengeführt, Musik gemischt).
  • F-44 Bei Abschluss: Embed mit Ausgabepfad, Dauer der Verarbeitung, Dateigröße.
  • F-45 Ist die fertige Datei ≤ 25 MB und upload_results: true, wird sie direkt in Discord hochgeladen.
  • F-46 Bei Fehlern: Embed mit Fehlermeldung und dem betroffenen Verarbeitungsschritt (roter Embed-Rand).

8.7 Job-Verwaltung

  • F-47 Jobs werden sequenziell in einer FIFO-Warteschlange abgearbeitet — kein paralleles Rendering, da ffmpeg die CPU auslastet.
  • F-48 Jeder Job erhält eine eindeutige Job-ID (kurzer UUID-Präfix), die in allen Nachrichten angezeigt wird.
  • F-49 Läuft bereits ein Job, wird der neue Job mit geschätzter Warteposition bestätigt ("Job #3 in Warteschlange").
  • F-50 /cancel bricht laufende ffmpeg-Subprozesse sauber ab (process.terminate()).

8.8 Sicherheit

  • F-51 Dateipfade aus Discord-Nachrichten werden auf erlaubte Basis-Verzeichnisse beschränkt (konfigurierbar: allowed_paths). Path-Traversal-Angriffe (../) werden abgewiesen.
  • F-52 Shell-Injection ist ausgeschlossen, da alle ffmpeg-Aufrufe als Argument-Listen via subprocess erfolgen (kein shell=True).
  • F-53 Der Bot-Token wird niemals in Logs oder Discord-Nachrichten ausgegeben.

8.9 Neue Projektdatei

auto_video_cut/
└── bot.py    ← Discord-Bot (discord.py, Slash-Commands, Job-Queue)

9. Video-Übergänge und Effekte

9.1 Crossfade

  • F-54 Zwischen zwei Clips kann ein Crossfade (weicher Übergang) eingefügt werden via ffmpeg xfade Filter.
  • F-55 Konfigurierbare Parameter pro Sequenz-Eintrag:
    • transition — Übergangstyp: crossfade | dissolve | wipeleft (Standard: keiner)
    • transition_duration — Dauer in Sekunden (Standard: 0.5)
  • F-56 Globale Fade-Optionen:
    • fade_in — Einblende-Dauer am Anfang des Gesamtvideos
    • fade_out — Ausblende-Dauer am Ende des Gesamtvideos

9.2 Audio-Ducking

  • F-57 Hintergrundmusik wird automatisch leiser wenn Original-Audio (Sprache) erkannt wird, via ffmpeg sidechaincompress.
  • F-58 Konfigurierbare Ducking-Parameter:
    • ducking — aktivieren/deaktivieren (Standard: false)
    • duck_threshold — ab welcher Lautstärke die Musik abgesenkt wird (Standard: 0.02)
    • duck_ratio — Stärke der Absenkung (Standard: 4.0)
    • duck_attack — wie schnell die Musik leiser wird in Sekunden (Standard: 0.3)
    • duck_release — wie schnell die Musik wieder lauter wird in Sekunden (Standard: 1.0)

9.3 Fortschrittsanzeige

  • F-59 Alle ffmpeg-Operationen zeigen einen Echtzeit-Fortschrittsbalken mit Prozent und geschätzter Restzeit via rich.
  • F-60 ffmpeg wird mit -progress pipe:1 gestartet; out_time_ms wird geparst und gegen die Gesamt-Dauer gerechnet.

9.4 Preview und Dry-Run

  • F-61 --preview erzeugt eine niedrig aufgelöste Schnellversion (360p, ultrafast-Preset) im Temp-Ordner.
  • F-62 --dry-run zeigt die geplante Verarbeitung ohne zu rendern: Clip-Liste, geschätzte Gesamtdauer, geschätzte Dateigröße.

10. KI-Features

10.1 Whisper-Transkription

  • F-63 Audio wird aus dem Video extrahiert (WAV, 16kHz Mono) und lokal mit faster-whisper transkribiert.
  • F-64 Konfigurierbare Whisper-Parameter:
    • whisper_model — Modellgröße: tiny | base | small | medium | large-v3 (Standard: base)
    • whisper_language — Sprache oder null für Auto-Erkennung (Standard: null)
    • whisper_device — Gerät: auto | cpu | cuda (Standard: auto)
  • F-65 Das Transkript enthält Wort-Level-Timestamps (Start, Ende, Konfidenz pro Wort).
  • F-66 KI-Features sind optional: fehlt faster-whisper, wird eine verständliche Fehlermeldung ausgegeben mit Installationshinweis.

10.2 Automatische Untertitel

  • F-67 Aus dem Whisper-Transkript wird eine .srt-Datei mit korrekten Timestamps erzeugt.
  • F-68 Untertitel werden via ffmpeg subtitles-Filter ins Video eingebrannt.
  • F-69 Konfigurierbare Stil-Optionen: Schriftgröße, Farbe, Umrissfarbe, Position.
  • F-70 In der Sequenz-Datei pro Clip aktivierbar: auto_subtitles: true.
  • F-71 Alternativ: bestehende .srt-Datei direkt einbrennen ohne Whisper.

10.3 Intelligentes Schneiden (Smart Cut)

  • F-72 Füllwort-Erkennung: Deutsche und englische Füllwörter ("äh", "ähm", "also", "halt", "uh", "um") werden im Transkript erkannt und als Schnitt-Kandidaten markiert.
  • F-73 Fehlstart-Erkennung: Sätze die abbrechen und neu begonnen werden, werden erkannt (Heuristik: kurzes Segment + Pause + ähnlicher Neubeginn).
  • F-74 Pausen-Kürzung: Pausen zwischen Segmenten werden auf eine konfigurierbare Maximaldauer gekürzt (Standard: 1.0s → 0.3s).
  • F-75 --analyze-only zeigt eine Aufschlüsselung aller erkannten Schnitt-Kandidaten (Typ, Zeitposition, eingesparte Sekunden) ohne das Video zu schneiden.
  • F-76 Jede Schnitt-Kategorie (Füllwörter, Fehlstarts, Pausen) ist einzeln aktivierbar/deaktivierbar.
  • F-77 In der Sequenz-Datei pro Clip aktivierbar: smart_cut: true.

10.4 Auto-Kapitel

  • F-78 Das Whisper-Transkript wird an ein LLM (Claude oder lokales Modell via Ollama) gesendet, das inhaltliche Kapitel mit Titeln erzeugt.
  • F-79 Unterstützte LLM-Provider:
    • anthropic — Claude API (API-Key aus Config oder ANTHROPIC_API_KEY)
    • ollama — lokales Modell (URL und Modellname konfigurierbar)
  • F-80 Export-Formate für Kapitel:
    • YouTube-kompatibel (0:00 Intro, 0:45 Ankunft in Berlin, ...)
    • Als type: text-Einträge für die Sequenz-Datei (Kapitelmarken einblenden)
  • F-81 Maximale Kapitelanzahl konfigurierbar (Standard: 10).

10.5 Highlight-Reel

  • F-82 Transkript + Szenen-Erkennung → LLM bewertet jede Szene nach inhaltlichem Interesse (Schlüsselaussagen, Emotionen, Themenwechsel).
  • F-83 Die besten Szenen werden chronologisch ausgewählt und zu einem Highlight-Video zusammengeschnitten.
  • F-84 Ziel-Dauer des Highlight-Reels ist konfigurierbar (Standard: 60s).
  • F-85 Zwischen Highlight-Szenen werden automatisch Crossfades eingefügt.

10.6 Natürlichsprachliche Sequenz-Erstellung

  • F-86 Eine natürlichsprachliche Beschreibung wird per LLM in eine vollständige sequence.yaml übersetzt.
  • F-87 Das LLM erhält als Kontext: verfügbare Ressourcen (Musik, Intros, Bilder), Dateien im angegebenen Ordner, und das Schema der Sequenz-Datei.
  • F-88 Die generierte Sequenz wird zur Bestätigung angezeigt, bevor optional direkt gerendert wird (--execute).

11. KI-Konfiguration

Neuer Block in config.yaml:

ai:
  whisper_model: "base"
  whisper_language: null
  whisper_device: "auto"
  llm_provider: "anthropic"
  llm_model: "claude-haiku-4-5-20251001"
  anthropic_api_key: null
  ollama_url: "http://localhost:11434"
  ollama_model: "llama3"
  • F-89 Der Anthropic-API-Key wird aus der Config oder der Umgebungsvariable ANTHROPIC_API_KEY gelesen.
  • F-90 Fehlt der API-Key, funktionieren alle Features außer Auto-Kapitel, Highlights und natürlichsprachliche Sequenzen.

12. Neue CLI-Befehle

video-cut smart-cut

video-cut smart-cut --input VIDEO [--output DATEI]
                    [--keep-fillers] [--no-false-starts]
                    [--max-pause 1.0] [--analyze-only]

video-cut transcribe

video-cut transcribe --input VIDEO [--output DATEI.srt]
                     [--model base] [--language de]

video-cut subtitle

video-cut subtitle --input VIDEO [--output DATEI]
                   [--srt DATEI.srt]

video-cut chapters

video-cut chapters --input VIDEO [--output chapters.txt]
                   [--format youtube|sequence]
                   [--inject-titles]

video-cut highlights

video-cut highlights --input VIDEO [--output highlights.mp4]
                     [--duration 60]

video-cut describe

video-cut describe "Beschreibung des gewünschten Videos"
                   [--execute] [--output sequence.yaml]

13. Nicht-funktionale Anforderungen

  • NF-01 Kein GUI — ausschließlich Kommandozeile.
  • NF-02 Alle Video-Operationen laufen über subprocess + ffmpeg/ffprobe; kein proprietäres Video-Framework.
  • NF-03 Temporäre Dateien werden in einem tempfile.TemporaryDirectory() erzeugt und nach Abschluss automatisch gelöscht.
  • NF-04 Fehlermeldungen erscheinen auf stderr; Fortschritts-Ausgaben auf stdout.
  • NF-05 Exit-Code 0 bei Erfolg, 1 bei Fehler.
  • NF-06 Ausgabe-Ordner werden automatisch angelegt, wenn sie nicht existieren.
  • NF-07 Standardauflösung für generierte Clips (Text, Bilder): 1920×1080 @ 25fps, H.264, AAC.
  • NF-08 Das Paket ist via pip install -e . installierbar (PEP 517, setuptools).
  • NF-09 Der Discord-Bot läuft als Langzeit-Prozess; er blockiert nicht den CLI-Betrieb — beide Modi sind unabhängig voneinander nutzbar.
  • NF-10 Discord-Befehle und CLI-Befehle rufen dieselbe interne Logik auf — keine duplizierte Implementierung.
  • NF-11 KI-Features (faster-whisper, anthropic) sind optionale Abhängigkeiten — das Tool funktioniert ohne sie.
  • NF-12 Whisper läuft lokal, keine Daten werden an externe Server gesendet (außer bei LLM-Provider anthropic).

14. Bekannte Einschränkungen

  • E-01 --no-normalize beim merge-Befehl kann zu Kompatibilitätsproblemen führen, wenn die Clips unterschiedliche Codecs oder Framerates haben.
  • E-02 type: folder in der Sequenz-Datei erkennt Dateitypen nur anhand der Dateiendung, nicht des tatsächlichen Inhalts.
  • E-03 Text-Overlays setzen voraus, dass die Standard-Schriftart von ffmpeg (default) auf dem System verfügbar ist; für abweichende Fonts muss fontfile in der drawtext-Option ergänzt werden (aktuell nicht konfigurierbar).
  • E-04 Szenen-Erkennung via split_scenes setzt PySceneDetect und OpenCV voraus; fehlt das Paket, wird eine klare Fehlermeldung ausgegeben.
  • E-05 music.mode: loop wiederholt aktuell nur die erste alphabetische Datei, kein echter Playlist-Loop über mehrere Dateien.
  • E-06 Discord-Uploads sind auf 25 MB begrenzt (Discord-Limit für reguläre Server). Größere Ausgabe-Videos können nur als Pfad-Referenz zurückgemeldet werden.
  • E-07 Slash-Commands müssen einmalig bei Discord registriert werden (bot.tree.sync()); nach Deployment kann die Synchronisation einige Minuten dauern.
  • E-08 Der Bot unterstützt nur einen Server gleichzeitig sinnvoll — allowed_channel_ids verhindert ungewollten Multi-Server-Betrieb.
  • E-09 Whisper-Modelle medium und large-v3 benötigen signifikant mehr RAM/VRAM; auf CPU-only-Systemen empfohlen: tiny oder base.
  • E-10 Füllwort-Erkennung kann kontextabhängige Wörter falsch markieren (z.B. "also" als Satzanfang vs. Füllwort). --analyze-only ermöglicht Review vor dem Schnitt.
  • E-11 Auto-Kapitel und Highlights benötigen einen LLM-API-Zugang (Anthropic oder Ollama). Ohne API-Key sind diese Features deaktiviert.
  • E-12 ffmpeg xfade erfordert ffmpeg >= 4.3. Ältere Versionen fallen auf harten Schnitt zurück.

15. Verifikation

Test Erwartetes Ergebnis
pip install -e . video-cut --help zeigt alle Befehle
video-cut cut --input test.mp4 --remove-silence Stille-freie MP4 im gleichen Ordner
video-cut cut --input test.mp4 --scene-detect Ordner test_scenes/ mit Szenen-Clips
video-cut music --input test.mp4 --config config.yaml MP4 mit Hintergrundmusik aus resources/music/
video-cut batch --input ./videos/ --config config.yaml --remove-silence Alle Videos in output/ ohne Stille
video-cut sequence --seq sequence.yaml --config config.yaml Finales Video gemäß Timeline in output/
video-cut bot --config config.yaml Bot startet, registriert Slash-Commands, wartet auf Befehle
Discord: /cut input:/pfad/test.mp4 remove_silence:true Bot bestätigt Job, verarbeitet Video, meldet Ergebnis zurück
Discord: /status Embed mit aktuellem Job-Status und Warteschlange
Discord: /cancel Laufender ffmpeg-Prozess wird beendet, Bestätigung im Kanal
video-cut transcribe --input test.mp4 SRT-Datei mit Timestamps im gleichen Ordner
video-cut subtitle --input test.mp4 Video mit eingebrannten Untertiteln
video-cut smart-cut --input test.mp4 --analyze-only Aufschlüsselung: Füllwörter, Fehlstarts, Pausen
video-cut smart-cut --input test.mp4 Video ohne Füllwörter und mit gekürzten Pausen
video-cut chapters --input test.mp4 --format youtube YouTube-Kapitel-Beschreibung auf stdout
video-cut highlights --input test.mp4 --duration 60 60-Sekunden-Highlight-Video
video-cut merge --inputs a.mp4 b.mp4 -o out.mp4 --crossfade 0.5 Video mit Crossfade-Übergang
video-cut sequence --seq s.yaml --preview Schnelle 360p-Vorschau
video-cut sequence --seq s.yaml --dry-run Clip-Liste und Dauer-Schätzung ohne Rendering
Reference in New Issue View Git Blame Copy Permalink