Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/calmerism/Tamed/llms.txt

Use this file to discover all available pages before exploring further.

Tamed supports scrobbling to both Last.fm and ListenBrainz, letting you build an accurate and permanent record of your listening history. Both services can be enabled at the same time — Tamed handles each submission independently. Scrobbling is powered by ScrobbleManager, which tracks playback position, pauses the timer when you pause, and fires the scrobble only once the configured threshold is reached.
You can enable Last.fm and ListenBrainz scrobbling simultaneously. Each service receives its own independent submission — enabling both is a great way to keep a backup across two platforms.

​
Last.fm

​
Setup

1

API credentials (source builds only)

If you are building Tamed from source, you must supply a Last.fm API key and secret via the build configuration fields LASTFM_API_KEY and LASTFM_SECRET in your local local.properties or equivalent Gradle build config. Official releases have these bundled. You can obtain keys at last.fm/api/account/create.
2

Sign in to Last.fm

In Tamed, navigate to Settings → Account → Last.fm (or Settings → Integrations → Last.fm). Tap Login and enter your Last.fm username and password. Tamed calls the auth.getMobileSession endpoint behind the scenes. On success, it stores:
  • LastFMUsernameKey — your Last.fm username
  • LastFMSessionKey — the session key used for all subsequent API calls
Your password is never stored; only the session key is persisted.
3

Enable scrobbling

After logging in, toggle Enable Scrobbling (EnableLastFMScrobblingKey) to true. The toggle is disabled until a valid session key is present.
4

Configure Now Playing (optional)

Enable Now Playing (LastFMUseNowPlaying) to send a track.updateNowPlaying notification to Last.fm when a track starts. This updates the “Listening now” section on your Last.fm profile in real time, even before the full scrobble fires.

​
Last.fm Settings Reference

KeyTypeDescription
EnableLastFMScrobblingKeybooleanMaster scrobbling toggle; requires an active session
LastFMUsernameKeystringStored after login — your Last.fm username
LastFMSessionKeystringSession key obtained during OAuth-style login
LastFMUseNowPlayingbooleanSend a “Now Playing” update when a track starts
ScrobbleDelayPercentKeyfloatPercentage of track duration to play before scrobbling (range 30%–95%)
ScrobbleDelaySecondsKeyintAbsolute maximum wait time in seconds before scrobbling (range 30–360s)
ScrobbleMinSongDurationKeyintMinimum track duration in seconds to be eligible for scrobbling (range 10–60s)

​
ListenBrainz

​
Setup

1

Create a ListenBrainz account

Visit listenbrainz.org and create a free account if you don’t already have one.
2

Copy your user token

Log in to ListenBrainz, go to your profile settings, and copy the User Token shown there.
3

Enter the token in Tamed

In Tamed, navigate to Settings → Integrations → ListenBrainz. Paste your token into the token field (ListenBrainzTokenKey) and enable the ListenBrainz toggle (ListenBrainzEnabledKey).

​
ListenBrainz Settings Reference

KeyTypeDescription
ListenBrainzEnabledKeybooleanEnables ListenBrainz submission
ListenBrainzTokenKeystringYour ListenBrainz user token from your profile page
Tamed submits to https://api.listenbrainz.org/1/submit-listens using the standard ListenBrainz JSON payload format, including duration_ms, artist name(s), track name, and release name when available.

​
Scrobble Timing Behavior

Understanding when Tamed fires a scrobble helps you tune the delay settings to match your preferences.

Percentage-based delay

ScrobbleDelayPercentKey (default ~50%) defines what fraction of the track must play before the scrobble is submitted. For a 4-minute track at 50%, the scrobble fires after 2 minutes.

Absolute seconds cap

ScrobbleDelaySecondsKey acts as a ceiling. The scrobble fires at whichever threshold is reached first — the percentage point or the absolute seconds limit.

Minimum duration gate

Tracks shorter than ScrobbleMinSongDurationKey (default 30s) are never scrobbled, regardless of how much of them plays. This prevents accidental scrobbles from brief interludes or sound effects.

Pause-aware timer

ScrobbleManager pauses its internal countdown when playback is paused and resumes it when playback continues. Elapsed time while paused does not count toward the scrobble threshold.
The scrobble timer calculates its threshold as min(duration × percent, delaySeconds) in milliseconds. If that value is zero or negative at the start of a track, the scrobble is submitted immediately.

​
Scrobble Submission Details

Tamed submits the following metadata with each scrobble:
  • Artist — all artists joined; Last.fm uses ", " as the separator, ListenBrainz uses " & "
  • Track — song title
  • Album — album title (omitted if unavailable)
  • Duration — track duration in seconds
  • Timestamp — Unix epoch seconds at the moment the track started playing
For ListenBrainz, additional additional_info fields are included in the payload:
  • playing_now submissions include duration_ms, position_ms, and submission_client
  • Finished-listen submissions include duration_ms, start_ms, end_ms, and submission_client

Build docs developers (and LLMs) love

Get started for freeTalk to us