---
title: ytdl-sub
created: 2026-06-07
updated: 2026-06-07
type: app
tags: [catalogue, downloads, youtube, yt-dlp, subscriptions, python, media-library]
confidence: high
contested: false
sources: [https://selfh.st/apps/?tag=downloads, https://github.com/jmbannon/ytdl-sub]
---

# 📥 ytdl-sub

> **Gestionnaire de téléchargements YouTube piloté par fichiers de configuration YAML** : définissez vos abonnements une fois (`channels.yml`, `subscriptions.yml`), ytdl-sub synchronise, télécharge, **renomme et enrichit** chaque vidéo avec métadonnées et jaquettes pour les **\*arr et Jellyfin/Plex**. L'outil des power-users qui aiment l'Infrastructure-as-Code.

| Métadonnée | Valeur |
| :--- | :--- |
| **Site web** | [https://ytdl-sub.readthedocs.io](https://ytdl-sub.readthedocs.io) |
| **GitHub** | [https://github.com/jmbannon/ytdl-sub](https://github.com/jmbannon/ytdl-sub) |
| **License** | GPL-3.0 |
| **Langage** | Python |
| **Étoiles** | 101 ⭐ |
| **Dernière MAJ** | 2025-11 |
| **Catégorie** | [[cat-downloads\|Downloads]] |

## Description

**ytdl-sub** est né d'un besoin très précis : transformer un dossier de téléchargements YouTube bruts en une **vraie médiathèque** lisible par Sonarr/Radarr/Lidarr/Jellyfin/Plex, **sans dépendre d'une UI web**. L'idée : tout se décrit dans un **fichier YAML** (subscriptions, overrides, plugins), ytdl-sub fait le reste — téléchargement via `yt-dlp`, **renommage selon des presets** (Series, Movie, Music), **fetching de métadonnées** (TMDB, TVDB, MusicBrainz, Spotify), **génération de fichiers `.nfo`** (Kodi/Jellyfin), **placement dans la bonne arborescence** (hardlink possible), et **notifications**.

Les **overrides** sont le cœur du système : on décrit un *handler* par chaîne YouTube ("TechLinked" = émission type TV, "Veritasium" = documentaire, "Alice in Chains" = groupe) et ytdl-sub applique un **preset** (Series, Movie, Music) avec les bons champs (saison, épisode, album, artiste). On peut par exemple générer automatiquement :
- `/tv/TechLinked/Season 2024/S2024E12 - Titre.mkv` + `.nfo`
- `/movies/A Camera Film (2023)/A Camera Film (2023).mkv` + `poster.jpg`
- `/music/Alice in Chains/Dirt/01 - Them Bones.opus`

Tout est **reproductible** : le YAML est versionnable dans Git, on peut dry-run, et ytdl-sub est **idempotent** (relancer n'écrase rien). Supporte aussi les **chapters**, **SponsorBlock**, **sous-titres** (multi-langues), **cookies YouTube**, et **CLI complète** (`ytdl-sub sub`, `ytdl-sub refresh`, `ytdl-sub view`).

**Points forts** : IaC, plugins très riches, métadonnées Tier-1, intégration *arr native, **GPL-3.0**.

**Points faibles** : pas d'UI web (CLI only), courbe d'apprentissage YAML, mono-langue par défaut (anglais) pour les métadonnées, maintenance moins active que Pinchflat.

## Installation

### Via Docker (recommandé)

```yaml
# docker-compose.yml
services:
  ytdl-sub:
    image: ghcr.io/jmbannon/ytdl-sub:latest
    container_name: ytdl-sub
    restart: unless-stopped
    environment:
      - TZ=Europe/Paris
      - PUID=1000
      - PGID=1000
    volumes:
      - ./config:/config
      - /mnt/media/tv:/tv
      - /mnt/media/movies:/movies
      - /mnt/media/music:/music
      - /mnt/media/youtube:/youtube
    # Pas de port exposé : CLI only
```

Exemple de `config/subscriptions.yaml` minimal :
```yaml
__preset__:
  preset: "tv_show"
  tv_show_directory: "/tv"
  tv_show_name: "{title}"
overrides:
  TechLinked:
    TVShowTitle: "TechLinked"
    TVShowDate: "{upload_date>%Y}"
```

### Installation manuelle

Python 3.10+, `ffmpeg`. `pip install ytdl-sub`, créer le dossier de config, `ytdl-sub sub config/subscriptions.yaml`.

## Configuration

1. **Choisir un preset** (`series`, `tv_show`, `movie`, `music_video`, `music`, `audio`) — chacun a ses propres variables.
2. **Écrire le YAML** : pour chaque source (chaîne, playlist, URL) on définit un **override** avec les champs à matcher.
3. **Credentials metadata** (optionnel) : API keys TMDB, TVDB, MusicBrainz, Spotify pour enrichir.
4. **Cookies YouTube** : `./config/cookies.txt` monté en read-only.
5. **Cron externe** : `ytdl-sub sub` doit tourner périodiquement (cron, systemd-timer, ou un sidecar).
6. **Webhooks** : `ytdl-sub` peut appeler une URL après chaque import → rafraîchir Jellyfin.
7. **Pas de reverse-proxy** : application CLI/headless, on s'y connecte via SSH ou un wrapper UI.

## Alternatives

### Open source
- [[app-tubesync]] — UI web intégrée, plus "presse-bouton"
- [[app-pinchflat]] — UI web moderne Elixir/LiveView
- [[app-metube]] — wrapper web ponctuel `yt-dlp`
- [[app-hometube]] — pont YouTube ↔ Jellyfin
- [[app-sonarr]] / [[app-radarr]] / [[app-lidarr]] — les **consommateurs** de la sortie de ytdl-sub
- **youtube-dl-server** — abandonné

### Propriétaires
- **Plex Watch Later** — fermé, lié au compte Plex
- **iCloud + YouTube Premium** — pas d'équivalent hors-ligne persistant
- **Jellyfin YouTube Plugin** — lecture seule, pas de download

## Sécurité

- ⚠️ **Cookies YouTube** : critique, à monter en read-only 0400.
- ⚠️ **API keys** (TMDB, TVDB…) : dans `./config` ou variables d'environnement, jamais dans Git en clair — utiliser **git-crypt** ou **SOPS**.
- ✅ **Aucune exposition réseau** : ytdl-sub est headless/CLI, surface d'attaque nulle.
- ⚠️ **Espace disque** : les presets `tv_show` et `movie` répliquent les fichiers (hardlink recommandé) — sinon doubler l'espace.
- ⚠️ **Cron output** : rediriger les logs vers un fichier, surveiller les erreurs `yt-dlp` (changements d'API YouTube fréquents).
- ✅ **Sauvegardes** : `./config` (YAML versionné) + `cookies.txt`.

## Ressources
- [Documentation officielle](https://ytdl-sub.readthedocs.io)
- [Wiki / Presets](https://ytdl-sub.readthedocs.io/en/latest/config.html)
- [GitHub](https://github.com/jmbannon/ytdl-sub)
- [selfh.st — Downloads](https://selfh.st/apps/?tag=downloads)

## Pages Liées
- [[cat-downloads]] — Catégorie parente
- [[app-tubesync]] — Concurrent UI web
- [[app-pinchflat]] — Concurrent UI web moderne
- [[app-sonarr]] / [[app-radarr]] / [[app-lidarr]] — Consommateurs
- [[app-jellyfin]] — Media server cible
- [[recettes-docker-compose]] — Templates Docker
- [[securisation-home-lab]] — Bonnes pratiques