add hg and python

1 files changed, 202 insertions, 0 deletions

diff --git a/sys/src/cmd/python/Doc/lib/libaifc.tex b/sys/src/cmd/python/Doc/lib/libaifc.tex
new file mode 100644
index 000000000..65abe8484
--- /dev/null
+++ b/sys/src/cmd/python/Doc/lib/libaifc.tex
@@ -0,0 +1,202 @@
+\section{\module{aifc} ---
+         Read and write AIFF and AIFC files}
+
+\declaremodule{standard}{aifc}
+\modulesynopsis{Read and write audio files in AIFF or AIFC format.}
+
+
+This module provides support for reading and writing AIFF and AIFF-C
+files.  AIFF is Audio Interchange File Format, a format for storing
+digital audio samples in a file.  AIFF-C is a newer version of the
+format that includes the ability to compress the audio data.
+\index{Audio Interchange File Format}
+\index{AIFF}
+\index{AIFF-C}
+
+\strong{Caveat:}  Some operations may only work under IRIX; these will
+raise \exception{ImportError} when attempting to import the
+\module{cl} module, which is only available on IRIX.
+
+Audio files have a number of parameters that describe the audio data.
+The sampling rate or frame rate is the number of times per second the
+sound is sampled.  The number of channels indicate if the audio is
+mono, stereo, or quadro.  Each frame consists of one sample per
+channel.  The sample size is the size in bytes of each sample.  Thus a
+frame consists of \var{nchannels}*\var{samplesize} bytes, and a
+second's worth of audio consists of
+\var{nchannels}*\var{samplesize}*\var{framerate} bytes.
+
+For example, CD quality audio has a sample size of two bytes (16
+bits), uses two channels (stereo) and has a frame rate of 44,100
+frames/second.  This gives a frame size of 4 bytes (2*2), and a
+second's worth occupies 2*2*44100 bytes (176,400 bytes).
+
+Module \module{aifc} defines the following function:
+
+\begin{funcdesc}{open}{file\optional{, mode}}
+Open an AIFF or AIFF-C file and return an object instance with
+methods that are described below.  The argument \var{file} is either a
+string naming a file or a file object.  \var{mode} must be \code{'r'}
+or \code{'rb'} when the file must be opened for reading, or \code{'w'} 
+or \code{'wb'} when the file must be opened for writing.  If omitted,
+\code{\var{file}.mode} is used if it exists, otherwise \code{'rb'} is
+used.  When used for writing, the file object should be seekable,
+unless you know ahead of time how many samples you are going to write
+in total and use \method{writeframesraw()} and \method{setnframes()}.
+\end{funcdesc}
+
+Objects returned by \function{open()} when a file is opened for
+reading have the following methods:
+
+\begin{methoddesc}[aifc]{getnchannels}{}
+Return the number of audio channels (1 for mono, 2 for stereo).
+\end{methoddesc}
+
+\begin{methoddesc}[aifc]{getsampwidth}{}
+Return the size in bytes of individual samples.
+\end{methoddesc}
+
+\begin{methoddesc}[aifc]{getframerate}{}
+Return the sampling rate (number of audio frames per second).
+\end{methoddesc}
+
+\begin{methoddesc}[aifc]{getnframes}{}
+Return the number of audio frames in the file.
+\end{methoddesc}
+
+\begin{methoddesc}[aifc]{getcomptype}{}
+Return a four-character string describing the type of compression used
+in the audio file.  For AIFF files, the returned value is
+\code{'NONE'}.
+\end{methoddesc}
+
+\begin{methoddesc}[aifc]{getcompname}{}
+Return a human-readable description of the type of compression used in
+the audio file.  For AIFF files, the returned value is \code{'not
+compressed'}.
+\end{methoddesc}
+
+\begin{methoddesc}[aifc]{getparams}{}
+Return a tuple consisting of all of the above values in the above
+order.
+\end{methoddesc}
+
+\begin{methoddesc}[aifc]{getmarkers}{}
+Return a list of markers in the audio file.  A marker consists of a
+tuple of three elements.  The first is the mark ID (an integer), the
+second is the mark position in frames from the beginning of the data
+(an integer), the third is the name of the mark (a string).
+\end{methoddesc}
+
+\begin{methoddesc}[aifc]{getmark}{id}
+Return the tuple as described in \method{getmarkers()} for the mark
+with the given \var{id}.
+\end{methoddesc}
+
+\begin{methoddesc}[aifc]{readframes}{nframes}
+Read and return the next \var{nframes} frames from the audio file.  The
+returned data is a string containing for each frame the uncompressed
+samples of all channels.
+\end{methoddesc}
+
+\begin{methoddesc}[aifc]{rewind}{}
+Rewind the read pointer.  The next \method{readframes()} will start from
+the beginning.
+\end{methoddesc}
+
+\begin{methoddesc}[aifc]{setpos}{pos}
+Seek to the specified frame number.
+\end{methoddesc}
+
+\begin{methoddesc}[aifc]{tell}{}
+Return the current frame number.
+\end{methoddesc}
+
+\begin{methoddesc}[aifc]{close}{}
+Close the AIFF file.  After calling this method, the object can no
+longer be used.
+\end{methoddesc}
+
+Objects returned by \function{open()} when a file is opened for
+writing have all the above methods, except for \method{readframes()} and
+\method{setpos()}.  In addition the following methods exist.  The
+\method{get*()} methods can only be called after the corresponding
+\method{set*()} methods have been called.  Before the first
+\method{writeframes()} or \method{writeframesraw()}, all parameters
+except for the number of frames must be filled in.
+
+\begin{methoddesc}[aifc]{aiff}{}
+Create an AIFF file.  The default is that an AIFF-C file is created,
+unless the name of the file ends in \code{'.aiff'} in which case the
+default is an AIFF file.
+\end{methoddesc}
+
+\begin{methoddesc}[aifc]{aifc}{}
+Create an AIFF-C file.  The default is that an AIFF-C file is created,
+unless the name of the file ends in \code{'.aiff'} in which case the
+default is an AIFF file.
+\end{methoddesc}
+
+\begin{methoddesc}[aifc]{setnchannels}{nchannels}
+Specify the number of channels in the audio file.
+\end{methoddesc}
+
+\begin{methoddesc}[aifc]{setsampwidth}{width}
+Specify the size in bytes of audio samples.
+\end{methoddesc}
+
+\begin{methoddesc}[aifc]{setframerate}{rate}
+Specify the sampling frequency in frames per second.
+\end{methoddesc}
+
+\begin{methoddesc}[aifc]{setnframes}{nframes}
+Specify the number of frames that are to be written to the audio file.
+If this parameter is not set, or not set correctly, the file needs to
+support seeking.
+\end{methoddesc}
+
+\begin{methoddesc}[aifc]{setcomptype}{type, name}
+Specify the compression type.  If not specified, the audio data will
+not be compressed.  In AIFF files, compression is not possible.  The
+name parameter should be a human-readable description of the
+compression type, the type parameter should be a four-character
+string.  Currently the following compression types are supported:
+NONE, ULAW, ALAW, G722.
+\index{u-LAW}
+\index{A-LAW}
+\index{G.722}
+\end{methoddesc}
+
+\begin{methoddesc}[aifc]{setparams}{nchannels, sampwidth, framerate, comptype, compname}
+Set all the above parameters at once.  The argument is a tuple
+consisting of the various parameters.  This means that it is possible
+to use the result of a \method{getparams()} call as argument to
+\method{setparams()}.
+\end{methoddesc}
+
+\begin{methoddesc}[aifc]{setmark}{id, pos, name}
+Add a mark with the given id (larger than 0), and the given name at
+the given position.  This method can be called at any time before
+\method{close()}.
+\end{methoddesc}
+
+\begin{methoddesc}[aifc]{tell}{}
+Return the current write position in the output file.  Useful in
+combination with \method{setmark()}.
+\end{methoddesc}
+
+\begin{methoddesc}[aifc]{writeframes}{data}
+Write data to the output file.  This method can only be called after
+the audio file parameters have been set.
+\end{methoddesc}
+
+\begin{methoddesc}[aifc]{writeframesraw}{data}
+Like \method{writeframes()}, except that the header of the audio file
+is not updated.
+\end{methoddesc}
+
+\begin{methoddesc}[aifc]{close}{}
+Close the AIFF file.  The header of the file is updated to reflect the
+actual size of the audio data. After calling this method, the object
+can no longer be used.
+\end{methoddesc}