Scrobbletail

A typed, runtime-validating TypeScript client for the Last.fm API. Scrobbletail covers all 57 currently documented, non-deprecated methods, groups them into nine namespaces, and validates every successful response with TypeBox.

• Complete Last.fm API coverage
• Inferred TypeScript response types
• TypeBox schemas exported for runtime validation
• Stable Last.fm request signing
• Web, desktop, and mobile-session authentication helpers
• ESM-only package for Bun, Node.js 18.17+, and Web API-compatible runtimes
• Fetch-compatible transport powered by ofetch

Scrobbletail is an independent project. It is not affiliated with, endorsed by, or sponsored by Last.fm or Paramount Global.

Contents

• Install
• Get API credentials
• Quick start
• Usage examples
• Authentication
• Authenticated actions
• Scrobbling
• Configuration
• Errors
• Schemas and types
• API coverage
• Development

Install

npm install scrobbletail

bun add scrobbletail

Scrobbletail is ESM-only and includes TypeScript declarations.

Get API credentials

Create a Last.fm API application from the Last.fm API account page. Public read methods need an API key. Signed application and user-session methods also need the API secret.

Keep API secrets, session keys, and user passwords out of browser bundles, source control, and logs.

Quick start

Create a client with an API key and call a namespace method:

import { createScrobbletailClient } from "scrobbletail";

const lastfm = createScrobbletailClient({
  apiKey: process.env.LASTFM_API_KEY!,
});

const chart = await lastfm.chart.getTopArtists({ limit: 10 });

for (const artist of chart.artist) {
  console.log(artist.name, artist.url);
}

Response values use Last.fm's JSON representation. Counts, ranks, booleans, and timestamps returned by Last.fm are generally strings rather than numbers.

Usage examples

Search the catalog

const results = await lastfm.track.search("Teardrop", {
  artist: "Massive Attack",
  limit: 5,
});

for (const track of results.trackmatches.track) {
  console.log(`${track.artist} — ${track.name}`);
}

Search methods are available for albums, artists, and tracks:

const albums = await lastfm.album.search("Mezzanine", { limit: 5 });
const artists = await lastfm.artist.search("Portishead", { limit: 5 });
const tracks = await lastfm.track.search("Jóga", { artist: "Björk" });

Look up music by name or MBID

Album, artist, and track methods accept an exclusive identifier object. Supply names or an MBID, not both:

const album = await lastfm.album.getInfo({
  artist: "Massive Attack",
  album: "Mezzanine",
});

const artist = await lastfm.artist.getInfo({
  mbid: "10adbe2f-6c87-4cc8-a679-39c13f7b3d63",
});

const track = await lastfm.track.getInfo(
  { artist: "Björk", track: "Jóga" },
  { autocorrect: true, username: "lastfm-user" },
);

console.log(album.name, artist.name, track.listeners);

TypeScript rejects identifier objects that mix an MBID with artist, album, or track names.

Browse related music

const [similar, topAlbums, taggedTracks] = await Promise.all([
  lastfm.artist.getSimilar({ artist: "Portishead" }, { limit: 10 }),
  lastfm.artist.getTopAlbums(
    { artist: "Portishead" },
    { limit: 10, autocorrect: true },
  ),
  lastfm.tag.getTopTracks("trip-hop", { limit: 10 }),
]);

console.log(similar.artist.map((item) => item.name));
console.log(topAlbums.album.map((item) => item.name));
console.log(taggedTracks.track.map((item) => item.name));

Read user listening history

const recent = await lastfm.user.getRecentTracks("lastfm-user", {
  from: new Date("2026-01-01T00:00:00Z"),
  to: new Date("2026-02-01T00:00:00Z"),
  extended: true,
  limit: 50,
});

for (const track of recent.track) {
  const playedAt = track.date?.uts ?? "now playing";
  console.log(`${track.artist} — ${track.name} (${playedAt})`);
}

from and to accept a Date or a non-negative integer Unix timestamp in seconds.

Top-item methods accept Last.fm reporting periods:

const topTracks = await lastfm.user.getTopTracks("lastfm-user", {
  period: "1month",
  limit: 25,
});

console.log(topTracks.track.map((item) => item.name));

Abort a request

Every endpoint accepts signal and custom headers in its final options object:

const result = await lastfm.chart.getTopTracks({
  limit: 20,
  signal: AbortSignal.timeout(5_000),
  headers: {
    "x-request-id": crypto.randomUUID(),
  },
});

Scrobbletail overwrites protected transport headers such as Accept, Content-Type, and User-Agent where required.

Authentication

Last.fm authorization creates a long-lived session key. Scrobbletail returns the key but never stores it; persistence belongs to your application.

Web flow

Create an authorization URL, redirect the user to it, then exchange the callback token:

import {
  createAuthorizationUrl,
  createScrobbletailClient,
} from "scrobbletail";

const apiKey = process.env.LASTFM_API_KEY!;
const apiSecret = process.env.LASTFM_API_SECRET!;

const authorizationUrl = createAuthorizationUrl({
  apiKey,
  callbackUrl: "https://music.example.com/auth/lastfm/callback",
});

// Redirect the user to authorizationUrl.

In the callback handler:

const authClient = createScrobbletailClient({ apiKey, apiSecret });

async function handleLastFmCallback(request: Request) {
  const token = new URL(request.url).searchParams.get("token");
  if (!token) throw new Error("Last.fm callback did not include a token");

  const session = await authClient.auth.getSession(token);
  await secureSessionStore.write(session.key);

  return session.name;
}

The authorization endpoint must use HTTPS. Callback URLs may use HTTP only for local development.

Desktop flow

Desktop applications can request a token before opening the authorization page:

const authClient = createScrobbletailClient({ apiKey, apiSecret });
const token = await authClient.auth.getToken();
const authorizationUrl = createAuthorizationUrl({ apiKey, token });

await openInBrowser(authorizationUrl);
await waitForUserApproval();

const session = await authClient.auth.getSession(token);
await secureSessionStore.write(session.key);

Mobile session

auth.getMobileSession sends a plaintext password in a signed HTTPS form body. Use it only from a trusted server or native application—never from browser code.

const session = await authClient.auth.getMobileSession(
  usernameFromSecureInput,
  passwordFromSecureInput,
);

Scrobbletail intentionally excludes the deprecated authToken parameter.

Authenticated actions

Create a signed-session client with an API secret and either a fixed session key or a lazy provider. The provider takes precedence and runs only for methods that require a session.

const lastfm = createScrobbletailClient({
  apiKey: process.env.LASTFM_API_KEY!,
  apiSecret: process.env.LASTFM_API_SECRET!,
  getSessionKey: async () => secureSessionStore.read(),
});

await lastfm.track.love("Massive Attack", "Teardrop");
await lastfm.track.addTags("Massive Attack", "Teardrop", [
  "trip-hop",
  "favorite",
]);
await lastfm.album.removeTag("Massive Attack", "Mezzanine", "favorite");

Tag mutations accept 1–10 tags. Empty lists and larger batches fail locally before a network request.

Four read methods use the active session when their optional user is omitted:

const profile = await lastfm.user.getInfo();
const tags = await lastfm.track.getTags({
  artist: "Massive Attack",
  track: "Teardrop",
});

Pass a user explicitly to use ordinary API-key mode:

const profile = await lastfm.user.getInfo("lastfm-user");
const tags = await lastfm.track.getTags(
  { artist: "Massive Attack", track: "Teardrop" },
  { user: "lastfm-user" },
);

The other two methods with this behavior are album.getTags and artist.getTags.

Scrobbling

Update the active session user's now-playing track:

const nowPlaying = await lastfm.track.updateNowPlaying({
  artist: "Massive Attack",
  track: "Teardrop",
  album: "Mezzanine",
  albumArtist: "Massive Attack",
  duration: 330,
});

if (nowPlaying.ignoredMessage.code !== "0") {
  console.error(nowPlaying.ignoredMessage["#text"]);
}

Submit one scrobble or a batch of up to 50:

const result = await lastfm.track.scrobble([
  {
    artist: "Portishead",
    track: "Roads",
    album: "Dummy",
    timestamp: new Date("2026-01-10T20:30:00Z"),
  },
  {
    artist: "Björk",
    track: "Jóga",
    album: "Homogenic",
    timestamp: 1_768_077_240,
    chosenByUser: true,
  },
]);

console.log(
  `Accepted ${result["@attr"].accepted}; ignored ${result["@attr"].ignored}`,
);

Scrobble timestamps must be valid Date objects or non-negative integer Unix seconds. Every request uses Last.fm's indexed form fields, including single-item submissions. Retry policy and offline persistence are intentionally left to the consuming application.

Configuration

const lastfm = createScrobbletailClient({
  apiKey: process.env.LASTFM_API_KEY!,
  apiSecret: process.env.LASTFM_API_SECRET,
  sessionKey: sessionKeyFromSecureStorage,
  getSessionKey: async () => secureSessionStore.read(),
  baseUrl: "https://lastfm-proxy.example/2.0/",
  userAgent: "my-music-app/1.0",
  timeout: 10_000,
  fetch: customFetch,
});

Option	Required	Purpose
apiKey	Yes	Last.fm application API key sent with every request.
apiSecret	For signed methods	Signs application and session requests. Never sent as a request parameter.
sessionKey	For session methods	Fixed Last.fm user-session key.
getSessionKey	No	Lazy session-key provider; takes precedence over sessionKey.
baseUrl	No	HTTPS Last.fm-compatible API root. Defaults to https://ws.audioscrobbler.com/2.0/.
userAgent	No	Requested User-Agent value. Defaults to scrobbletail.
timeout	No	Request timeout in milliseconds. Omit to leave timeout handling unset.
fetch	No	Fetch-compatible transport for proxies, custom networking, or tests.

Browsers may strip the forbidden User-Agent header. Browser applications that require guaranteed identification should use a custom fetch or an HTTPS proxy.

Undefined request parameters are omitted. 0, false, and empty strings are preserved. Automatic retries are not performed.

Errors

import {
  LastFmApiError,
  ScrobbletailResponseValidationError,
  ScrobbletailTransportError,
} from "scrobbletail";

try {
  await lastfm.track.love("Massive Attack", "Teardrop");
} catch (error) {
  if (error instanceof LastFmApiError) {
    console.error(error.code, error.method, error.status, error.message);
  } else if (error instanceof ScrobbletailResponseValidationError) {
    console.error(error.method, error.issues);
  } else if (error instanceof ScrobbletailTransportError) {
    console.error(error.method, error.status);
  } else {
    throw error;
  }
}

LastFmApiError covers provider errors, including errors returned in an HTTP 200 response. ScrobbletailResponseValidationError means a successful response did not match its endpoint schema. ScrobbletailTransportError reports redacted network and non-provider HTTP failures without retaining signed URLs, request parameters, credentials, or underlying causes.

Schemas and types

Every response schema and its inferred type are exported from the package root:

import { Value } from "@sinclair/typebox/value";
import {
  TrackInfoSchema,
  type Scrobble,
  type TrackInfo,
} from "scrobbletail";

const cached: unknown = await loadCachedValue();

if (Value.Check(TrackInfoSchema, cached)) {
  const track: TrackInfo = cached;
  console.log(track.name);
}

const queuedScrobble = {
  artist: "Massive Attack",
  track: "Teardrop",
  timestamp: new Date(),
} satisfies Scrobble;

The same schemas validate live API responses before Scrobbletail returns them.

API coverage

The client exposes exactly nine namespaces and 57 methods:

Namespace	Methods	Purpose
album	6	Album metadata, tags, and search.
artist	10	Artist metadata, corrections, similarity, charts, tags, and search.
auth	3	Tokens and Last.fm sessions.
chart	3	Global top artists, tags, and tracks.
geo	2	Country and location charts.
library	1	User library artists.
tag	7	Tag metadata, similarity, charts, and weekly ranges.
track	12	Track metadata, tags, love state, search, now playing, and scrobbling.
user	13	Profiles, friends, listening history, personal tags, and charts.

See API_COVERAGE.md for the exact method inventory and authentication mode of every endpoint.

Development

bun install
bun run typecheck
bun run test
bun run coverage
bun run build
bun run pack:dry

Publishing is triggered by a v* Git tag through the npm workflow in .github/workflows/npm-publish.yml.