ts3-switcher

Windows utility for moving selected TeamSpeak 3 users between two channels. It is intended for World of Warcraft raid encounters where the group must split into separate voice channels for a mechanic, then merge again for the next phase or after the fight. One example is L'ura in a World of Warcraft: Midnight raid.

The switcher uses TeamSpeak's ServerQuery interface. It does not modify the TeamSpeak client.

Features

• Move a configured group to a split channel or merge channel.
• Trigger moves from the GUI, system-wide hotkeys, or trigger files.
• Select users and channels in the Windows GUI.
• Keep selected offline users ready for the next move.
• Reconnect automatically after an established ServerQuery connection is interrupted.
• Run as a GUI application or a console application.

Requirements

• Windows 64-bit.
• A TeamSpeak 3 ServerQuery account allowed to list clients and move them between the configured channels.

Release downloads are self-contained and do not require a separate .NET installation.

Installation

1. Download ts3-switcher-gui-win-x64.zip or ts3-switcher-cli-win-x64.zip from the latest GitHub Release.
2. Extract the ZIP to a writable directory.
3. Run the executable once to create config.json beside it.
4. Close the application and enter the TeamSpeak connection details in config.json.
5. Restart the application, then select the target users and split/merge channels in the GUI.

config.json contains the ServerQuery password and TeamSpeak client identifiers in plaintext. Keep it private and do not commit it.

TeamSpeak setup

Create a ServerQuery login

A TeamSpeak administrator must create the login from a TeamSpeak client identity with permission to list clients and move them:

1. Connect to the TeamSpeak server with the administrator identity.
2. Open Tools > ServerQuery Login.
3. Enter a login name and create the login.
4. Copy the generated password immediately. TeamSpeak only displays it once.
5. Put the login name in Username and the generated password in Password in config.json.

This is a ServerQuery login, not the password used to connect with the normal TeamSpeak client.

Configure the server

Set these fields in config.json:

Field	Value
Host	TeamSpeak server hostname or IP address.
QueryPort	ServerQuery port, normally 10011.
Username	Name created under Tools > ServerQuery Login.
Password	Password generated for that ServerQuery login.
VirtualServerId	Numeric ID of the virtual TeamSpeak server.

To find VirtualServerId, first enter the correct host, query port, username, and password, but leave the default server ID. Start the application and check its log. If that ID is invalid, the switcher prints the available virtual servers in this form:

Available virtual servers:
  Id=1  Port=9987  Status=Online  Clients=20/64  Name=Raid Server

Copy the required Id into VirtualServerId and restart the application. A normal installation with one TeamSpeak virtual server commonly uses ID 1.

After connecting, the GUI loads the channel tree and connected users. Select the users to move, choose the split and merge channels, configure the hotkeys, and apply the settings. The CLI prints the same channel IDs and client IDs for manual configuration.

Usage

The GUI supports selecting target users, choosing split and merge channels, assigning hotkeys, and moving users manually. Trigger-file paths and ServerQuery connection details are configured in config.json.

The CLI prints available channel IDs and connected client IDs after connecting. Configure at least one hotkey or trigger file before starting it.

Supported hotkeys are F1 through F24, letters, and digits. Letters and digits require at least one of Ctrl, Alt, Shift, or Win, for example Ctrl+Shift+M.

When a configured trigger file appears, the switcher deletes it and performs the associated move. This allows an external tool or game addon bridge to request a split or merge without sending TeamSpeak credentials to that tool.

Build

Building requires the .NET 10 SDK on Windows.

dotnet build ts3-switcher.sln

Run either application from source:

dotnet run --project Ts3Switcher.Gui
dotnet run --project Ts3Switcher.Cli

Create self-contained, single-file win-x64 builds under publish\:

publish.cmd

Use publish.cmd gui or publish.cmd cli to publish only one application. Equivalent tasks are available in VS Code.

Releases

Pushes and pull requests are built when source, project, build, or workflow files change. Documentation-only changes do not start a build. Pushing a tag in vX.Y.Z format always creates a GitHub Release with self-contained GUI and CLI ZIP files:

git tag v1.0.0
git push origin v1.0.0

Published releases are immutable: their tag and attached files cannot be changed. GitHub Actions records build provenance for both archives. After downloading an archive, verify that it was produced by this repository's release workflow:

gh attestation verify ts3-switcher-gui-win-x64.zip --repo MangelSpec/ts3-switcher

License

MIT, see LICENSE.