Stream is an abstract class that is not used directly. The following attempts to document some aspects of the use of Streams for music generation.
A Stream represents a sequence of values that are obtained incrementally by repeated next messages. A Stream can be restarted with a reset message. (Not all streams actually implement reset semantics.)
The class Object defines next to return the object itself. Thus every object can be viewed as a stream and most simply stream themselves.
In SuperCollider, Streams are primarily used for handling text and for generating music.
A Function defines a stream consisting of the Function itself, a FuncStream defines a stream that consists of evaluations of its nextFunction.
In a FuncStream, the nextFunction runs through to completion for each element of the stream. In a Routine, the nextFunction returns values with yield and resumes execution (when it receives a next message) at the expression following the yield. This allows a sequence of expressions in the function definition to represent a sequence of distinct events, like a musical score.
Once the nextFunction completes execution, the Routine simply yields nil repeatedly. Control structures (such as do or while) can be used within the nextFunction in a manner analogous to repeat marks in a score.
Because streams respond like functions to the value message, they can be used as a scheduling task.
Streams that return numbers can be played directly with the play message.
Streams that return Events need to be wrapped in an EventStreamPlayer. The Event's delta (can also be set by dur) is used as a scheduling beats value:
The method -do effectively 'plays' a stream by iterating all of its contents.
And the following messages create a stream by filtering another stream in some way: -collect, -reject, -select, -dot, -interlace, -appendStream, -embedInStream, -trace.
Routines can be embedded in each other, using -embedInStream :
Routines can be concatenated just like Streams:
Routines can be combined with the composition operator <>
Composite Streams can be defined as combinations of Streams using the unary and binary messages.
Streams support most of the unary messages defined in AbstractFunction :
Streams support the following binary messages defined in AbstractFunction :
Streams that return numbers can be played directly with the play message. Streams that return events need to be wrapped in an EventStreamPlayer. See -asEventStreamPlayer.
| clock |
a clock. TempoClock by default. |
| quant |
either a number n (quantize to n beats), or an array [n, m] (quantize to n beats, with offset m). |
iterate until a nil is encountered.
iterate indefinitely.
return only those elements for which function.value(element) is false.
return only those elements for which function.value(element) is true.
return function.value(this.next, stream.next) for each element.
iterate all of stream for each element of this. Combine the values using function.
append stream after this returns nil. The same like ++
iterate all of this from within whatever Stream definition it is called.
print out the results of a stream while returning the original values.
| key |
when streaming events, post only this key. |
| printStream |
printOn this stream (default: Post). |
| prefix |
string added to the printout to separate different streams. |