@4players/odin-nodejs 0.10.3 → 0.11.1

package/libs/include/odin.h

@@ -10,373 +10,327 @@
 #include <stdint.h>
 #include <stdlib.h>
 
-#define ODIN_VERSION "1.6.4"
+#define ODIN_VERSION "1.8.2"
 
 /**
- * Known types of a media stream.
- *
- * Note: Video streams are not supported yet.
+ * Defines known error codes returned by ODIN functions.
  */
-typedef enum OdinMediaStreamType {
+typedef enum OdinError {
     /**
-     * Media stream is of type audio
+     * Operation completed successfully
      */
-    OdinMediaStreamType_Audio,
+    ODIN_ERROR_SUCCESS = 0,
     /**
-     * Media stream is of type video
+     * No data available
      */
-    OdinMediaStreamType_Video,
+    ODIN_ERROR_NO_DATA = 1,
     /**
-     * Media stream is invalid
+     * The runtime initialization failed
      */
-    OdinMediaStreamType_Invalid,
-} OdinMediaStreamType;
-
-/**
- * Valid levels for aggressiveness of the noise suppression. A higher level will reduce the noise
- * level at the expense of a higher speech distortion.
- */
-typedef enum OdinNoiseSuppressionLevel {
+    ODIN_ERROR_INITIALIZATION_FAILED = -1,
     /**
-     * Noise suppression is disabled
+     * The specified API version is not supported
      */
-    OdinNoiseSuppressionLevel_None,
+    ODIN_ERROR_UNSUPPORTED_VERSION = -2,
     /**
-     * Use low suppression (6 dB)
+     * The object is in an unexpected state
      */
-    OdinNoiseSuppressionLevel_Low,
+    ODIN_ERROR_UNEXPECTED_STATE = -3,
     /**
-     * Use moderate suppression (12 dB)
+     * The object is closed
      */
-    OdinNoiseSuppressionLevel_Moderate,
+    ODIN_ERROR_CLOSED = -4,
     /**
-     * Use high suppression (18 dB)
+     * A mandatory argument is null
      */
-    OdinNoiseSuppressionLevel_High,
+    ODIN_ERROR_ARGUMENT_NULL = -11,
     /**
-     * Use very high suppression (21 dB)
+     * A provided argument is too small
      */
-    OdinNoiseSuppressionLevel_VeryHigh,
-} OdinNoiseSuppressionLevel;
-
-/**
- * All valid connection states for an ODIN room.
- */
-typedef enum OdinRoomConnectionState {
+    ODIN_ERROR_ARGUMENT_TOO_SMALL = -12,
     /**
-     * Connection is being established
+     * A provided argument is out of the expected bounds
      */
-    OdinRoomConnectionState_Connecting,
+    ODIN_ERROR_ARGUMENT_OUT_OF_BOUNDS = -13,
     /**
-     * Connection is established
+     * A provided string argument is not valid UTF-8
      */
-    OdinRoomConnectionState_Connected,
-    /**
-     * Connection is being closed
-     */
-    OdinRoomConnectionState_Disconnecting,
-    /**
-     * Connection is closed
-     */
-    OdinRoomConnectionState_Disconnected,
-} OdinRoomConnectionState;
-
-/**
- * Possible reasons for connection state changes of an ODIN room.
- */
-typedef enum OdinRoomConnectionStateChangeReason {
-    /**
-     * Connection state change was initiated by the user
-     */
-    OdinRoomConnectionStateChangeReason_ClientRequested,
-    /**
-     * Connection state change was initiated by the server (e.g. peer was kicked)
-     */
-    OdinRoomConnectionStateChangeReason_ServerRequested,
-    /**
-     * Connection state change was caused by a timeout
-     */
-    OdinRoomConnectionStateChangeReason_ConnectionLost,
-} OdinRoomConnectionStateChangeReason;
-
-/**
- * Valid audiences for ODIN room tokens.
- */
-typedef enum OdinTokenAudience {
+    ODIN_ERROR_ARGUMENT_INVALID_STRING = -14,
     /**
-     * JWT has no audience
+     * A provided handle argument is invalid
      */
-    OdinTokenAudience_None,
+    ODIN_ERROR_ARGUMENT_INVALID_HANDLE = -15,
     /**
-     * JWT is accepted the ODIN gateway
+     * A provided identifier argument is invalid
      */
-    OdinTokenAudience_Gateway,
+    ODIN_ERROR_ARGUMENT_INVALID_ID = -16,
     /**
-     * JWT is accepted by the ODIN server
+     * The provided version is invalid
      */
-    OdinTokenAudience_Sfu,
-} OdinTokenAudience;
-
-/**
- * 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;
-
-/**
- * A numeric code returned by ODIN function calls. Use `odin_is_error` to determine whether the
- * code represents an error or an actual result value.
- *
- * Note: Use `odin_error_format` to get a human readable string to represent error codes.
- */
-typedef uint32_t OdinReturnCode;
-
-/**
- * Audio stream configuration.
- */
-typedef struct OdinAudioStreamConfig {
+    ODIN_ERROR_INVALID_VERSION = -21,
     /**
-     * The number of samples per second in hertz (between 8000 and 192000)
+     * The provided access key is invalid
      */
-    uint32_t sample_rate;
+    ODIN_ERROR_INVALID_ACCESS_KEY = -22,
     /**
-     * The number of channels for the new audio stream (between 1 and 2)
+     * The provided gateway/server address is invalid
      */
-    uint8_t channel_count;
-} OdinAudioStreamConfig;
-
-/**
- * Internal handle identifier for an ODIN room to interact with.
- */
-typedef size_t OdinRoomHandle;
-
-/**
- * Internal handle identifier for an ODIN audio/video stream used to send/receive data.
- */
-typedef size_t OdinMediaStreamHandle;
-
-/**
- * All the different events emitted from an ODIN room.
- */
-typedef enum OdinEventTag {
+    ODIN_ERROR_INVALID_URI = -23,
     /**
-     * Emitted after joining once initial room information was processed
+     * The provided token is invalid
      */
-    OdinEvent_Joined,
+    ODIN_ERROR_INVALID_TOKEN = -24,
     /**
-     * Emitted when other peers joined the room
+     * The provided effect is not compatible to the expected effect type
      */
-    OdinEvent_PeerJoined,
+    ODIN_ERROR_INVALID_EFFECT = -25,
     /**
-     * Emitted when other peers left the room
+     * The provided MessagePack encoded bytes are invalid
      */
-    OdinEvent_PeerLeft,
+    ODIN_ERROR_INVALID_MSG_PACK = -26,
     /**
-     * Emitted when other peers updated their user data
+     * The provided JSON string invalid
      */
-    OdinEvent_PeerUserDataChanged,
+    ODIN_ERROR_INVALID_JSON = -27,
     /**
-     * Emitted when other peers started a media stream
+     * The provided token does not grant access to the requested room
      */
-    OdinEvent_MediaAdded,
+    ODIN_ERROR_TOKEN_ROOM_REJECTED = -31,
     /**
-     * Emitted when other peers stopped a media stream
+     * The token is missing a customer identifier
      */
-    OdinEvent_MediaRemoved,
+    ODIN_ERROR_TOKEN_MISSING_CUSTOMER = -32,
     /**
-     * Emitted whenever data is sent/received over any known media
+     * The audio processing module reported an error
      */
-    OdinEvent_MediaActiveStateChanged,
+    ODIN_ERROR_AUDIO_PROCESSING_FAILED = -41,
     /**
-     * Emitted when other peers changed the global user data of the room itself
+     * The setup process of the Opus audio codec reported an error
      */
-    OdinEvent_RoomUserDataChanged,
+    ODIN_ERROR_AUDIO_CODEC_CREATION_FAILED = -42,
     /**
-     * Emitted when the internal room connection state of the ODIN client changed
+     * Encoding of an audio packet failed
      */
-    OdinEvent_RoomConnectionStateChanged,
+    ODIN_ERROR_AUDIO_ENCODING_FAILED = -43,
     /**
-     * Emitted when others peers sent arbitrary data
+     * Decoding of an audio packet failed
      */
-    OdinEvent_MessageReceived,
-} OdinEventTag;
+    ODIN_ERROR_AUDIO_DECODING_FAILED = -44,
+} OdinError;
 
-typedef struct OdinEvent_JoinedData {
-    /**
-     * Name of the joined room (null-terminated)
-     */
-    const char *room_id;
-    /**
-     * Length of the room name
-     */
-    size_t room_id_len;
+/**
+ * Audio-related events emitted by encoders and decoders. These values act as bitflags and
+ * can be combined to filter or report multiple events.
+ */
+typedef enum OdinAudioEvents {
     /**
-     * Byte array with arbitrary user data of the room
+     * Triggered when the silence state changes.
      */
-    const uint8_t *room_user_data;
+    ODIN_AUDIO_EVENTS_IS_SILENT_CHANGED = 1,
     /**
-     * Length of the room user data array
+     * Enables all available audio events.
      */
-    size_t room_user_data_len;
+    ODIN_AUDIO_EVENTS_ALL = -1,
+} OdinAudioEvents;
+
+/**
+ * Valid levels for aggressiveness of the noise suppression. A higher level will reduce the noise
+ * level at the expense of a higher speech distortion.
+ */
+typedef enum OdinNoiseSuppressionLevel {
     /**
-     * Identifier of the customer the room is assigned to (nul-terminated)
+     * Noise suppression is disabled
      */
-    const char *customer;
+    ODIN_NOISE_SUPPRESSION_LEVEL_NONE,
     /**
-     * Length of the customer identifier
+     * Use low suppression (6 dB)
      */
-    size_t customer_len;
+    ODIN_NOISE_SUPPRESSION_LEVEL_LOW,
     /**
-     * Own peer ID assigned by the server
+     * Use moderate suppression (12 dB)
      */
-    uint64_t own_peer_id;
+    ODIN_NOISE_SUPPRESSION_LEVEL_MODERATE,
     /**
-     * Own user identifier of the peer specified during authentication (null-terminated)
+     * Use high suppression (18 dB)
      */
-    const char *own_user_id;
+    ODIN_NOISE_SUPPRESSION_LEVEL_HIGH,
     /**
-     * Length of the own user identifier
+     * Use very high suppression (21 dB)
      */
-    size_t own_user_id_len;
-} OdinEvent_JoinedData;
+    ODIN_NOISE_SUPPRESSION_LEVEL_VERY_HIGH,
+} OdinNoiseSuppressionLevel;
 
-typedef struct OdinEvent_PeerJoinedData {
-    /**
-     * ID of the peer
-     */
-    uint64_t peer_id;
-    /**
-     * Byte array with arbitrary user data of the peer
-     */
-    const uint8_t *peer_user_data;
+/**
+ * Available versions of the automatic gain controller (AGC) to be used. This adjusts the audio
+ * signal's amplitude to reach a target level, helping to maintain a consistent output.
+ */
+typedef enum OdinGainControllerVersion {
     /**
-     * Length of the room user data array
+     * AGC is disabled; the signal is not modified
      */
-    size_t peer_user_data_len;
+    ODIN_GAIN_CONTROLLER_VERSION_NONE,
     /**
-     * User identifier of the peer specified during authentication (null-terminated)
+     * Legacy AGC with adaptive digital gain control and a limiter
      */
-    const char *user_id;
+    ODIN_GAIN_CONTROLLER_VERSION_V1,
     /**
-     * Length of the user identifier
+     * Enhanced AGC with improved digital processing and an input volume controller
      */
-    size_t user_id_len;
-} OdinEvent_PeerJoinedData;
+    ODIN_GAIN_CONTROLLER_VERSION_V2,
+} OdinGainControllerVersion;
 
-typedef struct OdinEvent_PeerLeftData {
-    /**
-     * ID of the peer
-     */
-    uint64_t peer_id;
-} OdinEvent_PeerLeftData;
-
-typedef struct OdinEvent_PeerUserDataChangedData {
+/**
+ * Defines the types of audio pipeline effects available.
+ */
+typedef enum OdinEffectType {
     /**
-     * ID of the peer
+     * Voice Activity Detection (VAD) effect for detecting active speech segments in an audio stream
      */
-    uint64_t peer_id;
+    ODIN_EFFECT_TYPE_VAD,
     /**
-     * Byte array with arbitrary user data of the peer
+     * Audio Processing Module (APM) effect to apply audio enhancements like noise suppression
      */
-    const uint8_t *peer_user_data;
+    ODIN_EFFECT_TYPE_APM,
     /**
-     * Length of the room user data array
+     * Custom user-defined audio processing effect that can be integrated into the audio pipeline
      */
-    size_t peer_user_data_len;
-} OdinEvent_PeerUserDataChangedData;
+    ODIN_EFFECT_TYPE_CUSTOM,
+} OdinEffectType;
 
-typedef struct OdinEvent_MediaAddedData {
-    /**
-     * ID of the peer this media belongs to
-     */
-    uint64_t peer_id;
-    /**
-     * Handle identifier of the new audio/video stream
-     */
-    OdinMediaStreamHandle media_handle;
-} OdinEvent_MediaAddedData;
+/**
+ * An opaque type representing an ODIN connection pool, which encapsulates the internal management
+ * of all connections used by the clients. It is responsible for creating, retrieving and managing
+ * communication channels, handling room join requests and processing associated authorization and
+ * connection state changes. The connection pool ensures thread-safe access and coordinated shutdown
+ * of active connections. Additionally, it allows joining multiple rooms through the same connection
+ * by performing transparent connection sharing if possible.
+ */
+typedef struct OdinConnectionPool OdinConnectionPool;
 
-typedef struct OdinEvent_MediaRemovedData {
-    /**
-     * ID of the peer this media belongs to
-     */
-    uint64_t peer_id;
-    /**
-     * Handle identifier of the audio/video stream
-     */
-    OdinMediaStreamHandle media_handle;
-} OdinEvent_MediaRemovedData;
+/**
+ * Represents a decoder for media streams from remote voice chat clients, which encapsulates all
+ * the components required to process incoming audio streams. It includes an egress resampler for
+ * sample rate conversion, an Opus decoder for decompressing audio data, and a customizable audio
+ * pipeline that enables the application of effects to modify the raw audio samples.
+ *
+ * Encoder operations are thread-safe and the same encoder handle may be accessed concurrently
+ * from multiple threads.
+ */
+typedef struct OdinDecoder OdinDecoder;
 
-typedef struct OdinEvent_MediaActiveStateChangedData {
-    /**
-     * ID of the peer this media belongs to
-     */
-    uint64_t peer_id;
-    /**
-     * Handle identifier of the audio/video stream
-     */
-    OdinMediaStreamHandle media_handle;
-    /**
-     * Indicator for whether or not the media is sending/receiving data
-     */
-    bool active;
-} OdinEvent_MediaActiveStateChangedData;
+/**
+ * Represents an encoder for local media streams, which encapsulates the components required to
+ * process outgoing audio streams captured from local sources (e.g. a microphone). It includes
+ * an ingress resampler for sample rate conversion, an Opus encoder for compressing the audio
+ * data and a customizable audio pipeline that allows the application of effects to modify the
+ * raw audio samples before transmission.
+ *
+ * Encoder operations are thread-safe and the same encoder handle may be accessed concurrently
+ * from multiple threads.
+ */
+typedef struct OdinEncoder OdinEncoder;
 
-typedef struct OdinEvent_RoomUserDataChangedData {
-    /**
-     * Byte array with arbitrary user data of the room
-     */
-    const uint8_t *room_user_data;
-    /**
-     * Length of the room user data array
-     */
-    size_t room_user_data_len;
-} OdinEvent_RoomUserDataChangedData;
+/**
+ * A highly dynamic audio processing chain that manages a thread-safe collection of filters like
+ * voice activity detection, echo cancellation, noise suppression and even custom effects. This
+ * allows sequential processing and real-time modification of audio streams through operations
+ * like insertion, removal, reordering and configuration updates.
+ */
+typedef struct OdinPipeline OdinPipeline;
 
-typedef struct OdinEvent_RoomConnectionStateChangedData {
-    /**
-     * Status of the room connection
-     */
-    enum OdinRoomConnectionState state;
-    /**
-     * Reason for this update
-     */
-    enum OdinRoomConnectionStateChangeReason reason;
-} OdinEvent_RoomConnectionStateChangedData;
+/**
+ * An opaque type representing an ODIN room, which manages by the underlying connection through
+ * a shared connection pool. This abstraction provides a high-level interface for joining rooms,
+ * managing persistent state and sending/receiving data, making it easier to integrate room-based
+ * interactions into your application.
+ */
+typedef struct OdinRoom OdinRoom;
 
-typedef struct OdinEvent_MessageReceivedData {
-    /**
-     * ID of the peer who sent this message
-     */
-    uint64_t peer_id;
-    /**
-     * Byte array with arbitrary data received
-     */
-    const uint8_t *data;
-    /**
-     * Length of the data array
-     */
-    size_t data_len;
-} OdinEvent_MessageReceivedData;
+/**
+ * A struct for generating ODIN tokens, 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;
 
-typedef struct OdinEvent {
-    OdinEventTag tag;
-    union {
-        OdinEvent_JoinedData joined;
-        OdinEvent_PeerJoinedData peer_joined;
-        OdinEvent_PeerLeftData peer_left;
-        OdinEvent_PeerUserDataChangedData peer_user_data_changed;
-        OdinEvent_MediaAddedData media_added;
-        OdinEvent_MediaRemovedData media_removed;
-        OdinEvent_MediaActiveStateChangedData media_active_state_changed;
-        OdinEvent_RoomUserDataChangedData room_user_data_changed;
-        OdinEvent_RoomConnectionStateChangedData room_connection_state_changed;
-        OdinEvent_MessageReceivedData message_received;
-    };
-} OdinEvent;
+/**
+ * Settings for configuring connection pools to define a set of callback functions that a connection
+ * pool uses to notify the application about incoming events. The `on_datagram` callback is invoked
+ * when a voice packet is received, providing the internal id of the associated ODIN room handle, the
+ * sender media ID, the audio data buffer and a user-defined pointer for contextual information.
+ * Similarly, the `on_rpc` callback is triggered for all incoming RPCs. This structure enables flexible
+ * integration of custom handling logic across all of your connection pools.
+ */
+typedef struct OdinConnectionPoolSettings {
+    /**
+     * Mandatory callback for incoming voice packets
+     */
+    void (*on_datagram)(uint64_t room_ref,
+                        uint16_t media_id,
+                        const uint8_t *bytes,
+                        uint32_t bytes_length,
+                        void *user_data);
+    /**
+     * Mandatory callback for incoming messages/events
+     */
+    void (*on_rpc)(uint64_t room_ref, const uint8_t *bytes, uint32_t bytes_length, void *user_data);
+    /**
+     * Optional user-defined data pointer, passed to all callbacks to provide a context or state
+     */
+    void *user_data;
+} OdinConnectionPoolSettings;
+
+/**
+ * Optional, pluggable encryption module for room communications. An cipher can be attached to an
+ * ODIN room handle on creation to enable customizable, end-to-end encryption (E2EE). When enabled,
+ * it intercepts data right before transmission and immediately after reception, allowing custom
+ * processing of datagrams, messages and custom peer user data. The structure provides a suite of
+ * callback functions for initialization, cleanup, event handling and encryption/decryption tasks,
+ * along with parameters to adjust for any additional capacity overhead.
+ */
+typedef struct OdinCipher {
+    void (*init)(struct OdinCipher *cipher, struct OdinRoom *room);
+    void (*free)(struct OdinCipher *cipher);
+    void (*on_event)(struct OdinCipher *cipher, const unsigned char *bytes, uint32_t length);
+    int32_t (*encrypt_datagram)(struct OdinCipher *cipher,
+                                const unsigned char *plaintext,
+                                uint32_t plaintext_length,
+                                unsigned char *ciphertext,
+                                uint32_t ciphertext_capacity);
+    int32_t (*decrypt_datagram)(struct OdinCipher *cipher,
+                                uint64_t peer_id,
+                                const unsigned char *ciphertext,
+                                uint32_t ciphertext_length,
+                                unsigned char *plaintext,
+                                uint32_t plaintext_capacity);
+    int32_t (*encrypt_message)(struct OdinCipher *cipher,
+                               const unsigned char *plaintext,
+                               uint32_t plaintext_length,
+                               unsigned char *ciphertext,
+                               uint32_t ciphertext_capacity);
+    int32_t (*decrypt_message)(struct OdinCipher *cipher,
+                               uint64_t peer_id,
+                               const unsigned char *ciphertext,
+                               uint32_t ciphertext_length,
+                               unsigned char *plaintext,
+                               uint32_t plaintext_capacity);
+    int32_t (*encrypt_user_data)(struct OdinCipher *cipher,
+                                 const unsigned char *plaintext,
+                                 uint32_t plaintext_length,
+                                 unsigned char *ciphertext,
+                                 uint32_t ciphertext_capacity);
+    int32_t (*decrypt_user_data)(struct OdinCipher *cipher,
+                                 uint64_t peer_id,
+                                 const unsigned char *ciphertext,
+                                 uint32_t ciphertext_length,
+                                 unsigned char *plaintext,
+                                 uint32_t plaintext_capacity);
+    uint32_t additional_capacity_datagram;
+    uint32_t additional_capacity_message;
+    uint32_t additional_capacity_user_data;
+} OdinCipher;
 
 /**
  * Statistics for the underlying connection of a room.
@@ -386,26 +340,26 @@ typedef struct OdinConnectionStats {
      * The amount of outgoing UDP datagrams observed
      */
     uint64_t udp_tx_datagrams;
-    /**
-     * The amount of outgoing acknowledgement frames observed
-     */
-    uint64_t udp_tx_acks;
     /**
      * The total amount of bytes which have been transferred inside outgoing UDP datagrams
      */
     uint64_t udp_tx_bytes;
     /**
-     * The amount of incoming UDP datagrams observed
+     * The the packet loss percentage of outgoing UDP datagrams
      */
-    uint64_t udp_rx_datagrams;
+    float udp_tx_loss;
     /**
-     * The amount of incoming acknowledgement frames observed
+     * The amount of incoming UDP datagrams observed
      */
-    uint64_t udp_rx_acks;
+    uint64_t udp_rx_datagrams;
     /**
      * The total amount of bytes which have been transferred inside incoming UDP datagrams
      */
     uint64_t udp_rx_bytes;
+    /**
+     * The the packet loss percentage of incoming UDP datagrams
+     */
+    float udp_rx_loss;
     /**
      * Current congestion window of the connection
      */
@@ -421,480 +375,624 @@ typedef struct OdinConnectionStats {
 } OdinConnectionStats;
 
 /**
- * Per-room configuration of the ODIN audio processing module which provides a variety of smart
- * enhancement algorithms.
+ * Audio decoder jitter statistics.
  */
-typedef struct OdinApmConfig {
+typedef struct OdinDecoderJitterStats {
     /**
-     * Enables or disables voice activity detection (VAD)
+     * The total number of packets seen by the medias jitter buffer.
      */
-    bool voice_activity_detection;
+    uint32_t packets_total;
     /**
-     * Voice probability value when the VAD should engage
+     * The number of packets available in the medias jitter buffer.
      */
-    float voice_activity_detection_attack_probability;
+    uint32_t packets_buffered;
     /**
-     * Voice probability value when the VAD should disengage
+     * The number of packets processed by the medias jitter buffer.
      */
-    float voice_activity_detection_release_probability;
+    uint32_t packets_processed;
     /**
-     * Enables or disables the input volume gate
+     * The number of packets dropped because they seemed to arrive too early.
      */
-    bool volume_gate;
+    uint32_t packets_arrived_too_early;
     /**
-     * Root mean square power (dBFS) when the volume gate should engage
+     * The number of packets dropped because they seemed to arrive too late.
      */
-    float volume_gate_attack_loudness;
+    uint32_t packets_arrived_too_late;
     /**
-     * Root mean square power (dBFS) when the volume gate should disengage
+     * The number of packets dropped due to a jitter buffer reset.
      */
-    float volume_gate_release_loudness;
+    uint32_t packets_dropped;
     /**
-     * Enable or disable echo cancellation
+     * The number of packets marked as invalid.
      */
-    bool echo_canceller;
+    uint32_t packets_invalid;
     /**
-     * Enable or disable high pass filtering
+     * The number of packets marked as duplicates.
      */
-    bool high_pass_filter;
+    uint32_t packets_repeated;
     /**
-     * Enable or disable the pre amplifier
+     * The number of packets marked as lost during transmission.
      */
-    bool pre_amplifier;
+    uint32_t packets_lost;
+} OdinDecoderJitterStats;
+
+/**
+ * A callback invoked when the decoder reports one or more audio events.
+ */
+typedef void (*OdinDecoderEventCallback)(struct OdinDecoder *decoder,
+                                         enum OdinAudioEvents events,
+                                         void *user_data);
+
+/**
+ * A callback invoked when the encoder reports one or more audio events.
+ */
+typedef void (*OdinEncoderEventCallback)(struct OdinEncoder *encoder,
+                                         enum OdinAudioEvents events,
+                                         void *user_data);
+
+/**
+ * Sensitivity parameters for ODIN voice activity detection module configuration.
+ */
+typedef struct OdinSensitivityConfig {
     /**
-     * Set the aggressiveness of the suppression
+     * Indicates whether the sensitivity configuration is enabled
      */
-    enum OdinNoiseSuppressionLevel noise_suppression_level;
+    bool enabled;
     /**
-     * Enable or disable the transient suppressor
+     * The threshold at which the trigger should engage
      */
-    bool transient_suppressor;
+    float attack_threshold;
     /**
-     * Enable or disable the gain controller
+     * The threshold at which the trigger should disengage
      */
-    bool gain_controller;
-} OdinApmConfig;
+    float release_threshold;
+} OdinSensitivityConfig;
 
 /**
- * Audio stream statistics.
+ * Pipeline configuration of the ODIN voice activity detection module, which offers advanced
+ * algorithms to accurately determine when to start or stop transmitting audio data.
  */
-typedef struct OdinAudioStreamStats {
+typedef struct OdinVadConfig {
     /**
-     * The total number of packets seen by the medias jitter buffer.
+     * When enabled, ODIN will analyze the audio input signal using smart voice detection algorithm
+     * to determine the presence of speech. You can define both the probability required to start
+     * and stop transmitting.
      */
-    uint32_t packets_total;
+    struct OdinSensitivityConfig voice_activity;
     /**
-     * The number of packets processed by the medias jitter buffer.
+     * When enabled, ODIN will measure the volume of the input audio signal, thus deciding when a
+     * user is speaking loud enough to transmit voice data. You can define both the root-mean-square
+     * power (dBFS) for when the gate should engage and disengage.
      */
-    uint32_t packets_processed;
-    /**
-     * The number of packets dropped because they seemed to arrive too early.
-     */
-    uint32_t packets_arrived_too_early;
+    struct OdinSensitivityConfig volume_gate;
+} OdinVadConfig;
+
+/**
+ * Pipeline configuration of the ODIN audio processing module which provides a variety of smart
+ * enhancement algorithms.
+ */
+typedef struct OdinApmConfig {
     /**
-     * The number of packets dropped because they seemed to arrive too late.
+     * When enabled the echo canceller will try to subtract echoes, reverberation, and unwanted
+     * added sounds from the audio input signal. Note, that you need to process the reverse audio
+     * stream, also known as the loopback data to be used in the ODIN echo canceller.
      */
-    uint32_t packets_arrived_too_late;
+    bool echo_canceller;
     /**
-     * The number of packets dropped due to a jitter buffer reset.
+     * When enabled, the high-pass filter will remove low-frequency content from the input audio
+     * signal, thus making it sound cleaner and more focused.
      */
-    uint32_t packets_dropped;
+    bool high_pass_filter;
     /**
-     * The number of packets marked as invalid.
+     * When enabled, the transient suppressor will try to detect and attenuate keyboard clicks.
      */
-    uint32_t packets_invalid;
+    bool transient_suppressor;
     /**
-     * The number of packets marked as duplicates.
+     * When enabled, the noise suppressor will remove distracting background noise from the input
+     * audio signal. You can control the aggressiveness of the suppression. Increasing the level
+     * will reduce the noise level at the expense of a higher speech distortion.
      */
-    uint32_t packets_repeated;
+    enum OdinNoiseSuppressionLevel noise_suppression_level;
     /**
-     * The number of packets marked as lost during transmission.
+     * When enabled, the gain controller will bring the input audio signal to an appropriate range
+     * when it's either too loud or too quiet.
      */
-    uint32_t packets_lost;
-} OdinAudioStreamStats;
-
-typedef size_t OdinResamplerHandle;
+    enum OdinGainControllerVersion gain_controller_version;
+} OdinApmConfig;
 
 /**
- * Options for ODIN room tokens.
+ * Defines the signature for custom effect callbacks in an ODIN audio pipeline. The callback
+ * receives a pointer to a buffer of audio samples, the number of samples in the buffer, a
+ * pointer to a flag indicating whether the audio is silent. This allows for custom, in-place
+ * processing of an audio stream.
  */
-typedef struct OdinTokenOptions {
-    /**
-     * Customer identifier (you should _NOT_ set this unless connecting directly to an ODIN server)
-     */
-    const char *customer;
-    /**
-     * Audience of the token
-     */
-    enum OdinTokenAudience audience;
-    /**
-     * Token lifetime in seconds
-     */
-    uint64_t lifetime;
-} OdinTokenOptions;
+typedef void (*OdinCustomEffectCallback)(float *samples,
+                                         uint32_t samples_count,
+                                         bool *is_silent,
+                                         const void *user_data);
 
 #ifdef __cplusplus
 extern "C" {
 #endif // __cplusplus
 
 /**
- * Formats an ODIN return code into a human readable string representation for use in logging and
- * diagnostics. If `buf` is `NULL` this functions simply returns the required buffer length to
- * store the output buffer.
+ * Initializes the internal ODIN client runtime with a specified version number, ensuring the correct
+ * header file is employed. The majority of the API functions hinge on an active ODIN runtime.
+ *
+ * Note: Utilize `ODIN_VERSION` to supply the `version` argument.
  */
-size_t odin_error_format(OdinReturnCode error, char *buf, size_t buf_len);
+enum OdinError odin_initialize(const char *version);
 
 /**
- * Checks whether the code returned from ODIN function calls represents an error or an actual
- * result. This is used to easier work with certain functions that might return an error or a
- * valid result like `odin_audio_data_len`.
- * Internally this simply does `(code >> 29) > 0`.
+ * Shuts down the internal ODIN runtime including all active connection pools. It is advisable to
+ * invoke this function prior to terminating your application.
  */
-bool odin_is_error(OdinReturnCode code);
+void odin_shutdown(void);
 
 /**
- * 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: Utilize `ODIN_VERSION` to supply the `version` argument.
+ * Returns the error message from the last occurred error, if available. If no error is present,
+ * an empty string is returned.
  */
-bool odin_startup(const char *version);
+const char *odin_error_get_last_error(void);
 
 /**
- * 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: Ensure consistent settings are used on successive invocations of this function.
+ * Resets the last error message by clearing the error buffer.
  */
-bool odin_startup_ex(const char *version, struct OdinAudioStreamConfig output_config);
+void odin_error_reset_last_error(void);
 
 /**
- * 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.
+ * Initializes a new ODIN connection pool with the given settings and outputs a pointer to the
+ * newly created connection pool. The connection pool is intended to manage multiple connections
+ * efficiently.
  */
-void odin_shutdown(void);
+enum OdinError odin_connection_pool_create(struct OdinConnectionPoolSettings settings,
+                                           struct OdinConnectionPool **out_connection_pool);
 
 /**
- * Creates a new ODIN room handle in an unconnected state and returns its handle identifier. This
- * will return `0` when the internal ODIN client runtime is not initialized using `odin_startup`
- * or has already been terminated using `odin_shutdown`.
+ * Frees the specified ODIN connection pool and releases the resources associated with it. If the
+ * connection pool is currently active, it will be properly shut down before being freed.
  */
-OdinRoomHandle odin_room_create(void);
+void odin_connection_pool_free(struct OdinConnectionPool *connection_pool);
+
+/**
+ * Creates a new ODIN room with default parameters. This basic variant requires only the connection
+ * pool, the address of an ODIN gateway/server and a JSON Web Token (JWT) for user authentication.
+ * On success, it returns the created room handle and immediately triggers asynchronous connection
+ * establishment, allowing the local peer to join the room.
+ *
+ * NOTE: For advanced configuration, see `odin_room_create_ex`.
+ */
+enum OdinError odin_room_create(struct OdinConnectionPool *connection_pool,
+                                const char *uri,
+                                const char *token,
+                                struct OdinRoom **out_room);
+
+/**
+ * Creates a new ODIN room with advanced parameters. In addition to the parameters required by the
+ * basic variant, this function accepts an optional room name to select a specific room when the
+ * token contains multiple room names (`odin_room_create` simply uses the first room name from the
+ * authentication token). It also allows specifying initial peer user data as a byte array and a
+ * 3-element float array representing 3D coordinates used for server-side voice packet culling.
+ * Additionally, an optional ODIN cipher plugin can be provided to enable end-to-end encryption
+ * of room communications. On success, it returns the created room handle and triggers asynchronous
+ * connection establishment, allowing the local peer to join the room.
+ */
+enum OdinError odin_room_create_ex(struct OdinConnectionPool *connection_pool,
+                                   const char *uri,
+                                   const char *token,
+                                   const char *room_name,
+                                   const unsigned char *user_data,
+                                   uint32_t user_data_length,
+                                   const float position[3],
+                                   struct OdinCipher *cipher,
+                                   struct OdinRoom **out_room);
 
 /**
  * Closes the specified ODIN room handle, thus making our own peer leave the room on the server
  * and closing the connection if needed.
  */
-OdinReturnCode odin_room_close(OdinRoomHandle room);
+void odin_room_close(struct OdinRoom *room);
 
 /**
- * Destroys the specified ODIN room handle.
+ * Retrieves the unique handle identifier for the specified room. Returns `0` if the room is invalid.
  */
-OdinReturnCode odin_room_destroy(OdinRoomHandle room);
+uint64_t odin_room_get_ref(struct OdinRoom *room);
 
 /**
- * Sets the event callback on the the specified `OdinRoomHandle`. Generally this should be called
- * _once_ before joining a room.
+ * Retrieves the name from the specified room.
  */
-OdinReturnCode odin_room_set_event_callback(OdinRoomHandle room,
-                                            void (*callback)(OdinRoomHandle room,
-                                                             const struct OdinEvent *event,
-                                                             void *extra_data),
-                                            void *extra_data);
+enum OdinError odin_room_get_name(struct OdinRoom *room,
+                                  char *out_value,
+                                  uint32_t *out_value_length);
 
 /**
- * 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: It's crucial to maintain consistent scaling across all client applications.
+ * Retrieves the underlying connection identifier associated with the room, or `0` if no valid
+ * connection exists.
  */
-OdinReturnCode odin_room_set_position_scale(OdinRoomHandle room, float scale);
+uint64_t odin_room_get_connection_id(struct OdinRoom *room);
 
 /**
- * Joins a room on an ODIN server. This function takes an URL to an ODIN gateway and a signed room
- * token obtained externally that authorizes the client to establish the connection. Unless you're
- * hosting your own servers, always use gateway running at `https://gateway.odin.4players.io`.
+ * Retrieves detailed connection statistics for the specified room, filling the provided structure
+ * with data such as the number of transmitted/received datagrams, bytes, packet loss percentage,
+ * congestion window information and round-trip time.
  */
-OdinReturnCode odin_room_join(OdinRoomHandle room, const char *url, const char *token);
+enum OdinError odin_room_get_connection_stats(struct OdinRoom *room,
+                                              struct OdinConnectionStats *out_stats);
 
 /**
- * Retrieves the room ID (e.g. the name of the room) from the specified `OdinRoomHandle`.
+ * Flushes the local peer's user data by re-sending it to the server, ensuring that the latest
+ * data is synchronized across all connected peers. This function does NOT need to be invoked
+ * manually. It is typically used internally by an ODIN cipher after encryption key rotations
+ * to update and maintain data consistency.
  */
-OdinReturnCode odin_room_id(OdinRoomHandle room, char *out_id, size_t out_id_len);
+enum OdinError odin_room_resend_user_data(struct OdinRoom *room);
 
 /**
- * Retrieves the identifier of the customer the room is assigned to from the specified `OdinRoomHandle`.
+ * Sends a MessagePack encoded RPC message to the server for the specified room.
  */
-OdinReturnCode odin_room_customer(OdinRoomHandle room,
-                                  char *out_customer,
-                                  size_t out_customer_len);
+enum OdinError odin_room_send_rpc(struct OdinRoom *room,
+                                  const uint8_t *bytes,
+                                  uint32_t bytes_length);
 
 /**
- * Retrieves your own peer ID from the specified `OdinRoomHandle`.
+ * Sends a MessagePack encoded RPC message using a local loopback mechanism. It bypasses
+ * the normal network transmission by directly invoking the RPC callback configured in
+ * the connection pool settings. It is useful for emitting synthetic events for testing
+ * and internal processing without involving the network layer.
  */
-OdinReturnCode odin_room_peer_id(OdinRoomHandle room, uint64_t *out_peer_id);
+enum OdinError odin_room_send_loopback_rpc(struct OdinRoom *room,
+                                           const uint8_t *bytes,
+                                           uint32_t bytes_length);
 
 /**
- * Retrieves statistics for the underlying connection of the specified `OdinRoomHandle`.
+ * Sends an encoded voice packet to the server for the specified room.
  */
-OdinReturnCode odin_room_connection_stats(OdinRoomHandle room, struct OdinConnectionStats *stats);
+enum OdinError odin_room_send_datagram(struct OdinRoom *room,
+                                       const uint8_t *bytes,
+                                       uint32_t bytes_length);
 
 /**
- * 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.
+ * Destroys the specified ODIN room handle.
+ */
+void odin_room_free(struct OdinRoom *room);
+
+/**
+ * Creates a new instance of an ODIN decoder with default settings used to process the remote
+ * media stream specified with the `media_id` parameter. The resulting decoder encapsulates an
+ * egress resampler using the given sample rate and channel layout.
  */
-OdinReturnCode odin_room_update_peer_user_data(OdinRoomHandle room,
-                                               const uint8_t *user_data,
-                                               size_t user_data_length);
+enum OdinError odin_decoder_create(uint16_t media_id,
+                                   uint32_t sample_rate,
+                                   bool stereo,
+                                   struct OdinDecoder **out_decoder);
 
 /**
- * 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`.
+ * Creates a new instance of an ODIN decoder with extended configuration options for processing
+ * a remote media stream specified by the `media_id` parameter. Like `odin_decoder_create`, this
+ * function initializes a decoder with an embedded egress resampler using the provided sample
+ * rate and channel layout. However, this extended version allows you to customize the jitter
+ * handling by specifying the number of packets to use in calculating the base jitter.
  *
- * Note: Use this before calling `odin_room_join` to set the initial peer position upon connect.
+ * The base jitter is computed as the product of the number of packets  and the duration of a
+ * single packet, which corresponds to 20ms in 90kHz units. Setting `base_jitter_packets` to `2`
+ * will yield a base jitter of 40ms. Adjusting this parameter can affect how the decoder handles
+ * variations in packet arrival times and performs loss concealment during periods of silence or
+ * packet loss.
  */
-OdinReturnCode odin_room_update_position(OdinRoomHandle room, float x, float y, float z);
+enum OdinError odin_decoder_create_ex(uint16_t media_id,
+                                      uint32_t sample_rate,
+                                      bool stereo,
+                                      uint8_t base_jitter_packets,
+                                      struct OdinDecoder **out_decoder);
 
 /**
- * Sends arbitrary data to a list of target peers over the ODIN server. If `NULL` is specified, the
- * message will be sent to all other peers in the same room.
+ * Returns a pointer to the internal ODIN audio pipeline instance used by the given decoder.
  */
-OdinReturnCode odin_room_send_message(OdinRoomHandle room,
-                                      const uint64_t *peer_id_list,
-                                      size_t peer_id_list_size,
-                                      const uint8_t *data,
-                                      size_t data_length);
+const struct OdinPipeline *odin_decoder_get_pipeline(struct OdinDecoder *decoder);
 
 /**
- * Adds a specified `OdinMediaStreamHandle` to the room. Please note, that this can only be done
- * _once_ on a given media. Trying to do it more than once will return an error on subsequent calls
- * to this function.
+ * Pushes an incoming datagram to the specified decoder for processing.
  */
-OdinReturnCode odin_room_add_media(OdinRoomHandle room, OdinMediaStreamHandle media);
+enum OdinError odin_decoder_push(struct OdinDecoder *decoder,
+                                 const uint8_t *datagram,
+                                 uint32_t datagram_length);
 
 /**
- * Configures the ODIN audio processing module on the room with the specified config.
+ * Retrieves a block of processed audio samples from the decoder's buffer. The samples are
+ * interleaved floating-point values in the range [-1, 1] and are written into the provided
+ * output buffer. A flag is also set to indicate if the output is silent.
  */
-OdinReturnCode odin_room_configure_apm(OdinRoomHandle room, struct OdinApmConfig config);
+enum OdinError odin_decoder_pop(struct OdinDecoder *decoder,
+                                float *out_samples,
+                                uint32_t out_samples_count,
+                                bool *out_is_silent);
 
 /**
- * Creates a new audio input stream, which can be added to a room and send data over it.
+ * Collects and returns jitter statistics for the specified decoder.
  */
-OdinMediaStreamHandle odin_audio_stream_create(struct OdinAudioStreamConfig config);
+enum OdinError odin_decoder_get_jitter_stats(struct OdinDecoder *decoder,
+                                             struct OdinDecoderJitterStats *out_stats);
 
 /**
- * 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.
+ * Returns whether the decoder is currently processing silence. This reflects the internal
+ * silence detection state of the decoder, which updates as audio is processed. If the
+ * provided handle is invalid, the function returns `true` for safety.
  */
-OdinMediaStreamHandle odin_video_stream_create(void);
+bool odin_decoder_is_silent(struct OdinDecoder *decoder);
 
 /**
- * Destroys the specified `OdinMediaStreamHandle`, after which you will no longer be able to
- * receive or send any data over it. If the media is currently 'attached' to a room it will be
- * removed.
+ * Registers a callback to receive decoder audio events. The `filter` determines which event
+ * types will trigger the callback, allowing selective handling. Any previously registered
+ * callback is replaced. The callback is invoked with the decoder handle, the combined event
+ * bitmask and the supplied `user_data`.
  */
-OdinReturnCode odin_media_stream_destroy(OdinMediaStreamHandle stream);
+enum OdinError odin_decoder_set_event_callback(struct OdinDecoder *decoder,
+                                               enum OdinAudioEvents filter,
+                                               OdinDecoderEventCallback callback,
+                                               void *user_data);
 
 /**
- * Retrieves the media ID of the specified `OdinMediaStreamHandle`.
+ * Frees the resources associated with the specified decoder.
  */
-OdinReturnCode odin_media_stream_media_id(OdinMediaStreamHandle stream, uint16_t *out_media_id);
+void odin_decoder_free(struct OdinDecoder *decoder);
 
 /**
- * Retrieves the peer ID of the specified `OdinMediaStreamHandle`.
+ * Creates a new ODIN encoder instance with default settings used to encode audio captured from
+ * local sources, such as a microphone. The encoder encapsulates an ingress resampler using the
+ * given sample rate and channel layout.
  */
-OdinReturnCode odin_media_stream_peer_id(OdinMediaStreamHandle stream, uint64_t *out_peer_id);
+enum OdinError odin_encoder_create(uint32_t sample_rate,
+                                   bool stereo,
+                                   struct OdinEncoder **out_encoder);
 
 /**
- * Returns the type of the specified media stream.
- *
- * Note: This function will always return `OdinMediaStreamType_Audio` at the moment.
+ * Creates a new ODIN encoder instance for local media streams with extended codec configuration
+ * parameters. In addition to the sample rate and stereo configuration, it allows specification
+ * of whether the application is intended for VoIP, a target bitrate and the encoder's expected
+ * packet loss percentage.
  */
-enum OdinMediaStreamType odin_media_stream_type(OdinMediaStreamHandle stream);
+enum OdinError odin_encoder_create_ex(uint32_t sample_rate,
+                                      bool stereo,
+                                      bool application_voip,
+                                      uint32_t bitrate_kbps,
+                                      uint8_t packet_loss_perc,
+                                      struct OdinEncoder **out_encoder);
 
 /**
- * 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.
+ * Returns a pointer to the internal ODIN audio pipeline instance used by the given encoder.
  */
-OdinReturnCode odin_media_stream_pause(OdinMediaStreamHandle stream);
+const struct OdinPipeline *odin_encoder_get_pipeline(struct OdinEncoder *encoder);
 
 /**
- * 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.
+ * Pushes raw audio samples to the encoder for processing. The provided audio samples, which
+ * must be interleaved floating-point values in the range [-1, 1], are processed through the
+ * encoder's pipeline, allowing any configured effects to be applied prior to encoding.
  */
-OdinReturnCode odin_media_stream_resume(OdinMediaStreamHandle stream);
+enum OdinError odin_encoder_push(struct OdinEncoder *encoder,
+                                 const float *samples,
+                                 uint32_t samples_count);
 
 /**
- * Sends data to the audio stream. The data has to be interleaved [-1, 1] float data.
+ * Retrieves an encoded datagram from the encoder's buffer. It can optionally consider multiple
+ * media IDs for processing, which can be useful when you're sending a voice packet to more than
+ * one room. The encoded data is written to the provided output buffer. Each datagram can include
+ * up to 4 media IDs. These IDs are drawn from the pool assigned by the server when joining a room,
+ * enabling a single datagram to be routed across multiple rooms.
  */
-OdinReturnCode odin_audio_push_data(OdinMediaStreamHandle stream, const float *buf, size_t buf_len);
+enum OdinError odin_encoder_pop(struct OdinEncoder *encoder,
+                                const uint16_t *media_ids,
+                                uint32_t media_ids_length,
+                                uint8_t *out_datagram,
+                                uint32_t *out_datagram_length);
 
 /**
- * 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.
+ * Returns whether the encoder is currently processing silence. This reflects the internal
+ * silence detection state of the encoder, which updates as audio is processed. If the
+ * provided handle is invalid, the function returns `true` for safety.
  */
-OdinReturnCode odin_audio_read_data(OdinMediaStreamHandle stream,
-                                    float *out_buffer,
-                                    size_t out_buffer_len);
+bool odin_encoder_is_silent(struct OdinEncoder *encoder);
 
 /**
- * Returns the number of samples available in the audio buffer of an output `OdinMediaStreamHandle`.
+ * Registers a callback to receive encoder audio events. The `filter` determines which event
+ * types will trigger the callback, allowing selective handling. Any previously registered
+ * callback is replaced. The callback is invoked with the encoder handle, the combined event
+ * bitmask and the supplied `user_data`.
  */
-OdinReturnCode odin_audio_data_len(OdinMediaStreamHandle stream);
+enum OdinError odin_encoder_set_event_callback(struct OdinEncoder *encoder,
+                                               enum OdinAudioEvents filter,
+                                               OdinEncoderEventCallback callback,
+                                               void *user_data);
 
 /**
- * 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.
+ * Frees the resources associated with the specified encoder.
  */
-OdinReturnCode odin_audio_reset(OdinMediaStreamHandle stream);
+void odin_encoder_free(struct OdinEncoder *encoder);
 
 /**
- * Retrieves statistics for the specified `OdinMediaStreamHandle`.
- *
- * Note: This will only work for output streams.
+ * Inserts a Voice Activity Detection (VAD) effect into the audio pipeline at the specified
+ * index and returns a unique effect identifier.
  */
-OdinReturnCode odin_audio_stats(OdinMediaStreamHandle stream, struct OdinAudioStreamStats *stats);
+enum OdinError odin_pipeline_insert_vad_effect(const struct OdinPipeline *pipeline,
+                                               uint32_t index,
+                                               uint32_t *out_effect_id);
 
 /**
- * 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 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.
+ * Retrieves the configuration for a VAD effect identified by `effect_id` from the specified
+ * audio pipeline.
  */
-OdinReturnCode odin_audio_mix_streams(OdinRoomHandle room,
-                                      const OdinMediaStreamHandle *streams,
-                                      size_t stream_count,
-                                      float *out_buffer,
-                                      size_t out_buffer_len);
+enum OdinError odin_pipeline_get_vad_config(const struct OdinPipeline *pipeline,
+                                            uint32_t effect_id,
+                                            struct OdinVadConfig *out_config);
 
 /**
- * Processes the reverse audio stream, also known as the loopback data to be used in the ODIN echo
- * canceller. This should only be done if you are _NOT_ using `odin_audio_mix_streams`.
+ * Updates the configuration settings of the VAD effect identified by `effect_id` in the specified
+ * audio pipeline.
  */
-OdinReturnCode odin_audio_process_reverse(OdinRoomHandle room, float *buffer, size_t buffer_len);
+enum OdinError odin_pipeline_set_vad_config(const struct OdinPipeline *pipeline,
+                                            uint32_t effect_id,
+                                            const struct OdinVadConfig *config);
 
 /**
- * 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.
+ * Inserts an Audio Processing Module (APM) effect into the audio pipeline at the specified index
+ * and returns a unique effect identifier.
+ */
+enum OdinError odin_pipeline_insert_apm_effect(const struct OdinPipeline *pipeline,
+                                               uint32_t index,
+                                               uint32_t playback_sample_rate,
+                                               bool playback_stereo,
+                                               uint32_t *out_effect_id);
+
+/**
+ * Retrieves the configuration for an APM effect identified by `effect_id` from the specified
+ * audio pipeline.
  */
-OdinReturnCode odin_audio_set_stream_delay(OdinRoomHandle room, uint64_t delay_ms);
+enum OdinError odin_pipeline_get_apm_config(const struct OdinPipeline *pipeline,
+                                            uint32_t effect_id,
+                                            struct OdinApmConfig *out_config);
 
 /**
- * Creates a new ODIN resampler instance. This is intended for situations where your audio pipeline
- * doesn't support 48 kHz.
+ * Updates the configuration settings of the APM effect identified by `effect_id` in the specified
+ * audio pipeline.
+ */
+enum OdinError odin_pipeline_set_apm_config(const struct OdinPipeline *pipeline,
+                                            uint32_t effect_id,
+                                            const struct OdinApmConfig *config);
+
+/**
+ * Updates the specified APM effect's sample buffer for processing the reverse (playback) audio
+ * stream. The provided samples must be interleaved float values in the range [-1, 1]. The delay
+ * parameter is used to align the reverse stream processing with the forward (capture) stream.
+ * The delay can be expressed as:
+ *
+ *  `delay = (t_render - t_analyze) + (t_process - t_capture)`
  *
- * Note: One resampler should be used exclusively per audio stream.
+ * where:
+ *  - `t_render` is the time the first sample of the same frame is rendered by the audio hardware.
+ *  - `t_analyze` is the time the frame is processed in the reverse stream.
+ *  - `t_capture` is the time the first sample of a frame is captured by the audio hardware.
+ *  - `t_process` is the time the frame is processed in the forward stream.
  */
-OdinResamplerHandle odin_resampler_create(uint32_t from_rate,
-                                          uint32_t to_rate,
-                                          uint16_t channel_count);
+enum OdinError odin_pipeline_update_apm_playback(const struct OdinPipeline *pipeline,
+                                                 uint32_t effect_id,
+                                                 const float *samples,
+                                                 uint32_t samples_count,
+                                                 uint64_t delay_ms);
 
 /**
- * Resamples a single chunk of audio. If the ODIN resampler instance was created with multiple
- * channels, the data is assumed to be interleaved. The `output_capacity` argument also serves as
- * an out parameter when the provided capacity wasn't enough to fulfill the resample request, in
- * which case this function will write the minimum required buffer size into the given variable.
- * On success, the written size for the processed sample is returned in both, the return value
- * and the `output_capacity` out parameter.
+ * Inserts a user-defined custom effect at the specified index in the audio pipeline. The effect
+ * is implemented via a callback function and associated user data. A unique effect identifier
+ * is returned.
  */
-OdinReturnCode odin_resampler_process(OdinResamplerHandle resampler,
-                                      const float *input,
-                                      size_t input_len,
-                                      float *output,
-                                      size_t *output_capacity);
+enum OdinError odin_pipeline_insert_custom_effect(const struct OdinPipeline *pipeline,
+                                                  uint32_t index,
+                                                  OdinCustomEffectCallback callback,
+                                                  const void *user_data,
+                                                  uint32_t *out_effect_id);
 
 /**
- * Destroys the given ODIN resampler instance. After this call, all attempts to use this handle
- * will fail.
+ * Returns the unique effect identifier from an audio pipeline corresponding to the effect located
+ * at the specified index.
  */
-OdinReturnCode odin_resampler_destroy(OdinResamplerHandle resampler);
+enum OdinError odin_pipeline_get_effect_id(const struct OdinPipeline *pipeline,
+                                           uint32_t index,
+                                           uint32_t *out_effect_id);
 
 /**
- * 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.
+ * Searches the specified audio pipeline for the effect with the specified `effect_id` and returns
+ * its current index.
+ */
+enum OdinError odin_pipeline_get_effect_index(const struct OdinPipeline *pipeline,
+                                              uint32_t effect_id,
+                                              uint32_t *out_index);
+
+/**
+ * Obtains the effect type (VAD, APM, or Custom) for the effect identified by `effect_id`.
+ */
+enum OdinError odin_pipeline_get_effect_type(const struct OdinPipeline *pipeline,
+                                             uint32_t effect_id,
+                                             enum OdinEffectType *out_effect_type);
+
+/**
+ * Retrieves the total number of effects currently in the audio pipeline.
  */
-OdinReturnCode odin_access_key_generate(char *buf, size_t buf_len);
+uint32_t odin_pipeline_get_effect_count(const struct OdinPipeline *pipeline);
 
 /**
- * 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.
+ * Reorders the audio pipeline by moving the effect with the specified `effect_id` to a new index.
  */
-OdinReturnCode odin_access_key_id(const char *access_key, char *out_key_id, size_t out_key_id_len);
+enum OdinError odin_pipeline_move_effect(const struct OdinPipeline *pipeline,
+                                         uint32_t effect_id,
+                                         size_t new_index);
 
 /**
- * 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.
+ * Deletes the effect identified by `effect_id` from the specified audio pipeline.
  */
-OdinReturnCode odin_access_key_public_key(const char *access_key,
-                                          char *out_public_key,
-                                          size_t out_public_key_len);
+enum OdinError odin_pipeline_remove_effect(const struct OdinPipeline *pipeline, uint32_t effect_id);
 
 /**
- * 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.
+ * Creates a new token generator using the specified ODIN access key. If no access key is provided,
+ * a new one will be generated.
  */
-OdinReturnCode odin_access_key_secret_key(const char *access_key,
-                                          char *out_secret_key,
-                                          size_t out_secret_key_len);
+enum OdinError odin_token_generator_create(const char *access_key,
+                                           struct OdinTokenGenerator **out_token_generator);
 
 /**
- * Creates a new token generator instance.
+ * Frees the specified token generator and releases the resources associated with it.
+ */
+void odin_token_generator_free(struct OdinTokenGenerator *token_generator);
+
+/**
+ * Retrieves the ODIN access key used by the specified token generator. An ODIN access key is a 44
+ * character long Base64-String that consists of an internal version number, a set of random bytes
+ * and a checksum.
  */
-struct OdinTokenGenerator *odin_token_generator_create(const char *access_key);
+enum OdinError odin_token_generator_get_access_key(struct OdinTokenGenerator *token_generator,
+                                                   char *out_access_key,
+                                                   uint32_t *out_access_key_length);
 
 /**
- * Destroys an existing token generator instance.
+ * Extracts the public key from the access key used by the specified token generator. The public
+ * key, derived from the Ed25519 curve, must be shared with _4Players_ to enable verification of
+ * a generated room token.
  */
-void odin_token_generator_destroy(struct OdinTokenGenerator *generator);
+enum OdinError odin_token_generator_get_public_key(struct OdinTokenGenerator *token_generator,
+                                                   char *out_public_key,
+                                                   uint32_t *out_public_key_length);
 
 /**
- * Generates a signed JWT, which can be used by an ODIN client to join a room.
+ * Extracts the key ID from the access key used by the specified token generator. The key ID is
+ * embedded in room tokens, enabling the identification of the corresponding public key required
+ * for verification.
  */
-OdinReturnCode odin_token_generator_create_token(struct OdinTokenGenerator *generator,
-                                                 const char *room_id,
-                                                 const char *user_id,
-                                                 char *out_token,
-                                                 size_t out_token_len);
+enum OdinError odin_token_generator_get_key_id(struct OdinTokenGenerator *token_generator,
+                                               char *out_key_id,
+                                               uint32_t *out_key_id_length);
 
 /**
- * Generates a signed JWT such as `odin_token_generator_create_token` and allows passing a custom
- * set of `OdinTokenOptions` for advanced use-cases.
+ * Signs the provided body using the key ID and access key stored in the token generator to sign
+ * the provided body, creating a JSON Web Token (JWT). The EdDSA (Ed25519) algorithm is used for
+ * the digital signature.
  */
-OdinReturnCode odin_token_generator_create_token_ex(struct OdinTokenGenerator *generator,
-                                                    const char *room_id,
-                                                    const char *user_id,
-                                                    const struct OdinTokenOptions *options,
-                                                    char *out_token,
-                                                    size_t out_token_len);
+enum OdinError odin_token_generator_sign(struct OdinTokenGenerator *token_generator,
+                                         const char *body,
+                                         char *out_token,
+                                         uint32_t *out_token_length);
+
+/**
+ * Helper function to deserialize MessagePack encoded data and convert it into a JSON string.
+ */
+enum OdinError odin_rpc_bytes_to_json(const uint8_t *bytes,
+                                      uint32_t bytes_length,
+                                      char *out_json,
+                                      uint32_t *out_json_length);
+
+/**
+ * Helper function to convert a JSON string into a MessagePack encoded byte array.
+ */
+enum OdinError odin_rpc_json_to_bytes(const char *json,
+                                      uint8_t *out_bytes,
+                                      uint32_t *out_bytes_length);
 
 #ifdef __cplusplus
-} // extern "C"
-#endif // __cplusplus
+}  // extern "C"
+#endif  // __cplusplus