pyblu 2.0.2__py2.py3-none-any.whl

pyblu/__init__.py

@@ -0,0 +1,6 @@
+"""A Python library for controlling BluOS players."""
+
+from .player import Player
+from .entities import Status, Volume, SyncStatus, PairedPlayer, PlayQueue, Preset, Input
+
+__all__ = ["Player", "Status", "Volume", "SyncStatus", "PairedPlayer", "PlayQueue", "Preset", "Input"]

pyblu/entities.py

@@ -0,0 +1,165 @@
+from dataclasses import dataclass
+
+
+@dataclass
+class Status:
+    etag: str
+    """Cursor for long polling requests. Can be passed to next status call."""
+
+    input_id: str | None
+    """Unique id of the input. Is not set for radio."""
+    service: str | None
+    """Service id of current input. 'Capture' for regular inputs."""
+
+    state: str
+    """Playback state"""
+    shuffle: bool
+    """Shuffle enabled"""
+
+    album: str | None
+    """Album name"""
+    artist: str | None
+    """Artist name"""
+    name: str | None
+    """Track name"""
+    image: str | None
+    """URL of the album art"""
+
+    volume: int
+    """Volume level with a range of 0-100"""
+    volume_db: float
+    """Volume level in dB"""
+
+    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."""
+
+    seconds: float | None
+    """Current playback position in seconds"""
+    total_seconds: float | None
+    """Total track length in seconds"""
+    can_seek: bool
+    """True if the current track can be seeked"""
+
+    sleep: int
+    """Sleep timer in minutes. 0 means the sleep timer is off."""
+
+    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."""
+
+    indexing: bool
+    """True if the player is currently indexing."""
+
+    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)."""
+
+
+@dataclass
+class PairedPlayer:
+    ip: str
+    """IP address of the player"""
+    port: int
+    """Port of the player"""
+
+
+@dataclass
+class SyncStatus:
+    etag: str
+    """Cursor for long polling requests. Can be passed to next sync_status call."""
+
+    id: str
+    """Player IP and port"""
+    mac: str
+    """MAC address of the player"""
+    name: str
+    """Name of the player"""
+
+    image: str
+    """URL of the player image"""
+    initialized: bool
+    """True means the player is already setup, false means the player needs to be setup"""
+
+    group: str | None
+    """Group name of the player"""
+    leader: PairedPlayer | None
+    """Player leading the group. Only present if the player is grouped and not leader itself"""
+    followers: list[PairedPlayer] | None
+    """List of following players. Only present if the player is leader of a group"""
+
+    zone: str | None
+    """Name of the zone the player is in. Zones are fixed groups."""
+    zone_leader: bool | None
+    """True if the player is the leader of the zone, false otherwise"""
+    zone_follower: bool | None
+    """True if the player is a follower in the zone, false otherwise"""
+
+    brand: str
+    """Brand name of the player"""
+    model: str
+    """Model name of the player"""
+    model_name: str
+    """Model name of the player"""
+
+    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."""
+    mute_volume: int | None
+    """If the player is muted, then this is the unmuted volume level. Absent if the player is not muted."""
+
+    volume_db: float
+    """Volume level in dB"""
+    volume: int
+    """Volume level with a range of 0-100. -1 means fixed volume."""
+
+
+@dataclass
+class Volume:
+    volume: int
+    """Volume level with a range of 0-100"""
+    db: float
+    """Volume level in dB"""
+    mute: bool
+    """Mute status"""
+
+
+@dataclass
+class PlayQueue:
+    id: str
+    """Unique id for the current play queue state. Changes whenever the play queue changes."""
+    shuffle: bool
+    """PlayQueue is shuffled"""
+    modified: bool
+    """PlayQueue was modified since it was loaded"""
+    length: int
+    """Number of tracks in the play queue"""
+
+
+@dataclass
+class Preset:
+    name: str
+    """Name of the preset"""
+    id: int
+    """Unique id of the preset"""
+    url: str
+    """URL of the preset. Can be used with *play_url* to play the preset"""
+    image: str | None
+    """URL of the preset image"""
+    volume: int | None
+    """Volume level with a range of 0-100. None means the volume is not set."""
+
+
+@dataclass
+class Input:
+    id: str | None
+    """Unique id of the input"""
+    text: str
+    """User friendly name of the input"""
+    image: str
+    """URL of the input image"""
+    url: str
+    """URL to play the input. Can be passed to *play_url*"""

pyblu/errors.py

@@ -0,0 +1,52 @@
+from typing import Awaitable, Callable, TypeVar, Any, cast
+
+from functools import wraps
+
+import aiohttp
+
+__all__ = ["PlayerError", "PlayerUnreachableError", "PlayerUnexpectedResponseError"]
+
+FuncT = TypeVar("FuncT", bound=Callable[..., Any])
+AsyncFuncT = TypeVar("AsyncFuncT", bound=Callable[..., Awaitable[Any]])
+
+
+class PlayerError(Exception):
+    """Base class for exceptions in this package."""
+
+    def __init__(self, message: str):
+        super().__init__(message)
+
+
+class PlayerUnreachableError(PlayerError):
+    """Exception raised when the player is not reachable.
+
+    This could be due to a timeout or the player being offline.
+    """
+
+
+class PlayerUnexpectedResponseError(PlayerError):
+    """Exception raised when the player returns an unexpected response. This is likely a bug in this library."""
+
+
+def _wrap_in_unxpected_response_error(func: FuncT) -> FuncT:
+    @wraps(func)
+    def wrapped(*args, **kwargs):
+        try:
+            return func(*args, **kwargs)
+        except Exception as e:
+            raise PlayerUnexpectedResponseError(f"Unexpected response from player: {e}") from e
+
+    return cast(FuncT, wrapped)
+
+
+def _wrap_in_unreachable_error(func: AsyncFuncT) -> AsyncFuncT:
+    @wraps(func)
+    async def wrapped(*args, **kwargs):
+        try:
+            return await func(*args, **kwargs)
+        except TimeoutError as e:
+            raise PlayerUnreachableError(f"Timout during request: {e}") from e
+        except aiohttp.ClientConnectionError as e:
+            raise PlayerUnreachableError(f"Connection error: {e}") from e
+
+    return cast(AsyncFuncT, wrapped)

pyblu/parse.py

@@ -0,0 +1,236 @@
+from urllib.parse import unquote
+
+from lxml import etree
+
+from pyblu.entities import Input, PairedPlayer, SyncStatus, Status, Volume, PlayQueue, Preset
+from pyblu.errors import _wrap_in_unxpected_response_error
+
+
+@_wrap_in_unxpected_response_error
+def parse_add_follower(response: bytes) -> list[PairedPlayer]:
+    """
+    :raises PlayerUnexpectedResponseError: If the response is not as expected.
+    """
+    # pylint: disable=c-extension-no-member
+    tree = etree.fromstring(response)
+    follower_elements = tree.xpath("//addSlave/slave")
+
+    return [PairedPlayer(ip=x.attrib["id"], port=int(x.attrib["port"])) for x in follower_elements]
+
+
+@_wrap_in_unxpected_response_error
+def parse_sync_status(response: bytes) -> SyncStatus:
+    """
+    :raises PlayerUnexpectedResponseError: If the response is not as expected.
+    """
+    # pylint: disable=c-extension-no-member
+    tree = etree.fromstring(response)
+
+    leader: PairedPlayer | None = None
+    leader_elements = tree.xpath("//SyncStatus/master")
+    if leader_elements:
+        leader_element = leader_elements[0]
+        leader_ip = leader_element.text
+        leader_port = leader_element.attrib["port"]
+        leader = PairedPlayer(ip=leader_ip, port=int(leader_port))
+
+    followers: list[PairedPlayer] | None = None
+    follower_elements = tree.xpath("//SyncStatus/slave")
+    if follower_elements:
+        followers = [PairedPlayer(ip=x.attrib["id"], port=int(x.attrib["port"])) for x in follower_elements]
+
+    sync_status_elements = tree.xpath("//SyncStatus")
+    assert len(sync_status_elements) == 1, "SyncStatus element not found or multiple found"
+    sync_status_element = sync_status_elements[0]
+
+    sync_status = SyncStatus(
+        etag=sync_status_element.attrib["etag"],
+        id=sync_status_element.attrib["id"],
+        mac=sync_status_element.attrib["mac"],
+        name=sync_status_element.attrib["name"],
+        image=sync_status_element.attrib["icon"],
+        initialized=sync_status_element.attrib.get("initialized") == "true",
+        group=sync_status_element.attrib.get("group"),
+        leader=leader,
+        followers=followers,
+        zone=sync_status_element.attrib.get("zone"),
+        zone_leader=sync_status_element.attrib.get("zoneMaster") == "true",
+        zone_follower=sync_status_element.attrib.get("zoneMaster") == "true",
+        brand=sync_status_element.attrib["brand"],
+        model=sync_status_element.attrib["model"],
+        model_name=sync_status_element.attrib["modelName"],
+        mute_volume_db=float(sync_status_element.attrib["muteDb"]) if "muteDb" in sync_status_element.attrib else None,
+        mute_volume=int(sync_status_element.attrib["muteVolume"]) if "muteVolume" in sync_status_element.attrib else None,
+        volume_db=float(sync_status_element.attrib["db"]),
+        volume=int(sync_status_element.attrib["volume"]),
+    )
+
+    return sync_status
+
+
+@_wrap_in_unxpected_response_error
+def parse_status(response: bytes) -> Status:
+    """
+    :raises PlayerUnexpectedResponseError: If the response is not as expected.
+    """
+    # pylint: disable=c-extension-no-member
+    tree = etree.fromstring(response)
+    status_elements = tree.xpath("//status")
+
+    assert len(status_elements) == 1, "Status element not found or multiple found"
+    status_element = status_elements[0]
+
+    name = status_element.findtext("name")
+    if name is None:
+        name = status_element.findtext("title1")
+    artist = status_element.findtext("artist")
+    if artist is None:
+        artist = status_element.findtext("title2")
+    album = status_element.findtext("album")
+    if album is None:
+        album = status_element.findtext("title3")
+
+    status = Status(
+        etag=status_element.attrib["etag"],
+        input_id=status_element.findtext("inputId"),
+        service=status_element.findtext("service"),
+        state=status_element.findtext("state"),
+        shuffle=status_element.findtext("shuffle") == "1",
+        album=album,
+        artist=artist,
+        name=name,
+        image=status_element.findtext("image"),
+        volume=int(status_element.findtext("volume")),
+        volume_db=float(status_element.findtext("db")),
+        mute=status_element.findtext("mute") == "1",
+        mute_volume=int(status_element.findtext("muteVolume")) if status_element.findtext("muteVolume") else None,
+        mute_volume_db=float(status_element.findtext("muteDb")) if status_element.findtext("muteDb") else None,
+        seconds=float(status_element.findtext("secs")) if status_element.findtext("secs") else None,
+        total_seconds=float(status_element.findtext("totlen")) if status_element.findtext("totlen") else None,
+        can_seek=status_element.findtext("canSeek") == "1",
+        sleep=int(status_element.findtext("sleep")) if status_element.findtext("sleep") else 0,
+        group_name=status_element.findtext("groupName"),
+        group_volume=int(status_element.findtext("groupVolume")) if status_element.findtext("groupVolume") else None,
+        indexing=status_element.findtext("indexing") == "1",
+        stream_url=status_element.findtext("streamUrl"),
+    )
+
+    return status
+
+
+@_wrap_in_unxpected_response_error
+def parse_volume(response: bytes) -> Volume:
+    """
+    :raises PlayerUnexpectedResponseError: If the response is not as expected.
+    """
+    # pylint: disable=c-extension-no-member
+    tree = etree.fromstring(response)
+    volume_elements = tree.xpath("//volume")
+
+    assert len(volume_elements) == 1, "Volume element not found or multiple found"
+    volume_element = volume_elements[0]
+
+    volume = Volume(
+        volume=int(volume_element.text),
+        db=float(volume_element.attrib["db"]),
+        mute=volume_element.attrib.get("mute") == "1",
+    )
+
+    return volume
+
+
+@_wrap_in_unxpected_response_error
+def parse_play_queue(response: bytes) -> PlayQueue:
+    """
+    :raises PlayerUnexpectedResponseError: If the response is not as expected.
+    """
+    # pylint: disable=c-extension-no-member
+    tree = etree.fromstring(response)
+    playlist_elements = tree.xpath("//playlist")
+
+    assert len(playlist_elements) == 1, "Playlist element not found or multiple found"
+    playlist_element = playlist_elements[0]
+
+    play_queue = PlayQueue(
+        id=playlist_element.attrib["id"],
+        modified=playlist_element.attrib.get("modified") == "1",
+        length=int(playlist_element.attrib["length"]),
+        shuffle=playlist_element.attrib.get("shuffle") == "1",
+    )
+
+    return play_queue
+
+
+@_wrap_in_unxpected_response_error
+def parse_presets(response: bytes) -> list[Preset]:
+    """
+    :raises PlayerUnexpectedResponseError: If the response is not as expected.
+    """
+    # pylint: disable=c-extension-no-member
+    tree = etree.fromstring(response)
+    preset_elements = tree.xpath("//presets/preset")
+
+    presets = [
+        Preset(
+            name=x.attrib["name"],
+            id=int(x.attrib["id"]),
+            url=x.attrib["url"],
+            image=x.attrib.get("image"),
+            volume=int(x.attrib.get("volume")) if x.attrib.get("volume") else None,
+        )
+        for x in preset_elements
+    ]
+
+    return presets
+
+
+@_wrap_in_unxpected_response_error
+def parse_state(response: bytes) -> str:
+    """
+    :raises PlayerUnexpectedResponseError: If the response is not as expected.
+    """
+    # pylint: disable=c-extension-no-member
+    tree = etree.fromstring(response)
+    state_elements = tree.xpath("//state")
+
+    assert len(state_elements) == 1, "State element not found or multiple found"
+    state_element = state_elements[0]
+
+    return state_element.text
+
+
+@_wrap_in_unxpected_response_error
+def parse_sleep(response: bytes) -> int:
+    """
+    :raises PlayerUnexpectedResponseError: If the response is not as expected.
+    """
+    # pylint: disable=c-extension-no-member
+    tree = etree.fromstring(response)
+    sleep_elements = tree.xpath("//sleep")
+
+    assert len(sleep_elements) == 1, "Sleep element not found or multiple found"
+    sleep_element = sleep_elements[0]
+
+    return int(sleep_element.text) if sleep_element.text else 0
+
+
+@_wrap_in_unxpected_response_error
+def parse_inputs(response: bytes) -> list[Input]:
+    """
+    :raises PlayerUnexpectedResponseError: If the response is not as expected.
+    """
+    # pylint: disable=c-extension-no-member
+    tree = etree.fromstring(response)
+    input_elements = tree.xpath("//radiotime/item")
+
+    inputs = [
+        Input(
+            id=x.attrib.get("id"),
+            text=x.attrib["text"],
+            image=x.attrib["image"],
+            url=unquote(x.attrib["URL"]),
+        )
+        for x in input_elements
+    ]
+
+    return inputs

pyblu/player.py

@@ -0,0 +1,514 @@
+import aiohttp
+
+from pyblu.entities import Status, Volume, SyncStatus, PairedPlayer, PlayQueue, Preset, Input
+from pyblu.parse import (
+    parse_add_follower,
+    parse_inputs,
+    parse_sleep,
+    parse_state,
+    parse_sync_status,
+    parse_status,
+    parse_volume,
+    parse_play_queue,
+    parse_presets,
+)
+from pyblu.errors import _wrap_in_unreachable_error
+
+
+class Player:
+    def __init__(self, host: str, port: int = 11000, session: aiohttp.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*.
+
+        :param host: The hostname or IP address of the player.
+        :param port: The port of the player. Default is 11000.
+        :param session: An optional aiohttp.ClientSession to use for requests.
+        :param default_timeout: The default timeout in seconds for requests. Can be overridden in each request.
+
+        :return: A new Player.
+        """
+        self.base_url = f"http://{host}:{port}"
+        self._default_timeout = default_timeout
+        if session:
+            self._session_owned = False
+            self._session = session
+        else:
+            self._session_owned = True
+            self._session = aiohttp.ClientSession()
+
+    @property
+    def default_timeout(self) -> float:
+        return self._default_timeout
+
+    async def close(self):
+        if self._session_owned:
+            await self._session.close()
+
+    async def __aenter__(self):
+        return self
+
+    async def __aexit__(self, *args):
+        await self.close()
+
+    @_wrap_in_unreachable_error
+    async def status(self, 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.
+
+        :param etag: The last etag received from the server. Triggers long polling if set.
+        :param poll_timeout: The timeout in seconds for long polling. Has to be smaller than timeout.
+        :param timeout: The timeout in seconds for the request. This overrides the default timeout. Has to be larger than poll_timeout.
+
+        :raises PlayerUnexpectedResponseError: If the response is not as expected. This is probably a bug in the library.
+        :raises PlayerUnreachableError: If the player is not reachable. Player is offline or request timed out.
+
+        :return: The current status of the player. Only selected fields are returned.
+        """
+        used_timeout = timeout if timeout is not None else self._default_timeout
+
+        params: dict[str, str] = {}
+        if etag is not None:
+            if poll_timeout >= used_timeout:
+                raise ValueError("poll_timeout has to be smaller than timeout")
+            params["etag"] = etag
+            params["timeout"] = str(poll_timeout)
+
+        async with self._session.get(f"{self.base_url}/Status", params=params, timeout=aiohttp.ClientTimeout(total=used_timeout)) as response:
+            response.raise_for_status()
+            response_data = await response.read()
+
+            status = parse_status(response_data)
+
+            return status
+
+    @_wrap_in_unreachable_error
+    async def sync_status(self, 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.
+
+        :param etag: The last etag received from the server. Triggers long polling if set.
+        :param poll_timeout: The timeout in seconds for long polling. Has to be smaller than timeout.
+        :param timeout: The timeout in seconds for the request. This overrides the default timeout. Has to be larger than poll_timeout.
+
+        :raises PlayerUnexpectedResponseError: If the response is not as expected. This is probably a bug in the library.
+        :raises PlayerUnreachableError: If the player is not reachable. Player is offline or request timed out.
+
+        :return: The SyncStatus of the player.
+        """
+        used_timeout = timeout if timeout is not None else self._default_timeout
+
+        params: dict[str, str] = {}
+        if etag is not None:
+            if poll_timeout >= used_timeout:
+                raise ValueError("poll_timeout has to be smaller than timeout")
+            params["etag"] = etag
+            params["timeout"] = str(poll_timeout)
+
+        async with self._session.get(f"{self.base_url}/SyncStatus", params=params) as response:
+            response.raise_for_status()
+            response_data = await response.read()
+
+            sync_status = parse_sync_status(response_data)
+
+            return sync_status
+
+    @_wrap_in_unreachable_error
+    async def volume(self, 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.
+
+        :param level: The volume level to set. Range is 0-100.
+        :param mute: Whether to mute the player.
+        :param tell_followers: Whether to tell grouped speakers to change their volume as well.
+        :param timeout: The timeout in seconds for the request. This overrides the default timeout.
+
+        :raises PlayerUnexpectedResponseError: If the response is not as expected. This is probably a bug in the library.
+        :raises PlayerUnreachableError: If the player is not reachable. Player is offline or request timed out.
+
+        :return: The current volume of the player.
+        """
+        used_timeout = timeout if timeout is not None else self._default_timeout
+
+        params: dict[str, str] = {}
+        if level is not None:
+            params["level"] = str(level)
+        if mute is not None:
+            params["mute"] = "1" if mute else "0"
+        if tell_followers is not None:
+            params["tell_slaves"] = "1" if tell_followers else "0"
+
+        async with self._session.get(f"{self.base_url}/Volume", params=params, timeout=aiohttp.ClientTimeout(total=used_timeout)) as response:
+            response.raise_for_status()
+            response_data = await response.read()
+
+            volume = parse_volume(response_data)
+            return volume
+
+    @_wrap_in_unreachable_error
+    async def play(self, 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.
+
+        :param seek: The position in seconds to seek to.
+        :param timeout: The timeout in seconds for the request. This overrides the default timeout.
+
+        :raises PlayerUnexpectedResponseError: If the response is not as expected. This is probably a bug in the library.
+        :raises PlayerUnreachableError: If the player is not reachable. Player is offline or request timed out.
+
+        :return: The playback state after command execution.
+        """
+        used_timeout = timeout if timeout is not None else self._default_timeout
+
+        params = {}
+        if seek is not None:
+            params["seek"] = seek
+
+        async with self._session.get(f"{self.base_url}/Play", params=params, timeout=aiohttp.ClientTimeout(total=used_timeout)) as response:
+            response.raise_for_status()
+            response_data = await response.read()
+
+            return parse_state(response_data)
+
+    @_wrap_in_unreachable_error
+    async def play_url(self, 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.
+
+        :param url: The URL of the track to play.
+        :param timeout: The timeout in seconds for the request. This overrides the default timeout.
+
+        :raises PlayerUnexpectedResponseError: If the response is not as expected. This is probably a bug in the library.
+        :raises PlayerUnreachableError: If the player is not reachable. Player is offline or request timed out.
+
+        :return: The playback state after command execution.
+        """
+        used_timeout = timeout if timeout is not None else self._default_timeout
+
+        params = {
+            "url": url,
+        }
+        async with self._session.get(f"{self.base_url}/Play", params=params, timeout=aiohttp.ClientTimeout(total=used_timeout)) as response:
+            response.raise_for_status()
+            response_data = await response.read()
+
+            return parse_state(response_data)
+
+    @_wrap_in_unreachable_error
+    async def pause(self, toggle: bool | None = None, timeout: float | None = None) -> str:
+        """Pause the current track. **toggle** can be used to toggle between playing and pause.
+
+        :param toggle: Toggle between playing and pause.
+        :param timeout: The timeout in seconds for the request. This overrides the default timeout.
+
+        :raises PlayerUnexpectedResponseError: If the response is not as expected. This is probably a bug in the library.
+        :raises PlayerUnreachableError: If the player is not reachable. Player is offline or request timed out.
+
+        :return: The playback state after command execution.
+        """
+        used_timeout = timeout if timeout is not None else self._default_timeout
+
+        params = {}
+        if toggle is not None:
+            params["toggle"] = "1"
+
+        async with self._session.get(f"{self.base_url}/Pause", params=params, timeout=aiohttp.ClientTimeout(total=used_timeout)) as response:
+            response.raise_for_status()
+            response_data = await response.read()
+
+            return parse_state(response_data)
+
+    @_wrap_in_unreachable_error
+    async def stop(self, timeout: float | None = None) -> str:
+        """Stop the current track. Stopped playback cannot be resumed.
+
+        :param timeout: The timeout in seconds for the request. This overrides the default timeout.
+
+        :raises PlayerUnexpectedResponseError: If the response is not as expected. This is probably a bug in the library.
+        :raises PlayerUnreachableError: If the player is not reachable. Player is offline or request timed out.
+
+        :return: The playback state after command execution.
+        """
+        used_timeout = timeout if timeout is not None else self._default_timeout
+
+        async with self._session.get(f"{self.base_url}/Stop", timeout=aiohttp.ClientTimeout(total=used_timeout)) as response:
+            response.raise_for_status()
+            response_data = await response.read()
+
+            return parse_state(response_data)
+
+    @_wrap_in_unreachable_error
+    async def skip(self, timeout: float | None = None) -> None:
+        """Skip to the next track.
+
+        :param timeout: The timeout in seconds for the request. This overrides the default timeout.
+
+        :raises PlayerUnexpectedResponseError: If the response is not as expected. This is probably a bug in the library.
+        :raises PlayerUnreachableError: If the player is not reachable. Player is offline or request timed out.
+        """
+        used_timeout = timeout if timeout is not None else self._default_timeout
+        async with self._session.get(f"{self.base_url}/Skip", timeout=aiohttp.ClientTimeout(total=used_timeout)) as response:
+            response.raise_for_status()
+
+    @_wrap_in_unreachable_error
+    async def back(self, timeout: float | None = None) -> None:
+        """Go back to the previous track.
+
+        :param timeout: The timeout in seconds for the request. This overrides the default timeout.
+
+        :raises PlayerUnexpectedResponseError: If the response is not as expected. This is probably a bug in the library.
+        :raises PlayerUnreachableError: If the player is not reachable. Player is offline or request timed out.
+        """
+        used_timeout = timeout if timeout is not None else self._default_timeout
+
+        async with self._session.get(f"{self.base_url}/Back", timeout=aiohttp.ClientTimeout(total=used_timeout)) as response:
+            response.raise_for_status()
+
+    @_wrap_in_unreachable_error
+    async def add_follower(self, 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.
+
+        :param ip: The IP address of the player to add.
+        :param port: The port of the player to add. Default is 11000.
+        :param timeout: The timeout in seconds for the request. This overrides the default timeout.
+
+        :raises PlayerUnexpectedResponseError: If the response is not as expected. This is probably a bug in the library.
+        :raises PlayerUnreachableError: If the player is not reachable. Player is offline or request timed out.
+
+        :return: The list of followers of the player.
+        """
+        used_timeout = timeout if timeout is not None else self._default_timeout
+
+        params: dict[str, str | int] = {
+            "slave": ip,
+            "port": port,
+        }
+        async with self._session.get(f"{self.base_url}/AddSlave", params=params, timeout=aiohttp.ClientTimeout(total=used_timeout)) as response:
+            response.raise_for_status()
+            response_data = await response.read()
+
+            followers_after_request = parse_add_follower(response_data)
+
+            return followers_after_request
+
+    @_wrap_in_unreachable_error
+    async def add_followers(self, 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.
+
+        :param followers: The list of players to add.
+        :param timeout: The timeout in seconds for the request. This overrides the default timeout.
+
+        :raises PlayerUnexpectedResponseError: If the response is not as expected. This is probably a bug in the library.
+        :raises PlayerUnreachableError: If the player is not reachable. Player is offline or request timed out.
+
+        :return: The list of followers of the player.
+        """
+        used_timeout = timeout if timeout is not None else self._default_timeout
+
+        params = {
+            "slaves": ",".join(x.ip for x in followers),
+            "ports": ",".join(str(x.port) for x in followers),
+        }
+        async with self._session.get(f"{self.base_url}/AddSlave", params=params, timeout=aiohttp.ClientTimeout(total=used_timeout)) as response:
+            response.raise_for_status()
+            response_data = await response.read()
+
+            followers_after_request = parse_add_follower(response_data)
+
+            return followers_after_request
+
+    @_wrap_in_unreachable_error
+    async def remove_follower(self, ip: str, port: int = 11000, timeout: float | None = None) -> SyncStatus:
+        """Remove a following player from the group.
+
+        :param ip: The IP address of the player to remove.
+        :param port: The port of the player to remove. Default is 11000.
+        :param timeout: The timeout in seconds for the request. This overrides the default timeout.
+
+        :raises PlayerUnexpectedResponseError: If the response is not as expected. This is probably a bug in the library.
+        :raises PlayerUnreachableError: If the player is not reachable. Player is offline or request timed out.
+
+        :return: The SyncStatus of the player.
+        """
+        used_timeout = timeout if timeout is not None else self._default_timeout
+
+        params: dict[str, str | int] = {
+            "slave": ip,
+            "port": port,
+        }
+        async with self._session.get(f"{self.base_url}/RemoveSlave", params=params, timeout=aiohttp.ClientTimeout(total=used_timeout)) as response:
+            response.raise_for_status()
+            response_data = await response.read()
+
+            sync_status = parse_sync_status(response_data)
+
+            return sync_status
+
+    @_wrap_in_unreachable_error
+    async def remove_followers(self, 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.
+
+        :param followers: The list of players to remove.
+        :param timeout: The timeout in seconds for the request. This overrides the default timeout.
+
+        :raises PlayerUnexpectedResponseError: If the response is not as expected. This is probably a bug in the library.
+        :raises PlayerUnreachableError: If the player is not reachable. Player is offline or request timed out.
+
+        :return: The SyncStatus of the player.
+        """
+        used_timeout = timeout if timeout is not None else self._default_timeout
+
+        params = {
+            "slaves": ",".join(x.ip for x in followers),
+            "ports": ",".join(str(x.port) for x in followers),
+        }
+        async with self._session.get(f"{self.base_url}/RemoveSlave", params=params, timeout=aiohttp.ClientTimeout(total=used_timeout)) as response:
+            response.raise_for_status()
+            response_data = await response.read()
+
+            sync_status = parse_sync_status(response_data)
+
+            return sync_status
+
+    @_wrap_in_unreachable_error
+    async def shuffle(self, shuffle: bool, timeout: float | None = None) -> PlayQueue:
+        """Set shuffle on current play queue.
+
+        :param shuffle: Whether to shuffle the playlist.
+        :param timeout: The timeout in seconds for the request. This overrides the default timeout.
+
+        :raises PlayerUnexpectedResponseError: If the response is not as expected. This is probably a bug in the library.
+        :raises PlayerUnreachableError: If the player is not reachable. Player is offline or request timed out.
+
+        :return: The current play queue.
+        """
+        used_timeout = timeout if timeout is not None else self._default_timeout
+
+        params = {
+            "shuffle": "1" if shuffle else "0",
+        }
+        async with self._session.get(f"{self.base_url}/Shuffle", params=params, timeout=aiohttp.ClientTimeout(total=used_timeout)) as response:
+            response.raise_for_status()
+            response_data = await response.read()
+
+            play_queue = parse_play_queue(response_data)
+
+            return play_queue
+
+    @_wrap_in_unreachable_error
+    async def clear(self, timeout: float | None = None) -> PlayQueue:
+        """Clear the play queue.
+
+        :param timeout: The timeout in seconds for the request. This overrides the default timeout.
+
+        :raises PlayerUnexpectedResponseError: If the response is not as expected. This is probably a bug in the library.
+        :raises PlayerUnreachableError: If the player is not reachable. Player is offline or request timed out.
+
+        :return: The current play queue.
+        """
+        used_timeout = timeout if timeout is not None else self._default_timeout
+
+        async with self._session.get(f"{self.base_url}/Clear", timeout=aiohttp.ClientTimeout(total=used_timeout)) as response:
+            response.raise_for_status()
+            response_data = await response.read()
+
+            play_queue = parse_play_queue(response_data)
+
+            return play_queue
+
+    @_wrap_in_unreachable_error
+    async def sleep_timer(self, 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.
+
+        :param timeout: The timeout in seconds for the request. This overrides the default timeout.
+
+        :raises PlayerUnexpectedResponseError: If the response is not as expected. This is probably a bug in the library.
+        :raises PlayerUnreachableError: If the player is not reachable. Player is offline or request timed out.
+
+        :return: The current sleep timer in minutes. 0 if no sleep timer is set.
+        """
+        used_timeout = timeout if timeout is not None else self._default_timeout
+
+        async with self._session.get(f"{self.base_url}/Sleep", timeout=aiohttp.ClientTimeout(total=used_timeout)) as response:
+            response.raise_for_status()
+            response_data = await response.read()
+
+            return parse_sleep(response_data)
+
+    @_wrap_in_unreachable_error
+    async def presets(self, timeout: float | None = None) -> list[Preset]:
+        """Get the list of presets of the player.
+
+        :param timeout: The timeout in seconds for the request. This overrides the default timeout.
+
+        :raises PlayerUnexpectedResponseError: If the response is not as expected. This is probably a bug in the library.
+        :raises PlayerUnreachableError: If the player is not reachable. Player is offline or request timed out.
+
+        :return: The list of presets of the player.
+        """
+        used_timeout = timeout if timeout is not None else self._default_timeout
+
+        async with self._session.get(f"{self.base_url}/Presets", timeout=aiohttp.ClientTimeout(total=used_timeout)) as response:
+            response.raise_for_status()
+            response_data = await response.read()
+
+            presets = parse_presets(response_data)
+
+            return presets
+
+    @_wrap_in_unreachable_error
+    async def load_preset(self, preset_id: int, timeout: float | None = None) -> None:
+        """Load a preset by ID.
+
+        :param timeout: The timeout in seconds for the request. This overrides the default timeout.
+        :param preset_id: The ID of the preset to load.
+
+        :raises PlayerUnexpectedResponseError: If the response is not as expected. This is probably a bug in the library.
+        :raises PlayerUnreachableError: If the player is not reachable. Player is offline or request timed out.
+        """
+        used_timeout = timeout if timeout is not None else self._default_timeout
+
+        params = {
+            "id": preset_id,
+        }
+        async with self._session.get(f"{self.base_url}/Preset", params=params, timeout=aiohttp.ClientTimeout(total=used_timeout)) as response:
+            response.raise_for_status()
+
+    @_wrap_in_unreachable_error
+    async def inputs(self, timeout: float | None = None) -> list[Input]:
+        """List all available inputs.
+
+        :param timeout: The timeout in seconds for the request. This overrides the default timeout.
+
+        :raises PlayerUnexpectedResponseError: If the response is not as expected. This is probably a bug in the library.
+        :raises PlayerUnreachableError: If the player is not reachable. Player is offline or request timed out.
+
+        :return: The list of inputs of the player.
+        """
+        used_timeout = timeout if timeout is not None else self._default_timeout
+
+        params = {"service": "Capture"}
+        async with self._session.get(f"{self.base_url}/RadioBrowse", params=params, timeout=aiohttp.ClientTimeout(total=used_timeout)) as response:
+            response.raise_for_status()
+            response_data = await response.read()
+
+            return parse_inputs(response_data)

pyblu-2.0.2.dist-info/METADATA

@@ -0,0 +1,41 @@
+Metadata-Version: 2.4
+Name: pyblu
+Version: 2.0.2
+Project-URL: repository, https://github.com/LouisChrist/pyblu
+Author-email: Louis Christ <mail@louischrist.de>
+License-File: LICENSE
+Requires-Dist: aiohttp>=3.10.5
+Requires-Dist: lxml>=5.3.0
+Description-Content-Type: text/markdown
+
+# pyblu
+
+[![PyPI](https://img.shields.io/pypi/v/pyblu)](https://pypi.org/project/pyblu/)
+[![PyPI - Python Version](https://img.shields.io/pypi/pyversions/pyblu)](https://pypi.org/project/pyblu/)
+[![PyPI - License](https://img.shields.io/pypi/l/pyblu)](https://github.com/LouisChrist/pyblu/blob/main/LICENSE)
+
+This is a Python library for interfacing with BluOS players. 
+It uses the 
+[BluOS API](https://bluesound-deutschland.de/wp-content/uploads/2022/01/Custom-Integration-API-v1.0_March-2021.pdf) 
+to control and query the status of BluOS players.
+Authentication is not required.
+
+Documentation is available at [here](https://louischrist.github.io/pyblu/)
+
+```python
+from pyblu import Player
+
+
+async def main():
+    async with Player("<host>") as player:
+        status = await player.status()
+        print(status)
+```
+
+## Installation
+
+```bash
+pip install pyblu
+```
+
+

pyblu-2.0.2.dist-info/RECORD

@@ -0,0 +1,10 @@
+pyblu/__init__.py,sha256=iHHwwn8WzibjysOGi_MM_CbILIp-TrCs-Ruq0QHh0gA,275
+pyblu/entities.py,sha256=_G-VfJIWe_vqpsNIJtEQegSJNMRSVuR-AZBiPVxTxLM,4696
+pyblu/errors.py,sha256=PyMHq5J49enCyx662-MQ0S8g0BHRzOhIqq947n8N7ts,1600
+pyblu/parse.py,sha256=5ODdXeOIWcKGaLe6PnikXIcQ75iuggyid-bd1PqB7sE,8626
+pyblu/player.py,sha256=8cosYiR8KZGG2CpJhJwXYTcrnyLY77bVVUUZtnsLjFc,24323
+pyblu/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+pyblu-2.0.2.dist-info/METADATA,sha256=qzLmsLmY8o-zMg869POq9gGgZ5SY3IPZe0l5gNooM2g,1154
+pyblu-2.0.2.dist-info/WHEEL,sha256=tkmg4JIqwd9H8mL30xA7crRmoStyCtGp0VWshokd1Jc,105
+pyblu-2.0.2.dist-info/licenses/LICENSE,sha256=-IzHfTBfUCjfyfsDXZgMBKx_IbyajmDw_XbvE5eQJ90,1069
+pyblu-2.0.2.dist-info/RECORD,,

pyblu-2.0.2.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.27.0
+Root-Is-Purelib: true
+Tag: py2-none-any
+Tag: py3-none-any

pyblu-2.0.2.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 Louis Christ
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.