Written by J. Laroche at the Center for Music Experiment at UCSD, San Diego California. December 1990.

Introduction.

The NeXT machine includes several facilities for sound recording/playing and processing: built-in digital to analog converters, built-in digital signal processing chip, a DSP debugger, and several kits of C or objective C code to help you build your application. This document is an attempt to put together pieces of info related to the programing of sound/music software on the NeXT machine, both on the host and the DSP side. It is not intended to be a stand-alone document. Rather, it should be used as a guide to other documents, and as a useful source of additional advice to avoid the many pitfalls (!) you're likely to come across using the NeXT machine (and eventually to reduce the number of times you'll need to reboot your computer!)

The main scope of this document is the sound/DSP driver. It does not include the music kit, nor the sound kit. It deals mainly with the low-level sound/dsp driver functions that can be used to input, output, and process sounds, possibly in real time. You don't need to know anything about objective C to use these functions, although if you plan to use interface builder, you'll have to know at least a little bit about it.
Using these low-level functions instead of the music or the sound kit objects gives you more flexibility, more power, and a greater insight on how the NeXT machine works. It's the only way to take fully advantage of the hardware capabilities of the machine. If you just want to create and play music instruments on the NeXT machine, the music kit might be a good solution for you. If you want to perform real time sound processing, then you'll need the sound driver low-level function package and this document might be for you!!! 

(other) Useful documents you'll need.

· The NeXT documentation, although not as complete as we'd like it to be, is the main document for everything running on the host (i.e. on the NeXT machine's CPU, the Motorola 68000.) To avoid frantic search in the many chapters it's composed of, a great tool is the Librarian application: given a key word, it finds all the chapters containing info related to it. See the User's Reference manual for a guide to Librarian. 

· Motorola's DSP56000 User's manual will be of great help for everything concerning the DSP chip hardware and software. It's a bit dry, but it contains just about everything you need to know to run an application on the DSP chip. It will tell you about number representation inside the DSP, host/DSP communication, Synchronous Serial Port (for the digital ears for example) etc...

· Motorola's DSP development software is devoted to the DSP assembly language. It is also very useful and is on-line, somewhere in the NeXT developer documentation. You'll learn about assembly language, macros, software managment, etc...

· Ariel's BUG56000 debugger guide is also a good reference to help you debugg your DSP application using BUG56. 

What you should read before starting. 

· The complete works by Monty Pythons, as a way to keep your good humour in spite of everything (the hungry in the world, Margareth Thatcher etc...)

· NeXT documentation's chapters about sound, and Sound/DSP Driver functions.

· NeXT documentation's chapters about the MACH operating system (just to get an idea of what ports and messages are, since these notions are extensively used in the Sound/DSP driver.) 

Contents:

· 01_Intro
Documents, thing to know before getting started...

· 02_Cfunctions
Describes the classes of C functions relative to the sound and the DSP. You should know of these functions (and where to look for them) before writing anything, so that you don't write something that already exists.

· 03_Play_Dacs
Play_Dacs is a simple example of how to set-up a stream from the memory to the DACs, open a sound file, play it on the stream and control the play-back. It does not use the DSP. The example to start with.

· 04_Rec_Mike
Rec_Mike is an example showing the basic way recording can be done. This example records from the microphone, and therefore is not very useful. But the mechanism of recording remains the same whether you record from the microphone of from the DSP. It does not use the DSP.

· 05_Dig_Ears
Dig_Ears shows how to set-up a stream from the DSP to the DACs, and get samples from the SSI port. If you have MetaResearch's Digital Ears, you can plug them in the DSP port, and use this example to play a source in real time through the DSP to the DACs. It uses the DSP, shows how to set-up the streams and the DSP, and how to pass data to the DSP to control its action on the sound (e.g. the volume at which the sound is played back etc...), and how DMA functions. If you have nothing to plug in the DSP port (no Digital Ears etc...) you can make the DSP send a pure sine wave instead (see the C program.)

· 06_Play_Through_DSP
Play_Through_DSP is an example showing how to play a sound through the DSP to the DACs using non DMA transfer from the host to the DSP and DMA from the DSP to the host. It shows you how to pass data to the DSP in a non DMA way.

· 07_DMA_To_DSP
DMA_To_DSP shows you how to set-up a DMA stream from the host to the DSP then to the DACs, and play a sound on it. It involves DMA transfer in both directions. The faster rate of transmission of DMA makes it possible to reliably play sounds at 44100 stereo (provided the high water mark in the driver is high enough, see the C program.) It also illustrates a scheme for passing data to the DSP while it's playing back the sound.

· 08_PitFalls
This is a huge sack where all the hints about the driver and the DSP are grouped. This is the trouble shooting part of this tutorial. Always turn to it if you have a problem!

· 09_Future
Future investigations, things to check etc...