{"id":1567,"library":"mutagen","title":"Mutagen Audio Tagging Library","description":"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.","status":"active","version":"1.47.0","language":"en","source_language":"en","source_url":"https://github.com/quodlibet/mutagen","tags":["audio","metadata","tagging","mp3","flac","id3","ogg"],"install":[{"cmd":"pip install mutagen","lang":"bash","label":"Install latest version"}],"dependencies":[],"imports":[{"note":"Primary entry point for opening any supported audio file type.","symbol":"File","correct":"from mutagen import File"},{"note":"For working specifically with MP3 files and their underlying ID3 tags.","symbol":"MP3","correct":"from mutagen.mp3 import MP3"},{"note":"Simplified interface for common ID3 tags (MP3s), often preferred for ease of use.","symbol":"EasyID3","correct":"from mutagen.easyid3 import EasyID3"},{"note":"For direct manipulation of ID3 tags and frames.","symbol":"ID3","correct":"from mutagen.id3 import ID3"},{"note":"Exception raised when an MP3 file lacks an ID3 header.","symbol":"ID3NoHeaderError","correct":"from mutagen.id3 import ID3NoHeaderError"}],"quickstart":{"code":"import os\nimport mutagen\nfrom mutagen.id3 import ID3, TIT2, TPE1, TALB\nfrom mutagen.mp3 import MP3\n\n# --- Create a dummy MP3 file for demonstration ---\n# In a real scenario, you would use an actual audio file.\n# This creates a minimal, valid-ish MP3 structure that mutagen can parse.\ntemp_mp3_path = \"temp_quickstart_audio.mp3\"\ntry:\n    with open(temp_mp3_path, \"wb\") as f:\n        f.write(b'\\xFF\\xFB\\x30\\x00' + b'\\x00' * 1024)\n\n    # --- Initializing and Adding Tags (using ID3 frames) ---\n    # mutagen.File() is the primary entry point; for MP3s, it returns an MP3 object.\n    audio_file = mutagen.File(temp_mp3_path)\n    if audio_file is None:\n        raise ValueError(\"Could not open dummy MP3 file.\")\n\n    # If the file has no ID3 tags, create a new ID3 object for it.\n    if audio_file.tags is None:\n        audio_file.tags = ID3()\n    \n    # Set common tags using ID3 frame objects\n    audio_file.tags.add(TIT2(encoding=3, text=[\"My New Track Title\"])) # Title\n    audio_file.tags.add(TPE1(encoding=3, text=[\"Example Artist\"])) # Artist\n    audio_file.tags.add(TALB(encoding=3, text=[\"Demo Album\"])) # Album\n    \n    audio_file.save() # Crucial: Saves changes to the file\n\n    print(f\"Tags written to '{temp_mp3_path}' using ID3 frames.\")\n\n    # --- Reading Tags (using EasyID3 for simpler access) ---\n    # Open the file again, using easy=True for a dictionary-like interface\n    easy_audio = mutagen.File(temp_mp3_path, easy=True)\n    if easy_audio is None:\n        raise ValueError(\"Could not re-open dummy MP3 with easy=True.\")\n\n    print(\"\\n--- Reading Tags (using EasyID3) ---\")\n    print(f\"Title: {easy_audio.get('title', ['N/A'])[0]}\")\n    print(f\"Artist: {easy_audio.get('artist', ['N/A'])[0]}\")\n    print(f\"Album: {easy_audio.get('album', ['N/A'])[0]}\")\n    \n    # --- Updating Tags (using EasyID3) ---\n    easy_audio[\"artist\"] = [\"Updated Artist Name\"]\n    easy_audio.save() # Save the update\n    \n    reloaded_easy_audio = mutagen.File(temp_mp3_path, easy=True)\n    print(f\"\\nEasyID3 Artist (updated): {reloaded_easy_audio.get('artist', ['N/A'])[0]}\")\n\nexcept Exception as e:\n    print(f\"An error occurred: {e}\")\n    print(\"Ensure you have write permissions in the current directory and the file can be created/accessed.\")\nfinally:\n    # Clean up the dummy file\n    if os.path.exists(temp_mp3_path):\n        os.remove(temp_mp3_path)\n        print(f\"\\nCleaned up '{temp_mp3_path}'.\")","lang":"python","description":"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."},"warnings":[{"fix":"Upgrade to Python 3.7 or newer to use mutagen 1.45.0+.","message":"Python 3.6 support was dropped.","severity":"breaking","affected_versions":">=1.45.0"},{"fix":"Always check for `None` after calling `mutagen.File()`: `audio = mutagen.File('path.mp3'); if audio is None: print('File not found or invalid.')`","message":"The `mutagen.File()` function returns `None` if the specified file does not exist or cannot be opened/parsed as an audio file.","severity":"gotcha","affected_versions":">=1.39"},{"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()`.","message":"Using `MP3.add_tags()` to add ID3 tags to an MP3 file is deprecated.","severity":"deprecated","affected_versions":">=1.44.0"},{"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.","message":"When creating a new `mutagen.id3.ID3` object, it no longer automatically populates with default frames. You must explicitly add all desired frames.","severity":"gotcha","affected_versions":">=1.43.0"},{"fix":"Always remember to call `audio_file.save()` after modifying tags: `audio_file['title'] = ['New Title']; audio_file.save()`.","message":"Changes made to audio tags are not persisted to the file system until the `.save()` method is explicitly called on the audio object.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-09T00:00:00.000Z","next_check":"2026-07-08T00:00:00.000Z"}