Choosing a Value

To properly set a parameter's value, you need to know the range of values that are meaningful to the object that applies it. The MusicKit parameter lists given in Appendix B supply this information. If you're creating an application (or writing a scorefile) in order to synthesize MKNotes on the DSP or on an external MIDI synthesizer, you should consult these lists to make sure you're setting the MKNotes' parameters to reasonable and musically useful values.

Three of the most commonly used parameters, those for pitch, begin time, and duration, are special. See the Section called Basic Parameters, later in this chapter, for a discussion of alternative ways to set and retrieve the values of these parameters.

Object-Valued Parameters

Some parameters take objects as their values. The methods for setting an object-valued parameter are:

• setPar:toEnvelope: sets the value as an MKEnvelope object.

• setPar:toWaveTable: sets the value as a MKWaveTable object.

• setPar:toObject: sets the value as a non-MusicKit object.

MKEnvelopes and MKWaveTables are described later in this chapter. The setPar:toObject: method is provided so you can set a parameter to an instance of one of your own classes. The class that you define should implement the following methods so its instances can be written to and read from a scorefile:

• writeASCIIStream: provides instructions for writing the object as ASCII text. In a scorefile, the text that represents an object―this includes MKEnvelopes and MKWaveTables―is enclosed in square brackets ([]). The ASCII representation of an object must not include a close bracket. The method's argument is the NSMutableData to which the text is written.

• readASCIIStream: provides instructions for creating an object from its ASCII representation. When the method is called, the argument (an NSMutableData) is pointing to the first character after the open bracket. You should leave the argument pointing to the close bracket. In other words, you should read in whatever you wrote out.

Both of these methods are called automatically when you read a scorefile into your application (scorefile-reading methods are described later in this chapter).

You can retrieve an object-valued parameter through the following methods:

• parAsEnvelope: returns an MKEnvelope object.

• parAsWaveTable: returns a MKWaveTable object.

• parAsObject: returns a non-MusicKit object.

Unlike the value retrieval methods shown in the previous section, these methods return nil if the parameter's value isn't the correct type.

Pitch Variables

A pitch variable takes the following form:

pitchLetter[sharpOrFlat]octave

• pitchLetter is a lowercase letter from a to g. As in standard music notation, the Music Kit's pitch variables are organized within an octave such that c is the lowest pitch and b is the highest.

• The optional sharpOrFlat is s for sharp and f for flat. They raise or lower by a semitone the pitch indicated by pitchLetter.

• octave is 00 or an integer from 0 to 9. The octave component of the pitch name variable places the pitch class within a particular octave, where 00 is the lowest octave and 9 is the highest. Octaves are numbered such that c4 is middle C.

Some examples of pitch variables are:

Notice that the natural sign isn't represented in the pitch variables. If neither the sharp nor the flat sign is present, the pitch is automatically natural. In addition, key signatures aren't represented; the accidentals that define a key must be present in each pitch that they affect.

Correspondence Between Pitch Variables and Frequencies

Each pitch variable represents a predefined frequency. By default, the frequencies that correspond to the pitch variables define a twelve-tone equal-tempered tuning system, with a4 equal to 440.0 Hz:

• Twelve-tone means that there are twelve discrete tones within an octave.

• Equal-tempered means that the frequency ratio between any pair of successive tones is always the same.

This is the tuning system used to tune modern fixed-pitch instruments, most notably the piano. The complete table of pitch variables and the corresponding default frequencies is given in the Section called Pitches and Frequencies in Appendix A.

Key Numbers

Another way to specify the pitch is to use a key number. Key numbers are integers that correspond to the keys of a MIDI keyboard. As a MIDI standard, 60 is the key number for the middle C of the keyboard. The MusicKit provides constants to represent key numbers. The form of these constants is like that of the pitch variables, but with the letter k appended; for example:

Key numbers are provided primarily to accommodate MIDI instruments. If you record a MIDI performance (using a MKMidi object), the pitch specifications will all be represented as key numbers. When you realize MKNotes on a MIDI synthesizer, the actual frequency represented by a particular key number is controlled by the synthesizer itself. The standard of “60 equals middle C” simply means that key number 60 creates a tone at whatever frequency the synthesizer's middle C key is tuned to produce.

Specifying Pitch in a MKNote

You can specify the pitch of MKNote objects as a frequency or pitch variable (a double), or as a key number (an int). These are represented by the parameter tags MK_freq and MK_keyNum. Regardless of how it's synthesized (on the DSP or on a MIDI instrument), the appropriate value is converted from whichever parameter is present.

To set a MKNote's pitch, you use the methods described earlier:

/* You must import this file when using pitch variables. */
#import <MusicKit/pitches.h>

/* Set the MKNote's pitch to middle C as a frequency. */
[aNote setPar: MK_freq toDouble: 261.625];

/* The same using a pitch variable. */
[aNote setPar: MK_freq toDouble: c4];

/* And as a key number. */
[aNote setPar: MK_keyNum toDouble: c4k];

The conversion between frequencies or pitch variables and key numbers allows you to create MKNote objects that can be played on both the DSP and on a MIDI instrument using the same pitch parameter.

Retrieving Pitch from a MKNote

Special methods are provided to retrieve pitch:

• freq: returns a double value as a frequency.

• keyNum: returns an int as a key number.

If the MK_freq parameter isn't present but MK_keyNum is, the freq: method returns a frequency value converted from the MK_keyNum parameter. Similarly, keyNum: returns a key number value converted from MK_freq in the absence of MK_keyNum.

The MusicKit MKSynthPatches use freq: to retrieve pitch information; MKMidi uses keyNum:.

Keep in mind that either retrieval method converts a value from the opposite parameter only if its own parameter isn't set. In addition, you can set MK_freq and MK_keyNum independently of each other: Setting one doesn't reset the other.

Since frequencies are continuous and key numbers are discrete, the correspondence between them isn't exact; conversion from frequency to key number sometimes requires approximation. The pitch table in the Section called Pitches and Frequencies in Appendix A gives the frequency range that corresponds to particular key numbers (in the default tuning system).

Loudness

The perceived loudness of a musical note depends on a number of factors, the most important being the amplitude of the waveform and its spectral energy, or brightness. All the MusicKit MKSynthPatches use the amplitude parameter, MK_amp; most also use MK_bright, the brightness parameter.

Amplitude

Amplitude is fairly straightforward: The value of the amplitude parameter determines the strength of the signal produced by the DSP. The value of MK_amp is retrieved as a double. Its value must be between 0.0 and 1.0, where 0.0 is inaudibly soft and 1.0 is a fully saturated signal. Perceived amplitude increases logarithmically: Successive Notes with incrementally increasing amplitude values are perceived to get louder by successively smaller amounts. For instance, the difference in loudness between amplitudes of 0.1 and 0.2 sounds much greater than the difference between 0.8 and 0.9.

Amplitude is set and retrieved through the normal methods; for example:

/* Set the amplitude of a MKNote. */
[aNote setPar: MK_amp toDouble: 0.2];

/* Retrieve amplitude. */
double myAmp = [aNote parAsDouble: MK_amp];

/* Set the amplitude of a MKNote. */
[aNote setPar: MK_amp toDouble: MKdB(-15.0)];

The range of the decibel scale extends from negative infinity (inaudible) to 0.0 (maximally loud). Decibel scaling creates a linear correspondence between increasing value and perceived loudness: The perceived increase in loudness from -20.0 to -15.0 is the same as that from -15.0 to -10.0 (as well as from -10.0 to -5.0 and from -5.0 to 0.0).

Brightness

Brightness can be thought of as a tone control. The greater the value of MK_bright, the brighter the synthesized sound. As you decrease brightness, the sound becomes darker. MK_bright is used differently by the various MKSynthPatch subclasses; usually it's used to modify the values of other timbre-related parameters. Some MKSynthPatches, such as those that perform MKWaveTable synthesis, don't use MK_bright at all.

Brightness values are usually set and retrieved through setPar:toDouble: and parAsDouble: (the MusicKit MKSynthPatches always retrieve the value of MK_bright as a double). The range of valid brightness values is, in general, 0.0 to 1.0; you can actually set MK_bright to a value in excess of 1.0, although this may cause distortion in some MKSynthPatches. Specifying brightness in decibels is possible, but the scale tends to have less meaning here than it does for amplitude.

Scale and Offset

Associated with each MKEnvelope parameter provided by the MusicKit are two related parameters that interpret the MKEnvelope's y values. The names of these parameters are formed as MK_attribute0 and MK_attribute1:

• MK_attribute0 is the value of the MKEnvelope when y is 0.0.

• MK_attribute1 is the value of the MKEnvelope when y is 1.0. As a convenience, the parameter MK_attribute is defined as a synonym for MK_attribute1.

The parameters that interpret the amplitude MKEnvelope, for example, are MK_amp0 and MK_amp1(which is synonymous with MK_amp). Since amplitude should always rise from and fall back to 0.0 (to avoid clicks), you'll probably never need to set the value of MK_amp0―if the parameter isn't set, its value defaults to 0.0. The amplitude MKEnvelope is normally interpreted by setting the value of MK_amp (only):

/* Set the amplitude MKEnvelope (as previously defined). */
[aNote setPar: MK_ampEnv toEnvelope: anEnvelope];

/* The value of MK_amp sets the value when y is 1.0. */
[aNote setPar: MK_amp toDouble: 0.15];

During synthesis, aNote's amplitude is scaled according to the value of MK_amp, as depicted in Figure 4-4 (notice that the breakpoint values themselves don't change, only their interpretations are affected).

Technically, the interpretation of a particular value of y is calculated according to the following formula:

interpretedValue = (scale* y) + offset

where scale is calculated as MK_attribute1 - MK_attribute0 and offset is simply the value of MK_attribute0.

The Stickpoint

When a MKSynthPatch receives a noteOn or noteDur, it starts processing the MKNote's MKEnvelopes, reading their breakpoints one by one. The y values are scaled and offset as described above; the x values are taken as seconds (with modifications described in the next section). If the MKNote's duration (in seconds) is greater than the duration of the MKEnvelope―in other words, if the MKEnvelope runs out of breakpoints before the DSP is done synthesizing the MKNote―then the final y value is maintained for the balance of the MKNote.

To accommodate MKNotes of different lengths, the MKEnvelope object lets you define one of its breakpoints as a stickpoint. When the MKSynthPatch reads an MKEnvelope's stickpoint, it “sticks” until a noteOff arrives (or the declared duration of a noteDur elapses). The MKEnvelope shown in the previous example, with its flat middle section, can easily be redefined using a stickpoint, as follows:

/* Instantiate arrays for x and y. */
double xVals = {0.0, 1.0, 2.0};
double yVals = {0.0, 1.0, 0.0};

/* Define the MKEnvelope and set the MK_amp constant. */
[anEnvelope pointCount: 3 xArray: xVals yArray: yVals];
[aNote setPar: MK_amp toDouble: 0.15];

/* Set the MKEnvelope's stickpoint. */
[anEnvelope setStickpoint: 1];

The argument to setStickpoint: is a zero-based index into the MKEnvelope's breakpoints. In the example, anEnvelope's second breakpoint is declared to be the stickpoint. Figure 4-5 shows how the stickpoint allows the same MKEnvelope to be applied to MKNotes (or MKNote phrases) with different durations. The stickpoint is shown as a solid circle; the sustained portion of the MKEnvelope is indicated as a dashed line. The tempo in the illustration is assumed to be 60.0.

Notice that the duration between the end of the stickpoint segment and the following breakpoint is always the same (one second, as defined by the MKEnvelope itself), regardless of the length of the MKNote.

Attack and Release

An MKEnvelope object is divided into three parts: attack, sustain, and release. The stickpoint defines the sustain; the attack is the portion that comes before the stickpoint and the release is the portion that comes after it. An MKEnvelope can have any number of breakpoints in its attack and release segments.

You can specify the absolute duration of the attack portion of an MKEnvelope by setting the value of the MK_attributeAtt parameter; the release is set through MK_attributeRel. For example, the amplitude attack and release parameters are MK_ampAtt and MK_ampRel, respectively. The values of these parameters are taken as the number of seconds (given as doubles) to spend in either segment, as illustrated in Figure 4-6. The x values of the breakpoints in the two segments are scaled within the given durations to maintain their defined proportions.

Since they're set as seconds (not beats), the attack and release times aren't affected by tempo.

Figure 4-7 shows the same (amplitude) MKEnvelope used in the previous examples with various attack and release values.

Figure 4-8 shows what happens when a noteOff arrives (or a noteDur expires) during the attack portion of the MKEnvelope―in other words, before the stickpoint is reached. For this illustration, both MK_ampAtt and MK_ampRel are assumed to have values of 1.0.

When the noteOff arrives, the MKEnvelope heads for the first breakpoint in the release (the first breakpoint after the stickpoint) from wherever it happens to be at the time. The release takes its full duration (as defined in the MKEnvelope itself, or by MK_ampRel, if present) regardless of whether the noteOff arrives before or after the stickpoint is reached.

Modeling a MKNote without Sustain

Not every instrument can create a sustained tone; the amplitude envelope of a piano tone, for example, is characterized by a sharp rise and fall followed by a gradual but steady decay to quiescence. This is depicted in Figure 4-9.

To simulate this sort of envelope shape, yet still accommodate MKNotes of any length, the MKEnvelope object definition would look something like this:

double xVals = {0.0, 0.05, 0.2, 0.5, 8.0, 8.15};
double yVals = {0,0, 1.0, 0.5, 0.3, 0.0, 0.0};
[anEnvelope setPointCount:6 xArray:xVals yArray:yVals];

/* Set the stickpoint to breakpoint 4, xy:(8.0, 0.0). */
[anEnvelope setStickpoint:4];

The MKEnvelope is depicted in Figure 4-10

Notice that the MKEnvelope's stickpoint is, curiously enough, set to a breakpoint that has a y value of 0.0. Equally curious is the release portion of the MKEnvelope: a flat piece of seemingly useless real estate. However, consider the result of the two possible scenarios:

• The noteOff arrives after the stickpoint is reached. In this case, the synthesized sound has already decayed to an amplitude of 0.0. When the noteOff arrives, the release portion is indeed executed, but since the amplitude is already at 0.0, the release portion doesn't produce an audible effect.

• The noteOff arrives before the stickpoint is reached. The release portion is triggered, causing the amplitude to decay to 0.0 in 0.15 seconds.

Attack and release durations on a nonsustaining instrument are generally invariant, so you would rarely set the MK_ampAtt and MK_ampRel parameter.

Portamento

The MusicKit provides an additional parameter, MK_portamento, with which you can further manipulate your MKEnvelopes' attack times. Like the MK_attributeAtt parameters, MK_portamento takes a double value that's measured in seconds, but rather than affect the entire attack portion, it sets the duration between the first two breakpoints only. Also, as used by the MKSynthPatches provided by the Music kit, MK_portamento affects all the MKEnvelopes in a MKNote―there aren't individual portamento parameters for amplitude, frequency, and so on. In a MKNote that contains a portamento value and one or more attack scalers, the attacks of the individual MKEnvelopes are scaled before the value of MK_portamento is applied.

MK_portamento is provided so you can easily and quickly control, to some degree, the rearticulation of a MKNote's MKEnvelopes. As such, it's only significant in a MKNote that rearticulates a phrase―it's ignored in a noteDur with no note tag, and has no immediate effect in a noteOn or a noteDur with a previously inactive note tag (although, in the latter case, the value of MK_portamento is stored in anticipation of subsequent rearticulations).

You should keep in mind that portamento is optional. It can be quite useful if you're modelling an instrument that has different attack characteristics depending on whether a MKNote is the beginning of a new phrase or part of a legato passage. For example, in some instruments, such as a horn, the attack of an initial musical note―in amplitude, frequency, and timbre―is more drawn out than in the subsequent notes of a phrase. To simulate such an instrument, it's convenient to use MK_portamento to affect all the MKEnvelopes at once.

Smoothing

The previous examples have shown the lines that connect an MKEnvelope's breakpoints as straight segments. In reality, as synthesized by the DSP, these segments follow an asymptotic curve. In an asymptotic curve, the target is never fully reached―the curve rises (or falls) in successively smaller steps as it approaches the target. However, there's a point in the curve where the target is perceived to have been attained. This point is controlled by the smoothing value.

By default, smoothing is 1.0, a value that's used to mean that the point at which the target is perceived to have been reached is equal to the difference between the x values in successive breakpoints; in other words, it takes the entire time between breakpoints to reach the target y value. Other values are, similarly, the ratio of curve duration to overall duration between a pair of breakpoints. For example, a smoothing of 0.5 means it takes half the time between a pair of breakpoints to (perceptually) complete the curve between the breakpoints' y values. A smoothing value in excess of 1.0 falls short of the target altogether (it takes longer than the allotted time to reach the target).

You can set the smoothing value for each breakpoint by defining the MKEnvelope through an alternative method:

setPointCount:xArray:orSamplingPeriod:yArray:

smoothingArray:orDefaultSmoothing:

Smoothing is set as either an array of values (one for each breakpoint) passed to as the argument to the smoothingArray: keyword, or as a default value passed as the argument to the orDefaultSmoothing: keyword. The default smoothing is used only if the argument to smoothingArray: is NULL.

Smoothing is, admittedly, a somewhat elusive concept, best explained by illustration. Figure 4-11 shows the shape of an MKEnvelope that uses various smoothing values between successive breakpoints. The values in parentheses are the x, y, and smoothing values for each breakpoint.

Notice that the smoothing value is omitted from the first breakpoint. While a smoothing value must be supplied as the first element in the smoothing array (if you use the smoothingArray: keyword), this value is actually ignored when the MKEnvelope is synthesized. This is because a breakpoint's smoothing value applies to the curve leading into it―the curve from the previous breakpoint to the current one. Since there isn't a previous breakpoint before the first one, the smoothing value for breakpoint 0 is thrown away.

Returning to the illustration, the smoothing value for the second breakpoint is 1.0; thus the curve leading from the first breakpoint into the second breakpoint takes up the entire duration between the two points. The smoothing value for the third break point is 0.2; the curve leading into the third breakpoint reaches the target y value with time to spare. The fourth breakpoint has a smoothing of 0.0. This means that it takes no time to reach the target; the MKEnvelope immediately leaps to the target y value. (Note that a smoothing of 0.0 is the only way to ensure that the asymptotic curve will, in truth, reach its target.) The final breakpoint smoothing value is 0.5. Accordingly, the curve reaches the target halfway between breakpoints.

While smoothing control is provided for completeness, most musical applications will be satisfied with the default smoothing provided by the setPointCount:xArray:yArray: method.

Sampling Period

You may have noticed that the MKEnvelope definition method that brought you smoothing also introduced an alternate way to set an MKEnvelope's x values. Rather than define x values in an array, you can also set them as a default increment by passing a (double) value to the method's orSamplingPeriod: keyword. Again, the default argument is used only if the array argument (in this case, the argument to xArray:) is NULL.

If you use a sampling period, the first x value is always 0.0. Successive x values are integer multiples of the sampling period value.

The MKPartials Class

You define a MKPartials object by supplying the frequency, amplitude, and phase information for a series of partials. This is done through the method setPartialCount:freqRatios:ampRatios:phases:orDefaultPhase:. The first argument is the number of partials; the next three arguments are arrays of double data that specify the frequency ratios, amplitude ratios, and initial phases of the partials, respectively. You can also set the phase as a constant by passing a double as the argument to the orDefaultPhase: keyword. In this case, you must pass NULL as the argument to phases:.

In the following example, a waveform is created from a series of partials that are integer multiples of a fundamental frequency; the partials decrease in amplitude as they increase in frequency.

/* Create the MKPartials object. */
MKPartials *aPartials = [MKPartials new];
double freqs[] = {1.0, 2.0, 3.0, 4.0, 5.0, 6.0};
double amps[] = {1.0, 0.5, 0.25, 0.12, 0.06, 0.03};

/* Fill the object with data. */
[aPartials setPartialCount: 6
                freqRatios: freqs
                 ampRatios: amps
                    phases: NULL
            orDefaultPhase: 0.0];

Phase is generally unimportant in creating musical timbres, although it can drastically affect a waveform that's used as a low-frequency control signal, such as vibrato.

The frequencies in a MKPartials object are specified as ratios, or multiples, of a fundamental frequency (the fundamental is represented by a frequency ratio of 1.0). The actual (fundamental) frequency of the waveform created from a MKPartials depends on the how the object is used by the MKSynthPatch that synthesizes it. In general, the waveform is “transposed” to produce the frequency specified in a MKNote's frequency parameter, MK_freq. Similarly, the amplitude of each partial is relative to the value of another parameter, usually MK_amp.