feat: Add support for the AudioReactive usermod

src/wled/__init__.py

@@ -18,6 +18,7 @@
     WLEDUpgradeError,
 )
 from .models import (
+    AudioReactive,
     Color,
     Device,
     Effect,
@@ -39,6 +40,7 @@
 
 __all__ = [
     "WLED",
+    "AudioReactive",
     "Color",
     "Device",
     "Effect",

src/wled/models.py

@@ -149,6 +149,19 @@ class Nightlight(BaseModel):
     """Target brightness of nightlight feature."""
 
 
+@dataclass(kw_only=True)
+class AudioReactive(BaseModel):
+    """Object holding the AudioReactive usermod state in WLED.
+
+    The AudioReactive usermod reports its state in the `AudioReactive`
+    key of the state object. Note that the state is reported in the `on`
+    field, while changing the state is done using the `enabled` field.
+    """
+
+    on: bool = field(default=False)
+    """AudioReactive currently enabled."""
+
+
 @dataclass(kw_only=True)
 class UDPSync(BaseModel):
     """Object holding UDP sync state in WLED.
@@ -571,6 +584,14 @@ def __post_deserialize__(cls, obj: Info) -> Info:
 class State(BaseModel):
     """Object holding the state of WLED."""
 
+    audio_reactive: AudioReactive | None = field(
+        default=None, metadata=field_options(alias="AudioReactive")
+    )
+    """AudioReactive usermod state.
+
+    `None` if the AudioReactive usermod is not installed on the device.
+    """
+
     brightness: int = field(default=1, metadata=field_options(alias="bri"))
     """Brightness of the light.
 

src/wled/wled.py

@@ -632,6 +632,23 @@ async def nightlight(
         nightlight = {k: v for k, v in nightlight.items() if v is not None}
         await self.request("/json/state", method="POST", data={"nl": nightlight})
 
+    async def audio_reactive(self, *, on: bool) -> None:
+        """Control the AudioReactive usermod of a WLED device.
+
+        Args:
+        ----
+            on: A boolean, true to enable the AudioReactive usermod,
+                false otherwise.
+
+        """
+        # The AudioReactive usermod reports its state in the `on` field,
+        # but accepts state changes in the `enabled` field.
+        await self.request(
+            "/json/state",
+            method="POST",
+            data={"AudioReactive": {"enabled": on}},
+        )
+
     async def upgrade(  # noqa: PLR0912
         self,
         *,

tests/test_models.py

@@ -393,6 +393,20 @@ def test_state_preset_id_positive() -> None:
     assert state.preset_id == 3
 
 
+def test_state_audio_reactive_absent() -> None:
+    """Test audio_reactive is None when the usermod is not installed."""
+    state = State.from_dict(_base_state())
+    assert state.audio_reactive is None
+
+
+@pytest.mark.parametrize("on", [True, False])
+def test_state_audio_reactive_present(on: bool) -> None:
+    """Test audio_reactive state is deserialized when the usermod is present."""
+    state = State.from_dict(_base_state(AudioReactive={"on": on}))
+    assert state.audio_reactive is not None
+    assert state.audio_reactive.on is on
+
+
 # =========================================================================
 # Preset model
 # =========================================================================

tests/test_wled.py

@@ -896,6 +896,25 @@ async def test_nightlight(
     )
 
 
+@pytest.mark.parametrize("on", [True, False])
+async def test_audio_reactive(responses: aioresponses, wled: WLED, on: bool) -> None:
+    """Test setting AudioReactive usermod state."""
+    responses.post(
+        "http://example.com/json/state",
+        status=200,
+        body="{}",
+        content_type="application/json",
+    )
+
+    await wled.audio_reactive(on=on)
+
+    assert_post_payload(
+        responses,
+        "http://example.com/json/state",
+        {"AudioReactive": {"enabled": on}, "v": True},
+    )
+
+
 # =========================================================================
 # Section 14: WLED client - reset, close, context manager, connected
 # =========================================================================