chore: improve channel mapping

Author: Harshal6927

.github/copilot-instructions.md

@@ -0,0 +1,67 @@
+# MUC Soundboard AI Instructions
+
+## 🏗 Architecture & Data Flow
+
+- **Core Components**:
+  - `CLI` (`src/cli.py`): Entry point using `rich-click`. Orchestrates `Soundboard` and `AudioManager`.
+  - `Config` (`src/config.py`): Persists state (device ID, volume) to `~/.muc/config.json`.
+  - `Soundboard` (`src/soundboard.py`): Manages sound library (scanning `sounds/`) and `pynput` hotkey bindings.
+  - `AudioManager` (`src/audio_manager.py`): Low-level audio I/O via `sounddevice` and `soundfile`.
+
+- **Audio Routing Strategy**:
+  - The app outputs audio to a **Virtual Audio Cable** (e.g., VB-Cable).
+  - **Critical**: The app must output to the "Input" side of the virtual cable (e.g., `CABLE Input`).
+  - Games/Apps read from the "Output" side (e.g., `CABLE Output`) as a microphone.
+  - `AudioManager.find_virtual_cable()` auto-detects devices with keywords: "cable", "virtual", "vb-audio".
+
+- **Data Flow**:
+  `CLI Command/Hotkey` -> `Soundboard` -> `AudioManager.play_audio()` -> `soundfile.read()` -> `numpy` processing (volume/channels) -> `sounddevice.play()` -> `Virtual Device`.
+
+## 🛠 Developer Workflows
+
+- **Dependency Management**: Use `uv` for package management.
+  - Install: `uv add muc` or `uv sync`
+  - Run: `uv run muc`
+- **Linting**: Run `make lint` to execute pre-commit hooks (ruff, etc.).
+- **Testing Audio**:
+  - Use `muc devices` to list IDs.
+  - Use `muc play [name]` to test playback without hotkeys.
+  - `AudioManager.play_audio(..., blocking=True)` is used for sequential playback (e.g., `muc auto`).
+
+## 🧩 Patterns & Conventions
+
+- **UI/UX**:
+  - **ALWAYS** use `rich.console.Console` for output. Never use `print()`.
+  - Use `rich.table.Table` for listing data (devices, sounds).
+  - Use `rich.panel.Panel` for welcome messages/headers.
+  - Style errors with `[red]✗[/red]` and successes with `[green]✓[/green]`.
+
+- **Audio Handling**:
+  - **Channel Mapping**: `AudioManager` automatically upmixes mono files to match the output device's channel count using `numpy.tile`.
+  - **Volume**: Applied as a scalar multiplication on the numpy array *before* playback.
+  - **Non-blocking by default**: `play_audio` is fire-and-forget unless `blocking=True` is passed.
+
+- **Configuration**:
+  - Config is auto-loaded on instantiation of `Config()`.
+  - `Config.save()` must be called explicitly after modifying settings.
+  - Paths are handled with `pathlib.Path`.
+
+- **Error Handling**:
+  - Catch `OSError` and `RuntimeError` from `sounddevice`/`pynput`.
+  - Display user-friendly messages via `console.print` instead of letting the app crash.
+  - Example:
+    ```python
+    try:
+        sd.play(data, samplerate)
+    except (OSError, RuntimeError) as e:
+        self.console.print(f"[red]Error:[/red] {e}")
+    ```
+
+## 🔑 Key Integration Points
+
+- **Hotkeys**:
+  - Uses `pynput.keyboard.GlobalHotKeys`.
+  - The listener runs in a daemon thread, but the CLI command (`listen`) must keep the main thread alive (often with a `keyboard.Listener` blocking on `join()`).
+- **File Discovery**:
+  - Recursively scans `sounds/` for extensions: `.wav`, `.mp3`, `.ogg`, `.flac`, `.m4a`.
+  - Uses `pathlib.Path.rglob("*")`.

src/audio_manager.py

@@ -117,6 +117,35 @@ def set_volume(self, volume: float) -> None:
         percentage = int(self.volume * 100)
         self.console.print(f"[cyan]♪[/cyan] Volume set to {percentage}%")
 
+    @staticmethod
+    def _adjust_channels(data: np.ndarray, max_channels: int) -> np.ndarray:
+        """Adjust audio channels to match the output device.
+
+        Args:
+            data: Audio data array
+            max_channels: Target number of channels
+
+        Returns:
+            Adjusted audio data array
+
+        """
+        if data.shape[1] < max_channels:
+            # Duplicate channels to fill as much as possible
+            tile_count = max_channels // data.shape[1]
+            data = np.tile(data, (1, tile_count))
+
+            # If we still don't have enough channels (e.g. 2 -> 5), pad with silence
+            current_channels = data.shape[1]
+            if current_channels < max_channels:
+                padding = np.zeros((data.shape[0], max_channels - current_channels))
+                data = np.hstack((data, padding))
+
+        elif data.shape[1] > max_channels:
+            # Take only the channels we need
+            data = data[:, :max_channels]
+
+        return data
+
     def play_audio(self, audio_file: Path, *, blocking: bool = False) -> bool:
         """Play an audio file through the selected output device.
 
@@ -155,12 +184,7 @@ def play_audio(self, audio_file: Path, *, blocking: bool = False) -> bool:
             max_channels = device_info["max_output_channels"]  # pyright: ignore[reportCallIssue, reportArgumentType]
 
             # Adjust channels if needed
-            if data.shape[1] < max_channels:
-                # Duplicate channels if we have fewer than device supports
-                data = np.tile(data, (1, max_channels // data.shape[1]))
-            elif data.shape[1] > max_channels:
-                # Take only the channels we need
-                data = data[:, :max_channels]
+            data = self._adjust_channels(data, max_channels)
 
             # Apply volume scaling
             data *= self.volume