Astra Blaster/Astra.cdr/voice/hearsay8.txt

Text File | 1992-04-08 | 20KB | 483 lines

                           PART II

                    HEARSAY PROGRAMMER'S GUIDE

                         INTRODUCTION

     Hearsay Gold  allows programmers  to call  speech functions  directly from
programs they write, without going through  the Hearsay menus.  These functions
can be called directly from assembly language or by  high level languages  with
register-access  capability such as "C".  For programmers  working in BASIC, an
assembly-language driver program is included on the Hearsay Gold diskette.  The
available functions are:

          - SPEAK A LINE OF TEXT
          - SET SCREEN ECHO PARAMETERS
          - SET SCREEN ECHO WINDOW
          - UNHOOK HEARSAY FROM DOS
          - LOAD DICTIONARY
          - GET VERSION NUMBER

     Examples are given in BASIC and Assembly Language.  For BASIC programmers,
sample code segments are provided, which when copied directly into your program
will call the Hearsay driver  program and exercise the  programmable functions.

          CALLING HEARSAY FUNCTIONS FROM BASIC

     To access Hearsay Gold  functions from BASIC programs,  a machine language
"Driver"  program  must  be  called  from  BASIC.  A  multiple  function driver
(HSGOLDDR.BAS) is supplied on the Hearsay Gold diskette.

     In order to use  the Hearsay functions,  your BASIC program  must load the
driver program into high memory,  and then "Call" the driver  for each function
required.

     To load the driver into high memory:

     1. When loading BASIC, reserve memory for the driver by using a /M switch.

     Type in: BASIC/M:65024 (BASICA/M:65024 if you use BASICA) then

     2. Include the  following lines  in your  program to  load the driver into
        memory:

          10 REM LOAD HEARSAY DRIVERS
          20 DEF SEG
          30 HSBASE=65024!               :REM This must be equal to the
          40                             :REM number used in the /M switch
          50 BLOAD "HSGOLDDR",HSBASE
          60
          70                             :REM INITIALIZE HEARSAY FUNCTIONS
          80 SAYSTR=HSBASE+256!          :REM Location of SAYSTR Driver
          90 BUFFER=HSBASE               :REM Location of SAYSTR Buffer
         100 SETSCRENCHO=HSBASE+272!     :REM Location of SETSCRENECHO
         110 SETWINDOW=HSBASE+321!       :REM Location of SET WINDOW
         120 UNHOOK=HSBASE+352!          :REM Location of UNHOOK HS
         130 LOADDICT=HSBASE+388!        :REM Location of LOAD DICTIONARY
         140 GET VERSION+HSBASE+411!     :REM Location of GET VERSION

     Once the driver is loaded, each Hearsay function  can be called by setting
the proper values & then calling the  desired function from the Hearsay driver.

     SPEAK A LINE OF TEXT

     The SAYSTR function speaks  a line (String) of text.  In the BASIC program
example given below,  this is a line of text  typed at the keyboard in response
to a  prompt,  but  it  could  have  been  hard  coded  into  the  program  (By
initializing A$ as the string to be spoken).

     PROGRAMMING IN BASIC

     The BASIC program segment below calls for the SAYSTR function.

          100 REM Input a line of text from the keybaord and speak it.
          110 SAYSTR=HSBASE+256!                  :REM Location of SAY driver
          120 BUFFER=HSBASE                       :REM Location of BUFFER
          130 INPUT A$                            :REM Get line from keyboard
          140 A$=A$+"."                           :REM Add period and space
          150 POKE BUFFER,LEN(A$)                 :REM Store length of line
          160 FOR N=1TOLEN(A$)                    :REM Store line in buffer
          170 POKE BUFFER+N,ASC(MID$(A$,N,1))
          180 NEXT N
          190 CALL SAYSTR                         :REM Speak line

     Lines 110-120 establish the parameters for the SAYSTR function.  Once that
has been done,  it is not necessary to  do it again each time a string is to be
spoken it remains available  to you until you  redfine it or leave the program.

     Lines 130-140 accept input keystrokes to define the string to be spoken, &
put a period & space at the end of it.  If you were hard coding the string into
your program you would replace these lines with a string defining A$, including
the period and space in the definition (ie. 130 A$="THIS IS A TEST.").

     Line 150 pokes the length of the string  into the beginning  of the buffer
and lines 160-180 poke the characters of the string into the buffer.  This must
done for each string you want Hearsay to speak.

     Once the string  has been defined  and poked into  the proper  location in
memory, line 190 calls the SAYSTR function which speaks the phrase.

          PROGRAMMING IN ASSEMBLER

     The SAYSTR function speaks the text string passed to it. The first byte of
the string must contain the  length of the string.  You must allocate 256 Bytes
for the string even if the length is less than 256 Bytes.

          USE

     1. First push a FAR pointer to string onto the stack.
     2. The call Hearsay Gold with a function code of  00h in the AL  register.
     3. Upon return, pull all parameters from the stack.

          SAY STRING EXAMPLE

     DATA            SEGMENT WORD PUBLIC 'DATA'

     String          EQU     $
                     DB      24d
                     DB      'I am the Hearsay Gold'
                     DB      13d

     DATA            ENDS

     CODE            SEGMENT BYTE PUBLIC 'CODE'
                     ASSUME CS:CODE,CS:DATA

     Say demo        PROCEDURE     NEAR

                     mov   ax,ds      ;Push far pointer to STRING
                     push  ax         ;onto the stack.
                     mov   ax,offset String
                     push  ax
                     mov   al,00h     ;Call the Hearsay Gold with
                     int   55h        ;a function code of 00h.
                     pop   ax         ;Pull parameters from stack.
                     pop   ax
                     ret
     Say demo        ENDP

     CODE            ENDS
                     END

          SET SCREEN ECHO PARAMETERS

     The SETSCRENECHO function set Screen Echo ON or OFF,  defines punctuation,
voice, pitch, and speed for both the Screen Echo and the Say String  functions.
If SETSCRNECHO is never called,  Hearsay will default to voice 1, pitch 6,  and
speed 7 for Say String functions.

          PROGRAMMING IN BASIC

     In the BASIC program sample given below, Screen Echo is set on & the other
parameters are set  to their default  values  (All parameters  must be included
when SETSCRNECHO is called,  even if they are to be set to the default values).

     100 SETSCRNECHO=HSBASE+272!     :REM Location of SETSCRNECHO
     110 ECHO%=1                     :REM Set ECHO on (0 would be off)
     120 PUNCT$=0                    :REM Don't speak punctuation
     130 LM%=0                       :REM Set Line Mode off
     140 VOICE%=1                    :REM Use voice 1
     150 PITCH%=6                    :REM Use pitch 6
     160 SPEED%=7                    :REM Speed 7
     170 CALL SETSCRENECHO
              (ECHO%,PUNCT%,LM%,VOICE%,PITCH%,SPEED%)
     180 REM Screen Echo is now set as indicated above

     Line 100  establishes  the  location  of  SETSCRENECHO,  the  Screen  Echo
function in the Hearsay driver. This line needs to  occur once in your program,
the location will be maintained until you leave the program.

     Lines 110-160 establish the  conditions to be implemented.  It's necessary
to enumerate all conditions every time you change any one.

     Line 170 calls  the SETSCRNECHO driver  and establishes the conditions you
described in lines 110-160.  This command will be included at any point in your
program where you want to change to Screen Echo settings.

          PROGRAMMING IN ASSEMBLER

     USE

     1. First push an integer  (1 to 9, 1 is slowest, 7 is default)  to specify
        speed.

     2. Next push an integer  (1 to 9,  1 is slowest, 6 is default)  to specify
        pitch.

     3. Then push an integer (1 or 2, 1 is lower and default) to specify voice.

     4. Next push an integer (1 or 0, 0 is off & default) to specify line mode.

     5. Then  push  an  integer  (1 or 0,  0 is off  and  default)  to  specify
        punctuation mode.

     6. Next push an integer  (1 or 0, 0 is off and default)  to specify screen
        echo.

     7. Now call Hearsay Gold with a function code of  01h in the AL  register.

     8. Upon return, pull all parameters from stack.

          SET SCREEN ECHO EXAMPLE

     CODE          SEGMENT BYTE PUBLIC 'CODE'
                   ASSUME CS:CODE

     Set echo      PROCEDURE        NEAR

                   push    bp       ;Save stack pointer
                   mov     bp,sp
                   mov     ax,7     ;Speed=7
                   push    ax
                   mov     ax,6     ;Pitch=6
                   push    ax
                   mov     ax,1     ;Voice=1
                   push    ax
                   mov     ax,0     ;Line mode off
                   push    ax
                   mov     ax,0     ;Punctuation mode off
                   push    ax
                   mov     ax,1     ;Screen echo on
                   push    ax
                   mov     al,01h   ;Call the Hearsay Gold with a
                   int     55h      ;function code of 01h
                   mov     sp,bp    ;Remove parameters from stack
                   pop     bp
                   ret
     Set echo      ENDP
     CODE          ENDS
                   END

          SET WINDOW

     The SETWINDOW function sets  Hearsay's Screen Echo window parameters.  The
function defines the top & bottom lines of the window,  and whether text inside
or outside of  it is to  be echoed.  Remember,  text will  only be  spoken when
Screen Echo is turned on.

          PROGRAMMING IN BASIC

     The BASIC program segment below calls the Set Window function.

     100 REM speak text from lines 10 to 15.
     110 SETWINDOW=HSBASE+321!:REM Location of SETWINDOW.
     120 MODE%=1:              REM Speak text inside window.
     130 TOP%=10:              REM From line 10 to 15
     140 BOTTOM%=15
     150 CALL SETWINDOW (MODE%,TOP%,BOTTOM%)

     Line 110 establishes the location of the SETWINDOW function.  This command
only needs to be executed once within your program.

     Lines 120-140 set window parameters  of inside or outside, top and bottom.

     Line 150 calls the SETWINDOW function and implements the parameters set in
lines 120-140. This line will  be used whenever it  is necessary  to change the
Hearsay window settings.

          PROGRAMMING IN ASSEMBLER

     USE

     1. First, push  an integer  (1 to 25, 25 is the bottom  row of the screen)
        specifying the bottom row of the window.

     2. Next push an integer (1 to 25, 1 is the top row) specifying the top row
        of the window.

     3. Then push an integer (0 or 1, 1 is inside) specifying the mode (Whether
        text inside or outside the window is to be spoken).

     4. Now call Hearsay Gold with a function of 2 in the AL register.

     5. Upon return pop all parameters from the stack.

          SET WINDOW EXAMPLE

     CODE     SEGMENT BYTE PUBLIC 'CODE'
              ASSUME CS:CODE

     WINDOW   PROCEDURE          NEAR
              mov     ax,20d     ;Only speak text printed from
              push    ax         ;Line 10 to line 20
              mov     ax,10d
              push    ax
              mov     ax,1       ;Set mode to speak inside window
              push    ax
              mov     al,02h     ;Call the HEARSAY GOLD with a
              int     55h        ;function code of 02h
              pop     ax         ;Pull parameters from stack
              pop     ax
              pop     ax
              ret
     WINDOW   ENDP
     CODE     ENDS
              END

          UNHOOK HEARSAY FROM DOS

     This command "Unloads" the Hearsay Gold program, removing all hooks to DOS
and returning all reserved memory to DOS.

     To rerun Hearsay after unhooking,  you must rerun the SpeechV2 or SPEECHV3
and Hearsay programs and redefine the Hearsay Key as you  normally do at setup.

          PROGRAMMING IN BASIC

     The BASIC program segment below shows the Unhook function in use.

     100 REM Unhook the HSGOLD from DOS
     110 UNHOOKHS=HSBASE+352!:        REM Location of UNHOOK HS.
     120 CALL UNHOOKHS:               REM Unhook HSGOLD from DOS.

     Line 110 established the location of the Unhook function (Only needs to be
done once) and line 120 calls the function.

          PROGRAMMING IN ASSEMBLER

     USE

     1. Issue a call to the Hearsay Gold  with a function  code of 3  in the AL
        register.

     2. No parameters are passed or returned.

     UNHOOK EXAMPLE

     CODE    SEGMENT BYTE PUBLIC 'CODE'
             ASSUME CS:CODE
     UNHOOK  HS   PROCEDURE     NEAR
             mov     al,03h  ;Call the Hearsay Gold with
             int     55h     ;a function code of 03h
             ret
     UNHOOK  HS   ENDP
     CODE    ENDS
             END

          LOAD DICTIONARY

     This command loads a dictionary file (Created with the Speech Editor) from
disk.

          PROGRAMMING IN BASIC

          An example of its use is given below:

     100 REM load dictionary file SAMPLE.
     110 LOADDICT=HSBASE+388!:          REM Location of Load Dictionary
     120 BUFFER=HSBASE:                 REM Location of buffer
     130 FILENAME$="SAMPLE":            REM Name of file to load
     140 FLAG%=0:                       REM Initialize ERROR
     150 POKE BUFFER,LEN(FILENAME$):    REM Store length of filename
     160 FORN=1TOLEN(FILENAME$):        REM Store filename in buffer
     170 POKE BUFFER+N,ASC(MID$(FILENAME$,N,1))
     180 NEXT N
     190 CALL LOADDICT(FLAG%):          REM Load the file
     200 IF FLAG%=0THEN220:             REM If error then print message
     210 PRINT "ERROR LOADING FILE"
     220 END

     Lines 110-120 establish the location of the LOADDICT function  (Only needs
to be done once), line 130 provides the filename of the dictionary file, & line
140 initializes the error flag.

     Lines 150-180 poke the filename into the buffer, & line 190 actually calls
the LOADDICT function which loads the specified dictionary in Hearsay's memory.

     The LOADDICT function  will check for  errors in loading  the file and set
the FLAG% variable if  any are encountered. Lines 200-210  check for errors and
print an  error message  on the  screen if  one is  encountered.  (In  your own
program, you may choose to  handle file loading  errors in some  other way, but
you will still test it by checking the value of FLAG%).

          PROGRAMMING IN ASSEMBLER

     The LOADDICT function is called with a FAR pointer  to the filename on the
stack.  The filename can be  any legal DOS filename without the file extension,
which Hearsay Gold will add automatically.

     If the file is to be loaded from other than the current drive & directory,
an optional path name must be included with the filename.

     If the file loads OK, 0 will be returned in the AX register.  If there was
an error in loading  the file, a non-zero  value will be  returned. Use the DOS
function call 59h (GET EXTENDED ERROR) to get further information on the error.

     USE

     1. Push a FAR pointer to the filename onto the stack.

     2. Call Hearsay Gold with the function code 05h in the AL register.

     3. Upon return, pull all parameters from the stack.

     LOAD DICTIONARY EXAMPLE

     DATA          SEGMENT WORD PUBLIC 'DATA'

     filename      EQU   $
                   DB    10d          ;Length of filename
                   DB    C:\HS\DEMO   ;Filename with drive C and directory HS

     DATA          ENDS
     CODE          SEGMENT BYTE PUBLIC 'CODE'
                   ASSUME CS:CODE,DS:DATA

     Load dict     PROCEDURE NEAR
                   push   bp          ;Save stack pointer
                   mov    bp,sp
                   mov    ax,ds       ;Push far pointer to filename
                   push   ax
                   mov    ax,offset filename
                   push   ax
                   mov    al,05h      ;Call the Hearsay Gold with a
                   int    55h         ;function code of 05h
                   mov    sp,bp       ;Remove filename from stack
                   pop    bp
                   cmp    pax,0       ;Error?
                   je     Done        ;no,exit
                   mov    bx,0h       ;DOS version #
                   mov    ah,59h      ;Get extended error information
                   int    21h         ;Process error
     Done:
                   ret
     Load dict     ENDP
     CODE          ENDS
                   END

          GET VERSION NUMBER

     This command  extracts the  version of  Hearsay Gold currently being used.
This permits software  developers to check version  number and version level as
part of  their program. Hearsay is committed  to upward compatibility,  so that
any program written for the Hearsay  Gold will run on any later version. If you
are developing  programs to  use Hearsay, check  that the version  number is no
lower than the one you used for development.

     The Version ID codes for Hearsay Gold versions 2 and 3 are 0300h and 0400h
respectively. The first two digits indicate the product code,  and the last two
indicate the release number of that product. Release 2 of Version 2 will have a
Version ID of 0301h or 769 decimal.

          PROGRAMMING IN BASIC

     The program segment below shows the function in use.

     100 REM Display the HSGOLD version number.
     110 HSVERSION=HSBASE+411!:           REM Location of GET VERSION
     120 VERSION%=0:                      REM Initialize number.
     130 CALL HSVERSION (VERSION%):       REM Get version number.
     140 IF VERSION%=768 THEN PRINT "VERSION 2"
     150 IF VERSION%=1024 THEN PRINT "VERSION 3"

     Line 110 locates the GET VERSION function (Only needs to be done once) and
line 120 initializes VERSION to 0.

     Line 130  actually  calls the  GET VERSION  function,  returning a version
number of 768 if Version 2 is loaded or 1024 if Version 3 is loaded. Lines 140-
150 test  to see which  version is loaded,  in the  example given  printing the
version number.

          PROGRAMMING IN ASSEMBLER

     The product  code is  returned in  register AH  and the  release number is
returned in register AL.

     USE

     1. Call Hearsay Gold with function code 06h in the AL register.

     2. The Version ID will be returned in register AX.

          GET VERSION EXAMPLE

     CODE          SEGMENT BYTE PUBLIC 'CODE'
                   ASSUME CS:CODE

     Get version   PROCEDURE NEAR
                   mov     al,06h    ;Call the Hearsay Gold with a
                   int 55h           ; function code of 06h
                   ret
     Get version   ENDP
     CODE          ENDS
                   END