Communitygithub.com

zgyk4167/sous-titres-karaoké

Grave des sous-titres karaoké mot par mot dans une vidéo en anglais. Chaque mot passe du blanc au vert et grossit brièvement lorsqu'il est prononcé. Ajoute optionnellement de courtes gloses en chinois simplifié (en bleu) pour les termes techniques, mots difficiles, verbes à particule et expressions idiomatiques, destinées aux apprenants de niveau CET-6. Utilisez cette compétence pour obtenir des sous-titres synchronisés avec effets karaoké, des légendes surlignées ou des sous-titres anglais avec gloses chinoises.

Qu'est-ce que sous-titres-karaoké ?

Cette compétence pour agent IA crée des sous-titres karaoké mot par mot dans des vidéos en anglais. Chaque mot devient vert et grossit brièvement lorsqu'il est prononcé, avec la possibilité d'ajouter des gloses en chinois simplifié (en bleu) pour les termes techniques, mots difficiles, verbes à particule et expressions idiomatiques, ciblant les apprenants de niveau CET-6 environ. Le pipeline fonctionne entièrement en local via l'outil CLI non interactif `scripts/pipeline.py`, enchaînant extraction audio, transcription ASR (DashScope), annotation des termes, génération de sous-titres ASS et incrustation vidéo avec ffmpeg/libass. Les API payantes sont utilisées uniquement pour la transcription et l'annotation. L'agent doit confirmer avec l'utilisateur la source vidéo, l'activation des gloses et le dossier de sortie. Les étapes supportent la reprise après interruption et les codes d'erreur guident l'utilisateur vers la résolution. Une vérification finale par extraction d'une image est recommandée pour éviter les conflits avec les sous-titres incrustés existants.

Compatible avec~Claude Code~Codex CLI~Cursor
npx skills add zgyk4167/karaoke-subtitles

Demander à votre IA préférée

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

Documentation

Sous-titres karaoké

Pipeline : vidéo → audio 16 kHz → DashScope ASR avec horodatages des mots → LLM sélectionne les termes et écrit les gloses en chinois → sous-titres ASS karaoké → incrustation par ffmpeg et libass.

Tout le travail passe par une seule interface CLI non interactive, scripts/pipeline.py. Les chemins dans ce fichier sont relatifs au répertoire de la compétence. Exécutez chaque commande depuis n'importe quel répertoire, avec le chemin de la compétence en préfixe, par exemple python3 /chemin/vers/karaoke-subtitles/scripts/pipeline.py doctor.

Avant la première exécution

  1. Exécutez python3 scripts/pipeline.py doctor. Le code de sortie 0 signifie que tout est prêt. Lorsqu'une clé est définie, une requête gratuite vérifie que DASHSCOPE_BASE correspond à la région de la clé. Rien n'est téléchargé ni facturé. Ajoutez --offline pour ignorer cette requête.
  2. Si le code de sortie est 3, exécutez bash scripts/install.sh et corrigez chaque ligne FAIL qu'il affiche. Si le script indique que sudo nécessite un mot de passe, ou que la clé API est manquante, arrêtez-vous et demandez à l'utilisateur. Ne demandez jamais à l'utilisateur de coller la clé dans le chat ; demandez-lui de la mettre dans .env (voir .env.example).
  3. Détails de configuration et paramètres : references/prerequisites.md.

Confirmer avec l'utilisateur

  • La vidéo : un fichier local ou une URL. L'utilisateur doit avoir le droit de la traiter.
  • Gloses activées (par défaut) ou désactivées (--no-annotate).
  • Où doit aller le résultat. Par défaut : retourner le chemin du fichier de sortie.

Conservez le style visuel tel quel, sauf si l'utilisateur demande un changement. Valeurs de style : references/ass-style.md.

Exécution

Une seule commande exécute tout et reprend après une interruption :

python3 scripts/pipeline.py all "<url-ou-fichier>" --work ./job [--no-annotate]

Ou exécutez les étapes une par une. Chaque étape écrit des noms de fichiers fixes dans le répertoire de travail et ignore le travail dont la sortie existe déjà. Ajoutez --force pour refaire une étape. Chaque sous-commande a --help.

ÉtapeÉcritAPI payante
fetch <url-ou-fichier>src.mp4non
transcribe [--audio-url URL]audio.mp3, asr_task.json, transcription.jsonoui
annotateannotations.jsonoui
ass [--no-pop] [--no-annotate]subs.assnon
render [--segment 1200] [--out FILE]karaoke.mp4non

L'API ASR lit l'audio depuis une URL. Par défaut, transcribe télécharge job/audio.mp3 vers le stockage temporaire gratuit de DashScope. Ce stockage conserve le fichier pendant 48 heures et seul le modèle ASR de ce compte peut le lire. Aucun bucket ni paramètre supplémentaire n'est nécessaire. Si l'utilisateur préfère son propre stockage, soit AUDIO_URL_CMD dans .env télécharge le fichier et imprime une URL, soit vous passez --audio-url URL.

La progression est envoyée sur stderr. Chaque étape imprime le chemin de sa sortie sur stdout.

Codes de sortie

CodeSignificationQue faire
0TerminéContinuer.
2Erreur d'utilisationLire l'--help de la sous-commande.
3Environnement non prêtSuivre la ligne next:, ou exécuter doctor. Demander à l'utilisateur une clé ou sudo, ou corriger le paramètre de région.
4Échec du service distantSuivre la ligne next:. Relancer la même commande conserve le travail déjà effectué.
5Entrée d'une étape précédente manquanteExécuter l'étape nommée dans la ligne next:.
1Échec inattenduLire la sortie de l'outil au-dessus de l'erreur.

Tâches longues

La transcription et le rendu peuvent prendre plus de temps qu'un outil shell ne le permet. Exécutez la commande en arrière-plan avec un fichier journal, par exemple nohup python3 scripts/pipeline.py all "<src>" --work ./job > job.log 2>&1 &, puis lisez le journal jusqu'à la fin. Si le processus meurt, relancez la même commande. La transcription reprend la tâche ASR sauvegardée au lieu de payer à nouveau ; le rendu réutilise les segments déjà terminés.

Vérification avant livraison

Extrayez une image du milieu de la sortie (ffmpeg -ss <secondes> -i job/karaoke.mp4 -frames:v 1 check.jpg) et examinez-la si vous pouvez visualiser des images. Si la source contient déjà des légendes incrustées, informez l'utilisateur et proposez deux options : les masquer avec une bande floutée, ou déplacer les nouveaux sous-titres en haut.

Règles

  • Ne jamais imprimer, journaliser ou valider DASHSCOPE_API_KEY. doctor signale uniquement si elle est définie.
  • transcribe et annotate coûtent de l'argent sur le compte de l'utilisateur. N'utilisez pas --force sur eux sans l'accord de l'utilisateur.
  • Les gloses sont uniquement en chinois simplifié. Pour les spectateurs qui ne lisent pas le chinois, utilisez --no-annotate.
  • L'ASR peut mal entendre les noms et le jargon, et peut renvoyer du texte en minuscules. Demandez à l'utilisateur de vérifier les sous-titres avant de partager la vidéo.

Skills associés