repository·master·Indexed 43 days ago
https://github.com/theholywaffle/teamspeak-3-java-apiA Java wrapper for the TeamSpeak 3 Server Query API providing synchronous and asynchronous implementations for managing TeamSpeak servers. It includes tools for server configuration via TS3Config, client metadata retrieval through the Client class, and command generation for bans, channels, and channel groups.
The FloodRate setting controls how frequently commands are sent to prevent the server from banning your account for spamming.
FloodRate.DEFAULT for standard accounts.FloodRate.UNLIMITED only if your query IP is explicitly whitelisted in the TeamSpeak server's query_ip_whitelist.txt file.To interact with a TeamSpeak 3 server, follow these steps:
TS3Config object.TS3Query object using that configuration.TS3Query#connect() to establish the connection.TS3Query#getApi().TS3Api object to execute commands.final TS3Config config = new TS3Config();
config.setHost("77.77.77.77");
final TS3Query query = new TS3Query(config);
query.connect();
final TS3Api api = query.getApi();
api.login("serveradmin", "serveradminpassword");
api.selectVirtualServerById(1);
api.setNickname("PutPutBot");
api.sendChannelMessage("PutPutBot is online!");If you are using Maven, the easiest way to enable logging is to add slf4j-simple. This allows you to see messages such as raw client-server communication if you configure it to DEBUG level via a simplelogger.properties file.
<dependency>
<groupId>org.slf4j</groupId>
<artifactId>slf4j-simple</artifactId>
<version>1.7.25</version>
</dependency>You can integrate the API into your project using either a standalone JAR or Maven.
Download the latest release and add the JAR to your project's buildpath.
Add the following dependency to your pom.xml:
<dependency>
<groupId>com.github.theholywaffle</groupId>
<artifactId>teamspeak3-api</artifactId>
<version>...</version>
</dependency>Note on Logging: The API uses SLF4J for logging but does not ship with a default implementation when using Maven. You must manually add a logging framework (like slf4j-simple) to your pom.xml to see any logs.
<dependency>
<groupId>com.github.theholywaffle</groupId>
<artifactId>teamspeak3-api</artifactId>
<version>...</version>
</dependency>Use the TS3Config class to define connection parameters and behavior.
| Option | Description | Method signature | Default value | Required |
|---|---|---|---|---|
| Host/IP | IP/Host of TeamSpeak 3 server. | setHost(String) | yes | |
| QueryPort | Query port of TeamSpeak 3 server. | setQueryPort(int) | 10011 | no |
| FloodRate | Prevents possible spam to the server. | setFloodRate(FloodRate) | FloodRate.DEFAULT | no |
| Communications logging | Log client-server communication. | setEnableCommunicationsLogging(boolean) | false | no |
| Command timeout | Time until a command waiting for a response fails | setCommandTimeout(int) | 4000 (ms) | no |
Command represents a single TeamSpeak server query command. It encapsulates the command's name, its associated Parameter collection, and a CommandFuture which handles the asynchronous response. When a command is executed, the result is typically returned via a CommandFuture containing a DefaultArrayResponse.The getIconId method generates a unique identifier for an icon based on its raw byte data using a CRC32 checksum. This is used to identify icons within the TeamSpeak system.
Parameters:
data: The byte[] representing the icon data.Returns: A long representing the CRC32 checksum of the data.
byte[] iconData = // ... raw icon bytes
long iconId = FileTransferHelper.getIconId(iconData);The PrivilegeKeyCommands class provides static factory methods to construct Command objects for managing TeamSpeak 3 privilege keys. These commands can be used to add, delete, list, or use privilege keys via the API.
privilegeKeyAddCreates a command to add a new privilege key.
type (PrivilegeKeyType): The type of privilege key. Must not be null.groupId (int): The ID of the group associated with the token.channelId (int): The ID of the channel associated with the token.description (String, optional): A description for the key. If null, the parameter is omitted.privilegekeyadd with parameters tokentype, tokenid1, tokenid2, and optionally tokendescription.privilegeKeyDeleteCreates a command to delete a specific privilege key.
token (String): The privilege key token. Must be a non-empty string.privilegekeydelete with parameter token.privilegeKeyListCreates a command to list all existing privilege keys.
privilegekeylist (no parameters).privilegeKeyUseCreates a command to use a specific privilege key.
token (String): The privilege key token. Must be a non-empty string.privilegekeyuse with parameter token.// Example: Adding a privilege key
Command addCmd = PrivilegeKeyCommands.privilegeKeyAdd(PrivilegeKeyType.GROUP, 6, 1, "Admin Token");
// Example: Deleting a privilege key
Command deleteCmd = PrivilegeKeyCommands.privilegeKeyDelete("ABC123XYZ");
// Example: Listing privilege keys
Command listCmd = PrivilegeKeyCommands.privilegeKeyList();
// Example: Using a privilege key
Command useCmd = PrivilegeKeyCommands.privilegeKeyUse("ABC123XYZ");To respond to server-side events (like client joins, messages, or channel changes), you must register one or more TS3Listener implementations with the EventManager. The EventManager handles the asynchronous dispatching of events to your listeners using an internal queue to ensure that event processing does not block the main query execution.
// Assuming you have access to the EventManager instance
eventManager.addListeners(new MyCustomListener());The QueryCommands class provides static factory methods to construct Command objects used for interacting with a TeamSpeak 3 server via the query interface. These methods abstract the underlying command syntax, parameters, and options into a type-safe Java API.
Available commands include:
logIn(username, password): Authenticates the query connection.logOut(): Ends the current session.quit(): Terminates the connection.serverNotifyRegister(eventType, channelId): Registers for specific server events.serverNotifyUnregister(): Unregisters from all server events.useId(id, nickname): Switches to a specific client ID.usePort(port, nickname): Switches to a specific port.whoAmI(): Returns information about the current connection.import com.github.theholywaffle.teamspeak3.commands.QueryCommands;
import com.github.theholywaffle.teamspeak3.commands.Command;
// Example: Creating a login command
Command login = QueryCommands.logIn("serveradmin", "password123");
// Example: Registering for client move events on a specific channel
Command register = QueryCommands.serverNotifyRegister(TS3EventType.CLIENT_MOVE, 123);
// Example: Switching to a specific client ID with a nickname
Command use = QueryCommands.useId(5, "MyNickname");Use channelList() to build a command that retrieves a list of channels. This command supports several optional parameters to filter or expand the returned data:
topicflagsvoicelimitsiconsecondsemptybannersCommand cmd = ChannelCommands.channelList();The instanceEdit(Map<ServerInstanceProperty, String> options) method allows you to modify properties of a server instance. You must provide a map where the keys are ServerInstanceProperty enums and the values are the new settings as strings.
Map<ServerInstanceProperty, String> settings = new HashMap<>();
settings.put(ServerInstanceProperty.SOME_PROPERTY, "new_value");
Command editCmd = ServerCommands.instanceEdit(settings);