Python Mutagen Snippets

1 O que é o Mutagen?

Mutagen é uma biblioteca Python que lê e escreve metadados de áudio (“tags”) em diversos formatos — MP3, FLAC, MP4/M4A, Ogg Vorbis, WMA, e mais. Ele mantém a conversão de tags consistente e evita o uso de ferramentas de linha de comando desajeitadas.

API Unificada: Os mesmos métodos funcionam para formatos diferentes.
Edições de tag sem perdas: Modifique metadados sem re-codificar o áudio.
Suporte a arte de capa: Adicione, leia e substitua arte embutida.
Suporte a capítulos e cues: Manipule arquivos divididos e metadados de capítulos.

Você receberá alguns trechos de código para copiar e colar diretamente em seus scripts.

2 Instale o Mutagen

Instale a versão estável via pip:

pip install --upgrade mutagen

Para Apple Silicon ou ambientes que precisam de codecs extras, você também pode instalar FFmpeg ou mutagen[mp4] para um suporte mais amplo a MP4 — o Mutagen em si não requer FFmpeg.

3 Carregue um Arquivo e Salve as Alterações

Abra um arquivo de áudio, leia suas tags, modifique um valor e escreva de volta — o Mutagen cuidará dos detalhes específicos do formato.

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

path = "caminho/para/arquivo.mp3"

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

# Leia uma tag
title = audio.get("TIT2") or audio.get("\xa9nam")  # ID3 v2 ou estilo iTunes
print(title)

# Escreva uma tag (crie ou atualize)
audio["TIT2"] = "Novo Título da Música"
audio["TPE1"] = "Novo Artista"

# Persista as alterações
audio.save()

O método .save() grava as tags sem alterar os dados de áudio em si.

4 Leia Tags Comuns em Diferentes Formatos

Use chaves agnósticas ao formato para extrair os mesmos campos de arquivos MP3, FLAC, MP4 e Ogg Vorbis.

from mutagen import File

path = "caminho/para/arquivo.mp3"  # funciona com .flac, .m4a, .ogg também

audio = File(path)
if audio is None:
    raise ValueError("Arquivo não suportado ou ilegível")

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)

O Mutagen normaliza campos comuns para a maioria dos contêineres; você ainda verá algumas chaves legadas ou específicas do fornecedor dependendo do formato.

5 Manipule Campos Multi-valor (Artistas, Gêneros)

Algumas tags são listas — o Mutagen as mantém como listas, não como strings concatenadas.

from mutagen import File

audio = File("caminho/para/arquivo.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")

# O Mutagen retorna uma lista ou None; use um fallback seguro
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)

# Escrever múltiplos valores é o mesmo — apenas atribua uma lista
audio["TPE1"] = ["Alice", "Bob"]
audio.save()

Nunca junte múltiplos valores com vírgulas você mesmo — players e taggers esperam listas limpas.

6 Adicione ou Substitua Arte de Capa

Leia um arquivo de imagem e anexe-o como APIC (ID3) ou como o átomo de capa MP4 padrão.

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

audio = MP3("caminho/para/arquivo.mp3", ID3=ID3)
audio.add_tags()  # garante que um cabeçalho ID3 exista

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

# ID3: anexa uma capa frontal em JPEG
audio.tags.add(APIC(
    encoding=3,      # UTF-8
    mime="image/jpeg",
    type=3,          # Capa frontal
    desc="Capa",
    data=cover_data
))
audio.save()

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

APIC funciona com MP3; MP4 usa um átomo covr com dados brutos da imagem. Outros formatos variam em nomes de chaves.

7 Leia a Duração (Comprimento)

A maioria dos objetos de áudio do Mutagen expõe info.length em segundos.

from mutagen import File

audio = File("caminho/para/arquivo.flac")
length_seconds = audio.info.length if getattr(audio, "info", None) else None
print("Duração:", length_seconds)

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

Taxa de bits e taxa de amostragem também residem em audio.info quando o formato os expõe.

8 Capítulos a partir de Cuesheets

Se você tem uma folha CUE, gere tags de capítulo para MP3 ou MP4. Este exemplo grava frames de capítulo ID3 (CHAP/CTOC) para MP3.

# pip install mutagen[chapters]  # se necessário para suporte a cuesheet
from mutagen.mp3 import MP3
from mutagen.id3 import CHAP, CTOC, ID3

audio = MP3("caminho/para/album.mp3", ID3=ID3)

# Cria uma tabela de conteúdo de nível superior com elementos de capítulo
toc = CTOC(
    elem_id=["toc"],
    flags=0x02,  # nível superior
    child_elem_ids=["ch0", "ch1", "ch2"],  # deve corresponder aos elem_ids dos capítulos
    sort_index=0
)
audio.tags.add(toc)

# Adiciona marcadores de capítulo simples em 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()

# Capítulos MP4 (M4A) são não triviais e às vezes gravados como faixas de texto.
# Muitos players preferem dividir faixas e retagging em vez de gravar capítulos MP4 diretamente.

Capítulos ID3 são amplamente suportados em players de desktop; o suporte a capítulos em MP4 é misto entre aplicativos.

9 Divida um Único Arquivo de Áudio por Cuesheet (ffmpeg + tags)

Quando você realmente precisa de arquivos separados, o FFmpeg pode fatiar o áudio enquanto o Mutagen fornece as tags. Aqui está um fluxo de trabalho conciso usando uma lista simples de timestamps.

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

input_path = "caminho/para/album.flac"
out_dir = Path("splits")
out_dir.mkdir(exist_ok=True)

# Timestamps de exemplo (mm:ss)
chapters = ["00:00", "02:00", "05:00", "07:30"]

audio = File(input_path)
title = (audio.get("TITLE") or audio.get("\xa9nam") or ["Faixa"]).value
artist = (audio.get("ARTIST") or audio.get("\xa9ART") or ["Artista"]).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"

    # Fatie com ffmpeg (sem re-codificação; copia os streams)
    cmd = [
        "ffmpeg", "-y",
        "-i", str(input_path),
        "-ss", start,
        "-to", end,
        "-c", "copy",
        str(out_path)
    ]
    subprocess.run(cmd, check=True)

    # Aplique tags ao novo arquivo
    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("Divisão concluída.")

Usar -c copy evita a transcodificação — apenas o contêiner é reescrito.

10 Correção em Lote de Números de Faixa

Renomeie e tag um grupo de faixas em uma única passagem usando a ordem do sistema de arquivos como fallback.

from pathlib import Path
from mutagen import File
import shutil

root = Path("caminho/para/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

    # Prefira TRACK existente; use o índice como fallback
    track = audio.get("TRACK") or audio.get("trkn") or [idx]
    # Normalize para o número da faixa atual (ignora o total para renomear)
    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))

    # Atualize TRACK com segurança
    audio["TRACK"] = f"{idx}/{len(files)}"
    # MP4 usa uma tupla para trkn; deixe outros formatos como string
    audio.save()

print("Faixas normalizadas.")

Tenha cuidado com o trkn do MP4 — é uma tupla. O código genérico acima mantém MP3/FLAC simples e deve funcionar na maioria dos casos.

11 E Agora?

Você tem uma caixa de ferramentas prática para ler, editar e reorganizar metadados de áudio. Algumas ideias:

Normalize rótulos e capitalização com um arquivo de configuração.
Escreva um pequeno endpoint web para servir tags para uma coleção estática.
Atualize em lote a arte por pasta, usando nomes de arquivo com hash para deduplicar.

Salve esses trechos; eles se encaixarão em seus scripts como uma chave bem gasta.

Progresso do Tutorial