add hg and python

1 files changed, 401 insertions, 0 deletions

diff --git a/sys/src/cmd/python/Doc/lib/libossaudiodev.tex b/sys/src/cmd/python/Doc/lib/libossaudiodev.tex
new file mode 100644
index 000000000..4c19aafbd
--- /dev/null
+++ b/sys/src/cmd/python/Doc/lib/libossaudiodev.tex
@@ -0,0 +1,401 @@
+\section{\module{ossaudiodev} ---
+         Access to OSS-compatible audio devices}
+
+\declaremodule{builtin}{ossaudiodev}
+\platform{Linux, FreeBSD}
+\modulesynopsis{Access to OSS-compatible audio devices.}
+
+\versionadded{2.3}
+
+This module allows you to access the OSS (Open Sound System) audio
+interface.  OSS is available for a wide range of open-source and
+commercial Unices, and is the standard audio interface for Linux and
+recent versions of FreeBSD.
+
+% Things will get more complicated for future Linux versions, since
+% ALSA is in the standard kernel as of 2.5.x.  Presumably if you
+% use ALSA, you'll have to make sure its OSS compatibility layer
+% is active to use ossaudiodev, but you're gonna need it for the vast
+% majority of Linux audio apps anyways.  
+%
+% Sounds like things are also complicated for other BSDs.  In response
+% to my python-dev query, Thomas Wouters said:
+%
+% > Likewise, googling shows OpenBSD also uses OSS/Free -- the commercial
+% > OSS installation manual tells you to remove references to OSS/Free from the
+% > kernel :)
+%
+% but Aleksander Piotrowsk actually has an OpenBSD box, and he quotes
+% from its <soundcard.h>:
+% >  * WARNING!  WARNING!
+% >  * This is an OSS (Linux) audio emulator.
+% >  * Use the Native NetBSD API for developing new code, and this
+% >  * only for compiling Linux programs.
+%
+% There's also an ossaudio manpage on OpenBSD that explains things
+% further.  Presumably NetBSD and OpenBSD have a different standard
+% audio interface.  That's the great thing about standards, there are so
+% many to choose from ... ;-)  
+%
+% This probably all warrants a footnote or two, but I don't understand
+% things well enough right now to write it!   --GPW
+
+\begin{seealso}
+\seetitle[http://www.opensound.com/pguide/oss.pdf]
+         {Open Sound System Programmer's Guide} {the official
+         documentation for the OSS C API}
+\seetext{The module defines a large number of constants supplied by
+         the OSS device driver; see \code{<sys/soundcard.h>} on either
+         Linux or FreeBSD for a listing .}
+\end{seealso}
+
+\module{ossaudiodev} defines the following variables and functions:
+
+\begin{excdesc}{OSSAudioError}
+This exception is raised on certain errors.  The argument is a string
+describing what went wrong.
+
+(If \module{ossaudiodev} receives an error from a system call such as
+\cfunction{open()}, \cfunction{write()}, or \cfunction{ioctl()}, it
+raises \exception{IOError}.  Errors detected directly by
+\module{ossaudiodev} result in \exception{OSSAudioError}.)
+
+(For backwards compatibility, the exception class is also available as
+\code{ossaudiodev.error}.)
+\end{excdesc}
+
+\begin{funcdesc}{open}{\optional{device, }mode}
+Open an audio device and return an OSS audio device object.  This
+object supports many file-like methods, such as \method{read()},
+\method{write()}, and \method{fileno()} (although there are subtle
+differences between conventional \UNIX{} read/write semantics and those of
+OSS audio devices).  It also supports a number of audio-specific
+methods; see below for the complete list of methods.
+
+\var{device} is the audio device filename to use.  If it is not
+specified, this module first looks in the environment variable
+\envvar{AUDIODEV} for a device to use.  If not found, it falls back to
+\file{/dev/dsp}.
+
+\var{mode} is one of \code{'r'} for read-only (record) access,
+\code{'w'} for write-only (playback) access and \code{'rw'} for both.
+Since many sound cards only allow one process to have the recorder or
+player open at a time, it is a good idea to open the device only for the
+activity needed.  Further, some sound cards are half-duplex: they can be
+opened for reading or writing, but not both at once.
+
+Note the unusual calling syntax: the \emph{first} argument is optional,
+and the second is required.  This is a historical artifact for
+compatibility with the older \module{linuxaudiodev} module which
+\module{ossaudiodev} supersedes.  % XXX it might also be motivated
+% by my unfounded-but-still-possibly-true belief that the default
+% audio device varies unpredictably across operating systems.  -GW
+\end{funcdesc}
+
+\begin{funcdesc}{openmixer}{\optional{device}}
+Open a mixer device and return an OSS mixer device object.  
+\var{device} is the mixer device filename to use.  If it is
+not specified, this module first looks in the environment variable
+\envvar{MIXERDEV} for a device to use.  If not found, it falls back to
+\file{/dev/mixer}.
+
+\end{funcdesc}
+
+\subsection{Audio Device Objects \label{ossaudio-device-objects}}
+
+Before you can write to or read from an audio device, you must call
+three methods in the correct order:
+\begin{enumerate}
+\item \method{setfmt()} to set the output format
+\item \method{channels()} to set the number of channels
+\item \method{speed()} to set the sample rate
+\end{enumerate}
+Alternately, you can use the \method{setparameters()} method to set all
+three audio parameters at once.  This is more convenient, but may not be
+as flexible in all cases.
+
+The audio device objects returned by \function{open()} define the
+following methods and (read-only) attributes:
+
+\begin{methoddesc}[audio device]{close}{}
+Explicitly close the audio device.  When you are done writing to or
+reading from an audio device, you should explicitly close it.  A closed
+device cannot be used again.
+\end{methoddesc}
+
+\begin{methoddesc}[audio device]{fileno}{}
+Return the file descriptor associated with the device.
+\end{methoddesc}
+
+\begin{methoddesc}[audio device]{read}{size}
+Read \var{size} bytes from the audio input and return them as a Python
+string.  Unlike most \UNIX{} device drivers, OSS audio devices in
+blocking mode (the default) will block \function{read()} until the
+entire requested amount of data is available.
+\end{methoddesc}
+
+\begin{methoddesc}[audio device]{write}{data}
+Write the Python string \var{data} to the audio device and return the
+number of bytes written.  If the audio device is in blocking mode (the
+default), the entire string is always written (again, this is different
+from usual \UNIX{} device semantics).  If the device is in non-blocking
+mode, some data may not be written---see \method{writeall()}.
+\end{methoddesc}
+
+\begin{methoddesc}[audio device]{writeall}{data}
+Write the entire Python string \var{data} to the audio device: waits
+until the audio device is able to accept data, writes as much data as it
+will accept, and repeats until \var{data} has been completely written.
+If the device is in blocking mode (the default), this has the same
+effect as \method{write()}; \method{writeall()} is only useful in
+non-blocking mode.  Has no return value, since the amount of data
+written is always equal to the amount of data supplied.
+\end{methoddesc}
+
+The following methods each map to exactly one
+\function{ioctl()} system call.  The correspondence is obvious: for
+example, \method{setfmt()} corresponds to the \code{SNDCTL_DSP_SETFMT}
+ioctl, and \method{sync()} to \code{SNDCTL_DSP_SYNC} (this can be useful
+when consulting the OSS documentation).  If the underlying
+\function{ioctl()} fails, they all raise \exception{IOError}.
+
+\begin{methoddesc}[audio device]{nonblock}{}
+Put the device into non-blocking mode.  Once in non-blocking mode, there
+is no way to return it to blocking mode.
+\end{methoddesc}
+
+\begin{methoddesc}[audio device]{getfmts}{}
+Return a bitmask of the audio output formats supported by the
+soundcard.  Some of the formats supported by OSS are:
+
+\begin{tableii}{l|l}{constant}{Format}{Description}
+\lineii{AFMT_MU_LAW}
+       {a logarithmic encoding (used by Sun \code{.au} files and
+        \filenq{/dev/audio})}
+\lineii{AFMT_A_LAW}
+       {a logarithmic encoding}
+\lineii{AFMT_IMA_ADPCM}
+       {a 4:1 compressed format defined by the Interactive Multimedia
+        Association} 
+\lineii{AFMT_U8}
+       {Unsigned, 8-bit audio}
+\lineii{AFMT_S16_LE}
+       {Signed, 16-bit audio, little-endian byte order (as used by
+        Intel processors)}
+\lineii{AFMT_S16_BE}
+       {Signed, 16-bit audio, big-endian byte order (as used by 68k,
+        PowerPC, Sparc)}
+\lineii{AFMT_S8}
+       {Signed, 8 bit audio}
+\lineii{AFMT_U16_LE}
+       {Unsigned, 16-bit little-endian audio}
+\lineii{AFMT_U16_BE}
+       {Unsigned, 16-bit big-endian audio}
+\end{tableii}
+Consult the OSS documentation for a full list of audio formats, and note
+that most devices support only a subset of these formats.  Some older
+devices only support \constant{AFMT_U8}; the most common format used
+today is \constant{AFMT_S16_LE}.
+\end{methoddesc}
+
+\begin{methoddesc}[audio device]{setfmt}{format}
+Try to set the current audio format to \var{format}---see
+\method{getfmts()} for a list.  Returns the audio format that the device
+was set to, which may not be the requested format.  May also be used to
+return the current audio format---do this by passing an ``audio format''
+of
+\constant{AFMT_QUERY}.  
+\end{methoddesc}
+
+\begin{methoddesc}[audio device]{channels}{nchannels}
+Set the number of output channels to \var{nchannels}.  A value of 1
+indicates monophonic sound, 2 stereophonic.  Some devices may have more
+than 2 channels, and some high-end devices may not support mono.
+Returns the number of channels the device was set to.
+\end{methoddesc}
+
+\begin{methoddesc}[audio device]{speed}{samplerate}
+Try to set the audio sampling rate to \var{samplerate} samples per
+second.  Returns the rate actually set.  Most sound devices don't
+support arbitrary sampling rates.  Common rates are:
+\begin{tableii}{l|l}{textrm}{Rate}{Description}
+\lineii{8000}{default rate for \filenq{/dev/audio}}
+\lineii{11025}{speech recording}
+\lineii{22050}{}
+\lineii{44100}{CD quality audio (at 16 bits/sample and 2 channels)}
+\lineii{96000}{DVD quality audio (at 24 bits/sample)}
+\end{tableii}
+\end{methoddesc}
+
+\begin{methoddesc}[audio device]{sync}{}
+Wait until the sound device has played every byte in its buffer.  (This
+happens implicitly when the device is closed.)  The OSS documentation
+recommends closing and re-opening the device rather than using
+\method{sync()}.
+\end{methoddesc}
+
+\begin{methoddesc}[audio device]{reset}{}
+Immediately stop playing or recording and return the device to a
+state where it can accept commands.  The OSS documentation recommends
+closing and re-opening the device after calling \method{reset()}.
+\end{methoddesc}
+
+\begin{methoddesc}[audio device]{post}{}
+Tell the driver that there is likely to be a pause in the output, making
+it possible for the device to handle the pause more intelligently.  You
+might use this after playing a spot sound effect, before waiting for
+user input, or before doing disk I/O.
+\end{methoddesc}
+
+The following convenience methods combine several ioctls, or one ioctl
+and some simple calculations.
+
+\begin{methoddesc}[audio device]{setparameters}
+  {format, nchannels, samplerate \optional{, strict=False}}
+
+Set the key audio sampling parameters---sample format, number of
+channels, and sampling rate---in one method call.  \var{format}, 
+\var{nchannels}, and \var{samplerate} should be as specified in the
+\method{setfmt()}, \method{channels()}, and \method{speed()} 
+methods.  If \var{strict} is true, \method{setparameters()} checks to
+see if each parameter was actually set to the requested value, and
+raises \exception{OSSAudioError} if not.  Returns a tuple (\var{format},
+\var{nchannels}, \var{samplerate}) indicating the parameter values that
+were actually set by the device driver (i.e., the same as the return
+values of \method{setfmt()}, \method{channels()}, and \method{speed()}).
+
+For example,
+\begin{verbatim}
+  (fmt, channels, rate) = dsp.setparameters(fmt, channels, rate)
+\end{verbatim}
+is equivalent to
+\begin{verbatim}
+  fmt = dsp.setfmt(fmt)
+  channels = dsp.channels(channels)
+  rate = dsp.rate(channels)
+\end{verbatim}
+\end{methoddesc}
+
+\begin{methoddesc}[audio device]{bufsize}{}
+Returns the size of the hardware buffer, in samples.
+\end{methoddesc}
+
+\begin{methoddesc}[audio device]{obufcount}{}
+Returns the number of samples that are in the hardware buffer yet to be
+played.
+\end{methoddesc}
+
+\begin{methoddesc}[audio device]{obuffree}{}
+Returns the number of samples that could be queued into the hardware
+buffer to be played without blocking.
+\end{methoddesc}
+
+Audio device objects also support several read-only attributes:
+
+\begin{memberdesc}[audio device]{closed}{}
+Boolean indicating whether the device has been closed.
+\end{memberdesc}
+
+\begin{memberdesc}[audio device]{name}{}
+String containing the name of the device file.
+\end{memberdesc}
+
+\begin{memberdesc}[audio device]{mode}{}
+The I/O mode for the file, either \code{"r"}, \code{"rw"}, or \code{"w"}.
+\end{memberdesc}
+
+
+\subsection{Mixer Device Objects \label{mixer-device-objects}}
+
+The mixer object provides two file-like methods:
+
+\begin{methoddesc}[mixer device]{close}{}
+This method closes the open mixer device file.  Any further attempts to
+use the mixer after this file is closed will raise an \exception{IOError}.
+\end{methoddesc}
+
+\begin{methoddesc}[mixer device]{fileno}{}
+Returns the file handle number of the open mixer device file.
+\end{methoddesc}
+
+The remaining methods are specific to audio mixing:
+
+\begin{methoddesc}[mixer device]{controls}{}
+This method returns a bitmask specifying the available mixer controls
+(``Control'' being a specific mixable ``channel'', such as
+\constant{SOUND_MIXER_PCM} or \constant{SOUND_MIXER_SYNTH}).  This
+bitmask indicates a subset of all available mixer controls---the
+\constant{SOUND_MIXER_*} constants defined at module level.  To determine if,
+for example, the current mixer object supports a PCM mixer, use the
+following Python code:
+
+\begin{verbatim}
+mixer=ossaudiodev.openmixer()
+if mixer.controls() & (1 << ossaudiodev.SOUND_MIXER_PCM):
+    # PCM is supported
+    ... code ...
+\end{verbatim}
+
+For most purposes, the \constant{SOUND_MIXER_VOLUME} (master volume) and
+\constant{SOUND_MIXER_PCM} controls should suffice---but code that uses the
+mixer should be flexible when it comes to choosing mixer controls.  On
+the Gravis Ultrasound, for example, \constant{SOUND_MIXER_VOLUME} does not
+exist.
+\end{methoddesc}
+
+\begin{methoddesc}[mixer device]{stereocontrols}{}
+Returns a bitmask indicating stereo mixer controls.  If a bit is set,
+the corresponding control is stereo; if it is unset, the control is
+either monophonic or not supported by the mixer (use in combination with
+\method{controls()} to determine which).
+
+See the code example for the \method{controls()} function for an example
+of getting data from a bitmask.
+\end{methoddesc}
+
+\begin{methoddesc}[mixer device]{reccontrols}{}
+Returns a bitmask specifying the mixer controls that may be used to
+record.  See the code example for \method{controls()} for an example of
+reading from a bitmask.
+\end{methoddesc}
+
+\begin{methoddesc}[mixer device]{get}{control}
+Returns the volume of a given mixer control.  The returned volume is a
+2-tuple \code{(left_volume,right_volume)}.  Volumes are specified as
+numbers from 0 (silent) to 100 (full volume).  If the control is
+monophonic, a 2-tuple is still returned, but both volumes are
+the same.
+
+Raises \exception{OSSAudioError} if an invalid control was is specified,
+or \exception{IOError} if an unsupported control is specified.
+\end{methoddesc}
+
+\begin{methoddesc}[mixer device]{set}{control, (left, right)}
+Sets the volume for a given mixer control to \code{(left,right)}.
+\code{left} and \code{right} must be ints and between 0 (silent) and 100
+(full volume).  On success, the new volume is returned as a 2-tuple.
+Note that this may not be exactly the same as the volume specified,
+because of the limited resolution of some soundcard's mixers.
+
+Raises \exception{OSSAudioError} if an invalid mixer control was
+specified, or if the specified volumes were out-of-range.
+\end{methoddesc}
+
+\begin{methoddesc}[mixer device]{get_recsrc}{}
+This method returns a bitmask indicating which control(s) are
+currently being used as a recording source.
+\end{methoddesc}
+
+\begin{methoddesc}[mixer device]{set_recsrc}{bitmask}
+Call this function to specify a recording source.  Returns a bitmask
+indicating the new recording source (or sources) if successful; raises
+\exception{IOError} if an invalid source was specified.  To set the current
+recording source to the microphone input:
+
+\begin{verbatim}
+mixer.setrecsrc (1 << ossaudiodev.SOUND_MIXER_MIC)
+\end{verbatim}
+\end{methoddesc}
+
+
+