Python Mutagen 代码片段

1 What is Mutagen?

Mutagen is a Python library that reads and writes audio metadata (“tags”) across many formats—MP3, FLAC, MP4/M4A, Ogg Vorbis, WMA, and more. It keeps tag conversion consistent and avoids shelling out to clunky CLI tools.

Unified API: The same methods work for different formats.
Lossless tag edits: Modify metadata without re-encoding audio.
Cover art support: Add, read, and replace embedded artwork.
Chapter and cue support: Handle split files and chapter metadata.

You’ll get a handful of copy‑pasteable snippets you can drop straight into your scripts.

2 Install Mutagen

Install the stable release via pip:

pip install --upgrade mutagen

For Apple Silicon or environments that need extra codecs, you may also install FFmpeg or mutagen[mp4] for broader MP4 support—Mutagen itself does not require FFmpeg.

3 Load a File and Save Changes

Open an audio file, read its tags, modify a value, and write back—Mutagen will handle the format‑specific details.

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

path = "path/to/file.mp3"

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

# Read a tag
title = audio.get("TIT2") or audio.get("\xa9nam")  # ID3 v2 or iTunes-style
print(title)

# Write a tag (create or update)
audio["TIT2"] = "New Song Title"
audio["TPE1"] = "New Artist"

# Persist changes
audio.save()

The .save() writes tags without touching the audio data itself.

4 Read Common Tags Across Formats

Use format‑agnostic keys to pull the same fields out of MP3, FLAC, MP4, and Ogg Vorbis files.

from mutagen import File

path = "path/to/file.mp3"  # works with .flac, .m4a, .ogg too

audio = File(path)
if audio is None:
    raise ValueError("Unsupported or unreadable file")

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 normalizes common fields for most containers; you’ll still see some legacy or vendor keys depending on the format.

5 Handle Multi‑value Fields (Artists, Genres)

Some tags are lists—mutagen keeps them as lists, not concatenated strings.

from mutagen import File

audio = File("path/to/file.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 returns a list or None; fall back safely
artists = artists if isinstance(artists, list) else ([artists] if artists else [])
genres = genres if isinstance(genres, list) else ([genres] if genres else [])

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

# Writing multi-values is the same—just assign a list
audio["TPE1"] = ["Alice", "Bob"]
audio.save()

Never join multi-values with commas yourself—players and taggers expect clean lists.

6 Add or Replace Cover Art

Read an image file and attach it as APIC (ID3) or as the standard MP4 cover atom.

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

audio = MP3("path/to/file.mp3", ID3=ID3)
audio.add_tags()  # ensure an ID3 header exists

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

# ID3: attach a front cover in JPEG
audio.tags.add(APIC(
    encoding=3,      # UTF-8
    mime="image/jpeg",
    type=3,          # Front cover
    desc="Cover",
    data=cover_data
))
audio.save()

# For MP4/M4A:
# from mutagen.mp4 import MP4
# mp4 = MP4("path/to/file.m4a")
# mp4["covr"] = [MP4.MP4Cover(cover_data, imageformat=MP4.FORMAT_JPEG)]
# mp4.save()

APIC works with MP3; MP4 uses a covr atom with raw image data. Other formats vary in key names.

7 Read Duration (Length)

Most Mutagen audio objects expose info.length in seconds.

from mutagen import File

audio = File("path/to/file.flac")
length_seconds = audio.info.length if getattr(audio, "info", None) else None
print("Length:", length_seconds)

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

Bitrate and sample rate also live under audio.info when the format exposes them.

8 Chapters from Cuesheets

If you have a CUE sheet, generate chapter tags for MP3 or MP4. This example writes ID3 chapter frames (CHAP/CTOC) for MP3.

# pip install mutagen[chapters]  # if needed for cuesheet support
from mutagen.mp3 import MP3
from mutagen.id3 import CHAP, CTOC, ID3

audio = MP3("path/to/album.mp3", ID3=ID3)

# Create a top-level table of contents with chapter elements
toc = CTOC(
    elem_id=["toc"],
    flags=0x02,  # top-level
    child_elem_ids=["ch0", "ch1", "ch2"],  # must match chapter elem_ids
    sort_index=0
)
audio.tags.add(toc)

# Add simple chapter markers at 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"Chapter {i + 1}"}
    ))

audio.save()

# MP4 (M4A) chapters are non-trivial and sometimes written as text tracks.
# Many players prefer splitting tracks and retagging instead of writing MP4 chapters directly.

ID3 chapters are widely supported in desktop players; chapter support in MP4 is mixed across apps.

9 Split a Single Audio File by Cuesheet (ffmpeg + tags)

When you actually need separate files, FFmpeg can slice the audio while Mutagen supplies the tags. Here’s a concise workflow using a simple timestamp list.

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

input_path = "path/to/album.flac"
out_dir = Path("splits")
out_dir.mkdir(exist_ok=True)

# Example timestamps (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"

    # Slice with ffmpeg (no re-encoding; copy streams)
    cmd = [
        "ffmpeg", "-y",
        "-i", str(input_path),
        "-ss", start,
        "-to", end,
        "-c", "copy",
        str(out_path)
    ]
    subprocess.run(cmd, check=True)

    # Apply tags to the new file
    track = MP3(str(out_path), ID3=ID3)
    track.add_tags()
    track["TIT2"] = f"{title} (Part {i+1})"
    track["TPE1"] = artist
    track["TRACK"] = f"{i+1}/{len(chapters)-1}"
    track.save()

print("Split complete.")

Using -c copy avoids transcoding—only the container is rewritten.

10 Batch Fix Track Numbers

Rename and tag a folder of tracks in one pass using filesystem order as a fallback.

from pathlib import Path
from mutagen import File
import shutil

root = Path("path/to/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

    # Prefer existing TRACK; fall back to index
    track = audio.get("TRACK") or audio.get("trkn") or [idx]
    # Normalize to current track number (ignore total for rename)
    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))

    # Update TRACK safely
    audio["TRACK"] = f"{idx}/{len(files)}"
    # MP4 uses a tuple for trkn; leave other formats as string
    audio.save()

print("Tracks normalized.")

Be careful with MP4 trkn—it’s a tuple. The generic code above keeps MP3/FLAC simple and should work in most cases.

11 What Next?

You’ve got a practical toolbox for reading, editing, and reorganizing audio metadata. A few ideas:

Normalize labels and casing with a config file.
Write a small web endpoint to serve tags for a static collection.
Batch‑update artwork per folder, using hashed filenames to deduplicate.

Save these snippets; they’ll slip into your scripts like a well‑worn key.