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
- 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 queDASHSCOPE_BASEcorrespond à la région de la clé. Rien n'est téléchargé ni facturé. Ajoutez--offlinepour ignorer cette requête. - Si le code de sortie est 3, exécutez
bash scripts/install.shet corrigez chaque ligneFAILqu'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). - 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 | Écrit | API payante |
|---|---|---|
fetch <url-ou-fichier> | src.mp4 | non |
transcribe [--audio-url URL] | audio.mp3, asr_task.json, transcription.json | oui |
annotate | annotations.json | oui |
ass [--no-pop] [--no-annotate] | subs.ass | non |
render [--segment 1200] [--out FILE] | karaoke.mp4 | non |
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
| Code | Signification | Que faire |
|---|---|---|
| 0 | Terminé | Continuer. |
| 2 | Erreur d'utilisation | Lire l'--help de la sous-commande. |
| 3 | Environnement non prêt | Suivre 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 distant | Suivre la ligne next:. Relancer la même commande conserve le travail déjà effectué. |
| 5 | Entrée d'une étape précédente manquante | Exécuter l'étape nommée dans la ligne next:. |
| 1 | Échec inattendu | Lire 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.doctorsignale uniquement si elle est définie. transcribeetannotatecoûtent de l'argent sur le compte de l'utilisateur. N'utilisez pas--forcesur 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.