EYED3(1)

📦
version 0.9.9 · 2 versions
, in ubuntu stonking

✨ NAME ✨

okay bestie, meet EYED3(1) — the manual page for eyeD3 💅 and what it does is literally displays and manipulates id3-tags on mp3 files. that's the whole vibe. periodt.

🎀 SYNOPSIS 🎀

eyeD3 [options] PATH [PATH...]

🌸 DESCRIPTION 🌸

so eyeD3 Manipulates ID3 tags in mp3 files and it can read, write, and convert between ID3 v1.0, v1.1, v2.3 and v2.4 tags. it gives you high-level access to most frames, including APIC frames (that's the image ones, iykyk) 🖼️

the eyeD3 command line interface is built on plugins that operate on files. wanna see what plugins you've got? use the --plugins option. wanna pick one? pass its name with --plugin=NAME. easy.

the PATH argument(s), plus optionally --exclude, are how you tell eyeD3 which files or directories to process. directories get searched recursively, and every file it bumps into gets passed to the selected plugin until no more files are found. she's thorough like that 💖

💖 BASE OPTIONS 💖

  • -h, --help — shows a lil brief help string and exits. you know, the classic.
  • --version — displays version information and exits.
  • --exclude=PATTERN — a regular expression for path exclusion. you can specify this one multiple times if you're feeling extra.
  • -L, --plugins — lists all the available plugins. window shopping ✨
  • -P NAME, --plugin=NAME — specify which plugin to use. the default is classic.
  • -C FILE, --config=FILE — supply a configuration file. the default is ~/.eyeD3/config.ini, although honestly even that is optional.
  • --no-config — do not load the default user config ~/.eyeD3/config.ini. the -c/--config options are still honored if present.
  • --backup — plugins should honor this option so that a backup is made of any file modified. the backup lands in the same directory, with a .orig extension added. protect your faves 🫶
  • -Q, --quiet — a hint to plugins to output less. shhh.
  • --fs-encoding=ENCODING — use the specified file system encoding for filenames. the default is detected from the current locale, and overriding it is useful for example when reading from mounted file systems.
  • --no-color — suppress color codes in console output. this happens automatically if the output is not a TTY (e.g. when redirecting to a file).

🐛 DEBUGGING 🐛

  • -l LEVEL[:LOGGER], --log-level=LEVEL[:LOGGER] — set a log level. this option may be specified multiple times. if a logger name is specified then the level applies only to that logger, otherwise the level is set on the top-level logger. acceptable levels are debug, verbose, info, warning, error, critical.
  • --profiler — run using python profiler.
  • --debugger — drop into python debugger when errors occur. 💀

👑 CLASSIC PLUGIN 👑

this plugin is the classic eyeD3 interface for viewing and editing tags. the goat, fr fr.

all PATH arguments are parsed and displayed. directory paths are searched recursively. any editing options (--artist, --title) are applied to each file read.

all date options (--release-year excepted) follow ISO 8601 format. this is yyyy-mm-ddThh:mm:ss. the year is required, and each component thereafter is optional. for example, "2012-03" is valid, "2012--12" is not. don't try it. 🙈

  • -a STRING, --artist=STRING — set the artist name.
  • -A STRING, --album=STRING — set the album name.
  • -b STRING, --album-artist=STRING — set the album artist name. "Various Artists", for example. another example is collaborations: when the track artist might be "Eminem featuring Proof" the album artist would be "Eminem".
  • -t STRING, --title=STRING — set the track title.
  • -n NUM, --track=NUM — set the track number. use 0 to clear.
  • -N NUM, --track-total=NUM — set total number of tracks. use 0 to clear.
  • --track-offset=N — increment/decrement the track number by [-]N. this option is applied after --track=N is set.
  • -d NUM, --disc-num=NUM — set the disc number. use 0 to clear.
  • -G GENRE, --genre=GENRE — set the genre. if the argument is a standard ID3 genre name or number, both will be set. otherwise, any string can be used. use --plugin=genres for a list of standard ID3 genre names/ids.
  • -Y YEAR, --release-year=YEAR — set the year the track was released. use the date options for more precise values or dates other than release.
  • -c STRING, --comment=STRING — set a comment. in ID3 tags this is the comment with an empty description. see --add-comment to add multiple comment frames.
  • --rename=PATTERN — rename file (the extension is not affected) based on data in the tag using substitution variables: $album, $album_artist, $artist, $best_date, $best_date:prefer_recording, $best_date:prefer_recording:year, $best_date:prefer_release, $best_date:prefer_release:year, $best_date:year, $disc:num, $disc:total, $file, $file:ext, $original_release_date, $original_release_date:year, $recording_date, $recording_date:year, $release_date, $release_date:year, $title, $track:num, $track:total.

💿 ID3 options 💿

  • -1, --v1 — only read and write ID3 v1.x tags. by default, v1.x tags are only read or written if there is not a v2 tag in the file.
  • -2, --v2 — only read/write ID3 v2.x tags. this is the default unless the file only contains a v1 tag.
  • --to-v1.1 — convert the file's tag to ID3 v1.1 (or 1.0 if there is no track number).
  • --to-v2.3 — convert the file's tag to ID3 v2.3.
  • --to-v2.4 — convert the file's tag to ID3 v2.4.
  • --release-date=DATE — set the date the track/album was released.
  • --orig-release-date=DATE — set the original date the track/album was released.
  • --recording-date=DATE — set the date the track/album was recorded.
  • --encoding-date=DATE — set the date the file was encoded.
  • --tagging-date=DATE — set the date the file was tagged.
  • --publisher=STRING — set the publisher/label name.
  • --play-count=[+]N — set the number of times played counter. if the argument value begins with + the tag's play count is incremented by N, otherwise the value is set to exactly N.
  • --bpm=N — set the beats per minute value.
  • --unique-file-id=OWNER_ID:ID — add a unique file ID frame. if the ID arg is empty the frame is removed. an OWNER_ID is required. the ID may be no more than 64 bytes.
  • --add-comment=COMMENT[:DESCRIPTION[:LANG]] — add or replace a comment. there may be more than one comment in a tag, as long as the DESCRIPTION and LANG values are unique. the default DESCRIPTION is '' and the default language code is 'eng'.
  • --remove-comment=DESCRIPTION[:LANG] — remove comment matching DESCRIPTION and LANG. the default language code is 'eng'.
  • --remove-all-comments — remove all comments from the tag.
  • --add-lyrics=LYRICS_FILE[:DESCRIPTION[:LANG]] — add or replace a lyrics. there may be more than one set of lyrics in a tag, as long as the DESCRIPTION and LANG values are unique. the default DESCRIPTION is '' and the default language code is 'eng'.
  • --remove-lyrics=DESCRIPTION[:LANG] — remove lyrics matching DESCRIPTION and LANG. the default language code is 'eng'.
  • --remove-all-lyrics — remove all lyrics from the tag.
  • --text-frame=FID:TEXT — set the value of a text frame. to remove the frame, specify an empty value. for example, --text-frame="TDRC:"
  • --user-text-frame=DESC:TEXT — set the value of a user text frame (i.e., TXXX). to remove the frame, specify an empty value. e.g., --user-text-frame="SomeDesc:"
  • --user-url-frame=DESCRIPTION:URL — set the value of a user URL frame (i.e., WXXX). to remove the frame, specify an empty value. e.g., --user-url-frame="SomeDesc:"
  • --add-image=IMG_PATH:TYPE[:DESCRIPTION] — add or replace an image. there may be more than one image in a tag, as long as the DESCRIPTION values are unique. the default DESCRIPTION is ''. if PATH begins with http[s]:// then it is interpreted as a URL instead of a file containing image data. the TYPE must be one of the following: OTHER, ICON, OTHER_ICON, FRONT_COVER, BACK_COVER, LEAFLET, MEDIA, LEAD_ARTIST, ARTIST, CONDUCTOR, BAND, COMPOSER, LYRICIST, RECORDING_LOCATION, DURING_RECORDING, DURING_PERFORMANCE, VIDEO, BRIGHT_COLORED_FISH, ILLUSTRATION, BAND_LOGO, PUBLISHER_LOGO.
  • --remove-image=DESCRIPTION — remove image matching DESCRIPTION.
  • --remove-all-images — remove all images from the tag.
  • --write-images=DIR — causes all attached images (APIC frames) to be written to the specified directory.
  • --add-object=OBJ_PATH:MIME-TYPE[:DESCRIPTION[:FILENAME]] — add or replace an object. there may be more than one object in a tag, as long as the DESCRIPTION values are unique. the default DESCRIPTION is ''.
  • --remove-object=DESCRIPTION — remove object matching DESCRIPTION.
  • --remove-all-objects — remove all objects from the tag.
  • --add-popularity=EMAIL:RATING[:PLAY_COUNT] — adds a popularity metric. there may be multiples popularity values, but each must have a unique email address component. the rating is a number between 0 (worst) and 255 (best). the play count is optional, and defaults to 0, since there is already a dedicated play count frame.
  • --remove-popularity=EMAIL — removes the popularity frame with the specified email key.
  • --remove-v1 — remove ID3 v1.x tag.
  • --remove-v2 — remove ID3 v2.x tag.
  • --remove-all — remove ID3 v1.x and v2.x tags.
  • --remove-frame=FID — remove all frames with the given ID. this option may be specified multiple times.
  • --max-padding=NUM_BYTES — shrink file if tag padding (unused space) exceeds the given number of bytes. (useful e.g. after removal of large cover art.) default is 64 KiB, file will be rewritten with default padding (1 KiB) or max padding, whichever is smaller.
  • --encoding=latin1|utf8|utf16|utf16-be — set the encoding that is used for all text frames. this option is only applied if the tag is updated as the result of an edit option (e.g. --artist, --title, etc.) or --force-update is specified.

🌈 Misc options 🌈

  • --force-update — rewrite the tag despite there being no edit options.
  • --preserve-file-times — when writing, do not update file modification times.

🌈 OTHER PLUGINS 🌈

Okay bestie, so classic is just one plugin — you can run a totally different one any time you want by passing it to --plugin. Here's the whole roster 💖

🎨 art

This plugin is your art-file babysitter 🖼️ It handles art files and tags for albums, artists, etc.

Heads up: --update-files and --update-tags are mutually exclusive. Pick one, babe, you can't have both. 💀
  • --update-files — writes art files out from the images sitting inside your tags.
  • --update-tags — the other direction: writes the tag image from your art files.

🔧 fixup

The glow-up plugin ✨ It runs a bunch of checks and fixes on directories full of audio files.

It works one directory at a time, treating each as a single unit (an album, a compilation, a live set, whatever). All the files in there should share common dates and stuff, though other characteristics are allowed to vary. Use --type whenever you can — lp is the default, just so you know.

The checks that ALWAYS happen no matter what

  1. Every file gets an ID3 tag if it doesn't already have one. No tag left behind 🫶
  2. Set ID3 v2.4.
  3. Set one consistent album name for every file in the directory.
  4. Set one consistent artist name for all the files — unless the type is various, in which case the artist is allowed to vary (but it still has to exist, fr).
  5. Make sure every file has a title.
  6. Make sure every file has a track # and a track total.
  7. Make sure every file has a release date and an original release date — unless the type is live, in which case the recording date gets set instead.
  8. All ID3 frames of these types are removed: USER, PRIV
  9. Every ID3 file gets TLEN (track length in ms) set (or updated).
  10. The album/dir type gets written into the tag. Types lp and various don't get this field set, because the latter is the default and the former can be figured out during sync. In ID3 terms the value lives in TXXX (description: eyeD3#album_type).
  11. Files get renamed like this:
    • Type various: ${track:num} - ${artist} - ${title}
    • Type single: ${artist} - ${title}
    • All other types: ${artist} - ${track:num} - ${title}
    • You can supply your own rename template with --file-rename-pattern
  12. Directories get renamed like this:
    • Type live: ${best_date:prefer_recording} - ${album}
    • All other types: ${best_date:prefer_release} - ${album}
    • You can supply your own rename template with --dir-rename-pattern

Album types 👑

  • lp — a traditional "album" of songs from a single artist. No extra info gets written to the tag since this is the default.
  • ep — a short collection of songs from a single artist. The string "ep" is written to the tag's eyeD3#album_type field.
  • various — a collection of songs from different artists. The string "various" is written to the tag's eyeD3#album_type field.
  • live — a collection of live recordings from a single artist. The string "live" is written to the tag's eyeD3#album_type field.
  • compilation — a collection of songs from various recordings by a single artist. The string "compilation'" is written to the tag's eyeD3#album_type field. Compilation dates, unlike other types, may differ.
  • demo — a demo recording by a single artist. The string "demo" is written to the tag's eyeD3#album_type field.
  • single — a track that should not be associated with an album (even if it has album metadata). The string "single" is written to the tag's eyeD3#album_type field.

fixup's options

  • -t TYPE, --type TYPE — one of the album types. How to treat each directory. The default is "lp", though you might get prompted for a different choice if your files look like something else.
  • --fix-case — fixes the casing on each string field by capitalizing every word.
  • -n, --dry-run — only prints the operations that would happen; doesn't actually do any of them. Perfect for a vibe check first 🧚
  • --no-prompt — bails out if it gets prompted.
  • --dotted-dates — separates the date with . instead of - when naming directories.
  • --file-rename-pattern FILE_RENAME_PATTERN — renames the file (the extension isn't affected) based on the data in the tag, using substitution variables: $album, $album_artist, $artist, $best_date, $best_date:prefer_recording, $best_date:prefer_recording:year, $best_date:prefer_release, $best_date:prefer_release:year, $best_date:year, $disc:num, $disc:total, $file, $file:ext, $original_release_date, $original_release_date:year, $recording_date, $recording_date:year, $release_date, $release_date:year, $title, $track:num, $track:total
  • --dir-rename-pattern DIR_RENAME_PATTERN — renames the directory based on the data in the tag, using substitution variables. The available substitutions are the same ones as in --file-rename-pattern

🎵 genres

Displays the entire list of standard ID3 genres.

ID3 v1 defined a list of genres and mapped them to numeric values so each one could be stored as a single byte. It's recommended that you use these genres — although most newer software (eyeD3 included, bestie) genuinely does not care. 🙈

🍎 itunes-podcast

Adds (or removes) the tags Apple iTunes needs to recognize a file as a podcast.

  • --add — adds the podcast frames.
  • --remove — removes the podcast frames.

🦴 lameinfo

Outputs the lame header (if there is one) for a file. The lame (or xing) header carries extra info about the mp3 that's useful to players and encoders, even though it's not officially part of the mp3 spec. Variable bit rate mp3s, for example, use this header. Iconic, honestly.

For more details see <http://gabriel.mp3-tech.org/mp3infotag.html>.

xing is an alias for this plugin, iykyk.

📄 nfo

Creates NFO files for each directory scanned. Every directory scanned is treated as an album, and an NFO (<http://en.wikipedia.org/wiki/.nfo>) file is written to standard out.

NFO files are often found in music archives. 🌸

📊 stats

Computes statistics for all audio files scanned.

  • --verbose — shows details for each file that has rule violations.

💬 xep-118

Outputs all tags in XEP-118 XML format.

See: <http://xmpp.org/extensions/xep-0118.html>

⚙️ CONFIGURATION FILE ⚙️

You can read your command line options straight out of a configuration file by using the -C/--config option. It wants a path to an Ini (<http://docs.python.org/2/library/configparser.html>) file containing sections with option values. Wanna see a sample config file? Peep /usr/share/doc/eyeD3/examples/config.ini.

And listen: if the file ${HOME}/.eyeD3/config.ini exists, it gets loaded every single time eyeD3 runs and its values take effect. 😳 You can turn that off with --no-config.

👀 SEE ALSO 👀

<http://eyed3.nicfit.net/>

✍️ AUTHOR ✍️

eyeD3 was written by Travis Shirk <travis@pobox.com>.

And that's the whole page, bestie, you made it to the end 🎀 This was eyeD3 0.7.9, dated Sept. 12, 2016, living in section EYED3(1) of the manual — go forth and tag your mp3s like the main character you are 💅💖✨

📦 where this page comes from