rmlyrics3

A Lyrics3 tag remover for MP3 files, written in Python.

Before ID3v2 came around, Lyrics3 and Lyrics3v2 had their uses (extending the 30-char limit, placing synced lyrics), but nowadays they are a nuisance for most of us. Plus, we have the lyrics frames USLT and SYLT in ID3v2.

Lyrics3 tags come between the audio data and an ID3v1/ID3v1.1 tag at the end of the file (sometimes without the following ID3v1 tag, even if that is mandatory according to Lyrics3 specs). Current ffmpeg and some players and tools still have bugs and try to interpret Lyrics3 tags as audio data, resulting in obscure errors. (See Moonbase59/loudgain#11 or https://trac.ffmpeg.org/ticket/7879.)

Unfortunately, there are almost no tools out there to remove Lyrics3 tags—most programs ignore them, but write them back if changing tags. When removing ID3v1 tags from a file, this can result in the illegal situation mentioned above (having a Lyrics3 tag without a following ID3v1 tag).

rmlyrics3 can remove Lyrics3 and Lyrics3v2 tags from MP3 files, even when there is no ID3v1 tag following.

This code has been tested with thousands of files but I can give no guarantees. If you destroy your whole music collection, it’s not my fault. Please have a backup!

Installation

Install on OSes that have Python installed

Just copy rmlyrics3 to a suitable location (i.e., ~/bin or /usr/local/bin) and make it executable (chmod +x rmlyrics3).

All other files are not needed for normal operation. These are mainly building and unit testing scripts.

Install on Windows with no Python installed

There is a Windows 32-bit executable rmlyrics3.exe in the dist/ folder which you can copy to a suitable location. It should run on Windows 7 and above.

The prebuilt Windows executable is meant to be used on systems with no Python installed. It brings its own Python interpreter and needed dependencies. Thus, it’s a little larger and takes a little longer to start than the pure Python version.

Rebuilding the Windows executable

Should you need to rebuild rmlyrics3.exe yourself, get PyInstaller, change to the directory into which you have git cloned rmlyrics3 and do a:

pyinstaller rmlyrics3.spec

Usage

This is also what you get when you type rmlyrics3 -h or rmlyrics3 --help:

usage: rmlyrics3 [-h] [-v] [-r] [-s] [-d] path [path ...]

Remove Lyrics3 tags from MP3 files.

positional arguments:
  path                  Path of a file or a folder of files.

optional arguments:
  -h, --help            show this help message and exit
  -v, --version         show program's version number and exit
  -r, --recursive       search through subfolders (default: False)
  -s, --stats           show statistics (default: False)
  -d, --dry-run, --dryrun
                        dry run; files not changed (default: False)

Please report any issues to https://github.com/Moonbase59/rmlyrics3/issues.

Examples

Remove Lyrics3 tag from a single file:

rmlyrics3 test.mp3

Remove Lyrics3 tags from a collection of files:

rmlyrics3 test1.mp3 test2.mp3 test3.mp3

Remove Lyrics3 tags from all MP3 files in a folder:

rmlyrics3 *.mp3

Remove Lyrics3 tags from all MP3 files in a folder and all its subfolders (recursively):

rmlyrics3 -r ~/Music/MyMP3/

For a dry run (without actually changing files), use the --dry-run (-d) switch:

rmlyrics3 --dry-run -r ~/Music/MyMP3/

Perform a dry-run (-d) and show some statistics (-s):

rmlyrics3 -d -s -r ~/Music/MyMP3/

The statistics will display how many files were checked, how many were (or will have to be) modified, and how many are corrupt, something like this:

147231 files checked, 1492 files to modify, 3 files are corrupt.

147231 files checked, 1492 files modified, 3 files are corrupt.

Technical

rmlyrics3 tries to segment the MP3 file into blocks. It knows about the following block types:

ID3v1, ID3v1.1, ID3v2.2, ID3v2.3, ID3v2.4, APEv1, APEv2, Lyrics3, Lyrics3v2, and audio data.

For safety reasons, rmlyrics3 proceeds as follows:

If more than one file is to be processed, build a list of file paths and names and sort them alphabetically. This makes it easier to search for a specific file in the output.
Read the original file (say, test.mp3), determine its structure and possibly show an error if the file is corrupt.
Determine if the file contains a Lyrics3 or Lyrics3v2 tag and skip the following steps if not so.
Rebuild a new copy of the file in the same folder, adding a .tmp extension (test.mp3 → test.mp3.tmp).
Display the path and file name and blocks found:
```
rmlyrics3 test.mp3
/home/user/Music/Test/test.mp3 ... (ID3v2, Audio, APEv2, Lyrics3v2, ID3v1)
```
You can easily see that this file contains an ID3v2 tag at the beginning, followed by the audio data, followed by an APEv2 tag, followed by a Lyrics3v2 tag, and ending with an ID3v1 tag. (After removal of the Lyrics3v2 tag, the sequence will be: ID3v2, audio data, APEv2, ID3v1.)

rmlyrics3 will only show files that are changed. This is an extra piece of safety since you can redirect its output to a file and later check if problems should arise:
```
rmlyrics3 test.mp3 > changed-files.txt
```
Finally, rmlyrics removes the original file (test.mp3) and renames the newly-built copy to the original’s name (test.mp3.tmp → test.mp3).
Proceed with next file, if any.

It could be argued to truncate the original file instead and rewrite part(s) of it, but this is not always a safe procedure (and truncate not being supported on all OSes), so I opted for the above strategy.

Should you get warning or error messages in the process, your file is most probably defective and has unexpected junk data inside. There are many more bad MP3 files out there than you might suspect. I strongly advise to delete such bad files or try to repair them using MP3 Diags, if you know what you’re doing.

Best of luck cleaning out your music files!

Moonbase59 / rmlyrics3