Stream:
Filter:

Stream : AbstractFunction : Object

Stream is the base class for classes that define streams
Source: Stream.sc

Description

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.

Overview

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.

FuncStream(nextFunction, resetFunction)

A Function defines a stream consisting of the Function itself, a FuncStream defines a stream that consists of evaluations of its nextFunction.

Routine(nextFunction, stacksize)

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.

Playing streams

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:

Iteration

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.

Composite Streams

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.

Unary messages

Streams support most of the unary messages defined in AbstractFunction :

Binary messages

Streams support the following binary messages defined in AbstractFunction :

Class Methods

Inherited class methods

Instance Methods

.play(clock, quant)

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.

Arguments:

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).

.do(function, inval)

iterate until a nil is encountered.

WARNING: Applying do to an endless stream will lock up the interpreter!

.collect(argCollectFunc)

iterate indefinitely.

.reject(function)

return only those elements for which function.value(element) is false.

.select(function)

return only those elements for which function.value(element) is true.

.dot(function, stream)

return function.value(this.next, stream.next) for each element.

.interlace(function, stream)

iterate all of stream for each element of this. Combine the values using function.

.appendStream(stream)

append stream after this returns nil. The same like ++

.embedInStream(inval)

iterate all of this from within whatever Stream definition it is called.

.trace(key, printStream, prefix: "")

print out the results of a stream while returning the original values.

Arguments:

key

when streaming events, post only this key.

printStream

printOn this stream (default: Post).

prefix

string added to the printout to separate different streams.

Inherited instance methods

Undocumented instance methods

++(stream)

<>(obj)

.all(inval)

.asEventStreamPlayer(protoEvent)

.buildForProxy

From extension in /SuperCollider/Contents/Resources/SCClassLibrary/JITLib/ProxySpace/wrapForNodeProxy.sc

.collate(stream)

.composeBinaryOp(argSelector, argStream, adverb)

.composeNAryOp(argSelector, anArgList)

.composeUnaryOp(argSelector)

.fastForward(by, tolerance: 0, inevent)

From extension in /SuperCollider/Contents/Resources/SCClassLibrary/JITLib/Patterns/extRoutine.sc

.generate(function, item)

.iter

.next

.parent

.proxyControlClass

From extension in /SuperCollider/Contents/Resources/SCClassLibrary/JITLib/ProxySpace/wrapForNodeProxy.sc

.put(item)

.putAll(aCollection)

.putN(n, item)

.repeat(repeats: inf)

.reverseComposeBinaryOp(argSelector, argStream, adverb)

.rewriteString(rules, level: 1, contextSize, parseRules: true, contextFree)

From extension in /Library/Application Support/SuperCollider/downloaded-quarks/MathLib/classes/LazyLindenmayer/extStringRewrite.sc

.setConvert

From extension in /Library/Application Support/SuperCollider/downloaded-quarks/MathLib/classes/patterns/extSetPattern.sc

.skipNextN(n, inval)

From extension in /Library/Application Support/SuperCollider/downloaded-quarks/FileLog/extStream.sc

.streamArg

.subSample(offset: 0, skipSize: 0)

.value(inval)

.valueArray