Data-Conduit Reference

Introduction

Orchestras have instruments. Instruments have units. Units typically have many inputs and one output. An argument is an expression which either tells an input from where it should draw data or tells an output to where it should transmit data. Each argument of a unit links to some conduit.

Data conduits are the means of directing data between the various signal-processing components that make up an orchestra. The scope of a data conduit identifies which orchestral components can access information from the conduit. The Sound engine implements three levels of scope:

• A conduit has global scope if every component of the orchestra can reference it. This scope applies only to System Variables, which are all statically defined.
• A conduit has instrument-level (local) scope if it is declared within an instrument. Only units of the same instrument, playing the same note, can access a local conduit.
• A conduit has voice-level (intermediate) scope if it is declared in association with a voice. Data conduits scoped at a voice level can be shared between instruments, so long as the instruments operate under a common voice.

Depending on its type, a conduit may hold either a single double-precision value or a sequence of double-precision values. Single-valued conduits include constants and variables. These are sometimes known (e.g. by Barry Vercoe) as scalars. Multivalued conduits are most commonly known as signals; but are also known as vectors as vectors. Within the Sound engine, contours are to signals what constants are to variables.

A word about “control-rate” signals and why I chose not to implement them within the Sound engine. Control-rate signals were implemented by Barry Vercoe's Music11, and have since carried over into Music11's platform-independent successor, CSound. Control-rate signals act functionally like audio-rate signals, but their values are calculated at a much slower rate. When I attended Vercoe's summer workshop in 1978 I thought control-rate processing was a really neat idea. I effused about it to Vercoe, but Vercoe cooled me down for this reason: Control values (for example in envelopes) change in small steps, and each step introduces a small discontinuity (i.e. click) into the generated output. So ultimately when you go about generating your finished wave file, you end up bumping the control rate up to the audio rate.

Constants

Constants are read-only and local to unit arguments. Constants are explicit double-precision values. A unit may never output to a constant.

System Variables

System variables are single read-only values of global scope. System variables access values from the Sound engine. Seven system variables are presently defined:

• SR provides access to the sample rate.
• NYQUIST (after the Nyquist frequency) is calculated as the sample rate divided by 2.
• SEMITONE returns the 12th root of 2.
• CENT returns the 1200th root of 2.
• MONO_OUTPUT returns 0. Reference this system variable in the channel argument to the Output unit when the channel count is 1.
• STEREO_LEFT returns 0. Reference this system variable in the channel argument to the Output unit when the channel count is 2.
• STEREO_RIGHT returns 1. Reference this system variable in the channel argument to the Output unit when the channel count is 2.
• PI returns the ratio of a circle's circumference to its diameter, approximately 3.14159.
• E returns Euler's constant, approximately 2.71828.
• GOLDEN returns an approximation of the Golden Ratio. The approximation is 1.6180339887.

Note Parameters

Parameters are single read-only values scoped to instruments. Parameters are are drawn from note statements in a note list.

Instrument Variables

Variables are single read/write values scoped to instruments. Variables must be calculated by one unit for use by later units in the same instrument. Two conditions apply:

• A unit may not consume a variable which is not an output of an earlier unit.
• Likewise, if a unit outputs to a variable, that variable must be consumed by a later unit.

Instrument Signals

Instrument Signals are read/write value sequences scoped to instruments. Two conditions apply:

• A unit may not consume an instrument-level signal which is not an output of an earlier unit.
• Likewise, if a unit outputs to an instrument-level signal, that signal must be consumed by a later unit.

Voice Signals

Voice Signals are read/write value sequences scoped to voices. A target note can only receive information from a source note through a voice-level signal if certain conditions are met.

• In all instances, the source and target notes must both reference the voice to which the signal belongs.
• One of two additional conditions must also apply.
  • Signal data may be transmitted if the target note has a larger instrument ID than the source note.
  • Alternatively, the source and target notes may share the same instrument ID, so long as the target note ID is larger than the source note ID.

If an instrument consumes a voice-level signal that was not previously the output of an earlier process, then the values in the signal default to zero.

The note-list compiler presently does not detect unconsumed voice-level signals, but such is clearly not good practice.

Contours

Contours are read-only value sequences scoped to voices. Contour values are drawn from ramp statements in a note list. A note can only receive information from a contour if the note references the voice to which the signal belongs. A unit may never output to a contour.