Common Music Reference Manual

Top Objects Processes IO Scales Data Patterns Plotter Utilities Index

3  Input and Output

3.1 Files and Ports

Input/output in Common Music is defined in terms of io structures called file, port and display. Functions that produce input/output accept io objects or their string names. To reference an existing io object use the #! macro. To create or reinitialize an io object use the io macro.

io object {name value}*

[Macro]

Creates or initializes an io structure.

Example

? (io "/zap/test.aiff" )
#<audio-file: "/zap/test.aiff">

? (io "/zap/test.aiff" srate 44100 channels 2)
#<audio-file: "/zap/test.aiff">

? (io "midi.port" connections *midi-default-connections*)
#<midi-port: "midi.port">

Initializations for all io objects:

rt {:milliseconds | t | nil}

If t the scheduler runs in "real time" mode. This means that objects are processed at their true clock time. The scheduler normally runs in "priority" mode, which means that objects are processed in clock order but as fast as possible. If rt is :milliseconds then object time values are treated as milliseconds. (A millisecond is 1/1000th of a second.)

Initializations for all files:

pathname string

The pathname for the file. The pathname must include the file extension. pathname can also be specified as name.

versions {number | t}

Causes a new version of the file to be created each time output occurs. The version name is based on the name of the file and the version count, which is initialized to number and incremented each time output occurs. A t value for versions is the same as 1.

handler {t | nil | :name}

Specifies what (if any) post-processing is to occur after the output file is written. Post-processing behavior depends on handler function(s) associated with the file class. If the value of handler is nil no post-processing occurs. To invoke a specific handler, specify its keyword name. The default value t invokes the default handler function. You can create your own handlers to process files in a variety of ways. See defhandler and "cm:etc;handlers.lisp" for more information.

audio-file

[Class]

Implements output to CLM audio files. This class is automatically chosen when you specify a file with a ".aiff", ".snd" or ".wav" extension.

audio-file implements the following initializations:

trace-output {t | nil}

If t then instrments will print their score times as the audio file is being written, otherwise no trace will be printed. The default value is nil.

clm-file

[Class]

clm-file implements the following initializations:

play {t | nil | :load}

If t the .clm score file is loaded by clm-load and the resulting sound file is played after it has been generated. If :play is :load then the score file is loaded but the resulting sound file is not played. The default value is t.

Other keyword initializations are passed to clm:clm-load.

cmn-file

[Class]

cmn-file implements the following initializations:

display {t | nil}

midi-file

[Class]

midi-file implements the following initializations:

divisions integer

The number of divisions per quarter note. Defaults to 96.

timesig (numerator denominator)

The time signature for the file. Defaults to (4 4). The time signature list may contain up to four values: (numerator denominator &optional clocks-per-quarter 32nds)

tempo number

The MIDI tempo of the file. Defaults to the tempo of 60 bpm.

play {t | nil}

If true (the default) the file is played after it is written.

divisions-per-semitone integer

Enables microtonal MIDI output at the specified resolution per semitone. The default value is 1 which means that no microtuning occurs. Values between 2 and 16 allocate and initialize that many MIDI channels produce microtones from floating point keynums.

synth-bend-width integer

Declares the pitch bend width in semitones for microtonal tuning. Used in conjunction with divisions-per-semitone to produce microtonal output. The default value is 2, which means that the synth is assumed to have a maximum pitch bend range of plus or minus a whole step.

midi-port

[Class]

midi-port implements the following initializations:

connections list

Sets the MIDI port connections to the entries specified in list. Each entry in list is a list in the format: ("input" "output") where input and output are string nameing the actual interface connections. These names depend on current MIDI System Interface configuration of the computer. For example, (("K2500" "K2500") (nil "QuickTime Music")) would define two connections, connection 0 is to the "K2500" interface and connection 1 is output only to "QuickTime Music". Defaults to the value of *midi-default-connections*, initially set to nil.

channel-tuning {nil | t | type}

If nil (the default) then a floating point keynum is rounded to the nearest MIDI integer keynum as it is sent to the MIDI port. If channel-tuning is not nil then floating point keynums kkk.cc will produce mirotonal inflections for keynums with a non-zero cent remainder cc. When channel-tuning is in effect then channel assignments in individual MIDI events are ignored and channels are selected based on the value specified to channel-tuning. If the value is t then a non-zero floating point keynum is directly preceded by a pitch bend value and sent to the next available channel. By default the entire range of channels (0-15) are used in round-robin fashion to minimize the likelyhood that the pitch bend value will affect a currently sounding note. To cycle through only a subrange of channels specify t in a list with the range: (t low high) where low and high specify the starting and ending channels to rotate through. If the value of channel-tuning is not nil or t it should be a keyword or symbol naming one of the predefined equal-division channel tunings: :12-note, :24-note, :36-note, :48-note, :60-note, :72-note, :84-note, :96-note, :108-note, :120-note, :132-note, :144-note, :156-note, :168-note, :180-note. The difference between consecutive degrees in a 180 note octave is 6.6 cents, close to the minimum change preceivable by humans.

synth-bend-width integer

Declares the pitch bend width in semitones for microtonal tuning. Used in conjunction with divisions-per-semitone to produce microtonal output. The default value is 2, which means that the synth is assumed to have a maximum pitch bend range of plus or minus a whole step.

channel-map vector

Maps logical channels to the 16 standard MIDI channels on a specified route. Each entry in vector is a list in the format: (logical-chan (route chan)). Defaults to the value of *midi-default-channel-map*, which is initially set to map 16 logical channels to the 16 standard MIDI channels on route 0.

queue-size integer

Sets output message queue size allocated during midi-open. Defaults to the value of *midi-default-queue-size*, initially set to 20000.

sco-file

[Class]

sco-file implements the following initializations:

orchestra pathname

Sets the optional pathname of a CSound orchestra file that CSound will use to play the score file.

header string

Sets the header of the score file to string. The header is printed before any i_statements are written to the file.

vrml-file

[Class]

defhandler file-class name file &rest keys &body body

[Macro]

Any file initialization specified to io or events that is not associated with a slot in the file is automatically passed as a keyword argument to the handler function for the file.

3.2 Reading and Writing Events

events objects destination &optional ahead &rest inits

[Function]

Example

? (events '(#!foo #!bar) "midi.port" 1)
#<midi-port "midi.port"#>

? (events #!foo "/tmp/test.midi" 10 :versions t :play nil)
"/tmp/test-1.midi"

import-events file &rest keywords

[Function]

If file is a .clm file then import-events imports every ins object that could be parsed from instrument calls in the file. The instruments referenced in file must be defined (loaded) before import-events can translate their calls into objects. import-events creates a .cm translation file containing translated instrument calls and other top-level forms from file not explicitly excluded by the user. By default the translation file is loaded after it has been written and a seq object containing the imported objects is returned by import-events.

Importing .clm files supports the following keywords:

:output pathname

The pathname of the translation file created from file. Defaults to the same directory and name as file with a "cm" extension added.

:seq {t | nil}

If t then import-events returns a seq object containing the imported objects, otherwise a list of objects is returned. Defaults to t.

:load {t | nil}

If t then import-events loads the translation file after it is written, otherwise the file is created but not loaded. Defaults to t.

:translations list

Specifies which expressions in file get translated into objects and how to translate them. Each entry is a list: (symbol function) where symbol is the name of the expression to be translated and function is its translation function. The function is passed four arguments: the form to translate and the :translation, :exclude and :include lists specified to import-events. The translation function can explicitly call import-form to recursivly process its subforms if necesary. :translations defaults to the value of *import-translations* which defines translations for let,let*,progn and with-sound expressions.

:exclude list

A list of top-level forms to omit from the translation file.

:include {t | list}

A list of undefined top-level forms in file that should be include in the translation file. All defun or defmacro forms encounted while translating file are automatically added to this list.

If file is a .sco file then import-events returns a seq containing the i objects in file. .sco file parsing handles the carry parameters . + and ^ but does not support a_statements or more than one s_statement. All f_statements are automatically added to the header of the file io structure.

Importing .sco files supports the following keywords:

:output pathname

The pathname of the .cm import file created of out file. Defaults to then same directory and name as the score file.

:load {t | nil}

Determines whether or not the translation file is loaded into CM or not. Defaults to t.

If file is a .midi file then import-events returns a seq containing midi objects from one or more tracks of file.

Importing .midi files supports the following keywords:

:tracks {t | number | list}

Specifies the tracks (zero-based) to import. Defaults to t, which imports all the tracks. Otherwise, the value should be a single track number or list of tracks specifications. Each track specification in the list can be a track number or a list: (track channel-exclude meta-exclude), where track is the track number, and channel-exclude and meta-exclude are defined below.

:channel-exclude {t | nil | opcode | list}

Specifies the type of channel messages to exclude, if any. Defaults to nil, which means that all channel messages are imported. Specify t to exclude all channel messages on all tracks. Otherwise, the value should be the status byte opcode or list of opcodes to ignore.

:meta-exclude {t | nil | list}

Specifies the type of meta messages to exclude, if any. Defaults to nil, which means that all meta messages are imported. Specify t to exclude all meta messages. Otherwise, the value should be the meta byte opcode or list of opcodes to ignore.

:time-format {:beats | :raw}

Determines if MIDI tempo meta messages will be parsed or ignored. Defaults to :beats.

:note-type {:note | :keynum}

Determines how MIDI key numbers are to be interpreted. Defaults to :note.

:note-off-stack {t | nil}

Determines how multiple note on/off message with identical channels and key numbers are paired. The default value is nil, which means that the current note off is matched with the earliest pending note on with the same channel and key number. A value of t means to match the current note off with the most recent pending note on with the same key number and channel.

play file &rest options

[Function]