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