Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 1 | :mod:`audioop` --- Manipulate raw audio data |
| 2 | ============================================ |
| 3 | |
| 4 | .. module:: audioop |
| 5 | :synopsis: Manipulate raw audio data. |
| 6 | |
Terry Jan Reedy | fa089b9 | 2016-06-11 15:02:54 -0400 | [diff] [blame] | 7 | -------------- |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 8 | |
| 9 | The :mod:`audioop` module contains some useful operations on sound fragments. |
Serhiy Storchaka | eaea5e9 | 2013-10-19 21:10:46 +0300 | [diff] [blame] | 10 | It operates on sound fragments consisting of signed integer samples 8, 16, 24 |
Serhiy Storchaka | e5ea1ab | 2016-05-18 13:54:54 +0300 | [diff] [blame] | 11 | or 32 bits wide, stored in :term:`bytes-like objects <bytes-like object>`. All scalar items are |
Serhiy Storchaka | 711e91b | 2013-11-10 21:44:36 +0200 | [diff] [blame] | 12 | integers, unless specified otherwise. |
Serhiy Storchaka | eaea5e9 | 2013-10-19 21:10:46 +0300 | [diff] [blame] | 13 | |
| 14 | .. versionchanged:: 3.4 |
| 15 | Support for 24-bit samples was added. |
R David Murray | 8591563 | 2014-03-07 21:35:31 -0500 | [diff] [blame] | 16 | All functions now accept any :term:`bytes-like object`. |
| 17 | String input now results in an immediate error. |
Serhiy Storchaka | 711e91b | 2013-11-10 21:44:36 +0200 | [diff] [blame] | 18 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 19 | .. index:: |
| 20 | single: Intel/DVI ADPCM |
| 21 | single: ADPCM, Intel/DVI |
| 22 | single: a-LAW |
| 23 | single: u-LAW |
| 24 | |
| 25 | This module provides support for a-LAW, u-LAW and Intel/DVI ADPCM encodings. |
| 26 | |
Christian Heimes | 5b5e81c | 2007-12-31 16:14:33 +0000 | [diff] [blame] | 27 | .. This para is mostly here to provide an excuse for the index entries... |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 28 | |
| 29 | A few of the more complicated operations only take 16-bit samples, otherwise the |
| 30 | sample size (in bytes) is always a parameter of the operation. |
| 31 | |
| 32 | The module defines the following variables and functions: |
| 33 | |
| 34 | |
| 35 | .. exception:: error |
| 36 | |
| 37 | This exception is raised on all errors, such as unknown number of bytes per |
| 38 | sample, etc. |
| 39 | |
| 40 | |
| 41 | .. function:: add(fragment1, fragment2, width) |
| 42 | |
| 43 | Return a fragment which is the addition of the two samples passed as parameters. |
Serhiy Storchaka | eaea5e9 | 2013-10-19 21:10:46 +0300 | [diff] [blame] | 44 | *width* is the sample width in bytes, either ``1``, ``2``, ``3`` or ``4``. Both |
Serhiy Storchaka | 01ad622 | 2013-02-09 11:10:53 +0200 | [diff] [blame] | 45 | fragments should have the same length. Samples are truncated in case of overflow. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 46 | |
| 47 | |
| 48 | .. function:: adpcm2lin(adpcmfragment, width, state) |
| 49 | |
| 50 | Decode an Intel/DVI ADPCM coded fragment to a linear fragment. See the |
| 51 | description of :func:`lin2adpcm` for details on ADPCM coding. Return a tuple |
| 52 | ``(sample, newstate)`` where the sample has the width specified in *width*. |
| 53 | |
| 54 | |
| 55 | .. function:: alaw2lin(fragment, width) |
| 56 | |
| 57 | Convert sound fragments in a-LAW encoding to linearly encoded sound fragments. |
| 58 | a-LAW encoding always uses 8 bits samples, so *width* refers only to the sample |
| 59 | width of the output fragment here. |
| 60 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 61 | |
| 62 | .. function:: avg(fragment, width) |
| 63 | |
| 64 | Return the average over all samples in the fragment. |
| 65 | |
| 66 | |
| 67 | .. function:: avgpp(fragment, width) |
| 68 | |
| 69 | Return the average peak-peak value over all samples in the fragment. No |
| 70 | filtering is done, so the usefulness of this routine is questionable. |
| 71 | |
| 72 | |
| 73 | .. function:: bias(fragment, width, bias) |
| 74 | |
| 75 | Return a fragment that is the original fragment with a bias added to each |
Serhiy Storchaka | 01ad622 | 2013-02-09 11:10:53 +0200 | [diff] [blame] | 76 | sample. Samples wrap around in case of overflow. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 77 | |
| 78 | |
Serhiy Storchaka | 3062c9a | 2013-11-23 22:26:01 +0200 | [diff] [blame] | 79 | .. function:: byteswap(fragment, width) |
| 80 | |
| 81 | "Byteswap" all samples in a fragment and returns the modified fragment. |
| 82 | Converts big-endian samples to little-endian and vice versa. |
| 83 | |
R David Murray | 2177be2 | 2014-03-09 20:42:49 -0400 | [diff] [blame] | 84 | .. versionadded:: 3.4 |
Serhiy Storchaka | 3062c9a | 2013-11-23 22:26:01 +0200 | [diff] [blame] | 85 | |
| 86 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 87 | .. function:: cross(fragment, width) |
| 88 | |
| 89 | Return the number of zero crossings in the fragment passed as an argument. |
| 90 | |
| 91 | |
| 92 | .. function:: findfactor(fragment, reference) |
| 93 | |
| 94 | Return a factor *F* such that ``rms(add(fragment, mul(reference, -F)))`` is |
| 95 | minimal, i.e., return the factor with which you should multiply *reference* to |
| 96 | make it match as well as possible to *fragment*. The fragments should both |
| 97 | contain 2-byte samples. |
| 98 | |
| 99 | The time taken by this routine is proportional to ``len(fragment)``. |
| 100 | |
| 101 | |
| 102 | .. function:: findfit(fragment, reference) |
| 103 | |
| 104 | Try to match *reference* as well as possible to a portion of *fragment* (which |
| 105 | should be the longer fragment). This is (conceptually) done by taking slices |
| 106 | out of *fragment*, using :func:`findfactor` to compute the best match, and |
| 107 | minimizing the result. The fragments should both contain 2-byte samples. |
| 108 | Return a tuple ``(offset, factor)`` where *offset* is the (integer) offset into |
| 109 | *fragment* where the optimal match started and *factor* is the (floating-point) |
| 110 | factor as per :func:`findfactor`. |
| 111 | |
| 112 | |
| 113 | .. function:: findmax(fragment, length) |
| 114 | |
| 115 | Search *fragment* for a slice of length *length* samples (not bytes!) with |
| 116 | maximum energy, i.e., return *i* for which ``rms(fragment[i*2:(i+length)*2])`` |
| 117 | is maximal. The fragments should both contain 2-byte samples. |
| 118 | |
| 119 | The routine takes time proportional to ``len(fragment)``. |
| 120 | |
| 121 | |
| 122 | .. function:: getsample(fragment, width, index) |
| 123 | |
| 124 | Return the value of sample *index* from the fragment. |
| 125 | |
| 126 | |
| 127 | .. function:: lin2adpcm(fragment, width, state) |
| 128 | |
| 129 | Convert samples to 4 bit Intel/DVI ADPCM encoding. ADPCM coding is an adaptive |
| 130 | coding scheme, whereby each 4 bit number is the difference between one sample |
| 131 | and the next, divided by a (varying) step. The Intel/DVI ADPCM algorithm has |
| 132 | been selected for use by the IMA, so it may well become a standard. |
| 133 | |
| 134 | *state* is a tuple containing the state of the coder. The coder returns a tuple |
| 135 | ``(adpcmfrag, newstate)``, and the *newstate* should be passed to the next call |
| 136 | of :func:`lin2adpcm`. In the initial call, ``None`` can be passed as the state. |
| 137 | *adpcmfrag* is the ADPCM coded fragment packed 2 4-bit values per byte. |
| 138 | |
| 139 | |
| 140 | .. function:: lin2alaw(fragment, width) |
| 141 | |
| 142 | Convert samples in the audio fragment to a-LAW encoding and return this as a |
Serhiy Storchaka | c8bd74d | 2012-12-27 20:43:36 +0200 | [diff] [blame] | 143 | bytes object. a-LAW is an audio encoding format whereby you get a dynamic |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 144 | range of about 13 bits using only 8 bit samples. It is used by the Sun audio |
| 145 | hardware, among others. |
| 146 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 147 | |
| 148 | .. function:: lin2lin(fragment, width, newwidth) |
| 149 | |
Serhiy Storchaka | eaea5e9 | 2013-10-19 21:10:46 +0300 | [diff] [blame] | 150 | Convert samples between 1-, 2-, 3- and 4-byte formats. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 151 | |
Christian Heimes | cc47b05 | 2008-03-25 14:56:36 +0000 | [diff] [blame] | 152 | .. note:: |
| 153 | |
Serhiy Storchaka | eaea5e9 | 2013-10-19 21:10:46 +0300 | [diff] [blame] | 154 | In some audio formats, such as .WAV files, 16, 24 and 32 bit samples are |
Christian Heimes | cc47b05 | 2008-03-25 14:56:36 +0000 | [diff] [blame] | 155 | signed, but 8 bit samples are unsigned. So when converting to 8 bit wide |
| 156 | samples for these formats, you need to also add 128 to the result:: |
| 157 | |
| 158 | new_frames = audioop.lin2lin(frames, old_width, 1) |
| 159 | new_frames = audioop.bias(new_frames, 1, 128) |
| 160 | |
Serhiy Storchaka | eaea5e9 | 2013-10-19 21:10:46 +0300 | [diff] [blame] | 161 | The same, in reverse, has to be applied when converting from 8 to 16, 24 |
| 162 | or 32 bit width samples. |
Christian Heimes | cc47b05 | 2008-03-25 14:56:36 +0000 | [diff] [blame] | 163 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 164 | |
| 165 | .. function:: lin2ulaw(fragment, width) |
| 166 | |
| 167 | Convert samples in the audio fragment to u-LAW encoding and return this as a |
Serhiy Storchaka | c8bd74d | 2012-12-27 20:43:36 +0200 | [diff] [blame] | 168 | bytes object. u-LAW is an audio encoding format whereby you get a dynamic |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 169 | range of about 14 bits using only 8 bit samples. It is used by the Sun audio |
| 170 | hardware, among others. |
| 171 | |
| 172 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 173 | .. function:: max(fragment, width) |
| 174 | |
| 175 | Return the maximum of the *absolute value* of all samples in a fragment. |
| 176 | |
| 177 | |
| 178 | .. function:: maxpp(fragment, width) |
| 179 | |
| 180 | Return the maximum peak-peak value in the sound fragment. |
| 181 | |
| 182 | |
Ezio Melotti | e0035a2 | 2012-12-14 20:18:46 +0200 | [diff] [blame] | 183 | .. function:: minmax(fragment, width) |
| 184 | |
| 185 | Return a tuple consisting of the minimum and maximum values of all samples in |
| 186 | the sound fragment. |
| 187 | |
| 188 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 189 | .. function:: mul(fragment, width, factor) |
| 190 | |
| 191 | Return a fragment that has all samples in the original fragment multiplied by |
Serhiy Storchaka | 01ad622 | 2013-02-09 11:10:53 +0200 | [diff] [blame] | 192 | the floating-point value *factor*. Samples are truncated in case of overflow. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 193 | |
| 194 | |
| 195 | .. function:: ratecv(fragment, width, nchannels, inrate, outrate, state[, weightA[, weightB]]) |
| 196 | |
| 197 | Convert the frame rate of the input fragment. |
| 198 | |
| 199 | *state* is a tuple containing the state of the converter. The converter returns |
| 200 | a tuple ``(newfragment, newstate)``, and *newstate* should be passed to the next |
| 201 | call of :func:`ratecv`. The initial call should pass ``None`` as the state. |
| 202 | |
| 203 | The *weightA* and *weightB* arguments are parameters for a simple digital filter |
| 204 | and default to ``1`` and ``0`` respectively. |
| 205 | |
| 206 | |
| 207 | .. function:: reverse(fragment, width) |
| 208 | |
| 209 | Reverse the samples in a fragment and returns the modified fragment. |
| 210 | |
| 211 | |
| 212 | .. function:: rms(fragment, width) |
| 213 | |
| 214 | Return the root-mean-square of the fragment, i.e. ``sqrt(sum(S_i^2)/n)``. |
| 215 | |
| 216 | This is a measure of the power in an audio signal. |
| 217 | |
| 218 | |
| 219 | .. function:: tomono(fragment, width, lfactor, rfactor) |
| 220 | |
| 221 | Convert a stereo fragment to a mono fragment. The left channel is multiplied by |
| 222 | *lfactor* and the right channel by *rfactor* before adding the two channels to |
| 223 | give a mono signal. |
| 224 | |
| 225 | |
| 226 | .. function:: tostereo(fragment, width, lfactor, rfactor) |
| 227 | |
| 228 | Generate a stereo fragment from a mono fragment. Each pair of samples in the |
| 229 | stereo fragment are computed from the mono sample, whereby left channel samples |
| 230 | are multiplied by *lfactor* and right channel samples by *rfactor*. |
| 231 | |
| 232 | |
| 233 | .. function:: ulaw2lin(fragment, width) |
| 234 | |
| 235 | Convert sound fragments in u-LAW encoding to linearly encoded sound fragments. |
| 236 | u-LAW encoding always uses 8 bits samples, so *width* refers only to the sample |
| 237 | width of the output fragment here. |
| 238 | |
Georg Brandl | 502d9a5 | 2009-07-26 15:02:41 +0000 | [diff] [blame] | 239 | Note that operations such as :func:`.mul` or :func:`.max` make no distinction |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 240 | between mono and stereo fragments, i.e. all samples are treated equal. If this |
| 241 | is a problem the stereo fragment should be split into two mono fragments first |
| 242 | and recombined later. Here is an example of how to do that:: |
| 243 | |
| 244 | def mul_stereo(sample, width, lfactor, rfactor): |
| 245 | lsample = audioop.tomono(sample, width, 1, 0) |
| 246 | rsample = audioop.tomono(sample, width, 0, 1) |
Georg Brandl | f3d0087 | 2010-10-17 10:07:29 +0000 | [diff] [blame] | 247 | lsample = audioop.mul(lsample, width, lfactor) |
| 248 | rsample = audioop.mul(rsample, width, rfactor) |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 249 | lsample = audioop.tostereo(lsample, width, 1, 0) |
| 250 | rsample = audioop.tostereo(rsample, width, 0, 1) |
| 251 | return audioop.add(lsample, rsample, width) |
| 252 | |
| 253 | If you use the ADPCM coder to build network packets and you want your protocol |
| 254 | to be stateless (i.e. to be able to tolerate packet loss) you should not only |
| 255 | transmit the data but also the state. Note that you should send the *initial* |
| 256 | state (the one you passed to :func:`lin2adpcm`) along to the decoder, not the |
| 257 | final state (as returned by the coder). If you want to use |
Serhiy Storchaka | bfdcd43 | 2013-10-13 23:09:14 +0300 | [diff] [blame] | 258 | :class:`struct.Struct` to store the state in binary you can code the first |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 259 | element (the predicted value) in 16 bits and the second (the delta index) in 8. |
| 260 | |
| 261 | The ADPCM coders have never been tried against other ADPCM coders, only against |
| 262 | themselves. It could well be that I misinterpreted the standards in which case |
| 263 | they will not be interoperable with the respective standards. |
| 264 | |
| 265 | The :func:`find\*` routines might look a bit funny at first sight. They are |
| 266 | primarily meant to do echo cancellation. A reasonably fast way to do this is to |
| 267 | pick the most energetic piece of the output sample, locate that in the input |
| 268 | sample and subtract the whole output sample from the input sample:: |
| 269 | |
| 270 | def echocancel(outputdata, inputdata): |
| 271 | pos = audioop.findmax(outputdata, 800) # one tenth second |
| 272 | out_test = outputdata[pos*2:] |
| 273 | in_test = inputdata[pos*2:] |
| 274 | ipos, factor = audioop.findfit(in_test, out_test) |
| 275 | # Optional (for better cancellation): |
Georg Brandl | 48310cd | 2009-01-03 21:18:54 +0000 | [diff] [blame] | 276 | # factor = audioop.findfactor(in_test[ipos*2:ipos*2+len(out_test)], |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 277 | # out_test) |
| 278 | prefill = '\0'*(pos+ipos)*2 |
| 279 | postfill = '\0'*(len(inputdata)-len(prefill)-len(outputdata)) |
Serhiy Storchaka | dba9039 | 2016-05-10 12:01:23 +0300 | [diff] [blame] | 280 | outputdata = prefill + audioop.mul(outputdata, 2, -factor) + postfill |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 281 | return audioop.add(inputdata, outputdata, 2) |
| 282 | |