Skip to content

Player

API #

Implementation to make API calls with.

Parameters:

get_playback_state #

get_playback_state(*, market: MissingOr[str] = MISSING) -> Player | None

Get information about the user's current playback state, including track or episode, progress, and active device.

Required Authorization Scope

USER_READ_PLAYBACK_STATE

Parameters:

Returns:

  • Player –

    Player information.

  • None –

    If there is no playback state.

transfer_playback #

transfer_playback(device_id: str, *, play: MissingOr[bool] = MISSING) -> None

Transfer playback to a new device and optionally begin playback.

Required Authorization Scope

USER_MODIFY_PLAYBACK_STATE

Premium

This endpoint only works for users who have Spotify Premium.

Parameters:

  • device_id (str) –

    The ID of the device on which playback should be started/transferred.

  • play (bool, default: False ) –

    Whether or not to ensure playback happens on the specified device.

get_available_devices #

get_available_devices() -> list[Device]

Get information about a user's available Spotify Connect devices. Some device models are not supported and will not be listed in the response.

Required Authorization Scope

USER_READ_PLAYBACK_STATE

Returns:

get_currently_playing_track #

get_currently_playing_track(*, market: MissingOr[str] = MISSING) -> PlayerTrack | None

Get the item currently being played on the user's Spotify account.

Required Authorization Scope

USER_READ_CURRENTLY_PLAYING

Parameters:

Returns:

  • PlayerTrack –

    The currently playing item.

  • None –

    If nothing is playing.

start_or_resume_playback #

start_or_resume_playback(*, device_id: MissingOr[str] = MISSING, context_uri: MissingOr[str] = MISSING, track_uris: MissingOr[list[str]] = MISSING, offset: MissingOr[int | str] = MISSING, position: MissingOr[timedelta] = MISSING) -> None

Start a new context or resume current playback on the user's active device.

Required Authorization Scope

USER_MODIFY_PLAYBACK_STATE

Premium

This endpoint only works for users who have Spotify Premium.

Parameters:

  • device_id (str, default: MISSING ) –

    The ID of the device this command is targeting. Default: currently active device.

    Note

    Only one of context_uri and track_uris may be supplied.

  • context_uri (str, default: MISSING ) –

    URI of an album, artist or playlist to play.

  • track_uris (list[str], default: MISSING ) –

    URIs of track(s) to play

  • offset (int | str, default: MISSING ) –

    Indicates where playback should start.

    • int - position where playback should start, 0 being the first item.
    • str - URI of the item to start at.

    Note

    offset can only be used when context_uri is an album or playlist.

  • position (timedelta, default: MISSING ) –

    The position in the (first) item at which to start playback.

pause_playback #

pause_playback(*, device_id: MissingOr[str] = MISSING) -> None

Pause playback on the user's account.

Required Authorization Scope

USER_MODIFY_PLAYBACK_STATE

Premium

This endpoint only works for users who have Spotify Premium.

Parameters:

  • device_id (str, default: MISSING ) –

    The ID of the device this command is targeting. Default: currently active device.

skip_to_next #

skip_to_next(*, device_id: MissingOr[str] = MISSING) -> None

Skip to the next item in the user's queue.

Required Authorization Scope

USER_MODIFY_PLAYBACK_STATE

Premium

This endpoint only works for users who have Spotify Premium.

Parameters:

  • device_id (str, default: MISSING ) –

    The ID of the device this command is targeting. Default: currently active device.

skip_to_previous #

skip_to_previous(*, device_id: MissingOr[str] = MISSING) -> None

Skip to the previous item in the user's queue.

Required Authorization Scope

USER_MODIFY_PLAYBACK_STATE

Premium

This endpoint only works for users who have Spotify Premium.

Parameters:

  • device_id (str, default: MISSING ) –

    The ID of the device this command is targeting. Default: currently active device.

seek_to_position #

seek_to_position(position: timedelta, *, device_id: MissingOr[str] = MISSING) -> None

Seeks to the given position in the user's currently playing track.

Required Authorization Scope

USER_MODIFY_PLAYBACK_STATE

Premium

This endpoint only works for users who have Spotify Premium.

Parameters:

  • position (timedelta) –

    The position to seek to. If this value is longer than the length of the current item, the next item will be played.

  • device_id (str, default: MISSING ) –

    The ID of the device this command is targeting. Default: currently active device.

set_repeat_mode #

set_repeat_mode(state: RepeatState, *, device_id: MissingOr[str] = MISSING) -> None

Set the repeat mode for the user's playback.

Required Authorization Scope

USER_MODIFY_PLAYBACK_STATE

Premium

This endpoint only works for users who have Spotify Premium.

Parameters:

  • state (RepeatState) –

    The repeat state (off/track/context).

  • device_id (str, default: MISSING ) –

    The ID of the device this command is targeting. Default: currently active device.

set_playback_volume #

set_playback_volume(volume_percent: int, *, device_id: MissingOr[str] = MISSING) -> None

Set the volume for the user's current playback device.

Required Authorization Scope

USER_MODIFY_PLAYBACK_STATE

Premium

This endpoint only works for users who have Spotify Premium.

Parameters:

  • volume_percent (int) –

    The volume to set. Must be a value from 0 to 100 inclusive.

  • device_id (str, default: MISSING ) –

    The ID of the device this command is targeting. Default: currently active device.

set_playback_shuffle #

set_playback_shuffle(state: bool, *, device_id: MissingOr[str] = MISSING) -> None

Set shuffle mode for user's playback.

Required Authorization Scope

USER_MODIFY_PLAYBACK_STATE

Premium

This endpoint only works for users who have Spotify Premium.

Parameters:

  • state (bool) –

    Whether or not to shuffle the user's playback.

  • device_id (str, default: MISSING ) –

    The ID of the device this command is targeting. Default: currently active device.

get_recently_played_tracks #

get_recently_played_tracks(*, limit: MissingOr[int] = MISSING, after: MissingOr[datetime] = MISSING, before: MissingOr[datetime] = MISSING) -> CursorPaginator[PlayHistory]

Get tracks from the current user's recently played tracks, starting with the most recently played track and going backwards in history.

Required Authorization Scope

USER_READ_RECENTLY_PLAYED

Note

Currently doesn't support podcast episodes.

Parameters:

  • limit (int, default: 20 ) –

    The maximum number of items to return. Default: 20. Minimum: 1. Maximum: 50.

    Note

    Only one of after and before may be provided.

  • after (datetime, default: MISSING ) –

    Return all items after (but not including) this time.

  • before (datetime, default: MISSING ) –

    Returns all items before (but not including) this time.

get_users_queue #

get_users_queue() -> Queue

Get the items in the user's queue.

Required Authorization Scopes

USER_READ_CURRENTLY_PLAYING & USER_READ_PLAYBACK_STATE

Returns:

add_item_to_playback_queue #

add_item_to_playback_queue(uri: str, *, device_id: MissingOr[str] = MISSING) -> None

Add an item to the end of the user's current playback queue.

Required Authorization Scope

USER_MODIFY_PLAYBACK_STATE

Premium

This endpoint only works for users who have Spotify Premium.

Parameters:

  • uri (str) –

    URI of a track or episode to add to the queue.

  • device_id (str, default: MISSING ) –

    The ID of the device this command is targeting. Default: currently active device.

Player #

Information about the user's current playback state.

context #

context: Context | None

Limited information about the currently playing item.

timestamp #

timestamp: datetime

Time when playback state was last changed (play, pause, skip, scrub, new song, etc.).

progress #

progress: timedelta | None = Field(alias='progress_ms')

Progress into the currently playing track or episode.

is_playing #

is_playing: bool

True if something is currently playing.

item #

item: TrackWithSimpleArtist | Episode | None

The currently playing track or episode.

currently_playing_type #

currently_playing_type: PlayingType

The type of the currently playing item.

actions #

actions: Actions

Actions available to control playback.

device #

device: Device

The device that is currently active.

repeat_state #

repeat_state: RepeatState

Whether or not a repeat is applied to the playback state.

shuffle_state #

shuffle_state: bool

Whether or not shuffle is applied to the playback state.

PlayerTrack #

Information about the user's currently playing item.

context #

context: Context | None

Limited information about the currently playing item.

timestamp #

timestamp: datetime

Time when playback state was last changed (play, pause, skip, scrub, new song, etc.).

progress #

progress: timedelta | None = Field(alias='progress_ms')

Progress into the currently playing track or episode.

is_playing #

is_playing: bool

True if something is currently playing.

item #

item: TrackWithSimpleArtist | Episode | None

The currently playing track or episode.

currently_playing_type #

currently_playing_type: PlayingType

The type of the currently playing item.

actions #

actions: Actions

Actions available to control playback.

Device #

Information about a playback device.

id #

id: str | None

The device ID. This ID is unique and persistent to some extent. However, this is not guaranteed and any cached device id should periodically be cleared out and re-fetched as necessary.

is_active #

is_active: bool

If this device is the currently active device.

is_private_session #

is_private_session: bool

If this device is currently in a private session.

is_restricted #

is_restricted: bool

Whether controlling this device is restricted. At present if this is True then no Web API commands will be accepted by this device.

name #

name: str

A human-readable name for the device. Some devices have a name that the user can configure (e.g. "Loudest speaker") and some devices have a generic name associated with the manufacturer or device model.

type #

type: str

Device type, such as "computer", "smartphone" or "speaker".

Note

I did not add an enum for this field as there no official list of values. This list from 2018 exists, but I don't trust that it is up to date and contains all available devices.

volume_percent #

volume_percent: int | None

The current volume in percent.

supports_volume #

supports_volume: bool

If this device can be used to set the volume.

PlayHistory #

Information about a track on a user's play history.

track #

track: TrackWithSimpleArtist

The track the user listened to.

played_at #

played_at: datetime

The date and time the track was played.

context #

context: Context | None

The context the track was played from.

Queue #

Information about a user's queue.

currently_playing #

currently_playing: Track | Episode | None

The currently playing track or episode.

queue #

queue: list[Track | Episode]

The tracks or episodes in the queue.

Context #

Limited information about the currently playing item.

type #

type: ContextType

The item type.

href #

href: str

A link to the Web API endpoint providing full details of the item.

external_urls #

external_urls: ExternalURLs

External URLs for this context.

uri #

uri: str

The Spotify URI for the context.

Actions #

Actions available to control playback.

interrupting_playback #

interrupting_playback: bool | None = None

Interrupting playback.

pausing #

pausing: bool | None = None

Pausing.

resuming #

resuming: bool | None = None

Resuming.

seeking #

seeking: bool | None = None

Seeking playback position.

skipping_next #

skipping_next: bool | None = None

Skipping to the next context.

skipping_prev #

skipping_prev: bool | None = None

Skipping to the previous context.

toggling_repeat_context #

toggling_repeat_context: bool | None = None

Toggling repeat context flag.

toggling_shuffle #

toggling_shuffle: bool | None = None

Toggling shuffle flag.

toggling_repeat_track #

toggling_repeat_track: bool | None = None

Toggling repeat track flag.

transferring_playback #

transferring_playback: bool | None = None

Transferring playback between devices.