clarity.enhancer.gha package

Submodules

clarity.enhancer.gha.gainrule_camfit module

clarity.enhancer.gha.gainrule_camfit.compute_proportion_overlap(a1: float, a2: float, b1: float, b2: float) → float

Compute proportion of overlap of two ranges.

For ranges (a1, a2) and (b1, b2), express the extent of the overlap in the range as a proportion of the extent of range (b1, b2)

e.g (4, 9) and (6, 15) -> overlap (6,9), so proportion is (9-6)/(15-6)

clarity.enhancer.gha.gainrule_camfit.gainrule_camfit_compr(audiogram_left: Audiogram, audiogram_right: Audiogram, sFitmodel: FittingParams, noisegatelevels: float | ndarray = 45.0, noisegateslope: float | ndarray = 1.0, level: float = 0.0, max_output_level: float = 100.0) → tuple[ndarray, ndarray, ndarray]

Applies compressive Cambridge rule for hearing aid fittings ‘CAMFIT’.

Translation of OpenMHA gainrule_camfit_compr.m. Applies compressive Cambridge rule for hearing aid fittings ‘CAMFIT’. Computes gains for compression according to Moore et al. (1999) “Use of a loudness model for hearing aid fitting: II. Hearing aids with multi-channel compression.” Brit. J. Audiol. (33) 157-170

The gain rule limits the gains so that in each band 100 dB output level is not exceeded. This function assumes audiogram frequencies are identical for the two ears. In this implementation, any negative gains are set to 0 dB.

The original function is part of the HörTech Open Master Hearing Aid (openMHA) Copyright © 2007 2009 2011 2013 2015 2017 2018 HörTech gGmbH openMHA is free software: see licencing conditions at http://www.openmha.org/

Parameters:

• audiogram_left (Audiogram) – the audiogram for the left ear

• audiogram_right (Audiogram) – the audiogram for the right ear

• sFitmodel (dict) – contains the center frequencies for the amplification bands and input levels in SPL for which to compute the gains

• noisegatelevels (ndarray) – compression threshold levels for each frequency band (default: 45)

• noisegateslope (int) – determines slope of gains below compression threshold

• level (int) – input level in each band for compression rate calculation (default: 0 for variable level depending on insertion gains)

• max_output_level (int) – maximum output level in dB

Returns:

containing gain table, noise gate, and noise

gate expansion slope

Return type:

tuple

clarity.enhancer.gha.gainrule_camfit.gainrule_camfit_linear(audiogram_left: Audiogram, audiogram_right: Audiogram, sFitmodel: FittingParams, noisegatelevels: float | ndarray = 45.0, noisegateslope: float | ndarray = 1.0, max_output_level: float = 100.0) → tuple[ndarray, ndarray, ndarray, ndarray]

Apply linear Cambridge rule for hearing aid fittings ‘CAMFIT’.

Based on OpenMHA gainrule_camfit_linear.m. Applies linear Cambridge rule for hearing aid fittings ‘CAMFIT’. Implemented as described in B. Moore and B. Glasberg (1998), “Use of a loudness model for hearing-aid fitting. I. Linear hearing aids” Brit. J. Audiol. (32) 317-335.

The gain rule limits the gains so that in each band 100 dB output level is not exceeded. The Cambridge formula defines intercepts only up to 5 kHz. Because the intercepts do not vary much between 1kHz and 5kHz anyway (these are all within 0dB +/- 1dB), we extend the last intercept of +1dB at 5kHz to all higher frequencies. This function assumes audiogram frequencies are identical for two ears.

The original function is part of the HörTech Open Master Hearing Aid (openMHA) Copyright © 2007 2009 2011 2013 2015 2017 2018 HörTech gGmbH openMHA is free software: see licencing conditions at http://www.openmha.org/

Parameters:

• sAud (dict) – contains the subject-specific hearing threshold levels in dB HL for the left and right ears, and the audiogram frequencies

• sFitmodel (dict) – contains the center frequencies for the amplification bands and input levels in SPL for which to compute the gains

• noisegatelevels (ndarray) – compression threshold levels for each frequency band (default: 45)

• noisegateslope (int) – determines slope of gains below compression threshold (default: 1)

Returns:

containing gain table, noise gate, and noise

gate expansion slope

Return type:

tuple

clarity.enhancer.gha.gainrule_camfit.gains(compr_thr_inputs: ndarray, compr_thr_gains: ndarray, compression_ratios: ndarray, levels: ndarray) → ndarray

Based on OpenMHA gains subfunction of gainrule_camfit_compr.

Parameters:

• compr_thr_inputs (ndarray) – levels for speech in dynamic compression (dc) bands minus minima distance (38 dB)

• compr_thr_gains (ndarray) – interpolated audiogram levels plus conversion factors of HL thresholds to SPL thresholds (output of isothr) minus compr_thr_inputs

• compression_ratios (ndarray) – compression ratios according to CAMFIT compressive

• levels (ndarray) – set of levels over which to calculate gains e.g. -10:110 dB

Returns:

set of uncorrected gains as 2-d numpy array

Return type:

ndarray

clarity.enhancer.gha.gainrule_camfit.isothr(vsDesF: list[int] | ndarray) → ndarray

Calculate conversion factors of HL thresholds to SPL thresholds.

Translation of OpenMHA isothr.m. Calculates conversion factors of HL thresholds to SPL thresholds. Values from 20 Hz to 12500 Hz are taken from ISO 226:2003(E). Values from 14000 Hz to 18000 Hz are taken from ISO 389-7:2005 (reference thresholds of hearing for free field listening). Values at 0 and 20000 Hz are not taken from the ISO Threshold contour.

Parameters:

vsDesF (list) – centre frequencies for the amplification bands as 177, 297, 500, 841, 1414, 2378, 4000, 6727, 11314 Hz

Returns:

conversion factors

Return type:

ndarray

clarity.enhancer.gha.gha_interface module

class clarity.enhancer.gha.gha_interface.GHAHearingAid(sample_rate=44100, ahr=20, audf=None, cfg_file='prerelease_combination4_smooth', noise_gate_levels=None, noise_gate_slope=0, cr_level=0, max_output_level=100, equiv_0db_spl=100, test_nbits=16)

Bases: object

create_HA_inputs(infile_names: list[str], merged_filename: str) → None

Create input signal for baseline hearing aids.

The baseline hearing aid takes a 4-channel wav file as input. This is constructed from the left and right signals of the front (CH1) and rear (CH3) microphones that are available in the Clarity data.

Args:

infile_names (list[str]): Names of file to read merged_file_name (str): Name of file to write

Raises:

ValueError: If input channel names are inconsistent

create_configured_cfgfile(input_file, output_file, formatted_sGt, cfg_template_file)

Using Jinja2, generates cfg file for given configuration.

Creates template output file and configures with correct filenames, peak level out and DC gaintable.

Parameters:

• input_file (str) – file to process

• output_file (str) – file in which to store processed file

• formatted_sGt (ndarray) – gaintable formatted for input into cfg file

• cfg_template_file – configuration file template

• ahr (int) – amplification headroom

Returns:

cfg filename

Return type:

cfg_filename (str)

process_files(infile_names: list[str], outfile_name: str, listener: Listener)

Process a set of input signals and generate an output.

Parameters:

• infile_names (list[str]) – List of input wav files. One stereo wav file for each hearing device channel

• outfile_name (str) – File in which to store output wav files

• dry_run (bool) – perform dry run only

clarity.enhancer.gha.gha_utils module

class clarity.enhancer.gha.gha_utils.FittingParams

Bases: TypedDict

Fitting parameters for gaintable calculation.

channels: int

edge_frequencies: ndarray

frequencies: ndarray

levels: ndarray

side: str

class clarity.enhancer.gha.gha_utils.Gaintable

Bases: TypedDict

Gaintable for a given audiogram.

channels: int

frequencies: ndarray

levels: ndarray

noisegatelevel: ndarray

noisegateslope: ndarray

sGt: ndarray

sGt_uncorr: ndarray

clarity.enhancer.gha.gha_utils.format_gaintable(gaintable: Gaintable, noisegate_corr: bool = True) → str

Format gaintable for insertion into cfg file as long string.

Parameters:

• gaintable (ndarray) – The gaintable to format

• noisegate_corr (boolean, optional) – apply noisegate correction or do not (default: True)

Returns:

gaintable formatted for insertion into OpenMHA

cfg file

Return type:

str

clarity.enhancer.gha.gha_utils.get_gaintable(audiogram_left: Audiogram, audiogram_right: Audiogram, noisegate_levels: float | ndarray, noisegate_slope: float | ndarray, cr_level: float, max_output_level: float) → Gaintable

Compute a gaintable for a given audiogram.

Replaces MATLAB GUI interface of original OpenMHA software for gaintable_camfit_compr table calculation. Assumes two channels and that audiogram frequencies are identical at two ears.

Parameters:

• audiogram_left (Audiogram) – the audiogram for the left ear

• audiogram_right (Audiogram) – the audiogram for the right ear

• audf (list) – audiogram frequencies for fitting

• noisegatelevels (ndarray) – compression threshold levels for each frequency band

• noisegateslope (float) – determines slope of gains below compression threshold

• cr_level (int) – overall input level in dB for calculation of compression ratios

• max_output_level (int) – maximum output level in dB

Returns:

dim ndarray of gains

Return type:

dict

clarity.enhancer.gha.gha_utils.multifit_apply_noisegate(gain_table: ndarray, sFit_model_frequencies: ndarray, sFit_model_levels: ndarray, noisegate_level: ndarray, noisegate_slope: ndarray) → ndarray

Apply noisegate to the gain table

Based on OpenMHA subfunction of libmultifit.m.

Parameters:

• gain_table (ndarray) – gain array

• sFit_model_frequencies (list) – FFT filterbank frequencies

• sFit_model_levels (ndarray) – levels at which to calculate gains

• noisegate_level (ndarray) – chosen compression threshold

• noisegate_slope (ndarray) – determines slope below compression threshold

Returns:

gain table with noisegate applied

Return type:

ndarray

Module contents