Home	Cars	Cats	Computers	Lightwave	Music	Software	Steel

VoiceCon 0.08 API

This is a very brief introduction to the VoiceCon API calls.

WIMP Messages

Message_VoiceConSendText - 0x51540

+16=0x51540
+20=Task handle of last recipient (ignore)
+24...=current sentance string (zero-terminated)

This is sent from the VoiceCon application to the other tasks (starting with the task which owns the caret, and then broadcast to all tasks) to indicate what the current sentance is. If your application does not understand the sentance, it should not reply to this message.

Message_VoiceConWantMore - 0x51541

This is used to acknowledge the Message_VoiceConSendText (0x51540) to say that your application understands the sentance, but it needs more in order to complete.

Message_VoiceConFinishedSentance - 0x51542

This is used to acknowledge the Message_VoiceConSendText (0x51540) to say that your application understands the sentance, and the sentance has finished.

Message_VoiceConNewPhrase - 0x51543

+16=0x51543
+20...=phrase to learn (ctrl-terminated)

This is broadcast by your application to tell VoiceCon to learn a new word or phrase. It is used by the helper when an application or a file is dragged on to the helper's window, so that the user may speak the application's (or file's) name.

Message_VoiceConProfile - 0x51544

+16=0x51545
+20...=Profile name (zero-terminated)

This is broadcast by VoiceCon to indicate that the profile has changed. It is really of importance for the helper, but it is broadcast anyway.

Using the API

VoiceCon compliant applications (VCCAs) can be very simple. To understand individual words, VCCAs need only respond to Message_VoiceConSendText (0x51540) with Message_VoiceConFinishedSentance (0x51542). However, to allow more complex sentance construction, VCCAs can use longer phrases.
It is essential that VCCAs are "stateless" in that they do not store anything about the sentance between WIMP polls. VoiceCon will send the whole sentance each time a new phrase/word is added to it.
For example, with the VoiceCon helper application, if the user says "Load application Paint", the API sequence will be :

User	Says "Load"	Stage 1
VoiceCon	Message_VoiceConSendText with "Load"
Helper	Message_VoiceConWantMore

User	Says "Application"	Stage 2
VoiceCon	Message_VoiceConSendText with "Load Application"
Helper	Message_VoiceConWantMore

User	Says "Paint"	Stage 3
VoiceCon	Message_VoiceConSendText with "Load Application Paint"
Helper	Message_VoiceConFinishedSentance
Helper	Runs !Paint

Although the VoiceCon helper is written in C, here is a BASIC fragment that performs the checks:

DEFPROCvoiceconsendtext(sentance$)
  IFsentance$="Load" THEN PROCacknowledge(&51541):ENDPROC
  IFsentance$="Load Application" THEN PROCacknowledge(&51541):ENDPROC
  IFLEFT$(sentance$,17)="Load Application " THEN
    PROCacknowledge(&51542)
    app$=MID$(sentance$,17)
    PROCloadapplication(app$)
  ENDIF
ENDPROC

Learning new words/phrases

VoiceCon can be asked to learn new words or phrases. To do this, use Message_VoiceConNewPhrase (0x51543). If VoiceCon already understands this phrase, it will not ask the user for it again; it will use the previous definition of it. Note that this will cause problems with the word "record" (as "Please record this for me" and "It's a new world record" have different pronounciations of "record").

For example, the following pseudo-BASIC fragment will ask VoiceCon to record a word:

DEFPROCvoiceconnewphrase(phrase$)
!wimpblock%=(24+LEN(phrase$))AND&FC
wimpblock%!4=0
wimpblock%!8=0
wimpblock%!12=0
wimpblock%!16=&51543
$(wimpblock%+20)=phrase$
SYS"Wimp_SendMessage",17,wimpblock%,0,0
ENDPROC

Note that you do not get any acknowledgement from VoiceCon.