Subtitles Studio

SKILL: Subtitles Studio — Modulare Bibliothek für dynamische Untertitel (subtitles_studio)

1. Überblick für die KI

Offizielles Repository: https://github.com/NicolasCoder/subtitles_studio.git

Dieser Ordner ist ein 100% unabhängiger und gemeinsam nutzbarer Werkzeugkasten zum Erstellen dynamischer Lockup-Untertitel (ein riesiges Hauptwort in der Mitte mit kleineren Wörtern, die in die tatsächlichen Zwischenräume der Ober- und Unterlängen der Schrift eingepasst sind) für HyperFrames (1080x1920 @ 30fps).

Ordnerstruktur

subtitles_studio/
├── SKILL.md                        # Dieses vollständige Handbuch für KI-Agenten
├── README.md                       # Kurzanleitung für Menschen
├── requirements.txt                # fonttools, brotli, Pillow, numpy
├── cli.py                          # Fertige Kommandozeilen-Schnittstelle
├── fonts/                          # Lokale, vorverpackte .woff2-Schriftarten (+ automatischer Download von Google Fonts)
├── caption_kit/                    # Importierbares Python-Paket
│   ├── __init__.py                 # Öffentliche API
│   ├── nesting.py                  # Engine für echte Glyphen-Geometrie + Auto-Download von Google Fonts
│   ├── grouper.py                  # Intelligente Wort-für-Wort-Gruppierung (hold >= 0.38s, Anti-Flimmern)
│   ├── renderer.py                 # HTML/CSS/GSAP-Compiler und dynamischer Lader aus dem styles/-Ordner
│   └── transcribe.py               # Wort-für-Wort-Transkription (CrisperWhisper / faster-whisper / whisper)
├── styles/                         # STIL-MODULE (1 .py- oder .json-Datei = 1 gemeinsam nutzbarer Stil!)
│   ├── _TEMPLATE_NOVO_ESTILO.py    # Kommentierte Vorlage zum Erstellen neuer Stile
│   ├── bold_ciano.py               # Bold Social — Cyan (#3de0c8)
│   ├── bold_vermelho.py            # Bold Social — Rot (#ff3355)
│   ├── bold_roxo.py                # Bold Social — Lila (#b855ff)
│   ├── bold_dourado.py             # Bold Social — Gold (#ffd24a)
│   ├── editorial.py                # Editorial Mix (Inter 900 + Playfair Display Italic)
│   ├── gold_script.py              # Gold Script (Pinyon Script + Oswald)
│   └── poster_impact.py            # Poster Impact (League Gothic + Montserrat 900)
└── examples/                       # Fertige Beispiele zum Testen (auf Portugiesisch)
    ├── demo_words_pt.json          # Wörter mit Zeitstempeln (Portugiesisch)
    └── demo_groups_pt.json         # Lockup-/Plain-Gruppen (Portugiesisch)

---

2. Verwendung über die Kommandozeile (cli.py)

# 1. Alle installierten Stile im styles/-Ordner auflisten
python cli.py --list-styles

# 2. Eine schnelle Demo für jeden Stil generieren
python cli.py --demo --style bold_roxo

# 3. Aus einem JSON mit Wörtern und Zeitstempeln (word, start, end) generieren
python cli.py --words examples/demo_words_pt.json --style bold_vermelho --out output/mein_test

# 4. Die Akzentfarbe im Handumdrehen wechseln, ohne den Stil bearbeiten zu müssen
python cli.py --words examples/demo_words_pt.json --style bold_ciano --accent "#00ff88"

# 5. Ein Video/Audio transkribieren (.mp4/.wav/.mp3) und synchronisierte Untertitel generieren
python cli.py --media mein_video.mp4 --lang pt --style bold_dourado --video mein_video.mp4

---

3. Verwendung über Python (Einbettung in ein HyperFrames-Projekt)

Wenn du eine vollständige Komposition in HyperFrames erstellst (mit A-Roll, B-Roll, Bewegungen, Soundeffekten und Musik), importiere caption_kit und verwende render_embeddable():

import sys
sys.path.insert(0, "pfad/zu/subtitles_studio")

from caption_kit import build_groups_from_words, render_embeddable

# 1. `words` ist eine Liste [{"word": "Criar", "start": 0.15, "end": 0.42}, ...]
groups = build_groups_from_words(words, min_hold=0.38)

# 2. Erzeugt CSS, DOM (mit internen <span>-Elementen für null Lint-Warnungen) und GSAP-JS:
caps_css, caps_dom, caps_js, report = render_embeddable(
    groups,
    prefix="v1",                 # Eindeutiges Präfix für IDs (#v1-g0, #v1-g1...)
    style_name="bold_vermelho",  # Beliebige Datei in styles/<name>.py
    accent_override=None,        # Oder z. B. "#ff3355" übergeben, um nur die Farbe zu ändern
    y_lockup=0.74,               # Sicherer Bereich für Reels (1300-1560px bei 1080x1920)
    y_plain=0.75,
    track_index=3,
    z_index=95,
)

Danach musst du nur noch Folgendes einfügen:

• {caps_css} in den <style>-Tag der Komposition;
• {caps_dom} in das <div id="root" ...>;
• {caps_js} in den <script>-Tag direkt nach const tl = gsap.timeline({ paused: true });.

---

4. Erstellen eines neuen gemeinsam nutzbaren Stils (Plug-in-System in styles/)

Das Stilsystem wurde für 100% Plug-and-Play entwickelt:

• Jede .py- (oder .json-) Datei im Ordner styles/, deren Name nicht mit _ beginnt, wird automatisch von load_styles() erkannt.
• Um auf Anfrage des Benutzers einen neuen Stil zu erstellen:
  1. Kopiere styles/_TEMPLATE_NOVO_ESTILO.py nach styles/<stilname>.py.
  2. Bearbeite das Dictionary STYLE = { ... }.
  3. Wenn du eine neue Schriftart von Google Fonts verwendest (z. B. "Bebas Neue", "Poppins", "Syne"), musst du sie nicht manuell herunterladen: Die Engine caption_kit/nesting.py lädt die .woff2-Dateien bei der ersten Ausführung automatisch von Google Fonts herunter und speichert sie in fonts/<familie>/!
  4. Damit der Benutzer diesen Stil mit jemand anderem teilen kann, reicht es, diese eine Datei styles/<stilname>.py zu versenden!

Anatomie des STYLE-Dictionary

STYLE = {
    "id": "neon_cyber",
    "label": "Neon Cyber (Montserrat 900 + Grünes Glühen)",
    # Hauptwort (Mitte des Lockups)
    "main_font": "Montserrat",
    "main_weight": 900,
    "main_style": "normal",
    "main_track": -0.05,
    "main_case": "none",           # WICHTIG: "none" verwenden, um Ober-/Unterlängen zu erhalten und das Einpassen zu ermöglichen! Verwende "upper" nur, wenn "nest_mode": "overlap".
    "main_lh": 0.80,
    "main_css": "color:#ffffff;text-shadow:0 10px 34px rgba(0,0,0,.6);",
    "max_px": 280,
    # Kleine Stützwörter (oben und unten)
    "small_font": "Inter",
    "small_weight": 800,
    "small_style": "normal",
    "small_track": -0.03,
    "small_case": "none",
    "small_css": "color:#ffffff;text-shadow:0 5px 20px rgba(0,0,0,.6);",
    "small_scale": 0.44,           # 0.25 bis 0.50 der Hauptwortgröße
    # Einfacher durchlaufender Untertitel
    "plain_font": "Inter",
    "plain_weight": 800,
    "plain_style": "normal",
    "plain_case": "none",
    "plain_css": "color:#ffffff;text-shadow:0 5px 20px rgba(0,0,0,.6);",
    # Akzentfarbe und Glanz
    "accent": "#00ff88",
    "accent_extra_css": "text-shadow:0 0 24px rgba(0,255,136,0.55);",
    "shine": ("#ffffff", "rgba(0,255,136,.9)"),
    # Geometrie und Animationen
    "tilt": (-2, 2),               # Neigung (Grad) der oberen und unteren Zeile
    "clear": 0.03,                 # Minimaler Abstand zwischen den Farben
    "variants": ("slam", "letters", "rise", "blur"),
}

---

5. Goldene Qualitätsregeln (Aus der Praxis gelernt)

1. Lesezeit (Minimale Haltezeit): Der Gruppierer (caption_kit/grouper.py) garantiert mindestens 0.38s, in denen der vollständige Satz auf dem Bildschirm angezeigt wird, bevor der Block gewechselt wird. Bei schneller Sprache komprimiert er den Stagger der Wortanimationen, sodass das Ende des Satzes nie abgeschnitten wird.
2. Chronologische Reihenfolge: Die Zeilen erscheinen immer in der tatsächlichen Reihenfolge, in der sie gesprochen werden (above → main → below).
3. Sicherer Bereich für Instagram Reels / TikTok (1080x1920):
   • Standardmäßig y_lockup=0.74 (~1420px), bleibt im sicheren Bereich 1300–1560px (unterhalb des Gesichts und der Motion-Karten, oberhalb der unteren Reels-Buttons).
4. Audio-Synchronisation in HyperFrames:
   • Wenn das Video Audio verwendet, das in mehrere Segmente geschnitten ist, verwende niemals mehrere <audio>-Tags, die mit data-media-start auf dieselbe Datei verweisen (das verschiebt das Audio in HyperFrames). Schneide das Audio immer vorher in eine einzige kontinuierliche .wav-Datei und verwende einen einzelnen <audio data-start="0.000">-Tag.