For Newbies
This document assumes you are already familiar with the Csound language. If you are new to Csound, you should first work through the provided tutorial files distributed with MacCsound. Then you might want to Richard Boulanger's TOOTorials. Probably the easiest thing to do is to download the entire package of source files from the right side of his index page, and then open and run each file while going through the TOOTorials online. Also take a look at the other example files provided with MacCsound.
This manual also assumes you are already familiar with the MacOS and its conventions such as Opening and Saving Files, Preferences, the Finder, Control Panels, etc.
If you have any questions, please feel free to post them to the csounds.com maccsound forum, the csound mailing list, or email ma++ directly.
Introduction
MacCsound is a development environment for creating and controlling Csound instruments and processes. All orchestra and score data, graphic control/display objects, and render options are displayed in one unified window with tabs and quick-keystrokes allowing you to easily switch among the views containing the data. In the upper right corner of each window, there are buttons allowing you to select real-time and file-based renders and start/pause/kill rendering. In addition, you can open soundfile documents for playback, run analysis utilities, or process the file with an effect. Effects are simply csound .csd files. You can create your own effects, essentially writing your own plug-ins with Csound code!
General Functionality
This popup menu button allows you to select render options. You can choose to play out an audio device in real-time , record a real-time performance 
, or render the orc/sco to an audio file. 
This button runs the Csound process, usually generating audio. You must have the Csound Document saved before pressing the start button.
This button pauses the Csound process. 
This button terminates the Csound process. MacCsound is a fully functioning text editor. Common editing, search, replace, undo, redo, and font traits [set from the Preferences Window] are implemented in the program.
orc/sco/csd Files
MacCsound saves all orc, sco, gui i/o, and option data into a unified csound file [*.csd]. In addition, it will allow you to read and export .orc and .sco files. [ Note that exporting .orc/.sco files will overwriting any file with the same name in the same directory. ]
When opening an .orc or .sco file, the matching .sco or .orc file will be automatically opened, if found.
To automatically save your project before rendering, make sure you turn on the option in the preferences.
In some instances, you may need to 'Get Info' for a file from the finder and change the 'open with' selection to MacCsound.
When MacCsound is launched, a default file is automatically opened for you. This file is called default.csd and is located in each user's home "~/Library/Application Support/MacCsound" directory. You can edit this file to customize all the default options and settings of a new file. You can also put anything in the orc, sco, and gui views to use as a default template when creating a new csd file.
Syntax Highlighting, Formatting, and Manual-Lookup
All Csound Opcodes and comments are displayed in a special color specified in the Preferences Window.
The syntax reference is displayed on the bottom of the window for any opcode found on the current line.
If you select an opcode [double click on it] and then select Lookup Selection from the ‘Help’ menu [shortcut cmd-’], the manual page for that opcode will be opened in your web browser.
The default manual is the one installed with the CsoundLib.framework.
You may alternatively specify a different local, or online URL in the Preferences Window.
Shift Left/Right options will shift all selected text by one tab-space.
Columnize will format all selected text to fit to tab-spaces.
There is a instr/opcode popup menu in the lower-left corner of the orc panel that allows you to quickly scroll to an instr or opcode. This can be helpful to navigate large files.
A line number display on the bottom of the orc and sco panels shows the current line number the insertion cursor is on in the orc and sco. This can be useful when tracking down errors reported by a failed csound render.
Real-Time Audio and MIDI
Audio
To enable real-time audio, select "Perform in Real-Time" in the render options popup button.
Select which output devices to use for input and output inside the Preferences Window. Although not recommended for optimum performance, you can use different devices for input and output as long as they have the same sample rate. [ You specify ‘Default Devices’ in the ‘Audio Midi Setup’ utility application or 'Sound System Preferences Panel'.]
The buffersize you set in the ‘options’ panel is used to change your device’s buffersize. You must make sure this is a valid size (hint: they do not necessarily need to be a power-of-2) for the selected device, and you must also make certain that the orc's sample rate matches the one on the devices you are using.
Smaller buffersizes will have smaller latency, but higher CPU usage. You can check your CPU usage on the bottom-left corner of the i/o panel. If you are getting too high CPU usage (>.80) you may exerience drop-outs in the audio -- if this happens try increasing the buffersize.
Multi-channel rendering is supported on MacOSX - channels are simply mapped in order starting with the first channel of the default device.
Multiple simultaneous renders are possible, but this feature is still considered experimental -- you must make sure that each .csd must have the same sr and buffersize.
If you select "Perform in Real-Time to File" in the render options popup button
, you can play out to the audio device in real-time while simultaneously writing to a file. The output file format options in the options tab view are used.
[ Currently only AIFF and SoundDesigner files are supported, with 16-bit, 24-bit, and 32-bit int sample sizes only. ]MIDI
MIDI input and output is supported. You can specify what devices to listen to for MIDI Input in the Preferences Window. MIDI output is sent to all MIDI devices, including MacCsound's own virtual MIDI port.
NOTE: You may have to restart MacCsound when you add/remove an audio or MIDI device to the system.
Graphic Control & Display Objects
MacCsound provides you with graphical I/O Objects to allow you to design your own graphic interface for controlling Csound instruments, displaying orchestra values, and spawning new score events.
An I/O Object is usually associated with a ‘control channel’ that corresponds to invalue or outvalue opcodes in your orchestra. A 'control channel' is simply a global k-rate value or string that can be accessed by both orchestra instruments and graphical I/O Objects. Every ‘control channel’ has a unique name and can be written/read to by as many I/O Objects, invalue opcodes and/or outvalue opcodes as you want.
For example, a Slider object whose 'control channel' name is “pitch” will need a corresponding line in the orc that looks like:
khz invalue “pitch”
You create new I/O Objects by clicking on an appropriate button on the top left palette in the I/O View.
To select objects, click on an object's border or drag the selection region over one or more objects.
You move and resize a selected object by clicking and dragging on the object's edge.
You can also move selected objects with the the arrow keys.
The 'Align Objects' command automatically aligns selected objects along their most shared edge or center-line.
When objects overlap, you can adjust their layered position by selecting the 'Bring to Front' and 'Send to Back' functions located in the 'Edit' menu.
You can copy/paste/clear/delete/opt-drag copy/select all/undo/redo objects with the usual Mac menus and keystrokes.
You can ‘lock’ and 'ulock' the gui by clicking on the tiny square button
in the lower right corner of the window, or by command-clicking on the edit view (a la max/pd).The current settings of all a project's I/O Objects are saved when the file is saved.
Although I/O Objects are primarily designed for real-time use, you can use them for file based rendering. Since invalue opcodes read 'control channel' values at i-time, you could use I/O Objects for a way to set intializing parameters for a render. [ You might need to use the i() opcode to convert get the k-rate value for opcodes that expect i-rate inputs. ] In addition, displaying values for a file-based render might be useful. It should also be mentioned that editing of I/O Objects can even happen while you are rendering in real-time!
When an I/O Object is selected, its inspector will appear above to let you modify the object's attributes.
I/O Objects and their attributes are as follows:
I/O View - the window panel that contains all I/O Objects.PresetsBackground Color - changes the background color of the entire I/O View.
[ You click on any "blank" background space in the I/O View to display its inspector. ]Message - a text scroller view displaying the Csound output messages.
A popup menu allowing you to choose if rendering output messages are displayed as an I/O Object, in its own window, or not displayed at all.Function - a graphic display of Csound functions.
A popup menu allowing you to choose if function tables are displayed in an I/O Object, in its own window, as ASCII text in the output messages, or not displayed at all.Slider - a value slider.
Channel Name - A name or number of the control channel.
Min/Max - Sets the value range of the slider.
Sliders can be horizontal or vertical, the larger dimension determines the orinetation.Button - a generic or picture button that sends score events or control value.
Button Text - The name displayed in the button.
Functionality Popup Menu - Set to one of the following modes:Button/Picture Score Event: sends a score Event Text when pressed.Select PICT file - Use the provided button to specify the file you want to use. Images are resized to the object frame, allowing you to resize the image with the mouse. When moving saved files to other computers, MacCsound will look for PICTs in the .csd file's directory, or you mayh manually re-specify the picture files. 'PICT' is the only graphics format currently supported. An easy way to convert an image file to PICT is to open it in Apples Preview application and select "Export" from the File Menu.
Button/Picture Singe Value: when pressed, sends Value on control Channel.
Picture (Static Only): display only. sends no messages.Text - text or number display and control
Function - Options are:Label - ASCII text display. Note you can use returns.Resolution - Sets the significant digits for Value Display/Scroll.
Edit the label by double-clicking on the object.
Click outside the object to turn off editing.
Edit Text - A text entry box, useful for sending text to the orchestra.
Value Display - Displays the value of the specified control channel.
Value Scroll - Displays control value, you can also "click-drag" to change the value.
An up/right drag increases the value, down/left decreases it.
The farther away from the object you drag, the faster the scrolling becomes.
With some practice, you will be able to quickly scroll with fine or course resolution.
Note that changing the Resolution will modify the rates of scrolling.
You can manually edit the value by double-clicking on the object.
Value Edit Text - A number entry box, useful for typing-in control values.
All values will be rounded to the nearest resolution. For instance, if the resolution is '.01', then the smallest increase in values would be something like 23.24, 23.25, 23.26, etc.. if the resolution is set to '100', then values would appear like: -100, 0, 100, 200, 300, etc... Resolution also sets the base increment in Value Scroll mode.Channel - A name or number of the control channel.
Font/Size/Justification - Sets the font, size, and justification of the text.
Has Border - Draws a border around the text.
Background Color - Sets the background color.
Text Color - Sets the text color.
Communication the Orchestra
The "invalue" and "outvalue" opcodes support string variables, allowing full communication with text i/o objects. In addition, Text objects will set to the path of any file you drag onto it. This can be handy for specifying a soundfile name in an instrument without having to type in every path names!Meter - 1 or 2 dimensional value display and "x-y" mouse control
Horizontal Channel - A name or number of the horizontal/primary control channel.
Vertical Channel - A name or number of the vertical/secondary control channel.
Display Type - One of the following modes:Fill: displays a colored square for the larger (horizontal/vertical) dimension.Tracking - Specifies a mode for tracking mouse:
only the appropriate control channel is displayed, however
when tracking is enabled, output is sent on both control channels.
Inverse Fill: same as 'Fill', except displays from the top or right.
Line: like 'Fill', except displays a line instead of a colored square.
Crosshair: like 'Line', except it displays both channels simultaneously, forming a cross.
Point: displays a colored circle located at the Horizontal and Vertical coordinates.None: ignores all mouse movementColor - Foreground color. defaults to the table graphics preference colors
Mouse Down: tracks the mouse only when the mouse button is depressed inside the object.
Mouse Down (Off Zeros): sets both channels to '0' when the mouse button is released.
Click Toggles: mouse click inside the object starts/stops tracking.
Click Toggles (Off Zeros): sets both channels to '0' when an "off" mouse click occurs.
Line Size - For display modes:'Line' & 'Crosshair': sets the width of the displayed line.Fade Speed - Allows you to set rate for a gradual fade for the display. For any setting other than the leftmost "Fast", the background color will be black, otherwise the table graphics background preference color will be used.
'Point': specifies the width of the circle.
'Fill': unusused
Meter objects only support values 0-1.Knob - a rotating slider knob
Channel Name - A name or number of the control channel.
Min/Max - Sets the value range of the knob.
Resolution - Sets the resolution of every knob value, in terms of the specified value range.
Knobs are controlled by clicking and dragging.
[ Left or Down decreases the value, Right or Up increases the value ]Checkbox - an on/off toggle
Channel Name - A name or number of the control channel.
Checkboxes send and receive a boolean value on the specified channel.
[ 1 = checked, 0 = not checked ]Menu - a popup menu for selecting items in a list
Channel Name - A name or number of the control channel.
Menu Size - Changes the size of the object.
Menu Items - A list of the menu item names in the menu, separated with commas and no spaces.
Menus set the control channel to the current menu item selected.
['1' for the first item, '2' for the second item, etc.]
Menus also listen for new values on the control channel, selecting the menu item accordingly.
Presets allow you to capture the currrent settings of all I/O control channels, and are saved inside the .csd file. You can create, save, delete, rename, and change presets from the popup menu at the bottom of the I/O panel. In addition, you can perform the same functions from the orc [ via an 'outvalue' opcode ], or from a GUI object, using the '_Preset' reserved control channel. There is no limitation to the number of presets you can create.
Reserved Control Channels
There are a number of pre-specified, "reserved" control channels for controlling MacCsound functionality via an i/o object or an instrument. They all begin with an underscore and are defined as follows:
_Offset - sets the score offset [ values in secs ]See the "Reserved_Controls.csd" example file for more details.
_Play - starts/stops render [ 1=play, 0=stop ]
_Pause - toggles pause [ any value ]
_Gain - output gain factor [ 0=silence, .5=1/2amp, 1=nochange, 2=2xamp, etc ]
_Preset - performs all preset commands, recognized values are:>0 - Number of Preset to Load
-1 - Save Settings as New Preset
-2 - Save Current Preset
-3 - Rename Current Preset
-4 - Delete Current Preset
Sound Files
To render your project to a sound file, select "Render to File" in the render options popup button
.
You can also record a real-time render to a sound file, see Real-Time Audio and MIDI, above, for more details.When rendering a project to a sound file, MacCsound displays the amount of audio rendered vs. computation time ratio on the bottom of the i/o panel. After pausing, killing, or completing the render, the file will be opened in its own window.
You can also open any other aiff, aifc, wav, or sd2 file in its own window. When opened, a sndinfo is automatically run and displayed, showing you details about the file. You can play the file with the quicktime scrub-bar as well as clicking the spacebar for start/stop. A preference option also allows you to have the sound automatically playback at opening.
Util Analysis
You can run csound util proprocesses in MacCsound on any sound file that is currently opened. A popup menu in the soundfile window lets you select a utility analyses or effect to perform on the file.
The pencil button
on the left of the window opens up a window allowing you to set any analysis options -- In most cases,
however, the default settings should be adequate and you will not need to specify any options. See the manual for
more information on utilities and settings.Effects
Effects are .csd files that you can edit/create yourself.
In a sense, this allows you to CREATE YOUR OWN PLUGIN EFFECTS WITH CSOUND CODE.
To edit an effect, click on the left button
in a soundfile window, the appropriate file will then open in a standard MacCsound window.
Look at the included effects for examples on how to design your own. You must place effets in the "/Library/Application Support/MacCsound/Effects" directory [
which should have been automatically created for you the first time you launched MacCsound. ] CsoundLib.framework and Render Options
You must have the CsoundLib.framework installed to run MacCsound. Most likely it was installed with MacCsound, and you should be able to install version updates without having to reinstall MacCsound.
In general, all of the most important render options [file format, sample size, peak, dither, output messages, etc] are taken care of automatically, or through settings you make in the options tab view in a project window. However, you may specify any needed options in the "Advanced Commandline Options" in the options tab view.
click here for descriptions of Csound Commandline Options
One directory is used for all of CsoundLib's directories [SFDIR, SADIR, INCDIR, etc..]
You can specify a directory for each project file, as well as a 'global' default directory in the Preferences Window.
The global default directory can be either be the current file's directory, the previous file's directory, or a specified directory.
MacCsound-Specific Opcodes
There are a few plugin opcodes that come pre-installed with MacCsound:
shell - run any commandline application. ( see example file for more info )In addition, there is a MacCsound orc macro so that you can use to specify code to be used only with MacCsound. This may be useful for designing an instrument that uses i/o objects but can run on other platforms, for example:
filevalid - input: a file name string. output: 1 = soundfile is valid, 0=file not found or notvalid.
offsetscore - sets the score start-offset in seconds.
#ifdef MacCsound kpitch invalue “pitch” #else kpitch = 440 #endif