@4players/odin-nodejs 0.7.3 → 0.8.0

package/README.md

@@ -3,7 +3,15 @@
 Native Node JS bindings for the ODIN SDK. It is based on the [ODIN Native SDK](https://github.com/4Players/odin-sdk) and
 wraps the C++ code into a Node JS module.
 
-Please check out the typings in `index.d.ts` for more information on the API.
+Check out documentation and guides at [developers.4players.io](https://www.4players.io/odin/sdk/nodejs).
+
+## Beta!
+
+**This SDK is currently in beta. This means that the API is not final and might change in the future. It's also not ready
+for production use as there might be bugs, memory leaks or other issues.** But it's good enough for testing AI 
+integration, recording or other interesting use cases.
+
+If you have any questions or feedback, please reach out to us at our [Discord Server](https://4np.de/discord).
 
 ## ODIN Node JS compared to Web SDK
 

package/binding.gyp

@@ -1,61 +1,63 @@
 {
-    "targets": [{
-        "target_name": "odin",
-        "sources": [
-            "cppsrc/binding.cpp",
-            "cppsrc/odinbindings.cpp",
-            "cppsrc/odinclient.cpp",
-            "cppsrc/odinroom.cpp",
-            "cppsrc/odinmedia.cpp",
-            "cppsrc/utilities.cpp"
-        ],
-        'dependencies': [
-            "<!(node -p \"require('node-addon-api').gyp\")"
-        ],
-        'defines': [ 'NAPI_DISABLE_CPP_EXCEPTIONS' ],
-          'cflags!': [ '-fno-exceptions' ],
-          'cflags_cc!': [ '-fno-exceptions' ],
-          'conditions': [
-            ["OS=='linux'", {
-              'libraries': [
-                "<(module_root_dir)/libs/bin/linux/<(target_arch)/libodin_static.a"
-              ],
-              'include_dirs': [
-                "<!@(node -p \"require('node-addon-api').include\")",
-                "<(module_root_dir)/libs/include"
-              ],
-            }],
-            ["OS=='win'", {
-              "defines": [
-                "_HAS_EXCEPTIONS=1"
-              ],
-              "msvs_settings": {
-                "VCCLCompilerTool": {
-                  "ExceptionHandling": 1
-                },
-              },
-              'runtime_library': [
-                "<(module_root_dir)/libs/bin/windows/<(target_arch)/odin_static.lib"
-              ],
-              'include_dirs': [
-                "<!@(node -p \"require('node-addon-api').include\")",
-                "<(module_root_dir)/libs/include"
-              ],
-            }],
-            ["OS=='mac'", {
-              'xcode_settings': {
-                'GCC_ENABLE_CPP_EXCEPTIONS': 'YES',
-                'CLANG_CXX_LIBRARY': 'libc++',
-                'MACOSX_DEPLOYMENT_TARGET': '10.12',
-              },
-              'libraries': [
-                "<(module_root_dir)/libs/bin/macos/<(target_arch)/libodin_static.a"
-              ],
-              'include_dirs': [
-                "<!@(node -p \"require('node-addon-api').include\")",
-                "<(module_root_dir)/libs/include"
-              ],
-            }],
+  "targets": [
+    {
+      "target_name": "odin",
+      "sources": [
+        "cppsrc/binding.cpp",
+        "cppsrc/odinbindings.cpp",
+        "cppsrc/odinclient.cpp",
+        "cppsrc/odinroom.cpp",
+        "cppsrc/odinmedia.cpp",
+        "cppsrc/utilities.cpp"
+      ],
+      "include_dirs": [
+        "<!@(node -p \"require('node-addon-api').include\")",
+        "<(module_root_dir)/libs/include"
+      ],
+      "dependencies": [
+        "<!(node -p \"require('node-addon-api').gyp\")"
+      ],
+      "conditions": [
+        ["OS=='linux'", {
+          "libraries": [
+            "-L<(module_root_dir)/libs/bin/linux/<(target_arch)",
+            "-lodin_static"
           ]
-    }]
+        }],
+        ["OS=='mac'", {
+          "libraries": [
+            "-L<(module_root_dir)/libs/bin/macos/<(target_arch)",
+            "-lodin_static",
+          ]
+        }],
+        ["OS=='win'", {
+          "msvs_settings": {
+            "VCCLCompilerTool": {
+              "AdditionalOptions": [ "/MD" ],
+            },
+            "VCLinkerTool": {
+
+            },
+          },
+          "libraries": [
+            "<(module_root_dir)/libs/bin/windows/<(target_arch)/odin_static.lib",
+            "-lws2_32",
+            "-lbcrypt",
+            "-lucrt",
+            "-lvcruntime",
+            "-lwinmm",
+            "-lntdll"
+          ]
+        }]
+      ],
+      "defines": [ "NAPI_DISABLE_CPP_EXCEPTIONS" ],
+      "cflags!": [ "-fno-exceptions" ],
+      "cflags_cc!": [ "-fno-exceptions" ],
+      "xcode_settings": {
+        "GCC_ENABLE_CPP_EXCEPTIONS": "NO",
+        "CLANG_CXX_LIBRARY": "libc++",
+        "MACOSX_DEPLOYMENT_TARGET": "10.12",
+      },
+    }
+  ]
 }

package/cppsrc/odinclient.cpp

@@ -72,7 +72,12 @@ OdinClient::OdinClient(const Napi::CallbackInfo& info) : Napi::ObjectWrap<OdinCl
     printf("Odin NodeJS Addon: Initializing Odin runtime (%s) with sample rate %f and %d channels\n", ODIN_VERSION, _sampleRate, _numChannels);
 #endif
 
-    odin_startup_ex(ODIN_VERSION, _sampleRate, _numChannels == 1 ? OdinChannelLayout_Mono : OdinChannelLayout_Stereo);
+    // Create a OdinAudioStreamConfig struct to configure the audio stream
+    OdinAudioStreamConfig config;
+    config.sample_rate = _sampleRate;
+    config.channel_count = _numChannels;
+
+    odin_startup_ex(ODIN_VERSION, config);
 }
 
 /**
@@ -141,6 +146,8 @@ Napi::Value OdinClient::CreateRoom(const Napi::CallbackInfo &info) {
     if (!generator)
     {
         Napi::TypeError::New(env, "Failed to initialize token generator, invalid access key").ThrowAsJavaScriptException();
+        odin_token_generator_destroy(generator);
+        return env.Undefined();
     }
 
     /*
@@ -151,6 +158,8 @@ Napi::Value OdinClient::CreateRoom(const Napi::CallbackInfo &info) {
     if (odin_is_error(error))
     {
         Napi::TypeError::New(env, "Creating access token failed").ThrowAsJavaScriptException();
+        odin_token_generator_destroy(generator);
+        return env.Undefined();
     }
 
     /*

package/cppsrc/odinmedia.cpp

@@ -232,7 +232,7 @@ void OdinMedia::SendData(const Napi::CallbackInfo &info) {
     Napi::Float32Array array = info[0].As<Napi::Float32Array>();
 
 #ifdef DEBUG
-    printf("Received %d bytes of audio data\n", (int)array.ElementLength());
+    printf("Sent %d bytes of audio data\n", (int)array.ElementLength());
 #endif
 
     OdinReturnCode result = odin_audio_push_data(_mediaStreamHandle, array.Data(), array.ElementLength());

package/cppsrc/odinroom.cpp

@@ -331,7 +331,6 @@ Napi::Object OdinRoom::Init(Napi::Env env, Napi::Object exports) {
     Napi::Function func = DefineClass(env, "OdinRoom", {
         InstanceMethod<&OdinRoom::Join>("join", static_cast<napi_property_attributes>(napi_writable | napi_configurable)),
         InstanceMethod<&OdinRoom::UpdatePeerUserData>("updateOwnUserData", static_cast<napi_property_attributes>(napi_writable | napi_configurable)),
-        InstanceMethod<&OdinRoom::UpdateRoomUserData>("updateRoomUserData", static_cast<napi_property_attributes>(napi_writable | napi_configurable)),
         InstanceMethod<&OdinRoom::SendMessage>("sendMessage", static_cast<napi_property_attributes>(napi_writable | napi_configurable)),
         InstanceMethod<&OdinRoom::SetEventListener>("setEventListener", static_cast<napi_property_attributes>(napi_writable | napi_configurable)),
         InstanceMethod<&OdinRoom::AddEventListener>("addEventListener", static_cast<napi_property_attributes>(napi_writable | napi_configurable)),
@@ -381,7 +380,7 @@ void OdinRoom::Join(const Napi::CallbackInfo &info) {
 
     if (info.Length() > 1) {
         Napi::Uint8Array data = info[1].As<Napi::Uint8Array>();
-        OdinReturnCode error = odin_room_update_user_data(_roomHandle, OdinUserDataTarget_Peer, data.Data(), data.ByteLength());
+        OdinReturnCode error = odin_room_update_peer_user_data(_roomHandle, data.Data(), data.ByteLength());
         if (odin_is_error(error))
         {
             Napi::TypeError::New(env, "Setting initial room peer data failed").ThrowAsJavaScriptException();
@@ -475,7 +474,7 @@ void OdinRoom::UpdatePeerUserData(const Napi::CallbackInfo &info) {
 
     Napi::Uint8Array data = info[0].As<Napi::Uint8Array>();
 
-    OdinReturnCode error = odin_room_update_user_data(_roomHandle, OdinUserDataTarget_Peer, data.Data(), data.ByteLength());
+    OdinReturnCode error = odin_room_update_peer_user_data(_roomHandle, data.Data(), data.ByteLength());
 
     if (odin_is_error(error))
     {
@@ -483,28 +482,6 @@ void OdinRoom::UpdatePeerUserData(const Napi::CallbackInfo &info) {
     }
 }
 
-/**
- * Updates the room user data. Requires an array of bytes as a parameter.
- * @param info
- * @return
- */
-void OdinRoom::UpdateRoomUserData(const Napi::CallbackInfo &info) {
-    Napi::Env env = info.Env();
-
-    if (info.Length() != 1 || !info[0].IsTypedArray()) {
-        Napi::TypeError::New(env, "Data as byte array expected").ThrowAsJavaScriptException();
-    }
-
-    Napi::Uint8Array data = info[0].As<Napi::Uint8Array>();
-
-    OdinReturnCode error = odin_room_update_user_data(_roomHandle, OdinUserDataTarget_Room, data.Data(), data.ByteLength());
-
-    if (odin_is_error(error))
-    {
-        OdinUtilities::ThrowNapiException(env, error, "Failed to update room user data");
-    }
-}
-
 /**
  * Sends a message to the room. Requires an array of bytes as a parameter and optinally a list of peer ids to send to.
  * Please note: If the list is NULL the message will be sent to all peers in the room. If the list is not NULL the message
@@ -544,7 +521,7 @@ void OdinRoom::SendMessage(const Napi::CallbackInfo &info) {
 
     if (odin_is_error(error))
     {
-        OdinUtilities::ThrowNapiException(env, error, "Failed to update room user data");
+        OdinUtilities::ThrowNapiException(env, error, "Failed to send message");
     }
 }
 

package/cppsrc/odinroom.h

@@ -47,7 +47,6 @@ private:
     void Close(const Napi::CallbackInfo& info);
     void Join(const Napi::CallbackInfo& info);
     void UpdatePeerUserData(const Napi::CallbackInfo &info);
-    void UpdateRoomUserData(const Napi::CallbackInfo &info);
     void SendMessage(const Napi::CallbackInfo &info);
     void SetEventListener(const Napi::CallbackInfo &info);
     void AddEventListener(const Napi::CallbackInfo &info);

package/index.d.ts

@@ -2,4 +2,10 @@ export * from "./odin.client";
 export * from "./odin.room";
 export * from "./odin.media";
 
+/**
+ * Generates an access token for a room and user ID. You can use this to join a room with a custom access token.
+ * @param accessKey - The access key to use for this client. You can get one from https://developers.4players.io
+ * @param roomId - The ID of the room to create.
+ * @param userId - The ID of the user
+ */
 export declare function generateAccessToken(accessKey: string, roomId: string, userId: string): string;

package/libs/include/odin.h

@@ -10,23 +10,7 @@
 #include <stdint.h>
 #include <stdlib.h>
 
-#define ODIN_VERSION "1.4.0"
-
-#define Frame_SAMPLE_RATE 48000
-
-/**
- * Supported channel layouts in audio functions.
- */
-typedef enum OdinChannelLayout {
-    /**
-     * Samples are sequential
-     */
-    OdinChannelLayout_Mono,
-    /**
-     * Channels are interleaved
-     */
-    OdinChannelLayout_Stereo,
-} OdinChannelLayout;
+#define ODIN_VERSION "1.6.4"
 
 /**
  * Known types of a media stream.
@@ -134,25 +118,11 @@ typedef enum OdinTokenAudience {
 } OdinTokenAudience;
 
 /**
- * Supported targets for user data updates.
- */
-typedef enum OdinUserDataTarget {
-    /**
-     * Individual user data for your own peer
-     */
-    OdinUserDataTarget_Peer,
-    /**
-     * Global user data for the room
-     */
-    OdinUserDataTarget_Room,
-} OdinUserDataTarget;
-
-/**
- * A pointer to a local ODIN token generator used to generate signed room tokens based based on an
- * access key. Please note, that access keys are your the unique authentication keys to be used to
- * generate room tokens for accessing the ODIN server network. For your own security, we strongly
- * recommend that you _NEVER_ put an access key in your client code and generate room tokens on a
- * server.
+ * A pointer to a local ODIN token generator, employed for generating signed room tokens predicated
+ * on an access key. Be aware that access keys serve as your unique authentication keys, requisite
+ * for generating room tokens to access the ODIN server network. To ensure your security, it's
+ * strongly recommended that you _NEVER_ embed an access key within your client code, and instead
+ * generate room tokens on a server.
  */
 typedef struct OdinTokenGenerator OdinTokenGenerator;
 
@@ -164,6 +134,20 @@ typedef struct OdinTokenGenerator OdinTokenGenerator;
  */
 typedef uint32_t OdinReturnCode;
 
+/**
+ * Audio stream configuration.
+ */
+typedef struct OdinAudioStreamConfig {
+    /**
+     * The number of samples per second in hertz (between 8000 and 192000)
+     */
+    uint32_t sample_rate;
+    /**
+     * The number of channels for the new audio stream (between 1 and 2)
+     */
+    uint8_t channel_count;
+} OdinAudioStreamConfig;
+
 /**
  * Internal handle identifier for an ODIN room to interact with.
  */
@@ -491,20 +475,6 @@ typedef struct OdinApmConfig {
     bool gain_controller;
 } OdinApmConfig;
 
-/**
- * Audio stream configuration.
- */
-typedef struct OdinAudioStreamConfig {
-    /**
-     * The number of samples per second in hertz (between 8000 and 192000)
-     */
-    uint32_t sample_rate;
-    /**
-     * The number of channels for the new audio stream (between 1 and 2)
-     */
-    uint8_t channel_count;
-} OdinAudioStreamConfig;
-
 /**
  * Audio stream statistics.
  */
@@ -583,30 +553,30 @@ size_t odin_error_format(OdinReturnCode error, char *buf, size_t buf_len);
 bool odin_is_error(OdinReturnCode code);
 
 /**
- * Starts the internal ODIN client runtime using recommended settings for audio output and verifies
- * that the correct API header file is used. This is ref-counted so you need matching calls of startup
- * and shutdown in your application. A lot of the functions in the API require a running ODIN runtime.
- * With the only exception being the `access_key` and `token_generator` related functions.
+ * Initializes the internal ODIN client runtime with optimized settings for audio output, ensuring
+ * the correct API header file is employed. This operation is ref-counted, necessitating paired
+ * invocations of startup and shutdown within your application. The majority of the API functions
+ * hinge on an active ODIN runtime, with the sole exception of `access_key` and `token_generator`
+ * related functions.
  *
- * Note: Use `ODIN_VERSION` to pass the `version` argument.
+ * Note: Utilize `ODIN_VERSION` to supply the `version` argument.
  */
 bool odin_startup(const char *version);
 
 /**
- * Starts the internal ODIN client runtime and allows passing the sample rate and channel layout
- * for audio output. This is ref-counted so you need matching calls of startup and shutdown in your
- * application.
+ * Initializes the internal ODIN client runtime, permitting the specification of sample rate and
+ * channel layout for audio output. This operation is ref-counted, necessitating paired invocations
+ * of startup and shutdown within your application.
  *
- * Note: Make sure to use the same settings on consecutive calls of this function.
+ * Note: Ensure consistent settings are used on successive invocations of this function.
  */
-bool odin_startup_ex(const char *version,
-                     uint32_t output_sample_rate,
-                     enum OdinChannelLayout output_channel_layout);
+bool odin_startup_ex(const char *version, struct OdinAudioStreamConfig output_config);
 
 /**
- * Terminates the internal ODIN runtime. This function _should_ be called before shutting down
- * the application. After calling this function all `odin_*` methods will fail immediately.
- * (Given the internal ref-count reached zero. See `odin_startup` for more information)
+ * Shuts down the internal ODIN runtime. It is advisable to invoke this function prior to
+ * terminating the application. Post invocation, all `odin_*` methods will cease to function
+ * immediately, provided the internal ref-count has descended to zero. Refer to `odin_startup`
+ * for additional details.
  */
 void odin_shutdown(void);
 
@@ -639,13 +609,13 @@ OdinReturnCode odin_room_set_event_callback(OdinRoomHandle room,
                                             void *extra_data);
 
 /**
- * Sets the scaling used for all coordinates passed to `odin_room_update_position`. This allows
- * adapting to the individual needs of your game coordinate system if necessary. Only peers within
- * a unit circle with a radius of `1.0` are able to 'see' each other. When changing the position
- * of a peer, the position must be scaled such as that the maximum distance is one or less. The
- * scaling can be done either manually or by setting the multiplicative scale here.
+ * Sets the scaling factor for coordinates supplied to `odin_room_update_position`, facilitating
+ * adaptation to your game's unique coordinate system requirements. Peers are visible to each other
+ * only within a unit circle of radius `1.0`. When altering a peer's position, ensure the position
+ * is scaled such that the maximum distance remains one or less. This scaling can be performed
+ * manually or by specifying the multiplicative scale here.
  *
- * Note: Please make sure that all of your client apps use the same scaling.
+ * Note: It's crucial to maintain consistent scaling across all client applications.
  */
 OdinReturnCode odin_room_set_position_scale(OdinRoomHandle room, float scale);
 
@@ -679,28 +649,26 @@ OdinReturnCode odin_room_peer_id(OdinRoomHandle room, uint64_t *out_peer_id);
 OdinReturnCode odin_room_connection_stats(OdinRoomHandle room, struct OdinConnectionStats *stats);
 
 /**
- * Updates the custom user data for either your own peer or the specified `OdinRoomHandle` itself.
- * All user data is synced automatically, which allows storing of arbitrary information for each
- * individual peer and even globally for the room if needed.
+ * Updates the custom user data for your own peer. All user data is synced automatically, which
+ * allows storing of arbitrary information for each individual peer.
  *
  * Note: Use this before calling `odin_room_join` to set initial peer user data upon connect.
  */
-OdinReturnCode odin_room_update_user_data(OdinRoomHandle room,
-                                          enum OdinUserDataTarget target,
-                                          const uint8_t *user_data,
-                                          size_t user_data_length);
+OdinReturnCode odin_room_update_peer_user_data(OdinRoomHandle room,
+                                               const uint8_t *user_data,
+                                               size_t user_data_length);
 
 /**
- * Updates the two-dimensional position of your own peer in the given `OdinRoomHandle`. The server
- * will use the specified coordinates for each peer in the same room to apply automatic culling
- * based on unit circles with a radius of `1.0`. This is ideal for any scenario, where you want to
- * put a very large number of peers into the same room and make them only 'see' each other while
- * being in proximity. Additionally, you can use `odin_room_set_position_scale` to adjust the
- * distance multiplier for position updates if needed.
+ * Updates the three-dimensional position of the current peer within the specified `OdinRoomHandle`.
+ * The server utilizes the provided coordinates to perform automatic culling among peers in the same
+ * room, based on unit circles with a radius of `1.0`. This feature is particularly beneficial in
+ * scenarios involving a large number of peers within the same room, enabling peers to interact or
+ * 'see' each other only when in close proximity. To modify the distance sensitivity for position
+ * updates, use `odin_room_set_position_scale`.
  *
  * Note: Use this before calling `odin_room_join` to set the initial peer position upon connect.
  */
-OdinReturnCode odin_room_update_position(OdinRoomHandle room, float x, float y);
+OdinReturnCode odin_room_update_position(OdinRoomHandle room, float x, float y, float z);
 
 /**
  * Sends arbitrary data to a list of target peers over the ODIN server. If `NULL` is specified, the
@@ -725,12 +693,12 @@ OdinReturnCode odin_room_add_media(OdinRoomHandle room, OdinMediaStreamHandle me
 OdinReturnCode odin_room_configure_apm(OdinRoomHandle room, struct OdinApmConfig config);
 
 /**
- * Creates a new audio stream, which can be added to a room and send data over it.
+ * Creates a new audio input stream, which can be added to a room and send data over it.
  */
 OdinMediaStreamHandle odin_audio_stream_create(struct OdinAudioStreamConfig config);
 
 /**
- * Creates a new video stream, which can be added to a room and send data over it.
+ * Creates a new video input stream, which can be added to a room and send data over it.
  *
  * Note: Video streams are not supported yet.
  */
@@ -760,21 +728,45 @@ OdinReturnCode odin_media_stream_peer_id(OdinMediaStreamHandle stream, uint64_t
  */
 enum OdinMediaStreamType odin_media_stream_type(OdinMediaStreamHandle stream);
 
+/**
+ * Instructs the server to pause the specified `OdinMediaStreamHandle`, 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.
+ */
+OdinReturnCode odin_media_stream_pause(OdinMediaStreamHandle stream);
+
+/**
+ * Instructs the server to resume the specified output `OdinMediaStreamHandle`, re-initiating the
+ * reception of data. This operation essentially communicates a server-side unmute request from the
+ * client, indicating a desire to restart packet reception for this media stream.
+ */
+OdinReturnCode odin_media_stream_resume(OdinMediaStreamHandle stream);
+
 /**
  * Sends data to the audio stream. The data has to be interleaved [-1, 1] float data.
  */
 OdinReturnCode odin_audio_push_data(OdinMediaStreamHandle stream, const float *buf, size_t buf_len);
 
 /**
- * Reads audio data from the specified `OdinMediaStreamHandle`. This will return audio data in
- * 48kHz interleaved.
- *
- * Note: `out_channel_layout` is reserved for future use.
+ * Reads audio data from the specified `OdinMediaStreamHandle`. This will return audio data in the
+ * format specified when calling `odin_startup_ex` or 48 kHz interleaved by default.
  */
 OdinReturnCode odin_audio_read_data(OdinMediaStreamHandle stream,
                                     float *out_buffer,
                                     size_t out_buffer_len);
 
+/**
+ * Returns the number of samples available in the audio buffer of an output `OdinMediaStreamHandle`.
+ */
+OdinReturnCode odin_audio_data_len(OdinMediaStreamHandle stream);
+
+/**
+ * Resets the specified `OdinMediaStreamHandle` to its initial state, restoring it to its default
+ * configuration. This operation resets the internal Opus encoder/decoder, ensuring a clean state.
+ * Additionally, it clears internal buffers, providing a fresh start.
+ */
+OdinReturnCode odin_audio_reset(OdinMediaStreamHandle stream);
+
 /**
  * Retrieves statistics for the specified `OdinMediaStreamHandle`.
  *
@@ -784,9 +776,9 @@ OdinReturnCode odin_audio_stats(OdinMediaStreamHandle stream, struct OdinAudioSt
 
 /**
  * Reads up to `out_buffer_len` samples from the given streams and mixes them into the `out_buffer`.
- * All audio streams will be read based on a 48khz sample rate so make sure to allocate the buffer
- * accordingly. After the call the `out_buffer_len` will contain the amount of samples that have
- * actually been read and mixed into `out_buffer`.
+ * All audio streams will be read based on the sample rate you chose when initializing the ODIN runtime
+ * so make sure to allocate the buffer accordingly. After the call the `out_buffer_len` will contain
+ * the amount of samples that have actually been read and mixed into `out_buffer`.
  *
  * If enabled this will also apply any audio processing to the output stream and feed back required
  * data to the internal audio processing pipeline which requires a final mix.
@@ -803,6 +795,17 @@ OdinReturnCode odin_audio_mix_streams(OdinRoomHandle room,
  */
 OdinReturnCode odin_audio_process_reverse(OdinRoomHandle room, float *buffer, size_t buffer_len);
 
+/**
+ * Sets the delay estimate for the reverse stream used in the ODIN echo cancellation. This function
+ * is important in scenarios where the audio output and the audio input are not synchronized. An
+ * accurate delay value ensures that the echo canceller can correctly align the two audio streams,
+ * resulting in effective echo cancellation.
+ *
+ * Improper delay values may lead to poor echo cancellation and thus degrade the quality of the
+ * audio communication.
+ */
+OdinReturnCode odin_audio_set_stream_delay(OdinRoomHandle room, uint64_t delay_ms);
+
 /**
  * Creates a new ODIN resampler instance. This is intended for situations where your audio pipeline
  * doesn't support 48 kHz.
@@ -834,28 +837,29 @@ OdinReturnCode odin_resampler_process(OdinResamplerHandle resampler,
 OdinReturnCode odin_resampler_destroy(OdinResamplerHandle resampler);
 
 /**
- * Creates a new access key required to access the ODIN network. An access key is a 44 character
- * long Base64-String, which consists of a version, random bytes and a checksum.
+ * Creates a new access key crucial for signing tokens, facilitating access to an ODIN server. An
+ * access key is a 44-character long Base64 String, embodying a version identifier, random bytes,
+ * and a checksum.
  */
 OdinReturnCode odin_access_key_generate(char *buf, size_t buf_len);
 
 /**
- * Retrieves the key ID from a specified access key. The key ID is included in room tokens,
- * making it possible to identify which public key must be used for verification.
+ * Extracts the key ID from a specified access key. The key ID is embedded in room tokens, enabling
+ * the identification of the corresponding public key required for verification.
  */
 OdinReturnCode odin_access_key_id(const char *access_key, char *out_key_id, size_t out_key_id_len);
 
 /**
- * Retrieves the public key from a specified access key. The public key is based on the Ed25519
- * curve and must be submitted to _4Players_ so that a generated room token can be verified.
+ * Extracts the public key from a specified access key. The public key, derived from the Ed25519
+ * curve, must be shared with _4Players_ to enable verification of a generated room token.
  */
 OdinReturnCode odin_access_key_public_key(const char *access_key,
                                           char *out_public_key,
                                           size_t out_public_key_len);
 
 /**
- * Retrieves the secret key from a specified access key. The secret key is based on the Ed25519
- * curve and used to sign a generated room token to access the ODIN network.
+ * Extracts the private key from a specified access key. The private key, rooted in the Ed25519
+ * curve, is utilized to sign a generated room token for accessing the ODIN network.
  */
 OdinReturnCode odin_access_key_secret_key(const char *access_key,
                                           char *out_secret_key,

package/odin.client.d.ts

@@ -7,16 +7,16 @@ import {OdinRoom} from "./odin.room";
 export declare class OdinClient {
     /**
      * Creates a new instance of a client with an access key.
-     * @param accessKey {string} The access key to use for this client. You can get one from https://developers.4players.io
-     * @param sampleRate {number} The sample rate of the audio stream (between 8000 and 48000)
-     * @param channelCount {number} The number of channels of the audio stream (1 or 2)
+     * @param accessKey - The access key to use for this client. You can get one from https://developers.4players.io
+     * @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)
      */
     constructor(accessKey: string, sampleRate?: number, channelCount?: number);
 
     /**
      * Creates a new local room instance with the given ID and user ID. Use join to connect to that room.
-     * @param roomId {string} The ID of the room to create.
-     * @param userId {string} The ID of the user to create the room for.
+     * @param roomId - The ID of the room to create.
+     * @param userId - The ID of the user to create the room for.
      */
     createRoom(roomId: string, userId: string): OdinRoom;
 }

package/odin.media.d.ts

@@ -1,4 +1,4 @@
-import {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.
@@ -7,11 +7,12 @@ import {OdinRoom} from "./odin.room";
 export declare class OdinMedia {
     /**
      * Creates a new instance of a media object. Don't create OdinMedia directly, use `createAudioStream` from OdinRoom instead.
-     * @param room {OdinRoom} The room to add the media to.
-     * @param sampleRate {number} The sample rate of the audio stream (between 8000 and 48000)
-     * @param channelCount {number} The number of channels of the audio stream (1 or 2)
+     * @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)
+     * @param options - Optional configuration options for Odin Audio Processing Module (APM).
      */
-    constructor(room: OdinRoom, sampleRate: number, channelCount: number);
+    constructor(room: OdinRoom, sampleRate: number, channelCount: number, options?: OdinAPMSettings);
 
     /**
      * Closes the local audio stream and removed the media from the room
@@ -22,12 +23,13 @@ export declare class OdinMedia {
      * 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
+     * @param data - A 32-bit float array containing the audio data.
      */
     sendAudioData(data: Float32Array): void;
 
     /**
      * Gets the ID of the media.
+     * @returns The ID of the media.
      */
     get id(): string;
 }

package/odin.room.d.ts

@@ -1,5 +1,8 @@
 import {OdinMedia} from "./odin.media";
 
+/**
+ * Defines available Odin events
+ */
 declare interface OdinEvents {
     /**
      * Fired when the local user connected to the room (successfully joined).
@@ -399,55 +402,49 @@ export declare interface OdinAPMSettings {
 export declare class OdinRoom {
     /**
      * Creates a new instance of a room with a token. Use OdinClient if you don't want to manage tokens yourself.
-     * @param token {string} The token to use for this room.
+     * @param token - The token to use for this room.
      */
     constructor(token: string);
 
     /**
      * Joins the room with the given gateway URL and optional user data.
-     * @param gatewayUrl {string} The gateway URL to connect to. Use gateway.odin.4players.io if you are unsure.
-     * @param userData {Uint8Array} The user data to send to the room. This can be used to identify the user.
+     * @param gatewayUrl - The gateway URL to connect to. Use gateway.odin.4players.io if you are unsure.
+     * @param userData - The user data to send to the room. This can be used to identify the user.
      */
     join(gatewayUrl: string, userData?: Uint8Array): void;
 
     /**
      * Sends a message to the room.
-     * @param message {Uint8Array} The message to send as a byte array.
-     * @param peerIdList {number[]} The list of peer IDs to send the message to. If this is undefined, the message will be sent to all peers. If the list is defined and empty an error will be thrown.
+     * @param message - The message to send as a byte array.
+     * @param peerIdList - The list of peer IDs to send the message to. If this is undefined, the message will be sent to all peers. If the list is defined and empty an error will be thrown.
      */
     sendMessage(message: Uint8Array, peerIdList?: number[]): void;
 
     /**
      * Adds an event listener to the room for specific events.
-     * @param event {Event} The event to listen for (see keys of OdinEvents for possible values)
-     * @param callback {(data: any) => void} The callback to call when the event is fired.
+     * @param eventName - The event to listen for (see keys of OdinEvents for possible values)
+     * @param handler - The callback to call when the event is fired.
      */
     addEventListener<Event extends keyof OdinEvents>(eventName: Event, handler: OdinEvents[Event]): void;
 
     /**
      * Removes an event listener from the room for specific events.
-     * @param event {Event} The event to remove the listener from (see keys of OdinEvents for possible values)
+     * @param eventName - The event to remove the listener from (see keys of OdinEvents for possible values)
      */
     removeEventListener<Event extends keyof OdinEvents>(eventName: Event): void;
 
     /**
      * Sets a global event listener that received all events, this can be helpful for debugging. Please use addEventListener instead for production code.
-     * @param callback {(data: any) => void} The callback to call when the event is fired.
+     * @param callback - The callback to call when the event is fired.
      */
     setEventListener(callback: (data: OdinEventPayload) => void): void;
 
     /**
      * Updates the peer user data of the local peer
-     * @param userData {Uint8Array} The new user data to set.
+     * @param userData - The new user data to set.
      */
     updateOwnUserData(userData: Uint8Array): void;
 
-    /**
-     * Updates the room user data (for all peers)
-     * @param userData {Uint8Array} The new user data to set.
-     */
-    updateRoomUserData(userData: Uint8Array): void;
-
     /**
      * Closes the room and disconnects from the server.
      */
@@ -466,8 +463,9 @@ export declare class OdinRoom {
     /**
      * Creates a local audio stream and adds it to the room. An OdinMedia object will be returned that allows you to send
      * audio data.
-     * @param sampleRate {number} The sample rate of the audio stream. Can be between 8000 and 48000.
-     * @param channels {number} The number of channels of the audio stream. Can be 1 or 2.
+     * @param sampleRate - The sample rate of the audio stream. Can be between 8000 and 48000.
+     * @param channels - The number of channels of the audio stream. Can be 1 or 2.
+     * @returns The OdinMedia object that allows you to send audio data.
      */
     createAudioStream(sampleRate: number, channels: number, apmSettings?: OdinAPMSettings): OdinMedia;
 }

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@4players/odin-nodejs",
-  "version": "0.7.3",
-  "description": "",
+  "version": "0.8.0",
+  "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": {
@@ -32,7 +32,8 @@
   },
   "devDependencies": {
     "node-gyp": "^9.3.1",
-    "prebuildify": "^5.0.1"
+    "prebuildify": "^5.0.1",
+    "typedoc": "^0.23.28"
   },
   "engines": {
     "node": ">=18"

package/tests/sending-audio/index.js

@@ -21,7 +21,7 @@ const userData = {
     version: "0.1"
 }
 const data = new TextEncoder().encode(JSON.stringify(userData));
-const odinClient = new OdinClient(accessKey, 44100, 1);
+const odinClient = new OdinClient(accessKey, 48000, 2);
 const room = odinClient.createRoom(roomName, userName);
 
 // Join the room
@@ -30,9 +30,7 @@ room.join("gateway.odin.4players.io", data);
 // Send a message to the room
 const message = {
     kind: 'message',
-    payload: {
-        text: 'Hello, I am a music bot and will stream some music to you.'
-    }
+    payload: 'Hello, I am a music bot and will stream some music to you.'
 }
 room.sendMessage(new TextEncoder().encode(JSON.stringify(message)));
 
@@ -41,29 +39,48 @@ const sendMusic = async (media) => {
     // Prepare our MP3 decoder and load the sample file
     const audioBuffer = await decode(fs.readFileSync('./santa.mp3'));
 
-    // Print our some info about the audio file
-    console.log(audioBuffer);
-
     // Create a stream that will match the settings of the file
-    const audioBufferStream = new AudioBufferStream({channels: 1, sampleRate: 44100, float: true, bitDepth: 32});
+    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
+    });
 
-    // Whenever the stream has data, send it to the media stream
+    // Create a queue to store the chunks of audio data
+    const queue = [];
+
+    // Whenever the stream has data, add it to the queue
     audioBufferStream.on('data', (data) => {
-        const floats = new Float32Array(new Uint8Array(data).buffer)
-        media.sendAudioData(floats);
+        const floats = new Float32Array(new Uint8Array(data).buffer);
+        queue.push(floats);
     });
 
+    // 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");
+        }
+    }, 20);  // Send a chunk every 20ms
+
     audioBufferStream.write(audioBuffer);
 }
 
 // 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(44100, 1);
+const media = room.createAudioStream(48000, 2);
 console.log(media);
 console.log("MEDIA-ID:", media.id);
 
 // Start the stream and send the music to ODIN
 sendMusic(media).then(() => {
-    console.log("Finished sending song");
+    console.log("Started sending audio");
 });
 
 // Wait until the user presses a key to stop