Version: 20 Mar 2024

AudioSink

Class that represents an audio sink used by the MLWebRTC API.

Inherits from:
Sink

Public Fields

CopyRawAudioDataToManagedMemory

Raw audio data received in the OnAudioDataAvailable_NativeCallbackThread delegate should be converted to float samples and copied from unmanaged to managed memory. Audio data received in OnAudioDataAvailable will always be available in managed memory. This is set to true by default. Disable this flag if you experience too many garbage collection invocations for MLAudio.Buffer.Samples & handle the audio data conversion from the unmanaged to managed and from Int to Float yourself.

public bool CopyRawAudioDataToManagedMemory { get; set; }

CurrentServiceStatus

Current status of the underlying audio service. Apps should use this status to determine whether its safe to set the audio attriutes like soundfield parameters and volume.

public ServiceStatus CurrentServiceStatus { get; set; }

Type	Description
ServiceStatus	Status of the underlying Audio Service the buffers are submitted & soundfield attributes applied to.

Mode

Audio buffer notification mode for this AudioSink

public BufferNotifyMode Mode { get; set; }

Type	Description
BufferNotifyMode	Behavior of the sink if audio buffer data is provided to the app in a callback.

Public Methods

AudioSink Create

Creates an initialized AudioSink object.

public static AudioSink Create(
    out MLResult result,
    BufferNotifyMode mode =BufferNotifyMode.None
)

Parameters

Type	Name	Description
out MLResult	result	The MLResult object of the inner platform call(s).
BufferNotifyMode	mode	Behavior of the sink if audio buffer data is provided to the app in a callback.

Returns: An initialized AudioSink object.

override MLResult Destroy

Destroys this audio sink object.

public virtual override MLResult Destroy()

Returns: MLResult.Result will be MLResult.Code.Ok if destroying all handles was successful. MLResult.Result will be MLResult.Code.WebRTCResultInstanceNotCreated if MLWebRTC instance was not created. MLResult.Result will be MLResult.Code.WebRTCResultMismatchingHandle if an incorrect handle was sent.

Reimplements: Destroy

delegate void OnAudioDataAvailableDelegate

Delegate to provide audio buffer data received for this audio sink.

public delegate void OnAudioDataAvailableDelegate(
    MLAudioOutput.Buffer buffer
)

Parameters

Type	Name	Description
MLAudioOutput.Buffer	bufferFormat	Format of the audio buffer
	buffer	Audio buffer

delegate void OnAudioServiceStatusChangedDelegate

Delegate to provide the current audio service status. Apps should use this status to determine whether its safe to set the audio attriutes like soundfield parameters and volume.

public delegate void OnAudioServiceStatusChangedDelegate(
    ServiceStatus status
)

Parameters

Type	Name	Description
ServiceStatus	status	The current status of the audio service

MLResult ResetPosition

Resets the world position of the audio sink for spatialized audio.

public MLResult ResetPosition()

MLResult SetCacheSize

Sets the number of milliseconds of audio that should be cached in the buffers before dropping the packets. Dictates the audio latency when app recovers from lifecycle state transitions like standby & reality. Default is 200ms.

public MLResult SetCacheSize(
    uint millisecondsToCache
)

Parameters

Type	Name	Description
uint	sinkHandle	The handle to the audio sink.
	millisecondsToCache	How many milliseconds worth of audio to cache.

MLResult SetDirectSendLevels

Sets the direct send levels of the audio sink for the specified channel.

public MLResult SetDirectSendLevels(
    MLAudioOutput.SpatialSound.SendLevels sendLevels,
    int channel =-1
)

Parameters

Type	Name	Description
MLAudioOutput.SpatialSound.SendLevels	sendLevels	The send levels of the audio sink.
int	channel	Channel to set this spatialization property for. Passing -1 sets it for all available channels.

MLResult SetDistanceProperties

Sets the distance properties of the audio sink for the specified channel.

public MLResult SetDistanceProperties(
    MLAudioOutput.SpatialSound.DistanceProperties distanceProperties,
    int channel =-1
)

Parameters

Type	Name	Description
MLAudioOutput.SpatialSound.DistanceProperties	distanceProperties	The distance properties of the audio sink.
int	channel	Channel to set this spatialization property for. Passing -1 sets it for all available channels.

MLResult SetOrientation

Sets the world orientation of the audio sink for the specified channel.

public MLResult SetOrientation(
    Quaternion orientation,
    int channel =-1
)

Parameters

Type	Name	Description
Quaternion	orientation	The orientation of the audio sink.
int	channel	Channel to set this spatialization property for. Passing -1 sets it for all available channels.

MLResult SetPosition

Sets the world position of the audio sink for the specified channel.

public MLResult SetPosition(
    Vector3 position,
    int channel =-1
)

Parameters

Type	Name	Description
Vector3	position	The position to set the audio sink to.
int	channel	Channel to set this spatialization property for. Passing -1 sets it for all available channels.

MLResult SetRadiationProperties

Sets the radiation properties of the audio sink for the specified channel.

public MLResult SetRadiationProperties(
    MLAudioOutput.SpatialSound.RadiationProperties radiationProperties,
    int channel =-1
)

Parameters

Type	Name	Description
MLAudioOutput.SpatialSound.RadiationProperties	radiationProperties	The radiation properties of the audio sink.
int	channel	Channel to set this spatialization property for. Passing -1 sets it for all available channels.

MLResult SetRoomSendLevels

Sets the room send levels of the audio sink for the specified channel.

public MLResult SetRoomSendLevels(
    MLAudioOutput.SpatialSound.SendLevels sendLevels,
    int channel =-1
)

Parameters

Type	Name	Description
MLAudioOutput.SpatialSound.SendLevels	sendLevels	The send levels of the audio sink.
int	channel	Channel to set this spatialization property for. Passing -1 sets it for all available channels.

MLResult SetStream

Sets the stream of the audio sink.

public MLResult SetStream(
    MediaStream stream
)

Parameters

Type	Name	Description
MediaStream	stream	The stream to use.

MLResult SetVolume

Sets the volume of the audio sink for the specified channel. The range of the volume is 0 to 8, with 0 for silence, 1 for unity gain, and 8 for 8x gain.

public MLResult SetVolume(
    float volume
)

Parameters

Type	Name	Description
float	volume	The volume of the audio sink.

Protected Methods

SetTrack

Sets the track of the audio sink.

protected virtual override MLResult SetTrack(
    MLWebRTC.MediaStream.Track track
)

Parameters

Type	Name	Description
MLWebRTC.MediaStream.Track	track	The track to use.

Reimplements: SetTrack

Public Events

OnAudioDataAvailable

Delegate invoked on the main thread to provide the audio buffer data for this sink. MLAudio.Buffer.NativeDataPtr is NOT valid for this delegate. Use the managed MLAudio.Buffer.Samples array instead.

public OnAudioDataAvailableDelegate OnAudioDataAvailable()

OnAudioDataAvailable_NativeCallbackThread

Delegate invoked on the native callback thread to provide the audio buffer data for this sink. MLAudio.Buffer.NativeDataPtr is valid for this delegate.

public OnAudioDataAvailableDelegate OnAudioDataAvailable_NativeCallbackThread()

OnAudioServiceStatusChanged

Delegate invoked on the main thread to notify the app about the current status of the underlying audio service. Apps should use this tatus to determine whether its safe to set the audio attriutes like soundfield parameters and volume.

public OnAudioServiceStatusChangedDelegate OnAudioServiceStatusChanged()

Public Enums

BufferNotifyMode

Behavior of the sink if audio buffer data is provided to the app in a callback.

Enumerator	Value	Description
None		Don't provide app with audio buffers, consume them in the underlying lib and play directly on the device.
NotifyAndPlay		Provide the app with audio buffers in a callback, AND also play the audio directly on the device. Ths is useful where apps want to use the buffers to calculate something (like RMS) but not take the responsibility of actually playing the audio.
NotifyOnly		Provide the app with audio buffers in a callback. The underlyin library will NOT play the audio. It is the app's responsibility to submit the audio buffers to the device.

ServiceStatus

Status of the underlying Audio Service the buffers are submitted & soundfield attributes applied to.

Enumerator	Value	Description
Initial		The audio service has been initialized but not ready to accept updates to any attributes (soundfield or volume).
Started		The audio service has started. It is now safe to update the audio attributes (soundfield and volume).
Failed		Audio service has failed. This will cause disruption in audio playback. Audio attributes (soundfield or volume) should not be set after receiving this status update.
Stopped		Audio service has stopped. Audio attributes (soundfield or volume) should not be set after receiving this status update.
Unknown		Audio service status is unknown. Audio attributes (soundfield or volume) should not be set after receiving this status update.

AudioSink

Public Fields​

CopyRawAudioDataToManagedMemory​

CurrentServiceStatus​

Mode​

Public Methods​

AudioSink Create​

override MLResult Destroy​

delegate void OnAudioDataAvailableDelegate​

delegate void OnAudioServiceStatusChangedDelegate​

MLResult ResetPosition​

MLResult SetCacheSize​

MLResult SetDirectSendLevels​

MLResult SetDistanceProperties​

MLResult SetOrientation​

MLResult SetPosition​

MLResult SetRadiationProperties​

MLResult SetRoomSendLevels​

MLResult SetStream​

MLResult SetVolume​

Protected Methods​

SetTrack​

Public Events​

OnAudioDataAvailable​

OnAudioDataAvailable_NativeCallbackThread​

OnAudioServiceStatusChanged​

Public Enums​

BufferNotifyMode​

ServiceStatus​

Public Fields

CopyRawAudioDataToManagedMemory

CurrentServiceStatus

Mode

Public Methods

AudioSink Create

override MLResult Destroy

delegate void OnAudioDataAvailableDelegate

delegate void OnAudioServiceStatusChangedDelegate

MLResult ResetPosition

MLResult SetCacheSize

MLResult SetDirectSendLevels

MLResult SetDistanceProperties

MLResult SetOrientation

MLResult SetPosition

MLResult SetRadiationProperties

MLResult SetRoomSendLevels

MLResult SetStream

MLResult SetVolume

Protected Methods

SetTrack

Public Events

OnAudioDataAvailable

OnAudioDataAvailable_NativeCallbackThread

OnAudioServiceStatusChanged

Public Enums

BufferNotifyMode

ServiceStatus