slippery chicken documentation - instruments and instrument-palettes

## Instruments and instrument-palettes

### + Associated example files

- instruments-examples.lsp

close

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:

    (soprano
     (: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.

close

### + 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.

close

### + 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+
      (make-instrument-palette
       'plucked-strings-aux-instrument-palette
       '((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))
         (tenor-banjo
          (: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:

    (make-slippery-chicken
     '+your-title-here+
     :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 http://tinyurl.com/pjbgnae) 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.
     :instrument-palette
     '((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")

close

### + 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:

    (add
      (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)
     +slippery-chicken-standard-instrument-palette+)

close

### + 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
              'b3
              'flute
              +slippery-chicken-standard-instrument-palette+)

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.

close