@database "narrator"
@master "Work:RKM/Includes&Autodocs/doc/narrator.doc"

@Node Main "narrator.doc"
@toc "2.0Includes_Autodocs/Autodocs"

@{" AbortIO() " Link "AbortIO()"}       @{" CMD_READ " Link "CMD_READ"}     @{" CMD_STOP " Link "CMD_STOP"}
@{" OpenDevice() " Link "OpenDevice()"}    @{" CMD_RESET " Link "CMD_RESET"}    @{" CMD_WRITE " Link "CMD_WRITE"}
@{" CMD_FLUSH " Link "CMD_FLUSH"}       @{" CMD_START " Link "CMD_START"}    @{" CloseDevice() " Link "CloseDevice()"}

@EndNode

@Node "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" Link "ADCD_v1.2:Inc&AD2.0/Includes/exec/io.h/Main" 19} may be in the queue or currently active.  If
    currently active, the request is immediately stopped and then
    removed.

INPUTS
    Pointer to the @{"IORequest" Link "ADCD_v1.2:Inc&AD2.0/Includes/exec/io.h/Main" 19} block to be aborted.

RESULTS
    io_Error field in the @{"IORequest" Link "ADCD_v1.2:Inc&AD2.0/Includes/exec/io.h/Main" 19} block set to #IOERR_ABORTED.

SEE ALSO

@EndNode

@Node "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" Link "ADCD_v1.2:Inc&AD2.0/Includes/exec/io.h/Main" 19} block, preventing subsequent IO until another
    @{"OpenDevice" Link "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" Link "ADCD_v1.2:Inc&AD2.0/Includes/exec/io.h/Main" 19} block with its io_Message structure, and
    io_Device and io_Unit fields properly initialized.  These
    fields are initialized by @{"OpenDevice" Link "OpenDevice()"}.

RESULTS
    CloseDevice invalidates the unit and device pointers in the
    @{"IORequest" Link "ADCD_v1.2:Inc&AD2.0/Includes/exec/io.h/Main" 19} block.

SEE ALSO

@EndNode

@Node "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" Link "ADCD_v1.2:Inc&AD2.0/Includes/exec/io.h/Main" 19} block with the io_Command field set to CMD_FLUSH.
    A valid @{"IORequest" Link "ADCD_v1.2:Inc&AD2.0/Includes/exec/io.h/Main" 19} 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" Link "ADCD_v1.2:Inc&AD2.0/Includes/exec/io.h/Main" 19} block after a successful @{"OpenDevice" Link "OpenDevice()"} call.

RESULTS
    io_Error in @{"IORequest" Link "ADCD_v1.2:Inc&AD2.0/Includes/exec/io.h/Main" 19} block set to 0

SEE ALSO
    Exec input/output documentation.

@EndNode

@Node "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" Link "ADCD_v1.2:Inc&AD2.0/Includes/exec/io.h/Main" 19} 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" Link "ADCD_v1.2:Inc&AD2.0/Includes/exec/io.h/Main" 19} block used to open the device.  Since the first field
    in the read @{"IORequest" Link "ADCD_v1.2:Inc&AD2.0/Includes/exec/io.h/Main" 19} block is a write @{"IORequest" Link "ADCD_v1.2:Inc&AD2.0/Includes/exec/io.h/Main" 19} structure, this
    association is easily made by copying the write @{"IORequest" Link "ADCD_v1.2:Inc&AD2.0/Includes/exec/io.h/Main" 19} block
    (after the @{"OpenDevice" Link "OpenDevice()"} call) into the voice field of the read
    @{"IORequest" Link "ADCD_v1.2:Inc&AD2.0/Includes/exec/io.h/Main" 19} 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" Link "ADCD_v1.2:Inc&AD2.0/Includes/devices/narrator.h/Main" 130} @{"IORequest" Link "ADCD_v1.2:Inc&AD2.0/Includes/exec/io.h/Main" 19} block with the voice field (a @{"narrator_rb" Link "ADCD_v1.2:Inc&AD2.0/Includes/devices/narrator.h/Main" 95}
    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" Link "ADCD_v1.2:Inc&AD2.0/Includes/devices/narrator.h/Main" 130} @{"IORequest" Link "ADCD_v1.2:Inc&AD2.0/Includes/exec/io.h/Main" 19} 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" Link "CMD_WRITE"}
    Exec input/output documentation.

@EndNode

@Node "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" Link "ADCD_v1.2:Inc&AD2.0/Includes/exec/io.h/Main" 19} block with the io_Command field set to CMD_RESET.
    A valid @{"IORequest" Link "ADCD_v1.2:Inc&AD2.0/Includes/exec/io.h/Main" 19} 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" Link "ADCD_v1.2:Inc&AD2.0/Includes/exec/io.h/Main" 19} block after a successful @{"OpenDevice" Link "OpenDevice()"} call.

RESULTS

SEE ALSO
    Exec input/output documentation.

@EndNode

@Node "CMD_START" "narrator.device/CMD_START"

NAME
    CMD_START - Restarts the device after a @{"CMD_STOP" Link "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" Link "ADCD_v1.2:Inc&AD2.0/Includes/exec/io.h/Main" 19} block with the io_Command field set to CMD_START
    A valid @{"IORequest" Link "ADCD_v1.2:Inc&AD2.0/Includes/exec/io.h/Main" 19} 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" Link "ADCD_v1.2:Inc&AD2.0/Includes/exec/io.h/Main" 19} block after a successful @{"OpenDevice" Link "OpenDevice()"} call.

RESULTS
    io_Error set to 0.

SEE ALSO
    Exec input/output documentation.

@EndNode

@Node "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" Link "ADCD_v1.2:Inc&AD2.0/Includes/exec/io.h/Main" 19} block with the io_Command field set to CMD_STOP.
    A valid @{"IORequest" Link "ADCD_v1.2:Inc&AD2.0/Includes/exec/io.h/Main" 19} 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" Link "ADCD_v1.2:Inc&AD2.0/Includes/exec/io.h/Main" 19} block after a successful @{"OpenDevice" Link "OpenDevice()"} call.

RESULTS
    io_Error set to 0.

SEE ALSO
    Exec input/output documentation.

@EndNode

@Node "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" Link "ADCD_v1.2:Inc&AD2.0/Includes/exec/io.h/Main" 19} block (struct @{"narrator_rb" Link "ADCD_v1.2:Inc&AD2.0/Includes/devices/narrator.h/Main" 95} as defined in .h file).
    The @{"OpenDevice" Link "OpenDevice()"} call will initialize the @{"IORequest" Link "ADCD_v1.2:Inc&AD2.0/Includes/exec/io.h/Main" 19} block to a
    "standard male" voice.  If you want to change any parms, do so
    after the @{"OpenDevice" Link "OpenDevice()"} call and before the @{"DoIO" Link "exec/DoIO()"} (or SendIO/WaitIO).
    For a complete description of the @{"narrator_rb" Link "ADCD_v1.2:Inc&AD2.0/Includes/devices/narrator.h/Main" 95} structure, see the
    narrator.h or .i include file.  Note that the @{"OpenDevice" Link "OpenDevice()"} call does
    not initialize all the fields needed by the narrator device.  The
    @{"IORequest" Link "ADCD_v1.2:Inc&AD2.0/Includes/exec/io.h/Main" 19} 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" Link "ADCD_v1.2:Inc&AD2.0/Includes/exec/io.h/Main" 19} 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" Link "ADCD_v1.2:Inc&AD2.0/Includes/exec/io.h/Main" 19} 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" Link "ADCD_v1.2:Inc&AD2.0/Includes/exec/io.h/Main" 19} 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.

@EndNode

@Node "OpenDevice()" "narrator.device/OpenDevice"

NAME
    OpenDevice - opens the narrator device.

SYNOPSIS
    error = OpenDevice("narrator.device",  unit, @{"IORequest" Link "ADCD_v1.2:Inc&AD2.0/Includes/exec/io.h/Main" 19}, 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" Link "ADCD_v1.2:Inc&AD2.0/Includes/exec/io.h/Main" 19} 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" Link "ADCD_v1.2:Inc&AD2.0/Includes/exec/io.h/Main" 19} block and clears the
    delayed expunge bit.

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

    Several new fields in the @{"IORequest" Link "ADCD_v1.2:Inc&AD2.0/Includes/exec/io.h/Main" 19} 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" Link "ADCD_v1.2:Inc&AD2.0/Includes/exec/io.h/Main" 19} block.  Note that NDB_NEWIORB is set in the @{"IORequest" Link "ADCD_v1.2:Inc&AD2.0/Includes/exec/io.h/Main" 19}
    block, NOT in the "flags" input parm to the OpenDevice call.

INPUTS
    device     - "narrator.device"
    unit       - 0
    @{"IORequest" Link "ADCD_v1.2:Inc&AD2.0/Includes/exec/io.h/Main" 19}  - Pointer to the user's @{"IORequest" Link "ADCD_v1.2:Inc&AD2.0/Includes/exec/io.h/Main" 19} block
    flags      - 0

RESULTS
    The narrator device will initialize the @{"IORequest" Link "ADCD_v1.2:Inc&AD2.0/Includes/exec/io.h/Main" 19} 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" Link "ADCD_v1.2:Inc&AD2.0/Includes/exec/io.h/Main" 19} block definition,
        default settings, and error return codes.
    Exec input/output documentation.

@EndNode

