linked-named-object/pitch [ Classes ]

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

NAME

 pitch

 File:             pitch.lsp

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

 Version:          1.0.0-beta2

 Project:          slippery chicken (algorithmic composition)

 Purpose:          Implementation of the pitch class for holding pitch
                   information: sybmolic representation (eg c4), MIDI note
                   number, frequency, sampling-rate conversion etc.

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

 Creation date:    March 18th 2001

 $$ Last modified: 20:42:24 Sat May 19 2012 BST

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

pitch/add-mark [ Methods ]

[ Top ] [ pitch ] [ Methods ]

DESCRIPTION

 Add a specified mark to the MARKS slot of the given pitch object.

 NB: The add-mark method does not check first to see whether the mark being
 added is a legitimate mark. It does print a warning, however, when the
 specified mark is already present in the MARKS slot, though it adds it
 anyway. 

ARGUMENTS

 - A pitch object.
 - A symbol that is a mark.

RETURN VALUE

 A list. The method returns the entire contents of the given pitch object's
 MARKS slot as a list.

 Prints a warning when the specified mark is already present in the given
 pitch object's MARKs slot.

EXAMPLE

;; By default the MARKS slot of a newly created pitch object is set to NIL
(let ((p (make-pitch 'c4)))
  (marks p))

=> NIL

;; Add two marks and print the contents of the given pitch object's MARKS slot
;; to see the changes
(let ((p (make-pitch 'c4)))
  (add-mark p 'pizz)
  (add-mark p 'a)
  (print (marks p)))  

=>
(A PIZZ)

;; Prints a warning when the specified mark is already present in the MARKS
;; slot, though it adds it again anyway.
(let ((p (make-pitch 'c4)))
  (add-mark p 'pizz)
  (add-mark p 'pizz)
  (marks p))

=> (PIZZ PIZZ)
WARNING: 
pitch::add-mark: mark PIZZ already present but adding again!

SYNOPSIS

(defmethod add-mark ((p pitch) mark &optional warn-rest)

pitch/degree- [ Methods ]

[ Top ] [ pitch ] [ Methods ]

DESCRIPTION

 Determine the difference between the quarter-tone degree of one pitch
 object and that of a second. 

 NB: This method does not return absolute difference; instead, it may return
 positive or negative results depending on the order in which the pitch
 objects are given. (This will aid in revealing directionality.)
 
 NB: The DEGREE slot is measured in quarter-tones, not semitones. Thus,
 middle-C is degree 120, not 60, and the difference between two consecutive
 semitones is 2, not 1.

ARGUMENTS

 - A first pitch object.
 - A second pitch object.

RETURN VALUE

 Returns a number. The number may be positive or negative.

EXAMPLE

;; Subtracting the lower pitch object from the higher returns a positive number
(let ((p1 (make-pitch 'd4))
      (p2 (make-pitch 'c4)))
  (degree- p1 p2))

=> 4

;; Reversing the order in which the pitch objects are entered may return a
;; negative number
(let ((p1 (make-pitch 'd4))
      (p2 (make-pitch 'c4)))
  (degree- p2 p1))

=> -4

SYNOPSIS

(defmethod degree- ((p1 pitch) (p2 pitch))

pitch/delete-marks [ Methods ]

[ Top ] [ pitch ] [ Methods ]

DESCRIPTION

 Delete all marks stored in the MARKS slot of the given pitch object and
 reset the slot to NIL.

ARGUMENTS

 - A pitch object.

RETURN VALUE

 Always returns NIL

EXAMPLE

;; Add two marks, then delete them. The method returns NIL
(let ((p (make-pitch 'c4)))
  (add-mark p 'pizz)
  (add-mark p 'a)
  (delete-marks p))

=> NIL

;; Add two marks and print the MARKS slot to see the changes. Then apply the
;; delete-marks method and print the MARKS slot to see the changes.
(let ((p (make-pitch 'c4)))
  (add-mark p 'pizz)
  (add-mark p 'a)
  (print (marks p))
  (delete-marks p)
  (print (marks p)))

=> 
(A PIZZ) 
NIL 

SYNOPSIS

(defmethod delete-marks ((p pitch))

pitch/enharmonic [ Methods ]

[ Top ] [ pitch ] [ Methods ]

DESCRIPTION

 Get the enharmonic equivalent of the given pitch object. Two chromatically
 consecutive "white-note" pitches (e.g. B-sharp/C-natural) are considered
 enharmonically equivalent. If there is no enharmonic equivalent, the
 function just returns the same note.

ARGUMENTS

 - A pitch object.

OPTIONAL ARGUMENTS

 - T or NIL to print a warning when no enharmonic can be found. Default = T. 

RETURN VALUE

 A pitch object.

EXAMPLE

;; A "black-key" enharmonic equivalent
(let ((p (make-pitch 'cs4)))
  (data (enharmonic p)))

=> DF4

;; Two chromatically consecutive "white-keys" are enharmonically equivalent
(let ((p (make-pitch 'f4)))
  (data (enharmonic p)))

=> ES4

;; The function returns a pitch object with the same pitch value if there is no
;; enharmonic equivalent
(let ((p (make-pitch 'g4)))
  (data (enharmonic p)))

=> G4

SYNOPSIS

(defmethod enharmonic ((p pitch) &key (warn t))

pitch/in-octave [ Functions ]

[ Top ] [ pitch ] [ Functions ]

DESCRIPTION

 Test to see if a specified pitch item falls within a specified octave. The
 pitch item can be a pitch object, a numerical frequency value, or a
 note-name symbol. 

ARGUMENTS

 - A pitch item. This can be a pitch object, a numerical frequency value, or
   a note-name symbol. 
 - A number that is the specified octave designator (e.g. the "4" in "C4").

RETURN VALUE

 T if the specified pitch item falls within the specified octave, otherwise
 NIL. 

EXAMPLE

;; The function returns NIL if the specified pitch item does not fall within
;; the specified octave.
(let ((p (make-pitch 'c4)))
  (in-octave p 3))

=> NIL

;; The function will accept pitch objects
(let ((p (make-pitch 'c4)))
  (in-octave p 4))

=> T

;; The function will accept numerical frequency values
(let ((p 261.63))
  (in-octave p 4))

=> T

;; The function will accept note-name symbols
(let ((p 'c4))
  (in-octave p 4))

=> T

SYNOPSIS

(defun in-octave (pitch octave)

pitch/invert-pitch-list [ Functions ]

[ Top ] [ pitch ] [ Functions ]

DESCRIPTION

 Using the lowest note in the list as the reference point, invert the rest
 of a given list of pitch items according to their distance from it. 

 The list of pitch items may consist of either note-name symbols, pitch
 objects or frequency numbers.

 NB: This function adheres to a concept of inversion more related to
 interval set theory than to the traditional inversion of a melodic
 contour. The given list of pitch items is first sorted from low to high
 before the internal semitone intervals are assessed. The resulting list
 will therefore always be in chromatic order, rather than having the
 inverted melodic contour of the orginal.

ARGUMENTS

 - A list of pitch items. This may consist of pitch objects, note-name
   symbols, or frequency numbers.

OPTIONAL ARGUMENTS

 - T or NIL to indicate whether the result should be a list of pitch objects
   or a list of note-name symbols. T = note-name symbols. Default = NIL.
 - The package in which the process is to be performed. Default = :sc.

RETURN VALUE

 Returns list of pitch objects by default. If the first optional argument is
 set to T, the function will return a list of note-name symbols instead.

EXAMPLE

;; The function returns a list of pitch objects by default
(let ((pl))
  (setf pl (loop for m in '(E4 G4 A4 C4) collect (make-pitch m)))
  (invert-pitch-list pl))

=>
(
PITCH: frequency: 261.626, midi-note: 60, midi-channel: 0 
[...]
data: C4
[...]
PITCH: frequency: 207.652, midi-note: 56, midi-channel: 0 
[...]
data: AF3
[...]
PITCH: frequency: 174.614, midi-note: 53, midi-channel: 0 
[...]
data: F3
[...]
PITCH: frequency: 155.563, midi-note: 51, midi-channel: 0 
[...]
data: EF3
)

;; Setting the first optional argument to T will cause the function to return a
;; list of note-name symbols instead
(let ((pl))
  (setf pl '(329.63 392.00 440.00 261.63))
  (invert-pitch-list pl t))

=> (C4 AF3 F3 EF3)

SYNOPSIS

(defun invert-pitch-list (pitch-list &optional
                          (return-symbols nil)
                          (package :sc))

pitch/make-pitch [ Functions ]

[ Top ] [ pitch ] [ Functions ]

DESCRIPTION

 Create a pitch object, specifying a note as either a symbol or a
 number. When the note is specified as a symbol, it is treated as a
 note-name; when it is specified as a number, it is treated as a frequency
 in hertz.
 
 NB if a pitch object is created from a frequency (rather than note symbol)
 then the given frequency is stored and the note/midi-note etc. nearest to
 it will be stored also.  So the frequency might not be the exact frequency
 of the reflected note.  This is by design, so that unusual temperaments can
 retain exact frequencies and show nearest notes etc.

ARGUMENTS

 - A note, either as a alphanumeric note name or a numeric hertz frequency.  

OPTIONAL ARGUMENTS

 keyword arguments:
 - :src-ref-pitch. A note-name symbol indicating the perceived fundamental
   pitch of a given digital audio file, to allow for later transposition of
   that audio file using note-names.
 - :midi-channel. An integer indicating which MIDI channel is to be used for
   playback of this pitch.

RETURN VALUE

 - A pitch object.

EXAMPLE

;; Make a pitch object using a note-name symbol
(make-pitch 'c4)

=> 
PITCH: frequency: 261.626, midi-note: 60, midi-channel: 0 
       pitch-bend: 0.0 
       degree: 120, data-consistent: T, white-note: C4
       nearest-chromatic: C4
       src: 1.0, src-ref-pitch: C4, score-note: C4 
       qtr-sharp: NIL, qtr-flat: NIL, qtr-tone: NIL,  
       micro-tone: NIL, 
       sharp: NIL, flat: NIL, natural: T, 
       octave: 4, c5ths: 0, no-8ve: C, no-8ve-no-acc: C
       show-accidental: T, white-degree: 28, 
       accidental: N, 
       accidental-in-parentheses: NIL, marks: NIL
LINKED-NAMED-OBJECT: previous: NIL, this: NIL, next: NIL
NAMED-OBJECT: id: C4, tag: NIL, 
data: C4

;; Make a pitch object using a frequency in hertz and including a value for the
;; keyword argument :midi-channel, then print the DATA and MIDI-NOTE slots to
;; see the method's automatic conversion for those values.
(let ((p (make-pitch 261.63 :midi-channel 1)))
  (print (data p))
  (print (midi-note p)))

=>
C4
60

;; Make a pitch object for use with a digital audio file that includes a
;; note-name symbol for the sample-rate-conversion reference pitch; then print
;; the SRC slot of the resulting pitch object
(let ((p (make-pitch 'c4 :src-ref-pitch 'a4)))
  (src p))

=> 0.5946035487490308

SYNOPSIS

(defun make-pitch (note &key (src-ref-pitch 'c4) (midi-channel 0))

pitch/midi- [ Methods ]

[ Top ] [ pitch ] [ Methods ]

DESCRIPTION

 Determine the difference in number of semitones between the values of the
 MIDI values of two given pitch objects. 

 NB: This method does not return absolute difference; instead, it may return
 positive or negative results depending on the order in which the pitch
 objects are given. (This will aid in revealing directionality.)

ARGUMENTS

 - A first pitch object.
 - A second pitch object.

RETURN VALUE

 Returns a number. The number may be positive or negative.

EXAMPLE

;; Subtracting the lower pitch object from the higher returns a positive number
(let ((p1 (make-pitch 'd4))
      (p2 (make-pitch 'c4)))
  (midi- p1 p2))

=> 2

;; Reversing the order in which the pitch objects are entered may return a
;; negative number
(let ((p1 (make-pitch 'd4))
      (p2 (make-pitch 'c4)))
  (midi- p2 p1))

=> -2

SYNOPSIS

(defmethod midi- ((p1 pitch) (p2 pitch))

pitch/no-accidental [ Methods ]

[ Top ] [ pitch ] [ Methods ]

DESCRIPTION

 don't show any accidentals when writing a score; none in parentheses either

ARGUMENTS

OPTIONAL ARGUMENTS

RETURN VALUE

EXAMPLE

SYNOPSIS

(defmethod no-accidental ((p pitch))

pitch/note= [ Methods ]

[ Top ] [ pitch ] [ Methods ]

DESCRIPTION

 Tests to see the note-name symbols (values in the DATA slots) of two given
 pitch objects are equal. 

 NB: This method allows for the comparison of pitch objects created using
 frequency numbers and those created using note-name symbols.

ARGUMENTS

 - A first pitch object.
 - A second pitch object.

RETURN VALUE

 T if the note-name symbols of the given pitch objects are equal, otherwise
 NIL.  

EXAMPLE

;; Two pitch objects with equal note-name symbols return T
(let ((p1 (make-pitch 'c4))
      (p2 (make-pitch 'c4)))
  (note= p1 p2))

=> T
;; Two pitch objects with unequal note-name symbols return F
(let ((p1 (make-pitch 'c4))
      (p2 (make-pitch 'd4)))
  (note= p1 p2))

=> NIL

;; Pitch objects created using frequency numbers and those created using
;; note-name symbols can be effectively compared using this method
(let ((p1 (make-pitch 'c4))
      (p2 (make-pitch 261.63)))
  (note= p1 p2))

=> T

SYNOPSIS

(defmethod note= ((p1 pitch) (p2 pitch) &optional ignore)

pitch/pitch- [ Methods ]

[ Top ] [ pitch ] [ Methods ]

DESCRIPTION

 Get the distance in semitones between the values of two pitch objects. This
 method also takes fractional values into consideration. The

ARGUMENTS

 - A first pitch object.
 - A second pitch object.

RETURN VALUE

EXAMPLE

;; Get the distance between two "white-keys"
(let ((p1 (make-pitch 'd4))
      (p2 (make-pitch 'c4)))
 (pitch- p1 p2))

=> 2.0

;; Get the distance in semitones between two frequencies (rounded to the
;; nearest degree, which by default is quarter-tones)
(let ((p1 (make-pitch 293.66))
      (p2 (make-pitch 261.63)))
 (pitch- p1 p2))

=> 2.0

;; Getting the distance in semitones between pitches with fractional values can
;; return fractional results
(let ((p1 (make-pitch 'dqs4))
      (p2 (make-pitch 'c4)))
 (pitch- p1 p2))

=> 2.5

SYNOPSIS

(defmethod pitch- ((p1 pitch) (p2 pitch))

pitch/pitch-class-eq [ Methods ]

[ Top ] [ pitch ] [ Methods ]

DATE

 14 Aug 2010

DESCRIPTION

 Test whether the values of two pitch objects are of the same pitch class,
 i.e. both Cs, or F#s,irrespective of octave. 

ARGUMENTS

 - A first pitch object.
 - A second pitch object.

OPTIONAL ARGUMENTS

 - T or NIL to indicate whether or not enharmonic pitches are considered 
   equal. T = enharmonic pitches are considered equal. Default = NIL. 

RETURN VALUE

 T if the values of the two pitch objects are of the same pitch class,
 otherwise NIL.

EXAMPLE

;; A comparison of two pitch objects with values of the same pitch class
;;; returns T
(let ((p1 (make-pitch 'c4))
      (p2 (make-pitch 'c5)))
  (pitch-class-eq p1 p2))

=> T

;; A comparison of two pitch objects with values of differing pitch classes
;; returns NIL
(let ((p1 (make-pitch 'c4))
      (p2 (make-pitch 'cs5)))
  (pitch-class-eq p1 p2))

=> NIL

;; A comparison of two pitch objects with enharmonically equivalent pitch
;; classes returns NIL by default
(let ((p1 (make-pitch 'c4))
      (p2 (make-pitch 'bs4)))
  (pitch-class-eq p1 p2))

=> NIL

;; Setting the optional argument to T causes the method to consider
;; enharmonically equivalent pitch classes equal
(let ((p1 (make-pitch 'c4))
      (p2 (make-pitch 'bs4)))
  (pitch-class-eq p1 p2 t))

=> T

SYNOPSIS

(defmethod pitch-class-eq ((p1 pitch) (p2 pitch)
                           &optional enharmonics-are-equal)

pitch/pitch-in-range [ Methods ]

[ Top ] [ pitch ] [ Methods ]

DESCRIPTION

 Determine whether the frequency of a given pitch object falls between the
 frequencies of two other given pitch objects.

ARGUMENTS

 - A first pitch object.
 - A second pitch object, which must be lower than the third.
 - A third pitch object, which must be higher than the second.

RETURN VALUE

 T if the frequency value of the first specified pitch object falls between
 the second and third specified pitch objects, otherwise NIL.

EXAMPLE

;; The method returns T when the frequency value of the first pitch object
;; falls between that of the second and third pitch objects.
(let ((p (make-pitch 'c4))
      (l (make-pitch 'g3))
      (h (make-pitch 'a7)))
  (pitch-in-range p l h))

=> T

;; The method returns NIL when the frequency value of the first pitch object is
;; below the range designated by the frequency values of the other two objects.
(let ((p (make-pitch 'g3))
      (l (make-pitch 'c4))
      (h (make-pitch 'a7)))
  (pitch-in-range p l h))

=> NIL

;; The method returns NIL when the frequency value of the first pitch object is
;; above the range designated by the frequency values of the other two objects.
(let ((p (make-pitch 'a7))
      (l (make-pitch 'g3))
      (h (make-pitch 'c4)))
  (pitch-in-range p l h))

=> NIL

;; The method will also return NIL if the frequency value of the second pitch
;; object is higher than that of the third
(let ((p (make-pitch 'c4))
      (l (make-pitch 'a7))
      (h (make-pitch 'g3)))
  (pitch-in-range p l h))

=> NIL

SYNOPSIS

(defmethod pitch-in-range ((p pitch) (lowest pitch) (highest pitch))

pitch/pitch-inc [ Methods ]

[ Top ] [ pitch ] [ Methods ]

DESCRIPTION

 Increment the value of a given pitch object by one degree (default) or by a
 specified number of degrees (optional argument).

 NB: The slippery-chicken package uses a quarter-tone degree system by
 default, so any function or method involving a degree argument will be
 measured in quarter-tones, not semitones. Thus, while the MIDI note value
 for 'C4 is 60 (chromatic semitones), (note-to-degree 'C4) will return
 120. Thus, this method will increment by one quarter-tone by default, and
 any value the chooser uses for the optional argument is also number of
 quarter-tones. 

 NB: This method returns a new pitch object rather than modifying the values
 of the original. 

ARGUMENTS

 - A pitch object.

OPTIONAL ARGUMENTS

 - A number indicating the step (in degrees) by which the pitch value is to
   be incremented. Defaults = 1. 

RETURN VALUE

 Returns a pitch object.

EXAMPLE

;; The method by default returns a pitch object and increments by one
;; quarter-tone 
(let ((p (make-pitch 'c4)))
  (pitch-inc p))

=> 
PITCH: frequency: 269.292, midi-note: 60, midi-channel: 0 
       pitch-bend: 0.5 
       degree: 121, data-consistent: T, white-note: C4
       nearest-chromatic: C4
       src: 1.0293022394180298, src-ref-pitch: C4, score-note: CS4 
       qtr-sharp: 1, qtr-flat: NIL, qtr-tone: 1,  
       micro-tone: T, 
       sharp: NIL, flat: NIL, natural: NIL, 
       octave: 4, c5ths: 0, no-8ve: CQS, no-8ve-no-acc: C
       show-accidental: T, white-degree: 28, 
       accidental: QS, 
       accidental-in-parentheses: NIL, marks: NIL
LINKED-NAMED-OBJECT: previous: NIL, this: NIL, next: NIL
NAMED-OBJECT: id: CQS4, tag: NIL, 
data: CQS4

;; Using the optional argument, increment steps can be changed; for example,
;; here to one semitone (= 2 quarter-tones)
(let ((p (make-pitch 'c4)))
  (data (pitch-inc p 2)))

=> CS4

;; Here the method increments by 4 quarter-tones = 1 whole-tone 
(let ((p (make-pitch 'c4)))
  (data (pitch-inc p 4)))

=> D4

;; Incrementing by an additional number of quarter-tones at each pass 
(let ((p (make-pitch 'c4)))
  (loop for i from 0 to 4 collect (data (pitch-inc p i))))

=> (C4 CQS4 CS4 DQF4 D4)

SYNOPSIS

(defmethod pitch-inc ((p pitch) &optional (degrees 1))

pitch/pitch-intersection [ Functions ]

[ Top ] [ pitch ] [ Functions ]

DESCRIPTION

 Return pitch objects whose values consist of pitches common to two given
 lists of pitch items. The given lists of pitch items can consist of pitch
 objects or note-name symbols, or one list of one type and the second of the
 other. 

ARGUMENTS

 - A first list of pitch objects.
 - A second list of pitch objects.

RETURN VALUE

 Returns a list of pitch objects that are common to both original lists.

EXAMPLE

;; Returns a list of pitch objects
(let ((p1 '(c4 d4 e4 f4))
      (p2 (loop for nn in '(d4 e4 f4 g4) collect (make-pitch nn))))
  (pitch-intersection p1 p2))

(
PITCH: frequency: 293.665, midi-note: 62, midi-channel: 0 
[...]
data: D4
[...]
PITCH: frequency: 329.628, midi-note: 64, midi-channel: 0 
[...]
data: E4
[...]
PITCH: frequency: 349.228, midi-note: 65, midi-channel: 0 
[...]
data: F4
[...]
) 

SYNOPSIS

(defun pitch-intersection (pitch-list1 pitch-list2)

pitch/pitch-list-to-symbols [ Functions ]

[ Top ] [ pitch ] [ Functions ]

DESCRIPTION

 Return as a list the note-name values from a given list of pitch objects.

ARGUMENTS

 - A list of pitch objects.

OPTIONAL ARGUMENTS

 - The package in which to process the list of pitches. Default = :sc.

RETURN VALUE

 A list of note-name symbols

EXAMPLE

;; Create a list of pitch objects and apply the pitch-list-to-symbols method 
(let ((pl))
  (setf pl (loop for m from 0 to 127 by 13 
              collect (make-pitch (midi-to-note m))))
  (pitch-list-to-symbols pl))

=> (C-1 CS0 D1 EF2 E3 F4 FS5 G6 AF7 A8)

SYNOPSIS

(defun pitch-list-to-symbols (pitch-list &optional (package :sc))

pitch/pitch-max [ Methods ]

[ Top ] [ pitch ] [ Methods ]

DESCRIPTION

 Determine which of two specified pitch objects has the greater frequency 
 value and return that pitch object.

 NB: If the two frequency values are equal, the method returns a pitch
 object equivalent to both.

ARGUMENTS

 - A first pitch object.
 - A second ptich object.

RETURN VALUE

 A pitch object.

EXAMPLE

;; Compare two pitch objects and return the one with the greater frequency
;;; value 
(let ((p1 (make-pitch 'c4))
      (p2 (make-pitch 'd4)))
  (pitch-max p1 p2))

=> 
PITCH: frequency: 293.665, midi-note: 62, midi-channel: 0 
       pitch-bend: 0.0 
       degree: 124, data-consistent: T, white-note: D4
       nearest-chromatic: D4
       src: 1.1224620342254639, src-ref-pitch: C4, score-note: D4 
       qtr-sharp: NIL, qtr-flat: NIL, qtr-tone: NIL,  
       micro-tone: NIL, 
       sharp: NIL, flat: NIL, natural: T, 
       octave: 4, c5ths: 0, no-8ve: D, no-8ve-no-acc: D
       show-accidental: T, white-degree: 29, 
       accidental: N, 
       accidental-in-parentheses: NIL, marks: NIL
LINKED-NAMED-OBJECT: previous: NIL, this: NIL, next: NIL
NAMED-OBJECT: id: D4, tag: NIL, 
data: D4

;; Comparing two pitch objects with equal frequency values returns a pitch
;; object equal to both
(let ((p1 (make-pitch 'c4))
      (p2 (make-pitch 'c4)))
  (data (pitch-max p1 p2)))

=> C4

SYNOPSIS

(defmethod pitch-max ((p1 pitch) (p2 pitch))

pitch/pitch-member [ Functions ]

[ Top ] [ pitch ] [ Functions ]

DESCRIPTION

 Test whether a specified pitch is a member of a given list of pitches.

 This function can take pitch objects, note-name symbols or numerical
 frequency values (or lists thereor) as its arguments.

ARGUMENTS

 - A pitch item. This may be a pitch object, a note-name symbol or a
   numerical frequency value.
 - A list of pitch items. These items may be pitch objects, note-name
   symbols, or numerical frequency values.

OPTIONAL ARGUMENTS

 - T or NIL to indicate whether or not the function should consider
   enharmonically equivalent pitches to be equal. T = enharmonics are 
   considered equal. Default = T.
 - The second optional argument allows the user to specify the test for
   comparison, such as note=, pitch-class-eq, or the default pitch=. If the
   user wants to specify his or her own, the test must take three arguments:
   p1, p2 and <enharmonics-are-equivalent> (which may of course be ignored).

RETURN VALUE

 Similar to Lisp's "member" function, this method returns the tail of the
 tested list starting with the specified pitch if the pitch is indeed a
 member of that list, otherwise returns NIL. NB: The list returned is a list
 of pitch objects.

EXAMPLE

;; Returns NIL if the specified pitch item is not a member of the given list 
(let ((pl '(c4 d4 e4)))
  (pitch-member 'f4 pl))

=> NIL

;; Returns the tail of the given list starting from the specified pitch if that
;; pitch is indeed a member of the tested list
(let ((pl '(c4 d4 e4)))
  (pitch-list-to-symbols (pitch-member 'd4 pl)))

=> (D4 E4)

;; Enharmonically equivalent pitches are considered equal by default
(let ((pl '(c4 ds4 e4)))
  (pitch-list-to-symbols (pitch-member 'ef4 pl)))

=> (DS4 E4)

;; Enharmonic equivalence can be turned off by setting the first optional
;; argument to NIL
(let ((pl '(c4 ds4 e4)))
  (pitch-list-to-symbols (pitch-member 'ef4 pl nil)))

=> NIL

SYNOPSIS

(defun pitch-member (pitch pitch-list 
                     &optional (enharmonics-are-equal t)
                               (test #'pitch=))

pitch/pitch-min [ Methods ]

[ Top ] [ pitch ] [ Methods ]

DESCRIPTION

 Determine which of two specified pitch objects has the lower frequency
 value and return that pitch object.

 NB: If the two frequency values are equal, the method returns a pitch
 object equivalent to both.

ARGUMENTS

 - A first pitch object.
 - A second ptich object.

RETURN VALUE

 A pitch object.

EXAMPLE

;; Compare two pitch objects and return the one with the lower frequency value 
(let ((p1 (make-pitch 'c4))
      (p2 (make-pitch 'd4)))
  (pitch-min p1 p2))

=> 
PITCH: frequency: 261.626, midi-note: 60, midi-channel: 0 
       pitch-bend: 0.0 
       degree: 120, data-consistent: T, white-note: C4
       nearest-chromatic: C4
       src: 1.0, src-ref-pitch: C4, score-note: C4 
       qtr-sharp: NIL, qtr-flat: NIL, qtr-tone: NIL,  
       micro-tone: NIL, 
       sharp: NIL, flat: NIL, natural: T, 
       octave: 4, c5ths: 0, no-8ve: C, no-8ve-no-acc: C
       show-accidental: T, white-degree: 28, 
       accidental: N, 
       accidental-in-parentheses: NIL, marks: NIL
LINKED-NAMED-OBJECT: previous: NIL, this: NIL, next: NIL
NAMED-OBJECT: id: C4, tag: NIL, 
data: C4

;; Comparing two pitch objects with equal frequency values returns a pitch
;; object equal to both
(let ((p1 (make-pitch 'c4))
      (p2 (make-pitch 'c4)))
  (data (pitch-min p1 p2)))

=> C4

SYNOPSIS

(defmethod pitch-min ((p1 pitch) (p2 pitch))

pitch/pitch-round [ Methods ]

[ Top ] [ pitch ] [ Methods ]

DESCRIPTION

 Rounds the value of a specified pitch object to the nearest chromatic
 semitone (non-microtonal MIDI) pitch.

ARGUMENTS

 - A pitch object.

OPTIONAL ARGUMENTS

 keyword arguments:
 - :as-symbol. T or NIL to indicate whether the method is to return an
   entire pitch object or just a note-name symbol of the new pitch. NIL = a
   new pitch object. Default = NIL.
 - :package. Used to identify a separate Lisp package in which to itern
   result. This is really only applicable is combination with :as-symbol set
   to T. Default = :sc.

RETURN VALUE

 A pitch object by default.

 If the :as-symbol argument is set to T, then a note-name symbol is returned
 instead. 

EXAMPLE

;; Returns a pitch object by default; here an example rounding a quarter-tone
;;; note-name symbol to the nearest chromatic pitch
(let ((p (make-pitch 'CQS4)))
  (pitch-round p))

=> 
PITCH: frequency: 261.626, midi-note: 60, midi-channel: 0 
[...]
NAMED-OBJECT: id: C4, tag: NIL, 
data: C4

;; Also rounds frequencies to the nearest chromatic pitch. This example first
;; prints the original values automatically stored with frequency 269.0
;; (rounded by default to the nearest quarter-tone), then the new value rounded
;; to the nearest chromatic semitone
(let ((p (make-pitch 269.0)))
  (print (data p))
  (print (pitch-round p :as-symbol t)))

=>
CQS4 
C4 

SYNOPSIS

(defmethod pitch-round ((p pitch) 
                        &key
                        (as-symbol nil)
                        (package :sc))

pitch/pitch< [ Methods ]

[ Top ] [ pitch ] [ Methods ]

DESCRIPTION

 Test to see if the frequency value of one specified pitch object is less
 than that of a second.

 NB: Due to the fact that a given note-name may encompass several
 fractionally different frequencies (e.g. both 261.626 and 261.627 are both
 considered to be C4), this method is not suitable for comparing pitch
 objects of which one was created using a frequency and the other was
 created using a note-name symbol.

ARGUMENTS

 - A pitch object.
 - A second pitch object.

RETURN VALUE

 Returns T if the frequency value of the first pitch object is less than
 that of the second, otherwise NIL.

EXAMPLE

;; T is returned when the frequency of the first pitch is less than that of
;; the second
(let ((p1 (make-pitch 'c4))
      (p2 (make-pitch 'd4)))
  (pitch< p1 p2))

=> T

;; NIL is returned when the frequency of the first pitch is not less than
;; that of the second
(let ((p1 (make-pitch 'c4))
      (p2 (make-pitch 'd4)))
  (pitch< p2 p1))

=> NIL

;; Equivalent pitches return NIL
(let ((p1 (make-pitch 'c4))
      (p2 (make-pitch 'c4)))
  (pitch< p2 p1))

=> NIL

;; This method can be effectively used to compare the frequency values of two
;; pitch objects that were both created using frequency numbers
(let ((p1 (make-pitch 261.63))
      (p2 (make-pitch 293.66)))
  (pitch< p1 p2))

=> T  

;; Due to sc's numerical accuracy, this method is not suitable for comparing
;; pitch objects of which one was created using a note-name symbol and the
;; other was created using a numerical frequency value. Such comparisons may
;; return misleading results.
(let ((p1 (make-pitch 'c4))
      (p2 (make-pitch 261.63)))
  (pitch< p1 p2))

=> T

SYNOPSIS

(defmethod pitch< ((p1 pitch) (p2 pitch))

pitch/pitch<= [ Methods ]

[ Top ] [ pitch ] [ Methods ]

DESCRIPTION

 Test to see if the frequency value of one specified pitch object is less
 than or equal to than that of a second.

 NB: Due to the fact that a given note-name may encompass several
 fractionally different frequencies (e.g. both 261.626 and 261.627 are both
 considered to be C4), this method is not suitable for comparing pitch
 objects of which one was created using a frequency and the other was
 created using a note-name symbol.

ARGUMENTS

 - A pitch object.
 - A second pitch object.

RETURN VALUE

 Returns T if the frequency value of the first pitch object is less than or
 equal to that of the second, otherwise NIL.

EXAMPLE

;; T is returned when the frequency of the first pitch is less than or equal to
;; that of the second
(let ((p1 (make-pitch 'c4))
      (p2 (make-pitch 'd4)))
  (pitch<= p1 p2))

=> T

;; NIL is returned when the frequency of the first pitch is not less than or
;; equal to that of the second
(let ((p1 (make-pitch 'c4))
      (p2 (make-pitch 'd4)))
  (pitch<= p2 p1))

=> NIL

;; Equivalent pitches return T
(let ((p1 (make-pitch 'c4))
      (p2 (make-pitch 'c4)))
  (pitch<= p2 p1))

=> T

;; This method can be effectively used to compare the frequency values of two
;; pitch objects that were both created using frequency numbers
(let ((p1 (make-pitch 261.63))
      (p2 (make-pitch 293.66)))
  (pitch<= p1 p2))

=> T  

;; Due to sc's numerical accuracy, this method is not suitable for comparing
;; pitch objects of which one was created using a note-name symbol and the
;; other was created using a numerical frequency value. Such comparisons may
;; return misleading results.
(let ((p1 (make-pitch 261.63))
      (p2 (make-pitch 'c4)))
  (pitch<= p1 p2))

=> NIL

SYNOPSIS

(defmethod pitch<= ((p1 pitch) (p2 pitch))

pitch/pitch= [ Methods ]

[ Top ] [ pitch ] [ Methods ]

DESCRIPTION

 Determines if the note-name and chromatic semtione MIDI values of two
 specified pitch objects are the same (or very close to each other in the
 case of frequency and src slot comparison).  

 By default, this method returns NIL when comparing enharmonic pitches. This
 can behavior can be changed by setting the optional argument to T, upon
 which enharmonic pitches are considered equal.

 NB: This method may return NIL when comparing pitch objects created using
 frequencies with those created using note-names. The method
 pitch::note= may be more useful in this case.
 
 NB: Pitch objects created using frequencies are only considered equal if
 their frequency values are within 0.01Hz of each other.

ARGUMENTS

 - A first pitch object.
 - A second pitch object.

OPTIONAL ARGUMENTS

 - T or NIL to indicate whether or not enharmonic pitches are considered 
   equal. T = enharmonic pitches are considered equal. Default = NIL. 

RETURN VALUE

 T if the values of the two specified pitch objects are equal, otherwise
 NIL. 

EXAMPLE

;; Comparison of equal pitch objects created using note-name symbols returns T 
(let ((p1 (make-pitch 'C4))
      (p2 (make-pitch 'C4)))
  (pitch= p1 p2))

=> T 

;; Comparison of unequal pitch objects created using note-name symbols returns
NIL 
(let ((p1 (make-pitch 'C4))
      (p2 (make-pitch 'D4)))
  (pitch= p1 p2))

=> NIL

;; Comparison of enharmonically equivalent pitch objects returns NIL by default 
;; Comparison of equal pitch objects created using note-name symbols returns T 
(let ((p1 (make-pitch 'CS4))
      (p2 (make-pitch 'DF4)))
  (pitch= p1 p2))

=> NIL

;; Comparison of enharmonically equivalent pitch objects return T when the
;; optional argument is set to T
;; Comparison of equal pitch objects created using note-name symbols returns T 
(let ((p1 (make-pitch 'C4))
      (p2 (make-pitch 'C4)))
  (pitch= p1 p2 t))

=> T

;; Comparison of pitch objects created using frequencies with those created
;; using note-name symbols return NIL
(let ((p1 (make-pitch 'C4))
      (p2 (make-pitch 261.63)))
  (pitch= p1 p2))

=> NIL

SYNOPSIS

(defmethod pitch= ((p1 pitch) (p2 pitch) &optional enharmonics-are-equal
                   (frequency-tolerance 0.01) (src-tolerance 0.0001))

pitch/pitch> [ Methods ]

[ Top ] [ pitch ] [ Methods ]

DESCRIPTION

 Test to see if the frequency value of one specified pitch object is greater
 than that of a second.

 NB: Due to the fact that a given note-name may encompass several
 fractionally different frequencies (e.g. both 261.626 and 261.627 are both
 considered to be C4), this method is not suitable for comparing pitch
 objects of which one was created using a frequency and the other was
 created using a note-name symbol.

ARGUMENTS

 - A pitch object.
 - A second pitch object.

RETURN VALUE

 Returns T if the frequency value of the first pitch object is greater than
 that of the second, otherwise NIL.

EXAMPLE

;; T is returned when the frequency of the first pitch is greater than that of
;; the second
(let ((p1 (make-pitch 'd4))
      (p2 (make-pitch 'c4)))
  (pitch> p1 p2))

=> T

;; NIL is returned when the frequency of the first pitch is not greater than
;; that of the second
(let ((p1 (make-pitch 'd4))
      (p2 (make-pitch 'c4)))
  (pitch> p2 p1))

=> NIL

;; Equivalent pitches return NIL
(let ((p1 (make-pitch 'd4))
      (p2 (make-pitch 'd4)))
  (pitch> p2 p1))

=> NIL

;; This method can be effectively used to compare the frequency values of two
;; pitch objects that were both created using frequency numbers
(let ((p1 (make-pitch 293.66))
      (p2  (make-pitch 261.63)))
  (pitch> p1 p2))

=> T  

;; Due to sc's numerical accuracy, this method is not suitable for comparing
;; pitch objects of which one was created using a note-name symbol and the
;; other was created using a numerical frequency value. Such comparisons may
;; return misleading results.
(let ((p1 (make-pitch 261.63))
      (p2 (make-pitch 'c4)))
  (pitch> p1 p2))

=> T

SYNOPSIS

(defmethod pitch> ((p1 pitch) (p2 pitch))

pitch/pitch>= [ Methods ]

[ Top ] [ pitch ] [ Methods ]

DESCRIPTION

 Test to see if the frequency value of one specified pitch object is greater
 than or equal to than that of a second.

 NB: Due to the fact that a given note-name may encompass several
 fractionally different frequencies (e.g. both 261.626 and 261.627 are both
 considered to be C4), this method is not suitable for comparing pitch
 objects of which one was created using a frequency and the other was
 created using a note-name symbol.

ARGUMENTS

 - A pitch object.
 - A second pitch object.

RETURN VALUE

 Returns T if the frequency value of the first pitch object is greater than
 or equal to that of the second, otherwise NIL.

EXAMPLE

;; T is returned when the frequency of the first pitch is greater than or equal
;;; to that of the second
(let ((p1 (make-pitch 'd4))
      (p2 (make-pitch 'c4)))
  (pitch>= p1 p2))

=> T

;; NIL is returned when the frequency of the first pitch is not greater than or
;; equal to that of the second
(let ((p1 (make-pitch 'd4))
      (p2 (make-pitch 'c4)))
  (pitch>= p2 p1))

=> NIL

;; Equivalent pitches return T
(let ((p1 (make-pitch 'c4))
      (p2 (make-pitch 'c4)))
  (pitch>= p2 p1))

=> T

;; This method can be effectively used to compare the frequency values of two
;; pitch objects that were both created using frequency numbers
(let ((p1 (make-pitch 293.66)) 
      (p2 (make-pitch 261.63)))
  (pitch>= p1 p2))

=> T  

;; Due to sc's numerical accuracy, this method is not suitable for comparing
;; pitch objects of which one was created using a note-name symbol and the
;; other was created using a numerical frequency value. Such comparisons may
;; return misleading results.
(let ((p1 (make-pitch 'c4))
      (p2 (make-pitch 261.63)))
  (pitch>= p1 p2))

=> NIL

SYNOPSIS

(defmethod pitch>= ((p1 pitch) (p2 pitch))

pitch/print-simple-pitch-list [ Functions ]

[ Top ] [ pitch ] [ Functions ]

DESCRIPTION

 Print the data symbols of a list of pitch objects.

DATE

 April 10th 2012

ARGUMENTS

 - A simple list of pitch objects.

OPTIONAL ARGUMENTS

 - The stream to print to (e.g. an open file). Default: the Lisp Terminal
   (REPL).

RETURN VALUE

 The list of pitch data symbols.

EXAMPLE

(print-simple-pitch-list (init-pitch-list '(c4 d4 e4)))
=>
(C4 D4 E4) 
(C4 D4 E4)

SYNOPSIS

(defun print-simple-pitch-list (pitch-list &optional stream)

pitch/remove-octaves [ Functions ]

[ Top ] [ pitch ] [ Functions ]

DESCRIPTION

 Removes all but one of any pitch items in a given list that have the same
 pitch-class but different octaves, keeping the lowest instance only.

 The list of pitch items may be a list of pitch objects or a list of
 note-name symbols. 

ARGUMENTS

 - A list of pitch items. These may be pitch objects or note-name symbols. 

OPTIONAL ARGUMENTS

 keyword arguments
 - :as-symbol. T or NIL indicating whether the object is to return a list of
   pitch objects or a list of note-name symbols. T = return pitch
   objects. Default = NIL.
 - :package. Used to identify a separate Lisp package in which to itern
   result. This is really only applicable is combination with :as-symbol set
   to T. Default = :sc.
 - :allow. T or NIL to indicate whether pitch objects of certain, specified
   octave-doublings are to be kept even if they are not the lowest. This
   argument takes the form of either a single number or a list of
   numbers. NB: This number does not indicate the octave in which the pitch
   object is found, but rather pitch objects that are the specified number
   of octaves above the lowest instance of the pitch class. Thus, :allow 2
   indicates keeping the lowest pitch plus any instances of the same pitch
   class two octaves above that lowest pitch (i.e.,
   double-octaves). However, it is important to note that the function first
   removes any octave doublings that are not excepted by the :allow
   argument, which may produce confusing results. Given a list of
   consecutive octaves, such as '(C1 C2 C3 C4) and an :allow value of 2, the
   function will first remove any equal pitch classes that are are not 2
   octaves apart, resulting in C2, C3, and C4 being removed as they are one
   octave distant from C1, C2 and C3. The result of the function using these
   values would therefore be '(C1).

RETURN VALUE

 Returns a list of pitch objects by default. If the keyword argument
 :as-symbol is set to T, the method returns a list of note-name symbols
 instead.
 
 If the first element of the pitch list is a number (i.e. a frequency), the 
 method returns a list of frequencies. 

EXAMPLE

;; The method returns a list of pitch objects by default
(remove-octaves '(c1 c2 c3 g3))

=> (
PITCH: frequency: 32.703, midi-note: 24, midi-channel: 0 
[...]
data: C1
[...]
PITCH: frequency: 195.998, midi-note: 55, midi-channel: 0 
[...]
data: G3
[...]
)

;; If the first element of the pitch list is a frequency, the method returns a
;; list of frequencies
(remove-octaves '(261.63 523.26 1046.52 196.00))

=> (261.63 196.0)
 
;; Setting keyword argument :as-symbol to T returns a list of note-name symbols
;; instead 
(remove-octaves '(261.63 523.26 1046.52 196.00) :as-symbol t)

=> (C4 G3)

SYNOPSIS

(defun remove-octaves (pitch-list &key as-symbol allow (package :sc))

pitch/remove-pitches [ Functions ]

[ Top ] [ pitch ] [ Functions ]

DESCRIPTION

 Remove a list of specified pitch items from a given list of pitch
 items. Even if only one pitch item is to be removed it should be stated as
 a list. 

 The pitch items can be in the form of pitch objects, note-name symbols or
 numerical frequency values.

ARGUMENTS

 - A list of pitch items from which the specified list of pitches is to be
   removed. These can take the form of pitch objects, note-name symbols or 
   numerical frequency values.
 - A list of pitch items to remove from the given list. These can take the
   form of pitch objects, note-name symbols or numerical frequency 
   values. Even if only one pitch is to be removed is must be stated as a 
   list. 

OPTIONAL ARGUMENTS

 keyword arguments:
 - :enharmonics-are-equal. Set to T or NIL to indicate whether or not
   enharmonically equivalent pitches are to be considered the same pitch. T
   = enharmonically equaivalent pitches are equal.  Default = T.
 - :return-symbols. Set to T or NIL to indicate whether the function is to
   return a list of pitch objects or note-name symbols. T = note-name
   symbols. Default = NIL.

RETURN VALUE

 Returns a list of pitch objects by default. When the keyword argument
 :return-symbols is set to T, the function will return a list of note-names
 instead. 

 If the specified list of pitches to be removed are not found in the given
 list, the entire list is returned.

EXAMPLE

;; By default the function returns a list of pitch objects
(let ((pl '(c4 d4 e4)))
  (remove-pitches pl '(d4 e4)))

=> (
PITCH: frequency: 261.626, midi-note: 60, midi-channel: 0 
[...]
data: C4
[...]
)

;; Setting the keyword argument :return-symbols to T causes the function to
;; return a list of note-name symbols instead. Note in this example too that
;; even when only one pitch item is being removed, it must be stated as a list. 
(let ((pl '(261.62 293.66 329.62)))
  (remove-pitches pl '(293.66) :return-symbols t))

=> (C4 E4)

;; The function will also accept pitch objects
(let ((pl (loop for n in '(c4 d4 e4) collect (make-pitch n))))
  (remove-pitches pl `(,(make-pitch 'e4)) :return-symbols t))

=> (C4 D4)

;; By default the function considers enharmonically equivalent pitches to be
;; equal 
(let ((pl (loop for n in '(c4 ds4 e4) collect (make-pitch n))))
  (remove-pitches pl '(ef4) :return-symbols t))

=> (C4 E4)

;; This feature can be turned off by setting the :enharmonics-are-equal keyword
;; argument to NIL. In this case here, the specified pitch is therefore not
;; found in the given list and the entire original list is returned. 
(let ((pl (loop for n in '(c4 ds4 e4) collect (make-pitch n))))
  (remove-pitches pl '(ef4) 
                  :return-symbols t
                  :enharmonics-are-equal nil))

=> (C4 DS4 E4)

SYNOPSIS

(defun remove-pitches (pitch-list remove 
                       &key (enharmonics-are-equal t)
                            (return-symbols nil))

pitch/set-midi-channel [ Methods ]

[ Top ] [ pitch ] [ Methods ]

DESCRIPTION

 Set the MIDI-CHANNEL slot of the given pitch object. 

 The method takes two mandatory arguments in addition to the given pitch
 object, the first being the MIDI-channel used for non-microtonal pitch
 objects, the second that used for microtonal pitch objects. 
 
 NB: The pitch object only has one MIDI-CHANNEL slot, and determines whether
 that slot is set to the specfied non-microtonal or microtonal midi-channel
 argument based on whether or not the pitch of the given pitch object is
 determined to be a microtone or not.

ARGUMENTS

 - A pitch object.
 - A number indicating the MIDI channel which is to be used to play back
   non-microtonal pitches.
 - A number indicating the MIDI channel which is to be used to play back
   microtonal pitches.

RETURN VALUE

 A number indicating which value has been set to the given pitch object's
 MIDI-CHANEL slot. 

EXAMPLE

;; When the pitch of the given pitch object is non-microtonal, the method sets
;; that pitch object's MIDI-CHANNEL slot to the first value specified.
(let ((p (make-pitch 'c4)))
  (set-midi-channel p 11 12)
  (midi-channel p))

=> 11

;; When the pitch of the given pitch object is microtonal, the method sets
;; that pitch object's MIDI-CHANNEL slot to the second value specified.
(let ((p (make-pitch 'cqs4)))
  (set-midi-channel p 11 12))

=> 12

SYNOPSIS

(defmethod set-midi-channel ((p pitch) midi-channel microtones-midi-channel)

pitch/sort-pitch-list [ Functions ]

[ Top ] [ pitch ] [ Functions ]

DESCRIPTION

 Sort a list of pitch objects from low to high based on their frequency
 value.

ARGUMENTS

 - A list of pitch objects.

OPTIONAL ARGUMENTS

 - T or NIL to indicate whether the method is to return a list of pitch
   objects or a list of note-name symbols.
 - The package in which the operation is to be performed. Default = :sc.

RETURN VALUE

 Returns a list of pitch objects by default. When the first optional
 argument is set to T, the method returns a list of note-name symbols
 instead. 

EXAMPLE

;; Create a list of pitch objects by passing downward through a series of MIDI
;; values and print the result. Then apply the sort-pitch-list method and print
;; the result of that to see the list now ordered from low to high.
(let ((pl))
  (setf pl (loop for m from 64 downto 60
              collect (make-pitch (midi-to-note m))))
  (print (loop for p in pl collect (data p)))
  (print (sort-pitch-list pl)))

=>
(E4 EF4 D4 CS4 C4) 
(
PITCH: frequency: 261.626, midi-note: 60, midi-channel: 0 
[...]
data: C4
[...]
PITCH: frequency: 277.183, midi-note: 61, midi-channel: 0 
[...]
data: CS4
[...]
PITCH: frequency: 293.665, midi-note: 62, midi-channel: 0 
[...]
data: D4
[...]
PITCH: frequency: 311.127, midi-note: 63, midi-channel: 0 
[...]
data: EF4
[...]
PITCH: frequency: 329.628, midi-note: 64, midi-channel: 0 
[...]
data: E4
)

;; Setting the first optional argument to T causes the method to return a list
;; of note-name symbols instead
(let ((pl))
  (setf pl (loop for m from 64 downto 60
              collect (make-pitch (midi-to-note m))))
  (sort-pitch-list pl t))

=> (C4 CS4 D4 EF4 E4)

SYNOPSIS

(defun sort-pitch-list (pitch-list &optional 
                        (return-symbols nil)
                        (package :sc))

pitch/transpose [ Methods ]

[ Top ] [ pitch ] [ Methods ]

DESCRIPTION

 Transpose the pitch information (frequency, note-name, midi-note etc.) of a
 given pitch object by a specified number of semitones. The number of
 semitones specified can be fractional; however, all fractional values will
 be rounded to the nearest quarter-tone frequency.

 NB: This method returns a new pitch object rather than altering the values
 of the current pitch object.

ARGUMENTS

 - A pitch object.
 - A number representing the number of semitones to be transposed, and which
   can be fractional.

OPTIONAL ARGUMENTS

 keyword arguments:
 - :as-symbol. T or NIL to indicate whether the method is to return an
   entire pitch object or just a note-name symbol of the new pitch. NIL = a
   new pitch object. Default = NIL.
 - :package. Used to identify a separate Lisp package in which to itern
   result. This is really only applicable is combination with :as-symbol set
   to T. Default = :sc.

RETURN VALUE

 A pitch object by default.

 If the :as-symbol argument is set to T, then a note-name symbol is returned
 instead. 

EXAMPLE

;; By default the method returns a pitch object
(let ((p (make-pitch 'c4)))
  (transpose p 2))

=> 
PITCH: frequency: 293.665, midi-note: 62, midi-channel: 0 
       pitch-bend: 0.0 
       degree: 124, data-consistent: T, white-note: D4
       nearest-chromatic: D4
       src: 1.1224620342254639, src-ref-pitch: C4, score-note: D4 
       qtr-sharp: NIL, qtr-flat: NIL, qtr-tone: NIL,  
       micro-tone: NIL, 
       sharp: NIL, flat: NIL, natural: T, 
       octave: 4, c5ths: 0, no-8ve: D, no-8ve-no-acc: D
       show-accidental: T, white-degree: 29, 
       accidental: N, 
       accidental-in-parentheses: NIL, marks: NIL
LINKED-NAMED-OBJECT: previous: NIL, this: NIL, next: NIL
NAMED-OBJECT: id: D4, tag: NIL, 
data: D4

;; Setting the :as-symbol keyword argument to T returns just the note-name
;; symbol of the new pitch instead
(let ((p (make-pitch 'c4)))
  (transpose p 2 :as-symbol t))

=> D4

;; The semitones argument can be set to a decimal-point fraction, which may
;; result in quarter-tone pitch values being returned
(let ((p (make-pitch 'c4)))
  (transpose p 2.5))

=> 
PITCH: frequency: 302.270, midi-note: 62, midi-channel: 0 
       pitch-bend: 0.5 
       degree: 125, data-consistent: T, white-note: D4
       nearest-chromatic: D4
       src: 1.1553527116775513, src-ref-pitch: C4, score-note: DS4 
       qtr-sharp: 1, qtr-flat: NIL, qtr-tone: 1,  
       micro-tone: T, 
       sharp: NIL, flat: NIL, natural: NIL, 
       octave: 4, c5ths: 0, no-8ve: DQS, no-8ve-no-acc: D
       show-accidental: T, white-degree: 29, 
       accidental: QS, 
       accidental-in-parentheses: NIL, marks: NIL
LINKED-NAMED-OBJECT: previous: NIL, this: NIL, next: NIL
NAMED-OBJECT: id: DQS4, tag: NIL, 
data: DQS4

;; Fractional semitone arguments are automatically rounded to the nearest
;; quarter-tone, causing x.5 and x.7, for example, to return the same result,
;; while x.3 and x.1 will return the same value as the given integer
(let ((p (make-pitch 'c4)))
  (print (transpose p 2 :as-symbol t))
  (print (loop for s from 0 to 4 
            collect (transpose p (+ 2 (* s .1)) :as-symbol t)))
  (print (loop for s from 5 to 9
            collect (transpose p (+ 2 (* s .1)) :as-symbol t))))

=>
D4 
(D4 D4 D4 D4 D4) 
(DQS4 DQS4 DQS4 DQS4 DQS4)

SYNOPSIS

(defmethod transpose ((p pitch) semitones &key (as-symbol nil) (package :sc)
                      ignore)

pitch/transpose-pitch-list [ Functions ]

[ Top ] [ pitch ] [ Functions ]

DESCRIPTION

 Transpose the values of a list of pitch objects by a specified number of
 semitones. 

ARGUMENTS

 - A list of pitch objects.
 - A number indicating the number of semitones by which the list is to be
   transposed. 

OPTIONAL ARGUMENTS

 - T or NIL indicating whether the method is to return a list of pitch
   objects or a list of note-name symbols for those pitch objects. T = 
   note-name symbols. Default = NIL.
 - The name of the package to perform the tranpositions. Default = :sc. 

RETURN VALUE

 By default, the method returns a list of pitch objects. When the first
 optional argument is set to T, a list of note-name symbols is returned
 instead. 

EXAMPLE

;; Create a list of pitch objects and apply the transpose-pitch-list method
;; with the semitones argument set to 2
(let ((pl))
  (setf pl (loop for m from 60 to 71 collect (make-pitch (midi-to-note m))))
  (transpose-pitch-list pl 2))

=>
(
PITCH: frequency: 293.665, midi-note: 62, midi-channel: 0 
[...]
PITCH: frequency: 311.127, midi-note: 63, midi-channel: 0 
[...]
PITCH: frequency: 329.628, midi-note: 64, midi-channel: 0 
[...]
PITCH: frequency: 349.228, midi-note: 65, midi-channel: 0 
[...]
PITCH: frequency: 369.994, midi-note: 66, midi-channel: 0 
[...]
PITCH: frequency: 391.995, midi-note: 67, midi-channel: 0 
[...]
PITCH: frequency: 415.305, midi-note: 68, midi-channel: 0 
[...]
PITCH: frequency: 440.000, midi-note: 69, midi-channel: 0 
[...]
PITCH: frequency: 466.164, midi-note: 70, midi-channel: 0 
[...]
PITCH: frequency: 493.883, midi-note: 71, midi-channel: 0 
[...]
PITCH: frequency: 523.251, midi-note: 72, midi-channel: 0 
[...]
PITCH: frequency: 554.365, midi-note: 73, midi-channel: 0 
[...]
)

;; Perform the same action with the return-symbols optional argument set to T
(let ((pl))
  (setf pl (loop for m from 60 to 71 collect (make-pitch (midi-to-note m))))
  (print (transpose-pitch-list pl 2 t)))

=> (D4 EF4 E4 F4 FS4 G4 AF4 A4 BF4 B4 C5 CS5)

SYNOPSIS

(defun transpose-pitch-list (pitch-list semitones &optional 
                             (return-symbols nil)
                             (package :sc))

pitch/transpose-pitch-list-to-octave [ Functions ]

[ Top ] [ pitch ] [ Functions ]

DESCRIPTION

 Transpose the pitch values of a list of pitch objects into a specififed
 octave. The individual initial pitch objects can have initial pitch values
 of different octaves.  

ARGUMENTS

 - A list of pitch objects.
 - A number indicating the octave in which the resulting list should be.

OPTIONAL ARGUMENTS

 keyword arguments:
 - :as-symbols. Set to T or NIL to indicate whether the method is to return
   a list of pitch objects or a list of the note-name symbols from those
   pitch objects. T = return as symbols. Default = NIL.
 - :package. Used to identify a separate Lisp package in which to itern
   result. This is really only applicable is combination with :as-symbol set
   to T. Default = :sc.
 - :remove-duplicates. Set to T or NIL to indicate whether any duplicate
   pitch objects are to be removed from the resulting list.  T = remove
   duplicates. Default = T.

RETURN VALUE

 Returns a list of pitch objects by default. When the keyword argument
 :as-symbols is set to T, the method returns a list of note-name symbols
 instead. 

EXAMPLE

;; Create a list of four pitch objects from random MIDI numbers and print it,
;; then apply transpose-pitch-list-to-octave, setting the octave argument to 4,
;; and print the result
(let ((pl))
  (setf pl (loop repeat 4 collect (make-pitch (midi-to-note (random 128)))))
  (print (loop for p in pl collect (data p)))
  (print (transpose-pitch-list-to-octave pl 4)))

=>
(CS7 F7 B0 D4) 
(
PITCH: frequency: 493.883, midi-note: 71, midi-channel: 0 
[...]
data: B4
[...]
PITCH: frequency: 293.665, midi-note: 62, midi-channel: 0 
[...]
data: D4
[...]
PITCH: frequency: 277.183, midi-note: 61, midi-channel: 0 
[...]
data: CS4
[...]
PITCH: frequency: 349.228, midi-note: 65, midi-channel: 0 
[...]
data: F4
)

;; Setting the keyword argument :as-symbols to T return a list of note-names 
;; instead 
(let ((pl))
  (setf pl (loop repeat 4 collect (make-pitch (midi-to-note (random 128)))))
  (print (loop for p in pl collect (data p)))
  (print (transpose-pitch-list-to-octave pl 4 :as-symbols t)))

=>
(D5 E1 C7 AF1) 
(E4 AF4 D4 C4)

;; The method removes duplicate pitch objects from the resulting list by
;; default 
(let ((pl))
  (setf pl (loop repeat 4 collect (make-pitch (midi-to-note (random 128)))))
  (print (loop for p in pl collect (data p)))
  (print (transpose-pitch-list-to-octave pl 4 :as-symbols t)))

=>
(B7 AF1 AF7 G1) 
(G4 AF4 B4)

SYNOPSIS

(defun transpose-pitch-list-to-octave (pitch-list octave
                                       &key
                                       as-symbols
                                       (package :sc)
                                       (remove-duplicates t))

pitch/transpose-to-octave [ Methods ]

[ Top ] [ pitch ] [ Methods ]

DESCRIPTION

 Transpose the values of a given pitch object to a specified octave.

 NB: This method creates a new pitch object rather than replacing the values
 of the original.

ARGUMENTS

 - A pitch object.
 - A number indicating the new octave.

OPTIONAL ARGUMENTS

 keyword arguments:
 - :as-symbol. T or NIL to indicate whether the method is to return an
   entire pitch object or just a note-name symbol of the new pitch. NIL = a
   new pitch object. Default = NIL.
 - :package. Used to identify a separate Lisp package in which to itern
   result. This is really only applicable is combination with :as-symbol set
   to T. Default = :sc.

RETURN VALUE

 A pitch object by default.

 If the :as-symbol argument is set to T, then a note-name symbol is returned
 instead. 

EXAMPLE

;; Transpose the values of a pitch object containing middle-C (octave 4) to the
;;; C of the treble clef (octave 5)
(let ((p (make-pitch 'c4)))
  (transpose-to-octave p 5))

=> 
PITCH: frequency: 523.251, midi-note: 72, midi-channel: 0 
       pitch-bend: 0.0 
       degree: 144, data-consistent: T, white-note: C5
       nearest-chromatic: C5
       src: 2.0, src-ref-pitch: C4, score-note: C5 
       qtr-sharp: NIL, qtr-flat: NIL, qtr-tone: NIL,  
       micro-tone: NIL, 
       sharp: NIL, flat: NIL, natural: T, 
       octave: 5, c5ths: 0, no-8ve: C, no-8ve-no-acc: C
       show-accidental: T, white-degree: 35, 
       accidental: N, 
       accidental-in-parentheses: NIL, marks: NIL
LINKED-NAMED-OBJECT: previous: NIL, this: NIL, next: NIL
NAMED-OBJECT: id: C5, tag: NIL, 
data: C5

;; Setting the :as-symbol argument to T returns a note-name symbol instead of a
;; pitch object
(let ((p (make-pitch 'c4)))
  (transpose-to-octave p 5 :as-symbol t))

=> C5

SYNOPSIS

(defmethod transpose-to-octave ((p pitch) new-octave 
                                &key
                                (as-symbol nil)
                                (package :sc))