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,boxedethigh-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équence | Préréglage |
|---|---|
| Paysage général ou contenu mixte | classic |
| Fond propre, plutôt sombre | minimal |
| Fond chargé, lumineux, diapositives ou enregistrement d'écran | boxed |
| Vidéo verticale/mobile ou fond 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 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
-
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 sous-titres 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 timestamps par mot. Cette requête exécute 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, enregistrez l'objetresultau format JSON. Le convertisseur accepte soit le JSON de transcription direct, soit un wrapper avecresult. -
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 queffprobe— un exécutable séparé qui doit également être dans 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 outrelibx264; WebM nécessitelibvpxetlibopus. 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, utilisezcurl -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). LeminCliVersiondans l'en-tête est la version minimale de l'interface en ligne de commande pour laquelle cette compétence est écrite — siedgespeak-cli --versionest plus ancien, ou si un indicateur documenté manque 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 à 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-topl'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-onlyignore 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 avecedgespeak-broadcastet 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 lorsquefc-listindique 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 avecfc-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: falselorsque 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_scriptchaque 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 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 à 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_