ibroadcastaio 0.1.0__tar.gz

ibroadcastaio-0.1.0/PKG-INFO

@@ -0,0 +1,150 @@
+Metadata-Version: 2.1
+Name: ibroadcastaio
+Version: 0.1.0
+Summary: Client for async communication with the iBroadcast api.
+License: MIT
+Author: Rob Sonke
+Author-email: rob@tigrou.nl
+Requires-Python: >=3.10,<4.0
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Requires-Dist: aiohttp (>=3.10.10,<4.0.0)
+Requires-Dist: pre-commit (>=4.0.1,<5.0.0)
+Requires-Dist: pylint (>=3.3.1,<4.0.0)
+Description-Content-Type: text/markdown
+
+# iBroadcastAIO
+
+A Python library inspired by [ibroadcast-python](https://github.com/ctrueden/ibroadcast-python) for interacting with the iBroadcast API in an async manner.
+This library is initially built for usage in an iBroadcast music provider in [Music Assistant](https://music-assistant.io/).
+
+## Shortcomings of the Current API
+
+While the iBroadcast API provides a robust set of features for interacting with the service, it has some shortcomings. One of the main issues is the lack of fine-grained control over data retrieval and manipulation, which can lead to higher memory usage. This library aims to address these issues by providing more efficient data handling in future updates, allowing for better memory management and performance.
+
+For more info, see their [documentation](https://devguide.ibroadcast.com/).
+
+
+## Installation
+
+To see if you already have a virtual env (but `poetry install` should create this for you):
+
+```bash
+poetry env info --path
+source venv/bin/activate
+```
+
+This project uses Poetry for dependency management. To install the dependencies and run the example script:
+
+```bash
+poetry install
+poetry run example
+```
+
+To build and publish the package, use:
+
+```bash
+poetry build
+poetry publish
+```
+
+To run the unit tests:
+
+```bash
+poetry run python -m unittest discover -s tests
+```
+
+
+## Data Structures
+
+For a very short and simplified example of the complete library JSON that the API provides, see [example.json](./example.json). Below you will find the fields of each main topic.
+
+### Tracks
+
+```json
+{
+    "trashed": 10,
+    "track": 0,
+    "artists_additional_map": {
+        "type": 2,
+        "phrase": 1,
+        "artist_id": 0
+    },
+    "type": 17,
+    "genre": 3,
+    "year": 1,
+    "enid": 8,
+    "uploaded_time": 19,
+    "length": 4,
+    "size": 11,
+    "uid": 13,
+    "path": 12,
+    "artwork_id": 6,
+    "artists_additional": 20,
+    "album_id": 5,
+    "uploaded_on": 9,
+    "rating": 14,
+    "title": 2,
+    "artist_id": 7,
+    "icatid": 22,
+    "genres_additional": 21,
+    "plays": 15,
+    "file": 16,
+    "replay_gain": 18
+}
+```
+
+### Playlist
+
+```json
+{
+    "public_id": 4,
+    "uid": 2,
+    "sort": 8,
+    "system_created": 3,
+    "artwork_id": 7,
+    "type": 5,
+    "tracks": 1,
+    "name": 0,
+    "description": 6
+}
+```
+
+### Artist
+
+```json
+{
+    "tracks": 1,
+    "trashed": 2,
+    "artwork_id": 4,
+    "rating": 3,
+    "name": 0,
+    "icatid": 5
+}
+```
+
+### Album
+
+```json
+{
+    "year": 6,
+    "name": 0,
+    "artists_additional": 7,
+    "artists_additional_map": {
+        "type": 2,
+        "artist_id": 0,
+        "phrase": 1
+    },
+    "tracks": 1,
+    "rating": 4,
+    "icatid": 8,
+    "disc": 5,
+    "trashed": 3,
+    "artist_id": 2
+}
+```
+

ibroadcastaio-0.1.0/README.md

@@ -0,0 +1,130 @@
+# iBroadcastAIO
+
+A Python library inspired by [ibroadcast-python](https://github.com/ctrueden/ibroadcast-python) for interacting with the iBroadcast API in an async manner.
+This library is initially built for usage in an iBroadcast music provider in [Music Assistant](https://music-assistant.io/).
+
+## Shortcomings of the Current API
+
+While the iBroadcast API provides a robust set of features for interacting with the service, it has some shortcomings. One of the main issues is the lack of fine-grained control over data retrieval and manipulation, which can lead to higher memory usage. This library aims to address these issues by providing more efficient data handling in future updates, allowing for better memory management and performance.
+
+For more info, see their [documentation](https://devguide.ibroadcast.com/).
+
+
+## Installation
+
+To see if you already have a virtual env (but `poetry install` should create this for you):
+
+```bash
+poetry env info --path
+source venv/bin/activate
+```
+
+This project uses Poetry for dependency management. To install the dependencies and run the example script:
+
+```bash
+poetry install
+poetry run example
+```
+
+To build and publish the package, use:
+
+```bash
+poetry build
+poetry publish
+```
+
+To run the unit tests:
+
+```bash
+poetry run python -m unittest discover -s tests
+```
+
+
+## Data Structures
+
+For a very short and simplified example of the complete library JSON that the API provides, see [example.json](./example.json). Below you will find the fields of each main topic.
+
+### Tracks
+
+```json
+{
+    "trashed": 10,
+    "track": 0,
+    "artists_additional_map": {
+        "type": 2,
+        "phrase": 1,
+        "artist_id": 0
+    },
+    "type": 17,
+    "genre": 3,
+    "year": 1,
+    "enid": 8,
+    "uploaded_time": 19,
+    "length": 4,
+    "size": 11,
+    "uid": 13,
+    "path": 12,
+    "artwork_id": 6,
+    "artists_additional": 20,
+    "album_id": 5,
+    "uploaded_on": 9,
+    "rating": 14,
+    "title": 2,
+    "artist_id": 7,
+    "icatid": 22,
+    "genres_additional": 21,
+    "plays": 15,
+    "file": 16,
+    "replay_gain": 18
+}
+```
+
+### Playlist
+
+```json
+{
+    "public_id": 4,
+    "uid": 2,
+    "sort": 8,
+    "system_created": 3,
+    "artwork_id": 7,
+    "type": 5,
+    "tracks": 1,
+    "name": 0,
+    "description": 6
+}
+```
+
+### Artist
+
+```json
+{
+    "tracks": 1,
+    "trashed": 2,
+    "artwork_id": 4,
+    "rating": 3,
+    "name": 0,
+    "icatid": 5
+}
+```
+
+### Album
+
+```json
+{
+    "year": 6,
+    "name": 0,
+    "artists_additional": 7,
+    "artists_additional_map": {
+        "type": 2,
+        "artist_id": 0,
+        "phrase": 1
+    },
+    "tracks": 1,
+    "rating": 4,
+    "icatid": 8,
+    "disc": 5,
+    "trashed": 3,
+    "artist_id": 2
+}
+```

ibroadcastaio-0.1.0/ibroadcastaio/__init__.py

@@ -0,0 +1,7 @@
+"""Provide a package for ibroadcastaio."""
+
+from .client import IBroadcastClient
+
+__all__ = [
+    "IBroadcastClient",
+]

ibroadcastaio-0.1.0/ibroadcastaio/client.py

@@ -0,0 +1,196 @@
+import json
+from typing import Any, AsyncGenerator
+
+from aiohttp import ClientSession
+
+from ibroadcastaio.const import (
+    BASE_API_URL,
+    BASE_LIBRARY_URL,
+    REFERER,
+    STATUS_API,
+    VERSION,
+)
+
+
+class IBroadcastClient:
+    """iBroadcast API Client to use the API in an async manner"""
+
+    _user_id = None
+    _token = None
+
+    _albums = None
+    _artists = None
+    _playlists = None
+    _tags = None
+    _tracks = None
+    _settings = None
+
+    def __init__(self, http_session: ClientSession) -> None:
+        """Main constructor"""
+        self.http_session = http_session
+
+    async def login(self, username: str, password: str) -> dict[str, Any]:
+        data = {
+            "mode": "status",
+            "email_address": username,
+            "password": password,
+            "version": VERSION,
+            "client": REFERER,
+            "supported_types": False,
+        }
+
+        status = await self.__post(
+            f"{BASE_API_URL}{STATUS_API}", {"content_type": "application/json"}, data
+        )
+        if "user" not in status:
+            raise ValueError("Invalid credentials")
+
+        # Store the token and user id
+        self._token = status["user"]["token"]
+        self._user_id = status["user"]["id"]
+
+        return status
+
+    async def refresh_library(self):
+        """Fetch the library to cache it locally"""
+        data = {
+            "_token": self._token,
+            "_userid": self._user_id,
+            "client": REFERER,
+            "version": VERSION,
+            "mode": "library",
+            "supported_types": False,
+        }
+
+        """
+            In a future version of this library, mainly once ibroadcast has a more fine grained API, we should not keep the library in memory.
+            For now we fetch the complete librady and split it into in memory class members.
+            Later, we remove this step and rewrite methods such as _get_albums(album_id) to directly fetch it from the API.
+        """
+        library = await self.__post(
+            f"{BASE_LIBRARY_URL}", {"content_type": "application/json"}, data
+        )
+
+        self._albums = {
+            album["album_id"]: album
+            async for album in self.__jsonToDict(
+                library["library"]["albums"], "album_id"
+            )
+        }
+        self._artists = {
+            artist["artist_id"]: artist
+            async for artist in self.__jsonToDict(
+                library["library"]["artists"], "artist_id"
+            )
+        }
+        self._playlists = {
+            playlist["playlist_id"]: playlist
+            async for playlist in self.__jsonToDict(
+                library["library"]["playlists"], "playlist_id"
+            )
+        }
+        self._tags = {
+            tag["tag_id"]: tag
+            async for tag in self.__jsonToDict(library["library"]["tags"], "tag_id")
+        }
+        self._tracks = {
+            track["track_id"]: track
+            async for track in self.__jsonToDict(
+                library["library"]["tracks"], "track_id"
+            )
+        }
+
+        self._settings = library["settings"]
+
+    async def get_settings(self):
+        self._check_library_loaded()
+        return self._settings
+
+    async def get_album(self, album_id: int):
+        self._check_library_loaded()
+        return self._albums.get(album_id)
+
+    async def __post(
+        self,
+        url: str,
+        headers: dict[str, Any] | None = None,
+        data: dict[str, Any] | None = None,
+    ):
+        async with self.http_session.post(
+            url=url, data=json.dumps(data), headers=headers
+        ) as response:
+            return await response.json()
+
+    async def __jsonToDict(
+        self, data: list[dict[str, Any]], main_key: str
+    ) -> AsyncGenerator[dict[str, Any], None]:
+        """
+        Convert the library json into python dicts. See the readme for all fields.
+
+        Example Album:
+
+            data = {
+            "12345" : [
+                "My album",
+                [
+                    123,
+                    124,
+                    125
+                ],
+                "123",
+                false,
+                null,
+                null,
+                null,
+                456,
+                1
+            ],
+            "map" : {
+                "artwork_id" : 7,
+                "description" : 6,
+                "name" : 0,
+                "public_id" : 4,
+                "sort" : 8,
+                "system_created" : 3,
+                "tracks" : 1,
+                "type" : 5,
+                "uid" : 2
+            }
+        }
+
+        will be turned into a dict as:
+
+        data = {
+            "12345" : {
+                "album_id" : 12345, ==> this is an extra field, to make life easier
+                "name": "My album",
+                "tracks": [
+                    123,
+                    124,
+                    125
+                ],
+                "uid": "123",
+                "system_created": false,
+                "public_id": null,
+                "type": null,
+                "description": null,
+                "artwork_id": 456,
+                "sort": 1
+            }
+        }
+        """
+        if "map" not in data or type(data["map"]) is not dict:
+            return
+
+        keymap = {v: k for (k, v) in data["map"].items() if not isinstance(v, dict)}
+
+        for key, value in data.items():
+            if type(value) is list:
+                result = {keymap[i]: value[i] for i in range(len(value))}
+                result[main_key] = int(key)
+                yield result
+
+    def _check_library_loaded(self):
+        """Check if the library is loaded"""
+        if self._settings is None:
+            raise ValueError("Library not loaded. Please call refresh_library first.")

ibroadcastaio-0.1.0/ibroadcastaio/const.py

@@ -0,0 +1,9 @@
+"""Constants for the iBroadcast client."""
+
+BASE_API_URL = "https://api.ibroadcast.com"
+BASE_LIBRARY_URL = "https://library.ibroadcast.com"
+
+STATUS_API = "/s/JSON/status"
+
+REFERER = "ibroadcastaio-client"
+VERSION = "0.1.0"

ibroadcastaio-0.1.0/pyproject.toml

@@ -0,0 +1,27 @@
+[tool.poetry]
+name = "ibroadcastaio"
+version = "0.1.0"
+description = "Client for async communication with the iBroadcast api."
+authors = ["Rob Sonke <rob@tigrou.nl>"]
+license = "MIT"
+readme = "README.md"
+
+[tool.poetry.dependencies]
+python = "^3.10"
+aiohttp = "^3.10.10"
+pre-commit = "^4.0.1"
+pylint = "^3.3.1"
+
+[tool.poetry.dev-dependencies]
+pytest = "^6.2.4"
+black = "^24.10.0"
+isort = "^5.13.2"
+flake8 = "^7.1.1"
+
+[tool.poetry.scripts]
+example = "example:main"
+test = "unittest:main"
+
+[build-system]
+requires = ["poetry-core"]
+build-backend = "poetry.core.masonry.api"