Pattern is an abstract class that is the base for the Patterns library. These classes form a rich and concise score language for music. The series of help files entitled Understanding Streams, Patterns and Events - Part 1 gives a detailed introduction. This attempts a briefer characterization.
A Stream is an object that responds to
embedInStream. Streams represent sequences of values that are obtained one at a time by with message
reset message will cause the stream to restart (many but not all streams actually repeat themselves.) If a stream runs out of values it returns
nil in response to
next. The message
embedInStream allows a stream definition to allow another stream to "take over control" of the stream. All objects respond to
reset, most by returning themselves in response to next. Thus, the number 7 defines a Stream that produces an infinite sequence of 7's. Most objects respond to
embedInStream with a singleton Stream that returns the object once.
A Pattern is an object that responds to
embedInStream. A Pattern defines the behavior of a Stream and creates such streams in response to the messages
asStream. The difference between a Pattern and a Stream is similar to the difference between a score and a performance of that score or a class and an instance of that class. All objects respond to this interface, most by returning themselves. So most objects are patterns that define streams that are an infinite sequence of the object and embed as singleton streams of that object returned once.
Patterns are defined in terms of other Patterns rather than in terms of specific values. This allows a Pattern of arbitrary complexity to be substituted for a single value anywhere within a Pattern definition. A comparison between a Stream definition and a Pattern will help illustrate the usefulness of Patterns.
The Pattern class Pseq(array, repetitions) defines a Pattern that will create a Stream that iterates an array. The class Routine(func, stackSize) defines a single Stream, the function that runs within that stream is defined to perform the array iteration.
Below a stream is created with Pseq and an
asStream message and an identical stream is created directly using Routine.
In example 1, there is little difference between using Pseq and Routine. But Pseq actually iterates its array as a collection of patterns to be embedded, allowing another Pseq to replace any of the values in the array. The Routine, on the other hand, needs to be completely redefined.
embedInStream is what allows Patterns to do this kind of nesting. Most objects (such as the number 3 below) respond to
embedInStream by yielding themselves once and returning. Streams respond to embedInStream by iterating themselves to completion, effectively "taking over" the calling stream for that time.
A Routine can perform a pattern simply by replacing calls to
yield with calls to
Of course, there is no concise way to define this stream without using Pseq.
embedInStreamassumes that it is called from within a Routine. Consequently,
embedInStreamshould never be called from within the function that defines a FuncStream or a Pfunc (the pattern that creates FuncStreams).
An Event is a Environment with a 'play' method. Typically, an Event consists of a collection of key/value pairs that determine what the play method actually does. The values may be any object including functions defined in terms of other named attributes. Changing those values can generate a succession of sounds sometimes called 'music'... The pattern Pbind connects specific patterns with specific names. Consult its help page for details.
The -play method does not return the pattern itself. Instead, it returns the EventStreamPlayer object that actually runs the pattern. Control instructions -- stop, pause, resume, play, reset -- should be addressed to the EventStreamPlayer. (The same pattern can play many times simultaneously, using different EventStreamPlayers.)
Patterns may be recorded in realtime or non-realtime. See the method -record for realtime recording.
For non-realtime recording see the Score helpfile, especially "creating Score from a pattern." It can be tricky, because NRT recording launches a new server instance. That server instance is not aware of buffers or other resources loaded into the realtime server you might have been using for tests. The pattern is responsible for (re)loading any resources (buffers, effects etc.). Pfset or Pproto may be useful.
Return a Stream from this pattern. One pattern can be used to produce any number of independent streams.
The inval is passed into all substreams and can be used to control how they behave from the outside.
The tempo clock that will run the pattern. If omitted, TempoClock.default is used.
The event prototype that will be fed into the pattern stream on each iteration. If omitted, event.default is used.
see the Quant helpfile.
Opens a disk file for recording and plays the pattern into it.
Disk location for the recorded file. If not given, a filename is generated for you and placed in the default recording directory:
Sample format, defaults to Server: -recSampleFormat.
Number of channels to record, default 2.
How long to run the pattern before stopping. If nil (default), the pattern will run until it finishes on its own; then recording stops. Or, use cmd-period to stop the recording. If a number is given, the pattern will run for that many beats and then stop (using Pfindur), ending the recording as well.
How many beats to allow after the last event before stopping the recording. Default = 0.2.
Which clock to use for play. Uses TempoClock.default if not otherwise specified.
Which event prototype to use for play. Falls back to Event.default if not otherwise specified.
Which server to play and record. Server.default if not otherwise specified.
Output bus to hear the pattern while recording, default = 0.
the number of out channels to play to the recorder. If larger than numChannels, outNumChannels will wrap .
Abbreviation for asEventStreamPlayer
Plays a pattern wrapped into a PsymNilSafe. Args clock, protoEvent and quant are passed to Pattern: -play, dict and maxNull work like with PsymNilSafe, dict defaults to the current Environment and maxNull to 128. See PLx and live coding with Strings
Wraps the receiver into a Pcollect with a Function that replaces according to EventShortcuts if it's turned on. This can be useful in cases where a pattern's method embedInStream changes keys of Events before applying the event type function, that employs the normal replacement mechanism of EventShortcuts. Then the mapping can be done inside/before. Normally you wouldn't need to call that method explicitely. See also EventShortcuts, Event: -eventShortcuts, SequenceableCollection: -eventShortcuts and PLx and live coding with Strings
Below are brief examples for most of the classes derived from Pattern. These examples all rely on the patterns assigned to the Interpreter variable p, q, and r in the first block of code.