Some of the examples in the last tutorial played notes using Pbind, and you might be wondering how it works in general and what else you can do with it.
In the most general sense, Pbind is just a way to give names to values coming out of the types of patterns we just saw. When you ask a Pbind stream for its next value, the result is an object called an Event. Like a Dictionary (which is a superclass of Event), an event is a set of "key-value pairs": each value is named by a key.
A Pbind is defined by a list of pairs: keys associated with the patterns that will supply the values for the events.
Things get interesting when the names associated with Pbind's sub-patterns are also SynthDef arguments. Then it becomes possible to play new Synths with Pbind, and feed their inputs with different values on each event.
We can look at the return values from a Pbind by calling
next on the stream. Note that it's necessary to pass an empty event into next, so that Pbind has somewhere to put the values.
The return events show us what Pbind really does. Each time the next value is requested, it goes through each key-pattern pair and gets the next value from each pattern (actually streams, but Pbind makes streams out of the sub patterns internally). Each value gets put into the event, using the associated key.
For the first event, the first key is
'degree' and the value is
0. This is placed into the event before moving to the next pair: the event in transition contains
( 'degree': 0 ). Then the next key supplies
'dur', and since there are no more pairs, the event is complete:
( 'degree': 0, 'dur': 0.5 ).
// User does:
// SuperCollider processes:
\degree stream returns
( 'degree': 0 )
\dur stream returns
( 'degree': 0, 'dur': 0.5 )
So far we haven't seen anything that produces a note, just data processing: fetching values from patterns and stitching them together into events. The notes come from the difference between Events and regular Dictionaries: Events can do things when you
The action that the event will take is defined in an "event prototype." The prototype must include a function for the
'play' key; this function is executed when
.play is called on the event. Also, optionally the prototype can contain default values for a wide variety of parameters.
Pbind doesn't do much without an event prototype. Fortunately, you don't have to write the prototype on your own. There is a default event, accessed by
Event.default, that includes functions for many different server-messaging tasks. If no specific action is requested, the normal action is to play a Synth. That's why playing a Pbind, as in the previous tutorial, with only
'dur' patterns produced notes: each event produces at least one synth by default, and the default event prototype knows how to convert scale degrees into frequencies and
'dur' (duration) into note lengths.
When a pattern is played, an object called EventStreamPlayer is created. This object reads out the events one by one from the pattern's stream (using a given event prototype as the base), and calls
play on each. The
'delta' value in the event determines how many beats to wait until the next event. Play continues until the pattern stops producing events, or you call .stop on the EventStreamPlayer. (Note that calling
.stop on the pattern does nothing. Patterns are stateless and cannot play or stop by themselves.)
- To sum up so far : A Pbind's stream generates Events. When an Event is played, it does some work that usually makes noise on the server. This work is defined in an event prototype. The Event class provides a default event prototype that includes powerful options to create and manipulate objects on the server.
Rests may be indicated in three ways.
A more complete discussion is found in the Rest help file.
Pbind plays separate notes by default. Sometimes, you might need a pattern to act more like a monophonic synthesizer, where it plays just one Synth node and changes its values with each event. If Pbind normally corresponds to
/s_new, Pmono corresponds to
Compare the sound of these patterns. Pbind produces an attack on every note, while Pmono glides from pitch to pitch.
Articulating phrases is possible with Pmono by chaining several Pmono patterns together in a row, or by using PmonoArtic.
Most SynthDefs have Control inputs, usually defined by arguments to the UGen function. For example, the default SynthDef (declared in Event.sc) defines five inputs:
When an event plays a synth, any values stored in the event under the same name as a SynthDef input will be passed to the new synth. Compare the following:
This leads to a key point: The names that you use for patterns in Pbind should correspond to the arguments in the SynthDef being played. The Pbind pattern names determine the names for values in the resulting Event, and those values are sent to the corresponding Synth control inputs.
The SynthDef to play is named by the
'instrument' key. To play a pattern using a different Synth, simply name it in the pattern.
It's actually an oversimplification to say that the Pbind names should always match up to SynthDef arguments.
'degree' to specify pitch, but the default SynthDef being played does not have a degree argument. It works because the default event converts degree into
'freq', which is an argument. The most important conversions are for pitch and timing. Timing is simple; pitch is more elaborate. See Pattern Guide 07: Value Conversions for an explanation of these automatic calculations.
Don't send or load SynthDefs; use .add or .store instead
To send only the relevant values to the new Synth, the Event needs to know what controls exist in the SynthDef. This is done by a library of descriptors for SynthDefs; the descriptor is a SynthDesc, and the library is a SynthDescLib. The normal methods --
.load(s) -- to communicate a SynthDef to the server do not enter it into the library. As a result, SynthDefs sent this way will not work properly with Pbind. Instead, use different methods that store the SynthDef into the library.
.load(s) --> .store
.send(s) --> .add
Beginning with version 3.5, rests may be indicated using instances of Rest.
Rest(0.5), and will pass transparently through calculations.
Rest(0). Rest objects now support math operators. That is, you can now write
Pseq([1, 2, Rest(0)], inf) * 2 and
[1, 2, Rest(0)] * 2. (Prior to 3.9, the former usage was supported, but only in Pbind, and the latter usage was not supported at all.)
The older convention for rests is to set the
\freq key to a Symbol. Commonly this is
\rest, but a backslash by itself is enough to suppress the note on the server. (This usage is still supported, but not recommended because it is limited to pitch-related keys only.)
If it's the
\freq key that determines whether the event as a rest or not, why does it work to use it with
\note? As noted, keys like
\midinote are automatically converted into frequency. The math operations that perform the conversion preserve Symbols intact -- e.g.,
\rest + 1 == \rest . So the
\rest value is passed all the way through the chain of conversions so that
\freq in the event ends up receiving
Note that it doesn't matter if the SynthDef has a
freq argument. It's the event, on the client side, that looks to this key to determine whether to play the note or not. If it is a rest, the server is not involved at all.
SynthDefs should have a couple of specific features to work well with patterns.
The default event prototype relies on the synth to remove itself from the server when it's finished. This can be done in several ways:
doneAction ( >= 2) in the envelope generator (see Done for a complete list). The
\harpsi SynthDef above uses this technique. A gated envelope specifies a release node or uses one of the predefined sustaining envelope types:
Env.dadsr. The Env help file offers more detail on gated envelopes.
Linen.kr, which is a shortcut for
EnvGen.kr(Env([0, susLevel, 0], [attackTime, releaseTime], \lin, releaseNode: 1), gate, doneAction: [2 or higher]). The default SynthDef uses this. The
doneAction should be at least 2 to release the node.
gate; standard event prototypes expect to be able to control the synth's release using this argument. Also, make sure the gate's default value is greater than 0. Otherwise, the envelope will never start and you will both hear nothing and watch synths pile up on the server.
One other subtle point about synth argument names. In a SynthDef, argument names can have the prefix
t_ to indicate a "trigger control," or
i_ for an "initial rate" control (meaning that it holds the value set when the Synth is first played). This is described in SynthDef help. Pbind and its cousins should leave out the prefixes, e.g.:
Previous: Pattern Guide 02: Basic Vocabulary