@4players/odin-nodejs 0.10.3 → 0.11.1

package/tests/sending-audio/README.md

@@ -1,20 +1,189 @@
-# ODIN Send Music Example
+# ODIN Audio Sending Examples
 
-This sample demonstrates how to use the ODIN SDK to send music to other users in a room. It loads a sample MP3 file, 
-decodes it and sends it to the ODIN server. 
+This folder contains examples demonstrating how to send audio to an ODIN room using both the **high-level** and **low-level** APIs.
+
+## Examples
+
+| File | API Level | Description |
+|------|-----------|-------------|
+| `test-kiss-api.js` | **High-Level** | Simplified API - just call `media.sendMP3()` |
+| `index.js` | **Low-Level** | Full control over audio transmission |
 
 ## 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://www.4players.io/odin/introduction/access-keys/)
+2. **Audio File**: A sample `santa.mp3` is included for testing
+
+## Configuration
+
+Edit either script and replace the placeholder values:
+
+```javascript
+const accessKey = "__YOUR_ACCESS_KEY__";  // Your ODIN access key
+const roomId = "__YOUR_ROOM_ID__";        // Room to send audio to
+const userId = "AudioBot-123";            // Bot's user ID
+```
+
+To enable E2EE (must match other peers):
+
+```javascript
+const cipherPassword = "shared-secret";
+```
+
+---
+
+## High-Level API (`test-kiss-api.js`)
+
+The high-level API is the **recommended approach** for most use cases. It handles all the complexity automatically.
 
-## Getting Started
+### Features
+- **Automatic Setup**: Claims media ID, sends StartMedia RPC
+- **Audio Decoding**: Supports MP3, WAV, and other formats
+- **Precise Timing**: Streams audio in 20ms chunks with correct timing
+- **Simple Interface**: One method call to send an entire file
 
-Run the script with the following command:
+### Running
 
 ```bash
+cd tests/sending-audio
+node test-kiss-api.js
+```
+
+### Code Example
+
+```javascript
+// Create room and wait for join
+const room = client.createRoom(token);
+await new Promise(resolve => room.onJoined(resolve));
+room.join("https://gateway.odin.4players.io");
+
+// Create audio stream
+const media = room.createAudioStream(44100, 2);
+
+// Send audio with one line!
+await media.sendMP3('./music.mp3');
+
+// Or send other formats
+await media.sendWAV('./audio.wav');
+await media.sendBuffer(audioBuffer);  // Decoded AudioBuffer
+
+// Clean up
+media.close();
+```
+
+---
+
+## Low-Level API (`index.js`)
+
+The low-level API provides **full control** over audio transmission. Use it when you need:
+
+- Custom audio sources (microphone, synthesized audio, real-time processing)
+- Dynamic sample rate or channel configuration
+- Fine-grained timing control
+- Integration with custom audio pipelines
+
+### Running
+
+```bash
+cd tests/sending-audio
 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
-start sending an MP3 file into the room.
+### Workflow
+
+1. **Join Room** and wait for `Joined` event
+2. **Get Media ID** from `event.mediaIds`
+3. **Create Audio Stream** with sample rate and channels
+4. **Set Media ID** on the stream
+5. **Send StartMedia RPC** to notify server
+6. **Send Audio Data** in 20ms chunks
+7. **Close** when done
+
+### Code Example
+
+```javascript
+import { encode } from '@msgpack/msgpack';
+
+room.onJoined(async (event) => {
+    // Get media ID from the event
+    const mediaId = event.mediaIds[0];
+    
+    // Create audio stream
+    const media = room.createAudioStream(48000, 2);
+    
+    // Set the server-assigned media ID
+    media.setMediaId(mediaId);
+    
+    // Notify server we're about to transmit
+    const rpc = encode([0, 1, "StartMedia", {
+        media_id: mediaId,
+        properties: { kind: "audio" }
+    }]);
+    room.sendRpc(new Uint8Array(rpc));
+    
+    // Send audio in 20ms chunks
+    const chunkMs = 20;
+    const samplesPerChunk = Math.floor(48000 * chunkMs / 1000) * 2;
+    
+    for (const chunk of audioChunks) {
+        media.sendAudioData(chunk);
+        await sleep(chunkMs);
+    }
+    
+    // Clean up
+    media.close();
+});
+```
+
+---
+
+## Audio Format Requirements
+
+### Input Audio
+- **Formats**: MP3, WAV, OGG, FLAC (via audio-decode)
+- **Sample Rate**: Any (encoder handles resampling)
+- **Channels**: Mono or Stereo
+
+### sendAudioData() Requirements
+- **Type**: `Float32Array`
+- **Range**: `-1.0` to `1.0`
+- **Format**: Interleaved if stereo (L, R, L, R, ...)
+- **Chunk Size**: 20ms worth of samples
+
+---
+
+## Comparison
+
+| Feature | High-Level API | Low-Level API |
+|---------|---------------|---------------|
+| Setup Complexity | Automatic | Manual |
+| Media ID Handling | Automatic | Manual |
+| StartMedia RPC | Automatic | Manual |
+| Timing | Automatic | Manual |
+| Custom Sources | ❌ | ✅ |
+| Real-time Audio | ❌ | ✅ |
+| Audio Processing | ❌ | ✅ |
+
+---
+
+## Troubleshooting
+
+### "No available media IDs" Error
+Wait for the `Joined` event before sending audio. The SDK provides media IDs in this event.
+
+### Audio Not Heard
+1. Check E2EE password matches other peers
+2. Verify you're in the same room
+3. Check that other peers have their audio output enabled
+
+### Audio Choppy
+- Ensure 20ms timing is maintained
+- Check network connection quality
+- Monitor jitter stats with `room.getJitterStats(mediaId)`
+
+---
+
+## Related Examples
+
+- [connection-test](../connection-test/) - Basic connection and events
+- [audio-recording](../audio-recording/) - Record audio from peers

package/tests/sending-audio/index.js

@@ -1,107 +1,270 @@
-const accessKey = "ASBKPRwUpEabybkUJMfdLD2b2J8K2mus1ekxMUK7VPEA";
-const roomName = "Lobby";
-const userName = "My Bot";
+/**
+ * ODIN Node.js SDK - Audio Sending Example (Low-Level API)
+ * 
+ * This example demonstrates the LOW-LEVEL API for sending audio to an ODIN room.
+ * Use this approach when you need full control over audio transmission, such as:
+ * - Custom audio sources (microphone, synthesized audio)
+ * - Dynamic sample rate or channel configuration
+ * - Fine-grained timing control
+ * - Integration with custom audio processing pipelines
+ * 
+ * For simpler use cases, see test-kiss-api.js which uses the HIGH-LEVEL API.
+ * 
+ * Workflow:
+ * 1. Join the room and wait for the Joined event
+ * 2. Get media ID from the event's mediaIds array
+ * 3. Create audio stream with sample rate and channels
+ * 4. Set the media ID on the stream
+ * 5. Send StartMedia RPC to notify the server
+ * 6. Push audio samples in 20ms chunks
+ * 7. Close when done
+ * 
+ * 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 and other libs
 import odin from '../../index.cjs';
-const {OdinClient} = odin;
+const { OdinClient, OdinCipher } = odin;
 import fs from 'fs';
-import decode, {decoders} from 'audio-decode';
-import AudioBufferStream from 'audio-buffer-stream';
-
-// Create an odin client instance using our access key and create a room
-const userData = {
-    name: "Music Bot",
-    avatar: "https://avatars.dicebear.com/api/bottts/123.svg?backgroundColor=%23333333&textureChance=0&margin=10",
-    seed: "123",
-    userId: "Bot007",
-    outputMuted: 1,
-    inputMuted: 0,
-    platform: "ODIN JS Bot SDK",
-    version: "0.1"
-}
-const data = new TextEncoder().encode(JSON.stringify(userData));
-const odinClient = new OdinClient(48000, 2);
+import decode from 'audio-decode';
+import path from 'path';
+import { fileURLToPath } from 'url';
+import { encode } from '@msgpack/msgpack';
 
-// Create a token then join the room with that token, token may also be created elsewhere
-const token = odinClient.generateToken(accessKey, roomName, userName);
-const room = odinClient.createRoomWithToken(token);
+// Get the directory of the current script (ESM equivalent of __dirname)
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
 
-// It's also possible to create a room with an access key, room name and username then token is created internally
-//const room = odinClient.createRoom(accessKey, roomName, userName);
+// ============================================
+// Configuration - Replace with your values
+// ============================================
 
-// Join the room
-room.join("gateway.odin.4players.io", data);
+/** 
+ * Your ODIN access key. Get one for free at https://docs.4players.io/voice/introduction/access-keys/
+ * @type {string}
+ */
+const accessKey = "__YOUR_ACCESS_KEY__";
 
-// Send a message to the room
-const message = {
-    kind: 'message',
-    payload: 'Hello, I am a music bot and will stream some music to you.'
-}
-room.sendMessage(new TextEncoder().encode(JSON.stringify(message)));
-
-// Send music to the room
-const sendMusic = async (media) => {
-    // Prepare our MP3 decoder and load the sample file
-    const audioBuffer = await decode(fs.readFileSync('./santa.mp3'));
-
-    // Create a stream that will match the settings of the file
-    const audioBufferStream = new AudioBufferStream({
-        channels: audioBuffer.numberOfChannels,
-        sampleRate: audioBuffer.sampleRate,
-        float: true,
-        bitDepth: 32,
-        chunkLength: 960 // 960 bytes every 20ms - might be doubled (1920) depending on the sample rate
-    });
+/**
+ * The room ID to join. All users joining the same room can hear your audio.
+ * @type {string}
+ */
+const roomId = "__YOUR_ROOM_ID__";
 
-    // Create a queue to store the chunks of audio data
-    const queue = [];
+/**
+ * Your unique user identifier.
+ * @type {string}
+ */
+const userId = "AudioBot-" + Math.floor(Math.random() * 10000);
 
-    // Whenever the stream has data, add it to the queue
-    audioBufferStream.on('data', (data) => {
-        const floats = new Float32Array(new Uint8Array(data).buffer);
-        queue.push(floats);
-    });
+/**
+ * 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;
+
+// ============================================
+// Audio Sending Function
+// ============================================
+
+/**
+ * Decodes an audio file and sends it to the room in real-time.
+ * Splits the audio into 20ms chunks and sends them with precise timing.
+ * 
+ * @param {object} media - The OdinMedia stream object
+ * @param {number} sampleRate - Target sample rate in Hz
+ * @param {number} numChannels - Number of channels (1=mono, 2=stereo)
+ */
+async function sendMusic(media, sampleRate, numChannels) {
+    console.log("Loading and decoding audio file...");
 
-    // Start a timer to send audio data at regular intervals
-    const interval = setInterval(() => {
-        if (queue.length > 0) {
-            const chunk = queue.shift();
-            media.sendAudioData(chunk);
-        } else {
-            // If there's no more data to send, stop the timer
-            clearInterval(interval);
-            audioBufferStream.end();
-            console.log("Audio finished");
+    // Load and decode the MP3 file
+    const audioBuffer = await decode(fs.readFileSync(path.join(__dirname, 'santa.mp3')));
+    console.log(`Audio loaded: ${audioBuffer.duration.toFixed(2)}s, ${audioBuffer.sampleRate}Hz, ${audioBuffer.numberOfChannels} channels`);
+
+    // Convert to interleaved format if stereo
+    let audioData;
+    if (numChannels === 2) {
+        const left = audioBuffer.getChannelData(0);
+        const right = audioBuffer.getChannelData(1);
+        const interleaved = new Float32Array(left.length * 2);
+        for (let i = 0; i < left.length; i++) {
+            interleaved[i * 2] = left[i];
+            interleaved[i * 2 + 1] = right[i];
         }
-    }, 20);  // Send a chunk every 20ms
+        audioData = interleaved;
+    } else {
+        audioData = audioBuffer.getChannelData(0);
+    }
+
+    // Calculate chunk size for 20ms of audio
+    const chunkDurationMs = 20;
+    const samplesPerChunk = Math.floor(sampleRate * chunkDurationMs / 1000);
+    const floatsPerChunk = samplesPerChunk * numChannels;
+
+    // Split audio into 20ms chunks
+    const chunks = [];
+    for (let offset = 0; offset < audioData.length; offset += floatsPerChunk) {
+        const end = Math.min(offset + floatsPerChunk, audioData.length);
+        chunks.push(audioData.slice(offset, end));
+    }
+
+    console.log(`Sending ${chunks.length} chunks (${samplesPerChunk} samples/chunk at ${sampleRate}Hz)...`);
+
+    // Send chunks with precise timing to maintain real-time playback
+    const startTime = Date.now();
+    for (let i = 0; i < chunks.length; i++) {
+        // Send the audio data
+        media.sendAudioData(chunks[i]);
 
-    audioBufferStream.write(audioBuffer);
+        // Calculate when the next chunk should be sent
+        const nextChunkTime = startTime + (i + 1) * chunkDurationMs;
+        const now = Date.now();
+        const waitTime = nextChunkTime - now;
+
+        // Wait if we're ahead of schedule
+        if (waitTime > 0 && i < chunks.length - 1) {
+            await new Promise(resolve => setTimeout(resolve, waitTime));
+        }
+    }
+
+    console.log(`Audio streaming complete. Sent ${chunks.length} chunks.`);
 }
 
-room.setPositionScale(25);
-room.updatePosition(0, 0, 0);
+// ============================================
+// Main Function
+// ============================================
 
-// Create a media stream in the room - it will return an OdinMedia instance that we can use to send data to ODIN
-const media = room.createAudioStream(48000, 2);
-console.log(media);
-console.log("MEDIA-ID:", media.id);
+async function main() {
+    console.log("=== ODIN NodeJS SDK - Audio Sending (Low-Level API) ===\n");
 
-// Start the stream and send the music to ODIN
-sendMusic(media).then(() => {
-    console.log("Started sending audio");
-});
+    // Prepare user data to send with join
+    const userData = {
+        name: "Music Bot",
+        avatar: "https://avatars.dicebear.com/api/bottts/123.svg",
+        platform: "ODIN Node.js SDK",
+        version: "0.11.0"
+    };
+    const data = new TextEncoder().encode(JSON.stringify(userData));
+
+    // 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.\n");
+
+    // Step 3: Create room
+    console.log("3. Creating room...");
+    const room = client.createRoom(token);
+
+    // Step 4: Set up E2EE cipher (optional)
+    if (cipherPassword) {
+        console.log("4. Setting up 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.\n");
+    }
+
+    // Set position (optional, for spatial audio)
+    room.setPositionScale(25);
+    room.updatePosition(0, 0, 0);
+
+    // Variable to track if audio has started (prevent duplicate handling)
+    let audioStarted = false;
 
-// Wait until the user presses a key to stop
-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");
+    // Listen for Joined event to get media IDs
+    room.onJoined(async (event) => {
+        console.log(`\n[Event] Joined`);
+        console.log(`   Own Peer ID: ${event.ownPeerId}`);
+        console.log(`   Available Media IDs: ${JSON.stringify(event.mediaIds)}`);
+
+        // Prevent duplicate audio sending
+        if (audioStarted) return;
+        audioStarted = true;
+
+        // Verify we have media IDs available
+        if (!event.mediaIds || event.mediaIds.length === 0) {
+            console.error("   ERROR: No media IDs available!");
+            return;
+        }
+
+        // Get the first available media ID
+        const mediaId = event.mediaIds[0];
+        console.log(`   Using Media ID: ${mediaId}\n`);
+
+        // Step 5: Create audio stream with source sample rate
+        const sampleRate = 44100;  // MP3 sample rate
+        const numChannels = 2;     // Stereo
+        console.log("5. Creating audio stream...");
+        const media = room.createAudioStream(sampleRate, numChannels);
+        console.log(`   Audio stream created (${sampleRate}Hz, ${numChannels === 2 ? 'stereo' : 'mono'}).`);
+
+        // Step 6: Set the server-assigned media ID (critical for SDK 1.8.2+)
+        console.log("6. Setting media ID...");
+        media.setMediaId(mediaId);
+        console.log(`   Media ID set to ${mediaId}.`);
+
+        // Step 7: Send StartMedia RPC to notify server
+        // Format: [type, requestId, methodName, params]
+        console.log("7. Sending StartMedia RPC...");
+        const startMediaRpc = encode([0, 1, "StartMedia", {
+            media_id: mediaId,
+            properties: { kind: "audio" }
+        }]);
+        room.sendRpc(new Uint8Array(startMediaRpc));
+        console.log("   StartMedia RPC sent.");
+
+        // Step 8: Send the audio
+        console.log("8. Sending audio...");
+        await sendMusic(media, sampleRate, numChannels);
+        console.log("   Audio sending complete.\n");
+
+        // Wait for audio to finish transmitting
+        console.log("9. Waiting for transmission to complete...");
+        await new Promise(resolve => setTimeout(resolve, 5000));
+
+        // Step 10: Clean up
+        console.log("10. Closing audio stream...");
+        media.close();
+        console.log("   Audio stream closed.\n");
+    });
+
+    // Connection state handler
+    room.onConnectionStateChanged((event) => {
+        console.log(`[Event] ConnectionStateChanged: ${event.state}${event.message ? ` (${event.message})` : ''}`);
+    });
+
+    // Step: Join the room
+    console.log("Joining room...");
+    room.join("https://gateway.odin.4players.io", data);
+    console.log("   Join initiated.\n");
+
+    // Keep alive for audio transmission
+    console.log("Waiting 30 seconds for audio transmission...\n");
+    await new Promise(resolve => setTimeout(resolve, 30000));
+
+    // Close room
+    console.log("\nClosing room...");
     room.close();
+    console.log("Room closed.\n");
 
-    process.exit();
-});
+    console.log("=== Test Complete ===");
+    process.exit(0);
+}
 
+// ============================================
+// Entry Point
+// ============================================
+
+main().catch(err => {
+    console.error("Error:", err);
+    process.exit(1);
+});