Mutagen Audio Tagging Library

1.47.0 · active · verified Thu Apr 09

Mutagen is a Python library to read and write audio tags for many formats, including MP3, FLAC, Ogg Vorbis/Opus/FLAC, M4A, ASF, and more. It provides both high-level access for common tags and low-level access to manipulate specific frame types. The library is actively maintained, with minor versions released every few months, currently at 1.47.0.

Warnings

breaking Python 3.6 support was dropped.
Fix: Upgrade to Python 3.7 or newer to use mutagen 1.45.0+.
gotcha The `mutagen.File()` function returns `None` if the specified file does not exist or cannot be opened/parsed as an audio file.
Fix: Always check for `None` after calling `mutagen.File()`: `audio = mutagen.File('path.mp3'); if audio is None: print('File not found or invalid.')`
deprecated Using `MP3.add_tags()` to add ID3 tags to an MP3 file is deprecated.
Fix: Instead of `audio = MP3('path.mp3'); audio.add_tags()`, directly assign a new `ID3` object if `audio.tags` is `None`: `audio = MP3('path.mp3'); if audio.tags is None: audio.tags = ID3()`.
gotcha When creating a new `mutagen.id3.ID3` object, it no longer automatically populates with default frames. You must explicitly add all desired frames.
Fix: When initializing new ID3 tags (`audio.tags = ID3()`), make sure to then `audio.tags.add(...)` all required frames (e.g., `TIT2`, `TPE1`, etc.) or assign them directly.
gotcha Changes made to audio tags are not persisted to the file system until the `.save()` method is explicitly called on the audio object.
Fix: Always remember to call `audio_file.save()` after modifying tags: `audio_file['title'] = ['New Title']; audio_file.save()`.

Install

pip install mutagen Install latest version

Imports

File
```
from mutagen import File
```
Primary entry point for opening any supported audio file type.
MP3
```
from mutagen.mp3 import MP3
```
For working specifically with MP3 files and their underlying ID3 tags.
EasyID3
```
from mutagen.easyid3 import EasyID3
```
Simplified interface for common ID3 tags (MP3s), often preferred for ease of use.
ID3
```
from mutagen.id3 import ID3
```
For direct manipulation of ID3 tags and frames.
ID3NoHeaderError
```
from mutagen.id3 import ID3NoHeaderError
```
Exception raised when an MP3 file lacks an ID3 header.

Quickstart

This quickstart demonstrates how to create a dummy MP3 file, add ID3 tags using `mutagen.id3.ID3` frame objects, save them, then read and update tags using the simpler `mutagen.File(..., easy=True)` interface. Remember to always call `.save()` to persist changes.

import os
import mutagen
from mutagen.id3 import ID3, TIT2, TPE1, TALB
from mutagen.mp3 import MP3

# --- Create a dummy MP3 file for demonstration ---
# In a real scenario, you would use an actual audio file.
# This creates a minimal, valid-ish MP3 structure that mutagen can parse.
temp_mp3_path = "temp_quickstart_audio.mp3"
try:
    with open(temp_mp3_path, "wb") as f:
        f.write(b'\xFF\xFB\x30\x00' + b'\x00' * 1024)

    # --- Initializing and Adding Tags (using ID3 frames) ---
    # mutagen.File() is the primary entry point; for MP3s, it returns an MP3 object.
    audio_file = mutagen.File(temp_mp3_path)
    if audio_file is None:
        raise ValueError("Could not open dummy MP3 file.")

    # If the file has no ID3 tags, create a new ID3 object for it.
    if audio_file.tags is None:
        audio_file.tags = ID3()
    
    # Set common tags using ID3 frame objects
    audio_file.tags.add(TIT2(encoding=3, text=["My New Track Title"])) # Title
    audio_file.tags.add(TPE1(encoding=3, text=["Example Artist"])) # Artist
    audio_file.tags.add(TALB(encoding=3, text=["Demo Album"])) # Album
    
    audio_file.save() # Crucial: Saves changes to the file

    print(f"Tags written to '{temp_mp3_path}' using ID3 frames.")

    # --- Reading Tags (using EasyID3 for simpler access) ---
    # Open the file again, using easy=True for a dictionary-like interface
    easy_audio = mutagen.File(temp_mp3_path, easy=True)
    if easy_audio is None:
        raise ValueError("Could not re-open dummy MP3 with easy=True.")

    print("\n--- Reading Tags (using EasyID3) ---")
    print(f"Title: {easy_audio.get('title', ['N/A'])[0]}")
    print(f"Artist: {easy_audio.get('artist', ['N/A'])[0]}")
    print(f"Album: {easy_audio.get('album', ['N/A'])[0]}")
    
    # --- Updating Tags (using EasyID3) ---
    easy_audio["artist"] = ["Updated Artist Name"]
    easy_audio.save() # Save the update
    
    reloaded_easy_audio = mutagen.File(temp_mp3_path, easy=True)
    print(f"\nEasyID3 Artist (updated): {reloaded_easy_audio.get('artist', ['N/A'])[0]}")

except Exception as e:
    print(f"An error occurred: {e}")
    print("Ensure you have write permissions in the current directory and the file can be created/accessed.")
finally:
    # Clean up the dummy file
    if os.path.exists(temp_mp3_path):
        os.remove(temp_mp3_path)
        print(f"\nCleaned up '{temp_mp3_path}'.")

view raw JSON →