The Synthesis ToolKit in C++ (STK)

Home Information Classes Download Usage Mail List Requirements Links FAQ Tutorial

Realtime Audio (blocking)

In this section, we modify the sineosc.cpp program in order to send the output to the default audio playback device on your computer system. We also make use of the stk::SineWave class as a sine-wave oscillator. stk::SineWave computes an internal, static sine-wave table when its first instance is created. Subsequent instances make use of the same table. The default table length, specified in SineWave.h, is 2048 samples.

// rtsine.cpp STK tutorial program
#include "SineWave.h"
#include "RtWvOut.h"
#include <cstdlib>
using namespace stk;
int main()
{
// Set the global sample rate before creating class instances.
Stk::setSampleRate( 44100.0 );
Stk::showWarnings( true );
int nFrames = 100000;
SineWave sine;
RtWvOut *dac = 0;
try {
// Define and open the default realtime output device for one-channel playback
dac = new RtWvOut( 1 );
}
catch ( StkError & ) {
exit( 1 );
}
sine.setFrequency( 441.0 );
// Option 1: Use StkFrames
/*
StkFrames frames( nFrames, 1 );
try {
dac->tick( sine.tick( frames ) );
}
catch ( StkError & ) {
goto cleanup;
}
*/
// Option 2: Single-sample computations
for ( int i=0; i<nFrames; i++ ) {
try {
dac->tick( sine.tick() );
}
catch ( StkError & ) {
goto cleanup;
}
}
cleanup:
delete dac;
return 0;
}
stk::RtWvOut
STK realtime audio (blocking) output class.
Definition RtWvOut.h:31
stk::RtWvOut::tick
void tick(const StkFloat sample)
Output a single sample to all channels in a sample frame.
stk::SineWave
STK sinusoid oscillator class.
Definition SineWave.h:26
stk::SineWave::setFrequency
void setFrequency(StkFloat frequency)
Set the data interpolation rate based on a looping frequency.
stk::SineWave::tick
StkFloat tick(void)
Compute and return one output sample.
Definition SineWave.h:99
stk::StkError
STK error handling class.
Definition Stk.h:87
stk::Stk::showWarnings
static void showWarnings(bool status)
Toggle display of WARNING and STATUS messages.
Definition Stk.h:213
stk::Stk::setSampleRate
static void setSampleRate(StkFloat rate)
Static method that sets the STK sample rate.
stk
The STK namespace.
Definition ADSR.h:6

The class stk::RtWvOut is a protected subclass of stk::WvOut. A number of optional constructor arguments can be used to fine tune its performance for a given system. stk::RtWvOut provides a "single-sample", blocking interface to the RtAudio class. Note that stk::RtWvOut (as well as the stk::RtWvIn class described below) makes use of RtAudio's callback input/output functionality by creating a large ring-buffer into which data is written. These classes should not be used when low-latency and robust performance is necessary

Though not used here, an stk::RtWvIn class exists as well that can be used to read realtime audio data from an input device. See the record.cpp example program in the examples project for more information.

It may be possible to use an instance of stk::RtWvOut and an instance of stk::RtWvIn to simultaneously read and write realtime audio to and from a hardware device or devices. However, it is recommended to instead use a single instance of RtAudio to achieve this behavior, as described in the next section. See the effects project or the duplex.cpp example program in the examples project for more information.

When using any realtime STK class (RtAudio, stk::RtWvOut, stk::RtWvIn, RtMidi, stk::InetWvIn, stk::InetWvOut, stk::Socket, stk::UdpSocket, stk::TcpServer, stk::TcpClient, and stk::Thread), it is necessary to specify an audio/MIDI API preprocessor definition and link with the appropriate libraries or frameworks. For example, the above program could be compiled on a Linux system using the GNU g++ compiler and the ALSA audio API as follows (assuming all necessary files exist in the project directory):

g++ -Wall -D__LINUX_ALSA__ -D__LITTLE_ENDIAN__ -o rtsine Stk.cpp Generator.cpp SineWave.cpp WvOut.cpp \
RtWvOut.cpp RtAudio.cpp rtsine.cpp -lpthread -lasound
RtAudio
Realtime audio i/o C++ classes.
Definition RtAudio.h:268

On a Macintosh OS X system, the syntax would be:

g++ -Wall -D__MACOSX_CORE__ -o rtsine Stk.cpp Generator.cpp SineWave.cpp WvOut.cpp RtWvOut.cpp RtAudio.cpp \
rtsine.cpp -lpthread -framework CoreAudio -framework CoreMIDI -framework CoreFoundation

[Main tutorial page] [Next tutorial]

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