Extended Tutorial

tutorials/ita_tutorial_record.m

@@ -2,25 +2,29 @@
 %
 % 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
-% of the itaMSRecord class, the basic recording class of the ITA toolbox.
-%
+% of the itaMSRecord class, the basic recording class of the ITA
+% toolbox.
 %
 % <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>
+%
+% For feedback or questions, please contact the ITA Toolbox developers:
+% toolbox-dev@akustik.rwth-aachen.de
+%
+% JCK 2017
 
 %% Set Hardware
 % Set your recording hardware in 'IO Settings'-tab ('recording' and
-% 'playback device'). For a calibrated measurement it is also recommended
-% to check 'Measurement Chain' on the % same 'IO Settings' tab.
-
-
+% 'playback device'). For a calibrated measurement it is also
+% recommended to check 'Measurement Chain' on the % same 'IO Settings'
+% tab.
 ita_preferences;
 
 %% Clear Workspace
-% The 'ccx' command basically resets Matlab to its start-up state.
+% The 'ccx' command basically resets MATLAB to its start-up state.
 ccx;
 
 %% Measurement Setup
@@ -36,26 +40,36 @@ MS = itaMSRecord;
 % We'll also define an FFT-degree of 19, meaning that our recording time
 % will be 2^19 Samples.
 %
-% We'll set a sampling rate of 44100 Hz. 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 .
+% 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 .
 MS.inputChannels = 1;
 MS.fftDegree = 19;
 MS.samplingRate = 44100;
 
+% 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
+
 %% 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
-% the element, connect you calibrator (pistonphone, voltage source, etc),
-% specify the properties of the calibrator in the GUI and click
+% the element, connect you calibrator (pistonphone, voltage source,
+% etc), specify the properties of the calibrator in the GUI and click
 % 'calibrate'. If the calibration does not report an error (like 'No
-% calibration signal detected'), a new calibration value will be shown in
-% the GUI. You can either repeat the calibration to see if that value
+% calibration signal detected'), a new calibration value will be shown
+% in the GUI. You can either repeat the calibration to see if that value
 % 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.
@@ -73,11 +87,24 @@ MS.inputMeasurementChain
 % the ITA Toolbox.
 result = MS.run;
 
+% 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.
+
+
 % 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
-% (.plot_time_dB or ptd)
+% (.plot_time_dB or .ptd)
 result.ptd
 
 % Have a look at the result in the frequency domain (.plot_freq or pf)
@@ -89,6 +116,15 @@ result.pf
 % 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).
-%
+
+%% Save data
+% To save your measurement data for later post processing you should use
+% 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 
+% 'current folder' in MATLAB.
+ita_write(result, 'result_file.ita');
+
 % Congrats! Now you are able to do a calibrated measurement.
 % Happy data acquisition!
\ No newline at end of file