pyambeo 0.1.0__tar.gz

pyambeo-0.1.0/.github/workflows/ci.yaml

@@ -0,0 +1,26 @@
+name: CI
+
+on:
+  push:
+  pull_request:
+
+jobs:
+  lint:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v6
+      - run: uv run --group dev ruff check .
+      - run: uv run --group dev ruff format --check .
+
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.12", "3.13"]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v6
+        with:
+          python-version: ${{ matrix.python-version }}
+      - run: uv run --group dev pytest --cov=pyambeo --cov-report=term-missing

pyambeo-0.1.0/.github/workflows/release.yaml

@@ -0,0 +1,40 @@
+name: Release
+
+on:
+  release:
+    types: [published]
+  workflow_dispatch:
+    inputs:
+      repository:
+        description: "Package index"
+        type: choice
+        options: [testpypi, pypi]
+        default: testpypi
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v6
+      - run: uv build
+      - uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+  publish:
+    needs: build
+    runs-on: ubuntu-latest
+    # Trusted publishing: configure the matching environment on (test.)pypi.org.
+    environment: ${{ github.event_name == 'release' && 'pypi' || inputs.repository }}
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+      - uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          repository-url: ${{ (github.event_name != 'release' && inputs.repository == 'testpypi') && 'https://test.pypi.org/legacy/' || 'https://upload.pypi.org/legacy/' }}

pyambeo-0.1.0/.gitignore

@@ -0,0 +1,10 @@
+__pycache__/
+*.py[cod]
+.venv/
+dist/
+build/
+*.egg-info/
+.pytest_cache/
+.ruff_cache/
+.coverage
+htmlcov/

pyambeo-0.1.0/.pre-commit-config.yaml

@@ -0,0 +1,7 @@
+repos:
+  - repo: https://github.com/astral-sh/ruff-pre-commit
+    rev: v0.15.10
+    hooks:
+      - id: ruff
+        args: [--fix]
+      - id: ruff-format

pyambeo-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 François AIZPURU
+
+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.

pyambeo-0.1.0/PKG-INFO

@@ -0,0 +1,92 @@
+Metadata-Version: 2.5
+Name: pyambeo
+Version: 0.1.0
+Summary: Async client for Sennheiser AMBEO soundbars
+Project-URL: Homepage, https://github.com/faizpuru/pyambeo
+Project-URL: Issues, https://github.com/faizpuru/pyambeo/issues
+Author: François AIZPURU
+License-Expression: MIT
+License-File: LICENSE
+Keywords: ambeo,asyncio,home-assistant,sennheiser,soundbar
+Classifier: Development Status :: 4 - Beta
+Classifier: Framework :: AsyncIO
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Home Automation
+Classifier: Typing :: Typed
+Requires-Python: >=3.12
+Requires-Dist: aiohttp>=3.9
+Requires-Dist: yarl>=1.9
+Description-Content-Type: text/markdown
+
+# pyambeo
+
+Async Python client for Sennheiser AMBEO soundbars (Max, Plus and Mini), built on `aiohttp`.
+
+It powers the [AMBEO Soundbar integration](https://github.com/faizpuru/ha-ambeo_soundbar) for Home Assistant, but does not depend on it.
+
+## Installation
+
+```bash
+pip install pyambeo
+```
+
+## Usage
+
+```python
+import asyncio
+
+import aiohttp
+
+from pyambeo import AmbeoSoundbar
+
+
+async def main() -> None:
+    async with aiohttp.ClientSession() as session:
+        # Detects the model and returns the matching implementation.
+        bar = await AmbeoSoundbar.connect("192.168.1.10", session)
+        print(bar.info)
+
+        state = await bar.fetch_state()
+        print(state)
+
+        await bar.set_volume(20)
+
+        # Push updates from the device.
+        async for updates in bar.listen():
+            print(updates)
+
+
+asyncio.run(main())
+```
+
+The caller owns the `aiohttp.ClientSession`. All errors raised by the library inherit from `AmbeoError`:
+
+| Exception | Meaning |
+|---|---|
+| `AmbeoConnectionError` | The device cannot be reached |
+| `AmbeoTimeoutError` | A request timed out (subclass of `AmbeoConnectionError`) |
+| `AmbeoResponseError` | The device answered with an unexpected response |
+| `AmbeoUnsupportedModelError` | The device model is not supported |
+
+## Supported devices
+
+| Model | Class |
+|---|---|
+| AMBEO Soundbar Max | `AmbeoEspresso` |
+| AMBEO Soundbar Plus | `AmbeoPopcorn` |
+| AMBEO Soundbar Mini | `AmbeoPopcorn` |
+
+## Development
+
+```bash
+uv run --group dev pytest
+uv run --group dev ruff check .
+```
+
+## License
+
+MIT

pyambeo-0.1.0/README.md

@@ -0,0 +1,68 @@
+# pyambeo
+
+Async Python client for Sennheiser AMBEO soundbars (Max, Plus and Mini), built on `aiohttp`.
+
+It powers the [AMBEO Soundbar integration](https://github.com/faizpuru/ha-ambeo_soundbar) for Home Assistant, but does not depend on it.
+
+## Installation
+
+```bash
+pip install pyambeo
+```
+
+## Usage
+
+```python
+import asyncio
+
+import aiohttp
+
+from pyambeo import AmbeoSoundbar
+
+
+async def main() -> None:
+    async with aiohttp.ClientSession() as session:
+        # Detects the model and returns the matching implementation.
+        bar = await AmbeoSoundbar.connect("192.168.1.10", session)
+        print(bar.info)
+
+        state = await bar.fetch_state()
+        print(state)
+
+        await bar.set_volume(20)
+
+        # Push updates from the device.
+        async for updates in bar.listen():
+            print(updates)
+
+
+asyncio.run(main())
+```
+
+The caller owns the `aiohttp.ClientSession`. All errors raised by the library inherit from `AmbeoError`:
+
+| Exception | Meaning |
+|---|---|
+| `AmbeoConnectionError` | The device cannot be reached |
+| `AmbeoTimeoutError` | A request timed out (subclass of `AmbeoConnectionError`) |
+| `AmbeoResponseError` | The device answered with an unexpected response |
+| `AmbeoUnsupportedModelError` | The device model is not supported |
+
+## Supported devices
+
+| Model | Class |
+|---|---|
+| AMBEO Soundbar Max | `AmbeoEspresso` |
+| AMBEO Soundbar Plus | `AmbeoPopcorn` |
+| AMBEO Soundbar Mini | `AmbeoPopcorn` |
+
+## Development
+
+```bash
+uv run --group dev pytest
+uv run --group dev ruff check .
+```
+
+## License
+
+MIT

pyambeo-0.1.0/pyproject.toml

@@ -0,0 +1,83 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "pyambeo"
+version = "0.1.0"
+description = "Async client for Sennheiser AMBEO soundbars"
+readme = "README.md"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [{ name = "François AIZPURU" }]
+requires-python = ">=3.12"
+dependencies = [
+    "aiohttp>=3.9",
+    "yarl>=1.9",
+]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Framework :: AsyncIO",
+    "Intended Audience :: Developers",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Home Automation",
+    "Typing :: Typed",
+]
+keywords = ["ambeo", "sennheiser", "soundbar", "asyncio", "home-assistant"]
+
+[project.urls]
+Homepage = "https://github.com/faizpuru/pyambeo"
+Issues = "https://github.com/faizpuru/pyambeo/issues"
+
+[dependency-groups]
+dev = [
+    "aioresponses",
+    "pre-commit",
+    "pytest",
+    "pytest-asyncio",
+    "pytest-cov",
+    "ruff",
+]
+
+[tool.uv]
+# Dev/test only: aioresponses 0.7.9 does not support aiohttp 3.14 yet.
+constraint-dependencies = ["aiohttp<3.14"]
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/pyambeo"]
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"
+asyncio_default_fixture_loop_scope = "function"
+
+[tool.ruff]
+target-version = "py312"
+line-length = 88
+
+[tool.ruff.lint]
+select = [
+    "E",   # pycodestyle errors
+    "W",   # pycodestyle warnings
+    "F",   # pyflakes
+    "I",   # isort
+    "UP",  # pyupgrade
+    "B",   # flake8-bugbear
+    "SIM", # flake8-simplify
+    "D",   # pydocstyle (PEP 257)
+]
+ignore = [
+    "E501", # line too long, handled by formatter
+]
+
+[tool.ruff.lint.pydocstyle]
+convention = "pep257"
+
+[tool.ruff.lint.isort]
+known-first-party = ["pyambeo"]
+
+[tool.ruff.format]
+quote-style = "double"
+indent-style = "space"

pyambeo-0.1.0/src/pyambeo/__init__.py

@@ -0,0 +1,31 @@
+"""Async client for Sennheiser Ambeo soundbars."""
+
+from .const import Capability, StateKey
+from .espresso import AmbeoEspresso
+from .exceptions import (
+    AmbeoConnectionError,
+    AmbeoError,
+    AmbeoResponseError,
+    AmbeoTimeoutError,
+    AmbeoUnsupportedModelError,
+)
+from .models import DeviceInfo, PlayerStatus, Preset, Source
+from .popcorn import AmbeoPopcorn
+from .soundbar import AmbeoSoundbar
+
+__all__ = [
+    "AmbeoConnectionError",
+    "AmbeoError",
+    "AmbeoEspresso",
+    "AmbeoPopcorn",
+    "AmbeoResponseError",
+    "AmbeoSoundbar",
+    "AmbeoTimeoutError",
+    "AmbeoUnsupportedModelError",
+    "Capability",
+    "DeviceInfo",
+    "PlayerStatus",
+    "Preset",
+    "Source",
+    "StateKey",
+]

pyambeo-0.1.0/src/pyambeo/const.py

@@ -0,0 +1,159 @@
+"""Constants for Ambeo Soundbar API."""
+
+from enum import StrEnum
+from typing import NamedTuple
+
+DEFAULT_PORT = 80
+DEFAULT_TIMEOUT = 5
+
+# ESPRESSO: MAX
+MAX_SOUNDBAR = "AMBEO Soundbar Max"
+EXCLUDE_SOURCES_MAX = ["aes"]
+AMBEO_MAX_VOLUME_STEP = 0.02
+
+
+# POPCORN: PLUS/MINI
+PLUS_SOUNDBAR = "AMBEO Soundbar Plus"
+MINI_SOUNDBAR = "AMBEO Soundbar Mini"
+AMBEO_POPCORN_VOLUME_STEP = 0.01
+
+
+BRIGHTNESS_RANGE_DEFAULT = (0, 100)
+BRIGHTNESS_RANGE_AMBEO_MAX_DISPLAY = (1, 126)
+BRIGHTNESS_RANGE_AMBEO_MAX_LOGO = (1, 118)
+
+
+class Capability(StrEnum):
+    """Device capability identifiers."""
+
+    AMBEO_LOGO = "AmbeoLogo"
+    DECODER_STATUS = "DecoderStatus"
+    AMBEO_MODE_LEVEL = "AmbeoModeLevel"
+    BLUETOOTH_PAIRING = "AmbeoBluetoothPairing"
+    CENTER_SPEAKER_LEVEL = "CenterSpeakerLevel"
+    CENTER_VOLUME = "CenterVolume"
+    CODEC_LED = "CodecLED"
+    ECO_MODE = "EcoMode"
+    LED_BAR = "LEDBar"
+    MAX_DISPLAY = "AmbeoMaxDisplay"
+    MAX_LOGO = "AmbeoMaxLogo"
+    RESET_EXPERT_SETTINGS = "ResetExpertSettings"
+    SIDE_FIRING_LEVEL = "SideFiringLevel"
+    STANDBY = "standby"
+    SUBWOOFER = "SubWoofer"
+    UP_FIRING_LEVEL = "UpFiringLevel"
+    NATIVE_VOLUME = "NativeVolume"
+    VOICE_ENHANCEMENT_LEVEL = "VoiceEnhancementLevel"
+    VOICE_ENHANCEMENT_TOGGLE = "VoiceEnhancementMode"
+
+
+class StateKey(StrEnum):
+    """Keys of the device state returned by fetch_state() and listen()."""
+
+    VOLUME = "volume"
+    MUTED = "muted"
+    STATE = "state"
+    CURRENT_SOURCE = "current_source"
+    CURRENT_PRESET = "current_preset"
+    PLAYER_DATA = "player_data"
+    PLAY_TIME = "play_time"
+    LED_BAR_BRIGHTNESS = "led_bar_brightness"
+    CODEC_LED_BRIGHTNESS = "codec_led_brightness"
+    LOGO_BRIGHTNESS = "logo_brightness"
+    LOGO_STATE = "logo_state"
+    DISPLAY_BRIGHTNESS = "display_brightness"
+    NIGHT_MODE = "night_mode"
+    AMBEO_MODE = "ambeo_mode"
+    AMBEO_MODE_LEVEL = "ambeo_mode_level"
+    SOUND_FEEDBACK = "sound_feedback"
+    VOICE_ENHANCEMENT = "voice_enhancement"
+    VOICE_ENHANCEMENT_LEVEL = "voice_enhancement_level"
+    BLUETOOTH_PAIRING = "bluetooth_pairing"
+    SUBWOOFER_STATUS = "subwoofer_status"
+    SUBWOOFER_VOLUME = "subwoofer_volume"
+    CENTER_SPEAKER_LEVEL = "center_speaker_level"
+    SIDE_FIRING_LEVEL = "side_firing_level"
+    UP_FIRING_LEVEL = "up_firing_level"
+    CENTER_VOLUME = "center_volume"
+    ECO_MODE = "eco_mode"
+    DECODER_STATUS = "decoder_status"
+
+
+class PathSub(NamedTuple):
+    """Describes a single event-queue subscription.
+
+    path       -- Device API path to subscribe to.
+    data_key   -- Key used in the state dict.
+    type_key   -- JSON type key inside the event's itemValue dict.
+    capability -- Required device capability, or None if always subscribed.
+    sub_key    -- If set, the final value is item_value[type_key][sub_key]
+                  (used when the type value is itself a dict).
+    """
+
+    path: str
+    data_key: StateKey
+    type_key: str
+    capability: Capability | None = None
+    sub_key: str | None = None
+
+
+class FeatureDef(NamedTuple):
+    """Optional state value fetched by fetch_state() when the capability matches."""
+
+    data_key: StateKey
+    api_method: str
+    capability: Capability | None = None
+
+
+OPTIONAL_FEATURES: tuple[FeatureDef, ...] = (
+    FeatureDef(StateKey.PLAY_TIME, "get_play_time"),
+    FeatureDef(
+        StateKey.LED_BAR_BRIGHTNESS, "get_led_bar_brightness", Capability.LED_BAR
+    ),
+    FeatureDef(
+        StateKey.CODEC_LED_BRIGHTNESS, "get_codec_led_brightness", Capability.CODEC_LED
+    ),
+    FeatureDef(StateKey.LOGO_BRIGHTNESS, "get_logo_brightness", Capability.AMBEO_LOGO),
+    FeatureDef(StateKey.LOGO_STATE, "get_logo_state", Capability.AMBEO_LOGO),
+    FeatureDef(StateKey.NIGHT_MODE, "get_night_mode"),
+    FeatureDef(StateKey.AMBEO_MODE, "get_ambeo_mode"),
+    FeatureDef(StateKey.SOUND_FEEDBACK, "get_sound_feedback"),
+    FeatureDef(
+        StateKey.VOICE_ENHANCEMENT,
+        "get_voice_enhancement",
+        Capability.VOICE_ENHANCEMENT_TOGGLE,
+    ),
+    FeatureDef(
+        StateKey.BLUETOOTH_PAIRING,
+        "get_bluetooth_pairing_state",
+        Capability.BLUETOOTH_PAIRING,
+    ),
+    FeatureDef(StateKey.SUBWOOFER_STATUS, "get_subwoofer_status", Capability.SUBWOOFER),
+    FeatureDef(StateKey.SUBWOOFER_VOLUME, "get_subwoofer_volume", Capability.SUBWOOFER),
+    FeatureDef(
+        StateKey.VOICE_ENHANCEMENT_LEVEL,
+        "get_voice_enhancement_level",
+        Capability.VOICE_ENHANCEMENT_LEVEL,
+    ),
+    FeatureDef(
+        StateKey.CENTER_SPEAKER_LEVEL,
+        "get_center_speaker_level",
+        Capability.CENTER_SPEAKER_LEVEL,
+    ),
+    FeatureDef(
+        StateKey.SIDE_FIRING_LEVEL,
+        "get_side_firing_level",
+        Capability.SIDE_FIRING_LEVEL,
+    ),
+    FeatureDef(
+        StateKey.UP_FIRING_LEVEL, "get_up_firing_level", Capability.UP_FIRING_LEVEL
+    ),
+    FeatureDef(StateKey.CENTER_VOLUME, "get_center_volume", Capability.CENTER_VOLUME),
+    FeatureDef(StateKey.ECO_MODE, "get_eco_mode", Capability.ECO_MODE),
+    FeatureDef(
+        StateKey.DECODER_STATUS, "get_decoder_status", Capability.DECODER_STATUS
+    ),
+    FeatureDef(
+        StateKey.AMBEO_MODE_LEVEL, "get_ambeo_mode_level", Capability.AMBEO_MODE_LEVEL
+    ),
+)