add hg and python

1 files changed, 259 insertions, 0 deletions

diff --git a/sys/src/cmd/python/Doc/lib/libaudioop.tex b/sys/src/cmd/python/Doc/lib/libaudioop.tex
new file mode 100644
index 000000000..52c6f3d79
--- /dev/null
+++ b/sys/src/cmd/python/Doc/lib/libaudioop.tex
@@ -0,0 +1,259 @@
+\section{\module{audioop} ---
+         Manipulate raw audio data}
+
+\declaremodule{builtin}{audioop}
+\modulesynopsis{Manipulate raw audio data.}
+
+
+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 \refmodule{al} and \refmodule{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 a-LAW, u-LAW and Intel/DVI ADPCM encodings.
+\index{Intel/DVI ADPCM}
+\index{ADPCM, Intel/DVI}
+\index{a-LAW}
+\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}{alaw2lin}{fragment, width}
+Convert sound fragments in a-LAW encoding to linearly encoded sound
+fragments.  a-LAW encoding always uses 8 bits samples, so \var{width}
+refers only to the sample width of the output fragment here.
+\versionadded{2.5}
+\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}{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}{lin2alaw}{fragment, width}
+Convert samples in the audio fragment to a-LAW encoding and return
+this as a Python string.  a-LAW is an audio encoding format whereby
+you get a dynamic range of about 13 bits using only 8 bit samples.  It
+is used by the Sun audio hardware, among others.
+\versionadded{2.5}
+\end{funcdesc}
+
+\begin{funcdesc}{lin2lin}{fragment, width, newwidth}
+Convert samples between 1-, 2- and 4-byte formats.
+\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 fragment
+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 tuple \code{(\var{newfragment}, \var{newstate})},
+and \var{newstate} should be passed to the next call of
+\function{ratecv()}.  The initial call should pass \code{None}
+as the state.
+
+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{displaymath}
+\catcode`_=8
+\sqrt{\frac{\sum{{S_{i}}^{2}}}{n}}
+\end{displaymath}
+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}