Whisper Lists

Introduction

This article will guide you through extending your Hello World Server application with the TeamSpeak Whisper feature to establish custom audio routing for clients.

Useful for

• Global announcements to all users connected to a server
• Communication to multiple users that are not in the same channel
• One-on-one private voice chat while in separate channels
• Communications between officers, team leaders, or instructors

Learn how to

• Set whisper lists
• Enable and disable whisper lists
• Toggle whisper lists

Let’s code

For demonstration purposes, we’ll create a toggle that switches between the default audio routing and allowing all users talking to each other without channel borders.

Setting whisper lists

To accomplish this, we will focus on the function unsigned int ts3server_setClientWhisperList(uint64 server_id, anyID client_id, const uint64* channel_ids, const anyID* client_ids);.

To get started, we’ll create a function void toggle_whisper(uint64 server_id) {} and add a global boolean bool is_whispering = false; for the status.

Since we want to toggle whispering for all clients in our example, and the function sets a whisperlist for a single client, the first thing we do is to get all clients on the virtual server.

anyID* all_clients_online;
ts3server_getClientList(server_id, &all_clients_online);

ts3server_freeMemory(all_clients_online);
is_whispering = !is_whispering;

So that we don’t forget about it later, we add the call to ts3server_freeMemory now, too. In our writeup we do not include error checking. In your production code, make sure to only free memory if the corresponding call resulted in ERROR_ok. See the full source code for reference.

Enable Whispering

If is_whispering is false, we want to enable it. Since there won’t be anything to do if there’s no client on the server, we check for that first. If there are clients, we want them to whisper to all channels, therefore we get the channel list of the virtual server:

if (is_whispering == false)
{
    if (all_clients_online[0] != 0)
    {
        uint64* all_channels;
        if (ts3server_getChannelList(server_id, &all_channels) == ERROR_ok)
        {
            ts3server_freeMemory(all_channels);
        }
    }
}

Finally, all we need to do is iterate through the clients and set their whisper list. This results in:

if (is_whispering == false)
{
    if (all_clients_online[0] != 0)
    {
        uint64* all_channels;
        if (CHECK_ERROR(ts3server_getChannelList(server_id, &all_channels)))
        {
            for (int i = 0; all_clients_online[i] != 0; ++i)
            {
                ts3server_setClientWhisperList(server_id, all_clients_online[i], all_channels, NULL);
            }
            ts3server_freeMemory(all_channels);
        }
    }
}

Disable Whispering

We’ve created the functionality to set whisper lists for clients, but we also want to toggle back to the default behaviour. We can do this by setting the whisper list to an empty channel and client id array.

else
{
    for (int i = 0; all_clients_online[i] != 0; ++i)
    {
        ts3server_setClientWhisperList(server_id, all_clients_online[i], NULL, NULL);
    }
}

Summing up

We’ve created a function to toggle whispering with the following source code:

bool is_whispering = false;

void toggle_whisper(uint64 server_id)
{
    anyID* all_clients_online;
    ts3server_getClientList(server_id, &all_clients_online);

    if (is_whispering == false)
    {
        if (all_clients_online[0] != 0)
        {
            uint64* all_channels;
            if (ts3server_getChannelList(server_id, &all_channels) == ERROR_ok)
            {
                for (int i = 0; all_clients_online[i] != 0; ++i)
                {
                    ts3server_setClientWhisperList(server_id, all_clients_online[i], all_channels, NULL);
                }
                ts3server_freeMemory(all_channels);
            }
        }
    }
    else
    {
        for (int i = 0; all_clients_online[i] != 0; ++i)
        {
            ts3server_setClientWhisperList(server_id, all_clients_online[i], NULL, NULL);
        }
    }

    ts3server_freeMemory(all_clients_online);
    is_whispering = !is_whispering;
}

Congratulations!

You have extended your Hello World server application using the TeamSpeak SDK with custom audio routing.