TWO CROSS-PLATFORM CSOUND-BASED PLUGIN GENERATORS Victor Lazzarini Rory Walsh, Martin Brogan An Grúpa Theicneolaíocht Fuaime agus Ceoil Music Department Dhigitigh Dundalk Institute of Technology National University of Ireland, Maynooth, [email protected] Ireland [email protected] [email protected] , ABSTRACT API call, it can be used to send control data to a running instance. This article describes two new plugin generators for the development of effects and instruments using the In the present systems, audio data is sent to the main Csound audio programming language, csLADSPA and input buffer of Csound and collected from the main csVST. It discusses the basics of these two systems, output buffer. This implies that the number of channels exploring some of their internal aspects. The text of a plugin is defined as a global constant in the Csound continues on to show three basic examples, two plugin code. However, the sampling rate and vector size will be effects and one synthesis instrument. These determined by the plugin host, overriding any values demonstrate both time-domain and spectral processes. defined by Csound. The API is also responsible for The article concludes with a look at specific details of loading and compiling all Csound code. operation of the two plugin generators. 2. THE PLUGIN GENERATORS 1. INTRODUCTION csLADSPA uses the LADSPA format. This plugin model The availability of a variety of plugin models and host came to fruition in early 2000 following the combined applications has provided fertile ground for the efforts of Paul Davis, Richard Furse, and Stefan development of audio effects. Such systems allow Westerfield. LADSPA provides developers with a simple programmers to concentrate on the signal processing way of developing audio plugins which can be loaded by tasks at hand, as they provide all the infrastructure for a wide range of host applications. audio input and output, as well as a model for the CsVST uses the VST plugin format. There are, in fact, creation of software components. In this article, we will two types of VST plugins supported by csVST: csVSTfx go a step further by providing the plugin developer with and csVSTi. The first one is used for general-purpose a full complement of signal processing operators, unit audio effects and the second for synthesiser instruments. generators, from a widely adopted system, Csound[1]. In The VST plugin framework is ubiquitous in the this scenario, a plugin designer can avail of already commercial music software market, therefore csVST existing components to build his/her own effects or should be of great utility to many users. instruments. 2.1. The inside bits The generators presented here support the creation of plugins under two major systems: a Free-software one, csLADSPA and csVST are not themselves the plugins, the Linux Audio Developer’s Simple Plugin API but plugin generators. They will create, in a host, any (Application Programming Interface) (LADSPA)[7] and number of plugins written by the user. Each one of these a commmercial system, the Virtual Studio Technology will be linked to a particular Csound orchestra/score. (VST) [8]. Plugins for both systems can be created using Plugins are created when csLADSPA (or csVST) is the same code, interchangeably, as they are solely based loaded by the host. In the case of csLADSPA, the on the Csound language. generator will then provide one plugin for each Csound code file found in a pre-defined directory. For csVST 1.1. The Csound host API plugins, the Csound code will be appended to the The main component of the systems presented here is the dynamic-loadable module (MS-Windows) or included in Csound 5 library (libcsound), accessed through its API. a bundle (OS X). Libcsound is a fully-reentrant object-oriented library, As mentioned above, the number of audio channels for allowing any number of instances of the audio processing a plugin and its controls is determined by the Csound engine to be run concurrently. The library can be code. A number of extra XML tags have been defined for programmed using a variety of languages. For the some of these tasks. Once plugins are created, they will present systems, we will be employing its C++[5] API. generally be displayed on a list by the host, from where Communication between a Csound instance and the they can be instantiated and run. host for control messages is enabled by the software bus. A basic model of how the plugins work is shown in This is based on a system of input/output channels, below (fig.1). The host application loads the csLADSPA referenced by name and managed by engine. Once a or csVST-created plugin. This will instantiate a Csound channel is created, either using Csound code or via an object and compile its associated orchestra/score code. When the user processes audio through it, the plugin will Tags Description route the input audio to that instance of Csound. This Name The name of the plugin as it will will then process this audio and return it to the plugin appear in the host application which will then route that audio to the host application. Maker Author of plugin Figure 2 shows a plugin in operation in the host UniqueID ID given to plugin, each plugin application Audacity. 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 Figure 1. csLADSPA/csVST plugin structure the range values. Table 1. Plugin tags For this to happen, calls are made to the ControlPort and Range tags are optional, but the former method, which is Csound::PerformKsmps() always requires the latter. Examples of how these tags responsible for processing or generating one vector full are used can be seen in the next section. of samples. These, in turn, are shifted in and out of the main Csound buffers to/from the host buffers. In the case 3. EXAMPLES of synthesizer instrument plugins (csVSTi), MIDI communication between the host and Csound is also In the following section two csLADSPA plugins are provided through API calls. In this case, Csound presented. The first illustrates the mechanisms for instruments will be instantiated by realtime MIDI events communication between the host and the csLADSPA sent in by the host. 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: Figure 2. A csLADSPA plugin in Audacity. <csLADSPA> 2.2. Plugin tags Name=AdFM Maker=Lazzarini, Walsh & Brogan Plugins will use the unified file format (CSD) for reading UniqueID=1054 Csound code. In these files, the user must specify some Copyright=None basic information about the plugin, in the form of XML ControlPort=Modulation Index|index Range=0|5 tags (table 1). This is done by adding a section in the ControlPort=Car-mod ratio|ratio CSD file whereby the user can specify things like the Range=0.5|2 name of the plugin, the author, etc. It is in this section </csLADSPA> that the user can also specify the control ports they will <CsoundSynthesizer> need in order to interact with their Csound code when <CsInstruments> running the plugin through a host. This section will be defined inside or opcode DFM,a,akki <csLADSPA>, <csVSTfx> setksmps 1 <csVSTi>, for LADSPA, VST effects and VST as,krt,knx,ifn xin instruments, respectively. kcps,kamp ptrack as,1024 adt oscili knx/($M_PI*kcps),kcps/krt,ifn adp delayr 1 /* delay line */ adel deltap3 adt + 2/sr xout adel endop instr 1 instr 1 imaxdel chnget "del" knx chnget "index" iblurtime chnget "blur" krt chnget "ratio" asig in ain in fsig pvsanal asig, 1024, 256, 1024, 1 a1 DFM ain,krt,knx,1 ftps pvsblur fsig, 0.2, 0.2 out a1 atps pvsynth ftps endin out atps </CsInstruments> endin <CsScore> f1 0 16384 20 2 </CsInstruments> i1 0 36000 <CsScore> </CsScore> f1 0 1024 10 1 </CsoundSynthesizer> i1 0 3600 </CsScore> As previously mentioned the means of communication </CsoundSynthesizer> between the plugin and the instance of Csound is provided by the software bus. In Csound we can use the 3.3. A Split-Sideband synthesis instrument chnget opcode to retrieve data from a particular bus channel. In the case above this data is used to control the The following code will create a synthesiser, using the Split-Sideband algorithm[4], that accepts MIDI messages different parameters as defined by the Range tag in the sent from the host application. MIDI is routed from the <csLADSPA> section of the above code. 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 p- field 4, converting them to Hz, where they can easily be retrieved in the instrument code.