pyambeo 0.1.0__py3-none-any.whl

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/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
+    ),
+)

pyambeo/espresso.py

@@ -0,0 +1,415 @@
+"""Implementation for Ambeo Soundbar Max (Espresso)."""
+
+import asyncio
+import logging
+from typing import Any
+
+from .const import (
+    AMBEO_MAX_VOLUME_STEP,
+    BRIGHTNESS_RANGE_AMBEO_MAX_DISPLAY,
+    BRIGHTNESS_RANGE_AMBEO_MAX_LOGO,
+    EXCLUDE_SOURCES_MAX,
+    MAX_SOUNDBAR,
+    Capability,
+    PathSub,
+    StateKey,
+)
+from .exceptions import AmbeoError, AmbeoResponseError
+from .models import Preset, Source
+from .soundbar import AmbeoSoundbar
+from .transport import AmbeoTransport
+
+_LOGGER = logging.getLogger(__name__)
+
+
+class AmbeoEspresso(AmbeoSoundbar):
+    """Ambeo Soundbar Max."""
+
+    models = (MAX_SOUNDBAR,)
+
+    capabilities = frozenset(
+        {
+            Capability.AMBEO_MODE_LEVEL,
+            Capability.CENTER_SPEAKER_LEVEL,
+            Capability.DECODER_STATUS,
+            Capability.MAX_DISPLAY,
+            Capability.MAX_LOGO,
+            Capability.NATIVE_VOLUME,
+            Capability.RESET_EXPERT_SETTINGS,
+            Capability.SIDE_FIRING_LEVEL,
+            Capability.STANDBY,
+            Capability.SUBWOOFER,
+            Capability.UP_FIRING_LEVEL,
+            Capability.VOICE_ENHANCEMENT_LEVEL,
+        }
+    )
+
+    # brightnessSensor is subscribed separately because it maps to two keys.
+    _BRIGHTNESS_PATH = "settings:/espresso/brightnessSensor"
+
+    _SUBSCRIPTIONS = (
+        PathSub("player:volume", StateKey.VOLUME, "i32_"),
+        PathSub("settings:/mediaPlayer/mute", StateKey.MUTED, "bool_"),
+        PathSub("espresso:nightModeUi", StateKey.NIGHT_MODE, "bool_"),
+        PathSub("espresso:ambeoModeUi", StateKey.AMBEO_MODE, "bool_"),
+        PathSub("settings:/espresso/soundFeedback", StateKey.SOUND_FEEDBACK, "bool_"),
+        PathSub("espresso:audioInputID", StateKey.CURRENT_SOURCE, "i32_"),
+        PathSub("settings:/espresso/equalizerPreset", StateKey.CURRENT_PRESET, "i32_"),
+        PathSub(
+            "ui:/mydevice/voiceEnhanceLevel",
+            StateKey.VOICE_ENHANCEMENT_LEVEL,
+            "i16_",
+            Capability.VOICE_ENHANCEMENT_LEVEL,
+        ),
+        PathSub(
+            "ui:/settings/audio/centerSettings",
+            StateKey.CENTER_SPEAKER_LEVEL,
+            "i16_",
+            Capability.CENTER_SPEAKER_LEVEL,
+        ),
+        PathSub(
+            "ui:/settings/audio/widthSettings",
+            StateKey.SIDE_FIRING_LEVEL,
+            "i16_",
+            Capability.SIDE_FIRING_LEVEL,
+        ),
+        PathSub(
+            "ui:/settings/audio/heightSettings",
+            StateKey.UP_FIRING_LEVEL,
+            "i16_",
+            Capability.UP_FIRING_LEVEL,
+        ),
+        PathSub(
+            "settings:/espresso/ambeoMode",
+            StateKey.AMBEO_MODE_LEVEL,
+            "i32_",
+            Capability.AMBEO_MODE_LEVEL,
+        ),
+        PathSub(
+            "ui:/settings/subwoofer/enabled",
+            StateKey.SUBWOOFER_STATUS,
+            "bool_",
+            Capability.SUBWOOFER,
+        ),
+        PathSub(
+            "ui:/settings/subwoofer/volume",
+            StateKey.SUBWOOFER_VOLUME,
+            "i16_",
+            Capability.SUBWOOFER,
+        ),
+        PathSub(
+            "settings:/espresso/decoderStatus",
+            StateKey.DECODER_STATUS,
+            "espressoDecoderStatus",
+            Capability.DECODER_STATUS,
+        ),
+    )
+
+    _PRESETS = (
+        Preset(0, "Neutral"),
+        Preset(1, "Movies"),
+        Preset(2, "Sport"),
+        Preset(3, "News"),
+        Preset(4, "Music"),
+    )
+
+    def __init__(self, transport: AmbeoTransport, *args, **kwargs) -> None:
+        """Initialize and set up instance variables."""
+        super().__init__(transport, *args, **kwargs)
+        self._has_subwoofer: bool | None = None
+        # Logo and display brightness share one path: serialize read-modify-write.
+        self._brightness_lock = asyncio.Lock()
+
+    def get_volume_max(self) -> int:
+        """Get the maximum native volume value."""
+        return 50
+
+    def get_volume_step(self) -> float:
+        """Get the volume step size."""
+        return AMBEO_MAX_VOLUME_STEP
+
+    def get_subwoofer_min_value(self) -> int:
+        """Get the subwoofer minimum value."""
+        return -12
+
+    def get_subwoofer_max_value(self) -> int:
+        """Get the subwoofer maximum value."""
+        return 12
+
+    def get_logo_brightness_range(self) -> tuple[int, int]:
+        """Get the Ambeo Max logo brightness range."""
+        return BRIGHTNESS_RANGE_AMBEO_MAX_LOGO
+
+    def get_display_brightness_range(self) -> tuple[int, int]:
+        """Get the Ambeo Max display brightness range."""
+        return BRIGHTNESS_RANGE_AMBEO_MAX_DISPLAY
+
+    async def stand_by(self) -> None:
+        """Put the device into standby mode."""
+        await self._transport.set_value("espresso:appRequestedStandby", "bool_", True)
+
+    async def wake(self) -> None:
+        """Wake the device from standby."""
+        await self._transport.set_value("espresso:appRequestedOnline", "bool_", True)
+
+    async def get_night_mode(self) -> bool | None:
+        """Get the night mode state."""
+        return await self._transport.get_value("espresso:nightModeUi", "bool_")
+
+    async def set_night_mode(self, night_mode: bool) -> None:
+        """Set the night mode state."""
+        await self._transport.set_value("espresso:nightModeUi", "bool_", night_mode)
+
+    async def get_ambeo_mode(self) -> bool | None:
+        """Get the Ambeo mode state."""
+        return await self._transport.get_value("espresso:ambeoModeUi", "bool_")
+
+    async def set_ambeo_mode(self, ambeo_mode: bool) -> None:
+        """Set the Ambeo mode state."""
+        await self._transport.set_value("espresso:ambeoModeUi", "bool_", ambeo_mode)
+
+    async def get_sound_feedback(self) -> bool | None:
+        """Get the sound feedback state."""
+        return await self._transport.get_value(
+            "settings:/espresso/soundFeedback", "bool_"
+        )
+
+    async def set_sound_feedback(self, state: bool) -> None:
+        """Set the sound feedback state."""
+        await self._transport.set_value(
+            "settings:/espresso/soundFeedback", "bool_", state
+        )
+
+    async def get_current_source(self) -> int | None:
+        """Get the current audio source ID."""
+        return await self._transport.get_value("espresso:audioInputID", "i32_")
+
+    async def fetch_sources(self) -> list[Source]:
+        """Fetch all available audio sources."""
+        input_names, inputs = await asyncio.gather(
+            self._transport.get_rows("settings:/espresso/inputNames", 0, 20),
+            self._transport.get_rows("espresso:", 0, 20),
+        )
+        input_index_map = {
+            row["title"].lower(): index
+            for index, row in enumerate(inputs)
+            if isinstance(row.get("title"), str)
+        }
+        sources = []
+        for name in input_names:
+            title = name.get("title")
+            value = name.get("value")
+            label = value.get("string_") if isinstance(value, dict) else None
+            if not isinstance(title, str) or label is None:
+                continue
+            key = title.lower()
+            if key in EXCLUDE_SOURCES_MAX or key not in input_index_map:
+                continue
+            sources.append(Source(input_index_map[key], label))
+        return sources
+
+    async def set_source(self, source_id: int) -> None:
+        """Set the audio source."""
+        await self._transport.set_value("espresso:audioInputID", "i32_", source_id)
+
+    async def get_current_preset(self) -> int | None:
+        """Get the current audio preset ID."""
+        return await self._transport.get_value(
+            "settings:/espresso/equalizerPreset", "i32_"
+        )
+
+    async def set_preset(self, preset: int) -> None:
+        """Set the audio preset."""
+        await self._transport.set_value(
+            "settings:/espresso/equalizerPreset", "i32_", preset
+        )
+
+    async def fetch_presets(self) -> list[Preset]:
+        """Return the audio presets (fixed on this model)."""
+        return list(self._PRESETS)
+
+    async def fetch_state(self, max_concurrency: int = 3) -> dict[StateKey, Any]:
+        """Fetch the full device state.
+
+        Logo and display brightness share one path, read once per fetch.
+        """
+        state, brightness = await asyncio.gather(
+            super().fetch_state(max_concurrency), self._fetch_brightness_state()
+        )
+        state.update(brightness)
+        return state
+
+    async def _fetch_brightness_state(self) -> dict[StateKey, Any]:
+        """Return the logo and display brightness state values."""
+        try:
+            brightness = await self._get_brightness()
+        except AmbeoError as e:
+            _LOGGER.debug("Brightness not available: %s", e)
+            return {}
+        values = {
+            StateKey.LOGO_BRIGHTNESS: brightness.get("ambeologo"),
+            StateKey.DISPLAY_BRIGHTNESS: brightness.get("display"),
+        }
+        return {key: value for key, value in values.items() if value is not None}
+
+    async def _get_brightness(self) -> dict:
+        """Get the logo and display brightness values."""
+        brightness = await self._transport.get_value(
+            self._BRIGHTNESS_PATH, "espressoBrightness"
+        )
+        return brightness if isinstance(brightness, dict) else {}
+
+    async def _set_brightness(self, key: str, brightness: int) -> None:
+        """Set one brightness value, keeping the other one unchanged."""
+        async with self._brightness_lock:
+            current = await self._get_brightness()
+            value = {
+                "ambeologo": current.get("ambeologo"),
+                "display": current.get("display"),
+                key: brightness,
+            }
+            if None in value.values():
+                raise AmbeoResponseError(
+                    f"Missing brightness value for path: {self._BRIGHTNESS_PATH}"
+                )
+            await self._transport.set_value(
+                self._BRIGHTNESS_PATH, "espressoBrightness", value
+            )
+
+    async def get_display_brightness(self) -> int | None:
+        """Get the display brightness."""
+        return (await self._get_brightness()).get("display")
+
+    async def set_display_brightness(self, brightness: int) -> None:
+        """Set the display brightness."""
+        await self._set_brightness("display", brightness)
+
+    async def get_logo_brightness(self) -> int | None:
+        """Get the Ambeo logo brightness."""
+        return (await self._get_brightness()).get("ambeologo")
+
+    async def set_logo_brightness(self, brightness: int) -> None:
+        """Set the Ambeo logo brightness."""
+        await self._set_brightness("ambeologo", brightness)
+
+    async def get_voice_enhancement_level(self) -> int | None:
+        """Get the voice enhancement level."""
+        return await self._transport.get_value("ui:/mydevice/voiceEnhanceLevel", "i16_")
+
+    async def set_voice_enhancement_level(self, level: int) -> None:
+        """Set the voice enhancement level."""
+        await self._transport.set_value("ui:/mydevice/voiceEnhanceLevel", "i16_", level)
+
+    async def get_center_speaker_level(self) -> int | None:
+        """Get the center speaker level."""
+        return await self._transport.get_value(
+            "ui:/settings/audio/centerSettings", "i16_"
+        )
+
+    async def set_center_speaker_level(self, level: int) -> None:
+        """Set the center speaker level."""
+        await self._transport.set_value(
+            "ui:/settings/audio/centerSettings", "i16_", level
+        )
+
+    async def get_side_firing_level(self) -> int | None:
+        """Get the side firing speaker level."""
+        return await self._transport.get_value(
+            "ui:/settings/audio/widthSettings", "i16_"
+        )
+
+    async def set_side_firing_level(self, level: int) -> None:
+        """Set the side firing speaker level."""
+        await self._transport.set_value(
+            "ui:/settings/audio/widthSettings", "i16_", level
+        )
+
+    async def get_up_firing_level(self) -> int | None:
+        """Get the up firing speaker level."""
+        return await self._transport.get_value(
+            "ui:/settings/audio/heightSettings", "i16_"
+        )
+
+    async def set_up_firing_level(self, level: int) -> None:
+        """Set the up firing speaker level."""
+        await self._transport.set_value(
+            "ui:/settings/audio/heightSettings", "i16_", level
+        )
+
+    async def get_ambeo_mode_level(self) -> int | None:
+        """Get the Ambeo mode level (1=Light, 2=Regular, 3=Boost)."""
+        return await self._transport.get_value("settings:/espresso/ambeoMode", "i32_")
+
+    async def set_ambeo_mode_level(self, level: int) -> None:
+        """Set the Ambeo mode level (1=Light, 2=Regular, 3=Boost)."""
+        await self._transport.set_value("settings:/espresso/ambeoMode", "i32_", level)
+
+    async def get_decoder_status(self) -> dict | None:
+        """Get the current audio decoder status."""
+        return await self._transport.get_value(
+            "settings:/espresso/decoderStatus", "espressoDecoderStatus"
+        )
+
+    async def reset_expert_settings(self) -> None:
+        """Reset expert audio settings to defaults."""
+        await self._transport.activate(
+            "ui:/settings/audio/resetExpertSettings", {"type": "bool_", "bool_": True}
+        )
+
+    # Subwoofer.
+    async def has_subwoofer(self) -> bool:
+        """Check if a subwoofer is connected."""
+        if self._has_subwoofer is None:
+            try:
+                data = await self._transport.get_data("ui:/settings/subwoofer/enabled")
+            except AmbeoResponseError:
+                data = None
+            self._has_subwoofer = (
+                bool(data.get("modifiable", False)) if isinstance(data, dict) else False
+            )
+        return self._has_subwoofer
+
+    async def get_subwoofer_volume(self) -> float | None:
+        """Get the subwoofer volume."""
+        return await self._transport.get_value("ui:/settings/subwoofer/volume", "i16_")
+
+    async def set_subwoofer_volume(self, volume: float) -> None:
+        """Set the subwoofer volume."""
+        await self._transport.set_value(
+            "ui:/settings/subwoofer/volume", "i16_", int(volume)
+        )
+
+    async def get_subwoofer_status(self) -> bool | None:
+        """Get the subwoofer enabled status."""
+        return await self._transport.get_value(
+            "ui:/settings/subwoofer/enabled", "bool_"
+        )
+
+    async def set_subwoofer_status(self, status: bool) -> None:
+        """Set the subwoofer enabled status."""
+        await self._transport.set_value(
+            "ui:/settings/subwoofer/enabled", "bool_", status
+        )
+
+    def subscribed_paths(self) -> list[str]:
+        """Return paths to subscribe to, filtered by device capabilities."""
+        paths = super().subscribed_paths()
+        if self.has_capability(Capability.MAX_DISPLAY) or self.has_capability(
+            Capability.MAX_LOGO
+        ):
+            paths.append(self._BRIGHTNESS_PATH)
+        return paths
+
+    def process_event(self, path: str, item_value: dict) -> dict[StateKey, Any]:
+        """Map an event path + itemValue to state updates."""
+        if path == self._BRIGHTNESS_PATH:
+            brightness = item_value.get("espressoBrightness")
+            if not isinstance(brightness, dict):
+                return {}
+            updates: dict[StateKey, Any] = {}
+            if "ambeologo" in brightness:
+                updates[StateKey.LOGO_BRIGHTNESS] = brightness["ambeologo"]
+            if "display" in brightness:
+                updates[StateKey.DISPLAY_BRIGHTNESS] = brightness["display"]
+            return updates
+        return super().process_event(path, item_value)

pyambeo/exceptions.py

@@ -0,0 +1,31 @@
+"""Exceptions for the Ambeo Soundbar API."""
+
+
+class AmbeoError(Exception):
+    """Base class for all Ambeo Soundbar API errors."""
+
+
+class AmbeoConnectionError(AmbeoError):
+    """Raised when the device cannot be reached."""
+
+
+class AmbeoTimeoutError(AmbeoConnectionError):
+    """Raised when a request to the device times out."""
+
+
+class AmbeoResponseError(AmbeoError):
+    """Raised when the device answers with an unexpected response."""
+
+    def __init__(self, message: str, status: int | None = None) -> None:
+        """Initialize with an optional HTTP status code."""
+        super().__init__(message)
+        self.status = status
+
+
+class AmbeoUnsupportedModelError(AmbeoError):
+    """Raised when the device model is not supported."""
+
+    def __init__(self, model: str | None) -> None:
+        """Initialize with the unsupported model name."""
+        super().__init__(f"Unsupported model: {model}")
+        self.model = model

pyambeo/models.py

@@ -0,0 +1,40 @@
+"""Data models for the Ambeo Soundbar API."""
+
+from dataclasses import dataclass
+from enum import StrEnum
+
+
+@dataclass(frozen=True, slots=True)
+class DeviceInfo:
+    """Static information about a soundbar."""
+
+    model: str
+    name: str | None
+    serial: str | None
+    firmware_version: str | None
+
+
+@dataclass(frozen=True, slots=True)
+class Source:
+    """An audio input (HDMI, Optical, …)."""
+
+    id: str | int
+    title: str
+
+
+@dataclass(frozen=True, slots=True)
+class Preset:
+    """An audio preset / sound mode (Movies, Music, …)."""
+
+    id: str | int
+    title: str
+
+
+class PlayerStatus(StrEnum):
+    """Effective playback status derived from the device state."""
+
+    PLAYING = "playing"
+    PAUSED = "paused"
+    IDLE = "idle"
+    ON = "on"
+    STANDBY = "standby"