VOICECOM  STC-S169

Software Developer Kit
Language Independent Voice Commands Recognition


USER'S GUIDE

Speech Technology Center
St. Petersburg
Russia
2000

VoiceCom SDK - User's Guide


Copyright

Copyright  1999, 2000 by Speech Technology Center Limited (STC Ltd.).
All rights reserved. VoiceCom SDK in a part or as a whole may be used
according to the corresponding license.
To receive more copies or other information, please contact STC.

Disclaimer
Speech Technology Center accepts no liability whatsoever for any loss
or injury incurred by the owner or by any third party while using this
VoiceCom SDK and specifically disclaims any warranties, merchantability
or fitness for any particular purpose.  The contents of the VoiceCom
SDK and User's Guide are subject to change without notice.

-------------------------------------------------------------------------------

CONTENTS

INTRODUCTION
OVERVIEW
HARDWARE REQUIREMENTS
MICROPHONE REQUIREMENTS
ALGORITHM DESCRIPTION
CREATION OF A TEMPLATES DATABASE.
RECOGNITION OF A VOICE COMMAND.
CD DESCRIPTION
FUNCTIONS DESCRIPTION
STREAM RAW DATA PROCESSING FUNCTIONS (PCM16, 11025 HZ, MONO)
WAVE FILE PROCESSING FUNCTIONS (PCM16, 11025 HZ, MONO)
EXTERNAL BUFFER RAW DATA PROCESSING FUNCTIONS (PCM16, 11025 HZ, MONO)
TEMPLATES PREPARATION AND COMPARISON FUNCTIONS
ERROR CODES
DEMO SOFTWARE
SUPPORT

----------------------------------------------

INTRODUCTION

Overview

VoiceCom is based on easy-to-use language independent voice commands
recognition technology.

SDK is developed using Microsoft Visual C++ 6.0 (an official trademark
of Microsoft Corp.). SDK for other OS and ANSI C source code are available
by special order. The library allows you to embed voice control feature
in your software.

VoiceCom SDK set includes
1) DLL for MS Windows 95/98/2000/NT;
2) user's manual;
3) sample demo software in Visual C++ source.

VoiceCom library features:
 enables the User to embed easily voice commands recognition into User's
  application;
 provides reliable recognition up to 2000 commands, in one application
  200-300 commands are usually enough;
 recognizes speech commands in any language;
 training session for a new speaker is short and one-time, there is an option
  for recognition improvement;
 can work in speaker independent mode after training more than 7 speakers;
 is noise robust, shows good recognition in noisy environment;
 consumes low resources.

Hardware requirements

The following minimum is required for standard functioning of SDK:

 IBM compatible 486DX/66 or higher PC;
 8 Mb RAM
 Hard disk
 Standard sound card, Sound Blaster 16 compatible
 Windows 95/97
 Microphone

Microphone requirements

A microphone used for work with SDK should be of good quality that is to
have broad frequency band width (50-10000 Hz or higher) and sensitivity
+ 6dB/  -6dB in the working band. In other case commands recognition could
be incorrect. It is better to use electret microphones, which provide
higher output signal level and are less sensitive to interferences.
Dynamic microphones should have metallic cover. Some dynamic microphones can
not provide an adequate sound level when used with certain types of sound
cards. You can use desktop, head or attached to clothes microphones.
Microphones mounted on monitors of computers should be used with care,
since some monitors generate significant amount of acoustic and electromagnetic
noise.

The greatest accuracy is achieved when microphone headsets are used, as they
support constant and optimum distance between mouth and microphone, irrespective
of head movements.

If a desktop microphone is used, the best result is reached when the distance
from mouth to the microphone is approximately 30 cm.

The microphone should be correctly connected to an input jack of a sound card.
Do not confuse an input microphone with linear input. Please, check input
signal level when the microphone is connected. If the signal level is too low,
it is necessary to increase microphone gain of your sound card. The adjustment
should be made with care, since the setting of too high gain level will deform
an input signal, that will have a negative effect on recognition.

It is necessary to remember that when a microphone or the level of loudness is
changed, templates of commands should be re-written.

------------------------------------------------------------------------------

ALGORITHM DESCRIPTION

VoiceCom compares an unknown utterance with all templates from speech database
so as to determine which word was pronounced. So the algorithm of voice
commands recognition can be divided in to two stages. The first one is the
preparation of a database of templates. A template means a stored in the
program pronunciation (utterance) of a voice command which serves as a sample
for recognition of that command. The second stage is to decide to what template
belongs a new unknown utterance.

Creation of a templates database.
Before starting the process of recognition, it is necessary to create a
templates database. A word or a short phrase can be used as a template for
one voice command.

Step 1: separating a word from the input signal. For this purpose the following
functions are used: VOICECOM_START, VOICECOM_START_READ_DATA,
VOICECOM_CONTINUE_READ_DATA or VOICECOM_START_READ_FILE,
VOICECOM_CONTINUE_READ_FILE depending on a source of input of speech signal.

Step 2: Storing the separated word. For this purpose the function
VOICECOM_SAVE_TEMPLATE () is used.

Step 3: Placing the template in to the user's database is carried out with
the help of functions VOICECOM_GET_TEMPLATE_LENGTH and VOICECOM_GET_TEMPLATE.

Recognition of a voice command.
-------------------------------

In order to determine to which template an unknown utterance belong, it is
necessary to compare this utterance with all templates of the database.

Step 1: the unknown utterance is inputted and saved, with the help of the
same functions, which were used for separating and storing templates.

Step 2: the unknown utterance is compared to all templates of the database
with the help of function VOICECOM_GET_DISTANCE, which returns a value of the
distance from an unknown utterance to the template.

Step 3: the nearest template is chosen that is the template, distance to which
is minimal.

Step 4: the received minimal distance is compared to the threshold (an average
value is 150). If the distance is less than the threshold, it is considered
that the command was uttered to which the nearest template belongs. If the
distance exceeds the threshold, the uttered word doesn't belong to the database.

There is an example in the demonstration program VoiceCom Demo (file
Voicedlg.cpp).

Input data sample is to be no longer than 2.5 sec. The size of one template
for one voice command of one speaker is equal to about 1500 bytes.

------------------------------------------------------------------------------

FUNCTIONS DESCRIPTION

Stream raw data processing functions (PCM16, 11025 Hz, mono)
It processes a live sound from standard sound card.

---------- VOICECOM_IS_BLASTER_PRESENT

Checks if a sound card is present.

        DllExport extern "C" BOOL VOICECOM_IS_BLASTER_PRESENT();

Return Values
        Returns "True" if the sound card is OK, is present and supports
        PCM 16 mono at 11025 Hz

---------- VOICECOM_START

Initializes the recognition. Starts sound data recognition which has been
received from the sound card. Thread will PostMessage with message_id to
notify_window, mParam will contain notification code (see List of notification
codes). Use the VOICECOM_SAVE_TEMPLATE for template saving.

        DllExport extern "C" LONG VOICECOM_START(
                        HWND hWnd,          //notify_window,
                        UINT Msg,           //message_id
        );

Parameters
        hWnd    Identifies the window which window procedure is to receive the
                message.
        Msg     Specifies the message to be posted.

Return Values
        Returns error code, see the List of error codes.

---------- VOICECOM_STOP

. Stops data recognition being received from Sound Card
. Closes recognition

        DllExport extern "C" LONG VOICECOM_STOP();


Wave file processing functions (PCM16, 11025 Hz, mono)
------------------------------------------------------

---------- VOICECOM_START_READ_FILE

 Initializes recognition
 Scans data in WAVE file for the word's boundaries.
 Use VOICECOM_SAVE_TEMPLATE as for Sound Card

        DllExport extern "C" SHORT VOICECOM_START_READ_FILE(
                CHAR* File_name          //file name
        );

Parameters
        File_name       Name of the scanned WAVE file.

Return Values
        Returns error code or 0 if a word is detected

---------- VOICECOM_CONTINUE_READ_FILE

 Continues scanning of data in  WAVE file.
 Use VOICECOM_SAVE_TEMPLATE as for Sound Card

        DllExport extern "C" SHORT VOICECOM_CONTINUE_READ_FILE();

Return Values
        Returns error code or 0 if a word is detected

---------- VOICECOM_STOP_READ_FILE

 Closes WAVE file
 Closes recognition

        DllExport extern "C" SHORT VOICECOM_STOP_READ_FILE();

Return Values
        Returns error code or 0 if Ok.

External buffer raw data processing functions (PCM16, 11025 Hz, mono)
---------------------------------------------------------------------

---------- VOICECOM_START_READ_DATA

 Initializes recognition
 Scans data in Buffer for the word's boundaries.
 Use VOICECOM_SAVE_TEMPLATE as for Sound Card

        DllExport extern "C" SHORT VOICECOM_START_READ_DATA(
                CHAR* Buffer,         //buffer for word
                INT Length            //length of  buffer
        );

Parameters
        Buffer  Points that the external buffer is buffer for scanned word.
        Length  The length of External buffer. It can't be >512

Return Values
        Returns error code or 0 if a word is detected

---------- VOICECOM_CONTINUE_READ_DATA

Continues the scanning of data in Buffer for the word's boundaries

        DllExport extern "C" SHORT VOICECOM_CONTINUE_READ_DATA(
                CHAR* Buffer,         //buffer for word
                INT Length            //length of  buffer
        );

Parameters

        Buffer  The pointer to external buffer that it is buffer for scanned
                word.
        Length  The length of the external buffer.

Return Values
        Returns error code or 0 if a word is detected

---------- VOICECOM_STOP_READ_DATA

Closes recognition.

        DllExport extern "C" SHORT VOICECOM_STOP_READ_DATA();

Templates preparation and comparison functions
----------------------------------------------

---------- VOICECOM_SAVE_TEMPLATE

Makes copy of the last word in the internal cache. It is necessary to use
it for the saved template after the function CONTINUE_READ_FILE,
CONTINUE_READ_DATA or the message about a word detected function VOICECOM_START.

        DllExport extern "C" SHORT VOICECOM_SAVE_TEMPLATE();

---------- VOICECOM_GET_TEMPLATE_LENGTH

Gets length of a template from the internal cache in bytes. It is necessary
to use for saved template in user buffer.

        DllExport extern "C" SHORT VOICECOM_GET_TEMPLATE_LENGTH();

---------- VOICECOM_GET_TEMPLATE

Gets a template from the internal cache in user buffer. It is necessary to use
for the saved template in user buffer.

        DllExport extern "C" SHORT VOICECOM_GET_TEMPLATE(
                CHAR* Buffer,                //user buffer
                INT Length                   //length of word
        );

Parameters
        Buffer  The pointer to user buffer saved word templates.
        Length  The length of a word is returned by the function
                        VOICECOM_GET_TEMPLATE_LENGTH.

---------- VOICECOM_GET_DISTANCE, VOICECOM_GET_DISTANCE2

 Returns the distance from an unknown word to a template word, if the error
        returns 31000
 Input data sample is to be no longer than 2.5 sec.
 The size of one template for one voice command of one speaker is equal to
        about 1500 bytes.
 VOICECOM_GET_DISTANCE2 the same as VOICECOM_GET_DISTANCE but uses another
        algorithm of calculation


        DllExport extern "C" SHORT VOICECOM_GET_DISTANCE(
                CHAR* Template_1,      // buffer with templates of one word
                INT Length_1,          // length of one word
                CHAR* Template_2,      // buffer with template of another word
                INT Length_2           // length of another word
        );

Parameters
        Template_1      pointer to a buffer with templates of one word.
        Length_1        length of one word.
        Template_2      pointer to a buffer with templates of another word.
        Length_2        length of another word.

Return Values
        Returns the distance from an unknown word to a template word,
        if error it returns 31000

---------- VOICECOM_GET_LEVEL();

Queries the input signal level on Sound Card to display input level

        DllExport extern "C" INT VOICECOM_GET_LEVEL();

---------- VOICECOM_FLAG_WORD();

True if start of the word is detected. May not result in notification if not a word has occurred.

        DllExport extern "C" BOOL VOICECOM_FLAG_WORD();

---------- VOICECOM_GET_TEMPLATE_SOUND_LENGTH();

Gets the length of the saved template sound data in sizeof(short).

        DllExport extern "C" INT VOICECOM_GET_TEMPLATE_SOUND_LENGTH();

---------- VOICECOM_GET_TEMPLATE_SOUND

Gets the template sound from the internal cache in user buffer.

        DllExport extern "C" SHORT VOICECOM_GET_TEMPLATE_SOUND(
                SHORT* Buffer,      //pointer to user buffer
                INT length                //length of sound data
                );
Parameters
        Buffer  The pointer to user buffer saved sound data.
        Length  The length of sound data is returned by the function
                VOICECOM_GET_TEMPLATE_SOUND_LENGTH;

Return Values
        Returns 0 if Ok, else error code

---------- VOICECOM_PLAY_TEMPLATE_SOUND

Plays template sound. Stop recognition firstly unless you have full duplex Sound Card.

        DllExport extern "C" SHORT VOICECOM_PLAY_TEMPLATE_SOUND();

-------------------------------------------------------------------------------

Error codes

SOUND CARD FUNCTIONS

VOICECOM_ERROR_OK			  0 - no error
VOICECOM_NO_WAVEIN_DEVICE 		  1 - no WaveIn device
VOICECOM_FORMAT_NOT_SUPPORTED             2 - Format PCM 16 bit mono 11025Hz  is not supported
VOICECOM_WAVEINOPEN_ERROR                 3 - cannot open WaveIn device
VOICECOM_REENTRANCE_ERROR                 4 - reentrance error
VOICECOM_MEMORY_ALLOCATION_ERROR          5 - no memory for buffers
VOICECOM_THREAD_ERROR                     6 - can not create new THREAD
VOICECOM_CAN_NOT_CLOSE_WAVEIN_DEVICE  	  7 - can not close WaveIn device

WAV FILES FUNCTIONS

VOICECOM_WORD_READY                       0 -  Word has been discovered
VOICECOM_BAD_FILENAME                     1 -  File name is NULL ptr
VOICECOM_BAD_FILE                         2 -  Can not open file
VOICECOM_BAD_FILE_FORMAT                  3 -  Not a WAV file PCM16 mono 11025
VOICECOM_END_OF_FILE                      4 -  End of file detected

BUFFER FUNCTIONS

VOICECOM_BAD_BUFFER                       5 - NULL ptr buffer
VOICECOM_BAD_BUFFERLENGTH                 6 - 0 or negative buffer length
VOICECOM_TOO_LONG_BUFFER                  7 - More than 512 counts of data
VOICECOM_END_OF_BUFFER                    8 - End of buffer reached (no word)

TEMPLATE FUNCTIONS

VOICECOM_WAVEOUTOPEN_ERROR                   	1
VOICECOM_WAVEOUT_PREPARE_ERROR                	2
VOICECOM_WAVEOUT_PLAY_ERROR                     3
VOICECOM_NO_TEMPLATESOUND_ERROR           	4
VOICECOM_SOUND_MEMORY_ALLOCATION_ERROR          5 - no memory for buffers

NOTIFICATION CODES

VOICECOM_NO_ERROR         			0  -  A word has been said
VOICECOM_LOW_LEVEL      			1  -   Speak louder
VOICECOM_HEAVY_NOISE  				2  -   Check microphone

-------------------------------------------------------------------------------

DEMO SOFTWARE
Source of DEMO.EXE project explains how to use VOICECOM.DLL and gives an
example of template library realization.

DEMO.EXE has the same features as the demo program (http://www.speechpro.com)
plus extra features. It can accept WAVE file instead of microphone sound input.
User can press "WAV files" button or Drag&Drop a WAVE file on main dialog.
All words from a WAVE file will be accepted one by one. Training also can be
done with WAVE files. User can Drag&Drop a WAVE file on Train word dialog.
The first word in the WAVE file will be taken as a template. Format of WAVE
files should be 11025Hz PCM 16bit mono.


-------------------------------------------------------------------------------

SUPPORT

Our developers are always ready to assist you. In case of any questions,
please don't hesitate to contact us.

WWW:	http://www.speechpro.com
E-mail: 	info@speechpro.com
Fax: 		+7 812 3279297
Phone:		+7 812 3258848

We hope that you would like our product.
Please note that we are always ready to develop any customized software for
you. Any questions on our products and development costs should be addressed
to our Sales department: e-mail: sales@speechpro.com).
