libWhisper Documentation

by Frederic Trouche.

$Id: libWhisper.sgml,v 1.3 2001/04/18 20:32:16 xfred Exp $


This document is a programmer's guide to the libWhisper library, a library providing useable classes, based upon libWhisperCore.

1. Purpose

libWhisper library is intended to provide specific application level objects, generaly based upon libWhisperCore classes. Obviously, this allows applications to share a common core.

2. Introduction

2.1 Quick...

Basicaly, a data handler is a detached thread that can have an incoming data stream and one (or more) outgoing data stream(s).

Please refer to libWhisperCore for more informations about data handlers (rtDataHandler) and data streams (rtDataStream).

2.2 What's in here ?

This library provides, among other things, non-abstract useable data handlers that could be used in any application using WHISPER.

3. Microphone handler

3.1 Overview

rtMicrophoneHandler, inherited from rtDataHandler, is the main class for microphone handling. It is the only one that has to be instancied by programmers. Its work is to initialise the microphone, and codes incoming audio streams into the outgoing buffer of data handler.

Audio encoding is made by an instance of rtMicrophoneCoder that belongs to a rtMicrophoneHandler.

Please note that rtDataHandler standard block handling method is ignored and that the execute(void*) method is overloaded (since no incoming stream rtDataStream exists).

3.2 Sound encoding

First of all, rtMicrophoneCoder is doing a basic microphone calibration. When done, it enters in a normal audio encoding mode that consists in listening for noise, ignore silences except when they reflect a end of speech stream (EOS), and chain either sound blocks (ST_SOUND data stream block type) or EOS block (ST_EOS type).

3.3 Parameters

The silenceBlocksForEOS parameter contains the number of silences corresponding to the end of speech/stream information.

Others parameters handle microphone hard configuration : acqFrequency (in Hz, default 8000), sampleSize (is the basic word's number of bits), blockSize (depending on underlaying hardware, this is the byte number that are readen from device in a raw; commonly 64), and blockNumber is the number of raw device blocks that'll be in encoded a sound block buffer.

4. Speech recoder

4.1 Purpose

rtSpeechRecoder class can be considered has a caching-only data handler. Is simply recodes incoming sound blocks into its outgoing buffer, using the handleSound(rtDataStreamBlock *) method of rtDataHandler.

4.2 Parameters

This class inherits all standards parameters of rtDataHandler, and use the normal stream handling method. Refers to this class for more explanation on the parameters and behaviour.

5. Phones handler

5.1 Purpose

Phones handler is providing a continuous listening of incoming audio blocks. To do that, it uses the EOS information, originaly given by rtMicrophoneHandler (which can be a remote handler).

5.2 Overview

Since rtPhonesHandler is derived from rtStreamWriterFile, it uses an overloading of the write(rtDataStream *) method that is used by parent's handleSound(rtDataStreamBlock *).

Silences and parameter changing into previous handlers are ignored (waitingBlocks is simply decremented in handleSilence(rtDataStreamBlock *) and handleParameters(rtDataStreamBlock *) methods.

5.3 Continuous speech

The rtDataHandler readConditionOnLast(rtDataStreamBlock *) now waits for an EOS block type or waiting blocks to be above 10 (default value). This affects the rtDataHandler behaviour.

6. zlib compression

rtZLibCompressor handler compress incoming audio stream into ST_ZDATA blocks using the zlib compression library. Thus, the outgoing stream should hold compressed audio blocks (and possibly some other block types).

7. zlib decompression

rtZLibDecompressor does the opposite : it decompresses each block of type ST_ZDATA into ST_AUDIO block.

8. GSM codec

8.1 Requierements

8.2 Overview

8.3 Coding to GSM format

8.4 Decoding from GSM format