Klang C++ 0.7.15
Language Reference (draft)
Loading...
Searching...
No Matches
Getting Started

What is Klang?

klang is a language for the design and development of realtime audio processes in C++.

As a dialect of modern C++, klang enables synthesisers and effects to be written in clearer, more concise language, using the concept of streams and OOP to combine the performance of native C++ and clarity of visual/data-flow languages, such as block diagrams or patch-based tools like Max or PureData, and is designed to facilitate rapid prototyping of audio processing, as well as experimentation, knowledge sharing, and learning.

Designed for both professional and academic use, klang hopes to facilitate the sharing of DSP knowledge with the community-led development of an open library of reference examples.

  • Concise, accessible, and extensible language for audio processing.
  • Performance of native C++, with single sample or buffer-based processing.
  • Primitives for all common DSP components (oscillators, filters, etc.).
  • Compatible with C++17 compilers and IDEs.
  • A single header file, easily integrated with any new or existing C++ project.
  • Designed for knowledge sharing; supporting a growing repository of DSP examples.
  • Permissive open-source (attribution) licence.

‍ NOTE: The klang language is under active development, so syntax may change between pre-release versions.

Basic Concepts

To use klang in a C++ project, simply include the klang.h header file in your C++ project.

#include <klang.h>
using namespace klang::optimised;

Audio objects can be qualified with their namespaces (e.g. klang::Effect and klang::optimised::Sine). klang tries to use plain language to describe objects, so the namespace is used to avoid conflict with similar terms in other APIs or code. If this is not needed, add the using namespace directive as shown above.

The core data type in klang is signal, an extension of the basic C type float with additional audio and streaming functionality. In many cases, signals can be used interoperably with floats, facilitating integration of klang with other C++ code, while enabling signal-flow expressions, such as in the following wah-wah effect. Declare Sine lfo; and LPF lpf; as members of an Effect and put these lines in its process() method.

signal mod = lfo(3) * 900 + 1200;
in >> lpf(mod) >> out;

... where lpf is a low-pass filter, in is the input signal, out the output signal, and mod is a signal used to modulate the filter's cutoff frequency between 300 and 2,100 Hz, based on a low-frequency (3 Hz) sine oscillator (lfo).

DSP components, like oscillators or filters, are declared as objects (using struct or class) as either a Generator (output only) or Modifier (input / output), supplying functions to handle parameter setting (set()) and signal processing (process()) ...

struct OnePoleLPF : Modifier {
param a = 0.1, b = 0.9;
void set(param coeff) override {
a = coeff;
b = 1 - a;
}
void process() override {
(a * in) + (b * out) >> out;
}
};

Here, the Modifier parent class adapts the one-pole filter so it can be used in a signal chain. Its set() method takes a coefficient between 0 and 1. Parameters have type param, which is derived from signal, allowing constants, floats, or signals to be used interchangeably with or as parameters. Filters are often described in mathematical terms, so you could also write out = (a * in) + (b * out);.

More complex audio processes are created by combining klang objects, as in this voice for a simple subtractive synthesiser:

struct Subtractive : Note {
Saw osc;
LPF lpf;
Sine lfo;
event on(Pitch pitch, Amplitude velocity) override {
const Frequency frequency(pitch -> Frequency);
osc.set(frequency);
}
void process() override {
signal mod = lfo(3) * 900 + 1200;
osc >> lpf(mod) >> out;
}
};

This class supplies the Note definition to be used as part of a synthesiser (Synth - see the Examples linked below). It processes audio, but also handles events such as a note on, where the supplied pitch is converted to a frequency (in Hz) for use in the oscillator. By default, without code to handle a note off, the note and audio processing will be automatically terminated when one is received. In the synth constructor, use notes.add<Subtractive>(16) to register a pool of 16 voices.

But most instruments continue making sound after a note is 'released'...

struct Subtractive : Note {
Saw osc;
LPF lpf;
Sine lfo;
ADSR adsr;
event on(Pitch pitch, Amplitude velocity) override {
const Frequency frequency(pitch -> Frequency);
osc.set(frequency);
adsr.set(0.25, 0.25, 0.5, 5.0);
}
event off(Amplitude) override {
adsr.release();
}
void process() override {
signal mod = lfo(3) * 900 + 1200;
osc * adsr >> lpf(mod) >> out;
if (adsr.finished())
stop();
}
};
signals< 2 > signal
Stereo audio signal.
Definition klang.h:5840
auto mod(LEFT left, RIGHT right)
Return the C++ remainder for integers and the floating-point remainder otherwise.
Definition klang.h:3881

This example shapes the note and adds a release stage using an ADSR amplitude envelope. The ADSR is a type of Envelope that takes four parameters (attack, decay, sustain, release - set in on()) and uses its output to scale the amplitude of the signal. The times are in seconds and sustain is a linear level. Reading adsr in the expression advances it by one sample. To add the 'release' stage and continue processing audio after a note off, we override the off(Amplitude) event and trigger the release of an ADSR envelope. Now, process() will continue to be called until you tell it to stop(), which we call when the ADSR is finished (that is, adsr.finished() is true).

For further techniques, see the Examples below.

Examples

The /examples folder contains an evolving selection of examples (and tests). Start with these core examples:

See the Examples page for the full collection. For more complex patches, see SuperSaw.k, DX7.k and SynTHX.k in the root of the examples folder.

Usage in a C++ project

This object defines the processing for a single synth note that can then be used in any audio C++ project. Place the following code fragments at the appropriate points in your host code. Set klang::fs to the host sample rate in the translation unit that runs the DSP.

Subtractive note;
klang::Note& voice = note;
voice.start(pitch, velocity); // Note On
voice.release(); // Note Off
klang::buffer buffer = { pfBuffer, numSamples };
if (!voice.finished())
voice.process(buffer);
bool finished() const
Definition klang.h:5623
virtual void start(Pitch p, Velocity v)
Definition klang.h:5598
virtual bool release(Velocity v=0)
Definition klang.h:5606
Audio buffer (mono)
Definition klang.h:2610
Synthesiser note (mono)
Definition klang.h:5633
virtual void process() override=0

The buffer wraps the host’s mono sample array. The voice adds its output to the buffer, so clear it before mixing voices into an empty output block.

More information

For more information about the project, or to get involved, email Chris Nash (klang@nash.audio).