BSAPI: SSignalModellingI Class Reference

virtual bool BSAPI_METHOD SSignalModellingI::ActivateAllModels ( ) [pure virtual]

Activate all models from a set stored in directory given by SetModelDirectory or by a configuration file.

Returns:: true if all models were found and activated correctly

See also:: SetModelDirectory()

Examples:: gender_identification.cpp, language_identification.cpp, and speaker_identification.cpp.

virtual bool BSAPI_METHOD SSignalModellingI::ActivateModels ( char * pList ) [pure virtual]

Activate selected models from a set.

The models are stored in a directory given by SetModelDirectory or by a configuration file.

Parameters:

pList

list of models separated by space, new line, colon or semicolon

Returns:: true if all models were found and activated correctly

See also:: SetModelDirectory()

Examples:: language_identification.cpp, and speaker_identification.cpp.

virtual bool BSAPI_METHOD SSignalModellingI::AddFile	(	char *	pModelName,
		char *	pFile
	)			`[pure virtual]`

Load a signal from a file and send it to the system for training/.

Parameters:

	pModelName	name of model the signal should be used for. Many models can be estimated during one training.
	pFile	file that should be loaded

Returns:: true if the file was loaded and the signal was added

See also:: SetTemporalFileName()

Examples:: language_identification.cpp, and speaker_identification.cpp.

virtual bool BSAPI_METHOD SSignalModellingI::AddFilesFromDirectory	(	char *	pModelName,
		char *	pDirectory,
		char *	pSuffix
	)			`[pure virtual]`

Add signals form all files in a directory with given suffix to the system for training.

Parameters:

	pModelName	name of model the signals should be used for. Many models can be estimated during one training.
	pDirectory	searched directory
	pSuffix	file suffix

Returns:: if all files were added correctly

Examples:: language_identification.cpp, and speaker_identification.cpp.

virtual bool BSAPI_METHOD SSignalModellingI::AddFilesFromListFile ( char * pListFile ) [pure virtual]

Add signals from many files according a list to the system for training/.

Parameters:

pFile

listfile, the model name and signal file name per line

Returns:: if all files were added correctly

Examples:: language_identification.cpp, and speaker_identification.cpp.

virtual bool BSAPI_METHOD SSignalModellingI::AddFilesFromMemList ( char * pMemList ) [pure virtual]

Add signals from many files according a list to the system for training.

Parameters:

pMemList

pointer to memory containing the list. The list contain model name and signal file name per record. The records are separated by new lines.

Returns:: if all files were added correctly

virtual bool BSAPI_METHOD SSignalModellingI::AddWaveform	(	char *	pModelName,
		void *	pWaveform,
		int	nBytes
	)			`[pure virtual]`

Send a signal to the system for training.

Parameters:

	pModelName	name of model the signal should be used for. Many models can be estimated during one training.
	pWaveform	the signal. The format of signal is given by a setting in configuration file and can be retrieved through waveform format convertor SWaveformFormatConvertorI.
	nBytes	number of bytes sent

Returns:: true if the signal was added

See also:: GetWaveformFormatConvertor()

virtual void BSAPI_METHOD SSignalModellingI::Cancel ( ) [pure virtual]

Cancel training/scoring and return the object to a default state.

In case of training, a state of model set before training started is restored.

virtual bool BSAPI_METHOD SSignalModellingI::FinishTraining ( ) [pure virtual]

Finish model set estimation. The models are saved to disk and the set is made default for scoring.

Returns:: true if the estimation finished correctly, false in case of an error. In the case of error, the system is trying to restore the previous model set or to remove trained models (according config file). In case of model removing, the set can end up with less models than before because a model could be retrained.

Examples:: language_identification.cpp, and speaker_identification.cpp.

virtual char* BSAPI_METHOD SSignalModellingI::GetBestModel ( float * pScore = 0 ) [pure virtual]

Gets best model name.

The best model name is chosen according to the best score. It can also return a name of special (other) class if the UBM have a better score and if it is enabled. The name is specified in configuration file, usually it is other or ubm.

Returns:: pointer to the best model name or zero in case of an error

Examples:: language_identification.cpp, and speaker_identification.cpp.

virtual unsigned int BSAPI_METHOD SSignalModellingI::GetMode ( ) [pure virtual]

Returns an approach used for score calculation.

Returns:: SM_IDENTIFICATION or SM_DETECTION

virtual char* BSAPI_METHOD SSignalModellingI::GetModelDirectory ( ) [pure virtual]

Returns model directory.

Returns:: actual model directory

virtual char** BSAPI_METHOD SSignalModellingI::GetModelNames ( int * pNumValues ) [pure virtual]

Returns an array of model names.

There will be number of models +1 scores. Index 0 is reserved for a name of an universal background model (UBM).

Parameters:

pNumValues

pointer to value where a number of model names will be stored. This pointer can be zero.

Returns:: array of names or zero in case of an error

Examples:: gender_identification.cpp, language_identification.cpp, and speaker_identification.cpp.

virtual float* BSAPI_METHOD SSignalModellingI::GetModelScores ( int * pNumValues ) [pure virtual]

Returns an array of model scores.

There will be number of models +1 scores. Index 0 is reserved for a score related to an universal background model.

Parameters:

pNumValues

pointer to value where a number of model scores will be stored. This pointer can be zero.

Returns:: array of scores or zero in case of an error

Examples:: gender_identification.cpp, language_identification.cpp, and speaker_identification.cpp.

virtual int BSAPI_METHOD SSignalModellingI::GetNRequestedTrainingIters ( ) [pure virtual]

Returns requested number of training iterations.

Returns:: number of times the training data should be send to the system for model estimation (training)

Examples:: language_identification.cpp, and speaker_identification.cpp.

virtual char** BSAPI_METHOD SSignalModellingI::GetSubsysNames ( int * pNumNames = 0 ) [pure virtual]

Get names of subsystems.

This allow to show the subsystem names to user and assign weight to each one.

Parameters:

pNumNames

a pointer to a value where the number of names will be stored. It can be zero.

Returns:: an array of names of subsystems or zero in case of error

virtual SSignalModellingSubsystemI* BSAPI_METHOD SSignalModellingI::GetSubsystem ( char * pName ) [pure virtual]

This function allows to access a subsystem directly.

Parameters:

pName

name of requested subsystem

Returns:: pointer to the instance of the requested subsystem or zero in case of error

virtual float* BSAPI_METHOD SSignalModellingI::GetSubsysWeights ( int * pNumWeights = 0 ) [pure virtual]

Return an array of weights, one for each subsystem.

Parameters:

pNumWeights

pointer to a value where the number of subsystems will be stored

Returns:: array of weights of subsystems or zero in case of error

virtual float BSAPI_METHOD SSignalModellingI::GetTestLength ( ) [pure virtual]

Get the length of the signal which was used for test (i.e. the sum of speech segments).

The length returned is not affected by current setting of active waveform part by the call of SetActiveWaveformPart

Returns:: length of the signal in seconds

Examples:: language_identification.cpp, and speaker_identification.cpp.

virtual float BSAPI_METHOD SSignalModellingI::GetTrainingLength ( const char * pModelName ) [pure virtual]

Get the length of the signal which was used for training particular model (i.e. the sum of speech segments).

Parameters:

pModelName

model name

Returns:: length of the signal in seconds or zero if the model was not found

Examples:: language_identification.cpp, and speaker_identification.cpp.

virtual STranscriptionMemoryI* BSAPI_METHOD SSignalModellingI::GetTranscriptionMemory ( ) [pure virtual]

Return pointer to transcription memory.

The transcription memory allows to access segmentation labels.

Returns:: pointer to instance of the STranscriptionMemoryI class

virtual SWaveformFilterI* BSAPI_METHOD SSignalModellingI::GetWaveformFilter ( ) [pure virtual]

Return pointer to waveform filter.

The filter can provide useful information about quality of signal - the length of voice, length technical noises etc.

Returns:: pointer to instance of the SWaveformFilterI class

See also:: SetTwoStageProcessing()

virtual SWaveformFormatConvertorI* BSAPI_METHOD SSignalModellingI::GetWaveformFormatConvertor ( ) [pure virtual]

Return pointer to waveform format convertor.

The waveform format convertor can provide useful information about format of the the input signal.

Returns:: pointer to instance of the SWaveformFormatConvertorI class

See also:: AddWaveform()
TestWaveform()

Examples:: gender_identification.cpp, language_identification.cpp, and speaker_identification.cpp.

virtual SWaveformMemoryI* BSAPI_METHOD SSignalModellingI::GetWaveformMemory ( ) [pure virtual]

Return pointer to waveform memory.

The waveform memory allows to access signal after waveform convertor and waveform filter.

Returns:: pointer to instance of the SWaveformMemoryI class

virtual bool BSAPI_METHOD SSignalModellingI::Init ( char * pConfigFile ) [pure virtual]

Initialization of signal modelling and its subsystems according a configuration file.

Parameters:

pConfigFile

configuration file

Returns:: true initialization finished correctly

Examples:: gender_identification.cpp, language_identification.cpp, and speaker_identification.cpp.

virtual bool BSAPI_METHOD SSignalModellingI::RemoveModel ( char * pName ) [pure virtual]

Remove model from the model set.

Parameters:

pName

model name

Returns:: true if the model was successfully removed. If not, check file access rights etc.

virtual bool BSAPI_METHOD SSignalModellingI::RenameModel	(	char *	pOldName,
		char *	pNewName
	)			`[pure virtual]`

Rename model from one name to another.

Parameters:

	pOldName	old model name
	pNewName	name the model should be renamed on

Returns:: true if the model was successfully renamed. If not, check file access rights etc.

virtual bool BSAPI_METHOD SSignalModellingI::ResetTest ( ) [pure virtual]

Inform the system that a new signal will be send for test.

This is the same as to call TestWaveform with the PF_LASTFRAME flag before.

Returns:: true reset end up correctly

See also:: SetTemporalFileName()

virtual bool BSAPI_METHOD SSignalModellingI::RunSecondStage ( ) [pure virtual]

Run second stage in two stage processing.

Returns:: true if the second stage end up correctly

virtual bool BSAPI_METHOD SSignalModellingI::SetActiveWaveformPart	(	float	startInSec,
		float	lenInSec
	)			`[pure virtual]`

Sets active part of the signal for scoring.

This can significantly speed-up processing in some application. For example the improvement is very small if a language is identified from 1 hour of speech instead of few minutes. The active part selection is not supported for part by part processing of signals. If the signal contain speech, the length is length of a clean speech without silence. If there is less speech or the speech is on another place, the selection is moved to satisfy the requested length of speech the best.

Parameters:

	startInSec	start of the selection in seconds
	lenInSec	length of the selection in second

Returns:: true if the selection end up correctly

Examples:: language_identification.cpp, and speaker_identification.cpp.

virtual void BSAPI_METHOD SSignalModellingI::SetMasterSignalModelling ( SSignalModellingI * pMasterSignalModelling ) [pure virtual]

Set master signal modelling object.

Master signal modelling object is supposed to perform signal preprocessing - waveform filtering and segmentation. If the master object is set this object gets preprocessing output from it. This may save computation time if there are multiple signal modelling objects working in 'parallel' (e.g. in gender dependent speaker identification).

Parameters:

pMasterSignalModelling

master signal modelling object

virtual bool BSAPI_METHOD SSignalModellingI::SetMode ( unsigned int mode ) [pure virtual]

Set an approach used for score calculation (given by use of scores).

Parameters:

mode

predefined constant SM_IDENTIFICATION or SM_DETECTION

SM_IDENTIFICATION - selection of one of N classes
SM_DETECTION - each class is taken as separate detector

Returns:: true if the setting end up correctly, false if the mode is not supported

virtual bool BSAPI_METHOD SSignalModellingI::SetModelDirectory ( char * pModelDirectory ) [pure virtual]

Sets a directory with model set, or a directory where some new models should be saved.

Parameters:

pModelDirectory

model directory

Returns:: false if the directory can not be changed or created

Examples:: language_identification.cpp, and speaker_identification.cpp.

virtual void BSAPI_METHOD SSignalModellingI::SetOverwriteFiles ( bool overwriteFiles ) [pure virtual]

Overwrite temporal files.

If the version of software changed, the temporal files must be removed before processing of overwritten.

Parameters:

overwriteFiles

true enable overwriting of temporal files
false disable overwriting of temporal files

See also:: SetOverwriteFiles()
SetTemporalFileName()

virtual void BSAPI_METHOD SSignalModellingI::SetSaveTemporalFiles ( bool saveTemporalFiles ) [pure virtual]

Save temporal files.

This can be good to speed up repeated processing (iterative training, hierarchical classification etc.)

Parameters:

saveTemporalFiles

true enable saving temporal files
false disable saving temporal files

virtual void BSAPI_METHOD SSignalModellingI::SetSubsysWeights ( float * pWeights ) [pure virtual]

Set weights of subsystems.

Each subsystem use a different approach to signal modelling. The scores are then merged linearly together to form a final score $S = \sum_{i=1}^N{w_i S_i}$ . But some subsystems are better for some tasks and another are beneficial elsewhere. For example the phonotactic system is better for language recognition of nonnative speakers. The acoustic language identification system is better for dialect recognition. This allows to weight the subsystems directly for the target task.

Parameters:

pWeighs

array of weights, one for each subsystem

virtual void BSAPI_METHOD SSignalModellingI::SetTemporalFileName ( char * pName ) [pure virtual]

Set temporal file name.

The temporal file name is usually derived from a processed file name by another suffix. But if a a signal from memory block is processed, this allow to setup the file name.

Parameters:

pName

temporal file name. The suffix is cut off and a predefined one (in a configuration file) is used.

See also:: SetSaveTemporalFiles()
SetOverwriteFiles()

virtual void BSAPI_METHOD SSignalModellingI::SetTwoStageProcessing ( bool twoStageProcessing ) [pure virtual]

Use two stage processing.

Input signal is loaded to memory, passed through waveform format convertor, through waveform filter and then the user has the choise to continue in processing or not. For example the processing can be canceled if there is not enough speech data, if there is too much noise etc.

Parameters:

twoStageProcessing

- true enable two stage processing

false disable two stage processing

See also:: RunSecondStage()
GetWaveformFilter()

virtual void BSAPI_METHOD SSignalModellingI::SetUseOtherClass ( bool useOtherClass ) [pure virtual]

Use a special (other) class if the system thinks that signal match non of the models.

This has a sense in case of identification (SetMode). The decision is made from a comparison to the UBM score.

Parameters:

useOtherClass

true use the other class
false do not use the other class

See also:: SetMode()

virtual bool BSAPI_METHOD SSignalModellingI::SetUseWaveformFilter ( bool useWaveformFilter = false ) [pure virtual]

Enable or disable waveform filter.

The signal modelling allows to pass the input signal through a waveform filter. This filter cuts off many technical noises, like DTMF tones, faxes, signalization, filter out short impulses, it shorten long parts of silences and also produce some statistics about the signal. This can improve classification/detection results an speed up the processing.

Parameters:

useWaveformFilter

true enable waveform filter
false disable waveform filter

Returns:: false in case the filter is not initialized

See also:: GetwaveformFilter()

virtual bool BSAPI_METHOD SSignalModellingI::StartTrainingIteration ( ) [pure virtual]

Notification for the system that the data set will be sent to the system.

Returns:: true if the previous iteration end up correctly and the training can continue, false if it and up in an error state and the training was canceled.

Note:: It is not necessary to call this function if all subsystems are known to request just one iteration.

Examples:: language_identification.cpp, and speaker_identification.cpp.

virtual bool BSAPI_METHOD SSignalModellingI::TestFile ( char * pFile ) [pure virtual]

Load a signal from a file and send it to the system for scoring.

The scores are then received by the GetModelScores function.

Parameters:

pFile

file that should be loaded

Returns:: true if the file was loaded and the signal was added

Examples:: gender_identification.cpp, language_identification.cpp, and speaker_identification.cpp.

virtual bool BSAPI_METHOD SSignalModellingI::TestWaveform	(	void *	pWaveform,
		int	nBytes,
		unsigned int	flag = `PF_LASTFRAME`
	)			`[pure virtual]`

Send signal to the system for scoring.

The signal can be send also part by part while the identification/detection is being improved. In this case, the PF_LASTFRAME flag is used just for the last part. The scores are then received by the GetModelScores function.

Parameters:

	pWaveform	the signal. The format of signal is given by a setting in configuration file and can be retrieved through waveform format convertor SWaveformFormatConvertorI.
	nBytes	number of bytes sent
	flags	PF_LASTFRAME - the last part of the signal was sent.

Returns:: true if the signal was added

Warning:: the incremental mode is not implemented yet

See also:: GetWaveformFormatConvertor()
GetModelScores()

SSignalModellingI Class Reference

Public Member Functions

Detailed Description

Member Function Documentation


Public Member Functions
virtual bool BSAPI_METHOD	Init (char *pConfigFile)=0
	Initialization of signal modelling and its subsystems according a configuration file.
virtual bool BSAPI_METHOD	SetMode (unsigned int mode)=0
	Set an approach used for score calculation (given by use of scores).
virtual unsigned int BSAPI_METHOD	GetMode ()=0
	Returns an approach used for score calculation.
virtual bool BSAPI_METHOD	SetModelDirectory (char *pModelDirectory)=0
	Sets a directory with model set, or a directory where some new models should be saved.
virtual char *BSAPI_METHOD	GetModelDirectory ()=0
	Returns model directory.
virtual int BSAPI_METHOD	GetNRequestedTrainingIters ()=0
	Returns requested number of training iterations.
virtual bool BSAPI_METHOD	StartTrainingIteration ()=0
	Notification for the system that the data set will be sent to the system.
virtual bool BSAPI_METHOD	AddWaveform (char pModelName, void pWaveform, int nBytes)=0
	Send a signal to the system for training.
virtual bool BSAPI_METHOD	AddFile (char pModelName, char pFile)=0
	Load a signal from a file and send it to the system for training/.
virtual bool BSAPI_METHOD	AddFilesFromListFile (char *pListFile)=0
	Add signals from many files according a list to the system for training/.
virtual bool BSAPI_METHOD	AddFilesFromMemList (char *pMemList)=0
	Add signals from many files according a list to the system for training.
virtual bool BSAPI_METHOD	AddFilesFromDirectory (char pModelName, char pDirectory, char *pSuffix)=0
	Add signals form all files in a directory with given suffix to the system for training.
virtual bool BSAPI_METHOD	FinishTraining ()=0
	Finish model set estimation. The models are saved to disk and the set is made default for scoring.
virtual bool BSAPI_METHOD	ActivateModels (char *pList)=0
	Activate selected models from a set.
virtual bool BSAPI_METHOD	ActivateAllModels ()=0
	Activate all models from a set stored in directory given by SetModelDirectory or by a configuration file.
virtual bool BSAPI_METHOD	TestWaveform (void *pWaveform, int nBytes, unsigned int flag=PF_LASTFRAME)=0
	Send signal to the system for scoring.
virtual bool BSAPI_METHOD	ResetTest ()=0
	Inform the system that a new signal will be send for test.
virtual bool BSAPI_METHOD	TestFile (char *pFile)=0
	Load a signal from a file and send it to the system for scoring.
virtual bool BSAPI_METHOD	SetActiveWaveformPart (float startInSec, float lenInSec)=0
	Sets active part of the signal for scoring.
virtual void BSAPI_METHOD	SetTwoStageProcessing (bool twoStageProcessing)=0
	Use two stage processing.
virtual bool BSAPI_METHOD	RunSecondStage ()=0
	Run second stage in two stage processing.
virtual float *BSAPI_METHOD	GetModelScores (int *pNumValues)=0
	Returns an array of model scores.
virtual char **BSAPI_METHOD	GetModelNames (int *pNumValues)=0
	Returns an array of model names.
virtual char *BSAPI_METHOD	GetBestModel (float *pScore=0)=0
	Gets best model name.
virtual void BSAPI_METHOD	SetUseOtherClass (bool useOtherClass)=0
	Use a special (other) class if the system thinks that signal match non of the models.
virtual void BSAPI_METHOD	Cancel ()=0
	Cancel training/scoring and return the object to a default state.
virtual void BSAPI_METHOD	SetSaveTemporalFiles (bool saveTemporalFiles)=0
	Save temporal files.
virtual float BSAPI_METHOD	GetTestLength ()=0
	Get the length of the signal which was used for test (i.e. the sum of speech segments).
virtual float BSAPI_METHOD	GetTrainingLength (const char *pModelName)=0
	Get the length of the signal which was used for training particular model (i.e. the sum of speech segments).
virtual void BSAPI_METHOD	SetOverwriteFiles (bool overwriteFiles)=0
	Overwrite temporal files.
virtual void BSAPI_METHOD	SetTemporalFileName (char *pName)=0
	Set temporal file name.
virtual bool BSAPI_METHOD	RemoveModel (char *pName)=0
	Remove model from the model set.
virtual bool BSAPI_METHOD	RenameModel (char pOldName, char pNewName)=0
	Rename model from one name to another.
virtual char **BSAPI_METHOD	GetSubsysNames (int *pNumNames=0)=0
	Get names of subsystems.
virtual void BSAPI_METHOD	SetSubsysWeights (float *pWeights)=0
	Set weights of subsystems.
virtual float *BSAPI_METHOD	GetSubsysWeights (int *pNumWeights=0)=0
	Return an array of weights, one for each subsystem.
virtual SSignalModellingSubsystemI *BSAPI_METHOD	GetSubsystem (char *pName)=0
	This function allows to access a subsystem directly.
virtual void BSAPI_METHOD	SetMasterSignalModelling (SSignalModellingI *pMasterSignalModelling)=0
	Set master signal modelling object.
virtual bool BSAPI_METHOD	SetUseWaveformFilter (bool useWaveformFilter=false)=0
	Enable or disable waveform filter.
virtual SWaveformFilterI *BSAPI_METHOD	GetWaveformFilter ()=0
	Return pointer to waveform filter.
virtual SWaveformFormatConvertorI *BSAPI_METHOD	GetWaveformFormatConvertor ()=0
	Return pointer to waveform format convertor.
virtual SWaveformMemoryI *BSAPI_METHOD	GetWaveformMemory ()=0
	Return pointer to waveform memory.
virtual STranscriptionMemoryI *BSAPI_METHOD	GetTranscriptionMemory ()=0
	Return pointer to transcription memory.