TuneLog

TuneLog is a self-hosted music recommendation system for Navidrome. It learns from listening behavior such as skips, partial plays, full plays, and repeats to generate personalized playlists and improve search results.

AI USAGES:

• AI were used in some sql Query
• Some part in debuggin and some assistance in building frontend like socketio
• Assistance in some of the research like which python module to use and stuff
• Playlist Page was re written using claude ai

[!important] Migrated from Mono Repo to Multi Repo Please Re download the ghcr-docker-compose.yaml file

---

New Features

Push Local Starred(heart) to Listenbrainz

This feature lets user sync there local starred song from navidrome to listenbrainz. Read here Push Heart

Skipped Songs Tracking

• A new Skipped Songs section has been added to the Library dashboard, making it easier to review songs that are frequently skipped.

Similar User Recommendations

• TuneLog can now generate collaborative recommendations using listening data from the most similar users on ListenBrainz.

ListenBrainz Collaborative Filtering Integration

• TuneLog now supports ListenBrainz Collaborative Filtering (CF) recommendations.

This feature uses ListenBrainz recommendation data and matches it against songs already available in your library to automatically generate personalized playlists.

For setup instructions and details, see the ListenBrainz Collaborative Filtering documentation.

Installation

Requirements

• Navidrome instance with API access
• Docker and Docker Compose, or Python 3.10+
• Node.js for the frontend if running manually

Option 1: Docker Compose

mkdir tunelog && cd tunelog
curl -o .env https://raw.githubusercontent.com/adiiverma40/tunelog/main/.env.example
curl -o ghcr-compose.yaml https://raw.githubusercontent.com/adiiverma40/tunelog/main/ghcr-compose.yaml
docker compose -f ghcr-compose.yaml up -d

Update:

docker compose -f ghcr-compose.yaml pull

Edit .env before starting the stack.

Option 2: Build from source

[!NOTE] You will have to manually Added or change the docker compose files for volume mounts

mkdir -p tunelog && cd tunelog
git clone https://github.com/adiiverma40/tunelog-backend
git clone https://github.com/adiiverma40/tunelog-frontend
curl -o .env https://raw.githubusercontent.com/adiiverma40/tunelog/main/.env.example

Backend

cd tunelog-backend
docker compose up --build

Frontend

cd tunelog-frontend
docker compose up --build

Option 3: Run without Docker

[!note] Note for Windows Users : PowerShell's default curl command may throw an SSL/Revocation error. If the curl commands below fail, simply download the .env.example file manually from the repository, place it in the respective folders, and rename it to .env. Or create .env file and paste the below config in both folders

Backend:

git clone https://github.com/adiiverma40/tunelog-backend
cd tunelog-backend
curl -o .env https://raw.githubusercontent.com/adiiverma40/tunelog/main/.env.example
cp .env.example .env
pip install -r requirements.txt
python3 error.py

Frontend:

git clone https://github.com/adiiverma40/tunelog-frontend
cd tunelog-frontend
curl -o .env https://raw.githubusercontent.com/adiiverma40/tunelog/main/.env.example
npm install
npm run dev

Configuration

Update .env with your Navidrome details and the addresses you want to allow.

# ================================================
#                NAVIDROME CONFIG
# ================================================

BASE_URL=http://navidrome-navidrome-1:4533      # Base URL for Navidrome Server
ADMIN_USERNAME=adii                             # Admin Username for Navidrome Server
ADMIN_PASSWORD=1234                             # Admin password for Navidrome Server

# ===============================================
#              DASHBOARD CONFIG
# ==============================================

VITE_URL=http://192.168.29.118:5173             # URL for Dashboard.
VITE_SERVER_PORT=8000                           # PORT on which Uvicorn(fastapi) server will be of Dashboard

# Add additional origins separated by commas, or use * to allow all.
ALLOWED_ORIGINS=http://localhost:5173,http://192.168.29.118:5173,*

# VITE_API_URL=http://192.168.29.118:8000       # NO NEED FOR THIS
# VITE_NAVIDROME_URL=http://192.168.29.118:4533 # NO NEED FOR THIS
MY_DOMAIN=192.168.29.118



# ================================================
#                     LOGGING
# ================================================

LOG_DIR=/app/logs
LOG_MAX_SIZE=10 MB
LOG_RETENTION_DAYS=7 days
LOG_LEVEL=DEBUG

# =================================================
#                   PROXY
# =================================================

PROXY_PORT=4534

Wiki:

• Playlist : guide on playlist generation and tweaks
• ListenBrainz Integration : guide on Listenbrainz integration in tunelog and dev info

Note: Navidrome/subsonic client like symfonium scrobble data to navidrome and navidrome reports that to listenbrainz, So Do not add those apps in pano app scrobble list or it will create two list of same song

ItunesFuzzy: Songs that are new or that is not in either itunes or musicbrainz, such as of small creators will be marked unmatched as api will return none

Note

• If there is any error, try copy pasting the config.json from github to your local file
• If Fast Library sync is taking too long, that will likely due to lyrics plugins, try turning off Lyrics Plugin in navidrome and runing the sync again Or change the lyrics priorty to emmbedded or .lrc

Features

• Personalized playlist generation from listening history
• Navidrome library sync
• Optional proxy layer for improved search and ranking
• Lyrics-aware search
• Fuzzy metadata matching
• CSV playlist import
• Logging and error handling
• Web dashboard and API backend
• Navidrome jam

Changes:

- No need to Mannually Add Listenbrainz token, Go to playlist > Listenbrainz cf > Add the token and save it

Navidrome jam

In the dashboard there is a jam section, if you wish to use jam go to jam and now playing section in the dashboard

features

• sync play , pause , skip
• Queue reorder
• Transfer host
• Chats for joined user - chats are not end to end encripted, do not share personal/private info
• Queue can be added from library or playlist
• In config you can toggle some features for jam like only host reorder queue, only host clear queue and more

Requirements

• Navidrome Running
• VITE_NAVIDROME_URL in .env for search and album arts
• All users in same server/dashboard

Setup

• Start the navidrome server
• start tunelog server and frontend
• go to dashboard
• do a library sync if havent
• Add or create users in users
• go to jam/nowplaying
• start jam
• users that have logged in the dashboard will see join jam option in nowplaying page,
• join it and enjoy

user profile

• User profile can be changed by users section

Optional Navidrome tag mapping

For better artist mapping, you can add this to navidrome.toml:

Tags.Artist.Aliases = ["artist", "artists"]

Then run a full library scan in Navidrome.

Proxy mode

The proxy layer is optional. When enabled, client search requests are routed through TuneLog before falling back to Navidrome.

To use it:

1. Set PROXY_PORT in .env if needed
2. Point your client to the proxy port instead of Navidrome directly
3. Keep the proxy and Navidrome on the same machine when possible

How it works

TuneLog uses implicit feedback from Navidrome activity to score tracks:

• Skipped tracks are penalized
• Partially played tracks get a small positive score
• Fully played tracks get a higher score
• Replayed tracks get the highest score

The playlist engine combines those scores with recency and discovery logic to keep playlists balanced.

Project structure

TuneLog/
├── backend/
│   ├── main.py
│   ├── playlist.py
│   ├── library.py
│   ├── db.py
│   └── Data/
├── frontend/
└── compose.yaml

Notes

• If you switch between Docker and manual runs, fix permissions on data/ if needed.
• Some features depend on Navidrome scanning and event support.
• Search quality depends on the metadata in your library.
• Speeding up or slowing down playback can affect listening detection.

Credits

• Navidrome
• FastAPI
• RapidFuzz
• TailAdmin