MP3Detective

v1.2.0 — Tag audio files using an LLM. Supports OpenAI, Ollama, and LM Studio. CLI or desktop GUI. Originals are never modified; tagged copies go to an output folder.

Features

• Providers: OpenAI (cloud), Ollama (local), or LM Studio (local)
• GUI: Configure folders and provider, run batches, cancel mid-run
• Formats: MP3, FLAC, M4A, MP4, OGG, OPUS
• Subfolders: Recursive scan; output keeps the same relative paths
• Safe: Copies into output/ before writing tags

Install

git clone https://github.com/deepakness/mp3detective.git
cd mp3detective

python -m venv venv
# Windows: venv\Scripts\activate
source venv/bin/activate

pip install -r requirements.txt

Requires Python 3.8+. The GUI needs tkinter (usually bundled with Python).

Configure an LLM

Edit the settings at the top of app.py, or use the GUI. Pick one provider.

You do not need a specific model. Use whatever works on your setup — larger models are often more accurate; smaller ones are faster. Set the model field to the name your provider already exposes.

OpenAI

1. Get an API key.
2. In app.py:

LLM_PROVIDER = "openai"
OPENAI_API_KEY = "your-key-here"
OPENAI_MODEL = "your-model-name"  # any chat model on your account

Ollama (default)

1. Install and run Ollama.
2. Pull/load any model that fits your machine.
3. In app.py (defaults already point at Ollama):

LLM_PROVIDER = "ollama"
OLLAMA_BASE_URL = "http://localhost:11434"
OLLAMA_MODEL = "your-model-name"  # must match `ollama list`

LM Studio

1. Install LM Studio, load any model, start the local server.
2. In app.py:

LLM_PROVIDER = "lmstudio"
LMSTUDIO_BASE_URL = "http://localhost:1234/v1"
LMSTUDIO_MODEL = "your-model-name"  # as shown in LM Studio

Other useful knobs in app.py: INPUT_FOLDER, OUTPUT_FOLDER, OVERWRITE, RATE_LIMIT_DELAY.

Run

CLI

# Put audio files in input/ (subfolders are fine)
python app.py

# Optional
python app.py --config path/to/config.json
python app.py --version

Tagged files land in output/.

GUI

python gui.py

Set input/output and provider under Configuration, then Start Processing. Settings are saved to ~/.mp3detective_config.json (mode 0600). If you store an OpenAI key there, treat that file as sensitive.

Tips

• Filenames drive results — clear title/artist names work best; the model never “hears” the audio.
• Privacy — OpenAI receives your filenames/prompts; Ollama and LM Studio stay local.
• Logs — metadata_updater.log
• Overwrite — with OVERWRITE = False, files that already have title/artist tags are skipped (based on the source file).

Troubleshooting

• Import errors — reinstall deps: pip install -r requirements.txt
• GUI / tkinter error — install your OS Tk package (e.g. python-tk on some Linux distros)
• Ollama connection — ensure Ollama is running and OLLAMA_BASE_URL is correct; model name must match ollama list
• LM Studio connection — local server must be running; base URL needs the /v1 suffix; model name must match LM Studio
• OpenAI errors — check API key, billing, and rate limits (RATE_LIMIT_DELAY)

License

MIT. Issues: github.com/deepakness/mp3detective/issues — include metadata_updater.log, OS, Python version, and provider when reporting bugs.