Audio Processing
****************

Octave provides a few functions for dealing with audio data.  An audio `sample' is a single output value from an A/D converter, i.e., a small integer number (usually 8 or 16 bits), and audio data is just a series of such samples.  It can be characterized by three parameters: the sampling rate (measured in samples per second or Hz, e.g., 8000 or 44100), the number of bits per sample (e.g., 8 or 16), and the number of channels (1 for mono, 2 for stereo, etc.).

There are many different formats for representing such data.  Currently, only the two most popular, linear encoding and mu-law encoding, are supported by Octave.  There is an excellent FAQ on audio formats by Guido van Rossum guido@cwi.nl which can be found at any FAQ ftp site, in particular in the directory /pub/usenet/news.answers/audio-fmts of the archive site rtfm.mit.edu.

Octave simply treats audio data as vectors of samples (non-mono data are not supported yet).  It is assumed that audio files using linear encoding have one of the extensions lin or raw, and that files holding data in mu-law encoding end in au, mu, or snd.

 -- Function File: lin2mu (X, N)
     Convert audio data from linear to mu-law.  Mu-law values use 8-bit unsigned integers.  Linear values use N-bit signed integers or floating point values in the range -1 ≤ X ≤ 1 if N is 0.

     If N is not specified it defaults to 0, 8, or 16 depending on the range of values in X. mu2lin, loadaudio, saveaudio

 -- Function File: mu2lin (X, N)
     Convert audio data from mu-law to linear.  Mu-law values are 8-bit unsigned integers.  Linear values use N-bit signed integers or floating point values in the range -1≤y≤1 if N is 0.

     If N is not specified it defaults to 0. lin2mu, loadaudio, saveaudio

 -- Function File: loadaudio (NAME, EXT, BPS)
     Load audio data from the file NAME.EXT into the vector X.

     The extension EXT determines how the data in the audio file is interpreted; the extensions lin (default) and raw correspond to linear, the extensions au, mu, or snd to mu-law encoding.

     The argument BPS can be either 8 (default) or 16, and specifies the number of bits per sample used in the audio file. lin2mu, mu2lin, saveaudio, playaudio, setaudio, record

 -- Function File: saveaudio (NAME, X, EXT, BPS)
     Save a vector X of audio data to the file NAME.EXT.  The optional parameters EXT and BPS determine the encoding and the number of bits per sample used in the audio file (see loadaudio); defaults are lin and 8, respectively. lin2mu, mu2lin, loadaudio, playaudio, setaudio, record

The following functions for audio I/O require special A/D hardware and operating system support.  It is assumed that audio data in linear encoding can be played and recorded by reading from and writing to /dev/dsp, and that similarly /dev/audio is used for mu-law encoding.  These file names are system-dependent.  Improvements so that these functions will work without modification on a wide variety of hardware are welcome.

 -- Function File: playaudio (NAME, EXT)
 -- Function File: playaudio (X)
     Play the audio file NAME.EXT or the audio data stored in the vector X. lin2mu, mu2lin, loadaudio, saveaudio, setaudio, record

 -- Function File: record (SEC, SAMPLING_RATE)
     Record SEC seconds of audio input into the vector X.  The default value for SAMPLING_RATE is 8000 samples per second, or 8kHz.  The program waits until the user types RET and then immediately starts to record. lin2mu, mu2lin, loadaudio, saveaudio, playaudio, setaudio

 -- Function File: setaudio ()
 -- Function File: setaudio (W_TYPE)
 -- Function File: setaudio (W_TYPE, VALUE)
     Execute the shell command mixer, possibly with optional arguments W_TYPE and VALUE.

 -- Function File: Y = wavread (FILENAME)
     Load the RIFF/WAVE sound file FILENAME, and return the samples in vector Y.  If the file contains multichannel data, then Y is a matrix with the channels represented as columns.

 -- Function File: [Y, FS, BPS] = wavread (FILENAME)
     Additionally return the sample rate (FS) in Hz and the number of bits per sample (BPS).

 -- Function File: [...] = wavread (FILENAME, N)
     Read only the first N samples from each channel.

 -- Function File: [...] = wavread (FILENAME, N1 N2)
     Read only samples N1 through N2 from each channel.

 -- Function File: [SAMPLES, CHANNELS] = wavread (FILENAME, "size")
     Return the number of samples (N) and channels (CH) instead of the audio data. wavwrite

 -- Function File: wavwrite (Y, FILENAME)
 -- Function File: wavwrite (Y, FS, FILENAME)
 -- Function File: wavwrite (Y, FS, BPS, FILENAME)
     Write Y to the canonical RIFF/WAVE sound file FILENAME with sample rate FS and bits per sample BPS.  The default sample rate is 8000 Hz with 16-bits per sample.  Each column of the data represents a separate channel. wavread