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.
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
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>
}
Key | Description |
---|---|
key | Event type |
value | Array 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
Name | Type | Description |
---|---|---|
type | string | Event type |
callback | (event?: Event) => void | Event 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
Name | Type | Description |
---|---|---|
event | Event | Event 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
Name | Type | Description |
---|---|---|
time | number | Time 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
Name | Type | Description |
---|---|---|
uri | string | Track URI string |
context | any | Context of the track. Default is {} |
options | any | Options 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
Name | Type | Description |
---|---|---|
type | string | Event type |
callback | (event?: Event) => void | Event listener |
seek
Seek track to position. Position can be in percentage (0 to 1) or in milisecond.
Spicetify.Player.seek(position);
Parameters
Name | Type | Description |
---|---|---|
position | number | Position 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
Name | Type | Description |
---|---|---|
status | boolean | Heart status |
setMute
Set the mute state of player.
Spicetify.Player.setMute(state);
Parameters
Name | Type | Description |
---|---|---|
state | boolean | Mute 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
Name | Type | Description |
---|---|---|
mode | number | Repeat mode |
setShuffle
Set the shuffle state of player.
Spicetify.Player.setShuffle(state);
Parameters
Name | Type | Description |
---|---|---|
state | boolean | Shuffle state |
setVolume
Set the volume of player. The value is from 0 to 1.
Spicetify.Player.setVolume(level);
Parameters
Name | Type | Description |
---|---|---|
level | number | Volume |
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();