%% Multiband Dynamic Range Compression for iOS Devices
% This example shows how to use the <docid:audio_ref#bu_1489-1 Crossover
% Filter> block and <docid:audio_ref#bu1d_ek-1 compressor> System object(TM) from
% the Audio Toolbox(TM) to implement a multiband dynamic range compressor
% model. You can run the model on your host computer or deploy it to an
% Apple iOS device.

% Copyright 2016-2019 The MathWorks, Inc.

%% Introduction
% Dynamic range compression reduces the dynamic range of a signal by 
% attenuating the level of strong peaks, while leaving weaker peaks 
% unchanged. Compression has applications in audio recording, mixing, and 
% broadcasting.
%
% Multiband compression compresses different audio frequency bands 
% separately, by first splitting the audio signal into multiple bands and 
% then passing each band through its own independently adjustable 
% compressor. Multiband compression is widely used in audio mastering and 
% is often included in digital audio workstations.
%
% The multiband compressor in this example first splits an audio signal 
% into different bands using a multiband crossover filter. Linkwitz-Riley 
% crossover filters are used to obtain an overall allpass frequency 
% response. Each band is then compressed using a separate dynamic range 
% compressor. Key compressor characteristics, such as the threshold, 
% the compression ratio, the attack time and the release time are
% independently tunable for each band. You can run the model either on the 
% host computer or an Apple iOS device. 
 
%% Required Hardware
% To run this example on iOS devices you need the following hardware:
%
% * iPhone, iPod or an iPad
% * Host computer with Mac OS X system
% * USB cable to connect the iOS device to host computer
% 
%% Model Setup
%
% <<../audiomultibandcompressoriOS_model.png>>
%
%%
% The |audiomultibandcompressoriOS| model is a cascade of audio sources, a
% multiband crossover filter, compressors, and a display subsystem. It
% provides a choice of model running device (host computer or iOS device)
% and audio source (MATLAB workspace or microphone). You can choose the
% configuration by clicking the |Configuration UI| button.
% 
% Configuration UI:
%
% <<../audiomultibandcompressoriOS_configuration.png>>
%
%% Crossover Filter
% 
% A crossover filter can split an audio signal into two or more 
% frequency bands. Its overall magnitude frequency response is flat, which
% retains frequency domain properties of an input audio signal.
% 
% In this model, you use the <docid:audio_ref#bu_1489-1 Crossover Filter>
% block from Audio Toolbox. You can open the block UI by clicking
% |Crossover Filter UI| and modify the cut-off frequencies.
%
% Crossover Filter UI:
%
% <<../audiomultibandcompressoriOS_crossoverfilter.png>>
%
% Note the |Number of crossovers| is set to |3| in this model to make a
% 4-band compressor. To make sure the model works properly, please keep
% |Number of crossovers| to be |3| and do not change it to other values.
%
%% Multiband Dynamic Range Compressor 
%
% In this example, the multiband dynamic range compressor is composed of
% four parallel single band compressors. Each single band
% <docid:audio_ref#bu1d_ek-1 compressor> controls one frequency band, whose
% frequency range is set by the crossover filter.
%
% There are four principal parameters for each single band compressor:
%
% * Threshold - the level above which the input signal is compressed
% * Ratio - the amount of compression
% * Attack time - the time it takes the compressor gain to rise from 10% to
% 90% of its final value when the input goes above the threshold
% * Release time -  the time it takes the compressor gain to drop from 90%
% to 10% of its final value when the input goes below the threshold
%
% In this example, you can modify the parameters for the four bands
% independently and view the static compression characteristic plots in
% real time.
%
%% Run Model on the Host Computer
% When you choose to run the model on the host computer, you can tune the 
% compressor parameters by clicking |Compressor Host Tuning UI|. 
% 
% Compressor Host Tuning UI:
% 
% <<../audiomultibandcompressoriOS_hosttuning.png>>
%
% The UI enables you to tune the parameters of four single-band compressors
% individually, and view the static compression characteristics in real
% time. You can check the |Bypass| check box to compare the modified sound
% with the original sound.
%
% Click the |View static characteristic| button to visualize the static
% compression characteristic plot.
% 
% <<../audiomultibandcompressoriOS_staticcharacteristic.png>>
%
% To compare the dynamic range of the uncompressed and compressed signals,
% the dynamic range is computed and displayed on the Simulink Model
% Display bar. The waveform of the uncompressed and compressed
% signals is also plotted in real time.
%
% Waveform of the uncompressed and compressed signals: 
%
% <<../audiomultibandcompressoriOS_arrayplot.png>>
% 
%% Run Model on an Apple iOS Device
%
% To run the model on your Apple iOS device, you need to first ensure that
% you have installed |Simulink Support Package for Apple iOS Devices| and
% that your iOS device is provisioned.
%
% Once your iOS device is properly configured, use a USB cable to connect
% the device to your host computer.
%
% You can choose to make an iOS standalone app by clicking the |Deploy to
% hardware| button on the Simulink Editor toolbar. After deployment, the
% app can run on your iOS device even when it is disconnected from the host
% computer. The compressor parameter tuning UI and the dynamic range
% display are designed on your iOS device screen, as shown below:
% 
% <<../audiomultibandcompressoriOS_slider1.jpg>>
%
% <<../audiomultibandcompressoriOS_slider2.jpg>>
%
% You can also run the model in |External| mode by clicking the |Run|
% button on the Simulink Editor toolbar. To run in |External| mode, the iOS
% device must stay connected to the host computer. Besides tuning
% compressor parameters on the iOS device screen, in this mode, you can
% open the |Crossover Filter UI| on the host computer and modify the
% cut-off frequencies while the model is running. This mode also enables
% you to view the dynamic range of the uncompressed and compressed signals
% in real time on the host computer.
