$ show quodlibet/mutagen
Mutagen is a mature, comprehensive Python library for reading and writing audio metadata across virtually all common formats, including MP3 (ID3v1/v2, APEv2), FLAC, Ogg Vorbis/Opus/Speex/Theora, MP4/M4A, ASF/WMA, WavPack, AIFF, DSF, DSDIFF, True Audio, Musepack, Monkey's Audio, OptimFROG, AAC, AC3, and more. It provides a consistent dictionary-like API for tag manipulation, format-specific stream info (bitrate, sample rate, channels, length), and low-level access to container structures (Ogg pages, ID3 frames, IFF chunks, MP4 atoms). The library is designed for embedding in larger applications (e.g., Quod Libet, Beets, MusicBrainz Picard) and also ships several command-line tools: mid3v2 (ID3 tag editor), mid3iconv (ID3 encoding converter), mid3cp (ID3 tag copier), moggsplit (Ogg stream splitter), mutagen-inspect (format inspector), and mutagen-pony (ID3 health checker). Architecturally, Mutagen follows a layered design: a base `FileType` class with format detection via static `score()` methods, per-format modules that parse container headers and metadata, and a shared utility layer (`_util.py`) providing file I/O decorators, binary packing/unpacking (`cdata`), bit-level readers, dictionary mixins, and padding management. The ID3 subsystem is particularly sophisticated, with a declarative frame specification system (`_specs.py`) that handles encoding, version conversion, and unsynchronization. The Ogg subsystem provides a clean `OggPage` abstraction reused by all Ogg-based formats. The IFF subsystem (`_iff.py`) generalizes chunk-based containers for AIFF, RIFF/WAVE, and DSDIFF. Data flows are straightforward: the user opens a file via `mutagen.File()` or a format-specific constructor, which triggers header parsing and tag loading. Tags are exposed as mutable dictionaries; saving writes updated metadata back to the file with configurable padding. The library supports file-like objects and pathlib paths throughout. External dependencies are minimal (pure Python, no runtime dependencies beyond the standard library), making it highly portable. The test suite includes over 3000 tests, fuzzing infrastructure, and a large corpus of synthetic audio fixtures covering edge cases and malformed inputs.
The LLM identified 4 files worth highlighting for reuse:
Core utility module providing the `loadfile` decorator (transparently handles filenames, file-like objects, and pathlib paths), `cdata` static class for all integer endianness/size conversions (generated via `_fill_cdata`), `BitReader` for bit-level parsing, `DictMixin`/`DictProxy` for dict-like tag wrappers, `PaddingInfo` for dynamic padding calculations, and file resizing helpers (`insert_bytes`, `delete_bytes`, `resize_bytes`). This module is self-contained (only imports standard library and `_constants`) and could be extracted into a standalone binary parsing utility library.
Implements `VComment` and `VCommentDict`, the standard Vorbis comment metadata container used by Ogg Vorbis, Opus, Speex, Theora, and FLAC. Provides case-insensitive key access, validation of field names and values (ASCII/UTF-8), and support for embedded images via `metadata_block_picture` and `coverart` fields. The pattern of a validated, case-insensitive dictionary with format-specific serialization is reusable for any key-value metadata system.
Generic IFF (Interchange File Format) chunk parsing infrastructure, providing `IffChunk` (individual chunk with type, size, data), `IffContainerChunkMixin` (for chunks that contain sub-chunks), and `IffFile` base class. Used by AIFF, RIFF/WAVE, and DSDIFF format modules. The design cleanly separates chunk reading/writing from format-specific logic and could be extracted as a reusable IFF parser library.
Provides `OggPage` class for parsing and writing Ogg container pages, including header fields (version, serial number, granule position, page sequence number, checksum), packet segmentation, and page flags (continued, first/last). Also includes `OggFileType` base class shared by all Ogg-based formats. The page abstraction is clean and self-contained, suitable for reuse in any Ogg stream manipulation tool.