Music 220b: Lecture 4 Slides

Item Streams, a more detailed look

The format of the item stream constructor macro

Let's split our canonical definition of an item stream in parts:

Broadly speaking we can split the typical macro call that creates an item stream in three parts: the macro name, which defines the type of the elements the item stream will store; the elements themselves and finally a list of optional keyword / value pairs. One of this keyword / value pairs is so important that I have split it out of the list because it defines the other single most important characteristic of the item stream: the pattern.

Element types

The most generic element type you can choose for an item stream is items. The constructor macro will not try to interpret the elements, so they will be stored "as is" in the item stream object:

    Stella [Top-Level]: (setf xxx (items 1 2 3 4.0 as4))

    #<CYCLIC-ITEM-STREAM 45550074>

    Stella [Top-Level]: (read-items xxx)

    (1 2 3 4.0 AS4)

Let's take a look at what the pitches constructor macro does when it creates an item stream. The macro tries to interpret the list of items according to the following criteria. Integer numbers are interpreted as standard MIDI key numbers and converted to the correspondig frequency in the current scale. Floating point numbers are interpreted as frequencies so they are left alone. Strings are interpreted as a pitch class / octave number representation of a note and also converted to a floating point frequency. Let's see what happens when we replace items with pitches in the previous example:

    Stella [Top-Level]: (setf xxx (pitches 1 2 3 4.0 as4))

    #<CYCLIC-PITCH-STREAM 45357130#>

    Stella [Top-Level]: (read-items xxx)

    (8.6619562479365388 9.1770229696436765 9.7227171524250195 4.0 466.16370931035846)

So "4.0" was left alone, but "1 2 3" and "as4" were converted to floating point frequencies.

IMPORTANT:: The item stream constructor macros never evaluate the elements. To force Common Music to evaluate enclose the expression whithin an (expr ) call...

Pattern types

The "in" keyword defines the pattern type of the item stream. The pattern defines which of the elements contained within the item stream will be returned at a given point. The default type is cycle:

   Stella [Top-Level]: (setf xxx (items 1 2 3 4 5))

   #<CYCLIC-ITEM-STREAM 45331604>

   Stella [Top-Level]: (read-items xxx)

   (1 2 3 4 5)

meaning that the selection cycles through the elements in a round robbin fashion. If we create a random item stream the selection process will be random, of course:

    Stella [Top-Level]: (setf xxx (items 1 2 3 4 5 in random))

    #<RANDOM-ITEM-STREAM 45034240>

    Stella [Top-Level]: (read-items xxx)

    (4 3 4 2 3)

If we create a heap item stream the selection process is random but we never get a repeated element:

    Stella [Top-Level]: (setf xxx (items 1 2 3 4 5 in heap))

    #<HEAP-ITEM-STREAM 44373074>

    Stella [Top-Level]: (read-items xxx)

    (5 1 2 4 3)

Universal keyword / value pairs

And of course there are a lot more optional keyword / value pairs. Some of them are common to all item stream types...

For example, for sets the period of an item stream to an arbitrary value, as in the following example:

Stella [Top-Level]: (setf xxx (items 1 2 3 4 5 in heap for 2))

#

Stella [Top-Level]: (read-items xxx)

(2 5)

Stella [Top-Level]: (read-items xxx)

(1 4)

Pattern dependant keyword / value pairs

There are many more keyword / value pairs, each different pattern type has its own. Look them up in the Common Music documentation...