bat/bat.1

   1 .TH BAT 1 "20th October 2015"
   2 .SH NAME
   3 bat \- command\-line sound tester for ALSA sound card driver
   4
   5 .SH SYNOPSIS
   6 \fBbat\fP [\fIflags\fP]
   7
   8 .SH DESCRIPTION
   9 \fBBAT(Basic Audio Tester)\fP is a simple command\-line utility intended
  10 to help automate audio driver and sound server testing with little human
  11 interaction. BAT can be used to test audio quality, stress test features
  12 and test audio before and after PM state changes.
  13
  14 BAT's design is relatively simple. BAT plays an audio stream and captures
  15 the same stream in either a digital or analog loop back. It then compares
  16 the captured stream using a FFT to the original to determine if the test
  17 case passes or fails.
  18
  19 BAT can either run wholly on the target machine being tested (standalone
  20 mode) or can run as a client/server mode where by bat client runs on the
  21 target and runs as a server on a separate tester machine. The client/server
  22 mode still requires some manual interaction for synchronization, but this
  23 is actively being developed for future releases.
  24
  25 The hardware testing configuration may require the use of an analog cable
  26 connecting target to tester machines or a cable to create an analog
  27 loopback if no loopback mode is not available on the sound hardware that
  28 is being tested.
  29 An analog loopback cable can be used to connect the "line in" to "line out"
  30 jacks to create a loopback. If only headphone and mic jacks (or combo jack)
  31 are available then the following simple circuit can be used to create an
  32 analog loopback :-
  33
  34 https://source.android.com/devices/audio/loopback.html
  35
  36 .SH OPTIONS
  37 .TP
  38 \fI\-h, \-\-help\fP
  39 Help: show syntax.
  40 .TP
  41 \fI\-D\fP
  42 Select sound card to be tested by name.
  43 .TP
  44 \fI\-P\fP
  45 Select the playback PCM device.
  46 .TP
  47 \fI\-C\fP
  48 Select the capture PCM device.
  49 .TP
  50 \fI\-f\fP
  51 Sample format
  52 .br
  53 Recognized sample formats are: U8 S16_LE S24_3LE S32_LE
  54 .br
  55 Some of these may not be available on selected hardware
  56 .br
  57 The available format shortcuts are:
  58 .nf
  59 \-f cd (16 bit little endian, 44100, stereo) [\-f S16_LE \-c2 \-r44100]
  60 \-f dat (16 bit little endian, 48000, stereo) [\-f S16_LE \-c2 \-r48000]
  61 .fi
  62 If no format is given S16_LE is used.
  63 .TP
  64 \fI\-c\fP
  65 The number of channels. The default is one channel.
  66 Valid values at the moment are 1 or 2.
  67 .TP
  68 \fI\-r\fP
  69 Sampling rate in Hertz. The default rate is 44100 Hertz.
  70 Valid values depends on hardware support.
  71 .TP
  72 \fI\-n\fP
  73 Duration of generated signal.
  74 The value could be either of the two forms:
  75 .br
  76 1. Decimal integer, means number of frames;
  77 .br
  78 2. Floating point with suffix 's', means number of seconds.
  79 .br
  80 The default is 2 seconds.
  81 .TP
  82 \fI\-k\fP
  83 Sigma k value for analysis.
  84 .br
  85 The analysis function reads data from WAV file, run FFT against the data
  86 to get magnitude of frequency vectors, and then calculates the average
  87 value and standard deviation of frequency vectors. After that, we define
  88 a threshold:
  89 .br
  90 threshold = k * standard_deviation + mean_value
  91 .br
  92 Frequencies with amplitude larger than threshold will be recognized as a
  93 peak, and the frequency with largest peak value will be recognized as a
  94 detected frequency.
  95 .br
  96 BAT then compares the detected frequency to target frequency, to decide
  97 if the detecting passes or fails.
  98 .br
  99 The default value is 3.0.
 100 .TP
 101 \fI\-F\fP
 102 Target frequency for signal generation and analysis, in Hertz.
 103 The default is 997.0 Hertz.
 104 Valid range is (DC_THRESHOLD, 40% * Sampling rate).
 105 .TP
 106 \fI\-p\fP
 107 Total number of periods to play or capture.
 108 .TP
 109 \fI\-\-log=#\fP
 110 Write stderr and stdout output to this log file.
 111 .TP
 112 \fI\-\-file=#\fP
 113 Input WAV file for playback.
 114 .TP
 115 \fI\-\-saveplay=#\fP
 116 Target WAV file to save capture test content.
 117 .TP
 118 \fI\-\-local\fP
 119 Internal loopback mode.
 120 Playback, capture and analysis internal to BAT only. This is intended for
 121 developers to test new BAT features as no audio is routed outside of BAT.
 122
 123 .SH EXAMPLES
 124
 125 .TP
 126 \fBbat \-P plughw:0,0 \-C plughw:0,0 \-c 2 \-f S32_LE \-F 250\fR
 127 Generate and play a sine wave of 250 Hertz with 2 channel and S32_LE format,
 128 and then capture and analyze.
 129
 130 .TP
 131 \fBbat \-P plughw:0,0 \-C plughw:0,0 \-\-file 500Hz.wav\fR
 132 Play the RIFF WAV file "500Hz.wav" which contains 500 Hertz waveform LPCM
 133 data, and then capture and analyze.
 134
 135 .SH RETURN VALUE
 136 .br
 137 On success, returns 0.
 138 .br
 139 If no peak be detected, returns -1001;
 140 .br
 141 If only DC be detected, returns -1002;
 142 .br
 143 If peak frequency does not match with the target frequency, returns -1003.
 144
 145 .SH SEE ALSO
 146 \fB
 147 aplay(1)
 148 \fP
 149
 150 .SH BUGS
 151 Currently only support RIFF WAV format with PCM data. Please report any bugs to
 152 the alsa-devel mailing list.
 153
 154 .SH AUTHOR
 155 \fBbat\fP is by Liam Girdwood <liam.r.girdwood@linux.intel.com>, Bernard Gautier
 156 <bernard.gautier@intel.com> and Han Lu <han.lu@intel.com>.
 157 This document is by Liam Girdwood <liam.r.girdwood@linux.intel.com> and Han Lu
 158 <han.lu@intel.com>.