@4players/odin-nodejs 0.10.3 → 0.11.1

package/libs/include/odin_crypto.h

@@ -0,0 +1,46 @@
+/* Copyright (c) 4Players GmbH. All rights reserved. */
+
+#pragma once
+
+/** @file */
+
+#include <stdarg.h>
+#include <stdbool.h>
+#include <stddef.h>
+#include <stdint.h>
+#include <stdlib.h>
+#include "odin.h"
+
+#define ODIN_CRYPTO_VERSION "1.0.0"
+
+#define OdinCipherImpl_ADDITIONAL_CAPACITY_DATAGRAM (TAG_SIZE + 12)
+
+enum OdinCryptoPeerStatus
+#ifdef __cplusplus
+  : int32_t
+#endif // __cplusplus
+ {
+    ODIN_CRYPTO_PEER_STATUS_PASSWORD_MISSMATCH = -1,
+    ODIN_CRYPTO_PEER_STATUS_UNKNOWN = 0,
+    ODIN_CRYPTO_PEER_STATUS_UNENCRYPTED = 1,
+    ODIN_CRYPTO_PEER_STATUS_ENCRYPTED = 2,
+};
+#ifndef __cplusplus
+typedef int32_t OdinCryptoPeerStatus;
+#endif // __cplusplus
+
+#ifdef __cplusplus
+extern "C" {
+#endif // __cplusplus
+
+OdinCipher *odin_crypto_create(const char *version);
+
+OdinCryptoPeerStatus odin_crypto_get_peer_status(OdinCipher *cipher, uint64_t peer_id);
+
+int32_t odin_crypto_set_password(OdinCipher *cipher,
+                                 const uint8_t *password,
+                                 uint32_t password_length);
+
+#ifdef __cplusplus
+}  // extern "C"
+#endif  // __cplusplus

package/odin.cipher.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Possible encryption status values for a peer.
+ * - 'unknown': Peer status not yet determined (no communication yet)
+ * - 'unencrypted': Peer is not using encryption
+ * - 'encrypted': Peer is using encryption with a matching password
+ * - 'password_mismatch': Peer is encrypted but password doesn't match
+ */
+export type OdinCryptoPeerStatus = 'unknown' | 'unencrypted' | 'encrypted' | 'password_mismatch';
+
+export declare class OdinCipher {
+    /**
+     * Creates a new OdinCipher instance with default version.
+     */
+    constructor();
+
+    /**
+     * Sets the encryption password for end-to-end encryption.
+     * All audio and messages will be encrypted using this password.
+     * @param password - The password as a byte array.
+     */
+    setPassword(password: Uint8Array): void;
+
+    /**
+     * Gets the encryption status of a specific peer.
+     * Useful for verifying that E2EE is working correctly with each peer.
+     * 
+     * @param peerId - The peer ID to check status for.
+     * @returns The encryption status of the peer.
+     */
+    getPeerStatus(peerId: number): OdinCryptoPeerStatus;
+}

package/odin.media.d.ts

@@ -1,12 +1,35 @@
-import {OdinAPMSettings, OdinRoom} from "./odin.room";
+import { OdinAPMSettings, OdinRoom } from "./odin.room";
 
 /**
- * The OdinMedia class. Represents a local media stream added to the room - i.e. a microphone, another audio stream like files.
+ * Represents a decoded audio buffer (from audio-decode library).
+ */
+export interface AudioBuffer {
+    sampleRate: number;
+    numberOfChannels: number;
+    duration: number;
+    length: number;
+    getChannelData(channel: number): Float32Array;
+}
+
+/**
+ * The OdinMedia class represents a local audio stream for sending audio to the room.
  * Don't create OdinMedia instances directly, use `createAudioStream` from OdinRoom instead.
+ * 
+ * This wrapper closely follows the core ODIN SDK pattern:
+ * 1. Create audio stream: `media = room.createAudioStream(48000, 2)`
+ * 2. Set server-assigned media ID: `media.setMediaId(mediaIds[0])`  // From Joined event
+ * 3. Send audio chunks: `media.sendAudioData(chunk)`  // 20ms chunks recommended
+ * 4. When done: `media.close()`
+ * 
+ * Or use the convenience API for file playback:
+ *   await media.sendMP3('./file.mp3');   // Auto handles everything
+ *   await media.sendWAV('./file.wav');
+ *   await media.sendBuffer(audioBuffer);
  */
 export declare class OdinMedia {
     /**
-     * Creates a new instance of a media object. Don't create OdinMedia directly, use `createAudioStream` from OdinRoom instead.
+     * Creates a new instance of a media object.
+     * Don't create OdinMedia directly, use `createAudioStream` from OdinRoom instead.
      * @param room - The room to add the media to.
      * @param sampleRate - The sample rate of the audio stream (between 8000 and 48000)
      * @param channelCount - The number of channels of the audio stream (1 or 2)
@@ -15,35 +38,62 @@ export declare class OdinMedia {
     constructor(room: OdinRoom, sampleRate: number, channelCount: number, options?: OdinAPMSettings);
 
     /**
-     * Closes the local audio stream and removed the media from the room
+     * Sets the server-assigned media ID.
+     * Must be called before sendAudioData() with an ID from the Joined event's mediaIds array.
+     * @param mediaId - The media ID from Joined event
+     */
+    setMediaId(mediaId: number): void;
+
+    /**
+     * Closes the local audio stream and releases resources.
+     * After calling this, the media stream cannot be used.
      */
     close(): void;
 
     /**
-     * Instructs the server to pause the media object, ceasing the reception of
-     * data. This operation essentially communicates a server-side mute request from the client, thus
-     * indicating a desire to halt packet reception for this media stream.
+     * Sends audio data to the room.
+     * Data must be a 32-bit float array with samples between -1 and 1.
+     * Audio data should be sent in regular intervals (20ms chunks recommended).
+     * @param data - A 32-bit float array containing the audio data.
+     */
+    sendAudioData(data: Float32Array): void;
+
+    /**
+     * Send an MP3 file with automatic decoding and real-time streaming.
+     * Handles all setup (media ID, StartMedia RPC, timing) automatically.
+     * 
+     * @param filePath - Path to the MP3 file
+     * @returns Promise that resolves when audio streaming is complete
      */
-    pause(): void;
+    sendMP3(filePath: string): Promise<void>;
 
     /**
-     * Instructs the server to resume the media object, resuming the reception of
-     * data. This operation essentially communicates a server-side unmute request from the client, thus
-     * indicating a desire to resume packet reception for this media stream.
+     * Send a WAV file with automatic decoding and real-time streaming.
+     * Handles all setup (media ID, StartMedia RPC, timing) automatically.
+     * 
+     * @param filePath - Path to the WAV file
+     * @returns Promise that resolves when audio streaming is complete
      */
-    resume(): void;
+    sendWAV(filePath: string): Promise<void>;
 
     /**
-     * Sends audio data to the room. The data must be in the format specified when creating the media as a 32-bit float array.
-     * Samples need to be between -1 and 1. Audio data needs to be sent in regular intervals, otherwise the audio will be sound
-     * interrupted. See the example for more details.
-     * @param data - A 32-bit float array containing the audio data.
+     * Send decoded audio with real-time streaming.
+     * Handles all setup (media ID, StartMedia RPC, timing) automatically.
+     * 
+     * @param audioBuffer - Decoded audio buffer (from audio-decode library)
+     * @returns Promise that resolves when audio streaming is complete
      */
-    sendAudioData(data: Float32Array): void;
+    sendBuffer(audioBuffer: AudioBuffer): Promise<void>;
 
     /**
      * Gets the ID of the media.
-     * @returns The ID of the media.
+     * @returns The ID of the media, or null if closed.
+     */
+    get id(): number | null;
+
+    /**
+     * Checks if this media stream has been closed.
+     * @returns True if the stream is closed and can no longer be used.
      */
-    get id(): string;
+    get closed(): boolean;
 }

package/odin.room.d.ts

@@ -1,4 +1,5 @@
-import {OdinMedia} from "./odin.media";
+import { OdinMedia } from "./odin.media";
+import { OdinCipher } from "./odin.cipher";
 
 /**
  * Defines available Odin events
@@ -64,6 +65,11 @@ declare interface OdinEvents {
      * You can use the samples to record audio or send them to an AI for transcription.
      */
     AudioDataReceived: OdinAudioDataReceivedEvent;
+
+    /**
+     * Fired when the tags of a remote peer changed.
+     */
+    PeerTagsChanged: OdinPeerTagsChangedEvent;
 }
 
 export type OdinConnectionStateChangedEvent = (event: OdinConnectionStateChangedEventPayload) => void;
@@ -78,6 +84,7 @@ export type OdinMediaAddedEvent = (event: OdinMediaAddedEventPayload) => void;
 export type OdinMediaRemovedEvent = (event: OdinMediaRemovedEventPayload) => void;
 export type OdinMediaActivityEvent = (event: OdinMediaActivityEventPayload) => void;
 export type OdinAudioDataReceivedEvent = (event: OdinAudioDataReceivedEventPayload) => void;
+export type OdinPeerTagsChangedEvent = (event: OdinPeerTagsChangedEventPayload) => void;
 
 /**
  * The base event payload that is passed to all events.
@@ -94,8 +101,87 @@ declare interface OdinEventPayload {
     tag: number;
 }
 
+/**
+ * Represents a media stream in the ODIN room.
+ * Media streams are used for audio transmission between peers.
+ */
+export declare interface OdinMediaInfo {
+    /**
+     * The unique identifier of the media stream.
+     */
+    id: number;
+
+    /**
+     * Custom properties associated with this media stream.
+     */
+    properties: Record<string, unknown>;
+
+    /**
+     * Whether the media stream is currently paused.
+     */
+    paused: boolean;
+}
+
+/**
+ * Represents a peer in the ODIN room.
+ * A peer is a participant in the room that can send and receive audio.
+ */
+export declare interface OdinPeerInfo {
+    /**
+     * The unique identifier of the peer within the room.
+     */
+    id: number;
+
+    /**
+     * The user ID associated with this peer (from the token).
+     */
+    user_id: string;
+
+    /**
+     * Custom user data associated with this peer.
+     */
+    user_data: Uint8Array | undefined;
+
+    /**
+     * List of media streams owned by this peer.
+     */
+    medias: OdinMediaInfo[];
+
+    /**
+     * Tags associated with this peer for filtering/grouping.
+     */
+    tags: string[];
+}
+
+/**
+ * Represents the room state returned when joining.
+ * Contains information about the room and all current participants.
+ */
+export declare interface OdinRoomInfo {
+    /**
+     * The unique identifier of the room.
+     */
+    id: string;
+
+    /**
+     * The customer ID owning this room.
+     */
+    customer: string;
+
+    /**
+     * Custom user data associated with the room.
+     */
+    user_data: Uint8Array | undefined;
+
+    /**
+     * List of all peers currently in the room.
+     */
+    peers: OdinPeerInfo[];
+}
+
 /**
  * The payload for the Joined event.
+ * This event is fired when the local user successfully joins a room.
  */
 export declare interface OdinJoinedEventPayload extends OdinEventPayload {
     /**
@@ -104,29 +190,39 @@ export declare interface OdinJoinedEventPayload extends OdinEventPayload {
     roomId: string;
 
     /**
-     * The ID of the local peer.
+     * The ID of the local peer within the room.
      */
     ownPeerId: number;
 
     /**
-     * The ID of the local user. It is the same as the user id that was passed to join.
+     * The full room state including all current peers and their media streams.
      */
-    ownUserId: string;
+    room: OdinRoomInfo;
 
     /**
-     * The current user data of the room
+     * List of media IDs owned by the local peer.
+     * These are media streams that were previously created and are still active.
      */
-    roomUserData: Uint8Array | undefined;
+    mediaIds: number[];
 }
 
 /**
  * The payload for the Left event.
+ * This event is fired when the local user leaves a room, either due to a server-initiated
+ * disconnect or when `room.close()` is called programmatically.
  */
 export declare interface OdinLeftEventPayload extends OdinEventPayload {
     /**
-     * The ID of the room that was left. It's the same as the room id that was passed to join.
+     * The ID of the room that was left.
      */
     roomId: string;
+
+    /**
+     * The reason for leaving the room.
+     * - 'ClientDisconnect': The client called `room.close()` programmatically
+     * - Other values: Server-initiated disconnects (e.g., 'kicked', 'timeout', etc.)
+     */
+    reason: string;
 }
 
 /**
@@ -301,6 +397,21 @@ export declare interface OdinAudioDataReceivedEventPayload {
     samples32: Uint8Array;
 }
 
+/**
+ * The payload for the PeerTagsChanged event.
+ */
+export declare interface OdinPeerTagsChangedEventPayload extends OdinEventPayload {
+    /**
+     * The ID of the peer whose tags changed.
+     */
+    peerId: number;
+
+    /**
+     * The new tags of the peer.
+     */
+    tags: string[];
+}
+
 /**
  * Noise suppression levels
  */
@@ -474,8 +585,24 @@ export declare class OdinRoom {
      */
     setPositionScale(scale: number): void;
 
+    /**
+     * Sets the cipher for end-to-end encryption.
+     * @param cipher - The cipher instance.
+     */
+    setCipher(cipher: OdinCipher): void;
+
     /**
      * Closes the room and disconnects from the server.
+     * 
+     * This method emits the 'Left' event before closing the native connection,
+     * ensuring that cleanup callbacks registered via `onLeft()` are triggered.
+     * The event payload will contain `{ reason: 'ClientDisconnect' }` to
+     * distinguish it from server-initiated disconnects.
+     * 
+     * This provides a single, consistent cleanup path for session state management,
+     * as the `onLeft` handler will fire for both:
+     * - Client-initiated disconnects (calling `close()`)
+     * - Server-initiated disconnects (kicked, timeout, etc.)
      */
     close(): void;
 
@@ -497,4 +624,218 @@ export declare class OdinRoom {
      * @returns The OdinMedia object that allows you to send audio data.
      */
     createAudioStream(sampleRate: number, channels: number, apmSettings?: OdinAPMSettings): OdinMedia;
+
+    /**
+     * Gets whether the room is currently connected.
+     */
+    get connected(): boolean;
+
+    // =========================================
+    // Convenience event handler methods
+    // =========================================
+
+    /**
+     * Set handler for when room is successfully joined.
+     * @param handler - Handler receiving `{ roomId, ownPeerId, room }`
+     */
+    onJoined(handler: OdinJoinedEvent): void;
+
+    /**
+     * Set handler for when room is left.
+     * @param handler - Handler receiving `{ reason }`
+     */
+    onLeft(handler: OdinLeftEvent): void;
+
+    /**
+     * Set handler for peer joined events.
+     * @param handler - Handler receiving `{ peerId, peer, userId, userData }`
+     */
+    onPeerJoined(handler: OdinPeerJoinedEvent): void;
+
+    /**
+     * Set handler for peer left events.
+     * @param handler - Handler receiving `{ peerId }`
+     */
+    onPeerLeft(handler: OdinPeerLeftEvent): void;
+
+    /**
+     * Set handler for media started events (when a peer starts streaming audio).
+     * @param handler - Handler receiving `{ peerId, media }`
+     */
+    onMediaStarted(handler: OdinMediaAddedEvent): void;
+
+    /**
+     * Set handler for media stopped events.
+     * @param handler - Handler receiving `{ peerId, mediaId }`
+     */
+    onMediaStopped(handler: OdinMediaRemovedEvent): void;
+
+    /**
+     * Set handler for message received events.
+     * @param handler - Handler receiving `{ senderPeerId, message }`
+     */
+    onMessageReceived(handler: OdinMessageReceivedEvent): void;
+
+    /**
+     * Set handler for connection state changes.
+     * @param handler - Handler receiving `{ state, message }`
+     */
+    onConnectionStateChanged(handler: OdinConnectionStateChangedEvent): void;
+
+    /**
+     * Set handler for audio data events (for recording/processing).
+     * @param handler - Handler receiving `{ peerId, mediaId, samples16, samples32 }`
+     */
+    onAudioDataReceived(handler: OdinAudioDataReceivedEvent): void;
+
+    /**
+     * Set handler for peer user data changed events.
+     * @param handler - Handler receiving `{ peerId, userData }`
+     */
+    onPeerUserDataChanged(handler: OdinPeerUserDataChangedEvent): void;
+
+    /**
+     * Set handler for room user data changed events.
+     * @param handler - Handler receiving `{ userData }`
+     */
+    onRoomUserDataChanged(handler: OdinRoomUserDataChangedEvent): void;
+
+    /**
+     * Set handler for media activity events (voice activity detection).
+     * @param handler - Handler receiving `{ peerId, mediaId, state }`
+     */
+    onMediaActivity(handler: OdinMediaActivityEvent): void;
+
+    /**
+     * Set handler for peer tags changed events.
+     * @param handler - Handler receiving `{ peerId, tags }`
+     */
+    onPeerTagsChanged(handler: OdinPeerTagsChangedEvent): void;
+
+    // =========================================
+    // Diagnostics and Statistics
+    // =========================================
+
+    /**
+     * Retrieves detailed connection statistics for the room.
+     * Useful for monitoring network quality and debugging connectivity issues.
+     * @returns Connection statistics object, or null if not connected.
+     */
+    getConnectionStats(): OdinConnectionStats | null;
+
+    /**
+     * Retrieves the underlying connection identifier for the room.
+     * @returns The connection ID, or 0 if not connected.
+     */
+    getConnectionId(): number;
+
+    /**
+     * Retrieves jitter buffer statistics for a specific media stream.
+     * Useful for debugging audio quality issues.
+     * @param mediaId - The media ID to get jitter stats for.
+     * @returns Jitter statistics object, or null if decoder not found.
+     */
+    getJitterStats(mediaId: number): OdinJitterStats | null;
+}
+
+/**
+ * Connection statistics returned by getConnectionStats().
+ * Provides detailed metrics about the underlying UDP connection.
+ */
+export declare interface OdinConnectionStats {
+    /**
+     * The number of outgoing UDP datagrams sent.
+     */
+    udpTxDatagrams: number;
+
+    /**
+     * The total number of bytes sent in outgoing UDP datagrams.
+     */
+    udpTxBytes: number;
+
+    /**
+     * The packet loss percentage for outgoing UDP datagrams (0.0 to 1.0).
+     */
+    udpTxLoss: number;
+
+    /**
+     * The number of incoming UDP datagrams received.
+     */
+    udpRxDatagrams: number;
+
+    /**
+     * The total number of bytes received in incoming UDP datagrams.
+     */
+    udpRxBytes: number;
+
+    /**
+     * The packet loss percentage for incoming UDP datagrams (0.0 to 1.0).
+     */
+    udpRxLoss: number;
+
+    /**
+     * The current congestion window size in bytes.
+     */
+    cwnd: number;
+
+    /**
+     * The number of congestion events that have occurred.
+     */
+    congestionEvents: number;
+
+    /**
+     * The current round-trip time (RTT) in milliseconds.
+     */
+    rtt: number;
+}
+
+/**
+ * Jitter buffer statistics returned by getJitterStats().
+ * Provides detailed metrics about audio packet reception and processing.
+ */
+export declare interface OdinJitterStats {
+    /**
+     * The total number of packets seen by the jitter buffer.
+     */
+    packetsTotal: number;
+
+    /**
+     * The number of packets currently buffered.
+     */
+    packetsBuffered: number;
+
+    /**
+     * The number of packets successfully processed.
+     */
+    packetsProcessed: number;
+
+    /**
+     * The number of packets dropped because they arrived too early.
+     */
+    packetsArrivedTooEarly: number;
+
+    /**
+     * The number of packets dropped because they arrived too late.
+     */
+    packetsArrivedTooLate: number;
+
+    /**
+     * The number of packets dropped due to jitter buffer reset.
+     */
+    packetsDropped: number;
+
+    /**
+     * The number of packets marked as invalid.
+     */
+    packetsInvalid: number;
+
+    /**
+     * The number of duplicate packets received.
+     */
+    packetsRepeated: number;
+
+    /**
+     * The number of packets lost during transmission.
+     */
+    packetsLost: number;
 }

package/package.json

@@ -1,12 +1,12 @@
 {
   "name": "@4players/odin-nodejs",
-  "version": "0.10.3",
+  "version": "0.11.1",
   "description": "NodeJS bindings for the ODIN SDK. Use for AI enhanced human interactions, content moderation and audio processing features in a backend.",
   "main": "index.cjs",
   "types": "index.d.ts",
   "scripts": {
-    "build:debug": "node-gyp rebuild --debug",
-    "build:release": "node-gyp rebuild",
+    "build:debug": "node-gyp rebuild --debug && node scripts/postbuild.cjs debug",
+    "build:release": "node-gyp rebuild && node scripts/postbuild.cjs",
     "build": "npm run build:release",
     "clean": "node-gyp clean",
     "install": "node-gyp-build"
@@ -20,6 +20,7 @@
   "dependencies": {
     "@4players/odin-foundation": "^0.2.0",
     "@4players/odin-tokens": "^1.3.0",
+    "@msgpack/msgpack": "^3.1.2",
     "audio-buffer-stream": "^1.1.0",
     "audio-decode": "^2.1.1",
     "audio-lena": "^2.3.0",
@@ -47,4 +48,4 @@
     "x64",
     "arm64"
   ]
-}
+}