---
title: yubal
created: 2026-06-07
updated: 2026-06-07
type: app
tags: [catalogue, downloads, youtube, music, python, yt-dlp, tagging]
confidence: medium
contested: false
sources:
  - https://selfh.st/apps/?tag=downloads
  - https://github.com/guillevc/yubal
---

# 🎵 yubal
> Téléchargeur et tagueur automatique pour YouTube Music : transforme playlists et albums en bibliothèque audio propre et correctement tagguée.

| Métadonnée | Valeur |
| :--- | :--- |
| **Site web** | https://github.com/guillevc/yubal |
| **GitHub** | https://github.com/guillevc/yubal |
| **License** | MIT |
| **Langage** | Python (FastAPI + uv) |
| **Étoiles** | 41 ⭐ |
| **Dernière MAJ** | 2026 |
| **Catégorie** | [[cat-downloads]] |

## Description

yubal est un projet récent (fin 2025) qui se concentre sur un créneau précis : **télécharger depuis YouTube Music avec un taggage propre, prêt à importer dans un lecteur**. Là où [[app-yt-dlp-web-player]] reste généraliste (vidéo, audio, formats), yubal va plus loin sur la partie *musique* : récupération des métadonnées YT Music (titre, album, artiste, n° de piste, année, pochette), taggage via mutagen, organisation en arborescence `Artiste/Album/## - Titre.ext`.

Le fonctionnement est volontairement simple : on colle une URL YouTube Music (track, album ou playlist), yubal télécharge en arrière-plan via yt-dlp, écrit les tags ID3/Vorbis, et expose une UI web légère pour suivre l'avancement. La v0.2 a ajouté le support natif des playlists (très demandé) et la possibilité de **synchroniser les métadonnées avec Spotify** (pour récupérer les cover arts haute résolution et les tags enrichis comme le BPM, l'ISRRC, etc.).

L'approche est minimaliste : pas de client torrent, pas de PVR, pas d'intégration *arr. C'est un outil **périphérique** idéal à coupler avec [[app-lidarr]] (import manuel), [[app-navidrome]] (scanner) ou un simple dossier Dropbox/SMB pour écoute nomade.

## Installation

### Docker Compose (recommandé)

```yaml
# docker-compose.yml
services:
  yubal:
    image: ghcr.io/guillevc/yubal:latest
    container_name: yubal
    restart: unless-stopped
    ports:
      - "8484:8484"
    environment:
      - TZ=Europe/Paris
      - DOWNLOAD_DIR=/downloads
      - AUDIO_FORMAT=mp3
      - AUDIO_QUALITY=320
    volumes:
      - ./config:/app/config
      - /data/music/yubal:/downloads
```

### Installation manuelle

```bash
# Prérequis : Python 3.11+, ffmpeg, uv
git clone https://github.com/guillevc/yubal
cd yubal
uv sync
uv run fastapi dev app/main.py
# UI sur http://localhost:8484
```

## Configuration

- **Format de sortie** : `mp3`, `flac`, `opus`, `m4a` — défaut `mp3` pour compatibilité maximale.
- **Qualité audio** : bitrate cible pour les formats lossy (`0` = best available).
- **Dossier de sortie** : un seul volume monté, organisation `Artiste/Année - Album/## - Titre.ext`.
- **Spotify sync (optionnel)** : client ID + secret pour enrichir les tags via l'API Spotify.
- **Cookies navigateur** : export `cookies.txt` YouTube Music si l'IP est restreinte (rares cas).
- **Watch folder** : un mode watch (à venir) devrait permettre de coller des URLs dans un fichier texte à surveiller.

## Alternatives

### Open Source

- [[app-yt-dlp-web-player]] — UI web générique pour yt-dlp (vidéo + audio), plus large mais sans focus musique.
- [[app-meetube]] — fork de MeTube, interface simple, peu de taggage.
- [[app-spotizerr]] — focus Spotify uniquement, résolution via YouTube.
- [[app-music-grabber]] — complément Lidarr pour backfill multi-sources.
- **spotDL** — CLI Python référence, pas d'UI web, excellent tagging Spotify→YT.
- **youtubedl-material** — UI web complète, plus ancien, plus lourd.

### Propriétaires (ce que yubal remplace)

- **YouTube Music Premium offline** — téléchargement只能在应用内，无法在Plex/Navidrome中读取。
- **SpotTube Premium** — pareil,只能在客户端读。
- Services de ripping payants (tunepat, soundiz) — non self-hosted, abonnement mensuel.

## Sécurité

- **Cookies YouTube** : si vous les fournissez pour contourner des restrictions, ils donnent accès à votre compte Google — à stocker dans `./config` chiffré, pas en variable d'environnement Docker inspectable.
- **Métadonnées Spotify** : ne jamais exposer le client secret, yubal ne supporte que OAuth local.
- **Droits d'auteur** : comme tout outil de la famille yt-dlp, à n'utiliser que sur du contenu sous licence libre (CC-BY) ou vos propres uploads.
- **Pas d'auth par défaut** : l'UI accepte n'importe quelle URL, ne pas exposer sur Internet sans reverse proxy authentifié ([[app-traefik]] + [[app-authentik]]).
- **Surface d'attaque faible** : projet jeune (~1 an), peu de dépendances lourdes, mais **bus factor 1** (un seul mainteneur actif).

## Ressources

- Repository : https://github.com/guillevc/yubal
- Release notes v0.2 (playlists) : https://www.reddit.com/r/selfhosted/comments/1qknc0i/
- yt-dlp upstream : https://github.com/yt-dlp/yt-dlp
- mutagen (lib de taggage) : https://mutagen.readthedocs.io/
- selfh.st downloads : https://selfh.st/apps/?tag=downloads

## Pages Liées

- [[cat-downloads]] — catégorie parente
- [[app-lidarr]] — peut ingérer les downloads
- [[app-navidrome]] — serveur de streaming musical
- [[app-yt-dlp-web-player]] — alternative généraliste
- [[app-spotizerr]] — alternative focus Spotify
- [[app-traefik]] — reverse proxy HTTPS
- [[app-authentik]] — SSO
- [[recettes-docker-compose]] — templates
- [[securisation-home-lab]] — bonnes pratiques