import-events

Function

(import-events file {keyword value}*)

Imports musical events in file according to the type of file specified. The currently supported score types are .clm, .mid and .sco files.

CLM Importing

If file is a .clm file then instrument calls are translated into an object definintion file and loaded into Lisp. Note that the CLM instruments referenced in file must already be loaded before calling the function. By default a seq object containing the imported objects is returned as the value of the function.

CLM importing supports the following keyword arguments:

:output pathname

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

:seq {boolean}

If true, then the function returns a seq object containing the imported objects, otherwise a list of objects is returned. Defaults to true.

:translations list

Specifies which expressions in file get translated into objects and how the translation is made. 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.

Csound Importing

If file is a .sco file then import-events returns a seq containing the i objects in file. Csound score 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.

Csound importing supports the following keyword arguments:

: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 {true | false}

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

Midi Importing

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

Midi importing supports the following keywords arguements:

:tracks {true | number | list}

Specifies the track numbers (zero-based) to import. Defaults to true, 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 {true | false | opspan | list}

Specifies the type of channel messages to exclude, if any. Defaults to false, which means that all channel messages are imported. Specify true to exclude all channel messages on all tracks. Otherwise, the value should be the status byte opspan or list of opspans to ignore.

:meta-exclude {true | false | list}

Specifies the type of meta messages to exclude, if any. Defaults to false, which means that all meta messages are imported. Specify true to exclude all meta messages. Otherwise, the value should be the meta byte opspan or list of opspans to ignore.

:time-format {:beats | :ticks}

Determines the format of time values in the imported data. If time-format is :beats (the default) then MIDI tempo changes in track zero are parsed and applied to the data as it is imported. If time-format is :ticks then the time values are in file ticks and no tempo changes are applied.

:tempo {false | number}

If time-format is :beats then a tempo value overrides any tempo changes in the file. If the file contains no tempo changes a default tempo of 120 is used. Tempo has no effect if time-format is :ticks,

:channel-tuning { true | false}

If true then any channel tuning information in the midi file will be parsed and converted into floating point keynumbers in the imported MIDI events.

:keynum-format {:keynum | :note | :hertz}

Determines how MIDI key number values are to be interpreted. Defaults to :keynum.

:note-off-stack {true | false}

Determines how multiple note on/off message with identical channels and key numbers are paired. The default value is false, 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 true means to match the current note off with the most recent pending note on with the same key number and channel.

See also

• play [Function]