The Configuration Box

Many of the features of the Configuration box have been discussed earlier in this chapter. In this section we’ll go through the details, tab by tab.

The Run Tab

Possibly the most important settings in CsoundQt are the Buffer Size and HW (hardware) Buffer Size, which appear at the top of the Run tab. You should normally leave these checkboxes checked. The numerical values you enter in the two fields will determine the latency of your system, which is not crucial if all you’re doing is playing back a standard score. If you’re playing Csound live, however, you want these values to be as small as possible.

The values are the number of samples in the buffers. For instance, with my system I normally set -b to 256 and -B to 512. With a sample rate of 44,100, a buffer size of 512 produces an 11-millisecond delay, which I feel is acceptable. If I try to dial back to 128 and 256, the real-time audio output breaks up badly. The safe way to enter data in these fields is in powers of 2.

Latency is often a concern in computer audio systems when the computer is being asked to generate sound in real time in response to user input. Latency is the time that passes between when you send a command, such as a MIDI note-on message, into the computer and when you hear the output. Usually latency is measured in milliseconds. (A millisecond, abbreviated ms, is .001 second.) For reference, it’s useful to realize that sound travels about one foot per millisecond in air. A latency of 10ms, then, is equivalent to plucking a guitar string and hearing the sound from an amplifier positioned 10 feet from you. An electric guitar player on a large stage may easily be standing more than 10 feet from his or her amp, without ever noticing the latency. Amounts above 20ms, however, tend to make a computer audio system feel sluggish.

The checkbox and field for additional command-line flags can be used to add flags (as listed in The Canonical Csound Reference Manual). One useful flag, for instance, is --displays. This does nothing if you’re running your .csd within CsoundQt unless a Graph widget is being used in the Widgets panel. With a Graph widget, --displays is needed to cause the widget to display any f-tables in your score. In addition, if you use the Run in Term button, when Csound runs you’ll see a graphic display of the f-tables if the --displays flag is used. This can be helpful if the data in an f-table isn’t doing what you think it ought to. You can also enter command-line flags in the <CsOptions> area of your .csd file, but in that case they’ll only operate within one file. Entering the flags in the Configuration box will make them active for all of your Csound files.

Normally, you should leave Use CsoundQt Options checked in both the File and Realtime Play areas of the Run tab. Unchecking this box will cause other options in the Configuration box, such as the buffer size settings, to be ignored. Unless your .csd file includes some equivalent flags in the <CsOptions> area, Csound won’t know what to do.

Quite a number of options are available in the File Type and Sample Format drop-downs in the File (offline render) area. Some of these may not work with your computer’s other audio applications, so you should probably choose either .WAV or .AIFF as the File Type and either 16-bit or 24-bit as the Sample Format.

I suggest checking the Ask for Filename Every Time box, as this will enable you to avoid accidentally overwriting a file during offline rendering.

In the Realtime Play area, you’ll need to select your input and output devices for audio and MIDI. Click on the “...” button, and you’ll see a list of the available devices. From time to time the devices in your system may change—for example, if you haven’t switched on a MIDI keyboard, causing its USB driver to be inactive. In this case, .csd files will refuse to run, and an error message will appear in the Output Console, until you select an active device or choose Disabled or None from the menu. If you never use MIDI devices, you can leave the MIDI fields blank.

The General Tab

The Run Utilities Using area has two radio buttons—Csound API and External Shell. If you invoke a file analysis utility from CsoundQt’s Utilities box, the former choice will cause messages to appear within CsoundQt’s Console pane. The latter choice will open up an external shell (Command Prompt in Windows, Terminal in Mac OS), and messages will appear there.

The Performance Tweaks area is useful if you’re pushing your CPU’s ability to generate sound. The Disable Python Callback checkbox will be grayed out unless you have built PythonQt and have CsoundQt built with PythonQt support.

The settings in the Console area are self-explanatory. They’re used in the Console pane of the main window.

The Record file can be set to a different bit depth than the offline render from the Record area of the General Tab.

The sensekey opcode is used for real-time input from the QWERTY keyboard. If this checkbox is checked, holding down a key will cause repeated events. If it’s not checked, you’ll get only a single event, when the key is first pressed.

The Allow Simultaneous Play checkbox lets you run several files at once. This process is not guaranteed to be error-free, however. It depends on whether the code to be run is re-entrant. Some Csound modules, such as portmidi, are not re-entrant, so using portmidi while attempting to run simultaneous files will cause crashes.

The Widgets Tab

The checkboxes in the Widgets tab are fairly self-explanatory. The widgets can transmit and receive using either invalue and outvalue or chnset and chnget, depending on what you choose in the drop-down menu. (The choice makes very little functional difference.) Normally you should leave Save Widgets in csd File checked. If you don’t, your widgets will be lost.

You may find that there are conflicts between CsoundQt and the FLTK opcodes, which generate graphic control panels rather like CsoundQt’s widgets. If you’re planning to use FLTK or have downloaded a Csound file that uses FLTK, you may be well advised to run Csound from the command line rather than within CsoundQt. If you want to try running an FLTK .csd file within CsoundQt, you need to enable FLTK using the checkbox in this tab.

If screen space is at a premium, you may prefer to check Widgets Are an Independent Window, as this generates a pop-up window where the widgets are displayed and can be interacted with. This option can also be handy if you have multiple computer screens, and it will allow you to minimize CsoundQt while leaving the Widgets panel open.

The Editor Tab

Again, the items in this tab are easy to understand. You can choose the font and size for text in the editor window and the format for line ends. (Leave this set to the value that matches your computer operating system.)

If you have Autocomplete Menu While Typing checked, CsoundQt will sense when you’re typing the name of an opcode and will offer a pop-up menu. You can move up and down through this menu using the arrow keys, select the item you want, and hit Return. This will put the prototype of the opcode into the text. I prefer to leave this box unchecked and consult the hint text at the bottom of the Editor window. This text contains the same information and doesn’t require that I replace text items with my own constants or variables. The feature is provided for those who prefer to work this way.

The Environment Tab

Use the buttons in this pane to select directories on your hard drive. In the Html Doc Directory tab, you want to find the /manual directory of your Csound installation. This will enable CsoundQt to display the manual.

The next five fields are explained on the “Csound Environment Variables” page in the manual. SADIR is the default directory for analysis files, which are created using the utilities in the Utilities box. SFDIR is the default directory for output audio files, and SSDIR is the default directory for input files, including both audio and MIDI files. INCDIR is the include directory and is the default location for files that are referenced by #include statements.

The External Programs Tab

In the External Programs tab, you can tell CsoundQt where to find other programs. In Windows, the Terminal field will normally have:

  cmd.exe

In the Macintosh version, you’ll find:

  /Applications/Utilities/Terminal.app

The Wave Editor, Wave Player, Browser, and PDF Viewer fields are used for telling CsoundQt where to look when you click the Ext. Editor or Ext. Player icon in the toolbar, or the Show Opcode Entry in External Browser or Open Quick Reference Guide command in the Help menu.

The Template Tab

When you start a new .csd file by clicking the New button in the toolbar or using the File > New menu command, CsoundQt will copy whatever text you’ve defined in the Template tab into the new file. By default, this text contains only the main tags, <CsoundSynthesizer> and so forth. You might want to add your preferred orchestra header to the template, as doing so saves a bit of typing.