FUNCTIONS

Signal processing library

General

The signal processing library is an independent part of the system. The library has several functions related to eg. the creation and modification of networks. All the library functionality can be used only with the C++ programming language.

Description and purpose

Simulations can be run on different signal processing networks independently from each other. When initiating a simulation run, the user must specify the length of the simulation. The simulation length is specified by means of the output signal duration, in milliseconds, seconds, minutes or some other unit.

Networks

A network consists of zero or more blocks and zero or more wires.

All networks have a function for printing a textual description of the network topology. This function will examine the structure of the network and formulate a printout of the structure with the names of blocks and input/output terminals. The printout is output to an output stream such as the standard output stream of a process.

Wires

Wires are unidirectional connections between a single output terminal of a block and a single input terminal of a block. There may be one or more wires connected to a single output terminal. Theoretically there may be multiple independent connections to block input terminals as well, but it is possible to restrict the number of connections a certain input terminal can handle. For example, the adder block (see section 4.2.2) has a single input terminal and a single output terminal while it can handle multiple input signals and can produce multiple (identical) output signals.

An input and an output terminal can be connected and disconnected by using the services provided by the SP library API.

Frames

All the signals flowing through the SP networks are segmentated to short frames. These frames are very short, typically a few milliseconds each. The frame length can be set between simulation runs.

The frame objects do not have a fixed duration but all can have a different length, see section 3.1.

Input terminals

There is exactly one input terminal per one signal input in a block. The input terminals may take multiple connections, provided that the block can handle it. If an input terminal takes multiple connections, the number of connections can be dynamically changed.

An input terminal does not know the source of the incoming signals. The signals are delivered to input terminals through wires from output terminals.

Output terminals

There is exactly one output terminal per one signal output in a block. A single output terminal can be connected to multiple input terminals, dynamically. An output terminal knows the destination input terminal if there is a wire between them.

Processing

Network design is accomplished by creating blocks and by connecting the blocks together with wires. There are functions for creating and destroying networks and blocks and making and removing the connections between blocks.

Network simulation is another function of the SP library. The simulation is carried out to a certain network. The network may necessarily not be suitable for simulation, and the simulation function will inspect the network before simulation. In the case of errors the application program using the library will be notified.

The simulation is carried out for a preset duration. The specification of this duration is done via the SP library API.

Error handling

If there is an error which stops the network simulation, all the opened files will be closed.

Memory allocation

The library will detect out of memory situations and will notify the application program in such cases.

Block errors

If an error occurs during processing of any block, the block orders the library to stop the simulation of the network. The application program using the library will identify the block that caused the error and give a textual description of the error.

Blocks

General to all blocks

Description and purpose

Blocks are independent signal processing algorithms with well-defined inputs and outputs. In general a block is the lowest-level implementation that is not divided into subparts. This implies that there may be some redundancy in the functionalities between different blocks.

Inputs and outputs

There are no inputs and outputs general to all blocks.

Processing

There are five functional features implemented in every block:

1.

constructor

2.

pre-simulation initialization

3.

simulation

4.

post-simulation cleanup

5.

destructor

Error handling

There are two kinds of general error situations detected.

Mathematics errors.

The base class will catch the math exceptions and stop the simulation of the network in these cases. Some examples of math exceptions are over- and underflow and division by zero.

Memory allocation errors.

The individual blocks will detect out of memory situations and respond by stopping the simulation of the network.

Adder

 

Description and purpose

Sum an arbitrary number of input signals together and output the sum.

Inputs and outputs

 

1. x₁ signal

$$\vdots \vdots$$

N. x_N 3lOutput:

1. y sum signal

Processing

The output is calculated as the pointwise sum of the inputs:

$$y[n] = \sum_{i=1}^N x_i[n]$$ (1)

Error handling

No specific error situations.

 

Q	=
	=

Biquad band-pass filter

 

Description and purpose

Perform band-pass filtering operations on a signal. The filter is a -order biquad infinite impulse response (IIR) filter [3].

Inputs and outputs

1. x signal

2. f₁ lower band frequency [Hz]

3. f₂ upper band frequency [Hz] 3lOutput:

1. y filtered signal

Processing

The biquad filter difference equation is as follows [11, Eq. 2.80]:

(2)

with the coefficients a_i and b_i as calculated in table 4.1 under BPF.

Error handling

Number Cause Error text

1. ``Lower frequency must be less than the upper frequency.''

2. ``Frequencies must be positive or zero.''

3. ``Frequencies must be less than or equal to half of sample frequency.''

Biquad band-stop filter

Description and purpose

Perform band-stop filtering operations on a signal. The filter is a -order biquad infinite impulse response (IIR) filter [3].

Inputs and outputs

1. x signal

2. f₁ lower band frequency [Hz]

3. f₂ upper band frequency [Hz] 3lOutput:

1. y filtered signal

Processing

The processing is done as described in section 4.2.3, with the coefficients a_i and b_i as calculated in table 4.1 under BSF.

Error handling

Number Cause Error text

1. ``Lower frequency must be less than the upper frequency.''

2. ``Frequencies must be positive or zero.''

3. ``Frequencies must be less than or equal to half of sample frequency.''

Biquad high-pass filter

Description and purpose

Perform high-pass filtering operations on a signal. The filter is a -order biquad infinite impulse response (IIR) filter [3].

Inputs and outputs

1. x signal

2. f cutoff frequency [Hz] 3lOutput:

1. y filtered signal

Processing

The processing is done as described in section 4.2.3, with the coefficients a_i and b_i as calculated in table 4.1 under HPF.

Error handling

Number Cause Error text

1. f < 0 ``Frequencies must be positive or zero.''

2. ``Frequencies must be less than or equal to half of sample frequency.''

Biquad low-pass filter

Description and purpose

Perform low-pass filtering operations on a signal. The filter is a -order biquad infinite impulse response (IIR) filter [3].

Inputs and outputs

1. x signal

2. f cutoff frequency [Hz] 3lOutput:

1. y filtered signal

Processing

The processing is done as described in section 4.2.3, with the coefficients a_i and b_i as calculated in table 4.1 under LPF.

Error handling

Number Cause Error text

1. f < 0 ``Frequencies must be positive or zero.''

2. ``Frequencies must be less than or equal to half of sample frequency.''

Delay line

Description and purpose

Delay the incoming signal by a certain amount. Initially the delay line contains all zeros.

The delay implements integer and fractional delay features [4], and the delay duration parameter can be undulated during simulation.

In order for this feature to work the user must specify the maximum delay duration d_max, which will set the length of the internal delay line buffer. If the maximum delay duration parameter is increased, the tail of the new buffer is padded with zeros.

Inputs and outputs

1. x signal

2. d delay duration [ms] 3lOutput:

1. y delayed signal

Processing

The output signal y is defined as

(3)

where .

Error handling

Number Cause Error text

1. d < 0 ``Delay must be positive or zero.''

2. d too large ``Delay is too large; out of memory.''

3. d > d_max ``Delay must be less than or equal to maximum delay.''

File input

Description and purpose

Read in an audio signal file and output the signal in question. The signal must be a 1-32-bit PCM  audio signal and must contain one channel. Supported file formats are AIFF  and RIFF WAV . The sampling rate specified in the signal file is discarded.

Inputs and outputs

1. t file name 3lOutput:

1. y signal

Processing

An integer PCM signal v is read from the file t by using a third-party audio file library called libaudiofile [13]. The output signal y is constructed from the integer signal by converting it to a floating-point representation within [-1, 1):

(4)

where b denotes the width (number of bits) of the integer data v.

Error handling

Number Cause Error text

1. file not found ``Audio file t is not found.''

2. file not readable ``Audio file t is not readable.''

3. unknown file format ``Audio file t is not an AIFF nor a WAV file.''

4. non-monaural file ``Audio file t contains several channels.''

5. non-PCM coding ``Audio file t does not contain linear PCM data.''

File output

Description and purpose

Write out an audio signal file of the input signal. The output data is written as 16-bit PCM audio. Output files are written in AIFF file format.

Inputs and outputs

1. x signal

2. t file name 3lNo outputs.

Processing

The input signal x is quantized to a 16-bit integer representation v with a similar quantizer as described in section 4.2.14. The signal is clipped to be within [-1, 1] prior to quantization. The clipped and quantized signal is written to the file t by using a third-party audio file library called libaudiofile [13].

Error handling

Number Cause Error text

1. file not writable ``Audio file t is not writable.''

Max/min

Description and purpose

Find the maximum and minimum values of an arbitrary number of input signals. The values are found fore each sample separetely.

Inputs and outputs

1. x₁ signal

$$\vdots \vdots$$

N. x_N 3lOutputs:

1. y_min minimum signal

2. y_max maximum signal

Processing

The output signals y_min and y_max are defined as

(5)

(6)

Error handling

No specific error situations.

Multiplier

Description and purpose

Multiply an arbitrary number of input signals together and output the product.

Inputs and outputs

1. x₁ signal

$$\vdots \vdots$$

N. x_N 3lOutput:

1. y product signal

Processing

The output is calculated as the pointwise product of the inputs:

(7)

Error handling

No specific error situations.

Negation

Description and purpose

Negate the incoming signal.

Inputs and outputs

1. x signal 3lOutput:

1. y negated signal

Processing

The output signal y is defined as

y[n] = -x[n]

Error handling

No specific error situations.

Noise generator

Description and purpose

Generate white noise with a uniform probability density function. The noise is a pseudo-random number sequence generated with a linear congruential generator  (LCG).

Inputs and outputs

1. A amplitude 3lOutput:

1. y noise signal

Processing

The LCG equation is as follows [12, Eq. 7.1.2]

(9)

where a=7⁵=16807 and m=2³¹-1=2147483647 [12, Eq. 7.1.3]. I₀ is the seed value for the pseudo-random number sequence. The seed is initialized to a promiscuous(FIXME) value; see [15, p. 223].

(10)

Error handling

Number Cause Error text

1. A < 0 ``Amplitude must be non-negative.''

Quantizer

 

Description and purpose

Quantize the signal by using a uniform quantizer.

Inputs and outputs

1. x signal

2. b number of bits 3lOutput:

1. y quantized signal

Processing

The uniform midtread quantizer equation is as follows [10, Eq. 1]:

(11)

where .

Error handling

Number Cause Error text

1. ``Number of bits must be between 1 and 32.''

2. b non-integer ``Number of bits must be integer.''

Reciprocal

Description and purpose

Compute the reciprocal signal of a signal.

Inputs and outputs

1. x signal 3lOutput:

1. y reciprocal signal

Processing

The output is calculated as the pointwise reciprocal of the input:

(12)

Error handling

Number Cause Error text

1. x = 0 ``Division by zero.''

Sine generator

Description and purpose

Generate a sine signal.

Inputs and outputs

1. f frequency [Hz]

2. A amplitude 3lOutput:

1. y sine signal

Processing

The output signal y is defined as

(13)

with

(14)

and .

Error handling

Number Cause Error text

1. ``Frequency must be smaller than equal to sample frequency.''

2. A < 0 ``Amplitude must be non-negative.''

Variable

Description and purpose

Generate a signal of selected value.

Inputs and outputs

1. y variable signal

Processing

The output signal y is defined as

y[n] = k

where k is desired variable value.

Error handling

No specific error situations.