Say plugin for Take Command / TCC / 4NT

Version 1.1.0     2014-04-23

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 64-bit version of Take Command, take Say-x64.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 CODEindicates text which must be typed exactly as shown.
CODEindicates optional text, which may be typed as shown or omitted.
Bold italicnames a required argument; a value must be supplied.
Regular italicnames an optional argument.
ellipsis…after an argument means that more than one may be given.

Plugin Features:

New commands: SAY, VOICE

New function: @VOICE

New variables: _NUMVOICES, _VOICE

New Commands:


SAY — Speak the specified text.

Syntax:
SAY /A /D /H /K /L /N /X text… @filename…

/Aspeak command-line text Asynchronously
/DDisable SAPI XML tags in text (default)
/Hspeak Help text
/Krestart voice; cancel any asynchronous speech
/LLine breaks in text files are significant
/Nspeak line Numbers in text files
/Xenable 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.

The @file syntax does not support the CLIP: device. To read text from the clipboard, you can use input redirection:

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:



VOICE — List available voices, or select the voice for SAY to use.

Syntax:
VOICE /A /D /H name

/Aread the list Aloud
/Dselect the system Default voice
/Hspeak 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.

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]

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



Changes:


1.0.02011-01-07initial release
1.0.12011-02-25fixed return codes
1.0.22011-03-11HELP and F1 give a popup; spoken help is now available via /H. Documented /D and /K.
1.0.32011-04-12fixed a problem with /H and /K in TCC 12.10
1.0.42011-04-21bug fix: plugin name not displayed on error opening @file list
1.0.52011-04-21minor improvement to sentence detection in @files; release file handle on ^C
1.0.62011-04-28tweaks to sentence detection, handling of pilcrows and section marks
1.0.72011-11-28better handling of UTF-8 text files; now command-line text is ground through the same parser as text from files or stdin
1.0.82013-04-23updated to Visual Studio 2010; updated the plugin’s web address
1.1.02014-04-23added VOICE, @VOICE, _NUMVOICES, and _VOICE; updated various internal features to match my other plugins

Status and Licensing:

This plugin is Copyright © 2014, 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://prospero.unm.edu/dl/say.zip or ftp://prospero.unm.edu/say.zip.