\documentclass{howto}

\title{PyAlsaAudio}

\release{0.2}

% At minimum, give your name and an email address.  You can include a
% snail-mail address if you like.
\author{Casper Wilstrup}
\authoraddress{cwi@unispeed.com}

\begin{document}
\maketitle

% 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.
%
\ifhtml
\chapter*{Front Matter\label{front}}
\fi

% Copyright statement should go here, if needed.
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.

% The abstract should be a paragraph or two long, and describe the
% scope of the document.
\begin{abstract}
\noindent
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 my priority list, but volunteers are welcome.

If you find bugs in the wrappers please notify me on email. 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.
\end{abstract}

\tableofcontents

\section{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:
\begin{itemize}
  \item 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
  \item A kernel level API for manipulating the ALSA devices.
  \item A user-space C library for simplified access to the sound hardware
        from userspace applications. This library is called \textit{libasound}
        and is required by all ALSA capable applications.
\end{itemize}

More information about ALSA may be found on the project homepage 
\url{http://www.alsa-project.org}

\section{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 (yet).

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 is probably a while of yet.

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
\section{Installation}

Note: the wrappers link with the alsasound library (from the alsa-lib
package). Verify that this is installed by looking for /usr/lib/libasound.so
before building. 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: \\
\begin{verbatim}
$ python setup.py build
\end{verbatim}

And then as root: \\
\begin{verbatim}
# python setup.py install
\end{verbatim}

\input{libalsaaudio}




\end{document}