https://github.com/codeconscious/audio-tag-tools
Cache audio tags, search for duplicates, and export genres.
https://github.com/codeconscious/audio-tag-tools
audio-tags dotnet fsharp
Last synced: about 1 month ago
JSON representation
Cache audio tags, search for duplicates, and export genres.
- Host: GitHub
- URL: https://github.com/codeconscious/audio-tag-tools
- Owner: codeconscious
- Created: 2025-05-04T03:31:42.000Z (about 1 year ago)
- Default Branch: main
- Last Pushed: 2026-04-13T08:52:11.000Z (2 months ago)
- Last Synced: 2026-04-13T10:34:50.355Z (2 months ago)
- Topics: audio-tags, dotnet, fsharp
- Language: F#
- Homepage:
- Size: 124 KB
- Stars: 0
- Watchers: 1
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
Awesome Lists containing this project
README
# Audio Tag Tools
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](https://fsprojects.github.io/FSharp.Data/library/JsonProvider.html), but it resolves a couple of small pain points for me as well.
# Requirements
- [.NET 10 runtime](https://dotnet.microsoft.com/en-us/download/dotnet/10.0)
- JSON settings file (only for the duplicate search) — plus comfort manually editing such JSON files
# Running
Ensure you are in the `AudioTagTools.Console` directory in your terminal.
## 1. Caching tags
Creates a "tag library," a JSON file containing the text tag data from the audio files in a specified directory.
> [!NOTE]
> If you have many files, especially on an external device, this process might take a while on its initial run, but will be much faster in subsequent ones.
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:
```sh
dotnet run -- cache-tags ~/Documents/Audio ~/Documents/Audio/tagLibrary.json
```
> [!TIP]
> The `--` is necessary to indicate that the command and arguments are for this program and not for `dotnet`.
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:
```json
[
{
"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"
}
]
```
> [!NOTE]
> This is the basically same format that the `--cache-tags` option of [my AudioTagger utility](https://github.com/codeconscious/audiotagger) outputs. The advantage of using this tool instead is that it compares tag data against files' last-modified dates and only updates out-of-date tag information, making the operation considerably faster, particularly when your audio files are on a slow external drive, etc.
## 2. Finding duplicates
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.
Click to expand the sample and notes...
```json
{
"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"
}
],
"equivalentArtists": [
["artistName", "equivalentArtistName"]
],
"artistReplacements": [
" ",
" ",
"The ",
"ザ・"
],
"titleReplacements": [
" ",
" ",
"(",
")",
"（",
"）",
"[",
"]",
"'",
"’",
"\"",
"”",
"-",
"–",
"—",
"~",
"〜",
"/",
"／",
"|",
"｜",
"?",
"？",
"!",
"！",
"~",
"〜",
"～",
"=",
"＝",
"&",
"＆",
"#",
"＃",
"•",
"・",
".",
"。",
",",
"、",
":",
"：",
"...",
"…",
"*",
"＊",
"+",
"＋",
"=",
"＝",
"✖︎",
"❌"
]
}
```
Notes:
1. Use `pathSearchFor` and `pathReplaceWith` if you wish to modify the base path of your media files in the playlist file—for example, if you wish the load the playlist on a different device where the files reside under a different base path. Otherwise, they may be left blank.
2. Use `equivalentArtists` to register lists of artists that should be considered identical for the purposes of duplicate-checking. Results will be reported using the first artist in each group.
To start, use the `find-duplicates` command like this:
```sh
dotnet run -- find-duplicates ~/Documents/Audio/findDupeSettings.json ~/Documents/Audio/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.
## 3. Exporting artist genres
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:
```sh
dotnet run -- export-genres ~/Downloads/Audio/tagLibrary.json ~/Downloads/Audio/genres.txt
```
If a genres file already exists at that path, a backup will be created automatically.
## 4. Analyzing cached tags
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:
```sh
dotnet run -- analyze-library ~/Downloads/Audio/tagLibrary.json
```
Several categories of data (e.g., most common artists, largest files) will be displayed.
## Other
### Exit codes
The program returns the following exit codes:
| Code | Meaning |
|------|---------------------------------------------------|
| 0 | Finished successfully |
| 1 | Invalid argument count |
| 2 | Invalid command |
| 3 | Failure during the requested command's operation |