rthm-seq-bar/add-half-beat-rest [ Methods ]

[ Top ] [ rthm-seq-bar ] [ Methods ]

DATE

 August 25th 2016, Edinburgh

DESCRIPTION

 Adds a half beat rest at the end of the bar. This is a destructive
 method. It will change the time signature, so a 2/4 bar becomes a 5/8
 bar, with an 1/8th rest at the end.

ARGUMENTS

 - rthm-seq-bar object

OPTIONAL ARGUMENTS

 - ignore: don't pass this; it's only there so we can have a bar number
 passed in the slippery-chicken class.

RETURN VALUE

 The modified rthm-seq-bar object passed as an argument

SYNOPSIS

(defmethod add-half-beat-rest ((rsb rthm-seq-bar) &optional ignore)

rthm-seq-bar/all-rests? [ Methods ]

[ Top ] [ rthm-seq-bar ] [ Methods ]

DESCRIPTION

 Test whether all rhythms in a rthm-seq-bar object are rests.

ARGUMENTS

 - A rthm-seq-bar object.

RETURN VALUE

 T if all rhythms are rests, otherwise NIL

EXAMPLE

(let ((rsb (make-rthm-seq-bar '((2 4) (q) (e) (s) (s)))))
  (all-rests? rsb))

=> T

(let ((rsb (make-rthm-seq-bar '((2 4) q e s s))))
  (all-rests? rsb))

=> NIL

SYNOPSIS

(defmethod all-rests? ((rsb rthm-seq-bar))

rthm-seq-bar/auto-beam [ Methods ]

[ Top ] [ rthm-seq-bar ] [ Methods ]

DESCRIPTION

 Automatically add beaming indications to the rhythm objects of the given
 rthm-seq-bar object.  This will only set one beam group per beat.

 NB: This method does not modify the data slot of the rthm-seq-bar object
     itself. Instead, it modifies the beam value for the individual rhythms.

ARGUMENTS

 - A rthm-seq-bar object.

OPTIONAL ARGUMENTS

 - The beat basis for the given rthm-seq-bar. This will affect which notes
   get beamed together. This value can be either numeric (4, 8 16 etc.) or
   alphabetic (q, e, s etc). If no beat is given, the method defaults this
   value to NIL and takes the beat from the current time signature.
 - Check-dur. This can be t, nil, #'warn or #'error, where t is the same as
   #'error. If T, the method will make sure there is a complete beat of
   rhythms for each beat of the bar and issue an error if a full beat's
   worth cannot be returned--this may not mean that your bar is
   malformed. Or if you pass a symbol like 'silent the 
   duration will be checked and NIL returned if we can't get an exact beat's
   worth of rthms. Default = T.

RETURN VALUE

 Returns the rthm-seq-bar-object

EXAMPLE

(let ((rsb (make-rthm-seq-bar '((2 4) e e s s s s))))
  (auto-beam rsb))

=> NIL

(let ((rsb (make-rthm-seq-bar '((2 4) e e s s s s))))
  (auto-beam rsb)
  (loop for r in (rhythms rsb) collect (beam r)))

=> (1 0 1 NIL NIL 0)

(let ((rsb (make-rthm-seq-bar '((2 4) e e s s s s))))
  (auto-beam rsb 8)
  (loop for r in (rhythms rsb) collect (beam r)))

=> (NIL NIL 1 0 1 0)

(let ((rsb (make-rthm-seq-bar '((2 4) e e s s s s))))
  (auto-beam rsb 8 t)
  (loop for r in (rhythms rsb) collect (beam r)))

=> (NIL NIL 1 0 1 0)

(let ((rsb (make-rthm-seq-bar '((2 4) e e s s s s))))
  (auto-beam rsb 8 nil)
  (loop for r in (rhythms rsb) collect (beam r)))

=> (NIL NIL 1 0 1 0)

SYNOPSIS

(defmethod auto-beam ((rsb rthm-seq-bar) &optional (beat nil) (check-dur t))

rthm-seq-bar/auto-put-tuplet-bracket-on-beats [ Methods ]

[ Top ] [ rthm-seq-bar ] [ Methods ]

DESCRIPTION

 Given a rthm-seq-bar object with tuplet rhythms and an indication of which
 tuplet value to place, this method will automatically add the appropriate
 tuplet bracket to the beats of the bar in the printed score output. If
 the TUPLET argument is set to NIL, the method will proceed on the basis of
 best-guessing rules. 

 NB: This method may produce results that encapsulate an entire beat when
     applying brackets to a portion of that beat. Thus bracketing the rhythm
     (e ts ts ts) will return
     { 3 e. ts ts ts } rather than 
     ( e { 3 ts ts ts } )

ARGUMENTS

 - A rthm-seq-bar object
 - An integer indicating the tuplet value (e.g. 3 for triplets, 5 for
   quintuplets etc.)

RETURN VALUE

 Returns T.

OPTIONAL ARGUMENTS

 - An integer indicating beat basis for the bar, or NIL. If NIL (default),
   the beat is taken from the time signature.
 - An integer indicating the beat number within the bar to look for
   tuplets, or T. If  T (default), all beats in the bar will be examined for
   possible tuplets. 
 - T or NIL to indicate whether to delete the tuplet bracket indicators
   already present in the given rthm-seq-bar object. T = delete. 
   Default = T. 

EXAMPLE

(let ((rsb (make-rthm-seq-bar '((2 4) te te te q))))
  (tuplets rsb))

=> NIL

(let ((rsb (make-rthm-seq-bar '((2 4) te te te q))))
  (loop for r in (rhythms rsb) collect (bracket r))

=> (NIL NIL NIL NIL)

(let ((rsb (make-rthm-seq-bar '((2 4) te te te q))))
  (auto-put-tuplet-bracket-on-beats rsb 3))

=> T

(let ((rsb (make-rthm-seq-bar '((2 4) te te te q))))
  (auto-put-tuplet-bracket-on-beats rsb 3)
  (print (tuplets rsb))
  (print (loop for r in (rhythms rsb) collect (bracket r))))

=>
((3 0 2)) 
(((1 3)) (-1) (1) NIL)

(let ((rsb (make-rthm-seq-bar '((2 4) te te te q))))
  (auto-put-tuplet-bracket-on-beats rsb nil)
  (tuplets rsb))

=> ((3 0 2))

;;; The method may bracket the entire beat, returning ((3 1 4)) rather than 
;;; ((3 2 4))
(let ((rsb (make-rthm-seq-bar '((2 4) q e ts ts ts))))
  (auto-put-tuplet-bracket-on-beats rsb 3)
  (tuplets rsb))

=> ((3 1 4))

SYNOPSIS

(defmethod auto-put-tuplet-bracket-on-beats ((rsb rthm-seq-bar) tuplet 
                                             &optional 
                                             (beat nil)
                                             ;; can be a beat number or t for
                                             ;; all
                                             (beat-number t)
                                             ;; delete the tuplets already
                                             ;; there?  
                                             (delete t))

rthm-seq-bar/auto-tuplets [ Methods ]

[ Top ] [ rthm-seq-bar ] [ Methods ]

DESCRIPTION

 Automatically place the data necessary for tuplet brackets in rthm-seq-bar
 objects that contain tuplet rhythms.

ARGUMENTS

 - A rthm-seq-bar object.

OPTIONAL ARGUMENTS

 - A function to be performed on fail. Default = #'error.

RETURN VALUE

 Returns T if successful. 

EXAMPLE

;;; Make a rthm-seq-bar object and print the values of the BRACKET slots for
;;; the rhythm objects it contains. Then apply auto-brackets and print the same
;;; again to see the change.
(let ((rsb (make-rthm-seq-bar '((4 4) tq tq tq +q fs fs fs fs fs))))
  (print (loop for r in (rhythms rsb) collect (bracket r)))
  (auto-tuplets rsb)
  (print (loop for r in (rhythms rsb) collect (bracket r))))

=>
(NIL NIL NIL NIL NIL NIL NIL NIL NIL) 
(((1 3)) (-1) (1) NIL ((2 5)) (-2) (-2) (-2) (2)) 

SYNOPSIS

(defmethod auto-tuplets ((rsb rthm-seq-bar) &optional (on-fail #'error))

rthm-seq-bar/check-beams [ Methods ]

[ Top ] [ rthm-seq-bar ] [ Methods ]

DESCRIPTION

 Check the BEAM slots of the event objects within a specified rthm-seq-bar
 object to ensure that every beginning beam indication (slot value of 1) is
 coupled with a corresponding closing beam indication (slot value of 0), and
 print a warning and return NIL if this is not the case.

ARGUMENTS

 - A rthm-seq-bar object.

OPTIONAL ARGUMENTS

 keyword arguments:
 - :auto-beam. T or NIL to indicate the method should apply the auto-beam
   algorithm to the given bar after the check has determined that the 
   beaming is wrong (and :on-fail is not NIL). T = auto-beam. Default = NIL. 
 - :print. T or NIL to indicate whether the method should print feedback of
   the checking process to the Lisp listener. T = print feedback. Default =
   NIL.
 - :fix. T or NIL to indicate that when a beam has been placed over a rhythm
    with no flags (e.g. a 1/4 note), then we delete beams over that note and
    try again. Default = T.
 - :on-fail. The function that should be applied when the check does not
   pass. May be NIL for no warning/error or #'error if processing should
   stop. Default = #'warn.  

RETURN VALUE

 T if the check passes, otherwise NIL.

EXAMPLE

(let ((mini
       (make-slippery-chicken
        '+mini+
        :ensemble '(((sax ((alto-sax tenor-sax) :midi-channel 1))))
        :instrument-change-map '((1 ((sax ((1 alto-sax) (3 tenor-sax)))))
                                 (2 ((sax ((2 alto-sax) (5 tenor-sax)))))
                                 (3 ((sax ((3 alto-sax) (4 tenor-sax))))))
        :set-palette '((1 ((c2 d2 g2 a2 e3 fs3 b3 cs4 fs4 gs4 ds5 f5 bf5))))
        :set-map '((1 (1 1 1 1 1))
                   (2 (1 1 1 1 1))
                   (3 (1 1 1 1 1)))
        :rthm-seq-palette '((1 ((((4 4) h e (s) (s) e+s+s))
                                :pitch-seq-palette ((1 2 3)))))
        :rthm-seq-map '((1 ((sax (1 1 1 1 1))))
                        (2 ((sax (1 1 1 1 1))))
                        (3 ((sax (1 1 1 1 1))))))))
  (check-beams (get-bar mini 1 'sax)))

=> T

(let ((mini
       (make-slippery-chicken
        '+mini+
        :ensemble '(((sax ((alto-sax tenor-sax) :midi-channel 1))))
        :instrument-change-map '((1 ((sax ((1 alto-sax) (3 tenor-sax)))))
                                 (2 ((sax ((2 alto-sax) (5 tenor-sax)))))
                                 (3 ((sax ((3 alto-sax) (4 tenor-sax))))))
        :set-palette '((1 ((c2 d2 g2 a2 e3 fs3 b3 cs4 fs4 gs4 ds5 f5 bf5))))
        :set-map '((1 (1 1 1 1 1))
                   (2 (1 1 1 1 1))
                   (3 (1 1 1 1 1)))
        :rthm-seq-palette '((1 ((((4 4) h e (s) (s) e+s+s))
                                :pitch-seq-palette ((1 2 3)))))
        :rthm-seq-map '((1 ((sax (1 1 1 1 1))))
                        (2 ((sax (1 1 1 1 1))))
                        (3 ((sax (1 1 1 1 1))))))))
  (setf (beam (nth 1 (rhythms (get-bar mini 1 'sax)))) 1)
  (check-beams (get-bar mini 1 'sax)))

=> NIL

SYNOPSIS

(defmethod check-beams ((rsb rthm-seq-bar) &key auto-beam print (fix t)
                                             (on-fail #'warn))

rthm-seq-bar/check-tuplets [ Methods ]

[ Top ] [ rthm-seq-bar ] [ Methods ]

DESCRIPTION

 Check the qualities of the tuplets brackets in a given rthm-seq-bar
 object to make sure they are all formatted properly (i.e. each starting
 tuplet bracket has a closing tuplet bracket etc.). If an error is found,
 the method will try to fix it, then re-check, and only issue an error then
 if another is found.

 NB this won't check whether tuplet brackets start and stop on notes
 spanning a whole beat (as that wouldn't make sense with nested tuplets) so
 it won't guarantee that a bar can be notated without errors.

ARGUMENTS

 - A rthm-seq-bar object.

OPTIONAL ARGUMENTS

 - The function to use if something is not ok with the tuplets. This
   defaults to #'error, but could also be #'warn for example

RETURN VALUE

 T if all tuplets brackets are ok, otherwise performs the on-fail function
 and returns NIL.

EXAMPLE

(let ((rsb (make-rthm-seq-bar '((4 4) { 3 te te te } q q q))))
  (setf (bracket (get-nth-event 2 rsb)) nil)
  (check-tuplets rsb #'warn))

=> rthm-seq-bar::check-tuplets: got a nil bracket when brackets still open.

SYNOPSIS

(defmethod check-tuplets ((rsb rthm-seq-bar) &optional (on-fail #'error))

rthm-seq-bar/chop [ Methods ]

[ Top ] [ rthm-seq-bar ] [ Methods ]

DESCRIPTION

 Creates a list of new rthm-seq-bar objects, with new time signatures, which
 are formed by systematically chopping the bar represented by the current
 rthm-seq-bar into segments. 

 The method creates these segments based on chop-point pairs specified in
 the <chop-points> argument, which is a list of 2-element lists, each of
 which specifies the start and end points of a rhythmic span within the
 bounds of a given beat, measured in the unit specified by the <unit>
 argument. 

 The chop points specified are used to individually process each beat in the
 given rthm-seq-bar object; thus, chop-points specified for the subdivisions
 of a quarter-note will not work if applied to a 5/8 bar.

 The method fills each newly created rthm-seq-bar object with one rhythmic
 duration that is equal to the length of the bar. If the beginning of the
 given chop segment coincides with an attack in the original bar, the result
 is a sounding note; if not, the result is a rest. NB: In this abstraction
 of the class for the sake of this documentation, sounding notes will appear
 as NIL. 

 The chop method is the basis for slippery-chicken's feature of
 intra-phrasal looping.

 NB: The <unit> argument must be a duplet rhythmic value (i.e. 32, 's, 'e
     etc.) and cannot be a tuplet value (i.e. 'te 'fe etc.). 

 NB: In order for the resulting chopped rhythms to be parsable by LilyPond
     and CMN, there can be no tuplets (triplets etc.) among the rhythms to
     be chopped. Such rhythms will result in LilyPond and CMN errors. This
     has only minimal bearing on any MIDI files produced, however, and these
     can potentially be imported into notation software.

ARGUMENTS

 - A rthm-seq-bar object.

OPTIONAL ARGUMENTS

 - <chop-points> A list of integer pairs, each of which delineates a segment
   of the beat of the given rthm-seq-bar object measured in the rhythmic
   unit specified by the <unit> argument. Thus, if all possible spans of
   sixteenth-notes within a quarter-note, starting from the first sixteenth,
   were delineated, they would span from 1 to 4 (the full quarter), 1 to 3
   (the first dotted 8th of the quarter), 1 to 2 (the first 8th) and 1 to 1
   (the first 16th of the quarter); the process could continue then with all
   rhythmic durations contained within the bounds of the same quarter
   starting on the second 16th, etc. The default chop-points for a quarter
   are '((1 4) (1 3) (1 2) (2 4) (2 3) (3 4) (1 1) (2 2) (3 3) (4 4)).
 - <unit>. The rhythmic duration that serves as the unit of measurement for
   the chop points. Default = 's.
 - <rthm-seq-id>. A symbol that will be the ID for the list created.

RETURN VALUE

 A list of rthm-seq-bar objects.

EXAMPLE

;; Systematically subdivide each quarter-note of a 2/4 bar containing two ; ;
;; quarter-notes into all possible segments whose durations are multiples of a ; ;
;; sixteenth-note unit, and print-simple the resulting list. The quarter-note ; ;
;; subdivision is re-specified here sightly differently to the default for the ; ;
;; sake of systematic clarity. Only those segments whose start point coincide ; ;
;; with an attack in the original bar, i.e. those that begin on the first ; ;
;; sixteenth of each  beat, will be assigned a NIL (which will later become ; ;
;; a sounding note); all others are assigned a rest. ; ;

(let* ((rsb (make-rthm-seq-bar '((2 4) q q)))
(ch (chop rsb 
'((1 4) (1 3) (1 2) (1 1) 
(2 4) (2 3) (2 2) 
(3 4) (3 3) 
(4 4))   
's))) 
(loop for b in ch do (print-simple b)))

=>
(1 4): NIL Q, 
(3 16): NIL E., 
(1 8): NIL E, 
(1 16): NIL S, 
(3 16): rest 16/3, 
(1 8): rest 8, 
(1 16): rest 16, 
(1 8): rest 8, 
(1 16): rest 16, 
(1 16): rest 16, 
(1 4): NIL Q, 
(3 16): NIL E., 
(1 8): NIL E, 
(1 16): NIL S, 
(3 16): rest 16/3, 
(1 8): rest 8, 
(1 16): rest 16, 
(1 8): rest 8, 
(1 16): rest 16, 
(1 16): rest 16,

;; The same thing, but returning all possible segments within the bounds of a ; ;
;; quarter-note whose durations that are multiple of an 8th-note unit ; ;
(let* ((rsb (make-rthm-seq-bar '((2 4) q q)))
(choprsb (chop rsb 
'((1 2) (1 1) (2 2))
'e)))
(loop for b in choprsb do (print-simple b)))

=>
(1 4): NIL Q, 
(1 8): NIL E, 
(1 8): rest 8, 
(1 4): NIL Q, 
(1 8): NIL E, 
(1 8): rest 8,

;; Adapt the 16th-note example above to a starting rthm-seq-bar object with ; ;
;; more complex rhythmic content. Note here, too, that the rthm-seq-bar object ; ;
;; being segmented contains rhythmic durations smaller than the <unit> ; ;
;; argument.                            ; ;
(let* ((rsb (make-rthm-seq-bar '((4 4) - (s) (32) 32 (s) s - - +s+32 (32) (e) -
(q) (s) s (e))))  
(choprsb (chop rsb 
'((1 4) (1 3) (1 2) (1 1) 
(2 4) (2 3) (2 2) 
(3 4) (3 3) 
(4 4))
's)))
(loop for b in choprsb do (print-simple b)))

=>
(1 4): rest S, rest 32, NIL 32, rest S, NIL S, 
(3 16): rest S, rest 32, NIL 32, rest S, 
(1 8): rest S, rest 32, NIL 32, 
(1 16): rest 16, 
(3 16): rest 32, NIL 32, rest S, NIL S, 
(1 8): rest 32, NIL 32, rest S, 
(1 16): rest 32, NIL 32, 
(1 8): rest S, NIL S, 
(1 16): rest 16, 
(1 16): NIL S, 
(1 4): rest 4, 
(3 16): rest 16/3, 
(1 8): rest 8, 
(1 16): rest 16, 
(3 16): rest 16/3, 
(1 8): rest 8, 
(1 16): rest 16, 
(1 8): rest 8, 
(1 16): rest 16, 
(1 16): rest 16, 
(1 4): rest 4, 
(3 16): rest 16/3, 
(1 8): rest 8, 
(1 16): rest 16, 
(3 16): rest 16/3, 
(1 8): rest 8, 
(1 16): rest 16, 
(1 8): rest 8, 
(1 16): rest 16, 
(1 16): rest 16, 
(1 4): rest S, NIL S, rest E, 
(3 16): rest S, NIL S, rest S, 
(1 8): rest S, NIL S, 
(1 16): rest 16, 
(3 16): NIL S, rest E, 
(1 8): NIL S, rest S, 
(1 16): NIL S, 
(1 8): rest 8, 
(1 16): rest 16, 
(1 16): rest 16,

;; The same again with a <unit> of eighths ; ;
(let* ((rsb (make-rthm-seq-bar '((4 4) - (s) (32) 32 (s) s - - +s+32 (32) (e) -
(q) (s) s (e))))  
(choprsb (chop rsb 
'((1 2) (1 1) (2 2))
'e)))
(loop for b in choprsb do (print-simple b)))

=>
(1 4): rest S, rest 32, NIL 32, rest S, NIL S, 
(1 8): rest S, rest 32, NIL 32, 
(1 8): rest S, NIL S, 
(1 4): rest 4, 
(1 8): rest 8, 
(1 8): rest 8, 
(1 4): rest 4, 
(1 8): rest 8, 
(1 8): rest 8, 
(1 4): rest S, NIL S, rest E, 
(1 8): rest S, NIL S, 
(1 8): rest 8,

SYNOPSIS

(defmethod chop ((rsb rthm-seq-bar) 
                 &optional chop-points (unit 's) rthm-seq-id)

rthm-seq-bar/consolidate-notes [ Methods ]

[ Top ] [ rthm-seq-bar ] [ Methods ]

DESCRIPTION

 Combine consecutive tied notes into one (or a few) notes of a longer
 rhythmic duration. 

 NB: This method is the core method that is called for rthm-seq objects or
     slippery-chicken objects, at which point it takes ties (and perhaps
     another couple of things) into consideration, after the tie slots
     etc. have been updated. As such, though it will
     work to a certain degree when called directly on a rthm-seq-bar object,
     it should primarily be used when getting a rthm-seq-bar from within a 
     rthm-seq object or slippery-chicken object.

ARGUMENTS

 - A rthm-seq-bar object.

OPTIONAL ARGUMENTS

 - T or NIL to indicate whether the method should make sure that an exact
   beat's worth of rhythms is handled. T = check durations. Default = NIL. 

RETURN VALUE

 The rthm-seq-bar object.

EXAMPLE

;;; Create a slippery-chicken object, print-simple a bar from that object,
;;; apply the consolidate-notes method to that bar, and print-simple that bar
;;; again to see the changes.

(let ((mini
       (make-slippery-chicken
        '+mini+
        :ensemble '(((vn (violin :midi-channel 1))))
        :set-palette '((1 ((gs4 af4 bf4))))
        :set-map '((1 (1 1 1)))
        :rthm-seq-palette '((1 ((((4 4) e +e +e +e e +s +s +s e.))
                                :pitch-seq-palette ((1 2 3)))))
        :rthm-seq-map '((1 ((vn (1 1 1))))))))
  (print-simple (get-bar mini 2 'vn))
  (consolidate-notes (get-bar mini 2 'vn))
  (print-simple (get-bar mini 2 'vn)))

=>
(4 4): GS4 E+, +GS4 E+, +GS4 E+, +GS4 E, AF4 E+, +AF4 S+, +AF4 S+, +AF4 S,
BF4 E.,
(4 4): GS4 H, AF4 Q+, +AF4 S, BF4 E.,

SYNOPSIS

(defmethod consolidate-notes ((rsb rthm-seq-bar)
                              ;; MDE Wed Nov 28 11:40:59 2012 -- added auto-beam
                              &optional check-dur beat (auto-beam t))

rthm-seq-bar/consolidate-rests [ Methods ]

[ Top ] [ rthm-seq-bar ] [ Methods ]

DESCRIPTION

 Consolidate two or more consecutive rests into one longer rhythmic
 unit. This method works on the basis of beats, striving to consolidate into
 beats first.

 NB: The user may find it helpful to adjust the :beat and :min values, and
     even to call the method more than once consecutively. For multiple
     calls, the method consolidate-rests-max may also be useful.

ARGUMENTS

 - A rthm-seq-bar object.

OPTIONAL ARGUMENTS

 keyword arguments
 - :beat. The beat basis into which rests are to be consolidated. If no
   value is given for this option, the method will take the beat from the
   time signature. 
 - :min. A seldom-used argument that will only make a difference when there
   are a number of rests of the same duration followed by a note.  This is
   then the minimum duration that such rests may have if they are to be
   consolidated. Default = NIL.
 - :warn. T or NIL to indicate whether the method should print a warning to
   the Lisp listener if it is mathematically unable to consolidate the
   rests. T = print warning. Default = NIL.
 - :auto-tuplets. Whether to force a call to the auto-tuplets method before
   returning. This will happen by default anyway if check-tuplets fails, but
   sometimes that doesn't fail, exactly, but auto-tuplets still makes
   sense. If, for example, Lilypond fails with strange error messages,
   setting this to T might help. Default = NIL. 

RETURN VALUE

 The rthm-seq-bar object

EXAMPLE

;;; Returns a list of rhythm/event objects 
(let ((rsb (make-rthm-seq-bar '((4 4) (e) (e) (e) (e) (e) (s) (s) (s) e.))))
  (consolidate-rests rsb))

=>
(
EVENT: start-time: NIL, end-time: NIL, 
[...]
data: 4
[...]
EVENT: start-time: NIL, end-time: NIL, 
[...]
data: 4
[...]
EVENT: start-time: NIL, end-time: NIL, 
[...]
data: 4
[...]
RHYTHM: value: 16.000, duration: 0.250, rq: 1/4, is-rest: T, 
[...]
data: S
[...]
RHYTHM: value: 5.333, duration: 0.750, rq: 3/4, is-rest: NIL, 
[...]
data: E.
)

;;; Consolidating on the basis of the time-signature's beat by default
(let ((rsb (make-rthm-seq-bar '((4 4) (e) (e) (e) (e) (e) (s) (s) (s) e.))))
  (consolidate-rests rsb)
  (loop for r in (rhythms rsb) collect (data r)))

=> (4 4 4 S E.)

;; Changing the :beat may effect the outcome
(let ((rsb (make-rthm-seq-bar '((4 4) (e) (e) (e) (e) (e) (s) (s) (s) e.))))
  (consolidate-rests rsb :beat 2)
  (loop for r in (rhythms rsb) collect (data r)))

=> (2 E E S E.)

;; Calling multiple times may further consolidate the results
(let ((rsb (make-rthm-seq-bar '((2 2) (e) (e) (e) (e) (e) (s) (s) (s) e.))))
  (consolidate-rests rsb)
  (print (loop for r in (rhythms rsb) collect (data r)))
  (consolidate-rests rsb)
  (print (loop for r in (rhythms rsb) collect (data r))))

=>
(2 E E S E.) 
(2 Q S E.)

SYNOPSIS

(defmethod consolidate-rests ((rsb rthm-seq-bar)
                              &key beat min warn auto-tuplets)

rthm-seq-bar/consolidate-rests-max [ Methods ]

[ Top ] [ rthm-seq-bar ] [ Methods ]

DESCRIPTION

 Similar to consolidate-rests, but calls that method repeatedly until no
 more changes can be made to the given rthm-seq-bar object.

 NB This will still only reduce rests down to a maximum of a beat.  If you
    need e.g. two quarter rests reduced to a single half rest in a 4/4 bar,
    specify :beat 2

ARGUMENTS

 - A rthm-seq-bar object.

OPTIONAL ARGUMENTS

 keyword arguments:
 - :beat. The beat basis into which rests are to be consolidated. If no
   value is given for this option, the method will take the beat from the
   time signature. 
 - :min. A seldom-used argument that will only make a difference when there
   are a number of rests of the same duration followed by a note.  This is
   then the minimum duration that such rests may have if they are to be
   consolidated. Default = NIL.
 - :warn. T or NIL to indicate whether the method should print a warning to
   the Lisp listener if it is mathematically unable to consolidate the
   rests. T = print warning. Default = NIL.

RETURN VALUE

 The rthm-seq-bar-object

EXAMPLE

;;; Two examples with the same result; the first calling consolidate-rests
;;; twice, the second calling consolidate-rests-max
(let ((rsb (make-rthm-seq-bar '((2 2) (e) (e) (e) (e) (e) (s) (s) (s) e.))))
  (consolidate-rests rsb)
  (consolidate-rests rsb)
  (loop for r in (rhythms rsb) collect (data r)))

=> (2 Q S E.)

(let ((rsb (make-rthm-seq-bar '((2 2) (e) (e) (e) (e) (e) (s) (s) (s) e.))))
  (consolidate-rests-max rsb)
  (loop for r in (rhythms rsb) collect (data r)))

=> (2 Q S E.)

SYNOPSIS

(defmethod consolidate-rests-max ((rsb rthm-seq-bar) &key beat min warn)

rthm-seq-bar/delete-beams [ Methods ]

[ Top ] [ rthm-seq-bar ] [ Methods ]

DESCRIPTION

 Remove any beaming indications from the rthm-seq-bar object. 

 NB: This method changes the data for the rthm-seq-bar object's BEAMS slot
     and the individual BEAM slots of the RHYTHMs contained within the
     rthm-seq-bar's RHYTHMS slot. It does not change the value of the
     rthm-seq-bar's DATA slot.

 NB: Neither the presence nor absence of beams are not reflected in the
     output of the print-simple method.

ARGUMENTS

 - A rthm-seq-bar object.

RETURN VALUE

 Returns T.

EXAMPLE

(let ((rsb (make-rthm-seq-bar '((2 4) - s s - s - s s s - s s))))
  (delete-beams rsb))

=> T

(let ((rbs (make-rthm-seq-bar '((2 4) - s s - s - s s s - s s))))
  (delete-beams rsb)
  (beams rsb))

=> NIL

(let ((rsb (make-rthm-seq-bar '((2 4) - s s - s - s s s - s s))))
  (delete-beams rsb)
  (loop for r in (rhythms rbs) collect (beam r)))

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

(let ((rbs (make-rthm-seq-bar '((2 4) - s s - s - s s s - s s))))
  (delete-beams rsb)
  (print rsb))

=>
RTHM-SEQ-BAR: time-sig: 1 (2 4)
              time-sig-given: T
              bar-num: -1
              old-bar-nums: NIL
              write-bar-num: NIL
              start-time: -1.0
              start-time-qtrs: -1.0
              is-rest-bar: NIL
              multi-bar-rest: NIL
              show-rest: T
              notes-needed: 8
              tuplets: NIL
              nudge-factor: 0.35
              beams: NIL
[...]
NAMED-OBJECT: id: NIL, tag: NIL, 
data: ((2 4) - S S - S - S S S - S S)

SYNOPSIS

(defmethod delete-beams ((rsb rthm-seq-bar))

rthm-seq-bar/delete-marks [ Methods ]

[ Top ] [ rthm-seq-bar ] [ Methods ]

DESCRIPTION

 Delete all marks from the rhythm (or event) objects contained within a given
 rthm-seq-bar object.
 
 ARGUMENT
 - A rthm-seq-bar object.

RETURN VALUE

 Always returns NIL.

EXAMPLE

;; Create a rthm-seq-bar object and print the contents of the MARKS slots of
;; the contained event objects to see they're set to NIL by default. Fill them
;; each with a 's (staccato) mark and print the results. Apply the delete-marks
;; method and print the results again to see that the values have been reset to
;; NIL. 
(let ((rsb (make-rthm-seq-bar 
            (list
             '(3 8) 
             (make-event 'cs4 'e)
             (make-event 'cs4 'e)
             (make-event 'cs4 'e)))))
  (print (loop for e in (rhythms rsb) collect (marks e)))
  (loop for e in (rhythms rsb) do (add-mark-once e 's))
  (print (loop for e in (rhythms rsb) collect (marks e)))
  (delete-marks rsb)
  (print (loop for e in (rhythms rsb) collect (marks e))))

=>
(NIL NIL NIL) 
((S) (S) (S)) 
(NIL NIL NIL)

SYNOPSIS

(defmethod delete-marks ((rsb rthm-seq-bar))

rthm-seq-bar/delete-tuplets [ Methods ]

[ Top ] [ rthm-seq-bar ] [ Methods ]

DESCRIPTION

 Removes all indications for tuplet brackets from a given rthm-seq-bar
 object. 

 NB: This method does not alter the tuplet rhythmic durations; it only
 removes the tuplet bracket from the score.

ARGUMENTS

 - A rthm-seq-bar.

RETURN VALUE

 The rthm-seq-bar object

EXAMPLE

(let ((rsb (make-rthm-seq-bar '((2 4) { 3 te te te } q))))
  (tuplets rsb))

=> ((3 0 2))

(let ((rsb (make-rthm-seq-bar '((2 4) { 3 te te te } q))))
  (delete-tuplets rsb))

=> NIL

(let ((rsb (make-rthm-seq-bar '((2 4) { 3 te te te } q))))
  (delete-tuplets rsb)
  (tuplets rsb))

=> NIL

(let ((rsb (make-rthm-seq-bar '((2 4) { 3 te te te } q))))
  (loop for r in (rhythms rsb) collect (bracket r)))

=> (((1 3)) (-1) (1) NIL)

(let ((rsb (make-rthm-seq-bar '((2 4) { 3 te te te } q))))
  (delete-tuplets rsb)
  (loop for r in (rhythms rsb) collect (bracket r)))

=> (NIL NIL NIL NIL)

SYNOPSIS

(defmethod delete-tuplets ((rsb rthm-seq-bar))

rthm-seq-bar/delete-written [ Methods ]

[ Top ] [ rthm-seq-bar ] [ Methods ]

DESCRIPTION

 Delete the contents of the WRITTEN-PITCH-OR-CHORD slot of a pitch object
 within a given event object and reset to NIL.

ARGUMENTS

 - A rthm-seq-bar object.

RETURN VALUE

 Always returns NIL.

EXAMPLE

;; Create a rthm-seq-bar object consisting of events and print the contents of ; ; ; ; ; ;
;; the WRITTEN-PITCH-OR-CHORD slots to see they're set to NIL. Apply the ; ; ; ; ; ;
;; set-written method with a value of -2 and print the contents of the ; ; ; ; ; ;
;; WRITTEN-PITCH-OR-CHORD slots to see the data of the newly created pitch ; ; ; ; ; ;
;; objects. Apply the delete-written method and print the contents of the ; ; ; ; ; ;
;; WRITTEN-PITCH-OR-CHORD slots to see they're empty. ; ; ; ; ; ;
  (let ((rsb (make-rthm-seq-bar 
(list
'(3 8) 
(make-event 'cs4 'e)
(make-event 'cs4 'e)
(make-event 'cs4 'e)))))
(print (loop for p in (rhythms rsb)
collect (written-pitch-or-chord p)))
(set-written rsb -2)
(print (loop for p in (rhythms rsb)
collect (get-pitch-symbol p)))
(delete-written rsb)
(print (loop for p in (rhythms rsb)
collect (written-pitch-or-chord p))))

  =>
  (NIL NIL NIL) 
  (B3 B3 B3) 
  (NIL NIL NIL)

SYNOPSIS

(defmethod delete-written ((rsb rthm-seq-bar))

rthm-seq-bar/enharmonic [ Methods ]

[ Top ] [ rthm-seq-bar ] [ Methods ]

DESCRIPTION

 Change the pitches of the events within a given rthm-seq-bar object to
 their enharmonic equivalents. 
 
 In its default form, this method only applies to note names that already
 contain an indication for an accidental (such as DF4 or BS3), while
 "white-key" note names (such as B3 or C4) will not produce an enharmonic
 equivalent. In order to change white-key pitches to their enharmonic
 equivalents, set the :force-naturals argument to T. 

ARGUMENTS

 - A rthm-seq-bar object.

OPTIONAL ARGUMENTS

 keyword arguments:
 - :written. T or NIL to indicate whether the test is to handle the
   written or sounding pitch in the event. T = written. 
   Default = NIL.
 - :force-naturals. T or NIL to indicate whether to force "natural"
   note names that contain no F or S in their name to convert to
   their enharmonic equivalent (e.g. B3 = CF4). Default = NIL.
 - :pitches. All sharp/flat pitches are changed by default but if a
   list of pitch objects or symbols is given, then only those
   pitches will be changed.  Note that if written is T, then this
   pitch list should be the written not sounding pitches.  
   Default = NIL.

RETURN VALUE

 Always returns T.

EXAMPLE

;; The method returns T.                ; ; ; ; ;
  (let ((rsb (make-rthm-seq-bar 
(list '(3 8) 
(make-event 'cs4 'e)
(make-event 'cs4 'e)
(make-event 'cs4 'e)))))
(enharmonic rsb))

  => T

;; Create a rthm-seq-bar object with events, apply the enharmonic method, and ; ; ; ; ;
;; print the corresponding slots to see the changes ; ; ; ; ; ;
  (let ((rsb (make-rthm-seq-bar 
(list
'(3 8) 
(make-event 'cs4 'e)
(make-event 'cs4 'e)
(make-event 'cs4 'e))))) 
(enharmonic rsb)
(loop for p in (rhythms rsb)
collect (get-pitch-symbol p)))

  => (DF4 DF4 DF4)

;; By default, the method will not change white-key pitches ; ; ; ; ;
  (let ((rsb (make-rthm-seq-bar 
(list
'(3 8) 
(make-event 'c4 'e)
(make-event 'c4 'e)
(make-event 'c4 'e)))))
(enharmonic rsb)
(loop for p in (rhythms rsb)
collect (get-pitch-symbol p)))

  => (C4 C4 C4)

;; This can be forced by setting the :force-naturals argument to T ; ; ; ; ;
  (let ((rsb (make-rthm-seq-bar 
(list
'(3 8) 
(make-event 'c4 'e)
(make-event 'c4 'e)
(make-event 'c4 'e)))))
(enharmonic rsb :force-naturals t)
(loop for p in (rhythms rsb)
collect (get-pitch-symbol p)))

  => (BS3 BS3 BS3)

;; Apply the set-written method to fill the WRITTEN-PITCH-OR-CHORD slot, print ; ; ; ; ;
;; its contents, apply the enharmonic method with the :written keyword argument ; ; ; ; ;
;; set to T, then print the pitch data of the same slot again to see the ; ; ; ; ;
;; change.                              ; ; ; ; ;
  (let ((rsb (make-rthm-seq-bar 
(list
'(3 8) 
(make-event 'cs4 'e)
(make-event 'cs4 'e)
(make-event 'cs4 'e)))))
(set-written rsb -3)
(print (loop for p in (rhythms rsb)
collect (get-pitch-symbol p)))
(enharmonic rsb :written t)
(print (loop for p in (rhythms rsb)
collect (get-pitch-symbol p))))

  =>
  (BF3 BF3 BF3) 
  (AS3 AS3 AS3)

SYNOPSIS

(defmethod enharmonic ((rsb rthm-seq-bar) &key written force-naturals
                       ;; MDE Wed Apr 18 11:34:01 2012
                       pitches)

rthm-seq-bar/events-update-time [ Functions ]

[ Top ] [ rthm-seq-bar ] [ Functions ]

DATE

 March 16th 2016, Edinburgh

DESCRIPTION

 Update the start-time and related slots of any events for which timing
 information is missing or out-of-sync. 

ARGUMENTS

 - a list of event objects

OPTIONAL ARGUMENTS

 keyword arguments:
 - :start-time. The start time in seconds of the first event
 - :start-time-qtrs. The start time in quarter notes of the first event (used
   in MIDI files)
 - :tempo. The tempo in beats per minute (or a tempo object)

RETURN VALUE

 two values: the list of events with their times updated, and the time the
 last event finishes.

EXAMPLE

  (event-list-to-midi-file
(events-update-time (make-events2 '(q q q) '(g4 g4 g4) 1))
:midi-file "/tmp/test.mid" :start-tempo 120)

SYNOPSIS

(defun events-update-time (events &key (start-time 0.0) (start-time-qtrs 0.0)
                                    (tempo 60.0))

rthm-seq-bar/fill-with-rhythms [ Methods ]

[ Top ] [ rthm-seq-bar ] [ Methods ]

DESCRIPTION

 Any rhythms (or event objects) in the existing rthm-seq-bar object will be
 deleted, and then rhythm (or event) objects will be taken one by one from
 the <rhythms> argument until the bar is full. 

 If too few rhythm or event objects are given, a warning will be printed
 that there are too few beats in the bar.

 If there are too many and the last rhythm or event object to be placed in
 the bar fills out the bar evenly, no warning is printed and the remaining
 rhythm or event objects are ignored. If :is-full-error is T (default) and
 the last rhythm or event object that the method attempts to place in the
 bar is too long to fit evenly into the bar, the method will drop into the
 debugger with an error. If in this case :is-full-error is NIL the bar will
 remain underfull and the index of the last rhythm added before over-filling
 will be returned. 

 The :transposition, :midi-channel, and :microtones-midi-channel arguments
 can only be used in conjunction with event objects.

 The number of rhythms (or event objects) used is returned.

 NB: This method does not change the DATA slot of the rthm-seq-bar object
     itself to reflect the new rhythms. Instead, it changes the contents of
     the RHYTHMS slot within that object and changes the DATA of the
     rthm-seq-bar object to NIL. It also assigns the ID of the named-object
     to "rhythms-inserted-by-fill-with-rhythms".

ARGUMENTS

 - A rthm-seq-bar object.
 - A list of rhythm objects or event objects.

OPTIONAL ARGUMENTS

 keyword arguments:
 - :transposition. An integer or NIL to indicate the transposition in
   semitones for written pitches of any event objects passed. If NIL, no
   written-pitches will be created. Default = NIL.
 - :midi-channel. An integer that will be used to set the MIDI-CHANNEL slot
   of any event objects passed. Default = 0.
 - :microtones-midi-channel. An integer that is the MIDI channel that will
   be assigned to event objects for microtonal MIDI pitches. NB: This value
   is only set when attached to event objects within a slippery-chicken
   object. Default = 0. NB: See player.lsp/make-player for details on
   microtones in MIDI output.  
 - :new-id. An optional ID for new rhythm or event objects added. 
   Default = "rhythms-inserted-by-fill-with-rhythms". 
 - :warn. T or NIL to indicate whether a warning should be printed if there
   are not enough rhythms to create a full bar. T = warn. Default = T.
 - :is-full-error. T or NIL to indicate whether the last rhythm or event
   object that the method attempts to add to the bar is too long to fit
   evenly into the bar. T = drop into the debugger with an error if this is
   the case. Default = T.

RETURN VALUE

 The number of rhythm or event objects used, which could be 0. NIL will be
 returned if, for example, an empty list of rhythms were passed, so do check
 for a NIL result. 

EXAMPLE

(let ((rsb (make-rthm-seq-bar '((3 4) q q q))))
  (fill-with-rhythms rsb (loop for r in '(e e e e e e)
                          collect (make-rhythm r))))

=> 6

(let ((rsb (make-rthm-seq-bar '((3 4) q q q))))
  (fill-with-rhythms rsb (loop for r in '(e e e e e e)
                          collect (make-rhythm r)))
  (print-simple rsb))

=> NIL
(3 4): note E, note E, note E, note E, note E, note E, 

(let ((rsb (make-rthm-seq-bar '((3 4) q q q))))
  (fill-with-rhythms rsb (loop for r in '(e e e e e e)
                          collect (make-rhythm r)))
  (print rsb))

=>
RTHM-SEQ-BAR: time-sig: 0 (3 4)
              time-sig-given: T
              bar-num: -1
              old-bar-nums: NIL
              write-bar-num: NIL
              start-time: -1.0
              start-time-qtrs: -1.0
              is-rest-bar: NIL
              multi-bar-rest: NIL
              show-rest: T
              notes-needed: 6
              tuplets: NIL
              nudge-factor: 0.35
              beams: NIL
              current-time-sig: 0
              write-time-sig: T
              num-rests: 0
              num-rhythms: 6
              num-score-notes: 6
              rhythms: (
RHYTHM: value: 8.0, duration: 0.5, rq: 1/2, is-rest: NIL, score-rthm: 8.0, 
        undotted-value: 8, num-flags: 1, num-dots: 0, is-tied-to: NIL, 
        is-tied-from: NIL, compound-duration: 0.5, 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: 8, 
        tuplet-scaler: 1, grace-note-duration: 0.05,
LINKED-NAMED-OBJECT: previous: NIL
                     this: NIL
                     next: NIL
NAMED-OBJECT: id: E, tag: NIL, 
data: E
[...]
NAMED-OBJECT: id: "rhythms-inserted-by-fill-with-rhythms", tag: NIL, 
data: NIL

;;; Using the :transpositions and :midi-channel arguments
(let ((rsb (make-rthm-seq-bar '((4 4) q q q q))))
  (fill-with-rhythms rsb (loop for r in '(h q e s s)
                              for p in '(c4 dqs4 e4 gqf4 a4)
                            collect (make-event p r))
                     :microtones-midi-channel 12
                     :transposition -14
                     :midi-channel 11)
  (print
   (loop for e in (rhythms rsb)
      collect (data (pitch-or-chord e))))
  (print 
   (loop for e in (rhythms rsb)
      collect (data (written-pitch-or-chord e))))
  (print 
   (loop for e in (rhythms rsb)
      collect (midi-channel (pitch-or-chord e)))))

=>
(C4 DQS4 E4 GQF4 A4) 
(D5 EQS5 FS5 AQF5 B5) 
(11 12 11 12 11)

SYNOPSIS

(defmethod fill-with-rhythms ((rsb rthm-seq-bar) rhythms
                              &key
                                ;; 24.3.11 add this too to make sure written
                                ;; pitch is set--this is the instrument
                                ;; transposition e.g. -14 for bass clarinet
                                transposition
                                (midi-channel 0)
                                (microtones-midi-channel 0)
                                (new-id "rhythms-inserted-by-fill-with-rhythms")
                                (warn t)
                                (is-full-error t))

rthm-seq-bar/force-all-rests [ Methods ]

[ Top ] [ rthm-seq-bar ] [ Methods ]

DATE

 November 7th 2018, Heidhausen

DESCRIPTION

 Makes all events in the bar rests. This differs from force-rest-bar in that
 it doesn't replace the events with a single full-bar rest  

ARGUMENTS

 - a rthm-seq-bar object

OPTIONAL ARGUMENTS

 - T or NIL to indicate that any marks (e.g. dynamics) should be retained,
   whether or not these make sense on rests. The exception is that slurs
   won't be retained.  Default = NIL.

RETURN VALUE

 the modified rthm-seq-bar object

SYNOPSIS

(defmethod force-all-rests ((rsb rthm-seq-bar) &optional retain-marks)

rthm-seq-bar/force-rest-bar [ Methods ]

[ Top ] [ rthm-seq-bar ] [ Methods ]

DESCRIPTION

 Force all rhythms of a rthm-seq-bar object to be replaced by rest.
 
 NB: This method changes the value of the RHYTHMS slot of the rthm-seq-bar
     but not the value of the rthm-seq-bar DATA slot.

ARGUMENTS

 - A rthm-seq-bar object.

RETURN VALUE

 Returns a rthm-seq-bar object.

EXAMPLE

(let ((rsb (make-rthm-seq-bar '((2 4) q e s s))))
  (force-rest-bar rsb))

=>
RTHM-SEQ-BAR: time-sig: 1 (2 4)
              time-sig-given: T
              bar-num: -1
              old-bar-nums: NIL
              write-bar-num: NIL
              start-time: -1.0
              start-time-qtrs: -1.0
              is-rest-bar: T
[...]
RHYTHM: value: 2.0, duration: 2.0, rq: 2, is-rest: T,
[...]
NAMED-OBJECT: id: NIL, tag: NIL, 
data: ((2 4) Q E S S)

(let ((rsb (make-rthm-seq-bar '((2 4) q e s s))))
  (force-rest-bar rsb)
  (print-simple rsb))

=>
(2 4): rest 2,

SYNOPSIS

(defmethod force-rest-bar ((rsb rthm-seq-bar))

rthm-seq-bar/get-beats [ Methods ]

[ Top ] [ rthm-seq-bar ] [ Methods ]

DESCRIPTION

 Try to organise the events of a bar into sublists of a beat's worth of
 events. 

 If beat is nil, we'll get the beat from the time-sig. If check-dur is T
 we'll make sure we get a complete beat of rhythms for each beat of the bar
 Since May 1 2012, check-dur can be T, NIL, #'warn or #'error, where t is
 the same as #'error. If you pass a symbol like 'silent the duration will be
 checked and NIL returned if we can't get an exact beat's worth of rthms.

ARGUMENTS

 - a rthm-seq-bar object

OPTIONAL ARGUMENTS

 - the beat, as a symbol or rhythm object (see above)
 - whether to check the duration of the beats to see if they're full (see
 above) 

RETURN VALUE

 A list of lists of event/rhythm objects

EXAMPLE

NB the elements returned will actually be rhythm objects but I'll just show the
rhythm symbol for clarity:  
(get-beats (make-rthm-seq-bar '((4 4) s x 4 q e e s e.)))
-->
((s s s s) (q) (e e) (s e.))

SYNOPSIS

(defmethod get-beats ((rsb rthm-seq-bar) &optional beat check-dur)

rthm-seq-bar/get-last-attack [ Methods ]

[ Top ] [ rthm-seq-bar ] [ Methods ]

DESCRIPTION

 Gets the rhythm object for the last note that needs an attack (i.e. not a
 rest and not a tied note) in a given rthm-seq-bar object.

ARGUMENTS

 - The given rthm-seq-bar object.

OPTIONAL ARGUMENTS

 - T or NIL indicating whether to print a warning message if the given index
   (minus one) is greater than the number of attacks in the RHYTHMS list 
   (default = T). This is a carry-over argument from the get-nth-attack
   method called within the get-last-attack method and not likely to be
   needed for use with get-last-attack.

RETURN VALUE

 A rhythm object.

 Returns NIL if the given index is higher than the highest possible index of
 attacks in the given rthm-seq-bar object.
 Get the rhythm object of the last 

EXAMPLE

(let ((rsb (make-rthm-seq-bar '((3 4) q+e (e) s (s) e))))
(get-last-attack rsb))

=>
RHYTHM: value: 8.0, duration: 0.5, rq: 1/2, is-rest: NIL, score-rthm: 8.0, 
undotted-value: 8, num-flags: 1, num-dots: 0, is-tied-to: NIL, 
is-tied-from: NIL, compound-duration: 0.5, 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: 8, 
tuplet-scaler: 1, grace-note-duration: 0.05,
LINKED-NAMED-OBJECT: previous: NIL
this: NIL
next: NIL
NAMED-OBJECT: id: E, tag: NIL, 
data: E

SYNOPSIS

(defmethod get-last-attack ((rsb rthm-seq-bar) &optional (warn t))

rthm-seq-bar/get-last-attacks [ Methods ]

[ Top ] [ rthm-seq-bar ] [ Methods ]

DATE

 July 24th 2015, Glenferness

DESCRIPTION

 Return the last nth attacks in a bar, with any notes tied from them.

ARGUMENTS

 - a rthm-seq-bar object
 - an integer indicating how many attacks to return

OPTIONAL ARGUMENTS

 - T or NIL to indicate whether a warning should be issued if the required
   number of attacks cannot be returned.

RETURN VALUE

 A list of lists of rhythm or event objects. The length of the outer list
 will be the same as the second argument. The sublists will contain the
 attack event with any subsequent events tied from it. NB if a request is
 made for more attacks than the bar contains the method returns NIL (rather
 than all the attacks in the bar).

SYNOPSIS

(defmethod get-last-attacks ((rsb rthm-seq-bar) how-many &optional (warn t))

rthm-seq-bar/get-last-event [ Methods ]

[ Top ] [ rthm-seq-bar ] [ Methods ]

DESCRIPTION

 Get the last event object (or rhythm object) of a given rthm-seq-bar
 object. 

ARGUMENTS

 - A rthm-seq-bar object.

RETURN VALUE

 Returns a rhythm object.

EXAMPLE

;; Returns a rhythm object.             ;
(let ((rsb (make-rthm-seq-bar '((2 4) s s e q))))
(get-last-event rsb))

=> 
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 get-last-event ((rsb rthm-seq-bar))

rthm-seq-bar/get-nth-attack [ Methods ]

[ Top ] [ rthm-seq-bar ] [ Methods ]

DESCRIPTION

 Gets the rhythm object for the nth note in a given rthm-seq-bar that needs
 an attack, i.e. not a rest and not tied. 

ARGUMENTS

 - The zero-based index number indicating which attack is sought.
 - The given rthm-seq-bar object in which to search.

OPTIONAL ARGUMENTS

 - T or NIL indicating whether to print a warning message if the given index
   is greater than the number of attacks in the RHYTHMS list (minus one to 
   compensate for the zero-based indexing) (default = T).   

RETURN VALUE

 A rhythm object.

 Returns NIL if the given index is higher than the highest possible index of
 attacks in the given rthm-seq-bar object.

EXAMPLE

;; The method returns a rhythm object when successful ; ;
(let ((rsb (make-rthm-seq-bar '((3 4) q+e (e) s (s) e))))
(get-nth-attack 0 rsb))

=> 
RHYTHM: value: 4.0, duration: 1.0, rq: 1, is-rest: NIL, score-rthm: 4.0, 
undotted-value: 4, num-flags: 0, num-dots: 0, is-tied-to: NIL, 
is-tied-from: NIL, compound-duration: 1.0, 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

(let ((rsb (make-rthm-seq-bar '((3 4) q+e (e) s (s) e))))
(data (get-nth-attack 1 rsb)))

=> S

(Let ((rsb (make-rthm-seq-bar '((3 4) q+e (e) s (s) e))))
(get-nth-attack 3 rsb))

=> NIL
WARNING: rthm-seq-bar::get-nth-attack:  index (3) < 0 or >= notes-needed (3)

(Let ((rsb (make-rthm-seq-bar '((3 4) q+e (e) s (s) e))))
(get-nth-attack 3 rsb nil))

=> NIL

SYNOPSIS

(defmethod get-nth-attack (index (rsb rthm-seq-bar) &optional (warn t))

rthm-seq-bar/get-nth-attack-with-tied [ Methods ]

[ Top ] [ rthm-seq-bar ] [ Methods ]

DATE

 July 24th 2015, Glenferness

DESCRIPTION

 Same as get-nth-attack method but will always return a list of the attacked
 event plus any following events this is tied to.

ARGUMENTS

 - The zero-based index number indicating which attack is sought.
 - The given rthm-seq-bar object in which to search.

OPTIONAL ARGUMENTS

 - T or NIL indicating whether to print a warning message if the given index
   is greater than the number of attacks in the RHYTHMS list (minus one to 
   compensate for the zero-based indexing) (default = T).   

RETURN VALUE

 A rhythm object.

 Returns NIL if the given index is higher than the highest possible index of
 attacks in the given rthm-seq-bar object.

SYNOPSIS

(defmethod get-nth-attack-with-tied (index (rsb rthm-seq-bar)
                                     &optional (warn t))

rthm-seq-bar/get-nth-event [ Methods ]

[ Top ] [ rthm-seq-bar ] [ Methods ]

DESCRIPTION

 Get the nth event (rhythm) in the given rthm-seq-bar object. This is a
 zero-based index.

 The method defaults to interrupting with an error if the n-value is greater
 than the number of items in the rthm-seq-bar. This can be disabled using
 the optional argument.

ARGUMENTS

 - A rthm-seq-bar object.
 - An index number.

OPTIONAL ARGUMENTS

 - T or NIL to indicate whether to interrupt and drop into the debugger with 
   an error. Default = T.

RETURN VALUE

 A rhythm object when successful. 

 Returns NIL when the specified index number is greater than the number of
 events in the rthm-seq-bar object. Also prints an error in this case by
 default, which can be suppressed by setting the optional argument to NIL.

EXAMPLE

;; Zero-based indexing. Returns a rhythm object when successful. ; ;
(let ((rsb (make-rthm-seq-bar '((2 4) q e s s))))
(get-nth-event 0 rsb))

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

;; Interrupts with an error and drops into the debugger by default if the ; ;
;; specified index number is greater than the number of events in the ; ;
;; rthm-seq-bar.                        ; ;
(let ((rsb (make-rthm-seq-bar '((2 4) q e s s))))
(get-nth-event 4 rsb))

=>
rthm-seq-bar::get-nth-event: Couldn't get event with index 4
[Condition of type SIMPLE-ERROR]

;; The error can be suppressed by setting the optional argument to NIL ; ;
(let ((rsb (make-rthm-seq-bar '((2 4) q e s s))))
(get-nth-event 4 rsb nil))

=> NIL

SYNOPSIS

(defmethod get-nth-event (index (rsb rthm-seq-bar)
                          &optional (error t))

rthm-seq-bar/get-nth-non-rest-rhythm [ Methods ]

[ Top ] [ rthm-seq-bar ] [ Methods ]

DESCRIPTION

 Get the nth non-rest rhythm object stored in the given rthm-seq-bar.  

ARGUMENTS

 - The zero-based index number indicating which non-rest-rhythm is sought.
 - The given rthm-seq-bar object in which to search.

OPTIONAL ARGUMENTS

 - T or NIL indicating whether to print an error message if the given index 
   is greater than the number of non-rest rhythms in the RHYTHMS list (minus 
   one to compensate for the zero-based indexing). (Default = T).  

RETURN VALUE

 A rhythm object.

 Returns NIL if the given index is higher than the highest possible index of
 non-rest rhythms in the given rthm-seq-bar object.

EXAMPLE

;; The method returns a rhythm object when successful ; ;
(let ((rsb (make-rthm-seq-bar '((2 4) e (e) s s (s) s))))
(get-nth-non-rest-rhythm 0 rsb))

=> 
RHYTHM: value: 8.0, duration: 0.5, rq: 1/2, is-rest: NIL, score-rthm: 8.0, 
undotted-value: 8, num-flags: 1, num-dots: 0, is-tied-to: NIL, 
is-tied-from: NIL, compound-duration: 0.5, 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: 8, 
tuplet-scaler: 1, grace-note-duration: 0.05,
LINKED-NAMED-OBJECT: previous: NIL
this: NIL
next: NIL
NAMED-OBJECT: id: E, tag: NIL, 
data: E

(let ((rsb (make-rthm-seq-bar '((2 4) e (e) s s (s) s))))
(data (get-nth-non-rest-rhythm 1 rsb)))

=> S

(let ((rsb (make-rthm-seq-bar '((2 4) e (e) s s (s) s))))
(data (get-nth-non-rest-rhythm 4 rsb)))

=>
Evaluation aborted on #<SIMPLE-ERROR>
rthm-seq-bar::get-nth-non-rest-rhythm: Couldn't get non-rest rhythm with index
4 for bar number -1 
[Condition of type SIMPLE-ERROR]

(let ((rsb (make-rthm-seq-bar '((2 4) e (e) s s (s) s))))
(get-nth-non-rest-rhythm 4 rsb nil))

=> NIL

SYNOPSIS

(defmethod get-nth-non-rest-rhythm (index (rsb rthm-seq-bar)
                                    &optional (error t))

rthm-seq-bar/get-nth-rest [ Methods ]

[ Top ] [ rthm-seq-bar ] [ Methods ]

DESCRIPTION

 Gets the rhythm object of the nth rest in a given rthm-seq-bar.

ARGUMENTS

 - The zero-based index number indicating which rest is sought.
 - The given rthm-seq-bar object in which to search.

OPTIONAL ARGUMENTS

 - T or NIL indicating whether to print an error message if the given index
   is greater than the number of rests in the RHYTHMS list (minus one to 
   compensate for the zero-based indexing) (default = T).    

RETURN VALUE

 A rhythm object.

 Returns NIL if the given index is higher than the highest possible index of
 rests in the given rthm-seq-bar object.

EXAMPLE

(let ((rsb (make-rthm-seq-bar '((3 4) e (e) s s (s) s (q)))))
(get-nth-rest 0 rsb))

=>
RHYTHM: value: 8.0, duration: 0.5, rq: 1/2, is-rest: T, score-rthm: 8.0, 
undotted-value: 8, num-flags: 1, num-dots: 0, is-tied-to: NIL, 
is-tied-from: NIL, compound-duration: 0.5, is-grace-note: NIL, 
needs-new-note: NIL, beam: NIL, bracket: NIL, rqq-note: NIL, 
rqq-info: NIL, marks: NIL, marks-in-part: NIL, letter-value: 8, 
tuplet-scaler: 1, grace-note-duration: 0.05,
LINKED-NAMED-OBJECT: previous: NIL
this: NIL
next: NIL
NAMED-OBJECT: id: E, tag: NIL, 
data: E

(let ((rsb (make-rthm-seq-bar '((3 4) e (e) s s (s) s (q)))))
(data (get-nth-rest 2 rsb)))

=> Q

(let ((rsb (make-rthm-seq-bar '((3 4) e (e) s s (s) s (q)))))
(get-nth-rest 3 rsb t))

Evaluation aborted on #<SIMPLE-ERROR>
rthm-seq-bar::get-nth-rest: Couldn't get rest with index 3
[Condition of type SIMPLE-ERROR]

(let ((rsb (make-rthm-seq-bar '((3 4) e (e) s s (s) s (q)))))
(get-nth-rest 3 rsb nil))

=> NIL

SYNOPSIS

(defmethod get-nth-rest (index (rsb rthm-seq-bar)
                         &optional (error t))

rthm-seq-bar/get-pitch-symbols [ Methods ]

[ Top ] [ rthm-seq-bar ] [ Methods ]

DESCRIPTION

 Return a list of the pitch symbols for the events in the bar.

ARGUMENTS

 - a rthm-seq-bar object

RETURN VALUE

 A list of pitch symbols 

EXAMPLE

(let ((mini
       (make-slippery-chicken
        '+mini+
        :ensemble '(((vn (violin :midi-channel 1))))
        :set-palette '((1 ((gs4 bf4 c4))))
        :set-map '((1 (1 1 1)))
        :rthm-seq-palette '((1 ((((4 4) e e e e e e e e))
                                :pitch-seq-palette ((1 2 1 2 1 1 3 1)))))
        :rthm-seq-map '((1 ((vn (1 1 1))))))))
  (get-pitch-symbols (get-bar mini 1 'vn)))
  =>
  (C4 GS4 C4 GS4 C4 C4 BF4 C4)

SYNOPSIS

(defmethod get-pitch-symbols ((rsb rthm-seq-bar) &optional written)

rthm-seq-bar/get-rhythm-symbols [ Methods ]

[ Top ] [ rthm-seq-bar ] [ Methods ]

DATE

 01-May-2012

DESCRIPTION

 Return the rhythms of a given rthm-seq-bar object as a list of rhythm
 symbols. 

ARGUMENTS

 - A rthm-seq-bar object.

RETURN VALUE

 - A list of rhythm symbols.

EXAMPLE

  (let ((rsb (make-rthm-seq-bar '((4 4) q e s s q. e))))
(get-rhythm-symbols rsb))

  => (Q E S S Q. E)

SYNOPSIS

(defmethod get-rhythm-symbols ((rsb rthm-seq-bar))

rthm-seq-bar/get-time-sig [ Methods ]

[ Top ] [ rthm-seq-bar ] [ Methods ]

DESCRIPTION

 Return the time-sig object for the given rthm-seq-bar object.

ARGUMENTS

 - A rthm-seq-bar object.

RETURN VALUE

 A time-sig object.

EXAMPLE

(let ((rsb (make-rthm-seq-bar '((2 4) q e s s))))
  (get-time-sig rsb))
=> 
TIME-SIG: num: 2, denom: 4, duration: 2.0, compound: NIL, midi-clocks: 24, 
num-beats: 2 
SCLIST: sclist-length: 2, bounds-alert: T, copy: T
LINKED-NAMED-OBJECT: previous: NIL, this: NIL, next: NIL
NAMED-OBJECT: id: "0204", tag: NIL, 
data: (2 4)

SYNOPSIS

(defmethod get-time-sig ((rsb rthm-seq-bar) &optional ignore)

rthm-seq-bar/get-time-sig-as-list [ Methods ]

[ Top ] [ rthm-seq-bar ] [ Methods ]

DESCRIPTION

 Get the time signature for a given rthm-seq-bar object in list form.

ARGUMENTS

 - A rthm-seq-bar object.

RETURN VALUE

 A list.

EXAMPLE

(let ((rsb (make-rthm-seq-bar '((2 4) q e s s))))
  (get-time-sig-as-list rsb))
=> (2 4)

SYNOPSIS

(defmethod get-time-sig-as-list ((rsb rthm-seq-bar))

rthm-seq-bar/make-rest-bar [ Functions ]

[ Top ] [ rthm-seq-bar ] [ Functions ]

DESCRIPTION

 Make a rthm-seq-bar object that consists of a bar of rest.

ARGUMENTS

 - The time signature of the rthm-seq-bar object to be made, as a quoted
   list.

OPTIONAL ARGUMENTS

 - T or NIL to indicate whether to print the time signature in score output.
 - show-rest. This argument indicates whether or not to print the rest in
   the printed score output (CMN/LilyPond). Default = T.
 
 The remaining optional arguments are set internally by the 
 slippery-chicken class, but can be read by the user for debugging.
 - missing-duration: Indicates whether the bar is missing a duration. 
 - player-section-ref: The current player and section of the given
   rthm-seq-bar object.
 - nth-seq: The current sequenz (with a "z") of the given rthm-seq-bar
   object.  
 - nth-bar: The current bar number of the given rthm-seq-bar object. 

RETURN VALUE

 A rthm-seq-bar object.

EXAMPLE

  (let ((rsb-rb (make-rest-bar '(2 4) nil t)))
(format t "~%time-sig: ~a~%is-rest-bar: ~a~%write-time-sig: ~
             ~a~%show-rest: ~a~%"
(data (get-time-sig rsb-rb))
(is-rest-bar rsb-rb)
(write-time-sig rsb-rb)
(show-rest rsb-rb))
(print-simple rsb-rb)
rsb-rb)

  =>
  RTHM-SEQ-BAR: time-sig: 0 (2 4), time-sig-given: T, bar-num: -1, 
  [...]

  time-sig: (2 4)
  is-rest-bar: T
  write-time-sig: NIL
  show-rest: T
  (2 4): rest 2,

SYNOPSIS

(defun make-rest-bar (time-sig &optional
                                 write-time-sig
                                 (show-rest t)
                                 missing-duration
                                 player-section-ref nth-seq
                                 nth-bar)

rthm-seq-bar/make-rthm-seq-bar [ Functions ]

[ Top ] [ rthm-seq-bar ] [ Functions ]

DESCRIPTION

 Public interface for creating a rthm-seq-bar object, each instance of which
 which holds one of the individual bars that reside in a rhythmic
 sequence. 

 This class is responsible for parsing lists containing rhythms and time
 signatures, but not for parsing these things themselves--that is done by
 separate classes.  

 A { followed by a number means that all the notes from now to the } will be
 enclosed in a bracket with the number inside.  This may be nested.  A -
 indicates beaming: the first - indicates the start of a beam, the second
 the end of that beam.

ARGUMENTS

 - A list of rhythmic durations, which may include ties and dots. Durations
   may be written as numeric (integer) values or may use the CM/CMN/SCORE 
   alphabetic shorthand s=16, e=8, q=4, h=2, w=1. NB: Repeating rhythms can
   be indicated using a shorthand notation consisting of a multiplication
   symbol ('x'), e.g.: (make-rthm-seq-bar '((4 4) s x 16)).

 make-rthm-seq-bar requires a time signature. If no time signature is
 provided, the most recently defined time signature will be used. If one is
 provided, it must be included as the first element of the data list. The
 time signature is formulated as a list containing two integers, the first
 being the number of beats in the bar and the second being the beat unit for
 the bar.

OPTIONAL ARGUMENTS

 - A name (symbol) for the object ID.

RETURN VALUE

 Returns a rthm-seq-bar.

EXAMPLE

  (make-rthm-seq-bar '((2 4) q e s s))

  => 
  RTHM-SEQ-BAR:
  [...]
  NAMED-OBJECT: id: NIL, tag: NIL, 
  data: ((2 4) Q E S S)

  (make-rthm-seq-bar '((2 4) q e s s) 'test)
  => 
  RTHM-SEQ-BAR:
  [...]
  NAMED-OBJECT: id: TEST, tag: NIL, 
  data: ((2 4) Q E S S)

  (make-rthm-seq-bar '((2 4) q \+16\.+32 e))
  => 
  RTHM-SEQ-BAR:
  [...]
  NAMED-OBJECT: id: NIL, tag: NIL, 
  data: ((2 4) Q +16.+32 E)

  (make-rthm-seq-bar '((2 4) { 3 te te te } q)) 
  => 
  RTHM-SEQ-BAR:
  [...]
  NAMED-OBJECT: id: NIL, tag: NIL, 
  data: ((2 4) { 3 TE TE TE } Q)

SYNOPSIS

(defun make-rthm-seq-bar (rhythms &optional name)

rthm-seq-bar/remove-dynamics [ Methods ]

[ Top ] [ rthm-seq-bar ] [ Methods ]

DATE

 June 13th

DESCRIPTION

 remove all dynamics attached to events in the bar

ARGUMENTS

 - a rthm-seq-bar object

OPTIONAL ARGUMENTS

 - T or NIL to remove hairpin marks too (e.g. cresc-beg). Default = NIL.

RETURN VALUE

 T

SYNOPSIS

(defmethod remove-dynamics ((rsb rthm-seq-bar) &optional hairpins)

rthm-seq-bar/remove-rhythms [ Methods ]

[ Top ] [ rthm-seq-bar ] [ Methods ]

DATE

 February 8th 2017

DESCRIPTION

 remove a specified number of rhythms/events from a rthm-seq-bar object.

ARGUMENTS

 - the rthm-seq-bar object
 - the rhythm/event to start removing at (1-based)
 - how many rhythms/events to remove

OPTIONAL ARGUMENTS

 - T or NIL to indicate whether the tuplets slot of the rthm-seq-bar should
   be updated to reflect changes. Default = T.
 - T or NIL to indicated whether the bracket slot of the starting
   rhythm/event should take the value of the last rhythm/event removed

RETURN VALUE

 the list of rhythm/event objects from the rhythms slot of the rthm-seq-bar

SYNOPSIS

(defmethod remove-rhythms ((rsb rthm-seq-bar) start how-many
                           &optional (update-tuplets t)
                             (inherit-last-tuplet t))

rthm-seq-bar/replace-rhythms [ Methods ]

[ Top ] [ rthm-seq-bar ] [ Methods ]

DATE

 February 16th 2017, Edinburgh

DESCRIPTION

 Replace the rhythms/events in a rthm-seq-bar object, with an option to
 automatically beam the result. The bar is checked to make sure it is full
 after replacing and an error will be issued if it is not.

ARGUMENTS

 - a rthm-seq-bar object
 - the index (1-based) of the rhythm/events to start at (integer)
 - the number of rhythms/events to replace (integer)
 - a list of the new rhythm/event objects

OPTIONAL ARGUMENTS

 T or NIL to indicate whether the automatic beaming routine should be called
 after the replacement

RETURN VALUE

 What the is-full method returns: two values: T or NIL to indicate whether
 the bar is full, and the difference between the duration of the time
 signature and the rhythms (usually a small floating-point error difference)

SYNOPSIS

(defmethod replace-rhythms ((rsb rthm-seq-bar) start-rhythm replace-num-rhythms
                            new-rhythms &optional auto-beam)

rthm-seq-bar/reset-8va [ Methods ]

[ Top ] [ rthm-seq-bar ] [ Methods ]

DATE

 22 Sep 2011 

DESCRIPTION

 Reset the 8VA slots of all event objects within a given rthm-seq-object to
 0 (no ottava/ottava bassa transposition).

ARGUMENTS

 - A rthm-seq-bar object

RETURN VALUE

 Always returns NIL.

EXAMPLE

;; Create a rthm-seq-bar object consisting of event objects, print the default ; ; ; ; ; ;
;; value of the 8VA slots for those events. Set the 8VA slots to 1 and print ; ; ; ; ; ;
;; the value of those slots to see the change. Apply the reset-8va method to ; ; ; ; ; ;
;; remove any values and reset the slots to NIL, and print the results. ; ; ; ; ; ;

  (let ((rsb (make-rthm-seq-bar 
(list
'(3 8) 
(make-event 'cs4 'e)
(make-event 'cs4 'e)
(make-event 'cs4 'e)))))
(print (loop for e in (rhythms rsb) collect (8va e)))
(set-8va rsb 1)
(print (loop for e in (rhythms rsb) collect (8va e)))
(reset-8va rsb)
(print (loop for e in (rhythms rsb) collect (8va e))))

  =>
  (0 0 0) 
  (1 1 1) 
  (0 0 0)

SYNOPSIS

(defmethod reset-8va ((rsb rthm-seq-bar))

rthm-seq-bar/respell-bar [ Methods ]

[ Top ] [ rthm-seq-bar ] [ Methods ]

DESCRIPTION

 Scan the specified rthm-seq-bar object for enharmonically equivalent
 pitches and unify their spelling.  This method won't generally be called by
 the user directly, rather, it's called by the respell-bars method in the
 slippery-chicken class.  
 
 Clearly, this method will not work if the rthm-seq-bar only contains rhythm
 objects: it's made to be called when these have been promoted to event
 objects during the initialization of a slippery-chicken object.
 
 NB: Although this method focuses on just one rthm-seq-bar object, the
     parent slippery-chicken object and player ID are needed in order to
     determine ties that may exist into the next bar from the present bar. 

 NB: The slippery-chicken class version of the method of this name uses
     pitches from previous bars as well when respelling a given rthm-seq-bar
     object, so different results are normal. Users should generally call
     the slippery-chicken method rather than calling this one directly on
     individual bars.

ARGUMENTS

 - A rthm-seq-bar object.
 - A slippery-chicken object.
 - A player ID (symbol).

OPTIONAL ARGUMENTS

 - T or NIL to indicate whether to process only written or only sounding
   pitches. T = only written. Default = NIL. 
 - The last attack (event object) of the previous bar. This is usually
   supplied by the calling method. Default = NIL.

RETURN VALUE

 Returns the rthm-seq-bar object it was passed.

EXAMPLE

;;; Create a slippery-chicken object using pitches GS4 and AF4, print the ; ; ; ; ; ;
;;; pitches of a specified bar within that object. Apply respell-bar and print ; ; ; ; ; ;
;;; the same pitches again to see the difference. ; ; ; ; ; ;

  (let ((mini
(make-slippery-chicken
'+mini+
:ensemble '(((vn (violin :midi-channel 1))))
:set-palette '((1 ((gs4 af4 bf4))))
:set-map '((1 (1 1 1)))
:rthm-seq-palette '((1 ((((4 4) e e e e e e e e))
:pitch-seq-palette ((1 2 1 1 1 1 1 1)))))
:rthm-seq-map '((1 ((vn (1 1 1))))))))
(print (loop for r in (rhythms (get-bar mini 2 'vn))
collect (get-pitch-symbol r)))
(respell-bar (get-bar mini 2 'vn) mini 'vn)
(print (loop for r in (rhythms (get-bar mini 2 'vn))
collect (get-pitch-symbol r))))
  =>
  (GS4 AF4 GS4 GS4 GS4 GS4 GS4 GS4) 
  (GS4 GS4 GS4 GS4 GS4 GS4 GS4 GS4)

SYNOPSIS

(defmethod respell-bar ((rsb rthm-seq-bar) sc player 
                        &optional written last-attack-previous-bar)

rthm-seq-bar/scale [ Methods ]

[ Top ] [ rthm-seq-bar ] [ Methods ]

DESCRIPTION

 Change the values of a rthm-seq-bar objects rhythm durations by a specified
 scaling factor.

 This method always returns a new rthm-seq-bar object, recreating scaled
 rhythms with beams etc. where appropriate. See time-sig::scale for details
 on how the new meter is created.

ARGUMENTS

 - A rthm-seq-bar object.
 - A number that is the scaling factor.

OPTIONAL ARGUMENTS

 - T or NIL to indicate whether to preserve the original meter (duple,
   triple, quadruple etc.)
 - (two ignore arguments for internal use only)

RETURN VALUE

 Returns a rthm-seq-bar object

EXAMPLE

;;; Create a rthm-seq-bar object and scale its durations by a fact of ; ;
;;; 2. Returns a rthm-seq-bar object.   ; ;
(let ((rsb (make-rthm-seq-bar '((2 4) q e s s))))
(scale rsb 2))

=> 
RTHM-SEQ-BAR: time-sig: 19 (2 2), time-sig-given: T, bar-num: -1, 
[...]
RHYTHM: value: 2.000, duration: 2.000, rq: 2, is-rest: NIL, 
[...]
data: H
[...]
RHYTHM: value: 4.000, duration: 1.000, rq: 1, is-rest: NIL, 
[...]
data: Q
[...]
RHYTHM: value: 8.000, duration: 0.500, rq: 1/2, is-rest: NIL, 
[...]
data: E
[...]
RHYTHM: value: 8.000, duration: 0.500, rq: 1/2, is-rest: NIL, 
[...]
data: E
[...]

;;; Use the print-simple method to see formatted results ;
(let ((rsb (make-rthm-seq-bar '((2 4) q e s s))))
(print-simple (scale rsb .5)))

=>
(2 8): note E, note S, note 32, note 32,

;;; Set the optional <preserve-meter> argument to NIL to allow the method to ;
;;; return results in a different metric quality (this returns a quadruple ;
;;; meter rather than a duple)          ;
(let ((rsb (make-rthm-seq-bar '((6 8) q e q s s))))
(print-simple (scale rsb 2 nil)))

=>
(12 8): note H, note Q, note H, note E, note E,

SYNOPSIS

(defmethod scale ((rsb rthm-seq-bar) scaler
                  &optional (preserve-meter t) ignore1 ignore2)

rthm-seq-bar/set-8va [ Methods ]

[ Top ] [ rthm-seq-bar ] [ Methods ]

DATE

 23-Sep-2011 

DESCRIPTION

 Set the 8VA (ottava) slots of the event objects within a given rthm-seq-bar 
 object. This number can be positive or negative. Only the values 1, 0 and
 -1 are valid for the number of octaves to be transposed.

ARGUMENTS

 - A rthm-seq-bar object.
 - A number indicating the number of octaves to be transposed in either
   direction (ottava/ottava bassa). 

RETURN VALUE

 Always returns NIL.

EXAMPLE

;; The method returns NIL               ; ; ; ; ;

  (let ((rsb (make-rthm-seq-bar 
(list
'(3 8) 
(make-event 'cs4 'e)
(make-event 'cs4 'e)
(make-event 'cs4 'e)))))
(set-8va rsb 1))

  => NIL

;; Create a rthm-seq-bar object with event objects, set the 8va slot to 1, and ; ; ; ; ;
;; access and print it to see it's new value. ; ; ; ; ;

  (let ((rsb (make-rthm-seq-bar 
(list
'(3 8) 
(make-event 'cs4 'e)
(make-event 'cs4 'e)
(make-event 'cs4 'e)))))
(set-8va rsb 1)
(loop for e in (rhythms rsb) collect (8va e)))

  => (1 1 1)

SYNOPSIS

(defmethod set-8va ((rsb rthm-seq-bar) 8va)

rthm-seq-bar/set-amplitudes [ Methods ]

[ Top ] [ rthm-seq-bar ] [ Methods ]

DESCRIPTION

 Add a specified amplitude (between 0.0 and 1.0) to all non-rest event
 objects in a specified rthm-seq-bar object.

ARGUMENTS

 - A rthm-seq-bar object.
 - A number that is an amplitude value between 0.0 and 1.0.

RETURN VALUE

 Returns the amplitude value set.

EXAMPLE

  (let* ((mini
(make-slippery-chicken
'+sc-object+
:ensemble '(((va (viola :midi-channel 2))))
:set-palette '((1 ((c3 d3 e3 f3 g3 a3 b3 c4))))
:set-map '((1 (1 1 1)))
:rthm-seq-palette '((1 ((((4 4) e (e) e (e) (e) e e e))
:pitch-seq-palette ((1 2 3 4 5)))))
:rthm-seq-map '((1 ((va (1 1 1))))))))
(set-amplitudes (get-bar mini 2 'va) 0.9)
(cmn-display mini))

SYNOPSIS

(defmethod set-amplitudes ((rsb rthm-seq-bar) amp)

rthm-seq-bar/set-dynamics [ Methods ]

[ Top ] [ rthm-seq-bar ] [ Methods ]

DESCRIPTION

 Add a specified dynamic mark to all attacked event objects (i.e. not rests
 and not notes that are tied to) in a specified rthm-seq-bar-object. This
 method was created mainly to make it easy to set amplitudes for a range of
 notes (e.g. with map-over-bars), so that they are, for example, reflected
 in MIDI velocities.  If used over many notes the score will probably then be
 littered with extraneous dynamic marks.  These can then be removed, if so
 desired, with the slippery-chicken class remove-extraneous-dynamics method.

ARGUMENTS

 - A rthm-seq-bar object.
 - A dynamic mark.

RETURN VALUE

 The specified dynamic mark

EXAMPLE

  (let* ((mini
(make-slippery-chicken
'+sc-object+
:ensemble '(((va (viola :midi-channel 2))))
:set-palette '((1 ((c3 d3 e3 f3 g3 a3 b3 c4))))
:set-map '((1 (1 1 1)))
:rthm-seq-palette '((1 ((((4 4) e (e) e (e) (e) e e e))
:pitch-seq-palette ((1 2 3 4 5)))))
:rthm-seq-map '((1 ((va (1 1 1))))))))
(set-dynamics (get-bar mini 2 'va) 'ppp))

  => PPP

SYNOPSIS

(defmethod set-dynamics ((rsb rthm-seq-bar) dynamic)

rthm-seq-bar/set-midi-channel [ Methods ]

[ Top ] [ rthm-seq-bar ] [ Methods ]

DESCRIPTION

 Set the MIDI-channel and microtonal MIDI-channel for the pitch object
 of an event object within a given rthm-seq-bar object. Sets the
 MIDI-CHANNEL slot of all event objects contained in the rthm-seq-bar object
 to the same channel.

ARGUMENTS

 - A rthm-seq-bar object.
 - A whole number indicating the MIDI channel to be used for the
   equal-tempered pitch material of the given rthm-seq-bar object. 
 - A whole number indicating the MIDI channel to be used for microtonal
   pitch material of the given rthm-seq-bar object. 

RETURN VALUE

 Always returns NIL.

EXAMPLE

;; Create a rthm-seq-bar using event objects and check the MIDI-CHANNEL slots ; ; ; ; ; ;
;; of those event objects to see that they are NIL by default. ; ; ; ; ; ;
  (let ((rsb (make-rthm-seq-bar 
(list
'(3 8) 
(make-event 'cs4 'e)
(make-event 'cs4 'e)
(make-event 'cs4 'e)))))
(loop for p in (rhythms rsb)
collect (midi-channel (pitch-or-chord p))))

  => (NIL NIL NIL)

;; Apply the set-midi-channel method to the rthm-seq-bar object and read and ; ; ; ; ; ;
;; print the MIDI-CHANNEL slots of each of the individual events to see that ; ; ; ; ; ;
;; they've been set.                    ; ; ; ; ; ;
  (let ((rsb (make-rthm-seq-bar 
(list
'(3 8) 
(make-event 'cs4 'e)
(make-event 'cs4 'e)
(make-event 'cs4 'e)))))
(set-midi-channel rsb 13 14)
(loop for p in (rhythms rsb)
collect (midi-channel (pitch-or-chord p))))

  => (13 13 13)

SYNOPSIS

(defmethod set-midi-channel ((rsb rthm-seq-bar) midi-channel
                             &optional microtonal-midi-channel)

rthm-seq-bar/set-nth-attack [ Methods ]

[ Top ] [ rthm-seq-bar ] [ Methods ]

DESCRIPTION

 Sets the value of the nth rhythm object of a given rthm-seq-bar that needs
 an attack; i.e., not a rest and not a tied note.

 NB: This method does not check to ensure that the resulting rthm-seq-bar
 contains the right number of beats.

ARGUMENTS

 - A zero-based index number for the attacked note to change.
 - An event.
 - A rthm-seq-bar object.

OPTIONAL ARGUMENTS

 - T or NIL indicating whether to print a warning message if the given index
   (minus one) is greater than the number of attacks in the RHYTHMS
   list. Default = T.    

RETURN VALUE

 An event object.

EXAMPLE

(let ((rsb (make-rthm-seq-bar '((2 4) q+e s s))))
(set-nth-attack 1 (make-event 'e4 'q) rsb))

=>
EVENT: start-time: NIL, end-time: NIL, 
[...]
PITCH: frequency: 329.6275526703903d0, midi-note: 64, midi-channel: NIL 
[...]
NAMED-OBJECT: id: E4, tag: NIL, 
data: E4
[...]
RHYTHM: value: 4.0, duration: 1.0, rq: 1, is-rest: NIL, score-rthm: 4.0, 
[...]
NAMED-OBJECT: id: Q, tag: NIL, 
data: Q

(let ((rsb (make-rthm-seq-bar '((2 4) q+e s s))))
(set-nth-attack 2 (make-event 'e4 'q) rsb)
(loop for r in (rhythms rsb) collect (data r)))

=> ("Q" "E" S Q)

(let ((rsb (make-rthm-seq-bar '((2 4) q+e s s))))
(set-nth-attack 3 (make-event 'e4 'q) rsb))

=> NIL
rthm-seq-bar::set-nth-attack: index (3) < 0 or >= notes-needed (3)

(let ((rsb (make-rthm-seq-bar '((2 4) q+e s s))))
(set-nth-attack 3 (make-event 'e4 'q) rsb nil))

=> NIL

SYNOPSIS

(defmethod set-nth-attack (index (e event) (rsb rthm-seq-bar) 
                           &optional (warn t))

rthm-seq-bar/set-written [ Methods ]

[ Top ] [ rthm-seq-bar ] [ Methods ]

DATE

 20 Jul 2011 (Pula)

DESCRIPTION

 Set the written pitch (as opposed to sounding; i.e., for transposing
 instruments) of an event object within a given rthm-seq-bar object. The
 sounding pitch remains unchanged as a pitch object in the PITCH-OR-CHORD
 slot, while the written pitch is added as a pitch object to the
 WRITTEN-PITCH-OR-CHORD slot. 

ARGUMENTS

 - A rthm-seq-bar-object
 - A number (positive or negative) indicating the transposition by
   semitones.  See this method in the event class for more information and
   examples.  

RETURN VALUE

 Always returns T.

EXAMPLE

;; The method returns NIL               ; ; ; ; ;
  (let ((rsb (make-rthm-seq-bar 
(list
'(3 8) 
(make-event 'cs4 'e)
(make-event 'cs4 'e)
(make-event 'cs4 'e)))))
(set-written rsb -2))

  => T

;; Set the written pitch transposition to 2 semitones lower, then check the ; ; ; ; ;
;; data of the WRITTEN-PITCH-OR-CHORD slot of each event to see the ; ; ; ; ;
;; corresponding pitches                ; ; ; ; ;
  (let ((rsb (make-rthm-seq-bar 
(list
'(3 8) 
(make-event 'cs4 'e)
(make-event 'cs4 'e)
(make-event 'cs4 'e)))))
(set-written rsb -2)
(loop for p in (rhythms rsb)
collect (get-pitch-symbol p)))

  => (B3 B3 B3)

SYNOPSIS

(defmethod set-written ((rsb rthm-seq-bar) transposition)

rthm-seq-bar/split [ Methods ]

[ Top ] [ rthm-seq-bar ] [ Methods ]

DATE

 27 Jan 2011

DESCRIPTION

 Splits a given rthm-seq-bar into multiple smaller rthm-seq-bar
 objects. This will only work if the given rthm-seq-bar object can be split
 into whole beats; e.g. a 4/4 bar will not be split into 5/8 + 3/8. 

 The keyword arguments :min-beats and :max-beats serve as guidelines rather
 than strict cut-offs. In some cases, the method may only be able to
 effectively split the given rthm-seq-bar by dividing it into segments that
 exceed the length stipulated by these arguments (see example below). 

 Depending on the min-beats/max-beats arguments stipulated by the user or
 the rhythmic structure of the given rthm-seq-bar object, the given
 rthm-seq-bar may not be splittable, in which case NIL is returned. If the
 keyword argument :warn is set to T, a warning will be also be printed in
 such cases.

 NB The method does not copy over and update bar start-times (this is meant
 to be done at the rthm-seq stage, not once the whole piece has been
 generated). 

ARGUMENTS

 - A rthm-seq-bar object.

OPTIONAL ARGUMENTS

 keyword arguments:
 - :min-beats. This argument takes an integer value to indicate the minimum
   number of beats in any of the new rthm-seq-bar objects created. This
   serves as a guideline only and may occasionally be exceeded in value by
   the method. Default value = 2.
 - :max-beats. This argument takes an integer value to indicate the maximum
   number of beats in any of the new rthm-seq-bar objects created. This
   serves as a guideline only and may occasionally be exceeded in value by
   the method. Default value = 5.
 - :warn. Indicates whether to print a warning if the rthm-seq-bar object is
   unsplittable. Value T = print a warning. Defaults to NIL.

RETURN VALUE

 Returns a list of rthm-seq-bar objects if successful, NIL if not. 

EXAMPLE

  (let* ((rsb (make-rthm-seq-bar '((7 4) h. e e +e. e. e q)))
(rsb-splt (split rsb)))
(loop for i in rsb-splt collect
(loop for r in (rhythms i) collect (data r))))

  => ((H.) (E E "E." E. E Q))

  (let* ((rsb (make-rthm-seq-bar '((7 4) h. e e +e. e. e q)))
(rsb-splt (split rsb)))
(loop for i in rsb-splt do (print-simple i)))

  =>
  (3 4): note H., 
  (4 4): note E, note E, note E., note E., note E, note Q,

  (let* ((rsb (make-rthm-seq-bar '((7 4) h. e e +e. e. e q)))
(rsb-splt (split rsb :min-beats 1 :max-beats 3)))
(loop for i in rsb-splt do (print-simple i)))

  =>
  (3 4): note H., 
  (1 4): note E, note E, 
  (2 4): note E., note E., note E, 
  (1 4): note Q, 

  (let ((rsb (make-rthm-seq-bar '((7 4) h. e e +e. e. e q))))
(split rsb :max-beats 1 :warn t))

  => NIL
  WARNING: rthm-seq-bar::split: couldn't split bar:

SYNOPSIS

(defmethod split ((rsb rthm-seq-bar) &key
                                       (min-beats 2) (max-beats 5) warn ignore)

rthm-seq-bar/time-sig-equal [ Methods ]

[ Top ] [ rthm-seq-bar ] [ Methods ]

DESCRIPTION

 Check to see if two given rthm-seq-bar objects have the same time signature.

ARGUMENTS

 - Two rthm-seq-bar objects.

RETURN VALUE

 T if the given rthm-seq-bar objects have the same time signature.
 NIL if the given rthm-seq-bar objects have different times signatures.

EXAMPLE

(let ((rsb1 (make-rthm-seq-bar '((2 4) q e s s)))
      (rsb2 (make-rthm-seq-bar '((2 4) s s e q))))
  (time-sig-equal rsb1 rsb2))

=> T

(let ((rsb1 (make-rthm-seq-bar '((2 4) q e s s)))
      (rsb2 (make-rthm-seq-bar '((3 4) q+e e s s s s))))
  (time-sig-equal rsb1 rsb2))
=> NIL

SYNOPSIS

(defmethod time-sig-equal ((rsb1 rthm-seq-bar) (rsb2 rthm-seq-bar))

rthm-seq-bar/transpose [ Methods ]

[ Top ] [ rthm-seq-bar ] [ Methods ]

DESCRIPTION

 Transpose the pitches of event objects stored in a rthm-seq-bar object by a
 specified number of semitones (positive for up, negative for down).

ARGUMENTS

 - A rthm-seq-bar object.
 - A whole number (positive or negative).

OPTIONAL ARGUMENTS

 keyword arguments:
 - :destructively. Set to T or NIL to indicate whether the slot values of
   the original rthm-seq-bar object should be changed or not (even though
   the method always returns a clone). T = change the originals. 
   Default = NIL.
 - :chord-function. A function to be used for the transposition of
   chords. Default = #'transpose.
 - :pitch-function. A function to be used for the transposition of
   pitches. Default = #'transpose.

RETURN VALUE

 This method returns a clone of the rthm-seq-bar object whether the keyword
 argument :destructively is set to T or NIL. It does change the
 corresponding slot values of the original when set to T even though it
 returns the clone.

EXAMPLE

;; Create a rthm-seq-bar object using make-event, transpose the contained 
;; pitches destructively, and read the values of the corresponding slots to see 
;; the change.
(let ((rsb (make-rthm-seq-bar 
            (list 
             '(3 8) 
             (make-event 'cs4 'e)
             (make-event 'cs4 'e)
             (make-event 'cs4 'e)))))
  (transpose rsb 3 :destructively t)
  (loop for p in (rhythms rsb)
     collect (data (pitch-or-chord p))))

=> (E4 E4 E4)

;; Do the same thing without the :destructively keyword being set to T 
(let ((rsb (make-rthm-seq-bar 
            (list
             '(3 8) 
             (make-event 'cs4 'e)
             (make-event 'cs4 'e)
             (make-event 'cs4 'e)))))
  (transpose rsb 3)
  (loop for p in (rhythms rsb)
     collect (data (pitch-or-chord p))))

=> (CS4 CS4 CS4)

SYNOPSIS

(defmethod transpose ((rsb rthm-seq-bar) semitones
                      &key
                      ;; when t, then the events will be replaced by the
                      ;; transposition.  
                      (destructively nil)
                      ;; the default functions are the class methods for pitch
                      ;; or chord.
                      (chord-function #'transpose)
                      (pitch-function #'transpose))

sclist/rthm-seq-bar [ Classes ]

[ Top ] [ sclist ] [ Classes ]

NAME

 rthm-seq-bar

 File:             rthm-seq-bar.lsp

 Class Hierarchy:  named-object -> linked-named-object -> sclist -> 
                   rthm-seq-bar 

 Version:          1.0.10

 Project:          slippery chicken (algorithmic composition)

 Purpose:          Implementation of the rthm-seq-bar class, objects of
                   which make up the individual bars that reside in a
                   rhythmic sequence.  This class is responsible for parsing
                   lists containing rhythms and time signatures (but not
                   parsing these things themselves--that is done by separate
                   classes).

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

 Creation date:    13th February 2001

 $$ Last modified:  18:22:06 Mon Sep 30 2019 CEST

 SVN ID: $Id$