Changelogs » Eyed3

PyUp Safety actively tracks 266,777 Python packages for vulnerabilities and notifies you when to upgrade.



  - `eyeD3 --genre ""` to clear genre frame restored.
  - Genre id->name mapping for non-standard genres and custom maps.


  - Relative volume adjustments (RVA2 and RVAD) (399)
  - Tag properties copyright and encoded_by
  - Support GRP1 (Apple) frames.
  - Genre serialization not ID3 v2.3 format by default, and other genre cleanup (402)
  fixes 382
  - Date correctness between ID3 versions (396)
  - PopularityFrame email encoding bug.
  - Plugins more featured in docs


  - Track/disc numbers can be set with integer strings.
  - Disc number getter and setter hooks


  - Removed setting of PYTHONIOENCODING, it breaks MacOS.
  Fixes 388


  - Docs and pep8.
  - Experiment with setting utf-8 writer for stdout and stderr.


  Major Changes
  - Dropped support for Python versions 2.7, 3.4, and 3.5.
  - File scanning is no longer recursive by default; use `-r / --recursive`.
  - Default log-level changed from WARNING to ERROR.
  - Mime-type detection uses (libmagic no longer required)
  - setFileScannerOpts function accepts `default_recursive` option.
  - A new `jsontag` plugin for converting tags to JSON.
  - A new `extract` plugin for extracting tags from media.
  - A new `yamltag` plugin for converting tags to YAML.
  - A new `mimetypes` plugin for listing file mime-types / measuring performance
  - Original artist support (TOPE frame, --orig-artist)
  - Added support for Python 3.8 and pypy3.
  - Log warning when ID3 v1.x text truncation occurs. Fixes 299.
  - Accept (invalid) date strings for the form YYYYMMDD. Fixes 379
  - Adjust replay gain correctly for lame >= 3.95.1 headers.
  - Added -r/--recursive argument. eyeD3 is no longer recursive by default (378)
  - Regenerated grako parser.
  - New ValueError for _setNum when unknown type/values are passed.
  - Moved src/* to top-level repo directory.
  - PRIV data type checking, fixed examples, etc.
  - Use tox for `make test`
  - ID3 v2.3 to v2.4 date conversion.
  - Match mp3 mime-types against all possible mime-types.
  Specifically, application/x-font-gdos. Fixes 338
  - Fix simple typo: titel -> title. <>
  - Fixed: load the right config file in arguments. <>
  - Fix issue tracker link. Fixes 333.
  - Fixed art plugin when `pylast` is not installed.
  - Unbound variable for track num/total.  Fixes 327.
  - Fixed MP3 header search to not false match on BOMs.
  - Honor APIC text encoding when description is "".  200.
  - Fixed bug with improper types when re-rendering unique file ID. (324)
  - UFID fixes, update (325) <>
  - Deprecation of eyed3.utils.guessMimeType
  - Removed ipdb from dev requirements


  - Accept (invalid) date strings for the form YYYYMMDD. Fixes 379
  - Test with py38


  - ID3 v2.3 to v2.4 date conversion.
  - Match mp3 mime-types against all possible mime-types.
  Specifically, application/x-font-gdos. Fixes 338


  - Log warning when ID3 v1.x text truncation occurs. Fixes 299.
  - Honor APIC text encoding when description is "".  200.
  - Fixed bug with improper types when re-rendering unique file ID. (324)
  v0.8.9 (2019-01-12) : Descent Into...
  - Fixup plugin: -t changed to --type.
  - Pin pathlib to latest version 1.0.1 (304) <>
  - Force no-color output when stdout is not a terminal (297)
  - Requirements.txt: pathlib is only needed for older python versions
  (284) <>
  - Art plugin: Pin pylast to 2.x to preserve Python2 support.


  - Follow symlink directories. Fixes 224
  - Eyed3.core.AudioInfo `time_secs` is now a float and non-lossy. Fixes 210
  - Removed Python 3.3 support.
  - Better type handling during TLEN [fixup plugin].
  - Don't tweak logging by default, only thru `main`. Fixes 243
  - Added a separate example for Windows (--add-image <url>) [Addresses
  the issue 219] (220) <>


  - Only use os.fwalk where supported.


  - Art plugin can now download album covers from
  - Use os.fwalk for its better performance (esp. >= py37) Fixes 166
  - TagTemplate `path_friendly` is now a string, namely the delimiter to use.
  - Classic plugin: --write-image will work with --quiet. Fixes 188
  - Multiple fixes for display plugin %images% replacements. Fixes 176
  - Allow --remove-* options to work when there are no tags. Fixes 183


  - Mp3AudioFile.initTag now returns the new tag.
  - Eyed3.core.EP_MAX_SIZE_HINT.
  - Added docs for install devel dependencies and test data.
  - Similarly to TextFrame, fallback to latin1 for invalid encodings.
  - Removed paver as a dep.
  - Removed fabfile and mkenv.
  - Clean pytest_cache.
  - cc update.
  - Handle missing `fcntl` on Windows. Fixes 135.
  - In addition to None, "" will now clear dates.
  - Update index.rst to reflect the code is in a Git repo, not Mercurial (164)
  - Update pytest from 3.2.2 to 3.5.0 (175) <>
  - Update twine from 1.9.1 to 1.11.0 (173) <>
  - Update sphinx from 1.6.5 to 1.7.2 (174) <>
  - Update sphinxcontrib-paverutils from 1.16.0 to 1.17.0 (172) <github->
  - Update pytest-runner from 3.0 to 4.2 (171) <>
  - Update from 0.7 to 0.8 (161) <>
  - Update ipdb from 0.10.3 to 0.11 (159) <>
  - Update factory-boy from 2.9.2 to 2.10.0 (150) <>
  - Update pyaml from 17.10.0 to 17.12.1 (138) <>
  - Update python-magic to 0.4.15 (130) <>
  - Update pip-tools from 1.10.1 to 1.11.0 (129) <>
  - Update check-manifest from 0.35 to 0.36 (125) <>


  - Composer (TCOM) support (123)
  - Check for version incompatibilities during version changes.
  - More forgiving of invalid text encoding identifiers (fixes 101)
  - More forgiving of bad Unicode in text frames (fixes 105)
  - EyeD3 cmd line helper turned not session-scoped fixture.
  - Only warn about missing grako when the plugin is used. Fixes 115.
  - Fix python3 setup when system encoding is not utf-8 (120)
  - Fix bad frames detection in stats plugin for python3 (113)
  - Script exits with 0 status when called with --version/--help (109)
  - Help pymagic with poorly encoded filenames.
  - [display plugin] Handle comments.
  - [display plugin] Handle internal exception types. Fixes 118.
  - IOError (nor OSError) have a message attr.
  - Set theme jekyll-theme-slate.
  - Update pytest to 3.2.5 (122) <>
  - Update pytest-runner to 3.0 (108) <>
  - Update sphinx to 1.6.5 (106) <>
  - Update flake8 to 3.5.0 (107) <>


  - Reload and process after tag removals, fixes 102. (PR 103)
  - Display incorrectly encoded strings (usually filenames)
  - Make the classic output span the actual width of the tty so you can
  see the actual path with a long file name. (92) <>


  - Pypy and pypy3 support.
  - 'nose' is no longer used/required for testing.
  - Fix for Unicode paths when using Python2.  Fixes 56.


  - ``make pkg-test-data`` target.
  - Sample mime-type tests.
  - Added ``python-magic`` as a dependency for reliable mime-type detection.
  Fixes 61
  - Add pathlib to requirements. Fixes 43.
  - [doc] Fixed github URL.


  .. warning::
  This release is **NOT** API compatible with 0.7.x. The majority
  of the command line interface has been preserved although many options
  have either changed or been removed.  Additionally, support for Python 2.6
  has been dropped.
  - Python 3 support (version 2.7 and >= 3.3 supported)
  - The Display plugin (-P/--plugin display) enables complete control over tag
  output. Requires ``grako``. If using pip, ``pip install eyeD3[display]``.
  Contributed by Sebastian Patschorke.
  - Genre.parse(id3_std=False) (and --non-std-genres) to disable genre
  - eyed3.load accept pathlib.Path arguments.
  - eyed3.core.AudioFile accept pathlib.Path arguments.
  - eyed3.utils.walk accept pathlib.Path arguments.
  - New manual page. Contributed by Gaetano Guerriero
  - ``make test-data``
  - Project home from to GitHub:
  - Lang fixes, and no longer coerce invalids to eng.
  - Moved to pytest, although unittest not yet purged.


  New Features:
  * Repo and issue tracker moved to GitHub:
  Bug Fixes:
  * 'NoneType' object has no attribute 'year'
  * Multiple date related fixes.
  * Allow superfluous --no-tagging-ttme-frame option for backward
  * The --version option now prints a short, version-only, message.
  * Allow --year option for backward compatibility.
  Converts to --release-year.
  * Fixes for --user-text-frame with multiple colons and similar fixes.
  * ID3 v1.1 encoding fixes.
  .. _release-0.7.10:


  Bug Fixes:
  * Missing import
  * Fix the rendering of default constructed id3.TagHeader
  * Fixed Tag.frameiter


  New Features:
  * process files and directories in a sorted fashion. <Hans-Peter Jansen>
  * display the ellipsis file name and path, and the file size right justified
  in printHeader. <Hans-Peter Jansen>
  * stating to be unable to find a valid mp3 frame without a hint, where this
  happened is rather unfortunate. I noticed this from using eyed3.load()
  calls. <Hans-Peter Jansen>
  * [fixup plugin] - Better compilation support.
  Bug Fixes:
  * Fixed missing 'math' import.
  * Replaced invalid Unicode.
  * Disabled ANSI codes on Windows
  * More friendly logging (as a module)


  New Features:
  * [pymod plugin] -- A more procedural plugin interface with modules.
  * [art plugin] -- Extract tag art to image files, or add images to tags.
  * - High level tag art API
  * eyed3.id3.frames.ImageFrame.makeFileName produces the file extension
  .jpg instead of .jpeg for JPEG mime-types.
  * Added eyed3.utils.makeUniqueFileName for better reuse.
  * [statistics plugin] -- Less score deduction for lower bit rates.
  * Split example plugins module into discrete plugin modules.
  * [fixup plugin] -- Added --fix-case for applying ``title()`` to names
  * [fixup plugin] -- Detects and optionally removes files determined to be
  * eyed3.id3.Tag -- Added ``frameiter`` method for iterating over tag
  * Added optional ``preserve_file_time`` argument to eyed3.id3.Tag.remove.
  * Removed python-magic dependency, it not longer offers any value (AFAICT).
  Bug Fixes:
  * ashing on --remove-frame PRIV
  * rse lameinfo even if crc16 is not correct
  * po in docs/installation.rst
  * Request to update the GPL License in source files
  * Fixes to eyed3.id3.tag.TagTemplate when expanding empty dates.
  * eyed3.plugins.Plugin.handleDone return code is not actually used.
  * [classic plugin] -- Fixed ID3v1 --verbose bug.
  * [fixup plugin] -- Better date handling, album type, and many bug fixes.


  New Features:
  * Support for album artist info.
  By Cyril Roelandt <>
  * [fixup plugin] -- Custom patterns for file/directory renaming.
  By Matt Black <>
  * API providing simple prompts for plugins to use.
  * API and TXXX frame mappings for album type (e.g. various, album, demo,
  etc.) and artist origin (i.e. where the artist/band is from).
  * Lower cases ANSI codes and other console fixes.
  * Added the ability to set (remove) tag padding. See
  `eyeD3 --max-padding` option. By Hans Meine.
  * Tag class contains read_only attribute than can be set to ``True`` to
  disable the ``save`` method.
  * [classic plugin] -- Added ``--track-offset`` for incrementing/decrementing
  the track number.
  * [fixup plugin] -- Check for and fix cover art files.
  Bug Fixes:
  * Build from pypi when ``paver`` is not available.
  * Disable ANSI color codes when TERM == "dumb"
  * Locking around libmagic.
  * Work around for zero-padded utf16 strings.
  * Safer tempfile usage.
  * Better default v1.x genre.


  Bug fixes:
  * Allow to run with having ``paver`` installed.
  * [statistics plugin] Don't crash when 0 files are processed.


  New Features:
  * Python 2.6 is now supported if ``argparse`` and ``ordereddict``
  dependencies are installed. Thanks to Bouke Versteegh for much of this.
  * More support and bug fixes for `ID3 chapters and table-of-contents`_.
  * [classic plugin] ``-d/-D`` options for setting tag
  disc number and disc set total.
  * Frames are always written in sorted order, so if a tag is rewritten
  with no values changed the file's checksum remains the same.
  * Documentation and examples are now included in source distribution.
  * [classic plugin] Removed ``-p`` for setting publisher since using it
  when ``-P`` is intended is destructive.
  * [classic plugin] Supports ``--no-color`` to disable color output. Note,
  this happens automatically if the output streams is not a TTY.
  * ```` supports preserving the file modification time; and option
  added to classic plugin.
  * [statistics plgin] Added rules for "lint-like" checking of a collection.
  The rules are not yet configurable.
  * ERROR is now the default log level.
  Bug fixes:
  * Various fixes for PRIV frames, error handling, etc. from Bouke Versteegh
  * Convert '/' to '-' in TagTemplate names (i.e. --rename)
  * Drop TSIZ frames when converting to ID3 v2.4
  * ID3 tag padding size now set correctly.
  * Fixes for Unicode paths.
  * License clarification in pkg-info.
  * The ``-b`` argument is now properly supported.
  * Magic module `hasattr` fix.
  * More robust handling of bogus play count values.
  * More robust handling of bogus date values.
  * Proper unicode handling of APIC descriptions.
  * Proper use of argparse.ArgumentTypeError
  * Allow TCMP frames when parsing.
  * Accept more invalid frame types (iTunes)
  * Documentation fixes.
  * Fix for bash completion script.
  * Fix for certain mp3 bit rate and play time computations.
  .. _ID3 chapters and table-of-contents:


  New Features:
  * Support for `ID3 chapters and table-of-contents`_ frames
  (i.e.CHAP and CTOC).
  * A new plugin for toggling the state of iTunes podcast
  files. In other words, PCST and WFED support. Additionally, the Apple
  "extensions" frames TKWD, TDES, and TGID are supported.
  Run ``eyeD3 -P itunes-podcast --help`` for more info.
  * Native frame type for POPM (Popularity meter).
  See the :func:`eyed3.id3.tag.Tag.popularities` accessor method.
  * Plugins can deal with traversed directories instead of only file-by-file.
  Also, :class:`eyed3.plugins.LoaderPlugin` can optionally cache the
  loaded audio file objects for each callback to ``handleDirectory``.
  * [classic plugin] New --remove-frame option.
  * [statistics plugin] More accurate values and easier to extend.
  Bug fixes:
  * Fixed a very old bug where certain values of 0 would be written to
  the tag as '' instead of '\x00'.
  * Don't crash on malformed (invalid) UFID frames.
  * Handle timestamps that are terminated with 'Z' to show the time is UTC.
  * Conversions between ID3 v2.3 and v2.4 date frames fixed.
  * [classic plugin] Use the system text encoding (locale) when converting
  lyrics files to Unicode.


  .. warning::
  This release is **NOT** API compatible with 0.6.x. The majority
  of the command line interface has been preserved although many options
  have either changed or been removed.
  New Features:
  * Command line script ``eyeD3`` now supports plugins. The default plugin
  is the classic interface for tag reading and editing.
  * Plugins for writing NFO files, displaying lame/xing headers, jabber tunes,
  and library statistics.
  * Module name is now ``eyed3`` (all lower case) to be more standards
  * New ``eyed3.id3.Tag`` interface based on properties.
  * Improved ID3 date frame support and 2.3<->2.4 conversion, and better
  conversions, in general.
  * Native support for many more ID3 frame types.
  * Python Package Index friendly, and installable with 'pip'.
  * Improved mime-type detection.
  * Improved unicode support.
  * Support for config files to contain common options for the command-line


  New features:
  * Support for disc number frames (TPOS).
  Thanks to Nathaniel Clark <>
  * Added %Y (year) and %G (genre) substitution variables for file renames.
  Thanks to Otávio Pontes <>
  * Improved XML (--jep-118) escaping and a new option (--rfc822) to output
  in RFC 822 format. Thanks to Neil Schemenauer <>
  * --rename will NOT clobber existing files.
  * New option --itunes to write only iTunes accepted genres.
  Thanks to Ben Isaacs <Ben XO>
  * If available the 'magic' module will be used to determine mimetypes when
  the filename is not enough. Thanks to Ville Skyttä <>
  * --set-encoding can be used along with a version conversion arg to apply
  a new encoding to the new tag.
  * Increased performance for mp3 header search when malformed GEOB frames
  are encountered. Thanks to Stephen Fairchild <>
  * Less crashing when invalid user text frames are encountered.
  * Less crashing when invalid BPM values (empty/non-numeric) are encountered.


  Bug fixes:
  * Workaround invalid utf16
  * Show all genres during --list-genres
  * Workaround invalid PLCT frames.
  * Show all tracks during --nfo output.
  New features:
  * Support for URL frames (W??? and WXXX)
  * Program exit code for the 'eyeD3' command line tool


  Bug fixes:
  * Typo fix of sysnc/unsync data. Thanks to Gergan Penkov <>
  * Infinite loop fix when dealing with malformed APIC frames.
  * Tag.removeUserTextFrame helper.
  Thanks to David Grant <>


  Bug fixes:
  * ID3 v1 comment encoding (latin1) bug fix
  (Renaud Saint-Gratien <>)
  * APIC picture type fix (Michael Schout <>)
  * Fixed console Unicode encoding for display.
  * Fixed frame de-unsnychronization bugs.
  * Round float BPMs to int (per the spec)


  Bugs fixes:
  - Fixed a nasty corruption of the first mp3 header when writing to files
  that do not already contain a tag.
  - Fixed a bug that would duplicate TYER frames when setting new values.
  - Fixed the reading/validation of some odd (i.e.,rare) mp3 headers
  New Features:
  - Encoding info extracted from Lame mp3 headers [Todd Zullinger]
  - Genre names will now support '|' to allow for genres like
  "Rock|Punk|Pop-Punk" and '!' for "Oi!"


  - Numerous write fixes, especially for v2.4 tags.
  Thanks to Alexander Thomas <> for finding these.
  - Add --no-zero-padding option to allow disabling of zero padding track
  - Add --nfo option to output NFO format files about music directories.
  - Time computation fixes when MP3 frames headers were mistakingly found.


  - Handle Mac style line ending in lyrics and display with the proper output
  encoding. [Todd Zullinger]
  - TDTG support and other date frame fixes. [Todd Zullinger]
  - Output encoding bug fixes. [Todd Zullinger]


  - Support for GEOB (General encapsulated object) frames from
  Aaron VonderHaar <>
  - Decreased memory consumption during tag rewrites/removals.
  - Allow the "reserved" mpeg version bits when not in strict mode.
  - Solaris packages available via Blastwave -


  - Unsynchronized lyrics (USLT) frame support [Todd Zullinger <>]
  - UTF16 bug fixes
  - More forgiving of invalid User URL frames (WXXX)
  - RPM spec file fixes [Knight Walker <>]
  - More details in --verbose display


  - eyeD3 (the CLI) processes directories more efficiently
  - A specific file system encoding can be specified for file renaming,
  see --fs-encoding (Andrew de Quincey)
  - Faster mp3 header search for empty and/or corrupt mp3 files
  - Extended header fixes
  - Bug fix for saving files with no current tag
  - What would a release be without unicode fixes, this time it's unicode
  filename output and JEP 0118 output.


  - Frame header size bug.  A _serious_ bug since writes MAY be
  affected (note: I've had no problems reported so far).


  - Beats per minute (TPBM) interface
  - Publisher/label (TPUB) interface
  - When not in strict mode exceptions for invalid tags are quelled more often
  - Support for iTunes ID3 spec violations regarding multiple APIC frames
  - Bug fix where lang in CommentFrame was unicode where it MUST be ascii
  - Bug fixed for v2.2 frame header sizes
  - Bug fixed for v2.2 PIC frames
  - File rename bug fixes
  - Added -c option as an alias for --comment
  - -i/--write-images now takes a destination path arg.  Due to optparse
  non-support for optional arguments the path MUST be specified.  This option
  no longer clobbers existing files.


  - APIC frames can now be removed.
  - An interface for TBPM (beats per minute) frames.
  - Utf-16 bug fixes and better unicode display/output
  - RPM spec file fixes


  - Read-only support for ID3 v2.2
  - TPOS frame support (disc number in set).
  - Bug fixes


  - Native support for play count (PCNT), and unique file id (UFID) frames.
  - More relaxed genre processing.
  - Sync-safe bug fixed when the tag header requests sync-safety and not the
  frames themselves.
  - configure should successfly detect python release candidates and betas.


  - Much better unicode support when writing to the tag.
  - Added Tag.setEncoding (--set-encoding) and --force-update
  - Handle MP3 frames that violate spec when in non-strict mode.
  (Henning Kiel <>)
  - Fix for Debian bug report 270964
  - Various bug fixes.


  - TagFile.rename and Tag.tagToString (eyeD3 --rename=PATTERN).
  The latter supports substitution of tag values:
  %A is artist, %t is title, %a is album, %n is track number, and
  %N is track total.
  - eyeD3 man page.
  - User text frame (TXXX) API and --set-user-text-frame.
  - Python 2.2/Optik compatibility works now.
  - ebuild for Gentoo (


  - Unicode support - UTF-8, UTF-16, and UTF-16BE
  - Adding images (APIC frames) is supported (--add-image, Tag.addImage(), etc.)
  - Added a --relaxed option to be much more forgiving about tags that violate
  the spec.  Quite useful for removing such tags.
  - Added Tag.setTextFrame (--set-text-frame=FID:TEXT)
  - Added --remove-comments.
  - Now requires Python 2.3. Sorry, but I like cutting-edge python features.
  - Better handling and conversion (2.3 <=> 2.4) of the multiple date frames.
  - Output format per JEP 0118: User Tune, excluding xsd:duration format for
  <length/> (
  - Lot's of bug fixes.
  - Added a mailing list.  Subscribe by sending a message to


  - Temporary files created during ID3 saving are now properly cleaned up.
  - Fixed a "bug" when date frames are present but contain empty strings.
  - Added a --no-color option to the eyeD3 driver.
  - Workaround invalid tag sizes by implyied padding.
  - Updated README


  - ID3 v2.x saving.
  - The eyeD3 driver/sample program is much more complete, allowing for most
  common tag operations such as tag display, editing, removal, etc.
  Optik is required to use this program.  See the README.
  - Complete access to all artist and title frames (i.e. TPE* and TIT*)
  - Full v2.4 date support (i.e. TDRC).
  - Case insensitive genres and compression fixes. (Gary Shao)
  - ExtendedHeader support, including CRC checksums.
  - Frame groups now supported.
  - Syncsafe integer conversion bug fixes.
  - Bug fixes related to data length indicator bytes.
  - Genre and lot's of other bug fixes.


  - Added the ability to save tags in ID v1.x format, including when the
  linked file was IDv2.  Original backups are created by default for the
  time being...
  - Added deleting of v1 and v2 frames from the file.
  - Zlib frame data decompression is now working.
  - bin/eyeD3 now displays user text frames, mp3 copyright and originality,
  URLs, all comments, and images. Using the --write-images arg will
  write each APIC image data to disk.
  - Added eyeD3.isMp3File(),  Tag.clear(), Tag.getImages(), Tag.getURLs(),
  Tag.getCDID(), FrameSet.removeFrame(),, ImageFrame.writeFile(),
  - Modified bin/eyeD3 to grok non Mp3 files.  This allows testing with
  files containing only tag data and lays some groundwork for future
  OGG support.
  - Fixed ImageFrame mime type problem.
  - Fixed picture type scoping problems.


  - RPM packages added.
  - Fixed a bug related to ID3 v1.1 track numbers. (Aubin Paul)
  - Mp3AudioFile matchs ``*.mp3`` and ``*.MP3``. (Aubin Paul)


  - Added a higher level class called Mp3AudioFile.
  - MP3 frame (including Xing) decoding for obtaining bit rate, play time,
  - Added APIC frame support (eyeD3.frames.Image).
  - BUG FIX: Tag unsynchronization and deunsynchronization now works
  correctly and is ID3 v2.4 compliant.
  - Tags can be linked with file names or file objects.
  - More tag structure abstractions (TagHeader, Frame, FrameSet, etc.).
  - BUG FIX: GenreExceptions were not being caught in eyeD3 driver.


  - ID3_Tag was renamed to Tag.
  - Added Genre and GenreMap (eyeD3.genres is defined as the latter type)
  - Added support of ID3 v1 and v2 comments.
  - The ID3v2Frame file was renamed ID3v2 and refactoring work has started
  with the addition of TagHeader.


  - Initial release.