Installation guide
Six steps, from installation to a result shown in your application. You will have a first score at the end of step 2. Nothing here needs an account or a key.
-
1
Install
You need Python 3.10 or later and
ffmpeg. Languages other than English also need theespeak-ngprogram. The first analysis downloads two speech models of 1.2 GB each.$ sudo apt install ffmpeg espeak-ng $ python3 -m venv .venv && . .venv/bin/activate $ pip install torch --index-url https://download.pytorch.org/whl/cpu $ pip install openpronounce
$ brew install ffmpeg espeak-ng $ python3 -m venv .venv && . .venv/bin/activate $ pip install openpronounce
$ git clone https://github.com/OpenPronounce/OpenPronounce && cd OpenPronounce $ docker build -t openpronounce . $ docker run -p 8000:8000 openpronounce
On Linux, the third line installs the CPU build of PyTorch, which is much smaller than the default. The Docker image includes the models and serves a web demo and the HTTP API on port 8000. On Windows, use Docker or WSL.
-
2
Score a read sentence
This recording from the project was made for the sentence "Hello, I am a good designer", but the speaker said "developer".
$ curl -LO https://raw.githubusercontent.com/OpenPronounce/OpenPronounce/main/assets/developer.wav $ openpronounce developer.wav "Hello, I am a good designer" Score : 36.2/100 accuracy 36.6, fluency 55.0, prosodic 45.9 Warning : not said: good (scores unreliable) Transcription: HELLO I AM A DEVELOPER Heard phones : /h ə l oʊ aɪ æ m ə d ɪ v ɛ l ə p ɚ/ Mispronounced: - good: not said - designer: expected /dɪzaɪnɚ/, heard /vɛləpɚ/ (confidence 89%)
Then try a recording of your own voice. It reads wav, mp3, flac, ogg and webm.
-
3
Score free speech
Without a sentence, the recording is transcribed, cut at its pauses and scored part by part.
$ curl -LO https://raw.githubusercontent.com/OpenPronounce/OpenPronounce/main/assets/harvard.wav $ openpronounce harvard.wav Score : 78.2/100 accuracy 81.5, fluency 78.8, prosodic 77.5 Transcription: the stale smell of old bear lingers it takes heat to bring out the odor ... Speech : 15.9 s in 4 segment(s)
-
4
Call it from Python
assesshandles both cases. It takes a 16 kHz mono waveform and returns a dictionary that serialises to JSON.from openpronounce import load_audio, assess result = assess(load_audio("developer.wav"), "Hello, I am a good designer") result["scores"] # {'total': 36.2, 'accuracy': 36.6, 'fluency': 55.0, 'prosodic': 45.9} result["reliable"] # False result["reasons"] # ['not said: good'] for word in result["differences"]["errors"]: print(word["word"], word["expected"], word["actual"], word.get("missing", False)) # good ɡʊd dɪ True # designer dɪzaɪnɚ vɛləpɚ False
Pass
lang="fr"for French, and so on. The result reference describes every field. -
5
Call it over HTTP
With the Docker image running, your web or mobile front end sends the recording and receives the same JSON.
$ curl -F file=@developer.wav -F expected_text="Hello, I am a good designer" \ http://localhost:8000/pronunciation $ curl -F file=@harvard.wav http://localhost:8000/free
const form = new FormData(); form.append("file", recordingBlob, "answer.webm"); form.append("expected_text", "Hello, I am a good designer"); const result = await (await fetch("/pronunciation", { method: "POST", body: form })).json();
The running server documents itself on
/docs. See also the endpoints. -
6
Show the result to your users
Check
reliablebefore anything else. When it is false, ask the speaker to try again and tell them why, usingreasons.Show the total as a band rather than a decimal: 76.6 and 78.1 describe the same performance. Then list two or three flagged words, each with a button that replays it from its
startto itsend, next to a native reading.If the product is closed source, it needs a commercial licence before it reaches users. Development and testing are covered by the AGPL.
Next: measure it on your own recordings
The published figures come from one group of speakers. A CSV of recordings scored by your own assessors and one command tell you how it does on yours.