docs(ipc): document audio playback and source options

Author: DennisMoschina

README.md

@@ -38,7 +38,7 @@ audio_df = dataset.get_audio_dataframe()
 
 ```python
 import asyncio
-from open_wearable import OpenWearableIPCClient
+from open_wearables import OpenWearableIPCClient
 
 
 async def main() -> None:
@@ -58,6 +58,27 @@ async def main() -> None:
         await stream.close()
 
 
+asyncio.run(main())
+```
+
+## IPC Audio Example
+
+```python
+import asyncio
+from open_wearables import OpenWearableIPCClient
+
+
+async def main() -> None:
+    async with OpenWearableIPCClient("ws://192.168.1.23:8765/ws") as client:
+        await client.audio.store_sound_file("beep_ok", "beep.wav", codec="wav")
+        await client.audio.play_sound("beep_ok", volume=1.0, codec="wav")
+        await client.audio.play_sound(url="https://example.org/alert.wav", volume=0.7)
+
+        async with client.audio.stream(volume=0.8) as stream:
+            stream_bytes = b"...raw chunk bytes..."
+            await stream.push(stream_bytes)
+
+
 asyncio.run(main())
 ```
 
@@ -72,12 +93,12 @@ asyncio.run(main())
 
 The library is organized into focused layers:
 
-- `open_wearable.schema`: sensor schema types and default schema builders.
-- `open_wearable.parsing`: stream parsing, payload parsers, and microphone helpers.
-- `open_wearable.data`: high-level dataset API (`SensorDataset`) and sensor accessors.
-- `open_wearable.ipc`: asynchronous WebSocket IPC client and protocol models.
+- `open_wearables.schema`: sensor schema types and default schema builders.
+- `open_wearables.parsing`: stream parsing, payload parsers, and microphone helpers.
+- `open_wearables.data`: high-level dataset API (`SensorDataset`) and sensor accessors.
+- `open_wearables.ipc`: asynchronous WebSocket IPC client and protocol models.
 
-Legacy flat modules (`open_wearable.scheme`, `open_wearable.parser`, `open_wearable.dataset`) remain available as compatibility facades.
+Legacy flat modules (`open_wearables.scheme`, `open_wearables.parser`, `open_wearables.dataset`) remain available as compatibility facades.
 
 ## License
 

docs/api-reference.md

@@ -70,6 +70,39 @@ Other helpers:
 - `wearable.streams.battery_health_status()`
 - `wearable.streams.battery_energy_status()`
 
+### Audio Playback
+
+Raw websocket-aligned methods:
+
+- `store_sound(sound_id, audio_base64, codec=None, sample_rate=None, num_channels=None, interleaved=None, buffer_size=None)`
+- `play_sound(sound_id=None, url=None, volume=None, codec=None, sample_rate=None, num_channels=None)` (exactly one of `sound_id` or `url`)
+- `start_audio_stream(volume=None)`
+- `push_audio_stream_chunk(audio_base64)`
+- `stop_audio_stream()`
+
+Python-friendly helpers:
+
+- `store_sound_bytes(sound_id, audio_bytes, codec=None, sample_rate=None, num_channels=None, interleaved=None, buffer_size=None)`
+- `store_sound_file(sound_id, file_path, codec=None, sample_rate=None, num_channels=None, interleaved=None, buffer_size=None)`
+- `push_audio_stream_chunk_bytes(audio_chunk)`
+- `push_audio_stream_chunk_file(file_path)`
+- `client.audio.store_sound(...)`
+- `client.audio.store_sound_file(...)`
+- `client.audio.play_sound(...)`
+- `client.audio.stream(volume=...)` (context-managed `AudioStreamSession`)
+
+Example:
+
+```python
+async with OpenWearableIPCClient("ws://192.168.1.23:8765/ws") as client:
+    await client.audio.store_sound_file("beep_ok", "beep.wav")
+    await client.audio.play_sound("beep_ok", volume=1.0)
+    await client.audio.play_sound(url="https://example.org/alert.wav", volume=0.7)
+
+    async with client.audio.stream(volume=0.8) as stream:
+        await stream.push(chunk_bytes)
+```
+
 ## `SensorDataset`
 
 High-level API for loading and analyzing a single `.oe` recording.