IRIS Digital Media Programming Guide Document Number 007-1799-040 CONTRIBUTORS Written by Patricia Creek; Part III written by Carolyn Curtis Illustrated by Patricia Creek, Dany Galgani, Cheri Brown, David Bertrand, and Dan Young Edited by Nancy Schweiger and Christina Cary Production by Derrald Vogt and Chris Everett Engineering contributions by John Barco, Brian Beach, Don Bennett, David Bertrand, Mark Callow, Wiltse Carpenter, Andrew Cherenson, Doug Cook, Jonathan Devine, Grant Dorman, Dan Fink, Ron Fischer, Jeff Glover, Brian Hill, Bryan James, Bruce Karsh, Robert Keller, Eva Manolis, Ted Marsh, Spencer Murray, Paul Ning, Candace Obert, Gordon Oliver, Chris Pirazzi, Scott Porter, Mike Portuesi, Scott Pritchett, Amit Shoham, Paul Spencer, Dave Story, Archer Sully, Ann Sydeman, Alex Tang, Mike Travis, I-Ching Wang, Jim Wanslow, and Jim Wiggins. Cover design and illustration by Rob Aguilar, Rikk Carey, Dean Hodgkinson, Erik Lindholm, and Kay Maitz © Copyright 1994, Silicon Graphics, Inc.— All Rights Reserved This document contains proprietary and confidential information of Silicon Graphics, Inc. The contents of this document may not be disclosed to third parties, copied, or duplicated in any form, in whole or in part, without the prior written permission of Silicon Graphics, Inc. RESTRICTED RIGHTS LEGEND Use, duplication, or disclosure of the technical data contained in this document by the Government is subject to restrictions as set forth in subdivision (c) (1) (ii) of the Rights in Technical Data and Computer Software clause at DFARS 52.227-7013 and/or in similar or successor clauses in the FAR, or in the DOD or NASA FAR Supplement. Unpublished rights reserved under the Copyright Laws of the United States. Contractor/manufacturer is Silicon Graphics, Inc., 2011 N. Shoreline Blvd., Mountain View, CA 94039-7311. Silicon Graphics, Indigo, IRIS, and the Silicon Graphics logo are registered trademarks and CHALLENGE, Cosmo Compress, Galileo Video, GL, Graphics Library, Image Vision Library, IndigoVideo, Indigo2, Indigo2 Video, Indy, Indy Cam, Indy Video, IRIS GL, IRIS Graphics Library, IRIS Indigo, IRIS InSight, IRIX, OpenGL, Personal IRIS, Sirius Video, Showcase, and VINO are trademarks of Silicon Graphics, Inc. Aware and the Aware logo are registered trademarks and AudioPlayback, AudioProducer, AudioPublisher, AudioSuite, Archiver, Audition, BrowsFX, IRIS Digital Media Programming Guide Document Number 007-1799-040 MultiRate, Psycoder, and Speed-of-Sound are trademarks of Aware, Inc. Betacam and Sony are registered trademarks and Hi-8mm is a trademark of Sony Corporation. Macintosh is a registered trademark and AppleTalk and QuickTime are trademarks of Apple Computer, Inc. MII is a trademark of Panasonic, Inc. Network License System and NetLS are trademarks of Apollo Computer Inc., a subsidiary of Hewlett-Packard Company. Prosonus is a registered trademark of Prosonus. MIPS and R3000 are registered trademarks of MIPS Technologies, Inc. Open Software Foundation is a registered trademark and OSF/Motif is a trademark of the Open Systems Foundation. S-VHS is a trademark of JVC, Inc. UNIX is a trademark of AT&T Bell Labs. X Window System is a trademark of Massachusetts Institute of Technology. IRIS Digital Media Programming Guide Document Number 007-1799-040 Contents List of Examples xxiii List of Figures xxvii List of Tables xxxi About This Guide xxxv What This Guide Contains xxxv How to Use This Guide xxxix Where to Start xxxix Style Conventions xxxix How to Use the Sample Programs xxxix Suggestions for Further Reading xl References for Using Digital Media with Other Libraries xl References for Adding a User Interface to Your Program xli PART ONE Digital Media Programming 1. Programming with the IRIS Digital Media Development Environment 5 About the Digital Media Library 6 About the Digital Audio and MIDI Libraries 6 About the Video Library 7 About the IndigoVideo Library 8 About the Compression Library 8 About the Movie Library 9 v Contents 2. Programming with the Digital Media Library 13 Digital Media Library Basics 13 Digital Media Type Definitions 13 Digital Media Parameters 15 Compiling and Linking a Digital Media Library Application 15 Debugging a Digital Media Library Application 16 Initializing a Digital Media Application 16 Creating and Destroying Parameter-value Lists 17 Creating Default Audio and Image Configurations 18 Setting and Getting Individual Parameter Values 25 Manipulating Parameter-value Lists 29 Synchronizing Digital Media 33 PART TWO Digital Audio and MIDI Programming 3. Introduction to Digital Audio and MIDI Programming 39 4. Digital Audio System Architecture 43 Indigo Audio System Architecture 43 Indigo Audio Features 43 Indigo Audio I/O Interface 44 Indigo2 and Indy Audio System Architecture 46 Indigo2 and Indy Audio I/O Interface 46 Indy Workstation Layout 47 4-channel Audio I/O Interface 49 Recommendations for Audio Development System Configurations 50 Memory 50 Disk Space 50 Peripherals 51 5. Digital Audio System Software 55 Digital Audio System Software Overview 55 About the Digital Audio Libraries 56 About Shared System-Wide Resources 57 vi Contents Tools Available for the Audio Application Developer 60 Graphical User Interface Audio Tools 60 Online Source Code Examples 61 Third-party Audio Software and Sound Libraries 61 Compiling and Linking an Audio Application 62 6. Programming with the Audio Library 67 Audio Library Basics 68 Audio Library Features 68 Audio Library Programming Model 68 Digital Audio Data Representation 69 Handling Audio Library Errors 72 Audio Library Application Programming Concepts 73 Initializing an Audio Library Application 74 About ALports 74 Using ALconfig Structures to Configure ALports 74 Opening and Closing Audio Ports 87 Reading and Writing Audio Data 90 Using Audio Sample Queues 90 Reading and Writing Samples 93 Detecting Errors in the Audio Stream 97 Querying and Controlling the Global Audio Device State 98 Techniques for Working with Global Parameters 102 Sample Code for Querying Features and Values 107 Audio Library Synchronization Facilities 112 Audio Sample Frame Count 112 Relating Audio Sample Frame Count to UST 116 Real-time Programming Techniques for Audio 119 Multiplexing Synchronous I/O 119 Using Scheduling Control to Give Audio High Priority 122 Preventing Memory Swapout 122 Creating Multiple Process Threads 122 Using Shared Arenas and Semaphores 123 vii Contents 7. Programming with the Audio File Library 127 Audio File Library Basics 128 Audio File Library Programming Model 128 Handling Audio File Library Errors 128 About Audio Files 129 Creating and Configuring Audio Files 132 Creating an Audio File Setup 132 Initializing Audio File Format 133 Initializing Audio Track Data 134 Initializing Instrument Data 140 Initializing Miscellaneous Data 141 Using the Audio Utility Library to Initialize Parameter Lists 143 Opening, Closing, and Updating Audio Files 147 Opening an Audio File 147 Getting an IRIX File Descriptor for an Audio File 148 Closing and Updating Files 149 Reading and Writing Audio Track Information 150 Getting Audio File Format 150 Getting and Setting Audio Track Parameters 152 Seeking, Reading, and Writing Audio Track Frames 160 Reading and Writing Instrument Configurations 163 Handling Miscellaneous Data Chunks 168 Audio File Library Programming Tips 171 Minimizing Data and File Format Dependence 171 Preventing Concurrent Access from Multiple Threads 172 Handling Errors in Multithreaded Applications 176 Sample Audio File Program 177 viii Contents 8. Programming with the CD Audio Library 183 CD Audio Library Basics 184 CD Frames, Samples, and Subcodes 184 CD Tracks, Indices, and Time Codes 186 CD Seeking, Reading, and Playing 186 CD Parser 186 Opening and Closing the CD-ROM Device 187 Controlling the CD-ROM Drive Caddy 187 Navigating through a CD 187 Getting CD Locations from the End User 188 Getting CD Locations from Calculations Internal to Your Application 188 Getting the Current CD Location 189 Seeking to a CD Location 189 Using the CD-ROM Drive 190 Playing an Audio CD from the CD-ROM Drive 190 Reading Audio Data from the CD-ROM Drive 191 Controlling the CD Parser 192 Communicating CD Status to the End User 194 CD Time Code Conversion Routines 195 CD Sample Program 196 9. Programming with the DAT Audio Library 203 DAT Audio Library Basics 203 DAT Frames, Samples, and Subcodes 204 DAT Audio Program Numbers and Indices 205 DAT Run Time, Absolute Time, and Program Time 205 DAT Seeking and Reading 205 DAT Parser 205 Opening and Closing the DAT Device for Audio 206 ix Contents Navigating through a DAT 206 Getting DAT Locations from the End User 207 Getting DAT Locations from Calculations Internal to Your Application 207 Seeking to a DAT Location 208 Using the DAT Drive 209 Playing a Tape in the DAT Drive 209 Making DAT Recordings for Playback on the DAT Drive 210 Reading Audio Data from the DAT Drive 211 Writing Audio Data to the DAT Drive 211 Controlling the DAT Parser 213 Communicating DAT Status to the End User 217 DAT Sample Program 217 Playing a DAT 217 10. Programming with the MIDI Library 223 MIDI System Architecture 224 Configuring Your System for MIDI Development 224 Connecting Devices to MIDI I/O Interfaces 227 Configuring Serial Ports for MIDI WIth the Port Setup Tool 229 MIDI Library Basics 231 Initializing MIDI Library Programs 231 Compiling and Linking MIDI Library Programs 231 MIDI Library Error Handling 231 MIDI Library Programming Model 232 Opening and Closing MIDI Ports 232 Getting the Name of an Available MIDI Port 232 Opening and Closing MIDI Input and Output Ports 233 Programming MIDI I/O 234 Hands-On MIDI Output Experience 234 About MIDI Events 235 Sending and Receiving MIDI Events 236 Printing MIDI Events 237 Processing MIDI Event Messages 238 x Contents Multiplexing MIDI I/O with File Descriptors 240 Hands-On Multiplexed MIDI I/O Experience 240 Getting a File Descriptor for a MIDI Port 240 Controlling MIDI Timing 241 Controlling MIDI Timing Mode 241 Controlling MIDI Tempo 243 Controlling MIDI Output Buffering 243 Hands-On MIDI File Player Experience 244 Synchronizing MIDI I/O with Other Media 246 Hands-On MIDI and Audio Synchronization Experience 246 PART THREE Video Programming 11.