Snippets de Python Mutagen

1 ¿Qué es Mutagen?

Mutagen es una biblioteca de Python que lee y escribe metadatos de audio ("etiquetas") en múltiples formatos: MP3, FLAC, MP4/M4A, Ogg Vorbis, WMA y más. Mantiene la conversión de etiquetas consistente y evita el uso de herramientas de línea de comandos torpes.

API Unificada: Los mismos métodos funcionan para diferentes formatos.
Ediciones de etiquetas sin pérdidas: Modifica metadatos sin volver a codificar el audio.
Soporte para arte de portada: Añade, lee y reemplaza arte incrustado.
Soporte para capítulos y cue sheets: Maneja archivos divididos y metadatos de capítulos.

Obtendrás un puñado de fragmentos que puedes copiar y pegar directamente en tus scripts.

2 Instala Mutagen

Instala la versión estable a través de pip:

pip install --upgrade mutagen

Para Apple Silicon o entornos que necesiten códecs adicionales, también puedes instalar FFmpeg o mutagen[mp4] para un mayor soporte de MP4; Mutagen en sí no requiere FFmpeg.

3 Carga un Archivo y Guarda Cambios

Abre un archivo de audio, lee sus etiquetas, modifica un valor y vuelve a escribir; Mutagen se encargará de los detalles específicos del formato.

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

path = "ruta/a/archivo.mp3"

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

# Lee una etiqueta
title = audio.get("TIT2") or audio.get("\xa9nam")  # ID3 v2 o estilo iTunes
print(title)

# Escribe una etiqueta (crea o actualiza)
audio["TIT2"] = "Nuevo Título de Canción"
audio["TPE1"] = "Nuevo Artista"

# Persiste los cambios
audio.save()

El método .save() escribe las etiquetas sin tocar los datos de audio en sí.

4 Lee Etiquetas Comunes a Través de Formatos

Usa claves agnósticas al formato para extraer los mismos campos de archivos MP3, FLAC, MP4 y Ogg Vorbis.

from mutagen import File

path = "ruta/a/archivo.mp3"  # funciona también con .flac, .m4a, .ogg

audio = File(path)
if audio is None:
    raise ValueError("Archivo no soportado o ilegible")

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 normaliza los campos comunes para la mayoría de los contenedores; aún verás algunas claves heredadas o específicas del proveedor dependiendo del formato.

5 Maneja Campos de Múltiples Valores (Artistas, Géneros)

Algunas etiquetas son listas; mutagen las mantiene como listas, no como cadenas concatenadas.

from mutagen import File

audio = File("ruta/a/archivo.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 devuelve una lista o None; usa una copia de seguridad segura
artists = artists if isinstance(artists, list) else ([artists] if artists else [])
genres = genres if isinstance(genres, list) else ([genres] if genres else [])

print("Artistas:", artists)
print("Géneros:", genres)

# Escribir múltiples valores es lo mismo; simplemente asigna una lista
audio["TPE1"] = ["Alice", "Bob"]
audio.save()

Nunca unas múltiples valores con comas tú mismo; los reproductores y etiquetadores esperan listas limpias.

6 Añade o Reemplaza Arte de Portada

Lee un archivo de imagen y adjúntalo como APIC (ID3) o como el átomo de portada MP4 estándar.

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

audio = MP3("ruta/a/archivo.mp3", ID3=ID3)
audio.add_tags()  # asegura que exista una cabecera ID3

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

# ID3: adjunta una portada frontal en JPEG
audio.tags.add(APIC(
    encoding=3,      # UTF-8
    mime="image/jpeg",
    type=3,          # Portada frontal
    desc="Cover",
    data=cover_data
))
audio.save()

# Para MP4/M4A:
# from mutagen.mp4 import MP4
# mp4 = MP4("ruta/a/archivo.m4a")
# mp4["covr"] = [MP4.MP4Cover(cover_data, imageformat=MP4.FORMAT_JPEG)]
# mp4.save()

APIC funciona con MP3; MP4 utiliza un átomo covr con datos de imagen en bruto. Otros formatos varían en los nombres de las claves.

7 Lee la Duración (Longitud)

La mayoría de los objetos de audio de Mutagen exponen info.length en segundos.

from mutagen import File

audio = File("ruta/a/archivo.flac")
length_seconds = audio.info.length if getattr(audio, "info", None) else None
print("Duración:", length_seconds)

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

La tasa de bits y la frecuencia de muestreo también se encuentran en audio.info cuando el formato las expone.

8 Capítulos desde Cue Sheets

Si tienes una hoja CUE, genera etiquetas de capítulo para MP3 o MP4. Este ejemplo escribe fotogramas de capítulo ID3 (CHAP/CTOC) para MP3.

# pip install mutagen[chapters]  # si es necesario para el soporte de cuesheet
from mutagen.mp3 import MP3
from mutagen.id3 import CHAP, CTOC, ID3

audio = MP3("ruta/a/album.mp3", ID3=ID3)

# Crea una tabla de contenidos de nivel superior con elementos de capítulo
toc = CTOC(
    elem_id=["toc"],
    flags=0x02,  # nivel superior
    child_elem_ids=["ch0", "ch1", "ch2"],  # deben coincidir con los elem_ids de los capítulos
    sort_index=0
)
audio.tags.add(toc)

# Añade marcadores de capítulo simples a los 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"Capítulo {i + 1}"}
    ))

audio.save()

# Los capítulos de MP4 (M4A) son complejos y a veces se escriben como pistas de texto.
# Muchos reproductores prefieren dividir pistas y volver a etiquetar en lugar de escribir capítulos MP4 directamente.

Los capítulos ID3 son ampliamente compatibles en reproductores de escritorio; el soporte de capítulos en MP4 es mixto entre aplicaciones.

9 Divide un Solo Archivo de Audio por Cuesheet (ffmpeg + etiquetas)

Cuando realmente necesites archivos separados, FFmpeg puede cortar el audio mientras Mutagen suministra las etiquetas. Aquí tienes un flujo de trabajo conciso utilizando una simple lista de marcas de tiempo.

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

input_path = "ruta/a/album.flac"
out_dir = Path("splits")
out_dir.mkdir(exist_ok=True)

# Marcas de tiempo de ejemplo (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"

    # Corta con ffmpeg (sin recodificar; copia flujos)
    cmd = [
        "ffmpeg", "-y",
        "-i", str(input_path),
        "-ss", start,
        "-to", end,
        "-c", "copy",
        str(out_path)
    ]
    subprocess.run(cmd, check=True)

    # Aplica etiquetas al nuevo archivo
    track = MP3(str(out_path), ID3=ID3)
    track.add_tags()
    track["TIT2"] = f"{title} (Parte {i+1})"
    track["TPE1"] = artist
    track["TRACK"] = f"{i+1}/{len(chapters)-1}"
    track.save()

print("División completada.")

Usar -c copy evita la transcodificación; solo se reescribe el contenedor.

10 Corrección por Lotes de Números de Pista

Renombra y etiqueta una carpeta de pistas en un solo paso, utilizando el orden del sistema de archivos como respaldo.

from pathlib import Path
from mutagen import File
import shutil

root = Path("ruta/a/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

    # Prefiere TRACK existente; recurre al índice
    track = audio.get("TRACK") or audio.get("trkn") or [idx]
    # Normaliza al número de pista actual (ignora el total para renombrar)
    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))

    # Actualiza TRACK de forma segura
    audio["TRACK"] = f"{idx}/{len(files)}"
    # MP4 usa una tupla para trkn; deja otros formatos como cadena
    audio.save()

print("Pistas normalizadas.")

Ten cuidado con trkn de MP4; es una tupla. El código genérico anterior mantiene MP3/FLAC simple y debería funcionar en la mayoría de los casos.

11 ¿Y ahora qué?

Ahora tienes una caja de herramientas práctica para leer, editar y reorganizar metadatos de audio. Algunas ideas:

Normaliza etiquetas y uso de mayúsculas con un archivo de configuración.
Escribe un pequeño endpoint web para servir etiquetas de una colección estática.
Actualiza por lotes el arte por carpeta, usando nombres de archivo hasheados para desduplicar.

Guarda estos fragmentos; se deslizarán en tus scripts como una llave bien usada.

Progreso del Tutorial