Doc/libaudio.tex

\section{Built-in Module \sectcode{audio}}
\label{module-audio}
\bimodindex{audio}

\strong{Note:} This module is obsolete, since the hardware to which it
interfaces is obsolete.  For audio on the Indigo or 4D/35, see
built-in module \code{al} above.

This module provides rudimentary access to the audio I/O device
\file{/dev/audio} on the Silicon Graphics Personal IRIS 4D/25;
see {\it audio}(7). It supports the following operations:

\renewcommand{\indexsubitem}{(in module audio)}
\begin{funcdesc}{setoutgain}{n}
Sets the output gain.
\iftexi
\code{0 <= \var{n} < 256}.
\else
$0 \leq \var{n} < 256$.
%%JHXXX Sets the output gain (0-255).
\fi
\end{funcdesc}

\begin{funcdesc}{getoutgain}{}
Returns the output gain.
\end{funcdesc}

\begin{funcdesc}{setrate}{n}
Sets the sampling rate: \code{1} = 32K/sec, \code{2} = 16K/sec,
\code{3} = 8K/sec.
\end{funcdesc}

\begin{funcdesc}{setduration}{n}
Sets the `sound duration' in units of 1/100 seconds.
\end{funcdesc}

\begin{funcdesc}{read}{n}
Reads a chunk of
\var{n}
sampled bytes from the audio input (line in or microphone).
The chunk is returned as a string of length n.
Each byte encodes one sample as a signed 8-bit quantity using linear
encoding.
This string can be converted to numbers using \code{chr2num()} described
below.
\end{funcdesc}

\begin{funcdesc}{write}{buf}
Writes a chunk of samples to the audio output (speaker).
\end{funcdesc}

These operations support asynchronous audio I/O:

\renewcommand{\indexsubitem}{(in module audio)}
\begin{funcdesc}{start_recording}{n}
Starts a second thread (a process with shared memory) that begins reading
\var{n}
bytes from the audio device.
The main thread immediately continues.
\end{funcdesc}

\begin{funcdesc}{wait_recording}{}
Waits for the second thread to finish and returns the data read.
\end{funcdesc}

\begin{funcdesc}{stop_recording}{}
Makes the second thread stop reading as soon as possible.
Returns the data read so far.
\end{funcdesc}

\begin{funcdesc}{poll_recording}{}
Returns true if the second thread has finished reading (so
\code{wait_recording()} would return the data without delay).
\end{funcdesc}

\begin{funcdesc}{start_playing}{}
\funcline{wait_playing}{}
\funcline{stop_playing}{}
\funcline{poll_playing}{}
\begin{sloppypar}
Similar but for output.
\code{stop_playing()}
returns a lower bound for the number of bytes actually played (not very
accurate).
\end{sloppypar}
\end{funcdesc}

The following operations do not affect the audio device but are
implemented in C for efficiency:

\renewcommand{\indexsubitem}{(in module audio)}
\begin{funcdesc}{amplify}{buf\, f1\, f2}
Amplifies a chunk of samples by a variable factor changing from
\code{\var{f1}/256} to \code{\var{f2}/256.}
Negative factors are allowed.
Resulting values that are to large to fit in a byte are clipped.         
\end{funcdesc}

\begin{funcdesc}{reverse}{buf}
Returns a chunk of samples backwards.
\end{funcdesc}

\begin{funcdesc}{add}{buf1\, buf2}
Bytewise adds two chunks of samples.
Bytes that exceed the range are clipped.
If one buffer is shorter, it is assumed to be padded with zeros.
\end{funcdesc}

\begin{funcdesc}{chr2num}{buf}
Converts a string of sampled bytes as returned by \code{read()} into
a list containing the numeric values of the samples.
\end{funcdesc}

\begin{funcdesc}{num2chr}{list}
\begin{sloppypar}
Converts a list as returned by
\code{chr2num()}
back to a buffer acceptable by
\code{write()}.
\end{sloppypar}
\end{funcdesc}