0
# Mutagen
1

2
Mutagen is a comprehensive Python library for handling audio metadata across 20+ different audio formats. It provides both low-level format-specific APIs and high-level easy-to-use interfaces for reading, writing, and manipulating audio file tags and stream information.
3

4
## Package Information
5

6
**Package:** `mutagen`  
7
**Version:** 1.47.0  
8
**PyPI:** https://pypi.org/project/mutagen/  
9

10
## Core Imports
11

12
```python { .api }
13
# Main entry point with auto-detection
14
import mutagen
15
from mutagen import File
16

17
# Base classes and exceptions
18
from mutagen import FileType, StreamInfo, Tags, Metadata, PaddingInfo, MutagenError
19

20
# Version information
21
from mutagen import version, version_string
22
```
23

24
## Basic Usage
25

26
### Auto-Detection
27
```python
28
import mutagen
29

30
# Automatically detect format and load appropriate handler
31
audio_file = mutagen.File("song.mp3")  # Returns MP3 instance
32
audio_file = mutagen.File("song.flac")  # Returns FLAC instance
33
audio_file = mutagen.File("song.m4a")   # Returns MP4 instance
34

35
# Access metadata like a dictionary
36
print(audio_file["TIT2"])  # Title for MP3/ID3
37
print(audio_file["TITLE"]) # Title for FLAC/Vorbis
38

39
# Stream information
40
info = audio_file.info
41
print(f"Length: {info.length} seconds")
42
print(f"Bitrate: {info.bitrate} bps")
43
```
44

45
### Format-Specific Loading
46
```python
47
from mutagen.mp3 import MP3
48
from mutagen.flac import FLAC
49
from mutagen.mp4 import MP4
50

51
mp3_file = MP3("song.mp3")
52
flac_file = FLAC("song.flac") 
53
mp4_file = MP4("song.m4a")
54
```
55

56
## Architecture
57

58
### Core Concepts
59

60
**FileType Classes**: Each supported format has a main class (MP3, FLAC, MP4, etc.) that inherits from `FileType`. These provide format-specific tag access and stream information.
61

62
**Auto-Detection**: The `File()` function examines file headers to automatically select the appropriate format handler, returning the correct FileType instance.
63

64
**Tag Containers**: Different formats use different tag systems (ID3 for MP3, Vorbis Comments for FLAC/OGG, iTunes metadata for MP4). Mutagen provides native access to each system.
65

66
**Easy Interfaces**: Simplified dictionary-like interfaces (EasyID3, EasyMP4) that normalize tag names across formats for easier cross-format development.
67

68
**Stream Information**: All formats provide `.info` attribute containing technical details like bitrate, sample rate, duration, and encoding parameters.
69

70
## Capabilities
71

72
### Format Support
73
Mutagen supports 20+ audio formats organized into these categories:
74

75
- **MP3 & ID3 Tags**: Complete ID3v2 implementation with 100+ frame types → [MP3 and ID3 Tags](./mp3-id3.md)
76
- **Lossless Formats**: FLAC, WavPack, TrueAudio, APE, and more → [Lossless Audio Formats](./lossless-formats.md)  
77
- **Container Formats**: MP4/M4A, ASF/WMA with native metadata → [Container Formats](./container-formats.md)
78
- **OGG Family**: Vorbis, FLAC, Opus, Speex, Theora in OGG containers → [OGG Formats](./ogg-formats.md)
79

80
### Core Functionality
81
```python { .api }
82
# File detection and base classes
83
def File(filething, options=None, easy=False) -> FileType | None:
84
    """Auto-detect audio format and return appropriate FileType instance.
85
    
86
    Args:
87
        filething: File path string or file-like object
88
        options: Sequence of FileType implementations, defaults to all included ones
89
        easy: If True, use easy interface when available
90
        
91
    Returns:
92
        FileType instance for the detected format, or None if type couldn't be determined
93
        
94
    Raises:
95
        MutagenError: if the detected type fails to load the file
96
    """
97

98
class FileType:
99
    """Abstract base class for all audio file types.
100
    
101
    Attributes:
102
        tags: Tag container for the file (format-specific)
103
        info: StreamInfo instance with technical details
104
    """
105
    
106
    def save(self, **kwargs) -> None:
107
        """Save tags back to file"""
108
    
109
    def delete(self) -> None:
110
        """Remove all tags from file"""
111

112
class StreamInfo:
113
    """Abstract base class for audio stream information.
114
    
115
    Attributes:
116
        length: Duration in seconds (float)
117
        bitrate: Bitrate in bits per second (int)
118
    """
119
```
120

121
### Tag Manipulation
122
```python { .api }
123
# Dictionary-like tag access
124
audio_file["TITLE"] = ["Song Title"]
125
audio_file["ARTIST"] = ["Artist Name"] 
126
audio_file["ALBUM"] = ["Album Name"]
127

128
# Save changes
129
audio_file.save()
130

131
# Remove specific tag
132
del audio_file["GENRE"]
133

134
# Remove all tags
135
audio_file.delete()
136
```
137

138
### Easy Interfaces
139
For simplified cross-format development → [Easy Interfaces](./easy-interfaces.md)
140

141
```python { .api }
142
from mutagen.easyid3 import EasyID3
143
from mutagen.easymp4 import EasyMP4
144

145
# Normalized tag names across formats
146
easy_id3 = EasyID3("song.mp3")
147
easy_mp4 = EasyMP4("song.m4a")
148

149
# Same tag names work for both
150
easy_id3["title"] = ["Song Title"]
151
easy_mp4["title"] = ["Song Title"]
152
```
153

154
### Advanced Features
155
```python { .api }
156
# Embedded artwork (format-dependent)
157
from mutagen.id3 import APIC
158
from mutagen.mp4 import MP4Cover
159

160
# ID3 artwork
161
mp3_file["APIC:"] = APIC(data=image_bytes, type=3, desc="Cover")
162

163
# MP4 artwork  
164
mp4_file["covr"] = [MP4Cover(image_bytes, MP4Cover.FORMAT_JPEG)]
165

166
# Custom metadata
167
mp4_file["----:com.apple.iTunes:CUSTOM"] = [b"Custom Value"]
168
```
169

170
## Error Handling
171

172
```python { .api }
173
from mutagen import MutagenError
174

175
try:
176
    audio_file = mutagen.File("corrupted.mp3")
177
    if audio_file is None:
178
        print("Unsupported or corrupted file")
179
except MutagenError as e:
180
    print(f"Mutagen error: {e}")
181
except IOError as e:
182
    print(f"File error: {e}")
183
```
184

185
## See Also
186

187
- [Core Functionality](./core-functionality.md) - File detection, base classes, and common patterns
188
- [MP3 and ID3 Tags](./mp3-id3.md) - Complete MP3 and ID3v2 tag support  
189
- [Lossless Audio Formats](./lossless-formats.md) - FLAC, WavPack, TrueAudio and other lossless formats
190
- [Container Formats](./container-formats.md) - MP4/M4A and ASF/WMA containers
191
- [OGG Formats](./ogg-formats.md) - OGG Vorbis, FLAC, Opus and other OGG-based formats
192
- [Easy Interfaces](./easy-interfaces.md) - Simplified cross-format tag access