Merge pull request #126 from mgth/main

release: promote main → release for 0.4.1

Author: mgth

.github/workflows/ci.yml

@@ -114,6 +114,14 @@ jobs:
         working-directory: omniphony-studio
         run: npm run build
 
+      # Translation parity is reported but never blocks a merge: incomplete
+      # locales fall back to English at runtime, so this is a heads-up, not a
+      # gate. Emits ::warning:: annotations on the PR.
+      - name: Check i18n parity (warn-only)
+        working-directory: omniphony-studio
+        continue-on-error: true
+        run: npm run i18n:check
+
   build-macos:
     # macOS arm64 compile gate. The renderer workspace pulls the CoreAudio
     # output backend (cpal) and the `sys` signal/IO layer, both of which carry

docs/osc-control-contract.md

@@ -119,6 +119,24 @@ latency. See `PI_TUNING_PROCEDURE.md` and `docs/latency-regulation.md`.
 | `/control/render/bridge_path` | s | Path to the format bridge library. |
 | `/control/render/input_pipe` | s | Named-pipe input path. |
 
+### Head tracking (binaural)
+
+Live head-pose control for the binaural (headphone) path. The orientation
+*feed* itself arrives on a **user-configured** address
+(`head_tracking.osc_address`, e.g. `/gamerotationvector` for Sensors2OSC /
+`nxosc`) parsed per `head_tracking.format` — that is config, not a fixed
+contract address. See `omniphony-renderer/BINAURAL.md`.
+
+| Address | Args | Meaning |
+|---|---|---|
+| `/control/head/orientation` | f×3 (euler °) | Set head pose directly (yaw, pitch, roll). |
+| `/control/head/quat` | f×4 | Set head pose directly (quaternion). |
+| `/control/head/recenter` | — | Capture the current orientation as "front". |
+| `/control/head/tracking/address` | s | Feed address the engine listens on (`""` disables tracking). |
+| `/control/head/tracking/format` | s | `auto` \| `quat` \| `rotvec` \| `euler`. |
+| `/control/head/tracking/smoothing` | f `[0,0.99]` | Pose smoothing (higher = smoother/laggier). |
+| `/control/head/tracking/invert` | int bool | Mirror the applied rotation. |
+
 ### Layout
 
 | Address | Args | Meaning |
@@ -168,6 +186,8 @@ exhaustive machine-readable list.
   `render/bridge_path`, `render/bridge_error`, `vbap/allow_negative_z`,
   `render_evaluation/*` (mirrors of the control resolutions), `speakers`,
   `speakers/recomputing`, `speakers/recompute_error`, `layout`.
+- **Head tracking** — `head_pose` (4-float quaternion `w,x,y,z`, broadcast at
+  ~30 Hz while a tracking feed is active, for low-latency client display).
 - **Metering / timing** — `clip`, `decode_time_ms`, `render_time_ms`,
   `write_time_ms`, `crossover_time_ms`, `frame_duration_ms`, `monitoring`,
   `loudness`, `realtime/{master_gain,object_gain,speaker_gain}`.

omniphony-renderer/BINAURAL.md

@@ -89,6 +89,22 @@ the phone strapped to the headband:
 `smoothing` (0–0.99, default 0.2) trades a little latency for pose stability;
 with Game Rotation Vector you can usually lower it.
 
+### Other sources
+
+The setup above uses a phone, but any OSC orientation source works. For the
+**Waves Nx Head Tracker** (Bluetooth LE, Linux/BlueZ) there is a small Rust
+CLI — **[`nxosc`](https://github.com/mgth/nx-tracker-osc)** — that decodes the
+tracker and emits the same `/gamerotationvector` feed, so it drops straight
+into the steps above in place of Sensors2OSC:
+
+```sh
+nxosc run --profile omniphony --osc-address /gamerotationvector --osc-target 127.0.0.1:9000
+```
+
+Keep `head_tracking.osc_address: /gamerotationvector` and `format: auto`.
+`nxosc` also has a `--profile scenerotator` mode to drive an IEM SceneRotator
+directly instead.
+
 ## Usage tips
 
 - **The room is YOUR room, not the scene's.** The reflections and the reverb

omniphony-renderer/audio_output/src/control.rs

@@ -15,6 +15,15 @@ pub struct RequestedAudioOutputConfig {
     pub latency_target_ms: Option<u32>,
     pub adaptive_enabled: bool,
     pub adaptive: AdaptiveResamplingConfig,
+    /// Live-requested output backend id ("pipewire" / "asio" / "file"), or
+    /// `None` to keep the active one. Parsed by the CLI's runtime sync layer
+    /// (this crate stays decoupled from the CLI's `OutputBackend` enum).
+    pub output_backend: Option<String>,
+    /// Live-requested destination for the `file` backend (`-` = stdout, or a
+    /// file/FIFO path).
+    pub output_file: Option<String>,
+    /// Live-requested `file` backend encoding ("raw_f32" / "caf").
+    pub output_file_format: Option<String>,
 }
 
 impl Default for RequestedAudioOutputConfig {
@@ -25,6 +34,9 @@ impl Default for RequestedAudioOutputConfig {
             latency_target_ms: None,
             adaptive_enabled: false,
             adaptive: AdaptiveResamplingConfig::default(),
+            output_backend: None,
+            output_file: None,
+            output_file_format: None,
         }
     }
 }
@@ -88,6 +100,30 @@ impl AudioControl {
         self.requested_snapshot().output_device
     }
 
+    pub fn set_requested_output_backend(&self, backend: Option<String>) {
+        self.update_requested(|requested| requested.output_backend = backend);
+    }
+
+    pub fn requested_output_backend(&self) -> Option<String> {
+        self.requested_snapshot().output_backend
+    }
+
+    pub fn set_requested_output_file(&self, output_file: Option<String>) {
+        self.update_requested(|requested| requested.output_file = output_file);
+    }
+
+    pub fn requested_output_file(&self) -> Option<String> {
+        self.requested_snapshot().output_file
+    }
+
+    pub fn set_requested_output_file_format(&self, format: Option<String>) {
+        self.update_requested(|requested| requested.output_file_format = format);
+    }
+
+    pub fn requested_output_file_format(&self) -> Option<String> {
+        self.requested_snapshot().output_file_format
+    }
+
     pub fn set_requested_output_sample_rate(&self, rate_hz: Option<u32>) {
         self.update_requested(|requested| requested.output_sample_rate_hz = rate_hz);
     }