The Synthesis ToolKit in C++ (STK)

Home Information Classes Download Usage Mail List Requirements Links FAQ Tutorial

Using Filters

In this section, we demonstrate the use of a few of the STK filter classes. The stk::Iir class provides functionality to implement a generalized infinite impulse response (IIR) digital filter, similar to the `filter` function in Matlab. In this example, we create an stk::Iir instance and initialize it with specific numerator and denominator coefficients. We then compute its impulse response for 20 samples.

#include "Iir.h"
using namespace stk;
int main()
{
StkFrames output( 20, 1 ); // initialize StkFrames to 20 frames and 1 channel (default: interleaved)
output[0] = 1.0;
std::vector<StkFloat> numerator( 5, 0.1 ); // create and initialize numerator coefficients
std::vector<StkFloat> denominator; // create empty denominator coefficients
denominator.push_back( 1.0 ); // populate our denomintor values
denominator.push_back( 0.3 );
denominator.push_back( -0.5 );
Iir filter( numerator, denominator );
filter.tick( output );
for ( unsigned int i=0; i<output.size(); i++ ) {
std::cout << "i = " << i << " : output = " << output[i] << std::endl;
}
return 0;
}
stk::Iir
STK general infinite impulse response filter class.
Definition Iir.h:35
stk::StkFrames
An STK class to handle vectorized audio data.
Definition Stk.h:279
stk
The STK namespace.
Definition ADSR.h:6

The stk::Iir class implements the standard difference equation

a[0]*y[n] = b[0]*x[n] + ... + b[nb]*x[n-nb] - a[1]*y[n-1] - ... - a[na]*y[n-na],

where "b" values are numerator coefficients and "a" values are denominator coefficients. Note that if the first denominator coefficient is not 1.0, the Iir class automatically normalizes all filter coefficients by that value. The coefficient values are passed to the Iir class via a C++ vector, a container object provided by the C++ Standard Library.

Most STK classes use more specific types of digital filters, such as the stk::OneZero, stk::OnePole, stk::TwoPole, or stk::BiQuad varieties. These classes inherit from the stk::Filter abstract base class and provide specific functionality particular to their use, as well as functions to independently control individual coefficient values.

# Resonances:

The STK stk::BiQuad and stk::TwoPole classes provide functionality for creating resonance filters. The following example demonstrates how to create a resonance centered at 440 Hz that is used to filter the output of a stk::Noise generator.

#include "BiQuad.h"
#include "Noise.h"
using namespace stk;
int main()
{
StkFrames output( 20, 1 ); // initialize StkFrames to 20 frames and 1 channel (default: interleaved)
Noise noise;
BiQuad biquad;
biquad.setResonance( 440.0, 0.98, true ); // automatically normalize for unity peak gain
for ( unsigned int i=0; i<output.size(); i++ ) {
output[i] = biquad.tick( noise.tick() ); // single-sample computations
std::cout << "i = " << i << " : output = " << output[i] << std::endl;
}
return 0;
}
stk::BiQuad
STK biquad (two-pole, two-zero) filter class.
Definition BiQuad.h:26
stk::BiQuad::setResonance
void setResonance(StkFloat frequency, StkFloat radius, bool normalize=false)
Sets the filter coefficients for a resonance at frequency (in Hz).
stk::BiQuad::tick
StkFloat tick(StkFloat input)
Input one sample to the filter and return a reference to one output.
Definition BiQuad.h:192
stk::Noise
STK noise generator.
Definition Noise.h:22
stk::Noise::tick
StkFloat tick(void)
Compute and return one output sample.
Definition Noise.h:59

By passing a boolian value of `true` as the third argument to the stk::BiQuad::setResonance() function, the filter coefficients are automatically scaled to achieve unity gain at the resonance peak frequency. The previous code could be easily modified for "vector-based" calculations:

#include "BiQuad.h"
#include "Noise.h"
using namespace stk;
int main()
{
StkFrames output( 20, 1 ); // initialize StkFrames to 20 frames and 1 channel (default: interleaved)
Noise noise;
BiQuad biquad;
biquad.setResonance( 440.0, 0.98, true ); // automatically normalize for unity peak gain
biquad.tick( noise.tick( output ) ); // vector-based computations
for ( unsigned int i=0; i<output.size(); i++ ) {
std::cout << "i = " << i << " : output = " << output[i] << std::endl;
}
return 0;
}

[Main tutorial page] [Next tutorial]

The Synthesis ToolKit in C++ (STK)
©1995--2023 Perry R. Cook and Gary P. Scavone. All Rights Reserved.