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/add-harmonics [ Methods ]

[ Top ] [ sc-set ] [ Methods ]

DESCRIPTION

 Adds pitches to the set which are harmonically related to the existing
 pitches.  The keywords are the same as for the get-harmonics function.  NB
 This will automatically sort all pitches from high to low (irrespective of
 the auto-sort slot).

ARGUMENTS

 - an sc-set object

OPTIONAL ARGUMENTS

 keyword arguments:
  see get-harmonics function

RETURN VALUE

 the same set object as the first argument but with new pitches added.

EXAMPLE

;;; treat the existing pitches as fundamentals. Note that the existence of E6
;;; twice in the result is not a mistake: though E6 is the nearest pitch, the
;;; frequencies are different.
(let ((s (make-sc-set '(c4 e4) :id 'test)))
  (add-harmonics s :start-partial 3 :max-results 3))
=>
SC-SET: auto-sort: T, rm-dups: T, warn-dups: T used-notes: 
[...]
data: (C4 E4 G5 B5 C6 E6 E6 AF6)

;;; treat the existing pitches as partials and add the fundamentals and
;;; harmonics
(let ((s (make-sc-set '(c4 e4) :id 'test)))
  (add-harmonics s :start-freq-is-partial 3 :max-results 3))
SC-SET: auto-sort: T, rm-dups: T, warn-dups: T used-notes: 
[...]
data: (F2 A2 F3 A3 C4 E4)

SYNOPSIS

(defmethod add-harmonics ((s sc-set) &rest keywords)

sc-set/average-pitch [ Methods ]

[ Top ] [ sc-set ] [ Methods ]

DATE

 July 24th 2015, Glenferness

DESCRIPTION

 Calculate the average frequency of all the pitches in the chord and return
 this as a new pitch-object. 

ARGUMENTS

 - the sc-set object

RETURN VALUE

 a pitch-object

EXAMPLE

(average-pitch (make-complete-set '(c4 cs4  d4 e4 ef4 g4 b4)))
=>
PITCH: frequency: 337.015, midi-note: 64, midi-channel: 0 
       pitch-bend: 0.38 
       degree: 64, data-consistent: T, white-note: E4
       nearest-chromatic: E4
       src: 1.2881585030063512d0, src-ref-pitch: C4, score-note: E4 
       qtr-sharp: NIL, qtr-flat: NIL, qtr-tone: NIL,  
       micro-tone: T, 
       sharp: NIL, flat: NIL, natural: T, 
       octave: 4, c5ths: 0, no-8ve: E, no-8ve-no-acc: E
       show-accidental: T, white-degree: 37, 
       accidental: N, 
       accidental-in-parentheses: NIL, marks: NIL, 
       marks-before: NIL
LINKED-NAMED-OBJECT: previous: NIL, this: NIL, next: NIL
NAMED-OBJECT: id: E4, tag: NIL, 
data: E4

SYNOPSIS

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

sc-set/create-chord [ Methods ]

[ Top ] [ sc-set ] [ Methods ]

DESCRIPTION

 Create a chord object from the pitches of the given sc-set object. As of
 1.0.6 sc-set is a subset of chord instead of sc-list so this shouldn't be
 necessary, but it's still here for legacy code purposes.

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,
 specifying 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 If the pitches are microtonal and thus have associated pitch-bends and
 microtonal frequencies, these will not be changed, i.e. only the micro-tone
 slot is changed.

 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-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 microtones (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 perceived 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 modified ("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 modified ("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 positive 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/has-pitches-in-range [ Methods ]

[ Top ] [ sc-set ] [ Methods ]

DATE

 June 28th 2017, Edinburgh

DESCRIPTION

 Tests whether a set has pitches within a certain range.

ARGUMENTS

 - the sc-set object
 - the lower pitch of the range (pitch object or symbol)
 - the upper pitch of the range (pitch object or symbol)

OPTIONAL ARGUMENTS

 - T or NIL to indicate that only chromatic pitches count, i.e. not
   microtones  

RETURN VALUE

 T or NIL

SYNOPSIS

(defmethod has-pitches-in-range ((s sc-set) lower upper &optional chromatic)

sc-set/least-used-octave [ Methods ]

[ Top ] [ sc-set ] [ Methods ]

DATE

 18th August 2015, Edinburgh

DESCRIPTION

 Return the octave with the least notes in it. This includes octaves between
 the lowest and highest notes inclusive, and may include an octave within
 those ranges with no notes at all. 

ARGUMENTS

 - the sc-set object

OPTIONAL ARGUMENTS

 keyword arguments:
 - :highest-wins. If two octaves share the least number of notes, return the
    highest when T. Default = T.
 - :avoiding. An integer or list of integers. Don't return any octave in
    this list or don't return this single integer argument. Default = NIL.

RETURN VALUE

 An integer representing the octave with the least notes.

EXAMPLE

(least-used-octave (make-sc-set '(cs2 d4 e4 g5)))
--> 3
(least-used-octave (make-sc-set '(cs2 d3 ds4 e4 g5)) :highest-wins nil)
--> 2
(least-used-octave (make-sc-set '(cs2 d3 ds4 e4 g5)))
--> 5

SYNOPSIS

(defmethod least-used-octave ((s sc-set) &key (highest-wins t) avoiding)

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 could for instance be selected in the chord-function
   passed to the instrument object.  In any case, if the instrument has a
   subset-id slot, and the current set contains a subset with that ID, the
   pitches the instrument may play are limited to that subset.
 - :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) tag
                             (warn-dups t) (rm-dups t))

sc-set/most-used-octave [ Methods ]

[ Top ] [ sc-set ] [ Methods ]

DATE

 18th August 2015, Edinburgh

DESCRIPTION

 Return the octave with the least notes in it. See least-used-octave for
 more details and argument descriptions.

SYNOPSIS

(defmethod most-used-octave ((s sc-set) &key (highest-wins t) avoiding)

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

[ Top ] [ sc-set ] [ Methods ]

DATE

 January 30th 2017

DESCRIPTION

 Round the (potentially very microtonal) pitches in the set to the nearest
 pitch of the current or given scale. Note that this is a destructive
 operation.  

ARGUMENTS

 - the sc-set 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 sc-set object

SYNOPSIS

(defmethod round-to-nearest ((s sc-set) &key (scale cm::*scale*))

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
 original set symmetrically; i.e., with the identical interval structure
 above the original set and inverted interval structure below.

 The second argument indicates how times this procedure is carried out.

 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.
 - An integer that is the number of new sets to be added to each end of the
   original set.

OPTIONAL ARGUMENTS

 keyword arguments:
 - :id. A symbol that will be the ID of the new sc-set object. Default NIL.
 - :by-freq. If T then use frequencies when calculating the interval
    structure instead of degrees (semitones if default scale is chromatic).
    In this case the frequencies of pitches will be retained but their
    symbolic value will be rounded to the nearest note in the current scale
    (and pitch bends will be set accordingly). Default NIL. 
 - :up. Apply the process upwards in pitch space. Default = T.
 - :down. Apply the process downwards in pitch space. Default = T.

RETURN VALUE

 A new sc-set object. This will have the same tag and id (unless given as a
 keyword argument here) slots as the original sc-set but not subsets,
 related-sets, used-notes, etc.

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)

;;; or by calling the make-stack function, which returns a complete-set object
;;; (subclass of tl-set and sc-set).  Called with (in-scale :chromatic):
(make-stack 'test '(430 441 889 270) 1 :by-freq t)
=>
COMPLETE-SET: complete: NIL
[...]
data: (G2 A2 CS4 A4 A4 A5 C6 C6 FS6)

SYNOPSIS

(defmethod stack ((s sc-set) num-stacks &key id by-freq (up t) (down t))

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 modified ("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))

sc-set/subsets-remove [ Methods ]

[ Top ] [ sc-set ] [ Methods ]

DATE

 June 2nd 2017, Edinburgh

DESCRIPTION

 Remove pitches from all subsets of an sc-set object

ARGUMENTS

 - the sc-set object
 - &rest the pitches to remove, as pitch objects or symbols

RETURN VALUE

 the sc-set

SYNOPSIS

(defmethod subsets-remove ((s sc-set) &rest pitches)

sc-set/thin [ Methods ]

[ Top ] [ sc-set ] [ Methods ]

DATE

 June 1st 2017, Edinburgh

DESCRIPTION

 Remove pitches from a set using a deterministic algorithm. From bottom to
 top (or vice-versa) pitches will be selected or rejected using the
 activity-levels class, to which the strength (1-10) is passed. The pitches
 removed are also removed from any subsets.

 By default the set will be reduced by 1/3 of its pitches but it is expected
 that either the :remove or :target keyword will be used (see below).

ARGUMENTS

 - an sc-set object

OPTIONAL ARGUMENTS

 keyword arguments:
 - :strength. An integer from 1-10 indicating the likelihood of removing
   individual pitches. 1 would be 10%, 10, 100%. Default = 5.
 - :remove. An integer indicating how many pitches to remove. Default = NIL
 - :target. An integer indicating how many pitches the set should be left
   with. Default = NIL
 - :invert. T or NIL to remove pitches starting at the top or bottom. T =
   from top, NIL = from bottom. Default = NIL 

RETURN VALUE

 The (thinned) sc-set object.

EXAMPLE

SYNOPSIS

(defmethod thin ((s sc-set) &key (strength 5) remove target invert)

sclist/sc-set [ Classes ]

[ Top ] [ sclist ] [ Classes ]

NAME

 player

 File:             sc-set.lsp

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

 Version:          1.0.12

 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:  14:58:36 Fri Sep 25 2020 CEST

 SVN ID: $Id$