instruments/natural-harmonic [ Functions ]

[ Top ] [ instruments ] [ Functions ]

DATE

 December 24th 2013

DESCRIPTION

 Determine whether a pitch can be played as a natural harmonic on a (string)
 instrument (with the guitar as default).

 MDE Tue Jan 8 18:22:09 2019 -- This function is retained for historical
 reasons but has been superseded by the instrument method natural-harmonic?
 along with the associated instrument slots open-strings, open-string-marks,
 and nodes (which altogether are more flexible and efficient than this
 function alone)  

ARGUMENTS

 - the pitch (symbol or pitch object)

OPTIONAL ARGUMENTS

 keyword arguments:
 - :tuning. a list of the fundamentals of the open strings, as pitch objects
   or symbols.  These should descend from the highest string.  Default:
   guitar tuning.  
 - :highest-partial.  Integer. What we consider the highest harmonic possible
   (counting the fundamental as 1).
 - :tolerance.  The deviation in cents that we can accept for the frequency
   comparison.  Default = 10.
 - :debug. Print data for debugging/testing purposes.  Default = NIL.

RETURN VALUE

 The string number and partial number as a list if possible as a harmonic,
 or NIL if not.

EXAMPLE

(NATURAL-HARMONIC 'b5) ; octave harmonic of B string
=> (2 2)
SC> (NATURAL-HARMONIC 'b6) ; octave + 5th of high E string
=> (1 3)

SYNOPSIS

(defun natural-harmonic (pitch &key (tuning '(e5 b4 g4 d4 a3 e3))
                         (highest-partial 6) (tolerance 15) debug)

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.10

 Project:          slippery chicken (algorithmic composition)

 Purpose:          Implementation of the pitch class for holding pitch
                   information: symbolic 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:  12:17:42 Mon Sep 16 2019 CEST

 SVN ID: $Id$

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 warn-again)

pitch/cents-hertz [ Methods ]

[ Top ] [ pitch ] [ Methods ]

DATE

 December 24th 2013

DESCRIPTION

 Convert an offset in cents into the frequency deviation of a pitch.

ARGUMENTS

 - a pitch object
 - the number of cents to offset the pitch and return the frequency
   deviation for  

RETURN VALUE

 The frequency deviation in Hertz of the offset pitch.

EXAMPLE

;;; taking as a given the usual floating point round errors:
(cents-hertz (make-pitch 'a4) 1200) 
=> 439.9999694824219d0 ; i.e. going up an octave from a4 would be 440 Hz higher
(cents-hertz (make-pitch 'a4) -1200)
=> -219.99998474121094d0
(cents-hertz (make-pitch 'a4) 3)
=> 0.7631253666877456d0
(cents-hertz (make-pitch 'a4) 10)
=> 2.5489090105293144d0
(cents-hertz (make-pitch 'a3) 10)
=> 1.2744545052646572d0

SYNOPSIS

(defmethod cents-hertz ((p pitch) cents)

pitch/cmn-display-pitch-list [ Functions ]

[ Top ] [ pitch ] [ Functions ]

DESCRIPTION

 Use CMN to display a list of pitch objects.

ARGUMENTS

 The list of pitch objects. This could also contain cmn objects if
 needed, e.g. cmn::bar, cmn::interior-double-bar, cmn::line-mark, etc.  

OPTIONAL ARGUMENTS

 keyword arguments:
 - :staff. The CMN staff object to display with.  Default = cmn::treble.
 - :size.  The CMN size for the staff.  Default = 20.
 - :file.  The path of the file to (over)write.  
    Default = "pitches.eps" in the directory (get-sc-config 'default-dir)
   (default /tmp)
 - :auto-open.  Whether to open the .EPS file once written. Currently only
    available on OSX with SBCL and CCL.  Uses the default app for .EPS
    files, as if opened with 'open' in the terminal.  Default = Value of
    (get-sc-config cmn-display-auto-open).

RETURN VALUE

 A CMN score object.

SYNOPSIS

(defun cmn-display-pitch-list 
    (pitches &key (staff cmn::treble) (size 20)
     (auto-open (get-sc-config 'cmn-display-auto-open))
     (file (concatenate 'string (get-sc-config 'default-dir) "pitches.eps")))

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
 method 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 new pitch object i.e. this method is non-destructive.

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 method 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/enharmonic-equivalents [ Methods ]

[ Top ] [ pitch ] [ Methods ]

DATE

 25th December 2013

DESCRIPTION

 Test whether two pitches are enharmonically equivalent.

ARGUMENTS

 - pitch object 1 
 - pitch object 2

RETURN VALUE

 T or NIL

EXAMPLE

(enharmonic-equivalents (make-pitch 'gs4) (make-pitch 'af4))
=> T
(enharmonic-equivalents (make-pitch 'gs4) (make-pitch 'gs4))
=> NIL

SYNOPSIS

(defmethod enharmonic-equivalents ((p1 pitch) (p2 pitch))

pitch/find-nearest-pitch [ Functions ]

[ Top ] [ pitch ] [ Functions ]

DATE

 April 23rd 2016, Edinburgh

DESCRIPTION

 In a given list of pitches, find the nearest pitch to the pitch given as
 the 2nd argument. 

ARGUMENTS

 - a list of pitches: either pitch objects or symbols. If symbols they will
   be convered to pitch objects first and optionally sorted from low to
   high.
 - the pitch to use in the search for the nearest. Again: either a pitch
   object or symbol.

OPTIONAL ARGUMENTS

 - T or NIL to indicate whether the pitch list should be sorted from low to
   high before being searched. Default = NIL.

RETURN VALUE

 Two values: the pitch from the pitch list which is the nearest to the 2nd
 argument, and the index of this pitch in the list. NB if the 2nd argument
 is equidistant from two pitches in the list, then the first pitch in the
 list will be returned.

EXAMPLE

(find-nearest-pitch '(b0 d1 fs1 a4) 'e1)
==>
PITCH: frequency: 36.708, midi-note: 26, midi-channel: 0 
       pitch-bend: 0.0 
       degree: 52, data-consistent: T, white-note: D1
       nearest-chromatic: D1
       src: 0.14030775, src-ref-pitch: C4, score-note: D1 
       qtr-sharp: NIL, qtr-flat: NIL, qtr-tone: NIL,  
       micro-tone: NIL, 
       sharp: NIL, flat: NIL, natural: T, 
       octave: 1, c5ths: 0, no-8ve: D, no-8ve-no-acc: D
       show-accidental: T, white-degree: 15, 
       accidental: N, 
       accidental-in-parentheses: NIL, marks: NIL, 
       marks-before: NIL
LINKED-NAMED-OBJECT: previous: NIL, this: NIL, next: NIL
NAMED-OBJECT: id: D1, tag: NIL, 
data: D1
**************

1

SYNOPSIS

(defun find-nearest-pitch (pitch-list pitch &optional auto-sort)

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 original.

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

;; Simple example returning pitch symbols:
(invert-pitch-list '(c4 cs4 f4 b4) t)
=>
(C4 B3 G3 CS3)

;; 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 an alphanumeric note name (e.g. cs4) 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. Default: C4
 - :midi-channel. An integer indicating which MIDI channel is to be used for
   playback of this pitch. Default: 1

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 (pitch &key (src-ref-pitch 'c4) (midi-channel 1))

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 [ Metadata ]

[ Top ] [ pitch ] [ Metadata ]

DESCRIPTION

 Set the SHOW-ACCIDENTAL and ACCIDENTAL-IN-PARENTHESES slots of a specified
 pitch object to NIL, preventing any accidentals or accidentals in
 parentheses from being shown for that event in the printed score.
 
 NB: This will only be effective if the :respell-notes option for
     cmn-display and write-lp-data-for-all is set to NIL.

ARGUMENTS

 - A pitch object.

RETURN VALUE

 Always NIL.

EXAMPLE

(let ((mini
       (make-slippery-chicken
        '+mini+
        :ensemble '(((vn (violin :midi-channel 1))))
        :set-palette '((1 ((c4 cs4 fs4))))
        :set-map '((1 (1)))
        :rthm-seq-palette '((1 ((((2 4) - s s s s - - s s s s -))
                                :pitch-seq-palette ((1 2 3 2 1 2 3 2)))))
        :rthm-seq-map '((1 ((vn (1))))))))
  (no-accidental (pitch-or-chord (get-note mini 1 7 'vn)))
  (cmn-display mini :respell-notes nil)
  (write-lp-data-for-all mini :respell-notes nil))

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 thereof) 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 process
   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 semitone 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. 
 - a number to indicate the frequency deviation allowed before returning 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 returns T
(let ((p1 (make-pitch 'C4))
      (p2 (make-pitch 261.63)))
  (pitch= p1 p2))

=> T

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. NB If you need to print
 these in the context of another printing routine, you can get a string by
 passing NIL as the stream.

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 t))

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 equivalent 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/round-to-nearest [ Methods ]

[ Top ] [ pitch ] [ Methods ]

DATE

 January 30th 2017

DESCRIPTION

 Round the pitch object to the nearest pitch in the current or given scale,
 i.e. force frequency, midi-note, pitch bend, etc. to conform to this nearest
 pitch.

 NB rounding to the nearest using a microtonal :scale argument might cause
 errors if the global (in-scale ...) scale is :chromatic because although
 chromatic-scale is a subset of quarter-tone and twelfth-tone (so all
 chromatic-pitches work) if you have microtonal pitches generated e.g. by
 frequency arguments to make-pitch the note symbol in the microtonal scale
 doesn't exist in :chromatic. E.g. the following breaks:

 (in-scale :chromatic)
 264Hz is approx. c 1/12 sharp
 (round-to-nearest (make-pitch 264) :scale 'twelfth-tone)
 -> fails because rounding in 1/12 tone scale gives us CTS4, which doesn't
 exist in the global chromatic scale. Of course all is well if we do this
 beforehand: 
 (in-scale :twelfth-tone)

ARGUMENTS

 the pitch object

OPTIONAL ARGUMENTS

 keyword argument:
 :scale. The scale to use when rounding. (Common Music tuning object or
 symbol). If a symbol, then 'chromatic-scale, 'twelfth-tone, or 'quarter-tone
 only at present. Default is the current scale as set by (in-scale :...).

RETURN VALUE

 the modified pitch object

EXAMPLE

(make-pitch 443)
-->
PITCH: frequency: 443.000, midi-note: 69, midi-channel: 1 
       pitch-bend: 0.12 
       degree: 138, data-consistent: T, white-note: A4
       nearest-chromatic: A4
       src: 1.6932597032572d0, src-ref-pitch: C4, score-note: A4 
       qtr-sharp: NIL, qtr-flat: NIL, qtr-tone: NIL,  
       micro-tone: T, 
...

(round-to-nearest (make-pitch 443)) 
-->
PITCH: frequency: 440.000, midi-note: 69, midi-channel: 1 
       pitch-bend: 0.0 
       degree: 138, data-consistent: T, white-note: A4
       nearest-chromatic: A4
       src: 1.6817929, src-ref-pitch: C4, score-note: A4 
       qtr-sharp: NIL, qtr-flat: NIL, qtr-tone: NIL,  
       micro-tone: NIL, 
...

;;; exact quarter tones round down, not up (true for quarter-sharps and flats):
(round-to-nearest (make-pitch 'dqs7) :scale 'chromatic-scale)
-->
PITCH: frequency: 2349.318, midi-note: 98, midi-channel: 1 
       pitch-bend: 0.0 
       degree: 196, data-consistent: T, white-note: D7
       nearest-chromatic: D7
       src: 8.979696, src-ref-pitch: C4, score-note: D7 
       qtr-sharp: NIL, qtr-flat: NIL, qtr-tone: NIL,  
       micro-tone: NIL, 
       sharp: NIL, flat: NIL, natural: T, 
       octave: 7, c5ths: 0, no-8ve: D, no-8ve-no-acc: D
       show-accidental: T, white-degree: 57, 
       accidental: N, 
       accidental-in-parentheses: NIL, marks: NIL, 
       marks-before: NIL
LINKED-NAMED-OBJECT: previous: NIL, 
                     this: NIL, 
                     next: NIL
NAMED-OBJECT: id: D7, tag: NIL, 
data: D7
**************

SYNOPSIS

(defmethod round-to-nearest ((p pitch) &key (scale cm::*scale*))

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 specified 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.

OPTIONAL ARGUMENTS

 - A number indicating the MIDI channel which is to be used to play back
   microtonal pitches. NB: See player.lsp/make-player for details on
   microtones in MIDI output. Default = NIL which means it will take on the
   value of the second argument (all pitches on the same channel, whether
   microtonal or not). 

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
                              &optional 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 process
   the 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

 keyword arguments
 - :return-symbols. 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.
 - :package. The name of the package to perform the transpositions. Default =
   :sc.
 - :lowest. Don't transpose pitches which are lower than this
   argument. Default = C-1 (midi note 0)  
 - :lowest. Don't transpose pitches which are higher than this
   argument. Default = B8 (midi note 119) 

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
                             &key
                               (return-symbols nil)
                               (package :sc)
                               lowest highest)

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

[ Top ] [ pitch ] [ Functions ]

DESCRIPTION

 Transpose the pitch values of a list of pitch objects into a specified
 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 process
   the 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))