TSP Lab - Software - libtsp

## Telecommunications & Signal Processing Laboratory

### libtsp Library Routines

The libtsp package is a library of routines for signal processing. It also includes a number of general purpose routines useful for program development. Examples of programs using this library for filtering, LPC analysis/synthesis and resampling are available as part of the AFsp package.

The libtsp library routines are divided into a number of categories, with the first two letters of the routine name keyed to the category. Examples of the functions available are listed for each category.

AF - Audio file routines

- Open and close audio files
- Read and write audio files

FI - Filtering routines

- Filter a signal (FIR and IIR filters)
- Generate windows (Hamming, Kaiser and raised-cosine)
- Design Kaiser-windowed lowpass filters
- Read filter coefficient files

FL - File routines

- Fill in the full path name for a file name
- Return the creation date for a file
- Prompt and read a line of text
- Read and write numeric data

FN - Functions

- Bessel function (0'th order modified)
- Greatest common divisor
- Series expansion of Chebyshev polynomials
- Log base 2

MA - Matrix routines

- Allocate space for a matrix
- Print a matrix
- Calculate quadratic and bilinear forms
- Solve equations (Cholesky decomposition and Toeplitz matrix)

MS - Miscellaneous routines

- Convolve coefficients of two arrays
- Nearest integer, floor and ceiling functions
- Interpolate a table of values (linear and cubic)
- Rational approximation to a value

SP - Signal processing routines

- Fast Fourier transform (complex and real)
- Discrete cosine transform
- Calculate covariance or autocorrelation from a block of data
- Convert between linear prediction parameters (error filter coefficients, predictor coefficients, cepstral coefficients, line spectral frequencies, reflection coefficients, autocorrelation coefficients)
- Solve for linear prediction coefficients (covariance and autocorrelation methods)
- Calculate the mean-square filtering error
- Distance measures (Itakura-Saito and RMS log LPC)
- Quantize a value given a table of boundaries (binary search)

ST - String routines

- Copy and concatenate strings
- Decode numeric values from a string
- Match a string to a table of keywords

UT - Utility routines

- Decode command line options
- Error message routines

VR - Vector routines

- Print a vector of values
- Vector functions (zero an array, convert to dB, dot product, minimum, maximum, scale, add, subtract, multiply)

The libtsp routines are divided into user routines and nucleus routines. The nucleus routines are used internally by the libtsp routines. Only the user level routines are documented in the HTML files.

### Include file

A routine that uses any of the libtsp routines should include the libtsp header file,

      #include <libtsp.h>

If the header file for the library is <path>/include/libtsp.h, then under Unix, the command to compile a routine proc.c, would be of the form,

      cc -c -I<path>/include proc.c

### Linking

User routines need to be linked to the libtsp library ( <path>/lib/libtsp.a ) and to the standard C math library libm.a (invoked during linking as -lm ). (A number of the libtsp routines use the standard math routines.) Under Unix, a typical link command is of the form,

      cc main.o proc.o <path>/lib/libtsp.a -lm -o main

The libtsp routines are written in C and have been tested on DEC, HP, SGI, Sun, and PC-386 machines, using a number of different compilers (ANSI and non-ANSI).

### Audio file routines

AFclose - Close an audio file
AFopenRead - Open an audio file for reading
AFopenWrite - Open an audio file for writing
AFreadData - Read data from an audio file (return float values)
AFsetFileType - Set the input audio file type
AFsetHinfo - Set the audio file header information string
AFsetNHpar - Set defaults for headerless audio files from a string specification
AFwriteData - Write data to an audio file (float input values)

### Filtering routines

FIKaiserLPF - Generate a Kaiser windowed lowpass filter
FIbiquad - Filter a signal using a biquadratic IIR filter
FIconvSI - Filter a signal with an FIR filter (sample rate change)
FIconvol - Filter a signal with an FIR filter
FIdeem - Deemphasize a signal using a first order recursive filter
FIfiltAP - Filter a signal with an all-pole IIR filter
FIfiltIIR - Filter a signal using a cascade of biquadratic IIR filters
FIpreem - Preemphasize a signal using a first difference filter
FIreadFilt - Read a filter coefficient file
FIwinHCos - Generate a Hamming/cosine window
FIwinHamm - Generate a Hamming window
FIwinKaiser - Generate a Kaiser window
FIwinRCos - Generate a raised-cosine window

### File routines

FLbackup - Rename an existing file
FLbaseName - Return the last component of a file path
FLdate - Find the last modification time for a file (by name)
FLdefName - Fill in file name components from a default string
FLdirName - Return all but the last component of a file path
FLexpHome - Expand the home directory specification for a file
FLextName - Return the extension component of a file name
FLfReadData - Read numeric data in text form from a file
FLfWriteData - Write a float array in text form to a file
FLfileDate - Find the last modification time for an open file
FLfullName - Expand a file name path
FLgetLine - Read a line of text from a file
FLgetRec - Read and assemble a text record from an input stream
FLhomeDir - Get the home directory for a user
FLpathList - Fill in a directory for a file name from a list of paths
FLpreName - Return the last component of a file name stripped of its extension
FLprompt - Print a prompt
FLreadLine - Print a prompt and read a line of text

### Functions

FNbessI0 - Evaluate the zeroth-order modified Bessel function of first kind
FNevChebP - Evaluate a series expansion in Chebyshev polynomials
FNgcd - Find the greatest common divisor of two integer values
FNiLog2 - Find the integer greater or equal to log (base 2)
FNsinc - Evaluate the sin(pi*x)/(pi*x) function

### Matrix routines

MAdAllocMat - Allocate a matrix of double values
MAdFreeMat - Free an allocated double matrix
MAdPrint - Print a double matrix along with a header text
MAfAllocMat - Allocate a matrix of float values
MAfChSolve - Solve a positive definite set of equations
MAfFreeMat - Free an allocated float matrix
MAfPrint - Print a float matrix along with a header text
MAfSubMat - Set up pointers to a submatrix of a matrix of float values
MAfSyBilin - Calculate a bilinear form for a symmetric matrix
MAfSyQuad - Calculate a quadratic form for a symmetric matrix
MAfTpQuad - Calculate a quadratic form for a symmetric Toeplitz matrix
MAfTpSolve - Solve a Toeplitz set of equations
MAiPrint - Print an integer matrix along with a header text
MAlPrint - Print a long integer matrix along with a header text

### Miscellaneous routines

MSconvCof - Convolve the coefficients of two arrays
MSdNint - Nearest integer function
MSfGaussRand - Generate a Gaussian pseudo-random value
MSfUnifRand - Generate a uniformly distributed pseudo-random value
MSiCeil - Ceiling function for the ratio of two integers
MSiFloor - Floor function for the ratio of two integers
MSiPower - Integer raised to an integer power
MSintLin - Interpolate a table of values using a piecewise linear interpolant
MSintMC - Interpolate a table of values using a piecewise monotonic cubic interpolant
MSlCeil - Ceiling function for the ratio of two long ints
MSlFloor - Floor function for the ratio of two long ints
MSratio - Find a ratio of integers approximation to a floating point value

### Signal processing routines

SPautoc - Calculate the autocorrelation for a data sequence
SPcFFT42 - Fast Fourier transform (complex data)
SPcepXpc - Convert cepstral coefficients to predictor coefficients
SPcorBWexp - Bandwidth expand a set of correlation values
SPcorFilt - Find filter coefficients to minimize the mean-square error
SPcorFmse - Calculate the mean-square filtering error
SPcorPmse - Calculate the mean-square prediction error
SPcorXpc - Find predictor coefficients from autocorrelation values
SPcovCXpc - Find predictor coefficients using the covariance lattice method (Cumani)
SPcovFilt - Find filter coefficients using the covariance approach
SPcovFmse - Find the mean-square error for a filter (covariance specified)
SPcovLXpc - Find predictor coefficients using the covariance lattice method
SPcovMXpc - Find predictor coefficients using the modified covariance method
SPcovPmse - Calculate the mean-square prediction error (covariance specified)
SPcovXpc - Find predictor coefficients using the covariance method
SPcovar - Calculate a correlation (covariance) matrix for a data sequence
SPecXpc - Convert prediction error filter coefficients to predictor coefficients
SPfDCT - Calculate the discrete cosine transform
SPlpcISdist - Calculate the Itakura-Saito LPC spectral distance measure
SPlpcLSdist - Calculate the RMS log LPC spectral distance measure
SPlsfXpc - Convert LSF's to predictor coefficients
SPpcBWexp - Bandwidth expand a set of predictor coefficients
SPpcXcep - Convert predictor coefficients to cepstral coefficients
SPpcXcor - Convert predictor coefficients to correlation values
SPpcXec - Convert predictor coefficients to prediction error filter coeffients
SPpcXlsf - Convert predictor coefficients to line spectral frequencies
SPpcXrc - Convert predictor coefficients to reflection coefficients
SPquant - Binary search for a bounding interval
SPrFFT - Fast Fourier transform of a real sequence
SPrcXpc - Convert reflection coefficients to predictor coefficients

### String routines

STcatMax - Concatenate at characters to a string (maximum length specified)
STcopyMax - Copy at most Maxchar characters to a string
STcopyNMax - Copy N characters characters to a string
STdec1double - Decode a double value
STdec1float - Decode a float value
STdec1int - Decode an integer value
STdec1long - Decode a long integer value
STdecDfrac - Decode a ratio specification of two double values
STdecIfrac - Decode a ratio specification of two integer values
STdecIrange - Decode a range specification for integer values
STdecLrange - Decode a range specification for long integer values
STdecNdouble - Decode double values (variable number)
STdecNfloat - Decode float values (variable number)
STdecNint - Decode integer values (variable number)
STdecNlong - Decode long integer values (variable number)
STfindToken - Find the first token string in a string
STkeyMatch - Match a string to keyword strings
STkeyXpar - Decode keywords and return parameter values
STtrim - Copy a string, trimming leading and trailing white-space
STunQuote - Copy a string, removing outer quote characters

### Utility routines

UTdate - Return a date/time string for the current time
UTerror - Print user and system error messages, stop with error status set
UTfree - Deallocate a block of memory
UTgetOption - Decode command line options and arguments
UThalt - Print an error message, stop with error status set
UTmalloc - Allocate a block of memory
UTrealloc - Reallocate a block of memory
UTsetProg - Set the program name for messages
UTsysMsg - Print user and system warning messages
UTuserName - Get the user name and host name
UTwarn - Print a warning message

### Vector routines

VRdPrint - Print a double array along with a header text
VRdZero - Zero an array of doubles
VRfAdd - Element-by-element sum of two float arrays
VRfAmpldB - Convert each value in an array of amplitudes to a decibel value
VRfCheckSym - Determine if an array of floats is symmetric or anti-symmetric
VRfCopy - Copy an array of floats
VRfDiffSq - Find the sum of squares of the differences for two float arrays
VRfDotProd - Dot product of two float arrays (double result)
VRfLog10 - Find the logarithm (base 10) of each element of an array
VRfMax - Return the maximum value in a float array
VRfMin - Return the minimum value in a float array
VRfMult - Element-by-element product of two float arrays
VRfPow10 - Find 10 raised to the power of each element of an array
VRfPrint - Print a float array along with a header text
VRfRev - Reverse the order of the elements of an array
VRfScale - Multiply each element of a float array by a scalar value
VRfSet - Set each element in an array of floats to a given value
VRfShift - Shift the elements of an array of floats
VRfSubt - Element-by-element subtraction of two float arrays
VRfSum - Calculate the sum of elements in an array of floats
VRfZero - Zero an array of floats
VRiPrint - Print an integer array along with a header text
VRiZero - Zero an array of ints
VRlPrint - Print a long integer array along with a header text

### Author / revision

P. Kabal - kabal@ECE.McGill.CA
Telecommunications & Signal Processing Laboratory
Department of Electrical & Computer Engineering
McGill University
Montreal, Canada H3A 2A7
1998/07/06 libtsp-v3r0