sonance-py 0.1.0__tar.gz

sonance_py-0.1.0/PKG-INFO

@@ -0,0 +1,93 @@
+Metadata-Version: 2.3
+Name: sonance-py
+Version: 0.1.0
+Summary: An async Python library and CLI for interacting with Sonance DSP amplifiers.
+Requires-Dist: aiohttp>=3.12.0
+Requires-Dist: pydantic>=2.12.0
+Requires-Dist: typer>=0.12.5
+Requires-Python: >=3.14
+Description-Content-Type: text/markdown
+
+# Sonance Py
+
+Sonance Py is an async Python library for controlling Sonance DSP amplifiers,
+including the DSP8-130 and related models that expose the same unauthenticated
+HTTP interface.
+
+The project is intended to support a future Home Assistant integration and a
+Typer-based CLI for local development, testing, and troubleshooting.
+
+## Current Status
+
+This project is in early development. The initial client implements the basic
+HTTP API shape discovered from the amplifier web UI:
+
+- General settings read/write operations
+- Input/output settings read/write operations
+- EQ preset read/write/action operations
+- Shared async HTTP session support
+
+The CLI is not implemented yet.
+
+## HTTP API
+
+The amplifier web UI calls an unauthenticated endpoint at:
+
+```text
+/Web/Handler.php
+```
+
+The API uses query parameters for reads and writes, and returns JSON state
+objects. The documented API shape is available in:
+
+```text
+Docs/http-api.md
+```
+
+## Basic Usage
+
+```python
+import asyncio
+
+from sonance_py import SonanceDSP
+
+
+async def main() -> None:
+    async with SonanceDSP("192.168.1.50") as amp:
+        general = await amp.read_general()
+        print(general.amplifier_model)
+
+
+asyncio.run(main())
+```
+
+## Development
+
+This project uses UV for dependency management and packaging.
+
+Install dependencies:
+
+```shell
+uv sync
+```
+
+Run Ruff:
+
+```shell
+uv run ruff check .
+uv run ruff format . --check
+```
+
+Build the package:
+
+```shell
+uv build
+```
+
+## Notes
+
+- The device endpoint is unauthenticated HTTP.
+- API indexes are zero-based because that is how the web UI addresses arrays.
+- The project targets Python 3.14 and newer.
+- Behavior still needs validation against real amplifier hardware and firmware
+  versions.

sonance_py-0.1.0/README.md

@@ -0,0 +1,83 @@
+# Sonance Py
+
+Sonance Py is an async Python library for controlling Sonance DSP amplifiers,
+including the DSP8-130 and related models that expose the same unauthenticated
+HTTP interface.
+
+The project is intended to support a future Home Assistant integration and a
+Typer-based CLI for local development, testing, and troubleshooting.
+
+## Current Status
+
+This project is in early development. The initial client implements the basic
+HTTP API shape discovered from the amplifier web UI:
+
+- General settings read/write operations
+- Input/output settings read/write operations
+- EQ preset read/write/action operations
+- Shared async HTTP session support
+
+The CLI is not implemented yet.
+
+## HTTP API
+
+The amplifier web UI calls an unauthenticated endpoint at:
+
+```text
+/Web/Handler.php
+```
+
+The API uses query parameters for reads and writes, and returns JSON state
+objects. The documented API shape is available in:
+
+```text
+Docs/http-api.md
+```
+
+## Basic Usage
+
+```python
+import asyncio
+
+from sonance_py import SonanceDSP
+
+
+async def main() -> None:
+    async with SonanceDSP("192.168.1.50") as amp:
+        general = await amp.read_general()
+        print(general.amplifier_model)
+
+
+asyncio.run(main())
+```
+
+## Development
+
+This project uses UV for dependency management and packaging.
+
+Install dependencies:
+
+```shell
+uv sync
+```
+
+Run Ruff:
+
+```shell
+uv run ruff check .
+uv run ruff format . --check
+```
+
+Build the package:
+
+```shell
+uv build
+```
+
+## Notes
+
+- The device endpoint is unauthenticated HTTP.
+- API indexes are zero-based because that is how the web UI addresses arrays.
+- The project targets Python 3.14 and newer.
+- Behavior still needs validation against real amplifier hardware and firmware
+  versions.

sonance_py-0.1.0/pyproject.toml

@@ -0,0 +1,43 @@
+[project]
+name = "sonance-py"
+version = "0.1.0"
+description = "An async Python library and CLI for interacting with Sonance DSP amplifiers."
+readme = "README.md"
+requires-python = ">=3.14"
+dependencies = [
+    "aiohttp>=3.12.0",
+    "pydantic>=2.12.0",
+    "typer>=0.12.5",
+]
+
+[project.scripts]
+sonance = "sonance_py.cli:app"
+
+[dependency-groups]
+dev = [
+    "pyright>=1.1.400",
+    "ruff>=0.14.0",
+]
+
+[build-system]
+requires = ["uv_build>=0.11.14,<0.12"]
+build-backend = "uv_build"
+
+[tool.ruff]
+target-version = "py314"
+line-length = 88
+src = ["src"]
+
+[tool.ruff.lint]
+select = [
+    "E",
+    "F",
+    "I",
+    "UP",
+]
+
+
+[tool.pyright]
+include = ["src", "main.py"]
+pythonVersion = "3.14"
+typeCheckingMode = "standard"

sonance_py-0.1.0/src/sonance_py/__init__.py

@@ -0,0 +1,52 @@
+"""Async client for Sonance DSP amplifiers."""
+
+from .amplifier import SonanceDSP, SonanceOutput
+from .models import (
+    AutoOnMethod,
+    BasicStatus,
+    BridgeModeItem,
+    CrossoverBand,
+    CrossoverFilterType,
+    CrossoverSettings,
+    DelaySettings,
+    EqSettings,
+    GeneralSettings,
+    InOutSettings,
+    Limiter,
+    OnOff,
+    Output,
+    OutputGroup,
+    OutputGroupItem,
+    ParametricEqBand,
+    PresetItem,
+    SourceMode,
+    StereoMode,
+    TiltBand,
+    TiltSettings,
+)
+
+__all__ = [
+    "AutoOnMethod",
+    "BasicStatus",
+    "BridgeModeItem",
+    "CrossoverBand",
+    "CrossoverFilterType",
+    "CrossoverSettings",
+    "DelaySettings",
+    "EqSettings",
+    "GeneralSettings",
+    "InOutSettings",
+    "Limiter",
+    "OnOff",
+    "Output",
+    "OutputGroupItem",
+    "OutputGroup",
+    "ParametricEqBand",
+    "PresetItem",
+    "SonanceDSP",
+    "SonanceOutput",
+    "SourceMode",
+    "StereoMode",
+    "TiltBand",
+    "TiltSettings",
+]

sonance_py-0.1.0/src/sonance_py/_wire_models.py

@@ -0,0 +1,302 @@
+"""Pydantic models for deserializing Sonance DSP HTTP API payloads."""
+
+from pydantic import BaseModel, ConfigDict, Field
+
+from .models import (
+    AutoOnMethod,
+    BasicStatus,
+    BridgeModeItem,
+    CrossoverBand,
+    CrossoverFilterType,
+    CrossoverSettings,
+    DelaySettings,
+    EqSettings,
+    GeneralSettings,
+    InOutSettings,
+    Limiter,
+    OnOff,
+    OutputGroup,
+    OutputGroupItem,
+    ParametricEqBand,
+    PresetItem,
+    SourceMode,
+    StereoMode,
+    TiltBand,
+    TiltSettings,
+)
+
+
+class SonanceWireModel(BaseModel):
+    """Base model for wire-format API payloads."""
+
+    model_config = ConfigDict(extra="allow", populate_by_name=True)
+
+
+class WirePresetItem(SonanceWireModel):
+    """Named preset option returned by the amplifier."""
+
+    name: str
+    value: str
+
+    def to_model(self) -> PresetItem:
+        """Convert the wire payload to a public dataclass."""
+
+        return PresetItem(name=self.name, value=self.value)
+
+
+class WireGeneralSettings(SonanceWireModel):
+    """Payload returned by the general settings read endpoint."""
+
+    ip_address: str = Field(alias="ip-address")
+    ip_subnet_mask: str = Field(alias="ip-subnet-mask")
+    dhcp_switch: OnOff = Field(alias="dhcp-switch")
+    flash_power_switch: OnOff = Field(alias="flash-power-switch")
+    power: OnOff
+    standby_mode: OnOff = Field(alias="standby-mode")
+    auto_on_method: AutoOnMethod = Field(alias="auto-on-method")
+    auto_on_delay: str = Field(alias="auto-on-delay")
+    amplifier_name: str = Field(alias="amplifier-name")
+    dealer_name: str = Field(alias="dealer-name")
+    amplifier_model: str = Field(alias="amplifier-model")
+    installer_name: str = Field(alias="installer-name")
+    customer_name: str = Field(alias="customer-name")
+    installition_date: str = Field(alias="installition-date")
+    firmware_version: str = Field(alias="firmware-version")
+    serial_number: str = Field(alias="serial-number")
+
+    def to_basic_status(self) -> BasicStatus:
+        """Convert the wire payload to a compact public status dataclass."""
+
+        return BasicStatus(
+            power=self.power,
+            firmware_version=self.firmware_version,
+            amplifier_name=self.amplifier_name,
+            serial_number=self.serial_number,
+        )
+
+    def to_model(self) -> GeneralSettings:
+        """Convert the wire payload to a public dataclass."""
+
+        return GeneralSettings(
+            ip_address=self.ip_address,
+            ip_subnet_mask=self.ip_subnet_mask,
+            dhcp_switch=self.dhcp_switch,
+            flash_power_switch=self.flash_power_switch,
+            power=self.power,
+            standby_mode=self.standby_mode,
+            auto_on_method=self.auto_on_method,
+            auto_on_delay=self.auto_on_delay,
+            amplifier_name=self.amplifier_name,
+            dealer_name=self.dealer_name,
+            amplifier_model=self.amplifier_model,
+            installer_name=self.installer_name,
+            customer_name=self.customer_name,
+            installition_date=self.installition_date,
+            firmware_version=self.firmware_version,
+            serial_number=self.serial_number,
+        )
+
+
+class WireOutputGroupItem(SonanceWireModel):
+    """Output group option returned by the input/output settings endpoint."""
+
+    name: str
+    value: OutputGroup
+
+    def to_model(self) -> OutputGroupItem:
+        """Convert the wire payload to a public dataclass."""
+
+        return OutputGroupItem(name=self.name, value=self.value)
+
+
+class WireBridgeModeItem(SonanceWireModel):
+    """Bridge mode option returned by the input/output settings endpoint."""
+
+    name: str
+    value: OnOff
+
+    def to_model(self) -> BridgeModeItem:
+        """Convert the wire payload to a public dataclass."""
+
+        return BridgeModeItem(name=self.name, value=self.value)
+
+
+class WireInOutSettings(SonanceWireModel):
+    """Payload returned by the input/output settings read endpoint."""
+
+    dsp_preset_items: list[WirePresetItem] = Field(alias="dsp-preset-items")
+    input_names: list[str] = Field(alias="input-names")
+    input_titles: list[str] = Field(alias="input-titles")
+    output_titles: list[str] = Field(alias="output-titles")
+    level_trim_dbs: list[str] = Field(alias="level-trim-dBs")
+    output_names: list[str] = Field(alias="output-names")
+    stereo_or_mono: list[StereoMode] = Field(alias="stereo-or-mono")
+    dsp_presets: list[int] = Field(alias="dsp-presets")
+    output_group_items: list[WireOutputGroupItem] = Field(alias="output-group-items")
+    output_groups: list[OutputGroup] = Field(alias="output-groups")
+    bridge_mode_items: list[WireBridgeModeItem] = Field(alias="bridge-mode-items")
+    bridge_modes: list[OnOff] = Field(alias="bridge-modes")
+    sources_1: list[int] = Field(alias="sources-1")
+    sources_2: list[int] = Field(alias="sources-2")
+    mode_sources: list[SourceMode] = Field(alias="mode-sources")
+    output_volumes: list[str] = Field(alias="output-volumes")
+    turn_on_volumes: list[str] = Field(alias="turn-on-volumes")
+    maximum_volumes: list[str] = Field(alias="maximum-volumes")
+    gain_offset: list[str] = Field(alias="gain-offset")
+    mute_volumes: list[OnOff] = Field(alias="mute-volumes")
+
+    def to_model(self) -> InOutSettings:
+        """Convert the wire payload to a public dataclass."""
+
+        return InOutSettings(
+            dsp_preset_items=[item.to_model() for item in self.dsp_preset_items],
+            input_names=self.input_names,
+            input_titles=self.input_titles,
+            output_titles=self.output_titles,
+            level_trim_dbs=self.level_trim_dbs,
+            output_names=self.output_names,
+            stereo_or_mono=self.stereo_or_mono,
+            dsp_presets=self.dsp_presets,
+            output_group_items=[item.to_model() for item in self.output_group_items],
+            output_groups=self.output_groups,
+            bridge_mode_items=[item.to_model() for item in self.bridge_mode_items],
+            bridge_modes=self.bridge_modes,
+            sources_1=self.sources_1,
+            sources_2=self.sources_2,
+            mode_sources=self.mode_sources,
+            output_volumes=self.output_volumes,
+            turn_on_volumes=self.turn_on_volumes,
+            maximum_volumes=self.maximum_volumes,
+            gain_offset=self.gain_offset,
+            mute_volumes=self.mute_volumes,
+        )
+
+
+class WireParametricEqBand(SonanceWireModel):
+    """Single parametric EQ band."""
+
+    enable_status: OnOff = Field(alias="enable-status")
+    freq: int
+    q: float
+    gain: float
+
+    def to_model(self) -> ParametricEqBand:
+        """Convert the wire payload to a public dataclass."""
+
+        return ParametricEqBand(
+            enable_status=self.enable_status,
+            freq=self.freq,
+            q=self.q,
+            gain=self.gain,
+        )
+
+
+class WireTiltBand(SonanceWireModel):
+    """Low or high tilt EQ band."""
+
+    on_or_off: OnOff = Field(alias="on-or-off")
+    freq: int
+    gain: float
+
+    def to_model(self) -> TiltBand:
+        """Convert the wire payload to a public dataclass."""
+
+        return TiltBand(on_or_off=self.on_or_off, freq=self.freq, gain=self.gain)
+
+
+class WireTiltSettings(SonanceWireModel):
+    """Tilt control settings."""
+
+    low: WireTiltBand
+    high: WireTiltBand
+
+    def to_model(self) -> TiltSettings:
+        """Convert the wire payload to a public dataclass."""
+
+        return TiltSettings(low=self.low.to_model(), high=self.high.to_model())
+
+
+class WireCrossoverBand(SonanceWireModel):
+    """Low-pass or high-pass crossover settings."""
+
+    on_or_off: OnOff = Field(alias="on-or-off")
+    freq: int
+    filter_type: CrossoverFilterType = Field(alias="filter-type")
+
+    def to_model(self) -> CrossoverBand:
+        """Convert the wire payload to a public dataclass."""
+
+        return CrossoverBand(
+            on_or_off=self.on_or_off,
+            freq=self.freq,
+            filter_type=self.filter_type,
+        )
+
+
+class WireCrossoverSettings(SonanceWireModel):
+    """Crossover settings."""
+
+    low_pass: WireCrossoverBand = Field(alias="low-pass")
+    high_pass: WireCrossoverBand = Field(alias="high-pass")
+
+    def to_model(self) -> CrossoverSettings:
+        """Convert the wire payload to a public dataclass."""
+
+        return CrossoverSettings(
+            low_pass=self.low_pass.to_model(),
+            high_pass=self.high_pass.to_model(),
+        )
+
+
+class WireDelaySettings(SonanceWireModel):
+    """Delay settings in the units returned by the amplifier."""
+
+    seconds: float
+    feet: float
+    meters: float
+
+    def to_model(self) -> DelaySettings:
+        """Convert the wire payload to a public dataclass."""
+
+        return DelaySettings(seconds=self.seconds, feet=self.feet, meters=self.meters)
+
+
+class WireEqSettings(SonanceWireModel):
+    """Payload returned by the EQ settings read endpoint."""
+
+    output_names: list[str] = Field(alias="output-names")
+    dsp_presets: list[int] = Field(alias="dsp-presets")
+    output_titles: list[str] = Field(alias="output-titles")
+    amplifier_model: str = Field(alias="amplifier-model")
+    input_names: list[str] = Field(alias="input-names")
+    source_select: list[int] = Field(alias="source-select")
+    output_volumes: list[str] = Field(alias="output-volumes")
+    mute_volumes: list[OnOff] = Field(alias="mute-volumes")
+    eq_presets: list[WirePresetItem] = Field(alias="eq-presets")
+    current_eq_preset: str = Field(alias="current-eq-preset")
+    parametric_eq: list[WireParametricEqBand] = Field(alias="parametric-eq")
+    tilt: WireTiltSettings
+    crossover: WireCrossoverSettings
+    limiter_limiters: Limiter = Field(alias="limiter-limiters")
+    delay: WireDelaySettings
+
+    def to_model(self) -> EqSettings:
+        """Convert the wire payload to a public dataclass."""
+
+        return EqSettings(
+            output_names=self.output_names,
+            dsp_presets=self.dsp_presets,
+            output_titles=self.output_titles,
+            amplifier_model=self.amplifier_model,
+            input_names=self.input_names,
+            source_select=self.source_select,
+            output_volumes=self.output_volumes,
+            mute_volumes=self.mute_volumes,
+            eq_presets=[item.to_model() for item in self.eq_presets],
+            current_eq_preset=self.current_eq_preset,
+            parametric_eq=[band.to_model() for band in self.parametric_eq],
+            tilt=self.tilt.to_model(),
+            crossover=self.crossover.to_model(),
+            limiter_limiters=self.limiter_limiters,
+            delay=self.delay.to_model(),
+        )