Restructured library documentation

1 files changed, 241 insertions, 0 deletions

diff --git a/Doc/libaudioop.tex b/Doc/libaudioop.tex
new file mode 100644
index 0000000..734065a
--- /dev/null
+++ b/Doc/libaudioop.tex
@@ -0,0 +1,241 @@
+\section{Built-in module \sectcode{audioop}}
+\bimodindex{audioop}
+
+The audioop module contains some useful operations on sound fragments.
+It operates on sound fragments consisting of signed integer samples of
+8, 16 or 32 bits wide, stored in Python strings.  This is the same
+format as used by the \code{al} and \code{sunaudiodev} modules.  All
+scalar items are integers, unless specified otherwise.
+
+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:
+
+\renewcommand{\indexsubitem}{(in module audioop)}
+\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}
+This function returns a fragment that 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}
+This routine decodes an Intel/DVI ADPCM coded fragment to a linear
+fragment. See the description of \code{lin2adpcm} for details on ADPCM
+coding. The routine returns 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}
+This routine decodes an alternative 3-bit ADPCM code. See
+\code{lin2adpcm3} for details.
+\end{funcdesc}
+
+\begin{funcdesc}{avg}{fragment\, width}
+This function returns the average over all samples in the fragment.
+\end{funcdesc}
+
+\begin{funcdesc}{avgpp}{fragment\, width}
+This function returns the average peak-peak value over all samples in
+the fragment. No filtering is done, so the useability of this routine
+is questionable.
+\end{funcdesc}
+
+\begin{funcdesc}{bias}{fragment\, width\, bias}
+This function returns a fragment that is the original fragment with a
+bias added to each sample.
+\end{funcdesc}
+
+\begin{funcdesc}{cross}{fragment\, width}
+This function returns the number of zero crossings in the fragment
+passed as an argument.
+\end{funcdesc}
+
+\begin{funcdesc}{findfactor}{fragment\, reference}
+This routine (which only accepts 2-byte sample fragments) calculates a
+factor \var{F} such that \code{rms(add(fragment, mul(reference, -F)))}
+is minimal, i.e. it calculates the factor with which you should
+multiply \var{reference} to make it match as good as possible to
+\var{fragment}. The fragments should be the same size.
+
+The time taken by this routine is proportional to \code{len(fragment)}. 
+\end{funcdesc}
+
+\begin{funcdesc}{findfit}{fragment\, reference}
+This routine (which only accepts 2-byte sample fragments) tries to
+match \var{reference} as good as possible to a portion of
+\var{fragment} (which should be the longer fragment). It
+(conceptually) does this by taking slices out of \var{fragment}, using
+\code{findfactor} to compute the best match, and minimizing the
+result.
+It returns a tuple \code{(\var{offset}, \var{factor})} with offset the
+(integer) offset into \var{fragment} where the optimal match started
+and \var{factor} the floating-point factor as per findfactor.
+\end{funcdesc}
+
+\begin{funcdesc}{findmax}{fragment\, length}
+This routine (which only accepts 2-byte sample fragments) searches
+\var{fragment} for a slice of length \var{length} samples (not bytes!)
+with maximum energy, i.e. it returns \var{i} for which
+\code{rms(fragment[i*2:(i+length)*2])} is maximal.
+
+The routine takes time proportional to \code{len(fragment)}.
+\end{funcdesc}
+
+\begin{funcdesc}{getsample}{fragment\, width\, index}
+This function returns the value of sample \var{index} from the
+fragment.
+\end{funcdesc}
+
+\begin{funcdesc}{lin2lin}{fragment\, width\, newwidth}
+This function converts samples between 1-, 2- and 4-byte formats.
+\end{funcdesc}
+
+\begin{funcdesc}{lin2adpcm}{fragment\, width\, state}
+This function converts 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 algorythm has been selected for
+use by the IMA, so may well become a standard.
+
+\code{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 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}
+This function converts samples in the audio fragment to U-LAW encoding
+and returns 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}
+This function returns a tuple consisting of the minimum and maximum
+values of all samples in the sound fragment.
+\end{funcdesc}
+
+\begin{funcdesc}{max}{fragment\, width}
+This function returns the maximum of the {\em absolute value} of all
+samples in a fragment.
+\end{funcdesc}
+
+\begin{funcdesc}{maxpp}{fragment\, width}
+This function returns the maximum peak-peak value in the sound fragment.
+\end{funcdesc}
+
+\begin{funcdesc}{mul}{fragment\, width\, factor}
+Mul returns 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}{reverse}{fragment\, width}
+This function reverses the samples in a fragment and returns the
+modified fragment.
+\end{funcdesc}
+
+\begin{funcdesc}{tomono}{fragment\, width\, lfactor\, rfactor} 
+This function converts 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}
+This function generates 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}{mul}{fragment\, width\, factor}
+Mul returns 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}{rms}{fragment\, width\, factor}
+Returns the root-mean-square of the fragment, i.e.
+\iftexi
+the square root of the quotient of the sum of all squared sample value,
+divided by the sumber of samples.
+\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
+This is a measure of the power in an audio signal.
+\end{funcdesc}
+
+\begin{funcdesc}{ulaw2lin}{fragment\, width}
+This function converts sound fragments in ULAW encoding to linearly
+encoded sound fragments. ULAW 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 \code{mul} or \code{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:
+\bcode\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}\ecode
+
+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
+lin2adpcm) along to the decoder, not the final state (as returned by
+the coder). If you want to use \code{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 \code{find...} routines might look a bit funny at first sight.
+They are primarily meant for doing 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:
+\bcode\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}\ecode