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.
• 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: Enables the cpal AudioBackend
• jack: 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
• 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.