asgardius/alsa-utils
1
0
Fork 0
mirror of https://github.com/alsa-project/alsa-utils synced 2024-11-10 04:35:43 +01:00
Code Issues Projects Releases Packages Wiki Activity

BAT: Add man page

Browse source 
Add more information about BAT utility, including design intent,
principles, use mode, hardware connection, options, example and
return value.

Signed-off-by: Lu, Han <han.lu@intel.com>
Signed-off-by: Takashi Iwai <tiwai@suse.de>
This commit is contained in:
Lu, Han 2015-10-21 14:53:27 +08:00 committed by Takashi Iwai
parent 2abee9c5b4
commit 73f9dd149e
2 changed files with 161 additions and 0 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

3
bat/Makefile.am
View file

@ -1,4 +1,7 @@
bin_PROGRAMS = bat
man_MANS = bat.1
EXTRA_DIST = bat.1
bat_SOURCES = \
bat.c \

158
bat/bat.1 Normal file
View file

@ -0,0 +1,158 @@
.TH BAT 1 "20th October 2015"
.SH NAME
bat \- command\-line sound tester for ALSA sound card driver
.SH SYNOPSIS
\fBbat\fP [\fIflags\fP]
.SH DESCRIPTION
\fBBAT(Basic Audio Tester)\fP is a simple command\-line utility intended
to help automate audio driver and sound server testing with little human
interaction. BAT can be used to test audio quality, stress test features
and test audio before and after PM state changes.
BAT's design is relatively simple. BAT plays an audio stream and captures
the same stream in either a digital or analog loop back. It then compares
the captured stream using a FFT to the original to determine if the test
case passes or fails.
BAT can either run wholly on the target machine being tested (standalone
mode) or can run as a client/server mode where by bat client runs on the
target and runs as a server on a separate tester machine. The client/server
mode still requires some manual interaction for synchronization, but this
is actively being developed for future releases.
The hardware testing configuration may require the use of an analog cable
connecting target to tester machines or a cable to create an analog
loopback if no loopback mode is not available on the sound hardware that
is being tested.
An analog loopback cable can be used to connect the "line in" to "line out"
jacks to create a loopback. If only headphone and mic jacks (or combo jack)
are available then the following simple circuit can be used to create an
analog loopback :-
https://source.android.com/devices/audio/loopback.html
.SH OPTIONS
.TP
\fI\-h, \-\-help\fP
Help: show syntax.
.TP
\fI\-D\fP
Select sound card to be tested by name.
.TP
\fI\-P\fP
Select the playback PCM device.
.TP
\fI\-C\fP
Select the capture PCM device.
.TP
\fI\-f\fP
Sample format
.br
Recognized sample formats are: U8 S16_LE S24_3LE S32_LE
.br
Some of these may not be available on selected hardware
.br
The available format shortcuts are:
.nf
\-f cd (16 bit little endian, 44100, stereo) [\-f S16_LE \-c2 \-r44100]
\-f dat (16 bit little endian, 48000, stereo) [\-f S16_LE \-c2 \-r48000]
.fi
If no format is given S16_LE is used.
.TP
\fI\-c\fP
The number of channels. The default is one channel.
Valid values at the moment are 1 or 2.
.TP
\fI\-r\fP
Sampling rate in Hertz. The default rate is 44100 Hertz.
Valid values depends on hardware support.
.TP
\fI\-n\fP
Duration of generated signal.
The value could be either of the two forms:
.br
1. Decimal integer, means number of frames;
.br
2. Floating point with suffix 's', means number of seconds.
.br
The default is 2 seconds.
.TP
\fI\-k\fP
Sigma k value for analysis.
.br
The analysis function reads data from WAV file, run FFT against the data
to get magnitude of frequency vectors, and then calculates the average
value and standard deviation of frequency vectors. After that, we define
a threshold:
.br
threshold = k * standard_deviation + mean_value
.br
Frequencies with amplitude larger than threshold will be recognized as a
peak, and the frequency with largest peak value will be recognized as a
detected frequency.
.br
BAT then compares the detected frequency to target frequency, to decide
if the detecting passes or fails.
.br
The default value is 3.0.
.TP
\fI\-F\fP
Target frequency for signal generation and analysis, in Hertz.
The default is 997.0 Hertz.
Valid range is (DC_THRESHOLD, 40% * Sampling rate).
.TP
\fI\-p\fP
Total number of periods to play or capture.
.TP
\fI\-\-log=#\fP
Write stderr and stdout output to this log file.
.TP
\fI\-\-file=#\fP
Input WAV file for playback.
.TP
\fI\-\-saveplay=#\fP
Target WAV file to save capture test content.
.TP
\fI\-\-local\fP
Internal loopback mode.
Playback, capture and analysis internal to BAT only. This is intended for
developers to test new BAT features as no audio is routed outside of BAT.
.SH EXAMPLES
.TP
\fBbat \-P plughw:0,0 \-C plughw:0,0 \-c 2 \-f S32_LE \-F 250\fR
Generate and play a sine wave of 250 Hertz with 2 channel and S32_LE format,
and then capture and analyze.
.TP
\fBbat \-P plughw:0,0 \-C plughw:0,0 \-\-file 500Hz.wav\fR
Play the RIFF WAV file "500Hz.wav" which contains 500 Hertz waveform LPCM
data, and then capture and analyze.
.SH RETURN VALUE
.br
On success, returns 0.
.br
If no peak be detected, returns -1001;
.br
If only DC be detected, returns -1002;
.br
If peak frequency does not match with the target frequency, returns -1003.
.SH SEE ALSO
\fB
aplay(1)
\fP
.SH BUGS
Currently only support RIFF WAV format with PCM data. Please report any bugs to
the alsa-devel mailing list.
.SH AUTHOR
\fBbat\fP is by Liam Girdwood <liam.r.girdwood@linux.intel.com>, Bernard Gautier
<bernard.gautier@intel.com> and Han Lu <han.lu@intel.com>.
This document is by Liam Girdwood <liam.r.girdwood@linux.intel.com> and Han Lu
<han.lu@intel.com>.