Documentation Bugs

Documentation Bugs

[Torrey Hoffman]

I've been working through the .asoundrc documentation and have found
several errors.

This is for the "asoundrc" documentation, viewed on Jan 23 '04, using
Mozilla 1.4.1, at the URL:

http://www.alsa-project.org/alsa-doc/doc-php/asoundrc.php3

I am using kernel 2.6.2-rc1 with the alsa-bk-2004-01-20.patch.gz,  and
the 1.0.1 version of alsa-lib, alsa-tools, and alsa-utils.

The hardware I used for these tests is the Intel ICH5 AC97 interface to
a Realtek ALC650 chip on an ABit MAX3 motherboard.

------------------------------------------------------
1. The "Aliases" section contains an incorrect example,  missing the
alias name:

"
For example, this gives your first soundcard an alias: 
	pcm. {
     		type hw
     		card 0
     		device 0
	}
Now you can access this card by the alias ''. 
	aplay -D  test.wav
"

This should be something like "pcm.my_alias_name {" ...

------------------------------------------------------
2. The Plugins section starts with an example of a very simple slave:
	pcm_slave.sltest {
     		pcm 
	}

This is incorrect.  It is missing the pcm device after the keyword pcm.

Similarly, the pcm_slave.sl2 rate-conversion example is missing the pcm
device name.

------------------------------------------------------
3. The rate conversion plug documentation (or code?) is broken.

I'm not sure if this is a documentation bug or a driver/alsa-lib bug. 

My .asoundrc at this point closely follows the documentation (with
corrections as noted in bug#2) and looks like:

pcm.ac97 {
	type hw
	card 0
	device 0
}

pcm_slave.sl2 {
	pcm ac97
	rate 44100
}

pcm.rate_convert {
	type rate
	slave sl2
}

The documentation says:  
"Now you can call this newly created virtual device by: aplay -D
rate_convert test.wav"

But when I try that, I get this error:

Playing WAVE 'test.wav' : Signed 16 bit Little Endian, Rate 44100 Hz, Stereo
aplay: set_params:805: Broken configuration for this PCM: no configurations available

Note that "aplay -D ac97 test.wav" works, but plays too fast (at 48000),
and gives the warning "please, try the plug plugin (-Dplug:ac97)". If I
do that, it works perfectly.

So I think the documentation is wrong, or at least incomplete, or rate
conversion does not work.

------------------------------------------------------
4.  The "plug" plugin documentation is wrong, or at least
incomplete/misleading.

First of all, the "syntax" description for "type plug" is complex and
not explained in this page of documentation at all.  route_policy,
ttable, etc. ???

The documentation goes on to say:

"	We can use it as follows: 
	pcm_slave.sl3 {
     		pcm  
     		format S16_LE
    	 	channels 1
     		rate 16000
	}

	pcm.complex_convert {
    		type plug
    		slave sl3
	}

	By calling it with: 
	aplay -vD complex_convert test.wav

	You will convert the sample during playing to the sample format:
	S16_LE, one channel and a sample rate of 16 kHz. As you called
	aplay with the verbose option -v you see this options as it
	appears as it comes from the original file"
"

First, the pcm name for the slave is missing, as in bug #2.


I copied and pasted this example directly into my .asoundrc, and then
filled in "ac97" for the missing pcm name.  Here are the results of
testing it:

[thoffman@moria thoffman]$ aplay -vD complex_convert test.wav
Playing WAVE 'test.wav' : Signed 16 bit Little Endian, Rate 44100 Hz, Stereo
ALSA lib pcm_params.c:2096:(snd_pcm_hw_refine_slave) Slave PCM not usable
aplay: set_params:805: Broken configuration for this PCM: no configurations available

I experimented by changing the slave channels to 2 and the rate to 44100
in .asoundrc, and got exactly the same error message.

Changing the slave rate to 48000 resulted in playback, but too fast of
course...

------------------------------------------------------
5. dmix documentation

Following the documentation example for how to use dmix, I wrote this
.asoundrc:

----cut----
pcm.ac97 {
	type hw
	card 0
	device 0
}

pcm.dmixer  {
	type dmix
	ipc_key 1024
	slave {
		pcm "ac97"
		period_time 0	
		period_size 1024
		buffer_size 4096
		rate 44100
	}
	bindings {
		0 0
		1 1
	}
}
 
ctl.dmixer {
	type hw
	card 0
}

pcm.!default {
	type plug
	slave.pcm "dmixer"
}
----cut----

When I tried "aplay -f cd -Dplug:default test.wav" as the documentation
suggests, I got no error message but no sound either.

When I tried "aplay -f cd -D default test.wav" instead, it worked, and I
was able to start multiple instances, which were mixed together as
expected.

So, I think the documentation is incorrect in suggesting that the "plug"
device be used from the command line.


Thanks,

-- 
Torrey Hoffman <thoffman@arnor.net>



-------------------------------------------------------
The SF.Net email is sponsored by EclipseCon 2004
Premiere Conference on Open Tools Development and Integration
See the breadth of Eclipse activity. February 3-5 in Anaheim, CA.
http://www.eclipsecon.org/osdn

Re: Documentation Bugs

[Patrick Shirkey]

Torrey Hoffman wrote:
> I've been working through the .asoundrc documentation and have found
> several errors.
> 

Thanks for the detailed report.

I have fixed the obvious errors but I'm not sure what the problem is 
with the rate_convert example. I have left it as is for now.



> 
> ------------------------------------------------------
> 3. The rate conversion plug documentation (or code?) is broken.
> 
> I'm not sure if this is a documentation bug or a driver/alsa-lib bug. 
> 
> My .asoundrc at this point closely follows the documentation (with
> corrections as noted in bug#2) and looks like:
> 
> pcm.ac97 {
> 	type hw
> 	card 0
> 	device 0
> }
> 
> pcm_slave.sl2 {
> 	pcm ac97
> 	rate 44100
> }
> 
> pcm.rate_convert {
> 	type rate
> 	slave sl2
> }
> 
> The documentation says:  
> "Now you can call this newly created virtual device by: aplay -D
> rate_convert test.wav"
> 
> But when I try that, I get this error:
> 
> Playing WAVE 'test.wav' : Signed 16 bit Little Endian, Rate 44100 Hz, Stereo
> aplay: set_params:805: Broken configuration for this PCM: no configurations available
> 
> Note that "aplay -D ac97 test.wav" works, but plays too fast (at 48000),
> and gives the warning "please, try the plug plugin (-Dplug:ac97)". If I
> do that, it works perfectly.
> 
> So I think the documentation is wrong, or at least incomplete, or rate
> conversion does not work.
> 


-- 
Patrick Shirkey - Boost Hardware Ltd.
Http://www.boosthardware.com
Http://www.djcj.org - The Linux Audio Users guide
========================================


  Apparently upon the beginning of the barrage, the donkey broke 
discipline and panicked, toppling the cart. At that point, the rockets 
disconnected from the timer, leaving them strewn around the street. 
Tethered to the now toppled cart, the donkey was unable to escape before 
the arrival of U.S. troops.

United Press International
Rockets on donkeys hit major Baghdad sites

By P. MITCHELL PROTHERO
Published 11/21/2003 11:13 AM



-------------------------------------------------------
The SF.Net email is sponsored by EclipseCon 2004
Premiere Conference on Open Tools Development and Integration
See the breadth of Eclipse activity. February 3-5 in Anaheim, CA.
http://www.eclipsecon.org/osdn

Re: Documentation Bugs

[Clemens Ladisch]

Torrey Hoffman wrote:
> My .asoundrc at this point closely follows the documentation (with
> corrections as noted in bug#2) and looks like:
>
> pcm.ac97 {
> 	type hw
> 	card 0
> 	device 0
> }
>
> pcm_slave.sl2 {
> 	pcm ac97
> 	rate 44100
> }
>
> pcm.rate_convert {
> 	type rate
> 	slave sl2
> }
>
> The documentation says:
> "Now you can call this newly created virtual device by: aplay -D
> rate_convert test.wav"
>
> But when I try that, I get this error:
>
> Playing WAVE 'test.wav' : Signed 16 bit Little Endian, Rate 44100 Hz, Stereo
> aplay: set_params:805: Broken configuration for this PCM: no configurations available
>
> Note that "aplay -D ac97 test.wav" works, but plays too fast (at 48000),
> and gives the warning "please, try the plug plugin (-Dplug:ac97)". If I
> do that, it works perfectly.

This example is intended to demonstrate a virtual device that accepts
all sample rates and converts them to 44.1 kHz before playing.

However, it seems your hardware supports 48 kHz only.

I think the example should use 48 instead of 44.1 because that is the
only sample rate guaranteed to be available on AC'97 codecs.


HTH
Clemens




-------------------------------------------------------
The SF.Net email is sponsored by EclipseCon 2004
Premiere Conference on Open Tools Development and Integration
See the breadth of Eclipse activity. February 3-5 in Anaheim, CA.
http://www.eclipsecon.org/osdn

Documentation Bugs

[Uwe Kleine-König]

Hello,

1) git-fetch(1) (from maint) states:

       -q, --quiet
           Pass --quiet to git-fetch-pack and silence any other internally
           used programs.
	
   but git-fetch doesn't like -q.  (master has
   a858c006fae17cef44dd63737771f2bebb6eeae8, but maint only has
   42905294de0c1885f5636319c4790f184d767875)

Maybe more difficult:
2) rebase a merged tree:

   If I made a local commit and pulled from origin, I get:

	zeisberg@cassiopeia:~/gsrc/git$ git show
	commit 15386213004a20dfdf92c654c737795079202545
	Merge: 9d740f0... 9159afb...
	Author: Uwe Kleine-König <ukleinek@informatik.uni-freiburg.de>
	Date:   Sun May 6 14:49:59 2007 +0200

	    Merge branch 'master' of git://git.kernel.org/pub/scm/git/git

	zeisberg@cassiopeia:~/gsrc/git$ git rebase junio/master
	Current branch master is up to date.

   (where junio/master is the tracking branch for
   git://git.kernel.org/pub/scm/git/git) but git-rebase(1) states:

	All changes made by commits in the current branch but that are
	not in <upstream> are saved to a temporary area. This is the
	same set of commits that would be shown by git log
	<upstream>..HEAD.

   and git-log junio/master..HEAD is not empty.

I didn't have the time to look into 2).  So I only report it for now.

Best regards
Uwe

-- 
Uwe Kleine-König

http://www.google.com/search?q=sin%28pi%2F2%29

Re: Documentation Bugs

[Uwe Kleine-König]

Hello,

> 2) rebase a merged tree:
> 
>    If I made a local commit and pulled from origin, I get:
> 
> 	zeisberg@cassiopeia:~/gsrc/git$ git show
> 	commit 15386213004a20dfdf92c654c737795079202545
> 	Merge: 9d740f0... 9159afb...
> 	Author: Uwe Kleine-König <ukleinek@informatik.uni-freiburg.de>
> 	Date:   Sun May 6 14:49:59 2007 +0200
> 
> 	    Merge branch 'master' of git://git.kernel.org/pub/scm/git/git
> 
> 	zeisberg@cassiopeia:~/gsrc/git$ git rebase junio/master
> 	Current branch master is up to date.
> 
>    (where junio/master is the tracking branch for
>    git://git.kernel.org/pub/scm/git/git) but git-rebase(1) states:
> 
> 	All changes made by commits in the current branch but that are
> 	not in <upstream> are saved to a temporary area. This is the
> 	same set of commits that would be shown by git log
> 	<upstream>..HEAD.
> 
>    and git-log junio/master..HEAD is not empty.
After having thought about that one once more, here some more info:  The
two patches I had in master were merged in the meantime.  So it was
correct for git-rebase to state that master is up to date.  Rereading
the documentation I realize there is no bug.  I just missed that both
patches were already merged and format-patch generated a patch anyhow.

The first issue remains however.

Best regards
Uwe

-- 
Uwe Kleine-König

If a lawyer and an IRS agent were both drowning, and you could only save
one of them, would you go to lunch or read the paper?