TeamTalk 5 C-API DLL: Sound Capture and Playback

TeamTalk 5 C-API DLL Version 5.18A

Loading...
Searching...
No Matches
Classes | Macros | Typedefs | Enumerations | Functions
Sound Capture and Playback

This section explains how to record and playback audio in the client instance. More...

## Classes

struct | SoundDevice
| A struct containing the properties of a sound device for either playback or recording. More...
struct | SoundDeviceEffects
| Set up audio effects supported by the sound device. More...
struct | AudioBlock
| An audio block containing the raw audio from a user who was talking. More...

## Macros

#define | TT_SAMPLERATES_MAX 16
#define | TT_SOUNDDEVICE_ID_SHARED_FLAG 0x00000800
| Flag/bit in `nDeviceID` telling if the SoundDevice is a shared version of an existing sound device.
#define | TT_SOUNDDEVICE_ID_MASK 0x000007FF
| Extract sound device ID of `nDeviceID` in SoundDevice by and'ing this value.
#define | TT_SOUNDDEVICE_ID_REMOTEIO 0
| Sound device ID for iOS AudioUnit subtype Remote I/O Unit.
#define | TT_SOUNDDEVICE_ID_VOICEPREPROCESSINGIO (1 | TT_SOUNDDEVICE_ID_SHARED_FLAG)
| Sound device ID for iOS AudioUnit subtype Voice-Processing I/O Unit.
#define | TT_SOUNDDEVICE_ID_OPENSLES_DEFAULT 0
| Sound device ID for Android OpenSL ES default audio device.
#define | TT_SOUNDDEVICE_ID_OPENSLES_VOICECOM 1
| Sound device ID for Android OpenSL ES voice communication mode. This device uses the OpenSL ES' AndroidConfiguration `SL_ANDROID_RECORDING_PRESET_VOICE_COMMUNICATION`.
#define | TT_SOUNDDEVICE_ID_TEAMTALK_VIRTUAL 1978
| Sound device ID for virtual TeamTalk sound device.
#define | TT_LOCAL_USERID 0
| User ID passed to TT_EnableAudioBlockEvent() in order to receive AudioBlock directly from sound input device after joining a channel.
#define | TT_LOCAL_TX_USERID 0x1002
| User ID passed to TT_EnableAudioBlockEvent() in order to receive AudioBlock when voice transmission is activated.
#define | TT_MUXED_USERID 0x1001 /* TT_USERID_MAX + 2 */
| User ID used to identify muxed audio that has been mixed into a single stream.

## Typedefs

typedef enum SoundSystem | SoundSystem
| The supported sound systems.
typedef enum SoundDeviceFeature | SoundDeviceFeature
| Features available on a sound device. Checkout `uSoundDeviceFeatures` on SoundDevice.
typedef UINT32 | SoundDeviceFeatures
| A bitmask of available SoundDeviceFeature. Checkout `uSoundDeviceFeatures` on SoundDevice.
typedef struct SoundDevice | SoundDevice
| A struct containing the properties of a sound device for either playback or recording.
typedef struct SoundDeviceEffects | SoundDeviceEffects
| Set up audio effects supported by the sound device.
typedef enum SoundLevel | SoundLevel
| An enum encapsulation the minimum, maximum and default sound levels for input and output sound devices.
typedef struct AudioBlock | AudioBlock
| An audio block containing the raw audio from a user who was talking.
typedef VOID | TTSoundLoop
| Pointer to a sound loop for testing sound devices created by TT_StartSoundLoopbackTest()

## Enumerations

enum

SoundSystem {
SOUNDSYSTEM_NONE = 0 , SOUNDSYSTEM_WINMM = 1 , SOUNDSYSTEM_DSOUND = 2 , SOUNDSYSTEM_ALSA = 3 ,
SOUNDSYSTEM_COREAUDIO = 4 , SOUNDSYSTEM_WASAPI = 5 , SOUNDSYSTEM_OPENSLES_ANDROID = 7 , SOUNDSYSTEM_AUDIOUNIT = 8 ,
SOUNDSYSTEM_AUDIOUNIT_IOS = SOUNDSYSTEM_AUDIOUNIT , SOUNDSYSTEM_PULSEAUDIO = 10
}

| The supported sound systems. More...

enum

SoundDeviceFeature {
SOUNDDEVICEFEATURE_NONE = 0x0000 , SOUNDDEVICEFEATURE_AEC = 0x0001 , SOUNDDEVICEFEATURE_AGC = 0x0002 , SOUNDDEVICEFEATURE_DENOISE = 0x0004 ,
SOUNDDEVICEFEATURE_3DPOSITION = 0x0008 , SOUNDDEVICEFEATURE_DUPLEXMODE = 0x0010 , SOUNDDEVICEFEATURE_DEFAULTCOMDEVICE = 0x0020
}

| Features available on a sound device. Checkout `uSoundDeviceFeatures` on SoundDevice. More...
enum | SoundLevel { SOUND_VU_MAX = 100 , SOUND_VU_MIN = 0 , SOUND_VOLUME_MAX = 32000 , SOUND_VOLUME_DEFAULT = 1000 , SOUND_VOLUME_MIN = 0 , SOUND_GAIN_MAX = 32000 , SOUND_GAIN_DEFAULT = 1000 , SOUND_GAIN_MIN = 0 }
| An enum encapsulation the minimum, maximum and default sound levels for input and output sound devices. More...

## Functions

TEAMTALKDLL_API TTBOOL | TT_GetDefaultSoundDevices (OUT INT32 *lpnInputDeviceID, OUT INT32 *lpnOutputDeviceID)
| Get the default sound devices.
TEAMTALKDLL_API TTBOOL | TT_GetDefaultSoundDevicesEx (IN SoundSystem nSndSystem, OUT INT32 *lpnInputDeviceID, OUT INT32 *lpnOutputDeviceID)
| Get the default sound devices for the specified sound system.
TEAMTALKDLL_API TTBOOL | TT_GetSoundDevices (IN OUT SoundDevice *lpSoundDevices, IN OUT INT32 *lpnHowMany)
| Retrieve list of sound devices for recording and playback.
TEAMTALKDLL_API TTBOOL | TT_RestartSoundSystem (void)
| Reinitialize sound system (in order to detect new/removed devices).
TEAMTALKDLL_API TTSoundLoop * | TT_StartSoundLoopbackTest (IN INT32 nInputDeviceID, IN INT32 nOutputDeviceID, IN INT32 nSampleRate, IN INT32 nChannels, IN TTBOOL bDuplexMode, IN const SpeexDSP *lpSpeexDSP)
| Perform a record and playback test of specified sound devices along with an audio configuration.
TEAMTALKDLL_API TTSoundLoop * | TT_StartSoundLoopbackTestEx (IN INT32 nInputDeviceID, IN INT32 nOutputDeviceID, IN INT32 nSampleRate, IN INT32 nChannels, IN TTBOOL bDuplexMode, IN const AudioPreprocessor *lpAudioPreprocessor, IN const SoundDeviceEffects *lpSoundDeviceEffects)
| Perform a record and playback test of specified sound devices along with an audio configuration.
TEAMTALKDLL_API TTBOOL | TT_CloseSoundLoopbackTest (IN TTSoundLoop *lpTTSoundLoop)
| Stop recorder and playback test.
TEAMTALKDLL_API TTBOOL | TT_InitSoundInputDevice (IN TTInstance *lpTTInstance, IN INT32 nInputDeviceID)
| Initialize the sound input device (for recording audio).
TEAMTALKDLL_API TTBOOL | TT_InitSoundInputSharedDevice (IN INT32 nSampleRate, IN INT32 nChannels, IN INT32 nFrameSize)
| Setup sample rate, channels and frame size of shared sound input device.
TEAMTALKDLL_API TTBOOL | TT_InitSoundOutputDevice (IN TTInstance *lpTTInstance, IN INT32 nOutputDeviceID)
| Initialize the sound output device (for audio playback).
TEAMTALKDLL_API TTBOOL | TT_InitSoundOutputSharedDevice (IN INT32 nSampleRate, IN INT32 nChannels, IN INT32 nFrameSize)
| Setup sample rate, channels and frame size of shared sound output device.
TEAMTALKDLL_API TTBOOL | TT_InitSoundDuplexDevices (IN TTInstance *lpTTInstance, IN INT32 nInputDeviceID, IN INT32 nOutputDeviceID)
| Enable duplex mode where multiple audio streams are mixed into a single stream using software.
TEAMTALKDLL_API TTBOOL | TT_CloseSoundInputDevice (IN TTInstance *lpTTInstance)
| Shutdown the input sound device.
TEAMTALKDLL_API TTBOOL | TT_CloseSoundOutputDevice (IN TTInstance *lpTTInstance)
| Shutdown the output sound device.
TEAMTALKDLL_API TTBOOL | TT_CloseSoundDuplexDevices (IN TTInstance *lpTTInstance)
| Shut down sound devices running in duplex mode.
TEAMTALKDLL_API TTBOOL | TT_SetSoundDeviceEffects (IN TTInstance *lpTTInstance, IN const SoundDeviceEffects *lpSoundDeviceEffect)
| Set up audio effects on a sound device.
TEAMTALKDLL_API TTBOOL | TT_GetSoundDeviceEffects (IN TTInstance *lpTTInstance, OUT SoundDeviceEffects *lpSoundDeviceEffect)
| Get the audio effects that are currently enabled.
TEAMTALKDLL_API INT32 | TT_GetSoundInputLevel (IN TTInstance *lpTTInstance)
| Get the volume level of the current recorded audio.
TEAMTALKDLL_API TTBOOL | TT_SetSoundInputGainLevel (IN TTInstance *lpTTInstance, IN INT32 nLevel)
| Set voice gaining of recorded audio.
TEAMTALKDLL_API INT32 | TT_GetSoundInputGainLevel (IN TTInstance *lpTTInstance)
| Get voice gain level of outgoing audio.
TEAMTALKDLL_API TTBOOL | TT_SetSoundInputPreprocess (IN TTInstance *lpTTInstance, IN const SpeexDSP *lpSpeexDSP)
| Enable sound preprocessor which should be used for processing audio recorded by the sound input device (voice input).
TEAMTALKDLL_API TTBOOL | TT_GetSoundInputPreprocess (IN TTInstance *lpTTInstance, OUT SpeexDSP *lpSpeexDSP)
| Get the sound preprocessor settings which are currently in use for recorded sound input device (voice input).
TEAMTALKDLL_API TTBOOL | TT_SetSoundInputPreprocessEx (IN TTInstance *lpTTInstance, IN const AudioPreprocessor *lpAudioPreprocessor)
| Enable sound preprocessor which should be used for processing audio recorded by the sound input device (voice input).
TEAMTALKDLL_API TTBOOL | TT_GetSoundInputPreprocessEx (IN TTInstance *lpTTInstance, OUT AudioPreprocessor *lpAudioPreprocessor)
| Get the sound preprocessor settings which are currently in use for recorded sound input device (voice input).
TEAMTALKDLL_API TTBOOL | TT_SetSoundOutputVolume (IN TTInstance *lpTTInstance, IN INT32 nVolume)
| Set master volume.
TEAMTALKDLL_API INT32 | TT_GetSoundOutputVolume (IN TTInstance *lpTTInstance)
| Get master volume.
TEAMTALKDLL_API TTBOOL | TT_SetSoundOutputMute (IN TTInstance *lpTTInstance, IN TTBOOL bMuteAll)
| Set all users mute.
TEAMTALKDLL_API TTBOOL | TT_Enable3DSoundPositioning (IN TTInstance *lpTTInstance, IN TTBOOL bEnable)
| Enable automatically position users using 3D-sound.
TEAMTALKDLL_API TTBOOL | TT_AutoPositionUsers (IN TTInstance *lpTTInstance)
| Automatically position users using 3D-sound.
TEAMTALKDLL_API TTBOOL | TT_EnableAudioBlockEvent (IN TTInstance *lpTTInstance, IN INT32 nUserID, IN StreamTypes uStreamTypes, IN TTBOOL bEnable)
| Enable/disable access to raw audio from individual users, local microphone input or mixed stream of all users.
TEAMTALKDLL_API TTBOOL | TT_EnableAudioBlockEventEx (IN TTInstance *lpTTInstance, IN INT32 nUserID, IN StreamTypes uStreamTypes, IN const AudioFormat *lpAudioFormat, IN TTBOOL bEnable)
| Enable/disable access to raw audio from individual users, local microphone input or mixed stream of all users.
TEAMTALKDLL_API TTBOOL | TT_SetUserVolume (IN TTInstance *lpTTInstance, IN INT32 nUserID, IN StreamType nStreamType, IN INT32 nVolume)
| Set the volume of a user.
TEAMTALKDLL_API TTBOOL | TT_SetUserMute (IN TTInstance *lpTTInstance, IN INT32 nUserID, IN StreamType nStreamType, IN TTBOOL bMute)
| Mute a user.
TEAMTALKDLL_API TTBOOL | TT_SetUserStoppedPlaybackDelay (IN TTInstance *lpTTInstance, IN INT32 nUserID, IN StreamType nStreamType, IN INT32 nDelayMSec)
| Set the delay of when a user should no longer be considered as playing audio (either voice or audio from media file).
TEAMTALKDLL_API TTBOOL | TT_SetUserJitterControl (IN TTInstance *lpTTInstance, IN INT32 nUserID, IN StreamType nStreamType, IN const JitterConfig *lpJitterConfig)
| Set the configuration for de-jitter measures for a user.
TEAMTALKDLL_API TTBOOL | TT_GetUserJitterControl (IN TTInstance *lpTTInstance, IN INT32 nUserID, IN StreamType nStreamType, IN JitterConfig *lpJitterConfig)
| Get the de-jitter configuration for a user.
TEAMTALKDLL_API TTBOOL | TT_SetUserPosition (IN TTInstance *lpTTInstance, IN INT32 nUserID, IN StreamType nStreamType, IN float x, IN float y, IN float z)
| Set the position of a user.
TEAMTALKDLL_API TTBOOL | TT_SetUserStereo (IN TTInstance *lpTTInstance, IN INT32 nUserID, IN StreamType nStreamType, IN TTBOOL bLeftSpeaker, IN TTBOOL bRightSpeaker)
| Set whether a user should speak in the left, right or both speakers. This function only works if AudioCodec has been set to use stereo.
TEAMTALKDLL_API TTBOOL | TT_SetUserMediaStorageDir (IN TTInstance *lpTTInstance, IN INT32 nUserID, IN const TTCHAR *szFolderPath, IN const TTCHAR *szFileNameVars, IN AudioFileFormat uAFF)
| Store user's audio to disk.
TEAMTALKDLL_API TTBOOL | TT_SetUserMediaStorageDirEx (IN TTInstance *lpTTInstance, IN INT32 nUserID, IN const TTCHAR *szFolderPath, IN const TTCHAR *szFileNameVars, IN AudioFileFormat uAFF, IN INT32 nStopRecordingExtraDelayMSec)
| Store user's audio to disk.
TEAMTALKDLL_API TTBOOL | TT_SetUserAudioStreamBufferSize (IN TTInstance *lpTTInstance, IN INT32 nUserID, IN StreamTypes uStreamType, IN INT32 nMSec)
| Change the amount of media data which can be buffered in the user's playback queue.
TEAMTALKDLL_API AudioBlock * | TT_AcquireUserAudioBlock (IN TTInstance *lpTTInstance, IN StreamTypes uStreamTypes, IN INT32 nUserID)
| Extract the raw audio associated with the event CLIENTEVENT_USER_AUDIOBLOCK.
TEAMTALKDLL_API TTBOOL | TT_ReleaseUserAudioBlock (IN TTInstance *lpTTInstance, IN AudioBlock *lpAudioBlock)
| Release the shared memory of an AudioBlock.

## Detailed Description

This section explains how to record and playback audio in the client instance.

Before being able to initialize the sound devices to use for recording and playback the computer's available sound devices must first be queried. This is done using the function TT_GetSoundDevices() which returns an array of SoundDevice-structs containing a description of the sound device. In the SoundDevice-struct there's a member variable called nDeviceID. This ID should be passed to the client instance's two sound initialization functions TT_InitSoundInputDevice and TT_InitSoundOutputDevice. Once this has been done the TT_GetFlags call will return a value containing the mask bits CLIENT_SNDINPUT_READY and CLIENT_SNDOUTPUT_READY.

A computer's default sound devices can be queried using TT_GetDefaultSoundDevices. A loop-back test of the selected sound devices can be performed using TT_StartSoundLoopbackTest.

Be aware that the sound devices might fail if e.g. a USB sound device is unplugged while the client is talking in a channel. In this case ensure the application is processing the errors INTERR_SNDINPUT_FAILURE and INTERR_SNDOUTPUT_FAILURE in the CLIENTEVENT_INTERNAL_ERROR event.

Read section Audio and Video Transmission to see how to transmit recorded audio to other users.

## Macro Definition Documentation

## ◆ TT_SAMPLERATES_MAX

#define TT_SAMPLERATES_MAX 16

The maximum number of sample rates supported by a SoundDevice.

Definition at line 155 of file TeamTalk.h.

## ◆ TT_SOUNDDEVICE_ID_SHARED_FLAG

#define TT_SOUNDDEVICE_ID_SHARED_FLAG 0x00000800

Flag/bit in `nDeviceID` telling if the SoundDevice is a shared version of an existing sound device.

On Android the recording device can only be used by one TeamTalk instance. As a workaround for this issue a shared recording device has been introduced. Internally TeamTalk initializes TT_SOUNDDEVICE_ID_OPENSLES_DEFAULT which then resample and distribute the audio data to multiple TeamTalk instances.

The shared audio device on Android will show up as (TT_SOUNDDEVICE_ID_OPENSLES_DEFAULT | TT_SOUNDDEVICE_ID_SHARED_FLAG), i.e. 2048.

Definition at line 537 of file TeamTalk.h.

## ◆ TT_SOUNDDEVICE_ID_MASK

#define TT_SOUNDDEVICE_ID_MASK 0x000007FF

Extract sound device ID of `nDeviceID` in SoundDevice by and'ing this value.

let PhysicalDeviceID = (SoundDevice.nDeviceID & TT_SOUNDDEVICE_ID_MASK).

Definition at line 543 of file TeamTalk.h.

## ◆ TT_SOUNDDEVICE_ID_REMOTEIO

#define TT_SOUNDDEVICE_ID_REMOTEIO 0

Sound device ID for iOS AudioUnit subtype Remote I/O Unit.

See also
  SOUNDSYSTEM_AUDIOUNIT

Definition at line 547 of file TeamTalk.h.

## ◆ TT_SOUNDDEVICE_ID_VOICEPREPROCESSINGIO

#define TT_SOUNDDEVICE_ID_VOICEPREPROCESSINGIO (1 | TT_SOUNDDEVICE_ID_SHARED_FLAG)

Sound device ID for iOS AudioUnit subtype Voice-Processing I/O Unit.

This sound device ID include the flag TT_SOUNDDEVICE_ID_SHARED_FLAG since multiple streams cannot be recorded/played on the device.

See also
  SOUNDSYSTEM_AUDIOUNIT

Definition at line 555 of file TeamTalk.h.

## ◆ TT_SOUNDDEVICE_ID_OPENSLES_DEFAULT

#define TT_SOUNDDEVICE_ID_OPENSLES_DEFAULT 0

Sound device ID for Android OpenSL ES default audio device.

See also
  SOUNDSYSTEM_OPENSLES_ANDROID

Definition at line 559 of file TeamTalk.h.

## ◆ TT_SOUNDDEVICE_ID_OPENSLES_VOICECOM

#define TT_SOUNDDEVICE_ID_OPENSLES_VOICECOM 1

Sound device ID for Android OpenSL ES voice communication mode. This device uses the OpenSL ES' AndroidConfiguration `SL_ANDROID_RECORDING_PRESET_VOICE_COMMUNICATION`.

See also
  SOUNDSYSTEM_OPENSLES_ANDROID

Definition at line 565 of file TeamTalk.h.

## ◆ TT_SOUNDDEVICE_ID_TEAMTALK_VIRTUAL

#define TT_SOUNDDEVICE_ID_TEAMTALK_VIRTUAL 1978

Sound device ID for virtual TeamTalk sound device.

This is a sound device which decodes received audio packets but does not send the decoded audio to a real sound device. When used for recording the virtual sound device injects silence.

In duplex mode the virtual TeamTalk sound device can only be used as input/output device.

See also
  SOUNDSYSTEM_NONE

Definition at line 575 of file TeamTalk.h.

## ◆ TT_LOCAL_USERID

#define TT_LOCAL_USERID 0

User ID passed to TT_EnableAudioBlockEvent() in order to receive AudioBlock directly from sound input device after joining a channel.

When this user ID is passed then the AudioBlock received will be prior to audio preprocessing (AudioPreprocessor).

Note, however, that CLIENTEVENT_USER_AUDIOBLOCK will not be triggered until the TTInstance is in a channel. This is because the sound input device is not started until it knows the AudioCodec's sample rate, number of channels and transmit interval.

Definition at line 712 of file TeamTalk.h.

## ◆ TT_LOCAL_TX_USERID

#define TT_LOCAL_TX_USERID 0x1002

User ID passed to TT_EnableAudioBlockEvent() in order to receive AudioBlock when voice transmission is activated.

Either through TT_EnableVoiceActivation() or TT_EnableVoiceTransmission().

Definition at line 721 of file TeamTalk.h.

## ◆ TT_MUXED_USERID

#define TT_MUXED_USERID 0x1001 /* TT_USERID_MAX + 2 */

User ID used to identify muxed audio that has been mixed into a single stream.

This user ID is passed to TT_EnableAudioBlockEvent() in order to receive AudioBlock of audio that is played by the TTInstance.

Definition at line 729 of file TeamTalk.h.

## Typedef Documentation

## ◆ SoundSystem

typedef enum SoundSystem SoundSystem

The supported sound systems.

See also
  SoundDevice
  TT_InitSoundInputDevice()
  TT_InitSoundOutputDevice()
  TT_InitSoundDuplexDevices()

## ◆ SoundDeviceFeature

typedef enum SoundDeviceFeature SoundDeviceFeature

Features available on a sound device. Checkout `uSoundDeviceFeatures` on SoundDevice.

## ◆ SoundDeviceFeatures

typedef UINT32 SoundDeviceFeatures

A bitmask of available SoundDeviceFeature. Checkout `uSoundDeviceFeatures` on SoundDevice.

Definition at line 389 of file TeamTalk.h.

## ◆ SoundDevice

typedef struct SoundDevice SoundDevice

A struct containing the properties of a sound device for either playback or recording.

Use nDeviceID to pass to TT_InitSoundInputDevice or TT_InitSoundOutputDevice.

Note that the nDeviceID may change if the user application is restarted and a new sound device is added or removed from the computer.

See also
  TT_GetSoundDevices

## ◆ SoundDeviceEffects

typedef struct SoundDeviceEffects SoundDeviceEffects

Set up audio effects supported by the sound device.

The effects supported by a sound device are listed in the `uSoundDeviceFeatures` property of SoundDevice.

To apply audio effects on a sound device call TT_SetSoundDeviceEffects()

## ◆ SoundLevel

typedef enum SoundLevel SoundLevel

An enum encapsulation the minimum, maximum and default sound levels for input and output sound devices.

## ◆ AudioBlock

typedef struct AudioBlock AudioBlock

An audio block containing the raw audio from a user who was talking.

To enable audio blocks first call TT_EnableAudioBlockEvent() then whenever new audio is played the event CLIENTEVENT_USER_AUDIOBLOCK is generated. Use TT_AcquireUserAudioBlock() to retrieve the audio block.

Note that each user is limited to 128 kbytes of audio data.

See also
  TT_EnableAudioBlockEvent()
  TT_AcquireUserAudioBlock()
  TT_ReleaseUserAudioBlock()

## ◆ TTSoundLoop

typedef VOID TTSoundLoop

Pointer to a sound loop for testing sound devices created by TT_StartSoundLoopbackTest()

Definition at line 4167 of file TeamTalk.h.

## Enumeration Type Documentation

## ◆ SoundSystem

enum SoundSystem

The supported sound systems.

See also
  SoundDevice
  TT_InitSoundInputDevice()
  TT_InitSoundOutputDevice()
  TT_InitSoundDuplexDevices()

Enumerator
SOUNDSYSTEM_NONE | Sound system denoting invalid or not found.
SOUNDSYSTEM_WINMM | Windows legacy audio system. Should be used on Windows Mobile.
SOUNDSYSTEM_DSOUND | DirectSound audio system. Should be used on Windows.
SOUNDSYSTEM_ALSA | Advanced Linux Sound Architecture (ALSA). Should be used on Linux. Often ALSA sound devices only support a limited number of sample rates so TeamTalk internally use software filters to resample the audio to the sample rate used by the selected audio codecs.
SOUNDSYSTEM_COREAUDIO | Core Audio. Should be used on MacOS.

SOUNDSYSTEM_WASAPI

Windows Audio Session API (WASAPI). Should be used on Windows Vista/7/8/10.

WASAPI audio devices typically only support a single sample rate so internally TeamTalk uses software filters to resample audio to the sample rate used by the selected audio codecs.

Check `supportedSampleRates` and `nDefaultSampleRate` of SoundDevice to see which sample rates are supported.

SOUNDSYSTEM_OPENSLES_ANDROID

Android sound API.

       The OpenSL ES sound API requires Android 4.1 or later.

       Duplex mode is not supported by OpenSL ES @see
       TT_InitSoundDuplexDevices()

SOUNDSYSTEM_AUDIOUNIT

iOS sound API.

       The following sound devices will appear when calling
       TT_GetSoundDevices(). Sound device ID
       #TT_SOUNDDEVICE_ID_REMOTEIO will be AudioUnit subtype
       Remote I/O Unit and sound device ID
       #TT_SOUNDDEVICE_ID_VOICEPREPROCESSINGIO will be AudioUnit
       subtype Voice-Processing I/O Unit.

       Note that iOS only supports one active Voice-Processing I/O
       Unit, i.e. only one #TTInstance can use the
       Voice-Processing I/O Unit.

       Add libraries @c AVFoundation.framework and
       @c AudioToolbox.framework.

       Duplex mode is not supported by AudioUnit iOS sound API.
       @see TT_SOUNDDEVICE_ID_REMOTEIO
       @see TT_SOUNDDEVICE_ID_VOICEPREPROCESSINGIO

SOUNDSYSTEM_AUDIOUNIT_IOS | Same as SOUNDSYSTEM_AUDIOUNIT.
SOUNDSYSTEM_PULSEAUDIO | PulseAudio API. PulseAudio is typically used on Ubuntu 22.

Definition at line 287 of file TeamTalk.h.

## ◆ SoundDeviceFeature

enum SoundDeviceFeature

Features available on a sound device. Checkout `uSoundDeviceFeatures` on SoundDevice.

Enumerator
SOUNDDEVICEFEATURE_NONE | No sound device features are available on this sound device.

SOUNDDEVICEFEATURE_AEC

The SoundDevice can enable Acoustic Echo Canceler (AEC). Enable AEC use property `bEnableAEC` on SoundDeviceEffects.

See also
  TT_SetSoundDeviceEffects()

SOUNDDEVICEFEATURE_AGC

The SoundDevice can enable Automatic Gain Control (AGC). Enable AGC use property `bEnableAGC` on SoundDeviceEffects.

See also
  TT_SetSoundDeviceEffects()

SOUNDDEVICEFEATURE_DENOISE

The SoundDevice can enable denoising. Enable denoising use property `bEnableDenoising` on SoundDeviceEffects.

See also
  TT_SetSoundDeviceEffects()

SOUNDDEVICEFEATURE_3DPOSITION

The SoundDevice can position user in 3D.

See also
  TT_SetUserPosition()

SOUNDDEVICEFEATURE_DUPLEXMODE

The SoundDevice can run in duplex mode.

See also
  TT_InitSoundDuplexDevices()

SOUNDDEVICEFEATURE_DEFAULTCOMDEVICE | The SoundDevice is the default communication device. This feature is only supported on SOUNDSYSTEM_WASAPI.

Definition at line 354 of file TeamTalk.h.

## ◆ SoundLevel

enum SoundLevel

An enum encapsulation the minimum, maximum and default sound levels for input and output sound devices.

Enumerator

SOUND_VU_MAX

The maximum value of recorded audio.

See also
  TT_GetSoundInputLevel
  TT_SetVoiceActivationLevel
  TT_GetVoiceActivationLevel

SOUND_VU_MIN

The minimum value of recorded audio.

See also
  TT_GetSoundInputLevel
  TT_SetVoiceActivationLevel
  TT_GetVoiceActivationLevel

SOUND_VOLUME_MAX

The maximum volume.

See also
  TT_SetSoundOutputVolume
  TT_GetSoundOutputVolume
  TT_SetUserVolume
  SOUND_VOLUME_DEFAULT

SOUND_VOLUME_DEFAULT

The default volume. Use this whenever possible since it requires the least amount of CPU usage.

See also
  TT_SetSoundOutputVolume
  TT_GetSoundOutputVolume
  TT_SetUserVolume

SOUND_VOLUME_MIN

The minimum volume.

See also
  TT_SetSoundOutputVolume
  TT_GetSoundOutputVolume
  TT_SetUserVolume

SOUND_GAIN_MAX

The maximum gain level.

A gain level of 32000 gains the volume by a factor 32. A gain level of SOUND_GAIN_DEFAULT means no gain.

See also
  TT_SetSoundInputGainLevel
  TT_GetSoundInputGainLevel

SOUND_GAIN_DEFAULT

The default gain level.

A gain level of 1000 means no gain. Check SOUND_GAIN_MAX and SOUND_GAIN_MIN to see how to increase and lower gain level.

See also
  TT_SetSoundInputGainLevel
  TT_GetSoundInputGainLevel

SOUND_GAIN_MIN

The minimum gain level (since it's zero it means silence).

A gain level of 100 is 1/10 of the default volume.

See also
  TT_SetSoundInputGainLevel
  TT_GetSoundInputGainLevel

Definition at line 580 of file TeamTalk.h.

## Function Documentation

## ◆ TT_GetDefaultSoundDevices()

TEAMTALKDLL_API TTBOOL TT_GetDefaultSoundDevices | ( | OUT INT32 * | lpnInputDeviceID,
|  | OUT INT32 * | lpnOutputDeviceID )

Get the default sound devices.

Parameters

  lpnInputDeviceID | The ID of the default input device.
  lpnOutputDeviceID | The ID of the default output device.

See also
  TT_InitSoundInputDevice
  TT_InitSoundOutputDevice

## ◆ TT_GetDefaultSoundDevicesEx()

TEAMTALKDLL_API TTBOOL TT_GetDefaultSoundDevicesEx | ( | IN SoundSystem | nSndSystem,
|  | OUT INT32 * | lpnInputDeviceID,
|  | OUT INT32 * | lpnOutputDeviceID )

Get the default sound devices for the specified sound system.

See also
  TT_GetDefaultSoundDevices()

## ◆ TT_GetSoundDevices()

TEAMTALKDLL_API TTBOOL TT_GetSoundDevices | ( | IN OUT SoundDevice * | lpSoundDevices,
|  | IN OUT INT32 * | lpnHowMany )

Retrieve list of sound devices for recording and playback.

Parameters

  lpSoundDevices | Array of SoundDevice-structs where lpnHowMany holds the size of the array. Pass NULL as lpSoundDevices to query the number of devices.
  lpnHowMany | This is both an input and an output parameter. If lpSoundDevices is NULL lpnHowMany will after the call hold the number of devices, otherwise it should hold the size of the lpSoundDevices array.

See also
  TT_GetDefaultSoundDevices
  TT_InitSoundInputDevice
  TT_InitSoundOutputDevice

## ◆ TT_RestartSoundSystem()

TEAMTALKDLL_API TTBOOL TT_RestartSoundSystem | ( | void |  | ) |

Reinitialize sound system (in order to detect new/removed devices).

When the TeamTalk client is first initialized all the sound devices are detected and stored in a list inside the client instance. If a user adds or removes e.g. a USB sound device then it's not picked up automatically by the client instance. TT_RestartSoundSystem() can be used to reinitialize the sound system and thereby detect if sound devices have been removed or added.

In order to restart the sound system all sound devices in all client instances must be closed using TT_CloseSoundInputDevice(), TT_CloseSoundoutputDevice() and TT_CloseSoundDuplexDevices().

## ◆ TT_StartSoundLoopbackTest()

TEAMTALKDLL_API TTSoundLoop * TT_StartSoundLoopbackTest | ( | IN INT32 | nInputDeviceID,
|  | IN INT32 | nOutputDeviceID,
|  | IN INT32 | nSampleRate,
|  | IN INT32 | nChannels,
|  | IN TTBOOL | bDuplexMode,
|  | IN const SpeexDSP * | lpSpeexDSP )

Perform a record and playback test of specified sound devices along with an audio configuration.

Deprecated
  Use TT_StartSoundLoopbackTestEx()

## ◆ TT_StartSoundLoopbackTestEx()

TEAMTALKDLL_API TTSoundLoop * TT_StartSoundLoopbackTestEx | ( | IN INT32 | nInputDeviceID,
|  | IN INT32 | nOutputDeviceID,
|  | IN INT32 | nSampleRate,
|  | IN INT32 | nChannels,
|  | IN TTBOOL | bDuplexMode,
|  | IN const AudioPreprocessor * | lpAudioPreprocessor,
|  | IN const SoundDeviceEffects * | lpSoundDeviceEffects )

Perform a record and playback test of specified sound devices along with an audio configuration.

Call TT_CloseSoundLoopbackTest() to stop the loopback test.

This function allows the use of SpeexDSP to enable AGC and echo cancellation.

Parameters

  nInputDeviceID | Should be the nDeviceID extracted through TT_GetSoundDevices().
  nOutputDeviceID | Should be the nDeviceID extracted through TT_GetSoundDevices().
  nSampleRate | The sample rate the client's recorder should use.
  nChannels | Number of channels to use, i.e. 1 = mono, 2 = stereo.
  bDuplexMode | Both input and output devices MUST support the specified sample rate since this loop back test uses duplex mode (

See also
  TT_InitSoundDuplexDevices() ). Check out `supportedSampleRates` of SoundDevice to see which sample rates are supported. The SoundDevice must have the feature SOUNDDEVICEFEATURE_DUPLEXMODE.

Parameters

  lpAudioPreprocessor | The preprocessing settings to use, i.e. AGC and denoising properties. Pass NULL to ignore AGC, denoise and AEC.
  lpSoundDeviceEffects | The sound device effects which should be applied before the loopback test is started.

Returns
  Returns NULL in case of error, otherwise sound loop instance which can be closed by TT_CloseSoundLoopbackTest();

See also
  TT_InitSoundInputDevice()
  TT_InitSoundOutputDevice()
  TT_InitSoundDuplexDevices()
  TT_CloseSoundLoopbackTest()

## ◆ TT_CloseSoundLoopbackTest()

TEAMTALKDLL_API TTBOOL TT_CloseSoundLoopbackTest | ( | IN TTSoundLoop * | lpTTSoundLoop | ) |

Stop recorder and playback test.

`lpTTSoundLoop` is destroyed after this call.

Parameters

  lpTTSoundLoop | Pointer to sound loop instance created by TT_StartSoundLoopbackTest().

See also
  TT_InitSoundInputDevice
  TT_InitSoundOutputDevice
  TT_StartSoundLoopbackTest

## ◆ TT_InitSoundInputDevice()

TEAMTALKDLL_API TTBOOL TT_InitSoundInputDevice | ( | IN TTInstance * | lpTTInstance,
|  | IN INT32 | nInputDeviceID )

Initialize the sound input device (for recording audio).

The nDeviceID of the SoundDevice should be used as nInputDeviceID.

The `nInputDeviceID` can be or'ed with TT_SOUNDDEVICE_ID_SHARED_FLAG if the TTInstance should share recording device with other instances.

Notice fixed sound device ID for some platforms:

- iOS
  - TT_SOUNDDEVICE_ID_REMOTEIO
  - TT_SOUNDDEVICE_ID_VOICEPREPROCESSINGIO
- Android
  - TT_SOUNDDEVICE_ID_OPENSLES_DEFAULT
- All platforms
  - TT_SOUNDDEVICE_ID_TEAMTALK_VIRTUAL

Calling this function will set the flag CLIENT_SNDINPUT_READY.

Parameters

  lpTTInstance | Pointer to client instance created by TT_InitTeamTalk.
  nInputDeviceID | The nDeviceID of SoundDevice extracted through TT_GetSoundDevices().

See also
  SoundDevice
  TT_GetDefaultSoundDevices
  TT_GetSoundDevices
  TT_CloseSoundInputDevice
  TT_GetSoundInputLevel

## ◆ TT_InitSoundInputSharedDevice()

TEAMTALKDLL_API TTBOOL TT_InitSoundInputSharedDevice | ( | IN INT32 | nSampleRate,
|  | IN INT32 | nChannels,
|  | IN INT32 | nFrameSize )

Setup sample rate, channels and frame size of shared sound input device.

By default a shared sound device (checkout TT_SOUNDDEVICE_ID_SHARED_FLAG) initialized by TT_InitSoundInputDevice will use the sound device's `nDefaultSampleRate`, `nMaxInputChannels` of SoundDevice and a frame size (callback buffer) of nDefaultSampleRate * 0.04.

TT_InitSoundInputSharedDevice() can be used to override these default settings.

Note that TT_InitSoundInputSharedDevice() must be called prior to TT_InitSoundInputDevice(). Also ensure no shared sound input device is currently active.

Parameters

  nSampleRate | The sample rate to use on the shared device. Must exist in SoundDevice's `inputSampleRates`. Pass zero to reset to default behaviour.
  nChannels | The number of channels to use (mono, stereo). Must be less or equals to SoundDevice's `nMaxInputChannels`. Pass zero to reset to default behaviour.
  nFrameSize | The number of samples in each callback from the shared sound device. A 40 msec callback on a 48 KHz input is calculated like this: nFrameSize = 48000 * 0.04. Pass zero to reset to default behaviour.

See also
  TT_InitSoundInputDevice()
  TT_InitSoundOutputSharedDevice()

## ◆ TT_InitSoundOutputDevice()

TEAMTALKDLL_API TTBOOL TT_InitSoundOutputDevice | ( | IN TTInstance * | lpTTInstance,
|  | IN INT32 | nOutputDeviceID )

Initialize the sound output device (for audio playback).

The nDeviceID of the SoundDevice should be used as nOutputDeviceID.

The `nOutputDeviceID` can be or'ed with TT_SOUNDDEVICE_ID_SHARED_FLAG if the TTInstance should share output device with other instances.

Notice fixed sound device ID for some platforms:

- iOS
  - TT_SOUNDDEVICE_ID_REMOTEIO
  - TT_SOUNDDEVICE_ID_VOICEPREPROCESSINGIO
- Android
  - TT_SOUNDDEVICE_ID_OPENSLES_DEFAULT
- All platforms
  - TT_SOUNDDEVICE_ID_TEAMTALK_VIRTUAL

Callling this function will set the flag CLIENT_SNDOUTPUT_READY.

Parameters

  lpTTInstance | Pointer to client instance created by TT_InitTeamTalk.
  nOutputDeviceID | The nDeviceID of SoundDevice extracted through TT_GetSoundDevices().

See also
  SoundDevice
  TT_GetDefaultSoundDevices
  TT_GetSoundDevices
  TT_CloseSoundOutputDevice

## ◆ TT_InitSoundOutputSharedDevice()

TEAMTALKDLL_API TTBOOL TT_InitSoundOutputSharedDevice | ( | IN INT32 | nSampleRate,
|  | IN INT32 | nChannels,
|  | IN INT32 | nFrameSize )

Setup sample rate, channels and frame size of shared sound output device.

By default a shared sound device (checkout TT_SOUNDDEVICE_ID_SHARED_FLAG) initialized by TT_InitSoundOutputDevice will use the sound device's `nDefaultSampleRate`, `nMaxOutputChannels` of SoundDevice and a frame size (callback buffer) of nDefaultSampleRate * 0.04.

TT_InitSoundOutputSharedDevice() can be used to override these default settings.

Note that TT_InitSoundOutputSharedDevice() must be called prior to TT_InitSoundOutputDevice(). Also ensure no shared sound output device is currently active.

Parameters

  nSampleRate | The sample rate to use on the shared device. Must exist in SoundDevice's `outputSampleRates`. Pass zero to reset to default behaviour.
  nChannels | The number of channels to use (mono, stereo). Must be less or equals to SoundDevice's `nMaxOutputChannels`. Pass zero to reset to default behaviour.
  nFrameSize | The number of samples in each callback from the shared sound device. A 40 msec callback on a 48KHz output is calculated like this: nFrameSize = 48000 * 0.04. Pass zero to reset to default behaviour.

See also
  TT_InitSoundInputDevice()
  TT_InitSoundOutputSharedDevice()

## ◆ TT_InitSoundDuplexDevices()

TEAMTALKDLL_API TTBOOL TT_InitSoundDuplexDevices | ( | IN TTInstance * | lpTTInstance,
|  | IN INT32 | nInputDeviceID,
|  | IN INT32 | nOutputDeviceID )

Enable duplex mode where multiple audio streams are mixed into a single stream using software.

To use duplex mode the feature SOUNDDEVICEFEATURE_DUPLEXMODE must be available on the SoundDevice.

If TT_InitSoundDuplexDevices() is successful the following flags will be set:

- CLIENT_SNDINOUTPUT_DUPLEX
- CLIENT_SNDOUTPUT_READY
- CLIENT_SNDINPUT_READY

Call TT_CloseSoundDuplexDevices() to shut down duplex mode.

Note that it is only the audio streams from users in the local client instance's current channel which will be mixed. If the local client instance calls TT_DoSubscribe() with SUBSCRIBE_INTERCEPT_VOICE on a user in another channel then the audio from this user will be started in a separate stream. The reason for this is that the other user may use an audio codec with a different sample rate or number of audio channels.

Parameters

  lpTTInstance | Pointer to client instance created by TT_InitTeamTalk.
  nInputDeviceID | The nDeviceID of SoundDevice extracted through TT_GetSoundDevices().
  nOutputDeviceID | The nDeviceID of SoundDevice extracted through TT_GetSoundDevices().

See also
  TT_InitSoundInputDevice()
  TT_InitSoundOutputDevice()
  TT_CloseSoundDuplexDevices()

## ◆ TT_CloseSoundInputDevice()

TEAMTALKDLL_API TTBOOL TT_CloseSoundInputDevice | ( | IN TTInstance * | lpTTInstance | ) |

Shutdown the input sound device.

Callling this function will clear the flag CLIENT_SNDINPUT_READY.

If the local client instance is running in duplex mode (flag CLIENT_SNDINOUTPUT_DUPLEX is set) then trying to close the sound device will fail since duplex mode require that both input and output sound devices are active at the same time. Therefore in order to close sound devices running in duplex mode call TT_CloseSoundDuplexDevices().

Parameters

  lpTTInstance | Pointer to client instance created by TT_InitTeamTalk.

Returns
  If running in sound duplex mode (CLIENT_SNDINOUTPUT_DUPLEX) then ensure to disable duplex mode prior to closing the sound device.

See also
  TT_InitSoundInputDevice

## ◆ TT_CloseSoundOutputDevice()

TEAMTALKDLL_API TTBOOL TT_CloseSoundOutputDevice | ( | IN TTInstance * | lpTTInstance | ) |

Shutdown the output sound device.

Callling this function will clear set the flag CLIENT_SNDOUTPUT_READY.

If the local client instance is running in duplex mode (flag CLIENT_SNDINOUTPUT_DUPLEX is set) then trying to close the sound device will fail since duplex mode require that both input and output sound devices are active at the same time. Therefore in order to close sound devices running in duplex mode call TT_CloseSoundDuplexDevices().

Parameters

  lpTTInstance | Pointer to client instance created by TT_InitTeamTalk.

Returns
  If running in sound duplex mode (CLIENT_SNDINOUTPUT_DUPLEX) then ensure to disable duplex mode prior to closing the sound device.

See also
  TT_InitSoundOutputDevice

## ◆ TT_CloseSoundDuplexDevices()

TEAMTALKDLL_API TTBOOL TT_CloseSoundDuplexDevices | ( | IN TTInstance * | lpTTInstance | ) |

Shut down sound devices running in duplex mode.

Calling this function only applies if sound devices has been initialized with TT_InitSoundDuplexDevices().

Parameters

  lpTTInstance | Pointer to client instance created by TT_InitTeamTalk.

## ◆ TT_SetSoundDeviceEffects()

TEAMTALKDLL_API TTBOOL TT_SetSoundDeviceEffects | ( | IN TTInstance * | lpTTInstance,
|  | IN const SoundDeviceEffects * | lpSoundDeviceEffect )

Set up audio effects on a sound device.

Some devices, like Android, enable the user to toggle certain audio effects on their device to improve audio quality. The SoundDeviceEffects-struct can be used to toggle these audio effects on the device.

The following sound systems support TT_SetSoundDeviceEffects():

- SOUNDSYSTEM_OPENSLES_ANDROID
  - Modifying SoundDeviceEffects on Android will apply to all active TTInstance, i.e. SoundDeviceEffects are applied globally.
- SOUNDSYSTEM_WASAPI
  - TT_SetSoundDeviceEffects() must be called prior to TT_InitSoundDuplexDevices(). Sound device effects cannot be used with TT_InitSoundInputDevice() and TT_InitSoundOutputDevice() since Windows needs to know both input and output device upon initialization.

This setting should not be confused with TT_SetSoundInputPreprocessEx() which runs entirely in software and is specific to the TTInstance.

Investigate SoundDeviceFeature to see what audio effects are supported by the available SoundDevice.

Note that the sound effects may not be immediately applied since an sound device is not active until the TTInstance joins a channel where the sound device knowns the sample rate and number of channels (mono/stereo). INTERR_SNDEFFECT_FAILURE will be posted if the SoundDeviceEffects was unable to initialize.

See also
  TT_GetSoundDeviceEffects()

## ◆ TT_GetSoundDeviceEffects()

TEAMTALKDLL_API TTBOOL TT_GetSoundDeviceEffects | ( | IN TTInstance * | lpTTInstance,
|  | OUT SoundDeviceEffects * | lpSoundDeviceEffect )

Get the audio effects that are currently enabled.

See also
  TT_SoundDeviceEffects()

## ◆ TT_GetSoundInputLevel()

TEAMTALKDLL_API INT32 TT_GetSoundInputLevel | ( | IN TTInstance * | lpTTInstance | ) |

Get the volume level of the current recorded audio.

The current level is updated at an interval specified in a channel's AudioCodec.

Note that the volume level will not be available until the client instance joins a channel, i.e. it knows what sample rate to use.

Parameters

  lpTTInstance | Pointer to client instance created by TT_InitTeamTalk.

Returns
  Returns a value between SOUND_VU_MIN and SOUND_VU_MAX.

## ◆ TT_SetSoundInputGainLevel()

TEAMTALKDLL_API TTBOOL TT_SetSoundInputGainLevel | ( | IN TTInstance * | lpTTInstance,
|  | IN INT32 | nLevel )

Set voice gaining of recorded audio.

The gain level ranges from SOUND_GAIN_MIN to SOUND_GAIN_MAX where SOUND_GAIN_DEFAULT is no gain. So 100 is 1/10 of the original volume and 8000 is 8 times the original volume.

Note that using TT_SetSoundInputPreprocess() will override settings on input gain level. This is because automatic gain control will adjust the volume level.

Deprecated
  Use TT_SetSoundInputPreprocessEx() and TEAMTALK_AUDIOPREPROCESSOR.

Parameters

  lpTTInstance | Pointer to client instance created by TT_InitTeamTalk.
  nLevel | A value from SOUND_GAIN_MIN to SOUND_GAIN_MAX.

See also
  TT_GetSoundInputGainLevel

## ◆ TT_GetSoundInputGainLevel()

TEAMTALKDLL_API INT32 TT_GetSoundInputGainLevel | ( | IN TTInstance * | lpTTInstance | ) |

Get voice gain level of outgoing audio.

Deprecated
  Use TT_GetSoundInputPreprocessEx()

Parameters

  lpTTInstance | Pointer to client instance created by TT_InitTeamTalk.

Returns
  A value from SOUND_GAIN_MIN to SOUND_GAIN_MAX.

See also
  TT_SetSoundInputGainLevel

## ◆ TT_SetSoundInputPreprocess()

TEAMTALKDLL_API TTBOOL TT_SetSoundInputPreprocess | ( | IN TTInstance * | lpTTInstance,
|  | IN const SpeexDSP * | lpSpeexDSP )

Enable sound preprocessor which should be used for processing audio recorded by the sound input device (voice input).

To ensure common settings for all users in a channel it's possible to use the `audiocfg` member of Channel as shared source for audio settings.

In order for echo cancellation to work best it's important to also enable AGC in the SpeexDSP.

Deprecated
  Use TT_SetSoundInputPreprocessEx()

Parameters

  lpTTInstance | Pointer to client instance created by TT_InitTeamTalk.
  lpSpeexDSP | The sound preprocessor settings to use. Preferably from the Channel's `audiocfg` member to ensure common settings for all users.

Returns
  TRUE on success, FALSE on failure.

## ◆ TT_GetSoundInputPreprocess()

TEAMTALKDLL_API TTBOOL TT_GetSoundInputPreprocess | ( | IN TTInstance * | lpTTInstance,
|  | OUT SpeexDSP * | lpSpeexDSP )

Get the sound preprocessor settings which are currently in use for recorded sound input device (voice input).

Deprecated
  Use TT_GetSoundInputPreprocessEx()

Parameters

  lpTTInstance | Pointer to client instance created by TT_InitTeamTalk.
  lpSpeexDSP | A preallocated SpeexDSP which will receive the settings that is currently in effect.

Returns
  TRUE on success, FALSE on failure.

## ◆ TT_SetSoundInputPreprocessEx()

TEAMTALKDLL_API TTBOOL TT_SetSoundInputPreprocessEx | ( | IN TTInstance * | lpTTInstance,
|  | IN const AudioPreprocessor * | lpAudioPreprocessor )

Enable sound preprocessor which should be used for processing audio recorded by the sound input device (voice input).

It is recommended to use the sound device's native echo cancellor, denoising and automatic gain control instead of SpeexDSP. Checkout TT_SetSoundDeviceEffects().

Parameters

  lpTTInstance | Pointer to client instance created by TT_InitTeamTalk.
  lpAudioPreprocessor | The sound preprocessor settings to use.

Returns
  TRUE on success, FALSE on failure.

## ◆ TT_GetSoundInputPreprocessEx()

TEAMTALKDLL_API TTBOOL TT_GetSoundInputPreprocessEx | ( | IN TTInstance * | lpTTInstance,
|  | OUT AudioPreprocessor * | lpAudioPreprocessor )

Get the sound preprocessor settings which are currently in use for recorded sound input device (voice input).

Parameters

  lpTTInstance | Pointer to client instance created by TT_InitTeamTalk.
  lpAudioPreprocessor | A preallocated AudioPreprocessor which will receive the settings that is currently in effect.

Returns
  TRUE on success, FALSE on failure.

## ◆ TT_SetSoundOutputVolume()

TEAMTALKDLL_API TTBOOL TT_SetSoundOutputVolume | ( | IN TTInstance * | lpTTInstance,
|  | IN INT32 | nVolume )

Set master volume.

If still not loud enough use TT_SetUserVolume.

Parameters

  lpTTInstance | Pointer to client instance created by TT_InitTeamTalk.
  nVolume | A value from SOUND_VOLUME_MIN to SOUND_VOLUME_MAX.

See also
  TT_SetUserVolume

## ◆ TT_GetSoundOutputVolume()

TEAMTALKDLL_API INT32 TT_GetSoundOutputVolume | ( | IN TTInstance * | lpTTInstance | ) |

Get master volume.

Parameters

  lpTTInstance | Pointer to client instance created by TT_InitTeamTalk.

Returns
  Returns the master volume.

See also
  SOUND_VOLUME_MAX
  SOUND_VOLUME_MIN

## ◆ TT_SetSoundOutputMute()

TEAMTALKDLL_API TTBOOL TT_SetSoundOutputMute | ( | IN TTInstance * | lpTTInstance,
|  | IN TTBOOL | bMuteAll )

Set all users mute.

To stop receiving audio from a user call TT_DoUnsubscribe.

Parameters

  lpTTInstance | Pointer to client instance created by TT_InitTeamTalk.
  bMuteAll | Whether to mute or unmute all users.

See also
  CLIENT_SNDOUTPUT_MUTE

## ◆ TT_Enable3DSoundPositioning()

TEAMTALKDLL_API TTBOOL TT_Enable3DSoundPositioning | ( | IN TTInstance * | lpTTInstance,
|  | IN TTBOOL | bEnable )

Enable automatically position users using 3D-sound.

3D sound position requires SOUNDDEVICEFEATURE_3DPOSITION.

Note that 3d-sound does not work if sound is running in duplex mode (CLIENT_SNDINOUTPUT_DUPLEX) or in stereo.

Parameters

  lpTTInstance | Pointer to client instance created by TT_InitTeamTalk.
  bEnable | TRUE to enable, otherwise FALSE.

See also
  TT_SetUserPosition()

## ◆ TT_AutoPositionUsers()

TEAMTALKDLL_API TTBOOL TT_AutoPositionUsers | ( | IN TTInstance * | lpTTInstance | ) |

Automatically position users using 3D-sound.

3D sound position requires SOUNDDEVICEFEATURE_3DPOSITION.

Note that 3d-sound does not work if sound is running in duplex mode (CLIENT_SNDINOUTPUT_DUPLEX) or in stereo.

Parameters

  lpTTInstance | Pointer to client instance created by TT_InitTeamTalk.

See also
  TT_SetUserPosition()

## ◆ TT_EnableAudioBlockEvent()

TEAMTALKDLL_API TTBOOL TT_EnableAudioBlockEvent | ( | IN TTInstance * | lpTTInstance,
|  | IN INT32 | nUserID,
|  | IN StreamTypes | uStreamTypes,
|  | IN TTBOOL | bEnable )

Enable/disable access to raw audio from individual users, local microphone input or mixed stream of all users.

Deprecated
  Use TT_EnableAudioBlockEventEx().

Parameters

  lpTTInstance | Pointer to client instance created by TT_InitTeamTalk.
  nUserID | See description in TT_EnableAudioBlockEventEx()
  uStreamTypes | See description in TT_EnableAudioBlockEventEx()
  bEnable | See description in TT_EnableAudioBlockEventEx()

See also
  TT_AcquireUserAudioBlock()
  TT_ReleaseUserAudioBlock()
  CLIENTEVENT_USER_AUDIOBLOCK

## ◆ TT_EnableAudioBlockEventEx()

TEAMTALKDLL_API TTBOOL TT_EnableAudioBlockEventEx | ( | IN TTInstance * | lpTTInstance,
|  | IN INT32 | nUserID,
|  | IN StreamTypes | uStreamTypes,
|  | IN const AudioFormat * | lpAudioFormat,
|  | IN TTBOOL | bEnable )

Enable/disable access to raw audio from individual users, local microphone input or mixed stream of all users.

With audio block event enabled all audio which has been played will be accessible by calling TT_AcquireUserAudioBlock(). Every time a new AudioBlock is available the event CLIENTEVENT_USER_AUDIOBLOCK is generated.

Special user IDs can be used to retrieve certain types of audio from the client instance:

- TT_LOCAL_USERID
  - Unprocessed audio from microphone when using STREAMTYPE_VOICE.
  - Decoded PCM16 when using STREAMTYPE_MEDIAFILE_AUDIO.
  - Decoded PCM16 when using STREAMTYPE_LOCALMEDIAPLAYBACK_AUDIO from all active local playbacks
    See also
      TT_InitLocalPlayback().
- TT_LOCAL_TX_USERID
  - Processed audio from microphone that is transmitted to channel when using STREAMTYPE_VOICE.
  - Not applicable for all other stream types except STREAMTYPE_VOICE
- TT_MUXED_USERID
  - Decoded PCM16 from all specified audio streams (StreamTypes) mixed into a single stream.

Parameters

  lpTTInstance | Pointer to client instance created by TT_InitTeamTalk.
  nUserID | User ID has different meanings depending on the StreamType being passed.

For STREAMTYPE_VOICE:

- Pass user ID to receive audio from voice stream.
- Pass special user ID TT_LOCAL_USERID for audio callback from local recorded audio prior to encoding/processing.
- Pass special user ID TT_MUXED_USERID to receive audio where voice stream has been mixed into the single stream. For STREAMTYPE_MEDIAFILE_AUDIO:
- Pass user ID to receive audio from media stream.
- Pass TT_LOCAL_USERID to receive audio from media file being streamed (transmitted).
  See also
    TT_StartStreamingMediaFileToChannel().
- Pass special user ID TT_MUXED_USERID to receive audio where media stream has been mixed into the single stream. For STREAMTYPE_LOCALMEDIAPLAYBACK_AUDIO:
- Pass session ID returned by TT_InitLocalPlayback() to receive audio stream from local playback.
- Pass TT_LOCAL_USERID to receive audio stream from all local playbacks.
- Pass special user ID TT_MUXED_USERID to receive audio where local playback stream has been mixed into the single stream.

When using TT_MUXED_USERID as user ID the TTInstance must be in a channel with a configured AudioCodec. Alternatively use `lpAudioFormat` to specify the audio properties.

Parameters

  uStreamTypes | Either STREAMTYPE_VOICE, STREAMTYPE_MEDIAFILE_AUDIO or STREAMTYPE_LOCALMEDIAPLAYBACK_AUDIO. For TT_MUXED_USERID it's possible to mix StreamTypes so e.g. STREAMTYPE_LOCALMEDIAPLAYBACK_AUDIO or'ed with STREAMTYPE_VOICE) will return an AudioBlock where these two stream types have been mixed together.
  lpAudioFormat | Resample audio format from user to this AudioFormat. Currently only AFF_WAVE_FORMAT is supported. Specify NULL to get original audio format.

When using TT_MUXED_USERID as user ID in combination with `lpAudioFormat` will cause AudioBlock to contain 20 msec of audio. If `lpAudioFormat` is NULL then the TTInstance will use the audio format that is configured in the channel's AudioCodec.

Parameters

  bEnable | Whether to enable the CLIENTEVENT_USER_AUDIOBLOCK event.

See also
  TT_AcquireUserAudioBlock()
  TT_ReleaseUserAudioBlock()
  CLIENTEVENT_USER_AUDIOBLOCK

## ◆ TT_SetUserVolume()

TEAMTALKDLL_API TTBOOL TT_SetUserVolume | ( | IN TTInstance * | lpTTInstance,
|  | IN INT32 | nUserID,
|  | IN StreamType | nStreamType,
|  | IN INT32 | nVolume )

Set the volume of a user.

Note that it's a virtual volume which is being set since the master volume affects the user volume.

Parameters

  lpTTInstance | Pointer to client instance created by TT_InitTeamTalk.
  nUserID | The ID of the user whose volume will be changed.
  nStreamType | The type of stream to change, either STREAMTYPE_VOICE or STREAMTYPE_MEDIAFILE_AUDIO.
  nVolume | Must be between SOUND_VOLUME_MIN and SOUND_VOLUME_MAX.

See also
  TT_SetSoundOutputVolume

## ◆ TT_SetUserMute()

TEAMTALKDLL_API TTBOOL TT_SetUserMute | ( | IN TTInstance * | lpTTInstance,
|  | IN INT32 | nUserID,
|  | IN StreamType | nStreamType,
|  | IN TTBOOL | bMute )

Mute a user.

To stop receiving audio from a user call TT_DoUnsubscribe with SUBSCRIBE_VOICE.

Parameters

  lpTTInstance | Pointer to client instance created by TT_InitTeamTalk.
  nUserID | The user ID of the user to mute (or unmute).
  nStreamType | The type of stream to change, either STREAMTYPE_VOICE or STREAMTYPE_MEDIAFILE_AUDIO.
  bMute | TRUE will mute, FALSE will unmute.

See also
  TT_SetSoundOutputMute

## ◆ TT_SetUserStoppedPlaybackDelay()

TEAMTALKDLL_API TTBOOL TT_SetUserStoppedPlaybackDelay | ( | IN TTInstance * | lpTTInstance,
|  | IN INT32 | nUserID,
|  | IN StreamType | nStreamType,
|  | IN INT32 | nDelayMSec )

Set the delay of when a user should no longer be considered as playing audio (either voice or audio from media file).

When a user starts talking the CLIENTEVENT_USER_STATECHANGE is triggered with `uUserState` changing. A user will remain in this active state until no packets are received from this user, plus a delay (due to network interruptions). This delay is by default set to 500 msec but can be changed by calling TT_SetUserStoppedTalkingDelay().

Parameters

  lpTTInstance | Pointer to client instance created by TT_InitTeamTalk.
  nUserID | The user ID of the user.
  nStreamType | Either STREAMTYPE_VOICE or STREAMTYPE_MEDIAFILE_AUDIO.
  nDelayMSec | Delay in milliseconds.

## ◆ TT_SetUserJitterControl()

TEAMTALKDLL_API TTBOOL TT_SetUserJitterControl | ( | IN TTInstance * | lpTTInstance,
|  | IN INT32 | nUserID,
|  | IN StreamType | nStreamType,
|  | IN const JitterConfig * | lpJitterConfig )

Set the configuration for de-jitter measures for a user.

TeamTalk can add a fixed delay at the start of the playout of a user stream. This delay acts as a buffer to smooth out jittering (non-constant delays) in the reception of network packets. The fixed delay is applied at the start of every new stream, such as a new PTT session. The default fixed delay is zero.

TeamTalk can also apply adaptive jitter buffering where the actual jitter is measured and the delay at the start of a stream is adapted based on those measurements. The adaptive delay will not go below the fixed delay. The parameter nMaxAdaptiveDelayMSec maximizes the total adaptive delay. By default, the adaptive mechanism is OFF

By default, all jitter control is OFF

The result of jitter buffering is that playout frames will get buffered in the playout buffer. Make sure to also size the playout buffer for the expected jitter via TT_SetUserAudioStreamBufferSize

Parameters

  lpTTInstance | Pointer to client instance created by TT_InitTeamTalk.
  nUserID | The user ID of the user to apply the configuration to.
  nStreamType | The type of stream to change, currently only STREAMTYPE_VOICE is supported. Other types are a no-op.
  lpJitterConfig | The jitter buffer configuration.

## ◆ TT_GetUserJitterControl()

TEAMTALKDLL_API TTBOOL TT_GetUserJitterControl | ( | IN TTInstance * | lpTTInstance,
|  | IN INT32 | nUserID,
|  | IN StreamType | nStreamType,
|  | IN JitterConfig * | lpJitterConfig )

Get the de-jitter configuration for a user.

See also
  TT_SetUserJitterControl()

Parameters

  lpTTInstance | Pointer to client instance created by TT_InitTeamTalk.
  nUserID | The user ID of the user to apply the configuration to.
  nStreamType | The type of stream to change, currently only STREAMTYPE_VOICE is supported. Other types are a no-op.
  lpJitterConfig | Pointer to an application-provided jitter buffer configuration that will be filled upon return.

## ◆ TT_SetUserPosition()

TEAMTALKDLL_API TTBOOL TT_SetUserPosition | ( | IN TTInstance * | lpTTInstance,
|  | IN INT32 | nUserID,
|  | IN StreamType | nStreamType,
|  | IN float | x,
|  | IN float | y,
|  | IN float | z )

Set the position of a user.

3D sound position requires SOUNDDEVICEFEATURE_3DPOSITION.

This can only be done using DirectSound (SOUNDSYSTEM_DSOUND), a mono channel and with sound duplex mode (CLIENT_SNDINOUTPUT_DUPLEX) disabled.

Parameters

  lpTTInstance | Pointer to client instance created by TT_InitTeamTalk.
  nUserID | ID of user.
  nStreamType | The type of stream to change, either STREAMTYPE_VOICE or STREAMTYPE_MEDIAFILE_AUDIO.
  x | Distance in meters to user (left/right).
  y | Distance in meters to user (back/forward).
  z | Distance in meters to user (up/down).

## ◆ TT_SetUserStereo()

TEAMTALKDLL_API TTBOOL TT_SetUserStereo | ( | IN TTInstance * | lpTTInstance,
|  | IN INT32 | nUserID,
|  | IN StreamType | nStreamType,
|  | IN TTBOOL | bLeftSpeaker,
|  | IN TTBOOL | bRightSpeaker )

Set whether a user should speak in the left, right or both speakers. This function only works if AudioCodec has been set to use stereo.

Parameters

  lpTTInstance | Pointer to client instance created by TT_InitTeamTalk.
  nUserID | ID of user.
  nStreamType | The type of stream to change, either STREAMTYPE_VOICE or STREAMTYPE_MEDIAFILE_AUDIO.
  bLeftSpeaker | TRUE if user should be played in left speaker.
  bRightSpeaker | TRUE if user should be played in right speaker.

## ◆ TT_SetUserMediaStorageDir()

TEAMTALKDLL_API TTBOOL TT_SetUserMediaStorageDir | ( | IN TTInstance * | lpTTInstance,
|  | IN INT32 | nUserID,
|  | IN const TTCHAR * | szFolderPath,
|  | IN const TTCHAR * | szFileNameVars,
|  | IN AudioFileFormat | uAFF )

Store user's audio to disk.

Set the path of where to store audio from a user to disk. Event CLIENTEVENT_USER_RECORD_MEDIAFILE is triggered when recording starts/stops.

To stop recording set szFolderPath to an empty string and uAFF to AFF_NONE.

To store audio of users not in current channel of the client instance check out the section Spying on Users.

Parameters

  lpTTInstance | Pointer to client instance created by TT_InitTeamTalk.
  nUserID | The ID of the User which should store audio to disk. Pass 0 to store local instance's media stream.
  szFolderPath | The path on disk to where files should be stored. This value will be stored in szMediaStorageDir of User.
  szFileNameVars | The file name used for audio files can consist of the following variables: %nickname%, %username%, %userid%, %counter%, %starttick% and a specified time based on `strftime` (google `'strftime'` for a description of the format. The default format used by TeamTalk is: '%Y%m%d-%H%M%S #%userid% %username%'. The %counter% variable is a 9 digit integer which is incremented for each audio file. The file extension is automatically appended based on the file type (.wav for AFF_WAVE_FORMAT and .mp3 for AFF_MP3_*_FORMAT). Pass NULL or empty string to revert to default format.
  uAFF | The AudioFileFormat to use for storing audio files. Passing AFF_NONE will cancel/reset the current recording.

Returns
  FALSE if path is invalid, otherwise TRUE.

See also
  User
  CLIENTEVENT_USER_RECORD_MEDIAFILE

## ◆ TT_SetUserMediaStorageDirEx()

TEAMTALKDLL_API TTBOOL TT_SetUserMediaStorageDirEx | ( | IN TTInstance * | lpTTInstance,
|  | IN INT32 | nUserID,
|  | IN const TTCHAR * | szFolderPath,
|  | IN const TTCHAR * | szFileNameVars,
|  | IN AudioFileFormat | uAFF,
|  | IN INT32 | nStopRecordingExtraDelayMSec )

Store user's audio to disk.

This extension has an extra parameter for an aditional delay that will be waited before closing the per-user recording. This allows the recording to still capture all voice of a stream in a single file even if there's heavy network jitter. A recording will always be started if a different stream is received for the user. The delay is added on top of the standard playout delay that can be set via

Note that the delay starts after the last packet was written to the playout and thus the delay is already 'counting' when the jitter-buffered playout is still playing

Only supported for STREAMTYPE_VOICE.

Parameters

  lpTTInstance | Pointer to client instance created by TT_InitTeamTalk.
  nUserID | See description in TT_SetUserMediaStorageDir()
  szFolderPath | See description in TT_SetUserMediaStorageDir()
  szFileNameVars | See description in TT_SetUserMediaStorageDir()
  uAFF | See description in TT_SetUserMediaStorageDir()
  nStopRecordingExtraDelayMSec | Extra delay before closing the recording file default is 0.

Returns
  FALSE if path is invalid, otherwise TRUE.

See also
  TT_SetUserMediaStorageDir()

## ◆ TT_SetUserAudioStreamBufferSize()

TEAMTALKDLL_API TTBOOL TT_SetUserAudioStreamBufferSize | ( | IN TTInstance * | lpTTInstance,
|  | IN INT32 | nUserID,
|  | IN StreamTypes | uStreamType,
|  | IN INT32 | nMSec )

Change the amount of media data which can be buffered in the user's playback queue.

Increasing the media buffer size is especially important when the user is currently streaming a media file using TT_StartStreamingMediaFileToChannel(). Once streaming has finished it is recommended to reset the media buffer, i.e. setting it to zero.

A simple way to notify users that the client instance is streaming a media file is to change the status of the local client instance using TT_DoChangeStatus() or to send a TextMessage using TT_DoTextMessage().

Parameters

  lpTTInstance | Pointer to client instance created by TT_InitTeamTalk.
  nUserID | The ID of the user who should have changed the size of the media buffer.
  uStreamType | The stream type to apply the buffer for, i.e. either STREAMTYPE_VOICE or STREAMTYPE_MEDIAFILE_AUDIO.
  nMSec | The number of miliseconds of audio and video which should be allowed to be stored in the media buffer. 2000 - 3000 msec is a good size for a media buffer. Set the media buffer size to 0 msec to reset the media buffer to its default value.

## ◆ TT_AcquireUserAudioBlock()

TEAMTALKDLL_API AudioBlock * TT_AcquireUserAudioBlock | ( | IN TTInstance * | lpTTInstance,
|  | IN StreamTypes | uStreamTypes,
|  | IN INT32 | nUserID )

Extract the raw audio associated with the event CLIENTEVENT_USER_AUDIOBLOCK.

To enable access to raw audio first call TT_EnableAudioBlockEvent(). Whenever new audio becomes available the event CLIENTEVENT_USER_AUDIOBLOCK is generated and TT_AcquireUserAudioBlock() can be called to extract the audio.

The AudioBlock contains shared memory with the local client instance therefore always remember to call TT_ReleaseUserAudioBlock() to release the shared memory.

Parameters

  lpTTInstance | Pointer to client instance created by TT_InitTeamTalk.
  uStreamTypes | The stream type to extract, either STREAMTYPE_VOICE STREAMTYPE_MEDIAFILE_AUDIO, STREAMTYPE_LOCALMEDIAPLAYBACK_AUDIO.
  nUserID | The ID of the user to retrieve the AudioBlock from. Basically TTMessage's `nSource` from CLIENTEVENT_USER_AUDIOBLOCK.

See also
  TT_ReleaseUserAudioBlock()
  TT_EnableAudioBlockEvent()
  CLIENTEVENT_USER_AUDIOBLOCK

## ◆ TT_ReleaseUserAudioBlock()

TEAMTALKDLL_API TTBOOL TT_ReleaseUserAudioBlock | ( | IN TTInstance * | lpTTInstance,
|  | IN AudioBlock * | lpAudioBlock )

Release the shared memory of an AudioBlock.

All AudioBlock-structures extracted through TT_AcquireUserAudioBlock() must be released again since they share memory with the local client instance.

Never access `lpAudioBlock` after releasing its AudioBlock. This will cause the application to crash with a memory exception.

See also
  TT_AcquireUserAudioBlock()
  CLIENTEVENT_USER_AUDIOBLOCK