MKMTCPerformer Class Reference

MKMTCPerformer is used to generate MKNotes with MIDI time code parameters. More...

#import <MKMTCPerformer.h>

Inheritance diagram for MKMTCPerformer:

List of all members.

Public Member Functions
(id)	- init
	Initialize the receiver.
(id)	- setFirstTimeTag:
	Sets firstTimeTag as specified.
(id)	- setLastTimeTag:
	Sets lastTimeTag, the last time code value that will be sent.
(id)	- setFirstTimeTagMTCHours:minutes:seconds:frames:
	Same as setFirstTimeTag:, except that the time is specified in MIDI time code units.
(id)	- setLastTimeTagMTCHours:minutes:seconds:frames:
	Same as setLastTimeTag:, except that the time is specified in MIDI time code units.
(id)	- setTimeShiftMTCHours:minutes:seconds:frames:
	Same as setTimeShift:, except that the time is specified in Midi time code units.
(double)	- firstTimeTag
	Returns firstTimeTag, as previously set with setLastTimeTag: or setFirstTimeTagMTCHours:minutes:seconds:frames:.
(double)	- lastTimeTag
	Returns lastTimeTag, as previously set with setLastTimeTag: or setLastTimeTagMTCHours:minutes:seconds:frames:.
(id)	- setFormat:
	Sets format of the timecode to one of the following:.
(double)	- timeTag
	Returns the time code value most recently sent.
(id)	- getMTCHours:minutes:seconds:frames:
	Same as timeTag, except that the time is returned in MIDI time code units.
(id)	- setDirection:
	Sets direction of time code to be generated.
(id)	- sendUserBits:groupFlagBits:
	Sends SMPTE user bits as indicated.
(id)	- freezeTimeCode
	Stops the advance of time code, but doesn't pause performer.
(id)	- thawTimeCode
	Undoes the effect of freezeTimeCode.
(id)	- sendFullMTCMessage
	Sends the current time as a MIDI time code Full Message.
(id)	- activateSelf
	Prepares the object for performance.
(void)	- deactivate
	Sends a MIDI system exclusive "NAK" message to signal that time code has stopped.
(id)	- pause
	Sends a MIDI system exclusive "NAK" message to signal that time code has stopped.
(id)	- resume
	Sends a MIDI time code Full Message.
(id)	- perform
	This is a subclass responsibility expected to send a MKNote and then set the value of nextPerform.
Protected Attributes
double	firstTimeTag
double	lastTimeTag
int	direction
short	format

---

Detailed Description

MKMTCPerformer is used to generate MKNotes with MIDI time code parameters.

The main use of this class is to send the MKNotes to a MKMidi object. To use an MKMTCPerformer, simply, instantiate the object, activate it, connect a MKMidi object to its one MKNoteSender and start the performance. This is done with the usual MKPerformer methods:

MKMTCPerformer *myMTCPerformer = [[MKMTCPerformer alloc] init]; MKMidi *myMidi = [MKMidi newOnDevice: @"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).

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

• MK_MTC_FORMAT_24
• MK_MTC_FORMAT_25
• MK_MTC_FORMAT_DROP_30
• MK_MTC_FORMAT_30

These are the standard MIDI time code formats. For more information, see the MIDI Time Code Specification (available from the MIDI Manufacturer's Association).

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 (before the performance) you set a MKPerformer's firstTimeTag to 10.0 seconds, 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 methods 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 firstTimeTag value as specified, assuming the current MTC format. Analagous methods are provided for setting lastTimeTag and 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.

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.

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.

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 MKConductor's time base.

See also:

MKPerformer, MKMidi

---

Member Function Documentation

- (id) init

Initialize the receiver.

Returns:

Returns an id. Must be sent when a new object is allocated. If you override this method, you must first send [super init] before doing your own initialization.

Reimplemented from MKPerformer.

- (id) setFirstTimeTag:

(double)

firstTimeTag

Sets firstTimeTag as specified.

This controls the time from activation at which the MKPerformer will begin sending time code. It also controls the first time code value it will send. You can decouple the time the performer runs from the time code it outputs by using Performer's setTimeShift:. For example, to generate time code, beginning with time 2, and to start sending that time code at time 3, you'd send:

[perf setFirstTimeTag: 2]; [perf setTimeOffset: 1];

Parameters:

firstTimeTag

is a double.

Returns:

Returns an id.

Reimplemented from MKPerformer.

- (id) setLastTimeTag:

(double)

lastTimeTag

Sets lastTimeTag, the last time code value that will be sent.

The MKPerformer runs until lastTimeTag is sent. If direction is MK_MTC_REVERSE, lastTimeTag should be less than firstTimeTag. Otherwise, lastTimeTag should be greater than firstTimeTag.

Parameters:

lastTimeTag

is a double.

Returns:

Returns an id.

Reimplemented from MKPerformer.

- (id) setFirstTimeTagMTCHours:		(short)	h
minutes:		(short)	m
seconds:		(short)	s
frames:		(short)	f

Same as setFirstTimeTag:, except that the time is specified in MIDI time code units.

Assumes the current format. (See setFormat:)

Parameters:

	h	is a short.
	m	is a short.
	s	is a short.
	f	is a short.

Returns:

Returns an id.

- (id) setLastTimeTagMTCHours:		(short)	h
minutes:		(short)	m
seconds:		(short)	s
frames:		(short)	f

Same as setLastTimeTag:, except that the time is specified in MIDI time code units.

Assumes the current format. (See setFormat:)

Parameters:

	h	is a short.
	m	is a short.
	s	is a short.
	f	is a short.

Returns:

Returns an id.

- (id) setTimeShiftMTCHours:		(short)	h
minutes:		(short)	m
seconds:		(short)	s
frames:		(short)	f

Same as setTimeShift:, except that the time is specified in Midi time code units.

Assumes the current format. (See setFormat:)

Parameters:

	h	is a short.
	m	is a short.
	s	is a short.
	f	is a short.

Returns:

Returns an id.

- (double) firstTimeTag

Returns firstTimeTag, as previously set with setLastTimeTag: or setFirstTimeTagMTCHours:minutes:seconds:frames:.

Returns:

Returns a double.

Reimplemented from MKPerformer.

- (double) lastTimeTag

Returns lastTimeTag, as previously set with setLastTimeTag: or setLastTimeTagMTCHours:minutes:seconds:frames:.

Returns:

Returns a double.

Reimplemented from MKPerformer.

- (id) setFormat:

(int)

fmt

Sets format of the timecode to one of the following:.

Parameters:

fmt

is an int.

Returns:

Returns an id. MK_MTC_FORMAT_24 (24 frames/second) MK_MTC_FORMAT_25 (25 frames/second) MK_MTC_FORMAT_DROP_30 (30 frames/second, drop-frame) MK_MTC_FORMAT_30 (30 frames/second, no drop-frame)

- (double) timeTag

Returns the time code value most recently sent.

Returns:

Returns a double.

- (id) getMTCHours:		(short *)	h
minutes:		(short *)	m
seconds:		(short *)	s
frames:		(short *)	f

Same as timeTag, except that the time is returned in MIDI time code units.

Parameters:

	h	is a short *.
	m	is a short *.
	s	is a short *.
	f	is a short *.

Returns:

Returns an id. Assumes the current format.

- (id) setDirection:

(int)

newDirection

Sets direction of time code to be generated.

Parameters:

newDirection

is an int.

Returns:

Returns an id. If newDirection is 1, forward time code is generated. If newDirectino is 0, backward time code is generated.

- (id) sendUserBits:		(unsigned int)	userBits
groupFlagBits:		(unsigned char)	groupFlagBits

Sends SMPTE user bits as indicated.

Parameters:

	userBits	is an unsigned int.
	groupFlagBits	is an unsigned char.

Returns:

Returns an id. These are defined by the SMPTE specification. The MusicKit ignores their content.

- (id) freezeTimeCode

Stops the advance of time code, but doesn't pause performer.

Returns:

Returns an id. Time code will continue to be generated, but the same value will be sent over and over.

- (id) thawTimeCode

Undoes the effect of freezeTimeCode.

Returns:

Returns an id.

- (id) sendFullMTCMessage

Sends the current time as a MIDI time code Full Message.

Returns:

Returns an id. See the MIDI Time Code Specification for details.

- (id) activateSelf

Prepares the object for performance.

Returns:

returns self

Reimplemented from MKPerformer.

- (void) deactivate

Sends a MIDI system exclusive "NAK" message to signal that time code has stopped.

Returns:

Returns an id.

Reimplemented from MKPerformer.

- (id) pause

Sends a MIDI system exclusive "NAK" message to signal that time code has stopped.

Returns:

Returns an id. Then invokes superclass version of method to pause the MKMTCPerformer.

Reimplemented from MKPerformer.

- (id) resume

Sends a MIDI time code Full Message.

Returns:

Returns an id. Then invokes superclass version of method to resume the MKMTCPerformer.

Reimplemented from MKPerformer.

- (id) perform

This is a subclass responsibility expected to send a MKNote and then set the value of nextPerform.

Returns:

Returns an id. The return value is ignored.

Reimplemented from MKPerformer.

---

Member Data Documentation

- (double) firstTimeTag [protected]

firstTimeTag, as specified by user.

- (double) lastTimeTag [protected]

lastTimeTag, as specified by user.

- (int) direction [protected]

1 for forward, -1 for reverse.

- (short) format [protected]

MTC format.

---

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

• MKMTCPerformer.h