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

#import <ZDKAudioEndpointControl.h>

Inheritance diagram for <ZDKAudioEndpointControl>:

Instance Methods
(ZDKAutomaticGainControlType)	- getAutomaticGainControlMode
	Gets the configured Automatic Gain Control (AGC) filter working mode. More...

(float)	- getAutomaticGainControlGain
	Gets the configured Automatic Gain Control (AGC) fixed gain. More...

(id< ZDKResult >)	- setAutomaticGainControlMode:gain:
	Configures the Automatic Gain Control (AGC) filter working mode. More...

(id< ZDKResult >)	- hostApi:
	Configures the audio host API to be used. More...

(id< ZDKResult >)	- resampler:
	Configures the audio resampler to be used. More...

(id< ZDKAudioDevice > _Nullable)	- getDeviceByName:
	Gets an audio device with the given name if exists, otherwise - nullptr. More...

(id< ZDKAudioDevice > _Nullable)	- getCurrentInputDevice
	Gets the selected input audio device. More...

(id< ZDKResult >)	- setCurrentInputDevice:
	Select the input audio device. More...

(id< ZDKAudioDevice > _Nullable)	- getCurrentOutputDevice
	Gets the selected output audio device. More...

(id< ZDKResult >)	- setCurrentOutputDevice:
	Select the output audio device. More...

(id< ZDKAudioDevice > _Nullable)	- getCurrentRingDevice
	Gets the selected ringing audio device. More...

(id< ZDKResult >)	- setCurrentRingDevice:
	Select the ringing audio device. More...

(id< ZDKSound > _Nullable)	- addSoundFromMemory:length:sampleLen:frequency:repeat:pauseMs:
	Load a sound from a memory buffer. More...

(id< ZDKSound > _Nullable)	- addSoundFromFile:fileFormat:repeat:pauseMs:
	Load a sound from a file. More...

(id< ZDKResult >)	- startSound:outputType:
	Start playback of a sound. More...

(id< ZDKResult >)	- stopSound:outputType:
	Stops playback of a sound. More...

(id< ZDKResult >)	- startPlayback:monitorDevice:
	Starts playback over the current call. More...

(id< ZDKResult >)	- stopPlayback
	Stops any playback. More...

(id< ZDKResult >)	- setCallRecordingNotifySound:monitorDevice:
	Sets the sound to be played over the current call on every recording start. More...

(id< ZDKResult >)	- muteInput:
	Mute or unmute the input device/microphone. More...

(id< ZDKResult >)	- muteOutput:
	Mute or unmute the output device/speaker. More...

(void)	- addStatusListener:
	Adds audio events listener. More...

(void)	- dropStatusListener:
	Drops audio events listener. More...

(NSString *)	- handlesDescription

Instance Methods inherited from <ZDKZHandle>
(long int)	- handle

(void)	- initialize

(void)	- releaseReference

(NSString *)	- handlesDescription

Properties
ZDKAudioRoutingEndpoint	audioEndpoint
	Configures the audio routing endpoint to be used. More...

double	micLevel
	Configures the audio input/microphone level. More...

double	outputLevel
	Configures the audio output level. More...

double	ringLevel
	Configures the audio ringing level. More...

ZDKEchoCancellationType	echoCancellation
	Configures the acoustic echo cancellation working mode. More...

BOOL	highPassFilter
	Controls the High Pass filter. More...

float	preAmplifier
	Controls the Pre Amplifier. More...

BOOL	noiseSuppression
	Controls the Noise Suppression filter. More...

ZDKAudioSourcePresetType	audioSourcePreset
	Configures the Audio Source Recorder Preset. More...

NSArray< id< ZDKAudioDevice > > *	audioDevices
	Gets a list with all available audio devices. More...

BOOL	micBoost
	Controls the microphone boost option. More...

BOOL	enableFixedSpeakerGain
	Enables or disables the fixed gain on the audio output. More...

double	fixedSpeakerGain
	Configures the fixed gain on the audio output. More...

Detailed Description

Audio endpoint's main entry point.

Entry point for controlling the audio endpoint

Method Documentation

◆ addSoundFromFile:fileFormat:repeat:pauseMs:

- (id< ZDKSound > _Nullable) addSoundFromFile:	(NSString *)	filePath
fileFormat:	(ZDKAudioFileFormat)	fileFormat
repeat:	(BOOL)	repeat
pauseMs:	(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]	filePath	Name of the file to load from, UTF-8
[in]	fileFormat	Type of the file to load from - !!!currently limited only to WAV!!!
[in]	repeat	1/TRUE if the sound should be looped when played
[in]	pauseMs	If 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: ZDKSound, AudioFileFormat, addSoundFromMemory()

◆ addSoundFromMemory:length:sampleLen:frequency:repeat:pauseMs:

- (id< ZDKSound > _Nullable) addSoundFromMemory:	(unsigned char *)	data
length:	(int)	length
sampleLen:	(int)	sampleLen
frequency:	(int)	frequency
repeat:	(BOOL)	repeat
pauseMs:	(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]	data	The samples to copy
[in]	length	Size of the data to be coppied in bytes
[in]	sampleLen	Size of a sample in bytes (must be 2)
[in]	frequency	Frequency of the sound in Hz (must be 8000)
[in]	repeat	1/TRUE if the sound should be looped when played
[in]	pauseMs	If 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: ZDKSound, AudioFileFormat, addSoundFromFile()

◆ addStatusListener:

- (void) addStatusListener: (id< ZDKAudioEventsHandler >) value

Adds audio events listener.

Parameters

[in] value The audio events handler

See also: ZDKAudioEventsHandler

◆ dropStatusListener:

- (void) dropStatusListener: (id< ZDKAudioEventsHandler >) value

Drops audio events listener.

Parameters

[in] value The audio events handler

See also: ZDKAudioEventsHandler

◆ getAutomaticGainControlGain

- (float) 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

- (ZDKAutomaticGainControlType) 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

- (id< ZDKAudioDevice > _Nullable) getCurrentInputDevice

Gets the selected input audio device.

Returns: The currently selected input audio device

See also: ZDKAudioDevice

◆ getCurrentOutputDevice

- (id< ZDKAudioDevice > _Nullable) getCurrentOutputDevice

Gets the selected output audio device.

Returns: The currently selected output audio device

See also: ZDKAudioDevice

◆ getCurrentRingDevice

- (id< ZDKAudioDevice > _Nullable) getCurrentRingDevice

Gets the selected ringing audio device.

Returns: The currently selected ringing audio device

See also: ZDKAudioDevice

◆ getDeviceByName:

- (id< ZDKAudioDevice > _Nullable) getDeviceByName: (NSString *) name

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

Parameters

[in] name The name of the audio device to be retrieved

Returns: The audio device with the specified name

See also: ZDKAudioDevice

◆ handlesDescription

- (NSString *) handlesDescription

Reimplemented from <ZDKZHandle>.

◆ hostApi:

- (id< ZDKResult >) hostApi: (ZDKHostAPI) value

Configures the audio host API to be used.

Parameters

[in] value The host API

Returns: Result of the invocation

See also: ZDKResult

◆ muteInput:

- (id< ZDKResult >) 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:

- (id< ZDKResult >) 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:

- (id< ZDKResult >) resampler: (ZDKAudioResampler) 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] value The audio resampler type

Returns: Result of the invocation

See also: AudioResampler, ZDKResult

◆ setAutomaticGainControlMode:gain:

- (id< ZDKResult >) setAutomaticGainControlMode:	(ZDKAutomaticGainControlType)	type
gain:	(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]	type	The AGC mode
[in]	gain	The 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, ZDKResult, AutomaticGainControlType

◆ setCallRecordingNotifySound:monitorDevice:

- (id< ZDKResult >) setCallRecordingNotifySound:	(id< ZDKSound >)	sound
monitorDevice:	(ZDKAudioOutputDeviceType)	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]	sound	The sound to play over the network
[in]	monitorDevice	Monitoring device

Returns: Result of the setting

See also: addSoundFromFile(), addSoundFromMemory(), startPlayback(), - stopPlayback

◆ setCurrentInputDevice:

- (id< ZDKResult >) setCurrentInputDevice: (id< ZDKAudioDevice >) device

Select the input audio device.

Parameters

[in] device The input device to be selected

Returns: Result of the selection

See also: ZDKAudioDevice, ZDKResult

◆ setCurrentOutputDevice:

- (id< ZDKResult >) setCurrentOutputDevice: (id< ZDKAudioDevice >) device

Select the output audio device.

Parameters

[in] device The output device to be selected

Returns: Result of the selection

See also: ZDKAudioDevice, ZDKResult

◆ setCurrentRingDevice:

- (id< ZDKResult >) setCurrentRingDevice: (id< ZDKAudioDevice >) device

Select the ringing audio device.

Parameters

[in] device The ringing device to be selected

Returns: Result of the selection

See also: ZDKAudioDevice, ZDKResult

◆ startPlayback:monitorDevice:

- (id< ZDKResult >) startPlayback:	(id< ZDKSound >)	sound
monitorDevice:	(ZDKAudioOutputDeviceType)	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]	sound	The sound to play over the network
[in]	monitorDevice	Monitoring device - optional local output device to play the sound

Returns: Result of the playback

See also: startSound(), - stopPlayback

◆ startSound:outputType:

- (id< ZDKResult >) startSound:	(id< ZDKSound >)	sound
outputType:	(ZDKAudioOutputDeviceType)	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]	sound	The sound to be played
[in]	outputType	The output device to play the sound

Returns: Result of the playback

See also: setCurrentOutputDevice(), setCurrentRingDevice(), addSoundFromFile(), addSoundFromMemory(), stopSound(), startPlayback()

◆ stopPlayback

- (id< ZDKResult >) stopPlayback

Stops any playback.

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

Returns: Result of the stop

See also: startPlayback()

◆ stopSound:outputType:

- (id< ZDKResult >) stopSound:	(id< ZDKSound >)	sound
outputType:	(ZDKAudioOutputDeviceType)	outputType

Stops playback of a sound.

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

Parameters

[in]	sound	Sound to stop playing
[in]	outputType	The output device to play the sound

Returns: Result of the stop

See also: startSound()

Property Documentation

◆ audioDevices

- (NSArray<id<ZDKAudioDevice> >*) audioDevices

readnonatomicassign

Gets a list with all available audio devices.

Returns: List with all available audio devices

See also: ZDKAudioDevice

◆ audioEndpoint

- (ZDKAudioRoutingEndpoint) audioEndpoint

readwritenonatomicassign

Configures the audio routing endpoint to be used.

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

Parameters

[in] value The audio routing endpoint

See also: AudioRoutingEndpoint

◆ audioSourcePreset

- (ZDKAudioSourcePresetType) audioSourcePreset

readwritenonatomicassign

Configures the Audio Source Recorder Preset.

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

Parameters

[in] value The audio source preset

See also: AudioSourcePresetType

◆ echoCancellation

- (ZDKEchoCancellationType) echoCancellation

readwritenonatomicassign

Configures the acoustic echo cancellation working mode.

Default is enabled in software mode.

Parameters

[in] value The acoustic echo cancellation mode

See also: EchoCancellationType

◆ enableFixedSpeakerGain

- (BOOL) enableFixedSpeakerGain

readwritenonatomicassign

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

readwritenonatomicassign

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] value Gain in dB

See also: enableFixedSpeakerGain()

◆ highPassFilter

- (BOOL) highPassFilter

readwritenonatomicassign

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

readwritenonatomicassign

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

readwritenonatomicassign

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] value The volume setting for the input device between 0.0 and 1.0

See also: outputLevel(), ringLevel()

◆ noiseSuppression

- (BOOL) noiseSuppression

readwritenonatomicassign

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

readwritenonatomicassign

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] value The volume setting for the output device between 0.0 and 1.0

See also: micLevel(), ringLevel()

◆ preAmplifier

- (float) preAmplifier

readwritenonatomicassign

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] value The amount of the fixed gain done by the pre amplifier.

◆ ringLevel

- (double) ringLevel

readwritenonatomicassign

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] value The volume setting for the ringing device between 0.0 and 1.0

See also: micLevel(), outputLevel()

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

Controllers/ZDKAudioEndpointControl.h

Instance Methods

Properties

Detailed Description

Method Documentation

◆ addSoundFromFile:fileFormat:repeat:pauseMs:

◆ addSoundFromMemory:length:sampleLen:frequency:repeat:pauseMs:

◆ addStatusListener:

◆ dropStatusListener:

◆ getAutomaticGainControlGain

◆ getAutomaticGainControlMode

◆ getCurrentInputDevice

◆ getCurrentOutputDevice

◆ getCurrentRingDevice

◆ getDeviceByName:

◆ handlesDescription

◆ hostApi:

◆ muteInput:

◆ muteOutput:

◆ resampler:

◆ setAutomaticGainControlMode:gain:

◆ setCallRecordingNotifySound:monitorDevice:

◆ setCurrentInputDevice:

◆ setCurrentOutputDevice:

◆ setCurrentRingDevice:

◆ startPlayback:monitorDevice:

◆ startSound:outputType:

◆ stopPlayback

◆ stopSound:outputType:

Property Documentation

◆ audioDevices

◆ audioEndpoint

◆ audioSourcePreset

◆ echoCancellation

◆ enableFixedSpeakerGain

◆ fixedSpeakerGain

◆ highPassFilter

◆ micBoost

◆ micLevel

◆ noiseSuppression

◆ outputLevel

◆ preAmplifier

◆ ringLevel