PlayerAPI¶

class minim.api.spotify.PlayerAPI(client: APIClient, /)[source]¶

Bases: SpotifyResourceAPI

Player API endpoints for the Spotify Web API.

Important

This class is managed by SpotifyWebAPIClient and should not be instantiated directly.

Parameters:

clientminim.api._shared.APIClient: API client instance used to make HTTP requests.

Methods

`add_to_queue`	Player > Add Item to Playback Queue: Add items to the playback queue.
`get_currently_playing`	Player > Get Currently Playing Track: Get playback state and Spotify catalog information for the currently playing item.
`get_devices`	Player > Get Available Devices: Get available Spotify Connect devices.
`get_playback_state`	Player > Get Playback State: Get the current playback state.
`get_queue`	Player > Get the User's Queue: Get Spotify catalog information for the currently playing and queued items.
`get_recently_played`	Player > Get Recently Played Tracks: Get Spotify catalog information for items recently played by the current user.
`pause_playback`	Player > Pause Playback: Pause playback.
`seek_to_position`	Player > Seek To Position: Seek to a specific position in the currently playing item.
`set_repeat`	Player > Set Repeat Mode: Set playback repeat mode.
`set_shuffle`	Player > Toggle Playback Shuffle: Set playback shuffle state.
`set_volume`	Player > Set Playback Volume: Set playback volume.
`skip_to_next`	Player > Skip To Next: Skip to the next item in the queue.
`skip_to_previous`	Player > Skip To Previous: Skip to the previous item in the queue.
`start_playback`	Player > Start/Resume Playback: Start or resume playback.
`transfer_playback`	Player > Transfer Playback: Transfer playback to a new device.

add_to_queue(uri: str, /, *, device_id: str | None = None) → None[source]¶

Player > Add Item to Playback Queue: Add items to the playback queue.

Authorization scope and subscription

Required

Spotify Premium subscription: Access the PUT /me/player/queue endpoint. Learn more.
user-modify-playback-state scope: Control playback on your Spotify clients and Spotify Connect devices. Learn more.

Parameters:

uristr; positional-only

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

Example: spotify:track:4iV5W9uYEdYUVa79Axb7Rh.

device_idstr; keyword-only; optional

ID of the target playback device. If not specified, the currently active device is the target.

Example: "0d1841b0976bae2a3a310dd74c0f3df354899bc8".

get_currently_playing(*, supported_item_types: str | Collection[str] | None = None, country_code: str | None = None) → dict[str, Any][source]¶

Player > Get Currently Playing Track: Get playback state and Spotify catalog information for the currently playing item.

Authorization scope and third-party application mode

Required

user-read-currently-playing scope: Read your currently playing content. Learn more.

Optional

Extended quota mode before November 27, 2024: Access 30-second preview URLs. Learn more.

Parameters:

supported_item_typesstr or Collection[str]; keyword-only; optional

Item types supported by the client.

Note

This parameter was introduced to allow existing clients to maintain their current behavior and may be deprecated in the future.

Valid values: "track", "episode".

API default: "track".

Examples: "track", "track,episode", ["track", "episode"].

country_codestr; keyword-only; optional

ISO 3166-1 alpha-2 country code. If provided, only content available in that market is returned. When a user access token accompanies the request, the country associated with the user account takes priority over this parameter.

Note

If neither a country code is provided nor a country can be determined from the user account, the content is considered unavailable for the client.

Example: "ES".

Returns:

itemdict[str, Any]

Playback state and Spotify metadata for the currently playing item.

Sample response

{
  "actions": {
    "interrupting_playback": <bool>,
    "pausing": <bool>,
    "resuming": <bool>,
    "seeking": <bool>,
    "skipping_next": <bool>,
    "skipping_prev": <bool>,
    "toggling_repeat_context": <bool>,
    "toggling_repeat_track": <bool>,
    "toggling_shuffle": <bool>,
    "transferring_playback": <bool>
  },
  "context": {
    "external_urls": {
      "spotify": <str>
    },
    "href": <str>,
    "type": <str>,
    "uri": <str>
  },
  "currently_playing_type": <str>,
  "device": {
    "id": <str>,
    "is_active": <bool>,
    "is_private_session": <bool>,
    "is_restricted": <bool>,
    "name": <str>,
    "supports_volume": <bool>,
    "type": <str>,
    "volume_percent": <int>
  },
  "is_playing": <bool>,
  "item": {
    "album": {
      "album_type": <str>,
      "artists": [
        {
          "external_urls": {
            "spotify": <str>
          },
          "href": <str>,
          "id": <str>,
          "name": <str>,
          "type": "artist",
          "uri": <str>
        }
      ],
      "available_markets": <list[str]>,
      "external_urls": {
        "spotify": <str>
      },
      "href": <str>,
      "id": <str>,
      "images": [
        {
          "height": <int>,
          "url": <str>,
          "width": <int>
        }
      ],
      "name": <str>,
      "release_date": <str>,
      "release_date_precision": <str>,
      "restrictions": {
        "reason": <str>
      },
      "total_tracks": <int>,
      "type": "album",
      "uri": <str>
    },
    "artists": [
      {
        "external_urls": {
          "spotify": <str>
        },
        "href": <str>,
        "id": <str>,
        "name": <str>,
        "type": "artist",
        "uri": <str>
      }
    ],
    "available_markets": <list[str]>,
    "disc_number": <int>,
    "duration_ms": <int>,
    "explicit": <bool>,
    "external_ids": {
      "ean": <str>,
      "isrc": <str>,
      "upc": <str>
    },
    "external_urls": {
      "spotify": <str>
    },
    "href": <str>,
    "id": <str>,
    "is_local": <bool>,
    "is_playable": <bool>,
    "linked_from": {
      "external_urls": {
        "spotify": <str>
      },
      "href": <str>,
      "id": <str>,
      "type": "track",
      "uri": <str>
    },
    "name": <str>,
    "popularity": <int>,
    "preview_url": <str>,
    "restrictions": {
      "reason": <str>
    },
    "track_number": <int>,
    "type": "track",
    "uri": <str>
  },
  "progress_ms": <int>,
  "repeat_state": <str>,
  "shuffle_state": <bool>,
  "timestamp": <int>
}

get_devices() → dict[str, list[dict[str, bool | int | str]]][source]¶

Player > Get Available Devices: Get available Spotify Connect devices.

Authorization scope

Required

user-read-playback-state scope: Read your currently playing content and Spotify Connect devices. Learn more.

Returns:

devicesdict[str, list[dict[str, bool | int | str]]]

Metadata of the available Spotify Connect devices.

Sample response

{
  "devices": [
    {
      "id": <str>,
      "is_active": <bool>,
      "is_private_session": <bool>,
      "is_restricted": <bool>,
      "name": <str>,
      "type": <str>,
      "supports_volume": <bool>,
      "volume_percent": <int>
    }
  ]
}

get_playback_state(*, supported_item_types: str | Collection[str] | None = None, country_code: str | None = None) → dict[str, Any][source]¶

Player > Get Playback State: Get the current playback state.

Authorization scope and third-party application mode

Required

user-read-playback-state scope: Read your currently playing content and Spotify Connect devices. Learn more.

Optional

Extended quota mode before November 27, 2024: Access 30-second preview URLs. Learn more.

Parameters:

supported_item_typesstr or Collection[str]; keyword-only; optional

Item types supported by the client.

Note

This parameter was introduced to allow existing clients to maintain their current behavior and may be deprecated in the future.

Valid values: "track", "episode".

API default: "track".

Examples: "track", "track,episode", ["track", "episode"].

country_codestr; keyword-only; optional

Note

If neither a country code is provided nor a country can be determined from the user account, the content is considered unavailable for the client.

Example: "ES".

Returns:

statedict[str, Any]

Playback state and Spotify metadata for the currently playing item.

Sample response

{
  "actions": {
    "interrupting_playback": <bool>,
    "pausing": <bool>,
    "resuming": <bool>,
    "seeking": <bool>,
    "skipping_next": <bool>,
    "skipping_prev": <bool>,
    "toggling_repeat_context": <bool>,
    "toggling_repeat_track": <bool>,
    "toggling_shuffle": <bool>,
    "transferring_playback": <bool>
  },
  "context": {
    "external_urls": {
      "spotify": <str>
    },
    "href": <str>,
    "type": <str>,
    "uri": <str>
  },
  "currently_playing_type": <str>,
  "device": {
    "id": <str>,
    "is_active": <bool>,
    "is_private_session": <bool>,
    "is_restricted": <bool>,
    "name": <str>,
    "supports_volume": <bool>,
    "type": <str>,
    "volume_percent": <int>
  },
  "is_playing": <bool>,
  "item": {
    "album": {
      "album_type": <str>,
      "artists": [
        {
          "external_urls": {
            "spotify": <str>
          },
          "href": <str>,
          "id": <str>,
          "name": <str>,
          "type": "artist",
          "uri": <str>
        }
      ],
      "available_markets": <list[str]>,
      "external_urls": {
        "spotify": <str>
      },
      "href": <str>,
      "id": <str>,
      "images": [
        {
          "height": <int>,
          "url": <str>,
          "width": <int>
        }
      ],
      "name": <str>,
      "release_date": <str>,
      "release_date_precision": <str>,
      "restrictions": {
        "reason": <str>
      },
      "total_tracks": <int>,
      "type": "album",
      "uri": <str>
    },
    "artists": [
      {
        "external_urls": {
          "spotify": <str>
        },
        "href": <str>,
        "id": <str>,
        "name": <str>,
        "type": "artist",
        "uri": <str>
      }
    ],
    "available_markets": <list[str]>,
    "disc_number": <int>,
    "duration_ms": <int>,
    "explicit": <bool>,
    "external_ids": {
      "ean": <str>,
      "isrc": <str>,
      "upc": <str>
    },
    "external_urls": {
      "spotify": <str>
    },
    "href": <str>,
    "id": <str>,
    "is_local": <bool>,
    "is_playable": <bool>,
    "linked_from": {
      "external_urls": {
        "spotify": <str>
      },
      "href": <str>,
      "id": <str>,
      "type": "track",
      "uri": <str>
    },
    "name": <str>,
    "popularity": <int>,
    "preview_url": <str>,
    "restrictions": {
      "reason": <str>
    },
    "track_number": <int>,
    "type": "track",
    "uri": <str>
  },
  "progress_ms": <int>,
  "repeat_state": <str>,
  "shuffle_state": <bool>,
  "timestamp": <int>
}

get_queue() → dict[str, Any][source]¶

Player > Get the User’s Queue: Get Spotify catalog information for the currently playing and queued items.

Authorization scope and third-party application mode

Required

user-read-currently-playing scope: Read your currently playing content. Learn more.
user-read-playback-state scope: Read your currently playing content and Spotify Connect devices. Learn more.

Optional

Extended quota mode before November 27, 2024: Access 30-second preview URLs. Learn more.

Returns:

queuedict[str, Any]

Spotify metadata for the currently playing and queued items.

Sample response

{
  "currently_playing": {
    "album": {
      "album_type": <str>,
      "artists": [
        {
          "external_urls": {
            "spotify": <str>
          },
          "href": <str>,
          "id": <str>,
          "name": <str>,
          "type": "artist",
          "uri": <str>
        }
      ],
      "available_markets": <list[str]>,
      "external_urls": {
        "spotify": <str>
      },
      "href": <str>,
      "id": <str>,
      "images": [
        {
          "height": <int>,
          "url": <str>,
          "width": <int>
        }
      ],
      "name": <str>,
      "release_date": <str>,
      "release_date_precision": <str>,
      "restrictions": {
        "reason": <str>
      },
      "total_tracks": <int>,
      "type": "album",
      "uri": <str>
    },
    "artists": [
      {
        "external_urls": {
          "spotify": <str>
        },
        "href": <str>,
        "id": <str>,
        "name": <str>,
        "type": "artist",
        "uri": <str>
      }
    ],
    "available_markets": <list[str]>,
    "disc_number": <int>,
    "duration_ms": <int>,
    "explicit": <bool>,
    "external_ids": {
      "ean": <str>,
      "isrc": <str>,
      "upc": <str>
    },
    "external_urls": {
      "spotify": <str>
    },
    "href": <str>,
    "id": <str>,
    "is_local": <bool>,
    "is_playable": <bool>,
    "linked_from": {
      "external_urls": {
        "spotify": <str>
      },
      "href": <str>,
      "id": <str>,
      "type": "track",
      "uri": <str>
    },
    "name": <str>,
    "popularity": <int>,
    "preview_url": <str>,
    "restrictions": {
      "reason": <str>
    },
    "track_number": <int>,
    "type": "track",
    "uri": <str>
  },
  "queue": [
    {
      "album": {
        "album_type": <str>,
        "artists": [
          {
            "external_urls": {
              "spotify": <str>
            },
            "href": <str>,
            "id": <str>,
            "name": <str>,
            "type": "artist",
            "uri": <str>
          }
        ],
        "available_markets": <list[str]>,
        "external_urls": {
          "spotify": <str>
        },
        "href": <str>,
        "id": <str>,
        "images": [
          {
            "height": <int>,
            "url": <str>,
            "width": <int>
          }
        ],
        "name": <str>,
        "release_date": <str>,
        "release_date_precision": <str>,
        "restrictions": {
          "reason": <str>
        },
        "total_tracks": <int>,
        "type": "album",
        "uri": <str>
      },
      "artists": [
        {
          "external_urls": {
            "spotify": <str>
          },
          "href": <str>,
          "id": <str>,
          "name": <str>,
          "type": "artist",
          "uri": <str>
        }
      ],
      "available_markets": <list[str]>,
      "disc_number": <int>,
      "duration_ms": <int>,
      "explicit": <bool>,
      "external_ids": {
        "ean": <str>,
        "isrc": <str>,
        "upc": <str>
      },
      "external_urls": {
        "spotify": <str>
      },
      "href": <str>,
      "id": <str>,
      "is_local": <bool>,
      "is_playable": <bool>,
      "linked_from": {
        "external_urls": {
          "spotify": <str>
        },
        "href": <str>,
        "id": <str>,
        "type": "track",
        "uri": <str>
      },
      "name": <str>,
      "popularity": <int>,
      "preview_url": <str>,
      "restrictions": {
        "reason": <str>
      },
      "track_number": <int>,
      "type": "track",
      "uri": <str>
    }
  ]
}

get_recently_played(*, played_after: int | None = None, played_before: int | None = None, limit: int | None = None) → dict[str, Any][source]¶

Player > Get Recently Played Tracks: Get Spotify catalog information for items recently played by the current user.

Authorization scope and third-party application mode

Required

user-read-recently-played scope: Access your recently played items. Learn more.

Optional

Extended quota mode before November 27, 2024: Access 30-second preview URLs. Learn more.

Important

Exactly one of played_after or played_before must be provided.

Parameters:

played_afterint or datetime.datetime; keyword-only; optional

Only return items played after this Unix timestamp, in milliseconds.

Minimum value: 0.

played_beforeint or datetime.datetime; keyword-only; optional

Only return items played before this Unix timestamp, in milliseconds.

Minimum value: 0.

limitint; keyword-only; optional

Maximum number of items to return.

Valid range: 1 to 50.

API default: 20.

Returns:

itemsdict[str, Any]

Page of Spotify metadata for the recently played items.

Sample response

{
  "cursors": {
    "after": <str>,
    "before": <str>
  },
  "href": <str>,
  "items": [
    {
      "context": {
        "external_urls": {
          "spotify": <str>
        },
        "href": <str>,
        "type": <str>,
        "uri": <str>
      },
      "played_at": <str>,
      "track": {
        "album": {
          "album_type": <str>,
          "artists": [
            {
              "external_urls": {
                "spotify": <str>
              },
              "href": <str>,
              "id": <str>,
              "name": <str>,
              "type": "artist",
              "uri": <str>
            }
          ],
          "available_markets": <list[str]>,
          "external_urls": {
            "spotify": <str>
          },
          "href": <str>,
          "id": <str>,
          "images": [
            {
              "height": <int>,
              "url": <str>,
              "width": <int>
            }
          ],
          "name": <str>,
          "release_date": <str>,
          "release_date_precision": <str>,
          "restrictions": {
            "reason": <str>
          },
          "total_tracks": <int>,
          "type": "album",
          "uri": <str>
        },
        "artists": [
          {
            "external_urls": {
              "spotify": <str>
            },
            "href": <str>,
            "id": <str>,
            "name": <str>,
            "type": "artist",
            "uri": <str>
          }
        ],
        "available_markets": <list[str]>,
        "disc_number": <int>,
        "duration_ms": <int>,
        "explicit": <bool>,
        "external_ids": {
          "ean": <str>,
          "isrc": <str>,
          "upc": <str>
        },
        "external_urls": {
          "spotify": <str>
        },
        "href": <str>,
        "id": <str>,
        "is_local": <bool>,
        "is_playable": <bool>,
        "linked_from": {
          "external_urls": {
            "spotify": <str>
          },
          "href": <str>,
          "id": <str>,
          "type": "track",
          "uri": <str>
        },
        "name": <str>,
        "popularity": <int>,
        "preview_url": <str>,
        "restrictions": {
          "reason": <str>
        },
        "track_number": <int>,
        "type": "track",
        "uri": <str>
      }
    }
  ],
  "limit": <int>,
  "next": <str>,
  "total": <int>
}

pause_playback(*, device_id: str | None = None) → None[source]¶

Player > Pause Playback: Pause playback.

Authorization scope and subscription

Required

Spotify Premium subscription: Access the PUT /me/player/pause endpoint. Learn more.
user-modify-playback-state scope: Control playback on your Spotify clients and Spotify Connect devices. Learn more.

Caution

The order of execution is not guaranteed when this endpoint is used with other Player API endpoints in the Spotify Web API.

Parameters:

device_idstr; keyword-only; optional

ID of the target playback device. If not specified, the currently active device is the target.

Example: "0d1841b0976bae2a3a310dd74c0f3df354899bc8".

seek_to_position(position_ms: int, /, *, device_id: str | None = None) → None[source]¶

Player > Seek To Position: Seek to a specific position in the currently playing item.

Authorization scope and subscription

Required

Spotify Premium subscription: Access the PUT /me/player/seek endpoint. Learn more.
user-modify-playback-state scope: Control playback on your Spotify clients and Spotify Connect devices. Learn more.

Caution

The order of execution is not guaranteed when this endpoint is used with other Player API endpoints in the Spotify Web API.

Parameters:

position_msint; positional-only

Playback position to seek to, in milliseconds. If the specified position exceeds the length of the track, the next track will start playing.

Minimum value: 0.

Example: 25_000.

device_idstr; keyword-only; optional

ID of the target playback device. If not specified, the currently active device is the target.

Example: "0d1841b0976bae2a3a310dd74c0f3df354899bc8".

set_repeat(repeat_mode: str, /, *, device_id: str | None = None) → None[source]¶

Player > Set Repeat Mode: Set playback repeat mode.

Authorization scope and subscription

Required

Spotify Premium subscription: Access the PUT /me/player/repeat endpoint. Learn more.
user-modify-playback-state scope: Control playback on your Spotify clients and Spotify Connect devices. Learn more.

Caution

The order of execution is not guaranteed when this endpoint is used with other Player API endpoints in the Spotify Web API.

Parameters:

repeat_modestr; positional-only

Playback repeat mode.

Valid values:

"track" – Repeat the current track.
"context" – Repeat tracks in the current context (album, artist, or playlist).
"off" – Turn repeat off.

device_idstr; keyword-only; optional

ID of the target playback device. If not specified, the currently active device is the target.

Example: "0d1841b0976bae2a3a310dd74c0f3df354899bc8".

set_shuffle(shuffle: bool, /, *, device_id: str | None = None) → None[source]¶

Player > Toggle Playback Shuffle: Set playback shuffle state.

Authorization scope and subscription

Required

Spotify Premium subscription: Access the PUT /me/player/shuffle endpoint. Learn more.
user-modify-playback-state scope: Control playback on your Spotify clients and Spotify Connect devices. Learn more.

Caution

The order of execution is not guaranteed when this endpoint is used with other Player API endpoints in the Spotify Web API.

Parameters:

shufflebool; positional-only

Whether to shuffle playback.

device_idstr; keyword-only; optional

ID of the target playback device. If not specified, the currently active device is the target.

Example: "0d1841b0976bae2a3a310dd74c0f3df354899bc8".

set_volume(volume_percent: int, /, *, device_id: str | None = None) → None[source]¶

Player > Set Playback Volume: Set playback volume.

Authorization scope and subscription

Required

Spotify Premium subscription: Access the PUT /me/player/volume endpoint. Learn more.
user-modify-playback-state scope: Control playback on your Spotify clients and Spotify Connect devices. Learn more.

Caution

The order of execution is not guaranteed when this endpoint is used with other Player API endpoints in the Spotify Web API.

Parameters:

volume_percentint; positional-only

Playback volume as a percentage.

Valid range: 0 to 100.

device_idstr; keyword-only; optional

ID of the target playback device. If not specified, the currently active device is the target.

Example: "0d1841b0976bae2a3a310dd74c0f3df354899bc8".

skip_to_next(*, device_id: str | None = None) → None[source]¶

Player > Skip To Next: Skip to the next item in the queue.

Authorization scope and subscription

Required

Spotify Premium subscription: Access the PUT /me/player/next endpoint. Learn more.
user-modify-playback-state scope: Control playback on your Spotify clients and Spotify Connect devices. Learn more.

Caution

The order of execution is not guaranteed when this endpoint is used with other Player API endpoints in the Spotify Web API.

Parameters:

device_idstr; keyword-only; optional

ID of the target playback device. If not specified, the currently active device is the target.

Example: "0d1841b0976bae2a3a310dd74c0f3df354899bc8".

skip_to_previous(*, device_id: str | None = None) → None[source]¶

Player > Skip To Previous: Skip to the previous item in the queue.

Authorization scope and subscription

Required

Spotify Premium subscription: Access the PUT /me/player/previous endpoint. Learn more.
user-modify-playback-state scope: Control playback on your Spotify clients and Spotify Connect devices. Learn more.

Caution

The order of execution is not guaranteed when this endpoint is used with other Player API endpoints in the Spotify Web API.

Parameters:

device_idstr; keyword-only; optional

ID of the target playback device. If not specified, the currently active device is the target.

Example: "0d1841b0976bae2a3a310dd74c0f3df354899bc8".

Player > Start/Resume Playback: Start or resume playback.

Authorization scope and subscription

Required

Spotify Premium subscription: Access the PUT /me/player/play endpoint. Learn more.
user-modify-playback-state scope: Control playback on your Spotify clients and Spotify Connect devices. Learn more.

Parameters:

urisstr or Collection[str]; positional-only

Spotify URIs to play. For context playback, provide an album, artist, or playlist URI. For item playback, provide one or more track URIs.

Examples:

"spotify:album:1Je1IMUlBXcx1Fz0WE7oPT"
"spotify:track:4iV5W9uYEdYUVa79Axb7Rh"
"spotify:track:4iV5W9uYEdYUVa79Axb7Rh,spotify:track:1301WleyT98MSxVHPZCA6M"
["spotify:track:4iV5W9uYEdYUVa79Axb7Rh", "spotify:track:1301WleyT98MSxVHPZCA6M"]

device_idstr; keyword-only; optional

ID of the target playback device. If not specified, the currently active device is the target.

Example: "0d1841b0976bae2a3a310dd74c0f3df354899bc8".

offsetint or str; keyword-only; optional

Zero-based index or Spotify URI of the item within the context specified by uris at which playback should start. Only applicable when uris contains a context (album, artist, or playlist).

Examples:

5 – Sixth item in the context.
spotify:track:1301WleyT98MSxVHPZCA6M – Specific item in the context.

position_msint; keyword-only; optional

Playback start position within the first track, in milliseconds. If the specified position exceeds the length of the track, playback will start at the next track.

Minimum value: 0.

Example: 25_000.

transfer_playback(device_id: str, /, *, play: bool | None = None) → None[source]¶

Player > Transfer Playback: Transfer playback to a new device.

Authorization scope and subscription

Required

Spotify Premium subscription: Access the PUT /me/player endpoint. Learn more.
user-modify-playback-state scope: Control playback on your Spotify clients and Spotify Connect devices. Learn more.

Caution

The order of execution is not guaranteed when this endpoint is used with other Player API endpoints in the Spotify Web API.

Parameters:

device_idstr; positional-only

ID of the target playback device.

Example: "0d1841b0976bae2a3a310dd74c0f3df354899bc8".

playbool; keyword-only; optional

Whether to start playback on the new device. If True, playback begins immediately. If False, the current playback state is preserved.