./../../src/chord.lsp

## chord/add-mark [ Methods ]

[ Top ] [ chord ] [ Methods ]

DESCRIPTION

     Add the specified mark to the MARKS slot of the given chord object.

ARGUMENTS

     - A chord object.
     - A mark.

OPTIONAL ARGUMENTS

     - T or NIL to indicate whether to print a warning when attempting to add a
       mark to a rest.

RETURN VALUE

     Returns the full contents of the MARKS slot of the given chord object

EXAMPLE

    ;;; Returns the complete contents of the MARKS slot
    (let ((chrd (make-chord '(cs4 e4 fs4 af4 bf4))))
      (add-mark chrd 'fff)
      (add-mark chrd 'pizz))

    => (PIZZ FFF)

SYNOPSIS

    (defmethod add-mark ((c chord) mark &optional warn-rest)

## chord/chord-equal [ Methods ]

[ Top ] [ chord ] [ Methods ]

DESCRIPTION

     Test to see if two chords are equal.

     NB: Two unsorted chord objects that contain the exact same pitch objects in
         a different order will not be considered equal and will return NIL.

     NB: Equality is tested on pitch content only, not on, for example, the
         values of the MIDI slots of those pitch objects etc.

ARGUMENTS

     - A first chord object.
     - A second chord object.

RETURN VALUE

     T or NIL. T if the pitch content of the chords is equal, otherwise NIL.

EXAMPLE

    ;; Two chords are equal
    (let ((chrd1 (make-chord '(c4 e4 gqs4 bqf4 d5 f5)
                            :midi-channel 11
                            :microtones-midi-channel 12))
          (chrd2 (make-chord '(c4 e4 gqs4 bqf4 d5 f5)
                            :midi-channel 11
                            :microtones-midi-channel 12)))
      (chord-equal chrd1 chrd2))

    => T

    ;; Chord objects with the same pitch objects in a different order are unequal
    (let ((chrd1 (make-chord '(c4 e4 gqs4 bqf4 d5 f5)
                            :midi-channel 11
                            :microtones-midi-channel 12))
          (chrd2 (make-chord '(e4 c4 gqs4 bqf4 d5 f5)
                            :midi-channel 11
                            :microtones-midi-channel 12
                            :auto-sort nil)))
      (chord-equal chrd1 chrd2))

    => NIL

    ;; Only the pitch content is compared. Content of other slots is irrelevant.
    (let ((chrd1 (make-chord '(e4 c4 gqs4 bqf4 d5 f5)
                             :midi-channel 11
                             :microtones-midi-channel 12))
          (chrd2 (make-chord '(e4 c4 gqs4 bqf4 d5 f5)
                             :midi-channel 7
                             :microtones-midi-channel 8)))
      (chord-equal chrd1 chrd2))

    => T

SYNOPSIS

    (defmethod chord-equal ((c1 chord) (c2 chord))

## chord/chord-member [ Methods ]

[ Top ] [ chord ] [ Methods ]

DESCRIPTION

     Test whether a specified pitch object is a member of a given chord object.

ARGUMENTS

     - A chord object.
     - A pitch object. This must be a pitch object, not just a note-name symbol,
       but the pitch object can be made with either a note-name symbol or a
       numerical hertz frequency value.

OPTIONAL ARGUMENTS

     - T or NIL to indicate whether or not the method should consider
       enharmonically equivalent pitches to be equal. T = enharmonics are
       equal. Default = T.

RETURN VALUE

     Similar to Lisp's "member" function, this method returns the tail of the
     data (list of pitch objects) of the tested chord object starting with the
     specified pitch object if that pitch is indeed a member of that list,
     otherwise returns NIL.

     NB: Since the method returns the tail of the given chord (the "rest" of the
         pitches after the given pitch), the result may be different depending
         on whether that chord has been auto-sorted or not.

EXAMPLE

    ;; Returns the tail of pitch objects contained starting with the tested pitch
    (let ((chrd (make-chord '(c4 e4 gqs4 a4 d5 f5 bqf5)
                            :midi-channel 11
                            :microtones-midi-channel 12)))
      (pitch-list-to-symbols (chord-member chrd (make-pitch 'a4))))

    => (A4 D5 F5 BQF5)

    ;; The chord object's default auto-sort feature might appear to affect outcome
    (let ((chrd (make-chord '(d5 c4 gqs4 a4 bqf5 f5 e4)
                            :midi-channel 11
                            :microtones-midi-channel 12)))
      (pitch-list-to-symbols (chord-member chrd (make-pitch 'a4))))

    => (A4 D5 F5 BQF5)

    ;; Returns NIL if the pitch is not present in the tested chord object. This
    ;; example uses the "pitch-list-to-symbols" function to simplify the
    ;; pitch-object output.
    (let ((chrd (make-chord '(d5 c4 gqs4 a4 bqf5 f5 e4)
                            :midi-channel 11
                            :microtones-midi-channel 12)))
      (pitch-list-to-symbols (chord-member chrd (make-pitch 'b4))))

    => NIL

    ;; The optional <enharmonics-are-equal> argument is set to NIL by default
    (let ((chrd (make-chord '(c4 e4 a4 d5 f5))))
      (pitch-list-to-symbols (chord-member chrd (make-pitch 'ds4))))

    => NIL

    ;; Setting the optional <enharmonics-are-equal> argument to T
    (let ((chrd (make-chord '(c4 ef4 a4 d5 f5))))
      (pitch-list-to-symbols (chord-member chrd (make-pitch 'ds4) t)))

    => (EF4 A4 D5 F5)

    ;; The optional <octaves-are-true> argument is NIL by default

    (let ((chrd (make-chord '(c4 ef4 a4 d5 ef5 f5))))
      (pitch-list-to-symbols (chord-member chrd (make-pitch 'c5))))

    => NIL

    ;; If optional <octaves-are-true> argument is set to T, any occurence of the
    ;; same pitch class in a different octave will be considered part of the chord
    ;; and return a positive result.
    (let ((chrd (make-chord '(c4 ef4 a4 d5 ef5 f5))))
      (pitch-list-to-symbols (chord-member chrd (make-pitch 'c5) nil t)))

    => (C4 EF4 A4 D5 EF5 F5)

SYNOPSIS

    (defmethod chord-member ((c chord) (p pitch)
                             &optional (enharmonics-are-equal t)
                                       (octaves-are-true nil))

## chord/common-notes [ Methods ]

[ Top ] [ chord ] [ Methods ]

DESCRIPTION

     Return the integer number of pitches common to two chord objects.

ARGUMENTS

     - A first chord object.
     - A second chord object.

OPTIONAL ARGUMENTS

     - T or NIL to indicate whether enharmonically equivalent pitches are to be
       considered the same pitch. T = enharmonically equivalent pitches are
       considered the same pitch. Default = T.
     - T or NIL to indicate whether the same pitch class in different octaves is
       to be considered the same pitch. T = consider the same pitch class from
       octaves to be the same pitch. Default = NIL.

RETURN VALUE

     Returns an integer that is the number of pitches common to the two chords
     objects.

EXAMPLE

    ;; The following two chord objects have 3 pitches in common
    (let ((chrd-1 (make-chord '(c4 e4 g4 b4 d5 f5)))
          (chrd-2 (make-chord '(d3 f3 a3 c4 e4 g4))))
      (common-notes chrd-1 chrd-2))

    => 3

    ;; By default, enharmonically equivalent pitches are considered to be the same
    ;; pitch
    (let ((chrd-1 (make-chord '(c4 e4 g4 b4 d5 f5)))
          (chrd-2 (make-chord '(d3 f3 a3 c4 ff4 g4))))
      (common-notes chrd-1 chrd-2))

    => 3

    ;; Setting the first optional argument to NIL causes enharmonically equivalent
    ;; pitches to be considered separate pitches
    (let ((chrd-1 (make-chord '(c4 e4 g4 b4 d5 f5)))
          (chrd-2 (make-chord '(d3 f3 a3 c4 ff4 g4))))
      (common-notes chrd-1 chrd-2 nil))

    => 2

    ;; By default, the same pitch class in different octaves is considered to be a
    ;; separate pitch
    (let ((chrd-1 (make-chord '(c4 e4 g4 b4 d5 f5)))
          (chrd-2 (make-chord '(d3 f3 a3 ff4 g4 c5))))
      (common-notes chrd-1 chrd-2 t))

    => 2

    ;; Setting the second optional argument to T causes all pitches of the same
    ;; pitch class to be considered equal regardless of their octave
    (let ((chrd-1 (make-chord '(c4 e4 g4 b4 d5 f5)))
          (chrd-2 (make-chord '(d3 f3 a3 ff4 g4 c5))))
      (common-notes chrd-1 chrd-2 t t))

    => 5

SYNOPSIS

    (defmethod common-notes ((c1 chord) (c2 chord)
                             &optional (enharmonics-are-equal t)
                             (octaves-are-true nil))

## chord/delete-marks [ Methods ]

[ Top ] [ chord ] [ Methods ]

DESCRIPTION

     Delete all marks from the MARKS slot of the given chord object.

ARGUMENTS

     - A chord object.

RETURN VALUE

     Returns NIL.

EXAMPLE

    ;;; Make a chord object, add two marks, and print the MARKS slot to see them;
    ;;; apply delete-marks and print the MARKS slot again to see the change
    (let ((chrd (make-chord '(cs4 e4 fs4 af4 bf4))))
      (add-mark chrd 'fff)
      (add-mark chrd 'pizz)
      (print (marks chrd))
      (delete-marks chrd)
      (print (marks chrd)))

    =>
    (PIZZ FFF)
    NIL

SYNOPSIS

    (defmethod delete-marks ((c chord))

## chord/get-midi-channel [ Methods ]

[ Top ] [ chord ] [ Methods ]

DESCRIPTION

     Get the MIDI channel of the first pitch object contained in a given chord
     object.

     NB: This method returns only the midi-channel of the first pitch object in
         the chord object's data list.

ARGUMENTS

     - A chord object.

RETURN VALUE

     An integer.

EXAMPLE

    (let ((chrd (make-chord '(c4 e4 gqs4 bqf4 d5 f5)
                            :midi-channel 11
                            :microtones-midi-channel 12)))
      (get-midi-channel chrd))

    => 11

SYNOPSIS

    (defmethod get-midi-channel ((c chord))

## chord/get-pitch [ Methods ]

[ Top ] [ chord ] [ Methods ]

DESCRIPTION

     Get the pitch object located at the specified index within the given chord
     object. The <ref> argument is 1-based.

ARGUMENTS

     - A chord object.
     - An integer that is the index of the pitch object sought within the data
       list of the given chord object.

RETURN VALUE

     A pitch object.

EXAMPLE

    (let ((chrd (make-chord '(c4 e4 gqs4 bqf4 d5 f5)
                            :midi-channel 11
                            :microtones-midi-channel 12)))
      (get-pitch chrd 3))

    =>
    PITCH: frequency: 403.482, midi-note: 67, midi-channel: 12
           pitch-bend: 0.5
           degree: 135, data-consistent: T, white-note: G4
           nearest-chromatic: G4
           src: 1.5422108173370361, src-ref-pitch: C4, score-note: GS4
           qtr-sharp: 1, qtr-flat: NIL, qtr-tone: 1,
           micro-tone: T,
           sharp: NIL, flat: NIL, natural: NIL,
           octave: 4, c5ths: 0, no-8ve: GQS, no-8ve-no-acc: G
           show-accidental: T, white-degree: 32,
           accidental: QS,
           accidental-in-parentheses: NIL, marks: NIL
    LINKED-NAMED-OBJECT: previous: NIL, this: NIL, next: NIL
    NAMED-OBJECT: id: GQS4, tag: NIL,
    data: GQS4

SYNOPSIS

    (defmethod get-pitch ((c chord) ref)

## chord/get-pitch-symbols [ Methods ]

[ Top ] [ chord ] [ Methods ]

DESCRIPTION

     Return the data of the pitch objects from a given chord object as a list of
     note-name symbols.

ARGUMENTS

     - A chord object.

RETURN VALUE

     A list of note-name symbols.

EXAMPLE

    (let ((chrd (make-chord '(c4 e4 gqs4 bqf4 d5 f5)
                            :midi-channel 11
                            :microtones-midi-channel 12)))
      (get-pitch-symbols chrd))

    => (C4 E4 GQS4 BQF4 D5 F5)

SYNOPSIS

    (defmethod get-pitch-symbols ((c chord) &optional ignore)

## chord/has-notes [ Methods ]

[ Top ] [ chord ] [ Methods ]

DATE

     16-Aug-2010

DESCRIPTION

     Tests whether a given chord object contains at least one pitch
     object.

     (make-chord nil) is a valid function call and creates a chord object with
     no notes.

ARGUMENTS

     - A chord object.

RETURN VALUE

     Returns T if the given chord object contains at least one pitch object,
     otherwise returns NIL.

EXAMPLE

    ;; Returns T if the given chord object contains at least one pitch object
    (let ((chrd (make-chord '(c4))))
      (has-notes chrd))

    => T

    (let ((chrd (make-chord '(c4 e4 g4))))
      (has-notes chrd))

    => T

    ;; Otherwise returns NIL
    (let ((chrd (make-chord nil)))
      (has-notes chrd))

    => NIL

SYNOPSIS

    (defmethod has-notes ((c chord))

## chord/highest [ Methods ]

[ Top ] [ chord ] [ Methods ]

DESCRIPTION

     Return the pitch object from the given chord object that has the highest
     pitch data.

     NB: As opposed to the "lowest" method, this method cannot handle chord
         objects whose pitches have not been auto-sorted from low to high.

ARGUMENTS

     - A chord object.

RETURN VALUE

     A pitch object

EXAMPLE

    ;; Returns the last pitch object of a chord object
    (let ((chrd (make-chord '(e4 c4 gqs4 bqf4 d5 f5)
                            :midi-channel 11
                            :microtones-midi-channel 12)))
      (highest chrd))

    =>
    PITCH: frequency: 698.456, midi-note: 77, midi-channel: 11
           pitch-bend: 0.0
           degree: 154, data-consistent: T, white-note: F5
           nearest-chromatic: F5
           src: 2.669679641723633, src-ref-pitch: C4, score-note: F5
           qtr-sharp: NIL, qtr-flat: NIL, qtr-tone: NIL,
           micro-tone: NIL,
           sharp: NIL, flat: NIL, natural: T,
           octave: 5, c5ths: 0, no-8ve: F, no-8ve-no-acc: F
           show-accidental: T, white-degree: 38,
           accidental: N,
           accidental-in-parentheses: NIL, marks: NIL
    LINKED-NAMED-OBJECT: previous: NIL, this: NIL, next: NIL
    NAMED-OBJECT: id: F5, tag: NIL,
    data: F5

    ;; Is not capable of returning the highest pitch object from chord objects that
    ;; have not been auto-sorted
    (let ((chrd (make-chord '(e4 c4 gqs4 bqf4 f5 d5)
                            :midi-channel 11
                            :microtones-midi-channel 12
                            :auto-sort nil)))
      (data (highest chrd)))

    => D5

SYNOPSIS

    (defmethod highest ((c chord))

## chord/lowest [ Methods ]

[ Top ] [ chord ] [ Methods ]

DESCRIPTION

     Return the pitch object from the given chord object that has the lowest
     pitch data. The method can handle chord objects whose pitches have not been
     auto-sorted from low to high.

ARGUMENTS

     - A chord object.

RETURN VALUE

     A pitch object.

EXAMPLE

    ;; Returns the pitch object of the lowest pitch despite not being sorted
    (let ((chrd (make-chord '(e4 c4 gqs4 bqf4 d5 f5)
                            :midi-channel 11
                            :microtones-midi-channel 12
                            :auto-sort nil)))
      (lowest chrd))

    =>
    PITCH: frequency: 261.626, midi-note: 60, midi-channel: 11
           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

SYNOPSIS

    (defmethod lowest ((c chord))

## chord/make-chord [ Functions ]

[ Top ] [ chord ] [ Functions ]

DESCRIPTION

     Create a chord object from a list of note-name symbols.

ARGUMENTS

     - A list of note-name symbols.

OPTIONAL ARGUMENTS

     keyword arguments:
     - :id. An element of any type that is to be the ID of the chord object
       created.
     - :auto-sort. T or NIL to indicate whether the method should first sort the
       individual pitch objects created from low to high before returning the
       new chord object. T = sort. Default = T.
     - :midi-channel. An integer that is to be the MIDI channel value to which
       all of the chromatic pitch objects in the given chord object are to be
       set for playback. Default = 0.
     - :microtones-midi-channel. An integer that is to be the MIDI channel value
       to which all of the microtonal pitch objects in the given chord object
       are to be set for playback. Default = 0. NB: See
       player.lsp/make-player for details on microtones in MIDI output.
     - :force-midi-channel. T or NIL to indicate whether to force a given value
       to the MIDI-CHANNEL slot, even if the notes passed to the method are
       already pitch objects with non-zero MIDI-CHANNEL values.

RETURN VALUE

     A chord object.

EXAMPLE

    ;; Simple useage with default values for keyword arguments
    (make-chord '(c4 e4 g4 b4 d5 f5))

    =>
    CHORD: auto-sort: T, marks: NIL, micro-tone: NIL
    SCLIST: sclist-length: 6, bounds-alert: T, copy: T
    LINKED-NAMED-OBJECT: previous: NIL, this: NIL, next: NIL
    NAMED-OBJECT: id: NIL, tag: NIL,
    data: (
    PITCH: frequency: 261.626, midi-note: 60, midi-channel: 0
    [...]
    data: C4
    PITCH: frequency: 329.628, midi-note: 64, midi-channel: 0
    [...]
    data: E4
    [...]
    PITCH: frequency: 391.995, midi-note: 67, midi-channel: 0
    [...]
    data: G4
    [...]
    PITCH: frequency: 493.883, midi-note: 71, midi-channel: 0
    [...]
    data: B4
    [...]
    PITCH: frequency: 587.330, midi-note: 74, midi-channel: 0
    [...]
    data: D5
    [...]
    PITCH: frequency: 698.456, midi-note: 77, midi-channel: 0
    [...]
    data: F5
    )

    ;; By default the pitches are first sorted low to high
    (let ((mc (make-chord '(e4 c4 g4 b4 f5 d5))))
      (loop for p in (data mc) collect (data p)))

    => (C4 E4 G4 B4 D5 F5)

    ;; Setting the :midi-channel and :microtones-midi-channel arguments results in
    ;; the MIDI-CHANNEL slot of each of the contained pitch objects being set
    ;; accordingly, depending on whether it is a chromatic or microtonal pitch
    (let ((mc (make-chord '(cqs4 e4 gqf4 b4 dqf5 f5)
                          :midi-channel 11
                          :microtones-midi-channel 12)))
      (loop for p in (data mc) collect (midi-channel p)))

    => (12 11 12 11 12 11)

SYNOPSIS

    (defun make-chord (note-list &key (id nil) (auto-sort t) (midi-channel 0)
                       (microtones-midi-channel 0) (force-midi-channel nil))

## chord/no-accidental [ Methods ]

[ Top ] [ chord ] [ Methods ]

DESCRIPTION

     Set the SHOW-ACCIDENTAL slot of all pitch objects within a given chord
     object to NIL. This results in no accidentals for the given chord being printed
     when written to a score, and also excludes the writing of any accidentals
     for that chord in parentheses.

ARGUMENTS

     - A chord object.

RETURN VALUE

     Always returns NIL.

EXAMPLE

    ;;; Make a chord, print the SHOW-ACCIDENTAL slots of the pitch objects it
    ;;; contains; then call the method and print the same slots again to see the
    ;;; change.

    (let ((chrd (make-chord '(cs4 e4 fs4 af4 bf4))))
      (print (loop for p in (data chrd) collect (show-accidental p)))
      (no-accidental chrd)
      (print (loop for p in (data chrd) collect (show-accidental p))))

    =>
    (T T T T T)
    (NIL NIL NIL NIL NIL)

SYNOPSIS

    (defmethod no-accidental ((c chord))

## chord/output-midi-note [ Methods ]

[ Top ] [ chord ] [ Methods ]

DESCRIPTION

     Generate the MIDI-related data for each pitch in a given chord object.

ARGUMENTS

     - A chord object.
     - A number that is the start time in seconds of the given chord within the
       output MIDI file.
     - A decimal number between 0.0 and 1.0 that is the amplitude of the given
       chord in the output MIDI file.
     - A number that is the duration in seconds of the given chord in the output
       MIDI file.

RETURN VALUE

     The corresponding data in list form.

EXAMPLE

    ;; Generate the MIDI-related data required for a 5-note chord that starts 100
    ;; seconds into the output MIDI file, with an amplitude of 0.5 and a duration
    ;; of 13.0 seconds.
    (let ((chrd (make-chord '(cs4 e4 fs4 af4 bf4))))
      (output-midi-note chrd 100.0 0.5 13.0))

    => (#i(midi time 100.0 keynum 61 duration 13.0 amplitude 0.5 channel -1)
        #i(midi time 100.0 keynum 64 duration 13.0 amplitude 0.5 channel -1)
        #i(midi time 100.0 keynum 66 duration 13.0 amplitude 0.5 channel -1)
        #i(midi time 100.0 keynum 68 duration 13.0 amplitude 0.5 channel -1)
        #i(midi time 100.0 keynum 70 duration 13.0 amplitude 0.5 channel -1))

SYNOPSIS

    (defmethod output-midi-note ((c chord) time amplitude duration)

## chord/pitch- [ Methods ]

[ Top ] [ chord ] [ Methods ]

DESCRIPTION

     Determine the difference between the lowest pitch of two chords. This
     method can be used, for example, to compare the written and sounding
     versions of a chord to determine transposition.

     If the lower chord is passed as the first argument, the method will return
     a negative number.

     NB: This method takes pitch bend into consideration when calculating.

ARGUMENTS

     - A first chord object.
     - A second chord object.

RETURN VALUE

     A positive or negative decimal number.

EXAMPLE

    ;; The method measures the distance between the first (lowest) pitches of the
    ;;; chord only.
    (let ((chrd-1 (make-chord '(c4 e4 g4)))
          (chrd-2 (make-chord '(d4 e4 fs4 a4))))
      (pitch- chrd-2 chrd-1))

    => 2.0

    ;;; Passing the lower chord as the first argument produces a negative result
    (let ((chrd-1 (make-chord '(c4 e4 g4)))
          (chrd-2 (make-chord '(d4 e4 fs4 a4))))
      (pitch- chrd-1 chrd-2))

    => -2.0

SYNOPSIS

    (defmethod pitch- ((c1 chord) (c2 chord))

## chord/respell-chord [ Methods ]

[ Top ] [ chord ] [ Methods ]

DESCRIPTION

     Respell the pitches of a given chord object to improve interval structure;
     i.e., removing augmented intervals etc.

     This method respells pitches from the bottom of the chord upwards. It does
     not process the pitches downwards again once pitches has been
     changed. Instead, it reattempts the whole respelling with the enharmonic of
     the lowest pitch to determine which spelling produces the fewest
     accidentals.

     NB: Respelling pitches in a chord is a rather complex process and is by no
         means fool-proof. The process employed here is based on avoiding double
         accidentals; thus, since both FS4 and BS4 have single sharps, the BS4
         won't be changed to C5.

ARGUMENTS

     - A chord object.

OPTIONAL ARGUMENTS

     - T or NIL to indicate whether to print feedback from the process to the
       listener. T = print. Default = NIL.

RETURN VALUE

     A chord object.

EXAMPLE

    (let ((chrd (make-chord '(a3 ds4 f4 fs5 c6))))
      (pitch-list-to-symbols (data (respell-chord chrd t))))

    => (A3 EF4 F4 GF5 C6)

SYNOPSIS

    (defmethod respell-chord ((c chord) &optional verbose)

## chord/set-midi-channel [ Methods ]

[ Top ] [ chord ] [ Methods ]

DESCRIPTION

     Set the MIDI channel of the pitch objects in a given chord object to the
     specified values.

ARGUMENTS

     - A chord object.
     - An integer that is to be the MIDI channel for chromatic pitches in the
       given chord object.
     - An integer that is to be the MIDI channel for microtonal pitches in the
       given chord object. NB: See player.lsp/make-player for details on
       microtones in MIDI output.

RETURN VALUE

     Always returns NIL.

EXAMPLE

    ;; Returns NIL
    (let ((chrd (make-chord '(c4 e4 gqs4 bqf4 d5 f5)
                              :midi-channel 11
                              :microtones-midi-channel 12)))
      (set-midi-channel chrd 3 4))

    => NIL

    ;; Print the value of the MIDI slot for each of the pitch objects contained in
    ;; the chord object before and after setting
    (let ((chrd (make-chord '(c4 e4 gqs4 bqf4 d5 f5)
                              :midi-channel 11
                              :microtones-midi-channel 12)))
      (print (loop for p in (data chrd) collect (midi-channel p)))
      (set-midi-channel chrd 3 4)
      (print (loop for p in (data chrd) collect (midi-channel p))))

    =>
    (11 11 12 12 11 11)
    (3 3 4 4 3 3)

SYNOPSIS

    (defmethod set-midi-channel ((c chord) midi-channel microtones-midi-channel)

## chord/sort-pitches [ Methods ]

[ Top ] [ chord ] [ Methods ]

DESCRIPTION

     Sort the pitch objects contained within a given chord object and return
     them as a list of pitch objects.

     As an optional argument, 'ascending or 'descending can be given to indicate
     whether to sort from low to high or high to low.

ARGUMENTS

     - A chord object.

OPTIONAL ARGUMENTS

     - The symbol 'ASCENDING or 'DESCENDING to indicate whether to sort the
       given pitch objects from low to high or high to low.
       Default = 'ASCENDING.

RETURN VALUE

     Returns a list of pitch obects.

EXAMPLE

    ;; Apply the method with no optional argument (defaults to 'ASCENDING) and
    ;; collect and print the data of the pitch objects in the resulting list
    (let ((chrd (make-chord '(d5 c4 gqs4 bqf5 f5 e4)
                            :midi-channel 11
                            :microtones-midi-channel 12)))
      (print (loop for p in (sort-pitches chrd) collect (data p))))

    => (C4 E4 GQS4 D5 F5 BQF5)

    ;; Sort from high to low
    (let ((chrd (make-chord '(d5 c4 gqs4 bqf5 f5 e4)
                            :midi-channel 11
                            :microtones-midi-channel 12)))
      (print (loop for p in (sort-pitches chrd 'descending) collect (data p))))

    => (BQF5 F5 D5 GQS4 E4 C4)

SYNOPSIS

    (defmethod sort-pitches ((c chord) &optional (order 'ascending))

## chord/transpose [ Methods ]

[ Top ] [ chord ] [ Methods ]

DESCRIPTION

     Transpose the pitches of a given chord object by a specified number of
     semitones. The specified number can be positive or negative, and may
     contain a decimal segment for microtonal transposition. If passed a decimal
     number, the resulting note-names will be scaled to the nearest degree of
     the current tuning.

ARGUMENTS

     - A chord object.
     - A positive or negative integer or decimal number indicating the number of
       semitones by which the pitches of the given chord object are to be
       transposed.

RETURN VALUE

     Returns a chord object.

EXAMPLE

    ;; Returns a chord obejct
    (let ((chrd (make-chord '(c4 e4 g4))))
      (transpose chrd 3))

    =>
    CHORD: auto-sort: T, marks: NIL, micro-tone: NIL
    SCLIST: sclist-length: 3, bounds-alert: T, copy: T
    LINKED-NAMED-OBJECT: previous: NIL, this: NIL, next: NIL
    NAMED-OBJECT: id: NIL, tag: NIL,
    data: (
    [...]
    )

    ;; Accepts positive and negative integers and decimal numbers
    (let ((chrd (make-chord '(c4 e4 g4))))
      (pitch-list-to-symbols (data (transpose chrd 3))))

    => (EF4 G4 BF4)

    (let ((chrd (make-chord '(c4 e4 g4))))
      (pitch-list-to-symbols (data (transpose chrd -3))))

    => (A3 CS4 E4)

    (let ((chrd (make-chord '(c4 e4 g4))))
      (pitch-list-to-symbols (data (transpose chrd -3.17))))

    => (AQF3 CQS4 EQF4)

SYNOPSIS

    (defmethod transpose ((c chord) semitones &key ignore1 ignore2 ignore3)

## sclist/chord [ Classes ]

[ Top ] [ sclist ] [ Classes ]

NAME

     chord

     File:             chord.lsp

     Class Hierarchy:  named-object -> linked-named-object -> sclist -> chord

     Version:          1.0.0-beta3

     Project:          slippery chicken (algorithmic composition)

     Purpose:          Implementation of the chord class that is simply an
                       sclist whose data is a list of pitch instances.

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

     Creation date:    July 28th 2001

     $$ Last modified: 12:45:00 Tue Jun 19 2012 BST

     SVN ID: $Id: chord.lsp 2531 2012-07-03 19:50:40Z medward2 $