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
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:280

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--2021 Perry R. Cook and Gary P. Scavone. All Rights Reserved.