Doc/libaudio.tex

   1 \section{Built-in Module \sectcode{audio}}
   2 \bimodindex{audio}
   3
   4 \strong{Note:} This module is obsolete, since the hardware to which it
   5 interfaces is obsolete.  For audio on the Indigo or 4D/35, see
   6 built-in module \code{al} above.
   7
   8 This module provides rudimentary access to the audio I/O device
   9 \file{/dev/audio} on the Silicon Graphics Personal IRIS 4D/25;
  10 see {\it audio}(7). It supports the following operations:
  11
  12 \renewcommand{\indexsubitem}{(in module audio)}
  13 \begin{funcdesc}{setoutgain}{n}
  14 Sets the output gain.
  15 \iftexi
  16 \code{0 <= \var{n} < 256}.
  17 \else
  18 $0 \leq \var{n} < 256$.
  19 %%JHXXX Sets the output gain (0-255).
  20 \fi
  21 \end{funcdesc}
  22
  23 \begin{funcdesc}{getoutgain}{}
  24 Returns the output gain.
  25 \end{funcdesc}
  26
  27 \begin{funcdesc}{setrate}{n}
  28 Sets the sampling rate: \code{1} = 32K/sec, \code{2} = 16K/sec,
  29 \code{3} = 8K/sec.
  30 \end{funcdesc}
  31
  32 \begin{funcdesc}{setduration}{n}
  33 Sets the `sound duration' in units of 1/100 seconds.
  34 \end{funcdesc}
  35
  36 \begin{funcdesc}{read}{n}
  37 Reads a chunk of
  38 \var{n}
  39 sampled bytes from the audio input (line in or microphone).
  40 The chunk is returned as a string of length n.
  41 Each byte encodes one sample as a signed 8-bit quantity using linear
  42 encoding.
  43 This string can be converted to numbers using \code{chr2num()} described
  44 below.
  45 \end{funcdesc}
  46
  47 \begin{funcdesc}{write}{buf}
  48 Writes a chunk of samples to the audio output (speaker).
  49 \end{funcdesc}
  50
  51 These operations support asynchronous audio I/O:
  52
  53 \renewcommand{\indexsubitem}{(in module audio)}
  54 \begin{funcdesc}{start_recording}{n}
  55 Starts a second thread (a process with shared memory) that begins reading
  56 \var{n}
  57 bytes from the audio device.
  58 The main thread immediately continues.
  59 \end{funcdesc}
  60
  61 \begin{funcdesc}{wait_recording}{}
  62 Waits for the second thread to finish and returns the data read.
  63 \end{funcdesc}
  64
  65 \begin{funcdesc}{stop_recording}{}
  66 Makes the second thread stop reading as soon as possible.
  67 Returns the data read so far.
  68 \end{funcdesc}
  69
  70 \begin{funcdesc}{poll_recording}{}
  71 Returns true if the second thread has finished reading (so
  72 \code{wait_recording()} would return the data without delay).
  73 \end{funcdesc}
  74
  75 \begin{funcdesc}{start_playing}{}
  76 \funcline{wait_playing}{}
  77 \funcline{stop_playing}{}
  78 \funcline{poll_playing}{}
  79 \begin{sloppypar}
  80 Similar but for output.
  81 \code{stop_playing()}
  82 returns a lower bound for the number of bytes actually played (not very
  83 accurate).
  84 \end{sloppypar}
  85 \end{funcdesc}
  86
  87 The following operations do not affect the audio device but are
  88 implemented in C for efficiency:
  89
  90 \renewcommand{\indexsubitem}{(in module audio)}
  91 \begin{funcdesc}{amplify}{buf\, f1\, f2}
  92 Amplifies a chunk of samples by a variable factor changing from
  93 \code{\var{f1}/256} to \code{\var{f2}/256.}
  94 Negative factors are allowed.
  95 Resulting values that are to large to fit in a byte are clipped.
  96 \end{funcdesc}
  97
  98 \begin{funcdesc}{reverse}{buf}
  99 Returns a chunk of samples backwards.
 100 \end{funcdesc}
 101
 102 \begin{funcdesc}{add}{buf1\, buf2}
 103 Bytewise adds two chunks of samples.
 104 Bytes that exceed the range are clipped.
 105 If one buffer is shorter, it is assumed to be padded with zeros.
 106 \end{funcdesc}
 107
 108 \begin{funcdesc}{chr2num}{buf}
 109 Converts a string of sampled bytes as returned by \code{read()} into
 110 a list containing the numeric values of the samples.
 111 \end{funcdesc}
 112
 113 \begin{funcdesc}{num2chr}{list}
 114 \begin{sloppypar}
 115 Converts a list as returned by
 116 \code{chr2num()}
 117 back to a buffer acceptable by
 118 \code{write()}.
 119 \end{sloppypar}
 120 \end{funcdesc}