eyed3
View and modify MP3 ID3 metadata tags
TLDR
View information about an MP3 file
Set the title of an MP3 file
Set the album of all the MP3 files in a directory
Set the front cover art for an MP3 file
SYNOPSIS
eyeD3 [global-options] {tags|stats|convert|fingerprint|header} [command-options] [audio-files...]
Legacy: eyeD3 [options] [audio-files]
PARAMETERS
-h, --help
Show help message and exit
-v, --verbose
Increase verbosity (repeatable)
--quiet
Suppress non-essential output
--debug
Enable debug output
-a TEXT, --artist TEXT
Set artist/performer (tags subcommand)
-t TEXT, --title TEXT
Set title/song name
-A TEXT, --album TEXT
Set album name
--track ONE [TOTAL]
Set track number and total tracks
--year YYYY
Set release year
--genre TEXT|ID
Set genre by name or ID
--add-image PATH [TYPE [DESC]]
Embed image file (cover art)
--remove-all
Remove all tags (tags subcommand)
--to-v2.3
Convert tags to ID3 v2.3
--rename PATTERN
Rename files based on tag pattern
--write-id3v1
Force write ID3 v1.1 tag
DESCRIPTION
eyeD3 is a versatile Python tool designed for reading, writing, and manipulating ID3 metadata tags in audio files. Primarily focused on MP3 files, it fully supports ID3v1.x, ID3v2.3, and ID3v2.4 standards, with extensibility to formats like FLAC, MP4/M4A, and Ogg Vorbis via plugins such as mutagen.
Users can set standard fields like artist, title, album, track number, genre, year, and comments, as well as advanced features including embedded images (cover art), lyrics (SYLT/USLT), popularimeter ratings, and custom text frames. Batch operations allow processing entire directories, renaming files based on tag patterns, validating tag integrity, and exporting metadata to text, XML, JSON, or HTML formats.
Modern versions (0.8+) feature a subcommand-based CLI for specialized tasks: tags for editing, stats for analysis, convert for transcoding and tag migration, and fingerprint for audio identification. It's script-friendly, cross-platform, and invaluable for music library automation on Linux servers or desktops without GUIs.
CAVEATS
Modifies files in-place; always backup originals. MP3 native support best; other formats require plugins like mutagen. Subcommand syntax mandatory in 0.8+; legacy mode deprecated. Large cover arts may increase file size significantly.
INSTALLATION
Linux: apt install eyed3 (Debian/Ubuntu) or pip install eyeD3. Requires Python 3.7+.
COMMON EXAMPLES
eyeD3 tags --artist "Beatles" song.mp3
eyeD3 stats *.mp3
eyeD3 tags --add-image cover.jpg song.mp3
SUBCOMMANDS
tags: Edit/read tags
stats: File/tag statistics
convert: Transcode audio/tag migration
fingerprint: Generate audio fingerprints
HISTORY
Created by Travis Shirk in 2001 as a Perl tool, rewritten in Python by 2003. Matured through 0.7.x series focusing on ID3v2.4. CLI refactored to subcommands in 0.8.0 (2016). Latest 0.9.10 (2024) adds fingerprinting and improved plugin support.
