This small command line application performs four tasks:

1. Cache metadata tags from audio files into a "library file"
2. Report likely duplicate files based on their tags
3. Export a list of artists with their most common genres
4. Analyze library files and display various statistics

I originally created this tool to practice with F# JSON type providers, but it resolves a couple of small pain points for me as well.

• .NET 9 runtime
• JSON settings file (only for the duplicate search) — plus comfort manually editing such JSON files

Ensure you are in the AudioTagTools.Console directory in your terminal.

Creates a "tag library," a JSON file containing the text tag data from the audio files in a specified directory.

Pass cache-tags with two arguments:

1. The path of the directory containing your audio files
2. The path of the library file that contains (or will contain, if it does not exist yet) your cached audio tags

Sample:

dotnet run -- cache-tags ~/Documents/Audio ~/Documents/Audio/tagLibrary.json

If a library file already exists at the specified path, a backup copy will automatically be created in the same directory.

The file will be in this JSON format:

[
  {
    "FileName": "FILENAME.m4a",
    "DirectoryName": "FULL_DIRECTORY_NAME",
    "Artists": [
      "SAMPLE ARTIST NAME"
    ],
    "AlbumArtists": [
      "SAMPLE ALBUM ARTIST NAME"
    ],
    "Album": "ALBUM_NAME",
    "TrackNo": 0,
    "Title": "TRACK_TITLE",
    "Year": 1950,
    "Genres": [
      "GENRE"
    ],
    "Duration": "00:03:39.6610000",
    "LastWriteTime": "2024-09-12T09:40:54+09:00"
  }
]

First, you must already have a tag library file containing your cached tag data. Check the section above if you don't have one yet.

Second, you must have a settings file containing exceptions—i.e., artists, track titles, and strings that you wish to exclude from the search. Actual entries are optional, but the file must be exist in the specified format. I have provided a sample you can use below.

{
  "playlist": {
    "saveDirectory": "/Users/me/Downloads/NewAudio",
    "pathSearchFor": "/Users/me/Documents/Media/",
    "pathReplaceWith": ""
  },
  "exclusions": [
    {
      "artist": "SAMPLE_ARTIST_NAME",
      "title": "SAMPLE_TRACK_NAME"
    },
    {
      "artist": "SAMPLE_ARTIST_NAME"
    },
    {
      "title": "SAMPLE_TRACK_NAME"
    }
  ],
  "artistReplacements": [
    " ",
    "　",
    "The ",
    "ザ・"
  ],
  "titleReplacements": [
    " ",
    "　",
    "(",
    ")",
    "（",
    "）",
    "[",
    "]",
    "'",
    "’",
    "\"",
    "”",
    "-",
    "–",
    "—",
    "~",
    "〜",
    "/",
    "／",
    "|",
    "｜",
    "?",
    "？",
    "!",
    "！",
    "~",
    "〜",
    "～",
    "=",
    "＝",
    "&",
    "＆",
    "#",
    "＃",
    "•",
    "・",
    ".",
    "。",
    ",",
    "、",
    ":",
    "：",
    "...",
    "…",
    "*",
    "＊",
    "+",
    "＋",
    "=",
    "＝",
    "✖︎",
    "❌"
  ]
}

To start, use the find-duplicates command like this:

dotnet run -- find-duplicates ~/Documents/settings.json ~/Downloads/Music/tagLibrary.json

If any potential duplicates are found, they will be listed, grouped by artist. If you see false positives (i.e., tracks that were detected as duplicates, but are actually not), you can add entries to the exclusions in your settings to ignore them in the future.

Creates a text file containing a list of artists with the genre that they are most associated with in your tag library.

To use it, pass export-genres with two arguments:

1. The path of your library file
2. The path of the text file that contains (or will contain, if it does not exist yet) your artists with corresponding genres

Sample:

dotnet run -- export-genres ~/Downloads/Music/tagLibrary.json ~/Downloads/Music/genres.txt

If a genres file already exists at that path, a backup will be created automatically.

You must already have a tag library file containing your cached tag data. Check above if you don't have one yet.

To start, simply use the analyze-library command like this:

dotnet run -- analyze-library ~/Downloads/Music/tagLibrary.json

Several categories of data (e.g., most common artists, largest files) will be displayed.

The program returns the following exit codes: