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 3 © 2004 Apple Computer, Inc. All Rights Reserved. CONTENTS 4 © 2004 Apple Computer, Inc. All Rights Reserved. CHAPTER 1 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 Overview of QTMA Components 5 © 2004 Apple Computer, Inc. All Rights Reserved. CHAPTER 1 QuickTime Music Architecture ■ 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 6 About QuickTime Music Events © 2004 Apple Computer, Inc. All Rights Reserved. CHAPTER 1 QuickTime Music Architecture ■ 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 Data Structures 7 © 2004 Apple Computer, Inc. All Rights Reserved. CHAPTER 1 QuickTime Music Architecture ■ 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 8 Tune Player Functions © 2004 Apple Computer, Inc. All Rights Reserved. CHAPTER 1 QuickTime Music Architecture ■ 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