@4players/odin-nodejs 0.10.3 → 0.11.1

package/scripts/postbuild.cjs

@@ -0,0 +1,133 @@
+#!/usr/bin/env node
+
+/**
+ * Post-build script for ODIN NodeJS bindings.
+ * 
+ * On macOS:
+ * - Copies dynamic libraries (dylibs) to the build output directory
+ * - Ad-hoc signs them to prevent Gatekeeper from blocking
+ * - Creates prebuilds directory for npm link compatibility
+ * 
+ * Usage:
+ *   node scripts/postbuild.cjs [debug]
+ */
+
+const fs = require('fs');
+const path = require('path');
+const { execSync } = require('child_process');
+
+const args = process.argv.slice(2);
+const isDebug = args.includes('debug');
+const buildDir = isDebug ? 'build/Debug' : 'build/Release';
+
+const projectRoot = path.resolve(__dirname, '..');
+const buildPath = path.join(projectRoot, buildDir);
+
+// Platform/arch for prebuilds directory naming
+const platform = process.platform;
+const arch = process.arch;
+
+console.log(`[postbuild] Platform: ${platform}, Arch: ${arch}`);
+console.log(`[postbuild] Build mode: ${isDebug ? 'Debug' : 'Release'}`);
+console.log(`[postbuild] Build path: ${buildPath}`);
+
+/**
+ * Copy dylibs to a target directory and sign them
+ */
+function copyAndSignDylibs(targetDir, dylibs, depsDir) {
+    // Ensure target directory exists
+    fs.mkdirSync(targetDir, { recursive: true });
+
+    // Copy dylibs
+    for (const dylib of dylibs) {
+        const src = path.join(depsDir, dylib);
+        const dest = path.join(targetDir, dylib);
+
+        if (!fs.existsSync(src)) {
+            console.error(`[postbuild] Source library not found: ${src}`);
+            process.exit(1);
+        }
+
+        console.log(`[postbuild] Copying ${dylib} to ${path.relative(projectRoot, targetDir)}/`);
+        fs.copyFileSync(src, dest);
+    }
+
+    // Ad-hoc sign the dylibs
+    console.log(`[postbuild] Ad-hoc signing dylibs in ${path.relative(projectRoot, targetDir)}/...`);
+    try {
+        execSync(`codesign -f -s - *.dylib`, {
+            cwd: targetDir,
+            stdio: 'inherit'
+        });
+    } catch (error) {
+        console.error(`[postbuild] Warning: codesign failed. Libraries may be blocked by Gatekeeper.`);
+        console.error(error.message);
+    }
+}
+
+if (platform === 'darwin') {
+    const depsDir = path.join(projectRoot, 'libs', 'bin', 'macos', 'universal');
+    const dylibs = ['libodin.dylib', 'libodin_crypto.dylib'];
+
+    // Ensure build directory exists
+    if (!fs.existsSync(buildPath)) {
+        console.error(`[postbuild] Build directory does not exist: ${buildPath}`);
+        process.exit(1);
+    }
+
+    // 1. Copy to build output directory
+    copyAndSignDylibs(buildPath, dylibs, depsDir);
+
+    // 2. Copy to prebuilds directory for npm link compatibility
+    // node-gyp-build looks for: prebuilds/{platform}-{arch}/
+    const prebuildsDir = path.join(projectRoot, 'prebuilds', `${platform}-${arch}`);
+    console.log(`[postbuild] Creating prebuilds for npm link compatibility...`);
+
+    // Copy the .node file to prebuilds
+    const nodeFile = 'odin.node';
+    const nodeSrc = path.join(buildPath, nodeFile);
+    if (fs.existsSync(nodeSrc)) {
+        fs.mkdirSync(prebuildsDir, { recursive: true });
+        const nodeDest = path.join(prebuildsDir, nodeFile);
+        console.log(`[postbuild] Copying ${nodeFile} to prebuilds/${platform}-${arch}/`);
+        fs.copyFileSync(nodeSrc, nodeDest);
+
+        // Copy dylibs to prebuilds too
+        copyAndSignDylibs(prebuildsDir, dylibs, depsDir);
+    } else {
+        console.log(`[postbuild] Note: ${nodeFile} not found in build output, skipping prebuilds.`);
+    }
+
+    console.log(`[postbuild] macOS post-build complete.`);
+} else if (platform === 'linux') {
+    // For Linux, copy .so files if using dynamic linking
+    const depsDir = path.join(projectRoot, 'libs', 'bin', 'linux', arch);
+    const prebuildsDir = path.join(projectRoot, 'prebuilds', `${platform}-${arch}`);
+
+    // Copy .node file to prebuilds if it exists
+    const nodeFile = 'odin.node';
+    const nodeSrc = path.join(buildPath, nodeFile);
+    if (fs.existsSync(nodeSrc) && fs.existsSync(buildPath)) {
+        fs.mkdirSync(prebuildsDir, { recursive: true });
+        console.log(`[postbuild] Copying ${nodeFile} to prebuilds/${platform}-${arch}/`);
+        fs.copyFileSync(nodeSrc, path.join(prebuildsDir, nodeFile));
+    }
+
+    console.log(`[postbuild] Linux post-build complete (static linking, no dylib copy needed).`);
+} else if (platform === 'win32') {
+    // For Windows, copy .node file to prebuilds
+    const prebuildsDir = path.join(projectRoot, 'prebuilds', `${platform}-${arch}`);
+
+    const nodeFile = 'odin.node';
+    const nodeSrc = path.join(buildPath, nodeFile);
+    if (fs.existsSync(nodeSrc) && fs.existsSync(buildPath)) {
+        fs.mkdirSync(prebuildsDir, { recursive: true });
+        console.log(`[postbuild] Copying ${nodeFile} to prebuilds/${platform}-${arch}/`);
+        fs.copyFileSync(nodeSrc, path.join(prebuildsDir, nodeFile));
+    }
+
+    console.log(`[postbuild] Windows post-build complete (static linking, no dll copy needed).`);
+} else {
+    console.log(`[postbuild] Unknown platform: ${platform}`);
+}
+

package/tests/audio-recording/README.md

@@ -1,24 +1,109 @@
-# ODIN Node JS Sample "Audio Recording"
+# ODIN Audio Recording Bot Example
 
-This sample demonstrates how to use the ODIN SDK to record audio from other users and sending these to OpenAI for
-transcription. It also features basic "Bot" functionality like sending a message to the chat.
+This example demonstrates how to create a recording bot that captures audio from other peers in an ODIN room and saves it as WAV files.
+
+## Features
+
+- **Automatic Recording**: Starts recording when peers begin speaking
+- **WAV Output**: Saves recordings as standard WAV files (48kHz, stereo, 16-bit)
+- **Peer Tracking**: Names recordings based on peer identity
+- **Graceful Shutdown**: Properly finalizes recordings on exit
+- **E2EE Support**: Optional end-to-end encryption
 
 ## Prerequisites
 
-You need to have an ODIN Access Key. See [here](https://www.4players.io/odin/introduction/access-keys/#generating-access-keys))
-for more info on the topic and to create one for free directly in the documentation.
+1. **ODIN Access Key**: Get one for free at [4Players ODIN](https://docs.4players.io/voice/introduction/access-keys/)
+2. **wav Package**: Already included in package.json dependencies
+
+## Configuration
+
+Edit `index.js` and replace the placeholder values:
 
-This sample also requires an OpenAI API Key for transcription. You can get one for free [here](https://beta.openai.com/).
+```javascript
+const accessKey = "__YOUR_ACCESS_KEY__";  // Your ODIN access key
+const roomId = "__YOUR_ROOM_ID__";        // Room to record
+const userId = "RecorderBot-123";         // Bot's user ID
+```
+
+To enable E2EE (must match other peers):
 
-## Getting Started
+```javascript
+const cipherPassword = "shared-secret";
+```
 
-Run the script with the following command:
+## Running the Bot
 
 ```bash
+cd tests/audio-recording
 node index.js
 ```
 
-It will connect to the room `Lobby` using your access key and will send a "Hello World" message to the chat. It will 
-then wait for users start to talk and will record their audio into a file. The file name will be the user's name with a 
-timestamp and will be a WAV file. 2 seconds after the user stops talking, the recording will be stopped and the file
-will be sent to OpenAI for transcription.
+Press `Ctrl+C` to stop recording and save all files.
+
+## How It Works
+
+1. **Connects** to the specified ODIN room
+2. **Listens** for audio data from all peers
+3. **Creates** a new WAV file when a peer starts speaking
+4. **Writes** audio samples to the file in real-time
+5. **Finalizes** recordings when the peer stops or disconnects
+
+## Output Files
+
+Recordings are saved in the current directory with the naming pattern:
+
+```
+recording_{peerName}_media{id}_{timestamp}.wav
+```
+
+Example: `recording_Alice_media123_2026-01-14T12-30-45-000Z.wav`
+
+### Audio Format
+
+- **Sample Rate**: 48,000 Hz (ODIN native)
+- **Channels**: 2 (stereo, interleaved)
+- **Bit Depth**: 16-bit signed integer
+
+## Example Output
+
+```
+=== ODIN Audio Recording Bot ===
+
+1. Creating ODIN client...
+2. Generating token from access key...
+   Token generated successfully.
+
+3. Creating room...
+4. E2EE disabled (no password configured).
+
+5. Joining room...
+   Join initiated.
+
+Recording bot is running. Press Ctrl+C to stop.
+
+[Connection] State: Connecting
+[Connection] State: Joined
+[Room] Joined! Room ID: my-room, Own Peer ID: 12345
+[Peer] Joined: Alice (ID: 67890)
+[Media] Started: Peer 67890, Media ID: 1
+[Recording] Started: ./recording_Alice_media1_2026-01-14T12-30-45-000Z.wav
+
+[Media] Stopped: Peer 67890, Media ID: 1
+[Recording] Saved: ./recording_Alice_media1_2026-01-14T12-30-45-000Z.wav (480000 samples)
+
+^C
+[Shutdown] Stopping...
+[Shutdown] Room closed.
+```
+
+## Use Cases
+
+- **Meeting Transcription**: Record meetings for later transcription
+- **Quality Assurance**: Monitor and review voice communications
+- **AI Training**: Collect voice data for machine learning
+- **Content Creation**: Capture voice for podcasts or videos
+
+## Related Examples
+
+- [connection-test](../connection-test/) - Basic connection and event handling
+- [sending-audio](../sending-audio/) - Send audio to the room

package/tests/audio-recording/index.js

@@ -1,148 +1,256 @@
-const accessKey = "__YOUR_ACCESS_KEY__";
-const roomName = "Lobby";
-const userName = "My Bot";
+/**
+ * ODIN Node.js SDK - Audio Recording Bot Example
+ * 
+ * This example demonstrates how to:
+ * - Connect to an ODIN room as a recording bot
+ * - Receive audio data from other peers
+ * - Save audio recordings as WAV files
+ * - Handle peer join/leave events
+ * 
+ * The bot automatically starts recording when a peer begins speaking
+ * and saves the audio to a WAV file when they stop.
+ * 
+ * Prerequisites:
+ * - Replace __YOUR_ACCESS_KEY__ with your ODIN access key
+ * - Get a free access key at https://docs.4players.io/voice/introduction/access-keys/
+ */
 
-// Load the odin module
 import odin from '../../index.cjs';
-const {OdinClient} = odin;
-
-// Import wav module and OpenAI API
+const { OdinClient, OdinCipher } = odin;
 import wav from 'wav';
-import { Configuration, OpenAIApi } from "openai";
-import fs from 'fs';
 
-// Configure OpenAI - use your own API key
-const configuration = new Configuration({
-    apiKey: '__YOUR_OPENAI_API_KEY__'
-});
-const openai = new OpenAIApi(configuration);
+// ============================================
+// Configuration - Replace with your values
+// ============================================
+
+/** 
+ * Your ODIN access key. Get one for free at https://docs.4players.io/voice/introduction/access-keys/
+ * @type {string}
+ */
+const accessKey = "__YOUR_ACCESS_KEY__";
 
-// Create an odin client instance using our access key and create a room
-const odinClient = new OdinClient();
-const room = odinClient.createRoom(accessKey, roomName, userName);
+/**
+ * The room ID to join. All users joining the same room can communicate.
+ * @type {string}
+ */
+const roomId = "__YOUR_ROOM_ID__";
 
-// Listen on PeerJoined messages and print the user data of the joined peer
-room.addEventListener('PeerJoined', (event) => {
-    console.log("Received PeerJoined event", event);
-    console.log(JSON.parse(new TextDecoder().decode(event.userData)));
-});
+/**
+ * Unique user ID for this recording bot.
+ * @type {string}
+ */
+const userId = "RecorderBot-" + Math.floor(Math.random() * 10000);
 
-// Listen on PeerLeft messages and print the user data of the left peer
-room.addEventListener('PeerLeft', (event) => {
-    console.log("Received PeerLeft event", event);
-});
+/**
+ * Optional: Password for End-to-End Encryption.
+ * Set to null to disable, or set a string that matches other peers.
+ * @type {string|null}
+ */
+const cipherPassword = null;
+
+// ============================================
+// Recording State
+// ============================================
+
+/**
+ * Maps media IDs to their active recording writers.
+ * @type {Object.<number, {wavEncoder: wav.FileWriter, fileName: string, peerId: number, sampleCount: number}>}
+ */
+const fileRecorder = {};
+
+/**
+ * Maps peer IDs to their info (name, etc.).
+ * @type {Map<number, {name: string}>}
+ */
+const activePeers = new Map();
+
+// ============================================
+// Main Recording Bot
+// ============================================
+
+async function run() {
+    console.log("=== ODIN Audio Recording Bot ===\n");
+
+    // Step 1: Create ODIN client
+    console.log("1. Creating ODIN client...");
+    const client = new OdinClient();
+
+    // Step 2: Generate token from access key
+    console.log("2. Generating token from access key...");
+    const token = client.generateToken(accessKey, roomId, userId);
+    console.log("   Token generated successfully.\n");
+
+    // Step 3: Create room using factory pattern (recommended approach)
+    console.log("3. Creating room...");
+    const room = client.createRoom(token);
+
+    // Step 4: Configure E2EE if password is provided
+    if (cipherPassword) {
+        console.log("4. Configuring E2EE cipher...");
+        const cipher = new OdinCipher();
+        cipher.setPassword(new TextEncoder().encode(cipherPassword));
+        room.setCipher(cipher);
+        console.log("   E2EE enabled.\n");
+    } else {
+        console.log("4. E2EE disabled (no password configured).\n");
+    }
+
+    // ========================================
+    // Event Handlers
+    // ========================================
+
+    // Connection state changes
+    room.onConnectionStateChanged((event) => {
+        console.log(`[Connection] State: ${event.state}`);
+    });
+
+    // Room joined - we're connected
+    room.onJoined((event) => {
+        console.log(`[Room] Joined! Room ID: ${event.roomId}, Own Peer ID: ${event.ownPeerId}`);
+        console.log(`[Room] Available media IDs: ${JSON.stringify(event.mediaIds)}`);
+    });
+
+    // Room left - we're disconnected
+    room.onLeft((event) => {
+        console.log(`[Room] Left. Reason: ${event.reason}`);
+    });
+
+    // Peer joined - track new peers for better file naming
+    room.onPeerJoined((event) => {
+        const peerId = event.peerId;
+        let userName = "Unknown";
+
+        // Try to parse user data to get the peer's name
+        if (event.userData) {
+            try {
+                const userData = JSON.parse(new TextDecoder().decode(new Uint8Array(event.userData)));
+                userName = userData.name || userData.userId || "Unknown";
+            } catch (e) {
+                // Ignore parse errors - user data might be binary
+            }
+        }
+
+        activePeers.set(peerId, { name: userName });
+        console.log(`[Peer] Joined: ${userName} (ID: ${peerId})`);
+    });
+
+    // Peer left - cleanup tracking
+    room.onPeerLeft((event) => {
+        const peerInfo = activePeers.get(event.peerId);
+        console.log(`[Peer] Left: ${peerInfo?.name || 'Unknown'} (ID: ${event.peerId})`);
+        activePeers.delete(event.peerId);
+    });
+
+    // Media started - a peer started their audio stream
+    room.onMediaStarted((event) => {
+        console.log(`[Media] Started: Peer ${event.peerId}, Media ID: ${event.media?.id}`);
+    });
 
-// Listen on MediaActivity messages and prepare a wav file for each media stream. The basic idea here is to
-// create a WAV encoder file whenever a users starts talking and to close the file when the user stops talking. This way,
-// we have isolated WAV files for each user and can transcribe them individually. If we don't want to create new files
-// during short pauses, we wait 2 seconds before closing the file.
-room.addEventListener('MediaActivity', (event) => {
-    if (event.state) {
-        // User started talking - prepare a new file
-        if (!fileRecorder[event.mediaId]) {
-            const timer = new Date().getTime();
-            const fileName = `./recording_${event.peerId}_${event.mediaId}_${timer}.wav`;
-            console.log("Created a new recording file: ", fileName);
-            fileRecorder[event.mediaId] = {
+    // Media stopped - finalize recording for this media stream
+    room.onMediaStopped((event) => {
+        console.log(`[Media] Stopped: Peer ${event.peerId}, Media ID: ${event.mediaId}`);
+
+        // Stop and save the recording if one exists
+        const recorder = fileRecorder[event.mediaId];
+        if (recorder) {
+            recorder.wavEncoder.end();
+            console.log(`[Recording] Saved: ${recorder.fileName} (${recorder.sampleCount} samples)`);
+            delete fileRecorder[event.mediaId];
+        }
+    });
+
+    // Message received - log any messages from peers
+    room.onMessageReceived((event) => {
+        console.log(`[Message] From Peer ${event.senderPeerId}`);
+        try {
+            const message = JSON.parse(new TextDecoder().decode(new Uint8Array(event.message)));
+            console.log(`  Content:`, message);
+        } catch (e) {
+            console.log(`  (Binary message, ${event.message?.length || 0} bytes)`);
+        }
+    });
+
+    // Audio data received - this is where we record!
+    // This event fires for each audio frame received from peers
+    room.onAudioDataReceived((data) => {
+        const mediaId = data.mediaId;
+
+        // Create a new recording file if this is a new media stream
+        if (!fileRecorder[mediaId]) {
+            const timestamp = new Date().toISOString().replace(/[:.]/g, '-');
+            const peerName = activePeers.get(data.peerId)?.name || `peer${data.peerId}`;
+            const fileName = `./recording_${peerName}_media${mediaId}_${timestamp}.wav`;
+
+            console.log(`[Recording] Started: ${fileName}`);
+
+            fileRecorder[mediaId] = {
                 wavEncoder: new wav.FileWriter(fileName, {
-                    channels: 1,
-                    sampleRate: 48000,
-                    bitDepth: 16
+                    channels: 2,       // ODIN decoder outputs stereo (interleaved L/R)
+                    sampleRate: 48000, // ODIN uses 48kHz
+                    bitDepth: 16       // 16-bit samples
                 }),
-                fileName: fileName
+                fileName: fileName,
+                peerId: data.peerId,
+                sampleCount: 0
             };
-        } else {
-            // We already have a file for this media stream - reset the timer to avoid closing the file
-            if (fileRecorder[event.mediaId].timer) {
-                clearTimeout(fileRecorder[event.mediaId].timer);
-                delete fileRecorder[event.mediaId].timer;
-            }
         }
-    } else {
-        // User stopped talking
-        if (fileRecorder[event.mediaId]) {
-            // If we don't have a timer yet, create one
-            if (!fileRecorder[event.mediaId].timer) {
-                fileRecorder[event.mediaId].timer = setTimeout(() => {
-                    // The timer timed out - i.e. the user did stop talking for 2 seconds - close the file
-                    fileRecorder[event.mediaId].wavEncoder.end();
-
-                    // Transcribe the file using OpenAI
-                    try {
-                        const file = fs.createReadStream(fileRecorder[event.mediaId].fileName);
-                        openai.createTranscription(file, "whisper-1").then((response) => {
-                            console.log("OpenAI Transcription: ", response.data.text);
-                        });
-                    } catch (e) {
-                        console.log("Failed to transcribe: ", e);
-                    }
-
-                    // Delete the file recorder object
-                    delete fileRecorder[event.mediaId];
-                }, 2000);
-            }
+
+        // Write audio samples to the recording
+        const recorder = fileRecorder[mediaId];
+        if (recorder && data.samples16) {
+            // Convert Int16Array to Buffer and write to WAV file
+            const buffer = Buffer.from(data.samples16.buffer, data.samples16.byteOffset, data.samples16.byteLength);
+            recorder.wavEncoder.write(buffer);
+            recorder.sampleCount += data.samples16.length;
         }
-    }
-});
+    });
 
-// Configure user data used by the bot - this user data will be compatible with ODIN Web Client (https://odin.4players.de/app).
-const userData = {
-    name: "Recorder Bot",
-    seed: "123",
-    userId: "Bot007",
-    outputMuted: 1,
-    platform: "ODIN JS Bot SDK",
-    version: "0.1"
-}
-// Create a byte array from the user data (ODIN uses byte arrays for user data for maximum flexibility)
-const data = new TextEncoder().encode(JSON.stringify(userData));
-
-// Join the room using the default gateway and our user data
-room.join("gateway.odin.4players.io", data);
-
-// Print the room-id
-console.log("ROOM-ID:", room.id);
-
-// Add an event filter for audio data received events
-room.addEventListener('AudioDataReceived', (data) => {
-    // Getting an array of the sample buffer - use for example to visualize audio
-    /*
-    let ui32 = new Float32Array(data.samples32.buffer);
-    console.log(ui32);
-
-    let ui16 = new Int16Array(data.samples16.buffer);
-    console.log(ui16);
-     */
-
-    // Write the audio data to the file using a WAV encoder
-    if (fileRecorder[data.mediaId]) {
-        fileRecorder[data.mediaId].wavEncoder.file.write(data.samples16, (error) => {
-            if (error) {
-                console.log("Failed to write audio file");
-            }
-        });
-    }
-});
+    // ========================================
+    // Join the room
+    // ========================================
 
-// Prepare a message compatible with the ODIN Web Client and send it to all users (see @4players/odin-foundation for more info)
-const message = {
-    kind: 'message',
-    payload: {
-        text: 'Hello World'
+    console.log("5. Joining room...");
+    try {
+        room.join("https://gateway.odin.4players.io");
+        console.log("   Join initiated.\n");
+    } catch (e) {
+        console.error("Failed to join:", e.message);
+        process.exit(1);
     }
+
+    // ========================================
+    // Graceful shutdown handler
+    // ========================================
+
+    console.log("Recording bot is running. Press Ctrl+C to stop.\n");
+
+    const shutdown = () => {
+        console.log("\n[Shutdown] Stopping...");
+
+        // Close all active recordings
+        for (const [mediaId, recorder] of Object.entries(fileRecorder)) {
+            console.log(`[Recording] Finalizing: ${recorder.fileName} (${recorder.sampleCount} samples)`);
+            recorder.wavEncoder.end();
+        }
+
+        // Close room connection
+        room.close();
+        console.log("[Shutdown] Room closed.");
+        process.exit(0);
+    };
+
+    process.on('SIGINT', shutdown);
+    process.on('SIGTERM', shutdown);
+
+    // Keep the process alive indefinitely
+    await new Promise(() => { }); // Never resolves - run until interrupted
 }
-room.sendMessage(new TextEncoder().encode(JSON.stringify(message)));
-
-// Wait for a key press to stop the script
-console.log("Press any key to stop");
-const stdin = process.stdin;
-stdin.resume();
-stdin.setEncoding( 'utf8' );
-stdin.on( 'data', function( key )
-{
-    console.log("Shutting down");
-    room.close();
-    fileWriter.end();
-
-    process.exit();
+
+// ============================================
+// Entry Point
+// ============================================
+
+run().catch(err => {
+    console.error("Fatal error:", err);
+    process.exit(1);
 });