Documentation de add_dub

Bienvenue dans la documentation officielle de add_dub, l'outil autonome de vocalisation de sous-titres en voix-off et de traduction automatisée pour Windows 10 et Windows 11 (64 bits).

📌 Présentation de l'Outil

add_dub transforme automatiquement les sous-titres d'une vidéo en une voix-off parlée et synchronisée, mixée avec le son d'origine qui s'atténue pendant les dialogues.

♿ Pourquoi cet outil et pour qui ?

Étant moi-même malvoyant, j'ai développé add_dub par besoin personnel : il m'est tout simplement impossible de lire les sous-titres à l'écran lorsque je regarde des films, séries ou animés étrangers.

add_dub a été créé avant tout comme un outil d'accessibilité universelle :

🎯 Philosophie de add_dub

add_dub n'a pas pour but de réaliser un doublage IA lourd avec clonage vocal, qui nécessiterait des ressources matérielles conséquentes (carte graphique dédiée, dizaines de gigaoctets de modèles ou installations complexes).

add_dub adopte le principe éprouvé de la voix-off :

🚀 Démarrage Rapide

La version officielle de add_dub est distribuée sous forme d'une application portable autonome pour Windows 10/11 64-bit : Python et les outils sont fournis dans l’archive.

Télécharger pour Windows 10/11 add_dub_v2.0.0_win64.zip

Étapes d'installation et premier test :

  1. Téléchargez l'archive add_dub_v2.0.0_win64.zip depuis la page des releases.
  2. Décompressez l'archive dans le dossier de votre choix.
  3. Double-cliquez sur add_dub.exe.
  4. Cliquez sur Ouvrir et choisissez vos vidéos ou un dossier sur votre ordinateur.
  5. Choisissez la piste audio, les sous-titres et la voix. Activez la traduction si nécessaire.
  6. Vous pouvez écouter un extrait dans l’onglet Essai pour ajuster les réglages.
  7. Cliquez sur Ajouter à la liste d’attente, puis sur Démarrer.
  8. Votre vidéo doublée est générée dans le dossier output/ !

Le bouton Ouvrir permet de choisir vos vidéos dans input/ ou dans tout autre dossier de votre ordinateur. Pour un premier test avec l’exemple fourni, choisissez input/extrait.mkv.

add_dub.exe ouvre l’interface graphique, add_dub_console.exe l’assistant console et add_dub_player.exe le lecteur.

💡 Pour Aller Plus Loin

⚙️ Fonctionnement du pipeline & Formats pris en charge

Lors du traitement, add_dub exécute automatiquement une chaîne de 5 étapes :

👁️ Support OCR & Traduction IA intégrés

Sous-titres d'images (Blu-ray & DVD) : Si vos sous-titres dans un conteneur MKV ne sont pas au format texte (SRT / ASS / WebVTT) mais au format image (PGS sur Blu-ray ou VobSub / SUB-IDX sur DVD), add_dub lance automatiquement une reconnaissance optique de caractères (OCR via Subtitle Edit & Tesseract 5) en arrière-plan pour les convertir en texte.

Traduction locale (CTranslate2) : Les modèles sont téléchargés à la première utilisation, puis CTranslate2 traduit sur votre ordinateur, sans clé API payante. Le moteur Google Traduction utilise Internet. La voix doit être choisie dans la langue du texte à lire.

🎮 Mode Interactif (Par défaut)

Ouvrez add_dub_console.exe pour utiliser l’assistant. Ce lanceur démarre par défaut en mode interactif. Il analyse automatiquement le dossier input/ et vous pose une série de questions numérotées simples.

Déroulement pas-à-pas :

  1. Sélection des vidéos : Choisissez le ou les fichiers à traiter dans input/.
  2. Piste audio : Choisissez la piste audio source à utiliser (ex: Japonais, Anglais...).
  3. Sous-titres : Sélectionnez la piste de sous-titres interne (MKV) ou un fichier .srt externe.
  4. Moteur TTS & Voix : Sélectionnez le moteur (Edge TTS recommandé, OneCore hors-ligne ou gTTS) puis choisissez la voix parmi les dizaines de langues et voix disponibles.
  5. Traduction (optionnelle) : Indiquez si vous souhaitez traduire automatiquement les sous-titres vers une autre langue avant la vocalisation.
  6. Réglages fins : Ajustez le niveau de ducking (atténuation du fond), les volumes ou les offsets si demandé.

📁 Traitement d'une saison entière (Multi-vidéos)

💡 Gain de temps pour les séries

Si vous avez par exemple une saison de 12 ou 24 épisodes dans le dossier input/ et que vous les sélectionnez tous lors de la première étape :

Les choix de configuration (audio, sous-titres, voix, langue) ne vous sont posés qu'UNE SEULE FOIS pour le premier épisode. add_dub applique ensuite automatiquement cette configuration à tous les épisodes restants, à la chaîne !

🎧 Mode Test & Ajustement rapide des volumes

Si l'option ask_test_before_cleanup = true est activée dans votre configuration, add_dub vous proposera d'écouter la vidéo finale avant de nettoyer les fichiers temporaires.

Si le volume de la musique vous paraît trop fort ou la voix trop faible, vous pouvez simplement entrer de nouveaux niveaux de volume (ex: bg = 1.5 et tts = 2.5). add_dub ré-exécute alors uniquement le mixage et l’export sans devoir recalculer tout le TTS !

⚙️ Configuration Avancée (options.conf)

Le fichier options.conf situé à la racine vous permet de définir vos préférences par défaut et de personnaliser complètement le comportement du mode interactif. Le bouton Paramètres de l’interface graphique permet aussi de modifier ces préférences.

Le rôle de la lettre d (Display)

Chaque ligne du fichier suit le format : clé = valeur [d]

Détail de toutes les options du fichier modèle (options.example.conf) :

Option Valeur du fichier modèle Description
input_dir "input" Dossier d'entrée contenant les vidéos à traiter.
output_dir "output" Dossier de destination où enregistrer les vidéos générées.
tmp_dir "tmp" Dossier de travail pour les fichiers temporaires.
language d auto Langue de l'interface du programme (auto pour détection automatique système, fr, en, es, de, it).
tts_engine d "onecore" Moteur de synthèse vocale : "onecore" (Windows hors-ligne), "edge" (Microsoft en ligne), "gtts" (Google).
voice_id "" Identifiant de la voix (vide = sélection ou détection automatique). Vous pouvez y coller un voice_id spécifique (ex: "fr-FR-DeniseNeural").
min_rate_tts 1.2 Vitesse minimale de base pour la lecture TTS (1.0 = vitesse normale).
max_rate_tts 1.8 Plafond d'accélération maximale quand une phrase longue doit rentrer dans une réplique courte.
db d -5.0 Atténuation (ducking) de l'audio original en dB pendant les dialogues (toujours interprété comme une baisse).
bg d 1.0 Facteur multiplicateur de volume du fond sonore original (1.0 = 100%).
tts d 1.0 Facteur multiplicateur de volume de la voix parlée TTS (1.0 = 100%).
offset d 0 Décalage temporel des sous-titres et de la voix en millisecondes (+/-).
offset_video 0 Décalage de la vidéo par rapport à l'audio en millisecondes.
audio_codec ac3 Codec audio pour les pistes exportées : ac3, aac, mp3, flac, opus.
audio_bitrate 256 Débit de la piste audio encodée en kbps (ex: 128, 192, 256, 320).
orig_audio_lang Original Ancienne préférence : le libellé est désormais déterminé à partir de la langue détectée pour la piste audio.
ask_test_before_cleanup false Si true, propose d'écouter la vidéo et de réajuster les volumes avant nettoyage.
translate d false Active ou non la traduction automatique des sous-titres par IA.
translate_to d fr Code de la langue de destination (ex: fr, en, es, de...).
translate_from d auto Langue source des sous-titres (auto pour détection automatique par IA).
reuse_translated_subs d true Si un fichier de sous-titre déjà traduit existe dans srt/, le réutilise sans recalculer.
translation_engine d ctranslate2 Moteur de traduction : ctranslate2 pour traduire localement après téléchargement des modèles, ou google pour traduire en ligne.

⚡ Mode Batch (Ligne de Commande)

Le mode Batch permet d'exécuter add_dub de manière 100% non interactive en passant tous les arguments en ligne de commande avec le drapeau --batch.

C'est l'outil parfait pour :

💡 Exemples de Commandes Représentatives

1. Traiter une vidéo unique avec Edge TTS et une voix française

add_dub_console.exe --batch -i "C:\Videos\film.mkv" --tts-engine edge --voice "fr-FR-DeniseNeural"

Explication : Traite directement le fichier film.mkv avec la voix Microsoft Denise et place le résultat dans output/.

2. Traiter récursivement tout un dossier de séries

add_dub_console.exe --batch -i "C:\Videos\Anime_Saison_1" --recursive --preserve-tree

Explication : Parcourt tous les sous-dossiers, traite chaque vidéo trouvée et recrée la même arborescence de dossiers dans output/.

3. Traduire automatiquement de l'anglais vers le français avant doublage

add_dub_console.exe --batch -i "C:\Videos\doc.mp4" --sub srt --translate --translate-from en --translate-to fr --translation-engine ctranslate2 --tts-engine edge --voice "fr-FR-HenriNeural"

Explication : Lit les sous-titres anglais du fichier doc.srt placé à côté de doc.mp4, les traduit en français via CTranslate2, puis génère la voix-off française et assemble le résultat.

4. Ajuster précisément le mixage sonore

add_dub_console.exe --batch -i "C:\Videos\film.mkv" --bg-mix 0.7 --tts-mix 1.4 --ducking-db -6.0

Explication : Règle le volume de fond à 70%, la voix à 140% et applique une atténuation plus forte de -6 dB pendant les paroles.

5. Reprise de traitement sans écraser l'existant

add_dub_console.exe --batch -i "C:\Videos\Series" --recursive --skip-existing

Explication : Vérifie si la vidéo de sortie finale existe déjà dans output/ et l'ignore immédiatement si c'est le cas (très utile en cas d'interruption).

📋 Référence Complète des Options CLI (Batch)

Option CLI Argument Description
--batch (flag) Active le mode d'exécution automatisé sans poser de question.
-i, --input PATH... Chemin(s) vers un ou plusieurs fichiers vidéo ou répertoires.
--output-dir PATH Dossier personnalisé où enregistrer les vidéos finales (défaut : output/).
-r, --recursive (flag) Scanne récursivement les sous-dossiers lors du passage d'un répertoire.
-t, --preserve-tree (flag) Préserve l'arborescence des dossiers source dans le dossier de sortie.
--skip-existing (flag) Ignore le traitement si le fichier de sortie existe déjà dans output/.
--overwrite (flag) Écrase les fichiers de sortie existants sans confirmation.
--dry-run (flag) Simule l'exécution et affiche les fichiers qui seraient traités sans rien modifier.
--tts-engine onecore|edge|gtts Moteur de synthèse vocale à utiliser.
--voice ID Identifiant de la voix (ex: fr-FR-DeniseNeural).
--audio-index IDX Index global FFmpeg de la piste audio, visible avec FFprobe ; ce n’est pas son numéro parmi les seules pistes audio.
--audio-codec CODEC Codec audio pour l'encodage final (ac3, aac, opus, flac, mp3).
--audio-bitrate KBPS Débit de la piste audio (ex: 192).
--sub auto|srt|mkv:N|stream:N Source des sous-titres : auto, srt, numéro parmi les pistes de sous-titres avec mkv:N (à partir de zéro), ou index global FFmpeg avec stream:N.
--translate / --no-translate (flag) Active ou désactive la traduction automatique des sous-titres avant synthèse.
--translate-to LANG Code langue cible de traduction (ex: fr, en, es).
--translate-from LANG Langue source (auto par défaut).
--translation-engine ctranslate2|google Choisit le moteur de traduction local ou en ligne.
--ducking-db DB Atténuation du fond en décibels (ex: -5.0).
--bg-mix FLOAT Volume du fond sonore original (ex: 1.0, 1.5).
--tts-mix FLOAT Volume de la voix TTS (ex: 1.2, 2.0).
--offset-ms MS Décalage des sous-titres et de la voix en millisecondes.
--offset-video-ms MS Décalage de la vidéo par rapport à l'audio en millisecondes.
--min-rate-tts FLOAT Vitesse minimale de base pour la synthèse.
--max-rate-tts FLOAT Vitesse maximale autorisée pour l'accélération des phrases longues.
--limit-duration-sec SEC Limite le traitement aux N premières secondes de la vidéo. La coupe peut varier légèrement selon la vidéo.
--offline (flag) Interdit services distants et téléchargements. Exige OneCore et, si vous traduisez, des modèles locaux déjà téléchargés.

🪟 Interface de production (--gui)

Ouvrez add_dub.exe, puis utilisez Ouvrir pour choisir des vidéos ou un dossier. Les sous-dossiers sont inclus. Choisissez les pistes, la voix et les réglages ; ils peuvent être adaptés à un dossier ou à une vidéo.

L’onglet Essai permet de sélectionner et d’écouter un passage avant de traiter la vidéo entière. Cliquez sur Tester pour le préparer. Les réglages de voix, de traduction et de volumes sont ceux de la vidéo sélectionnée.

Cliquez sur Ajouter à la liste d’attente, puis sur Démarrer. La file distingue En attente et Terminé. Choisissez le dossier de sortie et le remplacement ou l’ignorance des exports existants. Pour un dossier, l’arborescence est conservée en sortie.

Arrêter interrompt la vidéo en cours, qui sera retraitée depuis le début au prochain démarrage. Une sortie précédente est remplacée après réussite du nouvel export. Les barres et le temps restant donnent une estimation de la progression.

Paramètres modifie les préférences pour les prochains ajouts ; les lots déjà configurés conservent leurs réglages. L’interface est disponible en français, anglais, espagnol, allemand et italien. Redémarrez après un changement de langue.

▶ Lecteur vidéo séparé (--player)

Ouvrez add_dub_player.exe, puis une vidéo avec le bouton dossier ou Ctrl+O. Le clic droit permet de choisir les pistes audio et sous-titres et de lancer Vocaliser les sous-titres.

Choisissez la voix, sa vitesse, l’atténuation et les volumes. Le lecteur prépare l’audio avant l’écoute, sans exporter de nouvelle vidéo. Enregistrer les réglages les conserve séparément de ceux de l’interface de doublage. Ctrl+Maj+D prépare ensuite la voix avec ces réglages et relance la lecture depuis le début.

La vocalisation utilise les sous-titres intégrés à la vidéo. Pour un SRT externe ou pour traduire les sous-titres, utilisez l’interface de doublage. Les fichiers audio préparés sont conservés, mais ne sont pas réutilisés automatiquement lors d’une nouvelle préparation.

Espace met en pause, les flèches déplacent de cinq secondes, M coupe le son et F bascule le plein écran.

🛠️ Pour les Développeurs (Code Source)

Si vous souhaitez modifier le code source, contribuer au projet ou exécuter add_dub directement depuis Git sans passer par la version binaire pré-compilée, cette section est faite pour vous.

📥 Cloner le projet & Premier Lancement

Récupérez le dépôt officiel depuis GitHub et entrez dans le dossier du projet :

git clone https://github.com/Jobijoba2000/add_dub.git
cd add_dub
start_add_dub.bat

⚙️ Ce qui se passe au premier lancement (start_add_dub.bat)

Le script start_add_dub.bat est conçu pour automatiser l'intégralité de la configuration de votre environnement de développement :

  1. Environnement virtuel Python : Il crée automatiquement un environnement virtuel (venv) et installe l'ensemble des bibliothèques nécessaires à partir de requirements.lock.txt.
  2. Téléchargements individuels dans tools/ :

    Le lanceur prépare Python avec scripts/prepare_python.ps1, puis scripts/prepare_tools.py prépare FFmpeg, MKVToolNix, Subtitle Edit, Tesseract et mpv. Les archives sont contrôlées par SHA-256 et conservées dans .cache/. Les modèles OCR sont téléchargés par add_dub à la demande. Subtitle Edit utilise .NET Framework 4.8.

💡 Isolation complète de l'environnement

Grâce au dossier tools/ et à son environnement virtuel dédié, le projet fonctionne de manière 100% autonome et n'interfère jamais avec vos autres installations Python ou vos utilitaires système.

⚡ Mode Batch via Script Source

Si vous souhaitez lancer des commandes automatisées en mode Batch à partir du code source, passez simplement vos arguments CLI directement au script start_add_dub.bat :

start_add_dub.bat --batch -i "C:\Videos\film.mkv" --tts-engine edge --voice "fr-FR-DeniseNeural"
add_dub : Projet Open-Source sous licence GNU GPLv3 • Créé pour rendre le contenu accessible à tous.