MusicIndexer/README.md

MusicIndexer

Pull your Spotify library and listening stats via the Spotify Web API, index a local music library (audio tags + iTunes XML), and match the two so you can see which tracks you own, what's missing, and your top artists/tracks/playlists — in a Streamlit GUI.

Features

• Spotify backend — OAuth (Authorization Code) login, then fetch the user profile, liked tracks, all playlists and their tracks, long-term top tracks and top artists, and playlist/profile cover art. Resilient paginated fetching (follows next, retries dropped connections, honours 429 rate limits) with progress bars.
• Local backend — index a folder of audio files via mutagen tags.
• iTunes backend — parse an iTunes Library XML export.
• Matching — map local tracks to Spotify tracks (fuzzy matcher; ISRC/MBID matching planned).
• Stats & lyrics — generate listening stats and fetch lyrics.
• GUI — browse libraries as artist → album → track tables.

Setup

Requires Python 3.13+.

python -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt

Credentials

Create an app at https://developer.spotify.com/dashboard and add http://127.0.0.1:8888 as a Redirect URI. Credentials are read from the environment — never commit them.

cp .env.example .env
# edit .env with your client id/secret
source .env

Env.py reads SPOTIFY_CLIENT_ID / SPOTIFY_CLIENT_SECRET (plus optional MUSIC_LIBRARY_PATH and WORK_DIR) from the environment.

Usage

Edit main.py to uncomment the steps you want, then run:

python main.py

The flow steps (see Flow.py) include:

Step	What it does
fetch_spotify()	OAuth login + download all Spotify data into work_dir/spotify/
fetch_local()	index local audio files into work_dir/local/
parse_spotify_library() / parse_itunes_library() / parse_local_library()	build normalized libraries
load_libraries() / save_libraries()	(de)serialize libraries to work_dir
map_local_to_spotify()	match local tracks against the Spotify library
fetch_and_save_lyrics()	fetch lyrics for tracks
log_stats()	generate stats

On first fetch_spotify() a browser opens for the Spotify login; a local server on 127.0.0.1:8888 catches the redirect and exchanges the code for a token.

GUI

./gui.sh        # runs: .venv/bin/streamlit run Gui.py

Layout

main.py                 entry point (CLI flow)
Gui.py / gui.sh         Streamlit GUI
Flow.py                 orchestrates fetch / parse / map / stats
Env.py                  config (reads credentials from the environment)
src/
  Library.py            data model (Library / Artist / Album / Track)
  LibrarySerializer.py  load/save libraries
  backends/
    spotify/            Web API client, OAuth, parser
    local/              local-file indexer, parser, playlist generator
    itunes/             iTunes XML parser
    navidrome/          Navidrome backend
  mappers/              local↔Spotify matching (fuzzy / search)
  lyrics/               lyrics fetching
work_dir/               fetched data and serialized libraries (gitignored)

Notes

• Data is cached as JSON under work_dir/ (gitignored); re-running reuses it.
• The deprecated Spotify endpoints (audio-features, recommendations, etc.) are not used — only currently-supported endpoints.