How to set up a piece in the Lisp Kernel
John Rahn 12/9/91



See the ªsetup.clº section of the Lisp Kernel source code. What follows refers to that.

1. There are two or three global variables, assigned with DEFPARAMETER: 
a) CS-HEADER, a string holding the initialization and ªf-cardsº for a csound orch.
b) MODS, a note-structure implementing an environment passed as a parameter from higher levels down to the note level in functional programming style (see the Kernel code).
c) If you want to use this in your instrument definitions (see Kernel code and text below), OVERALLGAIN to adjust the global amplitude to fit the maximum amplitude to the size of the converters after each run.  OVERALLGAIN can be set using (ADJUST-AMP  newmax), where you get newmax from the csound printout for a run.

2. Set up the piece-name:
a) Define the name of the current piece by (PIECE 'MY). This name resides in the Lisp Kernel database as a global variable (not in the general Lisp environment); it can be accessed by (GET-GLOBAL 'CURRENT-PIECE). It is used by a lot of the internal machinery.
b) Define an orchestra for the the current piece using DEFUN; this must be a function from instrument numbers to instrument names (see Kernel code for example using CASE). In csound, the mapping can be one-to-one and can be essentially built in to your Lisp instruments so you do not have to specify it. (MUSIC4-type programs require many instrument numbers for each instrument name because in those programs, unlike csound, a given instrument number can play only one note at a time.)
c) Assign the orchestra function to the name of the piece using ASSIGN-ORCH. For example, if the piece-name is 'MY and the orchestra function's name is MY-ORCH, (ASSIGN-ORCH #'MY-ORCH 'MY).

3. Define the instrument functions using DEFUN (see code). 
a) The first form in the body of an instrument definition should be some version of CREATE-C, mainly to initialize the scratchpad, which is the symbol-plist of the atom 'NOTE -- a mere (PUTPL 'NOTE  NIL) will suffice. 
b) The last form should be (SAVE-NOTE), which writes (appends) the new note-structure that is by then the contents of the scratchpad to the database of notes under the name of the piece. 
c) The macro  ->  assigns values to parameter names on the scratchpad. Note that the name of the parameter is not quoted, since this is a macro. For example, (-> INSNO 2) means, ªassign to the parameter name INSNO the value 2.º
There are other ways of creating a note-structure appropriate for a given instrument and adding it to the list under a piece-name; see MIX2 in the setup.cl section.

4. Attach to each instrument name two entities a) a template and b) a write format for each parameter of that instrument.
a) The template is a list of parameter names in the order in which you want them written to the csound data file. Use (ASSIGN-TEMPLATE instrument-name template-list), for example, (ASSIGN-TEMPLATE 'KAZOO '(START DUR AMP PITCH)). The Lisp Kernel converts its internal note-structures to csound data format by selecting only parameters that are in the template and writing them to the data file re-ordered as necessary to fit the order specified by the template. Parameter names that may be in the note-structure but not in the template are ignored. Parameter names that are in the template but not in the note-structure are given a default value, if one has been specified for that parameter name using (ASSIGN-DEFAULT-VALUE instrument-name property-name value).
b)  The value for each parameter is written to the csound data file formatted as specified by a Lisp FORMAT string, which you can assign individually using (ASSIGN-PARAMETER-FORMATS instrument-name parameter-name1 format-string1 parameter-name2 format-string2 ....) for each instrument. For example, 
(ASSIGN-PARAMETER-FORMATS 'KAZOO 
	'START "~10,4f" 
	'DUR "~8,4f" 
	'AMP "~10,2f" 
	'PITCH "~9,5f"). 
The new, improved csound breaks if any value is written with more than 5 numbers after the decimal point. You can also assign a default parameter format effective for all the parameters of an instrument, using (ASSIGN-DEFAULT-FORMAT instrument-name format-string).

5. Edit the (PLAY) function to refer to the new name of the piece instead of 'MY. 
PLAY does a number of things (see code below). The name of the piece has the orchestra function attached to it. The names of the .sco and .snd files are arbitrary. The third argument to PRINTCS is anything that evaluates to a header string for csound; if this argument is left out, it defaults to a Lisp global variable named CS-HEADER.

;; PLAY will cause all notes saved under MY in the LK 
;; to be played using csound and class.orc
(defun play () 
		(shell "rm my.sco")
		(printcs 'my "my.sco")	
			;; print my notes in a csound score file named my.sco
		(shell "csound  -o my.snd class.orc my.sco")	
			;; run csound with class.orc and my.sco, output to my.snd
		(shell "sndplay snd/my.snd")
			;; hear the file my.snd using the NeXT utility sndplay
 )	


6. The header to the file kernel.cl in version .9991772 has detailed instructions on how to set up a NeXT computer not in SMCC to run the Lisp Kernel and csound.