PyTS3

PyTS3 is a Python 3.2+ package designed to interface with TeamSpeak 3 (TS3) servers. It provides a programmatic API for the following core functionalities:

• TS3 query connections: Establishing and managing connections to the TS3 server query interface.
• TS3 query events: Handling and responding to server-side events.
• TS3 file transfers: Managing file operations via the TS3 protocol.

Every query method returns a ts3.query.TS3QueryResponse instance.

• Use .parsed to access the parsed data.
• Use .error["id"] and .error["msg"] to inspect error details.
• The TS3QueryResponse class (and its parent TS3Response) acts as a container; you can iterate over the response object directly to loop through parsed items.

# Example of accessing parsed data and iterating
resp = ts3conn.clientlist()
print("Clients on the server:", resp.parsed)
print("Error:", resp.error["id"], resp.error["msg"])

# These two loops are equivalent:
for client in resp.parsed:
    print(client)
for client in resp:
    print(client)

The documentation currently describes v1. However, for new projects, it is highly recommended to use v2.

Key differences:

• v2 supports the TS3 client query interface and SSH.
• v1 is in maintenance mode and will only receive bug fixes, not new enhancements.

You can install the ts3 library directly from PyPi using pip3. To update the library to the latest version, use the --upgrade flag.

$ pip3 install ts3

# To update
$ pip3 install --upgrade ts3

If your application sends a high volume of queries, the TS3 server's anti-flood protection may close your connection. To prevent this, add your host's IP address to the query_ip_whitelist.txt file in your TS3 server directory.

$ echo "192.168.178.42" >> path/to/ts3/server/directory/query_ip_whitelist.txt

Install the ts3 package using pip3 to access the Python 3 API for TS3 query connections, events, and file transfers.

$ pip3 install ts3

If your Python script is being disconnected unexpectedly, the TeamSpeak 3 server might be triggering its anti-flood protection. By default, the server limits the number of queries a host can send per minute.

To resolve this, you can either increase the query limit in your TS3 server configuration or add the IP address of the machine running your script to the server's query whitelist by appending it to query_ip_whitelist.txt.

$ # In your TS3 server folder:
$ echo "192.168.178.42" >> query_ip_whitelist.txt

TeamSpeak 3 servers automatically close idle connections after 10 minutes. To prevent this, you must send a keepalive signal to the server. Use the send_keepalive method of the TS3BaseConnection class to send an empty query. Ensure this method is called at least once every 10 minutes to maintain the connection.

# Use the send_keepalive method on your connection instance
connection.send_keepalive()

The endless_poke.py script serves as an example of how to interact with a TeamSpeak 3 server using PyTS3. You can find the source code in the repository under ts3/examples/endless_poke.py.

# The content of endless_poke.py is included in the repository at:
# ts3/examples/endless_poke.py

The hello_bot.py example demonstrates how to create a basic TeamSpeak 3 bot using the py-ts3 library. This script typically connects to a TS3 server, handles basic events, and responds to user interactions. You can use this as a template for building more complex automation or bot features.

# Note: The actual implementation is located in the source file:
# ../../ts3/examples/hello_bot.py

The viewer.py script is an example implementation provided in the repository to demonstrate how to use the PyTS3 library. You can download or locate it in the ts3/examples/ directory to use as a reference for building your own TS3 client applications.

# The actual implementation is located at ts3/examples/viewer.py

Use ts3.query.TS3Connection as a context manager to establish a connection. Use .login() to authenticate.

Error Handling: The client waits for responses and will raise a ts3.query.TS3QueryError if the response error ID is not 0. You can access the error details via err.resp.error["msg"].

import ts3

with ts3.query.TS3Connection("localhost") as ts3conn:
    try:
        ts3conn.login(
            client_login_name="serveradmin",
            client_login_password="FoOBa9"
        )
    except ts3.query.TS3QueryError as err:
        print("Login failed:", err.resp.error["msg"])
        exit(1)

    ts3conn.use(sid=1)