blob: 52c6f3d798432371cb70df5fbeebcab3647170e5 [file] [log] [blame]
Fred Drake295da241998-08-10 19:42:37 +00001\section{\module{audioop} ---
Fred Drakeffbe6871999-04-22 21:23:22 +00002 Manipulate raw audio data}
Fred Drakeb91e9341998-07-23 17:59:49 +00003
Fred Drakeffbe6871999-04-22 21:23:22 +00004\declaremodule{builtin}{audioop}
Fred Drakeb91e9341998-07-23 17:59:49 +00005\modulesynopsis{Manipulate raw audio data.}
6
Guido van Rossum5fdeeea1994-01-02 01:22:07 +00007
Fred Drakefc576191998-04-04 07:15:02 +00008The \module{audioop} module contains some useful operations on sound
9fragments. It operates on sound fragments consisting of signed
10integer samples 8, 16 or 32 bits wide, stored in Python strings. This
Fred Drakeffbe6871999-04-22 21:23:22 +000011is the same format as used by the \refmodule{al} and \refmodule{sunaudiodev}
Fred Drakefc576191998-04-04 07:15:02 +000012modules. All scalar items are integers, unless specified otherwise.
13
14% This para is mostly here to provide an excuse for the index entries...
Anthony Baxterfa869072006-03-20 05:21:58 +000015This module provides support for a-LAW, u-LAW and Intel/DVI ADPCM encodings.
Fred Drakefc576191998-04-04 07:15:02 +000016\index{Intel/DVI ADPCM}
17\index{ADPCM, Intel/DVI}
Anthony Baxterfa869072006-03-20 05:21:58 +000018\index{a-LAW}
Fred Drakefc576191998-04-04 07:15:02 +000019\index{u-LAW}
Guido van Rossum5fdeeea1994-01-02 01:22:07 +000020
21A few of the more complicated operations only take 16-bit samples,
Fred Drakefc576191998-04-04 07:15:02 +000022otherwise the sample size (in bytes) is always a parameter of the
23operation.
Guido van Rossum5fdeeea1994-01-02 01:22:07 +000024
25The module defines the following variables and functions:
26
Guido van Rossum5fdeeea1994-01-02 01:22:07 +000027\begin{excdesc}{error}
28This exception is raised on all errors, such as unknown number of bytes
29per sample, etc.
30\end{excdesc}
31
Fred Drakecce10901998-03-17 06:33:25 +000032\begin{funcdesc}{add}{fragment1, fragment2, width}
Guido van Rossum470be141995-03-17 16:07:09 +000033Return a fragment which is the addition of the two samples passed as
34parameters. \var{width} is the sample width in bytes, either
35\code{1}, \code{2} or \code{4}. Both fragments should have the same
36length.
Guido van Rossum5fdeeea1994-01-02 01:22:07 +000037\end{funcdesc}
38
Fred Drakecce10901998-03-17 06:33:25 +000039\begin{funcdesc}{adpcm2lin}{adpcmfragment, width, state}
Guido van Rossum470be141995-03-17 16:07:09 +000040Decode an Intel/DVI ADPCM coded fragment to a linear fragment. See
Fred Drakefc576191998-04-04 07:15:02 +000041the description of \function{lin2adpcm()} for details on ADPCM coding.
Guido van Rossum470be141995-03-17 16:07:09 +000042Return a tuple \code{(\var{sample}, \var{newstate})} where the sample
43has the width specified in \var{width}.
Guido van Rossum5fdeeea1994-01-02 01:22:07 +000044\end{funcdesc}
45
Anthony Baxterfa869072006-03-20 05:21:58 +000046\begin{funcdesc}{alaw2lin}{fragment, width}
47Convert sound fragments in a-LAW encoding to linearly encoded sound
48fragments. a-LAW encoding always uses 8 bits samples, so \var{width}
49refers only to the sample width of the output fragment here.
50\versionadded{2.5}
51\end{funcdesc}
52
Fred Drakecce10901998-03-17 06:33:25 +000053\begin{funcdesc}{avg}{fragment, width}
Guido van Rossum470be141995-03-17 16:07:09 +000054Return the average over all samples in the fragment.
Guido van Rossum5fdeeea1994-01-02 01:22:07 +000055\end{funcdesc}
56
Fred Drakecce10901998-03-17 06:33:25 +000057\begin{funcdesc}{avgpp}{fragment, width}
Guido van Rossum470be141995-03-17 16:07:09 +000058Return the average peak-peak value over all samples in the fragment.
59No filtering is done, so the usefulness of this routine is
60questionable.
Guido van Rossum5fdeeea1994-01-02 01:22:07 +000061\end{funcdesc}
62
Fred Drakecce10901998-03-17 06:33:25 +000063\begin{funcdesc}{bias}{fragment, width, bias}
Guido van Rossum470be141995-03-17 16:07:09 +000064Return a fragment that is the original fragment with a bias added to
65each sample.
Guido van Rossum5fdeeea1994-01-02 01:22:07 +000066\end{funcdesc}
67
Fred Drakecce10901998-03-17 06:33:25 +000068\begin{funcdesc}{cross}{fragment, width}
Guido van Rossum470be141995-03-17 16:07:09 +000069Return the number of zero crossings in the fragment passed as an
70argument.
Guido van Rossum5fdeeea1994-01-02 01:22:07 +000071\end{funcdesc}
72
Fred Drakecce10901998-03-17 06:33:25 +000073\begin{funcdesc}{findfactor}{fragment, reference}
Guido van Rossum470be141995-03-17 16:07:09 +000074Return a factor \var{F} such that
Fred Drakefc576191998-04-04 07:15:02 +000075\code{rms(add(\var{fragment}, mul(\var{reference}, -\var{F})))} is
76minimal, i.e., return the factor with which you should multiply
77\var{reference} to make it match as well as possible to
78\var{fragment}. The fragments should both contain 2-byte samples.
Guido van Rossum5fdeeea1994-01-02 01:22:07 +000079
Fred Drakefc576191998-04-04 07:15:02 +000080The time taken by this routine is proportional to
81\code{len(\var{fragment})}.
Guido van Rossum5fdeeea1994-01-02 01:22:07 +000082\end{funcdesc}
83
Fred Drakecce10901998-03-17 06:33:25 +000084\begin{funcdesc}{findfit}{fragment, reference}
Guido van Rossum470be141995-03-17 16:07:09 +000085Try to match \var{reference} as well as possible to a portion of
86\var{fragment} (which should be the longer fragment). This is
87(conceptually) done by taking slices out of \var{fragment}, using
Fred Drakefc576191998-04-04 07:15:02 +000088\function{findfactor()} to compute the best match, and minimizing the
Guido van Rossum470be141995-03-17 16:07:09 +000089result. The fragments should both contain 2-byte samples. Return a
90tuple \code{(\var{offset}, \var{factor})} where \var{offset} is the
Guido van Rossum5fdeeea1994-01-02 01:22:07 +000091(integer) offset into \var{fragment} where the optimal match started
Guido van Rossum470be141995-03-17 16:07:09 +000092and \var{factor} is the (floating-point) factor as per
Fred Drakefc576191998-04-04 07:15:02 +000093\function{findfactor()}.
Guido van Rossum5fdeeea1994-01-02 01:22:07 +000094\end{funcdesc}
95
Fred Drakecce10901998-03-17 06:33:25 +000096\begin{funcdesc}{findmax}{fragment, length}
Guido van Rossum470be141995-03-17 16:07:09 +000097Search \var{fragment} for a slice of length \var{length} samples (not
98bytes!)\ with maximum energy, i.e., return \var{i} for which
99\code{rms(fragment[i*2:(i+length)*2])} is maximal. The fragments
100should both contain 2-byte samples.
Guido van Rossum5fdeeea1994-01-02 01:22:07 +0000101
Fred Drakefc576191998-04-04 07:15:02 +0000102The routine takes time proportional to \code{len(\var{fragment})}.
Guido van Rossum5fdeeea1994-01-02 01:22:07 +0000103\end{funcdesc}
104
Fred Drakecce10901998-03-17 06:33:25 +0000105\begin{funcdesc}{getsample}{fragment, width, index}
Guido van Rossum470be141995-03-17 16:07:09 +0000106Return the value of sample \var{index} from the fragment.
Guido van Rossum5fdeeea1994-01-02 01:22:07 +0000107\end{funcdesc}
108
Fred Drakecce10901998-03-17 06:33:25 +0000109\begin{funcdesc}{lin2adpcm}{fragment, width, state}
Guido van Rossum470be141995-03-17 16:07:09 +0000110Convert samples to 4 bit Intel/DVI ADPCM encoding. ADPCM coding is an
111adaptive coding scheme, whereby each 4 bit number is the difference
112between one sample and the next, divided by a (varying) step. The
113Intel/DVI ADPCM algorithm has been selected for use by the IMA, so it
114may well become a standard.
Guido van Rossum5fdeeea1994-01-02 01:22:07 +0000115
Fred Drakefc576191998-04-04 07:15:02 +0000116\var{state} is a tuple containing the state of the coder. The coder
Guido van Rossum5fdeeea1994-01-02 01:22:07 +0000117returns a tuple \code{(\var{adpcmfrag}, \var{newstate})}, and the
Fred Drakefc576191998-04-04 07:15:02 +0000118\var{newstate} should be passed to the next call of
119\function{lin2adpcm()}. In the initial call, \code{None} can be
120passed as the state. \var{adpcmfrag} is the ADPCM coded fragment
121packed 2 4-bit values per byte.
Guido van Rossum5fdeeea1994-01-02 01:22:07 +0000122\end{funcdesc}
123
Anthony Baxterfa869072006-03-20 05:21:58 +0000124\begin{funcdesc}{lin2alaw}{fragment, width}
125Convert samples in the audio fragment to a-LAW encoding and return
126this as a Python string. a-LAW is an audio encoding format whereby
127you get a dynamic range of about 13 bits using only 8 bit samples. It
128is used by the Sun audio hardware, among others.
129\versionadded{2.5}
130\end{funcdesc}
131
132\begin{funcdesc}{lin2lin}{fragment, width, newwidth}
133Convert samples between 1-, 2- and 4-byte formats.
134\end{funcdesc}
135
Fred Drakecce10901998-03-17 06:33:25 +0000136\begin{funcdesc}{lin2ulaw}{fragment, width}
Fred Drakefc576191998-04-04 07:15:02 +0000137Convert samples in the audio fragment to u-LAW encoding and return
138this as a Python string. u-LAW is an audio encoding format whereby
Guido van Rossum470be141995-03-17 16:07:09 +0000139you get a dynamic range of about 14 bits using only 8 bit samples. It
140is used by the Sun audio hardware, among others.
Guido van Rossum5fdeeea1994-01-02 01:22:07 +0000141\end{funcdesc}
142
Fred Drakecce10901998-03-17 06:33:25 +0000143\begin{funcdesc}{minmax}{fragment, width}
Guido van Rossum470be141995-03-17 16:07:09 +0000144Return a tuple consisting of the minimum and maximum values of all
145samples in the sound fragment.
Guido van Rossum5fdeeea1994-01-02 01:22:07 +0000146\end{funcdesc}
147
Fred Drakecce10901998-03-17 06:33:25 +0000148\begin{funcdesc}{max}{fragment, width}
Fred Drakeaf8a0151998-01-14 14:51:31 +0000149Return the maximum of the \emph{absolute value} of all samples in a
Guido van Rossum470be141995-03-17 16:07:09 +0000150fragment.
Guido van Rossum5fdeeea1994-01-02 01:22:07 +0000151\end{funcdesc}
152
Fred Drakecce10901998-03-17 06:33:25 +0000153\begin{funcdesc}{maxpp}{fragment, width}
Guido van Rossum470be141995-03-17 16:07:09 +0000154Return the maximum peak-peak value in the sound fragment.
Guido van Rossum5fdeeea1994-01-02 01:22:07 +0000155\end{funcdesc}
156
Fred Drakecce10901998-03-17 06:33:25 +0000157\begin{funcdesc}{mul}{fragment, width, factor}
Thomas Woutersf8316632000-07-16 19:01:10 +0000158Return a fragment that has all samples in the original fragment
Guido van Rossum470be141995-03-17 16:07:09 +0000159multiplied by the floating-point value \var{factor}. Overflow is
Guido van Rossum5fdeeea1994-01-02 01:22:07 +0000160silently ignored.
161\end{funcdesc}
162
Fred Drakefc576191998-04-04 07:15:02 +0000163\begin{funcdesc}{ratecv}{fragment, width, nchannels, inrate, outrate,
164 state\optional{, weightA\optional{, weightB}}}
Guido van Rossum6fb6f101997-02-14 15:59:49 +0000165Convert the frame rate of the input fragment.
166
Fred Drakefc576191998-04-04 07:15:02 +0000167\var{state} is a tuple containing the state of the converter. The
Thomas Woutersf8316632000-07-16 19:01:10 +0000168converter returns a tuple \code{(\var{newfragment}, \var{newstate})},
Fred Drakefc576191998-04-04 07:15:02 +0000169and \var{newstate} should be passed to the next call of
Tim Petersc7cb6922001-12-06 23:16:09 +0000170\function{ratecv()}. The initial call should pass \code{None}
171as the state.
Guido van Rossum6fb6f101997-02-14 15:59:49 +0000172
Fred Drakefc576191998-04-04 07:15:02 +0000173The \var{weightA} and \var{weightB} arguments are parameters for a
Fred Drake4aa4f301999-04-23 17:30:40 +0000174simple digital filter and default to \code{1} and \code{0} respectively.
Guido van Rossum6fb6f101997-02-14 15:59:49 +0000175\end{funcdesc}
176
Fred Drakecce10901998-03-17 06:33:25 +0000177\begin{funcdesc}{reverse}{fragment, width}
Guido van Rossum470be141995-03-17 16:07:09 +0000178Reverse the samples in a fragment and returns the modified fragment.
Guido van Rossum5fdeeea1994-01-02 01:22:07 +0000179\end{funcdesc}
180
Fred Drakecce10901998-03-17 06:33:25 +0000181\begin{funcdesc}{rms}{fragment, width}
Guido van Rossum470be141995-03-17 16:07:09 +0000182Return the root-mean-square of the fragment, i.e.
Guido van Rossum5fdeeea1994-01-02 01:22:07 +0000183\begin{displaymath}
184\catcode`_=8
185\sqrt{\frac{\sum{{S_{i}}^{2}}}{n}}
186\end{displaymath}
Guido van Rossum5fdeeea1994-01-02 01:22:07 +0000187This is a measure of the power in an audio signal.
188\end{funcdesc}
189
Fred Drakecce10901998-03-17 06:33:25 +0000190\begin{funcdesc}{tomono}{fragment, width, lfactor, rfactor}
Guido van Rossum470be141995-03-17 16:07:09 +0000191Convert a stereo fragment to a mono fragment. The left channel is
192multiplied by \var{lfactor} and the right channel by \var{rfactor}
193before adding the two channels to give a mono signal.
Guido van Rossum6bb1adc1995-03-13 10:03:32 +0000194\end{funcdesc}
195
Fred Drakecce10901998-03-17 06:33:25 +0000196\begin{funcdesc}{tostereo}{fragment, width, lfactor, rfactor}
Guido van Rossum470be141995-03-17 16:07:09 +0000197Generate a stereo fragment from a mono fragment. Each pair of samples
198in the stereo fragment are computed from the mono sample, whereby left
199channel samples are multiplied by \var{lfactor} and right channel
200samples by \var{rfactor}.
Guido van Rossum6bb1adc1995-03-13 10:03:32 +0000201\end{funcdesc}
202
Fred Drakecce10901998-03-17 06:33:25 +0000203\begin{funcdesc}{ulaw2lin}{fragment, width}
Fred Drakefc576191998-04-04 07:15:02 +0000204Convert sound fragments in u-LAW encoding to linearly encoded sound
205fragments. u-LAW encoding always uses 8 bits samples, so \var{width}
Guido van Rossum470be141995-03-17 16:07:09 +0000206refers only to the sample width of the output fragment here.
Guido van Rossum5fdeeea1994-01-02 01:22:07 +0000207\end{funcdesc}
208
Fred Drakefc576191998-04-04 07:15:02 +0000209Note that operations such as \function{mul()} or \function{max()} make
210no distinction between mono and stereo fragments, i.e.\ all samples
211are treated equal. If this is a problem the stereo fragment should be
212split into two mono fragments first and recombined later. Here is an
213example of how to do that:
214
Fred Drake19479911998-02-13 06:58:54 +0000215\begin{verbatim}
Guido van Rossum5fdeeea1994-01-02 01:22:07 +0000216def mul_stereo(sample, width, lfactor, rfactor):
217 lsample = audioop.tomono(sample, width, 1, 0)
218 rsample = audioop.tomono(sample, width, 0, 1)
219 lsample = audioop.mul(sample, width, lfactor)
220 rsample = audioop.mul(sample, width, rfactor)
221 lsample = audioop.tostereo(lsample, width, 1, 0)
222 rsample = audioop.tostereo(rsample, width, 0, 1)
223 return audioop.add(lsample, rsample, width)
Fred Drake19479911998-02-13 06:58:54 +0000224\end{verbatim}
Fred Drakefc576191998-04-04 07:15:02 +0000225
Guido van Rossum5fdeeea1994-01-02 01:22:07 +0000226If you use the ADPCM coder to build network packets and you want your
Guido van Rossum6bb1adc1995-03-13 10:03:32 +0000227protocol to be stateless (i.e.\ to be able to tolerate packet loss)
Guido van Rossum470be141995-03-17 16:07:09 +0000228you should not only transmit the data but also the state. Note that
Guido van Rossum5fdeeea1994-01-02 01:22:07 +0000229you should send the \var{initial} state (the one you passed to
Fred Drakefc576191998-04-04 07:15:02 +0000230\function{lin2adpcm()}) along to the decoder, not the final state (as
231returned by the coder). If you want to use \function{struct.struct()}
232to store the state in binary you can code the first element (the
233predicted value) in 16 bits and the second (the delta index) in 8.
Guido van Rossum5fdeeea1994-01-02 01:22:07 +0000234
235The ADPCM coders have never been tried against other ADPCM coders,
Guido van Rossum470be141995-03-17 16:07:09 +0000236only against themselves. It could well be that I misinterpreted the
Guido van Rossum5fdeeea1994-01-02 01:22:07 +0000237standards in which case they will not be interoperable with the
238respective standards.
239
Fred Drakefc576191998-04-04 07:15:02 +0000240The \function{find*()} routines might look a bit funny at first sight.
Guido van Rossum470be141995-03-17 16:07:09 +0000241They are primarily meant to do echo cancellation. A reasonably
Guido van Rossum5fdeeea1994-01-02 01:22:07 +0000242fast way to do this is to pick the most energetic piece of the output
243sample, locate that in the input sample and subtract the whole output
244sample from the input sample:
Fred Drakefc576191998-04-04 07:15:02 +0000245
Fred Drake19479911998-02-13 06:58:54 +0000246\begin{verbatim}
Guido van Rossum5fdeeea1994-01-02 01:22:07 +0000247def echocancel(outputdata, inputdata):
248 pos = audioop.findmax(outputdata, 800) # one tenth second
249 out_test = outputdata[pos*2:]
250 in_test = inputdata[pos*2:]
251 ipos, factor = audioop.findfit(in_test, out_test)
252 # Optional (for better cancellation):
253 # factor = audioop.findfactor(in_test[ipos*2:ipos*2+len(out_test)],
254 # out_test)
255 prefill = '\0'*(pos+ipos)*2
256 postfill = '\0'*(len(inputdata)-len(prefill)-len(outputdata))
257 outputdata = prefill + audioop.mul(outputdata,2,-factor) + postfill
258 return audioop.add(inputdata, outputdata, 2)
Fred Drake19479911998-02-13 06:58:54 +0000259\end{verbatim}