REF / Music API / Anode

Anode == "audio node"

Anodes are responsible for synthesizing or processing audio signals. Each Anode instance represents either an instance of a CLAP plugin or a built-in Modulator or Audio node. Anodes can respond several categories of methods. The categories that are central to most user-programs are the Note and Parameter families detailed below.

After creation, Anodes must be organized into an Agraph to define your audio scene. Usually you'll create and connect Anodes via the higher level Ascene methods.

Example

let scene = await Ascene.BeginThread(this); // ensure audio engine is ready
// create two Anodes
let n1 = scene.NewAnode("Vital");
let n2 = scene.NewAnode("Hz.Mix");
// find the system output Anode
let out = scene.GetDAC();
// establish our audio connections
scene.Chain(n1, n2, out);
await ascene.Sync(); // wait for Anode and Agraph updates
n2.SetParam("gain", -2); // set Hz.Mix parameter (dB)

n2.NoteOn(35, .8); // play MIDI note 35, with velocity .8
await scene.Wait(scene.Seconds(.25)); // hold the note for 1/4 second
n2.NoteOff(35, 0); // release the note

Anode functions

You can programatically query the capabilities of a plugin with these functions. After working with a plugin you quickly learn its capabilities and you may be able to configure them during Anode instantiate and seen here.

* example output for Hz.Mix

[ 
 {"id":0,"name":"mono","nin":2,"nout":1,"hasMainIn":true,"mainInNch":1,"mainInType":"mono","hasMainOut":true,"mainOutNch":1,"mainOutType":"mono"},
 {"id":1,"name":"stereo","nin":2,"nout":1,"hasMainIn":true,"mainInNch":2,"mainInType":"stereo","hasMainOut":true,"mainOutNch":2,"mainOutType":"stereo"} 
]

Anode methods

General

Notes and MIDI Events

* returns [noteId, voiceid?] useful for passing to NoteExpressions and Voices methods.

Parameters

Anode parameters control the built-in synthesis or processing algorithm. CLAP parameter changes are either Set or Modulate. The resulting parameter value is the sum of the two. Parameter changes can be associated with an individual note or apply globally. Some Anodes (eg Vital, Surge XT) have more than 750 parameters. That's a lot of parameters.

• a parameter id (pid) can be either its name or its id.

Presets and State

You can control the setting of a CLAP Plugin instance in bulk through the use of Presets or by restoring a previously saved state. These operations may interupt an active plugin so usually you'll invoke these prior to song performance. Also, since these methods access your local disk, they are asynchronous (more here).

If your audio scene contains multiple anodes you would theoretically need to save the state of each to preserve sufficient information to recreate the scene. This is the way that most DAWs operate. In the context of Hz, you can recreate this behavior with your scripts but it's more common to create state or presets incrementally on a per-node basis and then load all states during your startup. In other words there is no single scene-wide state file.

* Presets differ by CLAP Plugin. Hz's built-in plugins accept a parameter-value dictionary as a JSON string. FluidSynth accepts a pathname to a soundfont. Other plugins: YMMV.

** Plugins may also offer save & restore options in their GUI so you may find it easier to save states that way, then use RestoreState at startup.

Here you can find some examples of this methods.

GUI

GUI refers to the optional user interface window or panel for the Anode. GUIs can either be window-base or webview. The latter is currently specific to Hz plugins and these guis appear in Hz tabbed-window-panels.