feat: Add voice-assistant entity and audio-stream support (#38)

* voice_assistant entity and voice stream handler
* signal voice session termination reason to client

- For abnormal terminations (timeout, remote abort, local abort, error),
  raise specific exceptions from the iterator.
- expose metadata about the end (reason, error) via properties for post-
  loop inspection.
- Exception hierarchy:
  - `VoiceSessionClosed(Exception)` base with optional fields (reason, error).
  - `VoiceSessionTimeout(VoiceSessionClosed)`
  - `VoiceSessionRemoteEnd(VoiceSessionClosed)`
  - `VoiceSessionLocalEnd(VoiceSessionClosed)`
  - `VoiceSessionError(VoiceSessionClosed)`
- End reason type:
  - `VoiceEndReason` Enum: `NORMAL`, `TIMEOUT`, `REMOTE`, `LOCAL`, `ERROR`

* Enhance entity command handler with client connection

Pass the WS connection as an optional command parameter to the client.
This allows the client to send directed WS events back. Otherwise, the
only option is to use event broadcasts to all connected clients.
Implementation is backward compatible to existing clients without the
new websocket parameter in the CommandHandler callback, or extending a
concrete Entity class.

* Remove excessive logging in Entities.get method
* Import cleanup to avoid circular imports through the ucapi definition.
* Update readme

Author: zehnm

.idea/misc.xml

@@ -9,6 +9,17 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 _Changes in the next release_
 
+### Breaking Changes
+- Enhance entity command handler with WS client connection parameter in `CommandHandler` callback and `Entity.command`
+  method to allow clients to send back event messages.
+  - The implementation is currently backward-compatible but will be removed in a future release.
+
+### Added
+- New voice-assistant entity with voice-stream session handling.
+
+### Changed
+- Remove logging in Entities.get method if entity doesn't exist. This could lead to excessive logging in some integrations.
+
 ---
 
 ## v0.4.0 - 2025-11-24

.idea/runConfigurations/Check_isort.xml

@@ -4,23 +4,30 @@
 [![Code style: black](https://img.shields.io/badge/code%20style-black-000000.svg)](https://github.com/psf/black)
 
 This library simplifies writing Python-based integrations for the [Unfolded Circle Remote devices](https://www.unfoldedcircle.com/)
-by wrapping the [WebSocket Integration API](https://github.com/unfoldedcircle/core-api/tree/main/integration-api).
+by wrapping the [WebSocket Integration API](https://github.com/unfoldedcircle/core-api/tree/main/integration-api)
+and supporting the [available entities](https://unfoldedcircle.github.io/core-api/entities/).
 
-It's an alpha release (in our eyes). Breaking changes are to be expected and missing features will be continuously added.
-Based on our [Node.js integration library](https://github.com/unfoldedcircle/integration-node-library).
+> [!NOTE]
+> Please note that this library is more of a convenience Python wrapper for the WebSocket Integreation-API than a
+> full-featured SDK. It is based on our [Node.js integration library](https://github.com/unfoldedcircle/integration-node-library).
 
-❗️**Attention:**
+> [!IMPORTANT]
 > This is our first Python project, and we don't see ourselves as Python professionals.  
 > Therefore, the library is most likely not yet that Pythonic!  
 > We are still learning and value your feedback on how to improve it :-)
 
 Not yet supported:
 
 - Secure WebSocket
-- Token based authentication
+- Token-based authentication
 
 Requirements:
-- Python 3.10 or newer
+- Python 3.11 or newer
+
+Integrations using this library:
+  - [Android TV integration](https://github.com/unfoldedcircle/integration-androidtv)
+  - [Apple TV integration](https://github.com/unfoldedcircle/integration-appletv)
+  - [Denon AVR integration](https://github.com/unfoldedcircle/integration-denonavr)
 
 ## Installation
 
@@ -29,8 +36,7 @@ Use pip:
 pip3 install ucapi
 ```
 
-See [examples directory](https://github.com/aitatoi/integration-python-library/blob/main/examples) for a minimal
-integration driver example. More examples will be published.
+See [examples directory](https://github.com/aitatoi/integration-python-library/blob/main/examples) for some minimal integration driver examples.
 
 ### Environment Variables
 

.idea/runConfigurations/Run_isort.xml

@@ -16,3 +16,28 @@ Local installation:
 ```shell
 pip3 install --force-reinstall dist/ucapi-$VERSION-py3-none-any.whl
 ```
+
+## Protobuf
+
+1. Optional (recommended): install the Python plugin toolchain for consistent results:
+   ```bash
+   python3 -m pip install --upgrade grpcio-tools protobuf
+   ```
+2. From the project root, run:
+   ```bash
+   python3 scripts/compile_protos.py
+   ```
+   - This will generate `ucapi/proto/ucr_integration_voice_pb2.py` (and `.pyi` if supported).
+3. Add and commit the generated files to Git:
+   ```bash
+   git add ucapi/proto/ucr_integration_voice_pb2.py ucapi/proto/ucr_integration_voice_pb2.pyi || true
+   git commit -m "Generate protobuf Python modules for voice integration"
+   ```
+
+Notes:
+- The library does not re-generate at build time; we ship the generated code with the package.
+- If you prefer using system `protoc`, ensure it’s on `PATH`; the script will fall back to it automatically.
+- Imports at runtime (if/when needed) will look like:
+  ```python
+  from ucapi.proto import ucr_integration_voice_pb2 as voice_pb2
+  ```

CHANGELOG.md

@@ -1,6 +1,6 @@
 # API wrapper examples
 
-This directory contains a few examples on how to use the Remote Two Integration-API wrapper.
+This directory contains a few examples on how to use the Remote Two/3 Integration-API wrapper.
 
 Each example uses a driver metadata definition file. It's a json file named after the example.
 The most important fields are:
@@ -39,3 +39,9 @@ and are not yet available as typed Python objects.
 
 See `Setting` object definition and the referenced SettingTypeNumber, SettingTypeText, SettingTypeTextArea,
 SettingTypePassword, SettingTypeCheckbox, SettingTypeDropdown, SettingTypeLabel. 
+
+## voice
+
+The [voice ](voice.py) example shows how to use the voice-assistant entity and receiving a microphone audio stream.
+
+Firmware version 2.8.2 or higher is required.

README.md

@@ -11,7 +11,7 @@
 
 
 async def cmd_handler(
-    entity: ucapi.Button, cmd_id: str, _params: dict[str, Any] | None
+    entity: ucapi.Button, cmd_id: str, _params: dict[str, Any] | None, websocket: Any
 ) -> ucapi.StatusCodes:
     """
     Push button command handler.
@@ -21,6 +21,7 @@ async def cmd_handler(
     :param entity: button entity
     :param cmd_id: command
     :param _params: optional command parameters
+    :param websocket: optional client connection for sending directed events
     :return: status of the command
     """
     print(f"Got {entity.id} command request: {cmd_id}")

docs/setup.md

@@ -46,7 +46,7 @@
 
 
 async def cmd_handler(
-    entity: ucapi.Remote, cmd_id: str, params: dict[str, Any] | None
+    entity: ucapi.Remote, cmd_id: str, params: dict[str, Any] | None, websocket: Any
 ) -> ucapi.StatusCodes:
     """
     Remote command handler.
@@ -56,6 +56,7 @@ async def cmd_handler(
     :param entity: remote entity
     :param cmd_id: command
     :param params: optional command parameters
+    :param websocket: optional client connection for sending directed events
     :return: status of the command
     """
     print(f"Got {entity.id} command request: {cmd_id}")

examples/README.md

@@ -38,7 +38,7 @@ async def handle_driver_setup(
     """
     Start driver setup.
 
-    Initiated by Remote Two to set up the driver.
+    Initiated by Remote Two/3 to set up the driver.
 
     :param msg: value(s) of input fields in the first setup screen.
     :return: the setup action on how to continue
@@ -157,7 +157,7 @@ async def handle_user_data_response(msg: ucapi.UserDataResponse) -> ucapi.SetupA
 
 
 async def cmd_handler(
-    entity: ucapi.Button, cmd_id: str, _params: dict[str, Any] | None
+    entity: ucapi.Button, cmd_id: str, _params: dict[str, Any] | None, websocket: Any
 ) -> ucapi.StatusCodes:
     """
     Push button command handler.
@@ -167,6 +167,7 @@ async def cmd_handler(
     :param entity: button entity
     :param cmd_id: command
     :param _params: optional command parameters
+    :param websocket: optional client connection for sending directed events
     :return: status of the command
     """
     print(f"Got {entity.id} command request: {cmd_id}")