Télécharger automatiquement les sous-titres avec FlexGet et Subliminal

FlexGet ne sert pas seulement à automatiser des téléchargements. Il peut aussi surveiller un dossier de vidéos et lancer Subliminal pour récupérer automatiquement les sous-titres correspondants.

C’est pratique si vous avez une médiathèque locale, un dossier d’arrivée pour vos vidéos, un serveur personnel ou un NAS qui centralise vos fichiers. Au lieu de chercher un fichier .srt à la main, FlexGet parcourt le dossier, repère les vidéos, puis demande à Subliminal de télécharger les sous-titres disponibles.

Dans ce guide, on part d’une installation FlexGet déjà fonctionnelle. Si vous ne l’avez pas encore configurée, commencez par le tutoriel sur FlexGet et Transmission, puis revenez ici pour ajouter la partie sous-titres.

FlexGet, Subliminal et sous-titres : qui fait quoi ?

FlexGet orchestre les tâches. Il lit votre fichier config.yml, surveille un dossier, accepte les fichiers vidéo, puis lance les plugins configurés.

Subliminal fait le travail spécialisé : il analyse les fichiers vidéo, identifie le film ou l’épisode, cherche les sous-titres auprès de plusieurs fournisseurs, puis enregistre les fichiers trouvés à côté de la vidéo.

Le principe est donc simple :

1. FlexGet scanne un dossier local.
2. Il filtre les fichiers vidéo.
3. Il transmet les fichiers acceptés à Subliminal.
4. Subliminal télécharge les sous-titres dans les langues demandées.
5. Votre lecteur vidéo, Plex, Jellyfin, Kodi, VLC ou votre NAS peut ensuite les charger.

Ce n’est pas magique, mais quand c’est bien configuré, cela évite beaucoup de chasse au .srt. Et franchement, personne ne mérite de finir sa soirée à comparer quinze fichiers “proper-sync-final-v2”.

Pré-requis

Avant de commencer, vérifiez que vous avez :

• Python 3 installé ;
• pipx installé ;
• FlexGet installé et fonctionnel ;
• un dossier contenant vos vidéos locales ;
• des noms de fichiers suffisamment propres, avec titre, saison et épisode si possible ;
• un compte pour les services qui demandent une authentification, par exemple OpenSubtitles ou Addic7ed.

Pour les séries, les noms de fichiers propres améliorent énormément les résultats. Un fichier nommé Serie.Exemple.S01E03.1080p.WEB-DL.mkv a beaucoup plus de chances de trouver le bon sous-titre qu’un fichier nommé video3.mkv. Le logiciel est bon, mais il ne lit pas encore dans les pensées. Dommage, parfois.

Installer Subliminal dans l’environnement FlexGet

Si FlexGet a été installé avec pipx, il faut installer Subliminal dans le même environnement isolé que FlexGet. Sinon, FlexGet risque de ne pas voir le module Subliminal, même si la commande subliminal existe ailleurs sur le système.

Vérifiez d’abord que FlexGet fonctionne :

flexget --version

Installez ensuite Subliminal dans l’environnement FlexGet :

pipx inject flexget subliminal

Vous pouvez vérifier que FlexGet voit bien le plugin avec :

flexget plugins | grep -i subliminal

Si vous installez FlexGet dans un environnement Python classique plutôt qu’avec pipx, l’installation peut passer par l’extra officiel :

pip install "flexget[subliminal]"Code language: JavaScript (javascript)

Sur un serveur moderne, je préfère pipx pour ce type d’outil. L’environnement reste isolé, les dépendances ne polluent pas le Python système, et les mises à jour deviennent plus prévisibles.

Tester Subliminal directement avant FlexGet

Avant d’écrire la tâche FlexGet, testez Subliminal seul sur un dossier ou un fichier vidéo. Cela permet de séparer les problèmes Subliminal des problèmes FlexGet.

Exemple pour télécharger des sous-titres français et anglais dans un dossier :

subliminal download -l fr -l en /home/media/incoming

Pour forcer l’encodage des fichiers en UTF-8 :

subliminal download -l fr -l en -e utf-8 /home/media/incoming

Pour tester un seul fichier :

subliminal download -l fr -l en "/home/media/incoming/Serie.Exemple.S01E03.mkv"Code language: JavaScript (javascript)

Si cette commande ne trouve rien, FlexGet ne fera pas mieux. Dans ce cas, vérifiez le nom du fichier, la langue demandée, le provider utilisé, les identifiants, ou essayez une recherche manuelle dans VLC avec VLSub.

Configuration FlexGet simple pour télécharger les sous-titres

Éditez votre fichier de configuration FlexGet :

nano ~/.config/flexget/config.ymlCode language: JavaScript (javascript)

Ajoutez une tâche dédiée aux sous-titres :

tasks:
  get-subtitles:
    filesystem:
      path:
        - /home/media/incoming
      regexp: '.*\.(avi|mkv|mp4|m4v)$'
      recursive: yes
    accept_all: yes
    seen: local
    subliminal:
      languages:
        - fr
      alternatives:
        - en
      exact_match: yes
      single: no
      hearing_impaired: noCode language: JavaScript (javascript)

Adaptez le chemin /home/media/incoming à votre installation. Ce dossier doit contenir les vidéos pour lesquelles vous voulez récupérer les sous-titres.

Quelques remarques importantes :

• languages définit les langues prioritaires ;
• alternatives indique les langues secondaires ;
• exact_match: yes limite les mauvais sous-titres, mais peut réduire les résultats ;
• single: no ajoute le code langue au nom du fichier de sous-titres ;
• seen: local évite que cette tâche interfère avec les autres tâches FlexGet.

Avec single: no, vous obtiendrez par exemple :

Serie.Exemple.S01E03.mkv
Serie.Exemple.S01E03.fr.srt
Serie.Exemple.S01E03.en.srtCode language: CSS (css)

C’est généralement préférable si vous voulez garder plusieurs langues. Si votre lecteur exige absolument un fichier .srt sans code langue, utilisez single: yes, mais évitez cette option si vous téléchargez plusieurs langues.

Configuration avec providers et identifiants

Certains providers demandent un compte. Vous pouvez alors indiquer les identifiants dans la section authentication.

tasks:
  get-subtitles:
    filesystem:
      path:
        - /home/media/incoming
      regexp: '.*\.(avi|mkv|mp4|m4v)$'
      recursive: yes
    accept_all: yes
    seen: local
    subliminal:
      languages:
        - fr
      alternatives:
        - en
      exact_match: yes
      providers:
        - opensubtitles
        - addic7ed
        - podnapisi
        - tvsubtitles
      single: no
      hearing_impaired: no
      authentication:
        opensubtitles:
          username: votre_identifiant
          password: votre_mot_de_passe
        addic7ed:
          username: votre_identifiant
          password: votre_mot_de_passeCode language: JavaScript (javascript)

Cette configuration fonctionne comme base, mais gardez une chose en tête : les providers changent régulièrement leurs APIs, leurs quotas, leurs exigences de compte et parfois leurs domaines. Si un provider cesse de répondre, testez Subliminal directement en ligne de commande pour isoler le problème.

Pour une configuration plus propre, évitez de laisser vos mots de passe en clair dans un fichier versionné ou partagé. FlexGet propose un plugin de variables qui permet de sortir les secrets du fichier principal.

Utiliser un fichier de variables pour les identifiants

Créez un fichier dédié aux variables :

nano ~/.config/flexget/secrets.ymlCode language: JavaScript (javascript)

Ajoutez vos identifiants :

opensubtitles_user: "votre_identifiant"
opensubtitles_password: "votre_mot_de_passe"
addic7ed_user: "votre_identifiant"
addic7ed_password: "votre_mot_de_passe"Code language: JavaScript (javascript)

Protégez le fichier :

chmod 600 ~/.config/flexget/secrets.ymlCode language: JavaScript (javascript)

Puis référencez-le dans votre configuration FlexGet :

variables: secrets.yml

tasks:
  get-subtitles:
    filesystem:
      path:
        - /home/media/incoming
      regexp: '.*\.(avi|mkv|mp4|m4v)$'
      recursive: yes
    accept_all: yes
    seen: local
    subliminal:
      languages:
        - fr
      alternatives:
        - en
      exact_match: yes
      providers:
        - opensubtitles
        - addic7ed
        - podnapisi
        - tvsubtitles
      single: no
      hearing_impaired: no
      authentication:
        opensubtitles:
          username: "{? opensubtitles_user ?}"
          password: "{? opensubtitles_password ?}"
        addic7ed:
          username: "{? addic7ed_user ?}"
          password: "{? addic7ed_password ?}"Code language: PHP (php)

Résultat : votre fichier principal reste lisible, et les identifiants sont rangés dans un fichier séparé avec des permissions strictes.

Lancer la tâche FlexGet

Avant le premier lancement, vérifiez la configuration :

flexget check

Vous pouvez ensuite exécuter uniquement la tâche des sous-titres :

flexget execute --task get-subtitlesCode language: JavaScript (javascript)

Pour obtenir plus de détails pendant le test :

flexget -v execute --task get-subtitlesCode language: JavaScript (javascript)

Si tout fonctionne, des fichiers .srt apparaissent à côté de vos vidéos. Selon votre configuration, ils porteront un suffixe de langue comme .fr.srt ou .en.srt.

Automatiser avec cron

Pour exécuter la tâche régulièrement, vous pouvez utiliser cron. Ouvrez la crontab de l’utilisateur qui exécute FlexGet :

crontab -e

Ajoutez par exemple une exécution toutes les deux heures :

0 */2 * * * /home/votre_user/.local/bin/flexget execute --task get-subtitles >/dev/null 2>&1Code language: JavaScript (javascript)

Adaptez le chemin de flexget. Pour le trouver :

command -v flexget

Si vous avez plusieurs tâches FlexGet, vous pouvez aussi lancer tout le fichier de configuration avec :

0 */2 * * * /home/votre_user/.local/bin/flexget execute >/dev/null 2>&1Code language: JavaScript (javascript)

Je préfère cibler la tâche avec --task get-subtitles quand l’objectif est clair. Cela limite les effets secondaires si votre configuration FlexGet gère aussi d’autres automatisations.

Automatiser proprement avec systemd

Sur un serveur Linux moderne, un timer systemd est souvent plus propre qu’une ligne cron. Vous gagnez des logs centralisés, un statut lisible et une meilleure intégration au système.

Créez un service utilisateur :

mkdir -p ~/.config/systemd/user
nano ~/.config/systemd/user/flexget-subtitles.serviceCode language: JavaScript (javascript)

Ajoutez :

[Unit]
Description=Download subtitles with FlexGet and Subliminal

[Service]
Type=oneshot
ExecStart=%h/.local/bin/flexget execute --task get-subtitlesCode language: JavaScript (javascript)

Créez ensuite le timer :

nano ~/.config/systemd/user/flexget-subtitles.timerCode language: JavaScript (javascript)

Ajoutez :

[Unit]
Description=Run FlexGet subtitles task every two hours

[Timer]
OnBootSec=10min
OnUnitActiveSec=2h
Persistent=true

[Install]
WantedBy=timers.targetCode language: JavaScript (javascript)

Activez le timer :

systemctl --user daemon-reload
systemctl --user enable --now flexget-subtitles.timerCode language: CSS (css)

Vérifiez l’état :

systemctl --user status flexget-subtitles.timer
systemctl --user list-timersCode language: CSS (css)

Consultez les logs :

journalctl --user -u flexget-subtitles.service -n 100 --no-pagerCode language: CSS (css)

Si le timer doit tourner même lorsque votre session utilisateur n’est pas ouverte, activez le linger pour cet utilisateur :

sudo loginctl enable-linger votre_user

Configuration avancée avec subtitle_list

FlexGet propose aussi le plugin subtitle_list. Il sert à garder une liste de vidéos qui ont encore besoin de sous-titres. C’est utile si vous déplacez d’abord vos vidéos vers leur dossier final, puis téléchargez les sous-titres ensuite.

Exemple : une tâche ajoute les vidéos à une liste, puis une autre tâche traite cette liste avec Subliminal.

tasks:
  add-videos-to-subtitle-list:
    filesystem:
      path:
        - /home/media/incoming
      regexp: '.*\.(avi|mkv|mp4|m4v)$'
      recursive: yes
    accept_all: yes
    list_add:
      - subtitle_list:
          list: subtitles
          languages:
            - fr
            - en
          check_subtitles: yes

  download-subtitles-from-list:
    no_entries_ok: yes
    subtitle_list:
      list: subtitles
      recursion_depth: 3
    list_match:
      from:
        - subtitle_list:
            list: subtitles
    subliminal:
      languages:
        - fr
        - en
      providers:
        - opensubtitles
        - addic7ed
        - podnapisi
        - tvsubtitles
      single: no
      exact_match: noCode language: PHP (php)

Cette approche est plus lourde, mais elle devient intéressante si vos vidéos bougent entre plusieurs dossiers ou si vous voulez relancer régulièrement la recherche pour les fichiers qui n’avaient pas encore de sous-titres disponibles.

Choisir les bons codes langue

Selon les versions et les plugins, vous pouvez croiser des codes comme fr, en, fra ou eng. La documentation Subliminal actuelle utilise des codes IETF comme en ou pt-BR. Pour le français et l’anglais, commencez donc avec :

languages:
  - fr
alternatives:
  - en

Si votre configuration historique utilise fra et eng, testez-la. Cependant, pour une nouvelle configuration, je partirais sur fr et en, plus lisibles et cohérents avec les usages actuels de la CLI.

Exact match : faut-il l’activer ?

L’option exact_match détermine la tolérance de recherche.

Option	Avantage	Inconvénient
exact_match: yes	Réduit les mauvais sous-titres.	Peut ne rien trouver si le fichier est mal nommé.
exact_match: no	Trouve plus de résultats.	Augmente le risque de sous-titres décalés ou mauvais.

Ma recommandation : commencez avec exact_match: yes. Si vous avez trop peu de résultats, testez exact_match: no sur une tâche séparée ou avec une exécution manuelle.

Pourquoi les sous-titres ne sont pas toujours trouvés ?

Plusieurs causes reviennent souvent :

• le fichier vidéo est mal nommé ;
• la saison ou l’épisode n’apparaît pas dans le nom ;
• la langue demandée n’existe pas encore ;
• le provider limite les requêtes ;
• les identifiants sont incorrects ;
• un provider a changé son API ;
• le sous-titre existe, mais ne correspond pas assez bien au fichier ;
• le fichier contient déjà une piste de sous-titres intégrée.

Subliminal ignore normalement les vidéos qui possèdent déjà un sous-titre dans la langue demandée, qu’il soit externe ou intégré. C’est pratique, mais cela peut surprendre si vous vous attendez à voir un nouveau fichier .srt apparaître à chaque exécution.

Dépannage rapide

FlexGet ne trouve pas le plugin subliminal

Installez Subliminal dans l’environnement FlexGet :

pipx inject flexget subliminal

Puis vérifiez :

flexget plugins | grep -i subliminal

Si vous utilisez un virtualenv manuel, activez-le avant d’installer les dépendances.

Aucun sous-titre n’est téléchargé

Lancez Subliminal directement :

subliminal download -l fr -l en -v "/home/media/incoming/Serie.Exemple.S01E03.mkv"Code language: JavaScript (javascript)

Si Subliminal ne trouve rien, corrigez d’abord le nom du fichier ou testez un autre provider. Si Subliminal trouve un sous-titre, mais pas FlexGet, le problème vient plutôt de la configuration YAML, du chemin ou des permissions.

Les fichiers SRT sont créés au mauvais endroit

Par défaut, Subliminal enregistre les sous-titres à côté des vidéos. Vérifiez donc le dossier scanné, les droits d’écriture et l’utilisateur qui lance FlexGet.

ls -la /home/media/incoming
id
whoami

Si FlexGet tourne via cron ou systemd, l’utilisateur d’exécution peut être différent de celui utilisé pendant vos tests. Classique, discret, agaçant.

Les sous-titres sont décalés

Le sous-titre ne correspond probablement pas à la bonne release. Essayez d’abord exact_match: yes, améliorez le nom du fichier, puis cherchez une version qui correspond au même montage : WEB-DL, BluRay, HDTV, 720p, 1080p, x264, x265, etc.

Pour un usage ponctuel, vous pouvez aussi corriger temporairement le décalage dans VLC avec les touches G et H. J’ai détaillé cette méthode dans l’article sur le téléchargement automatique de sous-titres avec VLC.

Les accents sont cassés

Forcez l’encodage en UTF-8 quand vous utilisez Subliminal directement :

subliminal download -l fr -e utf-8 /home/media/incoming

Si un fichier SRT existe déjà avec un mauvais encodage, convertissez-le avec iconv :

iconv -f WINDOWS-1252 -t UTF-8 sous-titres.srt > sous-titres-utf8.srtCode language: CSS (css)

Gardez une copie avant conversion. Les fichiers de sous-titres anciens adorent transformer les accents en soupe typographique.

Bonnes pratiques pour une médiathèque propre

Pour améliorer les résultats, adoptez quelques règles simples :

• gardez les vidéos et leurs sous-titres dans le même dossier ;
• nommez les épisodes avec le format S01E03 ;
• gardez les informations de release utiles dans le nom ;
• évitez les noms trop courts ou trop personnalisés ;
• utilisez single: no si vous gérez plusieurs langues ;
• testez les providers un par un en cas d’erreur ;
• limitez la fréquence d’exécution pour éviter les quotas ;
• gardez les identifiants hors du fichier principal si possible.

Exemple de nommage propre :

Serie.Exemple.S01E03.1080p.WEB-DL.x264.mkv
Serie.Exemple.S01E03.1080p.WEB-DL.x264.fr.srt
Serie.Exemple.S01E03.1080p.WEB-DL.x264.en.srtCode language: CSS (css)

C’est moins joli qu’un titre manuscrit, mais les outils de médiathèque comprennent mieux. Et les machines, contrairement aux humains, ne récompensent pas la poésie dans les noms de fichiers.

Quand préférer Bazarr, Plex, Jellyfin ou Kodi ?

FlexGet et Subliminal conviennent très bien pour une automatisation simple côté serveur : un dossier, des vidéos, des langues, une tâche périodique.

En revanche, si vous gérez une grosse médiathèque avec Sonarr, Radarr, Plex, Jellyfin ou Kodi, un outil spécialisé comme Bazarr peut être plus confortable. Il suit les séries, les films, les langues manquantes, les profils, les providers et les relances avec une interface dédiée.

La règle simple :

• pour un dossier local simple : FlexGet + Subliminal suffit ;
• pour une médiathèque complète : Bazarr sera souvent plus agréable ;
• pour un besoin ponctuel : VLC + VLSub reste le plus rapide.

Exemple complet de configuration recommandée

Voici une configuration complète, raisonnable et facile à maintenir :

variables: secrets.yml

tasks:
  get-subtitles:
    filesystem:
      path:
        - /home/media/incoming
        - /home/media/series
      regexp: '.*\.(avi|mkv|mp4|m4v)$'
      recursive: yes
    accept_all: yes
    seen: local
    subliminal:
      languages:
        - fr
      alternatives:
        - en
      exact_match: yes
      providers:
        - opensubtitles
        - addic7ed
        - podnapisi
        - tvsubtitles
      single: no
      hearing_impaired: no
      authentication:
        opensubtitles:
          username: "{? opensubtitles_user ?}"
          password: "{? opensubtitles_password ?}"
        addic7ed:
          username: "{? addic7ed_user ?}"
          password: "{? addic7ed_password ?}"Code language: PHP (php)

Et le fichier secrets.yml associé :

opensubtitles_user: "votre_identifiant"
opensubtitles_password: "votre_mot_de_passe"
addic7ed_user: "votre_identifiant"
addic7ed_password: "votre_mot_de_passe"Code language: JavaScript (javascript)

Testez ensuite :

flexget check
flexget -v execute --task get-subtitlesCode language: JavaScript (javascript)

À retenir

FlexGet et Subliminal forment une solution légère pour télécharger automatiquement les sous-titres de vidéos locales. FlexGet surveille vos dossiers, Subliminal cherche les bons fichiers, puis vos lecteurs vidéo récupèrent les .srt placés à côté des vidéos.

Pour que l’ensemble fonctionne bien, soignez surtout trois points : les noms de fichiers, les langues configurées et les identifiants des providers. Ensuite, automatisez l’exécution avec cron ou systemd, et laissez la machine travailler. C’est tout l’intérêt d’un serveur : lui donner les tâches pénibles pendant que vous faites autre chose.

Besoin d’aide pour automatiser votre serveur ou votre médiathèque ?

Si vous voulez configurer proprement FlexGet, Transmission, un NAS, un serveur Linux, une médiathèque locale ou des tâches systemd, je peux vous aider à mettre en place une solution fiable et maintenable.

J’interviens sur les environnements Linux, WordPress, WooCommerce, NAS et serveurs personnels pour diagnostiquer les permissions, fiabiliser les automatisations, sécuriser les services et organiser les fichiers proprement.

• Configuration FlexGet, Transmission, cron et systemd.
• Organisation de médiathèque locale ou réseau.
• Diagnostic de permissions Linux et dossiers partagés.
• Configuration NAS, VLC, DLNA, Plex, Jellyfin ou Kodi.
• Maintenance serveur, sauvegardes et fiabilisation.

Vous voulez arrêter de déboguer des fichiers YAML à minuit ? Contactez-moi, on remettra votre stack au propre.

Checklist rapide

• Installer FlexGet avec pipx.
• Injecter Subliminal dans l’environnement FlexGet.
• Tester Subliminal seul sur un fichier vidéo.
• Créer une tâche FlexGet dédiée aux sous-titres.
• Utiliser fr et en comme codes langue.
• Garder single: no pour plusieurs langues.
• Stocker les identifiants dans un fichier séparé.
• Tester avec flexget check.
• Lancer avec flexget -v execute --task get-subtitles.
• Automatiser avec cron ou systemd.

FAQ : FlexGet, Subliminal et sous-titres

FlexGet peut-il télécharger automatiquement des sous-titres ?

Oui. FlexGet peut utiliser le plugin Subliminal pour chercher et télécharger des sous-titres pour des fichiers vidéo locaux.

Faut-il installer Subliminal séparément ?

Oui, si votre installation FlexGet ne contient pas déjà l’extra Subliminal. Avec une installation via pipx, utilisez pipx inject flexget subliminal.

Pourquoi FlexGet ne trouve-t-il pas le plugin subliminal ?

Le plus souvent, Subliminal n’est pas installé dans le même environnement Python que FlexGet. Installez-le avec pipx inject flexget subliminal, puis relancez flexget plugins.

Quelle langue utiliser pour les sous-titres français ?

Commencez avec le code fr. Pour l’anglais, utilisez en. Ces codes sont plus lisibles et cohérents avec les usages actuels de Subliminal.

Pourquoi les sous-titres téléchargés sont-ils décalés ?

Le fichier SRT ne correspond probablement pas à la même version que votre vidéo. Essayez un nom de fichier plus précis, activez exact_match: yes, ou choisissez un sous-titre correspondant à la même release.

FlexGet remplace-t-il Bazarr ?

Pas vraiment. FlexGet + Subliminal suffit pour un dossier simple. Pour une médiathèque complète avec Sonarr, Radarr, Plex ou Jellyfin, Bazarr est souvent plus confortable.

Peut-on utiliser VLC à la place ?

Oui, pour un usage ponctuel. VLC avec VLSub reste plus simple si vous voulez télécharger un sous-titre pour une seule vidéo. FlexGet devient intéressant quand vous voulez automatiser le processus.

Articles liés

• Télécharger vos fichiers torrent automatiquement avec FlexGet et Transmission
• Télécharger automatiquement des sous-titres avec VLC
• Mise à jour du serveur vers Ubuntu 24.04 LTS
• Couper un fichier APE avec un fichier CUE

Sources

• FlexGet — Plugin Subliminal
• FlexGet — Plugin subtitle_list
• Subliminal — documentation CLI
• Subliminal — documentation officielle

Report a typo