edifier-es300 0.1.1__tar.gz

edifier_es300-0.1.1/.bumpversion.cfg

@@ -0,0 +1,14 @@
+[bumpversion]
+current_version = 0.1.1
+commit = True
+tag = True
+tag_name = v{new_version}
+message = Bump version: {current_version} -> {new_version}
+
+[bumpversion:file:pyproject.toml]
+search = version = "{current_version}"
+replace = version = "{new_version}"
+
+[bumpversion:file:uv.lock]
+search = version = "{current_version}"
+replace = version = "{new_version}"

edifier_es300-0.1.1/.github/workflows/publish.yml

@@ -0,0 +1,30 @@
+name: Publish to PyPI
+
+on:
+  push:
+    tags:
+      - "v[0-9]+.[0-9]+.[0-9]+"
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    # Gates each release behind the `pypi` environment's protection rules
+    # (e.g. required reviewers). Must match the environment on the PyPI publisher.
+    environment: pypi
+    # Required for PyPI Trusted Publishing (OIDC): uv exchanges this token for a
+    # short-lived PyPI credential — no stored secret.
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v6
+        with:
+          python-version: "3.13"
+
+      - name: Build
+        run: uv build
+
+      - name: Publish
+        run: uv publish --trusted-publishing always

edifier_es300-0.1.1/.gitignore

@@ -0,0 +1,14 @@
+# Python-generated files
+__pycache__/
+*.py[oc]
+build/
+dist/
+wheels/
+*.egg-info
+
+# Tool caches
+.ruff_cache/
+.ty_cache/
+
+# Virtual environments
+.venv

edifier_es300-0.1.1/.pre-commit-config.yaml

@@ -0,0 +1,29 @@
+default_language_version:
+  python: python3.13
+
+repos:
+  - repo: https://github.com/pre-commit/pre-commit-hooks
+    rev: v6.0.0
+    hooks:
+      - id: end-of-file-fixer
+      - id: trailing-whitespace
+      - id: check-yaml
+      - id: check-toml
+      - id: check-added-large-files
+      - id: check-merge-conflict
+      - id: mixed-line-ending
+      - id: debug-statements
+
+  - repo: https://github.com/astral-sh/ruff-pre-commit
+    rev: v0.15.20
+    hooks:
+      # Lint + import sorting (fixes what it can, incl. isort-style I rules).
+      - id: ruff
+        args: [--fix]
+      # Formatting.
+      - id: ruff-format
+
+  - repo: https://github.com/astral-sh/ty-pre-commit
+    rev: v0.0.56
+    hooks:
+      - id: ty

edifier_es300-0.1.1/.python-version

@@ -0,0 +1 @@
+3.13

edifier_es300-0.1.1/CLAUDE.md

@@ -0,0 +1,79 @@
+# CLAUDE.md — working in `edifier_es300`
+
+Guidance for working in this Python package. Read `README.md` for user-facing usage.
+This file is about the *code*: how it's organized, the conventions to follow, and the
+Python-specific traps hit while building it.
+
+## What this is
+
+An `asyncio` package to control an Edifier ES300 speaker on the local network, plus a
+`click` CLI. The library is stdlib-only; only the CLI needs `click`. Python 3.13+.
+
+## Module layout
+
+- `__init__.py` — the `ES300` async client: connection lifecycle (async context
+  manager), the request/response plumbing, the public command methods (volume,
+  transport, light, EQ, input source), and the `discover()` classmethod. Stdlib-only.
+- `typing.py` — **all shared types**: `FrameData`, the `Status` dataclass,
+  `CommandResult`, and every device enum (`Source`, `EqPreset`, `LightEffect`,
+  `LightColor`, `BatteryStatus`, `PlayerStatus`). It imports nothing from
+  the package, so it can never be part of an import cycle.
+- `__main__.py` — the `click` CLI (`python -m edifier_es300`). A thin wrapper:
+  resolve a target (explicit `--host/--port` or auto-discover), open one connection
+  per command, format output with `click.echo`.
+- `discovery.py` — network discovery of speakers on the LAN; returns
+  `DiscoveredDevice`s. Uses `logging`, not `print`.
+
+## Conventions
+
+- **Types live in `typing.py`.** If a type is used by more than one module — or would
+  cause a circular import if defined in `__init__` — define it there. `__init__`
+  re-exports the ones it uses so `from edifier_es300 import Source` keeps working.
+  (Enums not referenced by `__init__`, like `BatteryStatus`, are imported from
+  `edifier_es300.typing` to avoid an unused import.)
+- **Type aliases use the `type` keyword** (PEP 695): `type FrameData = dict[str, Any]`.
+- **Name collisions get a trailing underscore.** Prefer a descriptive name first
+  (this is why the JSON-dict alias is `FrameData`, not `json_`); fall back to a `_`
+  suffix only for a genuine clash with a stdlib module or builtin.
+- **No 1–2 character variable names.** Spell them out (`header_pos`, `payload_len`,
+  `device`, `frame`, `chunk`).
+- **Device settings are enums.** `IntEnum` for index-valued settings (`Source`,
+  `EqPreset`, `LightEffect`, `BatteryStatus`, `PlayerStatus`); a plain `Enum` for `LightColor` (its
+  value is the RGB payload). For display, format members with `repr` (`%r` / `{x!r}`),
+  which gives `<Source.AIRPLAY: 3>`; plain `str` on an `IntEnum` is just the number.
+  Index enums also accept a raw `int` in method signatures (`Source | int`).
+- **CLI:** one `click` command per action; enum args use `click.Choice(...)` resolved
+  via `Enum[name.upper()]`. Omitting `--host` triggers auto-discovery.
+- **Logging, not print,** in library/discovery code. Only the CLI emits output
+  (through `click.echo`).
+
+## Python gotchas hit here
+
+- **`IntEnum.__str__` returns the number** in 3.11+ (`str(Source.AIRPLAY)` → `3`, not
+  `Source.AIRPLAY`). Use `repr` for display (`%r`) — `repr(Source.AIRPLAY)` →
+  `<Source.AIRPLAY: 3>` — which is why `Status.__str__` formats enum fields with `%r`.
+- **An `IntEnum` member with value `0` is falsy** (`EqPreset.CLASSIC`). Never test an
+  enum lookup with truthiness — use `is None`.
+- **`LightColor`'s value is a dict** (unhashable). `LightColor(some_dict)` still works
+  because `Enum.__new__` falls back to a linear value search, but the hashed
+  value→member map isn't built for it.
+- **PEP 695 `type` aliases are lazy** — the right-hand side isn't evaluated at import.
+  That's what lets `typing.py` hold `CommandResult = tuple[bool, Status | None]` and be
+  imported by `__init__` without an import cycle.
+
+## Testing
+
+- **Verify against the real speaker.** This project favors empirical checks over specs:
+  after a change, run the CLI live — typically `status`, then the command you changed,
+  then `status` again to confirm the effect landed.
+- Use `uv` + the project venv for tooling. The library itself needs no dependencies.
+
+## Running
+
+The package modules sit at the top of this directory, so run from the directory that
+*contains* `edifier_es300/`:
+
+- CLI: `python -m edifier_es300 <command>`
+- Library: `from edifier_es300 import ES300`
+
+The interpreter needs `click` importable for the CLI.

edifier_es300-0.1.1/PKG-INFO

@@ -0,0 +1,149 @@
+Metadata-Version: 2.4
+Name: edifier-es300
+Version: 0.1.1
+Summary: Add your description here
+Requires-Python: >=3.13
+Requires-Dist: click>=8.4.2
+Description-Content-Type: text/markdown
+
+# edifier_es300
+
+Control an **Edifier ES300** speaker over Wi-Fi, without the Edifier Home app.
+Ships an `asyncio` library and a `click`-based command-line interface.
+
+- **Library** (`edifier_es300`): stdlib-only, fully async.
+- **CLI** (`python -m edifier_es300`): thin wrapper over the library; needs `click`.
+
+## Requirements
+
+- Python 3.13+
+- `click` (CLI only — the library has no third-party dependencies)
+
+```bash
+uv sync        # or: pip install click
+```
+
+## Library usage
+
+Everything is async. The `ES300` connection is an async context manager — reuse a
+single connection for a burst of commands (the device drops an idle socket after a
+few seconds).
+
+```python
+import asyncio
+from edifier_es300 import ES300, Source, EqPreset, LightEffect, LightColor
+
+async def main():
+    async with ES300("192.168.1.123", 8080) as device:
+        print(await device.status())          # parsed Status (see below)
+
+        await device.volume(20)               # 0..30
+        await device.play()                   # resume
+        await device.pause()                  # pause
+        await device.play_pause_toggle()      # toggle
+        await device.next_track()
+        await device.prev_track()
+
+        await device.input_source(Source.AIRPLAY)
+
+        await device.light_switch(True)
+        await device.brightness(60)           # 0..100
+        await device.light_effect(LightEffect.BREATHING)
+        await device.light_color(LightColor.YELLOW)
+
+        await device.eq_preset(EqPreset.VOCAL)
+        await device.eq_custom([10, 5, 0, 0, 0, -5])   # tenths of a dB (-30..30)
+
+asyncio.run(main())
+```
+
+### Discovery
+
+`ES300.discover()` broadcasts on the LAN and returns a list of ready-to-use
+`ES300` objects (host, port, and name filled in):
+
+```python
+speakers = await ES300.discover(seconds=3.0)
+for speaker in speakers:
+    print(speaker)            # "EDIFIER ES300  192.168.1.123:8080"
+
+async with speakers[0] as device:
+    await device.volume(15)
+```
+
+### Return values
+
+- Command methods (`volume`, `play`, `input_source`, `eq_custom`, …) return
+  `CommandResult`, a `tuple[bool, Status | None]` of `(acknowledged, new_state)`.
+- `status()` returns a `Status | None` (`None` only if the device stays silent).
+
+### `Status`
+
+`str(status)` renders a human-readable dump (this is what the CLI `status` prints):
+
+```
+playing: - / - (status 0)
+volume : 6 / 30
+source : Source.AIRPLAY
+effect : LightEffect.STATIC
+color  : LightColor.YELLOW
+eq     : EqPreset.CLASSIC gains=[0, 0, 0, 0, 0, 0]
+battery: 100% (BatteryStatus.CONNECTED)
+```
+
+Fields: `volume`, `max_volume`, `song`, `lyric`, `player_status`, `input_source`,
+`light_effect`, `sound_index`, `eq_selected_index`, `eq_gains`, `battery`, and
+`raw` (the full status frame for anything not surfaced).
+
+### Enums
+
+| Enum | Values | Notes |
+|------|--------|-------|
+| `Source` | `BLUETOOTH=0`, `AUX=1`, `USB=2`, `AIRPLAY=3` | input source |
+| `EqPreset` | `CLASSIC=0`, `MONITOR=1`, `GAME=2`, `VOCAL=3`, `CUSTOMIZED=4` | `CUSTOMIZED` is the editable slot |
+| `LightEffect` | `STATIC=1`, `BREATHING=2`, `WATERFLOW=3` | ambient LED effect |
+| `LightColor` | `YELLOW`, `WHITE` | value is the RGB dict; hardware only does these two |
+| `BatteryStatus` | `CONNECTED=1`, `DISCONNECTED=2` | external power state (read-only) |
+
+`Source`, `EqPreset`, and `LightEffect` are `IntEnum`s, so methods also accept a
+plain `int`. Setting `eq_custom` gains automatically selects `EqPreset.CUSTOMIZED`.
+
+## CLI usage
+
+```bash
+python -m edifier_es300 [--host IP] [--port N] COMMAND [ARGS]
+```
+
+- `--host` — speaker IP. Omit it to **auto-discover** the first speaker on the LAN.
+- `--port` — control-channel TCP port (default `8080`).
+
+| Command | Args | Description |
+|---------|------|-------------|
+| `discover` | — | list speakers on the LAN (`name  ip:port`) |
+| `status` | — | dump volume / source / light / EQ / battery |
+| `vol` | `LEVEL` (0..30) | set volume |
+| `play` / `pause` | — | resume / pause playback |
+| `play-pause` | — | toggle play/pause |
+| `next` / `prev` | — | skip track |
+| `light` | `on` \| `off` | LED strip on/off |
+| `light-brightness` | `LEVEL` (0..100) | LED brightness |
+| `light-effect` | `static` \| `breathing` \| `waterflow` | LED effect |
+| `light-color` | `yellow` \| `white` | LED color |
+| `source` | `bluetooth` \| `aux` \| `usb` \| `airplay` | input source |
+| `preset` | `classic` \| `monitor` \| `game` \| `vocal` \| `customized` | EQ preset |
+| `eq` | `GAINS...` | 6 custom gains, tenths of a dB (-30..30 = -3.0..+3.0 dB) |
+
+### Examples
+
+```bash
+python -m edifier_es300 discover
+python -m edifier_es300 status                       # auto-discover, then dump state
+python -m edifier_es300 --host 192.168.1.123 vol 22
+python -m edifier_es300 source airplay
+python -m edifier_es300 light-effect breathing
+python -m edifier_es300 light-color yellow
+python -m edifier_es300 preset vocal
+python -m edifier_es300 eq -- 10 5 0 0 0 -5          # use -- so negatives aren't read as options
+```
+
+> Note: negative EQ gains look like CLI options, so prefix the gain list with `--`.

edifier_es300-0.1.1/README.md

@@ -0,0 +1,141 @@
+# edifier_es300
+
+Control an **Edifier ES300** speaker over Wi-Fi, without the Edifier Home app.
+Ships an `asyncio` library and a `click`-based command-line interface.
+
+- **Library** (`edifier_es300`): stdlib-only, fully async.
+- **CLI** (`python -m edifier_es300`): thin wrapper over the library; needs `click`.
+
+## Requirements
+
+- Python 3.13+
+- `click` (CLI only — the library has no third-party dependencies)
+
+```bash
+uv sync        # or: pip install click
+```
+
+## Library usage
+
+Everything is async. The `ES300` connection is an async context manager — reuse a
+single connection for a burst of commands (the device drops an idle socket after a
+few seconds).
+
+```python
+import asyncio
+from edifier_es300 import ES300, Source, EqPreset, LightEffect, LightColor
+
+async def main():
+    async with ES300("192.168.1.123", 8080) as device:
+        print(await device.status())          # parsed Status (see below)
+
+        await device.volume(20)               # 0..30
+        await device.play()                   # resume
+        await device.pause()                  # pause
+        await device.play_pause_toggle()      # toggle
+        await device.next_track()
+        await device.prev_track()
+
+        await device.input_source(Source.AIRPLAY)
+
+        await device.light_switch(True)
+        await device.brightness(60)           # 0..100
+        await device.light_effect(LightEffect.BREATHING)
+        await device.light_color(LightColor.YELLOW)
+
+        await device.eq_preset(EqPreset.VOCAL)
+        await device.eq_custom([10, 5, 0, 0, 0, -5])   # tenths of a dB (-30..30)
+
+asyncio.run(main())
+```
+
+### Discovery
+
+`ES300.discover()` broadcasts on the LAN and returns a list of ready-to-use
+`ES300` objects (host, port, and name filled in):
+
+```python
+speakers = await ES300.discover(seconds=3.0)
+for speaker in speakers:
+    print(speaker)            # "EDIFIER ES300  192.168.1.123:8080"
+
+async with speakers[0] as device:
+    await device.volume(15)
+```
+
+### Return values
+
+- Command methods (`volume`, `play`, `input_source`, `eq_custom`, …) return
+  `CommandResult`, a `tuple[bool, Status | None]` of `(acknowledged, new_state)`.
+- `status()` returns a `Status | None` (`None` only if the device stays silent).
+
+### `Status`
+
+`str(status)` renders a human-readable dump (this is what the CLI `status` prints):
+
+```
+playing: - / - (status 0)
+volume : 6 / 30
+source : Source.AIRPLAY
+effect : LightEffect.STATIC
+color  : LightColor.YELLOW
+eq     : EqPreset.CLASSIC gains=[0, 0, 0, 0, 0, 0]
+battery: 100% (BatteryStatus.CONNECTED)
+```
+
+Fields: `volume`, `max_volume`, `song`, `lyric`, `player_status`, `input_source`,
+`light_effect`, `sound_index`, `eq_selected_index`, `eq_gains`, `battery`, and
+`raw` (the full status frame for anything not surfaced).
+
+### Enums
+
+| Enum | Values | Notes |
+|------|--------|-------|
+| `Source` | `BLUETOOTH=0`, `AUX=1`, `USB=2`, `AIRPLAY=3` | input source |
+| `EqPreset` | `CLASSIC=0`, `MONITOR=1`, `GAME=2`, `VOCAL=3`, `CUSTOMIZED=4` | `CUSTOMIZED` is the editable slot |
+| `LightEffect` | `STATIC=1`, `BREATHING=2`, `WATERFLOW=3` | ambient LED effect |
+| `LightColor` | `YELLOW`, `WHITE` | value is the RGB dict; hardware only does these two |
+| `BatteryStatus` | `CONNECTED=1`, `DISCONNECTED=2` | external power state (read-only) |
+
+`Source`, `EqPreset`, and `LightEffect` are `IntEnum`s, so methods also accept a
+plain `int`. Setting `eq_custom` gains automatically selects `EqPreset.CUSTOMIZED`.
+
+## CLI usage
+
+```bash
+python -m edifier_es300 [--host IP] [--port N] COMMAND [ARGS]
+```
+
+- `--host` — speaker IP. Omit it to **auto-discover** the first speaker on the LAN.
+- `--port` — control-channel TCP port (default `8080`).
+
+| Command | Args | Description |
+|---------|------|-------------|
+| `discover` | — | list speakers on the LAN (`name  ip:port`) |
+| `status` | — | dump volume / source / light / EQ / battery |
+| `vol` | `LEVEL` (0..30) | set volume |
+| `play` / `pause` | — | resume / pause playback |
+| `play-pause` | — | toggle play/pause |
+| `next` / `prev` | — | skip track |
+| `light` | `on` \| `off` | LED strip on/off |
+| `light-brightness` | `LEVEL` (0..100) | LED brightness |
+| `light-effect` | `static` \| `breathing` \| `waterflow` | LED effect |
+| `light-color` | `yellow` \| `white` | LED color |
+| `source` | `bluetooth` \| `aux` \| `usb` \| `airplay` | input source |
+| `preset` | `classic` \| `monitor` \| `game` \| `vocal` \| `customized` | EQ preset |
+| `eq` | `GAINS...` | 6 custom gains, tenths of a dB (-30..30 = -3.0..+3.0 dB) |
+
+### Examples
+
+```bash
+python -m edifier_es300 discover
+python -m edifier_es300 status                       # auto-discover, then dump state
+python -m edifier_es300 --host 192.168.1.123 vol 22
+python -m edifier_es300 source airplay
+python -m edifier_es300 light-effect breathing
+python -m edifier_es300 light-color yellow
+python -m edifier_es300 preset vocal
+python -m edifier_es300 eq -- 10 5 0 0 0 -5          # use -- so negatives aren't read as options
+```
+
+> Note: negative EQ gains look like CLI options, so prefix the gain list with `--`.

edifier_es300-0.1.1/edifier_es300/__init__.py

@@ -0,0 +1,264 @@
+"""
+Edifier ES300 local control over Wi-Fi (reverse-engineered from Edifier Home 3.3.9).
+
+Transport: raw TCP to <ip>:8080
+  outbound (client->device): XOR_0xA5( json_utf8 )                 -- no header
+  inbound  (device->client): EE DD FF EE | len(2,BE) | json , whole frame XOR_0xA5
+
+Every command carries an "id". The device echoes that id back in:
+  - a `settings` ack frame      {payload:"settings",    id:<id>, message:"success"}
+  - a change-triggered status    {payload:"status_query", id:<id>, ...full state...}
+both ~1s later. We read until the matching id arrives instead of polling on a timer.
+
+Envelope: {"id":"<ms-timestamp>","payload":"settings","<field>":<obj>}
+Note: the device drops a session after ~5s of silence, so reuse one connection --
+the async context manager holds a single connection open for its lifetime.
+
+Verified live: volume, transport, light (on/off, mode, brightness, warm/cool),
+EQ (preset + 6-band custom), input source.
+
+Usage:
+    async with ES300("192.168.1.123") as device:
+        status = await device.status()
+        await device.volume(20)
+"""
+
+import asyncio
+import json
+import time
+from collections.abc import AsyncIterator
+from typing import Any
+
+from edifier_es300.typing_ import (
+    CommandResult,
+    EqPreset,
+    FrameData,
+    LightColor,
+    LightEffect,
+    PlayerStatus,
+    Source,
+    Status,
+)
+
+KEY: int = 0xA5
+FRAME_HEADER: bytes = b"\xee\xdd\xff\xee"
+
+
+def _xor(data: bytes) -> bytes:
+    return bytes(byte ^ KEY for byte in data)
+
+
+def _uid() -> str:
+    return str(int(time.time() * 1000))
+
+
+class ES300:
+    def __init__(self, host, port, name: str | None = None) -> None:
+        self.name: str | None = name  # from discovery; refreshed by status if present
+        self._host: str = host
+        self._port: int = port
+        self._reader: asyncio.StreamReader | None = None
+        self._writer: asyncio.StreamWriter | None = None
+        self._buffer = bytearray()  # decoded receive buffer; consumed bytes are trimmed
+        self._offset: int = 0  # scan cursor into _buffer
+
+    def __str__(self) -> str:
+        return "%s  %s:%s" % (self.name or "?", self._host, self._port)
+
+    @classmethod
+    async def discover(cls, seconds: float = 3.0) -> list["ES300"]:
+        """Broadcast-discover ES300 speakers on the LAN; one ES300 per device."""
+        from .discovery import discover
+
+        found = await discover(timeout=seconds)
+        return [
+            cls(
+                host=device.host or device.address,
+                port=device.port,
+                name=device.name,
+            )
+            for device in found
+        ]
+
+    def _absorb_name(self, status: "Status | None") -> "Status | None":
+        """Let a received status override the discovery name (when it carries one)."""
+        if status is not None:
+            name = status.raw.get("name")
+            if name:
+                self.name = name
+        return status
+
+    # --- connection lifecycle ---
+    async def __aenter__(self) -> "ES300":
+        self._reader, self._writer = await asyncio.open_connection(
+            self._host, self._port
+        )
+        return self
+
+    async def __aexit__(self, *exc: object) -> None:
+        if self._writer is not None:
+            self._writer.close()
+            try:
+                await self._writer.wait_closed()
+            except Exception:
+                pass
+        self._reader = self._writer = None
+
+    # --- framing ---
+    async def _send_raw(self, message: FrameData) -> None:
+        assert self._writer is not None, "not connected (use 'async with')"
+        self._writer.write(_xor(json.dumps(message).encode()))
+        await self._writer.drain()
+
+    async def _frames(self, seconds: float) -> AsyncIterator[FrameData]:
+        """Yield inbound JSON frames as they arrive, up to `seconds` seconds."""
+        assert self._reader is not None, "not connected (use 'async with')"
+        loop = asyncio.get_running_loop()
+        deadline = loop.time() + seconds
+        # Outer loop: keep pulling bytes off the socket until the deadline passes.
+        while True:
+            # Inner loop: drain every complete frame already sitting in the buffer.
+            # A frame is HDR + 2-byte big-endian length + that many payload bytes;
+            # we stop as soon as the next frame is missing or only partially received.
+            while True:
+                header_pos = self._buffer.find(FRAME_HEADER, self._offset)
+                if header_pos < 0 or header_pos + 6 > len(self._buffer):
+                    break  # no header yet, or length bytes not fully received
+                payload_len = (self._buffer[header_pos + 4] << 8) | self._buffer[
+                    header_pos + 5
+                ]
+                payload_start = header_pos + 6
+                payload_end = payload_start + payload_len
+                if payload_end > len(self._buffer):
+                    break  # payload still arriving; wait for more bytes
+                frame = self._buffer[payload_start:payload_end]
+                self._offset = payload_end
+                try:
+                    yield json.loads(frame)
+                except Exception:
+                    pass
+            # Drop consumed frames so the buffer only holds the unparsed tail --
+            # otherwise it would grow for the life of a long-running connection.
+            if self._offset:
+                del self._buffer[: self._offset]
+                self._offset = 0
+            remaining = deadline - loop.time()
+            if remaining <= 0:
+                return
+            try:
+                chunk = await asyncio.wait_for(
+                    self._reader.read(8192), timeout=remaining
+                )
+            except TimeoutError:
+                return
+            if not chunk:
+                return
+            self._buffer += _xor(chunk)
+
+    # --- core request/response ---
+    async def _command(
+        self, field: str, obj: Any, payload: str = "settings", seconds: float = 5.0
+    ) -> CommandResult:
+        """Send a setting and wait for the id-matched ack + status.
+        Returns (ok: bool, status: Status|None)."""
+        message_id = _uid()
+        await self._send_raw({"id": message_id, "payload": payload, field: obj})
+        acked: bool | None = None
+        status: Status | None = None
+        async for frame in self._frames(seconds):
+            if frame.get("id") != message_id:
+                continue
+            if frame.get("payload") == "settings":
+                acked = frame.get("message") == "success"
+            elif frame.get("payload") == "status_query":
+                status = self._absorb_name(Status.from_frame(frame))
+            if acked is not None and status is not None:
+                break
+        return bool(acked), status
+
+    # --- commands ---
+    async def status(self, seconds: float = 6.0) -> Status | None:
+        """Request full state; return the parsed status (id-matched if possible)."""
+        message_id = _uid()
+        await self._send_raw({"id": message_id, "payload": "status_query"})
+        fallback: Status | None = None
+        async for frame in self._frames(seconds):
+            if frame.get("payload") == "status_query":
+                parsed = self._absorb_name(Status.from_frame(frame))
+                if frame.get("id") == message_id:
+                    return parsed
+                fallback = parsed
+        return fallback
+
+    async def volume(self, level: int) -> CommandResult:
+        return await self._command("player", {"volume": level})  # 0..30
+
+    async def play(self) -> CommandResult:
+        return await self._command(
+            "player", {"playerStatus": int(PlayerStatus.PLAYING)}
+        )
+
+    async def pause(self) -> CommandResult:
+        return await self._command(
+            "player", {"playerStatus": int(PlayerStatus.STOPPED)}
+        )
+
+    async def play_pause_toggle(self) -> CommandResult:
+        # Toggle by sending the opposite of the current state, like the app's button.
+        current = await self.status()
+        playing = current is not None and current.player_status is PlayerStatus.PLAYING
+        target = PlayerStatus.STOPPED if playing else PlayerStatus.PLAYING
+        return await self._command("player", {"playerStatus": int(target)})
+
+    async def next_track(self) -> CommandResult:
+        return await self._command("player", {"next": 1})
+
+    async def prev_track(self) -> CommandResult:
+        return await self._command("player", {"previous": 1})
+
+    async def brightness(self, level: int) -> CommandResult:
+        return await self._command("lightEffect", {"brightness": level})  # 0..100
+
+    async def light_switch(self, enabled: bool) -> CommandResult:
+        return await self._command("lightEffect", {"lightSwitch": int(enabled)})
+
+    async def light_effect(self, effect: LightEffect | int) -> CommandResult:
+        return await self._command("lightEffect", {"selectedIndex": int(effect)})
+
+    async def light_color(self, color: LightColor) -> CommandResult:
+        return await self._command("lightEffect", {"color": color.value})
+
+    async def input_source(self, source: Source | int) -> CommandResult:
+        return await self._command("inputSource", {"selectedIndex": int(source)})
+
+    # EQ. Active EQ is chosen by selectedIndex (index into the speaker's preset list;
+    # the last entry is the editable custom slot, auto-selected when you set gains).
+    async def eq_preset(self, preset: EqPreset | int) -> CommandResult:
+        current = await self.status()
+        sound_index = current.sound_index if current else 2
+        return await self._command(
+            "soundEffect",
+            {"soundIndex": sound_index, "selectedIndex": int(preset)},
+        )
+
+    async def eq_custom(
+        self, gains: list[int]
+    ) -> CommandResult:  # up to 6 ints in tenths of a dB (-30..30 = -3.0..+3.0 dB), for 62/250/1k/4k/8k/16k Hz
+        current = await self.status()
+        if current is None:
+            return (False, None)
+        sound_effect = current.raw["soundEffect"]
+        diy = sound_effect["soundEffectDIY"]
+        for index, gain in enumerate(gains):
+            if index < len(diy["diyData"]):
+                diy["diyData"][index]["gain"]["value"] = gain
+        return await self._command(
+            "soundEffect",
+            {
+                "soundIndex": sound_effect["soundIndex"],
+                "selectedIndex": int(
+                    EqPreset.CUSTOMIZED
+                ),  # editing gains selects the custom slot
+                "soundEffectDIY": diy,
+            },
+        )

edifier_es300-0.1.1/edifier_es300/__main__.py

@@ -0,0 +1,209 @@
+import asyncio
+from collections.abc import Awaitable, Callable
+from typing import NamedTuple
+
+import click
+
+from edifier_es300 import ES300, EqPreset, LightColor, LightEffect, Source, Status
+from edifier_es300.typing_ import CommandResult
+
+DEFAULT_PORT: int = 8080
+
+type Action = Callable[[ES300], Awaitable]
+
+
+class Target(NamedTuple):
+    """Where to reach the speaker; host None means auto-discover on the LAN."""
+
+    host: str | None
+    port: int
+
+
+async def _resolve(target: Target) -> ES300:
+    """Return the target speaker: the given host, or the first one discovered."""
+    if target.host:
+        return ES300(target.host, target.port)
+    speakers = await ES300.discover()
+    if not speakers:
+        raise click.ClickException("no ES300 speakers found on the network")
+    return speakers[0]
+
+
+def _execute(target: Target, action: Action):
+    """Open a short-lived connection and run one coroutine against the device."""
+
+    async def runner():
+        device = await _resolve(target)
+        async with device:
+            return await action(device)
+
+    return asyncio.run(runner())
+
+
+def _report(label: str, result: CommandResult) -> Status | None:
+    acked, status = result
+    click.echo(("OK " if acked else "?? ") + label)
+    return status
+
+
+@click.group()
+@click.option(
+    "--host", default=None, help="Speaker IP (default: auto-discover on the LAN)."
+)
+@click.option(
+    "--port", default=DEFAULT_PORT, show_default=True, help="Control-channel TCP port."
+)
+@click.pass_context
+def cli(ctx: click.Context, host: str | None, port: int) -> None:
+    """Control an Edifier ES300 speaker over Wi-Fi."""
+    ctx.obj = Target(host, port)
+
+
+@cli.command()
+def discover() -> None:
+    """List ES300 speakers found on the local network."""
+    speakers = asyncio.run(ES300.discover())
+    if not speakers:
+        click.echo("no ES300 speakers found (same Wi-Fi as the speaker?)")
+        return
+    for speaker in speakers:
+        click.echo(speaker)
+
+
+@cli.command()
+@click.pass_obj
+def status(target: Target) -> None:
+    """Dump volume / source / light / EQ / battery."""
+    current = _execute(target, lambda device: device.status())
+    click.echo(current or "no status (device idle; retry)")
+
+
+@cli.command()
+@click.argument("level", type=click.IntRange(0, 30))
+@click.pass_obj
+def volume(target: Target, level: int) -> None:
+    """Set volume (0..30)."""
+    current = _report(
+        f"volume={level}", _execute(target, lambda device: device.volume(level))
+    )
+    click.echo("now %s" % (current.volume if current else "?"))
+
+
+@cli.command()
+@click.pass_obj
+def play(target: Target) -> None:
+    """Resume playback."""
+    _report("play", _execute(target, lambda device: device.play()))
+
+
+@cli.command()
+@click.pass_obj
+def pause(target: Target) -> None:
+    """Pause playback."""
+    _report("pause", _execute(target, lambda device: device.pause()))
+
+
+@cli.command()
+@click.pass_obj
+def play_pause(target: Target) -> None:
+    """Toggle play/pause."""
+    _report("play-pause", _execute(target, lambda device: device.play_pause_toggle()))
+
+
+@cli.command()
+@click.pass_obj
+def next(target: Target) -> None:
+    """Next track."""
+    _report("next", _execute(target, lambda device: device.next_track()))
+
+
+@cli.command()
+@click.pass_obj
+def previous(target: Target) -> None:
+    """Previous track."""
+    _report("prev", _execute(target, lambda device: device.prev_track()))
+
+
+@cli.command()
+@click.argument("level", type=click.IntRange(0, 100))
+@click.pass_obj
+def light_brightness(target: Target, level: int) -> None:
+    """Set LED brightness (0..100)."""
+    _report(
+        f"brightness={level}", _execute(target, lambda device: device.brightness(level))
+    )
+
+
+@cli.command()
+@click.argument("state", type=click.Choice(["on", "off"]))
+@click.pass_obj
+def light(target: Target, state: str) -> None:
+    """Turn the LED strip on/off."""
+    _report(
+        f"light {state}",
+        _execute(target, lambda device: device.light_switch(state == "on")),
+    )
+
+
+@cli.command()
+@click.argument("name", type=click.Choice(["static", "breathing", "waterflow"]))
+@click.pass_obj
+def light_effect(target: Target, name: str) -> None:
+    """Set light effect."""
+    chosen = LightEffect[name.upper()]
+    _report(
+        f"effect {name}", _execute(target, lambda device: device.light_effect(chosen))
+    )
+
+
+@cli.command()
+@click.argument("name", type=click.Choice(["yellow", "white"]))
+@click.pass_obj
+def light_color(target: Target, name: str) -> None:
+    """Set light color (yellow or white)."""
+    chosen = LightColor[name.upper()]
+    _report(
+        f"color {name}",
+        _execute(target, lambda device: device.light_color(chosen)),
+    )
+
+
+@cli.command()
+@click.argument("name", type=click.Choice(["bluetooth", "aux", "usb", "airplay"]))
+@click.pass_obj
+def source(target: Target, name: str) -> None:
+    """Select input source."""
+    chosen = Source[name.upper()]
+    _report(
+        f"source {name}", _execute(target, lambda device: device.input_source(chosen))
+    )
+
+
+@cli.command()
+@click.argument(
+    "name", type=click.Choice(["classic", "monitor", "game", "vocal", "customized"])
+)
+@click.pass_obj
+def preset(target: Target, name: str) -> None:
+    """Select an EQ preset."""
+    chosen = EqPreset[name.upper()]
+    current = _report(
+        f"preset {name}", _execute(target, lambda device: device.eq_preset(chosen))
+    )
+    click.echo("selectedIndex %s" % (current.eq_selected_index if current else "?"))
+
+
+@cli.command()
+@click.argument("gains", type=int, nargs=-1)
+@click.pass_obj
+def eq(target: Target, gains: tuple[int, ...]) -> None:
+    """Set custom 6-band gains in tenths of a dB (-30..30 = -3.0..+3.0 dB), for 62/250/1k/4k/8k/16k Hz."""
+    label = "eq %s" % " ".join(str(gain) for gain in gains)
+    current = _report(
+        label, _execute(target, lambda device: device.eq_custom(list(gains)))
+    )
+    click.echo("gains %s" % (current.eq_gains if current else "?"))
+
+
+if __name__ == "__main__":
+    cli()

edifier_es300-0.1.1/edifier_es300/discovery.py

@@ -0,0 +1,146 @@
+"""
+Auto-discovery for Edifier ES300 speakers on the local network.
+
+The Edifier Home app finds speakers with a UDP broadcast handshake on port 6000
+(not mDNS -- the app's Bonjour libs are only for AirPlay):
+
+  1. The app broadcasts, to 255.255.255.255:6000, the plaintext query:
+         {"firm":"EDF","phoneOS":1,"protocol":1}
+  2. Each speaker replies (on port 6000) with a plaintext `AudioWlan` JSON:
+         {"encryption":<xor key>, "firm":"EDF", "protocol":1, "product":..., "player":...,
+          "info":{"host":<ip>, "port":8080, "name":..., "uuid":..., "bluetoothMac":..., "wifiMac":...}}
+  3. The app then opens the TCP control channel at info.host:info.port.
+
+Unlike the control channel, discovery frames are NOT XOR-obfuscated -- both the
+query and the reply are plain UTF-8 JSON.
+
+Usage:
+    devices = await discover()
+    if devices:
+        async with ES300(devices[0].host, devices[0].port) as speaker:
+            ...
+
+Run standalone:
+    python -m edifier_es300.discovery
+"""
+
+import asyncio
+import json
+import logging
+from dataclasses import dataclass
+
+from edifier_es300.typing_ import FrameData
+
+logger = logging.getLogger(__name__)
+
+DISCOVERY_PORT: int = 6000
+BROADCAST_ADDR: str = "255.255.255.255"
+DISCOVERY_QUERY: FrameData = {"firm": "EDF", "phoneOS": 1, "protocol": 1}
+
+
+@dataclass
+class DiscoveredDevice:
+    """A speaker that answered the discovery broadcast."""
+
+    name: str | None
+    host: str | None  # info.host -- the control-channel IP
+    port: int | None  # info.port -- the control-channel TCP port (8080)
+    uuid: int | None
+    bluetooth_mac: str | None
+    wifi_mac: str | None
+    encryption: int | None  # XOR key the control channel expects (0xA5 on ES300)
+    address: str  # UDP source IP of the reply (host fallback)
+    raw: FrameData  # the full AudioWlan reply
+
+    @classmethod
+    def from_reply(cls, data: FrameData, source_ip: str) -> "DiscoveredDevice":
+        info = data.get("info") or {}
+        return cls(
+            name=info.get("name"),
+            host=info.get("host") or source_ip,
+            port=info.get("port"),
+            uuid=info.get("uuid"),
+            bluetooth_mac=info.get("bluetoothMac"),
+            wifi_mac=info.get("wifiMac"),
+            encryption=data.get("encryption"),
+            address=source_ip,
+            raw=data,
+        )
+
+    def __str__(self) -> str:
+        return "%s  %s:%s  uuid=%s  mac address=%s  encryption=%s" % (
+            self.name or "?",
+            self.host,
+            self.port,
+            self.uuid,
+            self.wifi_mac,
+            self.encryption,
+        )
+
+
+class _DiscoveryProtocol(asyncio.DatagramProtocol):
+    """Collects AudioWlan replies, ignoring our own echoed broadcast."""
+
+    def __init__(self) -> None:
+        self.replies: list[tuple[FrameData, str]] = []
+
+    def datagram_received(self, data: bytes, addr: tuple[str, int]) -> None:
+        try:
+            obj = json.loads(data.decode("utf-8"))
+        except Exception:
+            return
+        # Our own broadcast (the query) has no "info"; only real replies do.
+        if isinstance(obj, dict) and obj.get("info"):
+            self.replies.append((obj, addr[0]))
+
+
+async def discover(timeout: float = 3.0, broadcasts: int = 3) -> list[DiscoveredDevice]:
+    """Broadcast the discovery query and collect replies for `timeout` seconds.
+
+    Sends the query `broadcasts` times (spread across the window) since UDP is
+    lossy. Returns one DiscoveredDevice per speaker, de-duplicated by host.
+    """
+    loop = asyncio.get_running_loop()
+    transport, protocol = await loop.create_datagram_endpoint(
+        _DiscoveryProtocol,
+        local_addr=("0.0.0.0", DISCOVERY_PORT),
+        allow_broadcast=True,
+    )
+    try:
+        payload = json.dumps(DISCOVERY_QUERY).encode("utf-8")
+        deadline = loop.time() + timeout
+        gap = timeout / max(1, broadcasts)
+        for _ in range(max(1, broadcasts)):
+            transport.sendto(payload, (BROADCAST_ADDR, DISCOVERY_PORT))
+            await asyncio.sleep(min(gap, max(0.0, deadline - loop.time())))
+        remaining = deadline - loop.time()
+        if remaining > 0:
+            await asyncio.sleep(remaining)
+    finally:
+        transport.close()
+
+    devices: dict[str, DiscoveredDevice] = {}
+    for reply, source_ip in protocol.replies:
+        device = DiscoveredDevice.from_reply(reply, source_ip)
+        devices[device.host or source_ip] = device  # dedupe by host
+    return list(devices.values())
+
+
+async def discover_one(timeout: float = 3.0) -> DiscoveredDevice | None:
+    """Return the first speaker found, or None."""
+    devices = await discover(timeout=timeout)
+    return devices[0] if devices else None
+
+
+async def _main() -> None:
+    devices = await discover()
+    if not devices:
+        logger.warning("no ES300 speakers found (same Wi-Fi as the speaker?)")
+        return
+    for device in devices:
+        logger.info("%s", device)
+
+
+if __name__ == "__main__":
+    logging.basicConfig(level=logging.INFO, format="%(message)s")
+    asyncio.run(_main())

edifier_es300-0.1.1/edifier_es300/typing_.py

@@ -0,0 +1,114 @@
+"""Shared types for the edifier_es300 package."""
+
+from dataclasses import dataclass
+from enum import Enum, IntEnum
+from typing import Any
+
+type FrameData = dict[str, Any]  # a decoded JSON protocol frame
+
+
+class Source(IntEnum):
+    """Input sources; value is inputSource.selectedIndex (all verified live)."""
+
+    BLUETOOTH = 0
+    AUX = 1
+    USB = 2
+    AIRPLAY = 3
+
+
+class EqPreset(IntEnum):
+    """EQ presets; value is soundEffect.selectedIndex (CUSTOMIZED is the custom slot)."""
+
+    CLASSIC = 0
+    MONITOR = 1
+    GAME = 2
+    VOCAL = 3
+    CUSTOMIZED = 4
+
+
+class LightColor(Enum):
+    """Ambient LED colors; value is the RGB the app sends (ES300 only does these two)."""
+
+    YELLOW = {"r": 255, "g": 170, "b": 60}
+    WHITE = {"r": 255, "g": 255, "b": 255}
+
+
+class LightEffect(IntEnum):
+    """Ambient LED effects; value is lightEffect.selectedIndex."""
+
+    STATIC = 1
+    BREATHING = 2
+    WATERFLOW = 3
+
+
+class BatteryStatus(IntEnum):
+    """Battery power state; value is battery.status."""
+
+    CONNECTED = 1  # external power connected
+    DISCONNECTED = 2  # running on battery
+
+
+class PlayerStatus(IntEnum):
+    """Playback state; value is player.playerStatus."""
+
+    STOPPED = 0
+    PLAYING = 1
+
+
+@dataclass
+class Status:
+    """Parsed device state from a `status_query` frame."""
+
+    volume: int
+    max_volume: int
+    song: str | None
+    lyric: str | None
+    player_status: PlayerStatus
+    input_source: FrameData
+    light_effect: FrameData
+    sound_index: int
+    eq_selected_index: int
+    eq_gains: list[int]
+    battery: Any
+    raw: FrameData  # the original frame, for fields not surfaced above
+
+    @classmethod
+    def from_frame(cls, frame: FrameData) -> "Status":
+        player = frame["player"]
+        sound_effect = frame["soundEffect"]
+        return cls(
+            volume=player["volume"],
+            max_volume=player["maxVolume"],
+            song=player.get("song"),
+            lyric=player.get("lyric"),
+            player_status=PlayerStatus(player["playerStatus"]),
+            input_source=frame["inputSource"],
+            light_effect=frame["lightEffect"],
+            sound_index=sound_effect["soundIndex"],
+            eq_selected_index=sound_effect["selectedIndex"],
+            eq_gains=[
+                band["gain"]["value"]
+                for band in sound_effect["soundEffectDIY"]["diyData"]
+            ],
+            battery=frame.get("battery"),
+            raw=frame,
+        )
+
+    def __str__(self) -> str:
+        return "\n".join(
+            (
+                "playing: %s / %s (status %r)"
+                % (self.song or "-", self.lyric or "-", self.player_status),
+                "volume : %s / %s" % (self.volume, self.max_volume),
+                "source : %r" % Source(self.input_source["selectedIndex"]),
+                "effect : %r" % LightEffect(self.light_effect["selectedIndex"]),
+                "color  : %r" % LightColor(self.light_effect["color"]),
+                "eq     : %r gains=%s"
+                % (EqPreset(self.eq_selected_index), self.eq_gains),
+                "battery: %s%% (%r)"
+                % (self.battery["box"], BatteryStatus(self.battery["status"])),
+            )
+        )
+
+
+type CommandResult = tuple[bool, Status | None]  # (acked, status)

edifier_es300-0.1.1/pyproject.toml

@@ -0,0 +1,28 @@
+[project]
+name = "edifier-es300"
+version = "0.1.1"
+description = "Add your description here"
+readme = "README.md"
+requires-python = ">=3.13"
+dependencies = [
+    "click>=8.4.2",
+]
+
+[project.scripts]
+edifier-es300 = "edifier_es300.__main__:cli"
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.ruff]
+target-version = "py313"
+
+[tool.ruff.lint]
+# E/F = pyflakes + pycodestyle (defaults), I = isort import sorting.
+# E501 (line length) is left to the formatter, which won't reflow comments.
+select = ["E", "F", "I"]
+ignore = ["E501"]
+
+[tool.ty.environment]
+python-version = "3.13"

edifier_es300-0.1.1/uv.lock

@@ -0,0 +1,35 @@
+version = 1
+revision = 3
+requires-python = ">=3.13"
+
+[[package]]
+name = "click"
+version = "8.4.2"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+    { name = "colorama", marker = "sys_platform == 'win32'" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/76/d4/81420972a676e8ffea40450d8c8c92943e7218a78fe9b64359836cc9876b/click-8.4.2.tar.gz", hash = "sha256:9a6cea6e60b17ebe0a44c5cc636d94f09bd66142c1cd7d8b4cd731c4917a15f6", size = 338000, upload-time = "2026-06-24T17:45:15.148Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/fb/e2/79c688af8b210d232694e31e59da9f6ec747bae31c3f5946e4e9b98860d5/click-8.4.2-py3-none-any.whl", hash = "sha256:e6f9f66136c816745b9d65817da91d61d957fb16e02e4dcd0552553c5a197b76", size = 119243, upload-time = "2026-06-24T17:45:13.73Z" },
+]
+
+[[package]]
+name = "colorama"
+version = "0.4.6"
+source = { registry = "https://pypi.org/simple" }
+sdist = { url = "https://files.pythonhosted.org/packages/d8/53/6f443c9a4a8358a93a6792e2acffb9d9d5cb0a5cfd8802644b7b1c9a02e4/colorama-0.4.6.tar.gz", hash = "sha256:08695f5cb7ed6e0531a20572697297273c47b8cae5a63ffc6d6ed5c201be6e44", size = 27697, upload-time = "2022-10-25T02:36:22.414Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/d1/d6/3965ed04c63042e047cb6a3e6ed1a63a35087b6a609aa3a15ed8ac56c221/colorama-0.4.6-py2.py3-none-any.whl", hash = "sha256:4f1d9991f5acc0ca119f9d443620b77f9d6b33703e51011c16baf57afb285fc6", size = 25335, upload-time = "2022-10-25T02:36:20.889Z" },
+]
+
+[[package]]
+name = "edifier-es300"
+version = "0.1.1"
+source = { editable = "." }
+dependencies = [
+    { name = "click" },
+]
+
+[package.metadata]
+requires-dist = [{ name = "click", specifier = ">=8.4.2" }]