Csound 6.14 for Haiku

— February 2020 —

Overview

Csound is an extensive environment for audio synthesis and processing, and is not a domain to be entered into lightly! It is, however, capable of almost anything you might want to do — or that has ever been done — in this vast field. It has been around a while, with beginnings way back in the early days of computer music, but its community is very active, and development is continuous.

This package is the 6.14 Release Version. (A previous “6.14” package was a beta. This is the official release.) The current manual (with a “What's New” section describing the new features) can be downloaded from GitHub (see below).

The package is self-contained. Suitable versions of (the required) libsndfile and its associated libraries, and (the very useful) fluidsynth library are included in the package, to avoid possible conflicts with other packages.

The core of audio synthesis in Csound is the Orchestra, in which you build Instruments from sequences of Opcodes. This can be played by a Score that tells it what each Instrument is to do and when, or it can be driven by MIDI or other live source. The generated output can be written to a file (WAV, AIFF, and so on) or played directly to the machine’s audio. Orchestra and (the optional) Score may be individual files (with extensions ‘.orc’ and ‘.sco’ respectively), or combined in a single ‘.csd’ file.

Be aware that if you have never used Csound before, there will be a learning curve, and you’ll need to dig deeply into the manual (see below). An Instrument is basically just a list of Opcodes processed sequentially, but there’s a large variety of these, so deciding which ones will give you your dream sound may not be easy. Csound.com is the place to start for anything you want to know about the system.

Organization

Csound has many components, and for this distribution they are all packaged into one folder (‘...apps/Csound’), with links from system locations where required. (If you found this README in the ‘documentation’ hiearchy, it is just a link to the one in the above folder) The package aims to be self-contained, and provides all the libraries the system needs, even though they may also be already in the system. This wastes some space, but avoids conflicts and other problems with the current state of flux with Haiku… This version uses double-precision floating-point, so many components and links are suffixed with ‘64’ to indicate this. (It is not a 64-bit executable!) A few of the opcodes available on other platforms may nt have been implemented (yet), such as those for Lua. Some, such as FLTK, are not supported in Haiku. (The command ‘csound -z’ will print a list of all the available opcodes.)

The core of the package is the ‘csound’ program itself (though this is just a front-end to ‘libcsound64.so’ which actually provides the basic functionality. It is a command-line program and is provided (as a link) in the bin path. (There are various GUIs available on other platforms, but none (yet) for Haiku.)

A lot of functionality is added to the basic library by plugins, which need to be locatable. They are actually in this folder, but are linked to from ‘../../lib/csound6/plugins64’, which is in the default search path of the program. (See ‘Plugins’ below.)

The package also has a suite of (30!) utilities in the ‘Utilities’ sub-folder, but these are not, by default, in the path as they are less used. If you want any of them, you can either make a link to it from ’.../non-packaged/bin’ or just try it out from a Terminal in the ‘Utilities’ folder. You will need to refer to the ‘Utility’ section of the manual to discover their function.

Csd files open by default in Stylededit when double-clicked. If you have a preferred editor, just edit ‘Csound Document’ in the ‘text’ FileTypes.

Quick Test

Included in the package is ‘quick_test’, a little shell script that should be able to run csound immediately — you should hear some familiar notes from your speaker. You can run it either by double-clicking it, or — preferably — from a Terminal in this folder. Running from a Terminal is useful to let you see all Csound’s printout.

It essentially just runs the shell command ‘csound ce3k.csd’. The ‘ce3k.csd’ file that it uses is text, and will show you what a simple Csound control file looks like.

Documentation

You will certainly need to have the manual available to get any use out of Csound, but as the “Canonical Manual” is much bigger than this package, it’s not part of it. It’s conveniently readable online, at Csound.com (though that may not be the latest version), or you can download your own copy (in ZIP form) as HTML pages, or a PDF. The HTML archive includes an ‘examples’ folder with the executable csd files from the manual. The home page has a lot of useful links to other resources.

The manual is exhaustive, with a page for every opcode, but it is not easy to read as an introduction to the system. The “FLOSS Manual” is more informal, with discussions of techniques and so on.

Plugins

As mentioned, plugins do a lot of the work, and must be available. The program has a search path of a sequence of locations where they may be. In order these are:

The supplied plugins will be found in one of the first two links, depending on where the package has been installed. The latter two are available for any additional plugins that might be released later. Beware of having more than one plugin with a given name — behaviour might be undefined.

As an unlikely-to-be-needed alternative, you can define your own path in the environment variable ‘OPCODE6DIR64’. This will invalidate the default path if it is defined, so you will need to ensure the appropriate one of the above is included in your path. (Contrary to the manual, this setting is not mandatory in Haiku, as the correct defaults should always be present.)

Audio I/O

Audio output is just as in Csound on other platforms — the ‘-o’ option determines where the output goes. ‘-o dac‘ (or ‘-o devaudio‘) sends the audio to the system mixer. Any other name is the name of a file to be written (as WAV by default); if the environment variable SFDIR is not set, and no path is given, it will be written in the current directory. See the manual for all the options controlling output format and so on.

Live audio input isn’t yet available for Haiku, but of course you can read audio from a file with the ‘-i’ option. Again, see the manual.

MIDI I/O

You can read MIDI input from a file with the ‘-F’ option, just as on other platforms. The ‘-M’ option is used to get real-time MIDI input, but the behaviour of its parameter is a bit different from what you will read in the manual.

Haiku MIDI handling is based on being able to connect “Producer” ports to “Consumers”. Ports are visible to programs via their names. (A port need not have a name if a program just creates it to connect to a named one.) If you use an option of the form ‘-M <producer-name>’, where <producer-name> is an existing Producer, such as a MIDI input device, Csound will connect its input to that via an anonymous port. If any other name (which can be an arbitrary string) is given, Csound will create a Consumer of that name to which you can connect any Producer by any means suitable (‘PatchBay’ or a ‘MusicWeaver‘ ‘MidiLink’ element for instance)

Of course if you want to connect to a Producer, you have to enter the name correctly, or it will just create a Consumer instead! If you want to find out the Producers currently available, use ‘-M ?’ (space character required, and in a complete command line, as otherwise Csound will just abort before giving the information). Note that the names of devices look like pathnames (“/dev/midi/...“) but they are just strings. Giving a non-existing pathname will just result in a Consumer of that name.

Note that there is a slightly annoying glitch (almost certainly in Haiku rather than Csound). The first time after boot-up that you try to connect to an existing MIDI device, it probably won't be found! This only happens once, so if you hit it just quit Csound and start again.

If you have a keyboard or other source of MIDI messages, you may want to run ‘midi.csd’ for a simple test. Look at the file as text for details.

Real-time MIDI output (the ‘-Q’ option) is not currently available, but you can write a midifile with ‘—midioutfile=FILENAME’.

Notes

If you’re playing Csound in real-time, you might want to remember the ‘-L stdin’ option which lets you type score events straight into the Terminal running Csound. This can be particularly useful to terminate a live session just by sending an ‘e’ event (though ctrl-C will do that also). Any other named-pipe/fifo instead of ‘stdin’ can be used to feed it from some other process.

It seems that current Haiku doesn’t handle audio resampling very well. If the sample rate specified in Csound (or any other audio source) doesn’t match the driver’s sample rate, you are likely to hear ugly artefacts (crackles and “ghost tones”). If possible, it’s best that the ‘sr’ value you specify in an orchestra is the same as that set in the Media Preferences.

Although this version of Csound doesn’t have any GUI of its own, I find the MusicWeaver to be a fine way of giving some graphic real-time control. [OK… I admit I’m biased… (:-)] A Csound command line can be run in a PipeStream element, with MIDI input coming from a Producer offered by a ProduceMidi element. (I precede the csound command itself with a ‘sleep 1;’ to ensure the Producer is created before Csound looks for it.) It can also be useful to use ‘-L stdin‘ and feed the Pipestream’s input with score events as desired (usually from a table of them in a convenient StreamView element).

Newly available in Csound 6 is the UDP Server, which lets you send Orchestra code and Score events etc. to a running Csound via UDP. See the “UDP Server” section in the manual, and the “--port” command-line option.

If you want, you can make a ‘csd’ file directly playable when you click on its icon, provided it is self-contained — i.e. it doesn’t need any command-line options that are not in its “<CsOptions>” section. You do this by adding, at the very top of the file (before the “<CsoundSynthesizer>” and with no blank lines above), the line:

#! /bin/env csound
(This doesn’t affect its normal command-line usage.) Then, either using the ‘Get Info’ panel or from the shell, make it executable by setting the ‘x’ bit. A double-click should then start it up, though of course you will not see the logging text from Csound, as there is no Terminal. If you have xicon, you can simply make it an xicon script (with the same ‘shebang’ line) and you’ll get the terminal output as well.

The ‘experimental’ mp3out opcode mentioned in the manual’s “Whats New” section currently crashes things, so is not included.

I think that about covers it. Have fun!


Licence

Csound is copyright© 1991-2019 The Csound Developers. (see Contributors)

Csound is free software; you can redistribute this and/or modify this 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.

Csound 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 a copy of the GNU Lesser General Public License provided in the Haiku installation ; if not, write to the Free Software Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA

Contributors

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

Haiku port by Pete Goodeve.