Doc/libal.tex

\section{Built-in Module \sectcode{al}}
\bimodindex{al}

This module provides access to the audio facilities of the Indigo and
4D/35 workstations, described in section 3A of the IRIX 4.0 man pages
(and also available as an option in IRIX 3.3).  You'll need to read
those man pages to understand what these functions do!
Some of the functions are not available in releases below 4.0.5.
Again, see the manual to check whether a specific function is
available on your platform.

Symbolic constants from the C header file \file{<audio.h>} are defined
in the standard module \code{AL}, see below.

\strong{Warning:} the current version of the audio library may dump core
when bad argument values are passed rather than returning an error
status.  Unfortunately, since the precise circumstances under which
this may happen are undocumented and hard to check, the Python
interface can provide no protection against this kind of problems.
(One example is specifying an excessive queue size --- there is no
documented upper limit.)

Module \code{al} defines the following functions:

\renewcommand{\indexsubitem}{(in module al)}
\begin{funcdesc}{openport}{name\, direction\, config}
Equivalent to the C function ALopenport().  The name and direction
arguments are strings.  The optional config argument is an opaque
configuration object as returned by \code{al.newconfig()}.  The return
value is an opaque port object; methods of port objects are described
below.
\end{funcdesc}

\begin{funcdesc}{newconfig}{}
Equivalent to the C function ALnewconfig().  The return value is a new
opaque configuration object; methods of configuration objects are
described below.
\end{funcdesc}

\begin{funcdesc}{queryparams}{device}
Equivalent to the C function ALqueryparams().  The device argument is
an integer.  The return value is a list of integers containing the
data returned by ALqueryparams().
\end{funcdesc}

\begin{funcdesc}{getparams}{device\, list}
Equivalent to the C function ALgetparams().  The device argument is an
integer.  The list argument is a list such as returned by
\code{queryparams}; it is modified in place (!).
\end{funcdesc}

\begin{funcdesc}{setparams}{device\, list}
Equivalent to the C function ALsetparams().  The device argument is an
integer.The list argument is a list such as returned by
\code{al.queryparams}.
\end{funcdesc}

Configuration objects (returned by \code{al.newconfig()} have the
following methods:

\renewcommand{\indexsubitem}{(audio configuration object method)}
\begin{funcdesc}{getqueuesize}{}
Return the queue size; equivalent to the C function ALgetqueuesize().
\end{funcdesc}

\begin{funcdesc}{setqueuesize}{size}
Set the queue size; equivalent to the C function ALsetqueuesize().
\end{funcdesc}

\begin{funcdesc}{getwidth}{}
Get the sample width; equivalent to the C function ALgetwidth().
\end{funcdesc}

\begin{funcdesc}{getwidth}{width}
Set the sample width; equivalent to the C function ALsetwidth().
\end{funcdesc}

\begin{funcdesc}{getchannels}{}
Get the channel count; equivalent to the C function ALgetchannels().
\end{funcdesc}

\begin{funcdesc}{setchannels}{nchannels}
Set the channel count; equivalent to the C function ALsetchannels().
\end{funcdesc}

\begin{funcdesc}{getsampfmt}{}
Get the sample format; equivalent to the C function ALgetsampfmt().
\end{funcdesc}

\begin{funcdesc}{setsampfmt}{sampfmt}
Set the sample format; equivalent to the C function ALsetsampfmt().
\end{funcdesc}

\begin{funcdesc}{getfloatmax}{}
Get the maximum value for floating sample formats;
equivalent to the C function ALgetfloatmax().
\end{funcdesc}

\begin{funcdesc}{setfloatmax}{floatmax}
Set the maximum value for floating sample formats;
equivalent to the C function ALsetfloatmax().
\end{funcdesc}

Port objects (returned by \code{al.openport()} have the following
methods:

\renewcommand{\indexsubitem}{(audio port object method)}
\begin{funcdesc}{closeport}{}
Close the port; equivalent to the C function ALcloseport().
\end{funcdesc}

\begin{funcdesc}{getfd}{}
Return the file descriptor as an int; equivalent to the C function
ALgetfd().
\end{funcdesc}

\begin{funcdesc}{getfilled}{}
Return the number of filled samples; equivalent to the C function
ALgetfilled().
\end{funcdesc}

\begin{funcdesc}{getfillable}{}
Return the number of fillable samples; equivalent to the C function
ALgetfillable().
\end{funcdesc}

\begin{funcdesc}{readsamps}{nsamples}
Read a number of samples from the queue, blocking if necessary;
equivalent to the C function ALreadsamples.  The data is returned as a
string containing the raw data (e.g. 2 bytes per sample in big-endian
byte order (high byte, low byte) if you have set the sample width to 2
bytes.
\end{funcdesc}

\begin{funcdesc}{writesamps}{samples}
Write samples into the queue, blocking if necessary; equivalent to the
C function ALwritesamples.  The samples are encoded as described for
the \code{readsamps} return value.
\end{funcdesc}

\begin{funcdesc}{getfillpoint}{}
Return the `fill point'; equivalent to the C function ALgetfillpoint().
\end{funcdesc}

\begin{funcdesc}{setfillpoint}{fillpoint}
Set the `fill point'; equivalent to the C function ALsetfillpoint().
\end{funcdesc}

\begin{funcdesc}{getconfig}{}
Return a configuration object containing the current configuration of
the port; equivalent to the C function ALgetconfig().
\end{funcdesc}

\begin{funcdesc}{setconfig}{config}
Set the configuration from the argument, a configuration object;
equivalent to the C function ALsetconfig().
\end{funcdesc}

\begin{funcdesc}{getstatus}{list}
Get status information on last error
equivalent to C function ALgetstatus().
\end{funcdesc}

\section{Standard Module \sectcode{AL}}
\nodename{AL (uppercase)}
\stmodindex{AL}

This module defines symbolic constants needed to use the built-in
module \code{al} (see above); they are equivalent to those defined in
the C header file \file{<audio.h>} except that the name prefix
\samp{AL_} is omitted.  Read the module source for a complete list of
the defined names.  Suggested use:

\bcode\begin{verbatim}
import al
from AL import *
\end{verbatim}\ecode