API Reference

Main Classes

class pyblu.Player(host: str, port: int = 11000, session: ClientSession | None = None, default_timeout: float = 5.0)
__init__(host: str, port: int = 11000, session: ClientSession | None = None, default_timeout: float = 5.0)

Client for a BluOS player. Uses the HTTP API of the BluOS players to control it.

The passed sessions will not be closed when the player is closed and has to be closed by the caller. If no session is passed, a new session will be created and closed when the player is closed.

Player is an async context manager and can be used with async with.

Parameters:

  • host – The hostname or IP address of the player.

  • port – The port of the player. Default is 11000.

  • session – An optional aiohttp.ClientSession to use for requests.

  • default_timeout – The default timeout in seconds for requests. Can be overridden in each request.

Returns:

A new Player.

async add_follower(ip: str, port: int = 11000, timeout: float | None = None) → list[PairedPlayer]

Add a secondary player to the current player as a follower. If it fails the player won’t be in the returned list.

Parameters:

  • ip – The IP address of the player to add.

  • port – The port of the player to add. Default is 11000.

  • timeout – The timeout in seconds for the request. This overrides the default timeout.

Raises:
Returns:

The list of followers of the player.

async add_followers(followers: list[PairedPlayer], timeout: float | None = None) → list[PairedPlayer]

Add a list of following players to the current player. If it fails the player won’t be in the returned list.

Same as add_follower but with a list of players. Makes only one request to player.

Parameters:

  • followers – The list of players to add.

  • timeout – The timeout in seconds for the request. This overrides the default timeout.

Raises:
Returns:

The list of followers of the player.

async back(timeout: float | None = None) → None

Go back to the previous track.

Parameters:

timeout – The timeout in seconds for the request. This overrides the default timeout.

Raises:
async clear(timeout: float | None = None) → PlayQueue

Clear the play queue.

Parameters:

timeout – The timeout in seconds for the request. This overrides the default timeout.

Raises:
Returns:

The current play queue.

async inputs(timeout: float | None = None) → list[Input]

List all available inputs.

Parameters:

timeout – The timeout in seconds for the request. This overrides the default timeout.

Raises:
Returns:

The list of inputs of the player.

async load_preset(preset_id: int, timeout: float | None = None) → None

Load a preset by ID.

Parameters:

  • timeout – The timeout in seconds for the request. This overrides the default timeout.

  • preset_id – The ID of the preset to load.

Raises:
async pause(toggle: bool | None = None, timeout: float | None = None) → str

Pause the current track. toggle can be used to toggle between playing and pause.

Parameters:

  • toggle – Toggle between playing and pause.

  • timeout – The timeout in seconds for the request. This overrides the default timeout.

Raises:
Returns:

The playback state after command execution.

async play(seek: int | None = None, timeout: float | None = None) → str

Start playing the current track. Can also be used to seek within the current track. Works only when paused, not when stopped.

Parameters:

  • seek – The position in seconds to seek to.

  • timeout – The timeout in seconds for the request. This overrides the default timeout.

Raises:
Returns:

The playback state after command execution.

async play_url(url: str, timeout: float | None = None) → str

Start playing a track from a URL. Can also be used to select inputs. See inputs for available inputs.

Parameters:

  • url – The URL of the track to play.

  • timeout – The timeout in seconds for the request. This overrides the default timeout.

Raises:
Returns:

The playback state after command execution.

async presets(timeout: float | None = None) → list[Preset]

Get the list of presets of the player.

Parameters:

timeout – The timeout in seconds for the request. This overrides the default timeout.

Raises:
Returns:

The list of presets of the player.

async remove_follower(ip: str, port: int = 11000, timeout: float | None = None) → SyncStatus

Remove a following player from the group.

Parameters:

  • ip – The IP address of the player to remove.

  • port – The port of the player to remove. Default is 11000.

  • timeout – The timeout in seconds for the request. This overrides the default timeout.

Raises:
Returns:

The SyncStatus of the player.

async remove_followers(followers: list[PairedPlayer], timeout: float | None = None) → SyncStatus

Remove a list of following players from the group.

Same as remove_follower but with a list of players. Makes only one request to player.

Parameters:

  • followers – The list of players to remove.

  • timeout – The timeout in seconds for the request. This overrides the default timeout.

Raises:
Returns:

The SyncStatus of the player.

async shuffle(shuffle: bool, timeout: float | None = None) → PlayQueue

Set shuffle on current play queue.

Parameters:

  • shuffle – Whether to shuffle the playlist.

  • timeout – The timeout in seconds for the request. This overrides the default timeout.

Raises:
Returns:

The current play queue.

async skip(timeout: float | None = None) → None

Skip to the next track.

Parameters:

timeout – The timeout in seconds for the request. This overrides the default timeout.

Raises:
async sleep_timer(timeout: float | None = None) → int

Set sleep timer. Time steps are 15, 30, 45, 60, 90 minutes. Each call goes to next step. Resets to 0 if called when 90 minutes are set.

Parameters:

timeout – The timeout in seconds for the request. This overrides the default timeout.

Raises:
Returns:

The current sleep timer in minutes. 0 if no sleep timer is set.

async status(etag: str | None = None, poll_timeout: int = 30, timeout: float | None = None) → Status

Get the current status of the player.

This endpoint supports long polling. If etag is set, the server will wait until the status changes or the timeout is reached. etag has to be the last etag received from the server.

poll_timeout has to be smaller than timeout. The default_timout and the default value for poll_timeout do not fulfill this requirement. This means that timeout has to be set when using long polling in most cases.

Parameters:

  • etag – The last etag received from the server. Triggers long polling if set.

  • poll_timeout – The timeout in seconds for long polling. Has to be smaller than timeout.

  • timeout – The timeout in seconds for the request. This overrides the default timeout. Has to be larger than poll_timeout.

Raises:
Returns:

The current status of the player. Only selected fields are returned.

async stop(timeout: float | None = None) → str

Stop the current track. Stopped playback cannot be resumed.

Parameters:

timeout – The timeout in seconds for the request. This overrides the default timeout.

Raises:
Returns:

The playback state after command execution.

async sync_status(etag: str | None = None, poll_timeout: int = 30, timeout: float | None = None) → SyncStatus

Get the SyncStatus of the player.

This endpoint supports long polling. If etag is set, the server will wait until the status changes or the timeout is reached. etag has to be the last etag received from the server.

poll_timeout has to be smaller than timeout. The default_timout and the default value for poll_timeout do not fulfill this requirement. This means that timeout has to be set when using long polling in most cases.

Parameters:

  • etag – The last etag received from the server. Triggers long polling if set.

  • poll_timeout – The timeout in seconds for long polling. Has to be smaller than timeout.

  • timeout – The timeout in seconds for the request. This overrides the default timeout. Has to be larger than poll_timeout.

Raises:
Returns:

The SyncStatus of the player.

async volume(level: int | None = None, mute: bool | None = None, tell_followers: bool | None = None, timeout: float | None = None) → Volume

Get or set the volume of the player. Call without parameters to get the current volume. Call with parameters to set the volume.

Parameters:

  • level – The volume level to set. Range is 0-100.

  • mute – Whether to mute the player.

  • tell_followers – Whether to tell grouped speakers to change their volume as well.

  • timeout – The timeout in seconds for the request. This overrides the default timeout.

Raises:
Returns:

The current volume of the player.

Data Classes

class pyblu.Status(etag: str, input_id: str | None, service: str | None, state: str, shuffle: bool, album: str | None, artist: str | None, name: str | None, image: str | None, volume: int, volume_db: float, mute: bool, mute_volume: int | None, mute_volume_db: float | None, seconds: float | None, total_seconds: float | None, can_seek: bool, sleep: int, group_name: str | None, group_volume: int | None, indexing: bool, stream_url: str | None)
album: str | None

Album name

artist: str | None

Artist name

can_seek: bool

True if the current track can be seeked

etag: str

Cursor for long polling requests. Can be passed to next status call.

group_name: str | None

Name of the group the player is in. Only present on leader.

group_volume: int | None

Volume level of the group. Only present on leader. Range is 0-100.

image: str | None

URL of the album art

indexing: bool

True if the player is currently indexing.

input_id: str | None

Unique id of the input. Is not set for radio.

mute: bool

Mute status

mute_volume: int | None

If the player is muted, then this is the unmuted volume level. Absent if the player is not muted.

mute_volume_db: float | None

If the player is muted, then this is the unmuted volume level in dB. Absent if the player is not muted.

name: str | None

Track name

seconds: float | None

Current playback position in seconds

service: str | None

Service id of current input. ‘Capture’ for regular inputs.

shuffle: bool

Shuffle enabled

sleep: int

Sleep timer in minutes. 0 means the sleep timer is off.

state: str

Playback state

stream_url: str | None

The presence of this element should be treated as a flag and its contents as an opaque value. Seems to be present for radio stations and to be the same as the url from the matching preset(for Radio Stations).

total_seconds: float | None

Total track length in seconds

volume: int

Volume level with a range of 0-100

volume_db: float

Volume level in dB

class pyblu.Volume(volume: int, db: float, mute: bool)
db: float

Volume level in dB

mute: bool

Mute status

volume: int

Volume level with a range of 0-100

class pyblu.SyncStatus(etag: str, id: str, mac: str, name: str, image: str, initialized: bool, group: str | None, leader: pyblu.entities.PairedPlayer | None, followers: list[pyblu.entities.PairedPlayer] | None, zone: str | None, zone_leader: bool | None, zone_follower: bool | None, brand: str, model: str, model_name: str, mute_volume_db: float | None, mute_volume: int | None, volume_db: float, volume: int)
brand: str

Brand name of the player

etag: str

Cursor for long polling requests. Can be passed to next sync_status call.

followers: list[PairedPlayer] | None

List of following players. Only present if the player is leader of a group

group: str | None

Group name of the player

id: str

Player IP and port

image: str

URL of the player image

initialized: bool

True means the player is already setup, false means the player needs to be setup

leader: PairedPlayer | None

Player leading the group. Only present if the player is grouped and not leader itself

mac: str

MAC address of the player

model: str

Model name of the player

model_name: str

Model name of the player

mute_volume: int | None

If the player is muted, then this is the unmuted volume level. Absent if the player is not muted.

mute_volume_db: float | None

If the player is muted, then this is the unmuted volume level in dB. Absent if the player is not muted.

name: str

Name of the player

volume: int

Volume level with a range of 0-100. -1 means fixed volume.

volume_db: float

Volume level in dB

zone: str | None

Name of the zone the player is in. Zones are fixed groups.

zone_follower: bool | None

True if the player is a follower in the zone, false otherwise

zone_leader: bool | None

True if the player is the leader of the zone, false otherwise

class pyblu.PairedPlayer(ip: str, port: int)
ip: str

IP address of the player

port: int

Port of the player

class pyblu.Preset(name: str, id: int, url: str, image: str | None, volume: int | None)
id: int

Unique id of the preset

image: str | None

URL of the preset image

name: str

Name of the preset

url: str

URL of the preset. Can be used with play_url to play the preset

volume: int | None

Volume level with a range of 0-100. None means the volume is not set.

class pyblu.PlayQueue(id: str, shuffle: bool, modified: bool, length: int)
id: str

Unique id for the current play queue state. Changes whenever the play queue changes.

length: int

Number of tracks in the play queue

modified: bool

PlayQueue was modified since it was loaded

shuffle: bool

PlayQueue is shuffled

class pyblu.Input(id: str | None, text: str, image: str, url: str)
id: str | None

Unique id of the input

image: str

URL of the input image

text: str

User friendly name of the input

url: str

URL to play the input. Can be passed to play_url

Exceptions

class pyblu.errors.PlayerError(message: str)

Base class for exceptions in this package.

class pyblu.errors.PlayerUnreachableError(message: str)

Exception raised when the player is not reachable.

This could be due to a timeout or the player being offline.

class pyblu.errors.PlayerUnexpectedResponseError(message: str)

Exception raised when the player returns an unexpected response. This is likely a bug in this library.