%%% This file is part of the Open HörTech Master Hearing Aid (openMHA)
%%% Copyright © 2005 2006 2007 2013 2017 2018 HörTech gGmbH
%%%
%%% openMHA is free software: you can redistribute it and/or modify
%%% it under the terms of the GNU Affero General Public License as published by
%%% the Free Software Foundation, version 3 of the License.
%%%
%%% openMHA is distributed in the hope that it will be useful,
%%% but WITHOUT ANY WARRANTY; without even the implied warranty of
%%% MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
%%% GNU Affero General Public License, version 3 for more details.
%%%
%%% You should have received a copy of the GNU Affero General Public License, 
%%% version 3 along with openMHA.  If not, see <http://www.gnu.org/licenses/>.

\section{Introduction}
The H\"{o}rTech \emph{open Master Hearing Aid} (\mha), is a development
and evaluation software platform that is able to execute hearing aid signal
processing in real-\/time on standard computing hardware with a low delay
between sound input and output.

\subsection{Structure}\label{index_str}
The openMHA can be split into four major components :
\begin{itemize}
\item The openMHA command line application (MHA)
\item Signal processing plugins (plugins)
\item Audio input-\/output modules (IO)
\item The openMHA toolbox library (libopenmha)
\end{itemize} 
\MHAfigure[][0.4\linewidth]{Layered structure of the open Master Hearing Aid}{structure_openmha}

{\bf The MHA command line application} acts as a plugin host. It can
load signal processing plugins as well as audio input-\/output modules
(IO). Additionally, it provides the command line configuration
interface and a TCP/IP based configuration interface. Different IO
modules exist: For real-\/time signal processing, commonly the openMHA
\emph{MHAIOJack} module is used, which provides an
interface to the Jack Audio Connection Kit (JACK), the module
\emph{MHAIOFile} provide audio file access and \emph{MHAIOTCP}
TCP/IP-\/based signal exchange.

{\bf openMHA plugins} provide the audio signal processing capabilities and audio signal handling. Typically, one openMHA plugin implements one specific algorithm. A complete virtual hearing aid signal processing can be achieved by a combination of several openMHA plugins.\subsection{Platform Services and Conventions}\label{index_pltf}
The openMHA platform offers some services and conventions to algorithms implemented in plugins, that make it especially well suited to develop hearing aid algorithms, while still supporting general-\/purpose signal processing.\subsubsection{Audio Signal Domains}\label{index_asd}
As in most other plugin hosts, the audio signal in the openMHA is processed in fragments, i.e., in chunks of the input signal stream with a defined length. However, plugins are not restricted to propagate audio signal as fragments of audio samples in the time domain another option is to propagate the audio signal in the short time Fourier transform (STFT) domain, i.e. as spectra of fragments of audio signal, so that not every plugin has to perform its own STFT analysis and synthesis. Since STFT analysis and re-\/synthesis of acceptable audio quality always introduces an algorithmic delay, sharing STFT data is a necessity for a hearing aid signal processing platform in order to achieve a sufficiently low delay for the whole processing chain.

In addition, the openMHA allows arbitrary data to be exchanged between plugins through a mechanism called algorithm communication variables, (AC vars). This mechanism is commonly used to share data such as filter coefficients or filter states.\subsubsection{Real-\/Time Safe Complex Configuration Changes}\label{index_rtscc}
Hearing aid algorithms in the openMHA can export configuration settings that may be changed by the user at run time.

To ensure real-\/time safe signal processing, the audio processing will normally be done in a signal processing thread with real-\/time priority, while user interaction with configuration parameters would be performed in a configuration thread with normal priority, so that the audio processing does not get interrupted by configuration tasks. Two types of problems may occur when the user is changing parameters in such a setup:
\begin{DoxyItemize}
\item The change of a simple parameter exposed to the user may cause an involved recalculation of internal runtime parameters that the algorithm actually uses in processing. The duration required to perform this recalculation may be a significant portion of (or take even longer than) the time available to process one block of audio signal. In hearing aid usage, it is not acceptable to halt audio processing for the duration that the recalculation may require.
\item If the user needs to change multiple parameters to reach a desired configuration state of an algorithm from the original configuration state, then it may not be acceptable that processing is performed while some of the parameters have already been changed while others still retain their original values. It is also not acceptable to interrupt signal processing until all pending configuration changes have been performed.
\end{DoxyItemize}The openMHA provides a mechanism in its toolbox library to enable real-\/time safe configuration changes in openMHA plugins:
As in hearing aids, it is more acceptable to continue to use an outdated configuration for a few more milliseconds than blocking all processing, existing runtime configurations are used in the processing thread until the work of creating an updated runtime configuration has been completed in the configuration thread.

The openMHA toolbox library provides an easy-\/to-\/use mechanism to integrate real-\/time safe runtime configuration updates into every plugin.\subsubsection{Plugins can Themselves Host Other Plugins}\label{index_bridge}
An openMHA plugin can itself act as a plugin host. This allows to combine analysis and re-\/synthesis methods in a single plugin. Plugins that themselves can load other plugins are called \emph{bridge plugins} in the openMHA.

When such a bridge plugin is then called by the openMHA to process one block of signal, it will first perform its analysis, then invoke (as a function call) the signal processing in the loaded plugin to process the block of signal in the analysis domain, wait to receive a processed block of signal in the analysis domain back from the loaded plugin when the signal processing function call to that plugin returns, then perform the re-\/synthesis transform, and finally return the block of processed signal in the original domain back to the caller of the bridge plugin.\subsubsection{Central Calibration}\label{index_clb}
The purpose of hearing aid signal processing is to enhance the sound for hearing impaired listeners. Hearing impairment generally means that people suffering from it have increased hearing thresholds, i.e. soft sounds that are audible for normal hearing listeners may be imperceptible for hearing impaired listeners. To provide accurate signal enhancement for hearing impaired people, hearing aid signal processing algorithms have to be able to determine the absolute physical sound pressure level corresponding to a digital signal given to any openMHA plugin for processing. Inside the openMHA, we achieve this with the following convention: The single-\/precision floating point time-\/domain sound signal samples, that are processed inside the openMHA plugins in blocks of short durations, have the physical pressure unit Pascal ( $1 \mathrm{Pa} = 1 \mathrm{N} / \mathrm{m}^2$). With this convention in place, all plugins can determine the absolute physical sound pressure level from the sound samples that they process. A derived convention is employed in the spectral domain for STFT signals. Due to the dependency of the calibration on the hardware used, it is the responsibility of the user of the openMHA to perform calibration measurements and adapt the openMHA settings to make sure that this calibration convention is met. We provide the plugin {\ttfamily transducers} which can be configured to perform the necessary signal adjustments. 

%%% Local Variables: 
%%% mode: latex
%%% TeX-master: "openMHA_application_manual"
%%% indent-tabs-mode: nil
%%% coding: utf-8-unix
%%% End:
