Apple Developer Connection
Member Login Log In | Not a Member? Contact ADC

Next Page > Hide TOC

QuickTime Music Architecture Reference

Framework
Frameworks/QuickTime.framework
Declared in
IOMacOSTypes.h
QuickTimeMusic.h

Overview

The QuickTime Music Architecture (QTMA) allows QuickTime movies, applications, and other software to play individual musical notes, sequences of notes, and a broad range of sounds from a variety of instruments and synthesizers. With QTMA, you can also import Standard MIDI files and convert them into a QuickTime movie for easy playback.

Functions by Task

Allocating and Using Note Channels

Calling Generic Music Component Clients

Managing Instruments and Parts

Managing Synthesizers

Managing the Generic Music Component

MIDI Component Functions

Miscellaneous Music Component Functions

Note Allocator Configuration and Utilities

Note Allocator Interface Tools

Using the Tune Player

Supporting Functions

Functions

Callbacks

MusicMIDISendProc

Undocumented

typedef ComponentResult (*MusicMIDISendProcPtr) (ComponentInstance self, long refCon, MusicMIDIPacket *mmp);

If you name your function MyMusicMIDISendProc, you would declare it this way:

ComponentResult MyMusicMIDISendProc (
   ComponentInstance    self,
   long                 refCon,
   MusicMIDIPacket      *mmp );

Parameters
self

Undocumented

refCon

A reference constant that the client code supplies to your callback. You can use this reference to point to a data structure containing any information your callback needs.

mmp

A pointer to a MusicMIDIPacket structure.

Return Value

See Error Codes. Your callback should return noErr if there is no error.

Declared In
QuickTimeMusic.h

MusicOfflineDataProc

Undocumented

typedef ComponentResult (*MusicOfflineDataProcPtr) (Ptr SoundData, long numBytes, long myRefCon);

If you name your function MyMusicOfflineDataProc, you would declare it this way:

ComponentResult MyMusicOfflineDataProc (
   Ptr     SoundData,
   long    numBytes,
   long    myRefCon );

Parameters
SoundData

Undocumented

numBytes

Undocumented

myRefCon

Undocumented

Return Value

See Error Codes. Your callback should return noErr if there is no error.

Declared In
QuickTimeMusic.h

TuneCallBackProc

Called when a sequence of music events is placed into a queue to be played.

typedef void (*TuneCallBackProcPtr) (const TuneStatus *status, long refCon);

If you name your function MyTuneCallBackProc, you would declare it this way:

void MyTuneCallBackProc (
   const TuneStatus    *status,
   long                refCon );

Parameters
status

A pointer to a TuneStatus structure.

refCon

A reference constant that the client code supplies to your callback. You can use this reference to point to a data structure containing any information your callback needs.

Declared In
QuickTimeMusic.h

TunePlayCallBackProc

Supports the TuneSetNoteChannels function.

typedef void (*TunePlayCallBackProcPtr) (unsigned long *event, long seed, long refCon);

If you name your function MyTunePlayCallBackProc, you would declare it this way:

void MyTunePlayCallBackProc (
   unsigned long    *event,
   long             seed,
   long             refCon );

Parameters
event

A pointer to a QuickTime music event structure in the sequence data.

seed

A 32-bit value that is guaranteed to be different for each call to the callback routine (unless 2^32 calls are made, after which the values repeat), with one exception: the value passed at the beginning of a note is also passed at the end of the note's duration, together with a note structure or an extended note in which the velocity bits are set to 0.

refCon

A reference constant that the client code supplies to the callback.

Declared In
QuickTimeMusic.h

Data Types

AtomicInstrument

Represents a type used by the Music Architecture API.

typedef Handle AtomicInstrument;

Availability
Declared In
QuickTimeMusic.h

AtomicInstrumentPtr

Represents a type used by the Music Architecture API.

typedef Ptr AtomicInstrumentPtr;

Availability
Declared In
QuickTimeMusic.h

GCPart

Defines a part in the QuickTime Music Architecture.

struct GCPart {
   long                hwInstrumentNumber;
   short               controller[128];
   long                volume;
   long                polyphony;
   long                midiChannel;
   GCInstrumentData    id;
};

Fields
hwInstrumentNumber
Discussion

The instrument number of the instrument for the part.

controller
Discussion

An array of 128 bits identifying the available controllers; see Music Controllers. Bits are numbered from 1 to 128, starting with the most significant bit of the long word and continuing to the least significant of the last bit.

volume
Discussion

The sound volume for this part, ranging from -1.0 to +1.0. The high-order 8 bits contain the integer part; the low-order 8 bits contain the fractional part. A value of +1.0 constitutes the maximum volume of the user's computer. Negative values are silent but retain the magnitude of the volume setting.

polyphony
Discussion

The maximum number of voices.

midiChannel
Discussion

The system MIDI channel or, for a hardware device, the slot number.

id
Discussion

A GCInstrumentData structure.

Related Functions
MusicDerivedSetInstrument
MusicDerivedSetKnob
MusicDerivedSetPart
MusicDerivedSetPartInstrumentNumber
MusicDerivedStorePartInstrument
MusicGenericGetPart
Declared In
QuickTimeMusic.h

GenericKnobDescription

Describes a knob for the generic music component.

struct GenericKnobDescription {
   KnobDescription    kd;
   long               hw1;
   long               hw2;
   long               hw3;
   long               settingsID;
};

Fields
kd
Discussion

A KnobDescription structure.

hw1
Discussion

Undocumented

hw2
Discussion

Undocumented

hw3
Discussion

Undocumented

settingsID
Discussion

Undocumented

Discussion

Undocumented

Related Functions
MusicDerivedSetKnob
Declared In
QuickTimeMusic.h

GenericKnobDescriptionListHandle

Represents a type used by the Music Architecture API.

typedef GenericKnobDescriptionListPtr * GenericKnobDescriptionListHandle;

Availability
Declared In
QuickTimeMusic.h

GenericKnobDescriptionListPtr

Represents a type used by the Music Architecture API.

typedef GenericKnobDescriptionList * GenericKnobDescriptionListPtr;

Availability
Declared In
QuickTimeMusic.h

InstrumentAboutInfo

Contains the information that appears in an instrument's About box and is returned by MusicGetInstrumentAboutInfo.

struct InstrumentAboutInfo {
   PicHandle    p;
   Str255       author;
   Str255       copyright;
   Str255       other;
};

Fields
p
Discussion

A handle to a graphic for the About box.

author
Discussion

The author's name.

copyright
Discussion

The copyright information.

other
Discussion

Any other textual information.

Related Functions
MusicGetInstrumentAboutInfo
Declared In
QuickTimeMusic.h

InstrumentInfoListHandle

Represents a type used by the Music Architecture API.

typedef InstrumentInfoListPtr * InstrumentInfoListHandle;

Availability
Declared In
QuickTimeMusic.h

InstrumentInfoListPtr

Represents a type used by the Music Architecture API.

typedef InstrumentInfoList * InstrumentInfoListPtr;

Availability
Declared In
QuickTimeMusic.h

KnobDescription

Contains sound parameter values for a single knob.

struct KnobDescription {
   Str63    name;
   long     lowValue;
   long     highValue;
   long     defaultValue;
   long     flags;
   long     knobID;
};

Fields
name
Discussion

The name of the knob.

lowValue
Discussion

The lowest number you can set the knob to.

highValue
Discussion

The highest number you can set the knob to.

defaultValue
Discussion

A value to use for the default. A default instrument is made of all default values.

flags
Discussion

Constants (see below) that provide various items of information about the knob. See these constants:

knobID
Discussion

A knob ID or index. A nonzero value in the high byte indicates that it is an ID. The knob index ranges from 1 to the number of knobs; the ID is an arbitrary number. Use the knob ID to refer to the knob in preference to the knob index, which may change.

Related Functions
MusicGetDrumKnobDescription
MusicGetInstrumentKnobDescription
MusicGetKnobDescription
Declared In
QuickTimeMusic.h

MusicComponent

Represents a type used by the Music Architecture API.

typedef ComponentInstance MusicComponent;

Availability
Declared In
QuickTimeMusic.h

MusicController

Represents a type used by the Music Architecture API.

typedef SInt32 MusicController;

Availability
Declared In
QuickTimeMusic.h

MusicMIDIPacket

Describes MIDI data passed by note allocation calls.

struct MusicMIDIPacket {
   unsigned short    length;
   unsigned long     reserved;
   UInt8             data[249];
};

Fields
length
Discussion

The length of the data in the packet.

reserved
Discussion

Contains 0, or one of the music packet status constants (see below). See these constants:

data
Discussion

MIDI data.

Related Functions
MusicDerivedMIDISend
MusicMIDIReadHookProc
MusicMIDISendProc
MusicSendMIDI
NASendMIDI
QTMIDISendMIDI
Declared In
QuickTimeMusic.h

MusicMIDISendUPP

Represents a type used by the Music Architecture API.

typedef STACK_UPP_TYPE(MusicMIDISendProcPtr) MusicMIDISendUPP;

Availability
Declared In
QuickTimeMusic.h

MusicOfflineDataUPP

Represents a type used by the Music Architecture API.

typedef STACK_UPP_TYPE(MusicOfflineDataProcPtr) MusicOfflineDataUPP;

Availability
Declared In
QuickTimeMusic.h

NoteAllocator

Represents a type used by the Music Architecture API.

typedef ComponentInstance NoteAllocator;

Availability
Declared In
QuickTimeMusic.h

NoteChannel

Represents a type used by the Music Architecture API.

typedef struct OpaqueNoteChannel * NoteChannel;

Availability
Declared In
QuickTimeMusic.h

NoteRequest

Provides complete information for allocating a note channel.

struct NoteRequest {
   NoteRequestInfo    info;
   ToneDescription    tone;
};

Fields
info
Discussion

A NoteRequestInfo structure.

tone
Discussion

A ToneDescription structure.

Related Functions
NAGetNoteRequest
NANewNoteChannel
Declared In
QuickTimeMusic.h

QTMIDIComponent

Represents a type used by the Music Architecture API.

typedef ComponentInstance QTMIDIComponent;

Availability
Declared In
QuickTimeMusic.h

QTMIDIPortListHandle

Represents a type used by the Music Architecture API.

typedef QTMIDIPortListPtr * QTMIDIPortListHandle;

Availability
Declared In
QuickTimeMusic.h

QTMIDIPortListPtr

Represents a type used by the Music Architecture API.

typedef QTMIDIPortList * QTMIDIPortListPtr;

Availability
Declared In
QuickTimeMusic.h

Str31

Represents a type used by the Music Architecture API.

typedef unsigned char Str31;

Availability
Declared In
IOMacOSTypes.h

SynthesizerConnections

Describes how a MIDI device is connected to the user's computer.

struct SynthesizerConnections {
   OSType    clientID;
   OSType    inputPortID;
   OSType    outputPortID;
   long      midiChannel;
   long      flags;
   long      unique;
   long      reserved1;
   long      reserved2;
};

Fields
clientID
Discussion

The client ID provided by the MIDI Manager, or 'OMS ' for an OMS port.

inputPortID
Discussion

The ID provided by the MIDI Manager or OMS for the port used to SEND to the MIDI synthesizer.

outputPortID
Discussion

The ID provided by the MIDI Manager or OMS for the port that RECEIVES from a keyboard or other control device.

midiChannel
Discussion

The system MIDI channel or, for a hardware device, the slot number.

flags
Discussion

Constants (see below) that provide information about the type of connection. See these constants:

unique
Discussion

A unique ID you can use instead of an index to identify the synthesizer to the note allocator.

reserved1
Discussion

Reserved. Set to 0.

reserved2
Discussion

Reserved. Set to 0.

Related Functions
NAGetRegisteredMusicDevice
NARegisterMusicDevice
Declared In
QuickTimeMusic.h

SynthesizerDescription

Contains information about a synthesizer.

struct SynthesizerDescription {
   OSType           synthesizerType;
   Str31            name;
   unsigned long    flags;
   unsigned long    voiceCount;
   unsigned long    partCount;
   unsigned long    instrumentCount;
   unsigned long    modifiableInstrumentCount;
   unsigned long    channelMask;
   unsigned long    drumPartCount;
   unsigned long    drumCount;
   unsigned long    modifiableDrumCount;
   unsigned long    drumChannelMask;
   unsigned long    outputCount;
   unsigned long    latency;
   unsigned long    controllers[4];
   unsigned long    gmInstruments[4];
   unsigned long    gmDrums[4];
};

Fields
synthesizerType
Discussion

The synthesizer type. This is the same as the music component subtype.

name
Discussion

Text name of the synthesizer type.

flags
Discussion

Constants (see below) that provide information about how the synthesizer works. See these constants:

voiceCount
Discussion

Maximum polyphony.

partCount
Discussion

Maximum multi-timbrality (and MIDI channels).

instrumentCount
Discussion

The number of built-in ROM instruments. This does not include General MIDI instruments.

modifiableInstrumentCount
Discussion

The number of slots available for saving user-modified instruments.

channelMask
Discussion

Which channels a MIDI device always uses for instruments. Set to 0xFFFF for all channels.

drumPartCount
Discussion

The maximum multi-timbrality of drum parts. For synthesizers where drum kits are separated from instruments.

drumCount
Discussion

The number of built-in ROM drum kits. This does not include General MIDI drum kits. For synthesizers where drum kits are separated from instruments.

modifiableDrumCount
Discussion

The number of slots available for saving user-modified drum kits. For MIDI synthesizers where drum kits are separated from instruments.

drumChannelMask
Discussion

Which channels a MIDI device always uses for drum kits. Set to FFFF for all channels.

outputCount
Discussion

The number of audio outputs. This is usually 2.

latency
Discussion

The response time in microseconds.

controllers
Discussion

An array of 128 bits identifying the available controllers; see Music Controllers. Bits are numbered from 1 to 128, starting with the most significant bit of the long word and continuing to the least significant of the last bit.

gmInstruments
Discussion

An array of 128 bits giving the available General MIDI instruments.

gmDrums
Discussion

An array of 128 bits giving the available General MIDI drum kits.

Related Functions
MusicGetDescription
Declared In
QuickTimeMusic.h

TuneCallBackUPP

Represents a type used by the Music Architecture API.

typedef STACK_UPP_TYPE(TuneCallBackProcPtr) TuneCallBackUPP;

Availability
Declared In
QuickTimeMusic.h

TunePlayCallBackUPP

Represents a type used by the Music Architecture API.

typedef STACK_UPP_TYPE(TunePlayCallBackProcPtr) TunePlayCallBackUPP;

Availability
Declared In
QuickTimeMusic.h

TunePlayer

Represents a type used by the Music Architecture API.

typedef ComponentInstance TunePlayer;

Availability
Declared In
QuickTimeMusic.h

TuneStatus

Provides information on the currently playing tune.

struct TuneStatus {
   unsigned long *   tune;
   unsigned long *   tunePtr;
   TimeValue         time;
   short             queueCount;
   short             queueSpots;
   TimeValue         queueTime;
   long              reserved[3];
};

Fields
tune
Discussion

The currently playing tune.

tunePtr
Discussion

Current position within the playing tune.

time
Discussion

Current tune time.

queueCount
Discussion

Number of tunes queued up.

queueSpots
Discussion

Number of tunes that can be added to the queue.

queueTime
Discussion

Total amount of playing time represented by tunes in the queue. This value can be very inaccurate.

reserved
Discussion

Reserved; set to 0.