mirror of https://github.com/python/cpython
122 lines
3.4 KiB
TeX
122 lines
3.4 KiB
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}
|