First stab at documentation in gh-pages

_sources/index.txt

@@ -0,0 +1,26 @@
+alsaaudio documentation
+=======================
+
+.. toctree::
+   :maxdepth: 2
+
+   pyalsaaudio
+   terminology
+   libalsaaudio
+
+
+Github pages
+=================
+
+* `Project page <https://github.com/larsimmisch/pyalsaaudio/>`_
+* `Download from pypi: <https://pypi.python.org/pypi/pyalsaaudio>`_
+* `Bug tracker <https://github.com/larsimmisch/pyalsaaudio/issues>`_
+
+
+Indices and tables
+==================
+
+* :ref:`genindex`
+* :ref:`modindex`
+* :ref:`search`
+

_sources/libalsaaudio.txt

@@ -0,0 +1,551 @@
+****************
+:mod:`alsaaudio`
+****************
+
+.. module:: alsaaudio
+   :platform: Linux
+
+
+.. % \declaremodule{builtin}{alsaaudio}	% standard library, in C
+.. % not standard, in C
+
+.. moduleauthor:: Casper Wilstrup <cwi@aves.dk>
+.. moduleauthor:: Lars Immisch <lars@ibp.de>
+
+
+.. % Author of the module code;
+
+
+
+The :mod:`alsaaudio` module defines functions and classes for using ALSA.
+
+.. % ---- 3.1. ----
+.. % For each function, use a ``funcdesc'' block.  This has exactly two
+.. % parameters (each parameters is contained in a set of curly braces):
+.. % the first parameter is the function name (this automatically
+.. % generates an index entry); the second parameter is the function's
+.. % argument list.  If there are no arguments, use an empty pair of
+.. % curly braces.  If there is more than one argument, separate the
+.. % arguments with backslash-comma.  Optional parts of the parameter
+.. % list are contained in \optional{...} (this generates a set of square
+.. % brackets around its parameter).  Arguments are automatically set in
+.. % italics in the parameter list.  Each argument should be mentioned at
+.. % least once in the description; each usage (even inside \code{...})
+.. % should be enclosed in \var{...}.
+
+
+.. function:: cards()
+
+   List the available cards by name (suitable for PCM objects). 
+
+.. function:: mixers([cardindex])
+
+   List the available mixers. The optional *cardindex* specifies which card 
+   should be queried. The default is 0.
+
+.. class:: PCM(type=PCM_PLAYBACK, mode=PCM_NORMAL, card='default')
+
+   This class is used to represent a PCM device (both for playback and
+   recording - capture). The arguments are:
+
+   * *type* - can be either ``PCM_CAPTURE`` or ``PCM_PLAYBACK`` (default).  
+   * *mode* - can be either ``PCM_NONBLOCK``, or ``PCM_NORMAL`` (default). 
+   * *card* - specifies the name of the card that should be used.
+
+.. class:: Mixer(control='Master', id=0, cardindex=0)
+
+   This class is used to access a specific ALSA mixer. The arguments
+   are:  
+
+   * *control* - Name of the chosen mixed (default is 'Master').  
+   * *id* - id of mixer -- More explanation needed here 
+   * *cardindex*  specifies which card should be used.
+
+.. exception:: ALSAAudioError
+
+   Exception raised when an operation fails for a ALSA specific reason. The
+   exception argument is a string describing the reason of the failure.
+
+.. _pcm-objects:
+
+PCM Objects
+-----------
+
+PCM objects in :mod:`alsaaudio` can play or capture (record) PCM
+sound through speakers or a microphone. The PCM constructor takes the
+following arguments:
+
+.. class:: PCM(type=PCM_CAPTURE, mode=PCM_NORMAL, card='default')
+
+   *type* - can be either ``PCM_CAPTURE`` or ``PCM_PLAYBACK`` (default).
+
+   *mode* - can be either ``PCM_NONBLOCK``, or ``PCM_NORMAL`` (the
+   default). In ``PCM_NONBLOCK`` mode, calls to :func:`read` will return
+   immediately independent of whether there is any actual data to
+   read. Similarly, calls to :func:`write` will return immediately without
+   actually writing anything to the playout buffer if the buffer is
+   full [#f1]_.
+
+   *card* - specifies which card should be used. This can be a string
+   like 'default' or a name that was returned from the :func:`cards` function.
+
+   This will construct a PCM object with these default settings:
+
+   * Sample format: ``PCM_FORMAT_S16_LE``
+   * Rate: 44100 Hz 
+   * Channels: 2
+   * Period size: 32 frames
+
+PCM objects have the following methods:
+
+
+.. method:: PCM.pcmtype()
+
+   Returns the type of PCM object. Either ``PCM_CAPTURE`` or ``PCM_PLAYBACK``.
+
+
+.. method:: PCM.pcmmode()
+
+   Return the mode of the PCM object. One of ``PCM_NONBLOCK``, ``PCM_ASYNC``,
+   or ``PCM_NORMAL``
+
+
+.. method:: PCM.cardname()
+
+   Return the name of the sound card used by this PCM object.
+
+
+.. method:: PCM.setchannels(nchannels)
+
+   Used to set the number of capture or playback channels. Common
+   values are: 1 = mono, 2 = stereo, and 6 = full 6 channel audio. Few
+   sound cards support more than 2 channels
+
+
+.. method:: PCM.setrate(rate)
+
+   Set the sample rate in Hz for the device. Typical values are 8000
+   (mainly used for telephony), 16000, 44100 (CD quality), and 96000.
+
+
+.. method:: PCM.setformat(format)
+
+   The sound *format* of the device. Sound format controls how the PCM device
+   interpret data for playback, and how data is encoded in captures.
+
+   The following formats are provided by ALSA:
+
+   =====================  ===============
+          Format            Description
+   =====================  ===============
+   PCM_FORMAT_S8		  Signed 8 bit samples for each channel
+   PCM_FORMAT_U8		  Signed 8 bit samples for each channel
+   PCM_FORMAT_S16_LE	  Signed 16 bit samples for each channel Little Endian byte order)
+   PCM_FORMAT_S16_BE	  Signed 16 bit samples for each channel (Big Endian byte order)
+   PCM_FORMAT_U16_LE	  Unsigned 16 bit samples for each channel (Little Endian byte order)
+   PCM_FORMAT_U16_BE	  Unsigned 16 bit samples for each channel (Big Endian byte order)
+   PCM_FORMAT_S24_LE	  Signed 24 bit samples for each channel (Little Endian byte order)
+   PCM_FORMAT_S24_BE	  Signed 24 bit samples for each channel (Big Endian byte order)}
+   PCM_FORMAT_U24_LE	  Unsigned 24 bit samples for each channel (Little Endian byte order)
+   PCM_FORMAT_U24_BE	  Unsigned 24 bit samples for each channel (Big Endian byte order)
+   PCM_FORMAT_S32_LE	  Signed 32 bit samples for each channel (Little Endian byte order)
+   PCM_FORMAT_S32_BE	  Signed 32 bit samples for each channel (Big Endian byte order)
+   PCM_FORMAT_U32_LE	  Unsigned 32 bit samples for each channel (Little Endian byte order)
+   PCM_FORMAT_U32_BE	  Unsigned 32 bit samples for each channel (Big Endian byte order)
+   PCM_FORMAT_FLOAT_LE	  32 bit samples encoded as float (Little Endian byte order)
+   PCM_FORMAT_FLOAT_BE	  32 bit samples encoded as float (Big Endian byte order)
+   PCM_FORMAT_FLOAT64_LE  64 bit samples encoded as float (Little Endian byte order)
+   PCM_FORMAT_FLOAT64_BE  64 bit samples encoded as float (Big Endian byte order)
+   PCM_FORMAT_MU_LAW	  A logarithmic encoding (used by Sun .au files and telephony)
+   PCM_FORMAT_A_LAW		  Another logarithmic encoding
+   PCM_FORMAT_IMA_ADPCM	  A 4:1 compressed format defined by the Interactive Multimedia Association.
+   PCM_FORMAT_MPEG		  MPEG encoded audio?
+   PCM_FORMAT_GSM		  9600 bits/s constant rate encoding for speech
+   =====================  ===============
+   
+
+.. method:: PCM.setperiodsize(period)
+
+   Sets the actual period size in frames. Each write should consist of
+   exactly this number of frames, and each read will return this
+   number of frames (unless the device is in ``PCM_NONBLOCK`` mode, in
+   which case it may return nothing at all)
+
+
+.. method:: PCM.read()
+
+   In ``PCM_NORMAL`` mode, this function blocks until a full period is
+   available, and then returns a tuple (length,data) where *length* is
+   the number of frames of captured data, and *data* is the captured
+   sound frames as a string. The length of the returned data will be 
+   periodsize\*framesize bytes.
+
+   In ``PCM_NONBLOCK`` mode, the call will not block, but will return
+   ``(0,'')`` if no new period has become available since the last
+   call to read.
+
+
+.. method:: PCM.write(data)
+
+   Writes (plays) the sound in data. The length of data *must* be a
+   multiple of the frame size, and *should* be exactly the size of a
+   period. If less than 'period size' frames are provided, the actual
+   playout will not happen until more data is written.
+
+   If the device is not in ``PCM_NONBLOCK`` mode, this call will block if
+   the kernel buffer is full, and until enough sound has been played
+   to allow the sound data to be buffered. The call always returns the
+   size of the data provided.
+
+   In ``PCM_NONBLOCK`` mode, the call will return immediately, with a
+   return value of zero, if the buffer is full. In this case, the data
+   should be written at a later time.
+
+
+.. method:: PCM.pause([enable=1])
+
+   If *enable* is 1, playback or capture is paused. If *enable* is 0,
+   playback/capture is resumed.
+
+**A few hints on using PCM devices for playback**
+
+The most common reason for problems with playback of PCM audio is that writes 
+to PCM devices must *exactly* match the data rate of the device.
+
+If too little data is written to the device, it will underrun, and
+ugly clicking sounds will occur. Conversely, of too much data is
+written to the device, the write function will either block
+(``PCM_NORMAL`` mode) or return zero (``PCM_NONBLOCK`` mode).
+
+If your program does nothing but play sound, the best strategy is to put the
+device in ``PCM_NORMAL`` mode, and just write as much data to the device as
+possible. This strategy can also be achieved by using a separate
+thread with the sole task of playing out sound.
+
+In GUI programs, however, it may be a better strategy to setup the device,
+preload the buffer with a few periods by calling write a couple of times, and
+then use some timer method to write one period size of data to the device every
+period. The purpose of the preloading is to avoid underrun clicks if the used
+timer doesn't expire exactly on time.
+
+Also note, that most timer APIs that you can find for Python will
+accummulate time delays: If you set the timer to expire after 1/10'th
+of a second, the actual timeout will happen slightly later, which will
+accumulate to quite a lot after a few seconds. Hint: use time.time()
+to check how much time has really passed, and add extra writes as nessecary.
+
+
+.. _mixer-objects:
+
+Mixer Objects
+-------------
+
+Mixer objects provides access to the ALSA mixer API.
+
+
+.. class:: Mixer(control='Master', id=0, cardindex=0)
+
+   *control* - specifies which control to manipulate using this mixer
+   object. The list of available controls can be found with the 
+   :mod:`alsaaudio`.\ :func:`mixers` function.  The default value is
+   'Master' - other common controls include 'Master Mono', 'PCM', 'Line', etc.
+
+   *id* - the id of the mixer control. Default is 0
+
+   *cardindex* - specifies which card should be used [#f3]_. 0 is the
+   first sound card.
+
+   
+   **Note:** For a list of available controls, you can also use **amixer**::
+      
+      amixer
+
+Mixer objects have the following methods:
+
+.. method:: Mixer.cardname()
+
+   Return the name of the sound card used by this Mixer object
+
+
+.. method:: Mixer.mixer()
+
+   Return the name of the specific mixer controlled by this object, For example
+   'Master' or 'PCM'
+
+
+.. method:: Mixer.mixerid()
+
+   Return the ID of the ALSA mixer controlled by this object.
+
+
+.. method:: Mixer.switchcap()
+
+   Returns a list of the switches which are defined by this specific mixer.
+   Possible values in this list are:
+
+   ======================  ================
+   Switch                  Description
+   ======================  ================
+   'Mute'                  This mixer can mute
+   'Joined Mute'           This mixer can mute all channels at the same time
+   'Playback Mute'         This mixer can mute the playback output
+   'Joined Playback Mute'  Mute playback for all channels at the same time}
+   'Capture Mute'          Mute sound capture 
+   'Joined Capture Mute'   Mute sound capture for all channels at a time}
+   'Capture Exclusive'     Not quite sure what this is
+   ======================  ================
+
+   To manipulate these switches use the :meth:`setrec` or
+   :meth:`setmute` methods
+
+
+.. method:: Mixer.volumecap()
+
+   Returns a list of the volume control capabilities of this
+   mixer. Possible values in the list are:
+
+   ========================  ================
+   Capability                Description
+   ========================  ================
+   'Volume'                  This mixer can control volume
+   'Joined Volume'           This mixer can control volume for all channels at the same time
+   'Playback Volume'         This mixer can manipulate the playback output
+   'Joined Playback Volume'  Manipulate playback volumne for all channels at the same time
+   'Capture Volume'          Manipulate sound capture volume
+   'Joined Capture Volume'   Manipulate sound capture volume for all channels at a time
+   ========================  ================
+   
+.. method:: Mixer.getenum()
+
+   For enumerated controls, return the currently selected item and  the list of
+   items available.
+
+   Returns a tuple *(string, list of strings)*.
+
+   For example, my soundcard has a Mixer called *Mono Output Select*. Using
+   *amixer*, I get::
+
+      $ amixer get "Mono Output Select"
+      Simple mixer control 'Mono Output Select',0
+        Capabilities: enum
+        Items: 'Mix' 'Mic'
+        Item0: 'Mix'
+
+   Using :mod:`alsaaudio`, one could do::
+
+      >>> import alsaaudio
+      >>> m = alsaaudio.Mixer('Mono Output Select')
+      >>> m.getenum()
+      ('Mix', ['Mix', 'Mic'])
+
+   This method will return an empty tuple if the mixer is not an  enumerated
+   control.
+
+
+.. method:: Mixer.getmute()
+
+   Return a list indicating the current mute setting for each
+   channel. 0 means not muted, 1 means muted.
+
+   This method will fail if the mixer has no playback switch capabilities.
+
+
+.. method:: Mixer.getrange([direction])
+
+   Return the volume range of the ALSA mixer controlled by this object.
+
+   The optional *direction* argument can be either 'playback' or
+   'capture', which is relevant if the mixer can control both playback
+   and capture volume.  The default value is 'playback' if the mixer
+   has this capability, otherwise 'capture'
+
+
+.. method:: Mixer.getrec()
+
+   Return a list indicating the current record mute setting for each channel. 0
+   means not recording, 1 means recording.
+
+   This method will fail if the mixer has no capture switch capabilities.
+
+
+.. method:: Mixer.getvolume([direction])
+
+   Returns a list with the current volume settings for each channel. The list
+   elements are integer percentages.
+
+   The optional *direction* argument can be either 'playback' or
+   'capture', which is relevant if the mixer can control both playback
+   and capture volume. The default value is 'playback' if the mixer
+   has this capability, otherwise 'capture'
+
+
+.. method:: Mixer.setvolume(volume,[channel], [direction])
+
+   Change the current volume settings for this mixer. The *volume* argument
+   controls the new volume setting as an integer percentage.
+
+   If the optional argument *channel* is present, the volume is set
+   only for this channel. This assumes that the mixer can control the
+   volume for the channels independently.
+
+   The optional *direction* argument can be either 'playback' or 'capture' is
+   relevant if the mixer has independent playback and capture volume
+   capabilities, and controls which of the volumes if changed. The
+   default is 'playback' if the mixer has this capability, otherwise 'capture'.
+
+
+.. method:: Mixer.setmute(mute, [channel])
+
+   Sets the mute flag to a new value. The *mute* argument is either 0 for not
+   muted, or 1 for muted.
+
+   The optional *channel* argument controls which channel is
+   muted. The default is to set the mute flag for all channels.
+
+   This method will fail if the mixer has no playback mute capabilities
+
+
+.. method:: Mixer.setrec(capture,[channel])
+
+   Sets the capture mute flag to a new value. The *capture* argument
+   is either 0 for no capture, or 1 for capture.
+
+   The optional *channel* argument controls which channel is
+   changed. The default is to set the capture flag for all channels.
+
+   This method will fail if the mixer has no capture switch capabilities.
+
+.. method:: Mixer.polldescriptors()
+
+   Returns a tuple of (file descriptor, eventmask) that can be used to
+   wait for changes on the mixer with *select.poll*.
+
+**A rant on the ALSA Mixer API**
+
+The ALSA mixer API is extremely complicated - and hardly documented at all.
+:mod:`alsaaudio` implements a much simplified way to access this API. In
+designing the API I've had to make some choices which may limit what can and
+cannot be controlled through the API. However, If I had chosen to implement the
+full API, I would have reexposed the horrible complexity/documentation ratio of
+the underlying API.  At least the :mod:`alsaaudio` API is easy to
+understand and use.
+
+If my design choises prevents you from doing something that the underlying API
+would have allowed, please let me know, so I can incorporate these needs into
+future versions.
+
+If the current state of affairs annoys you, the best you can do is to write a
+HOWTO on the API and make this available on the net. Until somebody does this,
+the availability of ALSA mixer capable devices will stay quite limited.
+
+Unfortunately, I'm not able to create such a HOWTO myself, since I only
+understand half of the API, and that which I do understand has come from a
+painful trial and error process.
+
+.. % ==== 4. ====
+
+
+.. _pcm-example:
+
+Examples
+--------
+
+The following example are provided:
+
+* playwav.py
+* recordtest.py
+* playbacktest.py
+* mixertest.py
+
+All examples (except mixertest.py) accept the commandline option 
+*-c <cardname>*.
+
+To determine a valid card name, use the commandline ALSA player::
+
+   $ aplay -L
+
+or::
+
+   $ python
+
+   >>> import alsaaudio
+   >>> alsaaudio.cards()
+
+mixertest.py accepts the commandline option *-c <cardindex>*. Card 
+indices start at 0.
+
+playwav.py
+~~~~~~~~~~
+
+**playwav.py** plays a wav file. 
+
+To test PCM playback (on your default soundcard), run::
+
+   $ python playwav.py <wav file>
+
+recordtest.py and playbacktest.py
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+**recordtest.py** and **playbacktest.py** will record and play a raw
+sound file in CD quality.
+
+To test PCM recordings (on your default soundcard), run::
+
+   $ python recordtest.py <filename>
+
+Speak into the microphone, and interrupt the recording at any time
+with ``Ctl-C``.
+
+Play back the recording with::
+
+   $ python playbacktest.py <filename>
+
+mixertest.py
+~~~~~~~~~~~~
+
+Without arguments, **mixertest.py** will list all available *controls*. 
+The output might look like this::
+   
+   $ ./mixertest.py
+   Available mixer controls:
+     'Master'
+     'Master Mono'
+     'Headphone'
+     'PCM'
+     'Line'
+     'Line In->Rear Out'
+     'CD'
+     'Mic'
+     'PC Speaker'
+     'Aux'
+     'Mono Output Select'
+     'Capture'
+     'Mix'
+     'Mix Mono'
+
+With a single argument - the *control*, it will display the settings of 
+that control; for example::
+
+   $ ./mixertest.py Master
+   Mixer name: 'Master'
+   Capabilities: Playback Volume Playback Mute
+   Channel 0 volume: 61%
+   Channel 1 volume: 61%
+
+With two arguments, the *control* and a *parameter*, it will set the 
+parameter on the mixer::
+
+   $ ./mixertest.py Master mute
+
+This will mute the Master mixer.
+
+Or::
+
+   $ ./mixertest.py Master 40
+
+This sets the volume to 40% on all channels.
+
+.. rubric:: Footnotes
+
+.. [#f1]   ALSA also allows ``PCM_ASYNC``, but this is not supported yet.
+.. [#f2] :mod:`alsaaudio` will leave any name alone that has a ':' (colon) in it.
+.. [#f3] This is inconsistent with the PCM objects, which use names, but it is consistent with aplay and amixer.

_sources/pyalsaaudio.txt

@@ -0,0 +1,134 @@
+************
+Introduction
+************
+
+:Author: Casper Wilstrup
+:Author: Lars Immisch
+
+.. |release| replace:: 0.4
+
+.. % At minimum, give your name and an email address.  You can include a
+.. % snail-mail address if you like.
+
+.. % This makes the Abstract go on a separate page in the HTML version;
+.. % if a copyright notice is used, it should go immediately after this.
+.. % 
+
+
+.. _front:
+
+This software is licensed under the PSF license - the same one used by the
+majority of the python distribution. Basically you can use it for anything you
+wish (even commercial purposes). There is no warranty whatsoever.
+
+.. % Copyright statement should go here, if needed.
+
+.. % The abstract should be a paragraph or two long, and describe the
+.. % scope of the document.
+
+
+.. topic:: Abstract
+
+   This package contains wrappers for accessing the ALSA API from Python. It is
+   currently fairly complete for PCM devices and Mixer access. MIDI sequencer
+   support is low on our priority list, but volunteers are welcome.
+
+   If you find bugs in the wrappers please use the SourceForge bug tracker. 
+   Please don't send bug reports regarding ALSA specifically. There are several
+   bugs in this API, and those should be reported to the ALSA team - not me.
+
+
+************
+What is ALSA
+************
+
+The Advanced Linux Sound Architecture (ALSA) provides audio and MIDI
+functionality to the Linux operating system.
+
+Logically ALSA consists of these components:
+
+* A set of kernel drivers. ---  These drivers are responsible for handling the
+  physical sound  hardware from within the Linux kernel, and have been the
+  standard sound implementation in Linux since kernel version 2.5
+
+* A kernel level API for manipulating the ALSA devices.
+
+* A user-space C library for simplified access to the sound hardware from
+  userspace applications. This library is called *libasound* and is required by
+  all ALSA capable applications.
+
+More information about ALSA may be found on the project homepage
+`<http://www.alsa-project.org>`_
+
+
+ALSA and Python
+===============
+
+The older Linux sound API (OSS) which is now deprecated is well supported from
+the standard Python library, through the ossaudiodev module. No native ALSA
+support exists in the standard library.
+
+There are a few other "ALSA for Python" projects available, including at least
+two different projects called pyAlsa. Neither of these seem to be under active
+development at the time - and neither are very feature complete.
+
+I wrote PyAlsaAudio to fill this gap. My long term goal is to have the module
+included in the standard Python library, but that looks currently unlikely.
+
+PyAlsaAudio hass full support for sound capture, playback of sound, as well as
+the ALSA Mixer API.
+
+MIDI support is not available, and since I don't own any MIDI hardware, it's
+difficult for me to implement it. Volunteers to work on this would be greatly
+appreciated.
+
+
+************
+Installation
+************
+
+Note: the wrappers link with the alsasound library (from the alsa-lib package)
+and need the ALSA headers for compilation.  Verify that you have
+/usr/lib/libasound.so and /usr/include/alsa (or similar paths) before building.
+
+*On Debian (and probably Ubuntu), install libasound2-dev.*
+
+Naturally you also need to use a kernel with proper ALSA support. This is the
+default in Linux kernel 2.6 and later. If you are using kernel version 2.4 you
+may need to install the ALSA patches yourself - although most distributions 
+ship with ALSA kernels.
+
+To install, execute the following:  ---   ::
+
+   $ python setup.py build
+
+And then as root:  ---   ::
+
+   # python setup.py install
+
+*******
+Testing
+*******
+
+First of all, run::
+   
+   $ python test.py
+
+This is a small test suite that mostly performs consistency tests. If
+it fails, please file a `bug report
+<http://sourceforge.net/tracker/?group_id=120651>`_.
+
+To test PCM recordings (on your default soundcard), verify your
+microphone works, then do::
+
+   $ python recordtest.py <filename>
+
+Speak into the microphone, and interrupt the recording at any time
+with ``Ctl-C``.
+
+Play back the recording with::
+
+   $ python playbacktest.py <filename>
+
+
+

_sources/terminology.txt

@@ -0,0 +1,75 @@
+****************************
+PCM Terminology and Concepts
+****************************
+
+In order to use PCM devices it is useful to be familiar with some concepts and
+terminology.
+
+Sample
+   PCM audio, whether it is input or output, consists of *samples*. 
+   A single sample represents the amplitude of one channel of sound
+   at a certain point in time. A lot of individual samples are
+   necessary to represent actual sound; for CD audio, 44100 samples
+   are taken every second.
+
+   Samples can be of many different sizes, ranging from 8 bit to 64
+   bit precision. The specific format of each sample can also vary -
+   they can be big endian byte integers, little endian byte integers, or
+   floating point numbers.
+
+   Musically, the sample size determines the dynamic range. The
+   dynamic range is the difference between the quietest and the
+   loudest signal that can be resproduced.
+
+Frame
+   A frame consists of exactly one sample per channel. If there is only one 
+   channel (Mono sound) a frame is simply a single sample. If the sound is 
+   stereo, each frame consists of two samples, etc.
+
+Frame size
+   This is the size in bytes of each frame. This can vary a lot: if each sample
+    is 8 bits, and we're handling mono sound, the frame size is one byte. 
+	Similarly in 6 channel audio with 64 bit floating point samples, the frame 
+	size is 48 bytes
+
+Rate
+   PCM sound consists of a flow of sound frames. The sound rate controls how 
+   often the current frame is replaced. For example, a rate of 8000 Hz
+   means that a new frame is played or captured 8000 times per second.
+
+Data rate
+   This is the number of bytes, which must be recorded or provided per
+   second at a certain frame size and rate.
+
+   8000 Hz mono sound with 8 bit (1 byte) samples has a data rate of
+   8000  \* 1 \* 1 = 8 kb/s or 64kbit/s. This is typically used for telephony.
+
+   At the other end of the scale, 96000 Hz, 6 channel sound with 64
+   bit (8 bytes) samples has a data rate of 96000 \* 6 \* 8 = 4608
+   kb/s (almost 5 Mb sound data per second)
+
+Period
+   When the hardware processes data this is done in chunks of frames. The time
+   interval between each processing (A/D or D/A conversion) is known
+   as the period.
+   The size of the period has direct implication on the latency of the
+   sound input or output. For low-latency the period size should be
+   very small, while low CPU resource usage would usually demand
+   larger period sizes. With ALSA, the CPU utilization is not impacted
+   much by the period size, since the kernel layer buffers multiple
+   periods internally, so each period generates an interrupt and a
+   memory copy, but userspace can be slower and read or write multiple
+   periods at the same time.
+
+Period size
+   This is the size of each period in Hz. *Not bytes, but Hz!.* In 
+   :mod:`alsaaudio` the period size is set directly, and it is
+   therefore important to understand the significance of this
+   number. If the period size is configured to for example 32,
+   each write should contain exactly 32 frames of sound data, and each
+   read will return either 32 frames of data or nothing at all.
+
+Once you understand these concepts, you will be ready to use the PCM API. Read
+on.
+
+

_static/basic.css

@@ -0,0 +1,540 @@
+/*
+ * basic.css
+ * ~~~~~~~~~
+ *
+ * Sphinx stylesheet -- basic theme.
+ *
+ * :copyright: Copyright 2007-2011 by the Sphinx team, see AUTHORS.
+ * :license: BSD, see LICENSE for details.
+ *
+ */
+
+/* -- main layout ----------------------------------------------------------- */
+
+div.clearer {
+    clear: both;
+}
+
+/* -- relbar ---------------------------------------------------------------- */
+
+div.related {
+    width: 100%;
+    font-size: 90%;
+}
+
+div.related h3 {
+    display: none;
+}
+
+div.related ul {
+    margin: 0;
+    padding: 0 0 0 10px;
+    list-style: none;
+}
+
+div.related li {
+    display: inline;
+}
+
+div.related li.right {
+    float: right;
+    margin-right: 5px;
+}
+
+/* -- sidebar --------------------------------------------------------------- */
+
+div.sphinxsidebarwrapper {
+    padding: 10px 5px 0 10px;
+}
+
+div.sphinxsidebar {
+    float: left;
+    width: 230px;
+    margin-left: -100%;
+    font-size: 90%;
+}
+
+div.sphinxsidebar ul {
+    list-style: none;
+}
+
+div.sphinxsidebar ul ul,
+div.sphinxsidebar ul.want-points {
+    margin-left: 20px;
+    list-style: square;
+}
+
+div.sphinxsidebar ul ul {
+    margin-top: 0;
+    margin-bottom: 0;
+}
+
+div.sphinxsidebar form {
+    margin-top: 10px;
+}
+
+div.sphinxsidebar input {
+    border: 1px solid #98dbcc;
+    font-family: sans-serif;
+    font-size: 1em;
+}
+
+div.sphinxsidebar #searchbox input[type="text"] {
+    width: 170px;
+}
+
+div.sphinxsidebar #searchbox input[type="submit"] {
+    width: 30px;
+}
+
+img {
+    border: 0;
+}
+
+/* -- search page ----------------------------------------------------------- */
+
+ul.search {
+    margin: 10px 0 0 20px;
+    padding: 0;
+}
+
+ul.search li {
+    padding: 5px 0 5px 20px;
+    background-image: url(file.png);
+    background-repeat: no-repeat;
+    background-position: 0 7px;
+}
+
+ul.search li a {
+    font-weight: bold;
+}
+
+ul.search li div.context {
+    color: #888;
+    margin: 2px 0 0 30px;
+    text-align: left;
+}
+
+ul.keywordmatches li.goodmatch a {
+    font-weight: bold;
+}
+
+/* -- index page ------------------------------------------------------------ */
+
+table.contentstable {
+    width: 90%;
+}
+
+table.contentstable p.biglink {
+    line-height: 150%;
+}
+
+a.biglink {
+    font-size: 1.3em;
+}
+
+span.linkdescr {
+    font-style: italic;
+    padding-top: 5px;
+    font-size: 90%;
+}
+
+/* -- general index --------------------------------------------------------- */
+
+table.indextable {
+    width: 100%;
+}
+
+table.indextable td {
+    text-align: left;
+    vertical-align: top;
+}
+
+table.indextable dl, table.indextable dd {
+    margin-top: 0;
+    margin-bottom: 0;
+}
+
+table.indextable tr.pcap {
+    height: 10px;
+}
+
+table.indextable tr.cap {
+    margin-top: 10px;
+    background-color: #f2f2f2;
+}
+
+img.toggler {
+    margin-right: 3px;
+    margin-top: 3px;
+    cursor: pointer;
+}
+
+div.modindex-jumpbox {
+    border-top: 1px solid #ddd;
+    border-bottom: 1px solid #ddd;
+    margin: 1em 0 1em 0;
+    padding: 0.4em;
+}
+
+div.genindex-jumpbox {
+    border-top: 1px solid #ddd;
+    border-bottom: 1px solid #ddd;
+    margin: 1em 0 1em 0;
+    padding: 0.4em;
+}
+
+/* -- general body styles --------------------------------------------------- */
+
+a.headerlink {
+    visibility: hidden;
+}
+
+h1:hover > a.headerlink,
+h2:hover > a.headerlink,
+h3:hover > a.headerlink,
+h4:hover > a.headerlink,
+h5:hover > a.headerlink,
+h6:hover > a.headerlink,
+dt:hover > a.headerlink {
+    visibility: visible;
+}
+
+div.body p.caption {
+    text-align: inherit;
+}
+
+div.body td {
+    text-align: left;
+}
+
+.field-list ul {
+    padding-left: 1em;
+}
+
+.first {
+    margin-top: 0 !important;
+}
+
+p.rubric {
+    margin-top: 30px;
+    font-weight: bold;
+}
+
+img.align-left, .figure.align-left, object.align-left {
+    clear: left;
+    float: left;
+    margin-right: 1em;
+}
+
+img.align-right, .figure.align-right, object.align-right {
+    clear: right;
+    float: right;
+    margin-left: 1em;
+}
+
+img.align-center, .figure.align-center, object.align-center {
+  display: block;
+  margin-left: auto;
+  margin-right: auto;
+}
+
+.align-left {
+    text-align: left;
+}
+
+.align-center {
+    text-align: center;
+}
+
+.align-right {
+    text-align: right;
+}
+
+/* -- sidebars -------------------------------------------------------------- */
+
+div.sidebar {
+    margin: 0 0 0.5em 1em;
+    border: 1px solid #ddb;
+    padding: 7px 7px 0 7px;
+    background-color: #ffe;
+    width: 40%;
+    float: right;
+}
+
+p.sidebar-title {
+    font-weight: bold;
+}
+
+/* -- topics ---------------------------------------------------------------- */
+
+div.topic {
+    border: 1px solid #ccc;
+    padding: 7px 7px 0 7px;
+    margin: 10px 0 10px 0;
+}
+
+p.topic-title {
+    font-size: 1.1em;
+    font-weight: bold;
+    margin-top: 10px;
+}
+
+/* -- admonitions ----------------------------------------------------------- */
+
+div.admonition {
+    margin-top: 10px;
+    margin-bottom: 10px;
+    padding: 7px;
+}
+
+div.admonition dt {
+    font-weight: bold;
+}
+
+div.admonition dl {
+    margin-bottom: 0;
+}
+
+p.admonition-title {
+    margin: 0px 10px 5px 0px;
+    font-weight: bold;
+}
+
+div.body p.centered {
+    text-align: center;
+    margin-top: 25px;
+}
+
+/* -- tables ---------------------------------------------------------------- */
+
+table.docutils {
+    border: 0;
+    border-collapse: collapse;
+}
+
+table.docutils td, table.docutils th {
+    padding: 1px 8px 1px 5px;
+    border-top: 0;
+    border-left: 0;
+    border-right: 0;
+    border-bottom: 1px solid #aaa;
+}
+
+table.field-list td, table.field-list th {
+    border: 0 !important;
+}
+
+table.footnote td, table.footnote th {
+    border: 0 !important;
+}
+
+th {
+    text-align: left;
+    padding-right: 5px;
+}
+
+table.citation {
+    border-left: solid 1px gray;
+    margin-left: 1px;
+}
+
+table.citation td {
+    border-bottom: none;
+}
+
+/* -- other body styles ----------------------------------------------------- */
+
+ol.arabic {
+    list-style: decimal;
+}
+
+ol.loweralpha {
+    list-style: lower-alpha;
+}
+
+ol.upperalpha {
+    list-style: upper-alpha;
+}
+
+ol.lowerroman {
+    list-style: lower-roman;
+}
+
+ol.upperroman {
+    list-style: upper-roman;
+}
+
+dl {
+    margin-bottom: 15px;
+}
+
+dd p {
+    margin-top: 0px;
+}
+
+dd ul, dd table {
+    margin-bottom: 10px;
+}
+
+dd {
+    margin-top: 3px;
+    margin-bottom: 10px;
+    margin-left: 30px;
+}
+
+dt:target, .highlighted {
+    background-color: #fbe54e;
+}
+
+dl.glossary dt {
+    font-weight: bold;
+    font-size: 1.1em;
+}
+
+.field-list ul {
+    margin: 0;
+    padding-left: 1em;
+}
+
+.field-list p {
+    margin: 0;
+}
+
+.refcount {
+    color: #060;
+}
+
+.optional {
+    font-size: 1.3em;
+}
+
+.versionmodified {
+    font-style: italic;
+}
+
+.system-message {
+    background-color: #fda;
+    padding: 5px;
+    border: 3px solid red;
+}
+
+.footnote:target  {
+    background-color: #ffa;
+}
+
+.line-block {
+    display: block;
+    margin-top: 1em;
+    margin-bottom: 1em;
+}
+
+.line-block .line-block {
+    margin-top: 0;
+    margin-bottom: 0;
+    margin-left: 1.5em;
+}
+
+.guilabel, .menuselection {
+    font-family: sans-serif;
+}
+
+.accelerator {
+    text-decoration: underline;
+}
+
+.classifier {
+    font-style: oblique;
+}
+
+abbr, acronym {
+    border-bottom: dotted 1px;
+    cursor: help;
+}
+
+/* -- code displays --------------------------------------------------------- */
+
+pre {
+    overflow: auto;
+    overflow-y: hidden;  /* fixes display issues on Chrome browsers */
+}
+
+td.linenos pre {
+    padding: 5px 0px;
+    border: 0;
+    background-color: transparent;
+    color: #aaa;
+}
+
+table.highlighttable {
+    margin-left: 0.5em;
+}
+
+table.highlighttable td {
+    padding: 0 0.5em 0 0.5em;
+}
+
+tt.descname {
+    background-color: transparent;
+    font-weight: bold;
+    font-size: 1.2em;
+}
+
+tt.descclassname {
+    background-color: transparent;
+}
+
+tt.xref, a tt {
+    background-color: transparent;
+    font-weight: bold;
+}
+
+h1 tt, h2 tt, h3 tt, h4 tt, h5 tt, h6 tt {
+    background-color: transparent;
+}
+
+.viewcode-link {
+    float: right;
+}
+
+.viewcode-back {
+    float: right;
+    font-family: sans-serif;
+}
+
+div.viewcode-block:target {
+    margin: -1px -10px;
+    padding: 0 10px;
+}
+
+/* -- math display ---------------------------------------------------------- */
+
+img.math {
+    vertical-align: middle;
+}
+
+div.body div.math p {
+    text-align: center;
+}
+
+span.eqno {
+    float: right;
+}
+
+/* -- printout stylesheet --------------------------------------------------- */
+
+@media print {
+    div.document,
+    div.documentwrapper,
+    div.bodywrapper {
+        margin: 0 !important;
+        width: 100%;
+    }
+
+    div.sphinxsidebar,
+    div.related,
+    div.footer,
+    #top-link {
+        display: none;
+    }
+}

_static/default.css

@@ -0,0 +1,256 @@
+/*
+ * default.css_t
+ * ~~~~~~~~~~~~~
+ *
+ * Sphinx stylesheet -- default theme.
+ *
+ * :copyright: Copyright 2007-2011 by the Sphinx team, see AUTHORS.
+ * :license: BSD, see LICENSE for details.
+ *
+ */
+
+@import url("basic.css");
+
+/* -- page layout ----------------------------------------------------------- */
+
+body {
+    font-family: sans-serif;
+    font-size: 100%;
+    background-color: #11303d;
+    color: #000;
+    margin: 0;
+    padding: 0;
+}
+
+div.document {
+    background-color: #1c4e63;
+}
+
+div.documentwrapper {
+    float: left;
+    width: 100%;
+}
+
+div.bodywrapper {
+    margin: 0 0 0 230px;
+}
+
+div.body {
+    background-color: #ffffff;
+    color: #000000;
+    padding: 0 20px 30px 20px;
+}
+
+div.footer {
+    color: #ffffff;
+    width: 100%;
+    padding: 9px 0 9px 0;
+    text-align: center;
+    font-size: 75%;
+}
+
+div.footer a {
+    color: #ffffff;
+    text-decoration: underline;
+}
+
+div.related {
+    background-color: #133f52;
+    line-height: 30px;
+    color: #ffffff;
+}
+
+div.related a {
+    color: #ffffff;
+}
+
+div.sphinxsidebar {
+}
+
+div.sphinxsidebar h3 {
+    font-family: 'Trebuchet MS', sans-serif;
+    color: #ffffff;
+    font-size: 1.4em;
+    font-weight: normal;
+    margin: 0;
+    padding: 0;
+}
+
+div.sphinxsidebar h3 a {
+    color: #ffffff;
+}
+
+div.sphinxsidebar h4 {
+    font-family: 'Trebuchet MS', sans-serif;
+    color: #ffffff;
+    font-size: 1.3em;
+    font-weight: normal;
+    margin: 5px 0 0 0;
+    padding: 0;
+}
+
+div.sphinxsidebar p {
+    color: #ffffff;
+}
+
+div.sphinxsidebar p.topless {
+    margin: 5px 10px 10px 10px;
+}
+
+div.sphinxsidebar ul {
+    margin: 10px;
+    padding: 0;
+    color: #ffffff;
+}
+
+div.sphinxsidebar a {
+    color: #98dbcc;
+}
+
+div.sphinxsidebar input {
+    border: 1px solid #98dbcc;
+    font-family: sans-serif;
+    font-size: 1em;
+}
+
+
+
+/* -- hyperlink styles ------------------------------------------------------ */
+
+a {
+    color: #355f7c;
+    text-decoration: none;
+}
+
+a:visited {
+    color: #355f7c;
+    text-decoration: none;
+}
+
+a:hover {
+    text-decoration: underline;
+}
+
+
+
+/* -- body styles ----------------------------------------------------------- */
+
+div.body h1,
+div.body h2,
+div.body h3,
+div.body h4,
+div.body h5,
+div.body h6 {
+    font-family: 'Trebuchet MS', sans-serif;
+    background-color: #f2f2f2;
+    font-weight: normal;
+    color: #20435c;
+    border-bottom: 1px solid #ccc;
+    margin: 20px -20px 10px -20px;
+    padding: 3px 0 3px 10px;
+}
+
+div.body h1 { margin-top: 0; font-size: 200%; }
+div.body h2 { font-size: 160%; }
+div.body h3 { font-size: 140%; }
+div.body h4 { font-size: 120%; }
+div.body h5 { font-size: 110%; }
+div.body h6 { font-size: 100%; }
+
+a.headerlink {
+    color: #c60f0f;
+    font-size: 0.8em;
+    padding: 0 4px 0 4px;
+    text-decoration: none;
+}
+
+a.headerlink:hover {
+    background-color: #c60f0f;
+    color: white;
+}
+
+div.body p, div.body dd, div.body li {
+    text-align: justify;
+    line-height: 130%;
+}
+
+div.admonition p.admonition-title + p {
+    display: inline;
+}
+
+div.admonition p {
+    margin-bottom: 5px;
+}
+
+div.admonition pre {
+    margin-bottom: 5px;
+}
+
+div.admonition ul, div.admonition ol {
+    margin-bottom: 5px;
+}
+
+div.note {
+    background-color: #eee;
+    border: 1px solid #ccc;
+}
+
+div.seealso {
+    background-color: #ffc;
+    border: 1px solid #ff6;
+}
+
+div.topic {
+    background-color: #eee;
+}
+
+div.warning {
+    background-color: #ffe4e4;
+    border: 1px solid #f66;
+}
+
+p.admonition-title {
+    display: inline;
+}
+
+p.admonition-title:after {
+    content: ":";
+}
+
+pre {
+    padding: 5px;
+    background-color: #eeffcc;
+    color: #333333;
+    line-height: 120%;
+    border: 1px solid #ac9;
+    border-left: none;
+    border-right: none;
+}
+
+tt {
+    background-color: #ecf0f3;
+    padding: 0 1px 0 1px;
+    font-size: 0.95em;
+}
+
+th {
+    background-color: #ede;
+}
+
+.warning tt {
+    background: #efc2c2;
+}
+
+.note tt {
+    background: #d6d6d6;
+}
+
+.viewcode-back {
+    font-family: sans-serif;
+}
+
+div.viewcode-block:target {
+    background-color: #f4debf;
+    border-top: 1px solid #ac9;
+    border-bottom: 1px solid #ac9;
+}

_static/doctools.js

@@ -0,0 +1,247 @@
+/*
+ * doctools.js
+ * ~~~~~~~~~~~
+ *
+ * Sphinx JavaScript utilities for all documentation.
+ *
+ * :copyright: Copyright 2007-2011 by the Sphinx team, see AUTHORS.
+ * :license: BSD, see LICENSE for details.
+ *
+ */
+
+/**
+ * select a different prefix for underscore
+ */
+$u = _.noConflict();
+
+/**
+ * make the code below compatible with browsers without
+ * an installed firebug like debugger
+if (!window.console || !console.firebug) {
+  var names = ["log", "debug", "info", "warn", "error", "assert", "dir",
+    "dirxml", "group", "groupEnd", "time", "timeEnd", "count", "trace",
+    "profile", "profileEnd"];
+  window.console = {};
+  for (var i = 0; i < names.length; ++i)
+    window.console[names[i]] = function() {};
+}
+ */
+
+/**
+ * small helper function to urldecode strings
+ */
+jQuery.urldecode = function(x) {
+  return decodeURIComponent(x).replace(/\+/g, ' ');
+}
+
+/**
+ * small helper function to urlencode strings
+ */
+jQuery.urlencode = encodeURIComponent;
+
+/**
+ * This function returns the parsed url parameters of the
+ * current request. Multiple values per key are supported,
+ * it will always return arrays of strings for the value parts.
+ */
+jQuery.getQueryParameters = function(s) {
+  if (typeof s == 'undefined')
+    s = document.location.search;
+  var parts = s.substr(s.indexOf('?') + 1).split('&');
+  var result = {};
+  for (var i = 0; i < parts.length; i++) {
+    var tmp = parts[i].split('=', 2);
+    var key = jQuery.urldecode(tmp[0]);
+    var value = jQuery.urldecode(tmp[1]);
+    if (key in result)
+      result[key].push(value);
+    else
+      result[key] = [value];
+  }
+  return result;
+};
+
+/**
+ * small function to check if an array contains
+ * a given item.
+ */
+jQuery.contains = function(arr, item) {
+  for (var i = 0; i < arr.length; i++) {
+    if (arr[i] == item)
+      return true;
+  }
+  return false;
+};
+
+/**
+ * highlight a given string on a jquery object by wrapping it in
+ * span elements with the given class name.
+ */
+jQuery.fn.highlightText = function(text, className) {
+  function highlight(node) {
+    if (node.nodeType == 3) {
+      var val = node.nodeValue;
+      var pos = val.toLowerCase().indexOf(text);
+      if (pos >= 0 && !jQuery(node.parentNode).hasClass(className)) {
+        var span = document.createElement("span");
+        span.className = className;
+        span.appendChild(document.createTextNode(val.substr(pos, text.length)));
+        node.parentNode.insertBefore(span, node.parentNode.insertBefore(
+          document.createTextNode(val.substr(pos + text.length)),
+          node.nextSibling));
+        node.nodeValue = val.substr(0, pos);
+      }
+    }
+    else if (!jQuery(node).is("button, select, textarea")) {
+      jQuery.each(node.childNodes, function() {
+        highlight(this);
+      });
+    }
+  }
+  return this.each(function() {
+    highlight(this);
+  });
+};
+
+/**
+ * Small JavaScript module for the documentation.
+ */
+var Documentation = {
+
+  init : function() {
+    this.fixFirefoxAnchorBug();
+    this.highlightSearchWords();
+    this.initIndexTable();
+  },
+
+  /**
+   * i18n support
+   */
+  TRANSLATIONS : {},
+  PLURAL_EXPR : function(n) { return n == 1 ? 0 : 1; },
+  LOCALE : 'unknown',
+
+  // gettext and ngettext don't access this so that the functions
+  // can safely bound to a different name (_ = Documentation.gettext)
+  gettext : function(string) {
+    var translated = Documentation.TRANSLATIONS[string];
+    if (typeof translated == 'undefined')
+      return string;
+    return (typeof translated == 'string') ? translated : translated[0];
+  },
+
+  ngettext : function(singular, plural, n) {
+    var translated = Documentation.TRANSLATIONS[singular];
+    if (typeof translated == 'undefined')
+      return (n == 1) ? singular : plural;
+    return translated[Documentation.PLURALEXPR(n)];
+  },
+
+  addTranslations : function(catalog) {
+    for (var key in catalog.messages)
+      this.TRANSLATIONS[key] = catalog.messages[key];
+    this.PLURAL_EXPR = new Function('n', 'return +(' + catalog.plural_expr + ')');
+    this.LOCALE = catalog.locale;
+  },
+
+  /**
+   * add context elements like header anchor links
+   */
+  addContextElements : function() {
+    $('div[id] > :header:first').each(function() {
+      $('<a class="headerlink">\u00B6</a>').
+      attr('href', '#' + this.id).
+      attr('title', _('Permalink to this headline')).
+      appendTo(this);
+    });
+    $('dt[id]').each(function() {
+      $('<a class="headerlink">\u00B6</a>').
+      attr('href', '#' + this.id).
+      attr('title', _('Permalink to this definition')).
+      appendTo(this);
+    });
+  },
+
+  /**
+   * workaround a firefox stupidity
+   */
+  fixFirefoxAnchorBug : function() {
+    if (document.location.hash && $.browser.mozilla)
+      window.setTimeout(function() {
+        document.location.href += '';
+      }, 10);
+  },
+
+  /**
+   * highlight the search words provided in the url in the text
+   */
+  highlightSearchWords : function() {
+    var params = $.getQueryParameters();
+    var terms = (params.highlight) ? params.highlight[0].split(/\s+/) : [];
+    if (terms.length) {
+      var body = $('div.body');
+      window.setTimeout(function() {
+        $.each(terms, function() {
+          body.highlightText(this.toLowerCase(), 'highlighted');
+        });
+      }, 10);
+      $('<p class="highlight-link"><a href="javascript:Documentation.' +
+        'hideSearchWords()">' + _('Hide Search Matches') + '</a></p>')
+          .appendTo($('#searchbox'));
+    }
+  },
+
+  /**
+   * init the domain index toggle buttons
+   */
+  initIndexTable : function() {
+    var togglers = $('img.toggler').click(function() {
+      var src = $(this).attr('src');
+      var idnum = $(this).attr('id').substr(7);
+      $('tr.cg-' + idnum).toggle();
+      if (src.substr(-9) == 'minus.png')
+        $(this).attr('src', src.substr(0, src.length-9) + 'plus.png');
+      else
+        $(this).attr('src', src.substr(0, src.length-8) + 'minus.png');
+    }).css('display', '');
+    if (DOCUMENTATION_OPTIONS.COLLAPSE_INDEX) {
+        togglers.click();
+    }
+  },
+
+  /**
+   * helper function to hide the search marks again
+   */
+  hideSearchWords : function() {
+    $('#searchbox .highlight-link').fadeOut(300);
+    $('span.highlighted').removeClass('highlighted');
+  },
+
+  /**
+   * make the url absolute
+   */
+  makeURL : function(relativeURL) {
+    return DOCUMENTATION_OPTIONS.URL_ROOT + '/' + relativeURL;
+  },
+
+  /**
+   * get the current relative url
+   */
+  getCurrentURL : function() {
+    var path = document.location.pathname;
+    var parts = path.split(/\//);
+    $.each(DOCUMENTATION_OPTIONS.URL_ROOT.split(/\//), function() {
+      if (this == '..')
+        parts.pop();
+    });
+    var url = parts.join('/');
+    return path.substring(url.lastIndexOf('/') + 1, path.length - 1);
+  }
+};
+
+// quick alias for translations
+_ = Documentation.gettext;
+
+$(document).ready(function() {
+  Documentation.init();
+});

_static/pygments.css

@@ -0,0 +1,62 @@
+.highlight .hll { background-color: #ffffcc }
+.highlight  { background: #eeffcc; }
+.highlight .c { color: #408090; font-style: italic } /* Comment */
+.highlight .err { border: 1px solid #FF0000 } /* Error */
+.highlight .k { color: #007020; font-weight: bold } /* Keyword */
+.highlight .o { color: #666666 } /* Operator */
+.highlight .cm { color: #408090; font-style: italic } /* Comment.Multiline */
+.highlight .cp { color: #007020 } /* Comment.Preproc */
+.highlight .c1 { color: #408090; font-style: italic } /* Comment.Single */
+.highlight .cs { color: #408090; background-color: #fff0f0 } /* Comment.Special */
+.highlight .gd { color: #A00000 } /* Generic.Deleted */
+.highlight .ge { font-style: italic } /* Generic.Emph */
+.highlight .gr { color: #FF0000 } /* Generic.Error */
+.highlight .gh { color: #000080; font-weight: bold } /* Generic.Heading */
+.highlight .gi { color: #00A000 } /* Generic.Inserted */
+.highlight .go { color: #303030 } /* Generic.Output */
+.highlight .gp { color: #c65d09; font-weight: bold } /* Generic.Prompt */
+.highlight .gs { font-weight: bold } /* Generic.Strong */
+.highlight .gu { color: #800080; font-weight: bold } /* Generic.Subheading */
+.highlight .gt { color: #0040D0 } /* Generic.Traceback */
+.highlight .kc { color: #007020; font-weight: bold } /* Keyword.Constant */
+.highlight .kd { color: #007020; font-weight: bold } /* Keyword.Declaration */
+.highlight .kn { color: #007020; font-weight: bold } /* Keyword.Namespace */
+.highlight .kp { color: #007020 } /* Keyword.Pseudo */
+.highlight .kr { color: #007020; font-weight: bold } /* Keyword.Reserved */
+.highlight .kt { color: #902000 } /* Keyword.Type */
+.highlight .m { color: #208050 } /* Literal.Number */
+.highlight .s { color: #4070a0 } /* Literal.String */
+.highlight .na { color: #4070a0 } /* Name.Attribute */
+.highlight .nb { color: #007020 } /* Name.Builtin */
+.highlight .nc { color: #0e84b5; font-weight: bold } /* Name.Class */
+.highlight .no { color: #60add5 } /* Name.Constant */
+.highlight .nd { color: #555555; font-weight: bold } /* Name.Decorator */
+.highlight .ni { color: #d55537; font-weight: bold } /* Name.Entity */
+.highlight .ne { color: #007020 } /* Name.Exception */
+.highlight .nf { color: #06287e } /* Name.Function */
+.highlight .nl { color: #002070; font-weight: bold } /* Name.Label */
+.highlight .nn { color: #0e84b5; font-weight: bold } /* Name.Namespace */
+.highlight .nt { color: #062873; font-weight: bold } /* Name.Tag */
+.highlight .nv { color: #bb60d5 } /* Name.Variable */
+.highlight .ow { color: #007020; font-weight: bold } /* Operator.Word */
+.highlight .w { color: #bbbbbb } /* Text.Whitespace */
+.highlight .mf { color: #208050 } /* Literal.Number.Float */
+.highlight .mh { color: #208050 } /* Literal.Number.Hex */
+.highlight .mi { color: #208050 } /* Literal.Number.Integer */
+.highlight .mo { color: #208050 } /* Literal.Number.Oct */
+.highlight .sb { color: #4070a0 } /* Literal.String.Backtick */
+.highlight .sc { color: #4070a0 } /* Literal.String.Char */
+.highlight .sd { color: #4070a0; font-style: italic } /* Literal.String.Doc */
+.highlight .s2 { color: #4070a0 } /* Literal.String.Double */
+.highlight .se { color: #4070a0; font-weight: bold } /* Literal.String.Escape */
+.highlight .sh { color: #4070a0 } /* Literal.String.Heredoc */
+.highlight .si { color: #70a0d0; font-style: italic } /* Literal.String.Interpol */
+.highlight .sx { color: #c65d09 } /* Literal.String.Other */
+.highlight .sr { color: #235388 } /* Literal.String.Regex */
+.highlight .s1 { color: #4070a0 } /* Literal.String.Single */
+.highlight .ss { color: #517918 } /* Literal.String.Symbol */
+.highlight .bp { color: #007020 } /* Name.Builtin.Pseudo */
+.highlight .vc { color: #bb60d5 } /* Name.Variable.Class */
+.highlight .vg { color: #bb60d5 } /* Name.Variable.Global */
+.highlight .vi { color: #bb60d5 } /* Name.Variable.Instance */
+.highlight .il { color: #208050 } /* Literal.Number.Integer.Long */

_static/searchtools.js

@@ -0,0 +1,560 @@
+/*
+ * searchtools.js_t
+ * ~~~~~~~~~~~~~~~~
+ *
+ * Sphinx JavaScript utilties for the full-text search.
+ *
+ * :copyright: Copyright 2007-2011 by the Sphinx team, see AUTHORS.
+ * :license: BSD, see LICENSE for details.
+ *
+ */
+
+/**
+ * helper function to return a node containing the
+ * search summary for a given text. keywords is a list
+ * of stemmed words, hlwords is the list of normal, unstemmed
+ * words. the first one is used to find the occurance, the
+ * latter for highlighting it.
+ */
+
+jQuery.makeSearchSummary = function(text, keywords, hlwords) {
+  var textLower = text.toLowerCase();
+  var start = 0;
+  $.each(keywords, function() {
+    var i = textLower.indexOf(this.toLowerCase());
+    if (i > -1)
+      start = i;
+  });
+  start = Math.max(start - 120, 0);
+  var excerpt = ((start > 0) ? '...' : '') +
+  $.trim(text.substr(start, 240)) +
+  ((start + 240 - text.length) ? '...' : '');
+  var rv = $('<div class="context"></div>').text(excerpt);
+  $.each(hlwords, function() {
+    rv = rv.highlightText(this, 'highlighted');
+  });
+  return rv;
+}
+
+
+/**
+ * Porter Stemmer
+ */
+var Stemmer = function() {
+
+  var step2list = {
+    ational: 'ate',
+    tional: 'tion',
+    enci: 'ence',
+    anci: 'ance',
+    izer: 'ize',
+    bli: 'ble',
+    alli: 'al',
+    entli: 'ent',
+    eli: 'e',
+    ousli: 'ous',
+    ization: 'ize',
+    ation: 'ate',
+    ator: 'ate',
+    alism: 'al',
+    iveness: 'ive',
+    fulness: 'ful',
+    ousness: 'ous',
+    aliti: 'al',
+    iviti: 'ive',
+    biliti: 'ble',
+    logi: 'log'
+  };
+
+  var step3list = {
+    icate: 'ic',
+    ative: '',
+    alize: 'al',
+    iciti: 'ic',
+    ical: 'ic',
+    ful: '',
+    ness: ''
+  };
+
+  var c = "[^aeiou]";          // consonant
+  var v = "[aeiouy]";          // vowel
+  var C = c + "[^aeiouy]*";    // consonant sequence
+  var V = v + "[aeiou]*";      // vowel sequence
+
+  var mgr0 = "^(" + C + ")?" + V + C;                      // [C]VC... is m>0
+  var meq1 = "^(" + C + ")?" + V + C + "(" + V + ")?$";    // [C]VC[V] is m=1
+  var mgr1 = "^(" + C + ")?" + V + C + V + C;              // [C]VCVC... is m>1
+  var s_v   = "^(" + C + ")?" + v;                         // vowel in stem
+
+  this.stemWord = function (w) {
+    var stem;
+    var suffix;
+    var firstch;
+    var origword = w;
+
+    if (w.length < 3)
+      return w;
+
+    var re;
+    var re2;
+    var re3;
+    var re4;
+
+    firstch = w.substr(0,1);
+    if (firstch == "y")
+      w = firstch.toUpperCase() + w.substr(1);
+
+    // Step 1a
+    re = /^(.+?)(ss|i)es$/;
+    re2 = /^(.+?)([^s])s$/;
+
+    if (re.test(w))
+      w = w.replace(re,"$1$2");
+    else if (re2.test(w))
+      w = w.replace(re2,"$1$2");
+
+    // Step 1b
+    re = /^(.+?)eed$/;
+    re2 = /^(.+?)(ed|ing)$/;
+    if (re.test(w)) {
+      var fp = re.exec(w);
+      re = new RegExp(mgr0);
+      if (re.test(fp[1])) {
+        re = /.$/;
+        w = w.replace(re,"");
+      }
+    }
+    else if (re2.test(w)) {
+      var fp = re2.exec(w);
+      stem = fp[1];
+      re2 = new RegExp(s_v);
+      if (re2.test(stem)) {
+        w = stem;
+        re2 = /(at|bl|iz)$/;
+        re3 = new RegExp("([^aeiouylsz])\\1$");
+        re4 = new RegExp("^" + C + v + "[^aeiouwxy]$");
+        if (re2.test(w))
+          w = w + "e";
+        else if (re3.test(w)) {
+          re = /.$/;
+          w = w.replace(re,"");
+        }
+        else if (re4.test(w))
+          w = w + "e";
+      }
+    }
+
+    // Step 1c
+    re = /^(.+?)y$/;
+    if (re.test(w)) {
+      var fp = re.exec(w);
+      stem = fp[1];
+      re = new RegExp(s_v);
+      if (re.test(stem))
+        w = stem + "i";
+    }
+
+    // Step 2
+    re = /^(.+?)(ational|tional|enci|anci|izer|bli|alli|entli|eli|ousli|ization|ation|ator|alism|iveness|fulness|ousness|aliti|iviti|biliti|logi)$/;
+    if (re.test(w)) {
+      var fp = re.exec(w);
+      stem = fp[1];
+      suffix = fp[2];
+      re = new RegExp(mgr0);
+      if (re.test(stem))
+        w = stem + step2list[suffix];
+    }
+
+    // Step 3
+    re = /^(.+?)(icate|ative|alize|iciti|ical|ful|ness)$/;
+    if (re.test(w)) {
+      var fp = re.exec(w);
+      stem = fp[1];
+      suffix = fp[2];
+      re = new RegExp(mgr0);
+      if (re.test(stem))
+        w = stem + step3list[suffix];
+    }
+
+    // Step 4
+    re = /^(.+?)(al|ance|ence|er|ic|able|ible|ant|ement|ment|ent|ou|ism|ate|iti|ous|ive|ize)$/;
+    re2 = /^(.+?)(s|t)(ion)$/;
+    if (re.test(w)) {
+      var fp = re.exec(w);
+      stem = fp[1];
+      re = new RegExp(mgr1);
+      if (re.test(stem))
+        w = stem;
+    }
+    else if (re2.test(w)) {
+      var fp = re2.exec(w);
+      stem = fp[1] + fp[2];
+      re2 = new RegExp(mgr1);
+      if (re2.test(stem))
+        w = stem;
+    }
+
+    // Step 5
+    re = /^(.+?)e$/;
+    if (re.test(w)) {
+      var fp = re.exec(w);
+      stem = fp[1];
+      re = new RegExp(mgr1);
+      re2 = new RegExp(meq1);
+      re3 = new RegExp("^" + C + v + "[^aeiouwxy]$");
+      if (re.test(stem) || (re2.test(stem) && !(re3.test(stem))))
+        w = stem;
+    }
+    re = /ll$/;
+    re2 = new RegExp(mgr1);
+    if (re.test(w) && re2.test(w)) {
+      re = /.$/;
+      w = w.replace(re,"");
+    }
+
+    // and turn initial Y back to y
+    if (firstch == "y")
+      w = firstch.toLowerCase() + w.substr(1);
+    return w;
+  }
+}
+
+
+/**
+ * Search Module
+ */
+var Search = {
+
+  _index : null,
+  _queued_query : null,
+  _pulse_status : -1,
+
+  init : function() {
+      var params = $.getQueryParameters();
+      if (params.q) {
+          var query = params.q[0];
+          $('input[name="q"]')[0].value = query;
+          this.performSearch(query);
+      }
+  },
+
+  loadIndex : function(url) {
+    $.ajax({type: "GET", url: url, data: null, success: null,
+            dataType: "script", cache: true});
+  },
+
+  setIndex : function(index) {
+    var q;
+    this._index = index;
+    if ((q = this._queued_query) !== null) {
+      this._queued_query = null;
+      Search.query(q);
+    }
+  },
+
+  hasIndex : function() {
+      return this._index !== null;
+  },
+
+  deferQuery : function(query) {
+      this._queued_query = query;
+  },
+
+  stopPulse : function() {
+      this._pulse_status = 0;
+  },
+
+  startPulse : function() {
+    if (this._pulse_status >= 0)
+        return;
+    function pulse() {
+      Search._pulse_status = (Search._pulse_status + 1) % 4;
+      var dotString = '';
+      for (var i = 0; i < Search._pulse_status; i++)
+        dotString += '.';
+      Search.dots.text(dotString);
+      if (Search._pulse_status > -1)
+        window.setTimeout(pulse, 500);
+    };
+    pulse();
+  },
+
+  /**
+   * perform a search for something
+   */
+  performSearch : function(query) {
+    // create the required interface elements
+    this.out = $('#search-results');
+    this.title = $('<h2>' + _('Searching') + '</h2>').appendTo(this.out);
+    this.dots = $('<span></span>').appendTo(this.title);
+    this.status = $('<p style="display: none"></p>').appendTo(this.out);
+    this.output = $('<ul class="search"/>').appendTo(this.out);
+
+    $('#search-progress').text(_('Preparing search...'));
+    this.startPulse();
+
+    // index already loaded, the browser was quick!
+    if (this.hasIndex())
+      this.query(query);
+    else
+      this.deferQuery(query);
+  },
+
+  query : function(query) {
+    var stopwords = ["and","then","into","it","as","are","in","if","for","no","there","their","was","is","be","to","that","but","they","not","such","with","by","a","on","these","of","will","this","near","the","or","at"];
+
+    // Stem the searchterms and add them to the correct list
+    var stemmer = new Stemmer();
+    var searchterms = [];
+    var excluded = [];
+    var hlterms = [];
+    var tmp = query.split(/\s+/);
+    var objectterms = [];
+    for (var i = 0; i < tmp.length; i++) {
+      if (tmp[i] != "") {
+          objectterms.push(tmp[i].toLowerCase());
+      }
+
+      if ($u.indexOf(stopwords, tmp[i]) != -1 || tmp[i].match(/^\d+$/) ||
+          tmp[i] == "") {
+        // skip this "word"
+        continue;
+      }
+      // stem the word
+      var word = stemmer.stemWord(tmp[i]).toLowerCase();
+      // select the correct list
+      if (word[0] == '-') {
+        var toAppend = excluded;
+        word = word.substr(1);
+      }
+      else {
+        var toAppend = searchterms;
+        hlterms.push(tmp[i].toLowerCase());
+      }
+      // only add if not already in the list
+      if (!$.contains(toAppend, word))
+        toAppend.push(word);
+    };
+    var highlightstring = '?highlight=' + $.urlencode(hlterms.join(" "));
+
+    // console.debug('SEARCH: searching for:');
+    // console.info('required: ', searchterms);
+    // console.info('excluded: ', excluded);
+
+    // prepare search
+    var filenames = this._index.filenames;
+    var titles = this._index.titles;
+    var terms = this._index.terms;
+    var fileMap = {};
+    var files = null;
+    // different result priorities
+    var importantResults = [];
+    var objectResults = [];
+    var regularResults = [];
+    var unimportantResults = [];
+    $('#search-progress').empty();
+
+    // lookup as object
+    for (var i = 0; i < objectterms.length; i++) {
+      var others = [].concat(objectterms.slice(0,i),
+                             objectterms.slice(i+1, objectterms.length))
+      var results = this.performObjectSearch(objectterms[i], others);
+      // Assume first word is most likely to be the object,
+      // other words more likely to be in description.
+      // Therefore put matches for earlier words first.
+      // (Results are eventually used in reverse order).
+      objectResults = results[0].concat(objectResults);
+      importantResults = results[1].concat(importantResults);
+      unimportantResults = results[2].concat(unimportantResults);
+    }
+
+    // perform the search on the required terms
+    for (var i = 0; i < searchterms.length; i++) {
+      var word = searchterms[i];
+      // no match but word was a required one
+      if ((files = terms[word]) == null)
+        break;
+      if (files.length == undefined) {
+        files = [files];
+      }
+      // create the mapping
+      for (var j = 0; j < files.length; j++) {
+        var file = files[j];
+        if (file in fileMap)
+          fileMap[file].push(word);
+        else
+          fileMap[file] = [word];
+      }
+    }
+
+    // now check if the files don't contain excluded terms
+    for (var file in fileMap) {
+      var valid = true;
+
+      // check if all requirements are matched
+      if (fileMap[file].length != searchterms.length)
+        continue;
+
+      // ensure that none of the excluded terms is in the
+      // search result.
+      for (var i = 0; i < excluded.length; i++) {
+        if (terms[excluded[i]] == file ||
+            $.contains(terms[excluded[i]] || [], file)) {
+          valid = false;
+          break;
+        }
+      }
+
+      // if we have still a valid result we can add it
+      // to the result list
+      if (valid)
+        regularResults.push([filenames[file], titles[file], '', null]);
+    }
+
+    // delete unused variables in order to not waste
+    // memory until list is retrieved completely
+    delete filenames, titles, terms;
+
+    // now sort the regular results descending by title
+    regularResults.sort(function(a, b) {
+      var left = a[1].toLowerCase();
+      var right = b[1].toLowerCase();
+      return (left > right) ? -1 : ((left < right) ? 1 : 0);
+    });
+
+    // combine all results
+    var results = unimportantResults.concat(regularResults)
+      .concat(objectResults).concat(importantResults);
+
+    // print the results
+    var resultCount = results.length;
+    function displayNextItem() {
+      // results left, load the summary and display it
+      if (results.length) {
+        var item = results.pop();
+        var listItem = $('<li style="display:none"></li>');
+        if (DOCUMENTATION_OPTIONS.FILE_SUFFIX == '') {
+          // dirhtml builder
+          var dirname = item[0] + '/';
+          if (dirname.match(/\/index\/$/)) {
+            dirname = dirname.substring(0, dirname.length-6);
+          } else if (dirname == 'index/') {
+            dirname = '';
+          }
+          listItem.append($('<a/>').attr('href',
+            DOCUMENTATION_OPTIONS.URL_ROOT + dirname +
+            highlightstring + item[2]).html(item[1]));
+        } else {
+          // normal html builders
+          listItem.append($('<a/>').attr('href',
+            item[0] + DOCUMENTATION_OPTIONS.FILE_SUFFIX +
+            highlightstring + item[2]).html(item[1]));
+        }
+        if (item[3]) {
+          listItem.append($('<span> (' + item[3] + ')</span>'));
+          Search.output.append(listItem);
+          listItem.slideDown(5, function() {
+            displayNextItem();
+          });
+        } else if (DOCUMENTATION_OPTIONS.HAS_SOURCE) {
+          $.get(DOCUMENTATION_OPTIONS.URL_ROOT + '_sources/' +
+                item[0] + '.txt', function(data) {
+            if (data != '') {
+              listItem.append($.makeSearchSummary(data, searchterms, hlterms));
+              Search.output.append(listItem);
+            }
+            listItem.slideDown(5, function() {
+              displayNextItem();
+            });
+          }, "text");
+        } else {
+          // no source available, just display title
+          Search.output.append(listItem);
+          listItem.slideDown(5, function() {
+            displayNextItem();
+          });
+        }
+      }
+      // search finished, update title and status message
+      else {
+        Search.stopPulse();
+        Search.title.text(_('Search Results'));
+        if (!resultCount)
+          Search.status.text(_('Your search did not match any documents. Please make sure that all words are spelled correctly and that you\'ve selected enough categories.'));
+        else
+            Search.status.text(_('Search finished, found %s page(s) matching the search query.').replace('%s', resultCount));
+        Search.status.fadeIn(500);
+      }
+    }
+    displayNextItem();
+  },
+
+  performObjectSearch : function(object, otherterms) {
+    var filenames = this._index.filenames;
+    var objects = this._index.objects;
+    var objnames = this._index.objnames;
+    var titles = this._index.titles;
+
+    var importantResults = [];
+    var objectResults = [];
+    var unimportantResults = [];
+
+    for (var prefix in objects) {
+      for (var name in objects[prefix]) {
+        var fullname = (prefix ? prefix + '.' : '') + name;
+        if (fullname.toLowerCase().indexOf(object) > -1) {
+          var match = objects[prefix][name];
+          var objname = objnames[match[1]][2];
+          var title = titles[match[0]];
+          // If more than one term searched for, we require other words to be
+          // found in the name/title/description
+          if (otherterms.length > 0) {
+            var haystack = (prefix + ' ' + name + ' ' +
+                            objname + ' ' + title).toLowerCase();
+            var allfound = true;
+            for (var i = 0; i < otherterms.length; i++) {
+              if (haystack.indexOf(otherterms[i]) == -1) {
+                allfound = false;
+                break;
+              }
+            }
+            if (!allfound) {
+              continue;
+            }
+          }
+          var descr = objname + _(', in ') + title;
+          anchor = match[3];
+          if (anchor == '')
+            anchor = fullname;
+          else if (anchor == '-')
+            anchor = objnames[match[1]][1] + '-' + fullname;
+          result = [filenames[match[0]], fullname, '#'+anchor, descr];
+          switch (match[2]) {
+          case 1: objectResults.push(result); break;
+          case 0: importantResults.push(result); break;
+          case 2: unimportantResults.push(result); break;
+          }
+        }
+      }
+    }
+
+    // sort results descending
+    objectResults.sort(function(a, b) {
+      return (a[1] > b[1]) ? -1 : ((a[1] < b[1]) ? 1 : 0);
+    });
+
+    importantResults.sort(function(a, b) {
+      return (a[1] > b[1]) ? -1 : ((a[1] < b[1]) ? 1 : 0);
+    });
+
+    unimportantResults.sort(function(a, b) {
+      return (a[1] > b[1]) ? -1 : ((a[1] < b[1]) ? 1 : 0);
+    });
+
+    return [importantResults, objectResults, unimportantResults]
+  }
+}
+
+$(document).ready(function() {
+  Search.init();
+});

_static/sidebar.js

@@ -0,0 +1,151 @@
+/*
+ * sidebar.js
+ * ~~~~~~~~~~
+ *
+ * This script makes the Sphinx sidebar collapsible.
+ *
+ * .sphinxsidebar contains .sphinxsidebarwrapper.  This script adds
+ * in .sphixsidebar, after .sphinxsidebarwrapper, the #sidebarbutton
+ * used to collapse and expand the sidebar.
+ *
+ * When the sidebar is collapsed the .sphinxsidebarwrapper is hidden
+ * and the width of the sidebar and the margin-left of the document
+ * are decreased. When the sidebar is expanded the opposite happens.
+ * This script saves a per-browser/per-session cookie used to
+ * remember the position of the sidebar among the pages.
+ * Once the browser is closed the cookie is deleted and the position
+ * reset to the default (expanded).
+ *
+ * :copyright: Copyright 2007-2011 by the Sphinx team, see AUTHORS.
+ * :license: BSD, see LICENSE for details.
+ *
+ */
+
+$(function() {
+  // global elements used by the functions.
+  // the 'sidebarbutton' element is defined as global after its
+  // creation, in the add_sidebar_button function
+  var bodywrapper = $('.bodywrapper');
+  var sidebar = $('.sphinxsidebar');
+  var sidebarwrapper = $('.sphinxsidebarwrapper');
+
+  // for some reason, the document has no sidebar; do not run into errors
+  if (!sidebar.length) return;
+
+  // original margin-left of the bodywrapper and width of the sidebar
+  // with the sidebar expanded
+  var bw_margin_expanded = bodywrapper.css('margin-left');
+  var ssb_width_expanded = sidebar.width();
+
+  // margin-left of the bodywrapper and width of the sidebar
+  // with the sidebar collapsed
+  var bw_margin_collapsed = '.8em';
+  var ssb_width_collapsed = '.8em';
+
+  // colors used by the current theme
+  var dark_color = $('.related').css('background-color');
+  var light_color = $('.document').css('background-color');
+
+  function sidebar_is_collapsed() {
+    return sidebarwrapper.is(':not(:visible)');
+  }
+
+  function toggle_sidebar() {
+    if (sidebar_is_collapsed())
+      expand_sidebar();
+    else
+      collapse_sidebar();
+  }
+
+  function collapse_sidebar() {
+    sidebarwrapper.hide();
+    sidebar.css('width', ssb_width_collapsed);
+    bodywrapper.css('margin-left', bw_margin_collapsed);
+    sidebarbutton.css({
+        'margin-left': '0',
+        'height': bodywrapper.height()
+    });
+    sidebarbutton.find('span').text('»');
+    sidebarbutton.attr('title', _('Expand sidebar'));
+    document.cookie = 'sidebar=collapsed';
+  }
+
+  function expand_sidebar() {
+    bodywrapper.css('margin-left', bw_margin_expanded);
+    sidebar.css('width', ssb_width_expanded);
+    sidebarwrapper.show();
+    sidebarbutton.css({
+        'margin-left': ssb_width_expanded-12,
+        'height': bodywrapper.height()
+    });
+    sidebarbutton.find('span').text('«');
+    sidebarbutton.attr('title', _('Collapse sidebar'));
+    document.cookie = 'sidebar=expanded';
+  }
+
+  function add_sidebar_button() {
+    sidebarwrapper.css({
+        'float': 'left',
+        'margin-right': '0',
+        'width': ssb_width_expanded - 28
+    });
+    // create the button
+    sidebar.append(
+        '<div id="sidebarbutton"><span>&laquo;</span></div>'
+    );
+    var sidebarbutton = $('#sidebarbutton');
+    light_color = sidebarbutton.css('background-color');
+    // find the height of the viewport to center the '<<' in the page
+    var viewport_height;
+    if (window.innerHeight)
+ 	  viewport_height = window.innerHeight;
+    else
+	  viewport_height = $(window).height();
+    sidebarbutton.find('span').css({
+        'display': 'block',
+        'margin-top': (viewport_height - sidebar.position().top - 20) / 2
+    });
+
+    sidebarbutton.click(toggle_sidebar);
+    sidebarbutton.attr('title', _('Collapse sidebar'));
+    sidebarbutton.css({
+        'color': '#FFFFFF',
+        'border-left': '1px solid ' + dark_color,
+        'font-size': '1.2em',
+        'cursor': 'pointer',
+        'height': bodywrapper.height(),
+        'padding-top': '1px',
+        'margin-left': ssb_width_expanded - 12
+    });
+
+    sidebarbutton.hover(
+      function () {
+          $(this).css('background-color', dark_color);
+      },
+      function () {
+          $(this).css('background-color', light_color);
+      }
+    );
+  }
+
+  function set_position_from_cookie() {
+    if (!document.cookie)
+      return;
+    var items = document.cookie.split(';');
+    for(var k=0; k<items.length; k++) {
+      var key_val = items[k].split('=');
+      var key = key_val[0];
+      if (key == 'sidebar') {
+        var value = key_val[1];
+        if ((value == 'collapsed') && (!sidebar_is_collapsed()))
+          collapse_sidebar();
+        else if ((value == 'expanded') && (sidebar_is_collapsed()))
+          expand_sidebar();
+      }
+    }
+  }
+
+  add_sidebar_button();
+  var sidebarbutton = $('#sidebarbutton');
+  set_position_from_cookie();
+});

_static/underscore.js

@@ -0,0 +1,807 @@
+//     Underscore.js 1.1.6
+//     (c) 2011 Jeremy Ashkenas, DocumentCloud Inc.
+//     Underscore is freely distributable under the MIT license.
+//     Portions of Underscore are inspired or borrowed from Prototype,
+//     Oliver Steele's Functional, and John Resig's Micro-Templating.
+//     For all details and documentation:
+//     http://documentcloud.github.com/underscore
+
+(function() {
+
+  // Baseline setup
+  // --------------
+
+  // Establish the root object, `window` in the browser, or `global` on the server.
+  var root = this;
+
+  // Save the previous value of the `_` variable.
+  var previousUnderscore = root._;
+
+  // Establish the object that gets returned to break out of a loop iteration.
+  var breaker = {};
+
+  // Save bytes in the minified (but not gzipped) version:
+  var ArrayProto = Array.prototype, ObjProto = Object.prototype, FuncProto = Function.prototype;
+
+  // Create quick reference variables for speed access to core prototypes.
+  var slice            = ArrayProto.slice,
+      unshift          = ArrayProto.unshift,
+      toString         = ObjProto.toString,
+      hasOwnProperty   = ObjProto.hasOwnProperty;
+
+  // All **ECMAScript 5** native function implementations that we hope to use
+  // are declared here.
+  var
+    nativeForEach      = ArrayProto.forEach,
+    nativeMap          = ArrayProto.map,
+    nativeReduce       = ArrayProto.reduce,
+    nativeReduceRight  = ArrayProto.reduceRight,
+    nativeFilter       = ArrayProto.filter,
+    nativeEvery        = ArrayProto.every,
+    nativeSome         = ArrayProto.some,
+    nativeIndexOf      = ArrayProto.indexOf,
+    nativeLastIndexOf  = ArrayProto.lastIndexOf,
+    nativeIsArray      = Array.isArray,
+    nativeKeys         = Object.keys,
+    nativeBind         = FuncProto.bind;
+
+  // Create a safe reference to the Underscore object for use below.
+  var _ = function(obj) { return new wrapper(obj); };
+
+  // Export the Underscore object for **CommonJS**, with backwards-compatibility
+  // for the old `require()` API. If we're not in CommonJS, add `_` to the
+  // global object.
+  if (typeof module !== 'undefined' && module.exports) {
+    module.exports = _;
+    _._ = _;
+  } else {
+    root._ = _;
+  }
+
+  // Current version.
+  _.VERSION = '1.1.6';
+
+  // Collection Functions
+  // --------------------
+
+  // The cornerstone, an `each` implementation, aka `forEach`.
+  // Handles objects implementing `forEach`, arrays, and raw objects.
+  // Delegates to **ECMAScript 5**'s native `forEach` if available.
+  var each = _.each = _.forEach = function(obj, iterator, context) {
+    if (obj == null) return;
+    if (nativeForEach && obj.forEach === nativeForEach) {
+      obj.forEach(iterator, context);
+    } else if (_.isNumber(obj.length)) {
+      for (var i = 0, l = obj.length; i < l; i++) {
+        if (iterator.call(context, obj[i], i, obj) === breaker) return;
+      }
+    } else {
+      for (var key in obj) {
+        if (hasOwnProperty.call(obj, key)) {
+          if (iterator.call(context, obj[key], key, obj) === breaker) return;
+        }
+      }
+    }
+  };
+
+  // Return the results of applying the iterator to each element.
+  // Delegates to **ECMAScript 5**'s native `map` if available.
+  _.map = function(obj, iterator, context) {
+    var results = [];
+    if (obj == null) return results;
+    if (nativeMap && obj.map === nativeMap) return obj.map(iterator, context);
+    each(obj, function(value, index, list) {
+      results[results.length] = iterator.call(context, value, index, list);
+    });
+    return results;
+  };
+
+  // **Reduce** builds up a single result from a list of values, aka `inject`,
+  // or `foldl`. Delegates to **ECMAScript 5**'s native `reduce` if available.
+  _.reduce = _.foldl = _.inject = function(obj, iterator, memo, context) {
+    var initial = memo !== void 0;
+    if (obj == null) obj = [];
+    if (nativeReduce && obj.reduce === nativeReduce) {
+      if (context) iterator = _.bind(iterator, context);
+      return initial ? obj.reduce(iterator, memo) : obj.reduce(iterator);
+    }
+    each(obj, function(value, index, list) {
+      if (!initial && index === 0) {
+        memo = value;
+        initial = true;
+      } else {
+        memo = iterator.call(context, memo, value, index, list);
+      }
+    });
+    if (!initial) throw new TypeError("Reduce of empty array with no initial value");
+    return memo;
+  };
+
+  // The right-associative version of reduce, also known as `foldr`.
+  // Delegates to **ECMAScript 5**'s native `reduceRight` if available.
+  _.reduceRight = _.foldr = function(obj, iterator, memo, context) {
+    if (obj == null) obj = [];
+    if (nativeReduceRight && obj.reduceRight === nativeReduceRight) {
+      if (context) iterator = _.bind(iterator, context);
+      return memo !== void 0 ? obj.reduceRight(iterator, memo) : obj.reduceRight(iterator);
+    }
+    var reversed = (_.isArray(obj) ? obj.slice() : _.toArray(obj)).reverse();
+    return _.reduce(reversed, iterator, memo, context);
+  };
+
+  // Return the first value which passes a truth test. Aliased as `detect`.
+  _.find = _.detect = function(obj, iterator, context) {
+    var result;
+    any(obj, function(value, index, list) {
+      if (iterator.call(context, value, index, list)) {
+        result = value;
+        return true;
+      }
+    });
+    return result;
+  };
+
+  // Return all the elements that pass a truth test.
+  // Delegates to **ECMAScript 5**'s native `filter` if available.
+  // Aliased as `select`.
+  _.filter = _.select = function(obj, iterator, context) {
+    var results = [];
+    if (obj == null) return results;
+    if (nativeFilter && obj.filter === nativeFilter) return obj.filter(iterator, context);
+    each(obj, function(value, index, list) {
+      if (iterator.call(context, value, index, list)) results[results.length] = value;
+    });
+    return results;
+  };
+
+  // Return all the elements for which a truth test fails.
+  _.reject = function(obj, iterator, context) {
+    var results = [];
+    if (obj == null) return results;
+    each(obj, function(value, index, list) {
+      if (!iterator.call(context, value, index, list)) results[results.length] = value;
+    });
+    return results;
+  };
+
+  // Determine whether all of the elements match a truth test.
+  // Delegates to **ECMAScript 5**'s native `every` if available.
+  // Aliased as `all`.
+  _.every = _.all = function(obj, iterator, context) {
+    var result = true;
+    if (obj == null) return result;
+    if (nativeEvery && obj.every === nativeEvery) return obj.every(iterator, context);
+    each(obj, function(value, index, list) {
+      if (!(result = result && iterator.call(context, value, index, list))) return breaker;
+    });
+    return result;
+  };
+
+  // Determine if at least one element in the object matches a truth test.
+  // Delegates to **ECMAScript 5**'s native `some` if available.
+  // Aliased as `any`.
+  var any = _.some = _.any = function(obj, iterator, context) {
+    iterator || (iterator = _.identity);
+    var result = false;
+    if (obj == null) return result;
+    if (nativeSome && obj.some === nativeSome) return obj.some(iterator, context);
+    each(obj, function(value, index, list) {
+      if (result = iterator.call(context, value, index, list)) return breaker;
+    });
+    return result;
+  };
+
+  // Determine if a given value is included in the array or object using `===`.
+  // Aliased as `contains`.
+  _.include = _.contains = function(obj, target) {
+    var found = false;
+    if (obj == null) return found;
+    if (nativeIndexOf && obj.indexOf === nativeIndexOf) return obj.indexOf(target) != -1;
+    any(obj, function(value) {
+      if (found = value === target) return true;
+    });
+    return found;
+  };
+
+  // Invoke a method (with arguments) on every item in a collection.
+  _.invoke = function(obj, method) {
+    var args = slice.call(arguments, 2);
+    return _.map(obj, function(value) {
+      return (method.call ? method || value : value[method]).apply(value, args);
+    });
+  };
+
+  // Convenience version of a common use case of `map`: fetching a property.
+  _.pluck = function(obj, key) {
+    return _.map(obj, function(value){ return value[key]; });
+  };
+
+  // Return the maximum element or (element-based computation).
+  _.max = function(obj, iterator, context) {
+    if (!iterator && _.isArray(obj)) return Math.max.apply(Math, obj);
+    var result = {computed : -Infinity};
+    each(obj, function(value, index, list) {
+      var computed = iterator ? iterator.call(context, value, index, list) : value;
+      computed >= result.computed && (result = {value : value, computed : computed});
+    });
+    return result.value;
+  };
+
+  // Return the minimum element (or element-based computation).
+  _.min = function(obj, iterator, context) {
+    if (!iterator && _.isArray(obj)) return Math.min.apply(Math, obj);
+    var result = {computed : Infinity};
+    each(obj, function(value, index, list) {
+      var computed = iterator ? iterator.call(context, value, index, list) : value;
+      computed < result.computed && (result = {value : value, computed : computed});
+    });
+    return result.value;
+  };
+
+  // Sort the object's values by a criterion produced by an iterator.
+  _.sortBy = function(obj, iterator, context) {
+    return _.pluck(_.map(obj, function(value, index, list) {
+      return {
+        value : value,
+        criteria : iterator.call(context, value, index, list)
+      };
+    }).sort(function(left, right) {
+      var a = left.criteria, b = right.criteria;
+      return a < b ? -1 : a > b ? 1 : 0;
+    }), 'value');
+  };
+
+  // Use a comparator function to figure out at what index an object should
+  // be inserted so as to maintain order. Uses binary search.
+  _.sortedIndex = function(array, obj, iterator) {
+    iterator || (iterator = _.identity);
+    var low = 0, high = array.length;
+    while (low < high) {
+      var mid = (low + high) >> 1;
+      iterator(array[mid]) < iterator(obj) ? low = mid + 1 : high = mid;
+    }
+    return low;
+  };
+
+  // Safely convert anything iterable into a real, live array.
+  _.toArray = function(iterable) {
+    if (!iterable)                return [];
+    if (iterable.toArray)         return iterable.toArray();
+    if (_.isArray(iterable))      return iterable;
+    if (_.isArguments(iterable))  return slice.call(iterable);
+    return _.values(iterable);
+  };
+
+  // Return the number of elements in an object.
+  _.size = function(obj) {
+    return _.toArray(obj).length;
+  };
+
+  // Array Functions
+  // ---------------
+
+  // Get the first element of an array. Passing **n** will return the first N
+  // values in the array. Aliased as `head`. The **guard** check allows it to work
+  // with `_.map`.
+  _.first = _.head = function(array, n, guard) {
+    return (n != null) && !guard ? slice.call(array, 0, n) : array[0];
+  };
+
+  // Returns everything but the first entry of the array. Aliased as `tail`.
+  // Especially useful on the arguments object. Passing an **index** will return
+  // the rest of the values in the array from that index onward. The **guard**
+  // check allows it to work with `_.map`.
+  _.rest = _.tail = function(array, index, guard) {
+    return slice.call(array, (index == null) || guard ? 1 : index);
+  };
+
+  // Get the last element of an array.
+  _.last = function(array) {
+    return array[array.length - 1];
+  };
+
+  // Trim out all falsy values from an array.
+  _.compact = function(array) {
+    return _.filter(array, function(value){ return !!value; });
+  };
+
+  // Return a completely flattened version of an array.
+  _.flatten = function(array) {
+    return _.reduce(array, function(memo, value) {
+      if (_.isArray(value)) return memo.concat(_.flatten(value));
+      memo[memo.length] = value;
+      return memo;
+    }, []);
+  };
+
+  // Return a version of the array that does not contain the specified value(s).
+  _.without = function(array) {
+    var values = slice.call(arguments, 1);
+    return _.filter(array, function(value){ return !_.include(values, value); });
+  };
+
+  // Produce a duplicate-free version of the array. If the array has already
+  // been sorted, you have the option of using a faster algorithm.
+  // Aliased as `unique`.
+  _.uniq = _.unique = function(array, isSorted) {
+    return _.reduce(array, function(memo, el, i) {
+      if (0 == i || (isSorted === true ? _.last(memo) != el : !_.include(memo, el))) memo[memo.length] = el;
+      return memo;
+    }, []);
+  };
+
+  // Produce an array that contains every item shared between all the
+  // passed-in arrays.
+  _.intersect = function(array) {
+    var rest = slice.call(arguments, 1);
+    return _.filter(_.uniq(array), function(item) {
+      return _.every(rest, function(other) {
+        return _.indexOf(other, item) >= 0;
+      });
+    });
+  };
+
+  // Zip together multiple lists into a single array -- elements that share
+  // an index go together.
+  _.zip = function() {
+    var args = slice.call(arguments);
+    var length = _.max(_.pluck(args, 'length'));
+    var results = new Array(length);
+    for (var i = 0; i < length; i++) results[i] = _.pluck(args, "" + i);
+    return results;
+  };
+
+  // If the browser doesn't supply us with indexOf (I'm looking at you, **MSIE**),
+  // we need this function. Return the position of the first occurrence of an
+  // item in an array, or -1 if the item is not included in the array.
+  // Delegates to **ECMAScript 5**'s native `indexOf` if available.
+  // If the array is large and already in sort order, pass `true`
+  // for **isSorted** to use binary search.
+  _.indexOf = function(array, item, isSorted) {
+    if (array == null) return -1;
+    var i, l;
+    if (isSorted) {
+      i = _.sortedIndex(array, item);
+      return array[i] === item ? i : -1;
+    }
+    if (nativeIndexOf && array.indexOf === nativeIndexOf) return array.indexOf(item);
+    for (i = 0, l = array.length; i < l; i++) if (array[i] === item) return i;
+    return -1;
+  };
+
+
+  // Delegates to **ECMAScript 5**'s native `lastIndexOf` if available.
+  _.lastIndexOf = function(array, item) {
+    if (array == null) return -1;
+    if (nativeLastIndexOf && array.lastIndexOf === nativeLastIndexOf) return array.lastIndexOf(item);
+    var i = array.length;
+    while (i--) if (array[i] === item) return i;
+    return -1;
+  };
+
+  // Generate an integer Array containing an arithmetic progression. A port of
+  // the native Python `range()` function. See
+  // [the Python documentation](http://docs.python.org/library/functions.html#range).
+  _.range = function(start, stop, step) {
+    if (arguments.length <= 1) {
+      stop = start || 0;
+      start = 0;
+    }
+    step = arguments[2] || 1;
+
+    var len = Math.max(Math.ceil((stop - start) / step), 0);
+    var idx = 0;
+    var range = new Array(len);
+
+    while(idx < len) {
+      range[idx++] = start;
+      start += step;
+    }
+
+    return range;
+  };
+
+  // Function (ahem) Functions
+  // ------------------
+
+  // Create a function bound to a given object (assigning `this`, and arguments,
+  // optionally). Binding with arguments is also known as `curry`.
+  // Delegates to **ECMAScript 5**'s native `Function.bind` if available.
+  // We check for `func.bind` first, to fail fast when `func` is undefined.
+  _.bind = function(func, obj) {
+    if (func.bind === nativeBind && nativeBind) return nativeBind.apply(func, slice.call(arguments, 1));
+    var args = slice.call(arguments, 2);
+    return function() {
+      return func.apply(obj, args.concat(slice.call(arguments)));
+    };
+  };
+
+  // Bind all of an object's methods to that object. Useful for ensuring that
+  // all callbacks defined on an object belong to it.
+  _.bindAll = function(obj) {
+    var funcs = slice.call(arguments, 1);
+    if (funcs.length == 0) funcs = _.functions(obj);
+    each(funcs, function(f) { obj[f] = _.bind(obj[f], obj); });
+    return obj;
+  };
+
+  // Memoize an expensive function by storing its results.
+  _.memoize = function(func, hasher) {
+    var memo = {};
+    hasher || (hasher = _.identity);
+    return function() {
+      var key = hasher.apply(this, arguments);
+      return hasOwnProperty.call(memo, key) ? memo[key] : (memo[key] = func.apply(this, arguments));
+    };
+  };
+
+  // Delays a function for the given number of milliseconds, and then calls
+  // it with the arguments supplied.
+  _.delay = function(func, wait) {
+    var args = slice.call(arguments, 2);
+    return setTimeout(function(){ return func.apply(func, args); }, wait);
+  };
+
+  // Defers a function, scheduling it to run after the current call stack has
+  // cleared.
+  _.defer = function(func) {
+    return _.delay.apply(_, [func, 1].concat(slice.call(arguments, 1)));
+  };
+
+  // Internal function used to implement `_.throttle` and `_.debounce`.
+  var limit = function(func, wait, debounce) {
+    var timeout;
+    return function() {
+      var context = this, args = arguments;
+      var throttler = function() {
+        timeout = null;
+        func.apply(context, args);
+      };
+      if (debounce) clearTimeout(timeout);
+      if (debounce || !timeout) timeout = setTimeout(throttler, wait);
+    };
+  };
+
+  // Returns a function, that, when invoked, will only be triggered at most once
+  // during a given window of time.
+  _.throttle = function(func, wait) {
+    return limit(func, wait, false);
+  };
+
+  // Returns a function, that, as long as it continues to be invoked, will not
+  // be triggered. The function will be called after it stops being called for
+  // N milliseconds.
+  _.debounce = function(func, wait) {
+    return limit(func, wait, true);
+  };
+
+  // Returns a function that will be executed at most one time, no matter how
+  // often you call it. Useful for lazy initialization.
+  _.once = function(func) {
+    var ran = false, memo;
+    return function() {
+      if (ran) return memo;
+      ran = true;
+      return memo = func.apply(this, arguments);
+    };
+  };
+
+  // Returns the first function passed as an argument to the second,
+  // allowing you to adjust arguments, run code before and after, and
+  // conditionally execute the original function.
+  _.wrap = function(func, wrapper) {
+    return function() {
+      var args = [func].concat(slice.call(arguments));
+      return wrapper.apply(this, args);
+    };
+  };
+
+  // Returns a function that is the composition of a list of functions, each
+  // consuming the return value of the function that follows.
+  _.compose = function() {
+    var funcs = slice.call(arguments);
+    return function() {
+      var args = slice.call(arguments);
+      for (var i=funcs.length-1; i >= 0; i--) {
+        args = [funcs[i].apply(this, args)];
+      }
+      return args[0];
+    };
+  };
+
+  // Returns a function that will only be executed after being called N times.
+  _.after = function(times, func) {
+    return function() {
+      if (--times < 1) { return func.apply(this, arguments); }
+    };
+  };
+
+
+  // Object Functions
+  // ----------------
+
+  // Retrieve the names of an object's properties.
+  // Delegates to **ECMAScript 5**'s native `Object.keys`
+  _.keys = nativeKeys || function(obj) {
+    if (obj !== Object(obj)) throw new TypeError('Invalid object');
+    var keys = [];
+    for (var key in obj) if (hasOwnProperty.call(obj, key)) keys[keys.length] = key;
+    return keys;
+  };
+
+  // Retrieve the values of an object's properties.
+  _.values = function(obj) {
+    return _.map(obj, _.identity);
+  };
+
+  // Return a sorted list of the function names available on the object.
+  // Aliased as `methods`
+  _.functions = _.methods = function(obj) {
+    return _.filter(_.keys(obj), function(key){ return _.isFunction(obj[key]); }).sort();
+  };
+
+  // Extend a given object with all the properties in passed-in object(s).
+  _.extend = function(obj) {
+    each(slice.call(arguments, 1), function(source) {
+      for (var prop in source) {
+        if (source[prop] !== void 0) obj[prop] = source[prop];
+      }
+    });
+    return obj;
+  };
+
+  // Fill in a given object with default properties.
+  _.defaults = function(obj) {
+    each(slice.call(arguments, 1), function(source) {
+      for (var prop in source) {
+        if (obj[prop] == null) obj[prop] = source[prop];
+      }
+    });
+    return obj;
+  };
+
+  // Create a (shallow-cloned) duplicate of an object.
+  _.clone = function(obj) {
+    return _.isArray(obj) ? obj.slice() : _.extend({}, obj);
+  };
+
+  // Invokes interceptor with the obj, and then returns obj.
+  // The primary purpose of this method is to "tap into" a method chain, in
+  // order to perform operations on intermediate results within the chain.
+  _.tap = function(obj, interceptor) {
+    interceptor(obj);
+    return obj;
+  };
+
+  // Perform a deep comparison to check if two objects are equal.
+  _.isEqual = function(a, b) {
+    // Check object identity.
+    if (a === b) return true;
+    // Different types?
+    var atype = typeof(a), btype = typeof(b);
+    if (atype != btype) return false;
+    // Basic equality test (watch out for coercions).
+    if (a == b) return true;
+    // One is falsy and the other truthy.
+    if ((!a && b) || (a && !b)) return false;
+    // Unwrap any wrapped objects.
+    if (a._chain) a = a._wrapped;
+    if (b._chain) b = b._wrapped;
+    // One of them implements an isEqual()?
+    if (a.isEqual) return a.isEqual(b);
+    // Check dates' integer values.
+    if (_.isDate(a) && _.isDate(b)) return a.getTime() === b.getTime();
+    // Both are NaN?
+    if (_.isNaN(a) && _.isNaN(b)) return false;
+    // Compare regular expressions.
+    if (_.isRegExp(a) && _.isRegExp(b))
+      return a.source     === b.source &&
+             a.global     === b.global &&
+             a.ignoreCase === b.ignoreCase &&
+             a.multiline  === b.multiline;
+    // If a is not an object by this point, we can't handle it.
+    if (atype !== 'object') return false;
+    // Check for different array lengths before comparing contents.
+    if (a.length && (a.length !== b.length)) return false;
+    // Nothing else worked, deep compare the contents.
+    var aKeys = _.keys(a), bKeys = _.keys(b);
+    // Different object sizes?
+    if (aKeys.length != bKeys.length) return false;
+    // Recursive comparison of contents.
+    for (var key in a) if (!(key in b) || !_.isEqual(a[key], b[key])) return false;
+    return true;
+  };
+
+  // Is a given array or object empty?
+  _.isEmpty = function(obj) {
+    if (_.isArray(obj) || _.isString(obj)) return obj.length === 0;
+    for (var key in obj) if (hasOwnProperty.call(obj, key)) return false;
+    return true;
+  };
+
+  // Is a given value a DOM element?
+  _.isElement = function(obj) {
+    return !!(obj && obj.nodeType == 1);
+  };
+
+  // Is a given value an array?
+  // Delegates to ECMA5's native Array.isArray
+  _.isArray = nativeIsArray || function(obj) {
+    return toString.call(obj) === '[object Array]';
+  };
+
+  // Is a given variable an arguments object?
+  _.isArguments = function(obj) {
+    return !!(obj && hasOwnProperty.call(obj, 'callee'));
+  };
+
+  // Is a given value a function?
+  _.isFunction = function(obj) {
+    return !!(obj && obj.constructor && obj.call && obj.apply);
+  };
+
+  // Is a given value a string?
+  _.isString = function(obj) {
+    return !!(obj === '' || (obj && obj.charCodeAt && obj.substr));
+  };
+
+  // Is a given value a number?
+  _.isNumber = function(obj) {
+    return !!(obj === 0 || (obj && obj.toExponential && obj.toFixed));
+  };
+
+  // Is the given value `NaN`? `NaN` happens to be the only value in JavaScript
+  // that does not equal itself.
+  _.isNaN = function(obj) {
+    return obj !== obj;
+  };
+
+  // Is a given value a boolean?
+  _.isBoolean = function(obj) {
+    return obj === true || obj === false;
+  };
+
+  // Is a given value a date?
+  _.isDate = function(obj) {
+    return !!(obj && obj.getTimezoneOffset && obj.setUTCFullYear);
+  };
+
+  // Is the given value a regular expression?
+  _.isRegExp = function(obj) {
+    return !!(obj && obj.test && obj.exec && (obj.ignoreCase || obj.ignoreCase === false));
+  };
+
+  // Is a given value equal to null?
+  _.isNull = function(obj) {
+    return obj === null;
+  };
+
+  // Is a given variable undefined?
+  _.isUndefined = function(obj) {
+    return obj === void 0;
+  };
+
+  // Utility Functions
+  // -----------------
+
+  // Run Underscore.js in *noConflict* mode, returning the `_` variable to its
+  // previous owner. Returns a reference to the Underscore object.
+  _.noConflict = function() {
+    root._ = previousUnderscore;
+    return this;
+  };
+
+  // Keep the identity function around for default iterators.
+  _.identity = function(value) {
+    return value;
+  };
+
+  // Run a function **n** times.
+  _.times = function (n, iterator, context) {
+    for (var i = 0; i < n; i++) iterator.call(context, i);
+  };
+
+  // Add your own custom functions to the Underscore object, ensuring that
+  // they're correctly added to the OOP wrapper as well.
+  _.mixin = function(obj) {
+    each(_.functions(obj), function(name){
+      addToWrapper(name, _[name] = obj[name]);
+    });
+  };
+
+  // Generate a unique integer id (unique within the entire client session).
+  // Useful for temporary DOM ids.
+  var idCounter = 0;
+  _.uniqueId = function(prefix) {
+    var id = idCounter++;
+    return prefix ? prefix + id : id;
+  };
+
+  // By default, Underscore uses ERB-style template delimiters, change the
+  // following template settings to use alternative delimiters.
+  _.templateSettings = {
+    evaluate    : /<%([\s\S]+?)%>/g,
+    interpolate : /<%=([\s\S]+?)%>/g
+  };
+
+  // JavaScript micro-templating, similar to John Resig's implementation.
+  // Underscore templating handles arbitrary delimiters, preserves whitespace,
+  // and correctly escapes quotes within interpolated code.
+  _.template = function(str, data) {
+    var c  = _.templateSettings;
+    var tmpl = 'var __p=[],print=function(){__p.push.apply(__p,arguments);};' +
+      'with(obj||{}){__p.push(\'' +
+      str.replace(/\\/g, '\\\\')
+         .replace(/'/g, "\\'")
+         .replace(c.interpolate, function(match, code) {
+           return "'," + code.replace(/\\'/g, "'") + ",'";
+         })
+         .replace(c.evaluate || null, function(match, code) {
+           return "');" + code.replace(/\\'/g, "'")
+                              .replace(/[\r\n\t]/g, ' ') + "__p.push('";
+         })
+         .replace(/\r/g, '\\r')
+         .replace(/\n/g, '\\n')
+         .replace(/\t/g, '\\t')
+         + "');}return __p.join('');";
+    var func = new Function('obj', tmpl);
+    return data ? func(data) : func;
+  };
+
+  // The OOP Wrapper
+  // ---------------
+
+  // If Underscore is called as a function, it returns a wrapped object that
+  // can be used OO-style. This wrapper holds altered versions of all the
+  // underscore functions. Wrapped objects may be chained.
+  var wrapper = function(obj) { this._wrapped = obj; };
+
+  // Expose `wrapper.prototype` as `_.prototype`
+  _.prototype = wrapper.prototype;
+
+  // Helper function to continue chaining intermediate results.
+  var result = function(obj, chain) {
+    return chain ? _(obj).chain() : obj;
+  };
+
+  // A method to easily add functions to the OOP wrapper.
+  var addToWrapper = function(name, func) {
+    wrapper.prototype[name] = function() {
+      var args = slice.call(arguments);
+      unshift.call(args, this._wrapped);
+      return result(func.apply(_, args), this._chain);
+    };
+  };
+
+  // Add all of the Underscore functions to the wrapper object.
+  _.mixin(_);
+
+  // Add all mutator Array functions to the wrapper.
+  each(['pop', 'push', 'reverse', 'shift', 'sort', 'splice', 'unshift'], function(name) {
+    var method = ArrayProto[name];
+    wrapper.prototype[name] = function() {
+      method.apply(this._wrapped, arguments);
+      return result(this._wrapped, this._chain);
+    };
+  });
+
+  // Add all accessor Array functions to the wrapper.
+  each(['concat', 'join', 'slice'], function(name) {
+    var method = ArrayProto[name];
+    wrapper.prototype[name] = function() {
+      return result(method.apply(this._wrapped, arguments), this._chain);
+    };
+  });
+
+  // Start chaining a wrapped Underscore object.
+  wrapper.prototype.chain = function() {
+    this._chain = true;
+    return this;
+  };
+
+  // Extracts the result from a wrapped and chained object.
+  wrapper.prototype.value = function() {
+    return this._wrapped;
+  };
+
+})();

_static/websupport.js

@@ -0,0 +1,808 @@
+/*
+ * websupport.js
+ * ~~~~~~~~~~~~~
+ *
+ * sphinx.websupport utilties for all documentation.
+ *
+ * :copyright: Copyright 2007-2011 by the Sphinx team, see AUTHORS.
+ * :license: BSD, see LICENSE for details.
+ *
+ */
+
+(function($) {
+  $.fn.autogrow = function() {
+    return this.each(function() {
+    var textarea = this;
+
+    $.fn.autogrow.resize(textarea);
+
+    $(textarea)
+      .focus(function() {
+        textarea.interval = setInterval(function() {
+          $.fn.autogrow.resize(textarea);
+        }, 500);
+      })
+      .blur(function() {
+        clearInterval(textarea.interval);
+      });
+    });
+  };
+
+  $.fn.autogrow.resize = function(textarea) {
+    var lineHeight = parseInt($(textarea).css('line-height'), 10);
+    var lines = textarea.value.split('\n');
+    var columns = textarea.cols;
+    var lineCount = 0;
+    $.each(lines, function() {
+      lineCount += Math.ceil(this.length / columns) || 1;
+    });
+    var height = lineHeight * (lineCount + 1);
+    $(textarea).css('height', height);
+  };
+})(jQuery);
+
+(function($) {
+  var comp, by;
+
+  function init() {
+    initEvents();
+    initComparator();
+  }
+
+  function initEvents() {
+    $('a.comment-close').live("click", function(event) {
+      event.preventDefault();
+      hide($(this).attr('id').substring(2));
+    });
+    $('a.vote').live("click", function(event) {
+      event.preventDefault();
+      handleVote($(this));
+    });
+    $('a.reply').live("click", function(event) {
+      event.preventDefault();
+      openReply($(this).attr('id').substring(2));
+    });
+    $('a.close-reply').live("click", function(event) {
+      event.preventDefault();
+      closeReply($(this).attr('id').substring(2));
+    });
+    $('a.sort-option').live("click", function(event) {
+      event.preventDefault();
+      handleReSort($(this));
+    });
+    $('a.show-proposal').live("click", function(event) {
+      event.preventDefault();
+      showProposal($(this).attr('id').substring(2));
+    });
+    $('a.hide-proposal').live("click", function(event) {
+      event.preventDefault();
+      hideProposal($(this).attr('id').substring(2));
+    });
+    $('a.show-propose-change').live("click", function(event) {
+      event.preventDefault();
+      showProposeChange($(this).attr('id').substring(2));
+    });
+    $('a.hide-propose-change').live("click", function(event) {
+      event.preventDefault();
+      hideProposeChange($(this).attr('id').substring(2));
+    });
+    $('a.accept-comment').live("click", function(event) {
+      event.preventDefault();
+      acceptComment($(this).attr('id').substring(2));
+    });
+    $('a.delete-comment').live("click", function(event) {
+      event.preventDefault();
+      deleteComment($(this).attr('id').substring(2));
+    });
+    $('a.comment-markup').live("click", function(event) {
+      event.preventDefault();
+      toggleCommentMarkupBox($(this).attr('id').substring(2));
+    });
+  }
+
+  /**
+   * Set comp, which is a comparator function used for sorting and
+   * inserting comments into the list.
+   */
+  function setComparator() {
+    // If the first three letters are "asc", sort in ascending order
+    // and remove the prefix.
+    if (by.substring(0,3) == 'asc') {
+      var i = by.substring(3);
+      comp = function(a, b) { return a[i] - b[i]; };
+    } else {
+      // Otherwise sort in descending order.
+      comp = function(a, b) { return b[by] - a[by]; };
+    }
+
+    // Reset link styles and format the selected sort option.
+    $('a.sel').attr('href', '#').removeClass('sel');
+    $('a.by' + by).removeAttr('href').addClass('sel');
+  }
+
+  /**
+   * Create a comp function. If the user has preferences stored in
+   * the sortBy cookie, use those, otherwise use the default.
+   */
+  function initComparator() {
+    by = 'rating'; // Default to sort by rating.
+    // If the sortBy cookie is set, use that instead.
+    if (document.cookie.length > 0) {
+      var start = document.cookie.indexOf('sortBy=');
+      if (start != -1) {
+        start = start + 7;
+        var end = document.cookie.indexOf(";", start);
+        if (end == -1) {
+          end = document.cookie.length;
+          by = unescape(document.cookie.substring(start, end));
+        }
+      }
+    }
+    setComparator();
+  }
+
+  /**
+   * Show a comment div.
+   */
+  function show(id) {
+    $('#ao' + id).hide();
+    $('#ah' + id).show();
+    var context = $.extend({id: id}, opts);
+    var popup = $(renderTemplate(popupTemplate, context)).hide();
+    popup.find('textarea[name="proposal"]').hide();
+    popup.find('a.by' + by).addClass('sel');
+    var form = popup.find('#cf' + id);
+    form.submit(function(event) {
+      event.preventDefault();
+      addComment(form);
+    });
+    $('#s' + id).after(popup);
+    popup.slideDown('fast', function() {
+      getComments(id);
+    });
+  }
+
+  /**
+   * Hide a comment div.
+   */
+  function hide(id) {
+    $('#ah' + id).hide();
+    $('#ao' + id).show();
+    var div = $('#sc' + id);
+    div.slideUp('fast', function() {
+      div.remove();
+    });
+  }
+
+  /**
+   * Perform an ajax request to get comments for a node
+   * and insert the comments into the comments tree.
+   */
+  function getComments(id) {
+    $.ajax({
+     type: 'GET',
+     url: opts.getCommentsURL,
+     data: {node: id},
+     success: function(data, textStatus, request) {
+       var ul = $('#cl' + id);
+       var speed = 100;
+       $('#cf' + id)
+         .find('textarea[name="proposal"]')
+         .data('source', data.source);
+
+       if (data.comments.length === 0) {
+         ul.html('<li>No comments yet.</li>');
+         ul.data('empty', true);
+       } else {
+         // If there are comments, sort them and put them in the list.
+         var comments = sortComments(data.comments);
+         speed = data.comments.length * 100;
+         appendComments(comments, ul);
+         ul.data('empty', false);
+       }
+       $('#cn' + id).slideUp(speed + 200);
+       ul.slideDown(speed);
+     },
+     error: function(request, textStatus, error) {
+       showError('Oops, there was a problem retrieving the comments.');
+     },
+     dataType: 'json'
+    });
+  }
+
+  /**
+   * Add a comment via ajax and insert the comment into the comment tree.
+   */
+  function addComment(form) {
+    var node_id = form.find('input[name="node"]').val();
+    var parent_id = form.find('input[name="parent"]').val();
+    var text = form.find('textarea[name="comment"]').val();
+    var proposal = form.find('textarea[name="proposal"]').val();
+
+    if (text == '') {
+      showError('Please enter a comment.');
+      return;
+    }
+
+    // Disable the form that is being submitted.
+    form.find('textarea,input').attr('disabled', 'disabled');
+
+    // Send the comment to the server.
+    $.ajax({
+      type: "POST",
+      url: opts.addCommentURL,
+      dataType: 'json',
+      data: {
+        node: node_id,
+        parent: parent_id,
+        text: text,
+        proposal: proposal
+      },
+      success: function(data, textStatus, error) {
+        // Reset the form.
+        if (node_id) {
+          hideProposeChange(node_id);
+        }
+        form.find('textarea')
+          .val('')
+          .add(form.find('input'))
+          .removeAttr('disabled');
+	var ul = $('#cl' + (node_id || parent_id));
+        if (ul.data('empty')) {
+          $(ul).empty();
+          ul.data('empty', false);
+        }
+        insertComment(data.comment);
+        var ao = $('#ao' + node_id);
+        ao.find('img').attr({'src': opts.commentBrightImage});
+        if (node_id) {
+          // if this was a "root" comment, remove the commenting box
+          // (the user can get it back by reopening the comment popup)
+          $('#ca' + node_id).slideUp();
+        }
+      },
+      error: function(request, textStatus, error) {
+        form.find('textarea,input').removeAttr('disabled');
+        showError('Oops, there was a problem adding the comment.');
+      }
+    });
+  }
+
+  /**
+   * Recursively append comments to the main comment list and children
+   * lists, creating the comment tree.
+   */
+  function appendComments(comments, ul) {
+    $.each(comments, function() {
+      var div = createCommentDiv(this);
+      ul.append($(document.createElement('li')).html(div));
+      appendComments(this.children, div.find('ul.comment-children'));
+      // To avoid stagnating data, don't store the comments children in data.
+      this.children = null;
+      div.data('comment', this);
+    });
+  }
+
+  /**
+   * After adding a new comment, it must be inserted in the correct
+   * location in the comment tree.
+   */
+  function insertComment(comment) {
+    var div = createCommentDiv(comment);
+
+    // To avoid stagnating data, don't store the comments children in data.
+    comment.children = null;
+    div.data('comment', comment);
+
+    var ul = $('#cl' + (comment.node || comment.parent));
+    var siblings = getChildren(ul);
+
+    var li = $(document.createElement('li'));
+    li.hide();
+
+    // Determine where in the parents children list to insert this comment.
+    for(i=0; i < siblings.length; i++) {
+      if (comp(comment, siblings[i]) <= 0) {
+        $('#cd' + siblings[i].id)
+          .parent()
+          .before(li.html(div));
+        li.slideDown('fast');
+        return;
+      }
+    }
+
+    // If we get here, this comment rates lower than all the others,
+    // or it is the only comment in the list.
+    ul.append(li.html(div));
+    li.slideDown('fast');
+  }
+
+  function acceptComment(id) {
+    $.ajax({
+      type: 'POST',
+      url: opts.acceptCommentURL,
+      data: {id: id},
+      success: function(data, textStatus, request) {
+        $('#cm' + id).fadeOut('fast');
+        $('#cd' + id).removeClass('moderate');
+      },
+      error: function(request, textStatus, error) {
+        showError('Oops, there was a problem accepting the comment.');
+      }
+    });
+  }
+
+  function deleteComment(id) {
+    $.ajax({
+      type: 'POST',
+      url: opts.deleteCommentURL,
+      data: {id: id},
+      success: function(data, textStatus, request) {
+        var div = $('#cd' + id);
+        if (data == 'delete') {
+          // Moderator mode: remove the comment and all children immediately
+          div.slideUp('fast', function() {
+            div.remove();
+          });
+          return;
+        }
+        // User mode: only mark the comment as deleted
+        div
+          .find('span.user-id:first')
+          .text('[deleted]').end()
+          .find('div.comment-text:first')
+          .text('[deleted]').end()
+          .find('#cm' + id + ', #dc' + id + ', #ac' + id + ', #rc' + id +
+                ', #sp' + id + ', #hp' + id + ', #cr' + id + ', #rl' + id)
+          .remove();
+        var comment = div.data('comment');
+        comment.username = '[deleted]';
+        comment.text = '[deleted]';
+        div.data('comment', comment);
+      },
+      error: function(request, textStatus, error) {
+        showError('Oops, there was a problem deleting the comment.');
+      }
+    });
+  }
+
+  function showProposal(id) {
+    $('#sp' + id).hide();
+    $('#hp' + id).show();
+    $('#pr' + id).slideDown('fast');
+  }
+
+  function hideProposal(id) {
+    $('#hp' + id).hide();
+    $('#sp' + id).show();
+    $('#pr' + id).slideUp('fast');
+  }
+
+  function showProposeChange(id) {
+    $('#pc' + id).hide();
+    $('#hc' + id).show();
+    var textarea = $('#pt' + id);
+    textarea.val(textarea.data('source'));
+    $.fn.autogrow.resize(textarea[0]);
+    textarea.slideDown('fast');
+  }
+
+  function hideProposeChange(id) {
+    $('#hc' + id).hide();
+    $('#pc' + id).show();
+    var textarea = $('#pt' + id);
+    textarea.val('').removeAttr('disabled');
+    textarea.slideUp('fast');
+  }
+
+  function toggleCommentMarkupBox(id) {
+    $('#mb' + id).toggle();
+  }
+
+  /** Handle when the user clicks on a sort by link. */
+  function handleReSort(link) {
+    var classes = link.attr('class').split(/\s+/);
+    for (var i=0; i<classes.length; i++) {
+      if (classes[i] != 'sort-option') {
+	by = classes[i].substring(2);
+      }
+    }
+    setComparator();
+    // Save/update the sortBy cookie.
+    var expiration = new Date();
+    expiration.setDate(expiration.getDate() + 365);
+    document.cookie= 'sortBy=' + escape(by) +
+                     ';expires=' + expiration.toUTCString();
+    $('ul.comment-ul').each(function(index, ul) {
+      var comments = getChildren($(ul), true);
+      comments = sortComments(comments);
+      appendComments(comments, $(ul).empty());
+    });
+  }
+
+  /**
+   * Function to process a vote when a user clicks an arrow.
+   */
+  function handleVote(link) {
+    if (!opts.voting) {
+      showError("You'll need to login to vote.");
+      return;
+    }
+
+    var id = link.attr('id');
+    if (!id) {
+      // Didn't click on one of the voting arrows.
+      return;
+    }
+    // If it is an unvote, the new vote value is 0,
+    // Otherwise it's 1 for an upvote, or -1 for a downvote.
+    var value = 0;
+    if (id.charAt(1) != 'u') {
+      value = id.charAt(0) == 'u' ? 1 : -1;
+    }
+    // The data to be sent to the server.
+    var d = {
+      comment_id: id.substring(2),
+      value: value
+    };
+
+    // Swap the vote and unvote links.
+    link.hide();
+    $('#' + id.charAt(0) + (id.charAt(1) == 'u' ? 'v' : 'u') + d.comment_id)
+      .show();
+
+    // The div the comment is displayed in.
+    var div = $('div#cd' + d.comment_id);
+    var data = div.data('comment');
+
+    // If this is not an unvote, and the other vote arrow has
+    // already been pressed, unpress it.
+    if ((d.value !== 0) && (data.vote === d.value * -1)) {
+      $('#' + (d.value == 1 ? 'd' : 'u') + 'u' + d.comment_id).hide();
+      $('#' + (d.value == 1 ? 'd' : 'u') + 'v' + d.comment_id).show();
+    }
+
+    // Update the comments rating in the local data.
+    data.rating += (data.vote === 0) ? d.value : (d.value - data.vote);
+    data.vote = d.value;
+    div.data('comment', data);
+
+    // Change the rating text.
+    div.find('.rating:first')
+      .text(data.rating + ' point' + (data.rating == 1 ? '' : 's'));
+
+    // Send the vote information to the server.
+    $.ajax({
+      type: "POST",
+      url: opts.processVoteURL,
+      data: d,
+      error: function(request, textStatus, error) {
+        showError('Oops, there was a problem casting that vote.');
+      }
+    });
+  }
+
+  /**
+   * Open a reply form used to reply to an existing comment.
+   */
+  function openReply(id) {
+    // Swap out the reply link for the hide link
+    $('#rl' + id).hide();
+    $('#cr' + id).show();
+
+    // Add the reply li to the children ul.
+    var div = $(renderTemplate(replyTemplate, {id: id})).hide();
+    $('#cl' + id)
+      .prepend(div)
+      // Setup the submit handler for the reply form.
+      .find('#rf' + id)
+      .submit(function(event) {
+        event.preventDefault();
+        addComment($('#rf' + id));
+        closeReply(id);
+      })
+      .find('input[type=button]')
+      .click(function() {
+        closeReply(id);
+      });
+    div.slideDown('fast', function() {
+      $('#rf' + id).find('textarea').focus();
+    });
+  }
+
+  /**
+   * Close the reply form opened with openReply.
+   */
+  function closeReply(id) {
+    // Remove the reply div from the DOM.
+    $('#rd' + id).slideUp('fast', function() {
+      $(this).remove();
+    });
+
+    // Swap out the hide link for the reply link
+    $('#cr' + id).hide();
+    $('#rl' + id).show();
+  }
+
+  /**
+   * Recursively sort a tree of comments using the comp comparator.
+   */
+  function sortComments(comments) {
+    comments.sort(comp);
+    $.each(comments, function() {
+      this.children = sortComments(this.children);
+    });
+    return comments;
+  }
+
+  /**
+   * Get the children comments from a ul. If recursive is true,
+   * recursively include childrens' children.
+   */
+  function getChildren(ul, recursive) {
+    var children = [];
+    ul.children().children("[id^='cd']")
+      .each(function() {
+        var comment = $(this).data('comment');
+        if (recursive)
+          comment.children = getChildren($(this).find('#cl' + comment.id), true);
+        children.push(comment);
+      });
+    return children;
+  }
+
+  /** Create a div to display a comment in. */
+  function createCommentDiv(comment) {
+    if (!comment.displayed && !opts.moderator) {
+      return $('<div class="moderate">Thank you!  Your comment will show up '
+               + 'once it is has been approved by a moderator.</div>');
+    }
+    // Prettify the comment rating.
+    comment.pretty_rating = comment.rating + ' point' +
+      (comment.rating == 1 ? '' : 's');
+    // Make a class (for displaying not yet moderated comments differently)
+    comment.css_class = comment.displayed ? '' : ' moderate';
+    // Create a div for this comment.
+    var context = $.extend({}, opts, comment);
+    var div = $(renderTemplate(commentTemplate, context));
+
+    // If the user has voted on this comment, highlight the correct arrow.
+    if (comment.vote) {
+      var direction = (comment.vote == 1) ? 'u' : 'd';
+      div.find('#' + direction + 'v' + comment.id).hide();
+      div.find('#' + direction + 'u' + comment.id).show();
+    }
+
+    if (opts.moderator || comment.text != '[deleted]') {
+      div.find('a.reply').show();
+      if (comment.proposal_diff)
+        div.find('#sp' + comment.id).show();
+      if (opts.moderator && !comment.displayed)
+        div.find('#cm' + comment.id).show();
+      if (opts.moderator || (opts.username == comment.username))
+        div.find('#dc' + comment.id).show();
+    }
+    return div;
+  }
+
+  /**
+   * A simple template renderer. Placeholders such as <%id%> are replaced
+   * by context['id'] with items being escaped. Placeholders such as <#id#>
+   * are not escaped.
+   */
+  function renderTemplate(template, context) {
+    var esc = $(document.createElement('div'));
+
+    function handle(ph, escape) {
+      var cur = context;
+      $.each(ph.split('.'), function() {
+        cur = cur[this];
+      });
+      return escape ? esc.text(cur || "").html() : cur;
+    }
+
+    return template.replace(/<([%#])([\w\.]*)\1>/g, function() {
+      return handle(arguments[2], arguments[1] == '%' ? true : false);
+    });
+  }
+
+  /** Flash an error message briefly. */
+  function showError(message) {
+    $(document.createElement('div')).attr({'class': 'popup-error'})
+      .append($(document.createElement('div'))
+               .attr({'class': 'error-message'}).text(message))
+      .appendTo('body')
+      .fadeIn("slow")
+      .delay(2000)
+      .fadeOut("slow");
+  }
+
+  /** Add a link the user uses to open the comments popup. */
+  $.fn.comment = function() {
+    return this.each(function() {
+      var id = $(this).attr('id').substring(1);
+      var count = COMMENT_METADATA[id];
+      var title = count + ' comment' + (count == 1 ? '' : 's');
+      var image = count > 0 ? opts.commentBrightImage : opts.commentImage;
+      var addcls = count == 0 ? ' nocomment' : '';
+      $(this)
+        .append(
+          $(document.createElement('a')).attr({
+            href: '#',
+            'class': 'sphinx-comment-open' + addcls,
+            id: 'ao' + id
+          })
+            .append($(document.createElement('img')).attr({
+              src: image,
+              alt: 'comment',
+              title: title
+            }))
+            .click(function(event) {
+              event.preventDefault();
+              show($(this).attr('id').substring(2));
+            })
+        )
+        .append(
+          $(document.createElement('a')).attr({
+            href: '#',
+            'class': 'sphinx-comment-close hidden',
+            id: 'ah' + id
+          })
+            .append($(document.createElement('img')).attr({
+              src: opts.closeCommentImage,
+              alt: 'close',
+              title: 'close'
+            }))
+            .click(function(event) {
+              event.preventDefault();
+              hide($(this).attr('id').substring(2));
+            })
+        );
+    });
+  };
+
+  var opts = {
+    processVoteURL: '/_process_vote',
+    addCommentURL: '/_add_comment',
+    getCommentsURL: '/_get_comments',
+    acceptCommentURL: '/_accept_comment',
+    deleteCommentURL: '/_delete_comment',
+    commentImage: '/static/_static/comment.png',
+    closeCommentImage: '/static/_static/comment-close.png',
+    loadingImage: '/static/_static/ajax-loader.gif',
+    commentBrightImage: '/static/_static/comment-bright.png',
+    upArrow: '/static/_static/up.png',
+    downArrow: '/static/_static/down.png',
+    upArrowPressed: '/static/_static/up-pressed.png',
+    downArrowPressed: '/static/_static/down-pressed.png',
+    voting: false,
+    moderator: false
+  };
+
+  if (typeof COMMENT_OPTIONS != "undefined") {
+    opts = jQuery.extend(opts, COMMENT_OPTIONS);
+  }
+
+  var popupTemplate = '\
+    <div class="sphinx-comments" id="sc<%id%>">\
+      <p class="sort-options">\
+        Sort by:\
+        <a href="#" class="sort-option byrating">best rated</a>\
+        <a href="#" class="sort-option byascage">newest</a>\
+        <a href="#" class="sort-option byage">oldest</a>\
+      </p>\
+      <div class="comment-header">Comments</div>\
+      <div class="comment-loading" id="cn<%id%>">\
+        loading comments... <img src="<%loadingImage%>" alt="" /></div>\
+      <ul id="cl<%id%>" class="comment-ul"></ul>\
+      <div id="ca<%id%>">\
+      <p class="add-a-comment">Add a comment\
+        (<a href="#" class="comment-markup" id="ab<%id%>">markup</a>):</p>\
+      <div class="comment-markup-box" id="mb<%id%>">\
+        reStructured text markup: <i>*emph*</i>, <b>**strong**</b>, \
+        <tt>``code``</tt>, \
+        code blocks: <tt>::</tt> and an indented block after blank line</div>\
+      <form method="post" id="cf<%id%>" class="comment-form" action="">\
+        <textarea name="comment" cols="80"></textarea>\
+        <p class="propose-button">\
+          <a href="#" id="pc<%id%>" class="show-propose-change">\
+            Propose a change &#9657;\
+          </a>\
+          <a href="#" id="hc<%id%>" class="hide-propose-change">\
+            Propose a change &#9663;\
+          </a>\
+        </p>\
+        <textarea name="proposal" id="pt<%id%>" cols="80"\
+                  spellcheck="false"></textarea>\
+        <input type="submit" value="Add comment" />\
+        <input type="hidden" name="node" value="<%id%>" />\
+        <input type="hidden" name="parent" value="" />\
+      </form>\
+      </div>\
+    </div>';
+
+  var commentTemplate = '\
+    <div id="cd<%id%>" class="sphinx-comment<%css_class%>">\
+      <div class="vote">\
+        <div class="arrow">\
+          <a href="#" id="uv<%id%>" class="vote" title="vote up">\
+            <img src="<%upArrow%>" />\
+          </a>\
+          <a href="#" id="uu<%id%>" class="un vote" title="vote up">\
+            <img src="<%upArrowPressed%>" />\
+          </a>\
+        </div>\
+        <div class="arrow">\
+          <a href="#" id="dv<%id%>" class="vote" title="vote down">\
+            <img src="<%downArrow%>" id="da<%id%>" />\
+          </a>\
+          <a href="#" id="du<%id%>" class="un vote" title="vote down">\
+            <img src="<%downArrowPressed%>" />\
+          </a>\
+        </div>\
+      </div>\
+      <div class="comment-content">\
+        <p class="tagline comment">\
+          <span class="user-id"><%username%></span>\
+          <span class="rating"><%pretty_rating%></span>\
+          <span class="delta"><%time.delta%></span>\
+        </p>\
+        <div class="comment-text comment"><#text#></div>\
+        <p class="comment-opts comment">\
+          <a href="#" class="reply hidden" id="rl<%id%>">reply &#9657;</a>\
+          <a href="#" class="close-reply" id="cr<%id%>">reply &#9663;</a>\
+          <a href="#" id="sp<%id%>" class="show-proposal">proposal &#9657;</a>\
+          <a href="#" id="hp<%id%>" class="hide-proposal">proposal &#9663;</a>\
+          <a href="#" id="dc<%id%>" class="delete-comment hidden">delete</a>\
+          <span id="cm<%id%>" class="moderation hidden">\
+            <a href="#" id="ac<%id%>" class="accept-comment">accept</a>\
+          </span>\
+        </p>\
+        <pre class="proposal" id="pr<%id%>">\
+<#proposal_diff#>\
+        </pre>\
+          <ul class="comment-children" id="cl<%id%>"></ul>\
+        </div>\
+        <div class="clearleft"></div>\
+      </div>\
+    </div>';
+
+  var replyTemplate = '\
+    <li>\
+      <div class="reply-div" id="rd<%id%>">\
+        <form id="rf<%id%>">\
+          <textarea name="comment" cols="80"></textarea>\
+          <input type="submit" value="Add reply" />\
+          <input type="button" value="Cancel" />\
+          <input type="hidden" name="parent" value="<%id%>" />\
+          <input type="hidden" name="node" value="" />\
+        </form>\
+      </div>\
+    </li>';
+
+  $(document).ready(function() {
+    init();
+  });
+})(jQuery);
+
+$(document).ready(function() {
+  // add comment anchors for all paragraphs that are commentable
+  $('.sphinx-has-comment').comment();
+
+  // highlight search words in search results
+  $("div.context").each(function() {
+    var params = $.getQueryParameters();
+    var terms = (params.q) ? params.q[0].split(/\s+/) : [];
+    var result = $(this);
+    $.each(terms, function() {
+      result.highlightText(this.toLowerCase(), 'highlighted');
+    });
+  });
+
+  // directly open comment window if requested
+  var anchor = document.location.hash;
+  if (anchor.substring(0, 9) == '#comment-') {
+    $('#ao' + anchor.substring(9)).click();
+    document.location.hash = '#s' + anchor.substring(9);
+  }
+});

genindex.html

@@ -0,0 +1,299 @@
+
+
+
+
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
+  "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
+
+
+<html xmlns="http://www.w3.org/1999/xhtml">
+  <head>
+    <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
+    
+    <title>Index &mdash; alsaaudio 0.8 documentation</title>
+    
+    <link rel="stylesheet" href="_static/default.css" type="text/css" />
+    <link rel="stylesheet" href="_static/pygments.css" type="text/css" />
+    
+    <script type="text/javascript">
+      var DOCUMENTATION_OPTIONS = {
+        URL_ROOT:    '',
+        VERSION:     '0.8',
+        COLLAPSE_INDEX: false,
+        FILE_SUFFIX: '.html',
+        HAS_SOURCE:  true
+      };
+    </script>
+    <script type="text/javascript" src="_static/jquery.js"></script>
+    <script type="text/javascript" src="_static/underscore.js"></script>
+    <script type="text/javascript" src="_static/doctools.js"></script>
+    <link rel="top" title="alsaaudio 0.8 documentation" href="index.html" /> 
+  </head>
+  <body>
+    <div class="related">
+      <h3>Navigation</h3>
+      <ul>
+        <li class="right" style="margin-right: 10px">
+          <a href="#" title="General Index"
+             accesskey="I">index</a></li>
+        <li class="right" >
+          <a href="py-modindex.html" title="Python Module Index"
+             >modules</a> |</li>
+        <li><a href="index.html">alsaaudio 0.8 documentation</a> &raquo;</li> 
+      </ul>
+    </div>  
+
+    <div class="document">
+      <div class="documentwrapper">
+        <div class="bodywrapper">
+          <div class="body">
+            
+
+<h1 id="index">Index</h1>
+
+<div class="genindex-jumpbox">
+ <a href="#A"><strong>A</strong></a>
+ | <a href="#C"><strong>C</strong></a>
+ | <a href="#G"><strong>G</strong></a>
+ | <a href="#M"><strong>M</strong></a>
+ | <a href="#P"><strong>P</strong></a>
+ | <a href="#R"><strong>R</strong></a>
+ | <a href="#S"><strong>S</strong></a>
+ | <a href="#V"><strong>V</strong></a>
+ | <a href="#W"><strong>W</strong></a>
+ 
+</div>
+<h2 id="A">A</h2>
+<table style="width: 100%" class="indextable genindextable"><tr>
+  <td style="width: 33%" valign="top"><dl>
+      
+  <dt><a href="libalsaaudio.html#module-alsaaudio">alsaaudio (module)</a>
+  </dt>
+
+  </dl></td>
+  <td style="width: 33%" valign="top"><dl>
+      
+  <dt><a href="libalsaaudio.html#alsaaudio.ALSAAudioError">ALSAAudioError</a>
+  </dt>
+
+  </dl></td>
+</tr></table>
+
+<h2 id="C">C</h2>
+<table style="width: 100%" class="indextable genindextable"><tr>
+  <td style="width: 33%" valign="top"><dl>
+      
+  <dt><a href="libalsaaudio.html#alsaaudio.Mixer.cardname">cardname() (alsaaudio.Mixer method)</a>
+  </dt>
+
+      <dd><dl>
+        
+  <dt><a href="libalsaaudio.html#alsaaudio.PCM.cardname">(alsaaudio.PCM method)</a>
+  </dt>
+
+      </dl></dd>
+  </dl></td>
+  <td style="width: 33%" valign="top"><dl>
+      
+  <dt><a href="libalsaaudio.html#alsaaudio.cards">cards() (in module alsaaudio)</a>
+  </dt>
+
+  </dl></td>
+</tr></table>
+
+<h2 id="G">G</h2>
+<table style="width: 100%" class="indextable genindextable"><tr>
+  <td style="width: 33%" valign="top"><dl>
+      
+  <dt><a href="libalsaaudio.html#alsaaudio.Mixer.getenum">getenum() (alsaaudio.Mixer method)</a>
+  </dt>
+
+      
+  <dt><a href="libalsaaudio.html#alsaaudio.Mixer.getmute">getmute() (alsaaudio.Mixer method)</a>
+  </dt>
+
+      
+  <dt><a href="libalsaaudio.html#alsaaudio.Mixer.getrange">getrange() (alsaaudio.Mixer method)</a>
+  </dt>
+
+  </dl></td>
+  <td style="width: 33%" valign="top"><dl>
+      
+  <dt><a href="libalsaaudio.html#alsaaudio.Mixer.getrec">getrec() (alsaaudio.Mixer method)</a>
+  </dt>
+
+      
+  <dt><a href="libalsaaudio.html#alsaaudio.Mixer.getvolume">getvolume() (alsaaudio.Mixer method)</a>
+  </dt>
+
+  </dl></td>
+</tr></table>
+
+<h2 id="M">M</h2>
+<table style="width: 100%" class="indextable genindextable"><tr>
+  <td style="width: 33%" valign="top"><dl>
+      
+  <dt><a href="libalsaaudio.html#alsaaudio.Mixer">Mixer (class in alsaaudio)</a>, <a href="libalsaaudio.html#alsaaudio.Mixer">[1]</a>
+  </dt>
+
+      
+  <dt><a href="libalsaaudio.html#alsaaudio.Mixer.mixer">mixer() (alsaaudio.Mixer method)</a>
+  </dt>
+
+  </dl></td>
+  <td style="width: 33%" valign="top"><dl>
+      
+  <dt><a href="libalsaaudio.html#alsaaudio.Mixer.mixerid">mixerid() (alsaaudio.Mixer method)</a>
+  </dt>
+
+      
+  <dt><a href="libalsaaudio.html#alsaaudio.mixers">mixers() (in module alsaaudio)</a>
+  </dt>
+
+  </dl></td>
+</tr></table>
+
+<h2 id="P">P</h2>
+<table style="width: 100%" class="indextable genindextable"><tr>
+  <td style="width: 33%" valign="top"><dl>
+      
+  <dt><a href="libalsaaudio.html#alsaaudio.PCM.pause">pause() (alsaaudio.PCM method)</a>
+  </dt>
+
+      
+  <dt><a href="libalsaaudio.html#alsaaudio.PCM">PCM (class in alsaaudio)</a>, <a href="libalsaaudio.html#alsaaudio.PCM">[1]</a>
+  </dt>
+
+      
+  <dt><a href="libalsaaudio.html#alsaaudio.PCM.pcmmode">pcmmode() (alsaaudio.PCM method)</a>
+  </dt>
+
+  </dl></td>
+  <td style="width: 33%" valign="top"><dl>
+      
+  <dt><a href="libalsaaudio.html#alsaaudio.PCM.pcmtype">pcmtype() (alsaaudio.PCM method)</a>
+  </dt>
+
+      
+  <dt><a href="libalsaaudio.html#alsaaudio.Mixer.polldescriptors">polldescriptors() (alsaaudio.Mixer method)</a>
+  </dt>
+
+  </dl></td>
+</tr></table>
+
+<h2 id="R">R</h2>
+<table style="width: 100%" class="indextable genindextable"><tr>
+  <td style="width: 33%" valign="top"><dl>
+      
+  <dt><a href="libalsaaudio.html#alsaaudio.PCM.read">read() (alsaaudio.PCM method)</a>
+  </dt>
+
+  </dl></td>
+</tr></table>
+
+<h2 id="S">S</h2>
+<table style="width: 100%" class="indextable genindextable"><tr>
+  <td style="width: 33%" valign="top"><dl>
+      
+  <dt><a href="libalsaaudio.html#alsaaudio.PCM.setchannels">setchannels() (alsaaudio.PCM method)</a>
+  </dt>
+
+      
+  <dt><a href="libalsaaudio.html#alsaaudio.PCM.setformat">setformat() (alsaaudio.PCM method)</a>
+  </dt>
+
+      
+  <dt><a href="libalsaaudio.html#alsaaudio.Mixer.setmute">setmute() (alsaaudio.Mixer method)</a>
+  </dt>
+
+      
+  <dt><a href="libalsaaudio.html#alsaaudio.PCM.setperiodsize">setperiodsize() (alsaaudio.PCM method)</a>
+  </dt>
+
+  </dl></td>
+  <td style="width: 33%" valign="top"><dl>
+      
+  <dt><a href="libalsaaudio.html#alsaaudio.PCM.setrate">setrate() (alsaaudio.PCM method)</a>
+  </dt>
+
+      
+  <dt><a href="libalsaaudio.html#alsaaudio.Mixer.setrec">setrec() (alsaaudio.Mixer method)</a>
+  </dt>
+
+      
+  <dt><a href="libalsaaudio.html#alsaaudio.Mixer.setvolume">setvolume() (alsaaudio.Mixer method)</a>
+  </dt>
+
+      
+  <dt><a href="libalsaaudio.html#alsaaudio.Mixer.switchcap">switchcap() (alsaaudio.Mixer method)</a>
+  </dt>
+
+  </dl></td>
+</tr></table>
+
+<h2 id="V">V</h2>
+<table style="width: 100%" class="indextable genindextable"><tr>
+  <td style="width: 33%" valign="top"><dl>
+      
+  <dt><a href="libalsaaudio.html#alsaaudio.Mixer.volumecap">volumecap() (alsaaudio.Mixer method)</a>
+  </dt>
+
+  </dl></td>
+</tr></table>
+
+<h2 id="W">W</h2>
+<table style="width: 100%" class="indextable genindextable"><tr>
+  <td style="width: 33%" valign="top"><dl>
+      
+  <dt><a href="libalsaaudio.html#alsaaudio.PCM.write">write() (alsaaudio.PCM method)</a>
+  </dt>
+
+  </dl></td>
+</tr></table>
+
+
+
+          </div>
+        </div>
+      </div>
+      <div class="sphinxsidebar">
+        <div class="sphinxsidebarwrapper">
+
+   
+
+<div id="searchbox" style="display: none">
+  <h3>Quick search</h3>
+    <form class="search" action="search.html" method="get">
+      <input type="text" name="q" />
+      <input type="submit" value="Go" />
+      <input type="hidden" name="check_keywords" value="yes" />
+      <input type="hidden" name="area" value="default" />
+    </form>
+    <p class="searchtip" style="font-size: 90%">
+    Enter search terms or a module, class or function name.
+    </p>
+</div>
+<script type="text/javascript">$('#searchbox').show(0);</script>
+        </div>
+      </div>
+      <div class="clearer"></div>
+    </div>
+    <div class="related">
+      <h3>Navigation</h3>
+      <ul>
+        <li class="right" style="margin-right: 10px">
+          <a href="#" title="General Index"
+             >index</a></li>
+        <li class="right" >
+          <a href="py-modindex.html" title="Python Module Index"
+             >modules</a> |</li>
+        <li><a href="index.html">alsaaudio 0.8 documentation</a> &raquo;</li> 
+      </ul>
+    </div>
+    <div class="footer">
+        &copy; Copyright 2008-2009, Casper Wilstrup, Lars Immisch.
+      Last updated on Apr 30, 2015.
+      Created using <a href="http://sphinx.pocoo.org/">Sphinx</a> 1.1.3.
+    </div>
+  </body>
+</html>

index.html

@@ -0,0 +1,152 @@
+
+
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
+  "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
+
+
+<html xmlns="http://www.w3.org/1999/xhtml">
+  <head>
+    <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
+    
+    <title>alsaaudio documentation &mdash; alsaaudio 0.8 documentation</title>
+    
+    <link rel="stylesheet" href="_static/default.css" type="text/css" />
+    <link rel="stylesheet" href="_static/pygments.css" type="text/css" />
+    
+    <script type="text/javascript">
+      var DOCUMENTATION_OPTIONS = {
+        URL_ROOT:    '',
+        VERSION:     '0.8',
+        COLLAPSE_INDEX: false,
+        FILE_SUFFIX: '.html',
+        HAS_SOURCE:  true
+      };
+    </script>
+    <script type="text/javascript" src="_static/jquery.js"></script>
+    <script type="text/javascript" src="_static/underscore.js"></script>
+    <script type="text/javascript" src="_static/doctools.js"></script>
+    <link rel="top" title="alsaaudio 0.8 documentation" href="#" />
+    <link rel="next" title="Introduction" href="pyalsaaudio.html" /> 
+  </head>
+  <body>
+    <div class="related">
+      <h3>Navigation</h3>
+      <ul>
+        <li class="right" style="margin-right: 10px">
+          <a href="genindex.html" title="General Index"
+             accesskey="I">index</a></li>
+        <li class="right" >
+          <a href="py-modindex.html" title="Python Module Index"
+             >modules</a> |</li>
+        <li class="right" >
+          <a href="pyalsaaudio.html" title="Introduction"
+             accesskey="N">next</a> |</li>
+        <li><a href="#">alsaaudio 0.8 documentation</a> &raquo;</li> 
+      </ul>
+    </div>  
+
+    <div class="document">
+      <div class="documentwrapper">
+        <div class="bodywrapper">
+          <div class="body">
+            
+  <div class="section" id="alsaaudio-documentation">
+<h1>alsaaudio documentation<a class="headerlink" href="#alsaaudio-documentation" title="Permalink to this headline">¶</a></h1>
+<div class="toctree-wrapper compound">
+<ul>
+<li class="toctree-l1"><a class="reference internal" href="pyalsaaudio.html">Introduction</a></li>
+<li class="toctree-l1"><a class="reference internal" href="pyalsaaudio.html#what-is-alsa">What is ALSA</a><ul>
+<li class="toctree-l2"><a class="reference internal" href="pyalsaaudio.html#alsa-and-python">ALSA and Python</a></li>
+</ul>
+</li>
+<li class="toctree-l1"><a class="reference internal" href="pyalsaaudio.html#installation">Installation</a></li>
+<li class="toctree-l1"><a class="reference internal" href="pyalsaaudio.html#testing">Testing</a></li>
+<li class="toctree-l1"><a class="reference internal" href="terminology.html">PCM Terminology and Concepts</a></li>
+<li class="toctree-l1"><a class="reference internal" href="libalsaaudio.html"><tt class="docutils literal"><span class="pre">alsaaudio</span></tt></a><ul>
+<li class="toctree-l2"><a class="reference internal" href="libalsaaudio.html#pcm-objects">PCM Objects</a></li>
+<li class="toctree-l2"><a class="reference internal" href="libalsaaudio.html#mixer-objects">Mixer Objects</a></li>
+<li class="toctree-l2"><a class="reference internal" href="libalsaaudio.html#examples">Examples</a></li>
+</ul>
+</li>
+</ul>
+</div>
+</div>
+<div class="section" id="github-pages">
+<h1>Github pages<a class="headerlink" href="#github-pages" title="Permalink to this headline">¶</a></h1>
+<ul class="simple">
+<li><a class="reference external" href="https://github.com/larsimmisch/pyalsaaudio/">Project page</a></li>
+<li><a class="reference external" href="https://pypi.python.org/pypi/pyalsaaudio">Download from pypi:</a></li>
+<li><a class="reference external" href="https://github.com/larsimmisch/pyalsaaudio/issues">Bug tracker</a></li>
+</ul>
+</div>
+<div class="section" id="indices-and-tables">
+<h1>Indices and tables<a class="headerlink" href="#indices-and-tables" title="Permalink to this headline">¶</a></h1>
+<ul class="simple">
+<li><a class="reference internal" href="genindex.html"><em>Index</em></a></li>
+<li><a class="reference internal" href="py-modindex.html"><em>Module Index</em></a></li>
+<li><a class="reference internal" href="search.html"><em>Search Page</em></a></li>
+</ul>
+</div>
+
+
+          </div>
+        </div>
+      </div>
+      <div class="sphinxsidebar">
+        <div class="sphinxsidebarwrapper">
+  <h3><a href="#">Table Of Contents</a></h3>
+  <ul>
+<li><a class="reference internal" href="#">alsaaudio documentation</a><ul>
+</ul>
+</li>
+<li><a class="reference internal" href="#github-pages">Github pages</a></li>
+<li><a class="reference internal" href="#indices-and-tables">Indices and tables</a></li>
+</ul>
+
+  <h4>Next topic</h4>
+  <p class="topless"><a href="pyalsaaudio.html"
+                        title="next chapter">Introduction</a></p>
+  <h3>This Page</h3>
+  <ul class="this-page-menu">
+    <li><a href="_sources/index.txt"
+           rel="nofollow">Show Source</a></li>
+  </ul>
+<div id="searchbox" style="display: none">
+  <h3>Quick search</h3>
+    <form class="search" action="search.html" method="get">
+      <input type="text" name="q" />
+      <input type="submit" value="Go" />
+      <input type="hidden" name="check_keywords" value="yes" />
+      <input type="hidden" name="area" value="default" />
+    </form>
+    <p class="searchtip" style="font-size: 90%">
+    Enter search terms or a module, class or function name.
+    </p>
+</div>
+<script type="text/javascript">$('#searchbox').show(0);</script>
+        </div>
+      </div>
+      <div class="clearer"></div>
+    </div>
+    <div class="related">
+      <h3>Navigation</h3>
+      <ul>
+        <li class="right" style="margin-right: 10px">
+          <a href="genindex.html" title="General Index"
+             >index</a></li>
+        <li class="right" >
+          <a href="py-modindex.html" title="Python Module Index"
+             >modules</a> |</li>
+        <li class="right" >
+          <a href="pyalsaaudio.html" title="Introduction"
+             >next</a> |</li>
+        <li><a href="#">alsaaudio 0.8 documentation</a> &raquo;</li> 
+      </ul>
+    </div>
+    <div class="footer">
+        &copy; Copyright 2008-2009, Casper Wilstrup, Lars Immisch.
+      Last updated on Apr 30, 2015.
+      Created using <a href="http://sphinx.pocoo.org/">Sphinx</a> 1.1.3.
+    </div>
+  </body>
+</html>

libalsaaudio.html

@@ -0,0 +1,729 @@
+
+
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
+  "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
+
+
+<html xmlns="http://www.w3.org/1999/xhtml">
+  <head>
+    <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
+    
+    <title>alsaaudio &mdash; alsaaudio 0.8 documentation</title>
+    
+    <link rel="stylesheet" href="_static/default.css" type="text/css" />
+    <link rel="stylesheet" href="_static/pygments.css" type="text/css" />
+    
+    <script type="text/javascript">
+      var DOCUMENTATION_OPTIONS = {
+        URL_ROOT:    '',
+        VERSION:     '0.8',
+        COLLAPSE_INDEX: false,
+        FILE_SUFFIX: '.html',
+        HAS_SOURCE:  true
+      };
+    </script>
+    <script type="text/javascript" src="_static/jquery.js"></script>
+    <script type="text/javascript" src="_static/underscore.js"></script>
+    <script type="text/javascript" src="_static/doctools.js"></script>
+    <link rel="top" title="alsaaudio 0.8 documentation" href="index.html" />
+    <link rel="prev" title="PCM Terminology and Concepts" href="terminology.html" /> 
+  </head>
+  <body>
+    <div class="related">
+      <h3>Navigation</h3>
+      <ul>
+        <li class="right" style="margin-right: 10px">
+          <a href="genindex.html" title="General Index"
+             accesskey="I">index</a></li>
+        <li class="right" >
+          <a href="py-modindex.html" title="Python Module Index"
+             >modules</a> |</li>
+        <li class="right" >
+          <a href="terminology.html" title="PCM Terminology and Concepts"
+             accesskey="P">previous</a> |</li>
+        <li><a href="index.html">alsaaudio 0.8 documentation</a> &raquo;</li> 
+      </ul>
+    </div>  
+
+    <div class="document">
+      <div class="documentwrapper">
+        <div class="bodywrapper">
+          <div class="body">
+            
+  <div class="section" id="module-alsaaudio">
+<span id="alsaaudio"></span><h1><a class="reference internal" href="#module-alsaaudio" title="alsaaudio (Linux)"><tt class="xref py py-mod docutils literal"><span class="pre">alsaaudio</span></tt></a><a class="headerlink" href="#module-alsaaudio" title="Permalink to this headline">¶</a></h1>
+<p>The <a class="reference internal" href="#module-alsaaudio" title="alsaaudio (Linux)"><tt class="xref py py-mod docutils literal"><span class="pre">alsaaudio</span></tt></a> module defines functions and classes for using ALSA.</p>
+<dl class="function">
+<dt id="alsaaudio.cards">
+<tt class="descclassname">alsaaudio.</tt><tt class="descname">cards</tt><big>(</big><big>)</big><a class="headerlink" href="#alsaaudio.cards" title="Permalink to this definition">¶</a></dt>
+<dd><p>List the available cards by name (suitable for PCM objects).</p>
+</dd></dl>
+
+<dl class="function">
+<dt id="alsaaudio.mixers">
+<tt class="descclassname">alsaaudio.</tt><tt class="descname">mixers</tt><big>(</big><span class="optional">[</span><em>cardindex</em><span class="optional">]</span><big>)</big><a class="headerlink" href="#alsaaudio.mixers" title="Permalink to this definition">¶</a></dt>
+<dd><p>List the available mixers. The optional <em>cardindex</em> specifies which card
+should be queried. The default is 0.</p>
+</dd></dl>
+
+<dl class="class">
+<dt id="alsaaudio.PCM">
+<em class="property">class </em><tt class="descclassname">alsaaudio.</tt><tt class="descname">PCM</tt><big>(</big><em>type=PCM_PLAYBACK</em>, <em>mode=PCM_NORMAL</em>, <em>card='default'</em><big>)</big><a class="headerlink" href="#alsaaudio.PCM" title="Permalink to this definition">¶</a></dt>
+<dd><p>This class is used to represent a PCM device (both for playback and
+recording - capture). The arguments are:</p>
+<ul class="simple">
+<li><em>type</em> - can be either <tt class="docutils literal"><span class="pre">PCM_CAPTURE</span></tt> or <tt class="docutils literal"><span class="pre">PCM_PLAYBACK</span></tt> (default).</li>
+<li><em>mode</em> - can be either <tt class="docutils literal"><span class="pre">PCM_NONBLOCK</span></tt>, or <tt class="docutils literal"><span class="pre">PCM_NORMAL</span></tt> (default).</li>
+<li><em>card</em> - specifies the name of the card that should be used.</li>
+</ul>
+</dd></dl>
+
+<dl class="class">
+<dt id="alsaaudio.Mixer">
+<em class="property">class </em><tt class="descclassname">alsaaudio.</tt><tt class="descname">Mixer</tt><big>(</big><em>control='Master'</em>, <em>id=0</em>, <em>cardindex=0</em><big>)</big><a class="headerlink" href="#alsaaudio.Mixer" title="Permalink to this definition">¶</a></dt>
+<dd><p>This class is used to access a specific ALSA mixer. The arguments
+are:</p>
+<ul class="simple">
+<li><em>control</em> - Name of the chosen mixed (default is &#8216;Master&#8217;).</li>
+<li><em>id</em> - id of mixer &#8211; More explanation needed here</li>
+<li><em>cardindex</em>  specifies which card should be used.</li>
+</ul>
+</dd></dl>
+
+<dl class="exception">
+<dt id="alsaaudio.ALSAAudioError">
+<em class="property">exception </em><tt class="descclassname">alsaaudio.</tt><tt class="descname">ALSAAudioError</tt><a class="headerlink" href="#alsaaudio.ALSAAudioError" title="Permalink to this definition">¶</a></dt>
+<dd><p>Exception raised when an operation fails for a ALSA specific reason. The
+exception argument is a string describing the reason of the failure.</p>
+</dd></dl>
+
+<div class="section" id="pcm-objects">
+<span id="id1"></span><h2>PCM Objects<a class="headerlink" href="#pcm-objects" title="Permalink to this headline">¶</a></h2>
+<p>PCM objects in <a class="reference internal" href="#module-alsaaudio" title="alsaaudio (Linux)"><tt class="xref py py-mod docutils literal"><span class="pre">alsaaudio</span></tt></a> can play or capture (record) PCM
+sound through speakers or a microphone. The PCM constructor takes the
+following arguments:</p>
+<dl class="class">
+<dt>
+<em class="property">class </em><tt class="descclassname">alsaaudio.</tt><tt class="descname">PCM</tt><big>(</big><em>type=PCM_CAPTURE</em>, <em>mode=PCM_NORMAL</em>, <em>card='default'</em><big>)</big></dt>
+<dd><p><em>type</em> - can be either <tt class="docutils literal"><span class="pre">PCM_CAPTURE</span></tt> or <tt class="docutils literal"><span class="pre">PCM_PLAYBACK</span></tt> (default).</p>
+<p><em>mode</em> - can be either <tt class="docutils literal"><span class="pre">PCM_NONBLOCK</span></tt>, or <tt class="docutils literal"><span class="pre">PCM_NORMAL</span></tt> (the
+default). In <tt class="docutils literal"><span class="pre">PCM_NONBLOCK</span></tt> mode, calls to <a class="reference internal" href="#alsaaudio.PCM.read" title="alsaaudio.PCM.read"><tt class="xref py py-func docutils literal"><span class="pre">read()</span></tt></a> will return
+immediately independent of whether there is any actual data to
+read. Similarly, calls to <a class="reference internal" href="#alsaaudio.PCM.write" title="alsaaudio.PCM.write"><tt class="xref py py-func docutils literal"><span class="pre">write()</span></tt></a> will return immediately without
+actually writing anything to the playout buffer if the buffer is
+full <a class="footnote-reference" href="#f1" id="id2">[1]</a>.</p>
+<p><em>card</em> - specifies which card should be used. This can be a string
+like &#8216;default&#8217; or a name that was returned from the <a class="reference internal" href="#alsaaudio.cards" title="alsaaudio.cards"><tt class="xref py py-func docutils literal"><span class="pre">cards()</span></tt></a> function.</p>
+<p>This will construct a PCM object with these default settings:</p>
+<ul class="simple">
+<li>Sample format: <tt class="docutils literal"><span class="pre">PCM_FORMAT_S16_LE</span></tt></li>
+<li>Rate: 44100 Hz</li>
+<li>Channels: 2</li>
+<li>Period size: 32 frames</li>
+</ul>
+</dd></dl>
+
+<p>PCM objects have the following methods:</p>
+<dl class="method">
+<dt id="alsaaudio.PCM.pcmtype">
+<tt class="descclassname">PCM.</tt><tt class="descname">pcmtype</tt><big>(</big><big>)</big><a class="headerlink" href="#alsaaudio.PCM.pcmtype" title="Permalink to this definition">¶</a></dt>
+<dd><p>Returns the type of PCM object. Either <tt class="docutils literal"><span class="pre">PCM_CAPTURE</span></tt> or <tt class="docutils literal"><span class="pre">PCM_PLAYBACK</span></tt>.</p>
+</dd></dl>
+
+<dl class="method">
+<dt id="alsaaudio.PCM.pcmmode">
+<tt class="descclassname">PCM.</tt><tt class="descname">pcmmode</tt><big>(</big><big>)</big><a class="headerlink" href="#alsaaudio.PCM.pcmmode" title="Permalink to this definition">¶</a></dt>
+<dd><p>Return the mode of the PCM object. One of <tt class="docutils literal"><span class="pre">PCM_NONBLOCK</span></tt>, <tt class="docutils literal"><span class="pre">PCM_ASYNC</span></tt>,
+or <tt class="docutils literal"><span class="pre">PCM_NORMAL</span></tt></p>
+</dd></dl>
+
+<dl class="method">
+<dt id="alsaaudio.PCM.cardname">
+<tt class="descclassname">PCM.</tt><tt class="descname">cardname</tt><big>(</big><big>)</big><a class="headerlink" href="#alsaaudio.PCM.cardname" title="Permalink to this definition">¶</a></dt>
+<dd><p>Return the name of the sound card used by this PCM object.</p>
+</dd></dl>
+
+<dl class="method">
+<dt id="alsaaudio.PCM.setchannels">
+<tt class="descclassname">PCM.</tt><tt class="descname">setchannels</tt><big>(</big><em>nchannels</em><big>)</big><a class="headerlink" href="#alsaaudio.PCM.setchannels" title="Permalink to this definition">¶</a></dt>
+<dd><p>Used to set the number of capture or playback channels. Common
+values are: 1 = mono, 2 = stereo, and 6 = full 6 channel audio. Few
+sound cards support more than 2 channels</p>
+</dd></dl>
+
+<dl class="method">
+<dt id="alsaaudio.PCM.setrate">
+<tt class="descclassname">PCM.</tt><tt class="descname">setrate</tt><big>(</big><em>rate</em><big>)</big><a class="headerlink" href="#alsaaudio.PCM.setrate" title="Permalink to this definition">¶</a></dt>
+<dd><p>Set the sample rate in Hz for the device. Typical values are 8000
+(mainly used for telephony), 16000, 44100 (CD quality), and 96000.</p>
+</dd></dl>
+
+<dl class="method">
+<dt id="alsaaudio.PCM.setformat">
+<tt class="descclassname">PCM.</tt><tt class="descname">setformat</tt><big>(</big><em>format</em><big>)</big><a class="headerlink" href="#alsaaudio.PCM.setformat" title="Permalink to this definition">¶</a></dt>
+<dd><p>The sound <em>format</em> of the device. Sound format controls how the PCM device
+interpret data for playback, and how data is encoded in captures.</p>
+<p>The following formats are provided by ALSA:</p>
+<table border="1" class="docutils">
+<colgroup>
+<col width="22%" />
+<col width="78%" />
+</colgroup>
+<thead valign="bottom">
+<tr class="row-odd"><th class="head">Format</th>
+<th class="head">Description</th>
+</tr>
+</thead>
+<tbody valign="top">
+<tr class="row-even"><td>PCM_FORMAT_S8</td>
+<td>Signed 8 bit samples for each channel</td>
+</tr>
+<tr class="row-odd"><td>PCM_FORMAT_U8</td>
+<td>Signed 8 bit samples for each channel</td>
+</tr>
+<tr class="row-even"><td>PCM_FORMAT_S16_LE</td>
+<td>Signed 16 bit samples for each channel Little Endian byte order)</td>
+</tr>
+<tr class="row-odd"><td>PCM_FORMAT_S16_BE</td>
+<td>Signed 16 bit samples for each channel (Big Endian byte order)</td>
+</tr>
+<tr class="row-even"><td>PCM_FORMAT_U16_LE</td>
+<td>Unsigned 16 bit samples for each channel (Little Endian byte order)</td>
+</tr>
+<tr class="row-odd"><td>PCM_FORMAT_U16_BE</td>
+<td>Unsigned 16 bit samples for each channel (Big Endian byte order)</td>
+</tr>
+<tr class="row-even"><td>PCM_FORMAT_S24_LE</td>
+<td>Signed 24 bit samples for each channel (Little Endian byte order)</td>
+</tr>
+<tr class="row-odd"><td>PCM_FORMAT_S24_BE</td>
+<td>Signed 24 bit samples for each channel (Big Endian byte order)}</td>
+</tr>
+<tr class="row-even"><td>PCM_FORMAT_U24_LE</td>
+<td>Unsigned 24 bit samples for each channel (Little Endian byte order)</td>
+</tr>
+<tr class="row-odd"><td>PCM_FORMAT_U24_BE</td>
+<td>Unsigned 24 bit samples for each channel (Big Endian byte order)</td>
+</tr>
+<tr class="row-even"><td>PCM_FORMAT_S32_LE</td>
+<td>Signed 32 bit samples for each channel (Little Endian byte order)</td>
+</tr>
+<tr class="row-odd"><td>PCM_FORMAT_S32_BE</td>
+<td>Signed 32 bit samples for each channel (Big Endian byte order)</td>
+</tr>
+<tr class="row-even"><td>PCM_FORMAT_U32_LE</td>
+<td>Unsigned 32 bit samples for each channel (Little Endian byte order)</td>
+</tr>
+<tr class="row-odd"><td>PCM_FORMAT_U32_BE</td>
+<td>Unsigned 32 bit samples for each channel (Big Endian byte order)</td>
+</tr>
+<tr class="row-even"><td>PCM_FORMAT_FLOAT_LE</td>
+<td>32 bit samples encoded as float (Little Endian byte order)</td>
+</tr>
+<tr class="row-odd"><td>PCM_FORMAT_FLOAT_BE</td>
+<td>32 bit samples encoded as float (Big Endian byte order)</td>
+</tr>
+<tr class="row-even"><td>PCM_FORMAT_FLOAT64_LE</td>
+<td>64 bit samples encoded as float (Little Endian byte order)</td>
+</tr>
+<tr class="row-odd"><td>PCM_FORMAT_FLOAT64_BE</td>
+<td>64 bit samples encoded as float (Big Endian byte order)</td>
+</tr>
+<tr class="row-even"><td>PCM_FORMAT_MU_LAW</td>
+<td>A logarithmic encoding (used by Sun .au files and telephony)</td>
+</tr>
+<tr class="row-odd"><td>PCM_FORMAT_A_LAW</td>
+<td>Another logarithmic encoding</td>
+</tr>
+<tr class="row-even"><td>PCM_FORMAT_IMA_ADPCM</td>
+<td>A 4:1 compressed format defined by the Interactive Multimedia Association.</td>
+</tr>
+<tr class="row-odd"><td>PCM_FORMAT_MPEG</td>
+<td>MPEG encoded audio?</td>
+</tr>
+<tr class="row-even"><td>PCM_FORMAT_GSM</td>
+<td>9600 bits/s constant rate encoding for speech</td>
+</tr>
+</tbody>
+</table>
+</dd></dl>
+
+<dl class="method">
+<dt id="alsaaudio.PCM.setperiodsize">
+<tt class="descclassname">PCM.</tt><tt class="descname">setperiodsize</tt><big>(</big><em>period</em><big>)</big><a class="headerlink" href="#alsaaudio.PCM.setperiodsize" title="Permalink to this definition">¶</a></dt>
+<dd><p>Sets the actual period size in frames. Each write should consist of
+exactly this number of frames, and each read will return this
+number of frames (unless the device is in <tt class="docutils literal"><span class="pre">PCM_NONBLOCK</span></tt> mode, in
+which case it may return nothing at all)</p>
+</dd></dl>
+
+<dl class="method">
+<dt id="alsaaudio.PCM.read">
+<tt class="descclassname">PCM.</tt><tt class="descname">read</tt><big>(</big><big>)</big><a class="headerlink" href="#alsaaudio.PCM.read" title="Permalink to this definition">¶</a></dt>
+<dd><p>In <tt class="docutils literal"><span class="pre">PCM_NORMAL</span></tt> mode, this function blocks until a full period is
+available, and then returns a tuple (length,data) where <em>length</em> is
+the number of frames of captured data, and <em>data</em> is the captured
+sound frames as a string. The length of the returned data will be
+periodsize*framesize bytes.</p>
+<p>In <tt class="docutils literal"><span class="pre">PCM_NONBLOCK</span></tt> mode, the call will not block, but will return
+<tt class="docutils literal"><span class="pre">(0,'')</span></tt> if no new period has become available since the last
+call to read.</p>
+</dd></dl>
+
+<dl class="method">
+<dt id="alsaaudio.PCM.write">
+<tt class="descclassname">PCM.</tt><tt class="descname">write</tt><big>(</big><em>data</em><big>)</big><a class="headerlink" href="#alsaaudio.PCM.write" title="Permalink to this definition">¶</a></dt>
+<dd><p>Writes (plays) the sound in data. The length of data <em>must</em> be a
+multiple of the frame size, and <em>should</em> be exactly the size of a
+period. If less than &#8216;period size&#8217; frames are provided, the actual
+playout will not happen until more data is written.</p>
+<p>If the device is not in <tt class="docutils literal"><span class="pre">PCM_NONBLOCK</span></tt> mode, this call will block if
+the kernel buffer is full, and until enough sound has been played
+to allow the sound data to be buffered. The call always returns the
+size of the data provided.</p>
+<p>In <tt class="docutils literal"><span class="pre">PCM_NONBLOCK</span></tt> mode, the call will return immediately, with a
+return value of zero, if the buffer is full. In this case, the data
+should be written at a later time.</p>
+</dd></dl>
+
+<dl class="method">
+<dt id="alsaaudio.PCM.pause">
+<tt class="descclassname">PCM.</tt><tt class="descname">pause</tt><big>(</big><span class="optional">[</span><em>enable=1</em><span class="optional">]</span><big>)</big><a class="headerlink" href="#alsaaudio.PCM.pause" title="Permalink to this definition">¶</a></dt>
+<dd><p>If <em>enable</em> is 1, playback or capture is paused. If <em>enable</em> is 0,
+playback/capture is resumed.</p>
+</dd></dl>
+
+<p><strong>A few hints on using PCM devices for playback</strong></p>
+<p>The most common reason for problems with playback of PCM audio is that writes
+to PCM devices must <em>exactly</em> match the data rate of the device.</p>
+<p>If too little data is written to the device, it will underrun, and
+ugly clicking sounds will occur. Conversely, of too much data is
+written to the device, the write function will either block
+(<tt class="docutils literal"><span class="pre">PCM_NORMAL</span></tt> mode) or return zero (<tt class="docutils literal"><span class="pre">PCM_NONBLOCK</span></tt> mode).</p>
+<p>If your program does nothing but play sound, the best strategy is to put the
+device in <tt class="docutils literal"><span class="pre">PCM_NORMAL</span></tt> mode, and just write as much data to the device as
+possible. This strategy can also be achieved by using a separate
+thread with the sole task of playing out sound.</p>
+<p>In GUI programs, however, it may be a better strategy to setup the device,
+preload the buffer with a few periods by calling write a couple of times, and
+then use some timer method to write one period size of data to the device every
+period. The purpose of the preloading is to avoid underrun clicks if the used
+timer doesn&#8217;t expire exactly on time.</p>
+<p>Also note, that most timer APIs that you can find for Python will
+accummulate time delays: If you set the timer to expire after 1/10&#8217;th
+of a second, the actual timeout will happen slightly later, which will
+accumulate to quite a lot after a few seconds. Hint: use time.time()
+to check how much time has really passed, and add extra writes as nessecary.</p>
+</div>
+<div class="section" id="mixer-objects">
+<span id="id3"></span><h2>Mixer Objects<a class="headerlink" href="#mixer-objects" title="Permalink to this headline">¶</a></h2>
+<p>Mixer objects provides access to the ALSA mixer API.</p>
+<dl class="class">
+<dt>
+<em class="property">class </em><tt class="descclassname">alsaaudio.</tt><tt class="descname">Mixer</tt><big>(</big><em>control='Master'</em>, <em>id=0</em>, <em>cardindex=0</em><big>)</big></dt>
+<dd><p><em>control</em> - specifies which control to manipulate using this mixer
+object. The list of available controls can be found with the
+<a class="reference internal" href="#module-alsaaudio" title="alsaaudio (Linux)"><tt class="xref py py-mod docutils literal"><span class="pre">alsaaudio</span></tt></a>.<a class="reference internal" href="#alsaaudio.mixers" title="alsaaudio.mixers"><tt class="xref py py-func docutils literal"><span class="pre">mixers()</span></tt></a> function.  The default value is
+&#8216;Master&#8217; - other common controls include &#8216;Master Mono&#8217;, &#8216;PCM&#8217;, &#8216;Line&#8217;, etc.</p>
+<p><em>id</em> - the id of the mixer control. Default is 0</p>
+<p><em>cardindex</em> - specifies which card should be used <a class="footnote-reference" href="#f3" id="id4">[3]</a>. 0 is the
+first sound card.</p>
+<p><strong>Note:</strong> For a list of available controls, you can also use <strong>amixer</strong>:</p>
+<div class="highlight-python"><div class="highlight"><pre><span class="n">amixer</span>
+</pre></div>
+</div>
+</dd></dl>
+
+<p>Mixer objects have the following methods:</p>
+<dl class="method">
+<dt id="alsaaudio.Mixer.cardname">
+<tt class="descclassname">Mixer.</tt><tt class="descname">cardname</tt><big>(</big><big>)</big><a class="headerlink" href="#alsaaudio.Mixer.cardname" title="Permalink to this definition">¶</a></dt>
+<dd><p>Return the name of the sound card used by this Mixer object</p>
+</dd></dl>
+
+<dl class="method">
+<dt id="alsaaudio.Mixer.mixer">
+<tt class="descclassname">Mixer.</tt><tt class="descname">mixer</tt><big>(</big><big>)</big><a class="headerlink" href="#alsaaudio.Mixer.mixer" title="Permalink to this definition">¶</a></dt>
+<dd><p>Return the name of the specific mixer controlled by this object, For example
+&#8216;Master&#8217; or &#8216;PCM&#8217;</p>
+</dd></dl>
+
+<dl class="method">
+<dt id="alsaaudio.Mixer.mixerid">
+<tt class="descclassname">Mixer.</tt><tt class="descname">mixerid</tt><big>(</big><big>)</big><a class="headerlink" href="#alsaaudio.Mixer.mixerid" title="Permalink to this definition">¶</a></dt>
+<dd><p>Return the ID of the ALSA mixer controlled by this object.</p>
+</dd></dl>
+
+<dl class="method">
+<dt id="alsaaudio.Mixer.switchcap">
+<tt class="descclassname">Mixer.</tt><tt class="descname">switchcap</tt><big>(</big><big>)</big><a class="headerlink" href="#alsaaudio.Mixer.switchcap" title="Permalink to this definition">¶</a></dt>
+<dd><p>Returns a list of the switches which are defined by this specific mixer.
+Possible values in this list are:</p>
+<table border="1" class="docutils">
+<colgroup>
+<col width="31%" />
+<col width="69%" />
+</colgroup>
+<thead valign="bottom">
+<tr class="row-odd"><th class="head">Switch</th>
+<th class="head">Description</th>
+</tr>
+</thead>
+<tbody valign="top">
+<tr class="row-even"><td>&#8216;Mute&#8217;</td>
+<td>This mixer can mute</td>
+</tr>
+<tr class="row-odd"><td>&#8216;Joined Mute&#8217;</td>
+<td>This mixer can mute all channels at the same time</td>
+</tr>
+<tr class="row-even"><td>&#8216;Playback Mute&#8217;</td>
+<td>This mixer can mute the playback output</td>
+</tr>
+<tr class="row-odd"><td>&#8216;Joined Playback Mute&#8217;</td>
+<td>Mute playback for all channels at the same time}</td>
+</tr>
+<tr class="row-even"><td>&#8216;Capture Mute&#8217;</td>
+<td>Mute sound capture</td>
+</tr>
+<tr class="row-odd"><td>&#8216;Joined Capture Mute&#8217;</td>
+<td>Mute sound capture for all channels at a time}</td>
+</tr>
+<tr class="row-even"><td>&#8216;Capture Exclusive&#8217;</td>
+<td>Not quite sure what this is</td>
+</tr>
+</tbody>
+</table>
+<p>To manipulate these switches use the <a class="reference internal" href="#alsaaudio.Mixer.setrec" title="alsaaudio.Mixer.setrec"><tt class="xref py py-meth docutils literal"><span class="pre">setrec()</span></tt></a> or
+<a class="reference internal" href="#alsaaudio.Mixer.setmute" title="alsaaudio.Mixer.setmute"><tt class="xref py py-meth docutils literal"><span class="pre">setmute()</span></tt></a> methods</p>
+</dd></dl>
+
+<dl class="method">
+<dt id="alsaaudio.Mixer.volumecap">
+<tt class="descclassname">Mixer.</tt><tt class="descname">volumecap</tt><big>(</big><big>)</big><a class="headerlink" href="#alsaaudio.Mixer.volumecap" title="Permalink to this definition">¶</a></dt>
+<dd><p>Returns a list of the volume control capabilities of this
+mixer. Possible values in the list are:</p>
+<table border="1" class="docutils">
+<colgroup>
+<col width="28%" />
+<col width="72%" />
+</colgroup>
+<thead valign="bottom">
+<tr class="row-odd"><th class="head">Capability</th>
+<th class="head">Description</th>
+</tr>
+</thead>
+<tbody valign="top">
+<tr class="row-even"><td>&#8216;Volume&#8217;</td>
+<td>This mixer can control volume</td>
+</tr>
+<tr class="row-odd"><td>&#8216;Joined Volume&#8217;</td>
+<td>This mixer can control volume for all channels at the same time</td>
+</tr>
+<tr class="row-even"><td>&#8216;Playback Volume&#8217;</td>
+<td>This mixer can manipulate the playback output</td>
+</tr>
+<tr class="row-odd"><td>&#8216;Joined Playback Volume&#8217;</td>
+<td>Manipulate playback volumne for all channels at the same time</td>
+</tr>
+<tr class="row-even"><td>&#8216;Capture Volume&#8217;</td>
+<td>Manipulate sound capture volume</td>
+</tr>
+<tr class="row-odd"><td>&#8216;Joined Capture Volume&#8217;</td>
+<td>Manipulate sound capture volume for all channels at a time</td>
+</tr>
+</tbody>
+</table>
+</dd></dl>
+
+<dl class="method">
+<dt id="alsaaudio.Mixer.getenum">
+<tt class="descclassname">Mixer.</tt><tt class="descname">getenum</tt><big>(</big><big>)</big><a class="headerlink" href="#alsaaudio.Mixer.getenum" title="Permalink to this definition">¶</a></dt>
+<dd><p>For enumerated controls, return the currently selected item and  the list of
+items available.</p>
+<p>Returns a tuple <em>(string, list of strings)</em>.</p>
+<p>For example, my soundcard has a Mixer called <em>Mono Output Select</em>. Using
+<em>amixer</em>, I get:</p>
+<div class="highlight-python"><pre>$ amixer get "Mono Output Select"
+Simple mixer control 'Mono Output Select',0
+  Capabilities: enum
+  Items: 'Mix' 'Mic'
+  Item0: 'Mix'</pre>
+</div>
+<p>Using <a class="reference internal" href="#module-alsaaudio" title="alsaaudio (Linux)"><tt class="xref py py-mod docutils literal"><span class="pre">alsaaudio</span></tt></a>, one could do:</p>
+<div class="highlight-python"><div class="highlight"><pre><span class="gp">&gt;&gt;&gt; </span><span class="kn">import</span> <span class="nn">alsaaudio</span>
+<span class="gp">&gt;&gt;&gt; </span><span class="n">m</span> <span class="o">=</span> <span class="n">alsaaudio</span><span class="o">.</span><span class="n">Mixer</span><span class="p">(</span><span class="s">&#39;Mono Output Select&#39;</span><span class="p">)</span>
+<span class="gp">&gt;&gt;&gt; </span><span class="n">m</span><span class="o">.</span><span class="n">getenum</span><span class="p">()</span>
+<span class="go">(&#39;Mix&#39;, [&#39;Mix&#39;, &#39;Mic&#39;])</span>
+</pre></div>
+</div>
+<p>This method will return an empty tuple if the mixer is not an  enumerated
+control.</p>
+</dd></dl>
+
+<dl class="method">
+<dt id="alsaaudio.Mixer.getmute">
+<tt class="descclassname">Mixer.</tt><tt class="descname">getmute</tt><big>(</big><big>)</big><a class="headerlink" href="#alsaaudio.Mixer.getmute" title="Permalink to this definition">¶</a></dt>
+<dd><p>Return a list indicating the current mute setting for each
+channel. 0 means not muted, 1 means muted.</p>
+<p>This method will fail if the mixer has no playback switch capabilities.</p>
+</dd></dl>
+
+<dl class="method">
+<dt id="alsaaudio.Mixer.getrange">
+<tt class="descclassname">Mixer.</tt><tt class="descname">getrange</tt><big>(</big><span class="optional">[</span><em>direction</em><span class="optional">]</span><big>)</big><a class="headerlink" href="#alsaaudio.Mixer.getrange" title="Permalink to this definition">¶</a></dt>
+<dd><p>Return the volume range of the ALSA mixer controlled by this object.</p>
+<p>The optional <em>direction</em> argument can be either &#8216;playback&#8217; or
+&#8216;capture&#8217;, which is relevant if the mixer can control both playback
+and capture volume.  The default value is &#8216;playback&#8217; if the mixer
+has this capability, otherwise &#8216;capture&#8217;</p>
+</dd></dl>
+
+<dl class="method">
+<dt id="alsaaudio.Mixer.getrec">
+<tt class="descclassname">Mixer.</tt><tt class="descname">getrec</tt><big>(</big><big>)</big><a class="headerlink" href="#alsaaudio.Mixer.getrec" title="Permalink to this definition">¶</a></dt>
+<dd><p>Return a list indicating the current record mute setting for each channel. 0
+means not recording, 1 means recording.</p>
+<p>This method will fail if the mixer has no capture switch capabilities.</p>
+</dd></dl>
+
+<dl class="method">
+<dt id="alsaaudio.Mixer.getvolume">
+<tt class="descclassname">Mixer.</tt><tt class="descname">getvolume</tt><big>(</big><span class="optional">[</span><em>direction</em><span class="optional">]</span><big>)</big><a class="headerlink" href="#alsaaudio.Mixer.getvolume" title="Permalink to this definition">¶</a></dt>
+<dd><p>Returns a list with the current volume settings for each channel. The list
+elements are integer percentages.</p>
+<p>The optional <em>direction</em> argument can be either &#8216;playback&#8217; or
+&#8216;capture&#8217;, which is relevant if the mixer can control both playback
+and capture volume. The default value is &#8216;playback&#8217; if the mixer
+has this capability, otherwise &#8216;capture&#8217;</p>
+</dd></dl>
+
+<dl class="method">
+<dt id="alsaaudio.Mixer.setvolume">
+<tt class="descclassname">Mixer.</tt><tt class="descname">setvolume</tt><big>(</big><em>volume</em><span class="optional">[</span>, <em>channel</em><span class="optional">]</span><span class="optional">[</span>, <em>direction</em><span class="optional">]</span><big>)</big><a class="headerlink" href="#alsaaudio.Mixer.setvolume" title="Permalink to this definition">¶</a></dt>
+<dd><p>Change the current volume settings for this mixer. The <em>volume</em> argument
+controls the new volume setting as an integer percentage.</p>
+<p>If the optional argument <em>channel</em> is present, the volume is set
+only for this channel. This assumes that the mixer can control the
+volume for the channels independently.</p>
+<p>The optional <em>direction</em> argument can be either &#8216;playback&#8217; or &#8216;capture&#8217; is
+relevant if the mixer has independent playback and capture volume
+capabilities, and controls which of the volumes if changed. The
+default is &#8216;playback&#8217; if the mixer has this capability, otherwise &#8216;capture&#8217;.</p>
+</dd></dl>
+
+<dl class="method">
+<dt id="alsaaudio.Mixer.setmute">
+<tt class="descclassname">Mixer.</tt><tt class="descname">setmute</tt><big>(</big><em>mute</em><span class="optional">[</span>, <em>channel</em><span class="optional">]</span><big>)</big><a class="headerlink" href="#alsaaudio.Mixer.setmute" title="Permalink to this definition">¶</a></dt>
+<dd><p>Sets the mute flag to a new value. The <em>mute</em> argument is either 0 for not
+muted, or 1 for muted.</p>
+<p>The optional <em>channel</em> argument controls which channel is
+muted. The default is to set the mute flag for all channels.</p>
+<p>This method will fail if the mixer has no playback mute capabilities</p>
+</dd></dl>
+
+<dl class="method">
+<dt id="alsaaudio.Mixer.setrec">
+<tt class="descclassname">Mixer.</tt><tt class="descname">setrec</tt><big>(</big><em>capture</em><span class="optional">[</span>, <em>channel</em><span class="optional">]</span><big>)</big><a class="headerlink" href="#alsaaudio.Mixer.setrec" title="Permalink to this definition">¶</a></dt>
+<dd><p>Sets the capture mute flag to a new value. The <em>capture</em> argument
+is either 0 for no capture, or 1 for capture.</p>
+<p>The optional <em>channel</em> argument controls which channel is
+changed. The default is to set the capture flag for all channels.</p>
+<p>This method will fail if the mixer has no capture switch capabilities.</p>
+</dd></dl>
+
+<dl class="method">
+<dt id="alsaaudio.Mixer.polldescriptors">
+<tt class="descclassname">Mixer.</tt><tt class="descname">polldescriptors</tt><big>(</big><big>)</big><a class="headerlink" href="#alsaaudio.Mixer.polldescriptors" title="Permalink to this definition">¶</a></dt>
+<dd><p>Returns a tuple of (file descriptor, eventmask) that can be used to
+wait for changes on the mixer with <em>select.poll</em>.</p>
+</dd></dl>
+
+<p><strong>A rant on the ALSA Mixer API</strong></p>
+<p>The ALSA mixer API is extremely complicated - and hardly documented at all.
+<a class="reference internal" href="#module-alsaaudio" title="alsaaudio (Linux)"><tt class="xref py py-mod docutils literal"><span class="pre">alsaaudio</span></tt></a> implements a much simplified way to access this API. In
+designing the API I&#8217;ve had to make some choices which may limit what can and
+cannot be controlled through the API. However, If I had chosen to implement the
+full API, I would have reexposed the horrible complexity/documentation ratio of
+the underlying API.  At least the <a class="reference internal" href="#module-alsaaudio" title="alsaaudio (Linux)"><tt class="xref py py-mod docutils literal"><span class="pre">alsaaudio</span></tt></a> API is easy to
+understand and use.</p>
+<p>If my design choises prevents you from doing something that the underlying API
+would have allowed, please let me know, so I can incorporate these needs into
+future versions.</p>
+<p>If the current state of affairs annoys you, the best you can do is to write a
+HOWTO on the API and make this available on the net. Until somebody does this,
+the availability of ALSA mixer capable devices will stay quite limited.</p>
+<p>Unfortunately, I&#8217;m not able to create such a HOWTO myself, since I only
+understand half of the API, and that which I do understand has come from a
+painful trial and error process.</p>
+</div>
+<div class="section" id="examples">
+<span id="pcm-example"></span><h2>Examples<a class="headerlink" href="#examples" title="Permalink to this headline">¶</a></h2>
+<p>The following example are provided:</p>
+<ul class="simple">
+<li>playwav.py</li>
+<li>recordtest.py</li>
+<li>playbacktest.py</li>
+<li>mixertest.py</li>
+</ul>
+<p>All examples (except mixertest.py) accept the commandline option
+<em>-c &lt;cardname&gt;</em>.</p>
+<p>To determine a valid card name, use the commandline ALSA player:</p>
+<div class="highlight-python"><pre>$ aplay -L</pre>
+</div>
+<p>or:</p>
+<div class="highlight-python"><pre>$ python
+
+&gt;&gt;&gt; import alsaaudio
+&gt;&gt;&gt; alsaaudio.cards()</pre>
+</div>
+<p>mixertest.py accepts the commandline option <em>-c &lt;cardindex&gt;</em>. Card
+indices start at 0.</p>
+<div class="section" id="playwav-py">
+<h3>playwav.py<a class="headerlink" href="#playwav-py" title="Permalink to this headline">¶</a></h3>
+<p><strong>playwav.py</strong> plays a wav file.</p>
+<p>To test PCM playback (on your default soundcard), run:</p>
+<div class="highlight-python"><pre>$ python playwav.py &lt;wav file&gt;</pre>
+</div>
+</div>
+<div class="section" id="recordtest-py-and-playbacktest-py">
+<h3>recordtest.py and playbacktest.py<a class="headerlink" href="#recordtest-py-and-playbacktest-py" title="Permalink to this headline">¶</a></h3>
+<p><strong>recordtest.py</strong> and <strong>playbacktest.py</strong> will record and play a raw
+sound file in CD quality.</p>
+<p>To test PCM recordings (on your default soundcard), run:</p>
+<div class="highlight-python"><pre>$ python recordtest.py &lt;filename&gt;</pre>
+</div>
+<p>Speak into the microphone, and interrupt the recording at any time
+with <tt class="docutils literal"><span class="pre">Ctl-C</span></tt>.</p>
+<p>Play back the recording with:</p>
+<div class="highlight-python"><pre>$ python playbacktest.py &lt;filename&gt;</pre>
+</div>
+</div>
+<div class="section" id="mixertest-py">
+<h3>mixertest.py<a class="headerlink" href="#mixertest-py" title="Permalink to this headline">¶</a></h3>
+<p>Without arguments, <strong>mixertest.py</strong> will list all available <em>controls</em>.
+The output might look like this:</p>
+<div class="highlight-python"><pre>$ ./mixertest.py
+Available mixer controls:
+  'Master'
+  'Master Mono'
+  'Headphone'
+  'PCM'
+  'Line'
+  'Line In-&gt;Rear Out'
+  'CD'
+  'Mic'
+  'PC Speaker'
+  'Aux'
+  'Mono Output Select'
+  'Capture'
+  'Mix'
+  'Mix Mono'</pre>
+</div>
+<p>With a single argument - the <em>control</em>, it will display the settings of
+that control; for example:</p>
+<div class="highlight-python"><pre>$ ./mixertest.py Master
+Mixer name: 'Master'
+Capabilities: Playback Volume Playback Mute
+Channel 0 volume: 61%
+Channel 1 volume: 61%</pre>
+</div>
+<p>With two arguments, the <em>control</em> and a <em>parameter</em>, it will set the
+parameter on the mixer:</p>
+<div class="highlight-python"><pre>$ ./mixertest.py Master mute</pre>
+</div>
+<p>This will mute the Master mixer.</p>
+<p>Or:</p>
+<div class="highlight-python"><pre>$ ./mixertest.py Master 40</pre>
+</div>
+<p>This sets the volume to 40% on all channels.</p>
+<p class="rubric">Footnotes</p>
+<table class="docutils footnote" frame="void" id="f1" rules="none">
+<colgroup><col class="label" /><col /></colgroup>
+<tbody valign="top">
+<tr><td class="label"><a class="fn-backref" href="#id2">[1]</a></td><td>ALSA also allows <tt class="docutils literal"><span class="pre">PCM_ASYNC</span></tt>, but this is not supported yet.</td></tr>
+</tbody>
+</table>
+<table class="docutils footnote" frame="void" id="f2" rules="none">
+<colgroup><col class="label" /><col /></colgroup>
+<tbody valign="top">
+<tr><td class="label">[2]</td><td><a class="reference internal" href="#module-alsaaudio" title="alsaaudio (Linux)"><tt class="xref py py-mod docutils literal"><span class="pre">alsaaudio</span></tt></a> will leave any name alone that has a &#8216;:&#8217; (colon) in it.</td></tr>
+</tbody>
+</table>
+<table class="docutils footnote" frame="void" id="f3" rules="none">
+<colgroup><col class="label" /><col /></colgroup>
+<tbody valign="top">
+<tr><td class="label"><a class="fn-backref" href="#id4">[3]</a></td><td>This is inconsistent with the PCM objects, which use names, but it is consistent with aplay and amixer.</td></tr>
+</tbody>
+</table>
+</div>
+</div>
+</div>
+
+
+          </div>
+        </div>
+      </div>
+      <div class="sphinxsidebar">
+        <div class="sphinxsidebarwrapper">
+  <h3><a href="index.html">Table Of Contents</a></h3>
+  <ul>
+<li><a class="reference internal" href="#"><tt class="docutils literal"><span class="pre">alsaaudio</span></tt></a><ul>
+<li><a class="reference internal" href="#pcm-objects">PCM Objects</a></li>
+<li><a class="reference internal" href="#mixer-objects">Mixer Objects</a></li>
+<li><a class="reference internal" href="#examples">Examples</a><ul>
+<li><a class="reference internal" href="#playwav-py">playwav.py</a></li>
+<li><a class="reference internal" href="#recordtest-py-and-playbacktest-py">recordtest.py and playbacktest.py</a></li>
+<li><a class="reference internal" href="#mixertest-py">mixertest.py</a></li>
+</ul>
+</li>
+</ul>
+</li>
+</ul>
+
+  <h4>Previous topic</h4>
+  <p class="topless"><a href="terminology.html"
+                        title="previous chapter">PCM Terminology and Concepts</a></p>
+  <h3>This Page</h3>
+  <ul class="this-page-menu">
+    <li><a href="_sources/libalsaaudio.txt"
+           rel="nofollow">Show Source</a></li>
+  </ul>
+<div id="searchbox" style="display: none">
+  <h3>Quick search</h3>
+    <form class="search" action="search.html" method="get">
+      <input type="text" name="q" />
+      <input type="submit" value="Go" />
+      <input type="hidden" name="check_keywords" value="yes" />
+      <input type="hidden" name="area" value="default" />
+    </form>
+    <p class="searchtip" style="font-size: 90%">
+    Enter search terms or a module, class or function name.
+    </p>
+</div>
+<script type="text/javascript">$('#searchbox').show(0);</script>
+        </div>
+      </div>
+      <div class="clearer"></div>
+    </div>
+    <div class="related">
+      <h3>Navigation</h3>
+      <ul>
+        <li class="right" style="margin-right: 10px">
+          <a href="genindex.html" title="General Index"
+             >index</a></li>
+        <li class="right" >
+          <a href="py-modindex.html" title="Python Module Index"
+             >modules</a> |</li>
+        <li class="right" >
+          <a href="terminology.html" title="PCM Terminology and Concepts"
+             >previous</a> |</li>
+        <li><a href="index.html">alsaaudio 0.8 documentation</a> &raquo;</li> 
+      </ul>
+    </div>
+    <div class="footer">
+        &copy; Copyright 2008-2009, Casper Wilstrup, Lars Immisch.
+      Last updated on Apr 30, 2015.
+      Created using <a href="http://sphinx.pocoo.org/">Sphinx</a> 1.1.3.
+    </div>
+  </body>
+</html>

py-modindex.html

@@ -0,0 +1,115 @@
+
+
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
+  "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
+
+
+<html xmlns="http://www.w3.org/1999/xhtml">
+  <head>
+    <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
+    
+    <title>Python Module Index &mdash; alsaaudio 0.8 documentation</title>
+    
+    <link rel="stylesheet" href="_static/default.css" type="text/css" />
+    <link rel="stylesheet" href="_static/pygments.css" type="text/css" />
+    
+    <script type="text/javascript">
+      var DOCUMENTATION_OPTIONS = {
+        URL_ROOT:    '',
+        VERSION:     '0.8',
+        COLLAPSE_INDEX: false,
+        FILE_SUFFIX: '.html',
+        HAS_SOURCE:  true
+      };
+    </script>
+    <script type="text/javascript" src="_static/jquery.js"></script>
+    <script type="text/javascript" src="_static/underscore.js"></script>
+    <script type="text/javascript" src="_static/doctools.js"></script>
+    <link rel="top" title="alsaaudio 0.8 documentation" href="index.html" />
+ 
+
+    <script type="text/javascript">
+      DOCUMENTATION_OPTIONS.COLLAPSE_INDEX = true;
+    </script>
+
+
+  </head>
+  <body>
+    <div class="related">
+      <h3>Navigation</h3>
+      <ul>
+        <li class="right" style="margin-right: 10px">
+          <a href="genindex.html" title="General Index"
+             accesskey="I">index</a></li>
+        <li class="right" >
+          <a href="#" title="Python Module Index"
+             >modules</a> |</li>
+        <li><a href="index.html">alsaaudio 0.8 documentation</a> &raquo;</li> 
+      </ul>
+    </div>  
+
+    <div class="document">
+      <div class="documentwrapper">
+        <div class="bodywrapper">
+          <div class="body">
+            
+
+   <h1>Python Module Index</h1>
+
+   <div class="modindex-jumpbox">
+   <a href="#cap-a"><strong>a</strong></a>
+   </div>
+
+   <table class="indextable modindextable" cellspacing="0" cellpadding="2">
+     <tr class="pcap"><td></td><td>&nbsp;</td><td></td></tr>
+     <tr class="cap" id="cap-a"><td></td><td>
+       <strong>a</strong></td><td></td></tr>
+     <tr>
+       <td></td>
+       <td>
+       <a href="libalsaaudio.html#module-alsaaudio"><tt class="xref">alsaaudio</tt></a> <em>(Linux)</em></td><td>
+       <em></em></td></tr>
+   </table>
+
+
+          </div>
+        </div>
+      </div>
+      <div class="sphinxsidebar">
+        <div class="sphinxsidebarwrapper">
+<div id="searchbox" style="display: none">
+  <h3>Quick search</h3>
+    <form class="search" action="search.html" method="get">
+      <input type="text" name="q" />
+      <input type="submit" value="Go" />
+      <input type="hidden" name="check_keywords" value="yes" />
+      <input type="hidden" name="area" value="default" />
+    </form>
+    <p class="searchtip" style="font-size: 90%">
+    Enter search terms or a module, class or function name.
+    </p>
+</div>
+<script type="text/javascript">$('#searchbox').show(0);</script>
+        </div>
+      </div>
+      <div class="clearer"></div>
+    </div>
+    <div class="related">
+      <h3>Navigation</h3>
+      <ul>
+        <li class="right" style="margin-right: 10px">
+          <a href="genindex.html" title="General Index"
+             >index</a></li>
+        <li class="right" >
+          <a href="#" title="Python Module Index"
+             >modules</a> |</li>
+        <li><a href="index.html">alsaaudio 0.8 documentation</a> &raquo;</li> 
+      </ul>
+    </div>
+    <div class="footer">
+        &copy; Copyright 2008-2009, Casper Wilstrup, Lars Immisch.
+      Last updated on Apr 30, 2015.
+      Created using <a href="http://sphinx.pocoo.org/">Sphinx</a> 1.1.3.
+    </div>
+  </body>
+</html>

pyalsaaudio.html

@@ -0,0 +1,220 @@
+
+
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
+  "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
+
+
+<html xmlns="http://www.w3.org/1999/xhtml">
+  <head>
+    <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
+    
+    <title>Introduction &mdash; alsaaudio 0.8 documentation</title>
+    
+    <link rel="stylesheet" href="_static/default.css" type="text/css" />
+    <link rel="stylesheet" href="_static/pygments.css" type="text/css" />
+    
+    <script type="text/javascript">
+      var DOCUMENTATION_OPTIONS = {
+        URL_ROOT:    '',
+        VERSION:     '0.8',
+        COLLAPSE_INDEX: false,
+        FILE_SUFFIX: '.html',
+        HAS_SOURCE:  true
+      };
+    </script>
+    <script type="text/javascript" src="_static/jquery.js"></script>
+    <script type="text/javascript" src="_static/underscore.js"></script>
+    <script type="text/javascript" src="_static/doctools.js"></script>
+    <link rel="top" title="alsaaudio 0.8 documentation" href="index.html" />
+    <link rel="next" title="PCM Terminology and Concepts" href="terminology.html" />
+    <link rel="prev" title="alsaaudio documentation" href="index.html" /> 
+  </head>
+  <body>
+    <div class="related">
+      <h3>Navigation</h3>
+      <ul>
+        <li class="right" style="margin-right: 10px">
+          <a href="genindex.html" title="General Index"
+             accesskey="I">index</a></li>
+        <li class="right" >
+          <a href="py-modindex.html" title="Python Module Index"
+             >modules</a> |</li>
+        <li class="right" >
+          <a href="terminology.html" title="PCM Terminology and Concepts"
+             accesskey="N">next</a> |</li>
+        <li class="right" >
+          <a href="index.html" title="alsaaudio documentation"
+             accesskey="P">previous</a> |</li>
+        <li><a href="index.html">alsaaudio 0.8 documentation</a> &raquo;</li> 
+      </ul>
+    </div>  
+
+    <div class="document">
+      <div class="documentwrapper">
+        <div class="bodywrapper">
+          <div class="body">
+            
+  <div class="section" id="introduction">
+<h1>Introduction<a class="headerlink" href="#introduction" title="Permalink to this headline">¶</a></h1>
+<table class="docutils field-list" frame="void" rules="none">
+<col class="field-name" />
+<col class="field-body" />
+<tbody valign="top">
+<tr class="field-odd field"><th class="field-name">Author:</th><td class="field-body">Casper Wilstrup</td>
+</tr>
+<tr class="field-even field"><th class="field-name">Author:</th><td class="field-body">Lars Immisch</td>
+</tr>
+</tbody>
+</table>
+<p id="front">This software is licensed under the PSF license - the same one used by the
+majority of the python distribution. Basically you can use it for anything you
+wish (even commercial purposes). There is no warranty whatsoever.</p>
+<div class="topic">
+<p class="topic-title first">Abstract</p>
+<p>This package contains wrappers for accessing the ALSA API from Python. It is
+currently fairly complete for PCM devices and Mixer access. MIDI sequencer
+support is low on our priority list, but volunteers are welcome.</p>
+<p>If you find bugs in the wrappers please use the SourceForge bug tracker.
+Please don&#8217;t send bug reports regarding ALSA specifically. There are several
+bugs in this API, and those should be reported to the ALSA team - not me.</p>
+</div>
+</div>
+<div class="section" id="what-is-alsa">
+<h1>What is ALSA<a class="headerlink" href="#what-is-alsa" title="Permalink to this headline">¶</a></h1>
+<p>The Advanced Linux Sound Architecture (ALSA) provides audio and MIDI
+functionality to the Linux operating system.</p>
+<p>Logically ALSA consists of these components:</p>
+<ul class="simple">
+<li>A set of kernel drivers. &#8212;  These drivers are responsible for handling the
+physical sound  hardware from within the Linux kernel, and have been the
+standard sound implementation in Linux since kernel version 2.5</li>
+<li>A kernel level API for manipulating the ALSA devices.</li>
+<li>A user-space C library for simplified access to the sound hardware from
+userspace applications. This library is called <em>libasound</em> and is required by
+all ALSA capable applications.</li>
+</ul>
+<p>More information about ALSA may be found on the project homepage
+<a class="reference external" href="http://www.alsa-project.org">http://www.alsa-project.org</a></p>
+<div class="section" id="alsa-and-python">
+<h2>ALSA and Python<a class="headerlink" href="#alsa-and-python" title="Permalink to this headline">¶</a></h2>
+<p>The older Linux sound API (OSS) which is now deprecated is well supported from
+the standard Python library, through the ossaudiodev module. No native ALSA
+support exists in the standard library.</p>
+<p>There are a few other &#8220;ALSA for Python&#8221; projects available, including at least
+two different projects called pyAlsa. Neither of these seem to be under active
+development at the time - and neither are very feature complete.</p>
+<p>I wrote PyAlsaAudio to fill this gap. My long term goal is to have the module
+included in the standard Python library, but that looks currently unlikely.</p>
+<p>PyAlsaAudio hass full support for sound capture, playback of sound, as well as
+the ALSA Mixer API.</p>
+<p>MIDI support is not available, and since I don&#8217;t own any MIDI hardware, it&#8217;s
+difficult for me to implement it. Volunteers to work on this would be greatly
+appreciated.</p>
+</div>
+</div>
+<div class="section" id="installation">
+<h1>Installation<a class="headerlink" href="#installation" title="Permalink to this headline">¶</a></h1>
+<p>Note: the wrappers link with the alsasound library (from the alsa-lib package)
+and need the ALSA headers for compilation.  Verify that you have
+/usr/lib/libasound.so and /usr/include/alsa (or similar paths) before building.</p>
+<p><em>On Debian (and probably Ubuntu), install libasound2-dev.</em></p>
+<p>Naturally you also need to use a kernel with proper ALSA support. This is the
+default in Linux kernel 2.6 and later. If you are using kernel version 2.4 you
+may need to install the ALSA patches yourself - although most distributions
+ship with ALSA kernels.</p>
+<p>To install, execute the following:  &#8212;</p>
+<div class="highlight-python"><pre>$ python setup.py build</pre>
+</div>
+<p>And then as root:  &#8212;</p>
+<div class="highlight-python"><div class="highlight"><pre><span class="c"># python setup.py install</span>
+</pre></div>
+</div>
+</div>
+<div class="section" id="testing">
+<h1>Testing<a class="headerlink" href="#testing" title="Permalink to this headline">¶</a></h1>
+<p>First of all, run:</p>
+<div class="highlight-python"><pre>$ python test.py</pre>
+</div>
+<p>This is a small test suite that mostly performs consistency tests. If
+it fails, please file a <a class="reference external" href="http://sourceforge.net/tracker/?group_id=120651">bug report</a>.</p>
+<p>To test PCM recordings (on your default soundcard), verify your
+microphone works, then do:</p>
+<div class="highlight-python"><pre>$ python recordtest.py &lt;filename&gt;</pre>
+</div>
+<p>Speak into the microphone, and interrupt the recording at any time
+with <tt class="docutils literal"><span class="pre">Ctl-C</span></tt>.</p>
+<p>Play back the recording with:</p>
+<div class="highlight-python"><pre>$ python playbacktest.py &lt;filename&gt;</pre>
+</div>
+</div>
+
+
+          </div>
+        </div>
+      </div>
+      <div class="sphinxsidebar">
+        <div class="sphinxsidebarwrapper">
+  <h3><a href="index.html">Table Of Contents</a></h3>
+  <ul>
+<li><a class="reference internal" href="#">Introduction</a></li>
+<li><a class="reference internal" href="#what-is-alsa">What is ALSA</a><ul>
+<li><a class="reference internal" href="#alsa-and-python">ALSA and Python</a></li>
+</ul>
+</li>
+<li><a class="reference internal" href="#installation">Installation</a></li>
+<li><a class="reference internal" href="#testing">Testing</a></li>
+</ul>
+
+  <h4>Previous topic</h4>
+  <p class="topless"><a href="index.html"
+                        title="previous chapter">alsaaudio documentation</a></p>
+  <h4>Next topic</h4>
+  <p class="topless"><a href="terminology.html"
+                        title="next chapter">PCM Terminology and Concepts</a></p>
+  <h3>This Page</h3>
+  <ul class="this-page-menu">
+    <li><a href="_sources/pyalsaaudio.txt"
+           rel="nofollow">Show Source</a></li>
+  </ul>
+<div id="searchbox" style="display: none">
+  <h3>Quick search</h3>
+    <form class="search" action="search.html" method="get">
+      <input type="text" name="q" />
+      <input type="submit" value="Go" />
+      <input type="hidden" name="check_keywords" value="yes" />
+      <input type="hidden" name="area" value="default" />
+    </form>
+    <p class="searchtip" style="font-size: 90%">
+    Enter search terms or a module, class or function name.
+    </p>
+</div>
+<script type="text/javascript">$('#searchbox').show(0);</script>
+        </div>
+      </div>
+      <div class="clearer"></div>
+    </div>
+    <div class="related">
+      <h3>Navigation</h3>
+      <ul>
+        <li class="right" style="margin-right: 10px">
+          <a href="genindex.html" title="General Index"
+             >index</a></li>
+        <li class="right" >
+          <a href="py-modindex.html" title="Python Module Index"
+             >modules</a> |</li>
+        <li class="right" >
+          <a href="terminology.html" title="PCM Terminology and Concepts"
+             >next</a> |</li>
+        <li class="right" >
+          <a href="index.html" title="alsaaudio documentation"
+             >previous</a> |</li>
+        <li><a href="index.html">alsaaudio 0.8 documentation</a> &raquo;</li> 
+      </ul>
+    </div>
+    <div class="footer">
+        &copy; Copyright 2008-2009, Casper Wilstrup, Lars Immisch.
+      Last updated on Apr 30, 2015.
+      Created using <a href="http://sphinx.pocoo.org/">Sphinx</a> 1.1.3.
+    </div>
+  </body>
+</html>

search.html

@@ -0,0 +1,106 @@
+
+
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
+  "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
+
+
+<html xmlns="http://www.w3.org/1999/xhtml">
+  <head>
+    <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
+    
+    <title>Search &mdash; alsaaudio 0.8 documentation</title>
+    
+    <link rel="stylesheet" href="_static/default.css" type="text/css" />
+    <link rel="stylesheet" href="_static/pygments.css" type="text/css" />
+    
+    <script type="text/javascript">
+      var DOCUMENTATION_OPTIONS = {
+        URL_ROOT:    '',
+        VERSION:     '0.8',
+        COLLAPSE_INDEX: false,
+        FILE_SUFFIX: '.html',
+        HAS_SOURCE:  true
+      };
+    </script>
+    <script type="text/javascript" src="_static/jquery.js"></script>
+    <script type="text/javascript" src="_static/underscore.js"></script>
+    <script type="text/javascript" src="_static/doctools.js"></script>
+    <script type="text/javascript" src="_static/searchtools.js"></script>
+    <link rel="top" title="alsaaudio 0.8 documentation" href="index.html" />
+  <script type="text/javascript">
+    jQuery(function() { Search.loadIndex("searchindex.js"); });
+  </script>
+   
+
+  </head>
+  <body>
+    <div class="related">
+      <h3>Navigation</h3>
+      <ul>
+        <li class="right" style="margin-right: 10px">
+          <a href="genindex.html" title="General Index"
+             accesskey="I">index</a></li>
+        <li class="right" >
+          <a href="py-modindex.html" title="Python Module Index"
+             >modules</a> |</li>
+        <li><a href="index.html">alsaaudio 0.8 documentation</a> &raquo;</li> 
+      </ul>
+    </div>  
+
+    <div class="document">
+      <div class="documentwrapper">
+        <div class="bodywrapper">
+          <div class="body">
+            
+  <h1 id="search-documentation">Search</h1>
+  <div id="fallback" class="admonition warning">
+  <script type="text/javascript">$('#fallback').hide();</script>
+  <p>
+    Please activate JavaScript to enable the search
+    functionality.
+  </p>
+  </div>
+  <p>
+    From here you can search these documents. Enter your search
+    words into the box below and click "search". Note that the search
+    function will automatically search for all of the words. Pages
+    containing fewer words won't appear in the result list.
+  </p>
+  <form action="" method="get">
+    <input type="text" name="q" value="" />
+    <input type="submit" value="search" />
+    <span id="search-progress" style="padding-left: 10px"></span>
+  </form>
+  
+  <div id="search-results">
+  
+  </div>
+
+          </div>
+        </div>
+      </div>
+      <div class="sphinxsidebar">
+        <div class="sphinxsidebarwrapper">
+        </div>
+      </div>
+      <div class="clearer"></div>
+    </div>
+    <div class="related">
+      <h3>Navigation</h3>
+      <ul>
+        <li class="right" style="margin-right: 10px">
+          <a href="genindex.html" title="General Index"
+             >index</a></li>
+        <li class="right" >
+          <a href="py-modindex.html" title="Python Module Index"
+             >modules</a> |</li>
+        <li><a href="index.html">alsaaudio 0.8 documentation</a> &raquo;</li> 
+      </ul>
+    </div>
+    <div class="footer">
+        &copy; Copyright 2008-2009, Casper Wilstrup, Lars Immisch.
+      Last updated on Apr 30, 2015.
+      Created using <a href="http://sphinx.pocoo.org/">Sphinx</a> 1.1.3.
+    </div>
+  </body>
+</html>

terminology.html

@@ -0,0 +1,186 @@
+
+
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
+  "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
+
+
+<html xmlns="http://www.w3.org/1999/xhtml">
+  <head>
+    <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
+    
+    <title>PCM Terminology and Concepts &mdash; alsaaudio 0.8 documentation</title>
+    
+    <link rel="stylesheet" href="_static/default.css" type="text/css" />
+    <link rel="stylesheet" href="_static/pygments.css" type="text/css" />
+    
+    <script type="text/javascript">
+      var DOCUMENTATION_OPTIONS = {
+        URL_ROOT:    '',
+        VERSION:     '0.8',
+        COLLAPSE_INDEX: false,
+        FILE_SUFFIX: '.html',
+        HAS_SOURCE:  true
+      };
+    </script>
+    <script type="text/javascript" src="_static/jquery.js"></script>
+    <script type="text/javascript" src="_static/underscore.js"></script>
+    <script type="text/javascript" src="_static/doctools.js"></script>
+    <link rel="top" title="alsaaudio 0.8 documentation" href="index.html" />
+    <link rel="next" title="alsaaudio" href="libalsaaudio.html" />
+    <link rel="prev" title="Introduction" href="pyalsaaudio.html" /> 
+  </head>
+  <body>
+    <div class="related">
+      <h3>Navigation</h3>
+      <ul>
+        <li class="right" style="margin-right: 10px">
+          <a href="genindex.html" title="General Index"
+             accesskey="I">index</a></li>
+        <li class="right" >
+          <a href="py-modindex.html" title="Python Module Index"
+             >modules</a> |</li>
+        <li class="right" >
+          <a href="libalsaaudio.html" title="alsaaudio"
+             accesskey="N">next</a> |</li>
+        <li class="right" >
+          <a href="pyalsaaudio.html" title="Introduction"
+             accesskey="P">previous</a> |</li>
+        <li><a href="index.html">alsaaudio 0.8 documentation</a> &raquo;</li> 
+      </ul>
+    </div>  
+
+    <div class="document">
+      <div class="documentwrapper">
+        <div class="bodywrapper">
+          <div class="body">
+            
+  <div class="section" id="pcm-terminology-and-concepts">
+<h1>PCM Terminology and Concepts<a class="headerlink" href="#pcm-terminology-and-concepts" title="Permalink to this headline">¶</a></h1>
+<p>In order to use PCM devices it is useful to be familiar with some concepts and
+terminology.</p>
+<dl class="docutils">
+<dt>Sample</dt>
+<dd><p class="first">PCM audio, whether it is input or output, consists of <em>samples</em>.
+A single sample represents the amplitude of one channel of sound
+at a certain point in time. A lot of individual samples are
+necessary to represent actual sound; for CD audio, 44100 samples
+are taken every second.</p>
+<p>Samples can be of many different sizes, ranging from 8 bit to 64
+bit precision. The specific format of each sample can also vary -
+they can be big endian byte integers, little endian byte integers, or
+floating point numbers.</p>
+<p class="last">Musically, the sample size determines the dynamic range. The
+dynamic range is the difference between the quietest and the
+loudest signal that can be resproduced.</p>
+</dd>
+<dt>Frame</dt>
+<dd>A frame consists of exactly one sample per channel. If there is only one
+channel (Mono sound) a frame is simply a single sample. If the sound is
+stereo, each frame consists of two samples, etc.</dd>
+<dt>Frame size</dt>
+<dd><dl class="first last docutils">
+<dt>This is the size in bytes of each frame. This can vary a lot: if each sample</dt>
+<dd><dl class="first last docutils">
+<dt>is 8 bits, and we&#8217;re handling mono sound, the frame size is one byte.</dt>
+<dd>Similarly in 6 channel audio with 64 bit floating point samples, the frame
+size is 48 bytes</dd>
+</dl>
+</dd>
+</dl>
+</dd>
+<dt>Rate</dt>
+<dd>PCM sound consists of a flow of sound frames. The sound rate controls how
+often the current frame is replaced. For example, a rate of 8000 Hz
+means that a new frame is played or captured 8000 times per second.</dd>
+<dt>Data rate</dt>
+<dd><p class="first">This is the number of bytes, which must be recorded or provided per
+second at a certain frame size and rate.</p>
+<p>8000 Hz mono sound with 8 bit (1 byte) samples has a data rate of
+8000  * 1 * 1 = 8 kb/s or 64kbit/s. This is typically used for telephony.</p>
+<p class="last">At the other end of the scale, 96000 Hz, 6 channel sound with 64
+bit (8 bytes) samples has a data rate of 96000 * 6 * 8 = 4608
+kb/s (almost 5 Mb sound data per second)</p>
+</dd>
+<dt>Period</dt>
+<dd>When the hardware processes data this is done in chunks of frames. The time
+interval between each processing (A/D or D/A conversion) is known
+as the period.
+The size of the period has direct implication on the latency of the
+sound input or output. For low-latency the period size should be
+very small, while low CPU resource usage would usually demand
+larger period sizes. With ALSA, the CPU utilization is not impacted
+much by the period size, since the kernel layer buffers multiple
+periods internally, so each period generates an interrupt and a
+memory copy, but userspace can be slower and read or write multiple
+periods at the same time.</dd>
+<dt>Period size</dt>
+<dd>This is the size of each period in Hz. <em>Not bytes, but Hz!.</em> In
+<a class="reference internal" href="libalsaaudio.html#module-alsaaudio" title="alsaaudio (Linux)"><tt class="xref py py-mod docutils literal"><span class="pre">alsaaudio</span></tt></a> the period size is set directly, and it is
+therefore important to understand the significance of this
+number. If the period size is configured to for example 32,
+each write should contain exactly 32 frames of sound data, and each
+read will return either 32 frames of data or nothing at all.</dd>
+</dl>
+<p>Once you understand these concepts, you will be ready to use the PCM API. Read
+on.</p>
+</div>
+
+
+          </div>
+        </div>
+      </div>
+      <div class="sphinxsidebar">
+        <div class="sphinxsidebarwrapper">
+  <h4>Previous topic</h4>
+  <p class="topless"><a href="pyalsaaudio.html"
+                        title="previous chapter">Introduction</a></p>
+  <h4>Next topic</h4>
+  <p class="topless"><a href="libalsaaudio.html"
+                        title="next chapter"><tt class="docutils literal docutils literal"><span class="pre">alsaaudio</span></tt></a></p>
+  <h3>This Page</h3>
+  <ul class="this-page-menu">
+    <li><a href="_sources/terminology.txt"
+           rel="nofollow">Show Source</a></li>
+  </ul>
+<div id="searchbox" style="display: none">
+  <h3>Quick search</h3>
+    <form class="search" action="search.html" method="get">
+      <input type="text" name="q" />
+      <input type="submit" value="Go" />
+      <input type="hidden" name="check_keywords" value="yes" />
+      <input type="hidden" name="area" value="default" />
+    </form>
+    <p class="searchtip" style="font-size: 90%">
+    Enter search terms or a module, class or function name.
+    </p>
+</div>
+<script type="text/javascript">$('#searchbox').show(0);</script>
+        </div>
+      </div>
+      <div class="clearer"></div>
+    </div>
+    <div class="related">
+      <h3>Navigation</h3>
+      <ul>
+        <li class="right" style="margin-right: 10px">
+          <a href="genindex.html" title="General Index"
+             >index</a></li>
+        <li class="right" >
+          <a href="py-modindex.html" title="Python Module Index"
+             >modules</a> |</li>
+        <li class="right" >
+          <a href="libalsaaudio.html" title="alsaaudio"
+             >next</a> |</li>
+        <li class="right" >
+          <a href="pyalsaaudio.html" title="Introduction"
+             >previous</a> |</li>
+        <li><a href="index.html">alsaaudio 0.8 documentation</a> &raquo;</li> 
+      </ul>
+    </div>
+    <div class="footer">
+        &copy; Copyright 2008-2009, Casper Wilstrup, Lars Immisch.
+      Last updated on Apr 30, 2015.
+      Created using <a href="http://sphinx.pocoo.org/">Sphinx</a> 1.1.3.
+    </div>
+  </body>
+</html>