Inside Macintosh: Sound /

Chapter 1 - Introduction to Sound on the Macintosh / Using Sound on Macintosh Computers

Recording a Sound Resource

You can record sounds from the current input device by using the SndRecord function. The SndRecord function presents the sound recording dialog box. When calling SndRecord, you need to provide a handle to a block of memory where the incoming data should be stored. If you pass the address of a NIL handle, however, the Sound Input Manager allocates a large block of space in your application heap and resizes it when the recording stops. Listing 1-4 illustrates how to call SndRecord.

Listing 1-4 Recording through the sound recording dialog box

PROCEDURE MyRecordThruDialog (VAR mySndHandle: Handle);
VAR
   myErr:      OSErr;
   myCorner:   Point;
BEGIN
   MyGetTopLeftCorner(myCorner);
   mySndHandle := NIL;     {use default memory allocation}
   myErr := SndRecord(NIL, myCorner, siBestQuality, mySndHandle);
   IF (myErr <> noErr) AND (myErr <> userCanceledErr) THEN
      DoError(myErr);
END;

If the user cancels sound recording, then the SndRecord function returns the result code userCanceledErr. The MyRecordThruDialog procedure defined in Listing 1-4 returns a NIL sound handle if the user cancels recording.

If you pass a sound handle that is not NIL as the fourth parameter to the SndRecord function, the Sound Input Manager derives the maximum time of recording from the amount of space reserved by that handle. The handle is resized on completion of the recording.

The first parameter in the call to SndRecord is the address of a filter procedure that determines how user actions in the dialog box are filtered. In Listing 1-4, no filter procedure is desired, so the parameter is specified as NIL. For information on filter procedures, see the chapter "Dialog Manager" in Inside Macintosh: Macintosh Toolbox Essentials.

The second parameter in the call to SndRecord is the desired location (in global coordinates) of the upper-left corner of the dialog box. For example, the Sound control panel displays the dialog box near the control panel. Your application might place the dialog box elsewhere (for example in the standard alert position on the main screen). For more information on centering dialog boxes, see the chapter "Dialog Manager" in Inside Macintosh: Macintosh Toolbox Essentials.

The third parameter in the call to SndRecord specifies the quality of the recording. Currently three values are supported:

CONST
   siBestQuality     = 'best';   {the best quality available}
   siBetterQuality   = 'betr';   {a quality better than good}
   siGoodQuality     = 'good';   {a good quality}

The precise meanings of these constants are defined by the current sound-input device driver. The constant siBestQuality indicates that you want the highest quality recorded sound, usually at the expense of increased storage space (possibly because no compression is performed on the sound data). The constant siGoodQuality indicates that you are willing to sacrifice audio quality if necessary to minimize the amount of storage space required (typically this means that 6:1 compression is performed on the sound data). For most voice recording, you should specify siGoodQuality. The constant siBetterQuality defines a quality and storage space combination that is between those provided by the other two constants.

You could play the sound recorded using the MyRecordThruDialog procedure defined in Listing 1-4 by calling SndPlay and passing it the sound handle mySndHandle. That handle refers to some data in memory that has the structure of an 'snd ' resource, but it is not a handle to an existing resource. To save the recorded data as a resource, you can use the Resource Manager. Listing 1-5 calls the MyRecordThruDialog procedure and then uses the Resource Manager to save the recorded data as a resource in an open resource file.

Listing 1-5 Recording a sound resource

PROCEDURE MyRecordSndResource (resFileRefNum: Integer);
CONST
   kMinSysSndRes = 0;               {lowest reserved 'snd ' resource ID}
   kMaxSysSndRes = 8191;            {highest reserved ID}
VAR
   myPrevResFile:       Integer;    {current resource file}
   mySndHandle:         Handle;     {handle to resource data}
   myResID:             LongInt;    {ID of resource}
   myResName:           Str255;     {name of resource}
   myErr:               OSErr;
BEGIN
   myPrevResFile := CurResFile;     {remember current resource file}
   UseResFile(resFileRefNum);       {temporarily switch resource files}
   MyRecordThruDialog(mySndHandle); {record via standard interface}
   IF mySndHandle <> NIL THEN
   BEGIN                            {recording finished successfully}
      REPEAT                        {find acceptable resource ID number}
         myResID := Unique1ID('snd ');
      UNTIL (myResID < kMinSysSndRes) OR (myResID > kMaxSysSndRes);
                              
      MyGetSoundName(myResName);    {get name for sound resource}
                                    {add resource to file}
      AddResource(mySndHandle, 'snd ', myResID, myResName);
      myErr := ResError;
      IF myErr = noErr THEN
      BEGIN
         UpdateResFile(resFileRefNum);    {update resource file}
         myErr := ResError;
      END;
      IF myErr <> noErr THEN 
         DoError(myErr);
   END;
   UseResFile(myPrevResFile);       {restore previous resource file}
END;

The MyRecordSndResource procedure defined in Listing 1-5 takes as a parameter the reference number of an open resource file to which you wish to record. The procedure makes that resource file the current resource file and, after recording, reverts to what was previously the active resource file. Note that you should not record to your application's resource fork, because applications that write to their own resource forks cannot be used by multiple users at once over a network. For more information on reference numbers for resource files, see the chapter "Resource Manager" in Inside Macintosh: More Macintosh Toolbox.

The MyRecordSndResource procedure first presents the sound recording dialog box by calling the MyRecordThruDialog procedure defined in Listing 1-4 on page 1-28. If that procedure returns a valid sound handle, MyRecordSndResource finds an acceptable resource ID for the resource file and then calls a procedure that returns a name for the resource (perhaps by presenting a dialog box that asks the user to name the sound). Finally, MyRecordSndResource adds the resource to the specified resource file and updates that file by calling the Resource Manager procedure UpdateResFile.