AllCsnd manual

Creating a plugin involves creating a folder with:

• a Csound file (extension csd ) containing the DSP code in Csound language;
• a json file (extension json) describing the plugin UI and parameters;
• a copy of the executable or a link to:
  • AllCsndSY for a Jack synthesizer plugin;
  • AllCsndSY-vst.so for a VST2 synthesizer plugin;
  • AllCsndFX for a Jack effect plugin;
  • AllCsndFX-vst.so for a VST2 effect plugin.

For example, in the folder Examples/Flute, for a Jack synthesizer :

$ ln -s  ln -s ../../../bin/AllCsndSY/AllCsndSY Flute
$ tree .
.  
├── AllCsndSY -> ../../../bin/AllCsnd/AllCsndSY
├── Flute.csd
└── Flute.json

For an Effect just replace AllCsndSY by AllCsndFX.

With a modern linux box installed with Pipewire, the plugin can be launched as a standalone application very easily from the repository containing the json file, the Csound file, and the link to the executable AllCsndSY. First, make sure that the pipewire-jack package is installed. Similarly, to have a Jack virtual MIDI keyboard, you need to install the jack-keyboard package and finally qpwgraph to manage connections between plugins, audio devices, and MIDI devices. Finally, simply launch the plugin as follows:

$ cd Flute
$ tree
. 
├── Flute -> ../../../bin/AllCsndSY/AllCsndSY
├── Flute.csd
└── Flute.json

1 directory, 3 files
$  pw-jack ./Flute

From your Digital Audio Workstation's plugin manager, simply specify the executable file or the link to the executable file in the directory containing the plugin.

As its name suggests, this section contains the options that will be passed to the processor Csound., cf. https://csound.com/docs/manual/CommandFlags.html .

Most options do not make sense in the context of a plugin. Those that are mandatory for the plugin to work properly are placed directly in the plugin code without needing to be included in the Csound file.

csound->SetOption((char *)"-M0 -Q0");
csound->SetOption((char *)"-b0");
csound->SetOption((char *)"-+rtmidi=NULL");

The first directive is clearly mandatory for the CSound processor to accept MIDI messages. The usefulness of the other two is less obvious and requires further investigation.

Finally, the <CsOPtions> section is empty.

This is the main section which describe the CSound process. The section start with some mandatory initialization :

; Initialize the global variables
ksmps = 32
nchnls = 2
0dbfs = 1

The first parameter can be adjusted as needed, but the other two parameters must be set as indicated:

• The number of audio channels cannot be dynamically configured and is fixed at two.
• The amplitude must be consistent between the plugin and the host, which imposes an amplitude scale Odbfs.

The main part of the CsInstruments section is constituted by Opcode (UDO) and Instr (Instrument) definition. A template for synthesizer and one for effect are presented below.

Csound normally runs the CsScore section of the score using the instruments described in the CsInstruments section, then stops. However, in the context of a plugin, the Csound process must be ready to process MIDI messages and audio streams in real time as long as the plugin remains loaded by the host.

The instrument described above and the following instruction allow the Csound process to remain active for a very long time, approximately 7000 years:

;Run instrument for about 7000 years...
i "InstName" 0 z

A text widget simply displays a string. It admits the following properties:

Type

mandatory string set to "text"

Text

mandatory string

Example:

{
  "Type": "text",
  "Text": "Here is a nice text"
}

A separatorline widget draw a thin horizontal line with a optional string. It admits the following properties:

Type

mandatory string set to separatorline

Text

optional string

Example:

{
  "Type": "separatorline",
  "Text": "Here is a nice text"
}

By default, widgets are arranged one below the other. The “sameline” widget allows you to position the next widget horizontally after the previous one :

Type

mandatory string set to sameline

Example:

[
  {
    "Type": "knob",
    "Param": {
      ...
    }
  }
  {
    "Type": "sameline"
  }
  {
    "Type": "knob",
    "Param": {
      ...
    }
   }
]

The toggle widget associated to a plugin parameter is defined with the following properties:

Type

mandatory string set to toggle

Height

optional integer, 20 pixel by default - controls the height of the toggle widget

Width

optional integer, 30 pixel by default - controls the width of the toggle widget

Flags

optional enum, animated | borderedFrame by default - controls the widget's graphical rendering using one or more of the following values:

• animated
• borderedFrame
• borderedKnob
• shadowedFrame
• shadowedKnob

Param

mandatory - object parameter associate to the widget;

ChnName

mandatory string - identifies the Csound software bus associated with the parameter, as well as the plugin host's parameter. This name is required and must be unique within the plugin; it must follow the pattern ^[a-z,A-Z][,a-z,A-Z,0-9]*

Name

optional, chnName by default - character string defining the name of the parameter that will appear at the left of the toggle in the plugin's graphical user interface and the host interface

Hints

optional, none by default - defines the properties of the parameter among:

• automatable : if set, the parameter can be controlled by the host (real-time safe)
• isBoolean : the value of the parameter is Boolean.
• isHidden : the parameter is hidden on the host and visible only in the plugin's graphical user interface.

DefVal

optional, 0 by default - toggle is off

MidiCC

optional integer between [32..120], 0 by default which means that no MIDI control is associated - defines the number of the MIDI control associated to the parameter

Example :

{
  "Type": "toggle",
  "Param" : {
    "ChnName" : "kByPass",
    "Name":"ByPass",
    "DefVal" : 0,
    "Hints" : ["isAutomatable","isBoolean"]
  },
  "Height": 30,
  "Width": 40,
  "Flags": ["animated", "borderedFrame", "borderedKnob"]
}

The button widget is associated to a plugin parameter. Then button is on, the button is more light. The button widget have the following properties:

Type

mandatory string, set to button

Height

optional integer, 20 pixel by default - controls the height of the toggle widget

Width

optional integer, by default the width of the name on the button

Param

mandatory object parameter associate to the widget;

ChnName

mandatory string - identifies the Csound software bus associated with the parameter, as well as the plugin host's parameter. This name is required and must be unique within the plugin; it must follow the pattern ^[a-z,A-Z][,a-z,A-Z,0-9]*

Name

optional string, ChnName by default. it's the name of the parameter that will appear on the button in the plugin's graphical user interface and the host interface

Hints

optional, none by default - defines the properties of the parameter among:

• automatable : if set, the parameter can be controlled by the host (real-time safe)
• isBoolean : the value of the parameter is Boolean.
• isHidden : the parameter is hidden on the host and visible only in the plugin's graphical user interface.

DefVal

optional, 0 by default - button is off

MidiCC

optional integer between [32..120], 0 by default which means that no MIDI control is associated - defines the number of the MIDI control associated to the parameter

Example :

{
  "Type": "button",
  "Height": 30,
  "Width": 100,
  "Param" : {
    "ChnName" : "kButton",
    "Name": "MyButton",
    "Hints" : ["isAutomatable","isBoolean"],
    "DefVal" : 0,
    "MidiCC": 0
  }
}

The radio widget associated to a plugin parameter is defined with the following properties:

Type

mandatory string set to radios

Items

mandatory array of string one for each radio item

Horizontal

optional boolean, true by default; radio items are on the same line

Param

mandatory object plugin's parameter associate to the widget;

ChnName

mandatory string, identifying the Csound channel software bus associated with the parameter as well as the parameter for the plugin host. This name is mandatory and unique at the plugin level and must follow the pattern ^[a-z,A-Z][,a-z,A-Z,0-9]*

Name

optional string, ChnName by default. This string define the name of the parameter that will appear on the host interface

Hints

optional, none by default - defines the properties of the parameter among:

• automatable : if set, the parameter can be controlled by the host (real-time safe)
• isBoolean : the value of the parameter is Boolean.
• isHidden : the parameter is hidden on the host and visible only in the plugin's graphical user interface.

DefVal

optional, 0 by default - the index of the radio on

MidiCC

optional integer between [32..120], 0 by default which means that no MIDI control is associated - defines the number of the MIDI control associated to the parameter

{
  "Type": "radios",
  "Items": ["radio1","radio2", "radio3"],
  "Horizontal": true,
  "Param" : {
    "ChnName" : "kRadios",
    "DefVal" : 1.0,
    "Hints" : ["isAutomatable","isInteger"]
  }
}

The combo widget associated to a plugin parameter is defined with the following properties:

Type

mandatory string set to combo

Labels

mandatory array of string of items

NbItemsWindow

optional integer, by default, all items are presented when combo is opened; otherwise NbItemsWindow items are presented

Param

mandatory object plugin's parameter associate to the widget;

ChnName

mandatory string - identifies the Csound software bus associated with the parameter, as well as the plugin host's parameter. This name is required and must be unique within the plugin; it must follow the pattern ^[a-z,A-Z][,a-z,A-Z,0-9]*

Name

optional string, ChnName by default. This string define the name of the parameter that will appear on the plugin and the host interface

Hints

optional, none by default - defines the properties of the parameter among:

• automatable: if set, the parameter can be controlled by the host (real-time safe)
• isInteger: index of selected item is an integer
• isHidden: the parameter is hidden on the host and visible only in the plugin's graphical user interface.

DefVal

optional, 0 by default - the index of the selected item

MidiCC

optional integer between [32..120], 0 by default which means that no MIDI control is associated - defines the number of the MIDI control associated to the parameter

{
  "Type": "combo",
  "Items": ["combo1","combo2", "combo3", "combo4", "combo5"],
  "NbItemsWindow": 3,
  "Param" : {
    "ChnName" : "kCombo",
    "DefVal" : 1.0,
    "Hints" : ["isAutomatable","isInteger"]
  }
}

The horizontal slider is defined with the following properties :

Type

mandatory, set to hSlider

Width

optional, takes up the available width by default - controls the width of the slider. the height is determined by the font size

NoImput

optional boolean, false by default. Then true, disable CTRL + Click or Enter key allowing to input text directly into the widget.

Param

mandatory objet which describe the parameter associate to the widget

ChnName

mandatory string - identifies the Csound software bus associated with the parameter, as well as the plugin host's parameter. This name is required and must be unique within the plugin; it must follow the pattern ^[a-z,A-Z][,a-z,A-Z,0-9]*

Name

optional, ChnName by default - character string defining the name of the parameter that will appear in the plugin's graphical user interface and the host interface.

Unit

optional string, "" by default - defining the unit in which the parameter value is expressed, for example “dB,” “kHz,” and “ms.” The unit is used by the host and plugin graphical user interface.

Hints

optional, none by default - defines the properties of the parameter among:

• automatable: the value of the parameter can be controlled by the host (real-time safe)
• isLogarithmic: the value changes on a logarithmic scale.
• isOutput: the parameter value is output, meaning that the parameter can be modified by the plugin but not by the host. By default, a parameter is input, meaning that it is modified via the host using the plugin's graphical interface or a MIDI controller.
• isHidden: the parameter is hidden on the host and visible only in the plugin's graphical user interface.

MinVal

optional, 0 by default - minimum value of the parameter

MaxVal

optional, 1 by default - maximum value of the parameter

DefVal

optional, 0 by default - parameter value when launching the plugin

PrecVal

optional, 2 by default - precision of the parameter value, default two digits after the decimal point

MidiCC

optional integer between [32..120], 0 by default which means that no MIDI control is associated - defines the number of the MIDI control associated to the parameter

Note that value is to min/max bounds when input manually with CTRL+Click.

Here a example of an horizontal slider widget:

{
  "Type": "hSlider",
  "Width": 200,
  "NoImput": true,
  "Param" : {
    "ChnName" : "khSlider1",
    "Name":"hSlider1",
    "DefVal" : 0.6,
    "PrecVal" : 2,
    "MidiCC" : 101,
    "Hints" : ["isAutomatable", "isLogarithmic"]
  }
}

The horizontal slider is defined with the following properties; value of the slider appears as a tooltip ;

Type

mandatory, set to vSlider

Height

optional integer, 100 by default - controls the height of the slider

Width

optional integer, 14 by default - controls the width of the slider

NoImput

optional boolean, false by default. Then true, disable CTRL + Click or Enter key allowing to input text directly into the widget.

Param

mandatory objet which describe the parameter associate to the widget

ChnName

mandatory string - identifies the Csound software bus associated with the parameter, as well as the plugin host's parameter. This name is required and must be unique within the plugin; it must follow the pattern ^[a-z,A-Z][,a-z,A-Z,0-9]*

Name

optional, ChnName by default - character string defining the name of the parameter that will appear in the plugin's graphical user interface and the host interface.

Unit

optional string, "" by default - defining the unit in which the parameter value is expressed, for example “dB,” “kHz,” and “ms.” The unit is used by the host and plugin graphical user interface.

Hints

optional, none by default - defines the properties of the parameter among:

• automatable: the value of the parameter can be controlled by the host (real-time safe)
• isLogarithmic: the value changes on a logarithmic scale.
• isOutput: the parameter value is output, meaning that the parameter can be modified by the plugin but not by the host. By default, a parameter is input, meaning that it is modified via the host using the plugin's graphical interface or a MIDI controller.
• isHidden: the parameter is hidden on the host and visible only in the plugin's graphical user interface.

MinVal

optional, 0 by default - minimum value of the parameter

MaxVal

optional, 1 by default - maximum value of the parameter

DefVal

optional, 0 by default - parameter value when launching the plugin

PrecVal

optional, 2 by default - precision of the parameter value, default two digits after the decimal point

MidiCC

optional integer between [32..120], 0 by default which means that no MIDI control is associated - defines the number of the MIDI control associated to the parameter

Note that value is to min/max bounds when input manually with CTRL+Click.

Here a example of anvertical slider widget:

{
  "Type": "vSlider",
  "Height": 200,
  "Width": 14,
  "NoImput": true,
  "Param" : {
    "ChnName" : "kvSlider1",
    "Name":"vSlider1",
    "DefVal" : 0.6,
    "PrecVal" : 2,
    "MidiCC" : 101,
    "Hints" : ["isAutomatable", "isLogarithmic"]
  }
}

The knob widget is defined with the following properties :

Type

mandatory string, set to knob

Variant

optional enum, wiper by default - controls the widget's graphical rendering using one of the following values: ( https://github.com/altschuler/imgui-knobs )

• wiper
• tick
• dot
• wiperOnly
• wiperDot
• stepped
• space

Size

optional integer, 48 pixel by default - controls the size of the Knob widget

Flags

optional enum, none by default - changes the appearance and functionalities offered by the widget

• noTitle: hide the title above the widget
• noInput : Hide the input field below the widget
• valueTooltip: displays a tooltip containing the current value of the parameter when the mouse pointer hovers over it
• dragHorizontal: Only horizontal movement of the mouse pointer changes the parameter value (by default, the change is bidirectional).

Steps

optional integer, 0 by default - determines the number of graduations that will be displayed for a widget Knob (variant = "stepped")

Speed

optional float, 0 by default - Amplitude of the pointer's movement from the minimum to the maximum value

Param

mandatory object which describe the parameter associate to the widget;

ChnName

mandatory string - identifies the Csound software bus associated with the parameter, as well as the plugin host's parameter. This name is required and must be unique within the plugin; it must follow the pattern ^[a-z,A-Z][,a-z,A-Z,0-9]*

Name

optional string, ChnName by default - defines the name of the parameter that will appear in the plugin's graphical user interface and the host interface.

Unit

optional string, "" by default - defines the unit in which the parameter value is expressed, for example “dB,” “kHz,” and “ms.” The unit is used by the host and plugin graphical user interface.

Hints

optional enum, none by default - defines the properties of the parameter among:

• automatable: the value of the parameter can be controlled by the host (real-time safe)
• isLogarithmic: the value changes on a logarithmic scale.
• isOutput: the parameter value is output, meaning that the parameter can be modified by the plugin but not by the host. By default, a parameter is input, meaning that it is modified via the host using the plugin's graphical interface or a MIDI controller.
• isHidden: the parameter is hidden on the host and visible only in the plugin's graphical user interface.

MinVal

optional float, 0 by default - minimum value of the parameter

MaxVal

optional float, 1 by default - maximum value of the parameter

DefVal

optional, float, 0 by default - parameter value when launching the plugin

PrecVal

optional int, 2 by default - precision of the parameter value, default two digits after the decimal point

MidiCC

optional integer between [32..120], 0 by default which means that no MIDI control is associated - defines the number of the MIDI control associated to the parameter

The following properties proposed by ImGuiKnob are not implemented : angle_min, angle_max.

Here a example of a widget Knob :

{
  "Type": "knob",
  "Variant": "stepped",
  "Size" : 0,
  "Flags" : [
    "noTitle",
    "noInput",
    "valueToolTip"
  ],
  "Step" : 10,
  "Param" : {
    "ChnName" : "kknob2",
    "Name":"knob2",
    "DefVal" : 0.35,
    "PrecVal" : 2,
    "MidiCC" : 116,
    "Hints" : ["isAutomatable"]
  }
}

A block widget allows you to group a set of widgets together so that they form a single unit for placement within the window. it admits the following properties:

Type

mandatory string set to block

Height

optional integer, 0 pixel by default - controls the height of the toggle widget. If 0 then auto sizing

Width

optional integer, 0 pixel by default - controls the width of the toggle widget. If 0 the auto sizing

Flags

optional enum, none by default - defines the properties of the parameter among:

• borders: show an outer border and enable WindowPadding
• frameStyle: Style the child window like a framed item: use FrameBg, FrameRounding, FrameBorderSize, FramePadding instead of ChildBg, ChildRounding, ChildBorderSize, WindowPadding
• navFlattened: Share focus scope, allow keyboard/gamepad navigation to cross over parent border to this child or between sibling child windows.

Widgets

An array of widgets inside the block widget

Example:

{
  "Type": "block",
  "Width": 70,
  "Height": 205,
  "Flags" : ["borders", "navFlattened"],
  "Widgets" : [
    ...
  ]
}

In general, a widget parameter supports the following properties:

ChnName

mandatory - string identifying the Csound channel software bus associated with the parameter as well as the parameter for the plugin host. This name is mandatory and unique at the plugin level and must follow the pattern ^[a-z,A-Z][,a-z,A-Z,0-9]*

Name

optional, chnName by default - character string defining the name of the parameter that will appear in the plugin's graphical user interface and the host interface.

Unit

optional, "" by default - character string defining the unit in which the parameter value is expressed, for example “dB,” “kHz,” and “ms.” The unit is used by the host and plugin graphical user interface.

Hints

optional, none by default - defines the properties of the parameter among:

• isAutomatable: the value of the parameter can be controlled by the host (real-time safe)
• isBoolean: the value of the parameter is Boolean.
• isInteger: the value of the parameter is an integer.
• isLogarithmic: the value changes on a logarithmic scale.
• isOutput: the parameter value is output, meaning that the parameter can be modified by the plugin but not by the host. By default, a parameter is input, meaning that it is modified via the host using the plugin's graphical interface or a MIDI controller.
• isHidden: the parameter is hidden on the host and visible only in the plugin's graphical user interface
• isTrigger: Parameter value is a trigger. This means the value resets back to its default after each process/run call. Cannot be used for output parameters. Note only officially supported under LV2.

MinVal

optional, 0 by default - minimum value of the parameter

MaxVal

optional, 1 by default - maximum value of the parameter

DefVal

optional, 0 by default - parameter value when launching the plugin

PrecVal

optional, 2 by default - precision of the parameter value, default two digits after the decimal point

MidiCC

optional integer between [32..120], 0 by default which means that no MIDI control is associated. A value of 0 or 32 (bank change) is considered invalid. Must also be less or equal to 120. This value is only a hint! Hosts might map it automatically or completely ignore it.

The possibilities offered for characterizing the parameters are not being fully exploited at this time. This can be completed later :

EnumValue

parameter whose values are among an enumeration.

Designation

What is it for?

GroupID

What is it for?

Here is an example of the parameter section of a widget; “idetk” also appears in the Csound code:

"Param" : {
  "ChnName" : "idetk",
  "Name":"Decay",
  "DefVal" : 0.1,
  "PrecVal" : 2,
  "Unit" : "s",
  "MidiCC" : 102,
  "Hints" : ["isAutomatable"]
} 

Note: MIDI control messages are fully supported by the AllCsnd code, which directly updates the associated parameter values. The MIDI controls must be configured to operate in Relative mode: the knob will send values 61-63 when turned in a negative direction and values 65-67 when turned in a positive direction. Arturia's MiniLab MkII can work this way. This approach eliminates the problem of initializing the control in accordance with the parameter value. Therefore, MIDI control messages are neither sent nor processed by the Csound processor; only note messages are transmitted to the Csound processor.