cliamp-scrobble

Last.fm scrobbling for cliamp.

cliamp-scrobble waits until you have actually listened to a configurable amount of a track, then sends the scrobble to Last.fm. It also adds keybindings for loving/unloving tracks and temporarily toggling scrobbling.

Features

• Scrobbles after 50% of a track by default.
• Configurable scrobble threshold.
• * loves or un-loves the current track.
• & toggles automatic scrobbling for the current cliamp session.
• Retryable scrobble failures are cached and retried later.
• Optional Last.fm now-playing updates.
• Notifications are color-coded by status.

Quick Start

1. Install

Install the plugin first:

cliamp plugins install aloglu/cliamp-scrobble

Then install the auth helper:

curl -fsSL \
  https://raw.githubusercontent.com/aloglu/cliamp-scrobble/HEAD/lastfm-auth \
  -o ~/.config/cliamp/plugins/lastfm-auth
chmod +x ~/.config/cliamp/plugins/lastfm-auth

Note

cliamp plugins install only installs cliamp-scrobble.lua. It does not install extra repository files, so lastfm-auth needs the separate curl command above.

Other install methods

Install from a local checkout:

git clone https://github.com/aloglu/cliamp-scrobble.git
cd cliamp-scrobble
cliamp plugins install .

Manual file install:

mkdir -p ~/.config/cliamp/plugins
cp cliamp-scrobble.lua ~/.config/cliamp/plugins/
cp lastfm-auth ~/.config/cliamp/plugins/
chmod +x ~/.config/cliamp/plugins/lastfm-auth

Restart cliamp after either method.

2. Create a Last.fm API App

Create an API app here:

https://www.last.fm/api/account/create

You will need:

• API key
• shared secret

Important

Treat the shared secret and session key like passwords.

3. Authenticate

Run the helper:

~/.config/cliamp/plugins/lastfm-auth --write-config

The helper will:

• ask for your API key and shared secret
• open Last.fm in your browser
• ask you to approve the app
• write the plugin config to ~/.config/cliamp/config.toml

Restart cliamp after installing the plugin.

If the browser cannot open automatically:

~/.config/cliamp/plugins/lastfm-auth --no-open

Manual Last.fm authentication without the helper

Add this config block after you get a session key:

[plugins.cliamp-scrobble]
api_key = "$LASTFM_API_KEY"
api_secret = "$LASTFM_API_SECRET"
session_key = "$LASTFM_SESSION_KEY"
enabled = true
now_playing = false
threshold = 0.5
poll_secs = 2

Manual session-key flow:

1. Create a Last.fm API app at https://www.last.fm/api/account/create.
2. Copy the API key and shared secret.
3. Call auth.getToken with your API key and a valid API signature.
4. Open https://www.last.fm/api/auth/?api_key=YOUR_API_KEY&token=TOKEN.
5. Approve access in Last.fm.
6. Call auth.getSession with the approved token and a valid API signature.
7. Copy session.key into ~/.config/cliamp/config.toml.

Caveats:

• Auth tokens expire after 60 minutes.
• Auth tokens are single-use.
• API signatures sort parameters alphabetically, concatenate name + value, append the shared secret, and MD5-hash the result.
• Do not include format, callback, or api_sig itself in the signature string.
• Session keys usually stay valid until you revoke the app in Last.fm settings.

Configuration

Default config:

[plugins.cliamp-scrobble]
api_key = "$LASTFM_API_KEY"
api_secret = "$LASTFM_API_SECRET"
session_key = "$LASTFM_SESSION_KEY"
enabled = true
now_playing = false
threshold = 0.5
poll_secs = 2

cliamp supports environment-variable interpolation in config.toml, so secrets can stay in your shell environment.

now_playing enables Last.fm "Scrobbling now" updates:

now_playing = true

When enabled, the plugin sends now-playing updates as soon as a valid track starts or resumes. threshold still only controls when the final scrobble is submitted.

Scrobble Timing

threshold decides when a track is scrobbled.

Value	Meaning
0.5	scrobble after 50%
0.75	scrobble after 75%
1.0	scrobble after the full track

Example:

threshold = 0.75

poll_secs controls how often playback progress is checked:

poll_secs = 2

Note

Lower poll_secs values are more responsive. Higher values do less polling.

Usage

Inside cliamp:

Key	Action
*	love or un-love the current track
&	toggle automatic scrobbling for this session

The & toggle only affects automatic scrobbling. You can still love or un-love tracks with * while scrobbling is disabled. If now_playing is enabled, & also pauses now-playing updates for this cliamp session.

If * loves the current track before the scrobble threshold, the plugin immediately scrobbles that play session and marks it as handled.

Behavior

• Forward seeks do not immediately count as listened time.
• Tracks shorter than 30 seconds are ignored.
• Now-playing failures are logged but not cached or retried.
• Successful scrobbles show a cliamp message with the updated Last.fm play count when available.
• Retryable failures are stored in ~/.config/cliamp/lastfm-scrobbler-cache.json.
• Plugin logs are written to ~/.config/cliamp/plugins.log.

License

Released under the MIT License.