---
id: mediafile
version: "0.17.0"
license: MIT
license_treatment: permissive
maintenance: active
---

# mediafile — A simple, cross-format library for reading and writing media file metadata.

License: permissive · Maintenance: active · Downloads: 134.4K/mo

## What it is and what it does

MediaFile is a Python library that simplifies reading and writing metadata tags in audio files. It sits on top of Mutagen, a mature low-level tag manipulation library, and presents a unified, format-agnostic interface so you can work with tags the same way across different audio formats. Instead of learning format-specific tag APIs, you load an audio file into a MediaFile object, read or modify standard fields like title and artist, and call save() to write changes back.

The library is part of the beets project and supports Python 3.10 or later, including PyPy. It exposes both singular fields and plural fields for repeated metadata values, making it practical for music library tools, batch tagging scripts, and metadata workflows.

Use it for:

- Batch update or normalize metadata across a music collection without learning format-specific tag APIs.
- Build a music library management tool that reads and modifies tags consistently across multiple audio formats.
- Extract and display audio metadata in a music player or cataloging application.
- Programmatically fix or populate missing tags in audio files.
- Migrate or convert metadata between different audio formats by reading from one and writing to another.

## Worth the install?

AI-flagged interpretation of the facts above — verify before relying.

MediaFile reads and writes metadata tags across many audio file formats through a single, format-independent Python interface, wrapping the low-level Mutagen library.

Yes. MediaFile is actively maintained, has no known vulnerabilities, low install friction, and a permissive MIT license. It solves a real problem—unified audio metadata handling—with a clean API and proven track record as part of the beets project. Install it if you need to read or write audio tags programmatically.

## Install

pip install mediafile
uv add mediafile
poetry add mediafile

## Installing mediafile

Before you install: Low friction: pure Python wheel, only two runtime dependencies (filetype and mutagen), and actively maintained with a recent release.

License in practice: MIT license permits commercial and private use with minimal restrictions; you may use, modify, and distribute this package freely provided you include the license notice.

Quickstart:

pip install mediafile

from mediafile import MediaFile

f = MediaFile("Lucy.mp3")
f.title
f.artist = "The Beatles"
f.save()

Requires Python 3.10 or later.

Verify before relying:

- Which specific audio formats are supported beyond mp3 mentioned in the example.
- Whether plural fields (artists, composers, etc.) are available for all supported formats or only a subset.
- Performance characteristics when handling large audio files or batch operations.

## Package facts

- License: MIT (permissive)
- Python support: supports_current
- Install friction: low
- Maintenance: active
- Downloads: 134.4K/month (top 15,000 on PyPI)
- Known vulnerabilities: none known

## Tags

audio metadata tags read write, mp3 tag editor python, audio file metadata library, cross-format audio tagging, mutagen wrapper, audio metadata interface, audio-metadata, tag-editing

[View on SkillFed](https://skillfed.io/packages/mediafile) · [View on PyPI](https://pypi.org/project/mediafile/)