openpronounce 0.2.0__tar.gz

openpronounce-0.2.0/LICENSE

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2025 Jean-François Lépine <http://blog.lepine.pro>
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

openpronounce-0.2.0/PKG-INFO

@@ -0,0 +1,235 @@
+Metadata-Version: 2.4
+Name: openpronounce
+Version: 0.2.0
+Summary: Open-source, phoneme-level English pronunciation assessment (Wav2Vec2 + DTW). Score a recording, list mispronounced words, get prosody curves.
+Author: Jean-François Lépine
+License: MIT
+Project-URL: Homepage, https://github.com/Halleck45/OpenPronounce
+Project-URL: Repository, https://github.com/Halleck45/OpenPronounce
+Project-URL: Issues, https://github.com/Halleck45/OpenPronounce/issues
+Project-URL: Blog post, https://blog.lepine.pro/en/ai-wav2vec-pronunciation-vectorization/
+Keywords: pronunciation,pronunciation-assessment,speech,phonemes,wav2vec2,CAPT,language-learning,asr,prosody,visemes
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Education
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Education
+Classifier: Topic :: Multimedia :: Sound/Audio :: Speech
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: torch>=2.0
+Requires-Dist: transformers>=4.30
+Requires-Dist: librosa>=0.10
+Requires-Dist: soundfile>=0.12
+Requires-Dist: numpy>=1.24
+Requires-Dist: scipy>=1.10
+Requires-Dist: scikit-learn>=1.2
+Requires-Dist: fastdtw>=0.3
+Requires-Dist: phonemizer>=3.2
+Requires-Dist: Levenshtein>=0.20
+Requires-Dist: gTTS>=2.3
+Provides-Extra: app
+Requires-Dist: fastapi>=0.100; extra == "app"
+Requires-Dist: uvicorn[standard]>=0.23; extra == "app"
+Requires-Dist: python-multipart>=0.0.6; extra == "app"
+Requires-Dist: jinja2>=3.1; extra == "app"
+Requires-Dist: streamlit>=1.30; extra == "app"
+Provides-Extra: dev
+Requires-Dist: pytest>=7; extra == "dev"
+Requires-Dist: pytest-cov>=4; extra == "dev"
+Requires-Dist: httpx>=0.24; extra == "dev"
+Dynamic: license-file
+
+<h1 align="center">OpenPronounce</h1>
+
+<p align="center">
+  <b>Open-source, phoneme-level English pronunciation assessment.</b><br>
+  Give it a recording and the sentence that was supposed to be said. Get a score, the mispronounced words with expected vs. heard phonemes (IPA), the transcription and the prosody curves. Runs on your machine, on CPU.
+</p>
+
+<p align="center">
+  <a href="https://colab.research.google.com/github/Halleck45/OpenPronounce/blob/main/OpenPronounce-demo.ipynb"><img src="https://colab.research.google.com/assets/colab-badge.svg" alt="Open in Colab"></a>
+  <a href="https://github.com/Halleck45/OpenPronounce/actions/workflows/tests.yml"><img src="https://github.com/Halleck45/OpenPronounce/actions/workflows/tests.yml/badge.svg" alt="Tests"></a>
+  <a href="https://opensource.org/licenses/MIT"><img src="https://img.shields.io/badge/License-MIT-yellow.svg" alt="License: MIT"></a>
+  <a href="https://github.com/sponsors/Halleck45"><img src="https://img.shields.io/static/v1?label=Sponsor&message=%E2%9D%A4&logo=GitHub&color=%23fe8e86" alt="Sponsor"></a>
+</p>
+
+<p align="center">
+  <img src="./docs/open-pronounce-preview.png" alt="OpenPronounce web application: score, mispronounced words, phoneme and prosody charts" width="720">
+</p>
+
+```console
+$ openpronounce recording.wav "Hello, how are you?"
+Score        : 55.74/100
+Transcription: HELL NO WHO ARE YOU
+Heard phones : /h ɛ l n oʊ h u ɑɹ j u/
+Mispronounced:
+  - hello: expected /həloʊ/, heard /hɛlnoʊ/
+  - how: expected /haʊ/, heard /hu/
+```
+
+Commercial APIs (Azure Speech *Pronunciation Assessment*, SpeechAce, ELSA...) do this behind a paywall and a network call. OpenPronounce is the self-hosted, MIT-licensed building block for language-learning apps, EdTech products and research: no API key, no per-minute billing, your learners' voices stay on your servers.
+
+## What you get
+
+For each recording, a JSON-serializable dict:
+
+| Field | Meaning |
+|---|---|
+| `score` | 0-100 overall pronunciation score |
+| `transcribe` | what the model actually heard (Wav2Vec2 CTC) |
+| `differences.errors[]` | one entry per mispronounced or missing word: `word`, `expected` (IPA), `actual` (IPA, what was really heard), `position` |
+| `differences.heard_phones`, `differences.expected_phones` | the phones recognized in the audio, and the phones expected for each word |
+| `differences.words_with_errors` | the words to work on |
+| `differences.phoneme_error_rate`, `differences.word_error_rate` | edited phonemes / expected phonemes, edited words / expected words |
+| `differences.expected_phonemes`, `differences.transcribed_phonemes` | full phoneme sequences |
+| `differences.expected_vector`, `differences.transcribed_vector` | DTW-aligned phoneme traces, ready to plot |
+| `acoustic_distance` | mean per-frame DTW distance between the learner's Wav2Vec2 embeddings and a synthetic reference |
+| `prosody.f0`, `prosody.energy` | pitch and loudness contours |
+
+## Quickstart
+
+### Install
+
+Requires Python 3.10+, `ffmpeg` and `espeak-ng` on the system (`apt install ffmpeg espeak-ng`, `brew install ffmpeg espeak-ng`).
+
+```bash
+pip install torch --index-url https://download.pytorch.org/whl/cpu   # CPU wheels, much smaller
+pip install git+https://github.com/Halleck45/OpenPronounce.git
+```
+
+Two Wav2Vec2 checkpoints (~1.2 GB each) are downloaded from the Hugging Face Hub on first use: `facebook/wav2vec2-large-960h` (words) and `facebook/wav2vec2-lv-60-espeak-cv-ft` (phones). Set `OPENPRONOUNCE_PHONEME_MODEL=off` to skip the second one; word errors are then inferred from the transcription, which is less precise.
+
+### Command line
+
+```bash
+openpronounce recording.wav "Hello, I am a developer"
+openpronounce recording.mp3 "Hello, I am a developer" --json --no-prosody   # machine-readable
+```
+
+### Python
+
+```python
+from openpronounce import load_audio, compare_audio_with_text
+
+sound = load_audio("recording.wav")          # any format ffmpeg reads, resampled to 16 kHz mono
+result = compare_audio_with_text(sound, "Hello, I am a developer")
+
+print(result["score"])                       # 97.36
+for err in result["differences"]["errors"]:
+    print(err["word"], err["expected"], "->", err["actual"] or "(missing)")
+```
+
+Lower-level building blocks are exposed too: `transcribe(sound)`, `get_phonemes(text)`, `compare_transcriptions(heard_text, expected_text)`.
+
+### Docker
+
+```bash
+docker build -t openpronounce .
+docker run -p 8000:8000 openpronounce
+# open http://localhost:8000
+```
+
+### Web application (FastAPI)
+
+```bash
+pip install "openpronounce[app] @ git+https://github.com/Halleck45/OpenPronounce.git"
+git clone https://github.com/Halleck45/OpenPronounce.git && cd OpenPronounce
+uvicorn server:app --host 0.0.0.0 --port 8000
+```
+
+The UI records from the microphone, scores the sentence, animates a mouth (visemes) and plots the phoneme traces and prosody. Browsers only allow microphone access on `https://` or `localhost`.
+
+| Endpoint | Body (multipart form) | Returns |
+|---|---|---|
+| `POST /pronunciation` | `file`, `expected_text` | full analysis (see above) |
+| `POST /speech2text` | `file` | `{"transcript": ...}` |
+| `POST /phonemes` | `text` | `{"phonemes": [...], "words": [...]}` |
+| `POST /tts` | `text` | reference pronunciation, 16 kHz wav |
+| `GET /health` | | `{"status": "ok"}` |
+
+Interactive docs at `/docs` (Swagger UI).
+
+### Streamlit
+
+```bash
+streamlit run streamlit_app.py
+```
+
+### Notebook
+
+[Open in Colab](https://colab.research.google.com/github/Halleck45/OpenPronounce/blob/main/OpenPronounce-demo.ipynb): load a sample, score it, print the phoneme errors, plot the prosody, then try your own recording. No local setup.
+
+## How it works
+
+1. **Phones**: a Wav2Vec2 model fine-tuned on espeak labels (`wav2vec2-lv-60-espeak-cv-ft`) recognizes the phones actually said, straight from the audio. No word-level language model gets a chance to "correct" the learner.
+2. **Expected phones**: the sentence is phonemized with espeak-ng (IPA), word by word. Both sequences are normalized (length marks dropped, reduced vowels merged, cot-caught merger, a few function words with alternate pronunciations).
+3. **Alignment**: expected and heard phones are aligned with edit-distance opcodes; each word is compared with the phones it aligned to and reported when half of them (or 3 or more) are wrong. Thresholds: `phones.PHONE_ERROR_THRESHOLD`, `phones.PHONE_ERROR_MIN_EDITS`.
+4. **Words**: the audio is also transcribed with `wav2vec2-large-960h` for the transcription and the word error rate.
+5. **Acoustics**: the sentence is synthesized (gTTS), both recordings are encoded with Wav2Vec2 and aligned with DTW; the mean per-frame distance is the `acoustic_distance`.
+6. **Prosody**: F0 (pYIN) and RMS energy contours.
+
+The approach is described in [this blog post](https://blog.lepine.pro/en/ai-wav2vec-pronunciation-vectorization/).
+
+### The score
+
+`score = 0.2 × acoustic + 0.5 × (1 − phoneme error rate) + 0.3 × (1 − word error rate)`, each term clipped to [0, 100].
+The acoustic term maps the mean DTW distance linearly from 5 (100) to 15 (0); these bounds come from the bundled samples (`assets/`) and are exposed as `speech.ACOUSTIC_DISTANCE_GOOD` / `speech.ACOUSTIC_DISTANCE_BAD` if you want to recalibrate on your own data. All three terms are length-independent, so a long paragraph and a two-word sentence are scored on the same scale.
+
+## Visemes
+
+The web UI ships a small [phoneme-to-viseme](static/viseme.js) mapping for English (HumanBeanCMU39 mouth shapes), enough to animate a talking mouth from the phoneme list:
+
+```javascript
+import { Viseme } from "/static/viseme.js";
+const viseme = new Viseme(document.getElementById("mouth"));
+viseme.play(["həloʊ", "huː", "ɑːɹ", "juː"]);
+```
+
+## Limitations
+
+- English only for now (`en-us` phonemization, English Wav2Vec2). Swapping the model and the espeak language is the path to other languages.
+- The reference voice comes from gTTS, so the first analysis of a given sentence needs network access; references are cached afterwards.
+- Wav2Vec2 was trained on native read speech (LibriSpeech). Very strong accents, children's voices and noisy recordings degrade the transcription, and therefore the feedback.
+- The phone recognizer itself has an error rate (about 10 % of phones on a clean native reading of the bundled Harvard sentences); expect an occasional false alarm on short words. This is a heuristic assessment, not a Goodness-of-Pronunciation model trained on annotated L2 speech.
+
+## Roadmap
+
+Contributions welcome on any of these:
+
+- [ ] Publish on PyPI (`pip install openpronounce`)
+- [ ] Hosted demo (Hugging Face Space)
+- [ ] Offline TTS reference (piper / Kokoro) instead of gTTS
+- [ ] Per-phone confidence (CTC posteriors) to grade errors instead of a yes/no per word
+- [ ] Other languages
+- [ ] Benchmark on a public L2 dataset (speechocean762) to calibrate the score
+- [ ] GPU support in the Docker image
+
+## Contributing
+
+```bash
+git clone https://github.com/Halleck45/OpenPronounce.git && cd OpenPronounce
+python -m venv .venv && source .venv/bin/activate
+pip install torch --index-url https://download.pytorch.org/whl/cpu
+pip install -e ".[app,dev]"
+pytest
+```
+
+Tests do not need the network nor the model weights (model calls are mocked); espeak-ng must be installed.
+
+## References
+
+- [Vectorisation of sounds for pronunciation](https://blog.lepine.pro/en/ai-wav2vec-pronunciation-vectorization/) (blog post about this project)
+- [wav2vec 2.0](https://ai.meta.com/research/impact/wav2vec/), Baevski et al., 2020
+- [Azure Speech visemes](https://learn.microsoft.com/azure/ai-services/speech-service/how-to-speech-synthesis-viseme) and [SSML phonetic sets](https://learn.microsoft.com/azure/ai-services/speech-service/speech-ssml-phonetic-sets)
+- Mouth images: HumanBeanCMU39 viseme set
+
+## License
+
+MIT, see [LICENSE](LICENSE).

openpronounce-0.2.0/README.md

@@ -0,0 +1,187 @@
+<h1 align="center">OpenPronounce</h1>
+
+<p align="center">
+  <b>Open-source, phoneme-level English pronunciation assessment.</b><br>
+  Give it a recording and the sentence that was supposed to be said. Get a score, the mispronounced words with expected vs. heard phonemes (IPA), the transcription and the prosody curves. Runs on your machine, on CPU.
+</p>
+
+<p align="center">
+  <a href="https://colab.research.google.com/github/Halleck45/OpenPronounce/blob/main/OpenPronounce-demo.ipynb"><img src="https://colab.research.google.com/assets/colab-badge.svg" alt="Open in Colab"></a>
+  <a href="https://github.com/Halleck45/OpenPronounce/actions/workflows/tests.yml"><img src="https://github.com/Halleck45/OpenPronounce/actions/workflows/tests.yml/badge.svg" alt="Tests"></a>
+  <a href="https://opensource.org/licenses/MIT"><img src="https://img.shields.io/badge/License-MIT-yellow.svg" alt="License: MIT"></a>
+  <a href="https://github.com/sponsors/Halleck45"><img src="https://img.shields.io/static/v1?label=Sponsor&message=%E2%9D%A4&logo=GitHub&color=%23fe8e86" alt="Sponsor"></a>
+</p>
+
+<p align="center">
+  <img src="./docs/open-pronounce-preview.png" alt="OpenPronounce web application: score, mispronounced words, phoneme and prosody charts" width="720">
+</p>
+
+```console
+$ openpronounce recording.wav "Hello, how are you?"
+Score        : 55.74/100
+Transcription: HELL NO WHO ARE YOU
+Heard phones : /h ɛ l n oʊ h u ɑɹ j u/
+Mispronounced:
+  - hello: expected /həloʊ/, heard /hɛlnoʊ/
+  - how: expected /haʊ/, heard /hu/
+```
+
+Commercial APIs (Azure Speech *Pronunciation Assessment*, SpeechAce, ELSA...) do this behind a paywall and a network call. OpenPronounce is the self-hosted, MIT-licensed building block for language-learning apps, EdTech products and research: no API key, no per-minute billing, your learners' voices stay on your servers.
+
+## What you get
+
+For each recording, a JSON-serializable dict:
+
+| Field | Meaning |
+|---|---|
+| `score` | 0-100 overall pronunciation score |
+| `transcribe` | what the model actually heard (Wav2Vec2 CTC) |
+| `differences.errors[]` | one entry per mispronounced or missing word: `word`, `expected` (IPA), `actual` (IPA, what was really heard), `position` |
+| `differences.heard_phones`, `differences.expected_phones` | the phones recognized in the audio, and the phones expected for each word |
+| `differences.words_with_errors` | the words to work on |
+| `differences.phoneme_error_rate`, `differences.word_error_rate` | edited phonemes / expected phonemes, edited words / expected words |
+| `differences.expected_phonemes`, `differences.transcribed_phonemes` | full phoneme sequences |
+| `differences.expected_vector`, `differences.transcribed_vector` | DTW-aligned phoneme traces, ready to plot |
+| `acoustic_distance` | mean per-frame DTW distance between the learner's Wav2Vec2 embeddings and a synthetic reference |
+| `prosody.f0`, `prosody.energy` | pitch and loudness contours |
+
+## Quickstart
+
+### Install
+
+Requires Python 3.10+, `ffmpeg` and `espeak-ng` on the system (`apt install ffmpeg espeak-ng`, `brew install ffmpeg espeak-ng`).
+
+```bash
+pip install torch --index-url https://download.pytorch.org/whl/cpu   # CPU wheels, much smaller
+pip install git+https://github.com/Halleck45/OpenPronounce.git
+```
+
+Two Wav2Vec2 checkpoints (~1.2 GB each) are downloaded from the Hugging Face Hub on first use: `facebook/wav2vec2-large-960h` (words) and `facebook/wav2vec2-lv-60-espeak-cv-ft` (phones). Set `OPENPRONOUNCE_PHONEME_MODEL=off` to skip the second one; word errors are then inferred from the transcription, which is less precise.
+
+### Command line
+
+```bash
+openpronounce recording.wav "Hello, I am a developer"
+openpronounce recording.mp3 "Hello, I am a developer" --json --no-prosody   # machine-readable
+```
+
+### Python
+
+```python
+from openpronounce import load_audio, compare_audio_with_text
+
+sound = load_audio("recording.wav")          # any format ffmpeg reads, resampled to 16 kHz mono
+result = compare_audio_with_text(sound, "Hello, I am a developer")
+
+print(result["score"])                       # 97.36
+for err in result["differences"]["errors"]:
+    print(err["word"], err["expected"], "->", err["actual"] or "(missing)")
+```
+
+Lower-level building blocks are exposed too: `transcribe(sound)`, `get_phonemes(text)`, `compare_transcriptions(heard_text, expected_text)`.
+
+### Docker
+
+```bash
+docker build -t openpronounce .
+docker run -p 8000:8000 openpronounce
+# open http://localhost:8000
+```
+
+### Web application (FastAPI)
+
+```bash
+pip install "openpronounce[app] @ git+https://github.com/Halleck45/OpenPronounce.git"
+git clone https://github.com/Halleck45/OpenPronounce.git && cd OpenPronounce
+uvicorn server:app --host 0.0.0.0 --port 8000
+```
+
+The UI records from the microphone, scores the sentence, animates a mouth (visemes) and plots the phoneme traces and prosody. Browsers only allow microphone access on `https://` or `localhost`.
+
+| Endpoint | Body (multipart form) | Returns |
+|---|---|---|
+| `POST /pronunciation` | `file`, `expected_text` | full analysis (see above) |
+| `POST /speech2text` | `file` | `{"transcript": ...}` |
+| `POST /phonemes` | `text` | `{"phonemes": [...], "words": [...]}` |
+| `POST /tts` | `text` | reference pronunciation, 16 kHz wav |
+| `GET /health` | | `{"status": "ok"}` |
+
+Interactive docs at `/docs` (Swagger UI).
+
+### Streamlit
+
+```bash
+streamlit run streamlit_app.py
+```
+
+### Notebook
+
+[Open in Colab](https://colab.research.google.com/github/Halleck45/OpenPronounce/blob/main/OpenPronounce-demo.ipynb): load a sample, score it, print the phoneme errors, plot the prosody, then try your own recording. No local setup.
+
+## How it works
+
+1. **Phones**: a Wav2Vec2 model fine-tuned on espeak labels (`wav2vec2-lv-60-espeak-cv-ft`) recognizes the phones actually said, straight from the audio. No word-level language model gets a chance to "correct" the learner.
+2. **Expected phones**: the sentence is phonemized with espeak-ng (IPA), word by word. Both sequences are normalized (length marks dropped, reduced vowels merged, cot-caught merger, a few function words with alternate pronunciations).
+3. **Alignment**: expected and heard phones are aligned with edit-distance opcodes; each word is compared with the phones it aligned to and reported when half of them (or 3 or more) are wrong. Thresholds: `phones.PHONE_ERROR_THRESHOLD`, `phones.PHONE_ERROR_MIN_EDITS`.
+4. **Words**: the audio is also transcribed with `wav2vec2-large-960h` for the transcription and the word error rate.
+5. **Acoustics**: the sentence is synthesized (gTTS), both recordings are encoded with Wav2Vec2 and aligned with DTW; the mean per-frame distance is the `acoustic_distance`.
+6. **Prosody**: F0 (pYIN) and RMS energy contours.
+
+The approach is described in [this blog post](https://blog.lepine.pro/en/ai-wav2vec-pronunciation-vectorization/).
+
+### The score
+
+`score = 0.2 × acoustic + 0.5 × (1 − phoneme error rate) + 0.3 × (1 − word error rate)`, each term clipped to [0, 100].
+The acoustic term maps the mean DTW distance linearly from 5 (100) to 15 (0); these bounds come from the bundled samples (`assets/`) and are exposed as `speech.ACOUSTIC_DISTANCE_GOOD` / `speech.ACOUSTIC_DISTANCE_BAD` if you want to recalibrate on your own data. All three terms are length-independent, so a long paragraph and a two-word sentence are scored on the same scale.
+
+## Visemes
+
+The web UI ships a small [phoneme-to-viseme](static/viseme.js) mapping for English (HumanBeanCMU39 mouth shapes), enough to animate a talking mouth from the phoneme list:
+
+```javascript
+import { Viseme } from "/static/viseme.js";
+const viseme = new Viseme(document.getElementById("mouth"));
+viseme.play(["həloʊ", "huː", "ɑːɹ", "juː"]);
+```
+
+## Limitations
+
+- English only for now (`en-us` phonemization, English Wav2Vec2). Swapping the model and the espeak language is the path to other languages.
+- The reference voice comes from gTTS, so the first analysis of a given sentence needs network access; references are cached afterwards.
+- Wav2Vec2 was trained on native read speech (LibriSpeech). Very strong accents, children's voices and noisy recordings degrade the transcription, and therefore the feedback.
+- The phone recognizer itself has an error rate (about 10 % of phones on a clean native reading of the bundled Harvard sentences); expect an occasional false alarm on short words. This is a heuristic assessment, not a Goodness-of-Pronunciation model trained on annotated L2 speech.
+
+## Roadmap
+
+Contributions welcome on any of these:
+
+- [ ] Publish on PyPI (`pip install openpronounce`)
+- [ ] Hosted demo (Hugging Face Space)
+- [ ] Offline TTS reference (piper / Kokoro) instead of gTTS
+- [ ] Per-phone confidence (CTC posteriors) to grade errors instead of a yes/no per word
+- [ ] Other languages
+- [ ] Benchmark on a public L2 dataset (speechocean762) to calibrate the score
+- [ ] GPU support in the Docker image
+
+## Contributing
+
+```bash
+git clone https://github.com/Halleck45/OpenPronounce.git && cd OpenPronounce
+python -m venv .venv && source .venv/bin/activate
+pip install torch --index-url https://download.pytorch.org/whl/cpu
+pip install -e ".[app,dev]"
+pytest
+```
+
+Tests do not need the network nor the model weights (model calls are mocked); espeak-ng must be installed.
+
+## References
+
+- [Vectorisation of sounds for pronunciation](https://blog.lepine.pro/en/ai-wav2vec-pronunciation-vectorization/) (blog post about this project)
+- [wav2vec 2.0](https://ai.meta.com/research/impact/wav2vec/), Baevski et al., 2020
+- [Azure Speech visemes](https://learn.microsoft.com/azure/ai-services/speech-service/how-to-speech-synthesis-viseme) and [SSML phonetic sets](https://learn.microsoft.com/azure/ai-services/speech-service/speech-ssml-phonetic-sets)
+- Mouth images: HumanBeanCMU39 viseme set
+
+## License
+
+MIT, see [LICENSE](LICENSE).

openpronounce-0.2.0/openpronounce/__init__.py

@@ -0,0 +1,35 @@
+"""OpenPronounce: open-source, phoneme-level English pronunciation assessment.
+
+Typical usage::
+
+    from openpronounce import load_audio, compare_audio_with_text
+
+    sound = load_audio("recording.wav")
+    result = compare_audio_with_text(sound, "Hello, I am a developer")
+    print(result["score"], result["differences"]["errors"])
+"""
+
+from .audio import load as load_audio, text2speech
+from .phones import compare_phones, transcribe_phones
+from .speech import (
+    compare_audio_with_text,
+    compare_transcriptions,
+    get_phonemes,
+    get_phonemes_with_word_mapping,
+    transcribe,
+)
+
+__version__ = "0.2.0"
+
+__all__ = [
+    "__version__",
+    "load_audio",
+    "text2speech",
+    "compare_audio_with_text",
+    "compare_transcriptions",
+    "compare_phones",
+    "transcribe_phones",
+    "get_phonemes",
+    "get_phonemes_with_word_mapping",
+    "transcribe",
+]

openpronounce-0.2.0/openpronounce/audio.py

@@ -0,0 +1,75 @@
+"""Audio loading, conversion and reference-speech generation."""
+
+import hashlib
+import logging
+import os
+import tempfile
+
+import librosa
+import soundfile as sf
+from gtts import gTTS
+
+logger = logging.getLogger(__name__)
+
+TARGET_SR = 16000
+
+CACHE_DIR = os.environ.get(
+    "OPENPRONOUNCE_CACHE_DIR",
+    os.path.join(tempfile.gettempdir(), "openpronounce"),
+)
+
+
+def load(file_path, sr=TARGET_SR):
+    """Load any audio file (wav, mp3, flac, ogg, webm, m4a...) as a mono float32 waveform at 16 kHz."""
+    waveform, _ = librosa.load(file_path, sr=sr, mono=True)
+    return waveform
+
+
+def webm2wav(file_path):
+    """Convert a browser-recorded file (webm/ogg/wav/...) to a 16 kHz mono ``*.16k.wav`` file next to it.
+
+    Uses librosa (soundfile, then ffmpeg through audioread) so that ffmpeg is only
+    needed for formats libsndfile cannot read.
+    """
+    output_path = os.path.splitext(file_path)[0] + ".16k.wav"
+    try:
+        waveform = load(file_path)
+    except Exception as e:  # noqa: BLE001
+        raise RuntimeError(
+            f"Unable to decode {file_path!r} ({e}). Make sure ffmpeg is installed."
+        ) from e
+    sf.write(output_path, waveform, TARGET_SR)
+    return output_path
+
+
+# Backward-compatible alias (the original name was a typo)
+webp2wav = webm2wav
+
+
+def text2speech(text, lang="en", filename=None, target_sr=TARGET_SR):
+    """Generate a reference pronunciation of ``text`` as a 16 kHz mono wav file and return its path.
+
+    Uses gTTS (Google Translate TTS), so an internet connection is required the first
+    time a given text is requested. Results are cached in ``CACHE_DIR`` keyed by
+    ``(lang, text)`` so that repeated comparisons against the same sentence are free.
+    """
+    if filename is None:
+        os.makedirs(CACHE_DIR, exist_ok=True)
+        key = hashlib.sha1(f"{lang}\x00{target_sr}\x00{text}".encode("utf-8")).hexdigest()
+        filename = os.path.join(CACHE_DIR, f"tts-{key}.wav")
+        if os.path.exists(filename):
+            return filename
+
+    fd, mp3_path = tempfile.mkstemp(suffix=".mp3", prefix="openpronounce-tts-")
+    os.close(fd)
+    try:
+        gTTS(text=text, lang=lang, slow=False).save(mp3_path)
+        waveform = load(mp3_path, sr=target_sr)
+    finally:
+        try:
+            os.remove(mp3_path)
+        except OSError:
+            pass
+
+    sf.write(filename, waveform, target_sr)
+    return filename

openpronounce-0.2.0/openpronounce/cli.py

@@ -0,0 +1,48 @@
+"""Command-line entry point: ``openpronounce <audio> "<expected text>"``."""
+
+import argparse
+import json
+import sys
+
+
+def main(argv=None):
+    parser = argparse.ArgumentParser(
+        prog="openpronounce",
+        description="Score the pronunciation of an English recording against the sentence it should contain.",
+    )
+    parser.add_argument("audio", help="path to a wav/mp3/flac/ogg/webm recording")
+    parser.add_argument("text", help="the sentence the speaker was supposed to say")
+    parser.add_argument("--json", action="store_true", help="print the full JSON result instead of a summary")
+    parser.add_argument("--no-prosody", action="store_true", help="omit prosody contours from the JSON output")
+    args = parser.parse_args(argv)
+
+    from . import audio, speech
+
+    sound = audio.load(args.audio)
+    result = speech.compare_audio_with_text(sound, args.text)
+
+    if args.no_prosody:
+        result.pop("prosody", None)
+
+    if args.json:
+        json.dump(result, sys.stdout, ensure_ascii=False, indent=2)
+        sys.stdout.write("\n")
+        return 0
+
+    print(f"Score        : {result['score']}/100")
+    print(f"Transcription: {result['transcribe']}")
+    if "heard_phones" in result["differences"]:
+        print(f"Heard phones : /{' '.join(result['differences']['heard_phones'])}/")
+    errors = result["differences"]["errors"]
+    if errors:
+        print("Mispronounced:")
+        for err in errors:
+            actual = f"/{err['actual']}/" if err["actual"] else "(missing)"
+            print(f"  - {err['word']}: expected /{err['expected']}/, heard {actual}")
+    else:
+        print("No mispronounced word detected.")
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())