Metadata-Version: 2.4
Name: hyperion-utmosv2
Version: 1.3.1
Summary: Hyperion-maintained UTMOS v2 fork for MOS prediction
Author: Kaito Baba
Maintainer: Hyperion
License-Expression: MIT
Project-URL: Homepage, https://github.com/hyperion-ml/UTMOSv2
Project-URL: Repository, https://github.com/hyperion-ml/UTMOSv2
Project-URL: Upstream, https://github.com/sarulab-speech/UTMOSv2
Project-URL: Issues, https://github.com/hyperion-ml/UTMOSv2/issues
Keywords: speech,audio,mos,quality,utmos
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Science/Research
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Topic :: Multimedia :: Sound/Audio
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy<2.0,>=1.26
Requires-Dist: torch<=2.9.1,>=2.4.1
Requires-Dist: timm>=1.0.7
Requires-Dist: torchvision<=0.24.1,>=0.19.1
Requires-Dist: librosa<0.11,>=0.10.2
Requires-Dist: tqdm>=4.66.4
Requires-Dist: transformers<5,>=4.42.4
Requires-Dist: typing-extensions
Requires-Dist: torchaudio<=2.9.1,>=2.4.1
Provides-Extra: check
Requires-Dist: ruff; extra == "check"
Requires-Dist: mypy; extra == "check"
Requires-Dist: types-setuptools; extra == "check"
Requires-Dist: types-tqdm; extra == "check"
Provides-Extra: train
Requires-Dist: scikit-learn>=1.3.2; extra == "train"
Requires-Dist: wandb>=0.17.0; extra == "train"
Requires-Dist: python-dotenv>=1.0.1; extra == "train"
Provides-Extra: optional
Requires-Dist: pandas>=2.2.2; extra == "optional"
Provides-Extra: test
Requires-Dist: pytest; extra == "test"
Dynamic: license-file

<p align="center">
  <img src="docs/image/utmosv2.PNG" alt="utmosv2" width=500>
</p>

> This repository is a fork of the original [UTMOS v2 project](https://github.com/sarulab-speech/UTMOSv2), maintained by the [Hyperion organization](https://github.com/hyperion-ml). It packages the original implementation under the distribution name `hyperion-utmosv2` and adjusts dependency constraints so it can coexist with Hyperion. It is not an official UTMOS release and is not necessarily endorsed by the original authors.

The original `utmosv2` Python import name is intentionally preserved:

```python
import utmosv2
```

The original MIT license, copyright notice, paper citation, and attribution are preserved in this fork.

<h1 align="center">
  UTMOSv2: UTokyo-SaruLab MOS Prediction System
  <a href="https://github.com/sarulab-speech/UTMOSv2">
    <img width="94%" height="5px" src="docs/image/titleLine.svg">
  </a>
</h1>

<p align="center">
  🎤✨ Original project's official implementation ✨🎤<br>
  “<a href="http://arxiv.org/abs/2409.09305">The T05 System for The VoiceMOS Challenge 2024:</a><br>
  <a href="http://arxiv.org/abs/2409.09305">Transfer Learning from Deep Image Classifier to Naturalness MOS Prediction of High-Quality Synthetic Speech</a>”<br>
  🏅🎉&ensp;accepted by IEEE Spoken Language Technology Workshop (SLT) 2024.&ensp;🎉🏅
</p>

<p align="center">
  ꔫ･-･ꔫ･-･ꔫ･-･ꔫ･-･ꔫ･-･ꔫ･-･ꔫ･-･ꔫ
</p>

<p align="center">
  ✨&emsp;&emsp;UTMOSv2 achieved 1st place in 7 out of 16 metrics&emsp;&emsp;✨<br>
  ✨🏆&emsp;&emsp;&emsp;&emsp;and 2nd place in the remaining 9 metrics&emsp;&emsp;&emsp;&emsp;🏆✨<br>
  ✨&emsp;&emsp;&emsp;&emsp;in the <a href="https://sites.google.com/view/voicemos-challenge/past-challenges/voicemos-challenge-2024">VoiceMOS Challenge 2024</a> Track1!&emsp;&emsp;&emsp;&emsp;✨
</p>

<div align="center">
  <a target="_blank" href="https://www.python.org">
    <img src="https://img.shields.io/badge/python-3.10%20%7C%203.11%20%7C%203.12%20%7C%203.13-blue" alt="Python"/>
  </a>
</div>

<div  align="center">
  <a target="_blank" href="https://huggingface.co/spaces/sarulab-speech/UTMOSv2">
    <img src="https://img.shields.io/badge/%F0%9F%A4%97%20Hugging%20Face-Spaces-blue" alt="Hugging Face Spaces"/>
  </a>
  <a target="_blank" href="https://colab.research.google.com/github/sarulab-speech/UTMOSv2/blob/main/quickstart.ipynb">
    <img src="https://colab.research.google.com/assets/colab-badge.svg" alt="Open In Colab"/>
  </a>
</div>

<div  align="center">
  <a target="_blank" href="http://arxiv.org/abs/2409.09305">
    <img src="https://img.shields.io/badge/arXiv-2409.09305-b31b1b.svg" alt="arXiv"/>
  </a>
  <a target="_blank" href="https://ieeexplore.ieee.org/document/10832315">
    <img src="https://img.shields.io/badge/IEEE%20Xplore-10832315-blue.svg" alt="poster"/>
  </a>
  <a target="_blank" href="https://github.com/sarulab-speech/UTMOSv2/blob/main/poster.pdf">
    <img src="https://img.shields.io/badge/IEEE%20SLT%202024-Poster-blue.svg" alt="poster"/>
  </a>
</div>

<br>

<h2 align="left">
  <div>🚀 Quick Prediction</div>
  <a href="https://github.com/sarulab-speech/UTMOSv2/tree/main?tab=readme-ov-file#---quick-prediction--------">
    <img width="85%" height="6px" src="docs/image/line2.svg">
  </a>
</h2>

✨ You can easily use the pretrained UTMOSv2 model!

<h3 align="center">
  <div>🛠️ Using in your Python code 🛠️</div>
  <a href="https://github.com/sarulab-speech/UTMOSv2/tree/doc-user-friendly-api?tab=readme-ov-file#--%EF%B8%8F-using-in-your-python-code-%EF%B8%8F--------">
    <img width="70%" height="6px" src="docs/image/line3.svg">
  </a>
</h3>

<div align="center">
✨⚡️&emsp;With the UTMOSv2 library, you can easily integrate it into your Python code,&emsp;⚡️✨<br>
✨&ensp;allowing you to quickly create models and make predictions with minimal effort!!&ensp;✨
</div>

<br>

If you want to make predictions using the UTMOSv2 library, follow these steps:

1. Install the Hyperion-maintained package from PyPI

   ```bash
   pip install hyperion-utmosv2
   ```

   This package can be installed in the same environment as Hyperion. Install Hyperion according to its own documentation, then install `hyperion-utmosv2` in that environment.

2. Make predictions
   - To predict the MOS of a tensor or array already loaded in memory:

      ```python
      import utmosv2

      model = utmosv2.create_model(pretrained=True)
      # data: torch.Tensor or np.ndarray with shape (batch_size, sequence_length) or (sequence_length,)
      # sr: Sampling rate of the input audio data. If not provided, it defaults to 16000 Hz.
      mos = model.predict(
          data=data, sr=16000
      )  # Returns a torch.Tensor or np.ndarray with shape (batch_size,) or (1,)
      ```

   - To predict the MOS of a single `.wav` file:

      ```python
      import utmosv2

      model = utmosv2.create_model(pretrained=True)
      mos = model.predict(input_path="/path/to/wav/file.wav")  # Returns a float value
      ```

   - To predict the MOS of all `.wav` files in a folder:

      ```python
      import utmosv2

      model = utmosv2.create_model(pretrained=True)
      mos = model.predict(
          input_dir="/path/to/wav/dir/"
      )  # Returns a list of dicts with 'file_path' and 'predicted_mos' keys
      ```

> [!NOTE]
> When `data` is provided, `input_path` and `input_dir` are ignored.

> [!NOTE]
> Either `input_path` or `input_dir` must be specified when `data` is `None`, but not both.

<h3 align="center">
  <div>📜 Using the inference script 📜</div>
  <a href="https://github.com/sarulab-speech/UTMOSv2/tree/doc-user-friendly-api?tab=readme-ov-file#---using-the-inference-script---------">
    <img width="70%" height="6px" src="docs/image/line3.svg">
  </a>
</h3>

If you want to make predictions using the inference script, follow these steps:

1. Clone this repository and navigate to UTMOSv2 folder

   ```bash
   git clone https://github.com/sarulab-speech/UTMOSv2.git
   cd UTMOSv2
   ```

2. Install Package

   ```bash
   pip install -e '.[optional]'
   ```

3. Make predictions
   - To predict the MOS of a single `.wav` file:

      ```bash
      python inference.py --input_path /path/to/wav/file.wav --out_path /path/to/output/file.csv
      ```

   - To predict the MOS of all `.wav` files in a folder:

      ```bash
      python inference.py --input_dir /path/to/wav/dir/ --out_path /path/to/output/file.csv
      ```

> [!NOTE]
> If you are using zsh, quote the extras specifier like this:
>
> ```zsh
> pip install -e '.[optional]'
> ```

> [!TIP]
> If `--out_path` is not specified, the prediction results will be output to the standard output. This is particularly useful when the number of files to be predicted is small.

> [!NOTE]
> Either `--input_path` or `--input_dir` must be specified, but not both.

<br>

> [!NOTE]
> These methods provide quick and simple predictions. For more accurate predictions and detailed usage of the inference script, please refer to the [inference guide](docs/inference.md).

🤗 You can try a simple demonstration on Hugging Face Space:
<a href="https://huggingface.co/spaces/sarulab-speech/UTMOSv2">
  <img src="https://img.shields.io/badge/%F0%9F%A4%97%20Hugging%20Face-Spaces-blue" alt="Hugging Face Spaces" align="top">
</a>

## Model files, external assets, and limitations

The Python package does not bundle model checkpoints, datasets, caches, or audio files. `create_model(pretrained=True)` downloads the pretrained checkpoint at runtime from the upstream UTMOSv2 Hugging Face repository and stores it in the local UTMOSv2 cache; network access is therefore required for the first pretrained-model use. A custom checkpoint can be supplied with `checkpoint_path`. The package also relies on external pretrained transformer assets when the selected configuration uses them.

Dataset licenses and usage terms vary by dataset; see [docs/datasets.md](docs/datasets.md) and comply with each dataset's terms. The code is distributed under the MIT license in [LICENSE](LICENSE), while pretrained weights, model cards, datasets, and third-party assets may have separate terms. Review those terms before redistribution or commercial use. Predictions are model estimates and may not be suitable as the sole basis for safety-critical, compliance, or other high-stakes decisions.

## Publishing and release setup

The distribution name is `hyperion-utmosv2`; the import name remains `utmosv2`. The repository's release workflow builds and validates source and wheel distributions, then publishes only when a GitHub Release is published using PyPI Trusted Publishing/OIDC.

Before the first release:

1. Verify [the PyPI project page](https://pypi.org/project/hyperion-utmosv2/) is unavailable or belongs to this organization. If the name is taken, choose a different distribution name and update `pyproject.toml`, this README, and the Trusted Publisher configuration.
2. On PyPI, add a Trusted Publisher for owner `hyperion-ml`, repository `UTMOSv2`, workflow `.github/workflows/python-publish.yml`, and environment `pypi`.
3. In GitHub, create the `pypi` environment. Require approval from an appropriate maintainer and restrict deployments to the release workflow or protected release rules as appropriate for the organization. Do not add a PyPI API token; the workflow uses OIDC.
4. Merge the workflow to the repository's default `main` branch. Create a GitHub Release with a new tag (for example `v1.3.1`) and publish the release. A draft or prerelease does not trigger this workflow.
5. Verify the files, metadata, and installation from PyPI:

   ```bash
   python -m pip install --upgrade hyperion-utmosv2
   python -c "import utmosv2; print(utmosv2.__version__)"
   ```

   Also inspect the PyPI project page and `python -m pip show hyperion-utmosv2`. Use `python -m build` and `twine check dist/*` before release.

If `hyperion-utmosv2` is already registered, do not attempt to claim or overwrite it. Confirm ownership and contact the current owner if appropriate, or select an available name and update all package and publishing references consistently.

<h2 align="left">
  <div>⚒️ Train UTMOSv2 Yourself</div>
  <a href="https://github.com/sarulab-speech/UTMOSv2/tree/main?tab=readme-ov-file#--%EF%B8%8F-train-utmosv2-yourself--------">
    <img width="85%" height="6px" src="docs/image/line2.svg">
  </a>
</h2>

If you want to train UTMOSv2 yourself, please refer to the [training guide](docs/training.md). To reproduce the training as described in the paper or used in the competition, please refer to [this document](docs/reproduction.md).

<h2 align="left">
  <div>📂 Used Datasets</div>
  <a href="https://github.com/sarulab-speech/UTMOSv2/tree/main?tab=readme-ov-file#---used-datasets--------">
    <img width="85%" height="6px" src="docs/image/line2.svg">
  </a>
</h2>

Details of the datasets used in this project can be found in the [datasets documentation](docs/datasets.md).

<h2 align="left">
  <div>🔖 Citation</div>
  <a href="https://github.com/sarulab-speech/UTMOSv2/tree/main?tab=readme-ov-file#---citation--------">
    <img width="85%" height="6px" src="docs/image/line2.svg">
  </a>
</h2>

If you find UTMOSv2 useful in your research, please cite the following paper:

```bibtex
@inproceedings{baba2024utmosv2,
  title     = {The T05 System for The {V}oice{MOS} {C}hallenge 2024: Transfer Learning from Deep Image Classifier to Naturalness {MOS} Prediction of High-Quality Synthetic Speech},
  author    = {Baba, Kaito and Nakata, Wataru and Saito, Yuki and Saruwatari, Hiroshi},
  booktitle = {IEEE Spoken Language Technology Workshop (SLT)},
  year      = {2024},
  pages     = {818--824},
  doi       = {10.1109/SLT61566.2024.10832315},
}
```

<h2 align="left">
  <div>:octocat: GitHub Star History</div>
  <a href="https://github.com/sarulab-speech/UTMOSv2/tree/main?tab=readme-ov-file#--octocat-github-star-history--------">
    <img width="85%" height="6px" src="docs/image/line2.svg">
  </a>
</h2>


<div align="center">
  <img width="90%" src="https://starchart.cc/sarulab-speech/UTMOSv2.svg?variant=adaptive" alt="GitHub Star History"/>
</div>
