TABLE OF CONTENTS

narrator.device/AbortIO
narrator.device/OpenDevice
narrator.device/CMD_FLUSH
narrator.device/CMD_READ
narrator.device/CMD_RESET
narrator.device/CMD_START
narrator.device/CMD_STOP
narrator.device/CMD_WRITE
narrator.device/CloseDevice


narrator.device/AbortIO				    narrator.device/AbortIO

   NAME
	AbortIO - Abort an IO request


   SYNOPSIS
	AbortIO(IORequest)
		   A1


   FUNCTION
	Exec library call to abort a specified READ or WRITE request.
	The IORequest may be in the queue or currently active.  If
	currently active, the request is immediately stopped and then
	removed.


   INPUTS
	Pointer to the IORequest block to be aborted.


   RESULTS
	io_Error field in the IORequest block set to #IOERR_ABORTED.


   SEE ALSO



narrator.device/CloseDevice			  narrator.device/CloseDevice

   NAME
	CloseDevice - terminates access to the narrator device


   SYNOPSIS
	CloseDevice(IORequest)
		       A1

   FUNCTION
	Close invalidates the IO_UNIT and IO_DEVICE fields in the
	IORequest block, preventing subsequent IO until another
	OpenDevice.  CloseDevice also reduces the open count.  If
	the count goes to 0 and the expunge bit is set, the device
	is expunged.  If the open count goes to zero and the delayed
	expunge bit is not set, CloseDevice sets the expunge bit.


   INPUTS
	A valid IORequest block with its io_Message structure, and
	io_Device and io_Unit fields properly initialized.  These
	fields are initialized by OpenDevice.


   RESULTS
	CloseDevice invalidates the unit and device pointers in the
	IORequest block.


   SEE ALSO



narrator.device/CMD_FLUSH			narrator.device/CMD_FLUSH

   NAME
	CMD_FLUSH - Aborts all inprogress and queued requests


   SYNOPSIS
	Standard device command.


   FUNCTION
	Aborts all inprogress and queued speech requests.


   INPUTS
	Valid IORequest block with the io_Command field set to CMD_FLUSH.
	A valid IORequest block is one with its io_Message structure, and
	io_Device and io_Unit fields properly initialized.  The easiest
	way to insure proper initialization is to make a copy of the
	IORequest block after a successful OpenDevice call.


   RESULTS
	io_Error in IORequest block set to 0


   SEE ALSO
  	Exec input/output documentation.


narrator.device/CMD_Read			narrator.device/CMD_Read

   NAME
	CMD_READ - Query the narrator device for mouth shape or other
		   synchronization events.


   SYNOPSIS
	Standard device command.


   FUNCTION
	Currently, there are three events which the user can inquire
	about from the narrator device.  These are: mouth shape changes,
	start of word, and start of syllable.  Each read request returns
	information about any or all of these events as determined by
	the bits set in the sync field of the read IORequest block.  In
	the case of mouth shape changes, each shape returned is guaranteed
	to be different from the previously returned shape to allow
	updating to be done only when necessary.  Each read request is
	associated with a write request	by information contained in the
	IORequest block used to open the device.  Since the first field
	in the read IORequest block is a write IORequest structure, this
	association is easily made by copying the write IORequest block
	(after the OpenDevice call) into the voice field of the read
	IORequest block.  If there is no write in progress or in the
	device input queue with the same pseudo unit number as the read
	request, the read will be returned to the user with an error.  This
	is also how the user knows that the write request has finished and
	that s/he should not issue any more reads.  Note that in this case
	the mouth shapes may not be different from previously returned values.


   INPUTS
	mouth_rb IORequest block with the voice field (a narrator_rb
	structure) copied from the associated write request with the
	following fields modified:

	   io_Message - Pointer to message port for read request
	   io_Command - CMD_READ
	   io_Error   - Clear before issuing first read
	   width      - 0
	   height     - 0


   RESULTS
	As long as the speech is in progress, each read returns the
	following information in the mouth_rb IORequest block.

	If mouth shape changes are requested the following fields are
	modified:
	   width  - Contains mouth width value in arbitrary units
	   height - Contains mouth height value in arbitrary units
	   shape  - Compressed form of mouth shapes (internal use only)


	******	NEW FOR V37 NARRATOR

	If word synchronization is requested:
	   sync   - Bit NDB_WORDSYNC is set

	If syllable synchronization is requested:
	   sync   - Bit NDB_SYLSYNC is set

	Note that any or all of the above fields can be set and it is
	the user's responsibility to check for all possibilities.


   SEE ALSO
	CMD_WRITE
	Exec input/output documentation.


narrator.device/CMD_RESET			    narrator.device/CMD_RESET

   NAME
	CMD_RESET - Reset the device to a known state


   SYNOPSIS
	Standard device command.


   FUNCTION
	Resets the device as though it has just be initialized.
	Aborts all read/write requests whether active of enqueued.
	Restarts device if it has been stopped.


   INPUTS
	Valid IORequest block with the io_Command field set to CMD_RESET.
	A valid IORequest block is one with its io_Message structure, and
	io_Device and io_Unit fields properly initialized.  The easiest
	way to insure proper initialization is to make a copy of the
	IORequest block after a successful OpenDevice call.


   RESULTS


   SEE ALSO
	Exec input/output documentation.




narrator.device/CMD_START			    narrator.device/CMD_START


   NAME
	CMD_START - Restarts the device after a CMD_STOP command


   SYNOPSIS
	Standard device command.


   FUNCTION
	CMD_START restarts the currently active speech (if any)	and
	allows queued requests to start.


   INPUTS
	Valid IORequest block with the io_Command field set to CMD_START
	A valid IORequest block is one with its io_Message structure, and
	io_Device and io_Unit fields properly initialized.  The easiest
	way to insure proper initialization is to make a copy of the
	IORequest block after a successful OpenDevice call.


   RESULTS
	io_Error set to 0.


   SEE ALSO
	Exec input/output documentation.




narrator.device/CMD_STOP			    narrator.device/CMD_STOP

   NAME
	CMD_STOP  - Stops the device.


   SYNOPSIS
	Standard device command.


   FUNCTION
	CMD_STOP halts the currently active speech (if any) and	prevents
	any queued requests from starting.


   INPUTS
	Valid IORequest block with the io_Command field set to CMD_STOP.
	A valid IORequest block is one with its io_Message structure, and
	io_Device and io_Unit fields properly initialized.  The easiest
	way to insure proper initialization is to make a copy of the
	IORequest block after a successful OpenDevice call.


   RESULTS
	io_Error set to 0.


   SEE ALSO
	Exec input/output documentation.


narrator.device/CMD_WRITE			    narrator.device/CMD_WRITE

   NAME
	CMD_WRITE - Send speech request to the narrator device


   SYNOPSIS
	Standard device command.


   FUNCTION
	Sends a phonetic string to the narrator device to be spoken
	and, optionally, is used to direct the narrator device to
	return mouth shape changes, and word and syllable sync events
	in response to read requests from the user.  The phonetic string
	consists of ASCII characters representing the individual phonemes.
	Refer to the narrator device chapter of the libraries and devices
	volume of the ROM Kernel Manual for detailed information.


   INPUTS
	User IORequest block (struct narrator_rb as defined in .h file).
	The OpenDevice call will initialize the IORequest block to a
	"standard male" voice.  If you want to change any parms, do so
	after the OpenDevice call and before the DoIO (or SendIO/WaitIO).
	For a complete description of the narrator_rb structure, see the
	narrator.h or .i include file.  Note that the OpenDevice call does
	not initialize all the fields needed by the narrator device.  The
	IORequest fields which must be set by the user before issuing the
	write request are:

	   io_Command - Set to CMD_WRITE
	   io_Data    - Pointer to phonetic string
	   io_Length  - Length of phonetic string
	   ch_masks   - Array of audio channel selection masks (see audio
			device documentation for description of this field)
	   nm_masks   - Number of audio channel selection masks

	   ****** NEW FOR V37 NARRATOR

	   flags - The bit NDB_NEWIORB must be set in the flags field if
		   any of the new features of the V37 narrator are used


	In addition to producing synthetic speech, the narrator device
	also provides features for synchronizing the speech to animation
	or other user defined events.  There are three types of events
	that the user can request.  They are mouth shape changes, start of
	new word, and start of new syllable.  Mouth shape changes are
	requested by setting the mouths field of the IORequest block to a
	non-zero value.  Word and syllable sync events are requested by
	setting the NDB_WORDSYNC and/or NDB_SYLSYNC bits in the flags field
	of the IORequest block.  Note that word and syllable sync only work
	in V37 and later versions of the narrator device.


   RESULTS
	The narrator device range checks and performs other validity
	checks for all input parms.  If any input is in error, the device
	sets the io_Error field of the IORequest block to an appropriate
	value (see include files for error codes).  If everything is in
	order, the narrator device will produce the speech and clear the
	io_Error field.  The io_Actual field is set to the length of the
	input string that was actually processed.  If the return code
	indicates a phoneme error (ND_PhonErr), io_Actual is the NEGATIVE
	of the position in the input string where the error occured.


   SEE ALSO
	Read command.
	Audio device documentation.
	Exec input/output documentation.


narrator.device/OpenDevice			    narrator.device/OpenDevice

   NAME
	OpenDevice - opens the narrator device.


   SYNOPSIS
	error = OpenDevice("narrator.device",  unit, IORequest, flags);
	 D0                       A0            D0     A1         D1


   FUNCTION
	The OpenDevice routine grants access to the narrator device.
	OpenDevice checks the unit number, and if non-zero, returns an
	error (ND_UnitErr).  If this is the first time the driver has
	been opened, OpenDevice will attempt to open the audio device
	and allocate the driver's static buffers.  If either of these
	operations fail, an error is returned.  See the .h and .i
	include files for possible error return codes.  Next, OpenDevice
	(done for all opens, not just the first one) initializes various
	fields in the user's IORequest block (see below).  If users wish
	to use non-default values for these parms, the values must be set
	after the open is done.  OpenDevice also assigns a pseudo unit
	number to the IORB for use in synchronizing read and write requests.
	See the read command for more details.	Finally, OpenDevice stores
	the device node pointer in the IORequest block and clears the
	delayed expunge bit.

	***** NEW FOR V37 NARRATOR *****

	Several new fields in the IORequest block have been added for V37
	narrator.  These fields are initialized when the device is opened
	if the NDB_NEWIORB bit is set in the flags field of the user's
	IORequest block.  Note that NDB_NEWIORB is set in the IORequest
	block, NOT in the "flags" input parm to the OpenDevice call.


   INPUTS
	device     - "narrator.device"
	unit       - 0
	IORequest  - Pointer to the user's IORequest block
	flags	   - 0


   RESULTS
	The narrator device will initialize the IORequest block as follows
	(assume IORB points to the IOrequest block):

	IORB->rate = 150;		/* Speaking rate in words/minute */
	IORB->pitch = 110;		/* Baseline pitch in Hertz     	*/
	IORB->mode = NATURALF0;		/* Pitch (F0) mode		*/
	IORB->sex = MALE;		/* Sex of voice			*/
	IORB->volume = 64		/* Volume, full on		*/
	IORB->sampfreq = 22200		/* Audio sampling freq 		*/
	IORB->mouths = 0		/* Don't generate sync events	*/

	and if the NDB_NEWIORB bit is set:

	IORB->F0enthusiasm = 0		/* F0 excursion factor		*/
	IORB->F0perturb = 32		/* F0 perturbation (in 32nds)	*/
	IORB->F1adj = 0			/* F1 adjustment in ±5% steps	*/
	IORB->F2adj = 0 		/* F2 adjustment in ±5% steps	*/
	IORB->F3adj = 0			/* F3 adjustment in ±5% steps	*/
	IORB->A1adj = 0			/* A1 adjustment in decibels	*/
	IORB->A2adj = 0			/* A2 adjustment in decibels	*/
	IORB->A3adj = 0		 	/* A3 adjustment in decibels	*/
	IORB->articulate = 100		/* Transition time multiplier	*/
	IORB->centralize = 0		/* Degree of vowel centralization */
	IORB->centphon = ""		/* Pointer to central ASCII phon  */
	IORB->AVbias = 0		/* AV bias			*/
	IORB->AFbias = 0		/* AF bias			*/
	IORB->priority = 100		/* Priority while speaking	*/



   SEE ALSO
	The include files contain the complete IORequest block definition,
	    default settings, and error return codes.
	Exec input/output documentation.