Communitygithub.com

zgyk4167/karaoke-subtitles

Brennt wortgenaue Karaoke-Untertitel in ein englischsprachiges Video ein. Jedes Wort wechselt von Weiß zu Grün und wird kurz vergrößert, während es gesprochen wird. Optional werden kurze, inline vereinfachte chinesische Glossen in Blau für Fachbegriffe, schwierige Wörter, Phrasal Verbs und Redewendungen hinzugefügt, die auf chinesische Lernende auf CET-6-Niveau (China's College English Test Band 6, obere Mittelstufe) zugeschnitten sind.

Was ist karaoke-subtitles?

Das Skill-System 'karaoke-subtitles' automatisiert die Erstellung und Einbrennung von wortgenauen Karaoke-Untertiteln in englische Videos. Es nutzt eine Pipeline: Video → 16 kHz Audio → DashScope ASR mit Wort-Zeitstempeln → LLM wählt Begriffe aus und schreibt chinesische Glossen → ASS-Karaoke-Untertitel → ffmpeg und libass brennen sie ein. Nützlich für Sprachlerner, die englische Videos mit hervorgehobenen, synchronisierten Untertiteln und optionalen chinesischen Erklärungen für schwierige Wörter sehen möchten. Es unterstützt lokale Videodateien und URLs von YouTube, X oder anderen Seiten, die yt-dlp unterstützt. Benötigt lediglich einen Alibaba Cloud Model Studio (DashScope) API-Key; kein Storage-Bucket ist erforderlich. Die Bedienung erfolgt über ein nicht-interaktives CLI (`scripts/pipeline.py`), das alle Schritte von der Transkription bis zum Rendern ausführt, dabei Fehler behandelt und nach Unterbrechungen fortsetzt.

Funktioniert mit~Claude Code~Codex CLI~Cursor
npx skills add zgyk4167/karaoke-subtitles

In Ihrer bevorzugten KI fragen

Öffnet einen neuen Chat, in dem dieser Agent-Skill bereits geladen ist.

Dokumentation

Karaoke-Untertitel

Pipeline: Video → 16 kHz Audio → DashScope ASR mit Wort-Zeitstempeln → LLM wählt Begriffe aus und schreibt chinesische Glossen → ASS-Karaoke-Untertitel → ffmpeg und libass brennen sie ein.

Die gesamte Arbeit erfolgt über ein nicht-interaktives CLI, scripts/pipeline.py. Pfade in dieser Datei sind relativ zum Skill-Verzeichnis. Führen Sie jeden Befehl von einem beliebigen Verzeichnis aus, mit dem Skill-Pfad davor, z.B. python3 /pfad/zu/karaoke-subtitles/scripts/pipeline.py doctor.

Vor dem ersten Durchlauf

  1. Führen Sie python3 scripts/pipeline.py doctor aus. Exit-Code 0 bedeutet Bereitschaft. Wenn ein Schlüssel gesetzt ist, wird eine kostenlose Anfrage gestellt, um zu prüfen, ob DASHSCOPE_BASE mit der Region des Schlüssels übereinstimmt. Es wird nichts hochgeladen oder berechnet. Fügen Sie --offline hinzu, um diese Anfrage zu überspringen.
  2. Wenn Exit-Code 3 erscheint, führen Sie bash scripts/install.sh aus und beheben Sie jede FAIL-Zeile, die ausgegeben wird. Wenn das Skript angibt, dass sudo ein Passwort benötigt, oder der API-Schlüssel fehlt, stoppen Sie und fragen Sie den Benutzer. Bitten Sie den Benutzer niemals, den Schlüssel in den Chat einzufügen; bitten Sie ihn, ihn in die .env-Datei zu setzen (siehe .env.example).
  3. Einrichtungsdetails und Einstellungen: references/prerequisites.md.

Bestätigung mit dem Benutzer

  • Das Video: eine lokale Datei oder eine URL. Der Benutzer muss das Recht haben, es zu verarbeiten.
  • Glossen an (Standard) oder aus (--no-annotate).
  • Wohin das Ergebnis geht. Standard: Rückgabe des Ausgabedateipfads.

Behalten Sie den visuellen Stil bei, es sei denn, der Benutzer wünscht eine Änderung. Stilwerte: references/ass-style.md.

Ausführen

Ein Befehl führt alles aus und wird nach einer Unterbrechung fortgesetzt:

python3 scripts/pipeline.py all "<url-oder-datei>" --work ./job [--no-annotate]

Oder führen Sie die Schritte einzeln aus. Jeder Schritt schreibt feste Dateinamen in das Job-Verzeichnis und überspringt Arbeiten, deren Ausgabe bereits existiert. Fügen Sie --force hinzu, um einen Schritt zu wiederholen. Jeder Unterbefehl hat --help.

SchrittSchreibtKostenpflichtige API
fetch <url-oder-datei>src.mp4nein
transcribe [--audio-url URL]audio.mp3, asr_task.json, transcription.jsonja
annotateannotations.jsonja
ass [--no-pop] [--no-annotate]subs.assnein
render [--segment 1200] [--out DATEI]karaoke.mp4nein

Die ASR-API liest Audio von einer URL. Standardmäßig lädt transcribe job/audio.mp3 in den kostenlosen temporären Speicher von DashScope hoch. Dieser Speicher behält die Datei für 48 Stunden, und nur das ASR-Modell dieses Kontos kann sie lesen. Es wird kein Bucket oder zusätzliche Einstellung benötigt. Wenn der Benutzer seinen eigenen Speicher bevorzugt, lädt entweder AUDIO_URL_CMD in .env die Datei hoch und gibt eine URL aus, oder Sie übergeben --audio-url URL.

Fortschritt geht nach stderr. Jeder Schritt gibt den Pfad seiner Ausgabe auf stdout aus.

Exit-Codes

CodeBedeutungWas zu tun ist
0ErledigtFortfahren.
2NutzungsfehlerLesen Sie die --help des Unterbefehls.
3Umgebung nicht bereitFolgen Sie der next:-Zeile oder führen Sie doctor aus. Fragen Sie den Benutzer nach einem Schlüssel oder sudo oder bitten Sie ihn, die Regionseinstellung zu korrigieren.
4Remote-Dienst fehlgeschlagenFolgen Sie der next:-Zeile. Die erneute Ausführung desselben Befehls behält abgeschlossene Arbeiten bei.
5Eingabe eines früheren Schritts fehltFühren Sie den in der next:-Zeile genannten Schritt aus.
1Unerwarteter FehlerLesen Sie die Tool-Ausgabe oberhalb des Fehlers.

Lange Aufträge

Transkription und Rendern können länger dauern, als ein Shell-Tool erlaubt. Führen Sie den Befehl im Hintergrund mit einer Logdatei aus, z.B. nohup python3 scripts/pipeline.py all "<quelle>" --work ./job > job.log 2>&1 &, und lesen Sie dann das Log, bis es endet. Wenn der Prozess stirbt, führen Sie denselben Befehl erneut aus. Die Transkription setzt die gespeicherte ASR-Aufgabe fort, anstatt erneut zu bezahlen; das Rendern verwendet bereits abgeschlossene Segmente wieder.

Überprüfung vor der Auslieferung

Extrahieren Sie einen Frame aus der Mitte der Ausgabe (ffmpeg -ss <sekunden> -i job/karaoke.mp4 -frames:v 1 check.jpg) und sehen Sie ihn sich an, wenn Sie Bilder anzeigen können. Wenn die Quelle bereits eingebrannte Untertitel hat, informieren Sie den Benutzer und bieten Sie zwei Optionen an: sie mit einem Unschärfebalken abdecken oder die neuen Untertitel nach oben verschieben.

Regeln

  • Drucken, protokollieren oder committen Sie niemals DASHSCOPE_API_KEY. doctor meldet nur, ob er gesetzt ist.
  • transcribe und annotate kosten Geld auf dem Konto des Benutzers. Verwenden Sie --force nur dann, wenn der Benutzer zustimmt.
  • Glossen sind nur vereinfachtes Chinesisch. Für Zuschauer, die kein Chinesisch lesen, verwenden Sie --no-annotate.
  • ASR kann Namen und Fachbegriffe falsch verstehen und kann Text in Kleinbuchstaben zurückgeben. Sagen Sie dem Benutzer, dass er die Untertitel überprüfen soll, bevor er das Video teilt.

Verwandte Skills