Player

Player operations live under client.player.

Methods

Method	Returns	Description
`get_playback_state(market=None, additional_types=None)`	`PlaybackState \\| None`	Fetch the current playback state
`transfer_playback(device_id, play=None)`	`None`	Transfer playback to another device
`get_devices()`	`list[PlayerDevice]`	Fetch available playback devices
`get_currently_playing(market=None, additional_types=None)`	`CurrentlyPlaying \\| None`	Fetch the currently playing item
`start_playback(device_id=None, *, context_uri=None, uris=None, offset=None, position_ms=None)`	`None`	Start or resume playback
`pause_playback(device_id=None)`	`None`	Pause playback
`skip_to_next(device_id=None)`	`None`	Skip to the next item
`skip_to_previous(device_id=None)`	`None`	Skip to the previous item
`seek(position_ms, device_id=None)`	`None`	Seek within the current item
`set_repeat_mode(state, device_id=None)`	`None`	Set repeat mode
`set_volume(volume_percent, device_id=None)`	`None`	Set device volume
`set_shuffle(state, device_id=None)`	`None`	Enable or disable shuffle
`get_recently_played(limit=None, after=None, before=None)`	`RecentlyPlayedPage`	Fetch recently played tracks
`get_queue()`	`PlaybackQueue`	Fetch the current playback queue
`add_to_queue(uri, device_id=None)`	`None`	Add an item to the playback queue

Required scopes

Spotify requires user-scoped access tokens for player endpoints. Common scopes include user-read-playback-state, user-modify-playback-state, and user-read-recently-played.

Playback items

Playback responses may contain either tracks or episodes. Pass additional_types=["episode"] or ["track", "episode"] when you want episode playback to be included in the response.

Examples

SyncAsync

from spotify_sdk import SpotifyClient

with SpotifyClient(access_token="your-access-token") as client:
    devices = client.player.get_devices()
    playback = client.player.get_playback_state(
        market="US",
        additional_types=["track", "episode"],
    )
    client.player.start_playback(
        context_uri="spotify:playlist:FAKE_PLAYLIST_ID_123",
        offset=0,
    )
    client.player.set_volume(65)
    client.player.add_to_queue("spotify:track:FAKE_TRACK_ID_456")
    recent = client.player.get_recently_played(limit=5)

import asyncio
from spotify_sdk import AsyncSpotifyClient


async def main() -> None:
    async with AsyncSpotifyClient(access_token="your-access-token") as client:
        devices = await client.player.get_devices()
        playback = await client.player.get_currently_playing(
            market="US",
            additional_types=["episode"],
        )
        await client.player.transfer_playback(
            "FAKE_DEVICE_ID_123",
            play=True,
        )
        await client.player.start_playback(
            device_id="FAKE_DEVICE_ID_123",
            uris=[
                "spotify:track:FAKE_TRACK_ID_456",
                "spotify:episode:FAKE_EPISODE_ID_789",
            ],
            offset=1,
            position_ms=30_000,
        )
        queue = await client.player.get_queue()


asyncio.run(main())

API details

The sync client mirrors these methods, minus the await keywords.

Bases: AsyncBaseService

Playback control and player state operations.

`add_to_queue(uri, device_id=None)` `async`

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

`get_currently_playing(market=None, additional_types=None)` `async`

Get the item currently playing on the user's active device.

Parameters:

Name	Type	Description	Default
`market`	`str \| None`	An ISO 3166-1 alpha-2 country code.	`None`
`additional_types`	`list[Literal['track', 'episode']] \| None`	Additional item types to consider in playback.	`None`

Returns:

Type	Description
`CurrentlyPlaying \| None`	The current item, or `None` if nothing is active.

`get_devices()` `async`

Get the user's available playback devices.

`get_playback_state(market=None, additional_types=None)` `async`

Get the current user's playback state.

Parameters:

Name	Type	Description	Default
`market`	`str \| None`	An ISO 3166-1 alpha-2 country code.	`None`
`additional_types`	`list[Literal['track', 'episode']] \| None`	Additional item types to consider in playback.	`None`

Returns:

Type	Description
`PlaybackState \| None`	The current playback state, or `None` if nothing is active.

`get_queue()` `async`

Get the current user's playback queue.

`get_recently_played(limit=None, after=None, before=None)` `async`

Get the current user's recently played tracks.

Parameters:

Name	Type	Description	Default
`limit`	`int \| None`	Maximum number of items to return (1-50).	`None`
`after`	`int \| None`	Unix timestamp in milliseconds. Returns items after this.	`None`
`before`	`int \| None`	Unix timestamp in milliseconds. Returns items before this.	`None`

Raises:

Type	Description
`ValueError`	If pagination values are invalid.

`pause_playback(device_id=None)` `async`

Pause playback on the user's active device.

`seek(position_ms, device_id=None)` `async`

Seek to a position within the currently playing item.

`set_repeat_mode(state, device_id=None)` `async`

Set the repeat mode for the user's playback.

`set_shuffle(state, device_id=None)` `async`

Enable or disable shuffle for the user's playback.

`set_volume(volume_percent, device_id=None)` `async`

Set the volume for the user's playback device.

`skip_to_next(device_id=None)` `async`

Skip to the next item in the playback queue.

`skip_to_previous(device_id=None)` `async`

Skip to the previous item in the playback queue.

`start_playback(device_id=None, *, context_uri=None, uris=None, offset=None, position_ms=None)` `async`

Start or resume playback on the user's active device.

Parameters:

Name	Type	Description	Default
`device_id`	`str \| None`	Optional Spotify Connect device ID.	`None`
`context_uri`	`str \| None`	Context URI for an album, artist, or playlist.	`None`
`uris`	`list[str] \| None`	Explicit track or episode URIs to play.	`None`
`offset`	`int \| str \| None`	Starting offset as a zero-based position or item URI.	`None`
`position_ms`	`int \| None`	Position in milliseconds to start playback.	`None`

Raises:

Type	Description
`ValueError`	If parameters are empty, conflicting, or invalid.

`transfer_playback(device_id, play=None)` `async`

Transfer playback to another device.

Parameters:

Name	Type	Description	Default
`device_id`	`str`	The target Spotify Connect device ID.	required
`play`	`bool \| None`	Whether playback should start immediately after transfer.	`None`

Raises:

Type	Description
`ValueError`	If `device_id` is empty.

Player

Methods

Examples

API details

add_to_queue(uri, device_id=None) async

get_currently_playing(market=None, additional_types=None) async

get_devices() async

get_playback_state(market=None, additional_types=None) async

get_queue() async

get_recently_played(limit=None, after=None, before=None) async

pause_playback(device_id=None) async

seek(position_ms, device_id=None) async

set_repeat_mode(state, device_id=None) async

set_shuffle(state, device_id=None) async

set_volume(volume_percent, device_id=None) async

skip_to_next(device_id=None) async

skip_to_previous(device_id=None) async

start_playback(device_id=None, *, context_uri=None, uris=None, offset=None, position_ms=None) async

transfer_playback(device_id, play=None) async

`add_to_queue(uri, device_id=None)` `async`

`get_currently_playing(market=None, additional_types=None)` `async`

`get_devices()` `async`

`get_playback_state(market=None, additional_types=None)` `async`

`get_queue()` `async`

`get_recently_played(limit=None, after=None, before=None)` `async`

`pause_playback(device_id=None)` `async`

`seek(position_ms, device_id=None)` `async`

`set_repeat_mode(state, device_id=None)` `async`

`set_shuffle(state, device_id=None)` `async`

`set_volume(volume_percent, device_id=None)` `async`

`skip_to_next(device_id=None)` `async`

`skip_to_previous(device_id=None)` `async`

`start_playback(device_id=None, *, context_uri=None, uris=None, offset=None, position_ms=None)` `async`

`transfer_playback(device_id, play=None)` `async`