EdgeSpeak Karaoke
Erstelle Karaoke-Untertitel aus einer einzigen EdgeSpeak-Transkriptionsanfrage. Verwende die gebündelten, abhängigkeitsfreien Node.js-Skripte zur deterministischen ASS-Generierung, Echtzeit-Stilvorschau und FFmpeg-Rendering.
Lass den Benutzer das Aussehen wählen
Sammle den Quellpfad, den Ausgabeort und ob der Benutzer ASS, eingebrannte Untertitel oder beides möchte. Der Stil ist die eine Entscheidung, die der Benutzer sehen und ablehnen kann – behandle sie daher standardmäßig als seine Entscheidung:
- Explizit: Ehre die benannte Vorgabe oder Überschreibungen. Verfügbare Vorgaben sind
classic,minimal,boxedundhigh-contrast. - Auto: Nur wenn der Benutzer die Entscheidung tatsächlich abgibt – „entscheide du”, „was auch immer funktioniert”, „mach es einfach schnell”, „verwende die Standardeinstellung”. Wähle aus der Tabelle unten und fahre fort, ohne zu blockieren.
- Vorschau, dann Frage – die Standardeinstellung, wenn der Benutzer keine Stilpräferenz angegeben hat. Rendere jede Vorgabe auf echten Quellframes, zeige die PNGs mit der Bildanzeigefunktion der Laufzeitumgebung an und stelle eine kompakte Frage. Ein Terminal kann Pfade und Beschreibungen auflisten, aber ANSI-Text ist keine getreue visuelle Vorschau.
Stille ist keine Delegation. Ein Benutzer, der den Stil nie erwähnt hat, hat die Optionen normalerweise nicht gesehen, anstatt sich entschieden zu haben, sie zu überspringen. Fragen kostet einen kurzen Austausch; falsches Raten kostet ein Neu-Rendering des gesamten Videos, und bei eingebrannten Untertiteln ist das der teure Weg.
Für die zweisprachige Ausgabe ist die Frage, welche Sprache oben liegt, die gleiche Art von sichtbarer Entscheidung – integriere sie in diese eine Frage, anstatt zweimal zu fragen.
Rendere niemals Vorschauen, ohne sie anzuzeigen. --preview-media rendert alle vier Vorgaben bei jedem Durchlauf, sodass der vollständige Vergleich sofort nach Abschluss des Befehls auf der Festplatte existiert. Ein PNG zu öffnen, stillschweigend auszuwählen und nur den Gewinner zu melden, verbirgt einen Kompromiss, den der Benutzer sehen sollte.
Für den Automatikmodus – und um die zusammen mit den Vorschauen angebotene Empfehlung zu untermauern – untersuche repräsentative Quellframes und verwende diese Standardeinstellungen:
| Filmmaterial | Vorgabe |
|---|---|
| Allgemeine Landschaft oder gemischte Inhalte | classic |
| Sauberer, meist dunkler Hintergrund | minimal |
| Bewegter, heller Hintergrund, Folien oder Bildschirmaufzeichnung | boxed |
| Vertikaler/mobiler oder durchgehend schwieriger Hintergrund | high-contrast |
Wenn die Helligkeit über das Quellmaterial schwankt – dunkle Szenen und helle Szenen im selben Video –, entscheidet kein einzelner Frame die Wahl. Rendere Vorschauen zu zwei kontrastierenden Zeitstempeln und vergleiche beide, denn eine Vorgabe, die auf einem hellen Frame gewinnt, kann auf einem dunklen unsichtbar werden.
Anweisungen der aktuellen Anfrage haben Vorrang. Lies, falls vorhanden, auch optionale Einstellungen aus .edgespeak-skills/edgespeak-karaoke/EXTEND.md, dann ~/.edgespeak-skills/edgespeak-karaoke/EXTEND.md; Projekteinstellungen haben Vorrang vor Benutzereinstellungen. Nützliche Einstellungen umfassen Vorgabe, Schriftart, Schriftgröße, ASS-Farben, Rand, Ausgabeformat und Qualität.
Einmal transkribieren und ausrichten
-
Bestätige, dass die Quelle existiert, und untersuche ihre Dauer, Abmessungen und Container mit
ffprobe. -
Rufe
edgespeak_transcribe_fileeinmal auf:{ "path": "/absoluter/pfad/quellmedium", "timestamps": "word", "start_margin": 0, "end_margin": 0 }Füge
min_chars/max_charsnur hinzu, wenn der Benutzer unterschiedliche Untertitellängen anfordert. Fügemodelnur hinzu, wenn der Benutzer eines nennt. Wenn die Lokalität wichtig ist, untersucheedgespeak_list_modelsund wähle kein entferntes Modell ohne Zustimmung. -
Rufe
edgespeak_alignnicht auf, nach einer erfolgreichen Transkription mit Wort-Zeitstempeln. Diese Anfrage führt bereits EdgeSpeaks integrierten lokalen Forced-Alignment-Pfad aus und gibtsegments[].words[]zurück. -
Verwende für eine lange MCP-Antwort
artifact_json_path. Verwende für eine Inline-Antwort dasresult-Objekt als JSON. Der Konverter akzeptiert entweder direktes Transkript-JSON oder einen Wrapper mitresult. -
Fordere nicht leeres Wort-Timing in jedem zeitgesteuerten Segment. Erfinde niemals Wort-Timing oder falle stillschweigend auf Segment-Timing zurück.
Verwende edgespeak_align nur, wenn der Benutzer ein externes finales Transkript geliefert oder den ASR-Text wesentlich bearbeitet hat. Die Ausrichtung muss die endgültige Wortsequenz verwenden; behalte nach Bearbeitungen niemals veraltete Zeitstempel.
Eine Ausrichtung, die den Text nicht platzieren kann, ist ein Fehler, kein leeres Ergebnis: edgespeak_align gibt isError: true zurück mit JSON {"code": "alignment_failed" | "alignment_search_budget_exceeded", ..., "alignment": {...}} und keinen Wörtern (die CLI beendet sich mit einem Exit-Code ungleich null und demselben Code und Objekt in der Fehlerausgabezeile, die mit error: alignment_failed: oder error: alignment_search_budget_exceeded: beginnt). Entscheide nur anhand des alignment-Objekts:
alignment.retry_recommended: true→ rufeedgespeak_alignein weiteres Mal mit"search_effort": "extended"auf (CLI:--search-effort extended). Es sucht breiter, läuft langsamer und verbraucht zusätzlichen Speicher; zitierealignment.estimated_extra_bytes, wenn du es dem Benutzer mitteilst.- Andernfalls oder bei
alignment_search_budget_exceededwiederhole denselben Aufruf nicht. Überprüfe, ob das Transkript zu diesem Medium passt, oder richte einen kürzeren Clip aus. Sieheedgespeak-alignfür die vollständige Liste der Codes und Felder.
Baue niemals Karaoke-Hinweise aus einer fehlgeschlagenen Ausrichtung: keine gleichmäßig verteilten Wörter, kein Zurückfallen auf Segment-Timing, keine aus dem Transkript vor der Bearbeitung übernommenen Zeitangaben.
Voraussetzungen
- Node.js 18 oder neuer für die gebündelten Skripte.
- FFmpeg, erstellt mit
libass, plusffprobe– eine separate ausführbare Datei, die sich ebenfalls im PATH befinden muss. Jede Vorschau und jedes Einbrennen geht durch denass-Filter, daher schlägt ein FFmpeg ohne libass unabhängig von der ausgewählten Vorgabe mitNo such filter: 'ass'fehl. Das Brennen in MP4/MOV/MKV/TS benötigt zusätzlichlibx264; WebM benötigtlibvpxundlibopus. Homebrew und die Pakete der großen Distributionen enthalten alle diese. edgespeak-cli(oder die EdgeSpeak-App) für die Transkription, die auf macOS Apple Silicon, Linux x86_64 und Windows x64 läuft. Installiere unter Windows die EdgeSpeak-Desktop-App, die die CLI enthält. Unter macOS und Linux verweise den Benutzer auf das eigenständige Installationsprogramm unter https://edgespeak.com/docs/cli#install (keine Desktop-App erforderlich; unter Linux erkennt es NVIDIA-GPUs automatisch und installiert eine CUDA-fähige Laufzeitumgebung). Der Benutzer führt das Installationsprogramm aus; führe es nicht selbst aus. DieminCliVersionim Frontmatter ist die älteste CLI, für die dieser Skill geschrieben wurde – wennedgespeak-cli --versionälter ist oder ein dokumentiertes Flag in--helpfehlt, führeedgespeak-cli updateaus.
Wenn ein Lauf aufgrund einer fehlenden Abhängigkeit fehlschlägt, melde, welche Überprüfung fehlgeschlagen ist, anstatt es erneut zu versuchen:
node --version # v18+
ffprobe -version # muss zusammen mit ffmpeg existieren
ffmpeg -filters | grep -w ass # der ASS-Renderer (libass)
ffmpeg -encoders | grep -w libx264 # H.264-Ausgabe
ASS und Vorschauen generieren
Generiere die ausgewählte Vorgabe:
node <skill-verzeichnis>/scripts/karaoke-ass.mjs /pfad/zum/transkript.json \
-o /ausgabe/quelle.karaoke.ass \
--style classic \
--title "Quelltitel"
Um die Wahl zu präsentieren, rendere jede Vorgabe auf einem aktiven Hinweis aus der tatsächlichen Quelle. Dies ist der Standardpfad, kein Sonderfall – und jedes PNG, das es erzeugt, soll angezeigt werden:
node <skill-verzeichnis>/scripts/karaoke-ass.mjs /pfad/zum/transkript.json \
-o /ausgabe/quelle.karaoke.ass \
--style classic \
--preview-media /pfad/zum/quellvideo \
--preview-dir /ausgabe/quelle.karaoke-vorschauen
Verwende --preview-at <sekunden>, wenn ein anderer Frame repräsentativer ist, und führe es zweimal mit unterschiedlichen Zeitstempeln aus, wenn die Quelle helle und dunkle Szenen mischt. Liste Vorgaben mit --list-styles auf. Verfeinere mit --font, --font-size, --margin-v, --primary, --secondary, --outline und --back; ASS-Farben verwenden &HAABBGGRR. Das Skript bewahrt EdgeSpeak-Segmentgrenzen und bildet nur ausgerichtete Dauern/Lücken auf \kf / \k-Tags ab.
Die Abstände zwischen den Wörtern stammen aus dem eigenen text des Hinweises, nicht aus einem Leerzeichen pro Wort. Die erzwungene Ausrichtung hängt die Zeichensetzung an das Wort an, das sie begleitet, sodass jeder Eintrag in words[] eine Teilzeichenkette von text ist und ihre Positionen sich nur vorwärts bewegen – der Generator durchläuft text einmal und verwendet wieder, was zwischen zwei Wörtern tatsächlich steht. Dadurch bleibt high-performance mit Bindestrich erhalten (die Ausrichtung teilt es in high und performance auf, und der Bindestrich gehört zu keinem von beiden) und CJK bleibt ohne Leerzeichen, anstatt 本地转录 als 本 地 转 录 wiederzugeben. Wenn ein Wort in text nicht gefunden werden kann, fällt der Generator auf einzelne Leerzeichen zurück, anstatt zu raten.
Zweisprachiges Karaoke
Wenn das Transkript eine translation für jedes Segment enthält – was edgespeak-translate schreibt – gibt der Generator zwei Zeilen pro Hinweis aus und benötigt kein zusätzliches Flag:
node <skill-verzeichnis>/scripts/karaoke-ass.mjs /pfad/zum/transkript.zh.json \
-o /ausgabe/quelle.karaoke.ass --style boxed
Beide Zeilen befinden sich in einem Dialogue-Ereignis, getrennt durch \N, sodass ASS sie als einen einzigen Block vom gemeinsamen Rand entfernt stapelt. Zwei separate Ereignisse würden jeweils an diesem Rand verankern und sich überlappen.
--layout translation-top(Standard) platziert die Übersetzung über der Quelle;source-topdreht es um, für Zuschauer, die in der Quellsprache mitlesen. Die obere Zeile wird in der Vorgabegröße und die untere mit 72 % gerendert, sodass das Auge so oder so auf der primären Sprache landet.--layout source-onlyignoriert die Übersetzungen und erzeugt die einsprachige Datei.- Nur die Quell-Zeile wird hervorgehoben. Wortzeitangaben beschreiben das Quellaudio, daher erhält die Übersetzung keine
\k-Tags – sie erhält eine einfache Füllung für den gesamten Hinweis. Die Verteilung der Hinweisdauer auf die Zeichen der Übersetzung wäre erfundenes Timing; füge es nicht hinzu. Für echte Wortzeitangaben in der Zielsprache vertone die Übersetzung mit einem Sprachsynthese-Skill (falls installiert) und richte dieses Audio aus.
Die Schriftart ist nicht optional – in keiner der beiden Zeilen
libass ersetzt Schriftarten nicht pro Glyphe, wie es ein Browser tut. CJK-Text in einer lateinischen Stilschriftart wird als leere Kästchen gerendert – stillschweigend, während des gesamten Brennvorgangs. Jede Vorgabe enthält eine lateinische Schriftart, daher wählt der Generator nach Skript aus, anstatt die der Vorgabe zu erben. Dies gilt auch für die Quellzeile, nicht nur für die Übersetzung: Ein chinesisches Transkript ohne --font würde sonst als eine Reihe von Kästchen eingebrannt.
- Das Skript wird aus dem eigenen Text der Zeile erkannt und über
fc-match :lang=<tag>abgeglichen, wobei ein einzelner ASCII-Familienalias verwendet wird (eine Alias-Liste würde die kommagetrennte ASS-Stilzeile beschädigen). --font <name>(Quelle) und--translation-font <name>(Übersetzung) überschreiben es und werden abgelehnt, wennfc-listsagt, dass diese Schriftart die erkannte Sprache nicht abdeckt. Umgehe den Fehler nicht, indem du eine andere lateinische Schriftart wählst – überprüfe, was das Skript abdeckt, mitfc-list :lang=zh-cn family.- Lateinischer Text belässt die Vorgabeschriftart unverändert; der Austausch erfolgt nur, wenn die Vorgabe das Skript nicht abdecken würde.
- Ohne Fontconfig schlägt die automatische Auswahl lautstark fehl; übergib die Schriftart explizit. Der Lauf meldet
source_font_verified: false/translation_font_verified: false, wenn die Abdeckung nicht überprüft werden konnte, also melde diesen Vorbehalt, anstatt zu behaupten, die Schriftart sei in Ordnung. - Der Lauf meldet
source_font/source_script, wenn die Quelle nicht lateinisch ist.
Ein teilweise übersetztes Transkript wird rundheraus abgelehnt – es bedeutet, dass der Übersetzungsschritt vorzeitig gestoppt wurde, und das Ausgeben von nur quellsprachigen Hinweisen für den Rest würde eine unvollständige Datei als fertig ausgeben.
Hart eingebrannte Untertitel
Wenn die Quelle Videos enthält und der Benutzer hart eingebrannte Untertitel wünscht:
node <skill-verzeichnis>/scripts/render-hardsub.mjs \
/pfad/zum/quelle-video \
/ausgabe/quelle.karaoke.ass
Der Standard --format source erhält den Quell-Container wenn möglich:
- MP4/M4V/MOV -> gleiche Erweiterung mit H.264/AAC.
- MKV -> MKV mit H.264 und kopiertem Audio.
- WebM -> WebM mit VP9/Opus.
- TS/M2TS -> gleiche Erweiterung mit H.264/AAC.
- Nicht unterstützte/mehrdeutige Quellerweiterungen -> MKV-Fallback, gemeldet als
container_fallback: true.
Hart eingebrannte Untertitel erfordern immer eine Neucodierung des Videos; die Beibehaltung des Containers bedeutet nicht, den Quellvideocodec zu kopieren. Verwende --format mp4|mov|mkv|webm oder ein explizites -o nur, wenn der Benutzer ein anderes Ausgabeformat anfordert. Verwende --overwrite nur mit Autorisierung.
Passe die Quellbitrate an
Die Neucodierung mit einer festen Qualität ignoriert, mit welcher die Quelle geliefert wurde, und die Lücke kann groß sein: Das Brennen mit CRF 21 in eine schlanke 1,5 Mbit/s AV1-Datei ergibt eine 4,2 Mbit/s H.264-Kopie – das 2,8-fache der Quellbitrate, fast die 3-fache Dateigröße, ohne sichtbaren Gewinn. Das Skript untersucht daher die Quelle und leitet eine -maxrate / -bufsize-Obergrenze von ihrer Bitrate ab, skaliert um den Faktor, wie viel weniger effizient der Ausgabecodec ist (H.264 benötigt etwa das 1,6-fache der Bitrate von AV1 für vergleichbare Qualität). Die Qualität kommt immer noch von CRF; die Begrenzung verhindert nur, dass sie die Quelle überschreitet.
Dies ist automatisch für x264-Ziele. VP9/WebM wird in Ruhe gelassen, weil das .webm-Profil -b:v 0 für den Modus mit konstanter Qualität festlegt.
Der Bericht enthält source_video_bitrate, video_bitrate und die bitrate_cap-Entscheidung – vergleiche die ersten beiden, wenn du das Ergebnis meldest.
Überschreibe nur, wenn der Benutzer nach einer bestimmten Bitrate oder Qualitätsstufe fragt:
--crf <n>setzt das Qualitätsziel (niedriger ist besser, 21 Standard für H.264).--maxrate <rate>ersetzt die abgeleitete Obergrenze, z. B.--maxrate 4M.--maxrate nonedeaktiviert die Begrenzung vollständig und stellt das einfache CRF-Verhalten wieder her.
Die Bitrate ist auch der Hebel für die Dateigröße. Wenn ein Benutzer Einwände gegen die Ausgabegröße erhebt, zitiere die Quellbitrate zusammen mit der Ausgabebitrate, bevor du eine Änderung vorschlägst, und denke daran, dass flach illustrierte oder aufgenommene Bildschirmaufnahmen weitaus stärker komprimiert werden als Live-Action – Untertiteltext selbst bleibt auch bei CRF 28 scharf, daher ist er nie der Engpass.
CLI-Fallback
Falle auf edgespeak-cli zurück, wann immer MCP die Arbeit nicht erledigen kann – auch wenn der MCP-Server selbst läuft, aber seine Tools fehlschlagen. Der häufigste Fall: Die Desktop-App läuft nicht, daher gibt jedes EdgeSpeak-MCP-Tool runtime_error: could not reach gateway zurück. Das ist keine kaputte Installation und nichts, was man wiederholen sollte; der lang laufende MCP-Server startet absichtlich nie eine eigene Engine (ein dauerhafter Server hält...
(Der Text wurde abgeschnitten, daher hier beendet.)