pyblu 0.1.0__tar.gz

pyblu-0.1.0/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.

pyblu-0.1.0/PKG-INFO

@@ -0,0 +1,50 @@
+Metadata-Version: 2.1
+Name: pyblu
+Version: 0.1.0
+Summary: 
+Home-page: https://github.com/LouisChrist/pyblu
+License: MIT
+Author: Louis Christ
+Author-email: mail@louischrist.de
+Requires-Python: >=3.11,<4.0
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Requires-Dist: aiohttp (>=3.9.3,<4.0.0)
+Requires-Dist: xmltodict (>=0.13.0,<0.14.0)
+Project-URL: Repository, https://github.com/LouisChrist/pyblu
+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/python-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-0.1.0/README.md

@@ -0,0 +1,31 @@
+# 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/python-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-0.1.0/pyproject.toml

@@ -0,0 +1,46 @@
+[tool.poetry]
+name = "pyblu"
+version = "0.1.0"
+description = ""
+authors = ["Louis Christ <mail@louischrist.de>"]
+repository = "https://github.com/LouisChrist/pyblu"
+license = "MIT"
+readme = "README.md"
+packages = [
+    { include = "pyblu", from = "src" },
+]
+
+[tool.poetry.dependencies]
+python = "^3.11"
+xmltodict = "^0.13.0"
+aiohttp = "^3.9.3"
+
+[tool.poetry.group.dev.dependencies]
+pylint = "^3.1.0"
+black = "^24.2.0"
+pytest = "^8.1.1"
+aioresponses = "^0.7.6"
+pytest-asyncio = "^0.23.5.post1"
+sphinx = "^7.2.6"
+
+[build-system]
+requires = ["poetry-core"]
+build-backend = "poetry.core.masonry.api"
+
+[tool.pylint."messages control"]
+disable = [
+    "missing-function-docstring",
+    "missing-module-docstring",
+    "missing-class-docstring",
+    "too-many-instance-attributes",
+]
+
+[tool.pylint.format]
+max-line-length = 160
+
+[tool.black]
+line-length = 160
+
+[tool.pytest.ini_options]
+pythonpath = "src"
+asyncio_mode = "auto"

pyblu-0.1.0/src/pyblu/__init__.py

@@ -0,0 +1,4 @@
+"""A Python library for controlling BluOS players."""
+
+from ._player import Player
+from ._entities import Status, Volume, SyncStatus, PairedPlayer

pyblu-0.1.0/src/pyblu/_entities.py

@@ -0,0 +1,99 @@
+from dataclasses import dataclass
+
+
+@dataclass
+class Status:
+    etag: str
+    """Cursor for long polling requests. Can be passed to next status call."""
+    state: str
+    """Playback state"""
+
+    album: str
+    """Album name"""
+    artist: str
+    """Artist name"""
+    name: str
+    """Track name"""
+    image: str
+    """URL of the album art"""
+
+    volume: int
+    """Volume level with a range of 0-100"""
+    mute: bool
+    """Mute status"""
+    seconds: int
+    """Current playback position in seconds"""
+    total_seconds: float
+    """Total track length in seconds"""
+
+
+@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."""
+    sync_stat: str
+    """Id of sync status. Changes whenever the sync status changes."""
+
+    id: str
+    """Player IP and port"""
+    mac: str
+    """MAC address of the player"""
+    name: str
+    """Name of the player"""
+
+    icon_url: str
+    """URL of the player icon"""
+    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"""
+    master: PairedPlayer | None
+    """Master player IP and port. Only present if the player is grouped and not master itself"""
+    slaves: PairedPlayer | None
+    """List of slave players. Every entry is IP and port. Only present if the player is master"""
+
+    zone: str | None
+    """Name of the zone the player is in. Zones are fixed groups."""
+    zone_master: bool | None
+    """True if the player is the master of the zone, false otherwise"""
+    zone_slave: bool | None
+    """True if the player is a slave 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: int | None
+    """If the player is muted, then this is the unmuted volume level in dB"""
+    mute_volume: int | None
+    """If the player is muted, then this is the unmuted volume level"""
+
+    volume_db: float
+    """Volume level in dB"""
+    volume: int
+    """Volume level with a range of 0-100. -1 means fixed volume."""
+
+    schema_version: int
+    """Software schema version"""
+
+
+@dataclass
+class Volume:
+    volume: int
+    """Volume level with a range of 0-100"""
+    db: float
+    """Volume level in dB"""
+    mute: bool
+    """Mute status"""

pyblu-0.1.0/src/pyblu/_player.py

@@ -0,0 +1,288 @@
+from typing import TypeVar, Union, Callable, TypeAlias
+
+import aiohttp
+import xmltodict
+
+from pyblu._entities import Status, Volume, SyncStatus, PairedPlayer
+
+StringDict: TypeAlias = dict[str, Union[str, "StringDict"]]
+# pylint: disable=invalid-name
+T: TypeAlias = TypeVar("T")
+
+
+def chained_get(data: StringDict, *keys, _map: Callable[[str], T] = lambda x: x) -> T | None:
+    local_data = data
+    for key in keys:
+        local_data = local_data.get(key)
+        if not local_data:
+            return None
+    return _map(local_data)
+
+
+class Player:
+    def __init__(self, host: str, port: int = 11000, session: aiohttp.ClientSession = None):
+        """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.
+
+        :return: A new Player.
+        """
+        self.base_url = f"http://{host}:{port}"
+        if session:
+            self._session_owned = False
+            self._session = session
+        else:
+            self._session_owned = True
+            self._session = aiohttp.ClientSession()
+
+    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()
+
+    async def status(self, etag: str | None = None, timeout: int = 30) -> 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.
+
+        :param etag: The last etag received from the server. Triggers long polling if set.
+        :param timeout: The timeout in seconds for long polling.
+
+        :return: The current status of the player. Only selected fields are returned.
+        """
+        params = {}
+        if etag:
+            params["etag"] = etag
+            params["timeout"] = timeout
+        async with self._session.get(f"{self.base_url}/Status", params=params) as response:
+            response.raise_for_status()
+            response_data = await response.text()
+            response_dict = xmltodict.parse(response_data)
+
+            status = Status(
+                etag=chained_get(response_dict, "status", "@etag"),
+                state=chained_get(response_dict, "status", "state"),
+                album=chained_get(response_dict, "status", "album"),
+                artist=chained_get(response_dict, "status", "artist"),
+                name=chained_get(response_dict, "status", "title1"),
+                image=chained_get(response_dict, "status", "image"),
+                volume=chained_get(response_dict, "status", "volume", _map=int),
+                mute=chained_get(response_dict, "status", "mute") == "1",
+                seconds=chained_get(response_dict, "status", "secs", _map=int),
+                total_seconds=chained_get(response_dict, "status", "totlen", _map=float),
+            )
+
+            return status
+
+    async def sync_status(self, etag: str | None = None, timeout: int = 30) -> 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.
+
+        :param etag: The last etag received from the server. Triggers long polling if set.
+        :param timeout: The timeout in seconds for long polling.
+
+        :return: The SyncStatus of the player.
+        """
+        params = {}
+        if etag:
+            params["etag"] = etag
+            params["timeout"] = timeout
+        async with self._session.get(f"{self.base_url}/SyncStatus", params=params) as response:
+            response.raise_for_status()
+            response_data = await response.text()
+            response_dict = xmltodict.parse(response_data)
+
+            master_ip = chained_get(response_dict, "SyncStatus", "master", "#text")
+            master_port = chained_get(response_dict, "SyncStatus", "master", "@port")
+            master = PairedPlayer(ip=master_ip, port=int(master_port)) if master_ip and master_port else None
+
+            slaves_raw = chained_get(response_dict, "SyncStatus", "slave")
+            slaves = _parse_slave_list(slaves_raw)
+
+            sync_status = SyncStatus(
+                etag=chained_get(response_dict, "SyncStatus", "@etag"),
+                sync_stat=chained_get(response_dict, "SyncStatus", "@syncStat"),
+                id=chained_get(response_dict, "SyncStatus", "@id"),
+                mac=chained_get(response_dict, "SyncStatus", "@mac"),
+                name=chained_get(response_dict, "SyncStatus", "@name"),
+                icon_url=chained_get(response_dict, "SyncStatus", "@icon"),
+                initialized=chained_get(response_dict, "SyncStatus", "@initialized") == "true",
+                group=chained_get(response_dict, "SyncStatus", "@group"),
+                master=master,
+                slaves=slaves,
+                zone=chained_get(response_dict, "SyncStatus", "@zone"),
+                zone_master=chained_get(response_dict, "SyncStatus", "@zoneMaster") == "true",
+                zone_slave=chained_get(response_dict, "SyncStatus", "@zoneSlave") == "true",
+                brand=chained_get(response_dict, "SyncStatus", "@brand"),
+                model=chained_get(response_dict, "SyncStatus", "@model"),
+                model_name=chained_get(response_dict, "SyncStatus", "@modelName"),
+                mute_volume_db=chained_get(response_dict, "SyncStatus", "@muteDb", _map=int),
+                mute_volume=chained_get(response_dict, "SyncStatus", "@muteVolume", _map=int),
+                volume_db=chained_get(response_dict, "SyncStatus", "@db", _map=int),
+                volume=chained_get(response_dict, "SyncStatus", "@volume", _map=int),
+                schema_version=chained_get(response_dict, "SyncStatus", "@schemaVersion", _map=int),
+            )
+
+            return sync_status
+
+    async def volume(self, level: int = None, mute: bool = None, tell_slaves: bool = 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_slaves: Whether to tell grouped speakers to change their volume as well.
+
+        :return: The current volume of the player.
+        """
+        params = {}
+        if level:
+            params["level"] = level
+        if mute:
+            params["mute"] = "1" if mute else "0"
+        if tell_slaves:
+            params["tell_slaves"] = "1" if tell_slaves else "0"
+
+        async with self._session.get(f"{self.base_url}/Volume", params=params) as response:
+            response.raise_for_status()
+            response_data = await response.text()
+            response_dict = xmltodict.parse(response_data)
+
+            volume = Volume(
+                volume=chained_get(response_dict, "volume", "#text", _map=int),
+                db=chained_get(response_dict, "volume", "@db", _map=float),
+                mute=chained_get(response_dict, "volume", "@mute") == "1",
+            )
+
+            return volume
+
+    async def play(self, seek: int = 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.
+
+        :return: The playback state after command execution.
+        """
+        params = {}
+        if seek:
+            params["seek"] = seek
+
+        async with self._session.get(f"{self.base_url}/Play", params=params) as response:
+            response.raise_for_status()
+            response_data = await response.text()
+            response_dict = xmltodict.parse(response_data)
+
+            return chained_get(response_dict, "state")
+
+    async def pause(self, toggle: bool = None) -> str:
+        """Pause the current track. **toggle** can be used to toggle between playing and pause.
+
+        :param toggle: Toggle between playing and pause.
+
+        :return: The playback state after command execution.
+        """
+        params = {}
+        if toggle:
+            params["toggle"] = "1"
+
+        async with self._session.get(f"{self.base_url}/Pause", params=params) as response:
+            response.raise_for_status()
+            response_data = await response.text()
+            response_dict = xmltodict.parse(response_data)
+
+            return chained_get(response_dict, "state")
+
+    async def stop(self) -> str:
+        """Stop the current track. Stopped playback cannot be resumed.
+
+        :return: The playback state after command execution.
+        """
+        async with self._session.get(f"{self.base_url}/Stop") as response:
+            response.raise_for_status()
+            response_data = await response.text()
+            response_dict = xmltodict.parse(response_data)
+
+            return chained_get(response_dict, "state")
+
+    async def skip(self) -> None:
+        """Skip to the next track."""
+        async with self._session.get(f"{self.base_url}/Skip") as response:
+            response.raise_for_status()
+
+    async def back(self) -> None:
+        """Go back to the previous track."""
+        async with self._session.get(f"{self.base_url}/Back") as response:
+            response.raise_for_status()
+
+    async def add_slave(self, ip: str, port: int = 11000) -> list[PairedPlayer]:
+        """Add a secondary player to the current player as a slave.
+        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.
+
+        :return: The list of slaves of the player.
+        """
+        params = {
+            "slave": ip,
+            "port": port,
+        }
+        async with self._session.get(f"{self.base_url}/AddSlave", params=params) as response:
+            response.raise_for_status()
+            response_data = await response.text()
+            response_dict = xmltodict.parse(response_data)
+
+            slaves_raw = chained_get(response_dict, "addSlave", "slave")
+            slaves = _parse_slave_list(slaves_raw)
+
+            return slaves
+
+    async def add_slaves(self, slaves: list[PairedPlayer]) -> list[PairedPlayer]:
+        """Add a list of secondary players to the current player as slaves.
+        If it fails the player won't be in the returned list.
+
+        Same as *add_slave* but with a list of players. Makes only one request to player.
+
+        :param slaves: The list of players to add.
+
+        :return: The list of slaves of the player.
+        """
+        params = {
+            "slaves": ",".join(x.ip for x in slaves),
+            "ports": ",".join(str(x.port) for x in slaves),
+        }
+        async with self._session.get(f"{self.base_url}/AddSlave", params=params) as response:
+            response.raise_for_status()
+            response_data = await response.text()
+            response_dict = xmltodict.parse(response_data)
+
+            slaves_raw = chained_get(response_dict, "addSlave", "slave")
+            slaves = _parse_slave_list(slaves_raw)
+
+            return slaves
+
+
+def _parse_slave_list(slaves_raw: list[dict[str, str]]) -> list[PairedPlayer] | None:
+    match slaves_raw:
+        case {"@id": ip, "@port": port}:
+            return [PairedPlayer(ip=ip, port=int(port))]
+        case [*slaves_raw]:
+            return [PairedPlayer(ip=slave["@id"], port=int(slave["@port"])) for slave in slaves_raw]
+        case _:
+            return None