mel-cepstral-distance


Namemel-cepstral-distance JSON
Version 0.0.3 PyPI version JSON
download
home_page
SummaryCLI and library to compute the Mel-Cepstral Distance of two WAV files based on the paper 'Mel-Cepstral Distance Measure for Objective Speech Quality Assessment' by Robert F. Kubichek.
upload_time2024-01-25 13:54:10
maintainer
docs_urlNone
author
requires_python<3.12,>=3.8
licenseMIT
keywords tts text-to-speech speech synthesis mcd mel dtw dynamic time warping cepstral spectrogram distance divergence distortion language linguistics
VCS
bugtrack_url
requirements No requirements were recorded.
Travis-CI No Travis.
coveralls test coverage No coveralls. 
            # Mel-Cepstral Distance

[![PyPI](https://img.shields.io/pypi/v/mel-cepstral-distance.svg)](https://pypi.python.org/pypi/mel-cepstral-distance)
[![PyPI](https://img.shields.io/pypi/pyversions/mel-cepstral-distance.svg)](https://pypi.python.org/pypi/mel-cepstral-distance)
[![MIT](https://img.shields.io/github/license/jasminsternkopf/mel_cepstral_distance.svg)](https://github.com/jasminsternkopf/mel_cepstral_distance/blob/main/LICENSE)
![PyPI](https://img.shields.io/pypi/implementation/mel-cepstral-distance.svg)
[![PyPI](https://img.shields.io/github/commits-since/jasminsternkopf/mel_cepstral_distance/latest/main.svg)](https://github.com/jasminsternkopf/mel_cepstral_distance/compare/v0.0.3...main)
[![DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.10567255.svg)](https://doi.org/10.5281/zenodo.10567255)

CLI and library to compute the mel-cepstral distance of two WAV files based on the paper ["Mel-Cepstral Distance Measure for Objective Speech Quality Assessment"](https://ieeexplore.ieee.org/document/407206) by Robert F. Kubichek.

## Installation

```sh
pip install mel-cepstral-distance --user
```

## Usage as CLI

```sh
mcd-cli
```

### Example

```sh
# Download two example audio files
wget https://github.com/jasminsternkopf/mel_cepstral_distance/raw/main/examples/similar_audios/original.wav
wget https://github.com/jasminsternkopf/mel_cepstral_distance/raw/main/examples/similar_audios/inferred.wav

# Calculate metrics
mcd-cli from-wav original.wav inferred.wav
```

Output:

```text
Mel-Cepstral Distance: 19.013673608495836
Penalty: 0.11946050096339111
# Frames: 519
```

This will print a message informing you about the mel-cepstral distance and penalty between the audios whose paths were given as arguments and the number of frames that were used in the computation.

## Usage as a library

```py
from mel_cepstral_distance import get_metrics_wavs, get_metrics_mels, get_metrics_mels_pairwise
```

### Main methods

- `get_metrics_wavs`
- `get_metrics_mels`

Both methods return the mel-cepstral distance, the penalty and the final frame number. Examples and information on the parameters can be found in the corresponding documentations.

## Development setup

```sh
# update
sudo apt update
# install Python 3.8-3.11 for ensuring that tests can be run
sudo apt install python3-pip \
  python3.8 python3.8-dev python3.8-distutils python3.8-venv \
  python3.9 python3.9-dev python3.9-distutils python3.9-venv \
  python3.10 python3.10-dev python3.10-distutils python3.10-venv \
  python3.11 python3.11-dev python3.11-distutils python3.11-venv
# install pipenv for creation of virtual environments
python3.8 -m pip install pipenv --user

# check out repo
git clone https://github.com/jasminsternkopf/mel_cepstral_distance.git
cd mel_cepstral_distance
# create virtual environment
python3.8 -m pipenv install --dev
```

## Running the tests

```sh
# first, install the tool (see "Development setup")
# then, navigate into the directory of the repo
cd mel_cepstral_distance
# activate environment
python3.8 -m pipenv shell
# run tests
tox
```

## License

MIT License

## References

- Kubichek, R. “Mel-Cepstral Distance Measure for Objective Speech Quality Assessment.” In Proceedings of IEEE Pacific Rim Conference on Communications Computers and Signal Processing, 1:125–28. Victoria, BC, Canada: IEEE, 1993. https://doi.org/10.1109/PACRIM.1993.407206.
- Muda, Lindasalwa, Mumtaj Begam, and I. Elamvazuthi. “Voice Recognition Algorithms Using Mel Frequency Cepstral Coefficient (MFCC) and Dynamic Time Warping (DTW) Techniques.” Journal of Computing vol. 2, no. 3 (March 2010): 6.

## Acknowledgments

Funded by the Deutsche Forschungsgemeinschaft (DFG, German Research Foundation) – Project-ID 416228727 – CRC 1410

## Citation

If you want to cite this repo, you can use the BibTeX-entry generated by GitHub (see *About => Cite this repository*).

```txt
Sternkopf, J., & Taubert, S. (2024). mel-cepstral-distance (Version 0.0.3) [Computer software]. https://doi.org/10.5281/zenodo.10567255
```

## FAQ

### How were the default parameters set?

We based some of the parameters on the two mentioned references and set the other ones by ourselves depending on the parameter description of the underlying libraries:

- `hop-length` -> 256: Kubichek & Muda et al.
- `window` -> hamming: Muda et al.
- `n-mels` -> 20: Kubichek
  - [Battenberg et al. (2019)](https://arxiv.org/abs/1906.03402) computed the first 13 MFCCs
- `n-mfcc` -> 16: by us
- `n-fft` -> 1024: by us
- `center` -> False: by us
- `htk` -> False: by us
- `norm` -> None: by us
- `dtw` -> True: by us
  - calculate the MCD-DTW, which is used as metric in works like:
    - [Shah et al., 2014](https://ieeexplore.ieee.org/abstract/document/6853600)
    - [VoiceLoop (Taigman et al., 2018)](https://arxiv.org/abs/1707.06588)
    - [Capacitron (Battenberg et al., 2019)](https://arxiv.org/abs/1906.03402)
    - [Attentron (Choi et al., 2020)](https://arxiv.org/abs/2005.08484)

### Why is Python 3.12 not supported?

The dependency `numba` is currently not available for Python 3.12.

Raw data

            {
    "_id": null,
    "home_page": "",
    "name": "mel-cepstral-distance",
    "maintainer": "",
    "docs_url": null,
    "requires_python": "<3.12,>=3.8",
    "maintainer_email": "Stefan Taubert <pypi@stefantaubert.com>",
    "keywords": "TTS,Text-to-speech,Speech synthesis,MCD,Mel,DTW,Dynamic Time Warping,Cepstral,Spectrogram,Distance,Divergence,Distortion,Language,Linguistics",
    "author": "",
    "author_email": "Jasmin Sternkopf <jasmin.sternkopf@mathematik.tu-chemnitz.de>, Stefan Taubert <pypi@stefantaubert.com>",
    "download_url": "https://files.pythonhosted.org/packages/8b/10/d977a96531e3e7384b3d3ae661d410782daf94eb252d076265c90a574d05/mel-cepstral-distance-0.0.3.tar.gz",
    "platform": null,
    "description": "# Mel-Cepstral Distance\n\n[![PyPI](https://img.shields.io/pypi/v/mel-cepstral-distance.svg)](https://pypi.python.org/pypi/mel-cepstral-distance)\n[![PyPI](https://img.shields.io/pypi/pyversions/mel-cepstral-distance.svg)](https://pypi.python.org/pypi/mel-cepstral-distance)\n[![MIT](https://img.shields.io/github/license/jasminsternkopf/mel_cepstral_distance.svg)](https://github.com/jasminsternkopf/mel_cepstral_distance/blob/main/LICENSE)\n![PyPI](https://img.shields.io/pypi/implementation/mel-cepstral-distance.svg)\n[![PyPI](https://img.shields.io/github/commits-since/jasminsternkopf/mel_cepstral_distance/latest/main.svg)](https://github.com/jasminsternkopf/mel_cepstral_distance/compare/v0.0.3...main)\n[![DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.10567255.svg)](https://doi.org/10.5281/zenodo.10567255)\n\nCLI and library to compute the mel-cepstral distance of two WAV files based on the paper [\"Mel-Cepstral Distance Measure for Objective Speech Quality Assessment\"](https://ieeexplore.ieee.org/document/407206) by Robert F. Kubichek.\n\n## Installation\n\n```sh\npip install mel-cepstral-distance --user\n```\n\n## Usage as CLI\n\n```sh\nmcd-cli\n```\n\n### Example\n\n```sh\n# Download two example audio files\nwget https://github.com/jasminsternkopf/mel_cepstral_distance/raw/main/examples/similar_audios/original.wav\nwget https://github.com/jasminsternkopf/mel_cepstral_distance/raw/main/examples/similar_audios/inferred.wav\n\n# Calculate metrics\nmcd-cli from-wav original.wav inferred.wav\n```\n\nOutput:\n\n```text\nMel-Cepstral Distance: 19.013673608495836\nPenalty: 0.11946050096339111\n# Frames: 519\n```\n\nThis will print a message informing you about the mel-cepstral distance and penalty between the audios whose paths were given as arguments and the number of frames that were used in the computation.\n\n## Usage as a library\n\n```py\nfrom mel_cepstral_distance import get_metrics_wavs, get_metrics_mels, get_metrics_mels_pairwise\n```\n\n### Main methods\n\n- `get_metrics_wavs`\n- `get_metrics_mels`\n\nBoth methods return the mel-cepstral distance, the penalty and the final frame number. Examples and information on the parameters can be found in the corresponding documentations.\n\n## Development setup\n\n```sh\n# update\nsudo apt update\n# install Python 3.8-3.11 for ensuring that tests can be run\nsudo apt install python3-pip \\\n  python3.8 python3.8-dev python3.8-distutils python3.8-venv \\\n  python3.9 python3.9-dev python3.9-distutils python3.9-venv \\\n  python3.10 python3.10-dev python3.10-distutils python3.10-venv \\\n  python3.11 python3.11-dev python3.11-distutils python3.11-venv\n# install pipenv for creation of virtual environments\npython3.8 -m pip install pipenv --user\n\n# check out repo\ngit clone https://github.com/jasminsternkopf/mel_cepstral_distance.git\ncd mel_cepstral_distance\n# create virtual environment\npython3.8 -m pipenv install --dev\n```\n\n## Running the tests\n\n```sh\n# first, install the tool (see \"Development setup\")\n# then, navigate into the directory of the repo\ncd mel_cepstral_distance\n# activate environment\npython3.8 -m pipenv shell\n# run tests\ntox\n```\n\n## License\n\nMIT License\n\n## References\n\n- Kubichek, R. \u201cMel-Cepstral Distance Measure for Objective Speech Quality Assessment.\u201d In Proceedings of IEEE Pacific Rim Conference on Communications Computers and Signal Processing, 1:125\u201328. Victoria, BC, Canada: IEEE, 1993. https://doi.org/10.1109/PACRIM.1993.407206.\n- Muda, Lindasalwa, Mumtaj Begam, and I. Elamvazuthi. \u201cVoice Recognition Algorithms Using Mel Frequency Cepstral Coefficient (MFCC) and Dynamic Time Warping (DTW) Techniques.\u201d Journal of Computing vol. 2, no. 3 (March 2010): 6.\n\n## Acknowledgments\n\nFunded by the Deutsche Forschungsgemeinschaft (DFG, German Research Foundation) \u2013 Project-ID 416228727 \u2013 CRC 1410\n\n## Citation\n\nIf you want to cite this repo, you can use the BibTeX-entry generated by GitHub (see *About => Cite this repository*).\n\n```txt\nSternkopf, J., & Taubert, S. (2024). mel-cepstral-distance (Version 0.0.3) [Computer software]. https://doi.org/10.5281/zenodo.10567255\n```\n\n## FAQ\n\n### How were the default parameters set?\n\nWe based some of the parameters on the two mentioned references and set the other ones by ourselves depending on the parameter description of the underlying libraries:\n\n- `hop-length` -> 256: Kubichek & Muda et al.\n- `window` -> hamming: Muda et al.\n- `n-mels` -> 20: Kubichek\n  - [Battenberg et al. (2019)](https://arxiv.org/abs/1906.03402) computed the first 13 MFCCs\n- `n-mfcc` -> 16: by us\n- `n-fft` -> 1024: by us\n- `center` -> False: by us\n- `htk` -> False: by us\n- `norm` -> None: by us\n- `dtw` -> True: by us\n  - calculate the MCD-DTW, which is used as metric in works like:\n    - [Shah et al., 2014](https://ieeexplore.ieee.org/abstract/document/6853600)\n    - [VoiceLoop (Taigman et al., 2018)](https://arxiv.org/abs/1707.06588)\n    - [Capacitron (Battenberg et al., 2019)](https://arxiv.org/abs/1906.03402)\n    - [Attentron (Choi et al., 2020)](https://arxiv.org/abs/2005.08484)\n\n### Why is Python 3.12 not supported?\n\nThe dependency `numba` is currently not available for Python 3.12.\n",
    "bugtrack_url": null,
    "license": "MIT",
    "summary": "CLI and library to compute the Mel-Cepstral Distance of two WAV files based on the paper 'Mel-Cepstral Distance Measure for Objective Speech Quality Assessment' by Robert F. Kubichek.",
    "version": "0.0.3",
    "project_urls": {
        "Homepage": "https://github.com/jasminsternkopf/mel_cepstral_distance",
        "Issues": "https://github.com/jasminsternkopf/mel_cepstral_distance/issues"
    },
    "split_keywords": [
        "tts",
        "text-to-speech",
        "speech synthesis",
        "mcd",
        "mel",
        "dtw",
        "dynamic time warping",
        "cepstral",
        "spectrogram",
        "distance",
        "divergence",
        "distortion",
        "language",
        "linguistics"
    ],
    "urls": [
        {
            "comment_text": "",
            "digests": {
                "blake2b_256": "4709ed5d3917346e3345b76a69ec6ddc699d5e254673f8c2d0701cd9c2915d89",
                "md5": "e7dce15e813dade34c04856379001920",
                "sha256": "ec383a4f713abe96d20a1d5b316b1c04cd92611dcdc7b5b368349cb5dc5f89d9"
            },
            "downloads": -1,
            "filename": "mel_cepstral_distance-0.0.3-py3-none-any.whl",
            "has_sig": false,
            "md5_digest": "e7dce15e813dade34c04856379001920",
            "packagetype": "bdist_wheel",
            "python_version": "py3",
            "requires_python": "<3.12,>=3.8",
            "size": 20158,
            "upload_time": "2024-01-25T13:54:07",
            "upload_time_iso_8601": "2024-01-25T13:54:07.599371Z",
            "url": "https://files.pythonhosted.org/packages/47/09/ed5d3917346e3345b76a69ec6ddc699d5e254673f8c2d0701cd9c2915d89/mel_cepstral_distance-0.0.3-py3-none-any.whl",
            "yanked": false,
            "yanked_reason": null
        },
        {
            "comment_text": "",
            "digests": {
                "blake2b_256": "8b10d977a96531e3e7384b3d3ae661d410782daf94eb252d076265c90a574d05",
                "md5": "57c0f8950466f2711ad998027d28e312",
                "sha256": "eae9b24fa24f13558d51f3eea1865b8ccfd47e3e8894c702464515de1405e72f"
            },
            "downloads": -1,
            "filename": "mel-cepstral-distance-0.0.3.tar.gz",
            "has_sig": false,
            "md5_digest": "57c0f8950466f2711ad998027d28e312",
            "packagetype": "sdist",
            "python_version": "source",
            "requires_python": "<3.12,>=3.8",
            "size": 1939296,
            "upload_time": "2024-01-25T13:54:10",
            "upload_time_iso_8601": "2024-01-25T13:54:10.299624Z",
            "url": "https://files.pythonhosted.org/packages/8b/10/d977a96531e3e7384b3d3ae661d410782daf94eb252d076265c90a574d05/mel-cepstral-distance-0.0.3.tar.gz",
            "yanked": false,
            "yanked_reason": null
        }
    ],
    "upload_time": "2024-01-25 13:54:10",
    "github": true,
    "gitlab": false,
    "bitbucket": false,
    "codeberg": false,
    "github_user": "jasminsternkopf",
    "github_project": "mel_cepstral_distance",
    "travis_ci": false,
    "coveralls": false,
    "github_actions": false,
    "lcname": "mel-cepstral-distance"
}
Elapsed time: 0.30583s