./../../src/ensemble.lsp

## ensemble/add-player [ Methods ]

[ Top ] [ ensemble ] [ Methods ]

DESCRIPTION

     Add a player to an existing ensemble.  It will be added at the end of the
     list.

ARGUMENTS

     - The ensemble object.
     - The new player, either as a player object or symbol.  If the latter this
       becomes the id of the player we'll create.

OPTIONAL ARGUMENTS

     - The id of the instrument in the already existing instrument-palette.
       This is required if the player argument is a symbol.  Default NIL.
     - An instrument-palette object.  Default =
       +slippery-chicken-standard-instrument-palette+.

RETURN VALUE

     The player object added.

SYNOPSIS

    (defmethod add-player ((e ensemble) player
                           &optional
                           instrument-id
                           (instrument-palette
                            +slippery-chicken-standard-instrument-palette+))

## ensemble/get-player [ Methods ]

[ Top ] [ ensemble ] [ Methods ]

DESCRIPTION

     Return a player object from an ensemble, if it exists.

ARGUMENTS

     - An ensemble object.
     - The ID of a player.

RETURN VALUE

     The player object or NIL if there's no such player.

SYNOPSIS

    (defmethod get-player ((e ensemble) player)

## ensemble/get-players [ Methods ]

[ Top ] [ ensemble ] [ Methods ]

DESCRIPTION

     Return the IDs of the players from a given ensemble object.

ARGUMENTS

     - An ensemble object.

RETURN VALUE

     - A list of symbols that are the player IDs of the given ensemble object.

EXAMPLE

    (let ((ens (make-ensemble
                'ens
                '((flt ((flute piccolo) :midi-channel 1))
                  (clr ((b-flat-clarinet)))
                  (tpt ((b-flat-trumpet c-trumpet) :midi-channel 2))
                  (vln ((violin))))
                :instrument-palette
                +slippery-chicken-standard-instrument-palette+)))
      (get-players ens))

    => (FLT CLR TPT VLN)

SYNOPSIS

    (defmethod get-players ((e ensemble))

## ensemble/make-ensemble [ Functions ]

[ Top ] [ ensemble ] [ Functions ]

DESCRIPTION

     Make an ensemble object, specifying the players and associated
     instruments.

     NB: If you have an ensemble with a player doubling two instruments, be sure
         to indicate some keyword argument or other as
         (fl1 ((piccolo violin) :midi-channel 1)) works but
         (fl1 ((piccolo violin))) thinks that piccolo is a nested ensemble!!!

     NB: The argument :instrument-palette is a required argument although it is
         a keyword argument.

ARGUMENTS

     - An ID consisting of a symbol, string or number.
     - A list of 2-element sublists that define the ensemble. See the above
       comment on adding a keyword argument for doubling players.

OPTIONAL ARGUMENTS

     keyword arguments:
     - :instrument-palette. An instrument palette object. Default =
        +slippery-chicken-standard-instrument-palette+
     - :bar-line-writers. Obsolete as no longer used.

RETURN VALUE

     An ensemble object.

EXAMPLE

    (let ((ens (make-ensemble
                  'ens
                  '((flt ((flute piccolo) :midi-channel 1))
                    (clr ((b-flat-clarinet))))
                  :instrument-palette
                  +slippery-chicken-standard-instrument-palette+)))
      (print ens))

    =>

    ENSEMBLE: bar-line-writers: NIL
              players: (FLT CLR)
              (id instrument-palette): SLIPPERY-CHICKEN-STANDARD-INSTRUMENT-PALETTE
    RECURSIVE-ASSOC-LIST: recurse-simple-data: T
                          num-data: 2
                          linked: T
                          full-ref: NIL
    ASSOC-LIST: warn-not-found T
    CIRCULAR-SCLIST: current 0
    SCLIST: sclist-length: 2, bounds-alert: T, copy: T
    LINKED-NAMED-OBJECT: previous: NIL, this: NIL, next: NIL
    NAMED-OBJECT: id: ENS, tag: NIL,
    data: (
    PLAYER: (id instrument-palette): SLIPPERY-CHICKEN-STANDARD-INSTRUMENT-PALETTE
    doubles: T, cmn-staff-args: NIL
    LINKED-NAMED-OBJECT: previous: NIL, this: (FLT), next: (CLR)
    NAMED-OBJECT: id: FLT, tag: NIL,
    data:
    [...]
    data: (
    INSTRUMENT: lowest-written:
    [...]
    NAMED-OBJECT: id: FLUTE, tag: NIL,
    [...]
    INSTRUMENT: lowest-written:
    [...]
    NAMED-OBJECT: id: PICCOLO, tag: NIL,
    [...]
    PLAYER: (id instrument-palette): SLIPPERY-CHICKEN-STANDARD-INSTRUMENT-PALETTE
    doubles: NIL, cmn-staff-args: NIL
    LINKED-NAMED-OBJECT: previous: (FLT), this: (CLR), next: NIL
    NAMED-OBJECT: id: CLR, tag: NIL,
    data:
    INSTRUMENT: lowest-written:
    [...]
    NAMED-OBJECT: id: B-FLAT-CLARINET, tag: NIL,
    )

SYNOPSIS

    (defun make-ensemble (id ensemble &key bar-line-writers
                          (instrument-palette
                           +slippery-chicken-standard-instrument-palette+))

## ensemble/num-notes [ Methods ]

[ Top ] [ ensemble ] [ Methods ]

DESCRIPTION

     Get the number of attacked notes in a given slippery-chicken object. This
     method accesses the ensemble object within the given slippery-chicken
     object to perform this task.

ARGUMENTS

     - An ensemble object.

RETURN VALUE

     An integer that is the total number of attacked notes in the given
     slippery-chicken object.

EXAMPLE

    (let ((mini
           (make-slippery-chicken
            '+mini+
            :ensemble '(((vn (violin :midi-channel 1))
                         (vc (cello :midi-channel 2))))
            :set-palette '((1 ((f3 g3 a3 b3 c4 d4 e4 f4))))
            :set-map '((1 (1 1 1 1 1)))
            :rthm-seq-palette '((1 ((((2 4) e e e e))
                                    :pitch-seq-palette ((1 2 3 4)))))
            :rthm-seq-map '((1 ((vn (1 1 1 1 1))
                                (vc (1 1 1 1 1))))))))
      (num-notes (ensemble mini)))

    => 40

SYNOPSIS

    (defmethod num-notes ((e ensemble))

## ensemble/num-players [ Methods ]

[ Top ] [ ensemble ] [ Methods ]

DESCRIPTION

     Get the number of players in a given ensemble object.

ARGUMENTS

     - An ensemble object.

RETURN VALUE

     - An integer.

EXAMPLE

    (let ((ens (make-ensemble
                'ens
                '((flt ((flute piccolo) :midi-channel 1))
                  (clr ((b-flat-clarinet)))
                  (tpt ((b-flat-trumpet c-trumpet) :midi-channel 2))
                  (vln ((violin))))
                :instrument-palette
                +slippery-chicken-standard-instrument-palette+)))
      (num-players ens))

    => 4

SYNOPSIS

    (defmethod num-players ((e ensemble))

## ensemble/players-exist [ Methods ]

[ Top ] [ ensemble ] [ Methods ]

DESCRIPTION

     Produce an error message and drop into the debugger if the specified
     player IDs are not found within the given ensemble object.

ARGUMENTS

     - An ensemble object.
     - A list of symbols that are the IDs of the players sought.

RETURN VALUE

     NIL if the specified player ID is present within the given ensemble object,
     otherwise drops into the debugger with an error.

EXAMPLE

    ;;; Returns NIL if a player with the specified ID is found in the given
    ;;; ensemble object.
    (let ((ens (make-ensemble
                'ens
                '((flt ((flute piccolo) :midi-channel 1))
                  (clr ((b-flat-clarinet)))
                  (tpt ((b-flat-trumpet c-trumpet) :midi-channel 2))
                  (vln ((violin))))
                :instrument-palette
                +slippery-chicken-standard-instrument-palette+)))
      (players-exist ens '(vln)))

    => NIL

    ;; Drops into the debugger with an error if no player with the specified ID is
    ;; found in the given ensemble object.
    (let ((ens (make-ensemble
                'ens
                '((flt ((flute piccolo) :midi-channel 1))
                  (clr ((b-flat-clarinet)))
                  (tpt ((b-flat-trumpet c-trumpet) :midi-channel 2))
                  (vln ((violin))))
                :instrument-palette
                +slippery-chicken-standard-instrument-palette+)))
      (players-exist ens '(vla)))

    =>
    ensemble::players-exist: VLA is not a member of the ensemble
       [Condition of type SIMPLE-ERROR]

SYNOPSIS

    (defmethod players-exist ((e ensemble) players)

## ensemble/tessitura [ Methods ]

[ Top ] [ ensemble ] [ Methods ]

DESCRIPTION

     Get the average pitch of a given slippery-chicken object. This method
     accesses the ensemble object within the given slippery-chicken object to
     perform this task.

     NB: This method processes data in relationship to degrees of the current
         tuning system (scale), which is quarter-tone by default. It is
         therefore possible, when generating a piece using only chromatic
         pitches but within a non-chromatic tuning to get microtonal results.

ARGUMENTS

     - An ensemble object.

RETURN VALUE

     An integer that is the average pitch of the given slippery-chicken object
     in degrees.

EXAMPLE

    ;;; Change the tuning to chromatic first to get an accurate result:
    (in-scale :chromatic)

    => #<tuning "chromatic-scale">

    (let ((mini
           (make-slippery-chicken
            '+mini+
            :ensemble '(((vn (violin :midi-channel 1))
                         (vc (cello :midi-channel 2))))
            :set-palette '((1 ((f3 g3 a3 b3 c4 d4 e4 f4))))
            :set-map '((1 (1 1 1 1 1)))
            :rthm-seq-palette '((1 ((((2 4) e e e e))
                                    :pitch-seq-palette ((1 2 3 4)))))
            :rthm-seq-map '((1 ((vn (1 1 1 1 1))
                                (vc (1 1 1 1 1))))))))
      (tessitura (ensemble mini)))

    => C4

SYNOPSIS

    (defmethod tessitura ((e ensemble))

## recursive-assoc-list/ensemble [ Classes ]

[ Top ] [ recursive-assoc-list ] [ Classes ]

NAME

     ensemble

     File:             ensemble.lsp

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

     Version:          1.0.1

     Project:          slippery chicken (algorithmic composition)

     Purpose:          Implementation of the ensemble class.

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

     Creation date:    4th September 2001

     $$ Last modified: 12:37:41 Sat Apr 20 2013 BST

     SVN ID: $Id: ensemble.lsp 3468 2013-04-20 12:51:16Z medward2 $