boyingliu01/sous-titres-vidéo-bilingues

Bilingual Video Subtitles Sous-titres bilingues pour vidéos de formation

Le pipeline complet se trouve dans scripts/pipeline.py (point d'entrée unique, avec cache par étape et reprise possible après interruption).

Attention à l'environnement hôte : cette compétence est adaptée à différents environnements ; le backend de transcription est sélectionné automatiquement (Omni Gateway du bac à sable d'origine / API compatible OpenAI / pont whisper). En l'absence d'Omni Gateway et de backend API configuré, le système passe en mode agent : les étapes transcribe/translate se suspendent avec un code de sortie 3 et écrivent un manifeste. Une fois la transcription/traduction correspondante terminée, relancer build pour continuer. Lisez impérativement le protocole d'opération et la configuration du backend dans references/host-adaptation.md. Si le pipeline sort avec le code 3, ce n'est pas un échec : effectuez le travail demandé dans le manifeste, puis relancez.

Workflow standard

1. Obtenir les entrées : fichier vidéo + documents de référence correspondants (règlements, procédures, notes, etc. au format .docx/.txt/.md).
2. Lire les documents de référence et rédiger un glossaire glossary.txt (une ligne par terme : chinois = anglais, 10 à 40 entrées). Le glossaire détermine la cohérence de la traduction dans toute la vidéo. Couvrez impérativement : noms de règlements/procédures, rôles et abréviations (ex. PM=Project Manager), noms de documents commerciaux ou formulaires, noms de systèmes internes.
3. Exécuter la construction (en avant-plan, avec un timeout suffisant ; pour une vidéo de 50 minutes, le processus complet prend environ 15 à 25 minutes) :

python3 scripts/pipeline.py build \
  --video <chemin vidéo> --doc <chemin document de référence> \
  --work <répertoire de travail> --out <répertoire de sortie> \
  --glossary <glossary.txt> \
  --hotwords "安全红线,需求单,变更单,PM,QA,SRE" \
  --preview 90

4. Ordre de génération (chaque étape est mise en cache ; en cas d'échec, relancer la même commande pour reprendre) : setup (découpage audio) → transcribe (transcription mot à mot avec Qwen3-Omni) → timing (timeline avec whisper) → align (alignement pinyin) → clean (suppression des hésitations, segmentation en phrases) → translate (traduction chinois-anglais par lots) → package (fichier de projet + SRT + ASS) → render (vidéo d'aperçu + version complète).
5. D'abord, utilisez l'aperçu généré avec --preview pour faire valider le résultat par l'utilisateur (vous pouvez utiliser media-read pour vérifier le rendu des sous-titres par extraction d'images), puis livrez la vidéo complète, les SRT et le fichier de projet de sous-titres.

Description des livrables

Fichier	Utilisation
<nom>_Sous-titres_bilingues_chinois_anglais_Version_complète.mp4	Vidéo avec sous-titres incrustés (chinois en haut en blanc, anglais en bas en bleu clair, avec fond semi-transparent noir lisible sur tout arrière-plan)
<nom>_Sous-titres_bilingues_chinois_anglais.srt	Fichier de sous-titres bilingues (importable dans un lecteur/plateforme)
<nom>_Projet_sous-titres.json	Données principales : contient toute la timeline + le texte bilingue. À modifier seul pour les ajustements annuels
Répertoire --work	Cache des produits intermédiaires (transcription, timeline whisper). Sa conservation évite de retranscrire

Ajustements annuels (mise à jour des sous-titres après révision des règlements)

Lorsque les modifications des règlements n'affectent que quelques phrases, ne retranscrivez pas :

1. Demandez à l'utilisateur d'indiquer les plages horaires ou le contenu à modifier, ou modifiez directement le texte zh/en dans le fichier <nom>_Projet_sous-titres.json de l'année précédente (ne touchez pas start/end si la timeline ne change pas).
2. Re-rendu :

python3 scripts/pipeline.py render --project <projet.json> [--video <nouvelle vidéo>] [--srt-only]

Si la nouvelle vidéo comporte des ajouts/suppressions de phrases dans les chapitres correspondants : lancez build --stage transcribe pour obtenir une nouvelle transcription, comparez manuellement, remplacez les entrées correspondantes dans le fichier de projet, puis rendez.

Découpage en courtes vidéos par thème/rôle (apprentissage fragmenté)

Basé sur la vidéo complète déjà sous-titrée (les sous-titres bilingues sont conservés).

1. Localiser les limites des chapitres à partir des données de sous-titres : utilisez la liste des rôles/chapitres du document de référence comme mots-clés pour rechercher dans zh_lines.json (répertoire de travail) les phrases de transition typiques : "Le Nième rôle est X", "Ci-dessus sont les responsabilités de X, l'exigence est", "Les cas de violation de X sont" etc. Utilisez l'heure de début de la phrase de transition comme point de coupure (cette phrase est incluse dans l'épisode suivant).
2. Contrainte : un épisode ≤ 10 minutes (limite stricte 15 minutes) ; si un chapitre dépasse, découpez à l'intérieur du chapitre à des limites naturelles (par exemple entre "Responsabilités / Violations / Méthodes d'identification") ; ne fusionnez pas différents rôles.
3. Écrivez un plan de découpage JSON et exécutez :

{"base": "nom vidéo", "lead_in": 0.35,
 "chapters": [{"start": 0, "end": 288.4,
               "title": "01_Ouverture_But_et_synthèse", "note": "Description du contenu"}]}

python3 scripts/pipeline.py split --plan plan.json \
  --video <vidéo complète sous-titrée.mp4> --out <répertoire de sortie>

4. Sortie dans <répertoire de sortie>/<nom vidéo>_Découpage/ : épisodes nommés automatiquement + 00_Sommaire_découpage.txt (nom, plage horaire, durée, description).
5. Vérification par échantillonnage : extrayez une image du début de chaque épisode (ffmpeg capture PNG) pour confirmer que le point de coupure tombe bien sur la phrase d'ouverture du thème correspondant.

Conventions d'implémentation clés (ne pas s'en écarter)

• Le backend qwen-omni doit injecter l'intégralité du document de référence dans le prompt en tant que contexte terminologique, avec --timeout 900 --max-tokens 8192 (déjà intégré dans le script) ; pour les backends API avec ASR dédié (comme mimo-asr) qui n'acceptent pas de prompt textuel, la correction terminologique repose sur l'étape clean qui confronte le texte au document.
• whisper est utilisé uniquement pour la timeline ; son texte reconnu est systématiquement ignoré (le texte chinois est de mauvaise qualité, mais les horodatages sont précis).
• L'alignement doit être global, par chaîne pinyin (les erreurs d'homophones sont automatiquement résolues au niveau pinyin) ; un alignement glouton phrase par phrase entraîne une dérive globale.
• Qualité d'alignement : qual mean ≥0.75 en sortie d'alignement est normal ; <0.6 vérifiez d'abord la couverture vocale de whisper (voir references/troubleshooting.md).
• Pour les tâches CPU longues (whisper/render), tenez compte de la politique de nettoyage des tâches en arrière-plan de l'hôte ; exécutez en avant-plan si nécessaire.
• Restrictions réseau : HuggingFace nécessite un miroir ; le script intègre déjà HF_ENDPOINT=hf-mirror.com et HF_HUB_DISABLE_XET=1, ne les supprimez pas.

Dépannage

Voir references/troubleshooting.md pour traiter : dépassement de délai d'upload, lignes uniques trop longues dans la transcription, faible qualité d'alignement, polices mal affichées, échecs de rendu, etc.