Page  1 ï~~TWO CROSS-PLATFORM CSOUND-BASED PLUGIN GENERATORS Victor Lazzarini An Grufipa Theicneolaiocht Fuaime agus Ceoil Dhigitigh National University of Ireland, Maynooth, Ireland, ABSTRACT This article describes two new plugin generators for the development of effects and instruments using the Csound audio programming language, csLADSPA and csVST. It discusses the basics of these two systems, exploring some of their internal aspects. The text continues on to show three basic examples, two plugin effects and one synthesis instrument. These demonstrate both time-domain and spectral processes. The article concludes with a look at specific details of operation of the two plugin generators. 1. INTRODUCTION The availability of a variety of plugin models and host applications has provided fertile ground for the development of audio effects. Such systems allow programmers to concentrate on the signal processing tasks at hand, as they provide all the infrastructure for audio input and output, as well as a model for the creation of software components. In this article, we will go a step further by providing the plugin developer with a full complement of signal processing operators, unit generators, from a widely adopted system, Csound[ 1]. In this scenario, a plugin designer can avail of already existing components to build his/her own effects or instruments. The generators presented here support the creation of plugins under two major systems: a Free-software one, the Linux Audio Developer's Simple Plugin API (Application Programming Interface) (LADSPA)[7] and a commmercial system, the Virtual Studio Technology (VST) [8]. Plugins for both systems can be created using the same code, interchangeably, as they are solely based on the Csound language. 1.1. The Csound host API The main component of the systems presented here is the Csound 5 library (libcsound), accessed through its API. Libcsound is a fully-reentrant object-oriented library, allowing any number of instances of the audio processing engine to be run concurrently. The library can be programmed using a variety of languages. For the present systems, we will be employing its C++[5] API. Communication between a Csound instance and the host for control messages is enabled by the software bus. This is based on a system of input/output channels, referenced by name and managed by engine. Once a channel is created, either using Csound code or via an Rory Walsh, Martin Brogan Music Department Dundalk Institute of Technology ro..walsh API call, it can be used to send control data to a running instance. In the present systems, audio data is sent to the main input buffer of Csound and collected from the main output buffer. This implies that the number of channels of a plugin is defined as a global constant in the Csound code. However, the sampling rate and vector size will be determined by the plugin host, overriding any values defined by Csound. The API is also responsible for loading and compiling all Csound code. 2. THE PLUGIN GENERATORS csLADSPA uses the LADSPA format. This plugin model came to fruition in early 2000 following the combined efforts of Paul Davis, Richard Furse, and Stefan Westerfield. LADSPA provides developers with a simple way of developing audio plugins which can be loaded by a wide range of host applications. CsVST uses the VST plugin format. There are, in fact, two types of VST plugins supported by csVST: csVSTfx and csVSTi. The first one is used for general-purpose audio effects and the second for synthesiser instruments. The VST plugin framework is ubiquitous in the commercial music software market, therefore csVST should be of great utility to many users. 2.1. The inside bits csLADSPA and csVST are not themselves the plugins, but plugin generators. They will create, in a host, any number of plugins written by the user. Each one of these will be linked to a particular Csound orchestra/score. Plugins are created when csLADSPA (or csVST) is loaded by the host. In the case of csLADSPA, the generator will then provide one plugin for each Csound code file found in a pre-defined directory. For csVST plugins, the Csound code will be appended to the dynamic-loadable module (MS-Windows) or included in a bundle (OS X). As mentioned above, the number of audio channels for a plugin and its controls is determined by the Csound code. A number of extra XML tags have been defined for some of these tasks. Once plugins are created, they will generally be displayed on a list by the host, from where they can be instantiated and run. A basic model of how the plugins work is shown in below (fig. 1). The host application loads the csLADSPA or csVST-created plugin. This will instantiate a Csound object and compile its associated orchestra/score code.

Page  2 ï~~When the user processes audio through it, the plugin will route the input audio to that instance of Csound. This will then process this audio and return it to the plugin which will then route that audio to the host application. Figure 2 shows a plugin in operation in the host application Audacity. Figure 1. csLADSPA/csVST plugin structure For this to happen, calls are made to the Csound:: PerformKsmps () method, which is responsible for processing or generating one vector full of samples. These, in turn, are shifted in and out of the main Csound buffers to/from the host buffers. In the case of synthesizer instrument plugins (csVSTi), MIDI communication between the host and Csound is also provided through API calls. In this case, Csound instruments will be instantiated by realtime MIDI events sent in by the host. Tags Description Name The name of the plugin as it will appear in the host application Maker Author of plugin UniquelD ID given to plugin, each plugin should use a unique ID. Copyright Copyright/Licence notice ControlPort The name of the control as it appears when the plugin is ran and the name of the channel which Csound will retrieve the data on. The two names should be separated by a '|' symbol. Range Plugin max/min range. Again the two values are separated by a '|' symbol. If users wish to controls to respond logarithmically they can add a '&log' after they specify the range values. Table 1. Plugin tags ControlPort and Range tags are optional, but the former always requires the latter. Examples of how these tags are used can be seen in the next section. 3. EXAMPLES In the following section two csLADSPA plugins are presented. The first illustrates the mechanisms for communication between the host and the csLADSPA plugin. The other plugin makes use of some of the more advanced opcodes included with Csound5, i.e., the PVS[2] opcodes. 3.1. An Adaptive FM effect The first example features an effect based on Adaptive Frequency (AdFM) [3]. This technique uses an input audio signal as a carrier in a frequency modulation synthesis algorithm. The signal is put through a variable delayline and modulated with a sinusoidal oscillator. The AdFM effect is implemented by a User-Defined Opcode. This plugin will require two control ports, one for the index of modulation and another for the carrier:modulator frequency ratio: <csLADSPA> Name=AdFM Maker-Lazzarini, Walsh & Brogan UniquelD=1054 Copyright-None ControlPort=Modulation Index index Range=0 5 ControlPort=Car-mod ratio | ratio Range=0.5 2 </csLADSPA> <CsoundSynthesizer> <csInstruments> opcode DFM, a,akki setksmps 1 as,krt,knx, ifn xin kcps,kamp ptrack as,1024 adt oscili knx/ ($M PI*kcps),kcps/krt,ifn adp delayr 1 /* delay line */ Figure 2. A csLADSPA plugin in Audacity. 2.2. Plugin tags Plugins will use the unified file format (CSD) for reading Csound code. In these files, the user must specify some basic information about the plugin, in the form of XML tags (table 1). This is done by adding a section in the CSD file whereby the user can specify things like the name of the plugin, the author, etc. It is in this section that the user can also specify the control ports they will need in order to interact with their Csound code when running the plugin through a host. This section will be defined inside <csLADSPA>, <csVSTfx> or <csVSTi>, for LADSPA, VST effects and VST instruments, respectively.

Page  3 ï~~adel deltap3 adt xout adel endop 2/sr instr I knx chnget "index" krt chnget "ratio" ain in al DFM ain,krt,knx, out al endin </CsInstruments> <CsScore> fl 0 16384 20 2 i1 0 36000 </CsScore> </CsoundSynthesizer> instr 1 imaxdel chnget "del" iblurtime chnget "blur" asig in fsig pvsanal asig, 1024, 256, 1024, ftps pvsblur fsig, 0.2, 0.2 atps pvsynth ftps out atps endin As previously mentioned the means of communication between the plugin and the instance of Csound is provided by the software bus. In Csound we can use the chnget opcode to retrieve data from a particular bus channel. In the case above this data is used to control the different parameters as defined by the Range tag in the <csLADSPA> section of the above code. </CsInstruments> <CsScore> fl 0 1024 10 1 i1 0 3600 </CsScore> </CsoundSynthesizer> 3.3. A Split-Sideband synthesis instrument The following code will create a synthesiser, using the Split-Sideband algorithm[4], that accepts MIDI messages sent from the host application. MIDI is routed from the host to the plugin through the use of the -midi-key-cps flag which is passed to the CsOptions section of the csd file. This sends all note-on messages MIDI byte 2 to pfield 4, converting them to Hz, where they can easily be retrieved in the instrument code. As standard envelopes do not work well with indefinited duration events, we will use the extended 'r' family of evelopes. These can sense a turnoff event (such as a MIDI noteoff) and extend the performance time of the current instrument. In the case of linenr, an exponential decay is applied to the endportion of the envelope (its 'release'). <csVSTi> Name=SpSB Synth Maker=Lazzarini, Walsh & Brogan UniqueID=5961 Copyright=None ControlPort=Car-Mod Ratio kratio Range=0.5|2 ControlPort=Mod-Index kindx Range=0i20 </csVSTi> <CsoundSynthesizer> <CsOptions> -+rtmidi=null -MO -m0d --midi-key-cps=5 \ --midi-velocity-amp=4 </CsOptions> <CsInstruments> ksmps=32 nchnls=2 Figure 3. The PVS blur-based plugin in Soundforge 8.0 3.2. A spectral manipulation plugin Csound5 comes with a host of new Phase Vocoder Streaming, PVS, opcodes. These opcodes provide users with a means of manipulating spectral components of a signal in realtime. This plugin averages the amp/freq time functions of each analysis channel for a specified time. <csVSTfx> Name=PVSBlur Maker=Lazzarini, Walsh & Brogan UniqueID=1056 Copyright=None ControlPort=Max Delay del Range=0 1 ControlPort=Blur Timeiblur Range=0 10 &log </csVSTfx> <CsoundSynthesizer> <CsInstruments> opcode SpSB, aaaa, kkkki ka,kc,km,kndx,ifn xin al oscili kndx/(2*$M PI),km,ifn a2 tablei al,ifn,1,0.25,1 a3 tablei al,ifn,1,0,1 aae, abe hilbert a2 aao, abo hilbert a3 ac oscili ka/2,kc,ifn ad oscili ka/2,kc,ifn,0.25 aeu - aae*ac + abe*ad aou = aao*ac + abo*ad ael = aae*ac - abe*ad aol = aao*ac - abo*ad xout aeu,aou,ael,aol endop

Page  4 ï~~instr 1 krt chnget "kratio" kndx chnget "kindx" kamp linenr p4, 0.2, 0.2, 0.01 al,a2,a3,a4 SpSB kamp,p5,p5/krt,kndx, outs al+a2,a2+a4 endin </CsInstruments> <CsScore> fl 0 16384 10 1 </CsScore> </CsoundSynthesizer> as VST'. The program will scan the CSD text, check to see if it needs to create an effect or an instrument and then creates a new plugin accordingly. On OSX users must create a new plugin bundle and place their CSD file inside it. csVST then looks through the current bundle and loads the first CSD it finds. Bundles may not contain multiple CSD files may not run as expected. Included in the csVST source is a simple Python language[2] script which automates this process. 5. CONCLUSION The current versions of csLADSPA and csVST perform adequately and has been tested by students in the National University of Ireland Maynooth and at Dundalk Institute of Technology, Ireland. The system has been used both as a creative tool and as a pedagogical utility used in the teaching of DSP techniques. csLADSPA, in particular, has been tested using a number of hosts and has demonstrated to be a great companion to Paul Davis' Ardour. csLADSPA is Free Software and is included in the standard Csound 5 distribution ( The csVST plugin generator kit will be soon available as a binary distribution for the Windows and OSX platforms and as source code for all Csound 5 support platforms. 6. REFERENCES [1] ffitch, J. "On the Design of Csound5", Proceedings of the 3rd Linux Audio Conference, ZKM, Karlsruhe, Germany, pp. 37-42, 2005. [1] Lazzarini, V, Timoney, J and Lysaght, T. "Streaming Frequency-Domain DAFX in Csound 5". Proc. of the 9th Int. Conf on Digital Audio Effects (DAFX), Montreal, Canada, 2006, pp.275-278. [2] Lazzarini, V, Timoney, J. and Lysaght, T. "The Generation of Natural-Synthetic Spectra by Means of Adaptive Frequency Modulation". Computer Music Journal, 32 (2), 2008. [3] Lazzarini, V, Timoney, J. and Lysaght, T. "Split-Sideband Synthesis", submitted to ICMC 08. Figure 4. The SpSB synthesiser instrument in Ableton Live. 4. USING THE PLUGIN GENERATORS The specific details on creating the above plugins in various host applications depend on the type of plugin desired. csLADPSA plugins are by far the easiest to generate. In order to use the code examples above in a LADSPA plugin the end-user must place the csLADSPA dynamic module and the csd file in the folder pointed to by the LADSPA_PATH environment variable. The csLADSPA library will automatically detect all Csound files and load them as separate plugins. The mode of operation of csVST will depend on the target platform. On Microsoft Windows, we must make a copy of the generic csVST DLL and then append an appropriate CSD file to the end of the binary data. This method is similar to the one used in the Cabbage[6] application builder to generate Csound-based freestanding programs. A simple C++ utility program, included with the csVST source code, demonstrates how this works. An alternative is to use Rory Walsh's Lettuce Csound frontend[9], which provides an option to 'export [4] Stroustrop, Language, New York, B. The C++ Programming second edition. Addison-Wesley, 1991. [5] Van Rossum, G and Drake, F. The Python Language Reference Manual. Network Theory, Bristol, 2003. [6] Walsh, R. "'Cabbage, a new GUI framework for Csound", Proc. of the Linux Audio Developer's Conference, Cologne, Germany, 2008, to appear. [7] [8] [9]