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

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

NAME

``` pitch

File:             pitch.lsp

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

Version:          1.1.0

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

SVN ID: \$Id\$
```

[ 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)))
(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)))
(marks p))

=> (PIZZ PIZZ)
WARNING:
```

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)))
(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)))
(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. i.e. ascending notes return descending notes from the bottom pitch
down. This is quite different to the concept of chord inversion, where we
move from root position to first inversion, second inversion, etc.

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. Note that if one or more pitch objects have been initialised
then it is not necessary to specify the octave as the last octave will be
used.
```

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

;;  make two pitch objects; the 2nd uses the octave of the first
(progn (make-pitch 'cs6)
(make-pitch 'a))
=>
PITCH: frequency: 1760.000, midi-note: 93, midi-channel: 1
pitch-bend: 0.0
degree: 186, data-consistent: T, white-note: A6
nearest-chromatic: A6
...
```

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/midi-play-pitch-list [ Functions ]

[ Top ] [ pitch ] [ Functions ]

DATE

``` January 2nd 2020, Heidhausen
```

DESCRIPTION

``` Generate a MIDI file from a list of pitches.
```

ARGUMENTS

``` the pitch list: either pitch objects or symbols
```

OPTIONAL ARGUMENTS

``` keyword arguments:
- :rhythm. The rhythm (symbol or object) to be used for all pitches. Default
= 'e (eighth note)
- :tempo. The MIDI file tempo. Default = 120BPM.
- :file. The patch of the MIDI file to write. Default = "/tmp/tmp.mid"
```

RETURN VALUE

``` the MIDI file path (string)
```

SYNOPSIS

```(defun midi-play-pitch-list (pitches
&key (rhythm 'e) (tempo 120) (file "/tmp/tmp.mid"))
```

[ 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/partial-nodes [ Functions ]

[ Top ] [ pitch ] [ Functions ]

DATE

``` August 30th 2023
```

DESCRIPTION

``` Calculate the pitches that represent the nodal/touching points to achieve a
particular partial number from a given open-string. Note that despite the
general rule that nodes are available from one to 1- the desired partial,
not all can be used because they coincide with lower-order
partials. E.g. to get the 4th partial (double octave, usually achieved by
touching a perfect fourth above the open string) we have nodes at 1/4 and
3/4 but not at 2/4 because that is 1/2 i.e. the second partial.

```

ARGUMENTS

``` - the pitch of the open string either as a symbol or pitch object
- the desired partial number (where 1 = the open string)
```

RETURN VALUE

``` a list of ascending pitch objects representing the nodal/touching
points. Note that the last pitch will always be the harmonic sounding pitch.
last
```

EXAMPLE

```(partial-nodes 'd3 6)
(
PITCH: frequency: 176.199, midi-note: 53, midi-channel: 1
pitch-bend: 0.16
...
data: F3
**************

PITCH: frequency: 880.994, midi-note: 81, midi-channel: 1
pitch-bend: 0.02
...
data: A5
**************
)

;;; the closest pitches, rounded to a quarter-tone (the default scale) for
;;; then7th partial on the cello's D string (II) :
(mapcar #'id (partial-nodes 'd3 7))
--> (EQS3 AF3 BQS3 EQS4 BQS4 BQS5)
```

SYNOPSIS

```(defun partial-nodes (open-string partial)
```

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-or-chord= [ Methods ]

[ Top ] [ pitch ] [ Methods ]

AUTHOR

``` Daniel Ross (mr.danielross[at]gmail[dot]com)
```

DATE

``` Tue 29 Oct 2019 08:57:53 GMT - Warwick
```

DESCRIPTION

``` Convenience method, test to see if the pitch-or-chord slots of two event
objects are the same.
```

ARGUMENTS

``` - a pitch or chord object
- a pitch or chord 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 or chord 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-or-chord= p1 p2))

=> T

(let ((p1 (make-pitch 'c4))
(p2 (make-pitch 'bs3)))
(pitch-or-chord= p1 p2))

=> NIL

(let ((p1 (make-pitch 'c4))
(p2 (make-pitch 'bs3)))
(pitch-or-chord= p1 p2 t))

=> T

(let ((p1 (make-pitch 'c4))
(c1 (make-chord '(c4 e4 g4))))
(pitch-or-chord= p1 c1))

=> NIL

(let ((c1 (make-chord '(c4 e4 g4)))
(c2 (make-chord '(c4 e4))))
(pitch-or-chord= c1 c2))

=> NIL

(let ((c1 (make-chord '(c4 e4 g4)))
(c2 (make-chord '(bs4 ff4 g4))))
(pitch-or-chord= c1 c2))

=> NIL

(let ((c1 (make-chord '(c4 e4 g4)))
(c2 (make-chord '(bs3 ff4 g4))))
(pitch-or-chord= c1 c2 t))

=> T

;; Chords with only one pitch are the same as pitch object with the same pitch.
(let ((c (make-chord '(c4)))
(p (make-pitch 'c4)))
(pitch-or-chord= c p))

=> T
```

SYNOPSIS

```(defmethod pitch-or-chord= ((p1 pitch) (p2 pitch)
&optional enharmonics-are-equal
(frequency-tolerance 0.01))
```

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

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

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

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

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
(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 (or default smallest step
for the current scale).

NB: This method returns a new pitch object rather than altering the values
of the current pitch object.
NB: the :destructively argument is ignored in this class
```

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

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)
destructively)
```

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

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

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

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