Introduction

CsoundVST (by Michael Gogins) is an extended version of Csound (by Barry Vercoe), a powerful sound processing language and software synthesizer.

Computer music and experimental composers, researchers, and teachers have been using Csound since 1985 because of its unexcelled library of unit generators, its flexible score and orchestra languages, and the fact that it runs on almost every processor and operating system.

CsoundVST adds the following features to Csound:

· CsoundVST runs as a standalone program with a simple graphical user interface.

· CsoundVST runs as a VST plugin, either as an effect or as an instrument.

· CsoundVST runs as a Python extension module.

· CsoundVST embeds the Python interpreter, so you can write Python scripts to control Csound and generate Csound scores.

· CsoundVST comes with a number of Csound plugin unit generators and Python extension modules that add substantially to the already great power of Csound. These include:

1. Peter Hanappe's Fluidsynth SoundFont synthesizer, as a Csound plugin opcode.

2. Kelly Fitz and Lippold Haken's Loris, for analysis, manipulation, and synthesis of sound using the Reassigned Bandwidth-Enhanced Additive Sound Model:

1. Python interface to Loris.

2. Plugin Csound opcodes for Loris (lorisread, lorisplay, lorismorph).

3. My Silence system for composing with music graphs (see my paper), including:

1. ImageToSound, for generating scores from image files.

2. MCRM, for generating scores based on iterated function systems.

3. Lindenmayer, for generating scores based on Lindenmayer systems.

4. StrangeAttractor, for generating scores based on chaotic polynomial dynamical systems.

· CsoundVST comes with a basic COM interface that permits calling from COM-enabled and .NET applications such as Mathematica 5 or Excel.

· You can embed CsoundVST in other software using its C++ API (see the CsoundVSTWin project for an example of how to do this).

License

Csound and CsoundVST are open source software.

VST Plugin Interface Technology by Steinberg Soft- und Hardware GmbH

CsoundVST and Csound are free software; you can redistribute them and/or modify them 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. CsoundVST and Csound are distributed in the hope that they 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 this software; if not, write to the Free Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA

Csound contains contributions from musicians, scientists, and programmers from around the world. They include (but are not limited to):

Allan Lee

Bill Gardner

Bill Verplank

Dan Ellis

David Macintyre

Eli Breder

Gabriel Maldonado

Greg Sullivan

Hans Mikelson

Istvan Varga

Jean Piché

John ffitch

Marc Resibois

Mark Dolson

Matt Ingalls

Max Mathews

Michael Casey

Michael Clark

Michael Gogins

Mike Berry

Paris Smaragdis

Perry Cook

Peter Neubäcker

Peter Nix

Rasmus Ekman

Richard Dobson

Richard Karpen

Rob Shaw

Robin Whittle

Sean Costello

Tom Erbe

Victor Lazzarini

Ville Pulkki

CsoundVST incorporates the following open source third-party libraries:

· The Python programming language, a dynamically typed, object-oriented language with a cross-platform runtime (http://www.python.org/).

· The Fast Light Toolkit, for cross-platform graphical user interface programming (http://www.fltk.org/).

· The boost library of C++ templates (http://www.boost.org).

Download

You can download source code from CVS at http://www.sourceforge.net/projects/csound.

You can download prebuilt binaries for Windows, with source code, from the CsoundVST.zip file release at http://www.sourceforge.net/projects/csound.

Installation

1. Download the CsoundVST.zip file release from http://www.sourceforge.net/projects/csound.

2. Create a csound directory on your computer.

3. Unzip all files, preserving pathnames, into the csound directory.

4. Make sure that your csound/bin directory is in your computer’s executable path. On Windows XP:

a. Go to the Start menu, Settings item, Control Panel dialog.

b. Click on the System icon.

c. Select the Advanced tab.

d. Click on the Environment Variables button.

e. In the System variables group, select the Path variable, and click on the Edit button.

f. Add your csound/bin directory at the end of the PATH variable and click on the OK button.

5. Make sure that your csound/bin directory is in your PYTHONPATH environment variable. On Windows XP:

a. Go to the Start menu, Settings item, Control Panel dialog.

b. Click on the System icon.

c. Select the Advanced tab.

d. Click on the Environment Variables button.

e. In the System variables group, click on the New button.

f. Enter PYTHONPATH into the Variable name field, add your Csound bin directory at the end of the Variable value field, and click on the OK button.

Compiling

At this time, CsoundVST builds only on Windows. You can build it either with the free open source Bloodshed Dev-C++ integrated development environment, or with Microsoft Visual C++ version 7.0 or later (Visual Studio .NET).

1. Using CVS, download the CsoundVST source code from http://sourceforge.net/projects/csound/ to your computer.

2. Download the VST SDK from Steinberg Soft und Hardware GmbH. You must personally go to http://ygrabit.steinberg.de/users/ygrabit/public_html and follow the instructions there. Note that you may not redistribute any part of the VST SDK. In other words, the VST SDK is freely available, but it is not free software or open source software. It falls into the rather unusual category of freeware with source code, and the license has some additional requirements, concerning copyright notices and so on, that you must observe. Unzip all the VST SDK files into a directory of your choice. I suggest you unzip it into your CVSROOT.

3. Download and install Python from http://www.python.org. This build system uses Python 2.3. If you use an earlier or later version of Python, you will need to edit the include paths and libraries for Python throughout the build system.

4. Download and install the Software Wrapper and Interface Generator (SWIG) from http://www.swig.org.

5. Download and install the boost libraries from http://www.boost.org. I suggest you install it into your CVSROOT.

6. For Microsoft Visual C++:

1. Load the CsoundVST.sln solution.

2. Make sure that the VST SDK, Python, SWIG, and boost header files and library directories are set in your Visual Studio Tools menu, Options dialog, Projects node in the tree, VC++ Directories sub-node, Include files and Library files lists. Make sure that the SWIG directory is set in the Executable files list.

3. Rebuild the solution.

7. For Bloodshed Dev-C++:

1. Download and install Dev-C++ from Bloodshed Software at http://www.bloodshed.net/.

2. Use the Bloodshed Dev-C++ Tools menu, Check for Updates/Packages dialog to download and install the Fast Light Toolkit (FLTK) package for Dev-C++.

3. Make sure that the VST SDK, Python, SWIG, and boost header files and library directories are set in your Dev-C++ Tools menu, Compiler options dialog, Directories tab, Libraries, C Includes, and C++ Includes tabs. Make sure that the SWIG directory is set in the Binaries tab.

4. Load the pyrun.dev project into Dev-C++. Open the all-before.mak file and make sure that the names and locations for your Python installation are correct; if not, edit them. This step is crucial, as the all-before.mak file contains a rule for building a mingw import library for Python, libpython.a. If this build step fails, you may need to edit the file locations in the all-before.mak file. Rebuild the project. The pyrun.dev project also builds the Python runtime library, which is required for type casting C++ objects from different extension modules.

5. Load the csound.dev project into Dev-C++ and rebuild it to make the Csound API used by CsoundVST.

6. Load the CsoundVST.dev project into Dev-C++. Open the all-before.mak file and make sure that the names and locations for your Python, SWIG, and FLTK installations are correct; if not, edit them.

7. Steinberg's developers incorrectly assumed that everyone developing for Windows uses the Microsoft compiler. In order to use the GNU compiler, you must replace defined(WIN32) with defined(_MSC_VER) in all the VST SDK sources.

8. Rebuild the project.

9. Load the CsoundVSTWin.dev project into Dev-C++ and rebuild it.

8. Run CsoundVSTWin to verify the build.

CsoundVST User’s Guide

CsoundVST runs in several different modes:

As a stand-alone program with a graphical user interface, CsoundVSTWin.
As a VST plugin, _CsoundVST.
As a Python extension module, CsoundVST.
As a COM object, CsoundCOM.

You can find basic instructions for using these modes below. In addition, the examples directory contains a number of sample orchestra, score, and script files. Note: Most of the examples contain pathnames hard-coded to c:/cvs/CVSROOT/csound/CsoundVST/examples, and so on. You will need to make sure that these pathnames reflect your own installation.

Running CsoundVSTWin Standalone

Run CsoundVSTWin from the csound/bin directory.
Click on the Settings tab, and select the Classic check box in the Csound performance mode box.
In the Edit soundfiles with text field, enter the complete pathname of your favorite soundfile editor, such as Cool Edit, Wavelab, or Audacity.

To make these settings persist for future sessions of CsoundVST, click on the Apply button.
To load a Csound structured data (csd) file, click on the Open… button. Navigate to a directory containing a csd file, such as csound/CsoundVST/examples/xanadu.csd, select the file, and click on the OK button.
To load a Csound orchestra and score separately, click on the Open… button. Navigate to the directory containing the orc file, and click on the OK button. Then click on the Import… button. Navigate to the directory containing the sco file, and click on the OK button.
To edit the Csound orchestra, click on the Orchestra tab.

To edit the Csound score, click on the Score tab.
To render the score, click on the Perform button. CsoundVST should switch to the Messages tab, and you should see Csound's runtime messages scrolling by.
If you need to stop rendering, click on the Stop button.

When rendering is finished, click on the Edit… button to invoke your soundfile editor to load Csound's output soundfile so you can play it.
To create a new Csound piece, click on the New button. Enter your orchestra in the Orchestra tab, and your score in the Score tab. Note that you can paste text from the Windows clipboard into these text boxes. Click on the Save as… button to save your piece.

Running CsoundVST in a VST Host

The following instructions are for Cubase SX. You would follow roughly similar procedures in other hosts.

Use the Devices menu, Plug-In Information dialog, VST Plug-Ins tab, Shared VST Plug-ins Folder text field to add your csound/bin directory to Cubase's plugin path. You can have multiple directories separated by semicolons.

Quit Cubase, and start it again.
Use the File menu, New Project dialog to create a new song.
Use the Project menu, Add Track submenu, to add a new MIDI track.
Use the pencil tool to draw a Part on the track a few measures long. Write some music in the Part using the Event editor or the Score editor.
Use the Devices menu (or the F11 key) to open the VST Instruments dialog.
Click on one of the No VST Instrument labels, and select _CsoundVST from the list that pops up.
Click on the e (for edit) button to open the CsoundVST dialog.

Click on the Open… button to bring up the file selector dialog. Navigate to a directory containing a Csound csd file suitable for MIDI performance, such as csound/CsoundVST/examples/CsoundVST.csd. Click on the OK button to load the file. You can also open and import a suitable orc and sco file as described above.
Click on the VST Instruments dialog's on/off button to turn it on. This should compile the Csound orchestra. Note: If you don’t compile the orchestra, you won't be able to assign the plugin to a track.
In the Cubase Track Inspector, click on the out: Not Assigned label and select _CsoundVST from the list that pops up.
On the ruler at the top of the Arrangement window, select the loop end point and drag it to the end of your part, then click on the loop button to enable looping.
Click on the play button on the Transport bar. You should hear your music played by CsoundVST.
Try assigning your track to different channels; a different Csound instrument will perform each channel.
When you save your song, your Csound orchestra will be saved as part of the song and re-loaded when you re-load the song.
You can click on the Orchestra tab and edit your Csound instruments while CsoundVST is playing. To hear your changes, just click on the CsoundVST Perform button to recompile the orchestra.
You can assign up to 16 channels to a single CsoundVST plugin. However, you can't have more than one CsoundVST plugin in the same song!

Using CsoundVST as a Python Extension Module

You can use CsoundVST as a Python extension module. In fact, you can do this either in a standard Python interpreter, such as Python command line or the Idle Python GUI, or in CsoundVST itself in Python mode.

To use CsoundVST in a standard Python interpreter, import CsoundVST:

Create an instance of CppSound, which provides an object-oriented interface to the Csound API.

In a standard Python interpreter, run your script in the normal way. You can load a Csound csd file and perform it:

To use CsoundVST itself as your Python interpreter, click on the CsoundVST Settings tab, and select the Python check box in the Csound performance mode box. Do not create a new CppSound object – CsoundVST contains a built-in CppSound object that you must use.

The csound/CsoundVST/examples/koch.py and Lindenmayer.py scripts provide examples of how to use Python to do algorithmic composition for Csound. You can use Python triple-quoted string literals to hold your Csound files right in your script, and assign them to Csound:

To run your script in Csound VST, click on the Perform button.