instrument/default-chord-function [ Functions ]

[ Top ] [ instrument ] [ Functions ]

DESCRIPTION

 If an instrument is able to play chords, a function must be defined to
 select pitches from a list that it can play as a chord. This function (as a
 symbol) is passed as a slot to the instrument instance.
 
 This is the default function. It returns a 2-note chord with the pitch at
 index plus that below it, or that above it if there are no lower pitches
 available. Or it just returns a single-pitch chord object if neither of
 those cases are possible.

 NB: The arguments are supplied by slippery chicken when it calls the
     function.

ARGUMENTS

 - The current number from the pitch-seq. Currently ignored by default.
 - The index that the first argument was translated into by the offset and
   scaler (based on trying to get a best fit for the instrument and set).
   This can be assumed to be a legal reference into pitch-list as it was
   calculated as fitting in pitch-seq::get-notes.  (zero-based.)
 - The pitch-list created from the set, taking into account the instrument's
   range and other notes already played by other instruments.
 - The current pitch-seq object. Currently ignored by default.
 - The current instrument object. Currently ignored by default.
 - The current set object. Currently ignored by default.

RETURN VALUE

 A chord object.

SYNOPSIS

(defun default-chord-function (curve-num index pitch-list pitch-seq instrument
                               set)

instrument/in-range [ Methods ]

[ Top ] [ instrument ] [ Methods ]

DESCRIPTION

 Checks whether a specified pitch falls within the defined range of a given
 instrument object or not.

ARGUMENTS

 - An instrument object.
 - A pitch item (pitch object or note-naem symbol).

OPTIONAL ARGUMENTS

 - T or NIL to indicate whether the pitch specified ist to be compared with
   the given pitch object's sounding or written range. T = Sounding. 
   Default = NIL. If T, a secondary NIL is also returned to indicate that
   the specified pitch is neither too high nor too low.

RETURN VALUE

 Returns T if the specified pitch falls between the
 lowest-sounding/lowest-written and the highest-sounding/highest-written
 pitches of the given pitch object.

 If the specified pitch is outside of the range, an additional value of 0 or
 1 is also returned to indicate whether the specified pithc is too high (1)
 or too low (0).

EXAMPLE

;; Determine if a pitch provided as a note-name symbol falls within the written
;; range of a non-transposing instrument
(let ((i1 (make-instrument 'inst1 :lowest-written 'bf3 :highest-written 'a6)))
  (in-range i1 'c4))

=> T, NIL

;; Determine if a pitch provided as a note-name symbol falls within the
;; sounding range of a transposing instrument, using the optional argument T
(let ((i2 (make-instrument 'inst1 :lowest-written 'fs3 :highest-written 'c6
                           :transposition 'BF)))
  (in-range i2 'c6 T))

=> NIL, 1

;; A pitch object can be used as the specified pitch
(let ((i2 (make-instrument 'inst1 :lowest-written 'fs3 :highest-written 'c6
                           :transposition 'BF)))
  (in-range i2 (make-pitch 'd6)))

=> NIL, 1

SYNOPSIS

(defmethod in-range ((ins instrument) pitch &optional sounding)

instrument/make-instrument [ Functions ]

[ Top ] [ instrument ] [ Functions ]

DESCRIPTION

 Create an instrument object, specifying the values for a number of
 parameters for describing characteristics of a given instrument, such as
 lowest and highest pitch, transposition, clefs used by the instrument etc. 

 NB: The user will generally define instruments will in the context of the
 make-instrument-palette function and added directly to the
 +slippery-chicken-standard-instrument-palette+ parameter of the file
 instruments.lsp, using the keyword structure shown below in the OPTIONAL
 ARGUMENTS.

ARGUMENTS

 - A symbol that is the instrument ID.

OPTIONAL ARGUMENTS

 &key arguments:
 - :staff-name. String. This is the unabbreviated instrument name that will
   be used for the first page of printed scores.
 - :staff-short-name. String. This is the abbreviated instrument name that
   will be used for subsequent pages of printed scores.
 - :lowest-written. Note-name symbol. This is the lowest written pitch
   available on the given instrument. Defaults to NIL. A user may only
   define either the lowest-written value or the lowest-sounding value. If a
   lowest-written value is given, the method automatically determines the
   lowest-sounding value based on the lowest-written value and the
   transposition value.
 - :highest-written. Note-name symbol. This is the highest written pitch
   available on the given instrument. Defaults to NIL. A user may only
   define either the highest-written value or the highest-sounding value. If
   a highest-written value is given, the method automatically determines the
   highest-sounding value based on the highest-written value and the
   transposition value.
 - :lowest-sounding. Note-name symbol. This is the lowest sounding pitch
   available on the given instrument. Defaults to NIL. A user may only
   define either the lowest-sounding value or the lowest-written value. If a
   lowest-sounding value is given, the method automatically determines the
   lowest-written value based on the lowest-sounding value and the
   transposition value.
 - :highest-sounding. Note-name symbol. This is the highest sounding pitch
   available on the given instrument. Defaults to NIL. A user may only
   define either the highest-sounding value or the highest-written value. If
   a highest-sounding value is given, the method automatically determines
   the highest-written value based on the highest-sounding value and the
   transposition value.
 - :transposition. Note-name symbol. This is the key of the given instrument
   (such as the "B-flat" of the "B-flat clarinet"), given as a note-name
   symbol (such as 'BF for B-flat). If a value is only given for the
   :transposition argument but not for the :transposition-semitones
   argument, and there are multiple semitone transposition options for the
   key specified, the method will choose the most common semitone
   transposition for that given key. NB: When using keyword argument
   :transposition rather than :transposition-semitones, sc will have a
   warning printed by cm with indications as to which direction the
   transposition has been undertaken.
 - :transposition-semitones. Integer (positive or negative). The number of
   semitones lower that a given instrument sounds than written, e.g. -2 for
   B-flat Clarinet. If a value is only given for the
   :transposition-semitones argument but not for the :transposition
   argument, the method will automatically determine the key for the
   :transposition argument. The listener will drop into the debugger with an
   error if a key is given for the :transposition argument and the number
   specified for the :transposition-semitones does not correspond with that
   key.
 - :starting-clef. Symbol. This value determines the first clef that a given
   instrument is to use if that instrument can use different clefs. For a
   list of available clefs see the :clefs argument below. 
   Default = 'treble.
 - :clefs. List of symbols. All clefs that a given instrument may use in the
   course of a piece. Clefs available are treble, alto, tenor, bass,
   percussion, double-treble, and double-bass. Clefs are to be given in
   order of preference. Defaults automatically to the value given to
   :starting-clef if no other clefs are specified. NB: If a separate list is
   indeed given here, the method will automatically add the value for
   :starting-clef as well, should it have been omitted. In this case, a
   warning will also be printed.
 - :clefs-in-c. List of symbols. Similar to :clefs, but designates which
   clefs an instrument uses in a C-score; for example, bass clarinet may
   notated in bass cleff for sounding pitches though it is standardly
   notated in treble clef for written pitches. For a list of clefs available
   see the :clefs argument above.
 - :largest-fast-leap. Number. This value indicates the largest interval, in
   semitones, that a player can feasibly perform at a fast tempo on the
   given instrument. Default = 999. "Fast" here is determined for the whole
   piece by the slippery-chicken class's fast-leap-threshold slot.
 - :score-write-in-c. T or NIL. Determines whether the musical material for
   the given instrument should be printed in C.  T = print in C. 
   Default = NIL.
 - :score-write-bar-line. Integer. This argument is used for indicating
   system-grouping in the printed score. The given integer specifies how
   many instruments above this one should be grouped together with an
   unbroken bar-line. Default = 1.
 - :midi-program. Integer. The number of the MIDI program to be used for
   playing back this instrument. Default = 1.
 - :chords. T or NIL. Indicates whether the given instrument is capable of
   playing chords (starting with 2-note simultaneities, but not
   multiphonics).
 - :subset-id. Symbol, string, number, or NIL.  Indicates the ID of a
   specific subset of the current set to which the instrument's pitch
   selection is limited.  No error will occur if no subset with this ID
   exists in a given set, i.e. some may include this subset, some may not
   and everything will function correctly--if the specified subset is not
   present in the current set the pitch selection routine will select from
   the whole set.  In every case however, the usual set limiting according
   to instrument range etc. will also apply.  Default = NIL.
 - :microtones. T or NIL. Indicates whether the instrument can play
   microtones. T = can play microtones. Default = NIL. NB: If this value is
   set to T, a separate :microtones-midi-channel must be specified; this can
   be done for the given instrument object in the :ensemble block of the
   make-slippery-chicken function.
 - :missing-notes. A list of note-name symbols. This is a list of any notes
   which the given instrument can't play, for example certain
   quarter-tones. These are to be given by the user as written-pitch
   note-name symbols, but are always stored by the method as sounding
   pitches.
 - :prefers-notes. Symbol. 'high, 'low or NIL. This value indicates whether
   to give preference, when choosing notes for the given instrument, to
   pitches from the upper or lower end of the instrument's range. When NIL,
   preference is given to notes from its middle register. Default = NIL.
 - :chord-function. If the given instrument can play chords then it will
   need a reference to a function that can select chords for it. NB This
   should be a symbol not a function object; thus, 'my-fun not
   #'my-fun. Default = NIL.

RETURN VALUE

 Returns an instrument object.

EXAMPLE

;; Make-instrument for the flute:
(make-instrument 'flute :staff-name "Flute" :staff-short-name "Fl."
                 :lowest-written 'c4 :highest-written 'd7 
                 :starting-clef 'treble :midi-program 74 :chords nil
                 :microtones t :missing-notes '(cqs4 dqf4))

=> 
INSTRUMENT: lowest-written: 
PITCH: frequency: 261.626, midi-note: 60, midi-channel: 0 
[...]
, highest-written:
PITCH: frequency: 2349.318, midi-note: 98, midi-channel: 0 
[...]
lowest-sounding: 
PITCH: frequency: 261.626, midi-note: 60, midi-channel: 0 
[...]
, highest-sounding: 
PITCH: frequency: 2349.318, midi-note: 98, midi-channel: 0 
            starting-clef: TREBLE, clefs: (TREBLE), clefs-in-c: (TREBLE)
            prefers-notes: NIL, midi-program: 74
            transposition: C, transposition-semitones: 0
            score-write-in-c: NIL, score-write-bar-line: 1
            chords: NIL, chord-function: NIL, 
            total-bars: 0 total-notes: 0, total-duration: 0.0
            total-degrees: 0, microtones: T
            missing-notes: (CQS4 DQF4), subset-id: NIL
            staff-name: Flute, staff-short-name : Fl.,
            largest-fast-leap: 999
[...]
NAMED-OBJECT: id: FLUTE, tag: NIL, 
data: NIL

;; A make-instrument for the b-flat bass clarinet
(make-instrument 'bass-clarinet :staff-name "Bass Clarinet" :lowest-written 'c3 
                 :highest-written 'g6 :staff-short-name "Bass Cl." 
                 :chords nil :midi-program 72 :starting-clef 'treble
                 :microtones t :prefers-notes 'low
                 :missing-notes '(aqs4 bqf4 bqs4 cqs5 dqf5 gqf3 fqs3 fqf3 eqf3
                                  dqs3 dqf3 cqs3)
                 :clefs '(treble) :clefs-in-c '(treble bass)
                 :transposition-semitones -14)

=> 
INSTRUMENT: lowest-written: 
PITCH: frequency: 130.813, midi-note: 48, midi-channel: 0 
[...]
, highest-written: 
PITCH: frequency: 1567.982, midi-note: 91, midi-channel: 0 
[...]
            lowest-sounding: 
PITCH: frequency: 58.270, midi-note: 34, midi-channel: 0 
[...]
, highest-sounding: 
PITCH: frequency: 698.456, midi-note: 77, midi-channel: 0 
[...]
NAMED-OBJECT: id: BASS-CLARINET, tag: NIL, 
data: NIL

SYNOPSIS

(defun make-instrument (id &key 
                        staff-name
                        staff-short-name
                        lowest-written
                        highest-written
                        lowest-sounding
                        highest-sounding
                        transposition
                        transposition-semitones
                        (starting-clef 'treble)
                        clefs
                        (largest-fast-leap 999)
                        score-write-in-c
                        (score-write-bar-line 1)
                        (midi-program 1)
                        chords
                        clefs-in-c
                        subset-id
                        microtones
                        missing-notes
                        prefers-notes
                        chord-function)

instrument/prefers-high [ Methods ]

[ Top ] [ instrument ] [ Methods ]

DESCRIPTION

 Determine whether the PREFERS-NOTES slot of a given instrument object is
 set to 'HIGH. 

ARGUMENTS

 - An instrument object.

RETURN VALUE

 Returns T if the PREFERS-NOTES slot of the given instrument object is set
 to 'HIGH, otherwise NIL.

EXAMPLE

;; Returns T if the PREFERS-NOTES slot of the given instrument object is set to
;; 'HIGH
(let ((i1 (make-instrument 'inst :prefers-notes 'high)))
  (prefers-high i1))

=> T

;; Returns NIL if the PREFERS-NOTES slot of the given instrument object is not
;; set to 'HIGH
(let ((i1 (make-instrument 'inst1))
      (i2 (make-instrument 'inst2 :prefers-notes 'low)))
  (print (prefers-high i1))
  (print (prefers-high i2)))

=>
NIL 
NIL 

SYNOPSIS

(defmethod prefers-high ((ins instrument))

instrument/prefers-low [ Methods ]

[ Top ] [ instrument ] [ Methods ]

DESCRIPTION

 Determine whether the PREFERS-NOTES slot of a given instrument object is
 set to 'LOW. 

ARGUMENTS

 - An instrument object.

RETURN VALUE

 Returns T if the PREFERS-NOTES slot of the given instrument object is set
 to 'LOW, otherwise NIL.

EXAMPLE

;; Returns T if the PREFERS-NOTES slot of the given instrument object is set to
;; 'LOW 
(let ((i1 (make-instrument 'inst :prefers-notes 'low)))
  (prefers-low i1))

=> T

;; Returns NIL if the PREFERS-NOTES slot of the given instrument object is not
;; set to 'LOW
(let ((i1 (make-instrument 'inst1))
      (i2 (make-instrument 'inst2 :prefers-notes 'high)))
  (print (prefers-low i1))
  (print (prefers-low i2)))

=>
NIL 
NIL 

SYNOPSIS

(defmethod prefers-low ((ins instrument))

instrument/set-prefers-high [ Methods ]

[ Top ] [ instrument ] [ Methods ]

DATE

 05 Feb 2011

DESCRIPTION

 Sets the PREFERS-NOTES slot of the given instrument object to 'HIGH.

ARGUMENTS

 - An instrument object.

OPTIONAL ARGUMENTS

 (- optional ignore argument; for internal use only).

RETURN VALUE

 Returns symbol HIGH.

EXAMPLE

;; Returns symbol HIGH by default
(let ((i1 (make-instrument 'inst)))
  (set-prefers-high i1))

=> HIGH

;; Create an instrument object with only an ID, print the PREFERS-NOTES slot to
;; see that it is NIL by default, apply the set-prefers-high, and print the
;; slot again to see the changes
(let ((i1 (make-instrument 'inst)))
  (print (prefers-notes i1))
  (set-prefers-high i1)
  (print (prefers-notes i1)))

=> 
NIL 
HIGH

;; Reset to HIGH from LOW
(let ((i1 (make-instrument 'inst :prefers-notes 'low)))
  (print (prefers-notes i1))
  (set-prefers-high i1)
  (print (prefers-notes i1)))

=>
LOW
HIGH 

SYNOPSIS

(defmethod set-prefers-high ((ins instrument) &optional ignore) 

instrument/set-prefers-low [ Methods ]

[ Top ] [ instrument ] [ Methods ]

DATE

 05 Feb 2011

DESCRIPTION

 Sets the PREFERS-NOTES slot of the given instrument object to 'LOW.

ARGUMENTS

 - An instrument object.

OPTIONAL ARGUMENTS

 (- optional ignore argument; for internal use only).

RETURN VALUE

 Returns symbol LOW.

EXAMPLE

;; Returns symbol LOW by default
(let ((i1 (make-instrument 'inst)))
  (set-prefers-low i1))

=> LOW

;; Create an instrument object with only an ID, print the PREFERS-NOTES slot to
;; see that it is NIL by default, apply the set-prefers-low, and print the
;; slot again to see the changes
(let ((i1 (make-instrument 'inst)))
  (print (prefers-notes i1))
  (set-prefers-low i1)
  (print (prefers-notes i1)))

=> 
NIL 
LOW

;; Reset to LOW from HIGH
(let ((i1 (make-instrument 'inst :prefers-notes 'high)))
  (print (prefers-notes i1))
  (set-prefers-low i1)
  (print (prefers-notes i1)))

=>
HIGH 
LOW

SYNOPSIS

(defmethod set-prefers-low ((ins instrument) &optional ignore)

instrument/transposing-instrument-p [ Methods ]

[ Top ] [ instrument ] [ Methods ]

DESCRIPTION

 Determine whether a given instrument object defines a transposing
 instrument. 

ARGUMENTS

 - An instrument object.

OPTIONAL ARGUMENTS

 - ignore-octaves. T or NIL to indicate whether instruments that transpose
   at the octave are to be considered transposing instruments. 
   T = instruments that transpose at the octave are not considered
   transposing instruments. Default = T.

RETURN VALUE

 Returns T if the given instrument object defines a transposing instrument,
 otherwise NIL.

EXAMPLE

;; Returns NIL if the instrument is not a transposing instrument
(let ((i1 (make-instrument 'instrument-one)))
  (transposing-instrument-p i1))

=> NIL

;; Returns T if the instrument object has been defined using a non-NIL value
;; for :transposition
(let ((i2 (make-instrument 'instrument-two :transposition 'bf)))
  (transposing-instrument-p i2))

=> T

;; Returns T if the instrument object has been defined using a non-0 value for
;; :transposition-semitones 
(let ((i3 (make-instrument 'instrument-two :transposition-semitones -3)))
  (transposing-instrument-p i3))

=> T

;; Setting the optional argument to NIL causes instruments that transpose at
;; the octave to return T.
(let ((i3 (make-instrument 'instrument-two :transposition-semitones -12)))
  (transposing-instrument-p i3))

=> NIL

(let ((i3 (make-instrument 'instrument-two :transposition-semitones -12)))
  (transposing-instrument-p i3 nil))

=> T

SYNOPSIS

(defmethod transposing-instrument-p ((ins instrument) 
                                     &optional (ignore-octaves t))

linked-named-object/instrument [ Classes ]

[ Top ] [ linked-named-object ] [ Classes ]

NAME

 instrument

 File:             instrument.lsp

 Class Hierarchy:  named-object -> linked-named-object -> instrument

 Version:          1.0.0-beta2

 Project:          slippery chicken (algorithmic composition)

 Purpose:          Implementation of the instrument class which defines
                   musical instrument properties like range and
                   collects/stores information about what the instrument
                   plays: how many notes, in how many bars etc.  

 Author:           Michael Edwards: m@michael-edwards.org

 Creation date:    4th September 2001

 $$ Last modified: 14:11:49 Thu Apr 19 2012 BST

 SVN ID: $Id: instrument.lsp 1982 2012-05-24 15:35:54Z medward2 $