ita_tutorial_record.m 6.61 KB
Newer Older
1
%% Recording with the ITA Toolbox
Johannes Klein's avatar
 
Johannes Klein committed
2
%
mbe's avatar
mbe committed
3 4
% <<../../pics/ita_toolbox_logo_wbg.png>>
%
Johannes Klein's avatar
 
Johannes Klein committed
5 6
% In this tutorial you will learn how to set-up a simple the ITA Toolbox
% for a simple recording task. The first step is to create an instance
Johannes Klein's avatar
Johannes Klein committed
7 8
% of the itaMSRecord class, the basic recording class of the ITA
% toolbox.
Johannes Klein's avatar
 
Johannes Klein committed
9 10 11 12 13 14
%
% <ITA-Toolbox>
% This file is part of the ITA-Toolbox. Some rights reserved.
% You can find the license for this m-file in the license.txt file in
% the ITA-Toolbox folder.
% </ITA-Toolbox>
Johannes Klein's avatar
Johannes Klein committed
15 16 17 18 19
%
% For feedback or questions, please contact the ITA Toolbox developers:
% toolbox-dev@akustik.rwth-aachen.de
%
% JCK 2017
Johannes Klein's avatar
 
Johannes Klein committed
20 21 22

%% Set Hardware
% Set your recording hardware in 'IO Settings'-tab ('recording' and
Johannes Klein's avatar
Johannes Klein committed
23 24 25
% 'playback device'). For a calibrated measurement it is also
% recommended to check 'Measurement Chain' on the % same 'IO Settings'
% tab.
Johannes Klein's avatar
 
Johannes Klein committed
26 27 28
ita_preferences;

%% Clear Workspace
Johannes Klein's avatar
Johannes Klein committed
29
% The 'ccx' command basically resets MATLAB to its start-up state.
Johannes Klein's avatar
 
Johannes Klein committed
30 31 32
ccx;

%% Measurement Setup
33
% Create an instance of the recording class.
Johannes Klein's avatar
 
Johannes Klein committed
34 35 36 37
MS = itaMSRecord;

% Define recording parameters
% In this example we'll use the input channel 1 of the selected hardware
38
% device. For multiple channels please specify a vector (see example 
Johannes Klein's avatar
Johannes Klein committed
39
% below). In case you activated the 'Measurement Chain' in the
40 41
% ita_preferences, you will be asked about the elements in you input 
% chain, once you define the input and output.
Johannes Klein's avatar
Johannes Klein committed
42 43 44 45 46 47 48 49 50 51
% The input measurement chain consists of 3 elements (sensor, preamp and
% A/D converter). For each element you do not want to calibrate please 
% choose 'none' from the respective drop-down menu. For elements you 
% want to calibrate it is recommended to choose 'unknown' (meaning that
% you do not know the sensitivity of this element). All other options 
% are default entries for specific pieces of equipment and can be 
% ignored. If you do not want to calibrate each element individually,
% just declare the 'sensor' as 'unknown' and all other elements as 
% 'none'. This way you can calibrate the entire chain at once with a 
% sensor calibration device (e.g. a pistonphone).
Johannes Klein's avatar
 
Johannes Klein committed
52 53 54 55
%
% We'll also define an FFT-degree of 19, meaning that our recording time
% will be 2^19 Samples.
%
Johannes Klein's avatar
Johannes Klein committed
56 57 58 59 60 61 62 63 64 65
% We'll set a sampling rate of 44100 Hz. To fulfill the Nyquist 
% criterion (f_sampling = f_measurement * 2) you need to sample your 
% signal with 2 times the highest frequency it contains. The highest 
% audible frequency for humans is about 20 kHz. With a margin of safety 
% we consider it to be 22050 Hz, resulting in a 44100 Hz sampling 
% frequency Combined with the FFT-degree of 19, this will amount to 
% 11.9 s of recording time. With the itaMSRecord class, it is only 
% possible to define fixed recording times. If you need an unknown or 
% infinite recording time, you're probably better off with normal DAWs, 
% e.g. Reaper http://www.reaper.fm .
Johannes Klein's avatar
Johannes Klein committed
66
MS.inputChannels = 1; % for multiple channels (e.g. 1, 2 & 3): [1 2 3] 
Johannes Klein's avatar
 
Johannes Klein committed
67 68 69
MS.fftDegree = 19;
MS.samplingRate = 44100;

Johannes Klein's avatar
Johannes Klein committed
70 71 72 73 74
% To have a look at all the settings you can just type the name of your
% measurement setup object (e.g. 'MS') in the MATLAB command line and
% have a look at the output.
MS

Johannes Klein's avatar
 
Johannes Klein committed
75 76 77 78 79 80
%% Calibration
% To measure absolute SPL, it is mandatory to calibrate the input.
% This is possible if you enabled the 'Measurement Chain' in the
% ita_preferences. If you do not wish to calibrate a certain element
% (not recommended, why would you have specified it before?) you can
% just accept the default value ('1') by clicking accept. To calibrate
Johannes Klein's avatar
Johannes Klein committed
81 82
% the element, connect you calibrator (pistonphone, voltage source,
% etc), specify the properties of the calibrator in the GUI and click
Johannes Klein's avatar
 
Johannes Klein committed
83
% 'calibrate'. If the calibration does not report an error (like 'No
Johannes Klein's avatar
Johannes Klein committed
84 85
% calibration signal detected'), a new calibration value will be shown
% in the GUI. You can either repeat the calibration to see if that value
Johannes Klein's avatar
 
Johannes Klein committed
86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102
% changes, or accept the value if it seems reasonable by clicking
% 'Accept'. The calibration GUI will then open for the next element to
% be calibrated. After the last element the GUI will just close.
MS.calibrate;

% Have a look at the calibrated elements.
MS.inputMeasurementChain


%% Recording
% Now the the actual recording can be started (class method 'run'). Make
% sure you use a unique and meaningful target variable name. In this
% case we'll use the generic name 'result'. This target variable will be
% an itaAudio object and can be used with all signal processing tools of
% the ITA Toolbox.
result = MS.run;

Johannes Klein's avatar
Johannes Klein committed
103 104 105 106 107 108 109 110 111 112 113 114 115
% After the measurement you will see some command line output. The 
% interesting part for you right now is the 'Maximum digital level' 
% value. Its unit is 'dBFS' (dB full scale). 0 dBFS means that your
% recorded signal uses 100% of the available quantization range of your
% A/D converter. Signals with an amplitude above 0 dBFS will be clipped
% and you will get a warning in the command line saying 'Careful, 
% clipping or something else went wrong!'. The only solution to that 
% problem is to reduce the sensitivity of your input hardware (if 
% possible) or to move away further from the sound source. A signal in 
% the range from -20 dBFS to -5 dBFS usually provides good and safe 
% measurement results.


Johannes Klein's avatar
 
Johannes Klein committed
116 117 118 119
% Have a look at the result in the time domain (.plot_time or pt)
result.pt

% Have a look at the result in the time domain with a dB scale
Johannes Klein's avatar
Johannes Klein committed
120
% (.plot_time_dB or .ptd)
Johannes Klein's avatar
 
Johannes Klein committed
121 122 123 124 125 126 127 128 129 130 131
result.ptd

% Have a look at the result in the frequency domain (.plot_freq or pf)
result.pf

% You can also check your calibration by running a measurement with the
% pistonphone connected. Just repeat the MS.run command (if you don't
% specify a target variable, the measurement result will be in the
% standard variable 'ans') and have a look at the frequency domain
% (.pf). You should see an amplitude of 94dB (depending on your
% pistonphone) at 1000 Hz (also a property of your phone).
Johannes Klein's avatar
Johannes Klein committed
132 133

%% Save data
Johannes Klein's avatar
Johannes Klein committed
134
% To save your measurement data for later post processing you can use
Johannes Klein's avatar
Johannes Klein committed
135 136 137 138
% the 'ita_write' function. It's first input argument is the itaAudio
% object you want to save (e.g. 'result'), the second one is the 
% filename (optionally including the full file path). Without a path
% (as in the example below) the file will be saved in the 
Johannes Klein's avatar
Johannes Klein committed
139 140 141
% 'current folder' in MATLAB. If you specify a '.ita' extension, the 
% data will be saved as itaAudio. '.wav' will save the data as 
% normalized WAV file.
Johannes Klein's avatar
Johannes Klein committed
142
ita_write(result, 'result_file.ita');
Johannes Klein's avatar
Johannes Klein committed
143 144 145 146 147 148 149
% In case you would like to save all the workspace variables (including 
% you measurement setup ('MS') and the result ('result') you can also 
% use the native 'save' command. In this example we'll save everything 
% to a file called 'workspace.mat'.
save('workspace.mat');
% Congrats! Now you are able to do a calibrated measurement and save 
% your results. Happy data acquisition!