# "Primary Disposition" \newline A Guide to the Core Usage of slippery chicken

## Setting the Environment

- Instruct Lisp to process code within the sc (*slippery chicken*) package:

        (in-package :sc)

<!-- end list -->

- Instruct sc which tuning (scale) to use when processing note-name symbols.
- Certain pitches (e.g. quarter-tones) only available in specific scales.
- Available scales: `chromatic`, `quarter-tone`, `twelfth-tone` (CMN only).
- Default = `quarter-tone`.

        (in-scale :chromatic)

----

## The Call to `make-slippery-chicken`

- `make-slippery-chicken` function.
- First argument: global variable for object containing musical data generated. 
- Second argument: title of composition.
    - Used for title in score and for the names of the LilyPond files

<!-- end of list -->

        (make-slippery-chicken
          '+primary-disposition+
          :title "Primary Disposition"

----

## The Instruments and the Ensemble

### Instruments

- Refers to the `instrument-palette object` used for the piece.
- `+slippery-chicken-standard-instrument-palette+` loads with sc.
- If not specified, defaults to this.

        :instrument-palette
          +slippery-chicken-standard-instrument-palette+

----

### Ensemble

- IDs user-defined for each *player*.
- Player assigned one or more *instruments*.
- At least MIDI channel also specified here.

        :ensemble '(((flt (flute :midi-channel 1))
                     (clr (b-flat-clarinet :midi-channel 2))
                     (vln-one (violin :midi-channel 3)) 
                     (vla (viola :midi-channel 4)) 
                     (cel (cello :midi-channel 5))))

----

### Staff Groupings for Printed Output

- Staff grouping layout of printed score.
- Numbers of players in each group from top to bottom of `:ensemble`.
- Sum of numbers must equal number of players in ensemble.

        :staff-groupings '(2 3)

----

## Tempo

- `:tempo-map` (or `:tempo-curve`, which has different format)
- List of 2-item lists.
- Measure number followed by beat-basis paired with bpm.
- Must have at least a starting tempo attached to bar 1.
- If not specified, defaults to quarter = 60.

        :tempo-map '((1 (q 84)))

----

## Pitch Collections

### Note Names
- Letter with octave number, i.e `C4` = Middle C

### Accidentals
- sharp = S, i.e. `CS4`
- flat = F, i.e. `DF4`
- quarter-tone sharp = QS, i.e. `CQS4`
- quarter-tone flat = QF, i.e. `DQF4`
- sixth-tone sharp = `SS4`
- sixth-tone flat = `SF4`
- twelfth-tone sharp = TS, i.e. `CTS4`
- twelfth-tone flat = `TF4`

----

### set-palette

- Each set defines a limited collection of pitches.
- First element: user-defined ID for that set.
- IDs are referenced in the set-map to create a progression.

<!-- end list -->

        :set-palette '((set1 ((fs2 b2 d4 a4 d5 e5 a5 d6))) 
                       (set2 ((b2 fs3 d4 e4 a4 d5 e5 a5 d6)))
                       (set3 ((cs3 fs3 e4 a4 e5 a5 e6))) 
                       (set4 ((fs2 cs3 e4 a4 b4 e5 a5 b5 e6))))

----

### set-map

- Determines which set of pitches is available for each sequence.
    - Each set applies to an entire sequence (rthm-seq) of 1+ bars.
    - Each set applies to the entire ensemble.
- The first number is the section ID.
    - Corresponds to section IDs of the other -maps.
    - Must be a number.
- Paired with lists of set IDs.
    - Can be used in any order.
- Must be same number of set IDs in each section as there are rthm-seq IDs for
  each player in the rthm-seq-map.


<!-- end list -->

    :set-map '((1 (set1 set1 set2 set1 set2)) 
               (2 (set2 set2 set3 set2 set3 set2 set3)) 
               (3 (set3 set2 set4 set2 set4 set3 set4 set4 set2 set3 set4))
               (4 (set4 set1 set4 set1 set4 set1 set1)))

----
 
### Limiting an Instrument's Pitch Range

- In addition to highest and lowest pitches of an instrument's range.
- Constrain pitches assigned to a player using envelopes.
- First element: ID of player
    - If `all`, applies to all players.
- x-values: arbitrary range scaled to number of sequences in piece.
- y-values: note-name symbols
- Interpolated values change at full-sequence only.
- Must have at least two pairs.

        :set-limits-high '((vla (0 b4 100 b4))
                           (cel (0 f4 100 f4)))

----

## Rhythms

### Durations

#### *Numeric Representation*

- `1`, `2`, `4`, `8`, `16`, `32` etc.

#### *Alphabetic Representation*

- `w`, `h`, `q`, `e`, `s`

#### Rests

- Duration in parentheses: `(4)`, `(q)`

---- 

### Dots

- One or more periods after the duration: `q.`, `e..`
- Single numeric representation: Dot must be preceded by a backslash: `4\.`, `8\..` 

### Ties

- Indicated by `+` sign
- Either: Between two rhythms with no space: `q+e`, `4+8`
- Or: Before the rhythm being tied to: `+e`
    - Numeric representation: Plus must be preceded by a backslash: `\+8`

----

### Tuplets

#### *Numeric Representation*

- Number = division of a whole note
- 12 triplet eighths in a whole: One triplet eighth = `12`
- Septuplet sixteenth = `28`
- Septuplet eighth = `14`

#### *Alphabetic Representation*

- Triplet and quintuplet shorthand: `t` or `f` before the rhythm: `te`, `f16`

#### *Dots, ties, and rests are indicated the same way*

----

#### Tuplets are Actual Durations

- Must be entered as _actual_ duration, not as (visual) duration in score.
- Can be entered without tuplet brackets and numbers: 

        (te t8 (te) fs fs (f8) f16)

- Possible for partial-beat tuplets to be placed anywhere in a measure:

        (te e ts s ts s ts ts)

#### Brackets and Numbers

- Curly bracket followed by a number: `{ 5 fs fs (f8) f16 }`
- Can also be placed on partial-beat tuplets: 

        (s { 3 te ts } e { 3 t32 t32 } s { 3 ts ts })

----

#### Nested Tuplets

- *Remember*: Actual durations must be entered!

##### *Example: Triplet sixteenths within a triplet eighth:*

- Duration of the triplet eighth: 12
- Triplet eighth divided into three equal parts: 12 x 3 = 36
- One triplet sixteenth within a triplet eighth = `36` 
        
        { 3  12 12 { 3 36 36 36 } }

----

### Beams

- Indicated by a `-` sign: `- e e - - s (s) e -`

### Repeat Rhythms Shorthand

- Indicated by `x` with a number: `s x 16`

----

### rthm-seq-palette

- Rhythmic material for the piece.
- List of rhythm sequences (rthm-seq objects).
- Each rthm-seq is given a user-defined ID.

        :rthm-seq-palette
         '((seq1 ((((4 4) - 16 16 8 - { 5 - 20 10 20 20 - } { 3 3 6 } )
                   ( - s s s s - - (s) s s s - - +e. s - q))
                  :pitch-seq-palette (1 2 3 4 5 6 7 8 9 1 2 3 4 5 6 7 8 9)
                  :marks (mp 1 a 1 s 3 slur 1 3 a 4 slur 4 7 s 9 a 10
                             slur 16 18)))
         (seq2 ((((4 4) - e e - - s s s s - - (s) s (s) s 
                  - { 3 - te te te - } )
                 ( - s s s (s) - - { 3 te te (te) - } q \+8 (e) ))
                :pitch-seq-palette (11 10 9 11 10 8 7 11 10 6 5 11 10 9 8 7 11)
                :marks (mf 1 s 1 2 a 3 slur 3 4 a 5 slur 5 6 s 7 s 8 a 9
                           slur 9 11 a 12 slur 12 14 s 15 16 a 17))) 
        [...])

----

#### rthm-seq object

- First element: user-defined ID.
- Must consist of complete measures.
- At least one measure, but can have any number of measures.
- Each measure enclosed in parentheses.
- Each measure can have a different time signature.
    - Number of beats (numerator) and beat basis (denominator) enclosed in
      parentheses.   
- If no time signature, remains the same as previous measure. 
- Also contains pitch-curves and marks. 

        (seq1 ((((2 4) (s) - s e - - e e -)
                (q - e s s -)
                ((5 8)  - e s s e - q))
               :pitch-seq-palette ((5 5 3 3 3 4 3 3 1 1 1 1 1))
               :marks (as 1 te 2 s 3 4 slur 5 6 dim-beg 9 dim-end 13)))

----

#### Pitch curves

- Determines general melodic contour of pitches sc automatically selects.
- Indicates direction and relative size of melodic interval.
- Scaled to pitches available to each instrument at that time.
- Applies to given `rthm-seq` only.
- There can be as many as we like: they will be rotated.

        :pitch-seq-palette ((5 5 3 3 3 4 3 3 1 1 1 1 1))

----

#### Articulation, dynamics, slurs

- List of mark abbreviations paired with index numbers for rhythms.
    - Attached to rhythms, not items in the pitch-seq-palette.
    - Two tied rhythms count as separate rhythms. 
- Two numbers after non-slur mark: attach to all rhythms in span, incl.
- 3+ numbers after non-slur mark: attach to all specified rhythms.
- User-defined marks: text in quotation marks.

        :marks (ppp 1 a 1 3 5 s 2 "like a whisper" 4)

- Slurs and phrases indicated by either:
    - two numbers: indices of beginning and ending rhythms, or
    - `beg-sl`/`end-sl`, `beg-phrase`/`end-phrase`.
- Slurs may be nested in phrases, but not in other slurs. 

        :marks (beg-sl 1 end-sl 2 slur 5 6 beg-phrase 1 end-phrase 8)

- Complete tables of marks on `marks.html`

----

## Structure

### rthm-seq-map

- rthm-seq objects assembled to create structure of piece.
- *List of sections* containing *lists of players* containing *lists of rthm-seq IDs*.
- Must same number of sections in rhtm-seq-map as in set-map.
- Section IDs must be the same.
- Must be same number of rthm-seq IDs for each player as there are set IDs in
  corresponding section of set-map.
- All simultaneous rthm-seqs must be of equal length
    - Same number of bars and same metrical structure. 

----

    :rthm-seq-map
     '((1 ((flt (seq1 seq1 seq2 seq1 seq2)) 
           (clr (seq1 seq2 seq1 seq2 seq1)) 
           (vln-one (seq1 seq1 seq2 seq1 seq2))   
           (vla (seq1 seq2 seq1 seq2 seq1))   
           (cel (seq1 seq1 seq2 seq1 seq2))))
       (2 ((flt (seq1 seq1 seq2 seq1 seq2 seq1 seq2))
           (clr (seq1 seq1 seq3 seq1 seq3 seq1 seq3))
           (vln-one (seq2 seq2 seq3 seq2 seq3 seq2 seq3))  
           (vla (seq2 seq2 seq1 seq2 seq1 seq2 seq1))  
           (cel (seq3 seq3 seq2 seq3 seq2 seq3 seq2))))
       [...])

----

## Output

### MIDI

- `midi-play` method.
- Only required argument: *slippery-chicken* object to process.
    - Can be object, variable, or ID of object as global variable
- Output defaults to `/tmp/sc.mid`.
- Specify output using `:midi-file` plus string.

        (midi-play +primary-disposition+ :midi-file "/tmp/prim-disp.mid")

----

### Common Music Notation

- `cmn-display` method.
- Only required argument: *slippery-chicken* object to process.
    - Can be object, variable, or ID of object as global variable
- Output defaults to `/tmp/cmn.eps`.
- Specify output using `:file` plus string.

        (cmn-display +primary-disposition+ :file "/tmp/prim-disp.eps")

----

### LilyPond

- `write-lp-data-for-all` method.
- Only required argument: *slippery-chicken* object to process.
    - Can be object, variable, or ID of object as global variable
- Output defaults to `/tmp/...`
- Doesn't run LilyPond automatically.
- Produces all files LilyPond needs for typesetting.
    - Generates file names automatically based on `title` slot
- Specify output by only determining directory path via `:base-path`.

        (write-lp-data-for-all +primary-disposition+ :base-path "/tmp/")

----

###  Producing output

- Enter each Lisp expression at the `SC>` prompt.
- or: Save code in ASCII-only text file (usually with suffix `.lsp` or `.lisp`)
  and load:  

        (load "/path/to/primary-disposition.lsp")

- or: Emacs and SLIME: `C-x C-e` to evaluate each expression (recommended)

----

### Exercise: CORE USAGE

See http://michael-edwards.org/sc/workshop-exercises.lsp
