Crate knyst

Knyst - audio graph and synthesis library

Knyst is a real time audio synthesis framework focusing on flexibility and performance. It’s main target use case is desktop multi-threaded real time environments, but it can also do single threaded and/or non real time synthesis. Embedded platforms are currently not supported, but on the roadmap.

The main selling point of Knyst is that the graph can be modified while it’s running: nodes and connections between nodes can be added/removed. It also supports shared resources such as wavetables and buffers.

Status

Knyst is in its early stages. Expect large breaking API changes between versions.

The name

“Knyst” is a Swedish word meaning very faint sound.

Architecture

The core of Knyst is the Graph struct and the Gen trait. Graphs can have nodes containing anything that implements Gen. Graphs can also themselves be added as a node.

Nodes in a running Graph can be freed or signal to the Graph that they or the entire Graph should be freed. Connections between Nodes and the inputs and outputs of a Graph can also be changed while the Graph is running. This way, Knyst acheives a similar flexibility to SuperCollider.

It is easy to get things wrong when using a Graph as a Gen directly so that functionality is encapsulated. For the highest level Graph of your program you may want to use RunGraph to get a node which you can run in a real time thread or non real time to generate samples. Using the audio_backends this process is automated for you.

Features

• unstable: Enables unstable optimisations in some cases that currently requires nightly.
• assert_no_alloc: (default) Panics in debug builds if an allocation is detected on the audio thread.
• debug-warn-on-alloc: Print a warning instead of panicing when allocating on the audio thread (debug build only).
• serde-derive: Enables some data structures to be serialized/deserialized using serde.
• cpal: (default) Enables the cpal AudioBackend
• jack: (default) Enables the JACK AudioBackend

Re-exports

pub use modal_interface::knyst_commands;

pub use resources::Resources;

Modules

audio_backend

Audio backends for getting up and running quickly. To use the backends in this module you need to enable either the jack or the cpal feature.

buffer

Loading sound files and other data and reading from them. Module containing buffer functionality:

controller

API for interacting with a running top level Graph from any number of threads without having to manually keep track of running Graph::update regularly.

envelope

A pretty barebones Envelope Gen

gen

A Gen is anything that implements the Gen trait and is the code of Knyst. Gen is short for Generator, often called unit generators in other contexts, a term that dates back to Max Mathews’ program MUSIC from 1957

graph

Graph is the audio graph, the core of Knyst. Implement Gen and you can be a Node.

handles

Handles are the preferred and most ergonomic way of interacting with Knyst, and may become the only way in the future.

inspection

Inspection

modal_interface

Knyst is used through a modal interface. A KnystSphere corresponds to a whole instance of Knyst. Spheres are completely separated from each other. The current sphere and active graph within a sphere is set on a thread by thread basis using thread locals. Most Knyst programs only need one sphere.

node_buffer

Knyst uses its own wrapper around a buffer allocation: NodeBufferRef. Buffers are only dropped from a non-audio thread once no pointers to the allocation persist using an application specific atomic flag mechanism.

offline

For running and inspecting the output of Knyst offline i.e. generating buffers of samples without automatically outputing them anywhere e.g. to a sound card.

prelude

Exports the most often used parts of Knyst

resources

Some Gens benefit from shared resources: Buffers for example Wavetables. Resources provides an interface to such shared resources.

scheduling

This module contains things related to scheduling that are more generic than graph internals.

sphere

A KnystSphere contains one instance of Knyst running on a backend. You can create multiple KnystSpheres in one program and switch between them using set_active_sphere, but most use cases require only one KnystSphere.

time

Structs for dealing with time with determinism and high accuracy in seconds and beats.

trig

Triggers

wavetable

Wavetable synthesis

wavetable_aa

Wavetable synthesis

xorrng

Simple pseudorandom number generator

Macros

inputs

Create an InputBundle using the syntax

Structs

BlockSize

BlockSize.

SampleRate

Newtype for a sample rate to identify it in function signatures. Derefs to a Sample for easy use on the audio thread.

Enums

KnystError

Combined error type for Knyst, containing any other error in the library.

Functions

amplitude_to_db

Convert amplitude to db

db_to_amplitude

Convert db to amplitude

Type Aliases

Sample

The current sample type used throughout Knyst

Trig

Marker for inputs that are trigs. This makes it possible to set that value correctly through a Handle.