This is the old SWI interface for Speak V2
==========================================

Changes for V3 are indicated.



SWI Interfaces to the Speak Module.

The officially allocated SWI block number is  &4ad80.



SWI &4ad80    Speak_Ready
     Entry:   none
     
     Exit:    R0   0 if still speaking,  -1 if not speaking.
     
              R1   Index into the character string of the 'Say'
                   call which is currently speaking.  The
                   index points to the start of the word which
                   is currently being spoken.
                   
     Can be used to wait until the speak module has finished speaking,
     and to identify which word is currently being spoken.

    
     
     
SWI &4ad82    Speak_Misc     (Miscellaneous Functions)
     Entry:   R0   function
     
     
     R0=1  Register user.
     (Obsolete.  Has no effect.)
        
     R0=2  Deregister user.
     (Obsolete.  Has no effect.)
        
     R0=3  Translate to phoneme string.
        R1 String of a single English word.  This is translated into
           an ascii character string of the phonemes, which is returned, 
           pointed to by R0 and terminated by a zero byte.

        R2 0=ascii phonemes, 1=ipa phonemes (as UTF-8).
        
        Returns:
        R0 The phoneme string.
     
     R0=5  Read Voice names.
        Returns
           R0 = pointer to an array of strings, giving the
           available Voice names.  The list is terminated by a 
           NULL pointer.
           
           R1 = pointer to an array of strings, giving the
           available Voice Variant names. The list is terminated
           by a NULL pointer.
     



SWI &4ad83    Speak_Say
     Entry:   R0   Pointer to English text string to be spoken.  String
                   must be terminated by 0 byte or CR (&D byte), unless
                   the length is indicated by R1.
                   
                   When speaking passages of text, this SWI should not
                   be called for each individual word, but rather for
                   sentences.  This allows the Speak module to apply an
                   intonation pattern to the whole clause.
                   
                   The Speak module has to copy the text into an
                   internal buffer before speaking it.  This limits the
                   length the text string to 1000 characters.
                   
                   This SWI will return immediately, before the text
                   has been spoken.  Use SWI &4ad80 in a pooling loop to
                   determine when the speaking has finished.
                                      
              R1   If = 0, the end of the text string is indicated by
                   a terminator, as described for R0 above.
                   
                   If > 0, R1 specifies the length of the text string, in
                   which case it does not need a terminator.  A zero
                   byte within the string will still act as a
                   terminator,  CR will not.

              R2   -1 to indicate no voice change.
                   Use SWI &4ad8e Speak_SetVoice to set the voice.
              
                   or (deprecated)
                   Voice Number (from Speak_Misc 5 above)
              
              R3   Must be zero (may be used in future versions) 
                  
     Exit:    none
     
     
SWI &4ad84    Speak_SayW
     As SWI 3 (Say), but it does not return until the module has
     finished speaking the string.
(V3: currently the same as Speak_Say)


SWI &4ad85    Speak_Stop
     Stops speaking any "Say" calls which have been sent to the
     Speak module.
     

(The following SWIs can be used to set new values of the
 parameters which control the sound of the speech.)

SWI &4ad87    Speak_Pitch
     R0   Gives the new value of the 'pitch' parameter.
          Default value is 128.

SWI &4ad88    Speak_Speed
     R0   Gives the new value of the 'speed' parameter.
          Default value is 128.
    
SWI &4ad89    Speak_WordGap
     R0   Gives the new value of the 'word gap' parameter.
          0 = no extra gap between words.
          1 = ensure a short gap between each spoken word.
          2 or greater,  larger gap between words in multiples
              of approx 50mS.
          
          128 is treated the same as value 0.
          
SWI &4ad8a   Speak_PitchRange
     R0   Gives the new value of the 'pitch range' parameter.
          Default value is 128.
     
SWI &4ad8d   Speak_Volume
     R0   Gives the new volume (amplitude), range 0-255
     
SWI &4ad8e   Speak_SetVoice
     R0   Pointer to voice name (eg. "en-us" for the US English voice).
          Use + to add a voice variant (eg. "en-us+f3" use the "f3" female voice).

     R1   0
     R2   0
