List available modes and devices

Various playback and capture modes are available: DirectSound on all Windows platforms, Windows Audio Session API for Windows 7 and newer, Alsa and PulseAudio on Linux and CoreAudio on Mac OS.

Note

Available device names may differ depending on the mode.

Query default modes

The default capture mode can be queried using

unsigned int ts3client_getDefaultCaptureMode(char **result)

Retrieve the current default capture mode.

Parameters:

result – Address of a char array to receive a c string indicating the default mode. Memory is allocated by the client lib and must be freed by caller using ts3client_freeMemory

Returns:

An Error code from the Ts3ErrorType enum indicating either success or the failure reason

The default playback mode can be queried using

unsigned int ts3client_getDefaultPlayBackMode(char **result)

Retrieve the current default playback mode.

Parameters:

result – Address of a char array to receive the c string indicating the default mode. Memory is allocated by the client lib and must be freed by caller using ts3client_freeMemory

Returns:

An Error code from the Ts3ErrorType enum indicating either success or the failure reason

List available modes

Available capture modes can be queries using

unsigned int ts3client_getCaptureModeList(char ***result)

Retrieve available capture modes.

Parameters:

result – address of a variable that receives a NULL terminated array of utf8 encoded c strings of available capture modes. Memory is allocated by the client lib and caller must free individual strings and the array itself using ts3client_freeMemory

Returns:

An Error code from the Ts3ErrorType enum indicating either success or the failure reason

To list available playback modes use

unsigned int ts3client_getPlaybackModeList(char ***result)

Retrieve available playback modes.

Parameters:

result – address of a variable that receives a NULL terminated array of utf8 encoded c strings of available playback modes. Memory is allocated by the client lib and caller must free individual strings and the array itself using ts3client_freeMemory

Returns:

An Error code from the Ts3ErrorType enum indicating either success or the failure reason

Examples

Example to query all available playback modes:

char** array;

if (ts3client_getPlaybackModeList(&array) == ERROR_ok) {
    for (int i = 0; array[i] != NULL; ++i) {
        printf("Mode: %s\n", array[i]);
        ts3client_freeMemory(array[i]);  // Free C-string
    }
    ts3client_freeMemory(array);  // Free the array
}

Get default devices

Note

Default devices are set by the operating system.

To get the default capture device use

unsigned int ts3client_getDefaultCaptureDevice(const char *modeID, char ***result)

Get the current operating system defined default capture device for the indicated mode.

The operating system may define different devices for different modes.

Parameters:

modeID – a string indicating a valid capture mode as retrieved by ts3client_getCaptureModeList or ts3client_getDefaultCaptureMode
result – Address of a variable that receives a NULL terminated array of two c strings like {char* deviceName, char* deviceID, NULL} Memory is allocated by the client lib and both the array and its individual members must be freed by caller using ts3client_freeMemory

Returns:

An Error code from the Ts3ErrorType enum indicating either success or the failure reason

To get the default playback device use

unsigned int ts3client_getDefaultPlaybackDevice(const char *modeID, char ***result)

Get the current operating system defined default playback device for the indicated mode.

The operating system may define different devices for different modes.

Parameters:

modeID – a string indicating a valid playback mode as retrieved by ts3client_getPlaybackModeList or ts3client_getDefaultPlayBackMode
result – Address of a variable that receives a NULL terminated array of two c strings like {char* deviceName, char* deviceID, NULL} Memory is allocated by the client lib and caller must free individual strings and the array itself using ts3client_freeMemory

Returns:

An Error code from the Ts3ErrorType enum indicating either success or the failure reason

Example

Example to query the default playback device:

char* defaultMode;

/* Get default playback mode */
if (ts3client_getDefaultPlayBackMode(&defaultMode) == ERROR_ok) {
    char** defaultPlaybackDevice;

    /* Get default playback device */
    if (ts3client_getDefaultPlaybackDevice(defaultMode, &defaultPlaybackDevice) == ERROR_ok) {
        printf("Default playback device name: %s\n", defaultPlaybackDevice[0]);  /* First element: Device name */
        printf("Default playback device ID: %s\n",   defaultPlaybackDevice[1]);  /* Second element: Device ID */

        /* Release the two array elements and the array */
        ts3client_freeMemory(defaultPlaybackDevice[0]);
        ts3client_freeMemory(defaultPlaybackDevice[1]);
        ts3client_freeMemory(defaultPlaybackDevice);
    } else {
        printf("Failed to get default playback device\n");
    }
    ts3client_freeMemory(defaultMode); // Free default Mode
} else {
    printf("Failed to get default playback mode\n");
}

List available devices

To list devices available for capture use

unsigned int ts3client_getCaptureDeviceList(const char *modeID, char ****result)

Retrieve available recording devices as reported by the operating system.

Parameters:

modeID – a string indicating a valid capture mode as retrieved by ts3client_getCaptureModeList or ts3client_getDefaultCaptureMode
result – address of a variable that receives a NULL terminated array like `{{char* deviceName, char* deviceId, char* interfaceName char* description, char* fromFactor} …, NULL}on windows,{{char* deviceName, char* deviceId}, …, NULL}` on other platforms. Memory is allocated by the client lib and caller must free individual strings and the array itself using ts3client_freeMemory

Returns:

An Error code from the Ts3ErrorType enum indicating either success or the failure reason

To list devices available for playback use

unsigned int ts3client_getPlaybackDeviceList(const char *modeID, char ****result)

Retrieve available playback devices as reported by the operating system.

Parameters:

modeID – a string indicating a valid playback mode as retrieved by ts3client_getPlaybackModeList or ts3client_getDefaultPlaybackMode
result – address of a variable that receives a NULL terminated array like {{char* deviceName, char* deviceId, char* interfaceName char* description, char* fromFactor} ..., NULL} on windows, {{char* deviceName, char* deviceId}, ..., NULL} on other platforms. Memory is allocated by the client lib and caller must free individual strings, array members and the array itself using ts3client_freeMemory

Returns:

An Error code from the Ts3ErrorType enum indicating either success or the failure reason

Example

Example to query all available playback devices:

char* defaultMode;

if (ts3client_getDefaultPlayBackMode(&defaultMode) == ERROR_ok) {
    char*** array;

    if (ts3client_getPlaybackDeviceList(defaultMode, &array) == ERROR_ok) {
        for (int i=0; array[i] != NULL; ++i) {
            printf("Playback device name: %s\n", array[i][0]);  /* First element: Device name */
            printf("Playback device ID: %s\n",   array[i][1]);  /* Second element: Device ID */
#ifdef _WIN32
            printf("Playback device interface name: %s\n", array[i][2]);  /* win only: Third element: Device interface name */
            printf("Playback device desription: %s\n",     array[i][3]);  /* win only: Forth element: Device description */
            printf("Playback device formFactor: %s\n",     array[i][4]);  /* win only: Fifth element: Device form factor */
            ts3client_freeMemory(array[i][3]);
            ts3client_freeMemory(array[i][4]);
            ts3client_freeMemory(array[i][5]); // also free the last element, being "\0"
#endif
            /* Free element */
            ts3client_freeMemory(array[i][0]);
            ts3client_freeMemory(array[i][1]);
            ts3client_freeMemory(array[i][2]);
            ts3client_freeMemory(array[i]);
        }
        ts3client_freeMemory(array);  /* Free complete array */
    } else {
        printf("Error getting playback device list\n");
    }
    ts3client_freeMemory(defaultMode); // free default mode
} else {
    printf("Error getting default playback mode\n");
}