zdk.net
Public Member Functions | Public Attributes | Properties | List of all members
ZDK_NET::AudioEndpointControl Class Reference

Audio endpoint's main entry point. More...

#include <AudioEndpointControl.h>

Inheritance diagram for ZDK_NET::AudioEndpointControl:
ZDK_NET::ZHandle

Public Member Functions

 AudioEndpointControl (ZDK::Shared::AudioEndpointControl src)
 
ZDK_NET::AutomaticGainControlType GetAutomaticGainControlMode ()
 Gets the configured Automatic Gain Control (AGC) filter working mode. More...
 
float GetAutomaticGainControlGain ()
 Gets the configured Automatic Gain Control (AGC) fixed gain. More...
 
ZDK_NET::ResultSetAutomaticGainControlMode (ZDK_NET::AutomaticGainControlType type, float gain)
 Configures the Automatic Gain Control (AGC) filter working mode. More...
 
ZDK_NET::ResultHostApi (ZDK_NET::HostAPI value)
 Configures the audio host API to be used. More...
 
ZDK_NET::ResultResampler (ZDK_NET::AudioResampler value)
 Configures the audio resampler to be used. More...
 
ZDK_NET::AudioDeviceGetDeviceByName (System::String^ name)
 Gets an audio device with the given name if exists, otherwise - nullptr. More...
 
ZDK_NET::AudioDeviceGetCurrentInputDevice ()
 Gets the selected input audio device. More...
 
ZDK_NET::ResultSetCurrentInputDevice (ZDK_NET::AudioDevice^ device)
 Select the input audio device. More...
 
ZDK_NET::AudioDeviceGetCurrentOutputDevice ()
 Gets the selected output audio device. More...
 
ZDK_NET::ResultSetCurrentOutputDevice (ZDK_NET::AudioDevice^ device)
 Select the output audio device. More...
 
ZDK_NET::AudioDeviceGetCurrentRingDevice ()
 Gets the selected ringing audio device. More...
 
ZDK_NET::ResultSetCurrentRingDevice (ZDK_NET::AudioDevice^ device)
 Select the ringing audio device. More...
 
ZDK_NET::SoundAddSoundFromMemory (unsigned char *data, int length, int sampleLen, int frequency, bool repeat, int pauseMs)
 Load a sound from a memory buffer. More...
 
ZDK_NET::SoundAddSoundFromFile (System::String^ filePath, ZDK_NET::AudioFileFormat fileFormat, bool repeat, int pauseMs)
 Load a sound from a file. More...
 
ZDK_NET::ResultStartSound (ZDK_NET::Sound^ sound, ZDK_NET::AudioOutputDeviceType outputType)
 Start playback of a sound. More...
 
ZDK_NET::ResultStopSound (ZDK_NET::Sound^ sound, ZDK_NET::AudioOutputDeviceType outputType)
 Stops playback of a sound. More...
 
ZDK_NET::ResultStartPlayback (ZDK_NET::Sound^ sound, ZDK_NET::AudioOutputDeviceType monitorDevice)
 Starts playback over the current call. More...
 
ZDK_NET::ResultStopPlayback ()
 Stops any playback. More...
 
ZDK_NET::ResultSetCallRecordingNotifySound (ZDK_NET::Sound^ sound, ZDK_NET::AudioOutputDeviceType monitorDevice)
 Sets the sound to be played over the current call on every recording start. More...
 
ZDK_NET::ResultMuteInput (bool value)
 Mute or unmute the input device/microphone. More...
 
ZDK_NET::ResultMuteOutput (bool value)
 Mute or unmute the output device/speaker. More...
 
void AddStatusListener (ZDK_NET::AudioEventsHandler^ value)
 Adds audio events listener. More...
 
void DropStatusListener (ZDK_NET::AudioEventsHandler^ value)
 Drops audio events listener. More...
 
virtual long long Handle () override
 
virtual void Initialize () override
 
virtual void ReleaseReference () override
 

Public Attributes

ZDK::IAudioEndpointControl * cppRef = nullptr
 

Properties

ZDK_NET::AudioRoutingEndpoint AudioEndpoint [get, set]
 Configures the audio routing endpoint to be used. More...
 
double MicLevel [get, set]
 Configures the audio input/microphone level. More...
 
double OutputLevel [get, set]
 Configures the audio output level. More...
 
double RingLevel [get, set]
 Configures the audio ringing level. More...
 
ZDK_NET::EchoCancellationType EchoCancellation [get, set]
 Configures the acoustic echo cancellation working mode. More...
 
bool HighPassFilter [get, set]
 Controls the High Pass filter. More...
 
float PreAmplifier [get, set]
 Controls the Pre Amplifier. More...
 
bool NoiseSuppression [get, set]
 Controls the Noise Suppression filter. More...
 
ZDK_NET::AudioSourcePresetType AudioSourcePreset [get, set]
 Configures the Audio Source Recorder Preset. More...
 
List< AudioDevice^>^ AudioDevices [get]
 Gets a list with all available audio devices. More...
 
bool MicBoost [get, set]
 Controls the microphone boost option. More...
 
bool EnableFixedSpeakerGain [get, set]
 Enables or disables the fixed gain on the audio output. More...
 
double FixedSpeakerGain [get, set]
 Configures the fixed gain on the audio output. More...
 

Detailed Description

Audio endpoint's main entry point.

Entry point for controlling the audio endpoint

Member Function Documentation

◆ AddSoundFromFile()

ZDK_NET::Sound ^ ZDK_NET::AudioEndpointControl::AddSoundFromFile ( System::String^  filePath,
ZDK_NET::AudioFileFormat  fileFormat,
bool  repeat,
int  pauseMs 
)

Load a sound from a file.

Loads a sound from a file. The sound will inherit the file's format with the only exception that 8-bit, 24-bit and 32-bit PCM samples will be automatically converted to 16-bit while the sound is being loaded.

The frequency and channel count will be left unchanged.

While playing the resulting sound through StartSound() or StartPlayback() it can undergo resampling (to match frequencies) or remixing (to match the channels) based on the current audio settings.

Parameters
[in]filePathName of the file to load from, UTF-8
[in]fileFormatType of the file to load from - !!!currently limited only to WAV!!!
[in]repeat1/TRUE if the sound should be looped when played
[in]pauseMsIf the sound is to be looped, the amount of silence in milliseconds between each loop
Returns
The newly loaded sound or NULL in case of error
See also
Sound, AudioFileFormat, AddSoundFromMemory()

◆ AddSoundFromMemory()

ZDK_NET::Sound ^ ZDK_NET::AudioEndpointControl::AddSoundFromMemory ( unsigned char *  data,
int  length,
int  sampleLen,
int  frequency,
bool  repeat,
int  pauseMs 
)

Load a sound from a memory buffer.

Creates a sound structure and copies the provided samples into its buffers.

While playing the resulting sound through StartSound() or StartPlayback() it can undergo resampling (to match frequencies) or remixing (to match the channels) based on the current audio settings.

Parameters
[in]dataThe samples to copy
[in]lengthSize of the data to be coppied in bytes
[in]sampleLenSize of a sample in bytes (must be 2)
[in]frequencyFrequency of the sound in Hz (must be 8000)
[in]repeat1/TRUE if the sound should be looped when played
[in]pauseMsIf the sound is to be looped, the amount of silence in milliseconds between each loop
Returns
The newly loaded sound or NULL in case of error
See also
Sound, AudioFileFormat, AddSoundFromFile()

◆ AddStatusListener()

void ZDK_NET::AudioEndpointControl::AddStatusListener ( ZDK_NET::AudioEventsHandler value)

Adds audio events listener.

Parameters
[in]valueThe audio events handler
See also
AudioEventsHandler

◆ DropStatusListener()

void ZDK_NET::AudioEndpointControl::DropStatusListener ( ZDK_NET::AudioEventsHandler value)

Drops audio events listener.

Parameters
[in]valueThe audio events handler
See also
AudioEventsHandler

◆ GetAutomaticGainControlGain()

float ZDK_NET::AudioEndpointControl::GetAutomaticGainControlGain ( )

Gets the configured Automatic Gain Control (AGC) fixed gain.

The additional fixed gain (defaults to 0.f) added when using SoftwareDigitalV2 or SoftwareHybrid mode. It can have values between 0.f and 49.f db. The value is positive but it is interpreted as negative.

Returns
The AGC additional fixed gain
See also
GetAutomaticGainControlMode(), SetAutomaticGainControlMode()

◆ GetAutomaticGainControlMode()

ZDK_NET::AutomaticGainControlType ZDK_NET::AudioEndpointControl::GetAutomaticGainControlMode ( )

Gets the configured Automatic Gain Control (AGC) filter working mode.

Works on all platforms. For Desktop platforms the AGC includes both analog and digital adaptive control by controlling the analog gain for the microphone device. For mobile platforms only an adaptive digital gain is applied to the audio coming from the microphone.

The GUI is advised to bar the user from manipulating the hardware gain of the microphone. The GUI can also poll the audio input level via MicLevel() once or twice a second.

Returns
The AGC mode
See also
GetAutomaticGainControlGain(), SetAutomaticGainControlMode(), AutomaticGainControlType

◆ GetCurrentInputDevice()

ZDK_NET::AudioDevice ^ ZDK_NET::AudioEndpointControl::GetCurrentInputDevice ( )

Gets the selected input audio device.

Returns
The currently selected input audio device
See also
AudioDevice

◆ GetCurrentOutputDevice()

ZDK_NET::AudioDevice ^ ZDK_NET::AudioEndpointControl::GetCurrentOutputDevice ( )

Gets the selected output audio device.

Returns
The currently selected output audio device
See also
AudioDevice

◆ GetCurrentRingDevice()

ZDK_NET::AudioDevice ^ ZDK_NET::AudioEndpointControl::GetCurrentRingDevice ( )

Gets the selected ringing audio device.

Returns
The currently selected ringing audio device
See also
AudioDevice

◆ GetDeviceByName()

ZDK_NET::AudioDevice ^ ZDK_NET::AudioEndpointControl::GetDeviceByName ( System::String^  name)

Gets an audio device with the given name if exists, otherwise - nullptr.

Parameters
[in]nameThe name of the audio device to be retrieved
Returns
The audio device with the specified name
See also
AudioDevice

◆ HostApi()

ZDK_NET::Result ^ ZDK_NET::AudioEndpointControl::HostApi ( ZDK_NET::HostAPI  value)

Configures the audio host API to be used.

Parameters
[in]valueThe host API
Returns
Result of the invocation
See also
Result

◆ MuteInput()

ZDK_NET::Result ^ ZDK_NET::AudioEndpointControl::MuteInput ( bool  value)

Mute or unmute the input device/microphone.

Parameters
[in]value
  • 0 - unmute
  • 1 - mute
Returns
Result of the mute
See also
MuteOutput()

◆ MuteOutput()

ZDK_NET::Result ^ ZDK_NET::AudioEndpointControl::MuteOutput ( bool  value)

Mute or unmute the output device/speaker.

Parameters
[in]value
  • 0 - unmute
  • 1 - mute
Returns
Result of the mute
See also
MuteOutput()

◆ Resampler()

ZDK_NET::Result ^ ZDK_NET::AudioEndpointControl::Resampler ( ZDK_NET::AudioResampler  value)

Configures the audio resampler to be used.

Selects the resampler to be used by the audio engine. In most cases the native sampling rate of the audio hardware will not match the sampling rate of the active VoIP call. In this case a resampler is employed to do sample rate conversion. Different methods produce different quality and use algorithms of different complexity resulting in different CPU usage. In some cases the resampler cannot be selected.

The default behavior is the audio driver select the reampler.

Parameters
[in]valueThe audio resampler type
Returns
Result of the invocation
See also
AudioResampler, Result

◆ SetAutomaticGainControlMode()

ZDK_NET::Result ^ ZDK_NET::AudioEndpointControl::SetAutomaticGainControlMode ( ZDK_NET::AutomaticGainControlType  type,
float  gain 
)

Configures the Automatic Gain Control (AGC) filter working mode.

Works on all platforms. For Desktop platforms the AGC includes both analog and digital adaptive control by controlling the analog gain for the microphone device. For mobile platforms only an adaptive digital gain is applied to the audio coming from the microphone.

The GUI is advised to bar the user from manipulating the hardware gain of the microphone. The GUI can also poll the audio input level via MicLevel() once or twice a second.

Parameters
[in]typeThe AGC mode
[in]gainThe additional fixed gain added when using SoftwareDigitalV2 or SoftwareHybrid mode. It can have values between 0.f and 49.f db. The value is positive but it is interpreted as negative.
Returns
Result of the invocation
See also
GetAutomaticGainControlMode(), GetAutomaticGainControlGain(), Result, AutomaticGainControlType

◆ SetCallRecordingNotifySound()

ZDK_NET::Result ^ ZDK_NET::AudioEndpointControl::SetCallRecordingNotifySound ( ZDK_NET::Sound sound,
ZDK_NET::AudioOutputDeviceType  monitorDevice 
)

Sets the sound to be played over the current call on every recording start.

Sets the sound to be played back to the remote peer(s) (instead of the microphone input) on every start of call recording. (The sound must be added beforehand with AddSoundFromFile() or AddSoundFromMemory()). Optionally plays the sound on the output/ringing device (this is the "monitor" device).

When the whole sound has been played out the microphone will be reconnected again.

All changes made to the microphone during the playback will be applied after normal operation has been resumed.

Parameters
[in]soundThe sound to play over the network
[in]monitorDeviceMonitoring device
Returns
Result of the setting
See also
AddSoundFromFile(), AddSoundFromMemory(), StartPlayback(), StopPlayback()

◆ SetCurrentInputDevice()

ZDK_NET::Result ^ ZDK_NET::AudioEndpointControl::SetCurrentInputDevice ( ZDK_NET::AudioDevice device)

Select the input audio device.

Parameters
[in]deviceThe input device to be selected
Returns
Result of the selection
See also
AudioDevice, Result

◆ SetCurrentOutputDevice()

ZDK_NET::Result ^ ZDK_NET::AudioEndpointControl::SetCurrentOutputDevice ( ZDK_NET::AudioDevice device)

Select the output audio device.

Parameters
[in]deviceThe output device to be selected
Returns
Result of the selection
See also
AudioDevice, Result

◆ SetCurrentRingDevice()

ZDK_NET::Result ^ ZDK_NET::AudioEndpointControl::SetCurrentRingDevice ( ZDK_NET::AudioDevice device)

Select the ringing audio device.

Parameters
[in]deviceThe ringing device to be selected
Returns
Result of the selection
See also
AudioDevice, Result

◆ StartPlayback()

ZDK_NET::Result ^ ZDK_NET::AudioEndpointControl::StartPlayback ( ZDK_NET::Sound sound,
ZDK_NET::AudioOutputDeviceType  monitorDevice 
)

Starts playback over the current call.

Starts playing back the sound to the remote peer(s) (if there are active calls) instead of the microphone input. Microphone input will be discared during the playback. Optionally plays the sound on the output/ringing device (this is the "monitor" device). When the whole sound has been played out the microphone will be reconnected again. All changes made to the microphone during the playback will be applied after normal operation has been resumed.

Parameters
[in]soundThe sound to play over the network
[in]monitorDeviceMonitoring device - optional local output device to play the sound
Returns
Result of the playback
See also
StartSound(), StopPlayback()

◆ StartSound()

ZDK_NET::Result ^ ZDK_NET::AudioEndpointControl::StartSound ( ZDK_NET::Sound sound,
ZDK_NET::AudioOutputDeviceType  outputType 
)

Start playback of a sound.

Start playing the sound on one of the two output devices (either the selected output device or the selected ringing device). Use SetCurrentOutputDevice() and SetCurrentRingDevice() to select the output devices. The sound will be played on the device and will not be sent over the communication channel (see StartPlayback()).

Parameters
[in]soundThe sound to be played
[in]outputTypeThe output device to play the sound
Returns
Result of the playback
See also
SetCurrentOutputDevice(), SetCurrentRingDevice(), AddSoundFromFile(), AddSoundFromMemory(), StopSound(), StartPlayback()

◆ StopPlayback()

ZDK_NET::Result ^ ZDK_NET::AudioEndpointControl::StopPlayback ( )

Stops any playback.

Stops any playback and monitored sound immediately if there is such.

Returns
Result of the stop
See also
StartPlayback()

◆ StopSound()

ZDK_NET::Result ^ ZDK_NET::AudioEndpointControl::StopSound ( ZDK_NET::Sound sound,
ZDK_NET::AudioOutputDeviceType  outputType 
)

Stops playback of a sound.

Stops playing the sound. Must be called with the same parameters as StartSound().

Parameters
[in]soundSound to stop playing
[in]outputTypeThe output device to play the sound
Returns
Result of the stop
See also
StartSound()

Property Documentation

◆ AudioDevices

List< AudioDevice^>^ ZDK_NET::AudioEndpointControl::AudioDevices
get

Gets a list with all available audio devices.

Returns
List with all available audio devices
See also
AudioDevice

◆ AudioEndpoint

ZDK_NET:: AudioRoutingEndpoint ZDK_NET::AudioEndpointControl::AudioEndpoint
getset

Configures the audio routing endpoint to be used.

!!!NOT MPLEMENTED!!! The ZDK does not provide a mean for controlling the audio routing!

Parameters
[in]valueThe audio routing endpoint
See also
AudioRoutingEndpoint

◆ AudioSourcePreset

ZDK_NET:: AudioSourcePresetType ZDK_NET::AudioEndpointControl::AudioSourcePreset
getset

Configures the Audio Source Recorder Preset.

Currently used only for Android's OpenSLES, but this can change in the future.

Parameters
[in]valueThe audio source preset
See also
AudioSourcePresetType

◆ EchoCancellation

ZDK_NET:: EchoCancellationType ZDK_NET::AudioEndpointControl::EchoCancellation
getset

Configures the acoustic echo cancellation working mode.

Default is enabled in software mode.

Parameters
[in]valueThe acoustic echo cancellation mode
See also
EchoCancellationType

◆ EnableFixedSpeakerGain

bool ZDK_NET::AudioEndpointControl::EnableFixedSpeakerGain
getset

Enables or disables the fixed gain on the audio output.

Enable or disable the fixed speaker gain confgured by SetFixedSpeakerGain(). By default, the gain is not applied.

The filter that applies the gain is using a fixed point calculation (multiplication + shift + saturation checks). It should be very fast but you should not enable the gain unless you have set it to something different than 0.0.

The effect will be immediate. You can call this function at any time after initialization. This means you can enable/disable the gain during a call.

Parameters
[in]value
  • 0 - disable
  • 1 - enable
See also
FixedSpeakerGain()

◆ FixedSpeakerGain

double ZDK_NET::AudioEndpointControl::FixedSpeakerGain
getset

Configures the fixed gain on the audio output.

Configures the gain to be applied when the gain filter is enabled by EnableFixedSpeakerGain().

The gain is expressed in decibels (dB). It can be anything but some values will produce very distorted and loud noise, while others will effectively mute the audio.

Here are some example values, but please do tests and choose what best suits your case. The precision of the fixed-point calculation is 0.001.

+20.0 dB: Huge audio boost. Almost certain to produce loud noise unless the input is very quiet. Don't use values above this. +6.0 dB: Moderate boost +2.0 dB: Small boost 0.0 dB: No boost -6.0 dB: Moderate decrease in volume. Better use the hardware volume controls. -100 dB: Almost always will produce complete silence.

If you are familiar with how the audio is processed, here is the filter formula:

gain(s) = s * 10 ^ ( db / 20.0 )

Here gain is the gain filter, s is the sample being processed, db is the gain value in dB. We're using the amplitude forumla because of the way PCM is representing the audio.

As with EnableFixedSpeakerGain(), you can call this function at any time after initialization.

Parameters
[in]valueGain in dB
See also
EnableFixedSpeakerGain()

◆ HighPassFilter

bool ZDK_NET::AudioEndpointControl::HighPassFilter
getset

Controls the High Pass filter.

Enables or disables the High Pass filter. Works on all platforms.

Parameters
[in]value
  • 0 - disable
  • 1 - enable

◆ MicBoost

bool ZDK_NET::AudioEndpointControl::MicBoost
getset

Controls the microphone boost option.

Enables or disables the microphone boost. On some platforms the boost option is controlled via a text field and this might not work properly.

Parameters
[in]value
  • 0 - disable
  • 1 - enable

◆ MicLevel

double ZDK_NET::AudioEndpointControl::MicLevel
getset

Configures the audio input/microphone level.

The volume setting for the input device. Values are between 0.0 (muted) and 1.0 (maximum volume).

Parameters
[in]valueThe volume setting for the input device between 0.0 and 1.0
See also
OutputLevel(), RingLevel()

◆ NoiseSuppression

bool ZDK_NET::AudioEndpointControl::NoiseSuppression
getset

Controls the Noise Suppression filter.

Enables or disables the Noise Suppression filter. Enabled by default. Works on all platforms.

Parameters
[in]value
  • 0 - disable
  • 1 - enable

◆ OutputLevel

double ZDK_NET::AudioEndpointControl::OutputLevel
getset

Configures the audio output level.

The volume setting for the input device. Values are between 0.0 (muted) and 1.0 (maximum volume).

In many cases the ringing device and the output device are the same, so chaning one level will also change and the other.

Parameters
[in]valueThe volume setting for the output device between 0.0 and 1.0
See also
MicLevel(), RingLevel()

◆ PreAmplifier

float ZDK_NET::AudioEndpointControl::PreAmplifier
getset

Controls the Pre Amplifier.

Enables or disables the Pre Amplifier which amplifies the input signal before any other porcessing occurs. Works on all platforms.

The amount of the fixed gain done by the pre amplifier. The gain value is a positive value between 1.f (does nothing) and 49.f db. This value is interpreted as a negative value.

Disabled by default - less than 1.f!

Parameters
[in]valueThe amount of the fixed gain done by the pre amplifier.

◆ RingLevel

double ZDK_NET::AudioEndpointControl::RingLevel
getset

Configures the audio ringing level.

The volume setting for the ringing device. Values are between 0.0 (muted) and 1.0 (maximum volume).

In many cases the ringing device and the output device are the same, so chaning one level will also change and the other.

Parameters
[in]valueThe volume setting for the ringing device between 0.0 and 1.0
See also
MicLevel(), OutputLevel()

The documentation for this class was generated from the following file: