Modification History:
=====================

Version 4: Feb 4, 1990

Added fix_snddriver_timeout patch to work around the timeout problems observed.

Simplified the API for the recorder object (in preparation for merging with a playback object).

Version 3: Dec 12, 1989

Added a Play button to play back the sound file just recorded.  It took about ten minutes to make all the changes.  What a nice machine...

Version 2: Dec 5, 1989

Changes within the Transport object:

The DSP code is now bundled in a MachO segment and loaded via a call to
newFromMachO.  This means that RecordApp no longer cares where it's launched
from.

Transport now uses a SavePanel to specify the output filename, and adds
new menu items, File->Open and File->Close to specify the filename.

Stereo input data can be saved as Stereo, Mono Mix, Mono Left, or Mono
Right.

44.1KHz input data can be saved as a 44.1KHz data, or sample-rate reduced
(by simple decimation) to 22.05KHz data.  Not recommended for critical
applications.

Observed problems:
	Call to await stream failed: unknown error(108)
	Cannot enqueue read request: timed out(-203)

About RecordApp:
================

RecordApp is a simple program that demonstrates how to record data
from the DSP chip on the NeXT computer.  It receives samples at
44.1Khz and writes them to disk.  

RecordApp is somewhat akin to the 'sndrecord' command-line program
that is distributed on every NeXT machine, with the following
differences:

* RecordApp only knows how to record from the DSP; it does not record
  from the CODEC microphone input.
* RecordApp is a true application and not just a command-line program.
* RecordApp is distributed in source form, and implements some AppKit
  objects that can be used in (and modified for) other applications.

The RecordApp example may be used, distributed, and modified freely.
However, NeXT cannot assume responsibility nor offer support for this
code.

The Big Picture:
================

The RecordApp program implements three AppKit objects.  They work as
follows:

The Recorder object handles basic stop/pause/record messages.  It
needs to be subclassed by some more specific recorder object such as a
DSP recorder object or a CODEC recorder object (the latter is not
implemented).  The Recorder object simply keeps track of the current
state of recording (stopped, paused, recording), and sends one or more
of the following messages to the subclass when various buttons are
pushed:

  recorderPrepare  (set up to record, state => paused)
  recorderPause	   (pause the recording, state => paused)
  recorderStop	   (stop the recording, state => stopped)
  recorderResume   (continue or start recording, state => recording)

The DSPRecorder object implements the above four methods.  It handles
the grubby task of grabbing the requisite system resources, setting up
the mach ports, downloading the DSP code.  Left to its own, the
DSPRecorder object doesn't do anything with the data it records; it
depends on a delegate to do something intelligent with the data.  The
delegate methods that the DSPRecorder will call are:

  willRecord :recorder;
  didRecord :recorder;
  recordData :recorder :(char *)data :(int)nbytes;

The DSP recorder calls willRecord at the onset of any recording.  The
didRecord method is called whenever recording stops.  While recording
is actually happening, the DSP recorder will call hasRecorded every
time it receives a packet of data from the DSP.

The Transport object is a "dime store" controller for the DSP recorder
object.  (For those not familiar with professional tape decks, the
"transport" is the mechanical part of the tape deck that moves the
tape as opposed to the "electronics".)  The Transport provides the
user with three buttons (start, pause, stop), and a filename to store
the sound into.  It also displays a running update of the state of the
recorder and how many bytes have been recorded.

The Transport object establishes itself as the DSPRecorder's delegate.
It uses the willRecord method to open a sound file, the hasRecorded
method to write data to the file, and the didRecord method to put a
header on the file and to close it.

Hardware and Software Requirements:
===================================

As written, here's what you need to run the RecorderApp:

* You must have a Digital Ears A/D converter from MetaResearch or
  functional equivalent.  Other input devices could be supported with
  appropriate changes to the dsp code (see Other Directions below).
* You must have a hard disk.  The optical disk has a three-pass write
  cycle (erase/write/verify), and can't sustain the 176.4 Kb/sec data
  rate coming out of the DSP.
* You must be running Release 1.0 of the operating system.

To create a fresh RecorderApp, start a shell buffer, connect to the
directory with these files in it, and type 'make'.  This will create
an executable RecorderApp that can be launched from the shell or from
the Workspace Manager.

Other Directions:
=================

The RecordApp was written as a programming example; is intentionally
simplistic.  There are many ways that an ambitious programmer might
want to modify or extend the program:

* Add VU Meters: You probably wouldn't want to update the VU meter at
  every call to hasRecorded; the postcript overhead could become
  excessive and cause the RecordApp to drop buffers.  However, there
  probably is enough time to run through the buffers of recorded data
  and compute the average and peak levels.  Then, once every second, you
  could update the VU meters.
* Implement Pause/Resume differently: Currently, pause and resume
  sends messages to the driver to stop and restart the data streams.  If
  you had VU meters on screen, you might want them to continue to update
  even when the recorder was "paused".  In this case, you should not
  actually pause the data streams.  Rather, you would simply stop
  writing the data to disk, but allow the VU meter calculations to
  continue.
* Write .asm code for other devices.  The .asm code provided with the
  RecordApp was written to work with the MetaResearch Digital Ears.
  Other external devices may require different logic for the serial IO
  ports.
* Implement a CODECRecorder object to record from the CODEC rather
  than from the DSP.

Above all, enjoy.

- R Dunbar Poor
  NeXT Technical Support
  September, 1989