Say plugin for Take Command / TCC / TCC/LE
Version 1.2.1 2023-11-22
Charles Dye
Purpose:
This plugin provides a quick and intuitive interface to the Windows
text-to-speech feature. The plugin adds two new commands:
SAY, which speaks the text on the command
line or from a text file; and VOICE, which
lists available voices or selects the voice which SAY will use.
A few utility variables and functions
are also provided.
Windows XP or later is required.
Installation:
To use this plugin, copy Say.dll to some
known location on your hard drive. (If you are using the 32-bit version of
Take Command, take Say-x86.dll instead of
Say.dll.) Load the plugin with a
PLUGIN /L command. For example:
plugin /l c:\bin\tcmd\test\say.dll
If you copy Say.dll to a subdirectory named PlugIns within your Take Command program directory, the plugin will be loaded automatically by each new instance of TCC.
Syntax Note:
The syntax definitions in the following text use these conventions for clarity:
BOLD CODE | indicates text which must be typed exactly as shown. |
CODE | indicates optional text, which may be typed as shown or omitted. |
| Bold italic | names a required argument; a value must be supplied. |
| Regular italic | names an optional argument. |
| ellipsis… | after an argument means that more than one may be given. |
Plugin Features:
New variables: _NUMVOICES,
_VOICE, _VOICENUM
New Commands:
SAY — Speak the specified
text.
Syntax:
SAY /A /D /H /K /L /N /X text… @filename…
/A | speak command-line text Asynchronously |
/D | Disable SAPI XML tags in text (default) |
/H | speak Help text |
/K | restart voice; cancel any asynchronous speech |
/L | Line breaks in text files are significant |
/N | speak line Numbers in text files |
/X | enable SAPI XML tags in text |
Put options before any text or filenames. Text and files will be read
in the same order they are listed on the command line. Text can also be
piped or redirected into SAY; redirected input will be read
after any text or files specified on the command line.
While SAY is reading text from a file, you can abort by
pressing Ctrl-C or Ctrl-Break. Be patient; it may be several seconds until
the key is recognized.
Normally, SAY will not return until all text has been read.
You can use /A to speak text from the command line asynchronously
and return immediately. Note that this option only affects text on the
command line; it has no effect on text read from a file, redirection or a
pipe. You can cancel the speech with SAY /K.
SAY is intended primarily for “readable” English
text — sentences and paragraphs. Most line breaks in text files
will be ignored. If you want to use SAY to read a line-oriented
text file (piped output from a command, for example) you can use /L
to indicate that line breaks are significant. When /L is
specified, SAY will pause to “take a breath” (and
check for Ctrl-C) at the end of each line.
Option /N causes the program to speak a “line number”
before each line of text. These line numbers do not correspond to the visual
arrangement of text in the input file or stream. They are, rather, a running
count of the lines of text passed to the Windows speech engine. They might be
better called “sentence numbers” or “utterance numbers”
if those phrases weren’t so clumsy.
Options /L and /N only apply to text read from
a file, redirection, or a pipe. They don’t affect text specified on
the command line. Options /X and /D only affect
text and filenames which follow them on the command line.
To read text from the clipboard, you can use either the
@file syntax or input redirection:
say @clip:
say < clip:
• Note: If
you want to pipe text into SAY, remember that piping creates a
new shell. If the plugin is not loaded in the new shell, you’ll get
an “Unknown command” error. To prevent this, you can:
- copy the .DLL file into your PlugIns directory, so it’s automatically loaded by the right-hand shell.
- use an in-process pipe (registered versions TCC only).
- redirect to and from a temporary file, instead of using a pipe. Remember to delete the temp file when you’re done with it.
VOICE — List available voices,
or select the voice for SAY to use.
Syntax:
VOICE /A /D /H name
/A | read the list Aloud |
/D | select the system Default voice |
/H | speak the Help text |
If you do not give a voice name or
/D, VOICE will list all available voices. The
name must follow any options on the command
line.
If name contains wildcards, the first matching
voice found will be selected. Alternatively, name
can be a zero-based index number, as reported by VOICE without
options, or returned by _VOICENUM.
VOICE only affects this plugin’s SAY
command. It does not change the system default or affect any other program.
New Function:
@VOICE — Returns the name of
one voice.
Syntax:
%@VOICE[n]
| n | integer index from 0 to %_NUMVOICES - 1 |
This function will return -1 if n
is too high.
New Variables:
_NUMVOICES — Returns the
number of voices available.
Syntax:
%_NUMVOICES
This variable will return -1 if an error occurs.
_VOICE — Returns the name of
the current voice.
Syntax:
%_VOICE
This variable will return (unknown) if an error occurs.
_VOICENUM Returns the
index of the current voice.
Syntax:
%_VOICENUM
This variable will return a number from 0 to _NUMVOICES - 1, or -1 if any
error occurs.
Changes:
| 1.2.1 | 2023-11-22 | Added support for @CLIP:. Do not show
“Plugin not loaded” messages in transient or pipe shells. |
| 1.2.0.3 | 2023-10-15 | Minor cosmetic tweaks to ShowCmdHelp(). |
| 1.2.0.2 | 2023-10-12 | Updated the plugin’s web address. |
| 1.2.0.1 | 2021-08-14 | Tweaks to the version info structure; no changes to the code. |
| 1.2.0 | 2021-04-08 | Added _VOICENUM; Say.dll is now 64-bit; various tweaks and improvements to the code and HTML doc file. |
| 1.1.0 | 2014-04-23 | Added VOICE, @VOICE, _NUMVOICES, and _VOICE; updated various internal features to match my other plugins. |
| 1.0.8 | 2013-04-23 | Updated to Visual Studio 2010; updated the plugin’s web address. |
| 1.0.7 | 2011-11-28 | Better handling of UTF-8 text files; now command-line text is ground through the same parser as text from files or stdin. |
| 1.0.6 | 2011-04-28 | Tweaks to sentence detection, handling of pilcrows and section marks. |
| 1.0.5 | 2011-04-21 | Minor improvement to sentence detection in @files; release file handle on ^C. |
| 1.0.4 | 2011-04-21 | Bug fix: plugin name not displayed on error opening @file list. |
| 1.0.3 | 2011-04-12 | Fixed a problem with /H and /K in TCC 12.10. |
| 1.0.2 | 2011-03-11 | HELP and F1 give a popup; spoken help is now available via /H. Documented /D and /K. |
| 1.0.1 | 2011-02-25 | Fixed return codes. |
| 1.0.0 | 2011-01-07 | Initial release. |
Status and Licensing:
This plugin is Copyright © 2023, Charles Dye. Unaltered copies of the binary and documentation files may be freely distributed without restriction. I make no guarantee and give no warranty for its operation. Use it at your own risk. If you find a problem, you can report it in the JP Software support forum.
Download:
You can download the current version of the plugin from http://charlesdye.net/dl/say.zip.