TweetFollow Us on Twitter

Playing sound
Volume Number:7
Issue Number:1
Column Tag:XCMD Corner

Playing With Sound

By Donald Koscheka, Contributing Editor

Note: Source code files accompanying article are located on MacTech CD-ROM or source code disks.

The Importance of XCMDs

One of the questions that is raised by Hypercard 2.0’s new XCMD interface is, “How important are XCMDs to the vitality of the Macintosh?”. One cannot imagine that XCMDs would be very important at all so it would be useful to the xcmd programmer to ponder the future of xcmds in the Macintosh programming world.

After studying Hypercard 2.0 in great detail, I’ve concluded that XCMDs are very important to the success of this product and that Apple Computer, Inc. is acknowledging this by providing more services to the XCMD programmer such as windoids and script manipulation capability. But another event in the small computer world lends even more credence to XCMD as programming art. That event is quietly taking over the MS-DOS world as Microsoft successfully evangelizes the concept of Dynamic Link Libraries, or DLLs.

If you’re not a PC programmer (and who can afford not to be), then you may not know that DLLs are code modules that are written in such a way as to be loadable and thus callable at any time. DLLs are code segments that have a standard programming interface associated with them. In effect, DLLs allow you to build re-usable code modules that in theory can be used in any application. Well, if every application had such an interface on the Mac, let’s call it XCmdPtr, then xcmds would serve the same purpose -- the ability to call xcmds from any program that runs on the mac. Without a lot of induction, one can come to the conclusion that if xcmds can give you this type of capability on the Mac, then they are indeed important, at least at the conceptual level.

If xcmds become callable from any application then they become an integral part of the future of the Macintosh. It is not unimaginable to believe that someday you will flesh-out your application with some sort of screen generator and then build a set of xcmds to implement the application-specific code. I find it impossible to believe that this effective approach to programming won’t become the norm for all programmers in the future. In fact, Michael Swain suggests exactly this approach for PC programmers using ToolBook ( “Dr. Dobbs Journal”, November, 1990). When I read this column, my eyes popped out of my head. Mr. Swain’s concept of marrying rapid prototyping with rapid code development via DLL’s is exactly what we’ve been doing with Hypercard for the last three years. Any Windows developer that takes his advice will wonder what all the fuss was about; Windows will appear to be an easy and natural development environment.

So now I can rest easy. I am convinced that the XCMD approach to programming will prevail over time. It’s working for me. By forcing me to avoid globals and to think modularly, XCMDs have allowed me to write code that is re-usable in a wide-variety of applications. Each time I write an XCMD, I create a piece of code that I not only know I will use again but that I can comfortably extract from Hypercard without worrying about breaking it. That is the programmer’s holy grail and that is why XCMDs not only have a future, they are the future.

Playsound

Several months ago, I got a call from Bill Leitman, a fellow Mac developer in the New York area. He was working with a small film company in Brooklyn that needed an xcmd that played a portion of a sound resource. Bill’s approach was quite reasonable, he took a piece of code that he knew to be working from another application and dropped it into an xcmd. Lo and behold, it didn’t work. He called me in desperation to see if there was anything that I knew about xcmds that was causing his problem. To no avail, I also tried to get the sound manager to work from within an xcmd but after hours of head scratching and staring at TMON windows, I came to the conclusion that Hypercard just wasn’t going to let me use the sound manager.

This was unfortunate and unbelievable, but I’ve never been able to find a way to get the sampled synth playing in an xcmd. Imagine my surprise when I first encountered the following callbacks in Hypercard 2.0: BEGINXSOUND and ENDXSOUND. Is it possible that it wasn’t me? Did Hypercard actually work the way I thought it did by taking over the sound driver and not making it available to anyone else. I don’t know the answer to this question, ‘tho I’d like to so please write if you have some input. I do know that this must have been a problem since Apple went to the motions of adding these callbacks, which work quite perfectly for me.

This month’s playsound xcmd (listing 1) was inspired by Mr. Leitman and I am grateful to him that he gave me an excuse to explore the sound manager. It’s more daunting than the Sunday Times crossword puzzle and just as much fun!

Playsound takes up to four parameters: the first is the name of the file to retrieve the sound resource from. The second parameter is the name of the sound resource to retrieve. The third parameter is the index to the sample to start playing from (0 means play from the beginning of the sound). The fourth parameter is the last sample to play to. These last two parameters are optional, if they are left out, the entire sound resource will be played.

For simplicity, this code makes two assumptions that you can modify to meet your own needs: (1) you want to play the sound using the sampled synthesizer and (2) the sound is a format 2 ‘snd ‘ resource. I chose not to support format 1 ‘snd ‘ resources because Inside Macintosh indicates that format 2 snd resources should be adopted by developers as a standard. Should you decide that you want to support format 1 resources, refer to page 491 of Inside Macintosh Volume V for details on that format.

The xcmd parses out the parameters, opens the appropriate resource file and loads the ‘snd ‘ resource which it then detaches from the resource map. This is important because we are going to modify the resource and we don’t want the changes to be written back out by mistake. We call BEGINXSOUND to advise hypercard that we want to take over the sound drive for a while. Next we call PlayRunSound to play the sound, or sound fragment, and then we call ENDXSOUND to give the sound driver back to Hypercard.

PlayRunSound() is the heart and soul of this xcmd. The first thing that it does is check to see if the appropriate synthesizer is available. If so, it then allocates a new channel via the SndNewChannel call. This call returns a pointer to our new channel, initialized for the sampled synthesizer in theChan. We will pass this pointer to SndDoCommand to play this sound on that channel.

Once the channel is initialized and we know that we can use it, we set the start and stop time of the sound and play it. The first thing we need to do is check to see if we have the correct resource format which we do by testing to make sure that the first word in the resource (sndHdl) is set to 2. If it is, then we can access the fields in the snd resource by referring to the documentation on page 494 of IM vol V.

Figure 1. A typical format 2 ‘snd ‘ resource.

Here is how the sound fragment scheme works: The snd resource contains some header information (6 bytes) followed by a number of 8 byte sound commands (the sample sound resource in figure 1 contains only one sound command). The sound data immediately follows the sound commands. If there is only one sound command, then the sampled data table will begin at offset 14 (0x0E) in the record.

The first two long words in the sound data table tell us where the samples start and how many of them there are. The where is usually set to 0 and the how much is usually set to the number of samples to play back. We can modify these fields to change the starting point and the number of samples to play. Or, we can set just the new starting point and play back to the end of the sound. Playsound doesn’t use the sound command (in this case, ‘soundCmd’) but rather uses the ‘bufferCmd’ instead.

So, we modify the sound table by stuffing new values for the pointer and length and then call the sound manager via the bufferCmd. Once the sound is done playing, we call SndDisposeChannel to remove our allocated channel, in effect freeing up the sampled synthesizer in preparing to give it back to Hypercard. That’s all there is to it. You might want to use this xcmd to continue to explore the sound manager. It appears to have rich and intriguing repertoire. In fact, I hope to present more on the sound manager in the future. In the meantime, I will continue to illuminate Hypercard 2.0. Happy Hacking.

Listing 1:  PlaySndFrag.c
/********************************/
/* File: PlaySndFrag.c    */
/********************************/
#define UsingHypercard

#include  <SoundMgr.h>
#include<SetupA4.h>
#include  <HyperXCmd.h>
/* usage: playSndFrag fileName, soundName, start ,stop
 project requires the following files or libraries:
 ANSI-A4-- the A4 based standard “C” libraries
 HyperXLib-- the xcmd callback glue
 MacTraps -- what it is
 PlaySnd.c-- this file */
 
void    putResult( XCmdPtr pp, char *msg);
void  PlayRunSound( Handle sndHdl, long start, long stop );
long  paramtoNum( XCmdPtr pp, short i );
void  paramtoPString( XCmdPtr pp, short i, char *str );
Handle  strToParam( char  *str );

#ifndef NIL
 #defineNIL (void *)0L
#endif

pascal void main( XCmdPtr pp )
/******************************************
* The main entry point 
******************************************/
{
 short resFile;  /*** resource file holding ‘snd ‘ ***/
 short saveResFile; /*** previous resource file id ***/
 Handle sndHdl; /*** handle to the sound resource ***/
 long start; /*** start sample in sound ***/
 long stop; /*** end sample in sound ***/
 char  *temp[256]; 
 /*** for converting to pascal strings ***/
   
 pp->returnValue = NIL;  /* empty return means OK */
 if (pp->paramCount == 1){
 if ( **(pp->params[0]) == ‘!’ ){
 pp->returnValue = strToParam(“Play Sound XCMD, version 1.0, ©Donald 
Koscheka, 1990”);
 return;
 }
 
 if ( **(pp->params[0]) == ‘?’ ){
 pp->returnValue = strToParam(“PlaySound FILE, ‘snd ‘ rsrc id [,start][,stop]”);
 return;
 }
 }

 paramtoPString( pp, 0, (char *)&temp );           
 start  = paramtoNum( pp, 2 );
 stop   = paramtoNum( pp, 3 );
  
 saveResFile = CurResFile(); /* save current res file id */
 resFile = OpenResFile( temp );
  
 if (resFile == -1) {
 putResult( pp, “can’t open resource file” );
 return;
 }
 
 UseResFile( resFile );  /* in case it was already open */
 paramtoPString( pp, 1, (char *)&temp );
 sndHdl = Get1NamedResource( ‘snd ‘, &temp );
 /* getting the resource ok */
 
 if(!sndHdl){
   putResult( pp, “no such snd” );
 UseResFile( saveResFile ); 
   return;
 }
 
   BEGINXSOUND( pp, NIL );
 DetachResource( sndHdl );
    PlayRunSound( sndHdl, start, stop );
 DisposHandle( sndHdl );
    ENDXSOUND( pp );
    
 UseResFile( saveResFile ); 
}
 
void  PlayRunSound( sndHdl, start, stop )
 Handle sndHdl;
 long   start;
 long stop;
/**********************************
* st[0] determines whether we have a
* format 2 or a format 1 ‘snd ‘ resource.    
* currently use the 44K sampler. Refer to Inside Macintosh Vol V p.494 
for the format of a format 2 ‘snd ‘ resource
**********************************/
{
    short *st;
    long  *lt;
    SndCommand   sndCmd;
   long idx;
 SndChannelPtr theChan  = NIL;
 OSErr    err;
   
 sndCmd.cmd = availableCmd;
 
 if( err = SndControl( sampledSynth, &sndCmd ) ) return;
 if( err = SndNewChannel( &theChan, sampledSynth, initSRate44k, NIL ) 
) return; 
  
 HLock( sndHdl );
   st = (short *)*sndHdl;
 sndCmd.cmd = bufferCmd;
   sndCmd.param1 = 0L;
 if( *st == 2){
 idx  = 6L + ((long)st[2] << 3);
 /* offset to start of commands    */
 lt     = *sndHdl + idx;
   sndCmd.param2 = (long)lt;
   
   if( start )
   lt[0]= (long)*sndHdl + idx + start; 
   
   if( stop )
        lt[1]  = stop  - start;  
        
 err = SndDoCommand( theChan, &sndCmd, FALSE );
   err = SndDisposeChannel( theChan, FALSE );
 }
 HUnlock( sndHdl );
}
 
void putResult( XCmdPtr pp , char *msg )
{
   if (pp->returnValue)   
 DisposHandle(pp->returnValue);  
 
   pp->returnValue = (Handle)NewHandle(1 + strlen(msg) );
   strcpy( *(pp->returnValue), msg);
}
 
Handle  strToParam( char  *str )
/***************************
* Given a pointer to a string, copy that string into a handle
* and return the handle.
* The input and output strings are both null-terminated
***************************/
{
 Handle outH = NIL;
 long len = 0;
 
 len = strlen( str );
 if( len )
 if( outH = NewHandle( len ) )
 BlockMove( str, *outH, len + 1 );
 return( outH );
}

void  paramtoPString( XCmdPtr pp, short i, char *str )
/************************
* Given an index into the parameter list, convert the data
* in the Block into a pstring
*
* This sequence is so common in XCMDs that it makes sense to make it 
a subr. This is a generic routine that you can use in any xcmd.
************************/
{
 if( pp->params[i] ){
 HLock( pp->params[i] );
 ZEROTOPAS( pp, (Ptr)*(pp->params[i]), (StringPtr)str );
 HUnlock( pp->params[i] );
 }
 else
 *str = ‘\0’;
}

long  paramtoNum( XCmdPtr pp, short i )
/************************
* Given a Block to an input argument in the paramBlk
* return an integer representation of the data.
************************/
{
 char   theStr[32];
 
 theStr[0] = ‘\0’;
 if( pp->params[i] ){
 HLock( pp->params[ i ] );
 ZEROTOPAS( pp, (char *)*(pp->params[ i ]), theStr );
 HUnlock( pp->params[ i ] );
 return STRTOLONG( pp, theStr );
 }
 return 0L;
}

 

Community Search:
MacTech Search:

Software Updates via MacUpdate

Opera 48.0.2685.50 - High-performance We...
Opera is a fast and secure browser trusted by millions of users. With the intuitive interface, Speed Dial and visual bookmarks for organizing favorite sites, news feature with fresh, relevant content... Read more
Tor Browser Bundle 7.0.7 - Anonymize Web...
The Tor Browser Bundle is an easy-to-use portable package of Tor, Vidalia, Torbutton, and a Firefox fork preconfigured to work together out of the box. It contains a modified copy of Firefox that... Read more
FotoMagico 5.5 - Powerful slideshow crea...
FotoMagico lets you create professional slideshows from your photos and music with just a few, simple mouse clicks. It sports a very clean and intuitive yet powerful user interface. High image... Read more
Adobe Audition CC 2018 11.0.0 - Professi...
Audition CC 2018 is available as part of Adobe Creative Cloud for as little as $19.99/month (or $9.99/month if you're a previous Audition customer). Adobe Audition CC 2018 empowers you to create and... Read more
Alfred 3.5.1 - Quick launcher for apps a...
Alfred is an award-winning productivity application for OS X. Alfred saves you time when you search for files online or on your Mac. Be more productive with hotkeys, keywords, and file actions at... Read more
AirRadar 4.0 - $9.95
With AirRadar, scanning for wireless networks is now easier and more personalized! It allows you to scan for open networks and tag them as favourites or filter them out. View detailed network... Read more
DEVONthink Pro 2.9.16 - Knowledge base,...
Save 10% with our exclusive coupon code: MACUPDATE10 DEVONthink Pro is your essential assistant for today's world, where almost everything is digital. From shopping receipts to important research... Read more
ForkLift 3.0.8 Beta - Powerful file mana...
ForkLift is a powerful file manager and ferociously fast FTP client clothed in a clean and versatile UI that offers the combination of absolute simplicity and raw power expected from a well-executed... Read more
Data Rescue 5.0.1 - Powerful hard drive...
Data Rescue’s new and improved features let you scan, search, and recover your files faster than ever before. We have modernized the file-preview capabilities, added new files types to the recovery... Read more
Dropbox 37.4.29 - Cloud backup and synch...
Dropbox is an application that creates a special Finder folder that automatically syncs online and between your computers. It allows you to both backup files and keep them up-to-date between systems... Read more

Halcyon 6: Starbase Commander (Games)
Halcyon 6: Starbase Commander 1.4.2.0 Device: iOS Universal Category: Games Price: $6.99, Version: 1.4.2.0 (iTunes) Description: An epic space strategy RPG with base building, deep tactical combat, crew management, alien diplomacy,... | Read more »
Legacy of Discord celebrates its 1 year...
It’s been a thrilling first year for fans of Legacy of Discord, the stunning PvP dungeon-crawling ARPG from YOOZOO Games, and now it’s time to celebrate the game’s first anniversary. The developers are amping up the festivities with some exciting... | Read more »
3 reasons to play Thunder Armada - the n...
The bygone days of the Battleship board game might have past, but naval combat simulators still find an audience on mobile. Thunder Armada is Chinese developer Chyogames latest entry into the genre, drawing inspiration from the explosive exchanges... | Read more »
Experience a full 3D fantasy MMORPG, as...
Those hoping to sink their teeth into a meaty hack and slash RPG that encourages you to fight with others might want to check out EZFun’s new Eternity Guardians. Available to download for iOS and Android, Eternity Guardians is an MMORPG that lets... | Read more »
Warhammer Quest 2 (Games)
Warhammer Quest 2 1.0 Device: iOS Universal Category: Games Price: $4.99, Version: 1.0 (iTunes) Description: Dungeon adventures in the Warhammer World are back! | Read more »
4 of the best Halloween updates for mobi...
Halloween is certainly one of our favorite times for mobile game updates. Many popular titles celebrate this spooky season with fun festivities that can stretch from one week to even the whole month. As we draw closer and closer to Halloween, we'... | Read more »
Fire Rides guide - how to swing to succe...
It's another day, which means another Voodoo game has come to glue our hands to our mobile phones. Yes, it's been an especially prolific month for this particular mobile publisher, but we're certainly not complaining. Fire Rides is yet another... | Read more »
Time Recoil (Games)
Time Recoil 1.0.1 Device: iOS Universal Category: Games Price: $3.99, Version: 1.0.1 (iTunes) Description: Time Recoil is a top-down shooter where you kill to slow time, dominate slow motion gunfights, and trigger devastating special... | Read more »
Campfire Cooking (Games)
Campfire Cooking 1.0 Device: iOS Universal Category: Games Price: $3.99, Version: 1.0 (iTunes) Description: | Read more »
Returner 77 (Games)
Returner 77 1.0 Device: iOS Universal Category: Games Price: $4.99, Version: 1.0 (iTunes) Description: Returner 77 is a cinematic space mystery puzzle game. You are in a giant alien spaceship hovering above Earth, after everything... | Read more »

Price Scanner via MacPrices.net

Apple restocks full line of refurbished 13″ M...
Apple has restocked a full line of Apple Certified Refurbished 2017 13″ MacBook Pros for $200-$300 off MSRP. A standard Apple one-year warranty is included with each MacBook, and shipping is free.... Read more
13″ 3.1GHz/256GB MacBook Pro on sale for $167...
Amazon has the 2017 13″ 3.1GHz/256GB Space Gray MacBook Pro on sale today for $121 off MSRP including free shipping: – 13″ 3.1GHz/256GB Space Gray MacBook Pro (MPXV2LL/A): $1678 $121 off MSRP Keep an... Read more
13″ MacBook Pros on sale for up to $120 off M...
B&H Photo has 2017 13″ MacBook Pros in stock today and on sale for up to $120 off MSRP, each including free shipping plus NY & NJ sales tax only: – 13-inch 2.3GHz/128GB Space Gray MacBook... Read more
15″ MacBook Pros on sale for up to $200 off M...
B&H Photo has 15″ MacBook Pros on sale for up to $200 off MSRP. Shipping is free, and B&H charges sales tax in NY & NJ only: – 15″ 2.8GHz MacBook Pro Space Gray (MPTR2LL/A): $2249, $150... Read more
Roundup of Apple Certified Refurbished iMacs,...
Apple has a full line of Certified Refurbished 2017 21″ and 27″ iMacs available starting at $1019 and ranging up to $350 off original MSRP. Apple’s one-year warranty is standard, and shipping is free... Read more
Sale! 27″ 3.8GHz 5K iMac for $2098, save $201...
Amazon has the 27″ 3.8GHz 5K iMac (MNED2LL/A) on sale today for $2098 including free shipping. Their price is $201 off MSRP, and it’s the lowest price available for this model (Apple’s $1949... Read more
Sale! 10″ Apple WiFi iPad Pros for up to $100...
B&H Photo has 10.5″ WiFi iPad Pros in stock today and on sale for $50-$100 off MSRP. Each iPad includes free shipping, and B&H charges sales tax in NY & NJ only: – 10.5″ 64GB iPad Pro: $... Read more
Apple iMacs on sale for up to $130 off MSRP w...
B&H Photo has 21-inch and 27-inch iMacs in stock and on sale for up to $130 off MSRP including free shipping. B&H charges sales tax in NY & NJ only: – 27″ 3.8GHz iMac (MNED2LL/A): $2179 $... Read more
2017 3.5GHz 6-Core Mac Pro on sale for $2799,...
B&H Photo has the 2017 3.5GHz 6-Core Mac Pro (MD878LL/A) on sale today for $2799 including free shipping plus NY & NJ sales tax only . Their price is $200 off MSRP. Read more
12″ 1.2GHz Space Gray MacBook on sale for $11...
Amazon has the 2017 12″ 1.2GHz Space Gray Retina MacBook on sale for $100 off MSRP. Shipping is free: 12″ 1.2GHz Space Gray MacBook: $1199.99 $100 off MSRP Read more

Jobs Board

*Apple* Retail - Multiple Positions - Farmin...
Sales Specialist - Retail Customer Service and Sales Transform Apple Store visitors into loyal Apple customers. When customers enter the store, you're also the Read more
Frameworks Engineer, *Apple* Watch - Apple...
Job Summary Join the team that is shaping the future of software development for Apple Watch! As a software engineer on the Apple Watch Frameworks team you will Read more
*Apple* News Product Marketing Mgr., Publish...
Job Summary The Apple News Product Marketing Manager will work closely with a cross-functional group to assist in defining and marketing new features and services. Read more
Fraud Analyst, *Apple* Advertising Platform...
Job Summary Apple Ad Platforms has an opportunity to redefine advertising on mobile devices. Apple reaches hundreds of millions of iPhone, iPod touch, and iPad Read more
*Apple* Information Security - Security Data...
Job Summary This role is responsible for helping to strengthen Apple 's information security posture through the identification and curation of security event data. Read more
All contents are Copyright 1984-2011 by Xplain Corporation. All rights reserved. Theme designed by Icreon.