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/.
TTCom provides fast ways to accomplish the following tasks for those who are ok with typing (or dictating) commands:
allSum and shortSum commands.
admins command.
move command.
account command and its subcommands.
channel command and its subcommands.
kick, cKick, ban, and kb,
and also the
Server and Channel Ban Management section and its subsections.
file command and its subcommands, and the
File Transfer Management section and its subsections.
cmsg, umsg, and broadcast, and the
Text Messaging In TTCom section and its subsections.
TTCom also offers the following features over other TeamTalk clients:
pmsg.
Of course, TTCom also has some disadvantages as compared to other clients:
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:
ttcom.exe application.
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
python into the Windows
Run box, which will make Windows offer to install it.
apt, dnf, etc.
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.
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.
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.
silent=1 in
the above section. See ttcom.conf.sample for further ideas.
[server blah]
host=my.host.domain
tcpport=10333
username=blah
password=blah
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
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
-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>
Once TTCom is running and you see a command prompt:
?" or "help" at the TTCom command prompt to learn what is possible.
This will list all available commands and any other help topics that are available.
?whoIs". Case is not important in command names.
man, or equivalently www man, will launch the current online
version
of the TTCom manual (user guide) in the default browser.
www tt will launch the TeamTalk home page in the default browser.
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
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/
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!
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:
auth as a TTCom command.
This command can be used to create, validate, and reset BearWare account information in TTCom.
Important notes on BearWare logins:
ttcom.ini, not ttcom.conf.
If you intend to use TTCom on multiple machines and share BearWare logins among them, be sure to migrate all
or the appropriate part of ttcom.ini among machines as necessary.
Once TTCom is configured with an account to use for BearWare logins, the following setup will work for any server that should use the BearWare authentication system:
autoLogin option to anything but 0 until you are certain that
the login sequence works as expected. Failing to follow this suggestion is harmless but may result in useful
error messages being buried in other output at TTCom startup time.
username to exactly the id "bearware", without the quotes and in lower case.
refresh command to reload TTCom configuration information if necessary
after making the above changes.
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
username for the server is "bearware" and there is no password.
If either of these is not true, TTCom will attempt to log in with the credentials supplied and will not
contact the BearWare website for authentication.
In case of trouble not already addressed above, the result of the following command might be useful:
!app.curServer.bwxml
More information may appear depending on what the website supports going forward.<?xml version="1.0" encoding="utf-8"?> <teamtalk><bearware><username>MyID@bearware.dk</username></bearware></teamtalk>
TTCom includes three commands for summarizing who is where on servers:
summary
allSummary
shortSummary
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):
a: Include all clients (equivalent to -cntv).
c: Include clients that are in a channel.
n: Include clients that are not in a channel.
t: Include text clients such as TTCom.
v: Include voice-capable clients.
Special conveniences:
-c by itself is equivalent to -ctv (all clients in a channel).
-n is similarly equivalent to -ntv.
-t is equivalent to -tcn (all text clients whether in a channel or not).
-v is similarly equivalent to -vcn.
Examples beyond the listed conveniences:
-vn.
-ct.
TTCom includes some support for creating, deleting, and listing bans. TeamTalk supports two levels of bans: server bans and channel bans. TeamTalk also supports banning by username or by address. TeamTalk versions 5.13 and later also begin to support banning subnets and address patterns.
TTCom has long supported the handling of server bans but is beginning to support channel bans as well. TTCom is also beginning to support more types of bans as of April, 2024.
TeamTalk supports both server-level and channel-level bans. TTCom can show either or both and can show lists or just ban counts. The following basic ban commands are supported:
ban list with no further arguments.
ban list -C.
(This is a capital C.)
This will list all channel bans across all channels at once, a feature not currently supported by regular
TeamTalk clients.
ban list -a.
-c to any of the above
commands.
(This is a lower-case c.)
Warning: Depending on the number of channels on the server and other server configuration settings, listing channel bans may take some time and may fail with flood protection errors. In March, 2024, This TTCom author submitted a TeamTalk enhancement request to permit a much more efficient means of retrieving all channel bans at once. If this feature is implemented in TeamTalk servers, these commands will likely become much faster.
When any ban list is requested, the count of bans will appear, followed by information about each ban, oldest first by ban creation time.
The first line of the output for each ban will consist of a number, starting at 1 and
increasing for each entry, followed by the date and time when the ban was created.
The remainder of the information for the ban then appears, indented, on subsequent lines.
The first indented line for a ban shows the following, in order:
Any further indented lines show other information that the server provides for the ban. Possibilities include
Any ban list or count request may be filtered so that it only includes bans matching given criteria. Any
non-option arguments after ban list can be of any of three types:
ban list bob will match a ban whose nickname field was "Bob Logan" and also a ban
where the username was "Bob" or "Thingamabob."
nickname=bob will match only if the named field's value exactly matches the given
value, including letter casing.
ban list nickname=bob will match a ban where the nickname was "bob" but not one where it was
"Bob" with an upper-case first letter.
!nickname=bob will match if the named field's value does not match the given value.
ban list !username=Bob will match all bans that do not bear the username "Bob" (with an
upper-case first letter).
When a value against which you want to filter includes a space, place the corresponding command argument in quotes. Examples:
ban list "bob logan"
ban list "!username=Joe Blow"
ban list !username="Joe Blow"
Bans are removed with ban delete or just ban del.
By default, all available bans are shown and the user may select one or more to delete from that list.
The same filtering available for ban list may be used here
to limit the available deletion candidates.
No bans are removed without confirmation.
There are two ways to add a new ban: By selecting from currently connected users, or by adding a ban for a username, address, subnet, or address pattern regardless of whether any matching user is currently connected. TTCom adds another hybrid method, which is to ban a subnet or address pattern based on a currently connected user's address. In some cases, TTCom also generalizes new bans so that they work as expected across both IPv4 and IPv6 environments.
Warning: The syntaxes for adding bans in TTCom are undergoing revision at this writing and may change significantly. This is also true of the special behaviors for generalizing bans across network types.
To ban a currently connected user, type ban add followed by something that will match that
user. This is most often a name or partial name, or an IP address or partial address; but it could be part
of the value of any field for that user.
If more than one connection matches, they will all be presented for selection.
As is true in regular TeamTalk clients, banning a user does not also automatically kick that user from channel
or server. To do that, either add a -k option to the ban add command, or use the
kb command instead of ban add.
The following two commands are equivalent:
ban add -k dlee
kb dlee
Note: The syntax of this feature may change. To ban a user's subnet, specify as a single argument something that matches the user, then a slash (/), then the size of the subnet to ban. Currently, sizes of 16 and 24 are the only sizes supported. (a "/24 subnet" contains up to 256 addresses, and a "/16 subnet" contains up to 65,536 addresses. These names are based on the number of address bits that are shared by all addresses in the subnet.)
For example, imagine that a user matching "dolly" shows up from address 192.168.25.67. Typing
Why only two subnet sizes?
Do IPv6 subnet bans work? TTCom will quietly pass them to servers, but what happens from there is up to the
server. TeamTalk 5.15 and later server versions should support IPv6 subnet bans.
Server versions back through 5.13 may also, and the first mention of subnet ban support appeared in the
TeamTalk Qt client release notes for client version 5.3 (2018).
ban add -a dolly/24 will ban anyone from addresses starting with 192.168.25, and typing
ban add -a dolly/16 will ban anyone from any address starting with 192.168.
Of course, the danger of banning so many addresses at once is that the ban will catch innocent users that
use the same Internet Service Provider (ISP) or live in the same geographic area.
Why only two subnet sizes, and other likely questions
Warning: The syntaxes discussed in this section should not be used against TeamTalk servers older than 5.13, and doing so has not been tested.
The ban add command has a -a option for adding a ban based on an address, address
pattern, or subnet without reference to who is currently on server.
The following patterns are supported as indicated:
bann add -a 192.168.25.57
ban add -a 192.168.25.0/24 or ban add -a 192.168.25:
These are two equivalent ways to ban an arbitrary /24 subnet (255 addresses at once).
To dodge apparent differences in TeamTalk servers' handling of subnets, TTCom translates this into an
address pattern that matches this subnet whether a user connects from it on an IPv4 socket or an IPv6 socket.
ban add -a 192.168.0.0/16 or ban add -a 192.168:
Similar syntaxes for banning an arbitrary /16 network, which TTCom generalizes in the same manner.
ban add -a followed by any single argument that does not match any of
the above patterns will make TTCom send that argument as a ban to the server.
What the server does with this will depend on the TeamTalk server version.
This is how TTCom allows IPv6 addresses and subnets to be banned directly.
Beware, though, that server versions 5.13 through at least 5.16 have been seen to accept just about any
string as an address ban but without actually doing anything with it if it doesn't match specific syntax
rules depending on server version.
At this writing, TTCom does not support, or does not adequately support, the following ban features that are supported by TeamTalk servers:
TTCom includes a file command with subcommands for each of the following purposes:
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
To download files, join a channel containing files, then type file get followed by
* matches all files, while anything else matches
files whose names contain what is typed, ignoring case.
~" or "$HOME" can be used for the current user's
home directory.
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"
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.
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.
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.
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.
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
file sizes
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:
/rules.txt (or //rules.txt) means rules.txt in the root channel of
the server.
lounge/rules.txt means rules.txt files in all channels whose names contain the word
"lounge."
(A selector will appear to allow selection of specific "lounge" channels if more than one is available.)
*/rules.txt means all rules.txt files on the server.
(This will not produce a channel selector but will list all matching files on the server in a single list.)
*/.exe means all files whose names contain .exe in all channels.
Warning: This is not the same as all files with the .exe extension; a file named
list.of.executives.txt will also match.
*/* means all files in all channels on the server.
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.
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:
*) will cause TTCom to prompt you to select the owners you want from the set of all
owners of files on the server that match the file name pattern you specified in the command.
"") will match the anonymous account.
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 get -o doug * dl offers to download all files uploaded to the current channel by a user
whose name matches "doug".
file delete */* -o "" offers to delete all files uploaded to any channel by the anonymous
account. (Only admins can delete from all channels.)
fi get */* -o doug -o bob -o jill
offers to download, from any channel, any file uploaded by users matching "doug," "bob," or "jill."
TTCom provides the following features in its file transfer support beyond those in the official TeamTalk clients:
Security points worthy of note:
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:
:log and Enter
file delete */*
TeamTalk supports three types of messaging, with TTCom equivalents as shown, plus a notification type listed last:
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.
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 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.
*"Doug Lee" (dlee) has an empty typing area*This notification is also sent if the user empties the typing area without sending a message.
*"Doug Lee" (dlee) is typing*
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).
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:
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 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:
whoIs bob and notice the userid number. For this example, say it
is 251.
prefix bob, type prefix #251 (notice the number sign). This
will make your prefix send messages specifically to Bob's current TeamTalk session.
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:
socket.getaddrinfo() call.
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:
status: The status of the query. This is usually success but may be a different
value for a failed or invalid query.
lat and lon, an approximation of latitude and longitude for the IP address,
expressed as decimal numbers.
These should have similar accuracy to the address fields already mentioned.
org: The organization hosting the IP address; always seen to match isp during
testing of this TTCom feature.
as: The Autonomous System Number (ASN) assignment for the IP address and the company to which
the number is assigned.
query: The IP address that was queried; this is actually the IP address that normally appears
on the top line of the output when -v is not specified.
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 provides a system for creating and managing custom command shortcuts. It supports
the following syntaxes:
alias (by itself)
alias blah
blah. This will be what TTCom actually runs
when blah is typed as a command.
alias cl clear
cl to mean clear.
From now on, typing cl will clear the screen.
alias mv move
mv act like move.
mv doug / would now be equivalent to move doug /.
alias -cl mv
cl and mv aliases.
alias mbob umsg #498
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:
%) followed by a digit will be translated into
a parameter from the actual alias command line.
%%).
about, alias, errtrace, eof, exit,
help, and quit.
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)
box blah
blah. This will be what TTCom actually connects to
for any server that uses blah as a host address.
box bob myhost.mydomain.name
bob for use in server definition host lines.
If the box already had an address, it is updated to what is given.
box -bob
bob box definition.
Example usage: The command
box bob bobsbox.linode.com
host line in the configurations for all TeamTalk servers on that "box" to read
host=bob
host=bobsbox.linode.com
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:
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.
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.
The command described in this section is likely to be of use only to TeamTalk server box administrators who have access to the XML configuration files used to configure TeamTalk server instances.
TTCom includes a flags command that, given a flag type and a flag value, can print which flags
are enabled in the given value.
Type help flags for a list of the flag types supported.
See also the Technical Information For TTCom Users sections and its subsections,
which include tables listing some of these flag types and their values.
To use this command, type flags followed by the flag type and the flag value.
The flag type can be a prefix of the type name; e.g., "u" or "user" for UserRights.
The value can be a decimal value or "0x" followed by a hexadecimal value; e.g., "0x3F607."
By default, TTCom will print single-word values for the enabled flags. This can be adjusted by adding
-c for character values or -l for long (multi-word) values.
This section and its subsections are a reference for TTCom users on parts of the TeamTalk TCP protocol that are exposed directly through TTCom.
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.
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.
| Hex | Letter | Short Name | Description |
|---|---|---|---|
| 0x01 | P | permanent | Permanent channel (as opposed to temporary) |
| 0x02 | x | exclusive | Exclusive (one transmitter at a time) |
| 0x04 | c | classroom | Classroom channel |
| 0x08 | o | opOnly | Only ops see and hear |
| 0x10 | p | pushToTalk | Push to talk only |
| 0x20 | n | noRecord | No recording allowed |
| 0x40 | h | hidden | Hidden channel |
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.
| Hex | Letter | Short Name | Description |
|---|---|---|---|
| 0x00000001 | l | loginMultiple | Can log in multiple times |
| 0x00000002 | f | findUsers | Can see users in all channels |
| 0x00000004 | t | tempChannels | Can create temporary channels |
| 0x00000008 | p | permChannels | Can create/modify all channels |
| 0x00000010 | B | Broadcast | Can broadcast text messages |
| 0x00000020 | k | kick | Can kick users off the server |
| 0x00000040 | b | ban | Can ban users from the server |
| 0x00000080 | m | move | Can move users between channels |
| 0x00000100 | o | op | Can make other users channel operators |
| 0x00000200 | u | upload | Can upload files |
| 0x00000400 | d | download | Can download files |
| 0x00000800 | U | UpdateProps | Can update server properties |
| 0x00001000 | v | voice | Can transmit voice data |
| 0x00002000 | V | Video | Can transmit video data (webcam) |
| 0x00004000 | D | Desktop | Can share out the desktop |
| 0x00008000 | I | Input | Can send input to another user's desktop |
| 0x00010000 | s | streamAudio | Can stream audio files |
| 0x00020000 | S | StreamVideo | Can stream video files |
| 0x00040000 | N | nickLocked | Nickname is locked against user changes |
| 0x00080000 | T | statusLocked | Status is locked against user changes |
| 0x00100000 | r | record | Can record audio in all channels |
| 0x00200000 | h | seeHidden | Can see hidden channels |
| 0x00400000 | P | PM | Can send private messages* |
| 0x00800000 | C | CM | Can 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.
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.
This TTCom instance's subscribe command modifies sublocal.
Think of "sublocal" as meaning "subscriptions (and intercepts) that are locally set."
subpeer represents which information is wanted by the queried client from this TTCom instance.
This value is modified by the other client's subscription and intercept requests.
Think of "subpeer" as meaning "subscription and intercepts set by this other person's, peer's, client."
Notes on the below table:
| Hex | Letter | Short Name | Description |
|---|---|---|---|
| 0x00000001 | u | userMsg | user message subscription |
| 0x00000002 | c | channelMsg | channel message subscription |
| 0x00000004 | b | broadcast | broadcast message subscription |
| 0x00000008 | t | typing | typing notification and custom message subscription |
| 0x00000010 | a | audio | audio subscription |
| 0x00000020 | v | video | video subscription |
| 0x00000040 | d | desktop | desktop subscription |
| 0x00000080 | i | input | desktop input subscription |
| 0x00000100 | s | mediaStream | media stream subscription |
| 0x00000200 | k | bitK | bit k subscription |
| 0x00000400 | l | bitL | bit l subscription |
| 0x00000800 | m | bitM | bit m subscription |
| 0x00001000 | n | bitN | bit n subscription |
| 0x00002000 | o | bitO | bit o subscription |
| 0x00004000 | p | bitP | bit p subscription |
| 0x00008000 | q | bitQ | bit q subscription |
| 0x00010000 | U | iUserMsg | user message intercept |
| 0x00020000 | C | iChanMsg | channel message intercept |
| 0x00040000 | B | iBroadcast | broadcast message intercept (not used) |
| 0x00080000 | T | iTyping | typing notification and custom message intercept |
| 0x00100000 | A | iAudio | audio intercept |
| 0x00200000 | V | iVideo | video intercept |
| 0x00400000 | D | iDesktop | desktop intercept |
| 0x00800000 | I | iInput | desktop input intercept (not used) |
| 0x01000000 | S | iMediaStream | media stream intercept |
| 0x02000000 | K | iBitK | bit k intercept |
| 0x04000000 | L | iBitL | bit l intercept |
| 0x08000000 | M | iBitM | bit m intercept |
| 0x10000000 | N | iBitN | bit n intercept |
| 0x20000000 | O | iBitO | bit o intercept |
| 0x40000000 | P | iBitP | bit p intercept |
| 0x80000000 | Q | iBitQ | bit q intercept |
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:
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 communication is composed of two distinct types of Internet traffic:
TeamTalk uses TCP traffic for the following purposes:
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
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.
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:
welcome message to the client via TCP.
login command to the server and receive text (TCP) responses
indicating a successful login.
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.
join command via TCP to join the channel.
adduser events to all other clients to notify them that this client has
joined the channel.
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 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:
channel or chanid parameter update would not
apply in practice for an account whose server-side entry includes an initial channel (initchan),
so TTCom applying such a change would contradict expected TeamTalk behavior.
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.
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:
TZ that affect this determination
(this can cause TTCom to display a different time than shown by another client on the same computer),
and how accurate is the installation's data
regarding time zones and daylight saving change information for the zone.
This is the revision history of TTCom, most recent revision first:
Note: This is a significant update because it
ttcom.conf out into a new ttcom.ini file.
The file split will happen automatically when you first launch this updated TTCom revision,
though the upgrade process may require manual intervention if there are errors in the configuration file
such as duplicate server names.
ttcom.conf file.
This TTCom update changes several items that may affect plugins. The information is collapsed here so as not
to confuse non-coders, but plugin authors should come back and expand this section before upgrading TTCom.
Details on plugin interface changes
Authors and maintainers of TTCom plugins should keep the following in mind when supporting TTCom revisions
before, after, or both before and after this revision:
channelid to be a synonym for chanid.
This support is removed in this revision; plugins must reference chanid and not
channelid.
Simply change all channelid references to chanid for compatibility with both older
and newer TTCom revisions.
chanid has long been the correct name for this value in the TeamTalk TCP protocols.
server object's nonEmptyNickname method and passes
any boolean flags should replace the flags with a single flags value composed of characters for
each flag that should be True.
Use character d for forceDetails, t for includeUserType,
and n for noLimit.
Additionally, character c will cause the user's client name to be included after the username.
As an example, the call
should be replaced with the call
self.curServer.nonEmptyNickname(user, forceDetails=True, noLimit=True)
If you must pass flags to this method and must also remain compatible with older TTCom revisions, it will
become necessary to conditionalize the method signature based on the TTCom revision number, which can be
found as an self.curServer.nonEmptyNickname(user, "dn").
str in conf.version.
To access conf, use the line
One reason for this change is to simplify any future expansion of the accepted flag list without causing
newer code to stop working on older TTCom instances.
from conf import conf
ttcom.ini, rather than in
ttcom.conf, and should be accessed via the services of the conf or
configobj modules, not via iniparse which is removed from TTCom in this revision.
Use only conf module calls to remain compatible with old and new TTCom versions.
ttcom.ini will not take effect until a refresh command is
run, which will also update any servers whose definitions were changed in ttcom.conf.
This is not an operational change per se since this was also true when everything was in
ttcom.conf, but it is mentioned here to avoid any ambiguity.
ttcom.conf. This is fine, and those that are
known to this TTCom author are listed as "external" in the TTCom code as of this revision.
This author would appreciate being notified of any keys being added by a plugin, so new keys can be listed.
Future TTCom versions may begin producing warning messages about unrecognized keys in a server definition,
to help catch typos and other similar errors.
conf.servers().values() returned a list before but now returns a dict.
Note however that this call reads and parses the ttcom.conf file on every call, and is thus not
an efficient means for obtaining both routine and custom per-server parameters.
The preferred method is to use the TTComCmd.servers dict, whose keys are also
shortname.
This dict is updated only when a refresh command is run.
See also the next item.
loginParms key in the dict for a server contains the keys for that server from
ttcom.conf.
(This has been true for a very long time but was not formally documented.)
For most situations, the server relevant to the firing of a trigger in one of the trigger's methods is
self.server; thus, to get the speech value for the server that fired a trigger,
use self.server.loginParms['speech'].
conf.servers() results and the in-memory TTComCmd.servers dict
include actual addresses, not box names, for host values;
so plugin writers need not worry about this change.
toString method on any object of a
BitFlags subclass, these being
ChannelTypes, LogEvents, Subscriptions, and UserRights:
The interface has changed so that style is the only parameter and is a string rather than an int.
Translate any calls thus:
True for Optimize, add "A" to the style string and
remove the second argument.
There are several things to keep in mind during this update:
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.
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.
Until certain that your configuration file contains no errors, run TTCom from a command prompt where its
output will not be lost if it exits due to an error. Error messages will include the line number where the
error was found, to help with editing.
lint command is now obsolete
and is removed from TTCom, along with its section in this document.
ttcom.conf are
server and include.
All other sections are moved to ttcom.ini.
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.
ttcom_default.conf is now ttcom.conf.sample.
This file is not used by TTCom now but remains as a sample and possible starting point for server setup.
ttcom_default.conf that you find.
ban command in its subcommands in detail.
ban list command is reformatted and will include, when present, the user
name of the account that created the ban. This became available starting in TeamTalk server version 5.15
(December 20, 2023).
ban list command are ordered by increasing creation time. This may
also be the default order returned by TeamTalk servers for server bans, but this sorting order is now coded
into TTCom to ensure consistency and also to sort correctly when channel bans are also listed (see below).
ban add command has a new -a or --address option that allows
banning of an IP address, subnet, or pattern regardless of who is currently logged in.
Warning: This feature is experimental, subject to change, and may or may not work as
expected based on TeamTalk server version.
This feature should not be used against TeamTalk servers older than 5.13 and has mostly been tested on
server versions 5.15 and later.
The TTCom support for adding bans of this type is being designed to work around various apparent issues in
TeamTalk server handling of subnet and pattern bans.
Example: ban add -a 192.168.55.
ban delete will display matching bans even when there is only one match.
ban list command has some new options:
-a or --all
-C or --channel
-C short option is capitalized because -c has long been used already to return
a ban count instead of a ban list.
host lines to refer to a box (machine or VM running
TeamTalk servers) by a custom name. The address of that box can then be
changed in one place to cause all of those TeamTalk servers to use the new location.
ttcom.conf does not exist on TTCom startup, TTCom will run instead of exiting but will warn
of the file's absence.
-c option.
Place the command to run after the -c option. Do not place the command in quotes.
TTCom will not connect to servers when invoked in this manner, and it is an error to list servers when using
this option. Examples:
# Define an alias on the fly.
ttcom -c alias mv move
# Look up an IP address.
ttcom -c geo 192.168.1.1
refresh command, the current server will become the last server
that tries to log in, rather than the last server defined or refreshed.
stats command, which requires admin rights, prints file transfer statistics after
rather than before the totals.
This is because TeamTalk does not include file transfer byte counts in the totals.
motd) that result
only from changes in server-side variables that are included, such as user count on the server.
If the message is actually changed, the resulting motd_raw change will still be reported.
This change in behavior prevents other changes, such as a user timeout adjustment, from also printing old
and new copies of the motd when it did not substantively change.
geolocate command should accept IPv6 socket addresses for IPv4
connections, e.g., addresses starting with "::ffff:," in more circumstances.
loginError/connected instead of just
connected. This is considered a bug fix because this behavior was originally intended.
refresh causes
an extra instance of a changed server to remain logged in.
whoIs command.
version command allows multiselection when more than one user matches the given argument.
This feature was requested a while ago by Simon Jaeger.
url command no longer adds encrypted=false; the encrypted parameter
is only needed when it is true.
pmsg command still works.
stats command prints its results in a much more friendly manner:
stats command is only available to server administrators; this is a requirement
enforced by TeamTalk servers.
refresh command is issued.
usertimeout is
shortened substantially during an active session.
AttributeError on geo -v when the address lookup fails.
geo command to work on an IPv6 address even from a machine that doesn't support them.
Inspired by an old Mac.
Changes to commands and their responses:
WhoIs prints "Not connected" instead of an error if asked for info from a disconnected server.
geolocate command is used without arguments:
Previously, this looked up the current user's IP address. Now, it looks up the IP address of the current
TeamTalk server, which can be useful in diagnosing connectivity problems such as excessive lag times.
If the server is currently connected, the address of the connection is used. If it is not, TTCom looks up the
server's hostname.
This can result in more than one address, such as when a server supports both IPv4 and IPv6 connections. In
this case, address information will print for all returned addresses, in the order returned by the
Python socket.getaddrinfo() call.
-m (include me) flag on the allSummary command doing nothing.
Thanks to Christopher Duffley for spotting this.
account list and channel list commands:
-l flag for getting a long listing is changed to -v, for verbose.
-e flag for requesting everything including empty fields is removed; specify
-v twice, or just type -vv.
account list -vv will show "Note: None" for an account that has no note.
channel list -vv will show "Topic: None" for a channel that has no topic.
account list -v or -vv will include one-word descriptions of user rights
alongside the hex value of the field. When more flags are set than unset,
"all but" and the unset ones print, instead of a long list of set ones. The results "all" and "none" print for
cases when all or no flags are set as well.
Other changes and fixes:
ttcom.exe executable is now compiled with Python 3.11 instead of Python 3.7, is
distributed in its own ttcom_win.zip file instead of being part of the main ttcom.zip
file along with the TTCom source code, and is no longer compacted into a single .exe file.
(As a side effect, non-Windows users may now enjoy a much smaller ttcom.zip download size.)
There will now be several files and folders extracted when ttcom_win.zip is expanded.
This change may increase TTCom's loading speed on Windows. This change was motivated, however, by
difficulties with single-executable Python programs being routinely and inaccurately flagged by antivirus
software, including Windows Defender, as threats.
ttcom.exe contained a trojan horse. Research on this surprise immediately indicated that this
problem has become very common for single-file Windows executables that are compiled from Python and a few
other more rapid-development languages.
This author chose to work around this problem by distributing the Windows executable as a file set instead of
as a single file, rather than reverting to older Python and/or Pyinstaller versions. At this writing, it
appeared as though a Pyinstaller 4.x version would otherwise have been required, though current versions are
5.x.
geolocate command which looks up freely available location
and related information about an IP address.
The initial code for this feature was contributed by Ivan Soto
and uses ip-api.com to obtain its information.
server info is improved:
autosave when it is 0.
motd value is properly formatted instead of printing "\r\n" where a new line should begin.
In the unlikely event you really need the unformatted value, you can type this command to get it:
!app.curServer.info.motdraw
motd command is the proper way to get the message of the day with any
server-side variables translated into their values.
help followed by both a command and a subcommand, e.g., help account
list, is allowed and will print whatever help is directly available for that subcommand.
At this time though, most of this type of help will simply advise you to type the command, the subcommand, and
-h for more information.
whoIs command, when typed without arguments to retrieve information on the current user,
avoids printing the current user's password for TeamTalk servers that send it as part of the
accepted event that is sent during the login sequence.
TeamTalk servers do not send passwords for other users, so this only affects queries about yourself.
LogEvents value for a server changes, the change is shown as the added and/or
removed flags rather than as the old and new decimal values of the field, which is not easy for most people to
interpret.
ping to a server that is not connected will produce the
message, "OSError: Not connected," instead of the far less explanatory, "AttributeError: 'NoneType' object has
no attribute 'send'."
IndexError message.
pyinstaller tool, which ran in Windows to make the Windows
ttcom.exe file.
Difficulties with running Windows utilities against WSL files delayed migration of the build environment into
a WSL file folder. This is the change that permitted this update's fix to file permissions.
ttcom_default.conf no longer says that TTCom is unable to log into public servers, calls them
"official" servers now since "public" servers are no longer a thing in TeamTalk, and demonstrates a web login
as is required by the public US server.
details tag
that may be expanded to show them. Among the benefits of this, heading count is reduced and text searches won't
match very old material.
account, ban, and channel commands against a
field that does not always exist works now instead of producing a KeyError.
An example command that works now but did not before is account list !note="", which lists all
accounts that have a non-empty note field.
allSummarize command is renamed to allSummary, for consistency with the
summary and shortSummary commands.
silent=2.
This was inspired by cases of silent=2 causing TTCom users to be unaware that other users had moved
them into or among channels
without asking permission.
stats command is printed even when silent=2 or higher is in effect
for the current server.
This and the previous item are actually part of the next change.
silent=
value in ttcom.conf:
stats command.
account list command works against TeamTalk 5.13 servers instead of producing an
AttributeError.
TeamTalk 5.13 servers do not send a value for the note field when it is empty, and TTCom was
expecting a valid but empty value instead.
account list command also includes a Last Modified column in its default output format.
Beware, though, that some servers, especially older ones and servers that were set up long ago, will send
bogus dates for this field, commonly dates from 1969 or 1970.
summary command allows a -m flag to make results include "me" (the
current user, or self). Use the help summary_flags command for details on this and the other
available flags.
This new flag is intended to make finding oneself and other participants in the same channel easier, which is
in turn useful for those who often join a channel and use the cmsg command to text among channel
participants.
The allSummary and shortSummary commands also support this flag, though this may
well be less useful.
help summary_flags, should be improved a bit, such as
by minimizing the number of times a word is split between lines.
This may still happen when graphical characters appear in a line.
SendMessage, is no longer a user command.
This is the code that is used to send messages with
the cmsg, umsg, and broadcast commands.
Attempting to use the erroneous SendMessage command directly would have caused an error.
rel command for printing the release notes for all updates that have not already
been installed.
The material printed by this command comes directly from the Revision History section of this document's online
version. The formatting may be less visually appealing than in a web browser however, due to limitations of
Windows console output.
For those who like to live on the edge,
rel -b will check for and print release notes for beta revisions instead of releases.
file counts and file sizes.
These are mostly useful for server administrators; for non-admins, they are limited to the current channel.
file subcommands get, check, and delete have a
-o option for limiting considered files to those owned by specific users.
See the new Specifying File Owners section for details on how to select file owners.
account list, ban list, and channel list subcommands now have a
-c option for showing only a count rather than a list. Filtering is supported for each command
when counting just as when listing; e.g., account list -c -a and channel list -c
!type=1 are permitted.
channel command has a new flags subcommand that allows viewing and setting
of various flags on a channel.
Type channel flags -h in TTCom for help on this command.
File send allows admins to send to channels without first joining them.
This change is made in concert with TeamTalk itself officially supporting such admin behavior in official
clients.
help selection and errtrace output.
Significant changes in event and trigger handling:
silent value
for each server (but see below for a new silent=3 option)::
silent=3.
Note that this change will likely make trigger users want to remove any triggers specifically designed to
print these events or messages.
Sound-generating triggers for these may of course remain useful.
ttcom.conf file. An example that printed previously
but no longer will: Given a trigger like this in ttcom.conf:
TTCom previously printed this on a trigger match:match msg1.matchOnType=messagedeliver type=1 action msg1.sound=play msg1.wav
where "simon" is the shortname for the triggering server, "messagedeliver" is the TeamTalk event name causing the trigger, "msg1" is the trigger name, and "matchOnType" is the name of the match criterion for the trigger that actually matched and caused it to fire. Trivia: This TTCom author simply forgot to remove that for a very long time, having intended it as a debugging aid.[simon] messagedeliver triggers msg1 matchOnType
Other significantly visible and/or impactful changes:
whoIs, is now "t," for
typing notification subscription. (I only figured out the purpose of this bit on November 16, 2022.)
Note though that unsubscribing from "typing notifications" for another TTCom user will also prevent you from receiving any messages sent by that user via thesub dlee -t
pmsg command.
intercept command is removed, and the subscribe command is significantly
rewritten and supports management of intercepts along with subscriptions.
Use the command help subscribe for details.
Notable among the changes is the use of single-letter flags rather than words for subscription and intercept flags.
Other changes and fixes:
ttcom.conf configuration file, such as emojis in a
nickname field, caused errors on TTCom launch on Windows (not WSL).
This has been fixed via a TTCom-specific modification to the included IniParse library.
The ttcom.conf file is now assumed to use UTF-8 character encoding regardless of operating system.
beep command that sends a bell character to the TTCom output.
This may be useful for those who run TTCom in remote ssh sessions and use triggers for alerts for certain events.
Another perhaps better alternative, though, is to create a play command on the remote machine's
PATH, such as
This would have the effect of making TTCom produce one beep for every sound or rapidly-generated group of sounds, whereas using the#! /bin/sh echo -n >&2 "\07"
beep command in a trigger will generate one beep per triggering event,
even when they occur rapidly.
eval function are replaced with more efficient techniques.
gzip module is no longer imported as it is not being used.
play commands executed from a trigger, which some users use to play sounds
on certain events, should no longer cause all future TTCom sound file playing to stop working until the next TTCom
restart. This problem may still not be fully fixed, however.
Major updates:
server command for switching servers or running a command against a non-current server is
changed to switch, to make room for commands to query and manipulate server properties and/or
TTCom configurations for servers.
The > shortcut still works as before, by being translated to switch.
pmsg command for sending more private text messages
among TTCom clients.
Previously, this was accomplished with UMsg -i.
UMsg command's -i option is removed, as the above command replaces it.
server info command prints all server property information for the current server.
server info, for the event logging value.
account list -r (list accounts by user rights), for user rights values.
channel list with -l or -e, for channel type values.
whoIs, for the user rights value.
Minor updates and bug fixes:
shortSummary command abbreviates lists of users on a server when several share the same
name, by placing a count and an "x" in front of the duplicated name.
This feature was inspired by an Internet radio station server on which an instance of the station's stream
typically appeared in several channels at once.
url command includes the channel password when appropriate. Due to a bug, this was being
omitted.
url command works when channel names and/or passwords contain spaces or other special
characters.
Note though that TeamTalk client versions prior to 5.7.1 or so will still not process these URLs correctly.
lint command for reporting problems and anomalies in ttcom.conf is updated:
bearwareid sections are understood.
nickLimit no longer causes a warning.
serverpassword causes a warning, as it has been obsolete since the arrival of TeamTalk 5.0.
KeyError that was seen twice over the last three years in the summary command.
The error occurred when a user was in a channel whose name could not be retrieved. Now when this occurs, TTCom
will show the channel with a name like "<channel10>", where "10" is the channel id in the TeamTalk TCP
protocol.
Thanks to Chris Duffley for a precise error report demonstrating this issue.
account list, account delete, and account users commands accept
a -n argument to restrict the results to "normal" (non admin, non disabled) accounts.
Specifying more than one of -a, -d, and -n for any of these commands
will also generate a SyntaxError instead of resulting in no matching accounts.
account users command allows the -d argument to restrict to disabled
accounts. This may seem silly, since disabled accounts are not able to log in; however, account users
-d will list any users whose accounts have been disabled but who remain logged in from before this happened.
note field with the account mod command with
note="" or just note= works as expected.
ttcom.conf trigger for making a server connection sound using a SoX effect:
match connected.connected=_connected_
action connected.sound=play synth 0.1 exp 330-550 vol .2
synth sounds are natively full volume, so adding a vol effect to such
requests is very useful.
summary, allSummarize, and shortSummary commands
support a new set of summary flags that determine which clients/users to include in
the output.
help summary_flags in TTCom itself provides information on how the new summary flags work.
shortSummary command is changed to omit text clients even when
they are in a channel. To get the original behavior of including these clients, add a -c flag,
which means include everyone in a channel regardless of client type.
whoIs command prints the "modifiedTime" value as a date and time instead of as a (usually
large) integer. For date/time values before or during 2004 (which predates TeamTalk), the raw integer value is
also shown.
The whoIs command only shows this field when run against your own TTCom instance.
\r" in typing indicator messages produced by clients that send them,
such as the Qt client for MacOS and Windows.
nickLimit option
has been set by the user:
version command when applied to a user.
nickname command when used to check your own nickname.
ban add command's user selection list.
op command.
CMsg, UMsg, and Broadcast commands should handle quotes more
consistently and no longer produce syntax errors on some lines containing quotes.
\n in place of line endings.
ban command supports a count subcommand, for indicating how many bans, or
how many bans matching a filter, exist on a server.
prefix system ignores blank lines, so that pressing Enter at a prompt does not
cause error messages.
ping command includes the number of milliseconds between ping and server response.
This can be useful for measuring lag time between client and server.
usertimeout values; but for the normal value of 60 seconds,
TTCom now pings every 30 seconds like other clients do.
errTrace command
produces for other errors.
man and www commands for launching TTCom's user
guide or the TeamTalk home page in the default browser.
prefix command that may be useful when exchanging text
messages.
option command supports a new nickLimit option, the numeric value of which
will limit the length of nicknames printed by several commands. Nicknames longer than this will be cut short
and end with an ellipsis.
Unless this option is set to an integer value, full nicknames will always print.
This feature was inspired by a small band of TeamTalkers who carried around nicknames over 300 characters long.
clTypes command that lists how many people are using each client type across
all logged-in servers. The purpose of this command is to help track the progress of adoption of the TeamTalk
Qt client by long-time users of the Windows TeamTalk Classic client for accessibility.
-e option to the account list command formats the value of the
modifiedtime parameter, added in TeamTalk 5.8.1, as a date/time value instead of a long number.
This update's release notes are divided into sections because of the number of changes.
Changes to the file management commands:
file list and file delete commands print files in approximate upload time
order rather than in alphabetical order.
file delete command will only list files belonging to the
current user's account.
This is because TeamTalk servers will not allow a non-admin to delete a file uploaded under a different
account, and allowing this command to attempt to do so would only cause error messages.
Other command changes and additions:
ban del works again; not sure when this broke.
account list -r is reformatted and includes the number of users in each list as well as a brief
list of the rights themselves along with the hex rights values already printed.
The total number of accounts is also included.
account command has a new users subcommand that lists currently logged-in
users organized by the accounts they are using.
The subcommand accepts the -a flag to include only admin accounts, allows containment filtering on
username, and allows "" to match the anonymous account.
This subcommand does not require admin rights because it does not need to access the list of available accounts;
it simply uses the list of logged-in users to derive the list of accounts shown.
channel list command is now printed in hex instead of decimal
and includes a list of the type flags. The one-word-per-flag format is used when -l is specified;
otherwise, the single-letter flag format is used.
Documentation and miscellaneous updates:
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.
tt command for creating .tt files allows constructs like ~,
~username, and $HOME as part of file paths.
kick command allows a -c option for kicking from channel instead of server.
This duplicates the cKick command but in a way that more easily supports command dictation in place
of typing.
WhoIs command, rather than printing simple integers, prints subscriptions as both hexadecimal
numbers and a string of letters indicating what subscriptions and/or intercepts are active.
"Local subscriptions" are what this TTCom client subscribes to from the other client, and "peer subscriptions"
are what the other client subscribes to from this TTCom instance.
There is now also a section in this guide that lists the
subscription and intercept values shown by this command.
whoIs also prints user rights, when available, in both hex and word forms. See the User Rights Values section for further information on user rights.
Generally, a user can only see the rights applying directly to that user's current login session;
results from whoIs queries for other users will not include user rights.
ResourceWarning under Windows that could occur when a server connection fails.
url command for creating TeamTalk server links.
Updates for improved functionality with TeamTalk 5.7:
account add and account delete commands include a -d or
--disabled option to list disabled accounts, much like -a or --admin
already lists
admin accounts.
If both admin and disabled accounts are requested at once, only admin accounts will appear.
account add allows 0 for a usertype to create a disabled account, and
requires confirmation before creating one disabled account from another, just as for creating one admin account
from another.
account mod allows usertype=0 to change an account to disabled.
A typical syntax for disabling an account is account mod Doug usertype=0, and for re-enabling,
account mod Doug usertype=1 (or usertype=2 for an admin account).
Other enhancements:
move and kick commands allow multiple-user selection when a user list is
presented.
account, ban, and channel commands use a more robust means of
handling quotes and argument separation. Arguments that include spaces still need quotes, but some cases where
quotes should not have been required but still were should no longer remain.
list subcommand of account supports a -r option for listing
accounts organized by user rights instead of alphabetizing by user name.
Especially on servers with numerous user accounts, this should facilitate locating users whose rights might not
be set as expected or intended.
account list and whoIs, print hexadecimal (hex) instead of decimal rights values.
To avoid ambiguity, these values are prefixed with "0x," a common prefix that indicates a hexadecimal value.
This change, though perhaps odd to non-programmers, makes it easier to spot changes in rights. For example,
the difference between 259591 and 261639 does not immediately look like the addition of exactly one right;
but when these are shown as 0x3f607 and 0x3fe07, one who can read hex can more easily determine that the change
represents the addition of right 0x800, which is the right to change server properties.
account mod Doug userrights=0x3f607
Doug.
userrights values.
account list and channel list commands.
join
chanid=0x3.
TeamtalkServer objects have a loggedIn boolean property that is True only when
the server is logged in.
For Python triggers in ttcom_triggers.py, this means that a line like the following can prevent
triggers from firing when the server is not logged in:
if not self.server.loggedIn: return
ttcom.conf trigger stop firing when a server is not logged in, append
"_loggedin" to the event or pseudo event name; e.g., line_loggedin. Examples:
match disconnected.disconnected=_disconnected__loggedin
match badword.badword=line_loggedin blah
Bug fixes and documentation improvements:
join command the fact that channels can be found by property,
such as chanid.
lint command for diagnosing various problems with the TTCom configuration file.
url command for generating a TT URL for people to click in order to join the
current server.
The URL approach will work in many cases but will fail for some due to problems with characters in passwords
and possibly other fields.
See also the tt command for creating a .tt file that will launch TeamTalk into a
particular server.
Both commands also support automatic joining of a channel on connection if desired.
WhoIs command and to status change events that print asynchronously.
README.txt file, these release notes, and various other notes are combined and
transformed into a more comprehensive user guide,
which itself becomes the main website page for TTCom.
refresh command when the server
has been deleted from the TTCom configuration file.
login command to log into a disconnected server that uses encryption.
Startup-time login already worked, but manual login without an existing connection did not.
teamtalk"
and is reported on connect if different.
ttcom.conf.
SAYPREFIX, though, rather than TTCOM_SAYPREFIX.
This feature was accidentally lost during the conversion to Python 3.
imp library instead of the newer
importlib alternative. This change will only be noticed by users who run TTCom from source.
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:
tt command can make a proper .tt file for an encrypted server.
WhoIs command:
ttcom_default.conf is removed for the following
reasons:
ttcom_default.conf as an example server entry, however.
chanid=4
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/
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!
channel list command) now sort case insensitively by channel path,
much like the TeamTalk channel trees.
CKick command for kicking a user from current or specified channel, syntax similar
to that of CMsg.
refresh command deletes servers from the running list when they have been removed from the
config file.
allSum and shortSum results end with a total server count then broken down by
connection state.
ban list now uses a three-row format and includes ban type as text (IP address or Username). The
other two lines are nickname and channel at ban time.
addresses command is now just address.
whoIs reports IPv6 addresses correctly as does the address command.
whoIs and address commands.
TTCOM_SAYPREFIX works on MacOS as a place to put Mac-specific voice
parameters to apply to all event and trigger announcements.
This feature is included to help those who wish to hear events on a Mac at a personally chosen speech rate,
pitch, etc.
This feature is experimental and may change or vanish without notice, especially since it is Mac-specific and
relies on MacOS features that may themselves disappear.
Example usage: In Bash or a compatible shell or one of its initialization / startup files, add this line to
increase the TTCom voice speed:
export TTCOM_SAYPREFIX="[[rate 450]]"
UMsg can send to a userid directly via a number sign; e.g., umsg #232 I got that!. This
was documented but did not work as expected. This allows replying to messages such as described in the previous
item.
UMsg command for sending user messages has a new -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:
UMsg command for more information on this option.
Note that nothing in TeamTalk should be considered "private" (partly because nothing is encrypted) and that
neither the TTCom author nor the TeamTalk author can guarantee privacy of these new messages or that they will be
handled as expected by different client and server versions.
ttcom.conf) or without defining
servers in it now print more sensible error messages.
refresh command if no server definitions can be found.
vlist command now formats and sorts its output more intuitively.
WhoIs command includes the length of time the current user's status has been in
effect.
Note though that these durations reset when TTCom itself logs in and thus will not always reflect actual
status lifetimes.
WhoIs output.
WhoIs includes the domain address for an IP address that is given as the IPv6 version of an
IPv4 address; e.g., "::ffff:192.168.15.124."
refresh command if a server's
autoLogin value changed from 0 to 1 without other changes for that server.
Note: The syntax of the cmsg command is changed in this update.
cmsg, operates by default on the currently joined channel.
The following sequence will thus message the root channel:
join /
cmsg Hello!
cmsg @blah Hello to blah channel members.
If TTCom is not in a channel, a channel must of course be specified in this way.
voiceusers list changes as channel participants are voiced and unvoiced by an admin.
channel list command).
whoIs could include a line beginning with a comma.
summary, shortSummary, allSummary, VList.
This is for speech users, for whom the long ids are distracting and time-consuming to read. Full ids are still
printed for the WhoIs command.
This feature only applies when both server and client versions are 5.3 or later, which means when Facebook ids
are actually Facebook logins.
channel command. So far, the only implemented subcommand is list, which can
list channels with varying detail
and can filter the set of channels listed by many means.
Warning though: There are still problems with this command on servers with non-ASCII characters in channel names.
cmsg, allow channel matching by specific TeamTalk
parameter. One use of this is to
message a channel by its id:
cmsg chanid=5 Hello
account command:
account add command to be set to 0 when the user type
was given as a number
(1 or 2).
The following command will list any accounts on a server affected by this bug:
acc li userrights=0
Doug to the default values:
acc mod Doug userrights=259591
-p argument is specified.
account delete usage help text.
-e prints all fields except passwords (use -p to add passwords), even when
blank. This is useful for determining
what fields are allowed for an account.
-l and -e), fields are sorted by name except for
Note, which is always last.
ttcom_defaults.conf better documents the format and capabilities of TTCom .conf files.
python or ! commands, the name of the TTCom root object is now
app rather than
ttcom, for consistency with other projects.
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:
account.
ban.
kb.
help or ? followed by the command name. Each
of these commands now has
subcommands, for which help is also available.
account add now does the following sanity checks:
motd command for displaying the current server's message of the day.
version command is now about.
version without arguments gives the currently selected server's TeamTalk version, and with
arguments gives a client's version and client name.
all and negation via an exclamation mark (!) if multiple
selections are allowed.
Type help selection or ?selection for complete help on handling selection lists.
-p option added to the vlist command for filtering by packet protocol or voice
capability.
admin for admin users and
user for other users.
Fixes:
op, intercept, and subscribe commands to work on TeamTalk 5
servers. (The no-audio restriction
remains, however, as there is still no support for audio in TTCom.)
summary command no longer combines multiple instances of the same user in a channel into
a single entry.
nick command is now nickname, which lets nick continue working
while also letting nickname work.
join command.
Channel matching now works thus:
/ always refers to the root channel.
/ must match exactly except for letter casing.
/ is matched against all full channel names (path included).
Server command should properly honor any quoting on an included command.
autoLogin=1, the TTCom user may
restart the auto-login behavior by logging in again manually.
tt command allows a target TeamTalk client version number, such as 5.1, to be specified
before the name of the .tt file to create. This makes it possible to generate a tt file for a client whose
version number differs from that of the current TeamTalk server.
vlist command that summarizes users on the current server sorted by increasing
version number and then by client name.
say command on MacOS may work across more non-ASCII character situations.
say commands are created more securely.
WhoIs command with no arguments (i.e., a request for
information on this current TTCom user login).
speakEvents option is supported: Setting it makes TTCom try to speak all events that print
in the TTCom window through the active screen reader.
This currently requires SayTools to be installed on Windows but works natively on MacOS.
To turn this feature on, type opt speakEvents 1. Use 0 instead of 1 to
turn the feature off. The state of this option is saved across TTCom restarts.
This revision fixes more issues with TeamTalk 5 servers and adds a few enhancements:
version command reports the running TTCom version and other information.
/) works as expected.
tt file should generate TT files compatible with the
TeamTalk server version for which the file is being generated.
ban -d works.
account command works on TeamTalk 5 and supports copying user rights from a chosen source
account when creating a new one. To use this feature, specify an account name (or something that matches an
account name) in place of the 1 or 2 normally given as a user type. To use the anonymous
account as the source account for user rights, specify "" in place of the user type. The user type
will become 1 and the user rights for the new account will duplicate those assigned to the source
account indicated.
account scenarios; for example,
acc "" reports the information for the anonymous account instead of displaying a list of all
accounts.
udpport=0 to every ttcom.conf entry for TeamTalk 5
servers. TTCom no longer transmits a UDP handshake at all. (This was implemented to avoid short Windows XP
client freezes on TeamTalk 4 servers, but Windows XP has long been deprecated by Microsoft.)
statsAdmin command is now changed simply to stats, and the old stats
command is gone. Reasons for this include
/
commands sent to a channel..
/stats visibly into the root channel even if the sending console was not there, which could startle
and confuse users.
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:
WhoIs works when TTCom is not logged in as an admin.
Move, join, leave,
cmsg, and several other commands work as well.
The following commands still do not work completely on TeamTalk 5 servers:
Account
Intercept and Subscribe
Op
TT
Other changes in this release:
say command usable in triggers, when used on MacOS,
now uses the afplay command and a temporary file instead of
piping directly through say in order to avoid the speech
breakup that occurs often (at least on SnowLeopard) when the `say'
command is used. This change causes a Python warning against use of
tempnam() on the first say command call.
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: