website·Indexed 34 days ago
https://spicetify.app/Developer documentation for Spicetify, a tool for customizing the Spotify client. Includes guides on creating extensions, custom apps, and themes, as well as a comprehensive API wrapper reference covering React components, URI validation, and internal Spotify CLI flags.
CosmosAsync is an asynchronous API wrapper used by the Spotify client to make requests to internal Spotify APIs (using protocols like sp://, wg://, and hm://) as well as external URLs. It functions similarly to fetch or axios, but automatically handles the inclusion of required headers and cookies (such as user session tokens). All responses are automatically parsed as JSON.
Security Warning: Do not use CosmosAsync for requests to untrusted external URLs, as it sends the user's session credentials. Use the standard fetch API for general external requests.
// Internal Spotify endpoint
await Spicetify.CosmosAsync.get("sp://desktop/v1/version");
// Spotify Web API endpoint
await Spicetify.CosmosAsync.get("https://api.spotify.com/v1/me");
// External URL (Use fetch instead of CosmosAsync for security)
await fetch("https://example.com");Spicetify.GraphQL wrapper is used to communicate with Spotify's internal GraphQL API endpoints. It is preferred over the standard Web API or CosmosAsync for tailored client operations, such as fetching track colors for the 'Now Playing View' or retrieving specific playlist resources. The wrapper abstracts the complexity of managing operationName, variables, and extensions (specifically the sha256Hash used for persisted queries), providing a more readable and maintainable way to perform queries and mutations.Spicetify is a toolkit for Spotify that provides four primary ways to customize the client:
Spicetify.Player.data property provides an object containing all current information about the active track and the player state. This is useful for retrieving the current track URI or other metadata.// Get current track URI
const currentURI = Spicetify.Player.data?.item.uri;
if (currentURI) {
console.log(currentURI);
}LocalStorage namespace wrapper to simplify interactions with the browser's localStorage. It allows developers to store, retrieve, and delete string-based key-value pairs.namespace LocalStorage {
function clear(): void;
function get(key: string): string | null;
function remove(key: string): void;
function set(key: string, value: string): void;
}PlayerState type provides a comprehensive snapshot of the current playback state in the Spicetify API wrapper. It includes information about the current track, playback position, playback status (playing, paused, buffering), queue state (previous and next tracks), and session metadata.type PlayerState = {
timestamp: number;
context_uri: string;
context_url: string;
context_restrictions: Record<string, string[]>;
index?: {
page: number;
track: number;
};
track?: ProvidedTrack;
playback_id?: string;
playback_quality?: {
bitrate_level: string;
hifi_status?: string;
strategy?: string;
target_bitrate_available?: boolean;
target_bitrate_level?: string;
};
playback_speed?: number;
position_as_of_timestamp: number;
duration: number;
is_playing: boolean;
is_paused: boolean;
is_buffering: boolean;
play_origin: {
feature_identifier: string;
feature_version: string;
view_uri?: string;
external_referrer?: string;
referrer_identifier?: string;
device_identifier?: string;
};
options: {
shuffling_context?: boolean;
repeating_context?: boolean;
repeating_track?: boolean;
};
restrictions: Record<string, string[]>;
suppressions: {
providers: string[];
};
debug?: {
log: string[];
};
prev_tracks?: ProvidedTrack[];
next_tracks?: ProvidedTrack[];
context_metadata: Metadata;
page_metadata: Metadata;
session_id: string;
queue_revision?: string;
};Spotify resources (tracks, albums, playlists, users) are identified by URIs and URLs.
spotify:<type>:<id> (e.g., spotify:track:6rqhFgbbKwnb9MLmUQDhG6). The <id> is a base62 unique identifier.https://open.spotify.com/<type>/<id>?query=parameters (e.g., https://open.spotify.com/track/6rqhFgbbKwnb9MLmUQDhG6?si=...).To manually copy a URI from the Spotify client: Right-click an item -> hover over Share -> hold Ctrl -> select Copy Spotify URI.
Spicetify.Platform.// Run in DevTools to explore available methods
Spicetify.PlatformPlatformData object contains technical details about the current Spotify client and the host operating system, useful for version-specific logic or debugging.interface PlatformData {
app_platform: string; // e.g., "win32"
client_capabilities: Record<string, any>;
client_version_triple: string; // e.g., "1.2.8"
client_version_quadruple: string;
client_version_quintuple: string;
event_sender_context_information: Record<string, any>;
os_name: string; // e.g., "windows"
os_version: string; // e.g., "10.0.19042"
}
const os = Spicetify.Platform.PlatformData.os_name;Spicetify.ReactComponent containing a set of stock React components used by Spotify. These can be used to create custom UI elements that maintain the native Spotify look and feel.namespace ReactComponent {
const ContextMenu: any;
const RightClickMenu: any;
const Menu: any;
const MenuItem: any;
const AlbumMenu: any;
const PodcastShowMenu: any;
const ArtistMenu: any;
const PlaylistMenu: any;
const TooltipWrapper: any;
const IconComponent: any;
const TextComponent: any;
const ConfirmDialog: any;
const PanelSkeleton: any;
const PanelContent: any;
const PanelHeader: any;
const Toggle: any;
const Slider: any;
}