Cabbage is a software for creating Csound based audio plugins. It also ships with a standalone host so that instrument can be tested and played without the need of a VST host. Cabbage provide a simple albeit powerful toolkit for the development of cross-platform audio software. Although the project is being developed with real time, non-score driven performance in mind it can be used to run just about any Csound file.

Running Cabbage

When you open Cabbage you will be met with a small blank screen. Clicking on the options button will give you a access to the following commands

Open

Use this command to open a cabbage patch(Unified Csound file with a dedicated Cabbage section). Any text editor or Csound frontend can be used to create Cabbage patches.

Update

Whenever you make any changes to the text in a Cabbage patch you can hit this command so that the changes are reflected in the Cabbage GUI and processing methods.

Export As Plugin

Use this command to export your Cabbage patch as a VST/AU plugin. You will be asked to give a name and location for your plugin. Cabbage will then create a plugin library and place a copy of your Cabbage patch in the same directory as the plugin. Cabbage patches must reside in the same directly as their equivalent plugins. For example if you have created a plugin call Amp, you must make sure that Amp.csd is in the same directory. If not your plugin will not run. The exported plugins do not have any menus so you will not have access to any of the Options you have in the Cabbage host.

Audio Settings

Clicking on the audio setting command will open the audio settings window. Here you can choose your audio/MIDI input/output devices. You can also select the sampling rate and audio buffer sizes. Small buffer sizes will reduce latency but might cause some drop outs. Keep testing buffer sizes until you find a setting that works best for your machine.

The Cabbage host uses its own audio IO callbacks which will override any audio and MIDI settings specified in the CsOptions sections of the cabbage patch.

View Csound Messages

Call this to display Csound output messages.

Note The Csound Message window is invaluable when it comes to debugging patches. Using one of the many print family of opcodes in Csound allows you to print useful information to this window while Csound is running.

Your first Cabbage patch

The following section illustrates the steps involved in building a simple Cabbage patch. It’s assumed that the user has some prior knowledge of Csound. For a list of Csound tutorials and resources please visit the Csound Homepage. When creating a Cabbage patch users must provide special xml-style tags at the top of a unified Csound file. The Cabbage specific code should be placed between an opening <Cabbage> and a closing </Cabbage> tag.

Each line of Cabbage specific code relates to one GUI control only and the syntax is non case-sensitive. Each and every Cabbage application must have a form widget. Calling a Form widget creates the main application window. Forms do not communicate with an instance of Csound, only child widgets and menus contained within a form can communicate with an instance of Csound.

Note This section does not go into details about each Cabbage widget. Details about the various widgets can be found in quick reference section.

Code to create the most basic of Cabbage applications looks like this:

<Cabbage>
form caption("Minimal Example") size(280, 40)
</Cabbage>
<CsoundSynthesizer>
<CsOptions>
-n -g
</CsOptions>
<CsInstruments>
sr = 44100
ksmps = 64
nchnls = 2

instr 1
a1 oscil 10000, 440, 1
outs a1, a1
endin

</CsInstruments>
<CsScore>
f1 0 1024 10 1
i1 0 1000
</CsScore>
</CsoundSynthesizer>
Note You’ll notice that a -n and -g were passed to Csound in the CsOptions section. -n stops Csound from writing audio to disk. This must be used as Cabbage manages it’s own audio IO callbacks. The -g prevents any fltk widgets from displaying. When running Cabbage patches as plugins you will need to be careful to ensure your instrument runs for long enough time. It’s probably useful to get into the habit of passing long durations to you i-statements.

Controlling your Cabbage patch

The biggest drawback with the application presented above is that users can not interact with the underlying Csound instrument. In order to do this we can use one of the channel opcodes and a IO widget such as a slider. When one wants to interact with Csound one must supply a channel parameter to the widget. Widget parameters can be either strings denoted with double quotes or float values. More information on different widget parameters is given below in the Quick Reference section.

When one supplies a channel name to a widget Csound will listen for data being sent on that channel through the use of the named channel opcodes. There are a few ways of retrieving data from the named channel bus, one such way is by using the chnget opcode defined in Csound as:

kval chnget Sname

Where Sname is the name of the channel that was passed as the channel parameter to the IO widget. We can modify our previous example so that a slider controls the frequency of our oscillator.

<Cabbage>
form caption("Minimal Example") size(280, 40)
hslider channel("freq"), pos(15, 23),  max(1500), caption("Frequency");
</Cabbage>
<CsoundSynthesizer>
<CsOptions>
csound  -odevaudio -b64 -B4096 temp.orc temp.sco
</CsOptions>
<CsInstruments>
sr = 44100
ksmps = 64
nchnls = 2

instr 1
kfreq chnget "freq"
a1 oscil 10000, kfreq, 1
outs a1, a1
endin

</CsInstruments>
<CsScore>
f1 0 1024 10 1
i1 0 100
</CsScore>
</CsoundSynthesizer>

Cabbage Widgets

Each and every Cabbage must be supplied with a value for top, left, width and height. They can be passed to a widget using the pos() and size() macros:

pos(top, left): position on screen in pixels

size(width, height): size of application in pixels their position on screen and their size.

Apart from position and size all other parameters are optional. If left out default values will be assigned. Certain widgets accept certain macros. For example groupbox and form both accepts a colour() macro to specify colour. Sliders accept a min and max values while other widgets don’t. A list of macros supported by each widgets is given in the Quick Reference section. Parameters can appear in any order and are not case-sensitive. Below is a list of the different GUI controls currently available in Cabbage.

Form

form caption("title"), pos(Top, Left), size(Width, Height)

caption: The string passed to caption will be the string that appears on the main application window.

Form creates the main application window. Top, Left, Width and Height are all integer values. The default values for size are 400x600. Forms do not communicate with an instance of Csound, only child widgets and menus contained within a form can communicate with an instance of Csound, therefore no channel identifier is needed.

Sliders

slider chan("chanName"), pos(Top, Left), size(Width, Height), min(float), max(float), value(float), kind("type"), caption("caption")

min: minimum slider value

max: maximum slider value

value: initial value for slider

kind: string denoted the type of slider, must be vertical or horizontal. Defaults to horizontal.

channel: string denoting the named channel upon which to communicate with Csound.

name: string denoting the parameter name that will appear in a VST host

Scrollbar creates a scrollbar/slider that can be used to send data to Csound on the channel specified through the chanName string. Min and Max will determine the slider range while value initialises the slider to a particular value. There are three types of slider widgets provided by Cabbage:

Horizontal slider = hslider Vertical slider = vslider Rotary/Pot slider = rslider

Presented above is the syntax for a horizontal slider. In order to change it to another slider type simple substitute hslider with the appropriate identifier.

Button

button channel("chanName"), pos(Top, Left), size(Width,Height), OnOffCaption("OnCaption","OffCaption")

onoffCaption: The button will toggle between on and off captions when the pressed.

Button creates a button on screen that can be used for a whole range of different tasks. The "channel" string identifies the channel on which the host will communicate with an instance of Csound. "OnCaption" and "OffCaption" determine the strings that will appear on the button as users toggles between two states, i.e., 0 or 1. By default these captions are set to "On" and "Off" but the user can specifiy any strings they wish.

CheckBox

checkbox channel("chanName"),  pos(Top, Left), size(Width, Height), value(val), caption("Caption")

caption: string that will appear beside checkbox

Checkbox creates a checkbox which functions like a button only the associated caption will not change when the user checks it. As with all controls capable of sending data to an instance of Csound the channel string is the channel on which the control will communicate with Csound. The value attribute defaults to 0 while the caption is set by default to the same name as the channel.

ComboBox

combobox channel("chanName"),  pos(Top, Left), size(Width, Height), value(val), items("item1", "item2", ...), caption("caption");

items: list of items that will populate combobox

Combobox creates a drop-down list of items which end-users can choose from. Once the user selects an item, the index of their selection will be sent to Csound on a channel named by the channel string. The default value is 0 and three items named "item1", "item2" and "item3" fill the list by default.

GroupBox

groupbox caption("Caption"), pos(Top, Left), size(Width, Height), colour("Colour")

Groupbox creates a container for other GUI controls. It does not communicate with Csound but is useful when it comes to organising different widgets.

Keyboard

keyboard pos(Top, Left), size(Width, Height)

Keyboard creates a piano keyboard that will send MIDI information to your Csound instrument. This is a useful components for testing synth plugins while running patches in the Cabbage host.

Note You can only have one keyboard widget on each patch.

Quick Reference

This quick reference table table gives a list of the paramters that each Cabbgea widget accepts. Positon and size are the only paramters you must include. All other parameters have default values.

Parameter Form Slider Button CheckBox GroupBox ComboBox
position x x x x x x
size x x x x x x
channel x x x x
min x
max x
value x x x
onoffCaption x
caption x x x
items x
colour x x x x x x

Troubleshooting FAQ

TODO…. Why does my plugin not work? (midi options command line flags) Why does my plugin sound crackly? (-m0d, -b etc…) Why does my host not see my plugin? (make sure the VST path is correct) etc…

Examples

TODO…. Below is an overview of the examples that come with Cabbage.

License

Cabbage is free software; you can redistribute it and/or modify it under the terms of the GNU Lesser General Public License as published by the Free Software Foundation; either version 2.1 of the License, or (at your option) any later version.

Cabbage is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public License for more details. You should have received a copy of the GNU Lesser General Public License along with Csound; if not, write to the Free Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA

Acknowledgements

This project would not have come to fruition without the help of everyone on the Csound mailing list and in particular Victor Lazzarini, John ffitch, Michael Goggins, Steven Yi, Andres Cabrera, Matt Goggins, Stefano Bonetti, Art Hunkins and Istvan Varga.