Instruments and instrument-palettes

+ Associated example files


This page addresses topics related to instruments and instrument-palettes. A separate page is available for information specific to players and the ensemble.

+ Instrument objects

The slippery chicken instrument class currently has 25 slots, 21 of which are used to define the instrument's attributes and 4 of which can be used to retrieve information about data that slippery chicken has generated for that instrument.

The slots that define the instrument's attributes include parameters such as the highest and lowest pitches of the instrument's range, its transposition etc., as well as parameters necessary for output, such as the instrument's full and abbreviated staff names for the score, the clef it uses, or the MIDI program it is to use for playback etc.

Parameters can also be specified that affect slippery chicken's automatic selection of pitches for the instrument, including whether the instrument can play microtones, whether it can play chords, which chord function is to be used when selecting pitches for those chords, and pitch subsets that limit the automatic pitch selection for that instrument etc.

The various slots of an instrument object can be set using keyword arguments. This allows instrument objects to be created using any combination of any number of the slot names available. A simple definition of an instrument object within an instrument-palette may look like this:

 (:staff-name "soprano" :staff-short-name "s"
  :lowest-written c4 :highest-written c6
  :starting-clef treble
  :midi-program 54))

NB: This is the syntax for defining an instrument object within an instrument-palette using the make-instrument-palette function. This syntax is minimally different to that of the make-instrument function; however, the keyword arguments are all the same. See the source code documentation on make-instrument for a description of the keyword arguments and how to create an instrument object directly using that function. This page will make reference to both approaches.

Details on all of these parameters and the slot names required for modifying their values can be found in the source code documentation for the make-instrument function.


+ Instrument palettes

In order for slippery chicken to access instrument definitions, they must be stored in an instrument-palette. slippery chicken loads with a predefined instrument-palette, which consists of most standard instruments, assigned to the global variable +slippery-chicken-standard-instrument-palette+. This variable and the instrument objects assigned to it should generally be suitable for most compositions.

However, a number of options are available should the palette not contain a specific instrument, or should the user desire to change the attributes of a given instrument (such as making the range smaller for younger players etc.). Although this could be done by editing the instruments.lsp file directly, this is strongly discouraged, as updating slippery chicken in the future might overwrite carefully executed edits.

NB: The +slippery-chicken-standard-instrument-palette+ also serves as the default instrument-palette for all new slippery-chicken objects should none be otherwise specified. This allows the user to omit the :instrument-palette keyword argument from the make-slippery-chicken function if the instrument object definitions from the standard palette are sufficient. Since explicitly stating the standard palette is a functionally legitimate approach, the examples in this manual will sometimes include the specification of the instrument-palette and sometimes omit it.


+ Creating a new instrument-palette

One option for defining new instruments or new versions of existing instruments is to use the make-instrument-palette function. This function takes a list of instrument descriptions based on the keyword arguments of the make-instrument function.

An example of its usage might look like this:

(defparameter +plucked-strings-aux-instrument-palette+
      (:staff-name "mandolin" :staff-short-name "md"
       :lowest-written g3 :highest-written a6 :starting-clef treble
       :chords t :microtones nil :missing-notes nil 
       :midi-program 26))
      (:staff-name "tenor banjo" :staff-short-name "t-bj"
       :lowest-written c3 :highest-written a4 :starting-clef treble
       :transposition-semitones -12
       :chords t :microtones nil :missing-notes nil 
       :midi-program 106)))))

Instrument palettes can also be created on-the-fly as part of the call to make-slippery-chicken. The following is taken from our template file:

 :title "Your Title Here" 
 :composer "Your Name Here"
 ;; +slippery-chicken-standard-instrument-palette+ is the default instrument
 ;; palette. Only specify this slot if you need something special. See
 ;; instruments.lsp in the src directory (or for
 ;; details of all pre-defined instruments. But here's an example of the kind
 ;; of thing to do if you do want to define your own.
 '((piccolo (:transposition-semitones 12 :lowest-written d4
             :highest-written c6))
   ;; a more complete definition, by way of example
   (flute (:staff-name "flute" :staff-short-name "fl" 
           :lowest-written c4 :highest-written d7 
           :missing-notes (cqs4 dqf4) 
           :largest-fast-leap 19
           :starting-clef treble
           :chords nil 
           :microtones t 
           :midi-program 74))
   (b-flat-clarinet (:transposition-semitones -2 :lowest-written e3
                 :highest-written c6))  
   (violin (:lowest-written g3 :highest-written c7 :chords t)))
 :ensemble '(((flt ((flute piccolo) :midi-channel 1))
              (clr (b-flat-clarinet :midi-channel 2))
              (vln-one (violin :midi-channel 3))))

A typical entry for a given instrument will first need a symbol as its name, such as the symbols mandolin and tenor-banjo in the example above. This will be used later to assign an instrument to a player in an ensemble. The instrument definition will then generally consist of at least the parameters staff-name, staff-short-name, lowest-written, highest-written, transposition-semitones (if applicable), starting-clef, chords, and midi-program. See the source code documentation for the make-instrument function for more details on these and other possible keywords.

The symbols chosen as the names of instrument objects in a given instrument-palette are then the symbols used in the ensemble block of the slippery chicken object created for a given piece.

Saving the code for an instrument-palette to be loaded later

The user can also save the code for creating separate instrument-palette objects in a separate file so that these palettes can be loaded for use with future pieces. In such cases, the entire defparameter expression should be saved in a file with the .lsp suffix and loaded again later using Lisp's load function prior to evaluating the make-slippery-chicken function for which the palette is to be used, e.g.:

(load "/path/to/my-inst-palette.lsp") 


+ Adding instruments to existing instrument-palettes

If the user would like to add a single instrument object to an existing instrument-palette, this can be done using the add method:

  (make-instrument 'mandolin
                   :staff-name "mandolin" :staff-short-name "md"
                   :lowest-written 'g3 :highest-written 'a6 
                   :starting-clef 'treble 
                   :chords t :microtones nil :missing-notes nil 
                   :midi-program 26)


+ Changing instrument attributes temporarily

Any of the values stored in the various slots of an instrument object contained within a given instrument-palette can also be changed temporarily (until the same slot is changed again later, the current Lisp session is ended, or the given instrument-palette is reloaded) using the set-slot method in combination with the slot names (which are the same as the keyword arguments of the make-instrument function) for the values that are to be changed.

For example, to change the value of the lowest-written slot for the instrument object with the ID flute in the +slippery-chicken-standard-instrument-palette+ to B3, the following can be done:

(set-slot 'lowest-written 

This might also be combined with a loop to change many slot values at once, as is done for the largest-fast-leap slot of a number of the instruments in the second tutorial.