Python Mutagen Snippets

1 Qu'est-ce que Mutagen ?

Mutagen est une bibliothèque Python qui lit et écrit les métadonnées audio (“tags”) pour de nombreux formats — MP3, FLAC, MP4/M4A, Ogg Vorbis, WMA, et plus encore. Elle maintient la cohérence de la conversion des tags et évite de faire appel à des outils en ligne de commande peu pratiques.

API Unifiée : Les mêmes méthodes fonctionnent pour différents formats.
Modifications de tags sans perte : Modifiez les métadonnées sans réencoder l'audio.
Prise en charge des pochettes : Ajoutez, lisez et remplacez les illustrations intégrées.
Prise en charge des chapitres et des Cuesheets : Gérez les fichiers divisés et les métadonnées de chapitres.

Vous obtiendrez une poignée d’extraits copiables à coller que vous pourrez intégrer directement dans vos scripts.

2 Installer Mutagen

Installez la dernière version stable via pip :

pip install --upgrade mutagen

Pour les processeurs Apple Silicon ou les environnements nécessitant des codecs supplémentaires, vous pouvez également installer FFmpeg ou mutagen[mp4] pour une meilleure prise en charge des MP4 — Mutagen lui-même ne nécessite pas FFmpeg.

3 Charger un Fichier et Enregistrer les Modifications

Ouvrez un fichier audio, lisez ses tags, modifiez une valeur et réenregistrez — Mutagen gérera les détails spécifiques au format.

from mutagen.mp3 import MP3
from mutagen.id3 import ID3NoHeaderError

path = "chemin/vers/fichier.mp3"

try:
    audio = MP3(path, ID3=ID3)
except ID3NoHeaderError:
    audio = MP3(path)

# Lire un tag
title = audio.get("TIT2") or audio.get("\xa9nam")  # Style ID3 v2 ou iTunes
print(title)

# Écrire un tag (créer ou mettre à jour)
audio["TIT2"] = "Nouveau Titre de Chanson"
audio["TPE1"] = "Nouvel Artiste"

# Persister les changements
audio.save()

La méthode .save() écrit les tags sans toucher aux données audio elles-mêmes.

4 Lire les Tags Courants à travers les Formats

Utilisez des clés indépendantes du format pour extraire les mêmes champs des fichiers MP3, FLAC, MP4 et Ogg Vorbis.

from mutagen import File

path = "chemin/vers/fichier.mp3"  # fonctionne aussi avec .flac, .m4a, .ogg

audio = File(path)
if audio is None:
    raise ValueError("Fichier non pris en charge ou illisible")

title = audio.get("TITLE") or audio.get("\xa9nam") or audio.get("TIT2")
artist = audio.get("ARTIST") or audio.get("\xa9ART") or audio.get("TPE1")
album = audio.get("ALBUM") or audio.get("\xa9alb") or audio.get("TALB")
date = audio.get("DATE") or audio.get("\xa9day") or audio.get("TDRC")

print(title, artist, album, date)

Mutagen normalise les champs courants pour la plupart des conteneurs ; vous verrez toujours des clés héritées ou spécifiques au vendeur en fonction du format.

5 Gérer les Champs à Valeurs Multiples (Artistes, Genres)

Certains tags sont des listes — mutagen les conserve comme des listes, pas comme des chaînes concaténées.

from mutagen import File

audio = File("chemin/vers/fichier.mp3")
artists = audio.get("ARTIST") or audio.get("\xa9ART") or audio.get("TPE1")
genres = audio.get("GENRE") or audio.get("\xa9gen") or audio.get("TCON")

# Mutagen renvoie une liste ou None ; fallback sécurisé
artists = artists if isinstance(artists, list) else ([artists] if artists else [])
genres = genres if isinstance(genres, list) else ([genres] if genres else [])

print("Artistes :", artists)
print("Genres :", genres)

# L'écriture de valeurs multiples est la même — il suffit d'assigner une liste
audio["TPE1"] = ["Alice", "Bob"]
audio.save()

Ne joignez jamais vous-même des valeurs multiples avec des virgules — les lecteurs et les outils de tagging attendent des listes propres.

6 Ajouter ou Remplacer une Pochette

Lisez un fichier image et attachez-le en tant qu'APIC (ID3) ou en tant qu'atome de couverture standard MP4.

from mutagen.mp3 import MP3
from mutagen.id3 import APIC, ID3

audio = MP3("chemin/vers/fichier.mp3", ID3=ID3)
audio.add_tags()  # Assurez-vous qu'un en-tête ID3 existe

with open("cover.jpg", "rb") as f:
    cover_data = f.read()

# ID3 : attachez une couverture avant en JPEG
audio.tags.add(APIC(
    encoding=3,      # UTF-8
    mime="image/jpeg",
    type=3,          # Couverture avant
    desc="Cover",
    data=cover_data
))
audio.save()

# Pour MP4/M4A :
# from mutagen.mp4 import MP4
# mp4 = MP4("chemin/vers/fichier.m4a")
# mp4["covr"] = [MP4.MP4Cover(cover_data, imageformat=MP4.FORMAT_JPEG)]
# mp4.save()

APIC fonctionne avec les MP3 ; les MP4 utilisent un atome covr avec des données d'image brutes. D'autres formats varient dans les noms des clés.

7 Lire la Durée (Longueur)

La plupart des objets audio Mutagen exposent info.length en secondes.

from mutagen import File

audio = File("chemin/vers/fichier.flac")
length_seconds = audio.info.length if getattr(audio, "info", None) else None
print("Durée :", length_seconds)

# Affichage formaté mm:ss
if length_seconds:
    mins, secs = divmod(int(length_seconds), 60)
    print(f"{mins:02d}:{secs:02d}")

Le débit binaire et la fréquence d'échantillonnage se trouvent également sous audio.info lorsque le format les expose.

8 Chapitres à partir de Cuesheets

Si vous avez un fichier CUE, générez des tags de chapitre pour MP3 ou MP4. Cet exemple écrit des trames de chapitre ID3 (CHAP/CTOC) pour MP3.

# pip install mutagen[chapters]  # si nécessaire pour la prise en charge des cuesheets
from mutagen.mp3 import MP3
from mutagen.id3 import CHAP, CTOC, ID3

audio = MP3("chemin/vers/album.mp3", ID3=ID3)

# Créez une table des matières de niveau supérieur avec des éléments de chapitre
toc = CTOC(
    elem_id=["toc"],
    flags=0x02,  # niveau supérieur
    child_elem_ids=["ch0", "ch1", "ch2"],  # doit correspondre aux elem_ids des chapitres
    sort_index=0
)
audio.tags.add(toc)

# Ajoutez des marqueurs de chapitre simples à 0s, 120s, 300s
chapters = [0, 120, 300]
for i, start in enumerate(chapters):
    end = chapters[i + 1] if i + 1 < len(chapters) else None
    audio.tags.add(CHAP(
        elem_id=f"ch{i}",
        start_ms=start * 1000,
        end_ms=(end * 1000) if end else None,
        tags={"TIT2": f"Chapitre {i + 1}"}
    ))

audio.save()

# Les chapitres MP4 (M4A) sont non triviaux et parfois écrits comme des pistes texte.
# De nombreux lecteurs préfèrent diviser les pistes et réétiqueter plutôt que d'écrire directement des chapitres MP4.

Les chapitres ID3 sont largement pris en charge dans les lecteurs de bureau ; la prise en charge des chapitres dans les MP4 est mitigée selon les applications.

9 Diviser un seul Fichier Audio par Cuesheet (ffmpeg + tags)

Lorsque vous avez réellement besoin de fichiers séparés, FFmpeg peut découper l'audio pendant que Mutagen fournit les tags. Voici un flux de travail concis utilisant une simple liste d'horodatages.

import subprocess
from pathlib import Path
from mutagen import File
from mutagen.mp3 import MP3
from mutagen.id3 import ID3

input_path = "chemin/vers/album.flac"
out_dir = Path("splits")
out_dir.mkdir(exist_ok=True)

# Horodatages d'exemple (mm:ss)
chapters = ["00:00", "02:00", "05:00", "07:30"]

audio = File(input_path)
title = (audio.get("TITLE") or audio.get("\xa9nam") or ["Track"]).value
artist = (audio.get("ARTIST") or audio.get("\xa9ART") or ["Artist"]).value

for i in range(len(chapters) - 1):
    start = chapters[i]
    end = chapters[i + 1]
    out_path = out_dir / f"track_{i+1:02d}.mp3"

    # Découper avec ffmpeg (pas de réencodage ; copier les flux)
    cmd = [
        "ffmpeg", "-y",
        "-i", str(input_path),
        "-ss", start,
        "-to", end,
        "-c", "copy",
        str(out_path)
    ]
    subprocess.run(cmd, check=True)

    # Appliquer les tags au nouveau fichier
    track = MP3(str(out_path), ID3=ID3)
    track.add_tags()
    track["TIT2"] = f"{title} (Partie {i+1})"
    track["TPE1"] = artist
    track["TRACK"] = f"{i+1}/{len(chapters)-1}"
    track.save()

print("Division terminée.")

Utiliser -c copy évite la transcodage — seul le conteneur est réécrit.

10 Correction par Lots des Numéros de Piste

Renommez et étiquetez un dossier de pistes en une seule passe en utilisant l'ordre du système de fichiers comme solution de repli.

from pathlib import Path
from mutagen import File
import shutil

root = Path("chemin/vers/album")
files = sorted([p for p in root.iterdir() if p.suffix.lower() in (".mp3", ".flac", ".m4a", ".ogg")])

for idx, path in enumerate(files, start=1):
    audio = File(path)
    if not audio:
        continue

    # Préférer le TRACK existant ; revenir à l'index
    track = audio.get("TRACK") or audio.get("trkn") or [idx]
    # Normaliser au numéro de piste actuel (ignorer le total pour le renommage)
    cur = track[0] if isinstance(track, list) else track

    new_name = f"{cur:02d} - {path.name.split(' - ', 1)[-1] if ' - ' in path.name else path.name}"
    new_path = path.with_name(new_name)

    if new_path != path:
        shutil.move(str(path), str(new_path))

    # Mettre à jour TRACK en toute sécurité
    audio["TRACK"] = f"{idx}/{len(files)}"
    # MP4 utilise un tuple pour trkn ; laisser les autres formats sous forme de chaîne
    audio.save()

print("Pistes normalisées.")

Faites attention au trkn de MP4 — c'est un tuple. Le code générique ci-dessus garde MP3/FLAC simples et devrait fonctionner dans la plupart des cas.

11 Et Ensuite ?

Vous disposez d'une boîte à outils pratique pour lire, modifier et réorganiser les métadonnées audio. Quelques idées :

Normalisez les étiquettes et la casse avec un fichier de configuration.
Écrivez un petit point de terminaison web pour servir les tags d'une collection statique.
Mettez à jour en masse les illustrations par dossier, en utilisant des noms de fichiers hachés pour dédupliquer.

Enregistrez ces extraits ; ils s'intégreront dans vos scripts comme une clé bien rodée.

Progression du Tutoriel