@momo2555/koppeliajs 0.0.172 → 0.0.174

package/README.md

@@ -151,6 +151,13 @@ The `Device` class is your bridge to the physical world. Instead of dealing with
 * `onCursor(callback(x, y))`: Translates IMU spatial movement into 2D coordinates.
 * `onBiking(callback(speed))`: Reads data if the modular controller is clipped to a physical exercise bike pedal.
 
+**Available Microphone Methods:**
+* `enableMic()`: Enables real-time microphone streaming for this device. Returns a `Promise<void>`.
+* `disableMic()`: Stops microphone streaming and removes the audio sink from Maestro.
+* `setMicConfig({ volume, effect, intensity })`: Updates playback volume and optional voice effects.
+
+Filarmonic enforces a maximum of 5 active microphones at the same time. If the limit is reached, `enableMic()` rejects with `MicLimitError`.
+
 #### Example
 ```typescript
 import { Koppelia, Device } from "@momo2555/koppeliajs";
@@ -182,6 +189,78 @@ koppelia.onReady(async () => {
 
 ---
 
+### 3.1. Real-Time Microphone Streaming
+
+#### How it works & Capabilities
+The controller microphone can be streamed in real time to the console speakers. This is designed for games where the animator wants to temporarily amplify a resident, apply a playful voice effect, or create call-and-response mechanics.
+
+The audio path is intentionally low-latency:
+
+```text
+nRF52840 controller mic -> BLE audio characteristic -> AllegroLink -> UDP -> Maestro -> speakers
+```
+
+Filarmonic stays in the control path, not the audio path. It enables/disables the mic module, enforces the 5-mic limit, and forwards configuration commands to Maestro. The audio itself bypasses Filarmonic to avoid extra latency.
+
+**Configuration:**
+* `volume`: Number from `0` to `100`.
+* `effect`: `"echo"`, `"reverb"`, or `null`.
+* `intensity`: Number from `0.0` to `1.0`.
+
+Use microphone audio carefully in games: TV speakers can feed back into the controller microphone if the device is too close to the sound output. Prefer short push-to-talk interactions, moderate volume, and no effect by default.
+
+#### Example
+```typescript
+import { Koppelia, Device, MicLimitError, type MicConfig } from "@momo2555/koppeliajs";
+
+let koppelia = Koppelia.instance;
+
+koppelia.onReady(async () => {
+    const devices: Device[] = await koppelia.getDevices();
+    const device = devices[0];
+
+    const config: MicConfig = {
+        volume: 70,
+        effect: null,
+        intensity: 0.5,
+    };
+
+    try {
+        await device.enableMic();
+        device.setMicConfig(config);
+    } catch (error) {
+        if (error instanceof MicLimitError) {
+            console.warn("Too many microphones are already active.");
+            return;
+        }
+        throw error;
+    }
+
+    // Stop streaming when the microphone is no longer needed.
+    setTimeout(() => {
+        device.disableMic();
+    }, 10000);
+});
+```
+
+#### Push-To-Talk Pattern
+For most games, prefer a short-lived mic session controlled by the animator:
+
+```typescript
+async function startTalking(device: Device) {
+    await device.enableMic();
+    device.setMicConfig({ volume: 60, effect: null });
+}
+
+function stopTalking(device: Device) {
+    device.disableMic();
+}
+```
+
+Avoid leaving multiple microphones open during normal gameplay. If you use `"echo"` or `"reverb"`, keep `volume` lower because effects increase the risk of acoustic feedback.
+
+---
+
 ### 4. Remote Procedure Calls (`CustomCallbacks`)
 
 #### How it works & Capabilities
@@ -465,4 +544,4 @@ Here is a comprehensive example demonstrating how Routing, State, Hardware, and
         padding: 20px;
     }
 </style>
-```
+```

package/dist/index.d.ts

@@ -7,10 +7,13 @@ import { Koppelia } from "./scripts/koppelia.js";
 import { Console } from "./scripts/console.js";
 import { Message } from "./scripts/message.js";
 import { Device } from "./scripts/device.js";
+import { MicLimitError } from "./scripts/errors.js";
 import { Play } from "./scripts/play.js";
 import { Resident } from "./scripts/resident.js";
 import { Song } from "./scripts/song.js";
+import type { MicConfig, MicEffect } from "./scripts/device.js";
 import { updateRoute, routeType } from './stores/routeStore.js';
 import { audioManager, AudioManager } from './stores/audioManager.js';
 export { KBase, GrowableElement, Button, ResizableText };
-export { updateRoute, routeType, Koppelia, Console, Message, Device, Play, Song, audioManager, Resident, AudioManager };
+export { updateRoute, routeType, Koppelia, Console, Message, Device, Play, Song, audioManager, Resident, AudioManager, MicLimitError };
+export type { MicConfig, MicEffect };

package/dist/index.js

@@ -8,10 +8,11 @@ import { Koppelia } from "./scripts/koppelia.js";
 import { Console } from "./scripts/console.js";
 import { Message } from "./scripts/message.js";
 import { Device } from "./scripts/device.js";
+import { MicLimitError } from "./scripts/errors.js";
 import { Play } from "./scripts/play.js";
 import { Resident } from "./scripts/resident.js";
 import { Song } from "./scripts/song.js";
 import { updateRoute, routeType } from './stores/routeStore.js';
 import { audioManager, AudioManager } from './stores/audioManager.js';
 export { KBase, GrowableElement, Button, ResizableText }; // Compoenents
-export { updateRoute, routeType, Koppelia, Console, Message, Device, Play, Song, audioManager, Resident, AudioManager }; //  libraries and store
+export { updateRoute, routeType, Koppelia, Console, Message, Device, Play, Song, audioManager, Resident, AudioManager, MicLimitError }; //  libraries and store

package/dist/scripts/device.d.ts

@@ -7,6 +7,12 @@ type Color = {
     lon?: number;
     loff?: number;
 };
+export type MicEffect = "echo" | "reverb" | null;
+export type MicConfig = {
+    volume: number;
+    effect?: MicEffect;
+    intensity?: number;
+};
 /**
  * Represents a physical or logical device connected to the console.
  * Handles device-specific commands like LEDs, vibrations, and hardware module subscriptions.
@@ -61,6 +67,22 @@ export declare class Device {
      * @param moduleName The name of the module to enable (Note: retains original code spelling).
      */
     private _enableModule;
+    /**
+     * Enables the microphone module on this device.
+     * Filarmonic enforces a maximum of 5 simultaneous mic modules.
+     * @throws {MicLimitError} if the 5-mic limit has been reached.
+     */
+    enableMic(): Promise<void>;
+    /**
+     * Disables the microphone module on this device and removes its audio sink in Maestro.
+     */
+    disableMic(): void;
+    /**
+     * Configures the audio sink for this device's microphone.
+     * Must be called after enableMic() succeeds.
+     * @param config The microphone sink configuration.
+     */
+    setMicConfig(config: MicConfig): void;
     /**
      * Changes the current LED color of the device.
      * @param color The RGB color configuration to apply.

package/dist/scripts/device.js

@@ -1,4 +1,5 @@
 import { Console } from "./console.js";
+import { MicLimitError } from "./errors.js";
 import { Message, MessageType, PeerType } from "./message.js";
 import { Resident } from "./resident.js";
 /**
@@ -133,6 +134,54 @@ export class Device {
         request.setRequest("enableModule");
         this._console.sendMessage(request);
     }
+    /**
+     * Enables the microphone module on this device.
+     * Filarmonic enforces a maximum of 5 simultaneous mic modules.
+     * @throws {MicLimitError} if the 5-mic limit has been reached.
+     */
+    enableMic() {
+        return new Promise((resolve, reject) => {
+            let request = new Message();
+            request.addParam("module", "mic");
+            request.setDestination(PeerType.DEVICE, this._address);
+            request.setRequest("enableModule");
+            this._console.sendMessage(request, (response) => {
+                if (response.getType() === MessageType.ERROR) {
+                    const errMsg = response.getParam("error") ?? "Failed to enable mic module";
+                    reject(new MicLimitError(errMsg));
+                }
+                else {
+                    resolve();
+                }
+            });
+        });
+    }
+    /**
+     * Disables the microphone module on this device and removes its audio sink in Maestro.
+     */
+    disableMic() {
+        let request = new Message();
+        request.addParam("module", "mic");
+        request.setDestination(PeerType.DEVICE, this._address);
+        request.setRequest("disableModule");
+        this._console.sendMessage(request);
+    }
+    /**
+     * Configures the audio sink for this device's microphone.
+     * Must be called after enableMic() succeeds.
+     * @param config The microphone sink configuration.
+     */
+    setMicConfig(config) {
+        let request = new Message();
+        request.setDestination(PeerType.DEVICE, this._address);
+        request.setRequest("setMicConfig");
+        request.addParam("volume", config.volume);
+        if (config.effect !== undefined)
+            request.addParam("effect", config.effect);
+        if (config.intensity !== undefined)
+            request.addParam("intensity", config.intensity);
+        this._console.sendMessage(request);
+    }
     /**
      * Changes the current LED color of the device.
      * @param color The RGB color configuration to apply.

package/dist/scripts/errors.d.ts

@@ -0,0 +1,3 @@
+export declare class MicLimitError extends Error {
+    constructor(message?: string);
+}

package/dist/scripts/errors.js

@@ -0,0 +1,6 @@
+export class MicLimitError extends Error {
+    constructor(message = "Maximum of 5 mic modules can be active simultaneously") {
+        super(message);
+        this.name = "MicLimitError";
+    }
+}

package/dist/scripts/koppelia.js

@@ -303,11 +303,8 @@ export class Koppelia {
             getCurrentPlaysRequest.setRequest("getCurrentPlays");
             getCurrentPlaysRequest.setDestination(PeerType.MASTER, "");
             this._console.sendMessage(getCurrentPlaysRequest, (response) => {
-                let playsRawList = response.getParam("plays", {});
-                let plays = [];
-                for (let playId in playsRawList) {
-                    plays.push(new Play(this._console, playId, playsRawList[playId]));
-                }
+                let playsRawList = response.getParam("plays", []);
+                let plays = playsRawList.map((playData) => new Play(this._console, playData.id, playData));
                 resolve(plays);
             });
         });

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@momo2555/koppeliajs",
-	"version": "0.0.172",
+	"version": "0.0.174",
 	"scripts": {
 		"dev": "vite dev",
 		"build": "vite build && npm run package",