Resources
A great deal of material has been and continues to be written about how to use Csound. Even so, finding the information you need can sometimes be a bit of a chore. One of my goals in writing Csound Power! was to put all of the information a newcomer might need in one place, where it’s easy to refer to. But this book is certainly not a complete reference manual! In the next few pages, we’ll take a quick look at the main resources you may find yourself consulting, and I’ll say a few words about how to get the most out of them.
The Canonical Csound Reference Manual
When you download and run the Csound installer, you’ll install the current version of The Canonical Csound Reference Manual at the same time. In Csound Power!, references to “the manual” always refer to this document. The manual is also available as a separate download. The automatically installed version is a large, cross-linked set of HTML pages, which can be read using any web browser. If you prefer to read a PDF version, a Windows Help file version, or a version translated into French, you can download it separately.
To download the manual, go to http://sourceforge.net/projects/csound/files/csound5. Click on the link to the folder of the version of Csound you’re using or want to use (for example, csound5.13). You may find the downloads for the manual directly in this folder, or you may need to click on a manual folder within this folder.
I keep a shortcut to the manual on my computer desktop. The shortcut opens up the frames version (it points to the file indexframes.html), which has navigation bars of links across the top and down the left side (see Figure 1.2).
Caution The HTML version of The Canonical Manual for Csound 5.13 is not entirely compatible with the Firefox browser. The information is there, but the links with which the pages are accessed are broken. The manual files are compatible with Opera and Safari, and probably with other browsers as well.
Figure 1.2 The HTML frames version of The Canonical Manual, opened in Opera.
Using the Manual
Like Csound itself, the manual is perpetually in a state of flux. It is frequently updated, both to add new information and to correct mistakes. Like Csound, the manual is maintained entirely by unpaid volunteers. (I’ve rewritten one or two pages myself.) A great deal of vital information is packed into the manual, but its explanations are sometimes terse, and the organization takes some getting used to.
Until you understand the basic syntax of the Csound language and the conventions used in the manual, the manual may prove more frustrating than helpful. To help you understand the organization, we’ll take a quick look at one of the pages you’ll surely find yourself consulting while learning Csound, the page for the oscili opcode. In order to explain what’s on this page, I’ll need to refer to several technical terms that will be explained later in this book. If the explanation here doesn’t make much sense now, please return to it after you’ve read a bit further in Csound Power!
Each opcode in the Csound language has its own page in the manual. (Basically, an opcode is a software component that either generates or processes a signal. For a more complete explanation of what an opcode is, see Chapter 7.) Each opcode page is structured in sections. First is a definition of the opcode. This is followed by a section headed “Description.” Below this are the headings “Syntax,” “Initialization,” “Performance,” “Examples,” and “See Also.”
The definition for oscili reads as follows:
oscili—A simple oscillator with linear interpolation.
That’s clear enough, provided you know what linear interpolation is. You won’t find an explanation of this term on the oscili page, however; nor will you find a cross-reference to a page where the term is explained. The description provides a bit more information, but again, you’ll need to know what’s going on in order to interpret it:
oscili reads table ifn sequentially and repeatedly at a frequency xcps. The amplitude is scaled by xamp. Linear interpolation is applied for table lookup from internal phase values.
The italicized items ifn, xcps, and xamp are references to the two lines in the next section, “Syntax.” Here, we’re given prototypes that show how to use oscili in a Csound instrument:
ares oscili xamp, xcps, ifn [, iphs] kres oscili kamp, kcps, ifn [, iphs]
When you’re first exposed to Csound, that’s enough to make your eyes cross. But in fact there’s a lot of information packed into those two lines. The syntax will be explained more fully in Chapter 7. Briefly, there are two lines because the oscili opcode can run at audio rate (a-) or control rate (k-). For more on the difference between audio rate and control rate, see Chapter 6. The output of the opcode (the signal that will come from the oscillator) is at the left end of the line, followed by the opcode name itself. Items to the right of the opcode name are inputs to the opcode. Each opcode has its own defined set of inputs.
The x- at the beginning of some of the terms means that those variables can be either audio rate or control rate. Items that begin with i- (such as ifn) can only be given inputs at initialization (i-) time and can’t be changed while your Csound instrument is running. (Don’t worry—if you try to put a variable of the wrong type into an i-time argument, the compiler will complain and force you to change it.) Items that appear at the end of the line, in square brackets, are optional. If you don’t supply a value for this variable, Csound will use the default value defined within the opcode.
The “Initialization” section of the page in the manual explains the meaning of the i-rate inputs to the opcode. On the oscili page, this section explains the meanings of ifn and iphs.
The “Performance” section of the manual page explains, briefly, the meanings of k-rate, a-rate, and x-rate inputs. These inputs can be used to modify the output of the opcode while the instrument is running. The “Performance” section may also contain additional information.
Most of the manual pages contain brief examples of Csound code to illustrate how the opcode can be used. You can copy and paste an example into whatever text editor you’re using to create Csound files, save the file, and compile (run) it. At this writing, the examples are in the process of being revised to better reflect the way Csound is used today. Older examples may remain in your copy of the manual, however. In some cases, the example may do little more than illustrate the syntax of the opcode as it would be used in an actual Csound file, so copying it and running it may not tell you much. You may learn more by trying it out in your own code, making a few mistakes, revising the code, and so on.
The Csound Website
The Csound website (www.csounds.com—see Figure 1.3) is a hub that provides links to downloads, resources, and so forth. The home page also functions as an announcement area for news of interest to the Csound community.
Figure 1.3 The home page of Csounds.com has numerous links, including links to podcasts of Csound-based music.
The forum on Csounds.com seems to get very little traffic. A better resource for discussion is the Csound mailing list (see below). Other sections of the site, such as the Resources page, are more useful.
The Online Manual
An ongoing, user-written manual can be found at www.flossmanuals.net/csound (see Figure 1.4). The discussions of topics in this manual are generally more thorough and hands-on than in The Canonical Csound Reference Manual, and the example code tends to provide more detail as well. Created principally by Alex Hofmann, Iain McCurdy, Joachim Heintz, and Andrés Cabrera, the online manual is a work in progress; at this writing, some of its pages are blank. Even in its present state, however, it’s very valuable, and as time goes on it should become more comprehensive.
Figure 1.4 The online Floss Manual for Csound (www.flossmanuals.net/csound).
Mailing List
Discussions of various Csound-related topics take place daily on the mailing list. To join this list, send an email to [email protected]. In the first line of the message, type this:
SUBscribe csound <name>
Insert your name in place of <name>. You can set up your account to receive new messages via email as they’re sent to the list, or as a periodic (once or twice a day) digest.
To browse the recent activity on the mailing list, go to http://csound.1045644.n5.nabble.com/Csound-General-f1093014.html. This page is set up very much like a web-based forum. Lists for developers and for blue (a Csound front end) are also available from this page. In order to post messages to the web page, you will need to register with the mailing list by sending an email, as described earlier.
No question is too basic or too esoteric for the Csound mailing list. As long as you maintain a reasonable standard of politeness and provide details on your problem or quandary, experienced Csound users will be happy to answer any questions you may have. In addition to technical questions, the list provides announcements of computer music conferences and activities, announcements of new music, and so on.
At this writing, the status of the Csound mailing list remains a bit up in the air, due to John ffitch’s retirement from the University of Bath. If the email address doesn’t work, you should be able to find more current information at Csounds.com.
Code Examples
Assuming you’re using the CsoundQt front end, as described in Chapter 5, you’ll find a treasure trove of code examples in the Examples menu. It’s possible that a few of these may not work in the way you expect. If you’re new to Csound, this will be frustrating, but as you start to learn a little more, the examples will give you some easy (or not-so-easy) puzzles to solve.
Other scores, some simple and some bewilderingly complex, can be found on various web pages. Iain McCurdy, for instance, has more than 300 code examples, mostly tutorial in character, on his own website (http://iainmccurdy.org/csound.html). These examples will probably be bundled as Examples within CsoundQt, but if you’re using some other front end, you should be able to download them from Iain’s site.
The Csound Journal
Published two or three times a year, the Csound Journal (www.csounds.com/journal) is a free online magazine devoted to articles about how to use Csound. Some of the articles are highly technical in nature, while others are approachable by relative newcomers. Each issue includes a variety of topics—synthesis, signal processing, integrating Csound with other programming languages, and so on.
Online UDO Library
I’ll have more to say about user-defined opcodes (UDOs) in Chapter 7. The code snippets in the online UDO library are created by Csound users. They do various useful or bizarre things. After downloading and pasting into your code, they can be used almost exactly like Csound’s built-in opcodes. The main difference is that they’re written in the Csound programming language itself, so you can see what’s going on in the code and modify it if you need to. The constantly expanding UDO library can be found at http://www.csounds.com/udo.
Books for Further Study
By far the most important reference work for studying Csound is The Csound Book, a massive anthology edited by Richard Boulanger and published by MIT Press. If you’re serious about mastering Csound, you will definitely want to order a copy of this book. The text is more than 700 pages long—and two CD-ROMs packed with additional material are also included.
Note The home page for The Csound Book at MIT Press can be found at http://mitpress.mit.edu/e-books/csound/frontpage.html. Unfortunately, this page, though its banner proclaims it “The Csound Front Page,” is not being actively maintained. At this writing (September 2011), almost all of the links on its sub-pages are broken.
Contributors to the book or CD-ROMs include Barry Vercoe, Richard Boulanger, John ffitch, Michael Gogins, Gabriel Maldonado, Matt Ingalls, Hans Mikelson, Russel Pinkston, and many other luminaries within the Csound firmament. You’ll find chapters on FM synthesis, granular synthesis, optimizing your code, designing legato instruments, using delay lines, using the phase vocoder, and many other topics.
Once you move beyond the first 150 pages, you’ll find that The Csound Book is not really addressed to newcomers. There’s not a lot of math in the book, but you’ll definitely spot a few equations as you leaf through it. In addition, The Csound Book is now more than 10 years old, so it contains no information on the numerous developments that have been added to Csound since the beginning of the new century. For these reasons, I felt that there was a genuine need for a book like Csound Power! In no way, however, is Csound Power! intended to compete with The Csound Book!
Also worth studying or owning, if you can find a copy, is Virtual Sound, by Riccardo Bianchini and Alessandro Cipriani. You may be able to order a copy through the Italian publisher, ConTempo, but I have been unable to find a current distributor in the United States. (Not to worry—though written in Italy, it’s in English.) Virtual Sound is somewhat more beginner-oriented than The Csound Book, but like the latter, it’s more than 10 years old, so some of the information in it is no longer relevant.
If you’re serious about mastering computer music technology, there are several other books to consider. While not dealing specifically with Csound, these will give you a lot of excellent material (some of it quite advanced) on digital synthesis and signal processing. I recommend Computer Music: Synthesis, Composition, and Performance (Schirmer, 1997) by Charles Dodge and Thomas A. Jerse and The Computer Music Tutorial (MIT Press, 1996) by Curtis Roads.
You
Though it may not seem obvious when you’re first introduced to Csound, you yourself are an important resource for Csound development. If you have only a little knowledge, you can help by reporting bugs in Csound itself, in the front-end program(s) you’re using, or in any user-defined opcodes that you download. As a knowledgeable Csounder, you’ll be able to answer questions from newcomers on the mailing list. As time goes on, you may be able to help with testing by downloading and compiling source code. As Andrés Cabrera commented, “It’s the users and their interaction with developers that has kept Csound alive for so long.”