./../../src/piece.lsp

## bar-holder/piece [ Classes ]

[ Top ] [ bar-holder ] [ Classes ]

NAME

     piece

     File:             piece.lsp

     Class Hierarchy:  named-object -> linked-named-object -> sclist ->
                       circular-sclist -> assoc-list -> recursive-assoc-list ->
                       piece
                                       AND

                       named-object -> linked-named-object -> bar-holder ->
                       piece

     Version:          1.0.12

     Project:          slippery chicken (algorithmic composition)

     Purpose:          Implementation of the piece class which holds all the
                       note information for a whole piece in the form of
                       sections (possibly subsections), which then contain
                       player-sections, sequenzes and rthm-seq-bars.

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

     Creation date:    16th February 2002

     $$ Last modified:  16:24:47 Wed Dec 30 2020 CET

     SVN ID: $Id$

## piece/delete-sequenzes [ Methods ]

[ Top ] [ piece ] [ Methods ]

DESCRIPTION

     Delete one or more consecutive sequenz objects from a given piece object by
     specifying any bar number within the first sequenz object to be deleted.

     This method deletes the whole sequenz object which contains the bar with a
     given number.

     NB: This method only deletes the sequenz object for the specified player,
         so the remaining players will have a different structure, making MIDI
         or printable output impossible. The user must be sure that each section
         has the same number of sequenzes of identical time-signature structure
         in each section.

     NB: The user must call the update-slots method to ensure that changes to
         the NUM-BARS slot etc. are reflected in the given slippery-chicken
         object.

ARGUMENTS

     - A piece object.
     - An integer that is the number of the bar for which the containing sequenz
       is to be deleted.
     - The ID of the player from whose part the sequenz is to be deleted.

OPTIONAL ARGUMENTS

     - An integer that is the number of consecutive sequenz objects to delete,
       including the first sequenz indicated by the <bar-num> argument.
       Default = 1.

RETURN VALUE

     Returns T.

EXAMPLE

    ;;; Print the number of sequenz objects contained in section 2 of each player's
    ;;; part, delete two sequenz objects from each part in that section, and print
    ;;; the number of sequenz objects again to see the difference. Update the slots
    ;;; and call cmn-display for printable output.
    (let ((mini
           (make-slippery-chicken
            '+mini+
            :ensemble '(((hn (french-horn :midi-channel 1))
                         (vc (cello :midi-channel 2))))
            :set-palette '((1 ((f3 g3 a3 b3 c4 d4 e4 f4 g4 a4 b4 c5))))
            :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 q e s s))
                                    :pitch-seq-palette ((1 2 3 4 5))))
                                (2 ((((4 4) h h))
                                    :pitch-seq-palette ((1 2)))))
            :rthm-seq-map '((1 ((hn (1 1 1 1 1))
                                (vc (1 1 1 1 1))))
                            (2 ((hn (2 2 2 2 2))
                                (vc (2 2 2 2 2))))
                            (3 ((hn (1 1 1 1 1))
                                (vc (1 1 1 1 1))))))))
      (print (length (get-data-data 'hn (get-section mini 2))))
      (print (length (get-data-data 'vc (get-section mini 2))))
      (delete-sequenzes (piece mini) 8 'hn 2)
      (delete-sequenzes (piece mini) 8 'vc 2)
      (print (length (get-data-data 'hn (get-section mini 2))))
      (print (length (get-data-data 'vc (get-section mini 2))))
      (update-slots mini)
      (cmn-display mini))

SYNOPSIS

    (defmethod delete-sequenzes ((p piece) bar-num player &optional (how-many 1))

## piece/get-nth-sequenz [ Methods ]

[ Top ] [ piece ] [ Methods ]

DESCRIPTION

     Get the sequenz object from a specified section of a piece object by
     specifying a position index and a player.

     NB: This is the primary method for accessing player sequences, as it
         handles cases in which a player doesn't play in a sequence, and it is
         called automatically by slippery-chicken.

         When the specified player has no note events in the specified sequence
         and the optional argument <create-rest-seq> is set to T, this method
         creates a rest sequence (one that consists of the correct number of
         bars with the right time signatures, but in which the bars are only
         rest bars) based on a simultaneous sequence in one of the playing
         instruments.

ARGUMENTS

     - A piece object.
     - The ID of the section in from which the sequenz object is to be
       returned.
     - The ID of the player from whose part the sequenz object is to be
       returned.
     - An integer that is the index (position) of the desired sequenz object
       within the given section. This number is 0-based.

OPTIONAL ARGUMENTS

     - T or NIL to indicate whether to convert sequenz objects that are NIL
       (i.e., the specified player has no events in the specified sequenz) to
       sequenz objects consisting of full-bar rests. T = create rest sequences.
       Default = T. NB: This argument is already called by slippery-chicken with
       a value of T, so has no effect when used as a post-generation editing
       method and can be thus considered for internal use only.

RETURN VALUE

     Returns a sequenz object.

EXAMPLE

    ;;; Returns a sequenz object
    (let ((mini
           (make-slippery-chicken
            '+mini+
            :ensemble '(((hn (french-horn :midi-channel 1))
                         (vc (cello :midi-channel 2))))
            :set-palette '((1 ((f3 g3 a3 b3 c4 d4 e4 f4 g4 a4 b4 c5))))
            :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 q e s s))
                                    :pitch-seq-palette ((1 2 3 4 5)))))
            :rthm-seq-map '((1 ((hn (1 1 1 1 1))
                                (vc (1 1 1 1 1))))
                            (2 ((hn (nil nil nil nil nil))
                                (vc (1 1 1 1 1))))
                            (3 ((hn (1 1 1 1 1))
                                (vc (1 1 1 1 1))))))))
      (get-nth-sequenz (piece mini) 3 'hn 2))

    =>

    SEQUENZ: pitch-curve: (1 2 3 4 5)
    RTHM-SEQ: num-bars: 1
              num-rhythms: 5
              num-notes: 5
              num-score-notes: 5
              num-rests: 0
              duration: 4.0
              psp-inversions: NIL
              marks: NIL
              time-sigs-tag: NIL
              handled-first-note-tie: NIL
             (for brevity's sake, slots pitch-seq-palette and bars are not printed)
    SCLIST: sclist-length: 3, bounds-alert: T, copy: T
    LINKED-NAMED-OBJECT: previous: NIL, this: (1), next: NIL
    BAR-HOLDER:
                start-bar: 13
                end-bar: 13
                num-bars: 1
                start-time: 48.0
                end-time: 52.0
                start-time-qtrs: 48.0
                end-time-qtrs: 52.0
                num-notes (attacked notes, not tied): 5
                num-score-notes (tied notes counted separately): 5
                num-rests: 0
                duration-qtrs: 4.0
                duration: 4.0 (4.000)

SYNOPSIS

    (defmethod get-nth-sequenz ((p piece) section player seq-num ; 0-based
                                &optional (create-rest-seq t))

## piece/get-sequenz-from-bar-num [ Methods ]

[ Top ] [ piece ] [ Methods ]

DESCRIPTION

     Get the specified sequenz object located at a specified bar-number location
     of a specified player's part in a given piece object.

ARGUMENTS

     - A piece object.
     - An integer that is the number of the bar from which to return the sequenz
       object.
     - The ID of the player from whose part the sequenz object is to be
       returned.

RETURN VALUE

     A sequenz object.

EXAMPLE

    (let ((mini
           (make-slippery-chicken
            '+mini+
            :ensemble '(((hn (french-horn :midi-channel 1))
                         (vc (cello :midi-channel 2))))
            :set-palette '((1 ((f3 g3 a3 b3 c4 d4 e4 f4 g4 a4 b4 c5))))
            :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 q e s s))
                                    :pitch-seq-palette ((1 2 3 4 5)))))
            :rthm-seq-map '((1 ((hn (1 1 1 1 1))
                                (vc (1 1 1 1 1))))
                            (2 ((hn (1 1 1 1 1))
                                (vc (1 1 1 1 1))))
                            (3 ((hn (1 1 1 1 1))
                                (vc (1 1 1 1 1))))))))
      (get-sequenz-from-bar-num (piece mini) 7 'vc))

                 =>
                 SEQUENZ: pitch-curve: (1 2 3 4 5)
                 RTHM-SEQ: num-bars: 1
                 num-rhythms: 5
                 num-notes: 5
                 num-score-notes: 5
                 num-rests: 0
                 duration: 4.0
                 psp-inversions: NIL
                 marks: NIL
                 time-sigs-tag: NIL
                 handled-first-note-tie: NIL
                 (for brevity's sake, slots pitch-seq-palette and bars are not printed)
                 SCLIST: sclist-length: 3, bounds-alert: T, copy: T
                 LINKED-NAMED-OBJECT: previous: NIL, this: (1), next: NIL
                 BAR-HOLDER:
                 start-bar: 7
                 end-bar: 7
                 num-bars: 1
                 start-time: 24.0
                 end-time: 28.0
                 start-time-qtrs: 24.0
                 end-time-qtrs: 28.0
                 num-notes (attacked notes, not tied): 5
                 num-score-notes (tied notes counted separately): 5
                 num-rests: 0
                 duration-qtrs: 4.0
                 duration: 4.0 (4.000)

SYNOPSIS

    (defmethod get-sequenz-from-bar-num ((p piece) bar-num player)

## piece/insert-bar [ Methods ]

[ Top ] [ piece ] [ Methods ]

DESCRIPTION

     Insert a rthm-seq-bar object into an existing piece object.

     NB: As this is a post-generation editing method when used with this class,
         the rthm-seq-bar object must consist of event objects (with pitches),
         not just rhythm objects. If used to insert a bar into an isolated
         rthm-seq object (not a sequenz object), the inserted rthm-seq-bar could
         then consist of rhythm objects rather than events.

     NB: Slippery chicken does not check to ensure that a new bar is inserted
         for each player at a given point; this is up to the user.

     NB: The user must call the update-slots method to ensure that changes to
         the num-bars slot etc. are reflected in the given slippery-chicken
         object.

ARGUMENTS

     - A piece object.
     - A rthm-seq-bar object.
     - An integer that is the bar-number within the rthm-seq-bar object before
       which the new bar is to be inserted.
     - NB: The optional arguments are actually required for use with this class.

OPTIONAL ARGUMENTS

     NB: The optional arguments are actually required for use with this class.
     - An integer that is the section of in which the bar is to be inserted.
     - The ID of the player into whose part the new bar is to be added.
     - An integer that is the number of the sequenz object into which the bar is
       to be inserted. This is one-based.
     - A list of integers that are the curve for a pitch-seq object to be
       applied to the bar that is to be inserted.

RETURN VALUE

     T

EXAMPLE

    (let ((mini
           (make-slippery-chicken
            '+mini+
            :ensemble '(((hn (french-horn :midi-channel 1))
                         (vc (cello :midi-channel 2))))
            :set-palette '((1 ((f3 g3 a3 b3 c4 d4 e4 f4 g4 a4 b4 c5))))
            :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 q e s s))
                                    :pitch-seq-palette ((1 2 3 4 5))))
                                (2 ((((4 4) h h))
                                    :pitch-seq-palette ((1 2)))))
            :rthm-seq-map '((1 ((hn (1 1 1 1 1))
                                (vc (1 1 1 1 1))))
                            (2 ((hn (1 1 1 1 1))
                                (vc (1 2 1 1 1))))
                            (3 ((hn (1 1 1 1 1))
                                (vc (1 1 1 1 1)))))))
          (new-bar (make-rthm-seq-bar '((4 4) (w)))))

      (fill-with-rhythms new-bar (loop for r in '(h q. e)
                                    for p in '(c4 e4 g4)
                                    collect (make-event p r)))
      ;; slippery-chicken object has 15 bars  (print (num-bars mini))
      ;; print the number of bars in the sequenz in piece=mini, section=2,
      ;; seq=2 (0=based), player='hn.
      ;; has 1 bar
      (print (num-bars (get-nth-sequenz (piece mini) 2 'hn 2)))
      ;; insert an rsb in piece=mini, section=2, seq=3 (1-based), player='hn,
      ;; before rsb=1 of the existing seq
      (insert-bar (piece mini) new-bar 1 2 'hn 3 '(1 2 3))
      ;; insert an rsb in piece=mini, section=2, seq=3 (1-based), player='vc,
      ;; before rsb=1 of the existing seq
      (insert-bar (piece mini) new-bar 1 2 'vc 3 '(1 2 3))
      ;; print the number of bars in the sequenz in piece=mini, section=2,
      ;; seq=2 (0=based), player='hn.
      ;; now has 2 bars.
      (print (num-bars (get-nth-sequenz (piece mini) 2 'hn 2)))
      ;; update slots of the sc object.
      (update-slots mini)
      ;; print the number of bars of the slippery-chicken object.
      ;; now 16.
      (print (num-bars mini)))

    =>
    15
    1
    2
    16

SYNOPSIS

    (defmethod insert-bar ((p piece) (rsb rthm-seq-bar) bar-num
                           ;; these aren't actually optional but we don't
                           ;; need them in the rthm-seq method
                           &optional section player seq-num ; seq-num is 1-based!
                                     ;; this really is optional
                                     pitch-seq)

## piece/rebar [ Methods ]

[ Top ] [ piece ] [ Methods ]

DATE

     29-Jan-2010

DESCRIPTION

     Go through the sequences and rebar according to the first one that has the
     least number of bars (but following the player hierarchy).

ARGUMENTS

     - A piece object (usually provided by calling from the slippery-chicken
       class)

OPTIONAL ARGUMENTS

     - A list of player IDs from the given piece object, ordered in terms of
       importance i.e. which instrument's bar structure should take precedence.

     NB: The optional arguments are actually required in this class (not in
         slippery-chicken) but the rebar-fun is not yet used.

RETURN VALUE

     Always T.

SYNOPSIS

    (defmethod rebar ((p piece) &optional instruments-hierarchy rebar-fun)