The purpose of the mp3repair project is to repair the metadata contained in mp3 sound files in Windows.
The mp3repair program supports the following commands:
The about command provides information about the mp3repair program, including:
- The program version
- The build timestamp
- Copyright information
- The version of go used to compile the code
- A list of dependencies and their versions
The check command provides a means to run various checks on the mp3 files and their directories, governed by these command arguments:
| Argument Name | Value | Default Value | Description |
|---|---|---|---|
| -empty | Boolean | false | Check for empty artist and album directories |
| -gaps | Boolean | false | Check for gaps in the numbered mp3 files in an album directory |
| -integrity | Boolean | true | Check for discrepancies between the tag frames in the mp3 files |
If true, mp3repair ignores the -albumFilter and -artistFilter settings. An artist directory is any subdirectory of the -topDir directory, and mp3repair considers it to be empty if it contains no subdirectories. An album directory is any subdirectory of an artist directory and mp3repair considers it empty if it contains no mp3 files.
mp3repair assumes that the mp3 files on an album are numbered as tracks, starting with 1 and ending with N where N is the number of mp3 files in the directory. If any mp3 files have an associated track number outside the range of 1..N, mp3repair lists them in the output, as well as any track numbers in the expected range that are not associated with any mp3 files in the directory.
mp3repair reads the mp3 metadata for each track file; the -integrity check looks for discrepancies between that data and the files:
- Verify that the track file name begins with the track number encoded in the TRCK (track number/position in set) frame of the ID3V2 tag and the track field of the ID3V1 tag, and that the rest of the track name matches the value encoded in the TIT2 (title/song name/content description) frame of the ID3V2 tag and the song title field of the ID3v1 tag.
- Verify that the containing album directory's name matches the TALB (album/movie/show title) frame of the ID3V2 tag and the album field of the ID3V1 tag, and that all mp3 files on the album use the same album name in their ID3V2 and ID3V1 tags.
- Verify that the containing artist directory's name matches the TPE1 (lead artist/lead performer/soloist/performing group) frame of the ID3V2 tag and the artist field of the ID3V1 tag, and that all mp3 files within an artist directory use the same artist name in their ID3V2 and ID3V1 tags.
- Verify that all the mp3 files on an album contain the same TYER (year) frame of the ID3V2 tag and the year field of the ID3V1 tag.
- Verify that all the mp3 files io an album contain the same TCON (content type, aka genre) frame of the ID3V2 tag and the same genre field of the ID3V1 tag, and that the genres in each tag agree as closely as possible.
- Verify that all the mp3 files on an album contain the same MCDI (music CD identifier) frame of the ID3V2 tag; there is no corresponding data in the ID3V1 tag.
File names and their corresponding frame values cannot always be identical, as some characters in the frame may not be legal file name characters and end up being replaced with, typically, punctuation characters. The matching algorithm takes those differences into account. The following characters are known to be illegal in Windows file names:
- asterisk (*)
- backward slash (\)
- colon (:)
- forward slash (/)
- less than (<)
- greater than (>)
- question mark (?)
- quotation mark (")
- vertical bar (|)
The export command provides a means for exporting data to the file system. It is governed by these command arguments:
Argument Name | Value | Default Value | Description ---------------+---------+---------------+------------- -defaults | Boolean | false | If true, write all command defaults to a file -overwrite | Boolean | false | If true, existing files can be overwritten
If true, mp3repair writes the command defaults to a file named defaults.yaml in the %APPDATA%\mp3repair directory.
The list command provides a means for listing mp3 files. It can list artists, albums, and tracks, governed by these command arguments:
| Argument Name | Value | Default Value | Description |
|---|---|---|---|
| -annotate | Boolean | false | Annotate track and album names |
| -details | Boolean | false | Include details for tracks |
| -diagnostic | Boolean | false | Include diagnostic data for tracks |
| -includeArtists | Boolean | true | List album artists |
| -includeAlbums | Boolean | true | List album names |
| -includeTracks | Boolean | false | List track names |
| -sort | String | numeric | How to sort tracks, if listed |
If true, mp3repair provides the following annotations:
- Album names will include the recording artist if artists are not included (-includeArtists=false)
- Track names will include the album name if albums are not included (-includeAlbums=false), and the recording artist if artists are also not included (-includeArtists=false)
If true, mp3repair provides the following details, if available:
- Composer, which corresponds to the TCOM (Composer) frame of the track's ID3V2 tag.
- Conductor, which corresponds to the TPE3 (Conductor/performer refinement) frame of the track's ID3V2 tag.
- Key, which corresponds to the TKEY (Initial key) frame of the track's ID3V2 tag.
- Lyricist, which corresponds to the TEXT (Lyricist/Text writer) frame of the track's ID3V2 tag.
- Orchestra/Band, which corresponds to the TPE2 (Band/orchestra/accompaniment) frame of the track's ID3V2 tag.
- Subtitle, which corresponds to the TIT3 (Subtitle/Description refinement) frame of the track's ID3V2 tag.
Allowed values are numeric and alpha. If numeric sorting is requested, track and album listing must both be enabled; otherwise, it makes no sense.
If any value other than numeric or alpha is used, mp3repair will replace it with an appropriate value as follows:
- If tracks are not listed (-includeTracks=false), mp3repair ignores the value.
- If tracks and albums are listed (-includeTracks=true and -includeAlbums=true), mp3repair replaces the value with numeric.
- If tracks are listed (-includeTracks=true) but albums are not listed (-includeAlbums=false), mp3repair replaces the value with alpha.
The postRepair command provides a means to quickly delete the backup directories created by the repair command. It has no command arguments.
The repair command provides a means to repair tracks whose MP3 tags do not match the track name, album name, or artist name. It has a single command argument:
| Argument Name | Value | Default Value | Description |
|---|---|---|---|
| -dryRun | Boolean | false | If true, output what the command would repair, but take no action |
The resetDatabase command provides a means to reset the database that the Windows Media Player uses to catalogue the albums, artists, and tracks. The Windows Media Player will not recognize the effects of the repair command until that database is reset.
It takes a non-trivial amount of time for Windows Media Player to recreate its database, so the resetDatabase command will not run unless the repair command has edited at least one mp3 file since the last time the resetDatabase command was run (if ever).
If you need to reset the database (for instance: because you used another program such as WinAmp to edit mp3 file metadata) and the resetDatabase command insists that it doesn't need to do anything, simply create a file named metadata.dirty in the %APPDATA%\mp3repair directory and run the resetDatabase command again.
The resetDatabase command has the following command arguments:
| Argument Name | Value | Default Value | Description |
|---|---|---|---|
| -extension | String | .wmdb | The extension of the files to delete |
| -metadata | String | %USERPROFILE%\AppData\Local\Microsoft\Media Player\ | The directory where the metadata files are found |
| -service | String | WMPNetworkSVC | The name of the media player sharing service, which, if running, needs to be stopped before deleting the metadata files |
| -timeout | Numeric | 10 | The time, in seconds, in which the command will attempt to stop the media player sharing service before giving up |
The minimum value is 1 and the maximum value is 60. Values below 1 are replaced with 1 and values above 60 are replaced with 60.
The commands take a variety of command arguments. These arguments may be string-valued, numeric-valued, or boolean-valued (true/false). Many of the command arguments are command-specific and are described with the commands above.
These command arguments are common to the check, list, postRepair, and repair commands:
| Argument Name | Value | Default Value | Description |
|---|---|---|---|
| -topDir | String | %HOMEPATH%\Music | The directory whose subdirectories are artist names |
| -ext | String | .mp3 | The extension used to identify music files |
| -albumFilter | String | '.*' | Filter for which album directories to process |
| -artistFilter | String | '.*' | Filter for which artist directories to process |
Command arguments can be specified on the command line. On the command line, string-valued and numeric-valued arguments can be entered in any of the following forms:
- -argumentName argumentValue
- -argumentName=argumentValue
- --argumentName argumentValue
- --argumentName=argumentValue
Boolean (true/false) arguments can be entered in either of the following forms if the argument value is false:
- -argumentName=false
- --argumentName=false
They can be entered in any of the following forms if the argument value is true:
- -argumentName
- -argumentName=true
- --argumentName
- --argumentName=true
The various command arguments have built-in default values; the command arguments do not need to be specified on the command line unless the user wants to specify different values for those command arguments.
The user may find that she is constantly overriding some command arguments on the command line with the same values. The user can simplify their usage and override the default command argument values by placing a text file named defaults.yaml in the %APPDATA%\mp3repair directory. By default, there is no such directory, and the user must create it; the export command can be used to create a baseline version of the file, in the correct directory.
See YAML for a brief description of how the mp3repair program uses YAML and a link to YAML documentation.
The defaults.yaml file may contain seven blocks, all of which are optional:
- check The check block may have up to three boolean key-value pairs,
with each key controlling the default setting for its corresponding check
command argument:
- empty
- gaps
- integrity
- command The command block may have one string key-value pair:
- default the value of this entry must be one of about, check, list, postRepair, repair, or resetDatabase. It causes that command to become the default command when no command is specified on the command line.
- common The common block may have up to four string key-value pairs,
with each key controlling the default setting for its corresponding
common argument:
- albumFilter
- artistFilter
- ext
- topDir
- export The export block may have up to two boolean key-value pairs,
with each key controlling the default setting for its corresponding
export command argument:
- defaults
- overwrite
- list The list block may have up to six boolean key-value pairs and
one string key-value pair, with each key controlling the default setting for
its corresponding list command argument:
- annotate
- details
- diagnostic
- includeAlbums
- includeArtists
- includeTracks
- sort must be set to alpha or numeric
- repair The repair block may have one boolean key-value pair,
controlling the default setting for its corresponding repair command
argument:
- dryRun
- resetDatabase The resetDatabase block may have three string key-value
pairs and on numeric key-value pair, with each key controlling the default
setting for its corresponding resetDatabase command argument:
- extension
- metadata
- service
- timeout
As the about and postRepair commands have no arguments, if either is included as a block, the block will be ignored.
Here is the yaml content corresponding to the standard out of the box default values:
---
check:
empty: false
gaps: false
integrity: true
command:
default: list
common:
albumFilter: .*
artistFilter: .*
ext: .mp3
topDir: %HOMEPATH\Music
export:
defaults: false
overwrite: false
list:
annotate: false
details: false
diagnostic: false
includeAlbums: true
includeArtists: true
includeTracks: false
sort: numeric
repair:
dryRun: false
resetDatabase:
extension: .wmbd
metadata: %USERPROFILE%\AppData\Local\Microsoft\Media Player\
service: WMPNetworkSVC
timeout: 10A few comments concerning argument values:
Argument values may contain references to environment variables. These can be specified either in Windows format (%VAR_NAME%) or in *nix format ($VAR_NAME), such as $APPDATA/mp3repair or %APPDATA%\mp3repair.
The referenced environment variables must exist. Referring to a non-existent (e.g., misspelled) variable will result in the program failing with one or more error messages specifying the missing variable.
File separators, as in a path to the music files, may be forward slashes (/) or backward slashes (\).
Numeric argument values may be specified in decimal (e.g., 1234), octal (e.g., 0622), or hexadecimal (e.g., 0x2B), and may be negative.
Boolean argument values are true or false. True values may be specified as 1, t, T, true, TRUE, or True. False values may be specified as 0, f, F, false, FALSE, or False.
mp3repair depends on the following environment variables being set:
- TMP or TEMP - the system temporary directory. mp3repair looks for TMP first, and, if that variable is not defined, then mp3repair looks for TEMP. One of them must be set so that log files can be written.
mp3repair uses the following third party libraries:
- Basic command structure and logging implementation: https://github.com/majohn-r/cmd-toolkit.
- Console/Error/Log output control: https://github.com/majohn-r/output.
- Log rotation: https://github.com/utahta/go-cronowriter.
- Progress bar: https://github.com/cheggaaa/pb.
- Reading and writing the mp3 file ID3V2 metadata: https://github.com/bogem/id3v2.
- Reading configuration files: https://pkg.go.dev/gopkg.in/yaml.v3
In addition, I use https://libs.garden/ to look for libraries.
MP3 files contain metadata in the form of ID3V2 tags and ID3V1 tags; ID3V1 is the older tag format and is severely constrained compared to ID3V2, but it is still widely supported, and it is common to find MP3 files that contain both. While the mp3repair program primarily deals with the richer ID3V2 metadata, the check and repair commands will notice when ID3V1 tags are not in sync with the files and rewrite them as necessary. Information about the ID3V1 tag format can be found here: https://id3.org/ID3v1.
The mp3repair program depends heavily on the MP3 files containing an ID3V2.3.0 tag, which stores information about the audio file, particularly metadata, such as the title and performer. Information about the ID3V2.3.0 tag format can be found here: https://id3.org/id3v2.3.0.
The mp3repair program reads user-supplied files, written in YAML, for purposes such as configuring default argument values. For information on writing such files, the YAML specification can be found here: https://yaml.org/spec/1.2.2/.