608 lines
26 KiB
Markdown
Executable File
608 lines
26 KiB
Markdown
Executable File
# 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`:
|
||
|
||
```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
|
||
|
||
```bash
|
||
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`:
|
||
|
||
```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 |
|