🎵 Footprints

Self-hosted music history manager with stats, reports and charts, inspired by maloja.

Features

• 📊 Statistics & Analytics: Track your listening habits with detailed stats
• 📈 Charts & Reports: View yearly, monthly, and all-time reports
• 🎤 Entity Detail Pages: In-depth artist, album, and track pages with stats and charts
• 📅 Timeline: Browse your complete listening history
• 🔄 Multi-source Import: Import from Last.fm and ListenBrainz
• 🚫 Deduplication: Automatic prevention of duplicate scrobbles
• 🐳 Docker Support: Easy deployment with Docker and docker-compose
• ⚡ Lightweight: Minimal dependencies, fast and efficient
• 🗄️ SQLite Database: Simple, portable database storage

Tech Stack

• Backend: Rust with Axum web framework
• Database: SQLite with rusqlite
• Frontend: Vanilla HTML/CSS/JavaScript (no frameworks)
• Deployment: Docker & docker-compose

Quick Start

Using Nix Flakes (Recommended for NixOS)

# Development environment
nix develop

# Run directly
nix run

# Build the package
nix build

Using Docker Compose

1. Create a .env file in the project root with your Last.fm API key:

LASTFM_API_KEY=your_lastfm_api_key_here

2. Start the application:

docker-compose up -d

The application will be available at http://localhost:3000

Note: To enable artist/album images in the UI, you need a Last.fm API key. Get one for free at https://www.last.fm/api/account/create

Manual Build

# Build the application
cargo build --release

# Run the application
cargo run --release

Configuration

Create a .env file in the project root:

# Database configuration
DATABASE_PATH=footprints.db

# Server configuration
PORT=3000

# Logging level
RUST_LOG=footprints=info

# Last.fm API key for artist/album images
# Get your API key at: https://www.last.fm/api/account/create
LASTFM_API_KEY=your_lastfm_api_key_here

Important: The LASTFM_API_KEY is required to display artist and album images. Without it, the application will still work but will show gradient placeholders instead of images.

Usage

1. Access the Web Interface: Open http://localhost:3000 in your browser

2. Import Data (One-time):

   • Go to the "Import" tab
   • For Last.fm: Enter your username and API key (get one at https://www.last.fm/api/account/create)
   • For ListenBrainz: Enter your username (token is optional)
   • Click import and wait for the process to complete

3. Automatic Sync (Optional):

   • Set up automatic sync via the API (see Sync API section below)
   • Configure sync interval (default: 60 minutes)
   • Sync runs in the background and fetches only new scrobbles
   • No duplicates will be created thanks to database constraints

Acknowledgments

Inspired by maloja - a self-hosted music scrobble database