Last.fm URL Scrobbler

Scrobble tracks to Last.fm directly from any Last.fm URL (track, album, artist, or tag).

Features

• URL Parsing: Works with tracks, full albums, artist top tracks, user pages, and tag charts.
• Custom Timestamps: Set custom start dates and times in the past or future (e.g., "2024-05-20 14:30").
• Dry Run: Preview fetched tracklists and calculated timestamps without submitting scrobbles.

Prerequisites

• Python 3.8+
• A Last.fm account

1. Installation

pip install git+https://github.com/1orelai/lastfm-url-scrobbler.git

This installs two commands, lastfm-url-scrobbler and get-session-key, onto your PATH.

2. Set Up Last.fm API Credentials

1. Create a free API application on the Last.fm API account page.
2. Log in and submit the form (e.g., Application Name: URLScrobbler).
3. Copy your API Key and Shared Secret.

Export them in your terminal:

export LASTFM_API_KEY="your_api_key_here"
export LASTFM_API_SECRET="your_shared_secret_here"

3. Authenticate (One-Time)

Generate a write-enabled session key:

get-session-key

1. This opens an authorization URL in your browser.
2. Click Yes, Allow Access.
3. Return to the terminal and press Enter.
4. Copy the printed session key and export it:

export LASTFM_SESSION_KEY="your_retrieved_session_key"

Tip: Add all three export commands to your ~/.zshrc or ~/.bashrc so they persist across terminal sessions.

4. Usage

lastfm-url-scrobbler "https://www.last.fm/music/Magazine/Real+Life"

Options

Examples

Scrobble a single track:

lastfm-url-scrobbler "https://www.last.fm/music/The+Beatles/_/Blackbird"

Scrobble an artist's top tracks:

lastfm-url-scrobbler "https://www.last.fm/music/Joni+Mitchell/+tracks"

Scrobble an album with a custom start date:

lastfm-url-scrobbler "https://www.last.fm/music/The+Stooges/Fun+House" --start "2024-05-20 14:30"

Preview without sending (dry run):

lastfm-url-scrobbler "https://www.last.fm/tag/classic+rock" --dry-run

Development

To work on the tool locally instead of installing from GitHub:

git clone https://github.com/1orelai/lastfm-url-scrobbler.git
cd lastfm-url-scrobbler
pip install -e .

The -e (editable) install links the commands to your working copy, so changes take effect immediately.