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.
pip install mutagenVerified import paths — ran on the pinned version, not inferred.
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.
Upgrade to Python 3.7 or newer to use mutagen 1.45.0+.
Always check for `None` after calling `mutagen.File()`: `audio = mutagen.File('path.mp3'); if audio is None: print('File not found or invalid.')`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()`.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.
Always remember to call `audio_file.save()` after modifying tags: `audio_file['title'] = ['New Title']; audio_file.save()`.
Ensure the audio file being modified is valid and not corrupt. If creating a new file or adding tags, verify that the data (especially image data or custom frames) is correctly formatted and within expected limits. Always confirm write permissions for the target file and directory.
Verify the integrity of your MP3 file. If reading, try a different, known-good MP3 file. If writing, ensure the data you are writing is valid for the MP3 format and that the file system permissions allow for proper file creation/modification.
Install the library using pip: `python -m pip install mutagen` or `pip install mutagen` if your PATH is configured correctly.
Use a `try-except` block to handle missing keys or use the `.get()` method, which allows specifying a default value if the key is not found:
```python
from mutagen.id3 import ID3
audio = ID3('audio.mp3')
# Using .get() method
series = audio.get('TXXX:SERIES')
if series: # Check if series is not None
print(series.text)
else:
print('No series tag found')
# Or using try-except
try:
print(audio['TXXX:SERIES'].text)
except KeyError:
print('No series tag found')
```
For simpler tag manipulation with common keys, use `mutagen.easyid3.EasyID3`. For advanced control with the low-level `ID3` API, create appropriate `mutagen.id3.Frame` objects:
```python
# Fix using EasyID3 for simple tags
from mutagen.easyid3 import EasyID3
audio = EasyID3('audio.mp3')
audio['title'] = 'My Song Title'
audio['artist'] = 'My Artist'
audio.save()
# Fix using ID3 Frame objects for low-level API
from mutagen.id3 import ID3, TIT2, TPE1
audio = ID3('audio.mp3')
audio['TIT2'] = TIT2(encoding=3, text=['My Song Title'])
audio['TPE1'] = TPE1(encoding=3, text=['My Artist'])
audio.save()
```Ensure that `add_tags()` is called on a file that either already has tags or where you explicitly handle the possibility of `None` being returned. A common pattern is to check the return value or initialize tags if they don't exist:
```python
from mutagen.mp3 import MP3
from mutagen.id3 import ID3, TIT2
filename = 'audio.mp3'
mp3file = MP3(filename)
tags = mp3file.tags
if tags is None:
tags = ID3()
mp3file.tags = tags
tags.add(TIT2(encoding=3, text=['New Title']))
mp3file.save()
```No dependency data recorded yet.