./../../src/pitch.lsp

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

     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: 22:11:06 Thu Apr 18 2013 BST

     SVN ID: $Id: pitch.lsp 3462 2013-04-19 06:27:05Z 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/cmn-display-pitch-list [ Functions ]

[ Top ] [ pitch ] [ Functions ]

DESCRIPTION

     Use CMN to display a list of pitch objects.

ARGUMENTS

     The list of pitch objects

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 = "/tmp/pitches.eps"

RETURN VALUE

     A CMN score object.

SYNOPSIS

    (defun cmn-display-pitch-list (pitches &key (staff cmn::treble) (size 20)
                                   (file "/tmp/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 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 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/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

    ;; 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 [ 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.

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

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

     - 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 transpositions. 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 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))