The Synthesis ToolKit in C++ (STK)

Home Information Classes Download Usage Mail List Requirements Links FAQ Tutorial

Control Input

Each Synthesis ToolKit instrument exposes its relevant control parameters via public functions such as setFrequency() and controlChange(). Programmers are free to implement the control scheme of their choice in exposing those parameters to the user.

A text-based control protocol called SKINI is provided with the Synthesis ToolKit. SKINI extends the MIDI protocol in incremental ways, providing a text-based messaging scheme in human-readable format and making use of floating-point numbers wherever possible. Each SKINI message consists of a message type (e.g., NoteOn, PitchBend), a time specification (absolute or delta), a channel number (scanned as a long integer), and a maximum of two subsequent message-specific field values. Knowing this, it should be relatively clear what the following SKINI "scorefile" specifies:

NoteOn 0.000082 2 55.0 82.3
NoteOff 1.000000 2 55.0 64.0
NoteOn 0.000082 2 69.0 82.8
StringDetune 0.100000 2 10.0
StringDetune 0.100000 2 30.0
StringDetune 0.100000 2 50.0
StringDetune 0.100000 2 40.0
StringDetune 0.100000 2 22.0
StringDetune 0.100000 2 12.0
NoteOff 1.000000 2 69.0 64.0

MIDI messages are easily represented within the SKINI protocol.

The class stk::Messager can be used to acquire and parse MIDI messages from a MIDI device and SKINI messages from STDIN and socket connections. Incoming messages are acquired asynchronously and saved to an internal message queue of stk::Skini::Message types (MIDI messages are converted to the stk::Skini:Message format). The user then uses the stk::Messager:popMessage() function to retrieve incoming control messages. This function does not block, instead returning a message type of zero when no more messages are in the queue. Many of the example programs included with the ToolKit distribution use a stk::Messager instance to accept control input from the accompanying Tcl/Tk graphical user interfaces, from external MIDI devices, or from SKINI scorefiles.

In the following example, we'll modify the `bethree.cpp` program from the previous tutorial chapter and incorporate a stk::Messager class to allow control via SKINI messages read from a SKINI file.

// controlbee.cpp STK tutorial program
#include "BeeThree.h"
#include "RtAudio.h"
#include "Messager.h"
#include "SKINImsg.h"
#include <math.h>
#include <algorithm>
using std::min;
using namespace stk;
void usage(void) {
// Error function in case of incorrect command-line
// argument specifications.
std::cout << "\nuseage: controlbee file\n";
std::cout << " where file = a SKINI scorefile.\n\n";
exit(0);
}
// The TickData structure holds all the class instances and data that
// are shared by the various processing functions.
struct TickData {
Instrmnt *instrument;
Messager messager;
Skini::Message message;
int counter;
bool haveMessage;
bool done;
// Default constructor.
TickData()
: instrument(0), counter(0), haveMessage(false), done( false ) {}
};
#define DELTA_CONTROL_TICKS 64 // default sample frames between control input checks
// The processMessage() function encapsulates the handling of control
// messages. It can be easily relocated within a program structure
// depending on the desired scheduling scheme.
void processMessage( TickData* data )
{
StkFloat value1 = data->message.floatValues[0];
StkFloat value2 = data->message.floatValues[1];
switch( data->message.type ) {
case __SK_Exit_:
data->done = true;
return;
case __SK_NoteOn_:
if ( value2 == 0.0 ) // velocity is zero ... really a NoteOff
data->instrument->noteOff( 0.5 );
else { // a NoteOn
StkFloat frequency = 220.0 * pow( 2.0, (value1 - 57.0) / 12.0 );
data->instrument->noteOn( frequency, value2 * ONE_OVER_128 );
}
break;
case __SK_NoteOff_:
data->instrument->noteOff( value2 * ONE_OVER_128 );
break;
case __SK_ControlChange_:
data->instrument->controlChange( (int) value1, value2 );
break;
case __SK_AfterTouch_:
data->instrument->controlChange( 128, value1 );
} // end of switch
data->haveMessage = false;
return;
}
// This tick() function handles sample computation and scheduling of
// control updates. It will be called automatically when the system
// needs a new buffer of audio samples.
int tick( void *outputBuffer, void *inputBuffer, unsigned int nBufferFrames,
double streamTime, RtAudioStreamStatus status, void *dataPointer )
{
TickData *data = (TickData *) dataPointer;
StkFloat *samples = (StkFloat *) outputBuffer;
int counter, nTicks = (int) nBufferFrames;
while ( nTicks > 0 && !data->done ) {
if ( !data->haveMessage ) {
data->messager.popMessage( data->message );
if ( data->message.type > 0 ) {
data->counter = (long) (data->message.time * Stk::sampleRate());
data->haveMessage = true;
}
else
data->counter = DELTA_CONTROL_TICKS;
}
counter = min( nTicks, data->counter );
data->counter -= counter;
for ( int i=0; i<counter; i++ ) {
*samples++ = data->instrument->tick();
nTicks--;
}
if ( nTicks == 0 ) break;
// Process control messages.
if ( data->haveMessage ) processMessage( data );
}
return 0;
}
int main( int argc, char *argv[] )
{
if ( argc != 2 ) usage();
// Set the global sample rate and rawwave path before creating class instances.
Stk::setSampleRate( 44100.0 );
Stk::setRawwavePath( "../../rawwaves/" );
TickData data;
RtAudio dac;
// Figure out how many bytes in an StkFloat and setup the RtAudio stream.
RtAudio::StreamParameters parameters;
parameters.deviceId = dac.getDefaultOutputDevice();
parameters.nChannels = 1;
RtAudioFormat format = ( sizeof(StkFloat) == 8 ) ? RTAUDIO_FLOAT64 : RTAUDIO_FLOAT32;
unsigned int bufferFrames = RT_BUFFER_SIZE;
if ( dac.openStream( &parameters, NULL, format, (unsigned int)Stk::sampleRate(), &bufferFrames, &tick, (void *)&data ) ) {
std::cout << dac.getErrorText() << std::endl;
goto cleanup;
}
try {
// Define and load the BeeThree instrument
data.instrument = new BeeThree();
}
catch ( StkError & ) {
goto cleanup;
}
if ( data.messager.setScoreFile( argv[1] ) == false )
goto cleanup;
if ( dac.startStream() ) {
std::cout << dac.getErrorText() << std::endl;
goto cleanup;
}
// Block waiting until callback signals done.
while ( !data.done )
Stk::sleep( 100 );
// Shut down the output stream.
dac.closeStream();
cleanup:
delete data.instrument;
return 0;
}
RtAudio.h
RtAudioStreamStatus
unsigned int RtAudioStreamStatus
RtAudio stream status (over- or underflow) flags.
Definition RtAudio.h:178
RtAudioFormat
unsigned long RtAudioFormat
RtAudio data format type.
Definition RtAudio.h:105
RtAudio
Realtime audio i/o C++ classes.
Definition RtAudio.h:268
RtAudio::getDefaultOutputDevice
unsigned int getDefaultOutputDevice(void)
A function that returns the ID of the default output device.
Definition RtAudio.h:915
RtAudio::getErrorText
const std::string getErrorText(void)
Retrieve the error message corresponding to the last error or warning condition.
Definition RtAudio.h:920
RtAudio::closeStream
void closeStream(void)
A function that closes a stream and frees any associated stream memory.
Definition RtAudio.h:916
RtAudio::openStream
RtAudioErrorType openStream(RtAudio::StreamParameters *outputParameters, RtAudio::StreamParameters *inputParameters, RtAudioFormat format, unsigned int sampleRate, unsigned int *bufferFrames, RtAudioCallback callback, void *userData=NULL, RtAudio::StreamOptions *options=NULL)
A public function for opening a stream with the specified parameters.
RtAudio::startStream
RtAudioErrorType startStream(void)
A function that starts a stream.
Definition RtAudio.h:917
stk::BeeThree
STK Hammond-oid organ FM synthesis instrument.
Definition BeeThree.h:43
stk::Instrmnt
STK instrument abstract base class.
Definition Instrmnt.h:20
stk::Messager
STK input control message parser.
Definition Messager.h:56
stk::StkError
STK error handling class.
Definition Stk.h:87
stk
The STK namespace.
Definition ADSR.h:6
RtAudio::StreamParameters
The structure for specifying input or output stream parameters.
Definition RtAudio.h:302
RtAudio::StreamParameters::nChannels
unsigned int nChannels
Definition RtAudio.h:305
RtAudio::StreamParameters::deviceId
unsigned int deviceId
Definition RtAudio.h:304
stk::Skini::Message
A message structure to store and pass parsed SKINI messages.
Definition Skini.h:43

A realtime control message will usually have a delta time of zero, in which case it is processed as soon as possible. Non-realtime messages, normally from a scorefile, will usually have non-zero delta times. The scheme used in this example is designed to work for both scorefile and realtime input types. When no message is available from the queue, the instrument is "ticked" for DELTA_CONTROL_TICKS and then the queue is checked again. The value of DELTA_CONTROL_TICKS roughly defines the program "control rate" in a realtime context, though multiple available messages in the queue are processed in immediate succession when their delta time values are zero.

The `processMessage()` function centralizes the handling of control messages. Other control update schemes can be implemented, perhaps using a separate thread or in the `main()` function, and this function should work in any context.

Assuming the program is compiled as `controlbee` and the SKINI scorefile `bookert.ski` is in the `scores` directory, the program can be run as:

controlbee scores/bookert.ski

Only a few basic SKINI message type case statements are included in this example. It is easy to extend the program to support a much more elaborate set of instrument control parameters.

This example could also be easily extended to accept "realtime" control input messages via pipe, socket or MIDI connections. The stk::Messager class provides stk::Messager::startStdInput(), stk::Messager::startSocketInput(), and stk::Messager::startMidiInput() functions for this purpose.

[Main tutorial page] [Next tutorial]

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