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. 1

    Install

    You need Python 3.10 or later and ffmpeg. Languages other than English also need the espeak-ng program. 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

    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. 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. 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. 4

    Call it from Python

    assess handles 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. 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

    The running server documents itself on /docs. See also the endpoints.

  6. 6

    Show the result to your users

    Check reliable before anything else. When it is false, ask the speaker to try again and tell them why, using reasons.

    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 start to its end, 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.