1.0 Introduction
-----------------------

This plugin was designed for use with ALSA 0.5.x, using other versions might work
but is not recommended. Support for ALSA 0.9.x will be added later, however I 
believe that most users havae version 0.5.x.

The plugin will probe which cards and pcm-devices that are availible, and then
it tries to determine their capabilities. This will allow the use of multiple
cards with multiple pcm-devices - at the same time! Since I only have one card
on my system, as of yet, I haven't had the chance to try this out.

2.0 How to use it
--------------

Since we can have multiple soundcards, each having the same name - and also
multiple pcm-devices on each card, a problem with naming occurs. When
the alsa-plugins are initialized, a factory is created for each card and 
pcm-device on the system. However, there is no way to determine the name
of a card in advance - there are no alsasink- och alsasrc-factories present.

On my laptop, the following factories are created:
one "cs461x(0/0)-src", on "cs461x(0/0)-sink"
My stationary computer has a different and somewhat more interesting card:
"ens1371(0/0)-src", "ens1371(0/0)-sink" and "ens1371(0/1)-sink"

As you can see, these names are created dynamicly on the current system. 
Therefor you can't use the names directly.

To use the alsa-stuff, you will have to call the funtion

gst_plugin_find("alsasink") or gst_plugin_find("alsasrc")

and then call the function
gst_plugin_get_factrory_list(...) to obtain a list of factories.
Then it is trivial to choose one of them and create it.

3.0 Trouble-shooting
----------------

3.1 I am using ALSA 0.6.x, 0.7.x, 0.8.x, 0.9.x...
--------------------------------------------------

All I can say is, too bad for you. At the present time
only ALSA 0.5.x is supported - since the ALSA-team has
changed the API after 0.5.x. Due to lack of documentation,
it was easier to implement support for ALSA 0.5.x instead.
However, 0.9.x-support is planned to be added. But may take
a little while to do.

I believe that most users have the 0.5.x-version installed, and
therefor has more use of 0.5.x-support.

3.2 Low sound-quality
----------------------

In the file alsa.h there are som defines you can alter:
#define ALSA_BUFFER_SIZE (4096) /* size of buffer for block-mode */
#define ALSA_QUEUE_SIZE (2 * 4096) /* size of buffer for stream-mode */
#define ALSA_SLEEP_DELAY 10 /* time to wait before trying again(in ms) */

If you find that the sound-quality is low, try and change these values. Since
the size of the buffer is important for preventing buffer-underflows and 
buffer-overflows it might help to increase them. NOTE: Please do not use
values that are not multiples of 4096. Most likely it is the ALSA_QUEUE_SIZE you
need to increase. ALSA_SLEEP_DELAY should be a low value, but not to low since
that will waste cpu.

3.3 Other strange-error occuring and runtime
---------------------------------------------

If you get some strange error, audio doesn't play at all or anything
other strange related to the ALSA-stuff - please compile alsainfo
by typing 'make alsainfo'. This program will probe all cards and
their capabilities, and then output it to the screen.

Redirect the output to a file and send that file, along with a
description of the error.

You can also edit the Makefile and add the ALSA_DEBUG flag, recompiling
the alsa-source would now output some more debug-info that you can redirect
to another file and send along. 

This will hopefully make it easier to locate and solve the error.

This information should be sent to: thomas.nyberg@codefactory.se

4.0 Other
----------

If you have other problems or questions, do not hesitate to send them to
me at thomas.nyberg@codefactory.se .







