%% THD+N Measurement with Tone-Tracking
%
% This example shows how to measure total harmonic distortion and noise
% level of audio input and output devices. 

% Copyright 2015-2018 The MathWorks, Inc.

%% Introduction
% Audio input and output devices are non-linear in nature. This causes
% harmonic distortion in the audio signal. Apart from the unwanted signals
% that may be harmonically related to the signal, these devices can also
% add uncorrelated noise to the audio signal.
%
% Total Harmonic Distortion and Noise (THD+N) quantifies the sum of these
% two distortions. It is defined as the root mean square (RMS) level of all
% harmonics and noise components over a specified bandwidth. The signal
% level is also specified as a reference.
%
%% Measurement of THD+N
% This example introduces a reference model that can be used for THD+N
% measurements of audio input and output devices. The steps involved in
% measurement are:
%
% # Generate a pure sine wave of a specific frequency.
% # Play the signal through an audio output device and record it through an
% audio input device.
% # From the recorded signal, identify the sine wave peak. This will give
% the reference signal RMS level.
% # Remove the identified sine wave from recorded signal. What remains is
% everything unwanted, and its RMS will give THD+N value.
%
% This example follows the AES17-1998(r2004) [1] standard for THD+N
% measurement. The standard recommends a 997 Hz frequency sine wave. It
% also recommends a notch filter having Q between 1 and 5 for filtering out
% the sine wave from recorded signal. A Q value of 5 is used in this
% example.
open_system('audioTHDNmeasurementexample');

%% 
% The |audioTHDNmeasurementexample| model implements a reference system for
% measuring THD+N. Following the AES17-1998(r2004) standard, the sine wave
% source |Test Tone| generates a frequency of 997 Hz. The subsystem |System
% Under Test| is a variant subsystem. By default, it selects a non-linear
% model implemented in Simulink for measuring the THD+N. To perform the
% measurement on your machine's audio input and output device, set the
% |SUT| variable in base workspace to THDNDemoSUT.AudioHardware.
%
% The measurement is done by the |THD+N Measurement| subsystem.
open_system('audioTHDNmeasurementexample/THD+N Measurement', 'force');

%% Dual-Bandpass Controller
% The measurement system in the model uses a dual-peak tracking filter to
% locate the notch at the test tone's fundamental. This accommodates signal
% generators that are not synchronized to the ADC clock. The output of this
% block is the center frequency coefficient of the notch filter that will
% be used to extract the test sine tone. The two peaking filters in the
% controller are implemented using <docid:dsp_ref#bt77v0b-1
% dsp.NotchPeakFilter> System objects. When the model is run, the feedback
% loop works to adjust the center frequencies of the two peaking filters in
% such a way that the output locks on to the peak tone of the input.
open_system('audioTHDNmeasurementexample/THD+N Measurement/Dual-Bandpass Controller', 'force');

%% Notch-Peak Filter
% Once the frequency of the sine wave has been identified, pass it to a
% peaking filter to extract the test tone signal. This will be used to
% determine the test signal's peak level. A notch filter will then use the
% same center frequency to remove the sine wave. The remaining signal is
% the sum of the total harmonic distortion and noise. Use a single
% |dsp.NotchPeakFilter| to get both - notch and peak outputs. The Q-factor
% of this filter is chosen as 5, conforming to AES17-1998 standard.

%% THD+N Computer
% The |THD+N Computer| subsystem mimics a signal level meter. It takes the
% notch and peak outputs and smooths them using a lowpass filter. It then
% converts the level of the signals to dB.
open_system('audioTHDNmeasurementexample/THD+N Measurement/THD+N Computer', 'force');

%%
% You can run the model and see the displays update with measured sine wave
% frequency, THD+N level in dB, and reference signal level in dB.

close_system('audioTHDNmeasurementexample',0);

%% References
% [1] AES17-1998 "AES standard method for digital audio engineering -
% Measurement of digital audio equipment", Audio Engineering Society
% (1998), r2004.
