<!-- markdownlint-disable MD041 -->
<div align="center">
<h1>Machine learning challenges for hearing aid processing</h1>
<p align="center">
<img src="docs/images/earfinal_clarity_customColour.png" alt="drawing" width="200" hspace="40"/>
<img src="docs/images/cadenza_logo.png" alt="Cadenza Challenge" width="250" hspace="40"/>
<p>
[](https://badge.fury.io/py/pyclarity)
[](https://pypi.org/project/pyclarity/)
[](https://app.codecov.io/gh/claritychallenge/clarity)
[](https://github.com/psf/black)
[](https://github.com/PyCQA/pylint)
[](https://results.pre-commit.ci/latest/github/claritychallenge/clarity/main)
[](https://pepy.tech/project/pyclarity)
[](https://pypi.org/project/pyclarity/0.5.0/)
[](https://pypi.org/project/pyclarity/0.4.1/)
[](https://pypi.org/project/pyclarity/0.3.4/)
[](https://pypi.org/project/pyclarity/0.2.1/)
[](https://pypi.org/project/pyclarity/0.1.1/)
[](https://figshare.shef.ac.uk/articles/software/clarity/23230694/1)
</p>
</div>
---
We are organising a series of machine learning challenges to enhance hearing-aid signal processing and to better predict how people perceive speech-in-noise (Clarity) and speech-in-music (Cadenza). For further details of the Clarity Project visit [the Clarity project website](http://claritychallenge.org/), and for details of our latest Clarity challenges visit our [challenge documentation site](https://claritychallenge.github.io/clarity_CC_doc/). You can contact the Clarity Team by email at [claritychallengecontact@gmail.com](claritychallengecontact@gmail.com). For further details of the Cadenza Project visit [the Cadenza project website](http://cadenzachallenge.org/), and to find out about the latest Cadenza challenges join the [Cadenza Challenge Group](https://groups.google.com/g/cadenza-challenge).
In this repository, you will find code to support all Clarity and Cadenza Challenges, including baselines, toolkits, and systems from participants. **We encourage you to make your system/model open source and contribute to this repository.**
## Current Events
- The 3rd Clarity Enhancement Challenge is now open. :fire::fire:
- Visit the [challenge website](https://claritychallenge.org/docs/cec3/cec3_intro) for more details.
- Join the [Clarity Challenge Group](https://groups.google.com/g/clarity-challenge) to keep up-to-date on developments.
- The ICASSP 2024 Cadenza Challenge (CAD_ICASSP_2024) will be presented at ICASSP 2024.
- Join the [Cadenza Challenge Group](https://groups.google.com/g/cadenza-challenge) to keep up-to-date on developments.
- Visit the Cadenenza Challenge [website](https://cadenzachallenge.org/) for more details.
- The first Cadenza Challenge (CAD1) is closed.
- Subjective Evaluation is underway. :new:
- The 2nd Clarity Prediction Challenge (CPC2) is now closed.
- The 4th Clarity Workshop will be held as a satellite event of Interspeech 2023. For details visit the [workshop website](https://claritychallenge.org/clarity2023-workshop/).
## Installation
### PyPI
Clarity is available on the [Python Package Index (PyPI)](https://pypi.org/project/pyclarity) to install create and/or
activate a virtual environment and then use `pip` to install.
```bash
conda create --name clarity python=3.8
conda activate clarity
pip install pyclarity
```
### GitHub Cloning
```bash
# First clone the repo
git clone https://github.com/claritychallenge/clarity.git
cd clarity
# Second create & activate environment with conda, see https://docs.conda.io/projects/conda/en/latest/user-guide/install/index.html
conda create --name clarity python=3.8
conda activate clarity
# Last install with pip
pip install -e .
```
### GitHub pip install
Alternatively `pip` allows you to install packages from GitHub sources directly. The following will install the current
`main` branch.
```bash
pip install -e git+https://github.com/claritychallenge/clarity.git@main
```
## Challenges
Current challenge
- [The 3rd Clarity Enhancement Challenge](./recipes/cec3)
Previous challenges
- [The ICASSP 2024 Cadenza Challenge](./recipes/cad_icassp_2024)
- [The 1st Cadenza Challenge (CAD1)](./recipes/cad1)
- [The 2nd Clarity Prediction Challenge (CPC2)](./recipes/cpc2)
- [The ICASSP 2023 Clarity Enhancement Challenge](./recipes/icassp_2023)
- [The 2nd Clarity Enhancement Challenge (CEC2)](./recipes/cec2)
- [The 1st Clarity Prediction Challenge (CPC1)](./recipes/cpc1)
- [The 1st Clarity Enhancement Challenge (CEC1)](./recipes/cec1)
## Available tools
We provide also a number of tools in this repository:
- **Hearing loss simulation**
- [Cambridge MSBG hearing loss simulator](./clarity/evaluator/msbg): descriptions can be found in the [CEC1
description](./recipes/cec1); an usage example can be found in the [CEC1 baseline](./recipes/cec1/baseline)
evaluation script `evaluate.py`.
- **Objective intelligibility measurement**
- [Modified binaural STOI (MBSTOI)](./clarity/evaluator/mbstoi/mbstoi.py): a Python implementation of MBSTOI. It is
jointly used with the MSBG hearing loss model in the [CEC1 baseline](./recipes/cec1/baseline). The official matlab
implementation can be found here: <http://ah-andersen.net/code/>
- [Hearing-aid speech perception index (HASPI)](./clarity/evaluator/haspi/haspi.py): a Python implementation of
HASPI Version 2, and the better-ear HASPI for binaural speech signals. For official matlab implementation, request here: <https://www.colorado.edu/lab/hearlab/resources>
- [Hearing-aid speech quality index (HASQI)](./clarity/evaluator/hasqi/hasqi.py): a Python implementation of
HASQI Version 2, and the better-ear HASQI for binaural speech signals.
- [Hearing-aid audio quality index (HAAQI)](./clarity/evaluator/haaqi/haaqi.py): a Python implementation of
HAAQI.
- **Hearing aid enhancement**
- [Cambridge hearing aid fitting (CAMFIT)](./clarity/enhancer/gha/gainrule_camfit.py): a Python implementation of CAMFIT, translated from the [HörTech Open Master Hearing Aid (OpenMHA)](http://www.openmha.org/about/); the CAMFIT is used together with OpenMHA enhancement as the [CEC1 baseline](./recipes/cec1/baseline), see `enhance.py`.
- [NAL-R hearing aid fitting](./clarity/enhancer/nalr.py): a Python implementation of NAL-R prescription fitting. It is used as the [CEC2 baseline](./recipes/cec2/baseline), see `enhance.py`.
In addition, differentiable approximation to some tools are provided:
- [x] [Differentiable MSBG hearing loss model](./clarity/predictor/torch_msbg.py). See also the BUT implementation:
<https://github.com/BUTSpeechFIT/torch_msbg_mbstoi>
- [ ] Differentiable HASPI (coming)
## Open-source systems
- CPC1:
- [Exploiting Hidden Representations from a DNN-based Speech Recogniser for Speech Intelligibility Prediction in
Hearing-impaired Listeners](./recipes/cpc1/e032_sheffield)
- [Unsupervised Uncertainty Measures of Automatic Speech Recognition for Non-intrusive Speech Intelligibility
Prediction](./recipes/cpc1/e029_sheffield)
- CEC1:
- [A Two-Stage End-to-End System for Speech-in-Noise Hearing Aid Processing](./recipes/cec1/e009_sheffield)
Raw data
{
"_id": null,
"home_page": null,
"name": "pyclarity",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": null,
"keywords": "hearing, signal processing, clarity challenge",
"author": null,
"author_email": "The PyClarity Team <claritychallengecontact@gmail.com>",
"download_url": "https://files.pythonhosted.org/packages/c0/71/1790a1c97044eb09fb55983d10272c64ea78dd18d03880ab3755b83183c8/pyclarity-0.5.1.tar.gz",
"platform": null,
"description": "\n<!-- markdownlint-disable MD041 -->\n<div align=\"center\">\n\n<h1>Machine learning challenges for hearing aid processing</h1>\n\n<p align=\"center\">\n <img src=\"docs/images/earfinal_clarity_customColour.png\" alt=\"drawing\" width=\"200\" hspace=\"40\"/>\n\n <img src=\"docs/images/cadenza_logo.png\" alt=\"Cadenza Challenge\" width=\"250\" hspace=\"40\"/>\n<p>\n\n[](https://badge.fury.io/py/pyclarity)\n[](https://pypi.org/project/pyclarity/)\n[](https://app.codecov.io/gh/claritychallenge/clarity)\n[](https://github.com/psf/black)\n[](https://github.com/PyCQA/pylint)\n[](https://results.pre-commit.ci/latest/github/claritychallenge/clarity/main)\n[](https://pepy.tech/project/pyclarity)\n\n[](https://pypi.org/project/pyclarity/0.5.0/)\n[](https://pypi.org/project/pyclarity/0.4.1/)\n[](https://pypi.org/project/pyclarity/0.3.4/)\n[](https://pypi.org/project/pyclarity/0.2.1/)\n[](https://pypi.org/project/pyclarity/0.1.1/)\n\n[](https://figshare.shef.ac.uk/articles/software/clarity/23230694/1)\n</p>\n\n</div>\n\n---\n\nWe are organising a series of machine learning challenges to enhance hearing-aid signal processing and to better predict how people perceive speech-in-noise (Clarity) and speech-in-music (Cadenza). For further details of the Clarity Project visit [the Clarity project website](http://claritychallenge.org/), and for details of our latest Clarity challenges visit our [challenge documentation site](https://claritychallenge.github.io/clarity_CC_doc/). You can contact the Clarity Team by email at [claritychallengecontact@gmail.com](claritychallengecontact@gmail.com). For further details of the Cadenza Project visit [the Cadenza project website](http://cadenzachallenge.org/), and to find out about the latest Cadenza challenges join the [Cadenza Challenge Group](https://groups.google.com/g/cadenza-challenge).\n\nIn this repository, you will find code to support all Clarity and Cadenza Challenges, including baselines, toolkits, and systems from participants. **We encourage you to make your system/model open source and contribute to this repository.**\n\n## Current Events\n\n- The 3rd Clarity Enhancement Challenge is now open. :fire::fire:\n - Visit the [challenge website](https://claritychallenge.org/docs/cec3/cec3_intro) for more details.\n - Join the [Clarity Challenge Group](https://groups.google.com/g/clarity-challenge) to keep up-to-date on developments.\n- The ICASSP 2024 Cadenza Challenge (CAD_ICASSP_2024) will be presented at ICASSP 2024.\n - Join the [Cadenza Challenge Group](https://groups.google.com/g/cadenza-challenge) to keep up-to-date on developments.\n - Visit the Cadenenza Challenge [website](https://cadenzachallenge.org/) for more details.\n- The first Cadenza Challenge (CAD1) is closed.\n - Subjective Evaluation is underway. :new:\n- The 2nd Clarity Prediction Challenge (CPC2) is now closed.\n- The 4th Clarity Workshop will be held as a satellite event of Interspeech 2023. For details visit the [workshop website](https://claritychallenge.org/clarity2023-workshop/).\n\n## Installation\n\n### PyPI\n\nClarity is available on the [Python Package Index (PyPI)](https://pypi.org/project/pyclarity) to install create and/or\nactivate a virtual environment and then use `pip` to install.\n\n```bash\nconda create --name clarity python=3.8\nconda activate clarity\n\npip install pyclarity\n```\n\n### GitHub Cloning\n\n```bash\n# First clone the repo\ngit clone https://github.com/claritychallenge/clarity.git\ncd clarity\n\n# Second create & activate environment with conda, see https://docs.conda.io/projects/conda/en/latest/user-guide/install/index.html\nconda create --name clarity python=3.8\nconda activate clarity\n\n# Last install with pip\npip install -e .\n```\n\n### GitHub pip install\n\nAlternatively `pip` allows you to install packages from GitHub sources directly. The following will install the current\n`main` branch.\n\n```bash\npip install -e git+https://github.com/claritychallenge/clarity.git@main\n```\n\n## Challenges\n\nCurrent challenge\n\n- [The 3rd Clarity Enhancement Challenge](./recipes/cec3)\n\nPrevious challenges\n\n- [The ICASSP 2024 Cadenza Challenge](./recipes/cad_icassp_2024)\n- [The 1st Cadenza Challenge (CAD1)](./recipes/cad1)\n- [The 2nd Clarity Prediction Challenge (CPC2)](./recipes/cpc2)\n- [The ICASSP 2023 Clarity Enhancement Challenge](./recipes/icassp_2023)\n- [The 2nd Clarity Enhancement Challenge (CEC2)](./recipes/cec2)\n- [The 1st Clarity Prediction Challenge (CPC1)](./recipes/cpc1)\n- [The 1st Clarity Enhancement Challenge (CEC1)](./recipes/cec1)\n\n## Available tools\n\nWe provide also a number of tools in this repository:\n\n- **Hearing loss simulation**\n - [Cambridge MSBG hearing loss simulator](./clarity/evaluator/msbg): descriptions can be found in the [CEC1\n description](./recipes/cec1); an usage example can be found in the [CEC1 baseline](./recipes/cec1/baseline)\n evaluation script `evaluate.py`.\n- **Objective intelligibility measurement**\n - [Modified binaural STOI (MBSTOI)](./clarity/evaluator/mbstoi/mbstoi.py): a Python implementation of MBSTOI. It is\n jointly used with the MSBG hearing loss model in the [CEC1 baseline](./recipes/cec1/baseline). The official matlab\n implementation can be found here: <http://ah-andersen.net/code/>\n - [Hearing-aid speech perception index (HASPI)](./clarity/evaluator/haspi/haspi.py): a Python implementation of\n HASPI Version 2, and the better-ear HASPI for binaural speech signals. For official matlab implementation, request here: <https://www.colorado.edu/lab/hearlab/resources>\n - [Hearing-aid speech quality index (HASQI)](./clarity/evaluator/hasqi/hasqi.py): a Python implementation of\n HASQI Version 2, and the better-ear HASQI for binaural speech signals.\n - [Hearing-aid audio quality index (HAAQI)](./clarity/evaluator/haaqi/haaqi.py): a Python implementation of\n HAAQI.\n- **Hearing aid enhancement**\n - [Cambridge hearing aid fitting (CAMFIT)](./clarity/enhancer/gha/gainrule_camfit.py): a Python implementation of CAMFIT, translated from the [H\u00f6rTech Open Master Hearing Aid (OpenMHA)](http://www.openmha.org/about/); the CAMFIT is used together with OpenMHA enhancement as the [CEC1 baseline](./recipes/cec1/baseline), see `enhance.py`.\n - [NAL-R hearing aid fitting](./clarity/enhancer/nalr.py): a Python implementation of NAL-R prescription fitting. It is used as the [CEC2 baseline](./recipes/cec2/baseline), see `enhance.py`.\n\nIn addition, differentiable approximation to some tools are provided:\n\n- [x] [Differentiable MSBG hearing loss model](./clarity/predictor/torch_msbg.py). See also the BUT implementation:\n <https://github.com/BUTSpeechFIT/torch_msbg_mbstoi>\n- [ ] Differentiable HASPI (coming)\n\n## Open-source systems\n\n- CPC1:\n - [Exploiting Hidden Representations from a DNN-based Speech Recogniser for Speech Intelligibility Prediction in\n Hearing-impaired Listeners](./recipes/cpc1/e032_sheffield)\n - [Unsupervised Uncertainty Measures of Automatic Speech Recognition for Non-intrusive Speech Intelligibility\n Prediction](./recipes/cpc1/e029_sheffield)\n- CEC1:\n - [A Two-Stage End-to-End System for Speech-in-Noise Hearing Aid Processing](./recipes/cec1/e009_sheffield)\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Tools for the Clarity Challenge",
"version": "0.5.1",
"project_urls": {
"Bug_Tracker": "https://github.com/claritychallenge/clarity/issues",
"Documentation": "https://claritychallenge.github.io/clarity_CC_doc",
"Source": "https://github.com/claritychallenge/clarity"
},
"split_keywords": [
"hearing",
" signal processing",
" clarity challenge"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "f08f257bf9671ea6eb5256dd3fbac218830522af18d7d32659c775602441c88e",
"md5": "4ed247fc49a7952cab818b78fd3236da",
"sha256": "6bf2b71e49589c83d140fd249740ec930c6b4b95125562b0e17ca0b19c4e6a16"
},
"downloads": -1,
"filename": "pyclarity-0.5.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "4ed247fc49a7952cab818b78fd3236da",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 764318,
"upload_time": "2024-04-04T20:42:25",
"upload_time_iso_8601": "2024-04-04T20:42:25.215764Z",
"url": "https://files.pythonhosted.org/packages/f0/8f/257bf9671ea6eb5256dd3fbac218830522af18d7d32659c775602441c88e/pyclarity-0.5.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "c0711790a1c97044eb09fb55983d10272c64ea78dd18d03880ab3755b83183c8",
"md5": "03d244d367b13cd52bc640b5c1ab0859",
"sha256": "9a6bb7076718a0e0598b383b4f98269e57fae15ff4d57900f506238ce0ac29e0"
},
"downloads": -1,
"filename": "pyclarity-0.5.1.tar.gz",
"has_sig": false,
"md5_digest": "03d244d367b13cd52bc640b5c1ab0859",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 68682296,
"upload_time": "2024-04-04T20:42:28",
"upload_time_iso_8601": "2024-04-04T20:42:28.204646Z",
"url": "https://files.pythonhosted.org/packages/c0/71/1790a1c97044eb09fb55983d10272c64ea78dd18d03880ab3755b83183c8/pyclarity-0.5.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-04-04 20:42:28",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "claritychallenge",
"github_project": "clarity",
"travis_ci": false,
"coveralls": true,
"github_actions": true,
"lcname": "pyclarity"
}
JSON
