Examples

You can find more examples in the ts3.examples package.

• Show all clients on the virtual server with the server id 1:

  #!/usr/bin/python3
  
  import ts3
  
  with ts3.query.TS3ServerConnection("localhost") as ts3conn:
          # Note, that the client will wait for the response and raise a
          # **TS3QueryError** if the error id of the response is not 0.
          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)
  
          # Each query method will return a **TS3QueryResponse** instance,
          # with the response.
          resp = ts3conn.clientlist()
          print("Clients on the server:", resp.parsed)
          print("Error:", resp.error["id"], resp.error["msg"])
  
          # Note, the TS3Response class and therefore the TS3QueryResponse
          # class too, can work as a rudimentary container. So, these two
          # commands are equal:
          for client in resp.parsed:
                  print(client)
          for client in resp:
                  print(client)

• Say hello to all clients:

  #!/usr/bin/python3
  
  import ts3
  
  with ts3.query.TS3ServerConnection("localhost") as ts3conn:
          ts3conn.login(
                  client_login_name="serveradmin",
                  client_login_password="FoOBa9"
          )
          ts3conn.use(sid=1)
  
          for client in ts3conn.clientlist():
                  msg = "Hi {}".format(client["client_nickname"])
                  ts3conn.clientpoke(clid=client["clid"], msg=msg)

• Say hello to all clients but use it with the ClientQuery plugin instead of a ServerQuery connection:

  #!/usr/bin/python3
  
  import ts3
  
  with ts3.query.TS3Connection("localhost", 25639) as ts3conn:
          ts3conn.auth(apikey="AAAA-BBBB-CCCC-DDDD-EEEEh")
  
          for client in ts3conn.clientlist():
                  msg = "Hi {}".format(client["client_nickname"])
                  ts3conn.clientpoke(clid=client["clid"], msg=msg)

• Event handling (Server Query):

  #!/usr/bin/python3
  
  import time
  import ts3
  
  with ts3.query.TS3ServerConnection("localhost") as ts3conn:
          ts3conn.login(
                  client_login_name="serveradmin",
                  client_login_password="FoOBa9"
          )
          ts3conn.use(sid=1)
  
          # Register for events
          ts3conn.servernotifyregister(event="server")
  
          while True:
                  event = ts3conn.wait_for_event()
  
                  # Greet new clients.
                  if event[0]["reasonid"] == "0":
                          print("client connected")
                          ts3conn.clientpoke(clid=event[0]["clid"], msg="Hello :)")

• A simple TS3 viewer:

  #!/usr/bin/python3
  
  import ts3
  
  # The examples package already contains this implementation.
  # Note, that the ts3.examples.viewer module has an helpful class to
  # build a complete channel tree of a virtual server: ChannelTreeNode
  from ts3.examples.viewer import view
  
  with ts3.query.TS3ServerConnection("localhost") as ts3conn:
          ts3conn.login(
                  client_login_name="serveradmin",
                  client_login_password="FoOBa9"
          )
          view(ts3conn, sid=1)

• Download and upload files:

  #!/usr/bin/python3
  
  import ts3
  
  with ts3.query.TS3ServerConnection("localhost") as ts3conn:
          ts3conn.login(
                  client_login_name="serveradmin",
                  client_login_password="FoOBa9"
          )
  
          # Create a new TS3FileTransfer instance associated with the
          # TS3ServerConnection.
          ts3ft = ts3.filetransfer.TS3FileTransfer(ts3conn)
  
          # Upload the image *baz.png* to the channel with the id 2 on the
          # TS3 server.
          # Note the opening mode ("rb").
          with open("baz.png", "rb") as file:
                  ts3ft.init_upload(input_file=file, name="/baz.png", cid=2)
  
          # Download the file into *baz1.png*.
          with open("baz1.png", "wb") as file:
                  ts3ft.init_download(output_file=file, name="/baz.png", cid=2)

• Event handling (Client Query):

  #!/usr/bin/python3
  
  import time
  import ts3
  
  with ts3.query.TS3ClientConnection("localhost") as ts3conn:
          ts3conn.auth(apikey="AAAA-....-EEEE")
          ts3conn.use()
  
          # Register for events
          ts3conn.clientnotifyregister(event="any")
  
          while True:
                  event = ts3conn.wait_for_event()
                  print(event.parsed)