DATK - Distortion Analysis Toolkit
DATK - Distortion Analysis Toolkit
The operation and usage of the DATK is explained in a journal article in EURASIP JASP 2010. You can read the paper at http://www.hindawi.com/journals/asp/2010/617325.html
Setting up the Matlab-version
Simply download the zip-file and unarchive it. Then run the DATK_Create and DATK_Analyze files, as explained in the Usage-section below.
Installing the standalone version
If you do not have Matlab Compiler Runtime (MCR) environment installed (that is, if you have not used Matlab-standalone programs on your computer before), download the package with MCR on the main page. Next, install the MCR by double-clicking the MCR installer -icon. In OSX, the MCR will find its place under /Applications/MATLAB/MATLAB_Compiler_Runtime/, and you do not need to remember that location. Under Linux, however, the MCR installer asks you where to install the MCR, and you should remember the location since you need it when running the DATK. In Windows, double-click the file DATK_Create_pkg.exe, which installs the MCR and creates the DATK_Create.exe-file.
Usage
The usage instructions and the operation of the DATK is thoroughly explained in the journal article mentioned at the top of this page. Brief instructions are given below:
1.Creating the excitation signal
On the Matlab-version, run the DATK_Create.m-file. On the standalone version in OSX & Windows, double-click the DATK_Create-icon, (DATK_Create.exe in Windows) or in Linux run a shell script by typing ./run_DATK_Create.sh V711_location, where the V711_location is the path to the MCR folder v711 (under the path you specified when installing the MCR). This starts the program and opens a dialog box. Insert the desired sampling rate and bit depth into the dialog box. Since the excitation consists of several short pulses, you also need to define the length of the silence between the pulses. The correct value of the gap depends on the measured device and sample rate; short gaps give shorter excitation signals and thus faster analysis, but you need to make sure that the previous response has died out before the new pulse starts. Luckily, you can easily verify this from the manual alignment -dialog box (explained below).
Next, select the file containing the analysis commands. An example file TestCommands.txt is included in the package, and it can be used as a basis for your own command files. See the abovementioned journal article for an explanation on the analysis types. Finally, set the name and location for the excitation wave file that you will insert to the measured device.
2.Inserting the excitation and recording the responses
Open an audio program with the ability to simultaneously play and record audio (such as Audacity or Garageband). Insert the freshly created .wav-file on one track. Now, if you are measuring a physical effects device (such as a distortion pedal or a guitar preamp), connect your soundcard output to its input, and the output from the device to the sound card input (note that if the track is armed and monitoring is on, this may cause a feedback loop). Play the .wav-file and simultaneously record the device output onto another track.
Check the waveform to see that the signal level is reasonable and that the sound card is not clipping the signal. Also check that the signal level at the device input is within the intended range for the device. Adjust the sound card input and output levels and repeat the recording, if necessary. Also, you may change the controls of the device and make another recording on a different channel (just remember to name the recorded files so that you can recall which is which). If you are measuring a software plugin, you can simply add it as an effect for the excitation track and record the response. It is advisable to edit the recorded responses to have approximately the same length as the excitation, since this will speed up the analysis process later. Create a directory for the output files and export the recorded files there using the same sample rate and bit depth as for the excitation signal (also note that the directory should not contain any other files, just the response .wav-files).
3.Performing the analysis
On the Matlab-version, run the DATK_Analyze.m-file. On the standalone version, double-click the DATK_Analyze-icon (OSX), or type in console ./run_DATK_Analyze.sh V711_location (Linux). In step 1 of the freshly opened dialog box, locate the excitation .wav-file you used as the input signal for the measured device. In step 2, locate the directory that contains all the response .wav-files (and no other files) you recorded. In step 3, select whether you would like to align the excitation and response files manually, or apply a fixed delay (positive or negative) to the response files. Good time alignment between the excitation and responses is important for the analysis to function properly, and you should select the manual alignment -option, unless you are certain that all responses have a fixed delay in comparison to the excitation (e.g. if you have already aligned the signals in the audio program, in which case the delay value should be zero).
Step 4 defines the plotting options for the results, and you can set the number of rows and columns for the subplots here. For example, if you recorded six different response files, it would probably be most convenient to represent the results using two rows and three columns, or three rows and two columns. If you specify a number for the rows and columns that does not match the number of response files, it will open a warning dialog box but you can still continue. Finally, press the Analyze!-button and wait for the analysis figures to open. If you are running the Matlab-version of DATK, you can use the standard figure editing tools in Matlab in for example making the analysis figures comply with journal manuscript specifications.
Instructions
Copyright Jyri Pakarinen 2010. All rights reserved.
All software and information here is presented without warranty and is subject to change any time without prior notice. The author refuses to take any responsibility in damages to people, property, loss of data, or anything bad resulting in the use of this software or information presented here. Especially, be sure to understand what you are doing when conducting electrical measurements, and protect yourself and sensitive devices the best way you can. Do not break your computer or sound card by connecting them to devices you are not familiar with.
Oh yeah, remember to have fun while measuring!