MusicKit and SndKit Concepts
PrevAppendix B. MIDI Time Code in the MusicKitNext

Generating MIDI Time Code

Generating MIDI Time Code is quite easy. You simply instantiate an instance of the class MKMTCPerformer. This is a subclass of MKPerformer with a perform method that sends MIDI time code messages. To use an MKMTCPerformer, simply, instantiate the object, activate it, connect it to a MKMidi object and start the performance. This is done with the usual MKPerformer methods:

MKMTCPerformer *myMTCPerformer =[[MKMTCPerformer alloc] init];
MKMidi *myMidi = [MKMidi midiOnDevice: @"midi0"];
[[myMTCPerformer noteSender] connect:[myMidi noteReceiver]];
[myMTCPerformer activate];
[myMidi run];
[MKConductor startPerformance];

This will begin generating time code in a forward direction, beginning with the value 0:0:0:0, using the default format (24 frames/second).

Customizing Time Code Generation

You set the format with the method setFormat:. The argument should be one of the following constants, defined in <MusicKit/MKMTCPerformer.h>:

You set the first and last MTC value using the methods setFirstTimeTag:, setLastTimeTag: and setTimeShift:. To set the first value the MKPerformer will generate, you use setFirstTimetTag:. Note that this method also sets the time from activation at which the MKPerformer will start sending time code. For example, if you set a MKPerformer's firstTimeTag to 10.0 seconds before the performance has started, then activate the MKPerformer and start the performance, the MKPerformer will begin sending time code at time 10.0 seconds and the values will begin at the MTC time 0:0:10:0 (zero hours, zero minutes, ten seconds, zero frames).

You may want the time code to begin sending immediately, regardless of firstTimeTag. To do this, use the MKPerformer method setTimeShift: and pass it an argument of -firstTimeTag:

MKMTCPerformer *myMTCPerformer =[[MKMTCPerformer alloc] init];	
[myMTCPerformer setFirstTimeTag:10.0];	
[myMTCPerformer setTimeShift:-10.0];	
[myMTCPerformer activate];	
[MKConductor startPerformance];

If you want to generate time code beginning with a value of 2.0 seconds and start sending that time that time code at time 3.0 seconds, set firstTimeTag to 2.0 and timeShift to 1.0. In general, the formula is:

start time = timeShift + firstTimeTag + activation time

The default value for both timeShift and firstTimeTag is 0.0. Keep in mind that the start time given in the formula above is relative to the time of activation.

By default, time code generation continues until you deactivate the MKPerformer or finish the performance. However, you can specify that the MKPerformer automatically deactivate when it reaches a certain target MTC value by sending it the setLastTimeTag: message. Normally, lastTimeTag should be greater than firstTimeTag. However, you can tell the MKPerformer to send reverse time code as follows:

[myMTCPerformer setDirection:MK_MTC_REVERSE];

Then, lastTimeTag should be less than firstTimeTag. Time code values will count down from firstTimeTag until lastTimeTag is reached. You cancel generation of reverse time code by sending the message:

[myMTCPerformer setDirection:MK_MTC_FORWARD];

As an alternative to using setFirstTimeTag:, setLastTimeTag: and setTimeShift:, you can use met hods that allow you to specify the time directly in MTC units. For example, to set firstTimeTag to a MTC value of 0:21:59:5, you send the following mesage:

[myMTCPerformer setFirstTimeTagMTCHours: 0
                                minutes: 21
                                seconds: 59
                                 frames: 5];

This sets the firstTimeTagvalue as specified, assuming the current MTC format. Analagous methods are provided for setting lastTimeTagand timeShift.

To conveniently convert between seconds and MTC time formats, the Music Kit provides two C functions:

extern double /* Returns time in seconds */ 
 MKConvertMTCToSeconds(short format,
                       short hours,  
                       short minutes, 
                       short seconds, 
                       short frames); 

extern void /* Returns (by reference) time in MTC units */ 
 MKConvertSecondsToMTC(double seconds,
                       short format,
                       short *hoursPtr,
                       short *minutesPtr,
                       short *secondsPtr, 
                       short *framesPtr);

These functions do straight translation. They do not take into account any DeltaTime value (described later in this document).

Pausing or Freezing Time Code Generation

You can pause time code generation using the standard MKPerformer pause method. A paused MKPerformer stops sending MIDI time code until it is resumed using the resume message. When it is resumed, it sends a MTC Full Message, then resumes time code generation where it left off.

You can also freeze the advance of time, using the freezeTimeCode method. An MKMTCPerformer that is frozen continues sending MTC messages, but the time code values remain the same. Time code can be made to advance again by sending the thawTimeCode message.

Generating Full Messages and SMPTE User Bits

A MTC Full Message is sent when the performer is resumed and the first time it is activated. Normally, this is sufficient. However, you can send a Full Message at any time, by sending sendFullMTCMessage.

User bits are part of the SMPTE specification. They are not interpreted by the MusicKit. You can send user bits by sending sendUserBits:groupFlagBits:. See the MIDI Time Code specification or the SMPTE specification for the meaning of the arguments.

What Time is It?

You can ask the MKMTCPerformer the current MTC time with the timeTag or getMTCHours:minutes:seconds:frames:message, which return the time in seconds and MTC units, respectively. The time tag returned is in the clock Conductor's time base. See the discussion on deltaT later in this document.

See the MKMTCPerformer Class Description for further information.

PrevHomeNext
MIDI Time Code in the MusicKitUpSynchronizing to Incoming MIDI Time Code