Quicktime Music Architecture

QuickTime Music Architecture

September 17, 2002 MANUAL IS SOLD “AS IS,” AND YOU, THE PURCHASER, ARE ASSUMING THE ENTIRE Apple Computer, Inc. RISK AS TO ITS QUALITY AND ACCURACY. ' 2004 Apple Computer, Inc. IN NO EVENT WILL APPLE BE LIABLE FOR All rights reserved. DIRECT, INDIRECT, SPECIAL, INCIDENTAL, OR CONSEQUENTIAL DAMAGES RESULTING FROM ANY DEFECT OR No part of this publication may be INACCURACY IN THIS MANUAL, even if reproduced, stored in a retrieval system, or advised of the possibility of such damages. transmitted, in any form or by any means, THE WARRANTY AND REMEDIES SET FORTH ABOVE ARE EXCLUSIVE AND IN mechanical, electronic, photocopying, LIEU OF ALL OTHERS, ORAL OR WRITTEN, recording, or otherwise, without prior EXPRESS OR IMPLIED. No Apple dealer, agent, or employee is authorized to make any written permission of Apple Computer, Inc., modification, extension, or addition to this with the following exceptions: Any person warranty. is hereby authorized to store documentation Some states do not allow the exclusion or on a single computer for personal use only limitation of implied warranties or liability for incidental or consequential damages, so the and to print copies of documentation for above limitation or exclusion may not apply to personal use provided that the you. This warranty gives you specific legal rights, and you may also have other rights which documentation contains Apple’s copyright vary from state to state. notice. The Apple logo is a trademark of Apple Computer, Inc. Use of the “keyboard” Apple logo (Option-Shift-K) for commercial purposes without the prior written consent of Apple may constitute trademark infringement and unfair competition in violation of federal and state laws. No licenses, express or implied, are granted with respect to any of the technology described in this document. Apple retains all intellectual property rights associated with the technology described in this document. This document is intended to assist application developers to develop applications only for Apple-labeled or Apple-licensed computers. Every effort has been made to ensure that the information in this document is accurate. Apple is not responsible for typographical errors. Apple Computer, Inc. 1 Infinite Loop Cupertino, CA 95014 408-996-1010

Apple, the Apple logo, and QuickTime are trademarks of Apple Computer, Inc., registered in the United States and other countries. Simultaneously published in the United States and Canada. Even though Apple has reviewed this manual, APPLE MAKES NO WARRANTY OR REPRESENTATION, EITHER EXPRESS OR IMPLIED, WITH RESPECT TO THIS MANUAL, ITS QUALITY, ACCURACY, MERCHANTABILITY, OR FITNESS FOR A PARTICULAR PURPOSE. AS A RESULT, THIS Contents

Chapter 1 QuickTime Music Architecture 5

Overview of QTMA Components 5 About QuickTime Music Events 6 Using the QuickTime Music Architecture 6 Constants 6 Data Structures 7 Tune Player Functions 8 Note Allocator Functions: Note Channel Allocation and Use 9 Note Allocator Functions: Miscellaneous Interface Tools 10 Note Allocator Functions: System Configuration and Utility 10 Music Component Functions: Synthesizer 11 Music Component Functions: Instruments and Parts 11 Music Component Functions: Miscellaneous 12 Instrument Component Functions 12 MIDI Component Functions 13 Functions for Importing MIDI Files 13 Function Provided by the Generic Music Component 13 Functions Implemented by Music Components that Use the Generic Music Component 13 Result Codes 14

QuickTime Music Architecture

This chapter describes the QuickTime music architecture (QTMA), which allows QuickTime movies 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.

You can use the QuickTime music synthesizer, which is a software-based music synthesizer included with QuickTime, to generate sounds or music using a computer's built-in audio or sound card. You can also use the General MIDI component for playing music on a MIDI device attached to a serial port.

Before reading this chapter, you should already be familiar with QuickTime and QuickTime components. In order to use any component, your application must use the Component Manager.

You need to read this chapter if you are writing an application that creates QuickTime movies and you want to incorporate music tracks as part of the movie, either by importing MIDI files or by programmatically generating musical sequences. If you want to create a music component or add an instrument to the existing library of instruments, you also need to read this chapter. If you are creating new instruments, you should be familiar with QT atoms and atom containers, which are described in "QT Atoms".

Overview of QTMA Components

QuickTime Music Architecture intoduces the components that make up QTMA and describes how each is used.

■ Note Allocator Component ■ Tune Player Component ■ Music Components Included in QuickTime ■ Instrument Components and Atomic Instruments ■ The QuickTime Music Synthesizer Component ■ The General MIDI Synthesizer Component ■ The MIDI Synthesizer Component

■ The Base Instrument Component ■ The Generic Music Component ■ MIDI Components

About QuickTime Music Events

QuickTime Music Architecture describes the data structure of QuickTime music events. Music events specify the instruments and notes of a musical composition. The events described in this section initialize and modify sound-producing music devices and define the notes and rests to be played. Several different event types are defined.

■ Note Event and Extended Note Event

■ Rest Event ■ Marker Event ■ Controller Event and Extended Controller Event ■ General Event ■ Knob Event

Using the QuickTime Music Architecture

QuickTime Music Architecture discusses some of the more common operations your application may perform with the QTMA.

■ QuickTime Settings Music Panel ■ Converting MIDI Data to a QuickTime Music Track Using MoviePlayer ■ Importing a Standard MIDI File As a Movie Using the Movie Toolbox ■ Playing Notes With the Note Allocator ■ Note-Related Data Structures ■ Playing Piano Sounds With the Note Allocator

Constants

QuickTime Music Architecture describes the constants provided by QTMA for use in your application.

■ Atom Types for Atomic Instruments ■ Instrument Knob Flags

■ Loop Type Constants ■ Music Component Type ■ Synthesizer Type Constants ■ Synthesizer Description Flags ■ Synthesizer Knob ID Constants ■ Controller Numbers ■ Controller Range ■ Drum Kit Numbers ■ Tone Fit Flags ■ Knob Flags

■ Knob Value Constants ■ Music Packet Status ■ Atomic Instrument Information Flags ■ Flags for Setting Atomic Instruments ■ Instrument Info Flags ■ Synthesizer Connection Type Flags ■ Instrument Match Flags ■ Note Request Constants ■ Pick Instrument Flags ■ Note Allocator Type ■ Tune Queue Depth ■ Tune Player Type ■ Tune Queue Flags ■ MIDI Component Constants ■ MIDI System Exclusive Constants ■ MIDI File Import Flags ■ Part Mixing Flags

Data Structures

QuickTime Music Architecture defines the data structures used in QTMA.

■ Instrument Knob Structure

■ Instrument Knob List ■ Atomic Instrument Sample Description Structure ■ Synthesizer Description Structure ■ Tone Description Structure ■ Knob Description Structure ■ Instrument About Information ■ MIDI Packet ■ Instrument Information Structure ■ Instrument Information List ■ General MIDI Instrument Information Structure

■ Non-General MIDI Instrument Information Structure ■ Non-General MIDI Instrument Information List ■ Complete Instrument Information List ■ Synthesizer Connections for MIDI Devices ■ QuickTime MIDI Port ■ QuickTime MIDI Port List ■ Note Request Information Structure ■ Note Request Structure ■ Tune Status

Tune Player Functions

QuickTime Music Architecture describes the functions the tune player provides for setting, queueing, and manipulating music sequences. It also describes tune player utility functions.

■ TuneSetHeader

■ TuneSetHeaderWithSize

■ TuneSetNoteChannels

■ TuneQueue

■ TuneStop

■ TuneGetVolume

■ TuneSetVolume

■ TuneSetSoundLocalization

■ TuneGetTimeBase

■ TuneGetTimeScale

■ TuneSetTimeScale

■ TuneGetPartMix

■ TuneSetPartMix

■ TuneInstant

■ TunePreroll

■ TuneUnroll

■ TuneGetIndexedNoteChannel

■ TuneGetStatus

■ TuneSetPartTranspose

■ TuneGetNoteAllocator

■ TuneSetSofter

■ TuneSetBalance

■ TuneTask

Note Allocator Functions: Note Channel Allocation and Use

QuickTime Music Architecture defines the functions that make up the note allocator component. The note allocator contains a set of functions for allocating and manipulating note channels and playing notes. This set of functions is defined here. It also contains a set of user interface functions and a set of utility and system configuration functions, which are defined in the next sections.

■ NANewNoteChannel

■ NANewNoteChannelFromAtomicInstrument

■ NADisposeNoteChannel

■ NAGetNoteChannelInfo

■ NAGetIndNoteChannel

■ NAUseDefaultMIDIInput ■ NALoseDefaultMIDIInput

■ NAPrerollNoteChannel

■ NAUnrollNoteChannel

■ NAResetNoteChannel

■ NASetNoteChannelVolume

■ NASetNoteChannelBalance

■ NASetNoteChannelSoundLocalization

■ NAPlayNote

■ NAGetController

■ NASetController

■ NAGetKnob

■ NASetKnob

■ NAFindNoteChannelTone

■ NASetInstrumentNumber

■ NASetInstrumentNumberInterruptSafe

■ NASetAtomicInstrument

■ NASendMIDI

■ NAGetNoteRequest

Note Allocator Functions: Miscellaneous Interface Tools

QuickTime Music Architecture defines the functions of the note allocator component which provide a user interface.

■ NAPickInstrument

■ NAPickEditInstrument

■ NAStuffToneDescription

■ NAPickArrangement

■ NACopyrightDialog

Note Allocator Functions: System Configuration and Utility

QuickTime Music Architecture defines the functions of the note allocator component that are used for system configuration or utility purposes.

■ NARegisterMusicDevice

■ NAUnregisterMusicDevice

■ NAGetRegisteredMusicDevice

■ NAGetDefaultMIDIInput ■ NASetDefaultMIDIInput

■ NAGetMIDIPorts

■ NASaveMusicConfiguration

■ NATask

Music Component Functions: Synthesizer

QuickTime Music Architecture defines the music component functions that obtain specific information about a synthesizer, obtain a best instrument fit from the available instruments within the synthesizer, play a note, get and set a synthesizer knob, obtain synthesizer knob information, and get and set external MIDI procedure name entry points.

■ MusicGetDescription

■ MusicFindTone

■ MusicPlayNote

■ MusicGetKnob

■ MusicSetKnob

■ MusicGetKnobDescription

■ MusicGetInstrumentKnobDescription

■ MusicGetDrumKnobDescription

■ MusicGetKnobSettingStrings

■ MusicSetMIDIProc

■ MusicGetMIDIProc

■ MusicSendMIDI

■ MusicGetDeviceConnection

■ MusicUseDeviceConnection

Music Component Functions: Instruments and Parts

QuickTime Music Architecture defines the music component functions that initialize a part with an instrument, store instruments, list available instruments, manipulate parts, and get information about parts.

■ MusicGetPartInstrumentNumber

■ MusicSetPartInstrumentNumber

■ MusicSetPartInstrumentNumberInterruptSafe

■ MusicGetPartAtomicInstrument

■ MusicSetPartAtomicInstrument

■ MusicStorePartInstrument

■ MusicGetInstrumentAboutInfo

■ MusicGetInstrumentInfo

■ MusicGetPart

■ MusicSetPart

■ MusicGetPartName

■ MusicSetPartName

■ MusicGetPartKnob

■ MusicSetPartKnob

■ MusicResetPart

■ MusicGetPartController

■ MusicSetPartController

■ MusicSetPartSoundLocalization

Music Component Functions: Miscellaneous

QuickTime Music Architecture defines the functions of the music component that get and modify the master tuning of the synthesizer, cause the synthesizer to play off-line, and allow the music component to perform tasks it must perform in the foreground foreground.

■ MusicGetMasterTune

■ MusicSetMasterTune

■ MusicStartOffline

■ MusicSetOfflineTimeTo

■ MusicTask

Instrument Component Functions

QuickTime Music Architecture defines the functions that make up an instrument component.

■ InstrumentGetInfo ■ InstrumentGetInst ■ InstrumentInitialize ■ InstrumentOpenComponentResFile

■ InstrumentCloseComponentResFile ■ InstrumentGetComponentRefCon ■ InstrumentSetComponentRefCon

MIDI Component Functions

QuickTime Music Architecture defines the functions of the MIDI component.

■ QTMIDIGetMIDIPorts

■ QTMIDISendMIDI

■ QTMIDIUseReceivePort

■ QTMIDIUseSendPort

Functions for Importing MIDI Files

QuickTime Music Architecture defines the functions used for importing MIDI files into QuickTime.

■ MIDIImportGetSettings

■ MIDIImportSetSettings

Function Provided by the Generic Music Component

QuickTime Music Architecture defines the MusicGenericConfigure function.

■ MusicGenericConfigure

Functions Implemented by Music Components that Use the Generic Music Component

QuickTime Music Architecture defines functions that are implemented by client music components of the generic music component. These functions are called by the generic music component, as necessary for responding to function calls made by applications.

■ MusicDerivedSetKnob

■ MusicDerivedSetPart

■ MusicDerivedSetInstrument

■ MusicDerivedSetInstrumentPartNumber

■ MusicDerivedSetMIDI

■ MusicDerivedStorePartInstrument

Result Codes

QuickTime Music Architecture lists all of the result codes returned by QuickTime music architecture functions.