#import <MKTuningSystem.h>
Public Member Functions | |
| (id) | - init |
| Initializes receiver to 12-tone equal tempered tuning. | |
| (id) | - copyWithZone: |
| Creates and returns a new MKTuningSystem as a copy of the receiver. | |
| (void) | - setTo12ToneTempered |
| Sets the receiver's tuning to 12-tone equal-tempered at A = 440Hz. | |
| (id) | - install |
| Installs the receiver's tuning as the current tuning system. | |
| (int) | - keyCount |
| Returns the number of "keys" (tunable elements) in a tuning system. | |
| (double) | - freqForKeyNum: |
| Returns the receiver's frequency for the key number aKeyNum. | |
| (id) | - setKeyNum:toFreq: |
| Tunes the receiver's aKeyNum key number to freq and returns the receiver. | |
| (id) | - setKeyNumAndOctaves:toFreq: |
| Tunes all the receiver's key numbers with the same pitch class as aKeyNum to octaves of freq such that aKeyNum is tuned to freq. | |
| (void) | - transpose: |
| Transposes the receiver by semitones half-steps (the half-step used here is 12-tone equal-tempered). | |
Static Public Member Functions | |
| (MKTuningSystem *) | + tuningSystem |
| Creates a MKTuningSystem object and tunes it to the installed tuning system. | |
| (NSString *) | + pitchNameForKeyNum: |
| Return formatted pitch name given a key number. | |
| (double) | + freqForKeyNum: |
| Returns the installed frequency for the key number aKeyNum. | |
| (MKKeyNum) | + keyNumForFreq:pitchBentBy:bendSensitivity: |
| Returns keyNum (pitch index) of closest pitch variable to the specified frequency. | |
| (id) | + setKeyNum:toFreq: |
| Tunes the installed tuning system's aKeyNum key number to freq and returns the receiver. | |
| (id) | + setKeyNumAndOctaves:toFreq: |
| Tunes the key numbers in the installed tuning system that are the same pitch class as aKeyNum to octaves of freq such that aKeyNum is tuned to freq. | |
| (void) | + transpose: |
| Transposes the installed tuning system by semitones half-steps. | |
| (int) | + findPitchVar: |
| Returns keyNum corresponding to the specified pitch variable or MAXINT if none. | |
Protected Attributes | |
| NSMutableArray * | frequencies |
The method -setFreq:forKeyNum: establishes a frequency/key number correspondence, defining the frequency value (in Hertz) for a specified key number. To tune a key number and its octaves at the same time, invoke the method setFreq:forKeyNumAndOctaves:. The frequencies in a MKTuningSystem object don't have to increase as the key numbers increase - you can even create a MKTuningSystem that descends in pitch as the key numbers ascend the scale. The freqForKeyNum: method retrieves the frequency value of the argument key number. Such values are typically used to set the frequency of a MKNote object:
[aNote setPar: MK_freq
toDouble: [aTuningSystem freqForKeyNum: c4k]];
The MKTuningSystem class maintains a master system called the installed tuning system. By default, the installed tuning system is set to 12-tone equal-temperament with A above middle C set to 440 Hz. A key number that doesn't reference a MKTuningSystem object takes its frequency value from the installed tuning system. The frequency value of a pitch variable is also taken from the installed system. The difference between key numbers and pitch variables is explained in the section entitled Representing Music Data. The entire map of key numbers, pitch variables, and frequency values in the default 12-tone equal-tempered system is given in the section entitled Music Tables.
You can install a tuning system by sending the install message to a MKTuningSystem object. Keep in mind that this doesn't install the object itself, it simply copies its key number-frequency map. Subsequent changes to the object won't affect the installed tuning system (unless you again send the object the install message).
Note that while key numbers can also be used to define pitch for MKNotes used in MIDI performance, the MKTuningSystem object has no affect on the precise frequency of a MKNote sent to a MIDI instrument. The relationship between key numbers and frequencies on a MIDI instrument is set on the instrument itself. (An application can, of course, use the information in a MKTuningSystem object to configure the MIDI instrument).
| + (MKTuningSystem *) tuningSystem |
Creates a MKTuningSystem object and tunes it to the installed tuning system.
Tuning the returned object won't affect the installed MKTuningSystem.
| - (id) init |
Initializes receiver to 12-tone equal tempered tuning.
| - (id) copyWithZone: | (NSZone *) | zone |
| - (id) install |
Installs the receiver's tuning as the current tuning system.
The receiver itself isn't installed, only its tuning system; subsequent changes to the receiver won't affect the installed system unless you resend the install message to the receiver.
| - (int) keyCount |
Returns the number of "keys" (tunable elements) in a tuning system.
| + (NSString *) pitchNameForKeyNum: | (int) | keyNum |
Return formatted pitch name given a key number.
Returns an NSString object containing the pitch name associated with the key number argument. The format of the string is the same as Scorefile pitch arguments.
| keyNum | is an int. |
| + (double) freqForKeyNum: | (MKKeyNum) | aKeyNum |
Returns the installed frequency for the key number aKeyNum.
Returns the frequency that corresponds to the given key number, based upon the mapping of key numbers to frequencies in the installed tuning system (see the MKTuningSystem class description for more information on the installed tuning system).
If aKeyNum is out of bounds (less than 0 or greater than 127), returns MK_NODVAL (Use MKIsNoDVal() to check for MK_NODVAL). The value returned by this method is the same value as aKeyNum's analogous pitch variable.
| aKeyNum | is a MKKeyNum. |
| - (double) freqForKeyNum: | (MKKeyNum) | aKeyNum |
Returns the receiver's frequency for the key number aKeyNum.
Returns the frequency that corresponds to the given key number, based upon the mapping of key numbers to frequencies in the installed tuning system (see the MKTuningSystem class description for more information on the instralled tuning system).
If aKeyNum is out of bounds, returns MK_NODVAL (Use MKIsNoDVal() to check for MK_NODVAL).
| aKeyNum | is a MKKeyNum. |
| + (MKKeyNum) keyNumForFreq: | (double) | freq | ||
| pitchBentBy: | (int *) | bendPtr | ||
| bendSensitivity: | (double) | sensitivity | ||
Returns keyNum (pitch index) of closest pitch variable to the specified frequency.
Returns the key number that most closely corresponds to the given frequency. The amount of pitch bend needed to temper the pitch of the key number in order to match the actual frequency is returned by reference in bendPtr. This value is computed using the sensitivity argument as the number of semitones by which the key number is tempered given a maximum pitch bend; in other words, you supply the maximum pitch bend by passing in a sensitivity value, and the function returns, in bendPtr, the amount of the bend that's needed. The value of bendPtr is a 14-bit MIDI pitch bend number; you would use it to set the value of a MKNote's MK_pitchBend parameter (assuming that you use sensitivity as value of the MKNote's MK_pitchBendSensitivity parameter).
Sensitivity is interpreted such that with a sensitivity of 1.0, a pitch bend of 0 gives a maximum negative displacement of a semitone and a bend of 0x3fff gives a maximum positive displacement of a semitone. Similarly, a value of 2.0 give a whole tone displacement in either direction. MIDI_ZEROBEND gives no displacement.
| freq | The frequency in Hz. | |
| bendPtr | If bendPtr is not NULL, *bendPtr is set to the bend needed to get freq in the context of the specified pitch bend sensitivity. | |
| sensitivity | The pitch bend sensitivity. |
| - (id) setKeyNum: | (MKKeyNum) | aKeyNum | ||
| toFreq: | (double) | freq | ||
Tunes the receiver's aKeyNum key number to freq and returns the receiver.
If aKeyNum is out of bounds, returns MK_NODVAL (Use MKIsNoDVal() to check for MK_NODVAL).
| aKeyNum | is a MKKeyNum. | |
| freq | is a double. |
| + (id) setKeyNum: | (MKKeyNum) | aKeyNum | ||
| toFreq: | (double) | freq | ||
Tunes the installed tuning system's aKeyNum key number to freq and returns the receiver.
If aKeyNum is out of bounds, returns MK_NODVAL (Use MKIsNoDVal() to check for MK_NODVAL).
Note: If you're making several changes to the installed tuning system, it's more efficient to make the changes in an MKTuningSystem instance and then send it the install message than it is to repeatedly invoke this method.
| aKeyNum | is a MKKeyNum. | |
| freq | is a double. |
| - (id) setKeyNumAndOctaves: | (MKKeyNum) | aKeyNum | ||
| toFreq: | (double) | freq | ||
Tunes all the receiver's key numbers with the same pitch class as aKeyNum to octaves of freq such that aKeyNum is tuned to freq.
Returns the receiver or nil if aKeyNum is out of bounds.
| aKeyNum | is a MKKeyNum. | |
| freq | is a double. |
| + (id) setKeyNumAndOctaves: | (MKKeyNum) | aKeyNum | ||
| toFreq: | (double) | freq | ||
Tunes the key numbers in the installed tuning system that are the same pitch class as aKeyNum to octaves of freq such that aKeyNum is tuned to freq.
Returns the receiver or nil if aKeyNum is out of bounds.
Note: If you're making several changes to the installed tuning system, it's more efficient to make the changes in a MKTuningSystem instance and then send it the install message than it is to repeatedly invoke this method.
| aKeyNum | is a MKKeyNum. | |
| freq | is a double. |
| + (void) transpose: | (double) | semitones |
Transposes the installed tuning system by semitones half-steps.
(The half-step used here is 12-tone equal-tempered.) If semitones is positive, the transposition is up, if it's negative, the transposition is down. semitones can be any double value, thus you can transpose the tuning system by increments smaller than a half-step.
| semitones | is a double. |
| - (void) transpose: | (double) | semitones |
Transposes the receiver by semitones half-steps (the half-step used here is 12-tone equal-tempered).
If semitones is positive, the transposition is up, if it's negative, the transposition is down. semitones can be any double value, thus you can transpose the receiver by increments smaller than a half-step.
| semitones | is a double. |
- (NSMutableArray*) frequencies [protected] |
NSArray object of frequencies, indexed by keyNum.
1.5.6