INSIDE MACINTOSH - Vintage Apple

Assembly-Language InformationData Structures4-107Trap Macros4-109Result Codes4-110Chapter 5Sound Components4-1075-1About Sound Components5-4Sound Component Chains5-4The Apple Mixer5-6The Data Stream5-7Writing a Sound Component5-8Creating a Sound Component5-8Specifying Sound Component Capabilities5-11Dispatching to Sound Component-Defined Routines5-12Registering and Opening a Sound Component5-16Finding and Changing Component Capabilities5-18Sound Components Reference5-22Constants5-22Sound Component Information Selectors5-22Audio Data Types5-26Sound Component Features Flags5-26Action Flags5-27Data Format Flags5-28Data Structures5-29Sound Component Data Records5-29Sound Parameter Blocks5-30Sound Information Lists5-31Compression Information Records5-32Sound Manager Utilities5-33Opening and Closing the Apple Mixer Component5-33Saving and Restoring Sound Component Preferences5-35Sound Component-Defined Routines5-36Managing Sound Components5-37Creating and Removing Audio Sources5-42Getting and Setting Sound Component Information5-44Managing Source Data5-46Summary of Sound Components5-50C Summary5-50Constants5-50Data Types5-53Sound Manager Utilities5-54Sound Component-Defined Routines5-55Assembly-Language Summary5-56Data Structures5-56ix

Chapter 6Audio Components6-1About Audio Components6-3Writing an Audio Component6-5Creating an Audio Component6-5Dispatching to Audio Component-Defined RoutinesAudio Components Reference6-8Data Structures6-8Audio Information Records6-9Audio Component-Defined Routines6-9Getting and Setting Volumes6-10Managing the Mute State6-11Resetting Audio Components6-13Getting Audio Component Information6-13Summary of Audio Components6-15C Summary6-15Constants6-15Data Types6-16Audio Component-Defined Routines6-16Assembly-Language Summary6-17Data Structures6-17GlossaryIndexxIN-1GL-16-7

Figures, Tables, and ListingsChapter 1Introduction to Sound on the MacintoshFigure 1-1Figure 1-2Figure 1-3Figure 1-4Figure 1-5Figure 1-6Figure 1-7Figure 1-8Figure 1-9Figure 1-10Figure 1-11Figure 1-12Figure 1-13Figure 1-14Figure 1-15Figure 1-16Basic sound capabilities on Macintosh computers1-4Enhanced sound capabilities on Macintosh computers1-6High quality sound capabilities on Macintosh computers1-7A sound component chain1-8A sound component chain with a DSP board1-9The Sound Out control panel1-10The relation of the Sound Manager to the audio hardware1-11Bypassing the command queue1-13Mixing multiple channels of sampled sound1-14The Sound In control panel1-15The Alert Sounds control panel1-16The sound recording dialog box1-17The speech generation process1-21The Speech Manager and multiple voices1-21An icon for a Finder sound1-23A sound in the Scrapbook1-24Table 1-1AIFF and AIFF-C capabilitiesListing 1-1Listing 1-2Listing 1-3Playing a sound resource with SndPlay1-25Playing a sound file with SndStartFilePlay1-26Determining whether sound recording equipment isavailable1-27Recording through the sound recording dialog box1-28Recording a sound resource1-29Recording a sound file1-31Checking for speech generation capabilities1-31Using SpeakString to generate speech from a string1-32Generating speech synchronously1-33Stopping speech generated by SpeakString1-34Listing 1-4Listing 1-5Listing 1-6Listing 1-7Listing 1-8Listing 1-9Listing 1-10Chapter 21-1Sound ManagerFigure 2-1Figure 2-2Figure 2-3Figure 2-4Figure 2-5Figure 2-6Figure 2-7Figure 2-8Figure 2-91-192-1The position of the Sound Manager2-6A graph of a wave table2-9Interleaving stereo sample points2-11The structure of 'snd ' resources2-74The location of the data offset bit2-75The general structure of a chunk2-83A sample AIFF-C file2-88The 'snd ' resource type2-155The sound resource header2-156xi

Table 2-1Table 2-2Sample rates2-16Frequencies expressed as MIDI note valuesListing 2-1Listing 2-2Listing 2-3Listing 2-4Listing 2-5Listing 2-6Listing 2-7Creating a sound channel2-20Reinitializing a sound channel2-24Disposing of memory associated with a sound channel2-25Halving the frequency of a sampled sound2-26Changing the amplitude of a sound channel2-27Getting the amplitude of a sound in progress2-28Adding a channel to a group of channels to besynchronized2-30Setting left and right volumes2-32Determining if stereo capability is available2-34Determining if the enhanced Sound Manager is present2-35Testing for multichannel play capability2-36Testing for play-from-disk capability2-37Determining whether a sound channel is paused2-39Determining the number of allocated sound channels2-40Using the freqDurationCmd command2-42Installing a sampled sound as a voice in a channel2-44Looping an entire sampled sound2-45Issuing a callback command2-48Defining a callback procedure2-48Checking whether a callback procedure has executed2-49Stopping a sound that is playing asynchronously2-50Starting an asynchronous sound play2-50Defining a completion routine2-52Defining a data structure to track many sound channels2-54Marking a channel for disposal2-55Disposing of channels that have been marked for disposal2-55Playing a sound resource2-57Obtaining the offset in bytes to a sound header2-58Converting an offset to a sound header into a pointer to a soundheader2-60Playing a sound using the bufferCmd command2-62Finding a chunk in a sound file2-63Loading a chunk from a sound file2-65Compressing audio data2-67Setting up double buffers2-70Defining a doubleback procedure2-73A format 1 'snd ' resource2-76A format 1 'snd ' resource containing sampled-sounddata2-77An 'snd ' resource containing compressed sound data2-78A resource specification2-79A resource specification for the Simple Beep2-79A format 2 'snd ' resource2-81Listing 2-8Listing 2-9Listing 2-10Listing 2-11Listing 2-12Listing 2-13Listing 2-14Listing 2-15Listing 2-16Listing 2-17Listing 2-18Listing 2-19Listing 2-20Listing 2-21Listing 2-22Listing 2-23Listing 2-24Listing 2-25Listing 2-26Listing 2-27Listing 2-28Listing 2-29Listing 2-30Listing 2-31Listing 2-32Listing 2-33Listing 2-34Listing 2-35Listing 2-36Listing 2-37Listing 2-38Listing 2-39Listing 2-40Listing 2-41xii2-43

Chapter 3Chapter 4Sound Input ManagerFigure 3-1Figure 3-2An example of the csParam field for a Status requestAn example of the csParam field for a Control requestTable 3-1The sampled sound header format used bySetupSndHeader3-45Listing 3-1Listing 3-2Listing 3-3Recording directly from a sound input deviceDetermining the name of a sound input deviceDetermining some sound input device settingsSpeech Manager3-143-143-73-123-124-1Figure 4-1Figure 4-2Figure 4-3Figure 4-4Figure 4-5Figure 4-6Figure 4-7The speech generation process4-4The Speech Manager and multiple voices4-5MIDI note values and corresponding piano keys4-7An example of pitch range for a voice4-8Format of a pronunciation dictionary resource4-90Format of a dictionary entry in a dictionary resource4-92Format of a dictionary entry field4-93Table 4-1Table 4-2Table 4-3Table 4-4Table 4-5The embedded command syntax structure4-25Embedded speech commands4-26American English phoneme symbols4-33Prosodic control symbols4-34Effect of punctuation marks on English-languagesynthesizers4-35Listing 4-1Listing 4-2Listing 4-3Listing 4-4Listing 4-5Listing 4-6Listing 4-7Listing 4-8Listing 4-9Checking for speech generation capabilities4-12Speaking text with a speech channel4-13Getting a description of a voice4-15Changing the speech rate and pitch4-16Pausing and continuing speech production4-18Setting up a speech channel for callbacks4-21Installing a word callback procedure4-21A typical word callback procedure4-22Installing a pronunciation dictionary resource into a speechchannel4-37A sample pronunciation dictionary resource4-38Listing 4-10Chapter 53-1Sound ComponentsFigure 5-1Figure 5-2Figure 5-3Figure 5-45-1The component-based sound architecture5-5A component chain for audio hardware that can convert samplerates5-5Mixing multiple channels of sound5-6A sound output device component that can mix soundchannels5-7xiii

Listing 5-1Listing 5-2Listing 5-3Listing 5-4Listing 5-5Chapter 6Audio ComponentsFigure 6-1Figure 6-2xivRez input for a component resource5-11Handling Component Manager selectors5-14Finding the address of a component-defined routineInitializing an output device5-17Getting sound component information5-196-1The Apple AudioVision 14 Display6-4The Volumes control panel for the Apple AudioVision 14Display6-45-14

P R E F A C EAbout This BookThis book, Inside Macintosh: Sound, describes the parts of the Macintoshsystem software that allow you to manage sounds. It describes the servicesprovided by the three principal sound-related system software managers (theSound Manager, the Sound Input Manager, and the Speech Manager) andshows in detail how your application can record and play back sounds,compress and expand audio data, convert text to speech, and perform othersimilar operations.If you are not yet experienced with playing or recording sounds on Macintoshcomputers, you should begin with the chapter “Introduction to Sound on theMacintosh.” That chapter describes the services provided by the systemsoftware and shows how to use the most basic sound-related capabilities ofMacintosh computers. It provides complete source code examples illustratinghow to record sounds into resources and files, how to play sounds stored inresources and files, and how to convert written text into spoken words. It’spossible that this introductory chapter contains all the information you needto successfully integrate sound into your application.Once you are familiar with basic sound recording and production onMacintosh computers, you might want to read other chapters in this book.The chapter “Sound Manager” provides complete information about soundoutput. It shows how to control sound production at a very low level, how toproduce sound asynchronously (that is, while other operations in thecomputer take place), and how to compress and expand audio data. Thischapter also provides complete details about the structure of the two mainsound storage formats, sound resources and sound files.If you need more control over the sound recording process than is offered bythe basic recording functions described in the chapter “Introduction to Soundon the Macintosh,” you need to read the chapter “Sound Input Manager.”That chapter shows how to record sound without displaying the soundrecording dialog box or to interact directly with a sound input device driver.The chapter “Speech Manager” shows how you can convert written text intospeech. You’ll need to read this chapter if you want to convert arbitrary blocksof text (such as very large buffers of text) into spoken words, or if you need togain very fine control over speech production (for example, to synchronizespeech production with other activities, or to use customized pronunciationdictionaries).The chapter “Sound Components” describes how to write sound components.The Sound Manager uses sound components to manipulate audio data or tocommunicate with sound output devices. You need to read this chapter onlyif you are developing a new sound output device or want to use a customaudio data compression and expansion scheme.xv

P R E F A C EThe chapter “Audio Components” describes how to write audio components.The Sound Manager uses audio components to adjust volumes or othersettings of a sound output device when the device contains multiple outputports that can be independently controlled by software. You need to read thischapter only if you are developing a new sound output device that containsseveral sound-producing ports (such as both speakers and headphones).Format of a Typical ChapterAlmost all chapters in this book follow a standard structure. For example, thechapter “Sound Input Manager” contains these sections: “About the Sound Input Manager.” This section provides an overview ofthe features provided by the Sound Input Manager. “Using the Sound Input Manager.” This section describes the tasks you canaccomplish using the Sound Input Manager. It describes how to use themost common routines, gives related user interface information, providescode samples, and supplies additional information. “Sound Input Manager Reference.” This section provides a completereference for the Sound Input Manager by describing the constants, datastructures, routines, and resources it uses. Each routine description alsofollows a standard format, which presents the routine declaration followedby a description of every parameter of the routine. Some routinedescriptions also give additional descriptive information, such asassembly-language information or result codes. “Summary of the Sound Input Manager.” This section provides the Pascaland C interfaces for the constants, data structures, routines, and resultcodes associated with the Sound Input Manager. It also includes relevantassembly-language interface information.Conventions Used in This BookInside Macintosh uses special conventions to present certain types ofinformation. Words that require special treatment appear in specific fonts orfont styles. Certain information, such as parameter blocks, appears in specialformats so that you can scan it quickly.Special FontsAll code listings, reserved words, and the names of actual data structures,constants, fields, parameters, and routines are shown in Courier (thisis Courier).xvi

P R E F A C EWords that appear in boldface are key terms or concepts and are defined inthe glossary.Types of NotesThere are several types of notes used in this book.NoteA note like this contains information that is interesting but possibly notessential to an understanding of the main text. (An example appears onpage 1-6.) IMPORTANTA note like this contains information that is essential for anunderstanding of the main text. (An example appears on page 1-9.) WARNINGWarnings like this indicate potential problems that you should be awareof as you design your application. Failure to heed these warnings couldresult in system crashes or loss of data. (An example appears onpage 2-24.) Assembly-Language InformationInside Macintosh provides information about the registers for specific routinesin this format:Registers on entryA0Contents of register A0 on entryRegisters on exitD0Contents of register D0 on exitIn the “Assembly-Language Summary” section at the end of each chapter,Inside Macintosh presents information about the fields of data structures inthis format:0whatwordevent code2messagelongevent message6whenlongticks since startupThe left column indicates the byte offset of the field from the beginning of thedata structure. The second column shows the field name as defined in theMPW Pascal interface files; the third column indicates the size of that field.The fourth column provides a brief description of the use of the field. For acomplete description of each field, see the discussion of the data structure inthe reference section of the chapter.xvii

P R E F A C EIn addition, Inside Macintosh presents information about the fields of aparameter block in this format:Parameter block inAndOutIntegerInput/output parameter. output1PtrOutput parameter. input1PtrInput parameter.The arrow in the far left column indicates whether the field is an inputparameter, output parameter, or both. You must supply values for all inputparameters and input/output parameters. The routine returns values inoutput parameters and input/output parameters.The second column shows the field name as defined in the MPW Pascalinterface files; the third column indicates the Pascal data type of that field.The fourth column provides a brief description of the use of the field. Fora complete description of each field, see the discussion that follows theparameter block or the description of the parameter block in the referencesection of the chapter.Development EnvironmentThe system software routines described in this book are available usingPascal, C, or assembly-language interfaces. How you access these routinesdepends on the development environment you are using. When showingsystem software routines, this book uses the Pascal interfaces available withthe Macintosh Programmer’s Workshop (MPW). However, the chapters“Sound Components” and “Audio Components” use C interfaces, becausePascal interfaces are not currently available.All code listings in this book are shown in Pascal or C. They show methods ofusing various routines and illustrate techniques for accomplishing particulartasks. All code listings have been compiled and, in most cases, tested.However, Apple Computer, Inc. does not intend for you to use these codesamples in your application.This book occasionally illustrates concepts by referring to a sampleapplication called SurfWriter. This application is not an actual productof Apple Computer, Inc. This book also uses the names SurfBoard andWaveMaker to refer to sample sound output and input devices. These devicesare not actual products of Apple Computer, Inc.xviii

P R E F A C EFor More InformationAPDA is Apple’s worldwide source for over three hundred developmenttools, technical resources, training products, and information for anyoneinterested in developing applications on Apple platforms. Customers receivethe quarterly APDA Tools Catalog featuring all current versions of Apple andthe most popular third-party development tools. Ordering is easy; there areno membership fees, and application forms are not required for most of ourproducts. APDA offers convenient payment and shipping options, includingsite licensing.To order products or to request a complimentary copy of the APDA ToolsCatalog, contactAPDAApple Computer, Inc.P.O. Box 319Buffalo, NY 14207-0319Telephone800-282-2732 (United States)800-637-0029 (Canada)716-871-6555 (International)Fax716-871-6511AppleLinkAPDAAmerica plelink.apple.comIf you provide commercial products and services, call 408-974-4897 forinformation on the developer support programs available from Apple.For information of registering signatures, file types, and other technicalinformation, contactMacintosh Developer Technical SupportApple Computer, Inc.20525 Mariani Avenue, M/S 303-2TCupertino, CA 95014-6299xix

C H A P T E R1Introduction to Sound on theMacintoshContentsAbout Sound on Macintosh Computers1-4Sound Capabilities1-4Sound Production1-9Sound Recording1-15Sound Resources1-17Sound Files1-18Speech Generation1-20The User Interface for Sound1-23Using Sound on Macintosh Computers1-24Producing an Alert Sound1-24Playing a Sound Resource1-25Playing a Sound File1-

for Apple Macintosh computers. Every effort has been made to ensure that the information in this manual is accurate. Apple is not responsible for printing or clerical errors. Apple Computer, Inc. 20525 Mariani Avenue Cupertino, CA 95014 408-996-1010 Apple, the Apple logo, APDA, HyperCard, LaserWriter, Macint