Skip to main content

Player

Spicetify provides a collection of methods to interact with the Spotify player. You can get the current player state, play/pause, skip to next/previous track, set repeat/shuffle mode, and more.

This is mostly a wrapper of the Spicetify.Platform.PlayerAPI object.

namespace Player {
    function addEventListener(type: string, callback: (event?: Event) => void): void;
    function addEventListener(type: "songchange", callback: (event?: Event & { data: PlayerState }) => void): void;
    function addEventListener(type: "onplaypause", callback: (event?: Event & { data: PlayerState }) => void): void;
    function addEventListener(type: "onprogress", callback: (event?: Event & { data: number }) => void): void;
    function back(): void;
    const data?: PlayerState;
    function decreaseVolume(): void;
    function dispatchEvent(event: Event): void;
    const eventListeners: {
        [key: string]: Array<(event?: Event) => void>
    };
    function formatTime(milisecond: number): string;
    function getDuration(): number;
    function getMute(): boolean;
    function getProgress(): number;
    function getProgressPercent(): number;
    function getRepeat(): number;
    function getShuffle(): boolean;
    function getHeart(): boolean;
    function getVolume(): number;
    function increaseVolume(): void;
    function isPlaying(): boolean;
    function next(): void;
    function pause(): void;
    function play(): void;
    function playUri(uri: string, context?: any, options?: any): Promise<void>;
    function removeEventListener(type: string, callback: (event?: Event) => void): void;
    function seek(position: number): void;
    function setHeart(status: boolean): void;
    function setMute(state: boolean): void;
    function setRepeat(mode: number): void;
    function setShuffle(state: boolean): void;
    function setVolume(level: number): void;
    function skipBack(amount?: number): void;
    function skipForward(amount?: number): void;
    function toggleHeart(): void;
    function toggleMute(): void;
    function togglePlay(): void;
    function toggleRepeat(): void;
    function toggleShuffle(): void;
}

Properties​

data​

An object contains all information about current track and player.

caution

If the current player doesn't have any track, data will be null. Always check for null before using data to avoid errors.

Spicetify.Player.data;

Return​

PlayerState

Example​

// Get current track URI
const currentURI = Spicetify.Player.data?.item.uri;
if (currentURI) {
    console.log(currentURI);
}

eventListeners​

An object containing all registered event listeners.

Spicetify.Player.eventListeners;

Return​

{
    [key: string]: Array<(event?: Event) => void>
}
KeyDescription
keyEvent type
valueArray of registered event listeners

Methods​

addEventListener​

Register a listener of type on Spicetify.Player. You can use this method to listen to events that are fired throughout the app, including:

  • songchange type when player changes track.
  • onplaypause type when player plays or pauses.
  • onprogress type when track progress changes.
// Register a listener that will be called when player changes track
Spicetify.Player.addEventListener("songchange", (event) => {
    // Do something
    console.log(event.data);
});

Parameters​

NameTypeDescription
typestringEvent type
callback(event?: Event) => voidEvent listener. Includes relevant information about the event (e.g. data for songchange event)

dispatchEvent​

Dispatches an event at Spicetify.Player.

By default, Spicetify.Player always dispatch

  • songchange type when player changes track.
  • onplaypause type when player plays or pauses.
  • onprogress type when track progress changes.
Spicetify.Player.dispatchEvent(event);

Parameters​

NameTypeDescription
eventEventEvent to dispatch. Includes relevant information about the event (e.g. data for songchange event)

back​

Skip to previous track.

Spicetify.Player.back();

decreaseVolume​

Decrease a small amount of volume. The value is automatically determined by the client.

Spicetify.Player.decreaseVolume();

formatTime​

Format a time in milisecond to a string in mm:ss format.

Spicetify.Player.formatTime(time);

Parameters​

NameTypeDescription
timenumberTime in milisecond

Return​

string

Example​

Spicetify.Player.formatTime(1000); // "00:01"

// Get current track duration
const duration = Spicetify.Player.getDuration();
const formattedDuration = Spicetify.Player.formatTime(duration);
console.log(formattedDuration); // "03:45"

getDuration​

Return the duration of current track in milisecond.

Spicetify.Player.getDuration();

Return​

number

Example​

// Get current track duration
const duration = Spicetify.Player.getDuration();
console.log(duration); // 225000

getMute​

Return the mute state of player.

Spicetify.Player.getMute();

Return​

boolean

getProgress​

Return the progress of current track in milisecond.

Spicetify.Player.getProgress();

Return​

number

Example​

// Get current track progress
const progress = Spicetify.Player.getProgress();
console.log(progress); // 10000

getProgressPercent​

Return the progress of current track in percentage, from 0 to 1.

Spicetify.Player.getProgressPercent();

Return​

number

Example​

// Get current track progress
const progress = Spicetify.Player.getProgressPercent();
console.log(progress); // 0.04

getRepeat​

Return the repeat mode of player. The value can be:

  • 0 for no repeat.
  • 1 for repeat all.
  • 2 for repeat one.
Spicetify.Player.getRepeat();

Return​

number

getShuffle​

Return the shuffle state of player.

Spicetify.Player.getShuffle();

Return​

boolean

getHeart​

Return the heart state of player.

Spicetify.Player.getHeart();

Return​

boolean

getVolume​

Return the volume of player. The value is from 0 to 1.

Spicetify.Player.getVolume();

Return​

number

increaseVolume​

Increase a small amount of volume. The value is automatically determined by the client.

Spicetify.Player.increaseVolume();

next​

Skip to next track.

Spicetify.Player.next();

pause​

Pause the player.

Spicetify.Player.pause();

play​

Resume the player.

Spicetify.Player.play();

playUri​

Start playback of the specified track.

Spicetify.Player.playUri(uri, context?: any, options?: any);

Parameters​

NameTypeDescription
uristringTrack URI string
contextanyContext of the track. Default is {}
optionsanyOptions of the track. Default is {}

Example​

// 505 - Arctic Monkeys
const trackURI = "spotify:track:0BxE4FqsDD1Ot4YuBXwAPp";

await Spicetify.Player.playUri(trackURI);

removeEventListener​

Unregister added event listener type.

Spicetify.Player.removeEventListener(type, callback);

Parameters​

NameTypeDescription
typestringEvent type
callback(event?: Event) => voidEvent listener

seek​

Seek track to position. Position can be in percentage (0 to 1) or in milisecond.

Spicetify.Player.seek(position);

Parameters​

NameTypeDescription
positionnumberPosition to seek. Can be in percentage (0 to 1) or in milisecond

Example​

// Seek to 50% of track
Spicetify.Player.seek(0.5);

// Seek to 1 minute of track
Spicetify.Player.seek(60000);

setHeart​

Set the heart status of the currently playing track.

Spicetify.Player.setHeart(status);

Parameters​

NameTypeDescription
statusbooleanHeart status

setMute​

Set the mute state of player.

Spicetify.Player.setMute(state);

Parameters​

NameTypeDescription
statebooleanMute state

setRepeat​

Set the repeat mode of player. The value can be:

  • 0 for no repeat.
  • 1 for repeat all.
  • 2 for repeat one.
Spicetify.Player.setRepeat(mode);

Parameters​

NameTypeDescription
modenumberRepeat mode

setShuffle​

Set the shuffle state of player.

Spicetify.Player.setShuffle(state);

Parameters​

NameTypeDescription
statebooleanShuffle state

setVolume​

Set the volume of player. The value is from 0 to 1.

Spicetify.Player.setVolume(level);

Parameters​

NameTypeDescription
levelnumberVolume

toggleHeart​

Toggle the heart state of player / save / unsave the current track from user's library.

Spicetify.Player.toggleHeart();

toggleMute​

Toggle the mute state of player.

Spicetify.Player.toggleMute();

togglePlay​

Toggle the play state of player.

Spicetify.Player.togglePlay();

toggleRepeat​

Toggle the repeat mode of player. The value switches between: No repeat, Repeat all, Repeat one.

Spicetify.Player.toggleRepeat();

toggleShuffle​

Toggle the shuffle state of player.

Spicetify.Player.toggleShuffle();