Version: 2.x

UOdinEncoder

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).

Declaration
UCLASS(ClassGroup = (Odin), Blueprintable, BlueprintType)
class ODIN_API UOdinEncoder : public UObject

Header: #include "OdinAudio/OdinEncoder.h"
Module: Odin
Inherits from: UObject
Blueprint: Blueprint type, Blueprintable · Blueprint reference

Overview

Functions

Name	Description
`ConstructEncoder`	Create uobject encoder with already created encoder handle
`CreateEncoder`	Creates a new ODIN encoder instance with default settings used to encode audio captured from local sources, such as a microphone using the given sample rate and channel layout.
`ConstructEncoderEx`	Create uobject encoder with create encoder ex
`CreateEncoderEx`	Creates a new ODIN encoder instance with extended codec configuration parameters.
`FreeEncoder`	Releases the native encoder.
`FreeEncoderHandle`	Invalidate internal encoder handle
`GetOrCreateEncoderPipeline`	Retrieves the Audio Pipeline associated with this encoder.
`GetOrCreatePipeline`	Returns the audio pipeline of the encoder and creates it on first use.
`GetIsSilent`	Returns whether the encoder is currently processing silence.
`SetAudioEventHandler`	Registers a callback to receive encoder audio events.
`SetAudioGenerator`	Set and add generator delegate handle for current encoder
`SetPosition`	Updates the 3D position of the specified channel mask.
`SetPositions`	Convenience wrapper to assign a position to several channel masks at once to update position for a spatialized proximity channel alongside fixed/unused position one
`ClearPosition`	Removes the position entry associated with the given channel mask, which also stops the encoder from transmitting on that channel entirely
`Pop`	Runs the audio pipeline on the pushed samples and returns the next encoded voice packet (datagram).
`Push`	Pushes raw audio samples (32-bit float, interleaved if stereo) into the encoder.
`SetEchoCancellationProcessingDelay`	The delay parameter is used to align the reverse stream processing with the forward (capture) stream.
`GetNumSampleSize`	Get num based on samplerate and channels
`GetLinkedRooms`	Get all rooms this encoder currently broadcasts to
`GetHandle`	Get internal handle
`SetHandle`	Replace internal handle object

Properties

Name	Description
`AudioGenerator`	The audio generator the encoder reads from, if any.
`PeerId`	The peer ID the encoder was created with.
`SampleRate`	Sample rate of the audio the encoder expects.
`bStereo`	True if the encoder expects interleaved stereo audio.

Functions

ConstructEncoder

Overload 1

Static

Create uobject encoder with already created encoder handle

static UOdinEncoder* ConstructEncoder(UObject* WorldContextObject, OdinEncoder* Handle);

Parameter	Type	Description
`WorldContextObject`	`UObject*`	context lifetime object
`Handle`	`OdinEncoder*`	incomplete internal handle type

Returns UOdinEncoder* – uobject encoder or null

Overload 2

Static · Blueprint: Construct Encoder

Creates a new ODIN Encoder. Encoders capture audio from a local source (like a microphone), process it (VAD, Noise Suppression), and encode it into audio frames to be sent to the server. By default, it uses a sample rate of 48kHz.

UFUNCTION(BlueprintCallable, Category = "Odin|Audio Pipeline")
static UOdinEncoder* ConstructEncoder(
    UObject* WorldContextObject,
    int64 PeerId,
    int32 SampleRate,
    bool bStereo);

Parameter	Type	Description
`WorldContextObject`	`UObject*`	context lifetime object
`PeerId`	`int64`	binding id
`SampleRate`	`int32`	samplerate for f32bit
`bStereo`	`bool`	channels interleaved

Returns UOdinEncoder* – uobject encoder or null

CreateEncoder

Blueprint: Create Encoder

Creates a new ODIN encoder instance with default settings used to encode audio captured from local sources, such as a microphone using the given sample rate and channel layout.

UFUNCTION(BlueprintCallable, Category = "Odin|Audio Pipeline")
UOdinEncoder* CreateEncoder(int64 InPeerId, int32 InSampleRate, bool bUseStereo);

Parameter	Type	Description
`InPeerId`	`int64`	binding id
`InSampleRate`	`int32`	samplerate for f32bit
`bUseStereo`	`bool`	channels interleaved

Returns UOdinEncoder* – Encoder or null

note

Peer id 0 will rewrite header on datagram send for connected room peer id; default bitrate 32000 (with stereo 128000), voip true (with stereo false), disabled interval, and expected packet loss of 15%

ConstructEncoderEx

Static · Blueprint: Construct Encoder (Advanced)

Create uobject encoder with create encoder ex

UFUNCTION(BlueprintCallable, Category = "Odin|Audio Pipeline")
static UOdinEncoder* ConstructEncoderEx(
    UObject* WorldContextObject,
    int64 PeerId,
    int32 SampleRate,
    bool bStereo,
    bool bApplication_VOIP,
    int32 Bitrate_Kbps,
    int32 Packet_Loss_Perc,
    int64 Update_Position_Interval_MS);

Parameter	Type	Description
`WorldContextObject`	`UObject*`	context lifetime object
`PeerId`	`int64`	binding id
`SampleRate`	`int32`	samplerate for f32bit
`bStereo`	`bool`	channels interleaved
`bApplication_VOIP`	`bool`	Toggle codec type. Set to true for sending voice, false for anything else (like music).
`Bitrate_Kbps`	`int32`	encoding bitrate
`Packet_Loss_Perc`	`int32`	expected packet loss percentage
`Update_Position_Interval_MS`	`int64`	interval where pop will produce position datagram (disable 0)

Returns UOdinEncoder* – uobject encoder or null

CreateEncoderEx

Blueprint: Create Encoder (Advanced)

Creates a new ODIN encoder instance 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.

UFUNCTION(BlueprintCallable, Category = "Odin|Audio Pipeline")
UOdinEncoder* CreateEncoderEx(
    int64 InConnectedPeerId,
    int32 InSampleRate,
    bool bUseStereo,
    bool bApplication_VOIP,
    int32 Bitrate_Kbps,
    int32 Packet_Loss_Perc,
    int64 Update_Position_Interval_MS);

Parameter	Type	Description
`InConnectedPeerId`	`int64`	Binding id
`InSampleRate`	`int32`	samplerate for f32bit
`bUseStereo`	`bool`	channels interleaved
`bApplication_VOIP`	`bool`	Toggle codec type. Set to true for sending voice, false for anything else (like music).
`Bitrate_Kbps`	`int32`	encoding bitrate
`Packet_Loss_Perc`	`int32`	expected packet loss percentage
`Update_Position_Interval_MS`	`int64`	interval where pop will produce position datagram (disable 0)

Returns UOdinEncoder* – Encoder or null

FreeEncoder

Static · Blueprint: Free Encoder

Releases the native encoder. The encoder object can't be used anymore afterwards.

UFUNCTION(BlueprintCallable, Category = "Odin|Audio Pipeline")
static bool FreeEncoder(UOdinEncoder* Encoder);

Parameter	Type	Description
`Encoder`	`UOdinEncoder*`	get handle from

Returns bool – true if handle was set

FreeEncoderHandle

Static

Invalidate internal encoder handle

static bool FreeEncoderHandle(OdinEncoder* Encoder);

Parameter	Type	Description
`Encoder`	`OdinEncoder*`

Returns bool – true if handle is not nullptr

GetOrCreateEncoderPipeline

Static · Blueprint: Get Or Create Encoder Pipeline

Retrieves the Audio Pipeline associated with this encoder. The pipeline allows you to add effects like Echo Cancellation, Noise Suppression, and Voice Activity Detection (VAD).

UFUNCTION(BlueprintCallable, Category = "Odin|Audio Pipeline")
static UOdinPipeline* GetOrCreateEncoderPipeline(UOdinEncoder* Encoder);

Parameter	Type	Description
`Encoder`	`UOdinEncoder*`	get handle from

Returns UOdinPipeline* – get current pipeline or construct new

GetOrCreatePipeline

Blueprint: Get Or Create Pipeline

Returns the audio pipeline of the encoder and creates it on first use. Insert effects such as APM, VAD or a Mute Effect into it.

UFUNCTION(BlueprintCallable, Category = "Odin|Audio Pipeline")
UOdinPipeline* GetOrCreatePipeline();

Returns UOdinPipeline* – get current pipeline or construct new

GetIsSilent

Const · Blueprint: Get Silent Flag (Encoder)

Returns whether the encoder is currently processing silence. This reflects the internal silence detection state of the encoder, which updates as audio is processed.

UFUNCTION(BlueprintCallable, Category = "Odin|Audio Pipeline")
bool GetIsSilent() const;

Returns bool – True if silent.

note

Always returns true, if the passed encoder is invalid.

SetAudioEventHandler

Blueprint: Register AudioEvent Handler (Encoder)

Registers a callback to receive encoder audio events. The filter determines which event types will trigger the callback, allowing selective handling.

UFUNCTION(BlueprintCallable, Category = "Odin|Audio Pipeline|Events")
bool SetAudioEventHandler(UPARAM(meta = (DisplayName = "Filter", Bitmask, BitmaskEnum = EOdinAudioEvents)) int32 EFilter = 1);

Parameter	Type	Description
`EFilter`	`int32`	Bitmask filter for events. Default: `1`.

Returns bool – True if registration was successful.

note

Any previously registered callback is replaced.

SetAudioGenerator

Blueprint: Set Audio Generator

Set and add generator delegate handle for current encoder

UFUNCTION(BlueprintCallable, Category = "Odin|Audio Pipeline")
void SetAudioGenerator(UAudioGenerator* Generator);

Parameter	Type	Description
`Generator`	`UAudioGenerator*`	to add the delegate to

note

internal use

SetPosition

Blueprint: Set Encoder Position

Updates the 3D position of the specified channel mask. To assign different positions to multiple masks, call this function once per mask.

UFUNCTION(BlueprintCallable, Category = "Odin|Audio Pipeline")
bool SetPosition(FOdinChannelMask ChannelMask, FOdinPosition Position);

Parameter	Type	Description
`ChannelMask`	`FOdinChannelMask`	audio layer
`Position`	`FOdinPosition`	position for each layer

Returns bool – true if successful

note

An encoder holds at most 12 channel positions; each masked channel occupies one slot until removed with ClearPosition. Passing a full channel mask (FOdinChannelMask::CreateFull) therefore fails with ODIN_ERROR_AUDIO_POSITION_LIMIT_REACHED. Mask only the channels that are actually transmitted on - for plain voice transmission that is just channel 0.

The server only forwards audio to peers whose positions are within a distance of 1.0 of each other, so coordinates must be scaled such that 1.0 equals the intended hearing range (e.g. divide unreal world units by the distance where the client side attenuation reaches silence). Unscaled world coordinates put peers out of range of each other and the server forwards no audio at all.

SetPositions

Blueprint: Set Encoder Positions

Convenience wrapper to assign a position to several channel masks at once to update position for a spatialized proximity channel alongside fixed/unused position one

UFUNCTION(BlueprintCallable, Category = "Odin|Audio Pipeline")
bool SetPositions(const TArray<FOdinChannelPosition>& Positions);

Parameter	Type	Description
`Positions`	`const TArray<FOdinChannelPosition>&`	channel mask + position pairs to apply; equivalent to calling SetPosition once per entry

Returns bool – true if every SetPosition call succeeded

note

Positions follow the same scaling convention as SetPosition: coordinates scaled such that a distance of 1.0 equals the hearing range, beyond which the server stops forwarding audio.

ClearPosition

Blueprint: Clear Encoder Position

Removes the position entry associated with the given channel mask, which also stops the encoder from transmitting on that channel entirely

UFUNCTION(BlueprintCallable, Category = "Odin|Audio Pipeline")
bool ClearPosition(FOdinChannelMask ChannelMask);

Parameter	Type	Description
`ChannelMask`	`FOdinChannelMask`	audio layer

Returns bool – true if successful

note

this does not reset the position to the origin while leaving the channel active. Use SetPosition instead if the channel should keep transmitting with a unused position.

Pop

Blueprint: Pop Datagram

Runs the audio pipeline on the pushed samples and returns the next encoded voice packet (datagram). Only needed if you drive the encoder yourself instead of linking it to a room.

UFUNCTION(BlueprintCallable, Category = "Odin|Audio Pipeline")
int32 Pop(TArray<uint8>& Datagram);

Parameter	Type	Description
`Datagram`	`TArray<uint8>&`	buffer

Returns int32 – bytes written to buffer or 0

note

Will trigger processing of the audio pipeline and returns if processing is done

Push

Overload 1

Blueprint: Push Samples

Pushes raw audio samples (32-bit float, interleaved if stereo) into the encoder. The pipeline processes them on the next Pop Datagram. Only needed if you feed the encoder yourself instead of using an audio generator.

UFUNCTION(BlueprintCallable, Category = "Odin|Audio Pipeline")
int32 Push(TArray<float> Samples);

Parameter	Type	Description
`Samples`	`TArray<float>`	audio data

Returns int32 – samples send to encoder or 0

Overload 2

Set samples to process

int32 Push(float* Samples, int32 Count);

Parameter	Type	Description
`Samples`	`float*`	audio data
`Count`	`int32`	sample num

Returns int32 – samples send to encoder or 0

note

fill encoder with samples

SetEchoCancellationProcessingDelay

Blueprint: Set Echo Cancellation Processing Delay

The delay parameter is used to align the reverse stream processing with the forward (capture) stream.

UFUNCTION(BlueprintCallable, Category = "Odin|Audio Pipeline")
void SetEchoCancellationProcessingDelay(int32 DelayInMs = 15);

Parameter	Type	Description
`DelayInMs`	`int32`	Delay in Milliseconds. Default: `15`.

note

The delay can be expressed as:

delay = (t_render - t_analyze) + (t_process - t_capture)

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.

GetNumSampleSize

Const · Inline

Get num based on samplerate and channels

int32 GetNumSampleSize(const int32 MS = 20) const;

Parameter	Type	Description
`MS`	`const int32`	frame length Default: `20`.

Returns int32 – sample size

GetLinkedRooms

Const · Blueprint: Get Linked Rooms

Get all rooms this encoder currently broadcasts to

UFUNCTION(BlueprintCallable, BlueprintPure, Category = "Odin|Audio Pipeline")
TArray<UOdinRoom*> GetLinkedRooms() const;

Returns TArray<UOdinRoom*> – the rooms currently linked to this encoder

GetHandle

Const · Inline

Get internal handle

OdinEncoder* GetHandle() const;

Returns OdinEncoder* – incomplete handle type or nullptr

note

OdinEncoder operations are thread-safe and the same encoder handle may be accessed concurrently from multiple threads.

SetHandle

Replace internal handle object

void SetHandle(OdinEncoder* handle);

Parameter	Type	Description
`handle`	`OdinEncoder*`	internal handle

Properties

AudioGenerator

Blueprint: Get

The audio generator the encoder reads from, if any.

UPROPERTY(BlueprintReadOnly, Category = "Odin|Audio Capture")
UAudioGenerator* AudioGenerator = nullptr;

PeerId

Blueprint: Get

The peer ID the encoder was created with.

UPROPERTY(BlueprintReadOnly, Category = "Odin")
int64 PeerId;

SampleRate

Blueprint: Get

Sample rate of the audio the encoder expects.

UPROPERTY(BlueprintReadOnly, Category = "Odin")
int32 SampleRate = 48000;

bStereo

Blueprint: Get

True if the encoder expects interleaved stereo audio.

UPROPERTY(BlueprintReadOnly, Category = "Odin")
bool bStereo = false;

Events

OnAudioEventCallbackBP

Blueprint: On Audio Event (Encoder)

A callback invoked when the encoder reports one or more audio events.

UPROPERTY(BlueprintAssignable, Category = "Odin|Audio Pipeline|Events")
FOdinEncoderAudioEventCallbackDelegate OnAudioEventCallbackBP;

Signature: FOdinEncoderAudioEventCallbackDelegate void(UOdinEncoder* encoder, EOdinAudioEvents filter) (multicast)

warning

Please remember to start listening by calling SetAudioEventHandler!

Overview​

Functions​

Properties​

Functions​

ConstructEncoder​

CreateEncoder​

ConstructEncoderEx​

CreateEncoderEx​

FreeEncoder​

FreeEncoderHandle​

GetOrCreateEncoderPipeline​

GetOrCreatePipeline​

GetIsSilent​

SetAudioEventHandler​

SetAudioGenerator​

SetPosition​

SetPositions​

ClearPosition​

Pop​

Push​

SetEchoCancellationProcessingDelay​

GetNumSampleSize​

GetLinkedRooms​

GetHandle​

SetHandle​

Properties​

AudioGenerator​

PeerId​

SampleRate​

bStereo​

Events​

OnAudioEventCallbackBP​

Overview

Functions

Properties

Functions

ConstructEncoder

CreateEncoder

ConstructEncoderEx

CreateEncoderEx

FreeEncoder

FreeEncoderHandle

GetOrCreateEncoderPipeline

GetOrCreatePipeline

GetIsSilent

SetAudioEventHandler

SetAudioGenerator

SetPosition

SetPositions

ClearPosition

Pop

Push

SetEchoCancellationProcessingDelay

GetNumSampleSize

GetLinkedRooms

GetHandle

SetHandle

Properties

AudioGenerator

PeerId

SampleRate

bStereo

Events

OnAudioEventCallbackBP