mirror of
https://github.com/python/cpython.git
synced 2024-11-27 11:55:13 +08:00
263 lines
10 KiB
TeX
263 lines
10 KiB
TeX
\section{Built-in Module \module{audioop}}
|
|
\label{module-audioop}
|
|
\bimodindex{audioop}
|
|
|
|
The \module{audioop} module contains some useful operations on sound
|
|
fragments. It operates on sound fragments consisting of signed
|
|
integer samples 8, 16 or 32 bits wide, stored in Python strings. This
|
|
is the same format as used by the \module{al} and \module{sunaudiodev}
|
|
modules. All scalar items are integers, unless specified otherwise.
|
|
|
|
% This para is mostly here to provide an excuse for the index entries...
|
|
This module provides support for u-LAW and Intel/DVI ADPCM encodings.
|
|
\index{Intel/DVI ADPCM}
|
|
\index{ADPCM, Intel/DVI}
|
|
\index{u-LAW}
|
|
|
|
A few of the more complicated operations only take 16-bit samples,
|
|
otherwise the sample size (in bytes) is always a parameter of the
|
|
operation.
|
|
|
|
The module defines the following variables and functions:
|
|
|
|
\begin{excdesc}{error}
|
|
This exception is raised on all errors, such as unknown number of bytes
|
|
per sample, etc.
|
|
\end{excdesc}
|
|
|
|
\begin{funcdesc}{add}{fragment1, fragment2, width}
|
|
Return a fragment which is the addition of the two samples passed as
|
|
parameters. \var{width} is the sample width in bytes, either
|
|
\code{1}, \code{2} or \code{4}. Both fragments should have the same
|
|
length.
|
|
\end{funcdesc}
|
|
|
|
\begin{funcdesc}{adpcm2lin}{adpcmfragment, width, state}
|
|
Decode an Intel/DVI ADPCM coded fragment to a linear fragment. See
|
|
the description of \function{lin2adpcm()} for details on ADPCM coding.
|
|
Return a tuple \code{(\var{sample}, \var{newstate})} where the sample
|
|
has the width specified in \var{width}.
|
|
\end{funcdesc}
|
|
|
|
\begin{funcdesc}{adpcm32lin}{adpcmfragment, width, state}
|
|
Decode an alternative 3-bit ADPCM code. See \function{lin2adpcm3()}
|
|
for details.
|
|
\end{funcdesc}
|
|
|
|
\begin{funcdesc}{avg}{fragment, width}
|
|
Return the average over all samples in the fragment.
|
|
\end{funcdesc}
|
|
|
|
\begin{funcdesc}{avgpp}{fragment, width}
|
|
Return the average peak-peak value over all samples in the fragment.
|
|
No filtering is done, so the usefulness of this routine is
|
|
questionable.
|
|
\end{funcdesc}
|
|
|
|
\begin{funcdesc}{bias}{fragment, width, bias}
|
|
Return a fragment that is the original fragment with a bias added to
|
|
each sample.
|
|
\end{funcdesc}
|
|
|
|
\begin{funcdesc}{cross}{fragment, width}
|
|
Return the number of zero crossings in the fragment passed as an
|
|
argument.
|
|
\end{funcdesc}
|
|
|
|
\begin{funcdesc}{findfactor}{fragment, reference}
|
|
Return a factor \var{F} such that
|
|
\code{rms(add(\var{fragment}, mul(\var{reference}, -\var{F})))} is
|
|
minimal, i.e., return the factor with which you should multiply
|
|
\var{reference} to make it match as well as possible to
|
|
\var{fragment}. The fragments should both contain 2-byte samples.
|
|
|
|
The time taken by this routine is proportional to
|
|
\code{len(\var{fragment})}.
|
|
\end{funcdesc}
|
|
|
|
\begin{funcdesc}{findfit}{fragment, reference}
|
|
Try to match \var{reference} as well as possible to a portion of
|
|
\var{fragment} (which should be the longer fragment). This is
|
|
(conceptually) done by taking slices out of \var{fragment}, using
|
|
\function{findfactor()} to compute the best match, and minimizing the
|
|
result. The fragments should both contain 2-byte samples. Return a
|
|
tuple \code{(\var{offset}, \var{factor})} where \var{offset} is the
|
|
(integer) offset into \var{fragment} where the optimal match started
|
|
and \var{factor} is the (floating-point) factor as per
|
|
\function{findfactor()}.
|
|
\end{funcdesc}
|
|
|
|
\begin{funcdesc}{findmax}{fragment, length}
|
|
Search \var{fragment} for a slice of length \var{length} samples (not
|
|
bytes!)\ with maximum energy, i.e., return \var{i} for which
|
|
\code{rms(fragment[i*2:(i+length)*2])} is maximal. The fragments
|
|
should both contain 2-byte samples.
|
|
|
|
The routine takes time proportional to \code{len(\var{fragment})}.
|
|
\end{funcdesc}
|
|
|
|
\begin{funcdesc}{getsample}{fragment, width, index}
|
|
Return the value of sample \var{index} from the fragment.
|
|
\end{funcdesc}
|
|
|
|
\begin{funcdesc}{lin2lin}{fragment, width, newwidth}
|
|
Convert samples between 1-, 2- and 4-byte formats.
|
|
\end{funcdesc}
|
|
|
|
\begin{funcdesc}{lin2adpcm}{fragment, width, state}
|
|
Convert samples to 4 bit Intel/DVI ADPCM encoding. ADPCM coding is an
|
|
adaptive coding scheme, whereby each 4 bit number is the difference
|
|
between one sample and the next, divided by a (varying) step. The
|
|
Intel/DVI ADPCM algorithm has been selected for use by the IMA, so it
|
|
may well become a standard.
|
|
|
|
\var{state} is a tuple containing the state of the coder. The coder
|
|
returns a tuple \code{(\var{adpcmfrag}, \var{newstate})}, and the
|
|
\var{newstate} should be passed to the next call of
|
|
\function{lin2adpcm()}. In the initial call, \code{None} can be
|
|
passed as the state. \var{adpcmfrag} is the ADPCM coded fragment
|
|
packed 2 4-bit values per byte.
|
|
\end{funcdesc}
|
|
|
|
\begin{funcdesc}{lin2adpcm3}{fragment, width, state}
|
|
This is an alternative ADPCM coder that uses only 3 bits per sample.
|
|
It is not compatible with the Intel/DVI ADPCM coder and its output is
|
|
not packed (due to laziness on the side of the author). Its use is
|
|
discouraged.
|
|
\end{funcdesc}
|
|
|
|
\begin{funcdesc}{lin2ulaw}{fragment, width}
|
|
Convert samples in the audio fragment to u-LAW encoding and return
|
|
this as a Python string. u-LAW is an audio encoding format whereby
|
|
you get a dynamic range of about 14 bits using only 8 bit samples. It
|
|
is used by the Sun audio hardware, among others.
|
|
\end{funcdesc}
|
|
|
|
\begin{funcdesc}{minmax}{fragment, width}
|
|
Return a tuple consisting of the minimum and maximum values of all
|
|
samples in the sound fragment.
|
|
\end{funcdesc}
|
|
|
|
\begin{funcdesc}{max}{fragment, width}
|
|
Return the maximum of the \emph{absolute value} of all samples in a
|
|
fragment.
|
|
\end{funcdesc}
|
|
|
|
\begin{funcdesc}{maxpp}{fragment, width}
|
|
Return the maximum peak-peak value in the sound fragment.
|
|
\end{funcdesc}
|
|
|
|
\begin{funcdesc}{mul}{fragment, width, factor}
|
|
Return a fragment that has all samples in the original framgent
|
|
multiplied by the floating-point value \var{factor}. Overflow is
|
|
silently ignored.
|
|
\end{funcdesc}
|
|
|
|
\begin{funcdesc}{ratecv}{fragment, width, nchannels, inrate, outrate,
|
|
state\optional{, weightA\optional{, weightB}}}
|
|
Convert the frame rate of the input fragment.
|
|
|
|
\var{state} is a tuple containing the state of the converter. The
|
|
converter returns a tupl \code{(\var{newfragment}, \var{newstate})},
|
|
and \var{newstate} should be passed to the next call of
|
|
\function{ratecv()}.
|
|
|
|
The \var{weightA} and \var{weightB} arguments are parameters for a
|
|
simple digital filter and default to \code{1} and \code{0}
|
|
respectively.
|
|
\end{funcdesc}
|
|
|
|
\begin{funcdesc}{reverse}{fragment, width}
|
|
Reverse the samples in a fragment and returns the modified fragment.
|
|
\end{funcdesc}
|
|
|
|
\begin{funcdesc}{rms}{fragment, width}
|
|
Return the root-mean-square of the fragment, i.e.
|
|
%begin{latexonly}
|
|
\iftexi
|
|
%end{latexonly}
|
|
the square root of the quotient of the sum of all squared sample value,
|
|
divided by the sumber of samples.
|
|
%begin{latexonly}
|
|
\else
|
|
% in eqn: sqrt { sum S sub i sup 2 over n }
|
|
\begin{displaymath}
|
|
\catcode`_=8
|
|
\sqrt{\frac{\sum{{S_{i}}^{2}}}{n}}
|
|
\end{displaymath}
|
|
\fi
|
|
%end{latexonly}
|
|
This is a measure of the power in an audio signal.
|
|
\end{funcdesc}
|
|
|
|
\begin{funcdesc}{tomono}{fragment, width, lfactor, rfactor}
|
|
Convert a stereo fragment to a mono fragment. The left channel is
|
|
multiplied by \var{lfactor} and the right channel by \var{rfactor}
|
|
before adding the two channels to give a mono signal.
|
|
\end{funcdesc}
|
|
|
|
\begin{funcdesc}{tostereo}{fragment, width, lfactor, rfactor}
|
|
Generate a stereo fragment from a mono fragment. Each pair of samples
|
|
in the stereo fragment are computed from the mono sample, whereby left
|
|
channel samples are multiplied by \var{lfactor} and right channel
|
|
samples by \var{rfactor}.
|
|
\end{funcdesc}
|
|
|
|
\begin{funcdesc}{ulaw2lin}{fragment, width}
|
|
Convert sound fragments in u-LAW encoding to linearly encoded sound
|
|
fragments. u-LAW encoding always uses 8 bits samples, so \var{width}
|
|
refers only to the sample width of the output fragment here.
|
|
\end{funcdesc}
|
|
|
|
Note that operations such as \function{mul()} or \function{max()} make
|
|
no distinction between mono and stereo fragments, i.e.\ all samples
|
|
are treated equal. If this is a problem the stereo fragment should be
|
|
split into two mono fragments first and recombined later. Here is an
|
|
example of how to do that:
|
|
|
|
\begin{verbatim}
|
|
def mul_stereo(sample, width, lfactor, rfactor):
|
|
lsample = audioop.tomono(sample, width, 1, 0)
|
|
rsample = audioop.tomono(sample, width, 0, 1)
|
|
lsample = audioop.mul(sample, width, lfactor)
|
|
rsample = audioop.mul(sample, width, rfactor)
|
|
lsample = audioop.tostereo(lsample, width, 1, 0)
|
|
rsample = audioop.tostereo(rsample, width, 0, 1)
|
|
return audioop.add(lsample, rsample, width)
|
|
\end{verbatim}
|
|
|
|
If you use the ADPCM coder to build network packets and you want your
|
|
protocol to be stateless (i.e.\ to be able to tolerate packet loss)
|
|
you should not only transmit the data but also the state. Note that
|
|
you should send the \var{initial} state (the one you passed to
|
|
\function{lin2adpcm()}) along to the decoder, not the final state (as
|
|
returned by the coder). If you want to use \function{struct.struct()}
|
|
to store the state in binary you can code the first element (the
|
|
predicted value) in 16 bits and the second (the delta index) in 8.
|
|
|
|
The ADPCM coders have never been tried against other ADPCM coders,
|
|
only against themselves. It could well be that I misinterpreted the
|
|
standards in which case they will not be interoperable with the
|
|
respective standards.
|
|
|
|
The \function{find*()} routines might look a bit funny at first sight.
|
|
They are primarily meant to do echo cancellation. A reasonably
|
|
fast way to do this is to pick the most energetic piece of the output
|
|
sample, locate that in the input sample and subtract the whole output
|
|
sample from the input sample:
|
|
|
|
\begin{verbatim}
|
|
def echocancel(outputdata, inputdata):
|
|
pos = audioop.findmax(outputdata, 800) # one tenth second
|
|
out_test = outputdata[pos*2:]
|
|
in_test = inputdata[pos*2:]
|
|
ipos, factor = audioop.findfit(in_test, out_test)
|
|
# Optional (for better cancellation):
|
|
# factor = audioop.findfactor(in_test[ipos*2:ipos*2+len(out_test)],
|
|
# out_test)
|
|
prefill = '\0'*(pos+ipos)*2
|
|
postfill = '\0'*(len(inputdata)-len(prefill)-len(outputdata))
|
|
outputdata = prefill + audioop.mul(outputdata,2,-factor) + postfill
|
|
return audioop.add(inputdata, outputdata, 2)
|
|
\end{verbatim}
|