video-captioner — Animierte Untertitel-Pipeline
Transkribiert Sprache mit Whisper und brennt animierte, wortweise Untertitel in Videos ein. Keine Farbkorrektur – für visuelle Verbesserungen zuerst die video-enhancer-Fähigkeit nutzen.
Pipeline
Eingabevideo → Whisper-Transkription → pycaps-Untertitel-Rendering → Ausgabevideo mit Untertiteln
Untertitel-Stile
Drei Optionen:
- Standard (kein Flag) — pycaps-eigener minimalistischer Stil: einfacher weißer Text, keine Effekte.
- Futuristisch (mitgeliefert) —
--css scripts/futuristic.css— abwechselnd gold/magenta Untertitel mit Glow-Effekt und serifenloser Schrift. Gut geeignet für Technik-, Gaming- oder energiegeladene Inhalte. - Benutzerdefiniert — Der Benutzer kann einen beliebigen CSS-Dateipfad über
--css /pfad/zu/custom.cssangeben.
Falls der Benutzer keinen Untertitel-Stil erwähnt hat, fragen Sie, ob er den Standard-Look, den futuristischen Stil oder eine benutzerdefinierte CSS-Datei wünscht.
Statische Untertitel
Verwenden Sie --caption, um vordefinierten Text zu bestimmten Zeitstempeln hinzuzufügen, anstatt Audio zu transkribieren:
--caption "START-ENDE: TEXT"
Format:
- Zeiten im Format
M:SSoderMM:SS(z. B.0:05= 5 Sekunden,1:30= 90 Sekunden) - Mehrere Untertitel:
--captionmehrfach verwenden - Wenn sowohl statische Untertitel als auch eine Transkription angegeben werden, haben die statischen Untertitel Vorrang.
Beispiel:
uv run python scripts/caption_service.py \
--input ./eingabe --output ./ausgabe \
--caption "0:01-0:05: Hallo Welt" \
--caption "0:10-0:20: Dies ist eine Demo" \
--css scripts/futuristic.css
Untertitel-Stil
Das Styling wird über JSON-Konfigurationsdateien verwaltet. Bei statischen Untertiteln wird das Styling automatisch angewendet.
Standard-Styling
Wenn keine --style-config angegeben ist, wird config.default.json verwendet:
- Hintergrund: Weiß (
#FFFFFF) - Textfarbe: Blau (
#0066FF) - Schriftart:
auto– verwendet zuerst eine verfügbare Markenschriftart mit dem Tagcaption, fällt dann auf Courier New zurück - Padding:
10px 15px - Margin:
0
Verwenden einer Stil-Konfiguration
Wechseln Sie den Stil durch Übergabe einer Konfigurationsdatei:
# Dark-Mode-Stil verwenden
uv run python scripts/caption_service.py \
--input ./eingabe --output ./ausgabe \
--caption "0:01-0:05: Hallo" \
--style-config config.dark-mode.json
Enthaltene Konfigurationen:
config.default.json— weißer Hintergrund, blaue Schrift, Courier New (Standard)config.dark-mode.json— dunkler Hintergrund, weiße Schrift, größere Schriftgröße
Erstellen benutzerdefinierter Stil-Konfigurationen
Kopieren Sie config.default.json und ändern Sie es:
{
"caption_bg_color": "#000000",
"caption_color": "#FFFFFF",
"caption_font": "auto",
"caption_font_tag": "caption",
"caption_padding": "20px 30px",
"caption_margin": "10px",
"caption_font_size": 48
}
Dann verwenden Sie es:
uv run python scripts/caption_service.py \
--input ./eingabe --output ./ausgabe \
--caption "0:01-0:05: Text" \
--style-config meine-eigene-konfiguration.json
Überschreiben der Konfiguration mit CLI-Flags
CLI-Flags haben Vorrang vor den Werten in der Konfigurationsdatei:
uv run python scripts/caption_service.py \
--input ./eingabe --output ./ausgabe \
--caption "0:01-0:05: Hallo" \
--style-config config.dark-mode.json \
--caption-color "#00FF00" # Überschreibt die Textfarbe der Konfiguration
Referenz der Stil-Konfiguration
| Schlüssel | Typ | Beschreibung |
|---|---|---|
caption_bg_color | string | Hintergrundfarbe (Hex oder CSS-Farbname) |
caption_color | string | Textfarbe (Hex oder CSS-Farbname) |
caption_font | string | auto, Schriftfamilie oder Pfad zu .ttf, .otf, .woff, .woff2-Datei |
caption_font_tag | string oder null | Markenschriftart-Tag, das von brand-manager bevorzugt werden soll (caption, body, heading usw.) |
caption_padding | string | CSS-Padding (z. B. "10px 15px") |
caption_margin | string | CSS-Margin (z. B. "0") |
caption_font_size | integer oder null | Schriftgröße in Pixeln (null = automatische Skalierung) |
Verfügbare Schriftarten
Systemschriftarten können nach Namen angegeben werden:
DejaVu Sans/DejaVu Sans Bold/DejaVu SerifLiberation Sans/Liberation MonoCourier NewUbuntu Mono- Jeder TTF-Dateipfad:
/pfad/zu/schriftart.ttf
Oder wählen Sie aus Markenschriftarten in skills/brand-manager/brand-assets/asset-manifest.json.
Wenn caption_font auf auto gesetzt ist, liest die Fähigkeit das Marken-Manifest (oder CLAW_BRAND_ASSETS_DIR, falls gesetzt) und verwendet die erste verfügbare Schriftart, die mit caption_font_tag getaggt ist; falls keine getaggte Schriftart existiert, werden Markenschriftarten mit den Tags caption, body, heading oder bold probiert, dann fällt sie auf Courier New zurück. Wenn die aufgelöste Markenschriftart ein Dateipfad ist, enthält das generierte CSS eine @font-face-Regel, damit pycaps sie rendern kann.
So führen Sie es aus
Abhängigkeiten installieren (nur beim ersten Mal):
cd "$SKILL_DIR" && uv sync
Hinweis: Der erste Durchlauf wird langsam sein (möglicherweise mehrere Minuten), da pycaps das Whisper-Spracherkennungsmodell herunterlädt. Warnen Sie den Benutzer vor Beginn darüber.
Dann verarbeiten Sie Videos:
cd "$SKILL_DIR" && uv run python scripts/caption_service.py \
--input <pfad/zur/eingabe> \
--output <pfad/zur/ausgabe> \
[--css scripts/futuristic.css]
Häufige Aufrufe
# Standard-minimalistische Untertitel (Whisper-Transkription)
uv run python scripts/caption_service.py --input ./eingabe --output ./ausgabe
# Futuristischer Stil
uv run python scripts/caption_service.py \
--input ./eingabe --output ./ausgabe \
--css scripts/futuristic.css
# Benutzerdefiniertes CSS
uv run python scripts/caption_service.py \
--input ./eingabe --output ./ausgabe \
--css /pfad/zu/mein.css
# Statische Untertitel mit Standard-Styling (weißer Hintergrund, blaue Schrift, Courier New)
uv run python scripts/caption_service.py \
--input ./eingabe --output ./ausgabe \
--caption "0:01-0:05: Abonnieren für mehr" \
--caption "0:10-0:15: Folge uns auf Instagram"
# Statische Untertitel mit Dark-Mode-Stil
uv run python scripts/caption_service.py \
--input ./eingabe --output ./ausgabe \
--caption "0:01-0:05: Hallo Welt" \
--caption "0:10-0:20: Dies ist eine Demo" \
--style-config config.dark-mode.json
# Statische Untertitel mit benutzerdefinierter Stil-Konfiguration
uv run python scripts/caption_service.py \
--input ./eingabe --output ./ausgabe \
--caption "0:01-0:05: Benutzerdefinierter Text" \
--style-config meine-eigene-konfiguration.json
# Statische Untertitel mit CLI-Flag-Überschreibungen
uv run python scripts/caption_service.py \
--input ./eingabe --output ./ausgabe \
--caption "0:01-0:05: Hallo" \
--style-config config.dark-mode.json \
--caption-color "#00FF00"
# Watch-Modus (prüft alle 10s auf neue Videos)
uv run python scripts/caption_service.py --input ./eingabe --output ./ausgabe --watch
Nach der Ausführung
Melden Sie dem Benutzer:
- Wie viele Videos erfolgreich verarbeitet wurden und wie viele fehlgeschlagen sind.
- Den vollständigen Pfad zum Ausgabeverzeichnis.
- Falls Videos fehlgeschlagen sind, nennen Sie sie explizit.
Randfälle
- Wenn
ffmpegnicht installiert ist: Sagen Sie dem Benutzer, er solle es installieren (sudo pacman -S ffmpegunter Arch/CachyOS,brew install ffmpegunter macOS,sudo apt install ffmpegunter Ubuntu) - Wenn
uvnicht installiert ist: Verweisen Sie auf https://docs.astral.sh/uv/getting-started/installation/ - Wenn das Eingabeverzeichnis leer ist: Melden Sie dies deutlich, anstatt still zu beenden
- Der erste Durchlauf lädt das Whisper-Modell herunter (~140 MB für
tiny, ~1,5 GB fürlarge) — dies ist einmalig
Remote-Transkription
Diese Fähigkeit unterstützt jetzt eine optionale Remote-Transkription bei gleichzeitig lokalem pycaps-Rendering.
- Das Standardverhalten bleibt vollständig lokal: Whisper-Transkription innerhalb von pycaps + lokales Rendering
- Der Remote-Modus ersetzt nur den Transkriptionsschritt
- Das Rendern von Untertiteln, Vorlagen und CSS-Handling bleiben lokal
Unterstützte Anbieter
huggingfacereplicate
Konfigurations-/CLI-Schlüssel
| Schlüssel | Standard | Hinweise |
|---|---|---|
transcription_provider | null | null behält den lokalen Whisper-in-pycaps-Fluss bei |
remote_model | null | Optionaler anbieterspezifischer Überschreibung der Transkriptionsmodell |
hf_token_env | HF_TOKEN | Name der Umgebungsvariablen für die HuggingFace-Authentifizierung |
replicate_api_key_env | REPLICATE_API_TOKEN | Name der Umgebungsvariablen für die Replicate-Authentifizierung |
remote_timeout_seconds | 300 | Zeitüberschreitung für Remote-Aufrufe |
Beispiele
# HuggingFace-Remote-Transkription + lokales pycaps-Rendering
export HF_TOKEN=hf_ihr_token
uv run python scripts/caption_service.py --input ./eingabe --output ./ausgabe --transcription-provider huggingface
# Replicate-Remote-Transkription + lokales pycaps-Rendering
export REPLICATE_API_TOKEN=r8_ihr_token
uv run python scripts/caption_service.py --input ./eingabe --output ./ausgabe --transcription-provider replicate --remote-model <replicate-modell-slug>
Hinweise
- Es gibt keinen stillen Rückfall in den lokalen Modus, wenn die Remote-Authentifizierung/-Konfiguration fehlt
- Vorhandene lokale CLI-Aufrufe bleiben gültig
- Wenn Sie
--transcription-providernicht setzen, verwendet pycaps weiterhin seinen integrierten Whisper-Fluss