nicko1122/auto-subtitle

AutoSubtitle AI – Automatisierung & Agent Skill-Leitfaden

Dieser Skill führt dich durch die Automatisierung der Untertitel-Extraktion, Sprach-zu-Text-Transkription, Liedtext-Zwangsausrichtung (Luna-Pipeline), lokales LLM-Korrekturlesen und GPU-beschleunigtes Video-Hardsub-Einbrennen mit der auto-subtitle CLI und dem FastAPI-Backend.

---

📌 Workflow-Entscheidungsmatrix

Wähle den passenden Befehl oder die passende Pipeline basierend auf den Eingabedateien:

Szenario / Ziel	Empfohlener Befehl	Wichtige Argumente
Gesang / Liedtextausrichtung (Medien + .txt Liedtext)	python src/cli/main.py luna (oder align)	<media> <lyrics.txt> --llm local/api -o <dir>
Sprache / Talk / Video zu Untertiteln (Kein Skript)	python src/cli/main.py pipeline	<media> -d cuda -o <dir>
Nur Audio extrahieren	python src/cli/main.py extract	<video> -o <audio.wav> --sr 16000
Tippfehler / Homophone korrigieren (mit Edge LLM)	python src/cli/main.py proofread	<subtitles.srt> --gpu-layers -1
Untertitel in Video einbrennen (Hardsub)	python src/cli/main.py burn	<video> <subtitles.srt> --css "..."
Schriftarten verwalten (Open-Source-/Windows-Schriften installieren)	python src/cli/main.py fonts	list, install <id/pfad/url>, remove <dateiname>
Web Studio starten	python src/cli/main.py serve	--host 0.0.0.0 --port 8000

---

🛠️ CLI-Befehlsreferenz

1. Luna-Liedtext-Pipeline (luna / align)

Führt die 5-Schritt-Doppelverifikationspipeline aus: Whisper-Akustikmerkmal-Extraktion + stable-ts-Ausrichtung + LLM-Entscheidungsprüfung + +0,16s Lesbarkeits-Padding:

python src/cli/main.py luna inputclip/test_video.mp4 inputclip/audio-org.txt \
    --llm local \
    --output-dir output_luna

Ausgabeergebnisse in --output-dir:

• lyrics.srt: Standard-SRT-Untertitelspur.
• lyrics.vtt: WebVTT-Format für Web-Player.
• lyrics.lrc: Verbessertes LRC-Format mit Millisekunden-Zeitstempeln für Musikplayer.
• lyrics.ass: Formatierte ASS-Untertitel, bereit zum Einbrennen mit FFmpeg.
• cue_evidence.json: Vollständige akustische Nachweise und Konfidenzmetriken pro Zeile.
• review.csv: Detaillierter Bericht über auffällige Zeilen und LLM-Entscheidungen.
• run_manifest.json: SHA-256-Integritäts-Hashes der Quellmedien und Ausgaben.

2. End-to-End-Sprachpipeline (pipeline)

Automatische Sprachpipeline für Talkshows, Podcasts und Vorlesungen:

python src/cli/main.py pipeline inputclip/test_video.mp4 \
    --device cuda \
    --prompt "繁體中文" \
    --max-chars 16 \
    --pause 0.45 \
    --output-dir output/

3. Edge-LLM-Korrekturlesen (proofread)

Führt lokales Qwen2.5-3B-Instruct GGUF mit GPU-Offloading aus, um Spracherkennungsfehler zu korrigieren:

python src/cli/main.py proofread output/video.srt \
    --gpu-layers -1 \
    --batch-size 8 \
    --output output/video.proofread.srt

4. GPU-Hardsub-Video-Einbrennung (burn)

Brennt gestylte ASS-Untertitel direkt in Videoframes mit NVIDIA NVENC-GPU-Beschleunigung ein:

# Verwendung eines Inline-CSS-Strings (Unterstützt Deckkraft, Außenkontur, Schriftart, Box-Modell-Padding, Farben)
python src/cli/main.py burn inputclip/test_video.mp4 output/lyrics.srt \
    --css "font-family: 'Noto Sans CJK TC'; font-size: 36px; color: #FFD700; opacity: 0.85; -webkit-text-stroke: 3px #000; text-shadow: 2px 2px 3px #000; padding: 40px 40px 60px 40px;" \
    -o output/final_burned.mp4

# Oder mit einem externen CSS-Stylesheet:
python src/cli/main.py burn inputclip/test_video.mp4 output/lyrics.srt \
    --css-file styles/youtube_style.css \
    -o output/final_burned.mp4

# Oder mit expliziten Flags:
python src/cli/main.py burn inputclip/test_video.mp4 output/lyrics.srt \
    --font "jf-openhuninn-2.0" \
    --size 38 \
    --color "#FFFFFF" \
    --opacity 0.9 \
    --outline 3.0 \
    --outline-color "#000000" \
    --direction horizontal \
    --valign bottom \
    --halign center

5. Schriftartenverwaltung (fonts)

# Alle verfügbaren, installierten und Windows-Systemschriftarten auflisten
python src/cli/main.py fonts list

# Beliebte Open-Source-Schriftarten nach Preset-ID installieren:
# Optionen: openhuninn (粉圓體), lxgw-wenkai (霞鶩文楷), iansui (芫荽體), win-msjhbd (微軟正黑粗體)
python src/cli/main.py fonts install openhuninn

# Von einer URL oder lokalen Datei installieren:
python src/cli/main.py fonts install https://example.com/font.ttf
python src/cli/main.py fonts install /pfad/zu/benutzerdefinierte_schriftart.otf

---

🤖 Automatisierungsrezepte

Rezept 1: Alle Videos in einem Verzeichnis stapelverarbeiten (Bash)

#!/usr/bin/env bash
set -e
INPUT_DIR="./raw_videos"
OUTPUT_DIR="./dist_videos"
mkdir -p "$OUTPUT_DIR"

for video in "$INPUT_DIR"/*.mp4; do
  [ -f "$video" ] || continue
  filename=$(basename "$video")
  stem="${filename%.*}"
  lyrics="$INPUT_DIR/$stem.txt"
  
  echo "🚀 Verarbeite: $filename"
  
  if [ -f "$lyrics" ]; then
    # Pipeline mit Liedtextskript
    python3 src/cli/main.py luna "$video" "$lyrics" --output-dir "$OUTPUT_DIR/$stem" --llm local
    sub_file="$OUTPUT_DIR/$stem/lyrics.srt"
  else
    # Sprachpipeline ohne Skript
    python3 src/cli/main.py pipeline "$video" -d cuda --output-dir "$OUTPUT_DIR/$stem"
    sub_file="$OUTPUT_DIR/$stem/$stem.srt"
  fi
  
  # Hardsubs mit Branding-Style einbrennen
  python3 src/cli/main.py burn "$video" "$sub_file" \
    --css "font-size: 34px; color: #FFFFFF; opacity: 0.9; -webkit-text-stroke: 2.5px #000; text-shadow: 2px 2px #000;" \
    -o "$OUTPUT_DIR/${stem}_subtitled.mp4"
    
  echo "✔ Fertig: $stem"
done

Rezept 2: Python-Skript zur Untertitelgenerierung

from pathlib import Path
from src.core.luna_pipeline import run_luna_pipeline
from src.core.video_burner import burn_subtitles_to_video
from src.schemas.subtitle import SubtitleStyle

media_file = "inputclip/test_video.mp4"
lyrics_file = "inputclip/audio-org.txt"
out_dir = Path("output_automation")

# 1. Luna-Doppelverifikations-Pipeline ausführen
track = run_luna_pipeline(
    audio_path=media_file,
    lyrics_source=lyrics_file,
    output_dir=str(out_dir),
    llm_provider="local"
)

# 2. Untertitel-Stil mit Deckkraft und Außenkontur definieren
style = SubtitleStyle.from_css(
    "font-size: 36px; color: #FFD700; opacity: 0.85; -webkit-text-stroke: 3px #000;"
)

# 3. Untertitel direkt mit NVENC-GPU einbrennen
burned_mp4 = burn_subtitles_to_video(
    video_path=media_file,
    subtitles_source=str(out_dir / "lyrics.srt"),
    output_path=str(out_dir / "burned_output.mp4"),
    style=style,
    use_gpu=True
)
print(f"Video mit eingebrannten Untertiteln erstellt: {burned_mp4}")

Rezept 3: REST-API-Integration (FastAPI)

Der Server läuft unter http://localhost:8000:

• Transkribieren / Ohne Skript: POST /api/ai/transcribe mit Formularfeldern media_path=..., auto_proofread=true
• Ausrichten / Luna-Pipeline: POST /api/ai/align mit JSON {"media_path": "...", "script_text": "...", "script_mode": "reference", "llm_provider": "local"}
• CSS parsen: POST /api/style/parse-css mit JSON {"css": "font-size: 36px; opacity: 0.8;"}
• Video einbrennen: POST /api/burn mit JSON {"video_path": "...", "subtitle_path": "...", "css": "..."}

---

🎨 CSS-Box-Modell & ASS-Styling-Zuordnung

Bei der Gestaltung von Untertitel-Stilen mit --css:

CSS-Eigenschaft	ASS-Format-Übersetzung	Hinweise
opacity: 0.85	Invertierter Alpha-Hex &H26FFFFFF&	Alpha = round((1 - opacity) * 255). 0=undurchsichtig, 255=transparent.
-webkit-text-stroke: 4px #000	Outline: 2.0, OutlineColour: &H00000000&	Mit paint-order: stroke fill; wächst die Kontur nur nach außen.
text-shadow: 2px 2px 3px #000	Shadow: 2.0, BackColour: &H80000000&	Verwendet den größeren, absoluten Achsenversatz; CSS mit gleicher Achse liefert konsistente Ergebnisse.
writing-mode: vertical-rl	Vertikales Spaltenlayout mit \N-Umbrüchen	Automatischer rechts-nach-links-Umbruch bei Überschreitung der Viewport-Höhe.
text-align: center/left/right	九宮格-Ausrichtungszuordnung (1~9)	Unten-Mitte = 2, Oben-Mitte = 8, Mitte-Mitte = 5.
padding: 50px 40px 60px 40px	MarginV, MarginL, MarginR	Wird in ASS-Pixelabstände relativ zur PlayRes-Auflösung umgewandelt.

---

⚠️ Wichtige Implementierungshinweise

1. GPU-Beschleunigung:
   • Whisper: Alle skriptbasierten, nicht-skriptbasierten und zeitlich fixierten Inferenzen verwenden natives Whisper large-v3-turbo. Das Modell und das Backend sind festgelegt; übergib keine Modell- oder Berechnungstyp-Optionen.
   • Video-Einbrennung: Standardmäßig use_gpu=True versucht FFmpeg h264_nvenc. Verwende CLI --cpu für libx264, wenn NVENC zur Laufzeit nicht verfügbar ist.
2. Liedtext-Mehrzeilen-Strings vs. Dateipfade:
   • run_luna_pipeline akzeptiert entweder einen Dateipfad (.txt) oder einen rohen mehrzeiligen Liedtext-String; die CLI erwartet einen TXT-Pfad. Mehrzeilige Strings werden direkt ohne Dateisystem-Pfadprüfung analysiert.
3. Kein Überschreiben von Quell-Untertiteln:
   • Bei der Generierung von .srt- oder .vtt-Dateien werden Ausgaben in das Zielausgabeverzeichnis geschrieben oder mit .generated.srt suffiziert, falls bereits eine Datei mit demselben Namen existiert.