Communitygithub.com

dub-studio

Doublez une vidéo localement en traduisant et ré-énonçant la voix tout en conservant la musique et les effets sonores, sans service payant. Il transcrit localement avec faster-whisper (ou lit un fichier SRT/VTT), vous traduisez ligne par ligne en JSON avec un budget de temps, supprime la voix originale avec Demucs (ou une solution de repli), voix chaque ligne avec une voix synthétique Kokoro intégrée, ajuste les lignes à leurs plages (accélération, puis pauses, sinon un indicateur), mixe à un volume sonore cible (-16 LUFS par défaut) et produit un MP4, des sous-titres bilingues SRT/VTT, un rapport de timing et une feuille. À utiliser lorsque l'utilisateur souhaite doubler, traduire, ré-énoncer ou localiser une vidéo ou une voix off en espagnol, français, italien, portugais brésilien, hindi ou anglais, ou souhaite une « version espagnole » d'une vidéo. Uniquement pour les vidéos que l'utilisateur possède, dont il a les droits, ou dont la voix est déjà synthétique ; ne clone jamais une voix. Le malais, le japonais, l'allemand et les autres langues sans voix Kokoro fonctionnelle ne sont pas pris en charge.

Qu'est-ce que dub-studio ?

dub-studio est un pipeline de doublage vidéo entièrement local, sans abonnement ni service cloud. Il permet de remplacer la voix d'une vidéo par une traduction dans une autre langue, tout en conservant la musique et les effets sonores. Il prend en charge l'anglais, l'espagnol, le français, l'italien, le portugais brésilien, le hindi et le mandarin (expérimental), et peut transcrire à partir de n'importe quelle langue reconnue par faster-whisper. Le flux de travail typique consiste à préparer le projet (`prepare`), à traduire chaque ligne dans un fichier JSON (en respectant une limite de temps et de caractères), à vérifier les erreurs (`lint`), puis à construire la vidéo finale (`build`) avec mixage audio et normalisation du volume sonore. Il intègre la séparation vocale par Demucs (ou des méthodes de repli comme la soustraction du centre ou le ducking) et synthétise la voix traduite à l'aide de Kokoro. L'outil impose des règles éthiques strictes : vérification des droits d'utilisation, interdiction de clonage vocal, et étiquetage systématique des vidéos comme étant doublées avec une voix synthétique. Il est destiné aux développeurs et utilisateurs avancés qui souhaitent un contrôle complet sur le processus de doublage dans un environnement en ligne de commande.

Compatible avec~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/VinVirtual/dub-studio/tree/HEAD

Demander à votre IA préférée

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

Documentation

Que fait dub-studio ?

Pipeline : vidéo -> audio -> faster-whisper (ou sous-titres de l'utilisateur) -> lignes source minutées -> votre traduction (JSON, une ligne chacune, dans un budget de temps) -> Demucs supprime la voix -> Kokoro voix chaque ligne traduite -> ajustement temporel (atempo, pauses, indicateurs) -> mix avec le fond sonore -> volume sonore -> MP4 + sous-titres + rapport.

Dossier de la compétence (écrit $D ci-dessous) : ce dossier. Chaque commande est $D/dub <commande> ... ; $D/dub help les liste.

Règles (à lire en premier)

  • Droits. --rights est la déclaration de l'utilisateur lui-même ; l'outil l'enregistre mais ne peut pas la vérifier. Ne doublez que des vidéos que l'utilisateur a créées ou possède (--rights own), pour lesquelles il a une autorisation écrite ou une licence de doublage (licensed), ou dont la parole est déjà une voix synthétique qu'il peut remplacer (synthetic). Demandez si ce n'est pas clair. Si la vidéo montre ou fait parler une personne réelle qui n'a pas accepté, ne la doublez pas. Ne faites jamais dire à quelqu'un quelque chose qu'il n'a pas dit.
  • Pas de clonage. La nouvelle voix est toujours l'une des voix intégrées de Kokoro, choisie par son nom. N'essayez jamais d'imiter le locuteur original ou une personne réelle, et ne transmettez jamais un enregistrement comme voix (l'outil le refuse).
  • Étiquetez-la. Les métadonnées du MP4 de sortie, les fichiers VTT et out/<lang>/README.md indiquent que le doublage utilise une voix synthétique. Conservez cette étiquette lorsque vous remettez les fichiers et dites à l'utilisateur de la conserver lorsqu'il publie.
  • Qualité de la traduction. Vous écrivez la traduction. Dites qu'il s'agit d'une traduction automatique et suggérez qu'un locuteur courant la vérifie avant publication.

Langues

Exécutez $D/dub languages pour la liste en direct. Mesuré sur cette machine (Kokoro v1.0 via kokoro-onnx, phonèmes espeak-ng), vérifié en lisant la voix à haute voix avec reconnaissance vocale :

codelanguestatut
en-us, en-gbAnglaispris en charge
esEspagnolpris en charge
fr-frFrançaispris en charge
itItalienpris en charge
pt-brPortugais brésilienpris en charge
hiHindicorrect : compréhensible, quelques mots erronés
cmnChinois mandarinexpérimental : la plupart n'est pas compris à la relecture ; refusé sans --experimental
jaJaponaisne fonctionne pas avec kokoro-onnx (les kanji sont lus comme « lettre chinoise »)
msMalaisnon pris en charge : Kokoro n'a pas de voix malaise

Toute autre langue (allemand, coréen, indonésien, arabe...) n'est pas prise en charge : dites-le clairement et ne substituez pas la voix d'une autre langue. Toute langue que faster-whisper connaît peut être la source.

Flux de travail

  1. $D/dub check. Corrigez toute ligne MANQUANTE (check_env.sh affiche les commandes). Demucs est facultatif ; sans lui, le fond sonore tombe en repli (voir ci-dessous).
  2. Confirmez les droits et les langues cibles avec l'utilisateur.
  3. $D/dub prepare <video> --out <projet> --to es,fr-fr --rights own [--from en]
    • Ajoutez --srt subs.srt (ou .vtt) avec --from <lang> lorsque l'utilisateur a un script ou des sous-titres corrects : cela ignore la reconnaissance vocale et utilise ces temps de repère comme lignes.
    • L'entrée doit avoir un flux vidéo et une piste audio. --from doit être un code de langue simple (en, pt-BR).
    • Exécuter prepare à nouveau sur le même dossier est refusé, car source.json peut contenir des corrections. --force remplace source.json et recrée les fichiers de traduction.
    • Sans cela, faster-whisper small s'exécute sur le CPU (--model base est plus rapide, medium plus précis). Lisez source.json et corrigez les mots mal entendus avant de traduire (conservez les identifiants et les temps).
    • --voice es=em_alex choisit une voix ; --max-tempo 1.2 abaisse la limite d'accélération ; --target -23 définit le volume sonore de diffusion.
  4. Traduisez. Ouvrez chaque fichier translations/<lang>.json. Pour chaque ligne, écrivez la traduction de source dans text :
    • Une ligne entrée, une ligne sortie : ne fusionnez, ne divisez, ne réordonnez et ne supprimez jamais de lignes, ne changez jamais id.
    • Restez dans les budget.ideal caractères (tient à vitesse normale). budget.max est la limite stricte (parlé à la vitesse d'accélération maximale). Plus court est mieux que plus rapide : supprimez les mots de remplissage, utilisez la formulation naturelle la plus courte.
    • Traduisez le sens, pas les mots. Registre parlé, naturel. Conservez les noms, noms de produits et chiffres. N'ajoutez pas de faits.
    • Texte brut uniquement : pas de crochets, d'indications scéniques, de balises ou d'emojis.
  5. $D/dub lint <projet> : corrigez chaque ERREUR (trop long, vide, manquant). Lisez les AVERTISSEMENTS (lignes longues empruntant la pause après elles ; chiffres manquants ; lignes non traduites) et raccourcissez là où vous le pouvez.
  6. $D/dub build <projet> [--separation ...] : fond sonore, voix, ajustement, mixage, volume sonore, multiplexage. Affiche le MP4 de chaque langue, le volume sonore et le nombre de lignes accélérées, décalées ou signalées. Une ligne FLAG signifie que la traduction est trop longue même avec les pauses : raccourcissez-la et reconstruisez (les voix sont mises en cache, seules les lignes modifiées sont re-voix). Les lignes poussées en retard sont signalées comme delayed, pas comme signalées : corrigez la ligne signalée, pas les autres.
  7. Regardez-la. Lisez out/<lang>/sheet.png : la ligne de la voix de doublage doit se situer dans les créneaux des lignes source ; le bleu (décalage) est acceptable, le rouge (débordement) et le violet (retardé) ne le sont pas. Lisez out/<lang>/report.md.
  8. $D/dub verify <projet> --asr : vérifie la durée, le volume sonore (mesuré avec l'ebur128 de ffmpeg : à moins de 0,5 LU de la cible, le pic réel au maximum 0,5 dB au-dessus du plafond, car le codage AAC peut en ajouter un peu), les indicateurs et l'étiquette de voix synthétique dans le MP4, et relit le doublage avec la reconnaissance vocale. Vous ne pouvez pas entendre le résultat : ce score de relecture est la façon dont vous vérifiez que la voix dit les bons mots. Les lignes sous 60 % sont listées ; regardez-les.
  9. Remettez : les MP4, les fichiers de sous-titres et les chemins de rapport, le volume sonore mesuré, les scores de relecture et la phrase d'étiquette.

Où va quoi

  • dub.json : paramètres et déclaration des droits. fit.maxTempo (1,25), fit.gap (0,12 s entre les lignes), fit.maxEarly (0,3 s qu'une ligne peut commencer en avance), loudness.target (-16 LUFS) et ceiling (-1,5 dBTP), mix.background / mix.voice (dB), mix.duck (dB, pour le repli de ducking), keepOriginal (true conserve l'audio original comme deuxième piste non par défaut), separation.
  • source.json : les lignes source minutées. translations/<lang>.json : vos traductions.
  • out/<lang>/ : <name>.<lang>.mp4, <name>.<lang>.srt|vtt (doublage uniquement), <name>.<lang>+<src>.srt|vtt (bilingue), report.md|json, sheet.png, README.md.
  • work/ : cache (audio extrait, fond sonore, lignes vocalisées), indexé par le fichier source exact, la méthode de fond sonore et le niveau de ducking. Peut être supprimé en toute sécurité ; verify --asr nécessite alors dub build à nouveau, car il lit work/<lang>/voice.wav.

Fond sonore (musique et effets)

separation dans dub.json ou --separation :

  • demucs (par défaut si installé) : htdemucs sur le CPU, environ 15 à 25 s pour un clip de 20 s ici. Meilleur résultat. Les poids sont téléchargés depuis une révision épinglée de Hugging Face sous forme de safetensors et vérifiés par rapport aux valeurs SHA-256 épinglées ; le repli pickle de demucs n'est jamais utilisé.
  • center : supprime ce qui est panoramique au centre (généralement la voix). Uniquement pour le vrai stéréo ; supprime également les basses centrées et les instruments mono.
  • duck : conserve l'audio original et le baisse (mix.duck, -18 dB) pendant que la voix originale parle. La voix originale reste faiblement audible : dites-le à l'utilisateur.
  • none : voix uniquement. auto choisit demucs, sinon centre (stéréo avec contenu latéral réel), sinon duck, et le rapport indique lequel a été utilisé.

Dépannage

  • Erreurs « trop long » : raccourcissez la ligne ; n'augmentez pas maxTempo au-dessus d'environ 1,3, cela sonne précipité.
  • Les lignes dérivent en retard (shift s augmente dans le rapport) : une ligne précédente a débordé ; raccourcissez-la.
  • Mots mal entendus dans source.json : modifiez le texte directement (conservez les identifiants et les temps) et ne relancez pas prepare (cela refuse, et --force remplacerait vos modifications et les traductions). dub lint avertit alors sur chaque traduction dont la source ne correspond plus : mettez à jour ces traductions.
  • La vidéo contient du texte incrusté ou des sous-titres dans la langue source : ils restent. Dites-le ; le doublage ne remplace que le son.
  • Les bouches à l'écran ne correspondront pas : il s'agit d'un doublage de style voix off, pas de synchronisation labiale.
  • dub prepare refuse : lisez le message (droits, langue, audio manquant, mauvais sous-titres) et corrigez cela ; ne contournez pas la vérification des droits.

Skills associés