AudioMeta Python

A powerful, unified Python library for reading and writing audio metadata across multiple formats. AudioMeta supports MP3, FLAC, and WAV audio files, working seamlessly with ID3v1, ID3v2, Vorbis, and RIFF metadata formats through a single, consistent API.

Try it: A demo web app is available at audiometa.themusictree.org.

Author: Andreas Garcia

⭐ Show Your Support

If you find AudioMeta Python useful, please consider:

⭐ Starring this repository - It helps others discover the project
🐛 Reporting bugs - Help improve the library by opening an issue
💡 Suggesting features - Share your ideas via GitHub Discussions or feature requests
🤝 Contributing - See CONTRIBUTING.md for ways to help
📢 Sharing - Tell others about AudioMeta Python

Your support helps make this project better for everyone! 🎵

⭐ Show Your Support
✨ Features
📁 Supported Formats
📊 Supported Fields And Audio Technical Info
📦 Installation
🚀 Getting Started
⚡ Quick Start
📚 Core API Reference
📖 Metadata Guide
💻 Command Line Interface
📝 Changelog
🤝 Contributing
Code of Conduct
Security Policy
License

✨ Features

Unified API: A single, consistent API for reading and writing metadata across all supported formats. Use the same functions (get_unified_metadata(), update_metadata(), etc.) regardless of whether you're working with MP3, FLAC, or WAV files. The library automatically handles format-specific differences, normalizes field names, and intelligently merges metadata from multiple formats when reading.
Multi-format Support: ID3v1, ID3v2, Vorbis (FLAC), and RIFF (WAV) metadata formats. Many audio files can contain multiple metadata formats simultaneously (e.g., MP3 files with both ID3v1 and ID3v2 tags, FLAC files with ID3v1, ID3v2, and Vorbis comments). AudioMeta intelligently handles these scenarios with automatic format detection and priority-based reading.
Format Control: Force specific metadata formats when reading or writing for precise control. Read only ID3v1 tags from an MP3 file that contains both ID3v1 and ID3v2, or write metadata exclusively to the Vorbis format in a FLAC file. Essential for format-specific operations, migration tasks, or working with legacy metadata formats.
Technical Information: Access to technical information about audio files, including duration, bitrate, sample rate, channels, and file size. This technical data is extracted directly from audio file headers, so you can get comprehensive file analysis even when no metadata tags are present.
Core Metadata Fields: Support for 15+ metadata fields including title, artist, album, rating, BPM, and more. More fields are planned to be supported soon.
Read/Write Operations: Full read and write support for most formats
Rating Support: Normalized rating handling across different formats
Complete File Analysis: Get full metadata including headers and technical details even when no metadata is present

📁 Supported Formats

Supported Audio Formats Per Metadata Format

| Format | Audio Format | | ------ | -------------- | | ID3v1 | MP3, FLAC, WAV | | ID3v2 | MP3, FLAC, WAV | | Vorbis | FLAC | | RIFF | WAV |

Supported Metadata Formats per Audio Format

| Audio Format | Supported Metadata Formats | | ------------ | -------------------------- | | MP3 | ID3v1, ID3v2 | | FLAC | ID3v1, ID3v2, Vorbis | | WAV | ID3v1, ID3v2, RIFF |

Format Capabilities

For comprehensive information about each metadata format (history, structure, advantages, disadvantages, use cases), see the Metadata Formats Guide.

ID3v1 Metadata Format

Primary Support: MP3 files (native format)
Extended Support: FLAC and WAV files with ID3v1 tags
Limitations: 30-character field limits, no album artist support
Operations: Full read/write support with direct file manipulation
Note: ID3v1.1 is supported (track number supported in comment field)

ID3v2 Metadata Format

Supported Formats: MP3, WAV, FLAC
Features: All metadata fields, multiple artists, cover art, extended metadata
Versions: Supports ID3v2.3 and ID3v2.4
Note: Most versatile format, works across multiple file types

Vorbis Metadata Format

Primary Support: FLAC files (native Vorbis comments)
Features: Most metadata fields, multiple artists, cover art
Limitations: Some fields not supported (lyrics, etc.)
Note: Standard metadata format for FLAC files

Vorbis Comment Key Handling Vorbis comment field names are case-insensitive, as defined by the Xiph.org Vorbis Comment specification. To ensure consistent and predictable behavior, this library normalizes all field names internally and follows modern interoperability conventions.

Reading When reading Vorbis comments, the library treats field names in a case-insensitive manner. For example, "TITLE", "title", and "Title" are considered equivalent.

Writing When writing Vorbis comments, the library standardizes field names to uppercase to maintain consistency and compatibility with common practices in audio metadata management. It thus writes "TITLE" removing eventual existing variations in casing.

RIFF Metadata Format

Strict Support: WAV files only
Features: Most metadata fields including album artist, language, comments
Limitations: Some fields not supported (BPM, lyrics, etc.)
Note: Native metadata format for WAV files

📊 Supported Fields And Audio Technical Info

AudioMeta supports comprehensive audio information across all formats. For technical audio information (duration, bitrate, sample rate, channels, file size, format info, MD5 checksum validation and repair), see:

Audio Technical Info Guide

For metadata fields (title, artist, album, genres, ratings, etc.), see:

Metadata Field Guide: Support and Handling

📦 Installation

pip install audiometa-python

System Requirements

Python: 3.12, 3.13, or 3.14
Operating Systems: Windows, macOS, Linux
Dependencies: Automatically installed with the package
Required Tools: ffprobe (for WAV file processing), flac (for FLAC MD5 validation)

Installing Required Tools

The library requires several external tools for full functionality. Use the automated installation scripts to ensure you have the correct pinned versions that match CI.

Automated Setup {#automated-setup-recommended}

To ensure your local environment matches CI exactly, use the automated installation scripts:

# Ubuntu/Linux
./scripts/install-system-dependencies-ub

Audiometa

Install / Use

README