MacMix Processing and Synthesis UserHooks

Things you will need

• Macintosh
• Dyaxis Digital Audio Processor
• MacMix2.4 or later
• Think C 3.0 or later
• MacMix UserHooksIII toolkit disk

External Functions

Some MacMix users have asked for hooks into MacMix so that they can write their own external functions for signal processing and synthesis. This package describes a new facility for external functions.

External functions may be added into either the Process or the Synthesize menu of MacMix. A processing function takes the data from the sound segment of a currently active view window, processes it, and writes out a new Dyaxis sound file. A synthesis function writes out a new Dyaxis sound file from scratch.

How it works

(This implementation is modeled on Hypercard XCMD and XFCN resources, a similar mechanism to add new functions to the HyperTalk language.)

You can use ThinkC to create code resources which MacMix can dynamically load and execute. Two new resource types are used: 'Cprc' for processing functions, and 'Csyn' for synthesis functions. The 'main' function must accept a data pointer that MacMix will pass to it. This data structure includes fields such as the volume number and file name of a Dyaxis sound file. Your code resource will open, close, read and write these sound files.

Building code resources is discussed in Chapter 7 of your ThinkC manual.

When MacMix starts, it scans the folder it which it resides for files of type 'MHUK'. These files contain the code resources ('Cprc' or 'Csyn' ) called by Macmix when the user selects an item from the Process and Synthesize menu. The name of the item that appears in the menu is the name that you give the code resource (if you don't give the resource a name, then it will not appear in the menu).

When you select an item in the synthesis or processing pulldown menus, MacMix opens the file that contains the requested code resource and loads that resource. Before calling out to this code resource, MacMix uses a dialog box to allow the user to select and configure an output sound file. It passes the output file information (and the input file for processing functions) to your external function. See the declarations in the two header files processData.h and synthData.h for a complete description of the parameters passed.

Your function should return a Boolean value. If it is successful, return true. MacMix will open a view of the new output file you have just created.

How to Write External Function Code Resources

• SEC supplies a folder, "CommonCode", with the extension toolkit. It contains the Cext project and some header files which you must include in your project as described below.

• Decide if you are writing a synthesis or processing function.

• Create a new project for your external function. Your project must be a code resource of type 'Cprc' or 'Csyn' and its resource name should not conflict with other code resources. The type of the file should be set to 'MHUK'.  The creator should be 'MMIX'. Use the Set Project Type  item on the Project menu to define your project. (SEC reserves resource ID's 0-255 and plans to register names for your external functions. This will allow customers to build third-party external functions that will work together.)

• Add the Cext project to your project.

• Your project must have at least one other c file, which contains the entry routine named 'main.' Be sure to #include the header Extsynthesize.h or Extprocess.h in your main c module, and that your function agrees with the function prototype found in the header you included.

• The Extsynthesize.h and Extprocess.h headers contain #includes for three other header files that define utilities that you can call from your project:

soundfileio.h contains definitions of structures and functions which you will need to actually read and write Dyaxis sound files.

xfunction.h contains definitions of other functions which may be useful (e.g. progress indicator and watchcursor).

synthData.h or processData.h -- synthData.h contains the declaration for the data passed in the pointer to a synth function, and processData.h contains the declaration for the data structure passed to a process function.

• Your main function should return true if it is successful, false otherwise. If you return false and have supplied a non-null errorstring in the xstr argument, MacMix will display an error alert dialog with your message.

• You are responsible for any resource files your extension function may need.

• Note that if you are going to include any of your own projects, you must make sure that they are also defined as code resources before you add them to your extension project.

• Add your own MacTraps library to your project. Do not use any of the Quickdraw globals, a code resource will address them off of A4, while they are really indexed off of A5. To be absolutely safe, you can make a copy of MacTraps without these globals, see Chapter 7 of the ThinkC manual for details.

• Build a code resource from your project and place it in the same folder as MacMix.

The UserHooks disk contains the source code of a white noise synthesis function (Noise.prj) and a stereo to mono mix down processing function (StereoMono.prj). Studying and copying these is the easiest way to start.