Features

Spotify

Spotify and Discord Activities

ℹ️

Discord-provided data

PresenceKit reports Spotify activity visible through Discord. It does not require Spotify credentials or promise listening history.

PresenceKit reports the music and activities that Discord currently exposes for a consenting user. It does not connect to Spotify on the user's behalf or maintain a listening history.

Step 1 — Read Spotify metadata

example.tstypescript

import { createPresenceClient } from "@iconical/presence";

const client = createPresenceClient();
const result = await client.getPresence("123456789012345678");

if (result.spotify) {
  console.log(result.spotify.song);
  console.log(result.spotify.artist);
  console.log(result.spotify.albumArtUrl);
} else {
  console.log("No Spotify activity currently reported");
}

result.spotify is null when Discord does not report an active Spotify listening activity. Do not interpret null as an error or a guarantee that a user is not listening to music.

Music metadata terms

Discord activity: The current Rich Presence information supplied by Discord.
trackId: A Spotify track identifier, when visible and valid.
progressMs: Playback progress calculated from available timestamps.

Spotify fields

Field	Description
`song`	Visible track title
`artist` and `artists`	Artist string and parsed list, when supplied
`album`	Album label from Discord activity image metadata, when present
`trackId` and `trackUrl`	Safe Spotify track ID/link if Discord includes a valid identifier
`albumArtUrl`	Cover artwork when a valid image is available
`startedAt` and `endsAt`	ISO timestamps when supplied
`durationMs` and `progressMs`	Computed from visible timestamps, when possible

The album field comes from Discord's activity tooltip, not an independent Spotify metadata lookup. Missing values remain null.

Step 2 — Use helper functions

example.tstypescript

import {
  createPresenceClient,
  getSpotifyActivity,
  getSpotifyNowPlaying,
  getPlayingActivities,
  getCustomStatus,
} from "@iconical/presence";

const result = await createPresenceClient().getPresence("123456789012345678");
const currentTrack = getSpotifyNowPlaying(result.presence);
const games = getPlayingActivities(result.presence);
const customStatus = getCustomStatus(result.presence);

console.log(currentTrack?.song ?? "No visible track");
console.log(games.map((game) => game.name));
console.log(customStatus?.state ?? "No visible custom status");
console.log(getSpotifyActivity(result.presence)?.name ?? "No Spotify activity");

The helper getSpotifyNowPlaying(presence, now?) can recalculate progress at a supplied timestamp, useful for a local progress display without repeatedly fetching an API response.

Step 3 — React Spotify card

example.tsxtsx

import { SpotifyCard } from "@iconical/presence/react-ui";

function Music({ track }: { track: import("@iconical/presence").SpotifyNowPlaying | null }) {
  return <SpotifyCard track={track} theme={{ accent: "#ac1c23" }} />;
}

You can also use result.spotify to build a fully custom UI. The card renders nothing when track is null.

Other activity metadata

presence.activities can contain playing, streaming, listening, watching, custom and competing activities. The SDK preserves safe details such as name, type, description, state, timestamps, artwork and available URLs, but does not include Discord session IDs or Rich Presence join/spectate secrets.

For images, read Activity artwork. For all response types, see API reference.

Was this page helpful?

Activity Artwork Widgets