tclassp(n) 0.5 doc "tclassp library"

PACKAGE VARIABLES

::tclassp::errors

::tclassp::warnings

These variable store errors or warnings encountered during calls of the exec subcommands (see below). They will be reset at each new call of exec.

PACKAGE COMMANDS

::tclassp::object DOBJname "signalFileName"

This command creates a new ASSP DOBJ structure with an associated Tcl command whose name is DOBJname from the signal file referred to by "signalFileName". The name of the newly created command is returned. If there already is a Tcl Command named DOBJname it will be (safely) deleted. This DOBJ command is explained in full detail in the sections DOBJ COMMAND and DOBJ METHODS. The object command will be created under the current namespace if the DOBJname is not fully qualified, and in the specified namespace otherwise.

::tclassp::option AOPTSname analysisFunction

This command will probably only rarely be used directly since the package predefines AOPTS commands for all analysis procedures in libassp, see PREDEFINED AOPTS COMMANDS. The command creates a new ASSP AOPTS structure with an associated Tcl command whose name is AOPTSname. The AOPTS structure will be tailored for the analysis procedure given in analysisFunction. analysisFunction maybe any one returned by ::tclassp::anafuncs, see below. This AOPTS command is explained in full detail in the sections AOPTS COMMAND, COMMON AOPTS OPTIONS, and AOPTS METHODS. The object command will be created under the current namespace if the AOPTSname is not fully qualified, and in the specified namespace otherwise.

::tclassp::anacomds

Returns a list of available analysis commands. Every available analysis command is already predefined, see PREDEFINED AOPTS COMMANDS.

::tclassp::winfuncs

Returns a simple list of the code names of the available window functions. See WINDOW FUNCTIONS for details.

::tclassp::wininfo

Returns a nested list of details on the available window functions. See WINDOW FUNCTIONS for more information.

::tclassp::extract ?-nocomplain? "infile" start end "outfile"

This command extracts signal data from the signal file given in "infile" and writes them to the file whose name is given in "outfile". Extraction starts at the time specified as start and ends at the time given in end. Both times must be specified in milli seconds. Specifying times outside the range will result in an error and no data will be written to "outfile". Beware that, if present, "outfile" will be overwritten without warning.

::tclassp::verbose ?verbosityLevel?

If verbosityLevel is specified, this command sets the verbosity level of the package to the given value. If verbosityLevel is not specified the current value is returned. The package author is not sure whether or how this command works...

::tclassp::lptypes

This command returns a list of linear prediction types, see tclassp_rfcana for details.

::tclassp::specttypes

This command returns a list of spctrum types, see tclassp_spectrum for details.

DOBJ COMMAND

All commands created by ::tclassp::object have the following general form and may be used to invoke various operations on their data object.

DOBJname method ?arg arg ...?

The method method and its arg'uments determine the exact behavior of the command. See section DOBJ METHODS for the detailed specifications. DOBJ commands can be deleted safely using Tcl's rename mechanism.

% tclassp::object dobj "samplefile.wav"
dobj
% rename dobj ""

DOBJ METHODS

DOBJname copy ?newName?

This command creates a new DOBJ which is an almost exact copy of the original DOBJname and returns the name of the new DOBJ. This name is either newName if specified, or it is generated automatically, see AUTOMATIC OBJECT NAMING for details. The copy will only differ from the original in terms of its internally stored file path.

DOBJname data ?-start startSample? ?-end endSample? ?-emuformat segnum? ?-channel chan?

This command extracts data from the currently selected track of a DOBJ. If the -start and -end sample numbers are not given or less or greater than the range of the data, they will be set to the start and the end of the data. Specifying a start sample greater than the end sample or vice versa will result in an error. The extracted data will either be returned or, if -channel is specified and chan is an open Tcl Channel (as returned by e.g. open) written to said channel. In the latter case, the number of samples transferred from the DOBJ to the channel will be returned. If -emuformat is specified with a segnum greater 0 the result will be formatted such that it can be stored as an EMU track list (see http://emu.sourceforge.net). segnum should then correspond to the segment number in an EMU segment list.

DOBJname discard

This command frees the memory allocated to store the signal data but does not delete the DOBJ itself.

DOBJname exec AOPTSname ?newName?

This command applies the analysis function specified by a previously defined AOPTSname and the corresponding options to the data in DOBJname. The result is a new DOBJ named newName, if specified, otherwise a name is automatically assigned, see AUTOMATIC OBJECT NAMING for details. The command returns the name of the newly created object.

DOBJname info ?-all | -track?

This command returns a key/value list of informations about the DOBJ, such as sampling rate, format, duration etc. The optional argument can be -all in which case information on all available tracks is returned or -track in which case only information on the currently selected track is returned. Defaults to -all. The following example uses a data object containing formant data and the corrsponding bandwidths.

% ::tclassp::object formants formants.fms
formants
% formants info
file_name formants.fms file_format SSFF header_size 152 byte_order MSB_last data_rate 200.0
sample_rate 16000.0 number_frames 208 start_time 0.0025 duration {1.040 sec}
ssff_keyword fm data_type {formant_frequency (Hz)} data_format INT16 number_fields 4
ssff_keyword bw data_type {formant_bandwidth (Hz)} data_format INT16 number_fields 4
%
% formants info -track
file_name formants.fms file_format SSFF header_size 152 byte_order MSB_last data_rate 200.0
sample_rate 16000.0 number_frames 208 start_time 0.0025 duration {1.040 sec} 
ssff_keyword fm data_type {formant_frequency (Hz)} data_format INT16 number_fields 4

DOBJname needssave

This command returns a boolean value indicating whether the DOBJ currently contains unsaved data.

DOBJname origfreq

This command returns the value of the OriginalFreq field currently only available in SSFF. If this field is not present, 0 is returned. The OriginalFreq field can be present in parametric data files (e.g. spectral data) and states the sampling rate of the original signal file on which an analysis has been run. This information is especially useful for spectral data.

DOBJname sample sampleNumber ?values?

If values are not specified this command returns the value(s) of the sample spacified as sampleNumber. If values are specified there should be one value per channel in the currently selected track. A value specified as "?" will not be changed. The following example uses formant data with 4 channels (F1-F4).

% ::tclassp::object formants formants.fms
formants
% formants sample 39
367 2046 2407 3524
% formants sample 39 370 2050 2410 3520
% formants sample 39
370 2050 2410 3520
% formants sample 39 ? 0 0 ?
% formants sample 39
370 0 0 3520
% formants needssave
1

DOBJname track ?newTrack?

If newTrack is not specified, this command returns the currently selected track. At creation time, the first track encountered in the signal file is selected. If newTrack is specified, it must be a valid track of the DOBJ. The command returns the empty string on success or an error.

% ::tclassp::object formants formants.fms
formants
% formants track
fm
% formants track bw
% formants track
bw

DOBJname tracks

This command returns a list of all available tracks in the DOBJ.

% ::tclassp::object formants formants.fms
formants
% formants track
fm bw

DOBJname write ?"filename"?

This command writes the contents of a DOBJ to file. If the DOBJ internally has a file path (i.e. because it was vcreated from a file or has been written to already) the "filename" argument needs not be specified. If the DOBJ does not internally have a file path (i.e. because it was created by e.g. the copy or the exec subcommands) "filename" argument must be specified or else the command will return with an error.

AOPTS COMMAND

All commands created by ::tclassp::option have the following general form and may be used to invoke various operations on their data object.

AOPTSname method ?arg arg ...?

The method method and its arg'uments determine the exact behavior of the command. See section AOPTS METHODS for the detailed specifications. AOPTS commands can be deleted safely using Tcl's rename mechanism.

% ::tclassp::option aopt rmsana
aopt
% rename aopt ""

AOPTS METHODS

AOPTSname cget option

Returns the current setting of the option option. option may be any option appropraite for the underlying analysis function, see COMMON AOPTS OPTIONS and PREDEFINED AOPTS COMMANDS below.

AOPTSname configure option ?value? ?option? ?value?

For each option-value pair sets option to value. If the last option is missing its corresponding value the current value is returned. option may be any option appropraite for the underlying analysis function, see COMMON AOPTS OPTIONS and PREDEFINED AOPTS COMMANDS below.

Currently not standard behaviour, will be changed

AOPTSname exec fileNameList

Performs the ASSP analysis function specified at creation time on all files whose names are given in FileNameList. FileNameList must be a proper Tcl list. Returns the number of files processed successfully

AOPTSname info

This command returns a list of information on the AOPTS command. The first three elements of the list are

1. the name of the analysis function

2. the major version number

3. the minor version number

The remaining elements consist of key-value pairs listing all available options of the analysis function and the the option type. Option type is useful for the creation of graphical user interfaces and may be:

• bool: Options with a boolean value, best represented with check boxes

• text: Options with a more or less free value, best represented with entry fields

• radio: Options with a short range of fixed values, best represented by radio buttons

• combo: Options with longer ranges of fixed values, best represented by combo boxes

• spin: Options with continuos numerical value ranges, best represented by spin boxes

tkassp makes use of these otpion types to generate GUIs more or less automatically. In some cases, option type is the empty string to indicate that the option is not to be used in a GUI in the same way as the other options, see COMMON AOPTS OPTIONS for details.

AOPTSname reset

Resets all options to the default.

AOPTSname version

Returns the version of the ASSP analysis function.

COMMON AOPTS OPTIONS

The following options do not affect the resulting analysis. They do not have an option type as defined for the AOPTSname info command. These options are available for all analysis commands.

-extension outputExtension

Defines the value of the output extension when the analysis result is written to file.

-outDir outputDirectory

Defines the directory in which the resulting file (if any) is stored.

-counter counterVariable

If counterVariable is a fully qualified variable name, it is incremented each time the AOPTSname exec command finishes processing a file. This is useful to track the progress of the analysis especially for long file lists. If counterVariable is empty (the default) no counting is performed.

-stop stopVariable

If stopVariable is a fully qualified variable name, it is read each time the AOPTSname exec command start processing a file. Setting stopVariable to true will cause the abortion of the running AOPTSname exec command. This is useful if the necessity to abort time-consuming processes of of long file lists should arise. If stopVariable is the empty string (the default) aborting processes is not possible.

The following options will affect the results of the anaysis functions. Some are available in all ASSP analysis functions but not in all of them:

-begin beginTime

Start time of the analysis in ms. Defaults to begin of signal.

-end endTime

End time of the analysis in ms. Defaults to end of signal.

-central useCenterTime

If useCenterTime is true, a single frame analysis with the analysis window centered at the time specified in -begin will be performed. Overrules specifications of -end and -winShift. Defaults to false.

-winSize windowSize

Specifies the length of the anaysis window in ms.

-effLength useEffectivLength

Boolean value determining whether -winSize is interpreted as the effective or as the exact length of the analysis window.

-winShift windowShift

Specifies the size of the window shift in ms.

-window windowFunction

Specifies the code name of the window function to use. Valid window functions are listed in WINDOW FUNCTIONS.

There is a number of options not listed here which are used in few functions only. They are documented in the context were they occur, i.e. in the manual pages of the corresponding functions.