Karaoké EdgeSpeak
Créez des sous-titres karaoké à partir d'une seule requête de transcription EdgeSpeak. Utilisez les scripts Node.js fournis, sans dépendances externes, pour la génération déterministe de fichiers ASS, les aperçus de style sur des images réelles, et le rendu avec FFmpeg.
Laissez l'utilisateur choisir l'apparence
Collectez le chemin source, l'emplacement de sortie, et si l'utilisateur souhaite un fichier ASS, des sous-titres incrustés, ou les deux. Le style est la seule décision que l'utilisateur peut voir et contester, alors traitez-la comme lui appartenant par défaut :
- Explicite : respectez le préréglage nommé ou les surcharges. Les préréglages disponibles sont
classic,minimal,boxed, ethigh-contrast. - Automatique : uniquement lorsque l'utilisateur délègue réellement la décision — "choisis toi-même", "comme tu veux", "fais vite", "utilise le défaut". Choisissez dans le tableau ci-dessous et continuez sans bloquer.
- Aperçu puis demande — la valeur par défaut lorsque l'utilisateur n'a exprimé aucune préférence de style. Rendez chaque préréglage sur des images réelles de la source, montrez les PNG avec la capacité d'affichage d'images de l'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 court échange ; deviner faux coûte un nouveau rendu de toute la vidéo, et avec les sous-titres incrustés, c'est le chemin coûteux.
Pour une sortie bilingue, la langue placée 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 montrer. --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 seul PNG, choisir silencieusement, et ne signaler que le gagnant cache un compromis que l'utilisateur avait le droit de voir.
Pour le mode automatique — et pour amorcer la recommandation offerte avec les aperçus — inspectez les images représentatives de la source et utilisez ces valeurs par défaut :
| Contenu | Préréglage |
|---|---|
| Paysage général ou contenu mixte | classic |
| Arrière-plan propre, généralement sombre | minimal |
| Arrière-plan chargé, lumineux, diapositives ou enregistrement d'écran | boxed |
| Vidéo verticale/mobile ou arrière-plan systématiquement difficile | high-contrast |
Lorsque la luminosité varie dans la source — scènes sombres et scènes lumineuses dans la même vidéo — aucune image unique ne peut trancher le choix. Rendez les aperçus à deux horodatages 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 fois
-
Confirmez que la source existe et inspectez sa durée, ses dimensions et son conteneur avec
ffprobe. -
Appelez
edgespeak_transcribe_fileune seule fois :{ "path": "/chemin/absolu/media-source", "timestamps": "word", "start_margin": 0, "end_margin": 0 }Ajoutez
min_chars/max_charsuniquement lorsque l'utilisateur demande des longueurs de légende différentes. Ajoutezmodeluniquement lorsque l'utilisateur en nomme un. Si la localité est importante, inspectezedgespeak_list_modelset ne choisissez pas un modèle distant sans consentement. -
N'appelez pas
edgespeak_alignaprès une transcription réussie avec horodatage par mot. Cette requête suit déjà le chemin d'alignement forcé local en ligne d'EdgeSpeak et renvoiesegments[].words[]. -
Pour une réponse MCP longue, utilisez
artifact_json_path. Pour une réponse en ligne, sauvegardez l'objetresultau format JSON. Le convertisseur accepte soit un JSON de transcription direct, soit un wrapper avecresult. -
Exigez un timing de mot non vide dans chaque segment temporisé. N'inventez jamais de timing de mot et ne retombez pas silencieusement sur le timing du segment.
Utilisez edgespeak_align uniquement lorsque l'utilisateur a fourni une transcription finale externe ou a modifié de manière substantielle le texte ASR. L'alignement doit utiliser la séquence de mots finale ; ne conservez jamais d'horodatages obsolètes après des modifications.
Un alignement qui ne peut pas placer le texte est une erreur, pas un résultat vide : edgespeak_align renvoie isError: true avec un JSON {"code": "alignment_failed" | "alignment_search_budget_exceeded", ..., "alignment": {...}} et aucun mot (le CLI se termine avec un code non nul et le même objet sur la ligne stderr qui commence par error: alignment_failed: ou error: alignment_search_budget_exceeded:). Décidez uniquement à partir de l'objet alignment :
alignment.retry_recommended: true→ appelezedgespeak_alignune fois de plus avec"search_effort": "extended"(CLI :--search-effort extended). Il cherche plus largement, tourne plus lentement et utilise plus de mémoire ; citezalignment.estimated_extra_byteslorsque vous informez l'utilisateur.- Sinon, ou sur
alignment_search_budget_exceeded, ne relancez pas le même appel. Vérifiez que la transcription correspond à ce média, ou alignez un clip plus court. Voiredgespeak-alignpour la liste complète des codes et champs.
Ne construisez jamais de repères karaoké à partir d'un alignement échoué : pas de mots espacés uniformément, pas de repli sur le timing du segment, pas de timings reportés de la transcription pré-édition.
Prérequis
- Node.js 18 ou plus récent pour les scripts fournis.
- FFmpeg compilé avec
libass, plusffprobe— un exécutable séparé qui doit également être dans le PATH. Chaque aperçu et chaque incrustation passe par le filtreass, donc un FFmpeg sans libass échoue avecNo such filter: 'ass'quel que soit le préréglage sélectionné. L'incrustation en MP4/MOV/MKV/TS nécessite en pluslibx264; WebM nécessitelibvpxetlibopus. Homebrew et les principaux paquets de distribution incluent tout cela. edgespeak-cli(ou l'application EdgeSpeak) pour la transcription, qui fonctionne sur macOS Apple Silicon, Linux x86_64 et Windows x64. Sur Windows, installez l'application de bureau EdgeSpeak, qui inclut le CLI. Sur macOS et Linux, dirigez l'utilisateur vers l'installateur autonome à l'adresse https://edgespeak.com/docs/cli#install (pas besoin d'application de bureau ; sur Linux, il détecte automatiquement les GPU NVIDIA et installe un runtime compatible CUDA). L'utilisateur exécute l'installateur ; ne l'exécutez pas vous-même. LeminCliVersiondu frontmatter est la version la plus ancienne du CLI pour laquelle ce skill est écrit — siedgespeak-cli --versionest plus ancien, ou si un flag documenté est manquant dans--help, exécutezedgespeak-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 aux côtés de ffmpeg
ffmpeg -filters | grep -w ass # le moteur de rendu ASS (libass)
ffmpeg -encoders | grep -w libx264 # sortie H.264
Générer des fichiers ASS et des aperçus
Générez le préréglage sélectionné :
node <skill-dir>/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 repère actif de la source réelle. C'est le chemin par défaut, pas un cas particulier — et chaque PNG qu'il produit doit être montré :
node <skill-dir>/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-le deux fois avec des horodatages différents lorsque la source mélange des scènes claires 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 en balises \kf/\k.
L'espacement entre les mots provient du text du repère 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 les traits d'union dans haute-performance (l'alignement le divise en haute et performance, et le trait d'union n'appartient à aucun des deux) et ce qui maintient les langues CJK sans espace au lieu de rendre 本地转录 comme 本 地 转 录. Si un mot ne peut pas être trouvé dans text, le générateur se rabat sur 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 repère et n'a besoin d'aucun flag supplémentaire :
node <skill-dir>/scripts/karaoke-ass.mjs /chemin/vers/transcription.zh.json \
-o /sortie/source.karaoke.ass --style boxed
Les deux lignes vivent dans un é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-topl'inverse, pour les spectateurs qui suivent 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 se pose sur la langue principale dans les deux cas.--layout source-onlyignore les traductions et produit le fichier monolingue.- Seule la ligne source défile. Les horodatages des mots décrivent l'audio source, donc la traduction ne reçoit pas de balises
\k— elle conserve un remplissage uni pour tout le repère. Distribuer la durée du repère sur les caractères de la traduction serait un timing inventé ; ne l'ajoutez pas. Pour un véritable timing des mots dans la langue cible, vocalisez la traduction avec un skill de synthèse vocale (si installé) et alignez cet audio.
La police n'est pas optionnelle — sur l'une ou l'autre ligne
libass ne substitue pas les polices par glyphe comme le ferait un navigateur. Le texte CJK dans une police de style latin s'affiche sous forme de boîtes vides — silencieusement, tout au long d'une incrustation. Chaque préréglage est livré avec une police latine, donc le générateur choisit en fonction du script plutôt que d'hériter de celle du préréglage. Cela s'applique également à la ligne source, pas seulement à la traduction : une transcription en chinois sans --font s'incrusterait autrement comme une rangée de boîtes.
- Le script est détecté à partir du texte de la ligne lui-même et mis en correspondance via
fc-match :lang=<balise>, en prenant un seul alias de famille ASCII (une liste d'alias briserait 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 lorsquefc-listindique que cette police ne couvre pas la langue détectée. Ne contournez pas l'erreur en choisissant une autre police latine — vérifiez ce qui couvre le script avecfc-list :lang=zh-cn family.- Le texte latin conserve la police du préréglage inchangée ; 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: falselorsque la couverture n'a pas pu être vérifiée, donc rapportez cette réserve plutôt que d'affirmer que la police est correcte. - L'exécution signale
source_font/source_scriptchaque fois que la source n'est pas en latin.
Une transcription partiellement traduite est rejetée catégoriquement — cela signifie que l'étape de traduction s'est arrêtée prématurément, et émettre des repères uniquement source pour le reste ferait passer un fichier incomplet pour terminé.
Incruster les sous-titres
Lorsque la source contient une vidéo et que l'utilisateur souhaite des sous-titres incrustés :
node <skill-dir>/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 -> repli 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 de la source
Ré-encoder à une qualité fixe ignore ce que la source a fourni, et l'écart peut être important : incruster CRF 21 dans un fichier AV1 léger de 1,5 Mbps donne une copie H.264 de 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 a besoin d'environ 1,6 fois le débit binaire de l'AV1 pour une qualité comparable). La qualité provient toujours du CRF ; le plafond l'empêche seulement de dépasser la source.
C'est automatique pour les cibles x264. VP9/WebM est laissé tel quel 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 signalement du résultat.
Remplacez uniquement lorsque l'utilisateur demande un débit binaire ou un niveau de qualité spécifique :
--crf <n>définit l'objectif de qualité (plus bas est meilleur, 21 par défaut pour H.264).--maxrate <rate>remplace le plafond dérivé, par exemple--maxrate 4M.--maxrate nonedé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 avec le débit binaire de sortie avant de proposer un changement, et rappelez-vous que les images plates ou les enregistrements d'écran se compressent beaucoup plus difficilement que les prises de vue réelles — le texte des sous-titres lui-même reste net même à CRF 28, donc ce n'est jamais la contrainte.
Repli CLI
Repliez-vous sur edgespeak-cli chaque fois que MCP ne peut pas effectuer le travail — y compris lorsque le serveur MCP lui-même est en cours d'exécution mais que ses outils échouent. Le cas le plus courant : l'application de bureau n'est pas en cours d'exécution, donc chaque outil MCP EdgeSpeak 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 qui reste en mémoire ne doit pas présumer qu'un service de bureau local est disponible).
# Exemple d'appel de secours
edgespeak-cli transcribe /chemin/vers/media --timestamps word \
--output /chemin/vers/transcription.json
Vérifiez edgespeak-cli --version avant de l'appeler. Si le binaire est manquant, signalez-le à l'utilisateur avec les instructions d'installation.
Résumé du workflow
- Confirmez la source et rassemblez les métadonnées avec
ffprobe. - Transcrivez avec
edgespeak_transcribe_file. - Demandez à l'utilisateur son style de sous-titres préféré (ou utilisez une préférence enregistrée). Si l'utilisateur n'a pas de préférence, montrez des aperçus avec
--preview-media. - Générez le fichier ASS avec
karaoke-ass.mjs. - Si l'utilisateur le souhaite, incrustez les sous-titres dans la vidéo avec
render-hardsub.mjs. - Signalez le résultat à l'utilisateur, y compris le chemin du fichier de sortie et les options pertinentes (police utilisée, débit binaire, etc.).
Dépannage
| Problème | Cause probable | Solution |
|---|---|---|
No such filter: 'ass' | FFmpeg sans libass | Installez FFmpeg avec libass (via Homebrew, le gestionnaire de paquets de la distribution, ou une version statique) |
| Les caractères CJK s'affichent sous forme de boîtes | Police manquante pour le script CJK | Utilisez --font avec une police CJK (ou --translation-font) et fc-list :lang=zh-cn family pour trouver des polices appropriées |
error: alignment_failed: | La transcription ne correspond pas à l'audio | Vérifiez que la transcription fournie correspond au média ; vérifiez le fichier audio |
| Le fichier de sortie est beaucoup plus volumineux que la source | Plafond de débit binaire trop élevé ou désactivé | Utilisez --maxrate pour limiter ou augmentez --crf pour réduire la qualité |
Impossible de trouver edgespeak-cli | CLI non installé | Dirigez l'utilisateur vers https://edgespeak.com/docs/cli#install |
Considérations éthiques
- Consentement de l'utilisateur : montrez toujours les aperçus lorsque l'utilisateur n'a pas choisi de style ; ne présumez pas de ses préférences.
- Précision des données : ne falsifiez jamais les horodatages des mots. Signalez les erreurs d'alignement telles quelles, sans les masquer.
- Transparence : informez l'utilisateur lorsqu'une police est sélectionnée automatiquement et que la vérification de couverture est désactivée (
source_font_verified: false). - Respect des ressources : les ré-encodages doivent être aussi efficaces que possible ; ne surqualifiez pas inutilement la vidéo.