./../../src/sc-set.lsp

## sc-set/add [ Methods ]

[ Top ] [ sc-set ] [ Methods ]

DESCRIPTION

     Create a new sc-set object from the data of two other specified sc-set
     objects.

     NB: Any subsets contained in the original sc-set objects are lost in the
         process.

ARGUMENTS

     - A first sc-set object.
     - A second sc-set object.

OPTIONAL ARGUMENTS

     (- optional argument <ignore> is internal only)

RETURN VALUE

EXAMPLE

    (let ((mscs1 (make-sc-set '(d2 a2 e3 b3 gf4 df5 af5)))
          (mscs2 (make-sc-set '(f2 c3 g3 d4 bf4 f5 c6))))
      (add mscs1 mscs2))

    =>
    SC-SET: auto-sort: T, used-notes:
    RECURSIVE-ASSOC-LIST: recurse-simple-data: T
                          num-data: 0
                          linked: NIL
                          full-ref: NIL
    ASSOC-LIST: warn-not-found T
    CIRCULAR-SCLIST: current 0
    SCLIST: sclist-length: 0, bounds-alert: T, copy: T
    LINKED-NAMED-OBJECT: previous: NIL, this: NIL, next: NIL
    NAMED-OBJECT: id: USED-NOTES, tag: NIL,
    data: NIL

    **** N.B. All pitches printed as symbols only, internally they are all
    pitch-objects.

        subsets:
        related-sets:
    SCLIST: sclist-length: 14, bounds-alert: T, copy: T
    LINKED-NAMED-OBJECT: previous: NIL, this: NIL, next: NIL
    NAMED-OBJECT: id: NIL, tag: NIL,
    data: (D2 F2 A2 C3 E3 G3 B3 D4 GF4 BF4 DF5 F5 AF5 C6)

SYNOPSIS

    (defmethod add ((s1 sc-set) (s2 sc-set) &optional ignore)

## sc-set/contains-pitches [ Methods ]

[ Top ] [ sc-set ] [ Methods ]

DESCRIPTION

     Check to see if a given sc-set object contains pitch objects for all of the
     specified note-names. The method returns NIL if any one of the specified
     pitches is not found in the given sc-set object.

ARGUMENTS

     - An sc-set object.
     - A list of note-name symbosl. NB: If checking for only one pitch, that
       pitch must be passed as a single-item list.

RETURN VALUE

     T or NIL.

EXAMPLE

    ;; Returns T when all specified pitches are contained in the given sc-set
    ;; object
    (let ((mscs (make-sc-set '(d2 f2 a2 c3 e3 g3 b3 d4 gf4 bf4 df5 f5 af5 c6))))
      (contains-pitches mscs '(d2 e3 gf4 af5)))

    => T

    ;; Returns NIL if any one of the specififed pitches is not contained in the
    ;; given sc-set object.
    (let ((mscs (make-sc-set '(d2 f2 a2 c3 e3 g3 b3 d4 gf4 bf4 df5 f5 af5 c6))))
      (contains-pitches mscs '(d2 e3 gf4 b4 af5)))

    => NIL

SYNOPSIS

    (defmethod contains-pitches ((s sc-set) pitches)

## sc-set/create-chord [ Methods ]

[ Top ] [ sc-set ] [ Methods ]

DESCRIPTION

     Create a chord object from the pitches of the given sc-set object.

ARGUMENTS

     - An sc-set object.

RETURN VALUE

     A chord object.

EXAMPLE

    (let ((mscs (make-sc-set '(d2 c3 d4 df5 c6))))
      (create-chord mscs))

    =>
    CHORD: auto-sort: T, marks: NIL, micro-tone: NIL
    SCLIST: sclist-length: 5, bounds-alert: T, copy: T
    LINKED-NAMED-OBJECT: previous: NIL, this: NIL, next: NIL
    NAMED-OBJECT: id: NIL, tag: NIL,
    data: (
    PITCH: frequency: 73.416, midi-note: 38, midi-channel: 0
    [...]
    )

SYNOPSIS

    (defmethod create-chord ((s sc-set))

## sc-set/create-event [ Methods ]

[ Top ] [ sc-set ] [ Methods ]

DESCRIPTION

     Create an event object (that is a chord) from a given sc-set object,
     specifiying a rhythmic value and a start-time (in seconds).

ARGUMENTS

     - An sc-set object.
     - A rhythmic unit, either as a numerical value (32, 16 etc) or a symbol
       that is an alphabetic shorthand ('e, 's etc).
     - A number that is the start time in seconds.

OPTIONAL ARGUMENTS

     - A number that is the start-time in quarter-notes rather than seconds (see
       event class documentation for more details)

RETURN VALUE

     An event object.

EXAMPLE

    ;; Create an event from the specified sc-set object that is a quarter-note
    ;; chord starting at 0.0 seconds
    (let ((mscs (make-sc-set '(d2 c3 d4 df5 c6))))
      (create-event mscs 'q 0.0))

    =>
    EVENT: start-time: 0.000, end-time: NIL,
           duration-in-tempo: 0.000,
           compound-duration-in-tempo: 0.000,
           amplitude: 0.700
           bar-num: -1, marks-before: NIL,
           tempo-change: NIL
           instrument-change: NIL
           display-tempo: NIL, start-time-qtrs: 0.000,
           midi-time-sig: NIL, midi-program-changes: NIL,
           8va: 0
           pitch-or-chord:
    CHORD: auto-sort: T, marks: NIL, micro-tone: NIL
    SCLIST: sclist-length: 5, bounds-alert: T, copy: T
    LINKED-NAMED-OBJECT: previous: NIL, this: NIL, next: NIL
    NAMED-OBJECT: id: NIL, tag: NIL,
    data: (
    PITCH: frequency: 73.416, midi-note: 38, midi-channel: 0
    [...]
    RHYTHM: value: 4.000, duration: 1.000, rq: 1, is-rest: NIL,
            score-rthm: 4.0f0, undotted-value: 4, num-flags: 0, num-dots: 0,
            is-tied-to: NIL, is-tied-from: NIL, compound-duration: 1.000,
            is-grace-note: NIL, needs-new-note: T, beam: NIL, bracket: NIL,
            rqq-note: NIL, rqq-info: NIL, marks: NIL, marks-in-part: NIL,
            letter-value: 4, tuplet-scaler: 1, grace-note-duration: 0.05
    LINKED-NAMED-OBJECT: previous: NIL, this: NIL, next: NIL
    NAMED-OBJECT: id: Q, tag: NIL,
    data: Q

SYNOPSIS

    (defmethod create-event ((s sc-set) rhythm start-time &optional start-time-qtrs)

## sc-set/force-micro-tone [ Methods ]

[ Top ] [ sc-set ] [ Methods ]

DESCRIPTION

     Change the value of the MICRO-TONE slot of all pitch objects in a given
     sc-set object to the specified <value>.

     NB: Although the MICRO-TONE slot is generally used as a boolean, this
         method allows the user to force-set it to any value.

ARGUMENTS

     - An sc-set object.

OPTIONAL ARGUMENTS

     - An item of any type that is to be the new value of the MICRO-TONE slot of
       all pitch objects in the given sc-set object (generally T or
       NIL). Default = NIL.

RETURN VALUE

     Always returns NIL.

EXAMPLE

    ;; Create an sc-set object that contains micro-tones and print the MICRO-TONE
    ;; slot of all of the contained pitch objects to see their values:
    (let ((mscs (make-sc-set '(d2 cqs3 fs3 cs4 e4 c5 aqf5 ef6))))
      (loop for p in (data mscs) do (print (micro-tone p))))

    =>
    NIL
    T
    NIL
    NIL
    NIL
    NIL
    T
    NIL

    ;; Now apply the force-micro-tone method to the same set using the default
    ;; value of NIL and print the results

    (let ((mscs (make-sc-set '(d2 cqs3 fs3 cs4 e4 c5 aqf5 ef6))))
      (force-micro-tone mscs)
        (loop for p in (data mscs) do (print (micro-tone p))))

    =>
    NIL
    NIL
    NIL
    NIL
    NIL
    NIL
    NIL
    NIL

    ;; Using the same sc-set, force all the values to T
    (let ((mscs (make-sc-set '(d2 cqs3 fs3 cs4 e4 c5 aqf5 ef6))))
      (force-micro-tone mscs 't)
        (loop for p in (data mscs) do (print (micro-tone p))))

    =>
    T
    T
    T
    T
    T
    T
    T
    T

SYNOPSIS

    (defmethod force-micro-tone ((s sc-set) &optional value)

## sc-set/get-chromatic [ Methods ]

[ Top ] [ sc-set ] [ Methods ]

DESCRIPTION

     Return those notes of a given sc-set object that are normal chromatic notes
     (i.e. no microtones).

     If a number is given for the <octave> argument, the method will transpose
     all returned pitches into the specified octave, in which case any duplicate
     pitches are removed.

ARGUMENTS

     - An sc-set object.

OPTIONAL ARGUMENTS

     keyword arguments:
     - :octave. NIL or an integer that is the octave designator to which all
       resulting pitches are to be transposed (i.e. the "4" in "C4" etc.)
       Default = NIL.
     - :remove-duplicates. T or NIL to indicate whether any duplicate pitches
       within an octave that are created by use of the :octave keyword argument
       are to be removed. T = remove duplicates. Default = NIL.
     - :as-symbols. T or NIL to indicate whether to return the results of the
       method as a list of note-name symbols rather than a list of pitch
       objects. T = return as note-name symbols. Default = NIL.
     - :package. The package in which the pitches are to be handled.
       Default = :sc.
     - :invert. Get the micro-tone pitches instead.

RETURN VALUE

     Returns a list of pitch objects by default.

     When the :as-symbols argument is set to T, a list of note-name symbols is
     returned instead.

EXAMPLE

    ;;; Returns a list of pitch objects by default
    (let ((mscs (make-sc-set '(d2 cqs3 fs3 gqf3 cs4 e4 fqs4 c5 af5 bqf5 d6))))
      (get-chromatic mscs))

    =>
    (
    PITCH: frequency: 73.416, midi-note: 38, midi-channel: 0
           pitch-bend: 0.0
           degree: 76, data-consistent: T, white-note: D2
           nearest-chromatic: D2
           src: 0.28061550855636597, src-ref-pitch: C4, score-note: D2
           qtr-sharp: NIL, qtr-flat: NIL, qtr-tone: NIL,
           micro-tone: NIL,
           sharp: NIL, flat: NIL, natural: T,
           octave: 2, c5ths: 0, no-8ve: D, no-8ve-no-acc: D
           show-accidental: T, white-degree: 15,
           accidental: N,
           accidental-in-parentheses: NIL, marks: NIL
    LINKED-NAMED-OBJECT: previous: NIL, this: NIL, next: NIL
    NAMED-OBJECT: id: D2, tag: NIL,
    data: D2

    PITCH: frequency: 184.997, midi-note: 54, midi-channel: 0
    [...]
    )

    ;; Setting the :as-symbols argument to T returns a list of note-name symbols
    ;; instead
    (let ((mscs (make-sc-set '(d2 cqs3 fs3 gqf3 cs4 e4 fqs4 c5 af5 bqf5 d6))))
      (get-chromatic mscs
                     :as-symbols t))

    => (D2 FS3 CS4 E4 C5 AF5 D6)

    ;; Giving an integer as the :octave argument transposes all returned  pitches
    ;; to the specified octave, removing any duplicates by default.
    (let ((mscs (make-sc-set '(d2 cqs3 fs3 gqf3 cs4 e4 fqs4 c5 af5 bqf5 d6))))
      (get-chromatic mscs
                     :as-symbols t
                     :octave 4))

    => (FS4 CS4 E4 C4 AF4 D4)

    ;; Setting the :invert argument to T returns the non-chromatic elements of the
    ;; given sc-set object instead
    (let ((mscs (make-sc-set '(d2 cqs3 fs3 gqf3 cs4 e4 fqs4 c5 af5 bqf5 d6))))
      (get-chromatic mscs
                     :as-symbols t
                     :invert t))

    => (CQS3 GQF3 FQS4 BQF5)

SYNOPSIS

    (defmethod get-chromatic ((s sc-set)
                              &key
                              (octave nil)
                              (remove-duplicates t) ;; only if octave!
                              (as-symbols nil)
                              (package :sc)
                              (invert nil))

## sc-set/get-degrees [ Methods ]

[ Top ] [ sc-set ] [ Methods ]

DESCRIPTION

     Return the pitches contained in the given sc-set object as a list of
     DEGREES (which default to quarter-tones in slippery chicken).

ARGUMENTS

     - An sc-set object.

RETURN VALUE

     A list of integers.

EXAMPLE

    (let ((mscs (make-sc-set '(d2 f2 a2 c3 e3 g3 b3 d4 gf4 bf4 df5 f5 af5 c6))))
      (get-degrees mscs))

    => (76 82 90 96 104 110 118 124 132 140 146 154 160 168)

SYNOPSIS

    (defmethod get-degrees ((s sc-set))

## sc-set/get-freqs [ Methods ]

[ Top ] [ sc-set ] [ Methods ]

DESCRIPTION

     Return the pitches of a given sc-set object as a list of Hz frequencies

ARGUMENTS

     - An sc-set object.

RETURN VALUE

     A list of numbers

EXAMPLE

    (let ((mscs (make-sc-set '(d2 f2 a2 c3 e3 g3 b3 d4 gf4 bf4 df5 f5 af5 c6))))
      (get-freqs mscs))

    => (73.41618871368837 87.30705289160142 109.99999810639679 130.8127784729004
        164.81377633519514 195.99771591817216 246.94163930037348 293.6647548547535
        369.99440456398133 466.1637395092839 554.3652698843016 698.4564231328113
        830.6093584209975 1046.5022277832031)

SYNOPSIS

    (defmethod get-freqs ((s sc-set))

## sc-set/get-interval-structure [ Methods ]

[ Top ] [ sc-set ] [ Methods ]

DESCRIPTION

     Get the distances between each pitch in a given sc-set object and the
     lowest pitch in that object in DEGREES (which default to quarter-tones in
     slippery chicken). This method assumes that the given sc-set object is
     sorted from low to high, which is the default action for sc-set objects.

ARGUMENTS

     - An sc-set object.

     OPTIONAL
     - T or NIL indicating whether to return values in semitones or default of
       degrees. T = semitones. Default = NIL.

RETURN VALUE

     A list of integers.

EXAMPLE

    ;;; Returns the distances in degrees (which are quarter-tones by default
    ;;; in slippery chicken--use (in-scale :chromatic) at the top of your code to
    ;;; set to the chromatic scale):

    (let ((mscs (make-sc-set '(c4 e4 g4))))
      (get-interval-structure mscs))

    => (8 14)

    ;;; Return semitones
    (let ((mscs (make-sc-set '(c4 e4 g4))))
      (get-interval-structure mscs t))

    => (4 7)

SYNOPSIS

    (defmethod get-interval-structure ((s sc-set) &optional in-semitones)

## sc-set/get-midi [ Methods ]

[ Top ] [ sc-set ] [ Methods ]

DESCRIPTION

     Return the pitches of a given sc-set object as a list of their equivalent
     MIDI note numbers.

ARGUMENTS

     - An sc-set object.

RETURN VALUE

     A list of numbers

EXAMPLE

    (let ((mscs (make-sc-set '(d2 f2 a2 c3 e3 g3 b3 d4 gf4 bf4 df5 f5 af5 c6))))
      (get-midi mscs))

    => (38 41 45 48 52 55 59 62 66 70 73 77 80 84)

SYNOPSIS

    (defmethod get-midi  ((s sc-set))

## sc-set/get-non-chromatic [ Methods ]

[ Top ] [ sc-set ] [ Methods ]

DESCRIPTION

     Return those notes of a given sc-set object that are micr-tones (i.e. no
     "normal" chromatic notes).

     If a number is given for the <octave> argument, the method will transpose
     all returned pitches into the specified octave, in which case any duplicate
     pitches are removed.

ARGUMENTS

     - An sc-set object.

OPTIONAL ARGUMENTS

     keyword arguments:
     - :octave. NIL or an integer that is the octave designator to which all
       resulting pitches are to be transposed (i.e. the "4" in "C4" etc.)
       Default = NIL.
      :as-symbols. T or NIL to indicate whether to return the results of the
       method as a list of note-name symbols rather than a list of pitch
       objects. T = return as note-name symbols. Default = NIL.
     - :package. The package in which the pitches are to be handled.
       Default = :sc.

RETURN VALUE

     Returns a list of pitch objects by default.

     When the :as-symbols argument is set to T, a list of note-name symbols is
     returned instead.

EXAMPLE

    ;; Returns a list of pitch objects by default
    (let ((mscs (make-sc-set '(d2 cqs3 fs3 gqf3 cs4 e4 fqs4 c5 af5 bqf5 d6))))
      (get-non-chromatic mscs))

    =>
    => (
    PITCH: frequency: 134.646, midi-note: 48, midi-channel: 0
           pitch-bend: 0.5
           degree: 97, data-consistent: T, white-note: C3
           nearest-chromatic: C3
           src: 0.5146511197090149, src-ref-pitch: C4, score-note: CS3
           qtr-sharp: 1, qtr-flat: NIL, qtr-tone: 1,
           micro-tone: T,
           sharp: NIL, flat: NIL, natural: NIL,
           octave: 3, c5ths: 0, no-8ve: CQS, no-8ve-no-acc: C
           show-accidental: T, white-degree: 21,
           accidental: QS,
           accidental-in-parentheses: NIL, marks: NIL
    LINKED-NAMED-OBJECT: previous: NIL, this: NIL, next: NIL
    NAMED-OBJECT: id: CQS3, tag: NIL,
    data: CQS3

    PITCH: frequency: 190.418, midi-note: 54, midi-channel: 0
    [...]
    )

    ;; Setting :as-symbols to T returns a list of note-names instead
    (let ((mscs (make-sc-set '(d2 cqs3 fs3 gqf3 cs4 e4 fqs4 c5 af5 bqf5 d6))))
      (get-non-chromatic mscs
                         :as-symbols t))

    => (CQS3 GQF3 FQS4 BQF5)

    ;; Giving an integer as the :octave argument transposes all returned  pitches
    ;; to the specified octave, removing any duplicates
    (let ((mscs (make-sc-set '(d2 cqs3 fs3 gqf3 cs4 e4 fqs4 c5 af5 bqf5 cqs6 d6))))
      (get-non-chromatic mscs
                         :as-symbols t
                         :octave 4))

    => (GQF4 FQS4 BQF4 CQS4)

SYNOPSIS

    (defmethod get-non-chromatic ((s sc-set)
                                  &key
                                  (octave nil)
                                  (as-symbols nil)
                                  (package :sc))

## sc-set/get-semitones [ Methods ]

[ Top ] [ sc-set ] [ Methods ]

DESCRIPTION

     Get the distances in semitones of each pitch in a given sc-set
     object to a static reference pitch.

     Though this method can be used in other contexts, it was devised
     as an aid for transposing audio samples (sound files), and the
     reference pitch is therefore generally the percieved fundamental
     pitch of the audio sample to be transposed.

ARGUMENTS

     - An sc-set object.

OPTIONAL ARGUMENTS

     - An optional note-name symbol sets the value of the <reference-pitch>,
       which is the basis pitch to which the resulting number of semitones
       refer. This will generally be the perceived fundamental pitch of the
       sample (sound file) being modififed ("transposed").
     - The optional <offset> argument takes a number that is the number of
       semitones to add to the pitch of the given set prior to determining its
       distance in semitones from the reference pitch.

RETURN VALUE

     A list of positive and negative numbers.

EXAMPLE

    ;; Chromatic example
    (let ((mscs (make-sc-set '(d2 fs3 cs4 c5 af5 d6))))
      (get-semitones mscs))

    => (-22.0 -6.0 1.0 12.0 20.0 26.0)

    ;; Quarter-tone example; results can be decimal fractions of semitone
    (let ((mscs (make-sc-set '(d2 cqs3 fs3 gqf3 cs4 fqs4 c5 af5 bqf5 cqs6 d6))))
      (get-semitones mscs))

    => (-22.0 -11.5 -6.0 -5.5 1.0 5.5 12.0 20.0 22.5 24.5 26.0)

SYNOPSIS

    (defmethod get-semitones ((s sc-set) &optional
                              (reference-pitch 'c4)
                              (offset 0))

## sc-set/get-semitones-from-middle-note [ Methods ]

[ Top ] [ sc-set ] [ Methods ]

DESCRIPTION

     Return a list of numbers that are the distances in semitones of each pitch
     in a given sc-set object from the middle note of that object.

     NB: If the given sc-object contains an even number of pitch objects, the
         middle note is determined to be the first note of the second half of
         the set.

ARGUMENTS

     - An sc-set object.

OPTIONAL ARGUMENTS

     - A symbol that is the key of one of the key/data pairs contained in the
       SUBSETS slot of the given sc-set object.

RETURN VALUE

     A list of positive and negative numbers.

EXAMPLE

    ;; With an odd number of items in the sc-set object, the method returns the
    ;; same number of positive and negative numbers (non-zero)
    (let ((mscs (make-sc-set '(d2 f2 a2 c3 e3 g3 b3 d4 gf4 bf4 df5 f5 af5))))
      (get-semitones-from-middle-note mscs))

    => (-21.0 -18.0 -14.0 -11.0 -7.0 -4.0 0.0 3.0 7.0 11.0 14.0 18.0 21.0)

    ;; With an even number of items in the sc-set object, the middle note is
    ;; considered to be the first note of the second half of the set
    (let ((mscs (make-sc-set '(d2 f2 a2 c3 e3 g3 b3 d4 gf4 bf4 df5 f5 af5 c6))))
      (get-semitones-from-middle-note mscs))

    => (-24.0 -21.0 -17.0 -14.0 -10.0 -7.0 -3.0 0.0 4.0 8.0 11.0 15.0 18.0 22.0)

    ;; Setting the optional <subset> argument to a symbol that is the key of a
    ;; given key/data pair in the sc-object's SUBSETS slot applies the method to
    ;; that subset only
    (let ((mscs (make-sc-set '(d2 f2 a2 c3 e3 g3 b3 d4 gf4 bf4 df5 f5 af5 c6)
                             :subsets '((fl (df5 f5 af5 c6))
                                        (va (c3 e3 g3 b3 d4 gf4))))))
      (get-semitones-from-middle-note mscs 'fl))

    => (-7.0 -3.0 0.0 4.0)

SYNOPSIS

    (defmethod get-semitones-from-middle-note ((s sc-set) &optional subset)

## sc-set/get-srts [ Methods ]

[ Top ] [ sc-set ] [ Methods ]

DESCRIPTION

     Get the sampling-rate conversion factors for the given sc-set object,
     whereby 1.0 = unison, 2.0 = one octave higher and 0.5 = one octave lower
     etc.

ARGUMENTS

     - An sc-set object.

OPTIONAL ARGUMENTS

     - An optional note-name symbol sets the value of the <reference-pitch>,
       which is the basis pitch to which the resulting factors refer. This will
       generally be the perceived fundamental pitch of the sample (sound file)
       being modififed ("transposed").
     - The optional <offset> argument takes a number that is the number of
       semitones to add to the pitch of the given set prior to determining the
       sampling-rate conversion factors.

RETURN VALUE

     Returns a list of numbers.

EXAMPLE

    ;; Returns a list of factors that are the sampling-rate conversion factor
    ;; compared to a 'C4 by default:
    (let ((mscs (make-sc-set '(d2 fs3 cs4 c5 af5 d6))))
      (get-srts mscs))

    => (0.28061550855636597 0.7071067690849304 1.0594631433486938 2.0
        3.17480206489563 4.4898481369018555)

    ;; Comparing the same set against a higher reference-pitch will return lower
    ;; values
    (let ((mscs (make-sc-set '(d2 fs3 cs4 c5 af5 d6))))
      (get-srts mscs 'd4))

    => (0.25 0.6299605220704482 0.9438743681693953 1.781797458637491
        2.8284271254540463 4.0)

    ;; Conversely, comparing the same set against the default reference-pitch but
    ;; with a postive offset will return higher values

    (let ((mscs (make-sc-set '(d2 fs3 cs4 c5 af5 d6))))
      (get-srts mscs 'c4 2))

    => (0.3149802585215549 0.7937005124004939 1.1892071699914617 2.244924096618746
        3.563594828739576 5.039684136344879)

SYNOPSIS

    (defmethod get-srts ((s sc-set) &optional
                                    (reference-pitch 'c4)
                                    (offset 0))

## sc-set/make-sc-set [ Functions ]

[ Top ] [ sc-set ] [ Functions ]

DESCRIPTION

     Create an sc-set object, which holds pitch-set information for harmonic and
     pitch manipulation.

ARGUMENTS

     - A list of note-name symbols that is to be the set (pitch-set) for the
       given sc-set object.

OPTIONAL ARGUMENTS

     keyword arguments:
     - :id. A symbol that is to be the ID of the given sc-set object.
     - :subsets. An assoc-list of key/data pairs, in which the data is a list of
       note-name symbols that are a subset of the main set. One use for this
       keyword argument might be to create subsets that particular instruments
       can play; these would then be selected in the chord-function passed to
       the instrument object.
     - :related-sets. An assoc-list of key/data pairs, similar to :subsets, only
       that the pitches given here do not have to be part of the main set. This
       can be used, for example, for pitches missing from the main set.
     - :auto-sort. T or NIL to indicate whether the specified pitches (note-name
       symbols) are to be automatically sorted from lowest to highest.
       T = sort. Default = T.

RETURN VALUE

     An sc-set object.

EXAMPLE

    ;; Simplest usage, with no keyword arguments; returns an sc-set object
    (make-sc-set '(d2 cs3 fs3 cs4 e4 c5 af5 ef6))

    =>
    SC-SET: auto-sort: T, used-notes:
    RECURSIVE-ASSOC-LIST: recurse-simple-data: T
                          num-data: 0
                          linked: NIL
                          full-ref: NIL
    ASSOC-LIST: warn-not-found T
    CIRCULAR-SCLIST: current 0
    SCLIST: sclist-length: 0, bounds-alert: T, copy: T
    LINKED-NAMED-OBJECT: previous: NIL, this: NIL, next: NIL
    NAMED-OBJECT: id: USED-NOTES, tag: NIL,
    data: NIL

    N.B. All pitches printed as symbols only, internally they are all
    pitch-objects.

        subsets:
        related-sets:
    SCLIST: sclist-length: 8, bounds-alert: T, copy: T
    LINKED-NAMED-OBJECT: previous: NIL, this: NIL, next: NIL
    NAMED-OBJECT: id: NIL, tag: NIL,
    data: (D2 CS3 FS3 CS4 E4 C5 AF5 EF6)

    ;; With keyword arguments
    (make-sc-set '(d2 cs3 fs3 cs4 e4 c5 af5 ef6)
                 :id 'scs1
                 :subsets '((violin (e4 c5 af5 ef6))
                            (viola (cs4 e4)))
                 :related-sets '((missing (ds2 e2 b3 cs6 d6))))

    =>
    SC-SET: auto-sort: T, used-notes:
    RECURSIVE-ASSOC-LIST: recurse-simple-data: T
                          num-data: 0
                          linked: NIL
                          full-ref: NIL
    ASSOC-LIST: warn-not-found T
    CIRCULAR-SCLIST: current 0
    SCLIST: sclist-length: 0, bounds-alert: T, copy: T
    LINKED-NAMED-OBJECT: previous: NIL, this: NIL, next: NIL
    NAMED-OBJECT: id: USED-NOTES, tag: NIL,
    data: NIL

    N.B. All pitches printed as symbols only, internally they are all
    pitch-objects.

        subsets:
    VIOLIN: (E4 C5 AF5 EF6)
    VIOLA: (CS4 E4)
        related-sets:
    MISSING: (DS2 E2 B3 CS6 D6)
    SCLIST: sclist-length: 8, bounds-alert: T, copy: T
    LINKED-NAMED-OBJECT: previous: NIL, this: NIL, next: NIL
    NAMED-OBJECT: id: SCS1, tag: NIL,
    data: (D2 CS3 FS3 CS4 E4 C5 AF5 EF6)

SYNOPSIS

    (defun make-sc-set (sc-set &key id subsets related-sets (auto-sort t))

## sc-set/pitch-symbols [ Methods ]

[ Top ] [ sc-set ] [ Methods ]

DESCRIPTION

     Return the pitches of a given sc-set object as a list of note-name
     symbols.

ARGUMENTS

     - An sc-set object.

RETURN VALUE

     A list of note-name symbols.

EXAMPLE

    (let ((mscs (make-sc-set '(d2 c3 d4 df5 c6))))
      (pitch-symbols mscs))

    => (D2 C3 D4 DF5 C6)

SYNOPSIS

    (defmethod pitch-symbols ((s sc-set))

## sc-set/round-inflections [ Methods ]

[ Top ] [ sc-set ] [ Methods ]

DESCRIPTION

     Get the microtones of a given sc-set object, rounded to the nearest
     chromatic note.

     This method returns only the rounded microtones, and not any of the pitches
     of the original sc-set that are already chromatic.

     By default, this method only gets those microtones that are less than a
     quarter-tone. This behavior can be changed by setting the :qtr-tones-also
     argument to T.

     An optional argument allows for all pitches to be moved to a specified
     octave, in which case any duplicate pitches are removed.

ARGUMENTS

     - An sc-set object.

OPTIONAL ARGUMENTS

     keyword arguments:
     - :qtr-tones-also. T or NIL to indicate whether quarter-tones are also to
       be rounded to the nearest chromatic pitch and returned. T = round and
       return. Default = NIL.
     - :octave. NIL or an integer that is the octave designator to which all
       resulting pitches are to be transposed (i.e. the "4" in "C4" etc.)
       Default = NIL.
     - :remove-duplicates. T or NIL to indicate whether any duplicate pitches
       within an octave that are created by use of the :octave keyword argument
       are to be removed. T = remove duplicates. Default = NIL.
     - :as-symbols. T or NIL to indicate whether to return the results of the
       method as a list of note-name symbols rather than a list of pitch
       objects. T = return as note-name symbols. Default = NIL.
     - :package. The package in which the pitches are to be handled.
       Default = :sc.

RETURN VALUE

     A list of pitch objects.

EXAMPLE

    ;; First set the *scale* environment of CM (which is used by slippery chicken)
    ;; to twelfth-tones
    (setf cm::*scale* (cm::find-object 'twelfth-tone))

    => #<tuning "twelfth-tone">

    ;; By default the method returns a list of pitch objects.
    (let ((mscs (make-sc-set '(c4 cts4 css4 cqs4 cssf4 cstf4 cs4))))
      (round-inflections mscs))

    =>
    (
    PITCH: frequency: 261.626, midi-note: 60, midi-channel: 0
    [...]
    data: 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: 277.183, midi-note: 61, midi-channel: 0
    [...]
    data: CS4
    )

    ;; Setting the :as-symbols argument to T returns a list of note-name symbols
    ;; instead
    (let ((mscs (make-sc-set '(c4 cts4 css4 cqs4 cssf4 cstf4 cs4))))
      (round-inflections mscs :as-symbols t))

    => (C4 C4 CS4 CS4)

    ;; Setting the :qtr-tones-also argument to T returns causes quarter-tones to be
    ;; rounded and returned as well.
    (let ((mscs (make-sc-set '(c4 cts4 css4 cqs4 cssf4 cstf4 cs4))))
      (round-inflections mscs
                         :qtr-tones-also T
                         :as-symbols t))

    => (C4 C4 C4 CS4 CS4)

    ;; Specifying an octave transposes all returned pitches to that octave,
    ;; removing any duplicates by default
    (let ((mscs (make-sc-set '(c2 cts3 css4 cqs5 cssf6 cstf7 cs8))))
      (round-inflections mscs
                         :qtr-tones-also T
                         :octave 4
                         :as-symbols t))

    => (C4 CS4)

    ;; The removal of the duplicates can be turned off by setting the
    ;; :remove-duplicates argument to NIL
    (let ((mscs (make-sc-set '(c2 cts3 css4 cqs5 cssf6 cstf7 cs8))))
      (round-inflections mscs
                         :qtr-tones-also T
                         :octave 4
                         :remove-duplicates NIL
                         :as-symbols t))

    => (C4 C4 C4 CS4 CS4)

SYNOPSIS

    (defmethod round-inflections ((s sc-set)
                                  &key
                                  qtr-tones-also
                                  octave
                                  (remove-duplicates t) ;; only if octave!
                                  (as-symbols nil)
                                  (package :sc))

## sc-set/set-position [ Methods ]

[ Top ] [ sc-set ] [ Methods ]

DESCRIPTION

     Get the position (zero-index) of a specified pitch object within a given
     sc-set object.

ARGUMENTS

     - A pitch object.
     - An sc-set object.

RETURN VALUE

     An integer.

EXAMPLE

    (let ((mscs (make-sc-set '(d2 f2 a2 c3 e3 g3 b3 d4 gf4 bf4 df5 f5 af5 c6))))
      (set-position (make-pitch 'e3) mscs))

    => 4

SYNOPSIS

    (defmethod set-position ((p pitch) (s sc-set))

## sc-set/stack [ Methods ]

[ Top ] [ sc-set ] [ Methods ]

DESCRIPTION

     Extend the pitch content of a given sc-set object by adding new pitch
     objects which have the same interval structure as the original set.

     The method analyzes the interval structure of the original set from the
     bottom note to the top and adds new sets to the top and bottom of the
     orginal set symmetrically; i.e., with the identical interval structure
     above the original set and inverted interval structure below.

     The optional <num-stacks> argument indicates how many new sets are to be
     added to both ends.

     NB: The method assumes that the pitch content of the original sc-set object
         is sorted from low to high.

     See also: the make-stack method in the complete-set class to make a stack
               from a simple list of note-name symbols.

ARGUMENTS

     - An sc-set object.

OPTIONAL ARGUMENTS

     - An integer that is the number of new sets to be added to each end of the
       original set.
     - A symbol that will be the ID of the new sc-set object.

RETURN VALUE

     An sc-set object.

EXAMPLE

    ;; Extends the original set with new sets that have the identical interval
    ;; structure upwards and inverted interval structure downwards.
    (let ((set (make-sc-set '(c4 e4 g4))))
      (stack set 3))

    =>
    SC-SET: auto-sort: T, used-notes:
    [...]
    data: (EF2 GF2 BF2 DF3 F3 AF3 C4 E4 G4 B4 D5 GF5 A5 DF6 E6)

SYNOPSIS

    (defmethod stack ((s sc-set) &optional (num-stacks 1) id)

## sc-set/subset-get-srts [ Methods ]

[ Top ] [ sc-set ] [ Methods ]

DESCRIPTION

     Get the sampling-rate conversion factors for the specified subset of a
     given sc-set object, whereby 1.0 = unison, 2.0 = one octave higher and 0.5
     = one octave lower etc.

ARGUMENTS

     - An sc-set object.
     - A symbol that is the key of one of the key/data pairs stored in the
       SUBSETS slot of the given sc-set object.

OPTIONAL ARGUMENTS

     - The optional <reference-pitch> is the basis pitch to which the resulting
       factors refer. This will generally be the perceived fundamental pitch of
       the sample (sound file) being modififed ("transposed").
     - The optional <offset> argument is the number of semitones to add to the
       pitch of the given set prior to determining the sampling-rate conversion
       factors.

RETURN VALUE

EXAMPLE

    ;;; Create an sc-set object with two subsets named 'FL and 'VA, then get the
    ;;; sampling-rate conversion factors for the 'FL subset
    (let ((mscs (make-sc-set '(d2 f2 a2 c3 e3 g3 b3 d4 gf4 bf4 df5 f5 af5 c6)
                             :subsets '((fl (df5 f5 af5 c6))
                                        (va (c3 e3 g3 b3 d4 gf4))))))
      (subset-get-srts mscs 'fl))

    => (2.1189262866973877 2.669679641723633 3.17480206489563 4.0)

SYNOPSIS

    (defmethod subset-get-srts  ((s sc-set) subset &optional
                                 (reference-pitch 'c4)
                                 (offset 0))

## sclist/sc-set [ Classes ]

[ Top ] [ sclist ] [ Classes ]

NAME

     player

     File:             sc-set.lsp

     Class Hierarchy:  named-object -> linked-named-object -> sclist -> sc-set

     Version:          1.0.0-beta3

     Project:          slippery chicken (algorithmic composition)

     Purpose:          Implementation of the sc-set class which holds pitch set
                       information for harmonic and pitch manipulation.

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

     Creation date:    August 10th 2001

     $$ Last modified: 12:20:36 Mon Apr 23 2012 BST

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