@database Talk
@author "Mathew Wilson"
@wordwrap

## $VER: Talk.guide v1.00 (8.11.95)

## ars est celare artum

@node "Main" "Talk©"

	   Talk v1.00
	   ~~~~~~~~~~

	@{"  " LINK AboutTalk} What is Talk?

	@{"  " LINK Requirements} Requirements.

	@{"  " LINK Modes} Talk modes.

	@{"  " LINK Commands} Commands.

	-------------------

	@{"  " link Disclaimer} Disclaimer.
@endnode

@node AboutTalk "What is Talk?"

	@{u}About Talk.@{uu}

Talk is a replacement for the old Commodore 'Say' program.
It has 99% of the same features with a whole lot more added.

The only thing Talk doesn't have is the Phoneme window. I could have easily added it but I really couldn't be bothered as it is only of extreme trivial value.

This program was written basically so I could have more control over narration from shell. Talk has a whole range of commands that you will find useful, including some Time and string formatting features.

Talk is classified FreeWare. See @{"Disclaimer" link Disclaimer}.

Have fun...

Mathew Wilson

	Contact me at:
	Box 6022, Halifax Street Post Office
	Adelaide SA, 5000
	AUSTRALIA

At present I can be e-mailed via David Cottrell

	dcottrel@adam.com.au
@endnode

@node Requirements "Requirements"

	@{u}Things you will need to run Talk.@{uu}

If you have, at one time in your, life bought an Amiga with a 1.x - 2.x ROM then you will be lucky enough to own the Translator library and narrator device files on disk. Sadly the old Commodore (Rot. IP) did not renew their license agreement to distribute the files needed for speaking in the later operating systems. So if you do not have the LIBS:translator.library (used to translate text into phonetical symbols)  or DEVS:narrator.device (receives  phonetical symbols and speaks them) then find someone who does.

Updates to the Translator library can be found on the Public Domain. eg. Francesco Devitt's Multilingual-speech version.

The narration capabilities were upgraded with v37 of the OS and Talk takes advantages of these. Talk requires these later versions to operate properly.
@endnode

@node Modes "Modes of operation"

	@{u}Modes of Operation.@{uu}

Those of you who are familiar with the 'Say' program will find similarities with Talk in the following descriptions, plus some nice extras.

 Talk has four modes of operation.

@{b}Command Line:@{ub}

This is the standard form of executing programs from a CLI / Shell. The program handles multiple identical arguments per command line. It does not use standard AmigaDOS (ReadArgs) command parsing and will interpret every argument on the command line separately in a chronological order.

@{b}Direct Entry:@{ub}

If you launch Talk with no arguments, a window (console) will appear. A list of all options will appear and you may type directly into this window. Everytime you press return, that line will be performed by Talk. Do not confuse this with a CLI / Shell where you execute programs.
To quit this mode just close the window in the standard way(s).

@{b}File:@{ub}

This mode allows you to have Talk narrate a file containing pure ascii text. If you get extremely bored one day you could tell it to narrate your 's:user-startup' file. There are examples going round of scripts that get the computer to 'sing' via a clever combination of speech parameters.

@{b}Icon Tooltypes:@{ub}

If you launch Talk from Workbench via an icon then you may place speak commands in the tooltype list. Only one command is allowed per line! Multiple commands per line is available in every other mode except this one.

	Tooltypes:
	Legal: -r
	       hello, I'm
	       -p65
	       a robot.

	Illegal: -r hello, I'm -p65 a robot.

You may open a window (console) by entering '@CON' as a tooltype. In this case the Mode will change to File Mode as consoles are handled like opened files. Therefore, @{b}no@{ub} other tooltypes will be read after a '@CON'
@endnode

@node Commands "Commands"

	@{b}Talk Commands.@{ub}

Every command begins with a minus sign '-'. This identifies a command and the following character will always be interpreted as a command. String formatting commands begin with a '%' character.

All options can be obtained at anytime by entering a '?'. The options are:

   @{" > " link C_Sex} -m.....: Male voice.
   @{" > " link C_Sex} -f.....: Female voice.
   @{" > " link C_Mode} -r.....: Robotic voice.
   @{" > " link C_Mode} -n.....: Natural voice.
   @{" > " link C_Rate} -s###..: Speech rate (40 - 400).
   @{" > " link C_Pitch} -p###..: Speech pitch (65 - 320).
   @{" > " link C_Volume} -v##...: Volume (0 - 64).
   @{" > " link C_SamplingFrequency} -q#####: Sampling frequency (5000 - 28000).
 * @{" > " link C_ExtendedCommands} -t##...: F0 Perturb.
 * @{" > " link C_ExtendedCommands} -e##...: F0 Enthusiasm.
 * @{" > " link C_ExtendedCommands} -a##...: Articulate.
   @{" > " link C_Filename} -x file: [read] [nop]
   @{" > " link C_Default} -d[opt]: Reset setting(s) to default.
   @{" > " link C_DisplaySettings} -o[opt]: Display setting(s).
        -l.....: Toggle Filter (led).
   @{" > " link C_FaceWindow} -w#....: Face Window.
   @{" > " link C_LoadSettings} ->#....: Load setting (0, 1 - 9).
   @{" > " link C_SaveSettings} -<#....: Save setting (0, 1 - 9).
   @{" > " link C_SpeechString} string.: Speech string.

Any numerical parameters for an option @{fg highlight}must@{fg text} be positioned directly after the command option with no spaces.  

	 	LEGAL	-p65
		ILLEGAL	-p 65

The commands may be used in any of the standard @{"modes" LINK Modes}.

* I have not included all the v37+ extended commands because I haven't got round to it and don't use them much.
@endnode

/*** COMMANDS ***/

@node C_Sex

	@{b}Sex:@{ub}

Set the speaking voice.

   -f (female)
   -m (male);

   Default: Male

Not very convincing, but neither is life.
@endnode

@node C_Mode

	@{b}Mode:@{ub}

Set the speaking mode.

   -r (robotic)
   -n (natural) (if you can call it natural 8)

   Default: natural
@endnode

@node C_Rate

	@{b}Speech Rate:@{ub}

Set the speaking rate (speed).

   -s### (40 to 400)

   Default: 150
@endnode

@node C_Pitch

	@{b}Pitch:@{ub}
	
Set the speaking pitch.

   -p### (65 to 320)

   Default: 110
@endnode

@node C_Volume

	@{b}Volume:@{ub}

Set the speaking volume.

	-v## (0 to 64)

   Default: 64
@endnode

@node C_SamplingFrequency

	@{b}Sampling Frequency:@{ub}

Set the sampling frequency. The lower the frequency, the 'grittier' it sounds.

   -q##### (5000 to 28000)

   Default: 22200
@endnode

@node C_ExtendedCommands

	@{b}Extended Commands@{ub}

Not all narrator extended commands are available at the moment.

   Default:
      o F0Perturb    - 0
      o F0Enthusiasm - 32
      o Articulation - 100
@endnode

@node C_Filename

	@{b}File Name:@{ub}

Change to File Mode; specify a filename to be opened and read.

   -x (file name) [READ] [NOP]

@{u}A space must be placed before the file name.@{uu}

   LEGAL   -x ram:daisy
   ILLEGAL -xram.daisy

   READ - This option causes the contents of the file to be displayed as they are read.
   
   NOP  - Turns off Command Option Parsing for the file.
          That way Talk will not attempt to interpret any '-' command specifiers in the file to be read.
@endnode

@node C_Default

	@{b}Default(s):@{ub}
	
Reset one or all options to their default parameters.

   -d[option]

If you wish to reset one of the parameters to default then just type '-d' followed by the option.

	eg. '-dp' will reset the pitch to its default setting.

If you type '-d' then ALL options will be reset to their defaults.
NOTE: in the '-d' option, the character following the command will always be interpreted as an option unless it is a digit.

eg. -dg will try to reset a 'g' default which doesn't exist - ignored.
-d5 will reset all options to defaults and speak 'five'.
@endnode

@node C_DisplaySettings

	@{b}Display Settings:@{ub}

Display one or all of the Command Parameter settings.

   -o[option]

Just '-o' will display all the parameters with their current settings.
'-o' followed by a command character will display the corresponding parameter.

	eg. '-op' will display the current pitch setting.
@endnode

@node C_FaceWindow

	@{b}Face Window:@{ub}
	
Open or Close the Face Window.

   -w# (0, 1 to 9)
   
The Face Window contains a simple face. Its mouth moves when speaking occurs.
It can be turned on or resized by specifying a parmeter or 1 to 9. The size is relative to your screen height. So a size of 9 will be maximum height. You may turn the window off by either specifying a size of 0 or quiting the program.

   eg. '-w1' open window at minimum size.
       '-w9' open window at maximum size.
       '-w0' close window if it is opened.
@endnode

@node C_LoadSettings

	@{b}Load Settings:@{ub}
	
Load the speech settings from Saved or Environment file.

   -># (0, 1 to 9)
   
The @{"SaveSettings" link C_SaveSettings} command saves 9 different settings to the file "S:TalkDefaults"
You may load these individual settings with the '->' command.

There is also an Environment file called "TalkEnv" located in the ENV: drawer, which usually resides in RAM:. You may load this file as well.

To load the settings in the Environment file just specify '0' with the load command.
   eg. '->0'
   
To load the settings in the Saved file (S:TalkDefaults) just specify the number of the setting.
   eg. '->1'
       '->9'

As soon this command is successfully called, Talk will use these settings for its speech until you alter the settings or quit the program.

* BUT, everytime Talk runs, it will load the settings in the Environment file! This way you can set some global defaults so you don't have to keep giving the parameters you want or loading a Saved setting. Something to remember is that when Talk loads a settings file (including the Environment file) and it contains a @{"Face command" link C_FaceWindow}, the Face will not appear until something is to be spoken. Imagine you had the Global defaults in the Environment file saved with the Face Window open then you called talk but didn't want any Face Window open. The Face would be automatically opened whenever Talk runs. So then you decide to put a '-w0' on the command line for Talk. Now when Talk is run you would see the Face open and close. This is undesirable, so the Face Window will not be opened when Talk reads the Environment file, only when something is to be spoken. At all other times, the Face Window will open when called.

If you've installed Talk from the Everyday Organiser Installer then you'll find that some defaults have been copied into your s: drawer. Try the following for some crazy speech:

talk ->4 these earth creatures must be exterminated
@endnode

@node C_SaveSettings

	@{b}Save Settings:@{ub}
	
Save the current speech settings to a Saved or Environment file.

   -># (0, 1 to 9)

The Saved file refers to the file "S:TalkDefaults" (permanent file).
The Environment file refers to the file "ENV:TalkEnv" (temporary file).

You may save 9 different settings to the Saved file.
Only one lot of settings can be saved to the Environmental file.

When Talk runs, it uses the settings in the Environmental file for its defaults. If it can't find the file then it uses the standard system defaults.

So by saving the settings to the Saved file you can use it at a later date and saving to the Environmental file means that Talk will now use those settings for this current session.

Save to the Environmental file by specifying a '0' with the save command.
   eg. '-<0'

Save the settings to the Saved file by specifying a number from 1 to 9.
   eg. '-<1'
       '-<9'

You could load a Saved setting and save it to the Environmental file in your "s:User-Startup" to set your favourite parameters as defaults.
   eg. 'Talk ->1 -<0'
@endnode

@node C_SpeechString

You may enter any text to be spoken with the addition of the following Special Commands.

   @{b}Special Commands:@{ub}

   %t - the current time.    eg. 12 24 PM
   %T - the current time.    eg. 12 24 & 12 O'Clock (No AM or PM postfix)
   %w - the current weekday. eg. Wednesday
   %d - the current day.     eg. Eighth
   %m - the current month.   eg. November
   %y - the current year.    eg. 19 95
   
   %n - translate a number.  eg. %n21
   
These Special Commands (begin with '%') can be inserted in your speech string at anytime. The results are not Locale sensitive, sorry. The results are specially designed so they are spoken in english.

The '%n' option allows you to have Talk translate and say numbers correctly. If you wanted Talk to say the number 101 it would normally say 'one oh one.' But with the '%n' option it would say 'one hundred one.' Talk will translate numbers up to 99,999.

With the program Alarmist© by the same author you can have Talk speak the current time every hour with '%t' 
Try opening the Face Window as well and you'll have a face appear on every hour and tell you the time.

You could place Talk in your' user-startup' script to speak the day.
eg. 'c:talk today is %w, %d of %m'
@endnode

@node Disclaimer "Disclaimer."

The following notice applies to the program "Talk" and everything contained within its original distribution archive.

   ° The program was written by Mathew Wilson.

   ° The program is classified @{b}FreeWare@{ub}, which means it is:
      - Freely distributable as long as its original archive remains intact.
      - Copyrighted by its author and you are NOT permitted to modify the program(s) and documentation in any possible way.

   ° No warranties are given. No responsibility is taken for any possible use or misuse of the program(s) by its users.
     The Author has tried to prevent errors but he can't guarantee that it is 100% bug free. You therefore use this program and any other associated program at your own risk.

   ° This package must not be sold directly or indirectly without prior written consent given by the Author. Although, it may be placed on any media used in the distribution of free software without consent from the Author.

@endnode