./../../src/rthm-seq-bar.lsp

## 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 argument can be set to T or NIL. If T, the method will
       make sure there is a complete beat of rhythms for each beat of the bar.
       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. 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.
     - :on-fail. The function that should be applied when the check does not
       pass. 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
                            (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.

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 sure make sure that an exact
       beat's worth of rhythms is handled. T = check durations. Default = NIL.

RETURN VALUE

     A 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.

RETURN VALUE

     A list of rhythm/event objects.

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)

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

     Returns a list of event/rhythm objects.

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

     NIL

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/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 discarded. If 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.

     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.

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-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-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-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-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.
     - T or NIL instruction on whether to print the time signature in score
       output.

OPTIONAL ARGUMENTS

     - 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 write-time-sig &optional
                                                  (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/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
                                 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 3)
      (loop for p in (rhythms rsb)
         collect (data (pitch-or-chord p))))

    => (EF4 EF4 EF4)

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

    => (C4 C4 C4)

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.0

     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: 16:22:11 Thu Dec  6 2012 GMT

     SVN ID: $Id: rthm-seq-bar.lsp 3156 2012-12-06 16:22:58Z medward2 $