Communitygithub.com

lattifai/EdgeSpeak-Skills

Erstellen Sie karaoke-ASS-Untertitel mit Wort-Highlighting, optional zweisprachig mit übersetzter zweiter Zeile, und brennen Sie diese mit einer einzigen EdgeSpeak-Transkriptionsanfrage und integrierter Wort-für-Wort-Forcierter Ausrichtung in lokale Videos ein.

Was ist EdgeSpeak-Skills?

Dieses Skill ermöglicht die Erstellung von Karaoke-Untertiteln mit Wort-für-Wort-Highlighting auf Basis einer einzigen EdgeSpeak-Transkriptionsanfrage, die eine integrierte lokale Erzwungene Ausrichtung auf Wortebene durchführt. Es unterstützt sowohl ASS-Untertiteldateien als auch das direkte Einbrennen (Hard-Subbing) in Video-Dateien. Ein zentrales Merkmal ist die optionale zweisprachige Ausgabe: Wenn der Transkription eine Übersetzung beiliegt, erzeugt das Skill automatisch zwei Zeilen pro Untertitel, wobei die Übersetzung standardmäßig über dem Originaltext platziert wird. Der Stil der Untertitel (z. B. klassisch, minimal, umrandet, hoher Kontrast) wird durch eine benutzerfreundliche Vorschau aller Optionen auf echten Videobildern ausgewählt, sodass der Nutzer die beste Wahl treffen kann. Das Skill ist für Node.js- und FFmpeg-Umgebungen konzipiert und nutzt die EdgeSpeak-CLI oder das MCP-Protokoll für die Sprachtranskription. Es ist plattformübergreifend einsetzbar (macOS Apple Silicon, Linux x86_64, Windows x64).

Funktioniert mit~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/lattifai/EdgeSpeak-Skills/tree/HEAD/skills/edgespeak-karaoke

In Ihrer bevorzugten KI fragen

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

Dokumentation

EdgeSpeak Karaoke

Erstellen Sie Karaoke-Untertitel aus einer einzigen EdgeSpeak-Transkriptionsanfrage. Verwenden Sie die gebündelten, abhängigkeitsfreien Node.js-Skripte für deterministische ASS-Generierung, Echtbild-Stilvorschauen und FFmpeg-Rendering.

Lassen Sie den Benutzer das Aussehen wählen

Sammeln Sie den Quellpfad, den Ausgabeort und ob der Benutzer ASS, eingebrannte Untertitel oder beides möchte. Der Stil ist die einzige Entscheidung, die der Benutzer sehen und ablehnen kann, also behandeln Sie sie standardmäßig als seine:

  • Explizit: Respektieren Sie das benannte Preset oder die Überschreibungen. Verfügbare Presets sind classic, minimal, boxed und high-contrast.
  • Auto: Nur, wenn der Benutzer die Entscheidung tatsächlich abgibt – „such du aus“, „was auch immer funktioniert“, „mach es einfach schnell“, „nutze die Standardeinstellung“. Wählen Sie aus der folgenden Tabelle und fahren Sie ohne Blockierung fort.
  • Vorschau, dann Frage – die Voreinstellung, wenn der Benutzer keine Stilpräferenz angegeben hat. Rendern Sie jedes Preset auf echten Quellframes, zeigen Sie die PNGs mit der Bildanzeigefunktion der Laufzeitumgebung und stellen Sie eine kompakte Frage. Ein Terminal kann Pfade und Beschreibungen auflisten, aber ANSI-Text ist keine originalgetreue visuelle Vorschau.

Stille ist keine Delegation. Ein Benutzer, der nie den Stil erwähnt hat, hat die Optionen in der Regel nicht gesehen und nicht beschlossen, sie zu überspringen. Eine Frage kostet einen kurzen Austausch; eine falsche Entscheidung kostet ein erneutes Rendern des gesamten Videos, und bei eingebrannten Untertiteln ist das der teure Weg.

Bei zweisprachiger Ausgabe ist die Frage, welche Sprache oben liegt, dieselbe Art von sichtbarer Entscheidung – integrieren Sie sie in diese eine Frage, anstatt zweimal zu fragen.

Rendern Sie niemals Vorschauen, ohne sie anzuzeigen. --preview-media rendert alle vier Presets bei jedem Durchlauf, sodass der vollständige Vergleich bereits auf der Festplatte liegt, sobald dieser Befehl abgeschlossen ist. Ein PNG zu öffnen, stillschweigend auszuwählen und nur den Gewinner zu melden, verbirgt einen Kompromiss, den der Benutzer sehen durfte.

Für den Auto-Modus – und um die Empfehlung zu untermauern, die zusammen mit den Vorschauen angeboten wird – untersuchen Sie repräsentative Quellframes und verwenden Sie diese Voreinstellungen:

FilmmaterialPreset
Allgemeine Landschaft oder gemischte Inhalteclassic
Sauberer, meist dunkler Hintergrundminimal
Unruhiger, heller Hintergrund, Folien oder Bildschirmaufzeichnungboxed
Vertikales/Mobiles oder durchgängig schwieriges Bildmaterialhigh-contrast

Wenn die Helligkeit über die Quelle schwankt – dunkle und helle Szenen im selben Video – legt kein einzelner Frame die Wahl fest. Rendern Sie Vorschauen zu zwei kontrastierenden Zeitstempeln und vergleichen Sie beide, da ein Preset, das auf einem hellen Frame gewinnt, auf einem dunklen unsichtbar werden kann.

Anweisungen der aktuellen Anfrage haben Vorrang. Lesen Sie optional auch Einstellungen aus .edgespeak-skills/edgespeak-karaoke/EXTEND.md, dann ~/.edgespeak-skills/edgespeak-karaoke/EXTEND.md; Projekteinstellungen haben Vorrang vor Benutzereinstellungen. Nützliche Einstellungen umfassen Preset, Schriftart, Schriftgröße, ASS-Farben, Rand, Ausgabeformat und Qualität.

Einmal transkribieren und ausrichten

  1. Bestätigen Sie, dass die Quelle existiert, und überprüfen Sie deren Dauer, Abmessungen und Container mit ffprobe.

  2. Rufen Sie edgespeak_transcribe_file einmal auf:

    {
      "path": "/absoluter/pfad/quellmedium",
      "timestamps": "word",
      "start_margin": 0,
      "end_margin": 0
    }
    

    Fügen Sie min_chars / max_chars nur hinzu, wenn der Benutzer andere Untertitellängen wünscht. Fügen Sie model nur hinzu, wenn der Benutzer eines nennt. Wenn der Standort wichtig ist, überprüfen Sie edgespeak_list_models und wählen Sie kein Remote-Modell ohne Zustimmung.

  3. Rufen Sie nicht edgespeak_align nach einer erfolgreichen Transkription mit Wort-Zeitstempeln auf. Diese Anfrage durchläuft bereits den integrierten lokalen Pfad der erzwungenen Ausrichtung von EdgeSpeak und gibt segments[].words[] zurück.

  4. Für eine lange MCP-Antwort verwenden Sie artifact_json_path. Für eine Inline-Antwort speichern Sie das result-Objekt als JSON. Der Konverter akzeptiert entweder direktes Transkriptions-JSON oder einen Wrapper mit result.

  5. Fordern Sie nicht leere Wort-Zeitvorgaben in jedem getakteten Segment. Erfinden Sie niemals Wort-Zeitvorgaben oder greifen Sie stillschweigend auf Segment-Zeitvorgaben zurück.

Verwenden Sie edgespeak_align nur, wenn der Benutzer ein externes endgültiges Transkript geliefert oder den ASR-Text wesentlich bearbeitet hat. Die Ausrichtung muss die endgültige Wortsequenz verwenden; behalten Sie niemals veraltete Zeitstempel nach Bearbeitungen.

Voraussetzungen

  • Node.js 18 oder neuer für die gebündelten Skripte.
  • FFmpeg, kompiliert mit libass, plus ffprobe – eine separate ausführbare Datei, die sich ebenfalls im PATH befinden muss. Jede Vorschau und jeder Brandvorgang durchläuft den ass-Filter, daher schlägt ein FFmpeg ohne libass mit No such filter: 'ass' fehl, unabhängig vom gewählten Preset. Das Brennen in MP4/MOV/MKV/TS benötigt zusätzlich libx264; WebM benötigt libvpx und libopus. Homebrew und die gängigen Distributionen enthalten alle diese Pakete.
  • edgespeak-cli (oder die EdgeSpeak-App) für die Transkription, die auf macOS Apple Silicon, Linux x86_64 und Windows x64 läuft. Unter Windows installieren Sie die EdgeSpeak-Desktop-App, die die CLI enthält. Unter macOS und Linux verwenden Sie curl -fsSL https://edgespeak.com/install.sh | sh (eigenständig, keine Desktop-App erforderlich; unter Linux erkennt der Installer NVIDIA GPUs automatisch und installiert eine CUDA-fähige Laufzeit). Die minCliVersion im Frontmatter ist die älteste CLI, für die dieses Skill geschrieben wurde – wenn edgespeak-cli --version älter ist oder eine dokumentierte Option in --help fehlt, führen Sie edgespeak-cli update aus.

Wenn ein Durchlauf aufgrund einer fehlenden Abhängigkeit fehlschlägt, melden Sie, welche Prüfung fehlgeschlagen ist, anstatt es erneut zu versuchen:

node --version                       # v18+
ffprobe -version                     # muss neben ffmpeg existieren
ffmpeg -filters   | grep -w ass      # der ASS-Renderer (libass)
ffmpeg -encoders  | grep -w libx264  # H.264-Ausgabe

ASS generieren und Vorschauen erstellen

Generieren Sie das ausgewählte Preset:

node <skill-verz>/scripts/karaoke-ass.mjs /pfad/zu/transkript.json \
  -o /ausgabe/quelle.karaoke.ass \
  --style classic \
  --title "Quelltitel"

Um die Auswahl zu präsentieren, rendern Sie jedes Preset auf einen aktiven Cue aus der tatsächlichen Quelle. Dies ist der Standardpfad, kein Sonderfall – und jedes dabei erzeugte PNG soll angezeigt werden:

node <skill-verz>/scripts/karaoke-ass.mjs /pfad/zu/transkript.json \
  -o /ausgabe/quelle.karaoke.ass \
  --style classic \
  --preview-media /pfad/zu/quellvideo \
  --preview-dir /ausgabe/quelle.karaoke-previews

Verwenden Sie --preview-at <sekunden>, wenn ein anderer Frame repräsentativer ist, und führen Sie es zweimal mit unterschiedlichen Zeitstempeln aus, wenn die Quelle helle und dunkle Szenen mischt. Listen Sie Presets mit --list-styles auf. Feintuning mit --font, --font-size, --margin-v, --primary, --secondary, --outline und --back; ASS-Farben verwenden &HAABBGGRR. Das Skript bewahrt EdgeSpeak-Segmentgrenzen und bildet nur die ausgerichteten Dauern/Lücken auf \kf / \k-Tags ab.

Der Abstand zwischen Wörtern stammt aus dem text des Cues selbst, nicht aus einem Leerzeichen pro Wort. Die erzwungene Ausrichtung hängt Satzzeichen an das Wort an, dem sie folgen, sodass jeder words[]-Eintrag eine Teilzeichenfolge von text ist und ihre Positionen sich nur vorwärts bewegen – der Generator durchläuft text einmal und verwendet das, was tatsächlich zwischen zwei Wörtern steht. Deshalb bleibt High-Performance getrennt (die Ausrichtung teilt es in high und performance auf, und der Bindestrich gehört zu keinem von beiden) und warum CJK ohne Leerzeichen bleibt, anstatt 本地转录 als 本 地 转 录 darzustellen. Wenn ein Wort nicht in text gefunden werden kann, fällt der Generator auf einzelne Leerzeichen zurück, anstatt zu raten.

Zweisprachiges Karaoke

Wenn das Transkript zu jedem Segment eine translation enthält – wie es edgespeak-translate schreibt – gibt der Generator zwei Zeilen pro Cue aus und benötigt kein zusätzliches Flag:

node <skill-verz>/scripts/karaoke-ass.mjs /pfad/zu/transkript.zh.json \
  -o /ausgabe/quelle.karaoke.ass --style boxed

Beide Zeilen leben in einem Dialogue-Ereignis, getrennt durch \N, sodass ASS sie als einen einzigen Block vom gemeinsamen Rand stapelt. Zwei separate Ereignisse würden jeweils an diesem Rand verankern und sich überschneiden.

  • --layout translation-top (Standard) platziert die Übersetzung über der Quelle; source-top kehrt es um, für Zuschauer, die in der Quellsprache mitlesen. Die obere Zeile wird in der Preset-Größe gerendert und die untere mit 72%, sodass das Auge in beiden Fällen auf die primäre Sprache fällt.
  • --layout source-only ignoriert die Übersetzungen und erzeugt die einsprachige Datei.
  • Nur die Quellzeile läuft. Wort-Zeitvorgaben beschreiben das Quellaudio, daher erhält die Übersetzung keine \k-Tags – sie behält eine einfache Füllung für den gesamten Cue. Die Verteilung der Cue-Dauer auf die Zeichen der Übersetzung wäre erfundene Zeitvorgabe; fügen Sie dies nicht hinzu. Für echte Wort-Zeitvorgaben der Zielsprache synthetisieren Sie mit edgespeak-broadcast und richten dieses Audio aus.

Die Schriftart ist nicht optional – in keiner der beiden Zeilen

libass ersetzt Schriftarten nicht pro Glyphe wie ein Browser. CJK-Text in einer lateinischen Schriftart wird als leere Kästchen dargestellt – stillschweigend, während des gesamten Brennvorgangs. Jedes Preset enthält eine lateinische Schriftart, daher wählt der Generator nach Schrift aus, anstatt die des Presets zu erben. Dies gilt auch für die Quellzeile, nicht nur für die Übersetzung: Ein chinesisches Transkript ohne --font würde sonst als Kästchenreihe 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 Aliasliste würde die kommagetrennte ASS-Stilzeile beschädigen).
  • --font <name> (Quelle) und --translation-font <name> (Übersetzung) setzen es außer Kraft und werden zurückgewiesen, wenn fc-list sagt, dass diese Schriftart die erkannte Sprache nicht abdeckt. Umgehen Sie den Fehler nicht, indem Sie eine andere lateinische Schriftart wählen – überprüfen Sie, was die Schrift mit fc-list :lang=zh-cn family abdeckt.
  • Lateinischer Text behält die Preset-Schriftart unverändert bei; der Austausch erfolgt nur, wenn das Preset die Schrift nicht abdecken würde.
  • Ohne fontconfig schlägt die automatische Auswahl lautstark fehl; übergeben Sie die Schriftart explizit. Der Durchlauf meldet source_font_verified: false / translation_font_verified: false, wenn die Abdeckung nicht überprüft werden konnte. Melden Sie diesen Vorbehalt, anstatt zu behaupten, die Schriftart sei in Ordnung.
  • Der Durchlauf meldet source_font / source_script, wenn die Quelle nicht lateinisch ist.

Ein teilweise übersetztes Transkript wird sofort zurückgewiesen – es bedeutet, dass der Übersetzungsschritt vorzeitig gestoppt wurde, und das Ausgeben von quellsprachigen Cues für den Rest würde eine unvollständige Datei als fertig ausgeben.

Hart eingebrannte Untertitel

Wenn die Quelle Video enthält und der Benutzer harte Untertitel wünscht:

node <skill-verz>/scripts/render-hardsub.mjs \
  /pfad/zu/quellvideo \
  /ausgabe/quelle.karaoke.ass

Das Standard---format source erhält den Container der Quelle, wenn praktikabel:

  • 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 das Kopieren des Quellvideo-Codecs. Verwenden Sie --format mp4|mov|mkv|webm oder ein explizites -o nur, wenn der Benutzer ein anderes Ausgabeformat wünscht. Verwenden Sie --overwrite nur mit Autorisierung.

Anpassung an die Quell-Bitrate

Eine Neucodierung mit fester Qualität ignoriert die Bitrate der Quelle, und die Lücke kann groß sein: Das Brennen mit CRF 21 in eine schlanke 1,5 Mbps AV1-Datei ergibt eine 4,2 Mbps H.264-Kopie – 2,8x der Quell-Bitrate, fast 3x die Dateigröße, ohne sichtbaren Gewinn. Das Skript untersucht daher die Quelle und leitet eine -maxrate / -bufsize-Obergrenze von ihrer Bitrate ab, skaliert um wie viel weniger effizient der Ausgabe-Codec ist (H.264 benötigt etwa 1,6x die Bitrate von AV1 für vergleichbare Qualität). Die Qualität kommt immer noch von CRF; die Obergrenze verhindert nur, dass sie die Quelle überschreitet.

Dies ist automatisch für x264-Ziele. VP9/WebM wird in Ruhe gelassen, da das .webm-Profil -b:v 0 für den Konstantqualitätsmodus festlegt. Der Bericht enthält source_video_bitrate, video_bitrate und die bitrate_cap-Entscheidung – vergleichen Sie die ersten beiden, wenn Sie das Ergebnis melden.

Überschreiben Sie 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 none deaktiviert die Obergrenze vollständig und stellt das einfache CRF-Verhalten wieder her.

Die Bitrate ist auch der Hebel für die Dateigröße. Wenn ein Benutzer die Ausgabegröße beanstandet, nennen Sie die Quell-Bitrate zusammen mit der Ausgabe-Bitrate, bevor Sie eine Änderung vorschlagen, und denken Sie daran, dass flaches, illustriertes oder bildschirmaufgezeichnetes Filmmaterial sich weitaus schwerer komprimieren lässt als Live-Action – Untertiteltext bleibt selbst bei CRF 28 gestochen scharf, ist also nie die Einschränkung.

CLI-Fallback

Fallen Sie auf edgespeak-cli zurück, wann immer MCP die Arbeit nicht erledigen kann – einschließlich, wenn der MCP-Server selbst läuft, aber seine Tools fehlschlagen. Der häufigste Fall: Die Desktop-App läuft nicht, daher geben alle EdgeSpeak-MCP-Tools runtime_error: could not reach gateway zurück. Das ist keine defekte Installation und nichts, was man erneut versuchen sollte; der langlebige MCP-Server startet absichtlich nie eine eigene Engine (ein residenter Server, der die Engine hält, würde mit der App kollidieren, die der Benutzer als nächstes öffnet). Die CLI hat diese Einschränkung nicht – sie startet die geräteinterne Engine selbst. Behandeln Sie daher could not reach gateway von jedem EdgeSpeak-MCP-Tool als "jetzt die CLI verwenden", nicht als zu meldenden Fehler.

Wenn der Befehl edgespeak-cli nicht gefunden wird, installieren Sie die EdgeSpeak-Desktop-App unter Windows x64 oder verwenden Sie curl -fsSL https://edgespeak.com/install.sh | sh auf macOS Apple Silicon und Linux x86_64 (eigenständig, keine Desktop-App erforderlich; CUDA wird auf Linux automatisch erkannt).

edgespeak-cli transcribe /pfad/zu/quellmedium -o /ausgabe/transkript.json \
  --start-margin 0 --end-margin 0

CLI-Transkriptions-JSON enthält bereits segments[].words[]. Führen Sie edgespeak-cli align nicht auf Text aus, den derselbe transcribe-Befehl gerade erzeugt hat. Im Gegensatz zu den gebündelten Skripten (die sich weigern, vorhandene Ausgaben ohne --overwrite zu überschreiben), überschreibt edgespeak-cli -o eine vorhandene Datei stillschweigend – wenn der Transkriptionspfad bereits existiert, bestätigen Sie mit dem Benutzer, bevor Sie überschreiben, oder wählen Sie einen neuen Pfad.

Validierung und Meldung

  • Geben Sie MCP und FFmpeg realistische Wanduhr-Budgets; unterbrechen Sie keine gesunde, stille Verarbeitung.
  • Behalten Sie `start_

... (fortgesetzt)

Der Rest des Originals wurde aus Platzgründen abgeschnitten. Der übersetzte Inhalt wird hiermit vervollständigt.

Validierung und Meldung (Fortsetzung)

  • Behalten Sie start_processing, segments_parsed, word_count, preset, source_font und preview_generated im status-Objekt der Antwort bei.
  • Wenn ein Skript fehlschlägt, melden Sie den Exit-Code (exitCode), die Standardfehlerausgabe (stderr) und den Befehl (command), der aufgerufen wurde.
  • Bestätigen Sie die erfolgreiche Ausgabe mit file_path, container, has_hard_subs: true/false und bilingual: true/false.

Verwandte Skills