MusicKit  0.0.0
MKNote Class Reference

A MKNote object represents a musical sound or event by describing its attributes. More...

#import <MKNote.h>


Detailed Description

A MKNote object represents a musical sound or event by describing its attributes.

MKNote objects are containers of musical information. The amount and type of information that a MKNote can hold is practically unlimited; however, you should keep in mind that MKNotes haven't the ability to act on this information, but merely store it. It's left to other objects to read and process the information in a MKNote. Most of the other MusicKit classes are designed around MKNote objects, treating them as common currency. For example, MKPart objects store MKNotes, MKPerformers acquire them and pass them to MKInstruments, MKInstruments read the contents of MKNotes and apply the information therein to particular styles of realization, and so on.

The information that comprises a MKNote defines the attributes of a particular musical event. Typically, an object that uses MKNotes plucks from them just those bits of information in which it's interested. Thus you can create MKNotes that are meaningful in more than one application. For example, a MKNote object that's realized as synthesis on the DSP would contain many particles of information that are used to drive the synthesis machinery; however, this doesn't mean that the MKNote can't also contain graphical information, such as how the MKNote would be rendered when drawn on the screen. The objects that provide the DSP synthesis realization (MKSynthPatch objects, as defined by the MusicKit) are designed to read just those bits of information that have to do with synthesis, and ignore anything else the MKNote contains. Likewise, a notation application would read the attributes that tell it how to render the MKNote graphically, and ignore all else. Of course, some information, such as the pitch and duration of the MKNote, would most likely be read and applied in both applications.

Most of the methods defined by the MKNote class are designed to let you set and retrieve information in the form of parameters. A parameter consists of a tag, a name, a value, and a data type:

A parameter is said to be present within a MKNote once its value has been set. You can determine whether a parameter is present in one of four ways:

A MKNote has two special timing attributes: A MKNote's time tag corresponds, conceptually, to the time during a performance that the MKNote is performed. Time tags are set through the setTimeTag: method. The other timing attribute is the MKNote's duration, a value that indicates how long the MKNote will endure once it has been struck. It's set through setDur:. A single MKNote can have only one time tag and one duration. Keep in mind, however, that not all MKNotes need a time tag and a duration. For example, if you realize a MKNote by sending it directly to an MKInstrument, then the MKNote's time tag - indeed, whether it even has a time tag - is of no consequence; the MKNote's performance time is determined by when the MKInstrument receives it (although see the MKScorefileWriter, MKScoreRecorder, and MKPartRecorder class descriptions for alternatives to this edict). Similarly, a MKNote that merely initiates an event, relying on a subsequent MKNote to halt the festivities, as described in the discussion of note types, below, doesn't need and actually mustn't be given a duration value.

During a performance, time tag and duration values are measured in time units called beats. The size of a beat is determined by the tempo of the MKNote's MKConductor. You can set the MKNote's conductor directory with the method setConductor:. However, if the MKNote is in the process of being sent by a MKPerformer (or MKMidi), the MKPerformer's MKConductor is used instead. Hence, MKNote's conductor method returns the MKPerformer's MKConductor if the MKNote is in the process of being sent by a MKPerformer, or the MKNote's conductor otherwise. If no MKConductor is set, then its MKConductor is the defaultConductor, which has a default (but not immutable) tempo of 60.0 beats per minute.

Keep in mind that if you send a MKNote directly to an MKInstrument, then the MKNote's time tag is (usually) ignored, as described above, but its duration may be considered and employed by the MKInstrument.

A MKNote has a note type that casts it into one of five roles:

Only noteDurs may have duration values; the very act of setting a MKNote's duration changes it to a noteDur.

You match the two MKNotes in a noteOn/noteOff pair by giving them the same note tag value; a note tag is an integer that identifies two or more MKNotes as part of the same musical event or phrase. In addition to coining noteOn/noteOff pairs, note tags are used to associate a noteUpdate with a noteDur or noteOn that's in the process of being performed. The C function MKNoteTag() is provided to generate note tag values that are guaranteed to be unique across your entire application - you should never create a new note tag except through this function.

Instead of or in addition to being actively realized, a MKNote object can be stored. In a running application, MKNotes are stored within MKPart objects through the addToPart: method. A MKNote can only be added to one MKPart at a time; adding it to a MKPart automatically removes it from its previous MKPart. Within a MKPart object, MKNotes are sorted according to their time tag values.

For long-term storage, MKNotes can be written to a scorefile. There are two "safe" ways to write a scorefile: You can add a MKNote-filled MKPart to a MKScore and then write the MKScore to a scorefile, or you can send MKNotes during a performance to a MKScorefileWriter MKInstrument. The former of these two methods is generally easier and more flexible since it's done statically and allows random access to the MKNotes within a MKPart. The latter allows MKNote objects to be reused since the file is written dynamically; it also lets you record interactive performances.

You can also write individual MKNotes in scorefile format to an open stream by sending writeScorefileStream: to the MKNotes. This can be convenient while debugging, but keep in mind, however, that the method is designed primarily for use by MKScore and MKScorefileWriter objects; if you write MKNotes directly to a stream that's open to a file, the file isn't guaranteed to be recognized by methods that read scorefiles, such as MKScore's readScorefile:.

MKNote are automatically created by the MusicKit in a number of circumstances, such as when reading a MKScorefile. The function MKSetNoteClass() allows you to specify that your own subclass of MKNote be used when MKNotes are automatically created. You retrieve the MKNote class with MKGetNoteClass().


The documentation for this class was generated from the following file: