TeamTalk Commander (TTCom) Users Guide
Doug Lee
Last Revised January, 2024

This is the user guide for TTCom, the TeamTalk Commander, also informally referred to as the TeamTalk Console or the TTCom text client. This client is mostly for managerial (not necessarily administrative) functions and is not an audio or video client. TTCom may be of use to those meeting any of these criteria:

This document describes how to install, launch, and use TTCom and its command set. For information on recent updates, or to see a history of TTCom's evolution, see the final "Release History section.

This program is Copyright (C) 2011-2024 by Doug Lee and falls under the GNU General Public License as found in LICENSE.txt. The ConfigObj and Six modules are under separate licenses and copyrights; see those files for details.

TTCom is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with this program as LICENSE.txt. If not, see http://www.gnu.org/licenses/.

Table of Contents

TTCom Versus Other TeamTalk Clients

TTCom provides fast ways to accomplish the following tasks for those who are ok with typing (or dictating) commands:

TTCom also offers the following features over other TeamTalk clients:

Of course, TTCom also has some disadvantages as compared to other clients:

System Requirements

TTCom should run on any operating system where Python 3.7 or later can be found. Python (though not necessarily a new enough version) comes by default on at least Linux and MacOS. It can also be installed on Windows, though a ttcom.exe application is provided for Windows users to avoid the need to install Python.

This author is aware of users having successfully used TTCom in the following environments, run from source unless otherwise indicated:

Running TTCom on a phone allows server account setup from a phone, which current TeamTalk phone clients do not support.

Quick Installation and Startup Instructions

  1. If running from source on Windows or if your OS does not include Python 3.7 or later already, install Python 3.7 or later. Users of the compiled ttcom.exe executable on Windows do not need to install Python. As of February, 2024, the TTCom author uses Python 3.10 or later for TTCom and compiles the Windows ttcom.exe executable with Python 3.12. Possible sources of Python include Some operating systems include a package distribution system that simplifies Python installation; e.g., apt, dnf, etc.
  2. If you are running TTCom via the Windows executable, download the Windows TTCom Zip file containing ttcom.exe and unzip it into a convenient folder.
  3. If you are running TTCom from source, download the TTCom source code Zip file and unzip it into a convenient folder. It is also possible to unzip both this and the Windows zip files into the same folder.
  4. In your chosen TTCom folder, copy ttcom.conf.sample to ttcom.conf and edit to taste. This is where servers and per-server behaviors are defined. The autoLogin parameter determines which servers connect automatically on TTCom startup.
  5. This author recommends setting some defaults for all servers at once by including something like this in ttcom.conf:
    [server defaults]
    nickname=Bill Nice
    gender=m
    statusmsg=This is here so I can see who's around to talk on any of my servers when I have time to hang out.
    If you don't include at least a nickname, you will be called "TTCom User" everywhere you go. Of course, change "Bill Nice" above to what you want as a nickname. Gender is optional and can be any of these: The statusmsg line is completely optional but provides a place to say something about yourself, why your TTCom is connected, where you can be found, etc.
  6. If you want events to print as they occur for only the currently selected server, instead of for all connected servers, include silent=1 in the above section. See ttcom.conf.sample for further ideas.
  7. For each server you want to use, add a section like this:
    [server blah]
    host=my.host.domain
    tcpport=10333
    username=blah
    password=blah
    In the above example, the first "blah" is the short name for this server. Each server must have a short name that is not shared by any other server in the configuration file. The short name must not contain spaces. The "host" and "tcpport" lines define the server's location and port (10333 is assumed if a "tcpport" line is not present). "username" and "password" are required if you are logging into an account but can be omitted for anonymous login.
  8. On Windows, run ttcom.exe. If running from source (on Windows or anywhere else), run TTCom by running ttcom.py through Python 3.7 or later:
    python3 ttcom.py
    Warning: Just typing "python ttcom.py" may try to run TTCom through Python 2, which will not work. If you get errors, make sure you are running Python 3.7 or later by typing python -V or python3 -V to check the version number.

The final step above will launch TTCom and connect to all servers with an autoLogin value above 0. As an alternative, you can specify a server or servers on the command line, by their shortnames from ttcom.conf, to connect to just those servers:

python3 ttcom.py simon
To start TTCom without connecting to anything, use -n in place of a server name.

When TTCom launches and finishes any initial connections and setup, it will print a prompt consisting of "TTCom," the name of what it considers the "current" server if there is one, the name of the current channel (not the full path) if TTCom is in one, and a greater-than sign (>). An example prompt:

TTCom Pub_US>
This prompt will be referred to as the TTCom command prompt.

Once TTCom is running and you see a command prompt:

Making TTCom Join a Channel On Login

If you want TTCom to join a specific channel on logging into a particular server, indicate the channel in the server's configuration file section. There are two supported syntaxes, shown here by example:

chanid=4
makes TTCom join the channel with chanid 4 on login. Use channel list to find channel ids. This method has the advantage of working even if a channel or one of its parent channels is renamed. Alternatively,
channel=/My Space/the Library/
joins the channel with the given exact path. Letter casing in a channel path must match exactly, and the path must both begin and end with a slash. These rules also apply to other TeamTalk clients. Note that the root channel always has the id 1 and the path of just one slash character. If the channel requires a password, include another configuration line to specify it:
chanpassword=blah!blah!

Handling BearWare Web Logins

Some of the public TeamTalk servers and other professional-grade servers allow or require a BearWare.dk web login account for authentication. If you are not attempting to set up TTCom for participation on a server via the web login authentication mechanism, you may safely ignore this section.

To configure TTCom for use with a BearWare.dk account:

  1. Type auth as a TTCom command. This command can be used to create, validate, and reset BearWare account information in TTCom.
  2. If you already set up an account, you will now be allowed to reset it. This is normally not necessary unless you need to switch to a different account. The rest of these instructions apply for both a reset and the creation of a new account.
  3. You will be asked if you have created a BearWare login account. If you have not, you will be given the URL to visit for account creation. Do this, then run the auth command again.
  4. You will now be asked to enter the BearWare login username and password. When you have entered these, TTCom will check with the BearWare website to validate these credentials and obtain the necessary information for logging into servers with this account.
  5. If you entered an invalid name or password, an error to this effect will appear. Otherwise, the account information associated with the account will print; and TTCom will remember how to use this account for logging into TeamTalk servers.
  6. For any server that should use the BearWare authentication system:
  7. Manually log into the server with the login command. If the login works, the normal messages for login will appear. If authentication fails, an error like the following is likely to print:
    HTTPError: HTTP Error 401: Authentication Failed
    This is not expected to happen often but would likely indicate an invalid, expired, or disabled BearWare account.
  8. If you do not see the above HTTP error but do see the normal "invalid user account" message from the TeamTalk server, make sure that all of the following are true:

In case of trouble not already addressed above, the result of the following command might be useful:

!app.curServer.bwxml
If the BearWare.dk site returned any information on the login attempt, this will show that information. On a successful login, a simple result looks like this:
<?xml version="1.0" encoding="utf-8"?>
<teamtalk><bearware><username>MyID@bearware.dk</username></bearware></teamtalk>
More information may appear depending on what the website supports going forward.

Summarizing Who Is Where On Servers

TTCom includes three commands for summarizing who is where on servers:

summary
Lists users on the current server organized by channel, starting (by default) with any users that are not in a channel. The semicolon (;) or colon (:) can be used as shortcuts for this command. To summarize who is on a non-current server, follow the command (or shortcut) with all or part of the server's shortname.
allSummary
Summarize who is where on all currently connected servers, again organized by channel. Again by default, all users are included. This command also includes a list of servers in each connection state other than logged-in, such as disconnected and connected but not logged in.
shortSummary
Summarize who is connected to all servers to which you are currently logged in, without separating them into channels. This is especially useful when you have numerous servers in your list, there are many users on one or more of your servers, or you just want to find people to talk to. By default, this command only includes users who are in channels and who are using voice-capable TeamTalk clients, as opposed to text-only clients such as TTCom. This command also lists non-logged-in servers whose connection states are different than expected, based on the autoLogin flag for each server. As a final summary, the command prints a list of how many servers are in each connection state.

All of the above commands accept one or more flags to alter which users are included in the output. To alter which users/clients are included, use a dash (-)followed, without spaces, by one or more of the following (typing help summary_flags in TTCom itself also prints the below information):

Special conveniences:

Examples beyond the listed conveniences:

File Transfer Management

TTCom includes a file command with subcommands for each of the following purposes:

file get
Download one or more files.
file send
Upload one or more files to a channel.
file delete
Delete one or more files.
file check
Check if one or more files are actually available for download.
Note that it is often necessary to join a channel with TTCom before performing one of these actions, just as it is for official TeamTalk clients. See the Special File Management Support For Server Administrators section for information on TTCom features aimed specifically at simplifying server-side file store management, including further file subcommands. See the File Transfer Security and Interface Considerations section for more technical information on this interface to the TeamTalk file transfer system.

Example file transfer command sequence:

join lounge
file get rules.docx ~/downloads
file get txt ~/downloads
file send ~/documents/rules1.docx
file delete rules1.docx
leave
The above sequence makes TTCom join a channel whose name contains "lounge," then gets rules.docx from the channel and puts in a local downloads folder. The next command adds to that downloads folder all files in the lounge channel whose names contain "txt". Finally, we upload and then delete rules1.docx from a local documents folder, and leave the channel.

Downloading Files

To download files, join a channel containing files, then type file get followed by

  1. A specification of which files to download. * matches all files, while anything else matches files whose names contain what is typed, ignoring case.
  2. The local path where files are to be stored. If this is a relative path, it starts at the folder from which TTCom read its configuration file. Wildcards are not supported here, but "~" or "$HOME" can be used for the current user's home directory.
A selector of matching files will appear allowing selection of specific files for download. Files should appear in order by upload date, oldest first. On completion of this selection, the downloads will begin to occur one at a time until all have been completed, at which time the TTCom prompt will again appear. During each download, the remote file name will be shown; and for sufficiently long downloads, a progress percentage will be shown and updated every five seconds.

As a file begins to download, if a file by the same name in the same folder already exists locally, the new download will be locally renamed. The first time this happens, an underscore (_) and the number 1 will be added to the file's basename (before the dot and extension if any). If that file also already exists, the number will become 2, and so on until an unused name is found. In this way, TTCom will complete all downloads while being sure not to replace any local file. A file rename of this sort will be indicated in TTCom by an output line indicating server-side and local names of the file just before the download begins.

A TeamTalk server may occasionally abort a file transfer with the following message before the transfer begins:

error number=3009 message="Server failed to create file"
The message appears to indicate a temporary server-side inability to start a file download, for reasons unknown. When this occurs, TTCom will print, "File get failed to start, retrying," and will then pause for one second and try the download again. If the download fails four times in a row with the same message, TTCom will stop trying and will print the server's error message in a "ValueError" line. The user must then resume the download by starting with the first unsent file.

This command accepts one or more -o options for specifying owners of the files to consider. See the Specifying File Owners section for details on how to select file owners.

Uploading Files

To upload one or more files, first join the channel to which you want to send. Then type file send followed by a specification of which files to upload.. A relative path or a file name or pattern without a path will start from the folder from which TTCom read its configuration file. The wildcards supported by the local operating system are allowed, as are "~" or "$HOME" for the current user's home directory. If the path is to a folder rather than to one or more files, all files in the folder are considered.

A selector of matching files will appear allowing selection of specific files for upload. Select one or more files as directed. On completion of this selection, a final confirmation will print that indicates the number of files to be sent and the total size of all of the files combined. When this has been confirmed, the uploads will begin to occur one at a time until all have been completed, at which time the TTCom prompt will again appear. During each upload, the remote file name will be shown; and for sufficiently long uploads, a progress percentage will be shown and updated every five seconds.

As a file begins to upload, if a file by the same name in the current channel already exists on the server, the uploaded file will be named with an underscore and a number appended to its basename (before the extension if any) so that the name does not already exist in that channel. TTCom will indicate such a renaming with a line just before the upload begins.

Deleting Files From the Server

To delete one or more files from a server, join a channel that contains files, then type file delete followed by a specification of which files to delete. * matches all files, while anything else matches files whose names contain what is typed, ignoring case. A selector of matching files will then appear allowing selection of specific files for deletion. Files should appear in order by upload date, oldest first. On completion of this selection, one final confirmation will appear, indicating the number of files about to be deleted. Answering y to this confirmation will cause all selected files to be deleted from the server.

Note that only files sent under your current TeamTalk server account will be listed by this command if you are not logged in as a server administrator. This is because TeamTalk servers will not allow a non-admin to delete a file uploaded under a different account.

Checking Availability of Files On the Server

From time to time, due to disk trouble, incomplete server backup restoration, etc., TeamTalk may end up listing files for download that no longer actually exist on the server. This results in user error messages when a download of a missing file is attempted.

TTCom supports scanning the server for files that are listed but not available. This operation is intended for server administrators but is not restricted to them. However, if you are not logged in as a server administrator, this command will only list files uploaded under your current account. This is because TeamTalk servers will not allow a non-admin to delete a file uploaded under a different account, and the purpose of checking files for availability is to delete file records that are no longer attached to files.

To check one or more files on a server, join a channel that contains files, then type file check followed by a specification of which files to check. * matches all files, while anything else matches files whose names contain what is typed, ignoring case. A selector of matching files will then appear allowing selection of specific files. Files should appear in order by upload date, oldest first. On completion of this selection, TTCom will check each file in turn for availability. A progress percentage may appear during this process indicating how fast the validation is proceeding.

When the validation of selected files is complete, TTCom will report the total file count and how many available and missing files were found. If any files were missing, a confirmation will appear asking permission to delete the records for the missing files. Answering y to this confirmation will cause all found records for missing files to be deleted from the server.

Special File Management Support For Server Administrators

There are two more file subcommands that are most useful to server administrators (for non-admins, they only apply to the current channel):

file counts
Prints a list of channels containing files, in order of increasing file count, each followed by the channel's total file count and then a list of users with per-user file counts, ordered by decreasing count per user. Note that the anonymous account, which has no name, will be represented here by a blank spot before a file count. The output concludes with a total count of files per user across all channels, and finally the number of files, uploaders, and channels containing files on the server.
file sizes
Prints a list of all files on the server, smallest first, each with file size, file name, uploader account name, and channel. Again, the anonymous account will be represented by a blank spot where an uploader name should be. Sizes are printed in appropriate units (bytes, kb, mb, gb, etc.) for easier reading. The output concludes with a total file count and total size.

The file send command allows an extra final channel specification for admins, allowing a file upload into a non-current channel. Example: file send c:/doug/blah.txt /Uploads will send to an Uploads channel a text file from the local c:/doug folder. A plain dot (.) may be given to indicate the current channel, though leaving out the option entirely has the same effect.

The file delete and file check commands accept one or more -o options for specifying owners of the files to consider. See the Specifying File Owners section for details on how to select file owners.

The file get, file delete, and file check commands offer an advanced feature that permits server administrators to list, download, delete, or check files from a non-current channel or from multiple channels at once. The intention of this feature is to make it significantly easier for TeamTalk server administrators to manage the files stored on the server for users to download.

In addition, if you are logged in as a server administrator, the file delete and file check commands will not restrict file lists to files uploaded under your current account. This often means that these commands will produce larger file lists under an administrator account than under a regular account.

If the file specification for a file get, file delete, or file check command contains a slash (/), everything before the last slash is a channel specification. * allows files to come from any channel, / uses the root channel, and anything else allows any channel whose name contains what is typed, ignoring case. As a special case, just prefixing the file specification with a slash will refer to the root channel (this is just a shortcut for "//").

Example advanced file specifications:

The last of the above specifications provides administrators with a way to list every file available on the server for download. With the file check command, this makes it possible to clean the server of all invalid file records in all channels at once.

If there is a channel specification and it matches more than one channel and is not *, a selector will appear allowing one or more channels to be selected from a list. If there is no channel specification, the current channel will be assumed.

When using this advanced format for a file specification, it is not necessary to be in a channel. Non admin users will not be able to use this syntax, however, because TeamTalk file servers do not notify non-admin clients of the existence of files, or of additions or deletions, except within the client's current channel.

Specifying File Owners

The file subcommands get, check, and delete have a -o or --owner option for limiting considered files to those owned by specific users. This option is valid for the file get command regardless of whether you are an admin, but you must be an admin to make use of this option for a file delete or file check command.

The -o or --owner option is followed by a file owner specification. This specification can be one of the following:

The -o or --owner option may be specified more than once, to include files from multiple specific owners. If any value matches more than one account or matches no accounts, a selection list will appear allowing you to select from all owners matched by all -o options given. This is to void accidents like matching "lee" and "wellfleet" with -o lee on a file delete command.

Note, especially for users of the * feature: The set of owners available to this option will be determined by collecting the usernames of the owners of all files selected by name and/or channel by the command. This means that a command like file get -o * * dl will only list owners of files in the current channel, not all accounts on the server. file get -o * */* dl will list all accounts that have uploaded files currently available anywhere on the server.

Also note that, if an owner selection list appears, the anonymous account will appear as a selection number with no name beside it. This will usually be the first entry in the list when it is present.

Example commands:

File Transfer Security and Interface Considerations

TTCom provides the following features in its file transfer support beyond those in the official TeamTalk clients:

Security points worthy of note:

Useful Tricks For File Management

The file get command doubles as a lister: Just use "." for the download folder but then don't download anything. This TTCom author recommends this approach rather than using file delete as a lister just because any accidental Enter won't cause as great an increase in user blood pressure.

A server administrator can use the following trick, under Linux or MacOS or Cygwin or anywhere else that Screen or tmux works, to weed out old files across all channels at once:

  1. Open a Screen or tmux session and start logging screen output from the window. In Screen, this is done with Ctrl+A and then :log and Enter
  2. Start a TTCom session with your server.
  3. Type this command to get a scrolling list of all files on your server across all channels:
    file delete */*
  4. Wait about 15 seconds for Screen or tmux to commit the bulk of output to the log file.
  5. Open another window in Screen or tmux, and open the log file in it using your editor of choice. If the selection prompt is not at the end of the file, open or refresh it again to get the rest of the output.
  6. Read through the files. For any you wish to delete, switch back to the TTCom window and type its number followed by a space. Alternatively, to avoid confusion caused by events in TTCom breaking up your selection input line, collect the numbers into another file, Notepad instance, etc.
  7. When done collecting numbers, put them all on the selection line if you collected them elsewhere, then press Enter and confirm the delete when asked to do so. All files you selected will be deleted at once.

Text Messaging In TTCom

Message Types

TeamTalk supports three types of messaging, with TTCom equivalents as shown, plus a notification type listed last:

User messages
The UMsg command sends a message to a specific user. When TTCom receives a user message, it prints the message in a format like this:
*"Doug Lee" (dlee)* Hi there!
Use of the asterisks comes from the way IRC displays private messages.
Channel messages
The CMsg command sends a message to a specific channel. When TTCom receives a channel message, it prints the message in a format like this:
<"Doug Lee" (dlee)> Hi all!
Use of the angle brackets comes from the way IRC displays channel messages.
Broadcast messages
The broadcast command sends a server broadcast. When TTCom receives a broadcast message, it prints the message in a format like this:
!"Doug Lee" (dlee)! Server going down for maintenance, should be back in five minutes.
Use of the exclamation marks comes from the way IRC displays messages from IRC operators.
Typing notifications
Some TeamTalk clients send notifications when the user is typing a message in a private chat window. There are two types of these notifications. Note: As of TTCom revision 1473, TTCom no longer prints the below notifications, because of how much noise this caused during a typical private message conversation. The timing of these notifications is determined by the client sending them.

TTCom also supports a more private message type, but only between TTCom instances; see the next section.

If TTCom is intercepting messages and receives one, the normal output for the message type will be preceded on the same line with the word "Intercepted," and the sender will include "to" and the target being sent to (user or channel name). Example for a user message:

Intercepted *"Doug Lee" (dlee) to "Bob Lee" (bobl)* Psst.
The rules that apply to TTCom intercepting messages are the same as for all TeamTalk clients.

When using TTCom to send messages, do not place quotes around the message text (unless, of course, you want to send quote marks as part of the message itself).

TTCom-Specific Private Text Messaging

There is a pmsg command, similar to the umsg command, for sending a more private user message to another compatible text client. These messages have the following properties as compared to normal TeamTalk user messages:

See the help text for the pmsg command for more information.

When TTCom receives a private message of this type, it prints the message in a format like this:

="Doug Lee" (dlee)= Psst.
Use of the equal signs comes from the way IRC displays direct client-to-client (DCC) messages.

Note that although these messages are more private in nature than normal TeamTalk messages, this TTCom author is not able to guarantee the privacy of any TeamTalk communication:

The Prefix Command

The prefix command provides a way to send a series of commands that all begin with the same material. The prefix can simply be a command or a command and one or more of its arguments. The intended typical use of this command is to simplify sending chat messages to one user, though it may also find other uses.

An example: To send messages to user Bob, one would normally type "UMsg bob" followed by the message text. This might become tedious in a lively conversation. Typing "prefix UMsg bob" will set up TTCom to assume the prefix "UMsg bob" on all following lines entered. (Blank lines are ignored by this system though, so that pressing Enter at a prompt does not cause error messages.) While a prefix is in effect, the TTCom command prompt will include it, as a reminder of the context for the next command typed.

If you need to send a TTCom command without the prefix while a prefix is in effect, start the line with a slash (/). For example, typing "WhoIs bob" while the above prefix is in effect would send the chat message "WhoIs bob" to Bob. Typing "/WhoIs bob" would actually perform the wanted WhoIs command. (A leading slash is ignored if there is no prefix, so this command syntax is always valid.)

The above trick can also be used to change the prefix: "/prefix UMsg jane" would effectively change where subsequent text would be sent. To clear the prefix completely, type /prefix with nothing after it.

Warning: If you use a name, like Bob in the above example, the meaning of the name may change if, for example, Bob changes his nickname or another Bob logs in. A much safer way to make a prefix for a private chat is to use the userid:

  1. For the above example, type whoIs bob and notice the userid number. For this example, say it is 251.
  2. Instead of typing prefix bob, type prefix #251 (notice the number sign). This will make your prefix send messages specifically to Bob's current TeamTalk session.

Getting Geolocation Information For a User, Server, or IP Address

Note: The feature discussed in this section was introduced into TTCom by a code contribution from Ivan Soto in September, 2023. The data obtained by this command comes from ip-api.com, which is one of a fairly large number of websites that publish this type of information, sometimes for free and sometimes at a cost. The TTCom author had already for years manually used a similar service, ip2location.com, to obtain such information when it could help identify the source of a suspicious login or other cause for server owner concerns.

TTCom supports a geolocate command, often abbreviated to just geo, for retrieving and printing basic information about an IP address. There are three ways to use this command:

At this writing (September, 2023), the returned information includes

Adding -v immediately after the command will cause TTCom to print all information returned from the web query without attempting to reformat it. This may allow support of enhancements to the web query service in the future. An example command: geo -v bob. At this writing, this produces the following fields in addition to those already mentioned:

Note that the location information provided by this and other geolocation services is usually close but not precise and may in some cases be significantly inaccurate depending on the data available for the IP address. Different services may also provide differing values for the same field from time to time; e.g., city may not agree between services for the same IP address. For the service TTCom currently uses in particular:

The Alias Command For Making Custom Commands

The alias command provides a system for creating and managing custom command shortcuts. It supports the following syntaxes:

alias (by itself)
Prints a list of defined aliases.
alias blah
Prints the expansion of the alias blah. This will be what TTCom actually runs when blah is typed as a command.
alias cl clear
Defines alias cl to mean clear. From now on, typing cl will clear the screen.
alias mv move
Makes mv act like move. mv doug / would now be equivalent to move doug /.
alias -cl mv
Deletes the cl and mv aliases.
alias mbob umsg #498
Makes mbob a fast way to send user messages to userid 498. Temporary aliases like this are useful during extended conversations. Now, mbob Hello there! will send "Hello there!" to that user.

Syntax notes:

The Box Command For Simplifying Server Address Management

Similar to the alias command is the box command. Whereas an alias command creates a new command though, a box command creates a name for a host address for one or more TeamTalk servers. This may be useful for those who have in their TTCom server set several servers that share one host address. When the owner of such a set of TeamTalk servers decides to migrate all services to a new Internet Service Provider, all related host addresses in the TTCom server list must change accordingly. The box command can simplify this by allowing each TeamTalk server entry in the TTCom server list to refer to the box name rather than listing the address itself.

The syntax of the box command is very similar to that of the alias command:

box (by itself)
Prints a list of named boxes.
box blah
Prints the address for box blah. This will be what TTCom actually connects to for any server that uses blah as a host address.
box bob myhost.mydomain.name
Names the given address bob for use in server definition host lines. If the box already had an address, it is updated to what is given.
box -bob
Deletes the bob box definition.

Example usage: The command

box bob bobsbox.linode.com
would allow the host line in the configurations for all TeamTalk servers on that "box" to read
host=bob
instead of
host=bobsbox.linode.com
When Bob then moves his TeamTalk servers to newplace.blah.net, the following two commands would effect a move of all connections to the new location:
box bob newplace.blah.net
refresh

Note that box definitions are stored in ttcom.ini, not ttcom.conf. This has at least two noteworthy consequences:

  1. Migrating a ttcom.conf file from one machine to another will not be sufficient if boxes are defined; you will also need to copy the box eefinitions in ttcom.ini to the new machine.
  2. It is perfectly acceptable to have a box name defined differently on different machines, which can allow for things like local or internal IP address usage on machines that have such access. Examples of such a scenario include

If the address on a server's host line does not match a box name, the address is tried verbatim, even if the address contains no dot. Beware of this when deleting box definitions; make sure to clean up any references to a box name before removing its address! Dotless addresses are indeed valid in some situations, depending on local network configuration.

Technical Information For TTCom Users

This section and its subsections are a reference for TTCom users on parts of the TeamTalk TCP protocol that are exposed directly through TTCom.

A Note On Value Tables In This Section

This section contains tables of bit flag values used in the raw TeamTalk protocol. In these, the Hex column is the hexadecimal value of the flag. Multiple flags can be expressed in one value by adding these values together, for fields that support multiple flags at once. The Letter column serves to provide a single unique letter for each flag where possible (case matters for these!). The Short Name column provides a one-word name for each flag, and the Description column describes the flag in more detail. The Hex column represents a TeamTalk protocol element and is thus set by TeamTalk itself. The other three columns represent choices made by this TTCom author and are not themselves part of the TeamTalk protocol.

Channel Type Flags

The following table lists the bit flags that identify the type of a channel. Values of the type field in channel commands are composed of combinations of these values.

Channel type flags
HexLetterShort NameDescription
0x01PpermanentPermanent channel (as opposed to temporary)
0x02xexclusiveExclusive (one transmitter at a time)
0x04cclassroomClassroom channel
0x08oopOnlyOnly ops see and hear
0x10ppushToTalkPush to talk only
0x20nnoRecordNo recording allowed
0x40hhiddenHidden channel

User Rights Values

The following table lists the bit flags comprising the set of supported user rights in TeamTalk. Values of the userrights fields in account and whoIs commands are composed of combinations of these values.

User rights values
HexLetterShort NameDescription
0x00000001lloginMultipleCan log in multiple times
0x00000002ffindUsersCan see users in all channels
0x00000004ttempChannelsCan create temporary channels
0x00000008ppermChannelsCan create/modify all channels
0x00000010BBroadcastCan broadcast text messages
0x00000020kkickCan kick users off the server
0x00000040bbanCan ban users from the server
0x00000080mmoveCan move users between channels
0x00000100oopCan make other users channel operators
0x00000200uuploadCan upload files
0x00000400ddownloadCan download files
0x00000800UUpdatePropsCan update server properties
0x00001000vvoiceCan transmit voice data
0x00002000VVideoCan transmit video data (webcam)
0x00004000DDesktopCan share out the desktop
0x00008000IInputCan send input to another user's desktop
0x00010000sstreamAudioCan stream audio files
0x00020000SStreamVideoCan stream video files
0x00040000NnickLockedNickname is locked against user changes
0x00080000TstatusLockedStatus is locked against user changes
0x00100000rrecordCan record audio in all channels
0x00200000hseeHiddenCan see hidden channels
0x00400000PPMCan send private messages*
0x00800000CCMCan send channel messages*

* Added in TeamTalk server version 5.15, and shown by TTCom as enabled for older server versions where it may not be turned off.

Subscription and Intercept Values

The following table lists the bit flags comprising the set of supported subscriptions and intercepts in TeamTalk. Values of the sublocal and subpeer fields in the whoIs command are composed of combinations of these values:

Notes on the below table:

Subscription and intercept values
HexLetterShort NameDescription
0x00000001uuserMsguser message subscription
0x00000002cchannelMsgchannel message subscription
0x00000004bbroadcastbroadcast message subscription
0x00000008ttypingtyping notification and custom message subscription
0x00000010aaudioaudio subscription
0x00000020vvideovideo subscription
0x00000040ddesktopdesktop subscription
0x00000080iinputdesktop input subscription
0x00000100smediaStreammedia stream subscription
0x00000200kbitKbit k subscription
0x00000400lbitLbit l subscription
0x00000800mbitMbit m subscription
0x00001000nbitNbit n subscription
0x00002000obitObit o subscription
0x00004000pbitPbit p subscription
0x00008000qbitQbit q subscription
0x00010000UiUserMsguser message intercept
0x00020000CiChanMsgchannel message intercept
0x00040000BiBroadcastbroadcast message intercept (not used)
0x00080000TiTypingtyping notification and custom message intercept
0x00100000AiAudioaudio intercept
0x00200000ViVideovideo intercept
0x00400000DiDesktopdesktop intercept
0x00800000IiInputdesktop input intercept (not used)
0x01000000SiMediaStreammedia stream intercept
0x02000000KiBitKbit k intercept
0x04000000LiBitLbit l intercept
0x08000000MiBitMbit m intercept
0x10000000NiBitNbit n intercept
0x20000000OiBitObit o intercept
0x40000000PiBitPbit p intercept
0x80000000QiBitQbit q intercept

Technical Details On TTCom Private Messaging

Starting in November, 2018, TTCom has supported exchange of private messages between TTCom instances using a protocol that is ignored by all other known TeamTalk clients. The system used is actually the one used by official TeamTalk clients for typing notifications, but with different content than typing notifications use.

Until November 16, 2022, it was believed that these messages could neither be intercepted nor logged by any client or server. On November 16, however, this TTCom author discovered that TeamTalk servers do allow these messages to be intercepted, though no clients other than TTCom appear to be capable of using this ability. Per usual, only administrator users can intercept anything; TeamTalk servers enforce this.

To this author's knowledge, TeamTalk servers are still not able to log these messages. This of course may change in a future TeamTalk server update. In particular, the "User sent custom text message" item in the tree of logged events would appear to be what would enable this; and it is checked by default, but with no apparent effect in current server versions.

In detail then, this is the status of TTCom-specific private messaging as of November, 2022:

Technical Information On What TTCom Does and Does Not Support

Over its long lifespan since 2011, there has occasionally been confusion and misinformation as to what TTCom does and does not support. This section aims to explain this in some detail. This will be a fairly technical discussion.

For this discussion, "server" means a TeamTalk server to which people connect to talk and text; and "client" means any program that connects to a TeamTalk server. Users run clients and connect to a server. All communication between users travels between their clients through the server. Examples of clients include TTCom itself, standard TeamTalk Qt, Classic, phone, and other clients; and the open-source TeamTalk 5 PHP Admin script offered by the TeamTalk author for administration of TeamTalk servers.

TeamTalk Internet Traffic Types and Usage

TeamTalk communication is composed of two distinct types of Internet traffic:

Transport Control Protocol (TCP) traffic
A text-based communication mechanism that TeamTalk uses for login, logout, events, client commands, etc. This traffic lends itself easily to interpretation and experimentation, such as via Telnet. Additionally, the TeamTalk 5 PHP Admin script offered by the TeamTalk author demonstrates how to use much of this protocol.
User Datagram Protocol (UDP) traffic
A binary (non-text) protocol that TeamTalk uses for all exchange of audio, video, desktop sharing, and desktop input/control information. This traffic is not so easy to interpret and generally requires a paid copy of the TeamTalk SDK to use.

TeamTalk uses TCP traffic for the following purposes:

TTCom aims to support all TeamTalk services that are implemented wholely through this type of traffic.

TeamTalk uses UDP traffic for the following purposes:

TTCom has no support for UDP traffic, and there are no plans to change this. This is a non-text protocol without documentation that would take considerable effort to interpret and utilize without the TeamTalk SDK sold by the TeamTalk author.

More specifically, adding TTCom support for elements of this protocol would require the following efforts:

Alternatively, and likely preferred by the TeamTalk author, TTCom could incorporate the TeamTalk SDK; but this would require

Packet Protocol Types and Type Codes

When a client connects to and logs into a server, it must make a separate connection via UDP in order to send or receive UDP traffic. TeamTalk servers keep track of what clients support by whether this separate connection has been made. A client that connects via both TCP and UDP is said to support packet protocol 1, while a client like TTCom that only connects via TCP is said to support packet protocol 0. The TTCom WhoIs command will show the packet protocol supported by any client.

This author refers to any client that does not support UDP traffic, or in other words any client using packet protocol 0, as a "text client." TeamTalk servers do not transmit UDP data to any client that does not support packet protocol 1. This means that text clients do not receive audio, video, or desktop data from any TeamTalk server.

Note that, due to the significantly larger amount of UDP data as compared to TCP data, it is possible to verify the presence or absence of UDP data transmission from server to client via a local Internet traffic monitor. Some Internet routers/modems offer this type of information. The Windows Task Manager also offers network throughput statistics, as does the netstat command on MacOS, Linux, and similar platforms.

An Example

Suppose a client logs into a server and joins the root channel, which contains an active voice conversation and two people sending video. The following will occur:

  1. The client will connect to the server via TCP.
  2. The server will send a welcome message to the client via TCP.
  3. If the client plans to support UDP data (packet protocol 1), it will send a UDP initialization packet to the server; and the server will send a UDP packet back in response, establishing this separate connection.
  4. The client will send a TCP login command to the server and receive text (TCP) responses indicating a successful login.
  5. The server will send notification loggedin events via TCP to all other logged-in clients, so they will know that this client is now logged in. If this client made the UDP exchange, that event notification will include packetprotocol=1; otherwise, it will include packetprotocol=0.
  6. The client will send a join command via TCP to join the channel.
  7. The server will respond with confirmation of the join, again in TCP.
  8. The server will send TCP adduser events to all other clients to notify them that this client has joined the channel.
  9. If this client made the UDP exchange, the server will begin sending UDP data for all voice and video traffic in the channel to the client; otherwise, it will not.
  10. If this client supports UDP data (packet protocol 1), it will begin translating the server UDP data into sound, video, etc.

Known Issues

The following issues are known and may be fixed in a future version of TTCom:

General Issues

Events that print in the TTCom window can break up a command while it is being typed and can also break up the display of file transfer progress. The solution to this problem would require a full-screen interface, which though possible can complicate portability across operating systems and platforms.

Running a time-consuming command on a non-current server, using the switch command or its > equivalent, will temporarily make the target server "current." If either the previously current server or the target have silent=1 in effect, this may affect which events are seen in the TTCom window while the command is executing. This is especially worthy of note for long file transfers started with commands like one of these:

server paul file get war_and_peace.mp3 ~/books
>jolene file send please.mp3

A refresh after changes to some server parameters causes a logout and login even though this is not strictly necessary. Examples of such parameters include nickname, statusMsg, and channel. While it is technically possible to fix this, it is not likely to happen for several reasons:

The geolocate command only prints the first half of Canadian zip codes, stopping at the space. This is a shortcoming in the data provided by the service TTCom is using for this feature. As a result, the issue will only be fixed if either the service begins providing the full zipcode or TTCom starts using a different service.

Time Zone and Time Display Issues

TTCom's idea of the times on certain events, such as server bans shown in a ban list, may differ from those shown by other TeamTalk clients. At this writing, a perfect method of getting this right is not known, for several reasons:

Revision History

This is the revision history of TTCom, most recent revision first:

Revision 1511, February 10, 2024

Note: This is a significant update because it

There are several things to keep in mind during this update:
  1. The encoding for ttcom.conf is now officially UTF-8. A byte order mark (BOM) is not required (or recommended) but will be allowed (and ignored) if found.
  2. The new code for handling servers in ttcom.conf is much more careful to detect problems in server definitions. As a consequence, some issues like duplicate servers will generate errors instead of being ignored.
  3. Due to the better error checking at load time, the lint command is now obsolete and is removed from TTCom, along with its section in this document.
  4. The only two section types allowed now in ttcom.conf are server and include. All other sections are moved to ttcom.ini.
  5. There is a new ttcom_defaults.ini file. This file is currently empty but may one day have content. Do not edit or remove this file; it will be refreshed on TTCom update.

Other changes in this update:

Revision 1473, January 18, 2024

Revision 1454, November 16, 2023

Changes to commands and their responses:

Other changes and fixes:

Revision 1437, September 26, 2023

29 older revisions back through September 7, 2014

Revision 1406, June 29, 2023

Revision 1393, March 15, 2023

Revision 1372, November 24, 2022

Significant changes in event and trigger handling:

Other significantly visible and/or impactful changes:

Other changes and fixes:

Revision 1330, August 2, 2022

Major updates:

Minor updates and bug fixes:

Revision 1305, January 2, 2022

Revision 1288, November 23, 2021

Revision 1277, October 23, 2021

Revision 1262, September 15, 2021

Revision 1234, July 31, 2021

This update's release notes are divided into sections because of the number of changes.

Changes to the file management commands:

Other command changes and additions:

Documentation and miscellaneous updates:

Revision 1192, March 25, 2021

Note: This release was initially missing two files required for running TTCom from source. This was corrected on April 9, 2021, without a revision or code change.

Revision 1172, March 17, 2021

Revision 1146, March 10, 2021

Updates for improved functionality with TeamTalk 5.7:

Other enhancements:

Bug fixes and documentation improvements:

Revision 1119, October 26, 2020

Revision 1108, September 07, 2020 (version 3.1.0)

Revision 1021, August 24, 2019 (version 3.0.3)

Revision 1010, August 12, 2019 (version 3.0.2)

Revision 1005, August 8, 2019 (version 3.0.1)

Revision 1000, August 5, 2019 (version 3.0.0)

This is the first public TTCom release targeted at, and requiring, Python 3.7 rather than Python 2.7. The Windows stand-alone .exe will work as before, but running TTCom from source, on any operating system, will now require a Python 3.7 installation that launches with the "python3" (not just "python") command. This approach avoids problems on systems (such as MacOS) where the "python" command must for now continue to launch Python 2.x in order to avoid many other problems.

This release is also the first to support professional encrypted (SSL) TeamTalk servers. For these, add the line encrypted=true to the server's configuration section in ttcom.conf. Note that encryption, or SSL support, is not related to the new TeamTalk 5.4 web login system used by the public TeamTalk servers. The web login system is not at this time supported by TTCom.

Important: Install this TTCom into a fresh folder, not over the top of TTCom 2.x, to avoid stray and possibly problematic residual files from the older version. In particular, .pyc files produced by an older TTCom could confuse the new version, as Python 3 handles .pyc files differently.

Other enhancements in this release:

Revision 969, May 28, 2019 (version 2.1.0)

Revision 930, November 23, 2018 (version 2.0.5)

Revision 915, October 3, 2018 (version 2.0.4)

Revision 873, June 12, 2018 (version 2.0.3)

Note: The syntax of the cmsg command is changed in this update.

Revision 858, May 27, 2018 (version 2.0.2)

Revision 852, February 11, 2018 (version 2.0.1)

Revision 819, August 8, 2017 (version 2.0)

Please read this entire section of release notes before upgrading.

This revision includes many fixes, a few new commands and features, and some changes in syntax for existing commands.

This revision also marks the official end of TeamTalk 4 support. This does not mean that TTCom will instantly stop working with TeamTalk 4 servers; it simply means that support for those servers will begin to fail as reasons arise to remove or modify the code that supports them.

New and changed commands and features:

Fixes:

Revision 692, August 13, 2016 (version 1.4)

Revision 652, November 21, 2015 (version 1.2)

This revision fixes more issues with TeamTalk 5 servers and adds a few enhancements:

Revision 607, December 20, 2014 (version 1.1)

This release primarily fixes a number of issues TTCom initially had with TeamTalk 5 servers, caused by changes in the text TeamTalk client/server protocol:

The following commands still do not work completely on TeamTalk 5 servers:

Account
List may omit fields, and add/modify will not work.
Intercept and Subscribe
Bits are wrong.
Op
Not tested but not updated command formats.
TT
Not able to write updated file format.

Other changes in this release:

Revision 580, September 7, 2014 (version 1.0)

This is the initial public release of TTCom and the start of its falling under the GNU Public License (GPL). To learn of TTCom's use through the date of publication, see "All About the TeamTalk Commander." To learn its history prior to publication in more detail, read "TeamTalk Commander (TTCom) Pre-Publication History."

I am publishing TTCom for the following reasons, approximately in this order: