D


Intro       Symbols A B C D E F G H I J K L M N O P Q R S T U V W X Y Z       Index  
*default-midi-pathname* [Variable]

The default pathname for MIDI file operations. Initially set to "test.midi" in the directory returned by (user-homedir). All MIDI file functions merge a supplied file name with *default-midi-pathname* to form the fully specified pathname.

See Also:

MIDI

 


definstrument {name | (name {keyword value}*)} ({parameters}+) {form}* [Macro]

Defines a CLM instrument and a note class of the same name for composing with the instrument. name is the name of the instrument, and may be specified as a list together with optional keywords that provide control over the exact behavior of definstrument. In addtion to the keywords suported by CLM, Common Music adds three keywords of its own:

:time-parameter {name | position | nil}
Declares that the parameter name or the parameter at position (zero-based) in parameters is the "start time" of the instrument. The default value is 0, which means that time is to be passed as the first argument to the instrument. If :time-parameter is nil then no time value is passed.
:printer {function}
Declares function to be the scorefile printer for the object. The default printer is clm-print, which prints floating point numbers rounded to three places and precedes unquoted envelope lists with an explicit quote. If specified, function is passed two arguments, the value to print and the stream.
:instrument-only {nil | t}
Determines if a Common Music event class is defined for the instrument. The default value is nil, which means that an event class is defined.

See Also:

CLM, Working with CLM, tutorials/stella/fm.ins

 


defmode {name | (name} {option value})} {step}+ [Macro]

Defines a named, transposable subset of a scale. Modes may replace scales when specifying notes, pitches, degrees or intervals and may function as "filters" by using mode-note, mode-degree, or mode-pitch.

Name is the name of the new mode. Following name comes by zero or more option value pairs.

defmode supports the following options:

scale {scale}
Sets the scale of the mode to object, which must be a scale object. Defaults to *standard-scale*.
on {note | pitch | degree}
Sets the initial transposition level for the mode, expressed as a note, pitch or degree of the mode's scale.
The step content of a mode may be specified as either an ascending sequence of note names or as a sequence of integers defining the relative distances between adjancent notes in the mode. If note names are used then the lowest (first) note becomes the initial transposition offset for the mode. If the steps are specified as relative interval distances then the transposition offset of the mode must be set before the mode can be used. Use the transpose function to set or change the transposition level of a mode.

Example:

? (setf m (defmode (major on 'c4) 2 2 1 2 2 2 1))
#<MODE: Major (on C)>

? (note 0 m)
C00

? (note 7 m)
C0

? (setf x (intervals 0 1 2 3 4 5 6 7 from (notes c4 fs)
                     of m returning note))
#<CYCLIC-INTERVAL-STREAM 133753451>

? (read-items x 16)
(C4 D4 E4 F4 G4 A4 B4 C5 FS4 GS4 AS4 B4 CS5 DS5 F5 FS5)

? (transpose m 'D4)
#<MODE: Major (on D)>

? (loop for i from 35 repeat 15 collect (note i m))
(D4 E4 FS4 G4 A4 B4 CS5 D5 E5 FS5 G5 A5 B5 CS6 D6)

? (setf m (defmode funny-mode c0 d e fs gs as c1 cs ds e fs g a bf c2))
#<MODE: Funny-mode (on C0)>

? (loop for i from (degree 'c4) below (degree 'c6) by 1
        collect (mode-note i m))
(C4 C4 D4 D4 E4 E4 FS4 FS4 GS4 GS4 AS4 AS4 
    C5 CS5 CS5 DS5 E5 E5 FS5 G5 G5 A5 AS5 AS5)
;;;
;;; a few common mode definitions
;;;

(defmode pentatonic  2 3 2 2 3)
(defmode whole-tone  2 2 2 2 2 2)
(defmode octatonic1  1 2 1 2 1 2 1 2)
(defmode octatonic2  2 1 2 1 2 1 2 1)
(defmode dorian      2 1 2 2 2 1 2)
(defmode phrygian    1 2 2 2 1 2 2)
(defmode lydian      2 2 2 1 2 2 1)
(defmode mixolydian  2 2 1 2 2 1 2)
(defmode aeolian     2 1 2 2 1 2 2)
(defmode locrian     1 2 2 1 2 2 2)
(defmode ionian      2 2 1 2 2 2 1)

See Also:

defscale, mode-note, mode-pitch, mode-degree, transpose, defscales.lisp

 


defmultiple-item name ({field}+) ({keyword value})* [Macro]

Defines a class of item with component fields. Multiple items enumerate their fields in parallel, regardless of what type of pattern the multiple-item appears in. Fields may contain constant values or item streams. name is the name for the multiple item. Each field declares a component of the multiple item. Following the field specification comes zero or more option lists:

(:element-period {field | :all {field}* | :any {field}*})
sets which field or combination of fields controls the period length of the multiple item. If the value is a single field then that field controls the period length. Otherwise the value should be :all or :any followed by zero or more qualifying fields. :all means than each qualified field (or all the fields if none are qualified) must be at end-of-period before the multiple item is considered to be at end-of-period. :any specifies that the multiple-item will be at end-of-period when any of the qualifying fields (or all the fields if none are qualified) are at end-of-period. If only a single field is tracked, then :all and :any have the same effect.
(:element-parser lambda)
Defines a parser for the multiple item. The parser function is passed as many parameters as there are fields declared, and it must return the list of parsed field values. For example, a parser for a multiple item with two fields, the second of which generates scale degrees, would look like:
    (lambda (x y) (list x (degree y))
(:element-state field)
Names the field whose state is returned as the state of the multiple item.
(:element-filter lambda-expression)
Defines an element filter for the multiple item. The filter is passed the current elements in the multiple item and returns the actual list of elements to return.
defmultiple-item definitions should be compiled before using.

Example:

? (defmultiple-item gesture (pit rhy)
    (:element-period :all)
    (:element-parser (lambda (n r) (list (note n) (rhythm r)))))
#<Standard-Class GESTURE 137535711>

? (setf x (items (gesture c4 q)
                 (gesture (notes c5 c6 in random) w)
                 (gesture b3 (rhythms s e for 1))
                 in heap for 10))
#<HEAP-ITEM-STREAM 137443141>

? (read-items x)
((C4 1.0) (C5 4.0) (C5 4.0) (B3 0.25) (B3 0.5) (C6 4.0) (C5 4.0) 
 (C4 1.0) (C4 1.0) (B3 0.25) (C5 4.0) (C5 4.0) (C4 1.0))

See Also:

Item Streams, multiple-item-bind

 


defobject name ({super}*) ({slot}*) {option}* [Macro]

Defines a new class of object. name is the name for the new class. Following name comes a list of zero or more superclasses. The new object will inherit slots and behavior from each super in the list. Following this list comes the slot specification list. Each slot in the list is either the name of a slot or a list of the form:

    (slot &key :initform :accessor :reader :writer)
Following the slot specification list comes zero or more options. Each option is a list of the form:
    (option {value}*)
Where option is the keyword option name and value is a value.

defobject supports the following options:

(:parameters {slot}*)
Declares each slot to be a parameter of the object. A parameter is a slot whose value contributes to the overall makeup of a musical event.
defobject is a wrapper for Lisp's defclass macro. It automatically defines keyword and non-keyword slot initialization arguments to be used in conjunction with macros like algorithm and object.

defobject expressions should always be compiled before using.

See Also:

i1.lisp

 


defscale name ({keywords}*) {degree}+ [Macro]

Defines a musical scale. Three types of scales are supported: equal tempered scales have a fixed ratio between scale degrees and scale octaves; gapped scales have a fixed ratio between octaves, but not between intervals within an octave; and general scales have no fixed ratio between either intervals or octaves. The type of scale defined is normally determined automatically by defscale when it examines the keywords and degree forms that collectively define the scale's "prototype octave".

defscale supports the following keywords:

:class { nil | equal-tempered-scale | gapped-scale | general-scale}
Sets the class of scale to use for the new scale. If the value is nil (the default) the class is automatically determined.
:lowest-pitch {float}
Sets the lowest pitch (floating point) for gapped or equal tempered scales. The pitch for each degree in the prototype octave is then computed from the values of :lowest-pitch, :octave-ratio (if any) and the individual degrees defined in the prototype octave.
:number-of-octaves {integer | nil}
Sets the number of octaves that the new scale is defined over. The default value is 10. If nil a general scale will be created.
:divisions-per-octaves {integer | nil}
Sets the number of entries defined in the prototype octave. The default value is computed from the number of entries in the prototype octave. If a general scale has multiple octaves, this value must be supplied.
:octave-ratio {number | nil}
Sets the ratio between octaves (if any) in the scale. A number produces either a gapped scale or an equal tempered scale, depending on whether or not scalars and ratios are present in the prototype octave. A nil value creates a general scale.
:interval-ratio {number}
Yet another way to specify equal tempered scales. Defaults to octave-ratio^1/divisions-per-octave.
:suboctave-enharmonic {note}
Specifies the note name that is enharmonic with the first degree in an octave.
:superoctave-enharmonic {note}
Specifies the note name that is enharmonic with the last degree in an octave.
:first-octave-number {integer | |00|}
Sets the first octave's counting index, which defaults to 0. If you want a 00 first octave (MusicKit), specify the symbol '|00| as the value.
Each degree entry in the body of the macr defines a scale degree in the prototype octave. The full form for degree specification is:

     ((&rest note-names) &key :pitch :scaler :ratio)
note-names are all the possible (enharmonic) note names for the prototype degree. If there is only one note name for the entry it is not necessary to specify that name in a list. :pitch, :scaler, and :ratio are mutually exclusive ways for specifying a floating point pitch of a prototype degree. Use :pitch to directly specify the floating point frequency of the entry, but it is easier and safer to specify a pitch value indirectly, using either the :scaler or :ratio keywords. :scaler is a multiplier for the :lowest-pitch keyword for the scale. A :scaler value for the first degree in the prototype octave must therefore be 1.0. :ratio is a ratio distance to the next scale entry from the current one. The :ratio value for the last entry is ignored. :ratio is really syntactic sugar that is automatically converted to an absolute :scaler value. If no :scaler, :pitch or :ratio value is supplied (i.e. the scale is an equal tempered scale), then the surrounding () for note-names may be omitted.

The symbolic rest name Rindicating silence is automatically added to all scales.

Example:

;; a 4 octave equal tempered scale, 5 notes per octave, with
;; octaves slightly stretched:

? (defscale foo (:lowest-pitch 123.45 :number-of-octaves 4
                 :octave-ratio 2.1)
    i ii iii iv v)
#<EQUAL-TEMPERED-SCALE Foo 137653271>

? (in-scale 'foo)
#<EQUAL-TEMPERED-SCALE Foo 137653271>

? (read-items (pitches i0 i1 ii2 iii3 v1))
(123.45 259.245 631.5002 1538.2844 469.33813)

(in-scale 'chromatic-scale)
#<EQUAL-TEMPERED-SCALE Chromatic-Scale>

See Also:

defscales.lisp, find-scale, in-scale, list-all-scales, *standard-scale*

 


degree [Item Type]

The integer position of an entry in a musical scale. Scale entries have three different aspects: a note, or symbolic note name, a pitch, or floating point frequency, and a degree, or ordinal position.

Each of these reference types is supported by a function for converting to that type and a macro for creating item streams of that type.

See Also:

degree [Function], degrees, note, pitch

 


degree reference &optional scale [Function]

Returns the integer scale position of reference in scale. Reference may be a note, degree, or pitch. If scale is omitted it defaults to *standard-scale*.

Example:

? (degree 'a4)
69

? (degree 440.0)
69

? (degree 69)
69

See Also:

degree [Item Type], degrees, note, notes, pitch, pitches, *standard-scale*

 


degrees {reference}+ {option value}* [Macro]

Creates an item stream of integer scale positions. Each reference may be a note, degree, pitch or item stream.

degrees implements the following option value pairs:

of {scale}
Sets the musical scale for the stream. Defaults to *standard-scale*.
An additional set of basic option valuepairs are available in all item stream macros. Others may be available based on the pattern type specified to the macro.

Example:

? (setf x (degrees c4 d e f in random for 8))
#<RANDOM-DEGREE-STREAM 131443131>

? (read-items x)
(65 64 64 60 65 62 64 64)

See Also:

degree, Item Streams, note, notes, pitch, pitches

 


diminuendo {from amplitude} {to amplitude} {in integer}{beat amplitude}* [Macro]

Creates a cyclic amplitude stream. Amplitudes start at from and move to to over in number of beat type beats. from, to and in must be specified but may appear in any order.

Example:

? (setf x (diminuendo in 8 from .8 to .2))
#<CYCLIC-AMPLITUDE-STREAM 133753451>

? (read-items x)
(0.8 0.71428573 0.62857145 0.5428571 0.45714286 0.37142858
0.2857143 0.2)

See Also:

amplitude, amplitudes, crescendo

 


doitems ({var | (var1 var2)} {stream} {keyword value}*) {form}* [Macro]

Binds varto succesive items in stream. If var is a list of two variables, then the first variable is bound to successive items and the second variable is bound to successive states.

doitems supports the following keyword value pairs:

:periods {integer}
Sets the number of periods to perform iteration over. Defaults to 1.

Example:

? (doitems (x (items foo bar baz in random for 6))
    (format t " ~A" x))
BAR FOO BAZ BAZ FOO BAZ
NIL

See Also:

item, Item Streams, read-items