TeamTalk 5 C-API DLL Version 5.15A
Loading...
Searching...
No Matches
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 TTSoundLoopTT_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 TTSoundLoopTT_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 AudioBlockTT_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

◆ 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

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 4183 of file TeamTalk.h.

Enumeration Type Documentation

◆ 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

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
lpnInputDeviceIDThe ID of the default input device.
lpnOutputDeviceIDThe 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
lpSoundDevicesArray of SoundDevice-structs where lpnHowMany holds the size of the array. Pass NULL as lpSoundDevices to query the number of devices.
lpnHowManyThis 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
nInputDeviceIDShould be the nDeviceID extracted through TT_GetSoundDevices().
nOutputDeviceIDShould be the nDeviceID extracted through TT_GetSoundDevices().
nSampleRateThe sample rate the client's recorder should use.
nChannelsNumber of channels to use, i.e. 1 = mono, 2 = stereo.
bDuplexModeBoth 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
lpAudioPreprocessorThe preprocessing settings to use, i.e. AGC and denoising properties. Pass NULL to ignore AGC, denoise and AEC.
lpSoundDeviceEffectsThe 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
lpTTSoundLoopPointer 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:

Calling this function will set the flag CLIENT_SNDINPUT_READY.

Parameters
lpTTInstancePointer to client instance created by TT_InitTeamTalk.
nInputDeviceIDThe 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
nSampleRateThe sample rate to use on the shared device. Must exist in SoundDevice's inputSampleRates. Pass zero to reset to default behaviour.
nChannelsThe number of channels to use (mono, stereo). Must be less or equals to SoundDevice's nMaxInputChannels. Pass zero to reset to default behaviour.
nFrameSizeThe 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:

Callling this function will set the flag CLIENT_SNDOUTPUT_READY.

Parameters
lpTTInstancePointer to client instance created by TT_InitTeamTalk.
nOutputDeviceIDThe 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
nSampleRateThe sample rate to use on the shared device. Must exist in SoundDevice's outputSampleRates. Pass zero to reset to default behaviour.
nChannelsThe number of channels to use (mono, stereo). Must be less or equals to SoundDevice's nMaxOutputChannels. Pass zero to reset to default behaviour.
nFrameSizeThe 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:

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
lpTTInstancePointer to client instance created by TT_InitTeamTalk.
nInputDeviceIDThe nDeviceID of SoundDevice extracted through TT_GetSoundDevices().
nOutputDeviceIDThe 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
lpTTInstancePointer 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
lpTTInstancePointer 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
lpTTInstancePointer 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():

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.

If WebRTCAudioPreprocessor is active with levelestimation enabled then the current input level is based on WebRTC's level estimater.

Parameters
lpTTInstancePointer 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
lpTTInstancePointer to client instance created by TT_InitTeamTalk.
nLevelA 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
lpTTInstancePointer 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
lpTTInstancePointer to client instance created by TT_InitTeamTalk.
lpSpeexDSPThe 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
lpTTInstancePointer to client instance created by TT_InitTeamTalk.
lpSpeexDSPA 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
lpTTInstancePointer to client instance created by TT_InitTeamTalk.
lpAudioPreprocessorThe 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
lpTTInstancePointer to client instance created by TT_InitTeamTalk.
lpAudioPreprocessorA 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
lpTTInstancePointer to client instance created by TT_InitTeamTalk.
nVolumeA 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
lpTTInstancePointer 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
lpTTInstancePointer to client instance created by TT_InitTeamTalk.
bMuteAllWhether 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
lpTTInstancePointer to client instance created by TT_InitTeamTalk.
bEnableTRUE 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
lpTTInstancePointer 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
lpTTInstancePointer to client instance created by TT_InitTeamTalk.
nUserIDSee description in TT_EnableAudioBlockEventEx()
uStreamTypesSee description in TT_EnableAudioBlockEventEx()
bEnableSee 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:

Parameters
lpTTInstancePointer to client instance created by TT_InitTeamTalk.
nUserIDUser ID has different meanings depending on the StreamType being passed.

For STREAMTYPE_VOICE:

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
uStreamTypesEither 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.
lpAudioFormatResample 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
bEnableWhether 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
lpTTInstancePointer to client instance created by TT_InitTeamTalk.
nUserIDThe ID of the user whose volume will be changed.
nStreamTypeThe type of stream to change, either STREAMTYPE_VOICE or STREAMTYPE_MEDIAFILE_AUDIO.
nVolumeMust 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
lpTTInstancePointer to client instance created by TT_InitTeamTalk.
nUserIDThe user ID of the user to mute (or unmute).
nStreamTypeThe type of stream to change, either STREAMTYPE_VOICE or STREAMTYPE_MEDIAFILE_AUDIO.
bMuteTRUE 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
lpTTInstancePointer to client instance created by TT_InitTeamTalk.
nUserIDThe user ID of the user.
nStreamTypeEither STREAMTYPE_VOICE or STREAMTYPE_MEDIAFILE_AUDIO.
nDelayMSecDelay 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
lpTTInstancePointer to client instance created by TT_InitTeamTalk.
nUserIDThe user ID of the user to apply the configuration to.
nStreamTypeThe type of stream to change, currently only STREAMTYPE_VOICE is supported. Other types are a no-op.
lpJitterConfigThe 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
lpTTInstancePointer to client instance created by TT_InitTeamTalk.
nUserIDThe user ID of the user to apply the configuration to.
nStreamTypeThe type of stream to change, currently only STREAMTYPE_VOICE is supported. Other types are a no-op.
lpJitterConfigPointer 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
lpTTInstancePointer to client instance created by TT_InitTeamTalk.
nUserIDID of user.
nStreamTypeThe type of stream to change, either STREAMTYPE_VOICE or STREAMTYPE_MEDIAFILE_AUDIO.
xDistance in meters to user (left/right).
yDistance in meters to user (back/forward).
zDistance 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
lpTTInstancePointer to client instance created by TT_InitTeamTalk.
nUserIDID of user.
nStreamTypeThe type of stream to change, either STREAMTYPE_VOICE or STREAMTYPE_MEDIAFILE_AUDIO.
bLeftSpeakerTRUE if user should be played in left speaker.
bRightSpeakerTRUE 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
lpTTInstancePointer to client instance created by TT_InitTeamTalk.
nUserIDThe ID of the User which should store audio to disk. Pass 0 to store local instance's media stream.
szFolderPathThe path on disk to where files should be stored. This value will be stored in szMediaStorageDir of User.
szFileNameVarsThe 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.
uAFFThe 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
lpTTInstancePointer to client instance created by TT_InitTeamTalk.
nUserIDSee description in TT_SetUserMediaStorageDir()
szFolderPathSee description in TT_SetUserMediaStorageDir()
szFileNameVarsSee description in TT_SetUserMediaStorageDir()
uAFFSee description in TT_SetUserMediaStorageDir()
nStopRecordingExtraDelayMSecExtra 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
lpTTInstancePointer to client instance created by TT_InitTeamTalk.
nUserIDThe ID of the user who should have changed the size of the media buffer.
uStreamTypeThe stream type to apply the buffer for, i.e. either STREAMTYPE_VOICE or STREAMTYPE_MEDIAFILE_AUDIO.
nMSecThe 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
lpTTInstancePointer to client instance created by TT_InitTeamTalk.
uStreamTypesThe stream type to extract, either STREAMTYPE_VOICE STREAMTYPE_MEDIAFILE_AUDIO, STREAMTYPE_LOCALMEDIAPLAYBACK_AUDIO.
nUserIDThe 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