@4players/odin-nodejs 0.7.4 → 0.9.0

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,8 @@ 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::UpdatePosition>("updatePosition", static_cast<napi_property_attributes>(napi_writable | napi_configurable)),
+        InstanceMethod<&OdinRoom::SetPositionScale>("setPositionScale", 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)),
@@ -366,6 +367,50 @@ Napi::Object OdinRoom::Init(Napi::Env env, Napi::Object exports) {
     return exports;
 }
 
+/**
+ * Updates the position of this room. Requires x, y and z coordinates as parameters.
+ * @param info Napi::CallbackInfo
+ */
+void OdinRoom::UpdatePosition(const Napi::CallbackInfo &info)
+{
+    Napi::Env env = info.Env();
+
+    if (info.Length() != 3 || !info[0].IsNumber() || !info[1].IsNumber() || !info[2].IsNumber()) {
+        Napi::TypeError::New(env, "Provide x, y and z coordinates as numbers").ThrowAsJavaScriptException();
+    }
+
+    float x = info[0].ToNumber();
+    float y = info[1].ToNumber();
+    float z = info[2].ToNumber();
+
+    OdinReturnCode error = odin_room_update_position(_roomHandle, x, y, z);
+    if (odin_is_error(error))
+    {
+        OdinUtilities::ThrowNapiException(env, error, "Failed to update position");
+    }
+}
+
+/**
+ * Sets the position scale for this room. Requires a scale as a parameter.
+ * @param info Napi::CallbackInfo
+ */
+void OdinRoom::SetPositionScale(const Napi::CallbackInfo &info)
+{
+    Napi::Env env = info.Env();
+
+    if (info.Length() != 1 || !info[0].IsNumber()) {
+        Napi::TypeError::New(env, "Provide scale as number").ThrowAsJavaScriptException();
+    }
+
+    float scale = info[0].ToNumber();
+
+    OdinReturnCode error = odin_room_set_position_scale(_roomHandle, scale);
+    if (odin_is_error(error))
+    {
+        OdinUtilities::ThrowNapiException(env, error, "Failed to set position scale");
+    }
+}
+
 /**
  * Joins the Odin room. Requires a gateway URL as a parameter and optionally initial peer data.
  * @param info Napi::CallbackInfo
@@ -381,7 +426,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 +520,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 +528,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 +567,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);
@@ -57,6 +56,8 @@ private:
     EventData* PrepareEventData(OdinEvent* event);
     static uint16_t GetMediaIdFromHandle(OdinMediaStreamHandle handle);
     void HandleAudioData();
+    void UpdatePosition(const Napi::CallbackInfo &info);
+    void SetPositionScale(const Napi::CallbackInfo &info);
 
     Napi::Value CreateAudioStream(const Napi::CallbackInfo &info);
 };

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.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.
@@ -10,8 +10,9 @@ export declare class OdinMedia {
      * @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

package/odin.room.d.ts

@@ -446,10 +446,32 @@ export declare class OdinRoom {
     updateOwnUserData(userData: Uint8Array): void;
 
     /**
-     * Updates the room user data (for all peers)
-     * @param userData - The new user data to set.
-     */
-    updateRoomUserData(userData: Uint8Array): void;
+     * Updates the three-dimensional position of the current peer in this room.
+     * 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 `setPositionScale`.
+     *
+     * Note: Use this before calling `join` to set the initial peer position upon connect.
+     *
+     * @param x - The new x position of the peer.
+     * @param y - The new y position of the peer.
+     * @param z - The new z position of the peer.
+     */
+    updatePosition(x: number, y: number, z: number): void;
+
+    /**
+     * Sets the scaling factor for coordinates supplied to `updatePosition`, 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: It's crucial to maintain consistent scaling across all client applications.
+     * @param scale - The new scaling factor to use.
+     */
+    setPositionScale(scale: number);
 
     /**
      * Closes the room and disconnects from the server.

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@4players/odin-nodejs",
-  "version": "0.7.4",
-  "description": "",
+  "version": "0.9.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": {

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