TeamTalk Commander (TTCom) Users Guide
Doug Lee
Last Revised March, 2021

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-2021 by Doug Lee and falls under the GNU General Public License as found in LICENSE.txt. iniparse, included in its entirety, comes with its own license (also included).

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 stand-alone 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:

Quick Installation and Startup Instructions

  1. If running from source on Windows or if your OS does not include Python 3.7 already, install Python 3.7. Possible sources of Python 3.7 include Some operating systems include a package distribution system that simplifies Python installation. If you are using the Windows stand-alone executable ttcom.exe or your system already includes an appropriate Python version, this step is not necessary.
  2. Download the TTCom Zip file and unzip it into a convenient folder.
  3. Copy ttcom_default.conf 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.
  4. This author recommends setting a nickname for all servers at once by including something like this in ttcom.conf:
    [server defaults]
    nickname=My Name
    If you don't do this, you will be called "TTCom User" everywhere you go. Of course, change "My Name" above to what you want as a nickname.
  5. 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_default.conf for further ideas.
  6. On Windows, run ttcom.exe. If running from source (on Windows or anywhere else), run TTCom by running ttcom.py through Python 3.7:
    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 by typing python -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.

Once TTCom is running and you see a "TTCom>" prompt, type "?" or "help" at the TTCom command prompt to learn what is possible. You can add a command name for help on that command; e.g., "?whoIs." Case is not important in command names.

The Lint Command For Diagnosing Configuration File Problems

If you experience unexpected problems with your TTCom configuration, such as strange errors or updates that seem not to take effect, try typing "lint" as a command in TTCom. This will scan your configuration file and report anything that looks odd to TTCom. Each issue found will consist of the ttcom.conf line number followed by a description of the anomaly. The number of lines in the file will also be reported; this is primarily aimed at helping detect line ending problems caused by porting configuration files between operating systems.

The lint command is not guaranteed to catch all possible problems but will catch the following:

For the curious, the name "lint" is chosen because Lint was a C program checker that reported errors and warnings about C program syntax many years ago, and the term is still in common use in programming circles for anything that helps verify the correctness of code or file syntax.

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.
Note that it is generally necessary to join a channel with TTCom before performing one of these actions, just as it is for regular 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. 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. 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.

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. 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.

Special File Management Support For Server Administrators

The file get and file delete commands offer an advanced feature that permits server administrators to list, download, and delete 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.

If the file specification for a file get or file delete 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 for download or delete:

The last of the above specifications provides administrators with a way to list every file available on the server for download.

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.

File Transfer Security and Interface Considerations

TTCom provides the following features in its file transfer support beyond those in the regular 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.

TTCom-Specific Private Text Messaging

The UMsg command for sending user messages has a -i option 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 UMsg command for more information on this option.

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:

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.

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
0x00008000CControlDesktopCan control another user's shared desktop
0x00010000sstreamAudioCan stream audio files
0x00020000SStreamVideoCan stream video files
0x00040000nnickLockedNickname is locked against user changes
0x00100000rrecordCan record audio in all channels
0x00200000hseeHiddenCan see hidden channels

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. sublocal represents local subscriptions, specifying which information is wanted by this TTCom instance from the client being queried. subpeer represents which information is wanted by the queried client from this TTCom instance. The TTCom subscribe and intercept commands modify sublocal, whereas the queried client's options for subscribing and intercepting will modify subpeer.

Notes on the below table:

Subscription and intercept values
HexLetterShort NameDescription
0x00000001uuserMsguser message subscription
0x00000002cchannelMsgchannel message subscription
0x00000004bbroadcastbroadcast message subscription
0x00000008jbitJbit j subscription
0x00000010aaudioaudio subscription
0x00000020vvideovideo subscription
0x00000040ddesktopdesktop subscription
0x00000080xcontroldesktop control
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
0x00080000JiBitJbit j intercept
0x00100000AiAudioaudio intercept
0x00200000ViVideovideo intercept
0x00400000DiDesktopdesktop intercept
0x00800000XiControldesktop control
0x01000000SiMediaStreammedia stream intercept
0x02000000KiBitKbit k intercept
0x04000000LiBitLbit l intercept
0x08000000MiBitMbit m intercept
0x10000000NiBitNbit n intercept
0x20000000OiBitObit o intercept
0x40000000PiBitPbit p intercept
0x80000000QiBitQbit q intercept

Known Issues

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

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 server 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

Revision History

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

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: