Skip to main content

A library for reading and, in the future, writing metadata from audio files.

Project description


Docs - Stable Docs - Latest

audio-metadata is a library for reading and, in the future, writing metadata from audio files.

Why another audio metadata library? / Why not just use mutagen et al?

Clean and understandable code, nice API, and good UX (user experience) are the focal points of audio-metadata. One or more of these things I feel are lacking from already existing alternatives enough to want to write something from scratch with them in mind. Also, there are certain features not present in other solutions that would be prohibitively painful to add.

So, why should I use it?

Features and functionality that set it apart:

  • Uses the Python standard load(s)/dump(s) API.
    • Can load filepaths, file-like objects and binary data (bytes-like objects).
  • Metadata objects look like a dict and act like a dict.
    • Some common libraries shadow the representation of a dict and/or dict methods but do not behave like a dict.
    • Supports attribute-style access that can be mixed with dict key-subscription.
  • All metadata objects have user-friendly representations.
    • This includes humanized representations of certain values like filesize, bitrate, duration, and sample rate.
>>> import audio_metadata

>>> metadata = audio_metadata.load('05 - Heart of Hearts.flac')

>>> metadata
<FLAC ({
	'filepath': '05 - Heart of Hearts.flac',
	'filesize': '44.23 MiB',
	'pictures': [],
	'seektable': <FLACSeekTable (37 seekpoints)>,
	'streaminfo': <FLACStreamInfo ({
		'bit_depth': 16,
		'bitrate': '1022 Kbps',
		'channels': 2,
		'duration': '06:03',
		'md5': '3ae700893d099a5d281a5d8db7847671',
		'sample_rate': '44.1 KHz',
	'tags': <VorbisComment ({
		'album': ['Myth Takes'],
		'artist': ['!!!'],
		'bpm': ['119'],
		'date': ['2007'],
		'genre': ['Dance Punk'],
		'title': ['Heart of Hearts'],
		'tracknumber': ['05'],

>>> metadata['streaminfo']
<FLACStreamInfo ({
	'bit_depth': 16,
	'bitrate': '1022 Kbps',
	'channels': 2,
	'duration': '06:03',
	'md5': '3ae700893d099a5d281a5d8db7847671',
	'sample_rate': '44.1 KHz',

>>> metadata.streaminfo.bitrate

>>> metadata.streaminfo['duration']

>>> metadata['streaminfo'].sample_rate


pip install audio-metadata


For the release version, see the stable docs.
For the development version, see the latest docs.

The high-level API and basic usage are covered, but more advanced features/functionality need documentation.


Please don't submit issues regarding the following:

  • Docs, docs, and more docs.
  • Finish ID3 abstractions.
  • Add support for more file formats.
    • MP4 reading is already well underway.
  • Add write support.

If you're willing to contribute your time to work on them, post on the Development category on the Discourse forum.


Showing appreciation is always welcome.


Say Thanks

Get your own thanks inbox at


Contribute by submitting bug reports, feature requests, or code.

Help Others/Stay Informed

Discourse forum


Coinbase Digital Ocean Namecheap PayPal

ETH: 0x8E3f8d8eAedeA61Bf34A998A2104954FE508D5d0
LTC: LgsQU1YaY4a4s7m9efjn6m35XhVEpW1xoP

Project details

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

audio-metadata-0.3.4.tar.gz (23.8 kB view hashes)

Uploaded Source

Built Distribution

audio_metadata-0.3.4-py3-none-any.whl (71.8 kB view hashes)

Uploaded Python 3

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page