Metadata-Version: 2.4
Name: hyperion-voxprofile
Version: 0.1.0
Summary: Hyperion-maintained packaging of Vox-Profile speech and speaker trait models.
Author-email: Tiantian Feng <tiantiaf@usc.edu>
Maintainer: Hyperion ML
License-Expression: LicenseRef-RAIL-1.1
Project-URL: Homepage, https://github.com/hyperion-ml/vox-profile-release
Project-URL: Repository, https://github.com/hyperion-ml/vox-profile-release
Project-URL: Original, https://github.com/tiantiaf0627/vox-profile-release
Project-URL: Paper, https://arxiv.org/abs/2505.14648
Project-URL: Models, https://huggingface.co/collections/tiantiaf/vox-profile-6849966a82005eea95dc6274
Project-URL: Issues, https://github.com/hyperion-ml/vox-profile-release/issues
Keywords: speech,speaker traits,Vox-Profile,Hyperion
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
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: Operating System :: OS Independent
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: torch>=2.4.1
Requires-Dist: torchaudio>=2.4.1
Requires-Dist: torchvision>=0.19.0
Requires-Dist: huggingface-hub<1.0,>=0.31.4
Requires-Dist: loralib>=0.1.2
Requires-Dist: numpy<2.0,>=1.24.4
Requires-Dist: sentencepiece<0.3,>=0.2.0
Requires-Dist: transformers<5,>=4.46.3
Dynamic: license-file

# Hyperion VoxProfile

This repository is a Hyperion-maintained fork and Python packaging of
[Vox-Profile](https://github.com/tiantiaf0627/vox-profile-release), a speech
foundation-model benchmark for characterizing diverse speaker and speech
traits. It keeps the original Python import name, `vox_profile`, while the
published distribution is named `hyperion-voxprofile`.

Hyperion's changes are focused on dependency constraints and packaging
compatibility with the Hyperion toolkit. This fork is not an official release,
endorsement, or representation of the original authors.

## Installation

Python 3.10 or newer is required:

```bash
python -m pip install hyperion-voxprofile
```

The installable distribution name and import name intentionally differ:

```python
from vox_profile.model.accent.whisper_accent import WhisperWrapper
```

The package contains model architecture and adapter code only. It does not
include model weights, datasets, audio, caches, or other large artifacts.

## Basic use

Models are downloaded separately from Hugging Face when
`from_pretrained(...)` is called. For example, with an appropriate model
checkpoint and its dependencies:

```python
import torch
from vox_profile.model.accent.whisper_accent import WhisperWrapper

device = "cuda" if torch.cuda.is_available() else "cpu"
model = WhisperWrapper.from_pretrained(
    "tiantiaf/whisper-large-v3-narrow-accent"
).to(device)
model.eval()
```

Prepare input audio as mono, 16 kHz audio no longer than 15 seconds. Inputs
shorter than 3 seconds may produce unreliable predictions according to the
original project. See the [examples](https://github.com/hyperion-ml/vox-profile-release/tree/main/vox_profile/example)
and the [available model collection](https://huggingface.co/collections/tiantiaf/vox-profile-6849966a82005eea95dc6274).

## Dependencies and compatibility

The fork retains the upstream runtime dependencies while constraining their
versions so it can coexist with Hyperion. PyTorch and TorchAudio installation
may need to follow the official command for the target CPU/CUDA/ROCm platform;
the package metadata provides the general PyPI requirements. No Git or VCS
dependency is declared. If a platform-specific PyTorch build is needed,
install it separately before installing this package.

## Models, external assets, and limitations

Model weights are external Hugging Face assets and are not redistributed by
this package. Review the license and terms for each checkpoint, the underlying
pre-trained model, and any dataset used to train it before downloading or
redistributing them. The model collection and the [Vox-Profile paper](https://arxiv.org/abs/2505.14648)
provide the current checkpoint and research details.

These models produce statistical predictions about speech and speaker traits;
they are research tools, not ground truth, identity verification, medical
advice, employment decisions, or safety-critical systems. Consider accuracy,
bias, consent, privacy, jurisdictional requirements, and the possibility of
harm before using outputs. The original project is under peer review and model
coverage and performance may change.

## Attribution and license

Vox-Profile was created by Tiantian Feng and collaborators. Please cite the
original work:

```bibtex
@article{feng2025vox,
  title={Vox-Profile: A Speech Foundation Model Benchmark for Characterizing Diverse Speaker and Speech Traits},
  author={Feng, Tiantian and Lee, Jihwan and Xu, Anfeng and Lee, Yoonjeong and Lertpetchpun, Thanathai and Shi, Xuan and Wang, Helin and Thebaud, Thomas and Moro-Velazquez, Laureano and Byrd, Dani and others},
  journal={arXiv preprint arXiv:2505.14648},
  year={2025}
}
```

The source code remains distributed under the complete
[Responsible AI Source Code License v1.1 (RAIL)](LICENSE), including its
restrictions, notice requirements, and termination provisions. The full
license file is included in source distributions and wheels. Read it before
use or redistribution; this README does not replace the license and does not
grant permission for restricted uses.

## Development

```bash
python -m pip install -e .
python -m build
python -m twine check dist/*
```

## Maintainer publishing setup

The repository workflow publishes only when a GitHub Release is published. It
expects the release target branch to be `main` and uses PyPI Trusted
Publishing (OIDC), not an API token.

Before the first release:

1. Sign in to PyPI and search for `hyperion-voxprofile`. If it is unregistered,
   create the project by publishing through the configured trusted publisher;
   PyPI creates the project on the first successful upload. If the name is
   already registered by someone else, do not attempt to impersonate it:
   choose an available name or contact PyPI only if you have a legitimate
   naming/trademark claim.
2. In PyPI account settings, add a Trusted Publisher for owner `hyperion-ml`,
   repository `vox-profile-release`, workflow filename
   `.github/workflows/python-publish.yml`, and environment `pypi`.
3. In GitHub, create the `pypi` environment. Restrict deployment to the
   maintainers who may publish and, if desired, require reviewers or other
   environment protection rules. Do not add a PyPI token secret; the workflow
   needs only `contents: read` and `id-token: write`.
4. From `main`, create a version tag and a GitHub Release for that tag. Set
   the release target to `main` and publish it; drafts and ordinary pushes or
   pull requests do not publish.
5. Verify the workflow run, then inspect
   [the PyPI project page](https://pypi.org/project/hyperion-voxprofile/) for
   the wheel and source archive, metadata, Python requirement, dependencies,
   project URLs, and included `LICENSE` file. Test installation in a clean
   Python 3.10+ environment.

See the [GitHub workflow](.github/workflows/python-publish.yml) for the exact
Trusted Publisher values used by this repository.
