Guido van Rossum | 5fdeeea | 1994-01-02 01:22:07 +0000 | [diff] [blame] | 1 | \section{Built-in module \sectcode{audioop}} |
| 2 | \bimodindex{audioop} |
| 3 | |
| 4 | The audioop module contains some useful operations on sound fragments. |
| 5 | It operates on sound fragments consisting of signed integer samples of |
| 6 | 8, 16 or 32 bits wide, stored in Python strings. This is the same |
| 7 | format as used by the \code{al} and \code{sunaudiodev} modules. All |
| 8 | scalar items are integers, unless specified otherwise. |
| 9 | |
| 10 | A few of the more complicated operations only take 16-bit samples, |
| 11 | otherwise the sample size (in bytes) is always a parameter of the operation. |
| 12 | |
| 13 | The module defines the following variables and functions: |
| 14 | |
| 15 | \renewcommand{\indexsubitem}{(in module audioop)} |
| 16 | \begin{excdesc}{error} |
| 17 | This exception is raised on all errors, such as unknown number of bytes |
| 18 | per sample, etc. |
| 19 | \end{excdesc} |
| 20 | |
| 21 | \begin{funcdesc}{add}{fragment1\, fragment2\, width} |
| 22 | This function returns a fragment that is the addition of the two samples |
| 23 | passed as parameters. \var{width} is the sample width in bytes, either |
| 24 | \code{1}, \code{2} or \code{4}. Both fragments should have the same length. |
| 25 | \end{funcdesc} |
| 26 | |
| 27 | \begin{funcdesc}{adpcm2lin}{adpcmfragment\, width\, state} |
| 28 | This routine decodes an Intel/DVI ADPCM coded fragment to a linear |
| 29 | fragment. See the description of \code{lin2adpcm} for details on ADPCM |
| 30 | coding. The routine returns a tuple |
| 31 | \code{(\var{sample}, \var{newstate})} |
| 32 | where the sample has the width specified in \var{width}. |
| 33 | \end{funcdesc} |
| 34 | |
| 35 | \begin{funcdesc}{adpcm32lin}{adpcmfragment\, width\, state} |
| 36 | This routine decodes an alternative 3-bit ADPCM code. See |
| 37 | \code{lin2adpcm3} for details. |
| 38 | \end{funcdesc} |
| 39 | |
| 40 | \begin{funcdesc}{avg}{fragment\, width} |
| 41 | This function returns the average over all samples in the fragment. |
| 42 | \end{funcdesc} |
| 43 | |
| 44 | \begin{funcdesc}{avgpp}{fragment\, width} |
| 45 | This function returns the average peak-peak value over all samples in |
Guido van Rossum | 16d6e71 | 1994-08-08 12:30:22 +0000 | [diff] [blame^] | 46 | the fragment. No filtering is done, so the usefulness of this routine |
Guido van Rossum | 5fdeeea | 1994-01-02 01:22:07 +0000 | [diff] [blame] | 47 | is questionable. |
| 48 | \end{funcdesc} |
| 49 | |
| 50 | \begin{funcdesc}{bias}{fragment\, width\, bias} |
| 51 | This function returns a fragment that is the original fragment with a |
| 52 | bias added to each sample. |
| 53 | \end{funcdesc} |
| 54 | |
| 55 | \begin{funcdesc}{cross}{fragment\, width} |
| 56 | This function returns the number of zero crossings in the fragment |
| 57 | passed as an argument. |
| 58 | \end{funcdesc} |
| 59 | |
| 60 | \begin{funcdesc}{findfactor}{fragment\, reference} |
| 61 | This routine (which only accepts 2-byte sample fragments) calculates a |
| 62 | factor \var{F} such that \code{rms(add(fragment, mul(reference, -F)))} |
| 63 | is minimal, i.e. it calculates the factor with which you should |
| 64 | multiply \var{reference} to make it match as good as possible to |
| 65 | \var{fragment}. The fragments should be the same size. |
| 66 | |
| 67 | The time taken by this routine is proportional to \code{len(fragment)}. |
| 68 | \end{funcdesc} |
| 69 | |
| 70 | \begin{funcdesc}{findfit}{fragment\, reference} |
| 71 | This routine (which only accepts 2-byte sample fragments) tries to |
| 72 | match \var{reference} as good as possible to a portion of |
| 73 | \var{fragment} (which should be the longer fragment). It |
| 74 | (conceptually) does this by taking slices out of \var{fragment}, using |
| 75 | \code{findfactor} to compute the best match, and minimizing the |
| 76 | result. |
Guido van Rossum | 16d6e71 | 1994-08-08 12:30:22 +0000 | [diff] [blame^] | 77 | It returns a tuple \code{(\var{offset}, \var{factor})} with \var{offset} the |
Guido van Rossum | 5fdeeea | 1994-01-02 01:22:07 +0000 | [diff] [blame] | 78 | (integer) offset into \var{fragment} where the optimal match started |
Guido van Rossum | 16d6e71 | 1994-08-08 12:30:22 +0000 | [diff] [blame^] | 79 | and \var{factor} the floating-point factor as per \code{findfactor}. |
Guido van Rossum | 5fdeeea | 1994-01-02 01:22:07 +0000 | [diff] [blame] | 80 | \end{funcdesc} |
| 81 | |
| 82 | \begin{funcdesc}{findmax}{fragment\, length} |
| 83 | This routine (which only accepts 2-byte sample fragments) searches |
| 84 | \var{fragment} for a slice of length \var{length} samples (not bytes!) |
| 85 | with maximum energy, i.e. it returns \var{i} for which |
| 86 | \code{rms(fragment[i*2:(i+length)*2])} is maximal. |
| 87 | |
| 88 | The routine takes time proportional to \code{len(fragment)}. |
| 89 | \end{funcdesc} |
| 90 | |
| 91 | \begin{funcdesc}{getsample}{fragment\, width\, index} |
| 92 | This function returns the value of sample \var{index} from the |
| 93 | fragment. |
| 94 | \end{funcdesc} |
| 95 | |
| 96 | \begin{funcdesc}{lin2lin}{fragment\, width\, newwidth} |
| 97 | This function converts samples between 1-, 2- and 4-byte formats. |
| 98 | \end{funcdesc} |
| 99 | |
| 100 | \begin{funcdesc}{lin2adpcm}{fragment\, width\, state} |
| 101 | This function converts samples to 4 bit Intel/DVI ADPCM encoding. |
| 102 | ADPCM coding is an adaptive coding scheme, whereby each 4 bit number |
| 103 | is the difference between one sample and the next, divided by a |
Guido van Rossum | 16d6e71 | 1994-08-08 12:30:22 +0000 | [diff] [blame^] | 104 | (varying) step. The Intel/DVI ADPCM algorithm has been selected for |
| 105 | use by the IMA, so it may well become a standard. |
Guido van Rossum | 5fdeeea | 1994-01-02 01:22:07 +0000 | [diff] [blame] | 106 | |
| 107 | \code{State} is a tuple containing the state of the coder. The coder |
| 108 | returns a tuple \code{(\var{adpcmfrag}, \var{newstate})}, and the |
| 109 | \var{newstate} should be passed to the next call of lin2adpcm. In the |
| 110 | initial call \code{None} can be passed as the state. \var{adpcmfrag} is |
| 111 | the ADPCM coded fragment packed 2 4-bit values per byte. |
| 112 | \end{funcdesc} |
| 113 | |
| 114 | \begin{funcdesc}{lin2adpcm3}{fragment\, width\, state} |
| 115 | This is an alternative ADPCM coder that uses only 3 bits per sample. |
| 116 | It is not compatible with the Intel/DVI ADPCM coder and its output is |
| 117 | not packed (due to laziness on the side of the author). Its use is |
| 118 | discouraged. |
| 119 | \end{funcdesc} |
| 120 | |
| 121 | \begin{funcdesc}{lin2ulaw}{fragment\, width} |
| 122 | This function converts samples in the audio fragment to U-LAW encoding |
Guido van Rossum | 16d6e71 | 1994-08-08 12:30:22 +0000 | [diff] [blame^] | 123 | and returns this as a Python string. U-LAW is an audio encoding format |
Guido van Rossum | 5fdeeea | 1994-01-02 01:22:07 +0000 | [diff] [blame] | 124 | whereby you get a dynamic range of about 14 bits using only 8 bit |
| 125 | samples. It is used by the Sun audio hardware, among others. |
| 126 | \end{funcdesc} |
| 127 | |
| 128 | \begin{funcdesc}{minmax}{fragment\, width} |
| 129 | This function returns a tuple consisting of the minimum and maximum |
| 130 | values of all samples in the sound fragment. |
| 131 | \end{funcdesc} |
| 132 | |
| 133 | \begin{funcdesc}{max}{fragment\, width} |
| 134 | This function returns the maximum of the {\em absolute value} of all |
| 135 | samples in a fragment. |
| 136 | \end{funcdesc} |
| 137 | |
| 138 | \begin{funcdesc}{maxpp}{fragment\, width} |
| 139 | This function returns the maximum peak-peak value in the sound fragment. |
| 140 | \end{funcdesc} |
| 141 | |
| 142 | \begin{funcdesc}{mul}{fragment\, width\, factor} |
| 143 | Mul returns a fragment that has all samples in the original framgent |
| 144 | multiplied by the floating-point value \var{factor}. Overflow is |
| 145 | silently ignored. |
| 146 | \end{funcdesc} |
| 147 | |
| 148 | \begin{funcdesc}{reverse}{fragment\, width} |
| 149 | This function reverses the samples in a fragment and returns the |
| 150 | modified fragment. |
| 151 | \end{funcdesc} |
| 152 | |
| 153 | \begin{funcdesc}{tomono}{fragment\, width\, lfactor\, rfactor} |
| 154 | This function converts a stereo fragment to a mono fragment. The left |
| 155 | channel is multiplied by \var{lfactor} and the right channel by |
| 156 | \var{rfactor} before adding the two channels to give a mono signal. |
| 157 | \end{funcdesc} |
| 158 | |
| 159 | \begin{funcdesc}{tostereo}{fragment\, width\, lfactor\, rfactor} |
| 160 | This function generates a stereo fragment from a mono fragment. Each |
| 161 | pair of samples in the stereo fragment are computed from the mono |
| 162 | sample, whereby left channel samples are multiplied by \var{lfactor} |
| 163 | and right channel samples by \var{rfactor}. |
| 164 | \end{funcdesc} |
| 165 | |
| 166 | \begin{funcdesc}{mul}{fragment\, width\, factor} |
| 167 | Mul returns a fragment that has all samples in the original framgent |
| 168 | multiplied by the floating-point value \var{factor}. Overflow is |
| 169 | silently ignored. |
| 170 | \end{funcdesc} |
| 171 | |
| 172 | \begin{funcdesc}{rms}{fragment\, width\, factor} |
| 173 | Returns the root-mean-square of the fragment, i.e. |
| 174 | \iftexi |
| 175 | the square root of the quotient of the sum of all squared sample value, |
| 176 | divided by the sumber of samples. |
| 177 | \else |
| 178 | % in eqn: sqrt { sum S sub i sup 2 over n } |
| 179 | \begin{displaymath} |
| 180 | \catcode`_=8 |
| 181 | \sqrt{\frac{\sum{{S_{i}}^{2}}}{n}} |
| 182 | \end{displaymath} |
| 183 | \fi |
| 184 | This is a measure of the power in an audio signal. |
| 185 | \end{funcdesc} |
| 186 | |
| 187 | \begin{funcdesc}{ulaw2lin}{fragment\, width} |
| 188 | This function converts sound fragments in ULAW encoding to linearly |
| 189 | encoded sound fragments. ULAW encoding always uses 8 bits samples, so |
| 190 | \var{width} refers only to the sample width of the output fragment here. |
| 191 | \end{funcdesc} |
| 192 | |
| 193 | Note that operations such as \code{mul} or \code{max} make no |
| 194 | distinction between mono and stereo fragments, i.e. all samples are |
| 195 | treated equal. If this is a problem the stereo fragment should be split |
| 196 | into two mono fragments first and recombined later. Here is an example |
| 197 | of how to do that: |
| 198 | \bcode\begin{verbatim} |
| 199 | def mul_stereo(sample, width, lfactor, rfactor): |
| 200 | lsample = audioop.tomono(sample, width, 1, 0) |
| 201 | rsample = audioop.tomono(sample, width, 0, 1) |
| 202 | lsample = audioop.mul(sample, width, lfactor) |
| 203 | rsample = audioop.mul(sample, width, rfactor) |
| 204 | lsample = audioop.tostereo(lsample, width, 1, 0) |
| 205 | rsample = audioop.tostereo(rsample, width, 0, 1) |
| 206 | return audioop.add(lsample, rsample, width) |
| 207 | \end{verbatim}\ecode |
| 208 | |
| 209 | If you use the ADPCM coder to build network packets and you want your |
| 210 | protocol to be stateless (i.e. to be able to tolerate packet loss) |
| 211 | you should not only transmit the data but also the state. Note that |
| 212 | you should send the \var{initial} state (the one you passed to |
| 213 | lin2adpcm) along to the decoder, not the final state (as returned by |
| 214 | the coder). If you want to use \code{struct} to store the state in |
| 215 | binary you can code the first element (the predicted value) in 16 bits |
| 216 | and the second (the delta index) in 8. |
| 217 | |
| 218 | The ADPCM coders have never been tried against other ADPCM coders, |
| 219 | only against themselves. It could well be that I misinterpreted the |
| 220 | standards in which case they will not be interoperable with the |
| 221 | respective standards. |
| 222 | |
| 223 | The \code{find...} routines might look a bit funny at first sight. |
| 224 | They are primarily meant for doing echo cancellation. A reasonably |
| 225 | fast way to do this is to pick the most energetic piece of the output |
| 226 | sample, locate that in the input sample and subtract the whole output |
| 227 | sample from the input sample: |
| 228 | \bcode\begin{verbatim} |
| 229 | def echocancel(outputdata, inputdata): |
| 230 | pos = audioop.findmax(outputdata, 800) # one tenth second |
| 231 | out_test = outputdata[pos*2:] |
| 232 | in_test = inputdata[pos*2:] |
| 233 | ipos, factor = audioop.findfit(in_test, out_test) |
| 234 | # Optional (for better cancellation): |
| 235 | # factor = audioop.findfactor(in_test[ipos*2:ipos*2+len(out_test)], |
| 236 | # out_test) |
| 237 | prefill = '\0'*(pos+ipos)*2 |
| 238 | postfill = '\0'*(len(inputdata)-len(prefill)-len(outputdata)) |
| 239 | outputdata = prefill + audioop.mul(outputdata,2,-factor) + postfill |
| 240 | return audioop.add(inputdata, outputdata, 2) |
| 241 | \end{verbatim}\ecode |