Skip to content

Commit

Permalink
Release 4.5.2
Browse files Browse the repository at this point in the history
  • Loading branch information
@tobiasherzke
tobiasherzke committed Dec 6, 2017
1 parent 4a05543 commit 84c056a
Show file tree
Hide file tree
Showing 133 changed files with 11,831 additions and 498 deletions.
41 changes: 27 additions & 14 deletions .gitignore
View file
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
# This file is part of the HörTech Open Master Hearing Aid (MHA)
# This file is part of the HörTech Open Master Hearing Aid (openMHA)
# Copyright © 2013 2014 2015 2016 2017 HörTech gGmbH
#
# openMHA is free software: you can redistribute it and/or modify
Expand All @@ -13,26 +13,39 @@
# 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/>.

# The readme recommends copying all plugins into one "bin" directory.
bin

# Editor backup and lock files
*~
.#*
#*#
\#*#
*.bak
~$*
.~lock*

# system-specific configuration
config.mk
autom4te.cache
build
mha.creator.user

# An artifact left by octave when it crashes
mha/tools/mfiles/octave-workspace

meeting_notes/openMHA_status_May-17/openMHA_status_June-17.aux
meeting_notes/openMHA_status_May-17/openMHA_status_June-17.bbl
meeting_notes/openMHA_status_May-17/openMHA_status_June-17.blg
meeting_notes/openMHA_status_May-17/openMHA_status_June-17.nav
meeting_notes/openMHA_status_May-17/openMHA_status_June-17.out
meeting_notes/openMHA_status_May-17/openMHA_status_June-17.pdf
meeting_notes/openMHA_status_May-17/openMHA_status_June-17.snm
meeting_notes/openMHA_status_May-17/openMHA_status_June-17.synctex
meeting_notes/openMHA_status_May-17/openMHA_status_June-17.toc
# platform-specific directories where build artifacts are stored.
x86_64-linux-gcc-5
x86_64-linux-gcc-7
i686-linux-gcc-5
i686-MinGW-gcc-6
armv7l-linux-gcc-4.9

# coverage analysis artifacts
coverage.info
coverage
*.gcda
*.gcno

# octave specific files
mha/tools/mfiles/classpath.txt

# Local Variables:
# coding: utf-8-unix
# End:
8 changes: 5 additions & 3 deletions Makefile
View file
Original file line number Diff line number Diff line change
Expand Up @@ -30,8 +30,8 @@ MODULES = \
mha/libmha \
mha/frameworks \
mha/plugins \
mha/mhatest \
external_libs \
mha/mhatest \

DOCMODULES = \
mha/doc/flowcharts \
Expand All @@ -41,19 +41,21 @@ DOCMODULES = \

all: $(MODULES)

.PHONY : $(MODULES) $(DOCMODULES)
.PHONY : $(MODULES) $(DOCMODULES) coverage

$(MODULES:external_libs=) $(DOCMODULES):
$(MAKE) -C $@

external_libs:
$(MAKE) -j 1 -C $@
$(MAKE) -C $@

doc: mha/doc

clean:
for m in $(MODULES) $(DOCMODULES); do $(MAKE) -C $$m clean; done

install: all
mkdir -p bin; cp `find . -name *.so` mha/frameworks/$(BUILD_DIR)/mha bin
# Inter-module dependencies. Required for parallel building (e.g. make -j 4)
mha/libmha: external_libs
mha/frameworks: mha/libmha
Expand Down
195 changes: 140 additions & 55 deletions README.md
View file
Original file line number Diff line number Diff line change
@@ -1,107 +1,159 @@
# openMHA

HörTech Open Master Hearing Aid (openMHA)
HörTech Open Master Hearing Aid (openMHA)

1. Content of the openMHA release 4.5.1 (2017-07-17)
1. Content of the openMHA release 4.5.2 (2017-12-06)

The software contains the source code of the openMHA Toolbox library, of the
openMHA framework and command line application, and of a selection of algorithm
The software contains the source code of the openMHA Toolbox library, of the
openMHA framework and command line application, and of a selection of algorithm
plugins forming a basic hearing aid processing chain featuring
- calibration
- bilateral adaptive differential microphones for noise suppression
- binaural coherence filter for feedback reduction and dereverberation
- multi-band dynamic range compressor for hearing loss compensation
- beamformer algorithm (delay-and-sum, and also MVDR)
- single-channel noise reduction
- bilateral adaptive differential microphones for noise suppression [1]
- binaural coherence filter for feedback reduction and dereverberation [2]
- multi-band dynamic range compressor for hearing loss compensation [3]
- spatial filtering algorithms:
- a delay-and-sum beamformer
- a MVDR beamformer [4]
- single-channel noise reduction [5]
- simple upsampling and downsampling plugins
- STFT cyclic aliasing prevention
- simpler dynamic compressor
- adaptive feedback cancellation [6]

2. Citation in publications

In publications using openMHA, please cite

Herzke, T., Kayser, H., Loshaj, F., Grimm, G., Hohmann, V., Open signal
processing software platform for hearing aid research (openMHA).
Proceedings of the Linux Audio Conference. Université Jean Monnet,
Saint-Étienne, pp. 35-42, 2017.
Proceedings of the Linux Audio Conference. Université Jean Monnet,
Saint-Étienne, pp. 35-42, 2017.

As we are working on an updated paper, please check back this section
of the README for updates.

3. Source Code Overview
For individual algorithms, please also refer to the list of
publications at the end of this README.

Together with the MHA source code, we deliver the source code for the FFTW
3. Installation from binary packages on Ubuntu.

First, add the package source with the openMHA Debian packages to your system:

under Ubuntu 16.04

sudo apt-add-repository 'deb http://mha.hoertech.de/hoertech/xenial /'

under Ubuntu 14.04

sudo apt-add-repository 'deb http://mha.hoertech.de/hoertech/trusty /'

Update the list of available packages:

sudo apt-get update

This will give you a warning:

W: The repository 'http://mha.hoertech.de/hoertech/xenial Release' does not have a Release file.
N: Data from such a repository can't be authenticated and is therefore potentially dangerous to use.
N: See apt-secure(8) manpage for repository creation and user configuration details.

Install openMHA:

sudo apt-get install openmha

This will give you again an authentication warning:
WARNING: The following packages cannot be authenticated! openmha libopenmha Install these packages without verification? [y/N]

To install openMHA you have to type "y".

The authentification issue will be resolved in the future.

After installation, openMHA dcoumentation is found in
/usr/share/doc/openmha
and tools for GNU Octave/Matlab here:
/usr/lib/openmha/mfiles

To update openMHA when a new release is available run

sudo apt-get install --only-upgrade openmha



4. Source Code Overview

Together with the MHA source code, we deliver the source code for the FFTW
library, version 2.1.5, below the directory external_libs.
All openMHA source code lives under the directory mha: The MHA Toolbox
Library can be found in the sub-directory mha/libmha. It contains the
implementation of the MHA configuration language, of signal processing
primitives and also many signal processing algorithms to by used in MHA
plugins. The MHA command line application and its support framework
can be found in the sub-directory mha/frameworks. The plugins contained in this
release can be found in the sub-directory mha/plugins. The IO libraries,
that connect the MHA e.g. to the sound card for live processing, or to sound
files for offline processing, are also found here.
plugins. The MHA command line application and its support framework
can be found in the sub-directory mha/frameworks. The plugins contained in this
release can be found in the sub-directory mha/plugins. The IO libraries,
that connect the MHA e.g. to the sound card for live processing, or to sound
files for offline processing, are also found here.

4. Build Instructions
5. Build Instructions

The MHA source code has to be compiled before the MHA can be used. While MHA in
general can be compiled for many operating systems and hardware platforms, in
The MHA source code has to be compiled before the MHA can be used. While MHA in
general can be compiled for many operating systems and hardware platforms, in
this release we concentrate on compilation on Ubuntu 16.04 for 64-bit PC
processors (x86_64) and on Debian 8 (jessie) for the Beaglebone Black
single-board ARM computer.
single-board ARM computer.

Prerequisites:
Prerequisites:
64-bit version of Ubuntu 16.04 or later,
or a Beaglebone Black with Debian jessie installed.

with the following software packages installed:
with the following software packages installed:
- g++-5 for Ubuntu, g++-4.9 for Debian
- make
- libsndfile1-dev,
- make
- libsndfile1-dev,
- libjack-jackd2-dev
- jackd2
- optional: octave and default-jre
- jackd2
- portaudio19-dev
- optional:
- octave with the signal package and default-jre (e.g. openjdk-8-jre
and openjdk-8-jdk for Debian 9)

octave and default-jre are not essential for building or running the
openMHA. The build process uses octave + java to run some tests after
building openMHA. If octave is not available, this will fail. But
the produced openMHA will still work.
building openMHA. If octave is not available, this test will fail.
But the produced openMHA will still work.

The optional GUI (cf. openMHA_gui_manual.pdf) requires java-enabled
octave in version >= 4.2.1.

5. Compilation instructions:
6. Compilation instructions:

After downloading and unpacking the openMHA package, or cloning from github,
compile the MHA with ./configure && make

5.1 Installation instructions:
6.1 Installation instructions:

No installation routine is provided together with the source code. The binaries
will be generated in the source tree. To collect the relevant binaries in one
place, you may e.g. create a bin directory and copy all the binaries there with
A very simple installation routine is provided together with the
source code. To collect the relevant binaries in a subdirectory
"bin", execute

mkdir bin; cp $(find . -name *.so) mha/frameworks/x86_64-linux-gcc-5/mha bin
make install

Then, you should set the environment variable LD_LIBRARY_PATH to point to your
bin directory, like this:
Then, you should set the environment variable LD_LIBRARY_PATH to point to your
bin directory, like this:

export LD_LIBRARY_PATH=$PWD/bin
export LD_LIBRARY_PATH=$PWD/bin

You can also add the bin directory to the PATH environment variable:
You can also add the bin directory to the PATH environment variable:

export PATH=$PATH:$PWD/bin
export PATH=$PATH:$PWD/bin

After this, you can invoke the MHA command line. Perform a quick test with
After this, you can invoke the MHA command line. Perform a quick test with

mha ? cmd=quit
mha ? cmd=quit

Which should print the default configuration of the MHA without any plugins
loaded.
Which should print the default configuration of the MHA without any plugins
loaded.


6. Usage instructions:
7. Usage instructions:

We provide with this release several examples of configuration files
and sound examples. These are contained in the directory
Expand All @@ -110,21 +162,54 @@ and sound examples. These are contained in the directory
For example, we can start an example featuring multiple algorithms
together with the following command:

mha ?read:mha/configurations/prerelease_combination.cfg cmd=start cmd=quit
mha ?read:mha/configurations/prerelease_combination.cfg cmd=start cmd=quit

7. Documentation:
8. Documentation:

User manuals for different levels of usability in pdf format is provided
with this release. These files can also be generated by typing 'make doc' in
the terminal and the manuals will be created in the ./mha/doc/ directory. In
addition, html documentation is generated in ./mha/doc/mhadoc/html/ and
./mha/doc/mhaplugins/html/
User manuals are provided in PDF format. Recreating them from source is
normally not necessary.

Prerequisites:
User manuals for different levels of usability in PDF format are
provided with this release. These files can also be generated by
typing 'make doc' in the terminal. The new manuals will be created in
the ./mha/doc/ directory. In addition, html documentation is
generated in ./mha/doc/mhadoc/html/ and ./mha/doc/mhaplugins/html/

Prerequisites for recreating the documents (Optional!):
Extra packages are needed for generating documentation:

- doxygen
- xfig
- graphviz
- texlive
- texlive-latex-extra


9. References for individual algorithms.

[1] Elko GW, Pong ATN. A Simple Adaptive First-order Differential
Microphone. In: Proceedings of 1995 Workshop on Applications of Signal
Processing to Audio and Accoustics; 1995. p. 169–172.

[2] Grimm G, Hohmann V, Kollmeier B. Increase and Subjective
Evaluation of Feedback Stability in Hearing Aids by a Binaural
Coherence-based Noise Reduction Scheme. IEEE Transactions on Audio,
Speech, and Language Processing. 2009;17(7):1408–1419.

[3] Grimm G, Herzke T, Ewert S, Hohmann V. Implementation and
Evaluation of an Experimental Hearing Aid Dynamic Range Compressor
Gain Prescription. In: DAGA 2015; 2015. p. 996–999.

[4] Adiloğlu K, Kayser H, Baumgärtel RM, Rennebeck S, Dietz M, Hohmann
V. A Binaural Steering Beamformer System for Enhancing a Moving Speech
Source. Trends in Hearing. 2015;19:2331216515618903

[5] Gerkmann T, Hendriks RC. Unbiased MMSE-Based Noise Power
Estimation With Low Complexity and Low Tracking Delay. IEEE
Transactions on Audio, Speech, and Language
Processing. 2012;20(4):1383–1393.

[6] Schepker H, Doclo S, A semidefinite programming approach to
min-max estimation of the common part of acoustic feedback paths in
hearing aids. IEEE Transactions on Audio, Speech, and Language
Processing. 2016;24(2):366-377.
4 changes: 1 addition & 3 deletions external_libs/.gitignore
View file
Original file line number Diff line number Diff line change
Expand Up @@ -12,7 +12,5 @@
#
# 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/>.

fftw-2.1.5
x86_64-linux-gcc-5
i686-linux-gcc-5
armv7l-linux-gcc-4.9
Loading

0 comments on commit 84c056a

Please sign in to comment.