Metadata-Version: 2.4
Name: pronounce-assess
Version: 0.1.0
Summary: A voice pronunciation assessment library for Python.
Project-URL: Homepage, https://github.com/stringbot/OpenVoice
Author-email: Siyu Zeng <siyu_zeng1@brown.edu>
License-Expression: MIT
License-File: LICENSE
Keywords: assessment,pronunciation,speech,voice
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
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: Topic :: Multimedia :: Sound/Audio :: Speech
Requires-Python: >=3.9
Requires-Dist: cmudict
Requires-Dist: eng-to-ipa
Requires-Dist: librosa
Requires-Dist: numpy
Requires-Dist: sounddevice
Requires-Dist: torch
Requires-Dist: transformers
Provides-Extra: demo
Requires-Dist: gradio; extra == 'demo'
Provides-Extra: dev
Requires-Dist: pytest; extra == 'dev'
Description-Content-Type: text/markdown

# pronounce-assess

A voice pronunciation assessment library for Python. Streams audio through a
wav2vec2 CTC phoneme model and yields per-phoneme match events
(`correct` / `mispronounced` / `omitted` / `insertion`) against a reference
IPA sequence.

## Installation

```bash
pip install pronounce-assess   # numpy, torch, transformers, sounddevice, eng-to-ipa
```

## Usage

```python
from pronounce_assess import PronounceAssessModel
from pronounce_assess.audio import ChunkRecord

assessor = PronounceAssessModel()  # loads the model; picks cuda/cpu automatically
reference = assessor.sentence_to_phonemes("The quick brown fox")

with ChunkRecord(duration=5, chunk_len=8000) as chunks:
    for event in assessor.stream_decode(chunks, reference):
        print(event["phoneme"], event["label"], event["score"])
```

The lower-level pieces (`load_model`, `sentence_to_phonemes`, `stream_decode`)
remain available if you want to manage the processor/model pair yourself.
`stream_decode` accepts any iterable of float32 numpy chunks, so you can feed
it audio from a file, a websocket, or anything else — see
[examples/live_mic_demo.py](examples/live_mic_demo.py) for a live-microphone demo.

## Project layout

```
pronounce_assess/
    __init__.py     public API + version
    streaming.py    stream_decode – the core alignment/scoring algorithm
    phonemes.py     IPA normalization, sentence → phoneme conversion
    models.py       wav2vec2 model/processor loading + PronounceAssessModel
    audio.py        microphone chunk generator (optional, needs sounddevice)
    exceptions.py   error types
tests/              pytest suite
examples/           runnable demo scripts
```

## Development

```bash
# Install in editable mode with dev tools
pip install -e .[dev]

# Run tests
pytest
```

## License

MIT
