Communitygithub.com

EdgeSpeak Karaoke

Créez des sous-titres ASS de karaoké avec surbrillance mot par mot, éventuellement bilingues avec une deuxième ligne traduite, et incrustez-les dans des vidéos locales à l'aide d'une seule requête de transcription EdgeSpeak avec alignement forcé en ligne. Utilisez-le lorsque l'utilisateur demande des sous-titres karaoké, une surbrillance par mot, un fichier ASS, des sous-titres bilingues, des choix de style de sous-titres ou des aperçus, ou une vidéo avec sous-titres incrustés sans fournir de transcription de référence finale.

Qu'est-ce que EdgeSpeak Karaoke ?

Cette compétence génère des sous-titres de karaoké avec mise en évidence mot par mot à partir d'une seule requête de transcription EdgeSpeak. Elle utilise des scripts Node.js sans dépendances pour la création déterministe de fichiers ASS, des aperçus de style sur des images réelles, et le rendu vidéo via FFmpeg. L'utilisateur peut choisir entre plusieurs styles visuels (classique, minimal, encadré, contraste élevé) ou laisser l'IA décider en fonction de l'analyse des images source. La compétence prend en charge la création de sous-titres bilingues avec deux lignes (source + traduction) et l'incrustation directe dans la vidéo. Elle fonctionne sur macOS Apple Silicon, Linux x86_64 et Windows x64, et nécessite Node.js 18+, FFmpeg avec libass, et l'interface en ligne de commande EdgeSpeak.

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

Demander à votre IA préférée

Ouvre une nouvelle conversation avec cette compétence d'agent déjà préchargée.

Documentation

Que fait EdgeSpeak Karaoke ?

Créez des sous-titres karaoké à partir d'une seule requête de transcription EdgeSpeak. Utilisez les scripts Node.js sans dépendances fournis pour la génération déterministe d'ASS, les aperçus de style sur des images réelles et le rendu FFmpeg.

Laissez l'utilisateur choisir l'apparence

Collectez le chemin source, l'emplacement de sortie et si l'utilisateur souhaite des fichiers ASS, des sous-titres incrustés, ou les deux. Le style est la seule décision que l'utilisateur peut voir et contester, donc traitez-la comme la leur par défaut :

  • Explicite : honorez le préréglage nommé ou les surcharges. Les préréglages disponibles sont classic, minimal, boxed et high-contrast.
  • Automatique : seulement lorsque l'utilisateur délègue réellement la décision — « choisis toi-même », « ce qui va », « fais vite », « utilise le défaut ». Choisissez dans le tableau ci-dessous et continuez sans bloquer.
  • Aperçu puis demande — le comportement par défaut lorsque l'utilisateur n'a exprimé aucune préférence de style. Rendez chaque préréglage sur des images source réelles, affichez les PNG avec la capacité d'affichage d'images de l'environnement d'exécution et posez une question concise. Un terminal peut lister les chemins et descriptions, mais le texte ANSI n'est pas un aperçu visuel fidèle.

Le silence n'est pas une délégation. Un utilisateur qui n'a jamais mentionné le style n'a généralement pas vu les options plutôt que de décider de les ignorer. Demander coûte un bref échange ; deviner mal coûte un re-rendu de la vidéo entière, et avec les sous-titres incrustés, c'est le chemin coûteux.

Pour la sortie bilingue, la langue qui se trouve en haut est le même type de choix visible — intégrez-le dans cette seule question plutôt que de demander deux fois.

Ne rendez jamais d'aperçus sans les afficher. --preview-media rend les quatre préréglages à chaque exécution, donc dès que cette commande se termine, la comparaison complète existe déjà sur le disque. Ouvrir un PNG, choisir en silence et ne signaler que le gagnant cache un compromis que l'utilisateur avait le droit de voir.

Pour le mode automatique — et pour alimenter la recommandation offerte avec les aperçus — inspectez des images source représentatives et utilisez ces valeurs par défaut :

SéquencePréréglage
Paysage général ou contenu mixteclassic
Fond propre, plutôt sombreminimal
Fond chargé, lumineux, diapositives ou enregistrement d'écranboxed
Vidéo verticale/mobile ou fond systématiquement difficilehigh-contrast

Lorsque la luminosité varie dans la source — scènes sombres et scènes lumineuses dans la même vidéo — aucune image seule ne tranche le choix. Rendez les aperçus à deux timestamps contrastés et comparez les deux, car un préréglage qui gagne sur une image lumineuse peut devenir invisible sur une image sombre.

Les instructions de la requête en cours prévalent. Si présent, lisez également les préférences optionnelles depuis .edgespeak-skills/edgespeak-karaoke/EXTEND.md, puis ~/.edgespeak-skills/edgespeak-karaoke/EXTEND.md ; les préférences du projet l'emportent sur les préférences utilisateur. Les préférences utiles incluent le préréglage, la police, la taille de police, les couleurs ASS, la marge, le format de sortie et la qualité.

Transcrire et aligner une seule fois

  1. Confirmez que la source existe et inspectez sa durée, ses dimensions et son conteneur avec ffprobe.

  2. Appelez edgespeak_transcribe_file une seule fois :

    {
      "path": "/chemin/absolu/media-source",
      "timestamps": "word",
      "start_margin": 0,
      "end_margin": 0
    }
    

    Ajoutez min_chars / max_chars uniquement lorsque l'utilisateur demande des longueurs de sous-titres différentes. Ajoutez model uniquement lorsque l'utilisateur en nomme un. Si la localité est importante, inspectez edgespeak_list_models et ne choisissez pas un modèle distant sans consentement.

  3. N'appelez pas edgespeak_align après une transcription réussie avec timestamps par mot. Cette requête exécute déjà le chemin d'alignement forcé local en ligne d'EdgeSpeak et renvoie segments[].words[].

  4. Pour une réponse MCP longue, utilisez artifact_json_path. Pour une réponse en ligne, enregistrez l'objet result au format JSON. Le convertisseur accepte soit le JSON de transcription direct, soit un wrapper avec result.

  5. Exigez un timing de mot non vide dans chaque segment minuté. N'inventez jamais de timing de mot et ne reculez pas silencieusement vers un timing de segment.

Utilisez edgespeak_align uniquement lorsque l'utilisateur a fourni une transcription finale externe ou a modifié matériellement le texte ASR. L'alignement doit utiliser la séquence finale de mots ; ne conservez jamais de timestamps obsolètes après des modifications.

Exigences

  • Node.js 18 ou plus récent pour les scripts fournis.
  • FFmpeg compilé avec libass, ainsi que ffprobe — un exécutable séparé qui doit également être dans PATH. Chaque aperçu et chaque incrustation passe par le filtre ass, donc un FFmpeg sans libass échoue avec No such filter: 'ass' quel que soit le préréglage sélectionné. L'incrustation en MP4/MOV/MKV/TS nécessite en outre libx264 ; WebM nécessite libvpx et libopus. Homebrew et les paquets des distributions majeures incluent tout cela.
  • edgespeak-cli (ou l'application EdgeSpeak) pour la transcription, qui fonctionne sur macOS Apple Silicon, Linux x86_64 et Windows x64. Sous Windows, installez l'application de bureau EdgeSpeak, qui fournit l'interface en ligne de commande. Sous macOS et Linux, utilisez curl -fsSL https://edgespeak.com/install.sh | sh (autonome, pas besoin d'application de bureau ; sous Linux, l'installateur détecte automatiquement les GPU NVIDIA et installe un runtime CUDA). Le minCliVersion dans l'en-tête est la version minimale de l'interface en ligne de commande pour laquelle cette compétence est écrite — si edgespeak-cli --version est plus ancien, ou si un indicateur documenté manque dans --help, exécutez edgespeak-cli update.

Lorsqu'une exécution échoue sur une dépendance manquante, signalez quelle vérification a échoué plutôt que de réessayer :

node --version                       # v18+
ffprobe -version                     # doit exister à côté de ffmpeg
ffmpeg -filters   | grep -w ass      # le moteur de rendu ASS (libass)
ffmpeg -encoders  | grep -w libx264  # sortie H.264

Générer ASS et les aperçus

Générez le préréglage sélectionné :

node <dossier-de-la-competence>/scripts/karaoke-ass.mjs /chemin/vers/transcription.json \
  -o /sortie/source.karaoke.ass \
  --style classic \
  --title "Titre de la source"

Pour présenter le choix, rendez chaque préréglage sur un sous-titre actif de la source réelle. C'est le chemin par défaut, pas un cas particulier — et chaque PNG qu'il produit est destiné à être affiché :

node <dossier-de-la-competence>/scripts/karaoke-ass.mjs /chemin/vers/transcription.json \
  -o /sortie/source.karaoke.ass \
  --style classic \
  --preview-media /chemin/vers/video-source \
  --preview-dir /sortie/source.karaoke-previews

Utilisez --preview-at <secondes> lorsqu'une autre image est plus représentative, et exécutez-la deux fois avec des timestamps différents lorsque la source mélange des scènes lumineuses et sombres. Listez les préréglages avec --list-styles. Affinez avec --font, --font-size, --margin-v, --primary, --secondary, --outline et --back ; les couleurs ASS utilisent &HAABBGGRR. Le script préserve les limites de segments EdgeSpeak et ne mappe que les durées/écarts alignés aux balises \kf / \k.

L'espacement entre les mots provient du text du sous-titre lui-même, pas d'un espace par mot. L'alignement forcé attache la ponctuation au mot qu'elle suit, donc chaque entrée words[] est une sous-chaîne de text et leurs positions n'avancent que vers l'avant — le générateur parcourt text une fois et réutilise ce qui se trouve réellement entre deux mots. C'est ce qui maintient high-performance avec un trait d'union (l'alignement le sépare en high et performance, et le trait d'union n'appartient à aucun des deux) et ce qui garde le CJK sans espace au lieu de rendre 本地转录 comme 本 地 转 录. Si un mot ne peut pas être trouvé dans text, le générateur recourt à des espaces simples plutôt que de deviner.

Karaoké bilingue

Lorsque la transcription porte une traduction sur chaque segment — ce que edgespeak-translate écrit — le générateur émet deux lignes par sous-titre et n'a besoin d'aucun indicateur supplémentaire :

node <dossier-de-la-competence>/scripts/karaoke-ass.mjs /chemin/vers/transcription.zh.json \
  -o /sortie/source.karaoke.ass --style boxed

Les deux lignes vivent dans un seul événement Dialogue séparé par \N, donc ASS les empile comme un seul bloc sur la marge partagée. Deux événements séparés s'ancreraient chacun à cette marge et se chevaucheraient.

  • --layout translation-top (par défaut) place la traduction au-dessus de la source ; source-top l'inverse, pour les spectateurs lisant dans la langue source. La ligne du haut s'affiche à la taille du préréglage et celle du bas à 72 %, de sorte que l'œil atterrit sur la langue principale dans les deux cas.
  • --layout source-only ignore les traductions et produit le fichier monolingue.
  • Seule la ligne source défile. Les timings des mots décrivent l'audio source, donc la traduction n'obtient pas de balises \k — elle a un remplissage uni pour tout le sous-titre. Distribuer la durée du sous-titre sur les caractères de la traduction serait un timing inventé ; ne l'ajoutez pas. Pour un véritable timing mot par mot dans la langue cible, synthétisez avec edgespeak-broadcast et alignez cet audio.

La police n'est pas optionnelle — sur aucune des deux lignes

libass ne substitue pas les polices par glyphe comme le ferait un navigateur. Le texte CJK dans une police de style latin s'affiche comme des boîtes vides — silencieusement, jusqu'à la fin d'une incrustation. Chaque préréglage fournit une police latine, donc le générateur choisit par script plutôt que d'hériter de celle du préréglage. Cela s'applique aussi à la ligne source, pas seulement à la traduction : une transcription chinoise sans --font brûlerait autrement comme une rangée de boîtes.

  • Le script est détecté à partir du texte de la ligne elle-même et mis en correspondance via fc-match :lang=<tag>, en prenant un seul alias de famille ASCII (une liste d'alias casserait la ligne de style ASS délimitée par des virgules).
  • --font <nom> (source) et --translation-font <nom> (traduction) le remplacent, et sont rejetés lorsque fc-list indique que cette police ne revendique pas la langue détectée. Ne contournez pas l'erreur en choisissant une autre police latine — vérifiez ce qui couvre le script avec fc-list :lang=zh-cn family.
  • Le texte latin conserve la police du préréglage intacte ; l'échange ne se produit que lorsque le préréglage ne couvrirait pas le script.
  • Sans fontconfig, la sélection automatique échoue bruyamment ; passez la police explicitement. L'exécution signale source_font_verified: false / translation_font_verified: false lorsque la couverture n'a pas pu être vérifiée, alors signalez cette mise en garde plutôt que de prétendre que la police convient.
  • L'exécution signale source_font / source_script chaque fois que la source n'est pas latine.

Une transcription partiellement traduite est rejetée d'office — cela signifie que l'étape de traduction s'est arrêtée tôt, et émettre des sous-titres source uniquement pour le reste passerait un fichier incomplet pour terminé.

Incruster les sous-titres

Lorsque la source a une vidéo et que l'utilisateur veut des sous-titres incrustés :

node <dossier-de-la-competence>/scripts/render-hardsub.mjs \
  /chemin/vers/video-source \
  /sortie/source.karaoke.ass

Le --format source par défaut préserve le conteneur source lorsque c'est pratique :

  • MP4/M4V/MOV -> même extension avec H.264/AAC.
  • MKV -> MKV avec H.264 et audio copié.
  • WebM -> WebM avec VP9/Opus.
  • TS/M2TS -> même extension avec H.264/AAC.
  • Extensions source non prises en charge/ambiguës -> recours MKV, signalé comme container_fallback: true.

Les sous-titres incrustés nécessitent toujours un ré-encodage vidéo ; préserver le conteneur ne signifie pas copier le codec vidéo source. Utilisez --format mp4|mov|mkv|webm ou un -o explicite uniquement lorsque l'utilisateur demande un format de livraison différent. Utilisez --overwrite uniquement avec autorisation.

Correspondre au débit binaire source

Ré-encoder à une qualité fixe ignore le débit binaire de la source, et l'écart peut être important : incruster un CRF 21 dans un fichier AV1 léger à 1,5 Mbps produit une copie H.264 à 4,2 Mbps — 2,8 fois le débit binaire source, près de 3 fois la taille du fichier, sans gain visible. Le script sonde donc la source et dérive un plafond -maxrate / -bufsize de son débit binaire, ajusté par l'efficacité moindre du codec de sortie (H.264 nécessite environ 1,6 fois le débit binaire d'AV1 pour une qualité comparable). La qualité provient toujours du CRF ; le plafond empêche seulement de dépasser la source.

C'est automatique pour les cibles x264. VP9/WebM est laissé intact car le profil .webm fixe -b:v 0 pour le mode qualité constante. Le rapport inclut source_video_bitrate, video_bitrate et la décision bitrate_cap — comparez les deux premiers lors du rapport du résultat.

Remplacez uniquement lorsque l'utilisateur demande un débit binaire ou un niveau de qualité spécifique :

  • --crf <n> définit la cible de qualité (plus bas est meilleur, 21 par défaut pour H.264).
  • --maxrate <debit> remplace le plafond dérivé, par ex. --maxrate 4M.
  • --maxrate none désactive complètement le plafond et restaure le comportement CRF simple.

Le débit binaire est aussi le levier pour la taille du fichier. Lorsqu'un utilisateur objecte à la taille de sortie, citez le débit binaire source à côté du débit binaire de sortie avant de proposer un changement, et rappelez-vous que les séquences illustrées plates ou les enregistrements d'écran se compressent bien plus fort que les séquences réelles — le texte des sous-titres lui-même reste net même à CRF 28, donc ce n'est jamais la contrainte.

Repli vers l'interface en ligne de commande

Repliez-vous vers edgespeak-cli chaque fois que MCP ne peut pas faire le travail — y compris lorsque le serveur MCP lui-même est actif mais que ses outils échouent. Le cas le plus courant : l'application de bureau ne tourne pas, donc chaque outil EdgeSpeak MCP renvoie runtime_error: could not reach gateway. Ce n'est pas une installation cassée et ce n'est pas quelque chose à réessayer ; le serveur MCP de longue durée ne démarre délibérément jamais son propre moteur (un serveur résident détenant le moteur entrerait en conflit avec l'application que l'utilisateur ouvrira ensuite). L'interface en ligne de commande n'a pas cette contrainte — elle lance elle-même le moteur sur l'appareil. Traitez donc could not reach gateway de tout outil EdgeSpeak MCP comme « utilisez maintenant l'interface en ligne de commande », pas comme un échec à signaler.

Si la commande edgespeak-cli n'est pas trouvée, installez l'application de bureau EdgeSpeak sur Windows x64, ou utilisez curl -fsSL https://edgespeak.com/install.sh | sh sur macOS Apple Silicon et Linux x86_64 (autonome, pas besoin d'application de bureau ; CUDA détecté automatiquement sur Linux).

edgespeak-cli transcribe /chemin/vers/media-source -o /sortie/transcription.json \
  --start-margin 0 --end-margin 0

Le JSON de transcription de l'interface en ligne de commande contient déjà segments[].words[]. N'exécutez pas edgespeak-cli align sur du texte que la même commande transcribe vient de produire. Contrairement aux scripts fournis (qui refusent de remplacer les sorties existantes sans --overwrite), edgespeak-cli -o écrase silencieusement un fichier existant — si le chemin de la transcription existe déjà, confirmez avec l'utilisateur avant d'écraser ou choisissez un nouveau chemin.

Validation et rapport

  • Donnez à MCP et FFmpeg des budgets de temps réel réalistes ; n'interrompez pas un traitement sain silencieux.
  • Conservez les segments start_

Skills associés