Introduction
============

BAT is a small tool to help with automation testing for audio drivers.
BAT can also mean a small flying mammal with big ears and good hearing OR Basic 
Audio Tester OR Basic ALSA Tester. Take your pick.


Requirements
============

BAT uses GNU autotools. Please install :-

sudo apt-get gnome-common.

This will install all build tools required to build BAT.

alsalib and fftw3 are the audio and FFT libraries respectively that are
required in order to build BAT. They can be installed by running :-

sudo apt-get install libasound2-dev libfftw3-dev

If you want to use -t option, the library tinyalsa is required for compilation
and linking.
You can get it from here: https://github.com/tinyalsa/tinyalsa.git
Compile it: 
	make all
Install it: 
	copy include/tinyalsa/asoundlib.h to /usr/include/tinyalsa/asoundlib.h
	copy libtinyalsa.so to /usr/lib/x86_64-linux-gnu 
	  (or i386-linux-gnu for 32bits system)


Install
=======

BAT can be installed by running :
	./autogen.sh
	./configure
	make
	make install


Usage
=====

BAT is intended to analyse audio recorded in loopback mode for quality and gain
errors by comparing the captured audio PCM data to the original PCM data.
The input PCM data should be a sine wave. Comparison is done through extraction
of the main frequency of the output data and comparison to given value for 
input data.

BAT should be used as this :

1- Loopback with a wav file as input
    bat -D plughw:0,0 -f file.wav -F 250 [-l] [-t]
    bat -P plughw:0,3 -C plughw:0,0 -f file.wav -F 1000 [-l] [-t]
    
2- Loopback with a auto generated sine wawe as input
    bat -D plughw:0,0 -r 44100 -c 2 -s 2 -n 88200 -F 250,500 [-l]
    bat -P plughw:0,3 -C plughw:0,0 -r 16000 -c 2 -s 2 -n 1s -F 250 [-l]
    
3- Play endlessly a sinus wave at 44k1Hz on one channel with 16bits per sample.
    bat -D plughw:0,0 -r 44100 -c 1 -s 2 -n 0 

4- Single line mode. On PC plays, another one captures. 
    bat -P plughw:0,0 -r 44100 -c 2 -s 2 -n 88200 -F 5973,1711 [-t] (on 1st PC) 
    bat -C plughw:0,0 -r 44100 -c 2 -s 2 -n 44100 -F 5973,1711 [-t] (on 2nd PC)

Common switches:
------------------
Option -D, -P, -C are used to specific respectively the audio device for 
 playback and capture, the audio device for playback and the audio device 
 for capture

Option -F is used to specify the sine wave frequency of the input data.
 The sine wav frequency can be different for each channels. 
 Usage is -F 980,670 when using 2 channels
 
Option -n is used to specify the number of frames to be analyzed (if set to 0,
 then no analyzis is done and it plays endlessly). In single line mode (-C or
 -P), it is used to specify how many samples to play or capture.
 n can be given in number of samples or in second (ex: -n 2.1s)

Option -C and -P when used not together, are used to set single ended mode.
 i.e. only playback or capture.

option -p is used to limit the number of periods played or captured. 
 Use -n instead.
 
option -k is used to define to clip any peaks not significant for testing
 purposes. Default value should fit most of cases.

For using a wav file as input:
------------------
Option -f is used to specify the input file (which should contain a sine 
 wave of frequency given by -F argument)
 
For auto generated sine wave:
------------------
Option -r is used to specify the sampling rate

Option -c is used to specify the number of channels (1 or 2)

Option -s is used to specify the number of bytes per sample (1,2, 3 or 4)

Optional switches:
------------------
Option -l is optional and used to test the analyzis part of BAT. The audio path
 is not tested.

Option -t is optional and enable used of tinyalsa library instead of alsa
 library. See requirements.


You need to connect playback to capture through an audio jack cable. 
BAT will capture the playback of the input file and do a FFT to determine
 fundamental frequency of the input.
BAT will return a negative result on any errors and 0 if fundamental frequency
 found is one specified in F argument.

It can also be used to generate a continuous sine wave.

Returned errors
===============
0:	No error
-1: 	General error
-100: 	No peak detected
-101:	Peak detected at DC level (<7hz)
-102:	Peak detected not at right position

Notes
=====
If option -f is given, then parameter from arguments c, r, n and s are read from
 file. This means that you can not use a raw wav file (so without header) as
 these informations will be missing.

Device name are specified in the ALSA format (even for tinyalsa)
plughw:x,y	or hw:x,y
Where x is card number and y is device number
You can get the list of cards and devices by typing the command:
 aplay -l
 
One frame represents one sample from all channels (so for 2 channels,
 1 frame equals 2 samples).
 

Limitations
=====
- Input and output gain should be correctly set. Better is to use alsamixer to 
 set 0dB gain for both input and output, otherwise you may have
 distortions during recording and it may lead to non detection of main harmonic. 


Future Plans
============

See Intel JIRA VIZ-4287