⏪ Scrobble Time Machine

See what music you listened to in the current calendar week, but in a different year — based on your Last.fm scrobble history.

---

Features

Time Machine

• Browse any past year to see which tracks you played during the current calendar week
• Navigate with the ‹ › arrows, the year dropdown, or the ← → keyboard keys
• Tracks are sorted by play count and displayed with album art
• Click any track card to open a monthly play history chart for that track

Statistics

• Bar chart showing your total scrobbles for every year on record
• Click a year to see your top artists, top tracks, and genre breakdown
• Genres are fetched via Last.fm and permanently cached — no repeated API calls

Search

• Search Last.fm for any track or artist
• Click a result to view its full monthly play history

Spotify integration (optional, requires Spotify connection)

• Save as playlist — export the current week's tracks as a new Spotify playlist
• Add to queue — hover a track card and click the queue icon to add that track to your active Spotify playback queue (requires Spotify Premium and an active device)
• Uses PKCE OAuth — no client secret required

---

Requirements

• Last.fm account with scrobble history
• Docker + Docker Compose
• (Optional) Spotify Premium account for Spotify features
• (Optional) HTTPS certificate for Spotify outside localhost

---

1. Create a Last.fm API key

1. Go to https://www.last.fm/api/account/create
2. Enter a name (e.g. Scrobble Time Machine) and create an account
3. Copy the API key (the Shared Secret is not needed)

---

2. Set up Spotify (optional)

The Spotify integration uses PKCE OAuth — no client secret is required.

1. Go to https://developer.spotify.com/dashboard and create a new app
2. Under Redirect URIs, enter the address where the app is accessible, ending with /:
   • Local: http://localhost:3001/
   • Via Tailscale HTTPS: https://<your-hostname>.ts.net:3001/
3. Copy the Client ID

Note: Spotify only allows HTTP redirect URIs for localhost. For a Raspberry Pi or other server, HTTPS is required (see step 4).

---

3. Installation

# 1. Clone the repository
git clone https://github.com/NotVic/ScrobbleTimeMachine.git
cd ScrobbleTimeMachine

# 2. Create the .env file
cp .env.example .env
nano .env
# Fill in the values, save with Ctrl+O → Enter → Ctrl+X

# 3. Build and start
docker compose up -d

# 4. Open in browser
# http://<ip>:3001

---

4. Set up HTTPS via Tailscale (required for Spotify outside localhost)

Tailscale as a Docker container

# Check if the Tailscale container is running
docker ps | grep tailscale

# Get the hostname
docker exec tailscale tailscale status | head -3

# Generate a TLS certificate (HTTPS Certificates must be enabled in Tailscale Admin → DNS)
docker exec tailscale tailscale cert <your-hostname>.ts.net

# Copy the files to the host
mkdir -p /home/<user>/certs
docker cp tailscale:/tmp/<your-hostname>.ts.net.crt /home/<user>/certs/
docker cp tailscale:/tmp/<your-hostname>.ts.net.key /home/<user>/certs/

Then add the following to .env:

CERTS_DIR=/home/<user>/certs
SSL_CERT=/certs/<your-hostname>.ts.net.crt
SSL_KEY=/certs/<your-hostname>.ts.net.key

The app will then start automatically on HTTPS. Also update the Spotify Redirect URI to https://<your-hostname>.ts.net:3001/.

---

Environment variables

Variable	Required	Default	Description
LASTFM_API_KEY	Yes	—	Last.fm API key
LASTFM_USERNAME	Yes	—	Last.fm username
SPOTIFY_CLIENT_ID	No	—	Spotify app Client ID
APP_PORT	No	3001	External port on the host
SSL_CERT	No	—	Path to TLS certificate (inside container)
SSL_KEY	No	—	Path to TLS private key (inside container)
CERTS_DIR	No	/tmp	Directory on the host containing the certificate files

Example .env:

LASTFM_API_KEY=your_api_key_here
LASTFM_USERNAME=your_lastfm_username
SPOTIFY_CLIENT_ID=your_spotify_client_id
APP_PORT=3001
CERTS_DIR=/home/victor/certs
SSL_CERT=/certs/raspberrypi-tailscale.ts.net.crt
SSL_KEY=/certs/raspberrypi-tailscale.ts.net.key

---

Cache

Historical data is permanently stored as JSON files in a Docker named volume (cache_data). API calls for past years are made only once. The cache survives container restarts and updates.

# Inspect cache files (via Portainer: Volumes → cache_data → Browse)
docker run --rm -v scrobbletimemachine_cache_data:/cache alpine ls /cache

---

Installing updates

git pull
docker compose up -d --build

---

Viewing logs

docker compose logs -f