Player Endpoint Reference

Functions

async add_item_to_playback_queue(client: SpotanticClient, *, uri: SpotifyEpisodeURI | SpotifyTrackURI, device_id: str | None = None) → APICallModel[AddItemToPlaybackQueueRequest, RawAPIResponse, NoneType]

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

Add an item to be played next in the user’s current playback queue. This API only works for users who have Spotify Premium. The order of execution is not guaranteed when you use this API with other Player API endpoints.

Parameters:

client – SpotanticClient instance.
uri – The Spotify URI of the item to add to the queue. Must be a track or episode URI.
device_id – The id of the device this command is targeting. If not supplied, the user’s currently active device is the target.

Returns:

An object containing the request used to obtain the response and the response.

async get_available_devices(client: SpotanticClient) → APICallModel[GetAvailableDevicesRequest, JsonAPIResponse, list[DeviceModel]]

Get information about a user’s available Spotify Connect devices.

Some device models are not supported and will not be listed in the API response.

Parameters:: client – SpotanticClient instance.
Returns:: An object containing the request used to obtain the response, the retrieved data and parsed data as model.

async get_currently_playing_track(client: SpotanticClient, *, additional_types: Sequence[SpotifyItemType] = (SpotifyItemType.TRACK,), market: SpotifyMarketID | None = None) → APICallModel[GetCurrentlyPlayingTrackRequest, JsonAPIResponse, CurrentlyPlayingItemModel]

Get the object currently being played on the user’s Spotify account.

Parameters:

client – SpotanticClient instance.
additional_types – A list of item types that your client supports besides the default track type.
market – An ISO 3166-1 alpha-2 country code.

Returns:

An object containing the request used to obtain the response, the retrieved data and parsed data as model.

async get_playback_state(client: SpotanticClient, *, additional_types: Sequence[SpotifyItemType] = (SpotifyItemType.TRACK,), market: SpotifyMarketID | None = None) → APICallModel[GetPlaybackStateRequest, JsonAPIResponse, PlaybackStateModel]

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

Parameters:

client – SpotanticClient instance.
additional_types – A list of item types that your client supports besides the default track type.
market – An ISO 3166-1 alpha-2 country code.

Returns:

An object containing the request used to obtain the response, the retrieved data and parsed data as model.

async get_recently_played_tracks(client: SpotanticClient, *, limit: int = 20, after: int | None = None, before: int | None = None) → APICallModel[GetRecentlyPlayedTracksRequest, JsonAPIResponse, PagedResultWithCursorsModel[PlayHistoryModel]]

Get tracks from the current user’s recently played tracks.

Parameters:

client – SpotanticClient instance.
limit – The maximum number of items to return. Default is 20. Minimum is 1, maximum is 50.
after – A Unix timestamp in milliseconds. Returns all items after (but not including) this cursor position.
before – A Unix timestamp in milliseconds. Returns all items before (but not including) this cursor position.

Returns:

An object containing the request used to obtain the response, the retrieved data and parsed data as model.

async get_user_queue(client: SpotanticClient) → APICallModel[GetUserQueueRequest, JsonAPIResponse, GetUserQueueResponse]

Get the list of objects that make up the user’s queue.

Parameters:: client – SpotanticClient instance.
Returns:: An object containing the request used to obtain the response, the retrieved data and parsed data as model.

async pause_playback(client: SpotanticClient, *, device_id: str | None = None) → APICallModel[PausePlaybackRequest, RawAPIResponse, NoneType]

Pause playback on the user’s account.

Pause playback on the user’s account. This API only works for users who have Spotify Premium. The order of execution is not guaranteed when you use this API with other Player API endpoints.

Parameters:

client – SpotanticClient instance.
device_id – The id of the device this command is targeting. If not supplied, the user’s currently active device is the target.

Returns:

An object containing the request used to obtain the response and the response.

async seek_to_position(client: SpotanticClient, *, position_ms: int, device_id: str | None = None) → APICallModel[SeekToPositionRequest, RawAPIResponse, NoneType]

Seek to position in currently playing track.

Seeks to the given position in the user’s currently playing track. This API only works for users who have Spotify Premium. The order of execution is not guaranteed when you use this API with other Player API endpoints.

Parameters:

client – SpotanticClient instance.
position_ms – The position in milliseconds to seek to.
device_id – The id of the device this command is targeting. If not supplied, the user’s currently active device is the target.

Returns:

An object containing the request used to obtain the response and the response.

async set_playback_volume(client: SpotanticClient, *, volume_percent: int, device_id: str | None = None) → APICallModel[SetPlaybackVolumeRequest, RawAPIResponse, NoneType]

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

Set the volume for the user’s current playback device. This API only works for users who have Spotify Premium. The order of execution is not guaranteed when you use this API with other Player API endpoints.

Parameters:

client – SpotanticClient instance.
volume_percent – The volume to set. Must be a value from 0 to 100 inclusive.
device_id – The id of the device this command is targeting. If not supplied, the user’s currently active device is the target.

Returns:

An object containing the request used to obtain the response and the response.

async set_repeat_mode(client: SpotanticClient, *, state: RepeatMode, device_id: str | None = None) → APICallModel[SetRepeatModeRequest, RawAPIResponse, NoneType]

Set the repeat mode for the user’s current playback device.

Set the repeat mode for the user’s playback. This API only works for users who have Spotify Premium. The order of execution is not guaranteed when you use this API with other Player API endpoints.

Parameters:

client – SpotanticClient instance.
state – The repeat mode to set.
device_id – The id of the device this command is targeting. If not supplied, the user’s currently active device is the target.

Returns:

An object containing the request used to obtain the response and the response.

async skip_to_next(client: SpotanticClient, *, device_id: str | None = None) → APICallModel[SkipToNextRequest, RawAPIResponse, NoneType]

Skip to next track in the user’s queue.

Skips to next track in the user’s queue. This API only works for users who have Spotify Premium. The order of execution is not guaranteed when you use this API with other Player API endpoints.

Parameters:

client – SpotanticClient instance.
device_id – The id of the device this command is targeting. If not supplied, the user’s currently active device is the target.

Returns:

An object containing the request used to obtain the response and the response.

async skip_to_previous(client: SpotanticClient, *, device_id: str | None = None) → APICallModel[SkipToPreviousRequest, RawAPIResponse, NoneType]

Skip to previous track in the user’s queue.

Skips to previous track in the user’s queue. This API only works for users who have Spotify Premium. The order of execution is not guaranteed when you use this API with other Player API endpoints.

Parameters:

client – SpotanticClient instance.
device_id – The id of the device this command is targeting. If not supplied, the user’s currently active device is the target.

Returns:

An object containing the request used to obtain the response and the response.

Start or resume the user’s playback.

Start a new context or resume current playback on the user’s active device. This API only works for users who have Spotify Premium. The order of execution is not guaranteed when you use this API with other Player API endpoints.

Parameters:

client – SpotanticClient instance.
device_id – The id of the device this command is targeting. If not supplied, the user’s currently active device is the target.
context_uri – Spotify URI of the context to play. Valid contexts are albums, artists, and playlists.
uris – A list of Spotify track URIs to play.
offset – Indicates from where in the context playback should start. If an integer is provided, it is treated as a position index in the context. If a Spotify track URI is provided, playback will start from that track.
position_ms – Indicates the position in milliseconds to start playback.

Returns:

An object containing the request used to obtain the response and the response.

async toggle_playback_shuffle(client: SpotanticClient, *, state: bool, device_id: str | None = None) → APICallModel[TogglePlaybackShuffleRequest, RawAPIResponse, NoneType]

Toggle shuffle state for user’s playback.

Toggle shuffle on or off for user’s playback. This API only works for users who have Spotify Premium. The order of execution is not guaranteed when you use this API with other Player API endpoints.

Parameters:

client – SpotanticClient instance.
state – True to turn shuffle on, false to turn it off.
device_id – The id of the device this command is targeting. If not supplied, the user’s currently active device is the target.

Returns:

An object containing the request used to obtain the response and the response.

async transfer_playback(client: SpotanticClient, *, device_ids: Sequence[str], play: bool | None = None) → APICallModel[TransferPlaybackRequest, RawAPIResponse, NoneType]

Transfer playback to a new device.

Transfer playback to a new device and optionally begin playback. This API only works for users who have Spotify Premium. The order of execution is not guaranteed when you use this API with other Player API endpoints.

Parameters:

client – SpotanticClient instance.
device_ids – A list of the device IDs on which playback should be started/transferred to.
play – True to enable playback on the new device. If false or not provided, the user’s current playback will continue on the previous device.

Returns:

An object containing the request used to obtain the response and the response.

Request models

class AddItemToPlaybackQueueRequest(*, required_scopes: set[AuthScope] = {AuthScope.USER_MODIFY_PLAYBACK_STATE}, url: HttpUrl | None = None, endpoint: str | None = 'me/player/queue', method_type: HTTPMethod = <HTTPMethod.POST>, headers: RequestHeadersModel = <factory>, params: AddItemToPlaybackQueueRequestParams | None = None, body: None = None)

Bases: RequestModel[AddItemToPlaybackQueueRequestParams, NoneType]

Request model for Add Item To Playback Queue request.

classmethod build(*, uri: SpotifyEpisodeURI | SpotifyTrackURI, device_id: str | None = None) → AddItemToPlaybackQueueRequest

Builds a request model based on given parameters.

The function automatically determines the endpoint if it is not static. Also, it automatically assigns parameters to request query or body.

Parameters:

uri – The Spotify URI of the item to add to the queue.
device_id – The id of the device this command is targeting.

Returns:

Validated Request object.

endpoint: str | None: Endpoint associated with the request.

method_type: HTTPMethod: HTTP method type for the request.

required_scopes: set[AuthScope]: Required authorization scopes for the request.

class AddItemToPlaybackQueueRequestParams(*, uri: SpotifyEpisodeURI | SpotifyTrackURI, device_id: str | None = None)

Bases: BaseModel

Params model for Add Item To Playback Queue request.

device_id: str | None: The id of the device this command is targeting.

uri: SpotifyEpisodeURI | SpotifyTrackURI: The Spotify URI of the item to add to the queue

class GetAvailableDevicesRequest(*, required_scopes: set[AuthScope] = {AuthScope.USER_READ_PLAYBACK_STATE}, url: HttpUrl | None = None, endpoint: str | None = 'me/player/devices', method_type: HTTPMethod = <HTTPMethod.GET>, headers: RequestHeadersModel = <factory>, params: None = None, body: None = None)

Bases: RequestModel[NoneType, NoneType]

Request model for Get Available Devices endpoint.

classmethod build() → GetAvailableDevicesRequest

Builds a request model.

The function automatically determines the endpoint if it is not static. Also, it automatically assigns parameters to request query or body.

Returns:: Validated Request object.

endpoint: str | None: Endpoint associated with the request.

method_type: HTTPMethod: HTTP method for the request.

required_scopes: set[AuthScope]: Required authorization scopes for the request.

class GetCurrentlyPlayingTrackRequest(*, required_scopes: set[AuthScope] = {AuthScope.USER_READ_CURRENTLY_PLAYING}, url: HttpUrl | None = None, endpoint: str | None = 'me/player/currently-playing', method_type: HTTPMethod = <HTTPMethod.GET>, headers: RequestHeadersModel = <factory>, params: GetCurrentlyPlayingTrackRequestParams | None = None, body: None = None)

Bases: RequestModel[GetCurrentlyPlayingTrackRequestParams, NoneType]

Request model for Get Currently Playing Track endpoint.

classmethod build(*, additional_types: Sequence[SpotifyItemType] = (SpotifyItemType.TRACK,), market: SpotifyMarketID | None = None) → GetCurrentlyPlayingTrackRequest

Builds a request model based on given parameters.

The function automatically determines the endpoint if it is not static. Also, it automatically assigns parameters to request query or body.

Parameters:

additional_types – A list of item types that your client supports besides the default track type.
market – An ISO 3166-1 alpha-2 country code.

Returns:

Validated Request object.

endpoint: str | None: Endpoint associated with the request.

method_type: HTTPMethod: HTTP method for the request.

required_scopes: set[AuthScope]: Required authorization scopes for the request.

class GetCurrentlyPlayingTrackRequestParams(*, additional_types: Annotated[Sequence[SpotifyItemType], PlainSerializer(func=sequence_to_comma_separated_str, return_type=str, when_used=always)], market: SpotifyMarketID | None = None)

Bases: BaseModel

Params model for Get Currently Playing Track request.

classmethod check_value_is_playback_supported(value: Sequence[SpotifyItemType]) → Sequence[SpotifyItemType]

Validates that the provided item types are supported by playback.

Parameters:: value – The sequence of Spotify item types to validate.
Returns:: The validated sequence of Spotify item types.
Raises:: ValueError – If any of the provided item types are not supported by playback.

additional_types: Annotated[Sequence[SpotifyItemType], PlainSerializer(sequence_to_comma_separated_str, return_type=str)]: A list of item types that your client supports besides the default track type.

market: SpotifyMarketID | None: An ISO 3166-1 alpha-2 country code.

class GetPlaybackStateRequest(*, required_scopes: set[AuthScope] = {AuthScope.USER_READ_PLAYBACK_STATE}, url: HttpUrl | None = None, endpoint: str | None = 'me/player', method_type: HTTPMethod = <HTTPMethod.GET>, headers: RequestHeadersModel = <factory>, params: GetPlaybackStateRequestParams | None = None, body: None = None)

Bases: RequestModel[GetPlaybackStateRequestParams, NoneType]

Request model for Get Playback State endpoint.

classmethod build(*, additional_types: Sequence[SpotifyItemType] = (SpotifyItemType.TRACK,), market: SpotifyMarketID | None = None) → GetPlaybackStateRequest

Builds a request model based on given parameters.

The function automatically determines the endpoint if it is not static. Also, it automatically assigns parameters to request query or body.

Parameters:

additional_types – A list of item types that your client supports besides the default track type.
market – An ISO 3166-1 alpha-2 country code.

Returns:

Validated Request object.

endpoint: str | None: Endpoint associated with the request.

method_type: HTTPMethod: HTTP method for the request.

required_scopes: set[AuthScope]: Required authorization scopes for the request.

class GetPlaybackStateRequestParams(*, additional_types: Annotated[Sequence[SpotifyItemType], PlainSerializer(func=sequence_to_comma_separated_str, return_type=str, when_used=always)], market: SpotifyMarketID | None = None)

Bases: BaseModel

Params model for Get Playback State request.

classmethod check_value_is_playback_supported(value: Sequence[SpotifyItemType]) → Sequence[SpotifyItemType]

Validates that the provided item types are supported by playback.

Parameters:: value – The sequence of Spotify item types to validate.
Returns:: The validated sequence of Spotify item types.
Raises:: ValueError – If any of the provided item types are not supported by playback.

additional_types: Annotated[Sequence[SpotifyItemType], PlainSerializer(sequence_to_comma_separated_str, return_type=str)]: A list of item types that your client supports besides the default track type.

market: SpotifyMarketID | None: An ISO 3166-1 alpha-2 country code.

class GetRecentlyPlayedTracksRequest(*, required_scopes: set[AuthScope] = {AuthScope.USER_READ_RECENTLY_PLAYED}, url: HttpUrl | None = None, endpoint: str | None = 'me/player/recently-played', method_type: HTTPMethod = <HTTPMethod.GET>, headers: RequestHeadersModel = <factory>, params: GetRecentlyPlayedTracksRequestParams | None = None, body: None = None)

Bases: RequestModel[GetRecentlyPlayedTracksRequestParams, NoneType]

Request model for Get Recently Played Tracks endpoint.

classmethod build(*, limit: int = 20, after: int | None = None, before: int | None = None) → GetRecentlyPlayedTracksRequest

Builds a request model based on given parameters.

The function automatically determines the endpoint if it is not static. Also, it automatically assigns parameters to request query or body.

Parameters:

limit – The maximum number of items to return.
after – A Unix timestamp in milliseconds.
before – A Unix timestamp in milliseconds.

Returns:

Validated Request object.

endpoint: str | None: Endpoint associated with the request.

method_type: HTTPMethod: HTTP method for the request.

required_scopes: set[AuthScope]: Required authorization scopes for the request.

class GetRecentlyPlayedTracksRequestParams(*, limit: Annotated[int, Ge(ge=1), Le(le=50)], after: int | None = None, before: int | None = None)

Bases: BaseModel

Params model for Get Recently Played Tracks request.

check_only_cursor_is_given() → GetRecentlyPlayedTracksRequestParams

Validates that only one of after or before is provided.

Returns:: The validated model.
Raises:: ValueError – If both after and before are provided.

after: int | None: A Unix timestamp in milliseconds.

before: int | None: A Unix timestamp in milliseconds.

limit: Annotated[int, Field(ge=1, le=50)]: The maximum number of items to return.

class GetUserQueueRequest(*, required_scopes: set[AuthScope] = {AuthScope.USER_READ_CURRENTLY_PLAYING, AuthScope.USER_READ_PLAYBACK_STATE}, url: HttpUrl | None = None, endpoint: str | None = 'me/player/queue', method_type: HTTPMethod = <HTTPMethod.GET>, headers: RequestHeadersModel = <factory>, params: None = None, body: None = None)

Bases: RequestModel[NoneType, NoneType]

Request model for Get User Queue endpoint.

classmethod build() → GetUserQueueRequest

Builds a request model.

The function automatically determines the endpoint if it is not static. Also, it automatically assigns parameters to request query or body.

Returns:: Validated Request object.

endpoint: str | None: Endpoint associated with the request.

method_type: HTTPMethod: HTTP method for the request.

required_scopes: set[AuthScope]: Required authorization scopes for the request.

class PausePlaybackRequest(*, required_scopes: set[AuthScope] = {AuthScope.USER_MODIFY_PLAYBACK_STATE}, url: HttpUrl | None = None, endpoint: str | None = 'me/player/pause', method_type: HTTPMethod = <HTTPMethod.PUT>, headers: RequestHeadersModel = <factory>, params: PausePlaybackRequestParams | None = None, body: None = None)

Bases: RequestModel[PausePlaybackRequestParams, NoneType]

Request model for Pause Playback endpoint.

classmethod build(*, device_id: str | None = None) → PausePlaybackRequest

Builds a request model based on given parameters.

The function automatically determines the endpoint if it is not static. Also, it automatically assigns parameters to request query or body.

Parameters:: device_id – The id of the device this command is targeting.
Returns:: Validated Request object.

endpoint: str | None: Endpoint associated with the request.

method_type: HTTPMethod: HTTP method for the request.

required_scopes: set[AuthScope]: Required authorization scopes for the request.

class PausePlaybackRequestParams(*, device_id: str | None = None)

Bases: BaseModel

Params model for Pause Playback request.

device_id: str | None: The id of the device this command is targeting.

class SeekToPositionRequest(*, required_scopes: set[AuthScope] = {AuthScope.USER_MODIFY_PLAYBACK_STATE}, url: HttpUrl | None = None, endpoint: str | None = 'me/player/seek', method_type: HTTPMethod = <HTTPMethod.PUT>, headers: RequestHeadersModel = <factory>, params: SeekToPositionRequestParams | None = None, body: None = None)

Bases: RequestModel[SeekToPositionRequestParams, NoneType]

Request model for Seek To Position endpoint.

classmethod build(*, position_ms: int, device_id: str | None = None) → SeekToPositionRequest

Builds a request model based on given parameters.

The function automatically determines the endpoint if it is not static. Also, it automatically assigns parameters to request query or body.

Parameters:

position_ms – The position in milliseconds to seek to.
device_id – The id of the device this command is targeting.

Returns:

Validated Request object.

endpoint: str | None: Endpoint associated with the request.

method_type: HTTPMethod: HTTP method for the request.

required_scopes: set[AuthScope]: Required authorization scopes for the request.

class SeekToPositionRequestParams(*, position_ms: int, device_id: str | None = None)

Bases: BaseModel

Params model for Seek To Position request.

device_id: str | None: The id of the device this command is targeting.

position_ms: int: The position in milliseconds to seek to.

class SetPlaybackVolumeRequest(*, required_scopes: set[AuthScope] = {AuthScope.USER_MODIFY_PLAYBACK_STATE}, url: HttpUrl | None = None, endpoint: str | None = 'me/player/volume', method_type: HTTPMethod = <HTTPMethod.PUT>, headers: RequestHeadersModel = <factory>, params: SetPlaybackVolumeRequestParams | None = None, body: None = None)

Bases: RequestModel[SetPlaybackVolumeRequestParams, NoneType]

Request model for Set Playback Volume endpoint.

classmethod build(*, volume_percent: int, device_id: str | None = None) → SetPlaybackVolumeRequest

Builds a request model based on given parameters.

The function automatically determines the endpoint if it is not static. Also, it automatically assigns parameters to request query or body.

Parameters:

volume_percent – The volume to set. Must be a value from 0 to 100 inclusive.
device_id – The id of the device this command is targeting.

Returns:

Validated Request object.

endpoint: str | None: Endpoint associated with the request.

method_type: HTTPMethod: HTTP method for the request.

required_scopes: set[AuthScope]: Required authorization scopes for the request.

class SetPlaybackVolumeRequestParams(*, volume_percent: Annotated[int, Ge(ge=0), Le(le=100)], device_id: str | None = None)

Bases: BaseModel

Params model for Set Playback Volume request.

device_id: str | None: The id of the device this command is targeting.

volume_percent: Annotated[int, Field(ge=0, le=100)]: The volume to set. Must be a value from 0 to 100 inclusive.

class SetRepeatModeRequest(*, required_scopes: set[AuthScope] = {AuthScope.USER_MODIFY_PLAYBACK_STATE}, url: HttpUrl | None = None, endpoint: str | None = 'me/player/repeat', method_type: HTTPMethod = <HTTPMethod.PUT>, headers: RequestHeadersModel = <factory>, params: SetRepeatModeRequestParams | None = None, body: None = None)

Bases: RequestModel[SetRepeatModeRequestParams, NoneType]

Request model for Set Repeat Mode endpoint.

classmethod build(*, state: RepeatMode, device_id: str | None = None) → SetRepeatModeRequest

Builds a request model based on given parameters.

The function automatically determines the endpoint if it is not static. Also, it automatically assigns parameters to request query or body.

Parameters:

state – The repeat mode to set.
device_id – The id of the device this command is targeting.

Returns:

Validated Request object.

endpoint: str | None: Endpoint associated with the request.

method_type: HTTPMethod: HTTP method for the request.

required_scopes: set[AuthScope]: Required authorization scopes for the request.

class SetRepeatModeRequestParams(*, state: RepeatMode, device_id: str | None = None)

Bases: BaseModel

Params model for Set Repeat Mode request.

device_id: str | None: The id of the device this command is targeting.

state: RepeatMode: The repeat mode to set.

class SkipToNextRequest(*, required_scopes: set[AuthScope] = {AuthScope.USER_MODIFY_PLAYBACK_STATE}, url: HttpUrl | None = None, endpoint: str | None = 'me/player/next', method_type: HTTPMethod = <HTTPMethod.POST>, headers: RequestHeadersModel = <factory>, params: SkipToNextRequestParams | None = None, body: None = None)

Bases: RequestModel[SkipToNextRequestParams, NoneType]

Request model for Skip To Next endpoint.

classmethod build(*, device_id: str | None = None) → SkipToNextRequest

Builds a request model based on given parameters.

The function automatically determines the endpoint if it is not static. Also, it automatically assigns parameters to request query or body.

Parameters:: device_id – The id of the device this command is targeting.
Returns:: Validated Request object.

endpoint: str | None: Endpoint associated with the request.

method_type: HTTPMethod: HTTP method for the request.

required_scopes: set[AuthScope]: Required authorization scopes for the request.

class SkipToNextRequestParams(*, device_id: str | None = None)

Bases: BaseModel

Params model for Skip To Next request.

device_id: str | None: The id of the device this command is targeting.

class SkipToPreviousRequest(*, required_scopes: set[AuthScope] = {AuthScope.USER_MODIFY_PLAYBACK_STATE}, url: HttpUrl | None = None, endpoint: str | None = 'me/player/previous', method_type: HTTPMethod = <HTTPMethod.POST>, headers: RequestHeadersModel = <factory>, params: SkipToPreviousRequestParams | None = None, body: None = None)

Bases: RequestModel[SkipToPreviousRequestParams, NoneType]

Request model for Skip To Previous endpoint.

classmethod build(*, device_id: str | None = None) → SkipToPreviousRequest

Builds a request model based on given parameters.

The function automatically determines the endpoint if it is not static. Also, it automatically assigns parameters to request query or body.

Parameters:: device_id – The id of the device this command is targeting.
Returns:: Validated Request object.

endpoint: str | None: Endpoint associated with the request.

method_type: HTTPMethod: HTTP method for the request.

required_scopes: set[AuthScope]: Required authorization scopes for the request.

class SkipToPreviousRequestParams(*, device_id: str | None = None)

Bases: BaseModel

Params model for Skip To Previous request.

device_id: str | None: The id of the device this command is targeting.

class StartResumePlaybackRequest(*, required_scopes: set[AuthScope] = {AuthScope.USER_MODIFY_PLAYBACK_STATE}, url: HttpUrl | None = None, endpoint: str | None = 'me/player/play', method_type: HTTPMethod = <HTTPMethod.PUT>, headers: RequestHeadersModel = RequestHeadersModel(content_type='application/json', content_length=None, content_encoding=None, content_language=None), params: StartResumePlaybackRequestParams | None = None, body: StartResumePlaybackRequestBody | None = None)

Bases: RequestModel[StartResumePlaybackRequestParams, StartResumePlaybackRequestBody]

Request model for Start/Resume Playback endpoint.

Builds a request model based on given parameters.

The function automatically determines the endpoint if it is not static. Also, it automatically assigns parameters to request query or body.

Parameters:

device_id – The id of the device this command is targeting.
context_uri – Spotify URI of the context to play.
uris – A list of Spotify track URIs to play.
offset – Indicates from where in the context playback should start.
position_ms – Indicates the position in milliseconds to start playback.

Returns:

Validated Request object.

endpoint: str | None: Endpoint associated with the request.

headers: RequestHeadersModel: Headers for the request.

method_type: HTTPMethod: HTTP method for the request.

required_scopes: set[AuthScope]: Required authorization scopes for the request.

Bases: RequestBodyJsonModel

Body model for Start/Resume Playback request.

validate_body_data() → StartResumePlaybackRequestBody

Validates the body data according to Spotify API rules.

Returns:: The validated body model instance.
Raises:: ValueError – If validation fails.

context_uri: SpotifyAlbumURI | SpotifyArtistURI | SpotifyPlaylistURI | None: Spotify URI of the context to play.

offset: PositionOffsetModel | URIOffsetModel | None: Indicates from where in the context playback should start.

position_ms: int | None: Indicates the position in milliseconds to start playback.

uris: Sequence[SpotifyTrackURI] | None: A list of Spotify track URIs to play.

class StartResumePlaybackRequestParams(*, device_id: str | None = None)

Bases: BaseModel

Params model for Start/Resume Playback request.

device_id: str | None: The id of the device this command is targeting.

class TogglePlaybackShuffleRequest(*, required_scopes: set[AuthScope] = {AuthScope.USER_MODIFY_PLAYBACK_STATE}, url: HttpUrl | None = None, endpoint: str | None = 'me/player/shuffle', method_type: HTTPMethod = <HTTPMethod.PUT>, headers: RequestHeadersModel = <factory>, params: TogglePlaybackShuffleRequestParams | None = None, body: None = None)

Bases: RequestModel[TogglePlaybackShuffleRequestParams, NoneType]

Request model for Toggle Playback Shuffle endpoint.

classmethod build(*, state: bool, device_id: str | None = None) → TogglePlaybackShuffleRequest

Builds a request model based on given parameters.

The function automatically determines the endpoint if it is not static. Also, it automatically assigns parameters to request query or body.

Parameters:

state – Whether to shuffle the playback or not.
device_id – The id of the device this command is targeting.

Returns:

Validated Request object.

endpoint: str | None: Endpoint associated with the request.

method_type: HTTPMethod: HTTP method for the request.

required_scopes: set[AuthScope]: Required authorization scopes for the request.

class TogglePlaybackShuffleRequestParams(*, state: ~typing.Annotated[bool, ~pydantic.functional_serializers.PlainSerializer(func=~spotantic.models.player.requests._toggle_playback_shuffle.<lambda>, return_type=str, when_used=always)], device_id: str | None = None)

Bases: BaseModel

Params model for Toggle Playback Shuffle request.

device_id: str | None: The id of the device this command is targeting.

state: Annotated[bool, PlainSerializer(lambda flag: str(flag).lower(), return_type=str)]: Whether to shuffle the playback or not.

class TransferPlaybackRequest(*, required_scopes: set[AuthScope] = {AuthScope.USER_MODIFY_PLAYBACK_STATE}, url: HttpUrl | None = None, endpoint: str | None = 'me/player', method_type: HTTPMethod = <HTTPMethod.PUT>, headers: RequestHeadersModel = RequestHeadersModel(content_type='application/json', content_length=None, content_encoding=None, content_language=None), params: None = None, body: TransferPlaybackRequestBody | None = None)

Bases: RequestModel[NoneType, TransferPlaybackRequestBody]

Request model for Transfer Playback endpoint.

classmethod build(*, device_ids: Sequence[str], play: bool | None = None) → TransferPlaybackRequest

Builds a request model based on given parameters.

The function automatically determines the endpoint if it is not static. Also, it automatically assigns parameters to request query or body.

Parameters:

device_ids – A list of device IDs to transfer playback to.
play – True to start playback on the new device. If false or not provided, the user’s current playback will continue on the previous device.

Returns:

Validated Request object.

endpoint: str | None: Endpoint associated with the request.

headers: RequestHeadersModel: Headers for the request.

method_type: HTTPMethod: HTTP method for the request.

required_scopes: set[AuthScope]: Required authorization scopes for the request.

class TransferPlaybackRequestBody(*, device_ids: Annotated[Sequence[str], MaxLen(max_length=1)], play: bool | None = None)

Bases: RequestBodyJsonModel

Body model for Transfer Playback request.

device_ids: Annotated[Sequence[str], Field(max_length=1)]: A list of device IDs to transfer playback to.

play: bool | None: True to start playback on the new device. If false or not provided, the user’s current playback will continue on the previous device.

Response models

class GetAvailableDevicesResponse(*, devices: list[DeviceModel])

Bases: BaseModel

Response model for Get Available Devices endpoint.

devices: list[DeviceModel]: List of devices.

class GetUserQueueResponse(*, currently_playing: TrackModel | EpisodeModel | None = None, queue: list[Annotated[TrackModel | EpisodeModel, FieldInfo(annotation=NoneType, required=True, discriminator='item_type')]])

Bases: BaseModel

Response model for Get User Queue endpoint.

currently_playing: TrackModel | EpisodeModel | None: The currently playing track or episode.

queue: list[Annotated[TrackModel | EpisodeModel, FieldInfo(annotation=NoneType, required=True, discriminator='item_type')]]: The tracks or episodes in the queue.