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 sentence 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 sentence is. If your application does not understand the sentence, 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 sentence, but it needs more in order to complete.

Message_VoiceConFinishedSentence - 0x51542

This is used to acknowledge the Message_VoiceConSendText (0x51540) to say that your application understands the sentence, and the sentence 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_VoiceConFinishedSentence (0x51542). However, to allow more complex sentence construction, VCCAs can use longer phrases.

It is essential that VCCAs are "stateless" in that they do not store anything about the sentence between WIMP polls. VoiceCon will send the whole sentence 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_VoiceConFinishedSentence Helper Runs !Paint

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

DEFPROCvoiceconsendtext(sentence$)
  IFsentence$="Load" THEN PROCacknowledge(&51541):ENDPROC
  IFsentence$="Load Application" THEN PROCacknowledge(&51541):ENDPROC
  IFLEFT$(sentence$,17)="Load Application " THEN
    PROCacknowledge(&51542)
    app$=MID$(sentence$,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.