SpeechRecognition

.. image:: https://img.shields.io/pypi/v/SpeechRecognition.svg :target: https://pypi.python.org/pypi/SpeechRecognition/ :alt: Latest Version

.. image:: https://img.shields.io/pypi/status/SpeechRecognition.svg :target: https://pypi.python.org/pypi/SpeechRecognition/ :alt: Development Status

.. image:: https://img.shields.io/pypi/pyversions/SpeechRecognition.svg :target: https://pypi.python.org/pypi/SpeechRecognition/ :alt: Supported Python Versions

.. image:: https://img.shields.io/pypi/l/SpeechRecognition.svg :target: https://pypi.python.org/pypi/SpeechRecognition/ :alt: License

.. image:: https://api.travis-ci.org/Uberi/speechrecognition.svg?branch=master :target: https://travis-ci.org/Uberi/speechrecognition :alt: Continuous Integration Test Results

Library for performing speech recognition, with support for several engines and APIs, online and offline.

Speech recognition engine/API support:

• CMU Sphinx 

  __ (works offline)
• Google Speech Recognition

• Google Cloud Speech API 

  __

• Wit.ai 

  __

• Microsoft Azure Speech 

  __

• Microsoft Bing Voice Recognition (Deprecated) 

  __

• Houndify API 

  __

• IBM Speech to Text 

  __

• Snowboy Hotword Detection 

  __ (works offline)

Quickstart:

pip install SpeechRecognition

To quickly try it out, run

python -m speech_recognition

Project links:

• PyPI 

  __

• Source code 

  __

• Issue tracker 

  __

Library Reference

The

library reference 

reference/library-reference.rst

See

Notes on using PocketSphinx 

reference/pocketsphinx.rst

Examples

See the

examples/

directory 

• Recognize speech input from the microphone 

  __

• Transcribe an audio file 

  __

• Save audio data to an audio file 

  __

• Show extended recognition results 

  __

• Calibrate the recognizer energy threshold for ambient noise levels 

  __ (see

  recognizer_instance.energy_threshold

  for details)

• Listening to a microphone in the background 

  __

• Various other useful recognizer features 

  __

Installing

First, make sure you have all the requirements listed in the "Requirements" section.

The easiest way to install this is using

pip install SpeechRecognition

Otherwise, download the source distribution from

PyPI 

In the folder, run

python setup.py install

Requirements

To use all of the functionality of the library, you should have:

• Python 2.6, 2.7, or 3.3+ (required)
• PyAudio 0.2.11+ (required only if you need to use microphone input,

  Microphone

  )
• PocketSphinx (required only if you need to use the Sphinx recognizer,

  recognizer_instance.recognize_sphinx

  )
• Google API Client Library for Python (required only if you need to use the Google Cloud Speech API,

  recognizer_instance.recognize_google_cloud

  )
• FLAC encoder (required only if the system is not x86-based Windows/Linux/OS X)

The following requirements are optional, but can improve or extend functionality in some situations:

• On Python 2, and only on Python 2, some functions (like

  recognizer_instance.recognize_bing

  ) will run slower if you do not have Monotonic for Python 2 installed.
• If using CMU Sphinx, you may want to

  install additional language packs 

  __ to support languages like International French or Mandarin Chinese.

The following sections go over the details of each requirement.

Python ~~~~~~

The first software requirement is

Python 2.6, 2.7, or Python 3.3+ 

PyAudio (for microphone users) ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

PyAudio 

Microphone

If not installed, everything in the library will still work, except attempting to instantiate a

Microphone

AttributeError

The installation instructions on the PyAudio website are quite good - for convenience, they are summarized below:

• On Windows, install PyAudio using

  Pip 

  __: execute

  pip install pyaudio

  in a terminal.
• On Debian-derived Linux distributions (like Ubuntu and Mint), install PyAudio using

  APT 

  __: execute

  sudo apt-get install python-pyaudio python3-pyaudio

  in a terminal.
  • If the version in the repositories is too old, install the latest release using Pip: execute

    sudo apt-get install portaudio19-dev python-all-dev python3-all-dev && sudo pip install pyaudio

    (replace

    pip

    with

    pip3

    if using Python 3).
• On OS X, install PortAudio using

  Homebrew 

  :

  brew install portaudio

  . Then, install PyAudio using

  Pip 

  :

  pip install pyaudio

  .
• On other POSIX-based systems, install the

  portaudio19-dev

  and

  python-all-dev

  (or

  python3-all-dev

  if using Python 3) packages (or their closest equivalents) using a package manager of your choice, and then install PyAudio using

  Pip 

  __:

  pip install pyaudio

  (replace

  pip

  with

  pip3

  if using Python 3).

PyAudio

wheel packages 

third-party/

directory 

pip install wheel

pip install ./third-party/WHEEL_FILENAME

pip

pip3

root directory 

PocketSphinx-Python (for Sphinx users) ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

PocketSphinx-Python 

recognizer_instance.recognize_sphinx

PocketSphinx-Python

wheel packages 

third-party/

directory 

pip install wheel

(replace

with

On Linux and other POSIX systems (such as OS X), follow the instructions under "Building PocketSphinx-Python from source" in

Notes on using PocketSphinx 

Note that the versions available in most package repositories are outdated and will not work with the bundled language data. Using the bundled wheel packages or building from source is recommended.

See

Notes on using PocketSphinx 

reference/pocketsphinx.rst

Google Cloud Speech Library for Python (for Google Cloud Speech API users) ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Google Cloud Speech library for Python 

recognizer_instance.recognize_google_cloud

If not installed, everything in the library will still work, except calling

recognizer_instance.recognize_google_cloud

RequestError

According to the

official installation instructions 

Pip 

pip install google-cloud-speech

pip

pip3

FLAC (for some systems) ~~~~~~~~~~~~~~~~~~~~~~~

A

FLAC encoder 

Otherwise, ensure that you have the

flac

sudo apt-get install flac

brew install flac

Monotonic for Python 2 (for faster operations in some functions on Python 2) ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

On Python 2, and only on Python 2, if you do not install the

Monotonic for Python 2 

On Python 3, that library's functionality is built into the Python standard library, which makes it unnecessary.

This is because monotonic time is necessary to handle cache expiry properly in the face of system time changes and other time-related issues. If monotonic time functionality is not available, then things like access token requests will not be cached.

To install, use

Pip 

pip install monotonic

Troubleshooting

The recognizer tries to recognize speech even when I'm not speaking, or after I'm done speaking. ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Try increasing the

recognizer_instance.energy_threshold

This value depends entirely on your microphone or audio data. There is no one-size-fits-all value, but good values typically range from 50 to 4000.

Also, check on your microphone volume settings. If it is too sensitive, the microphone may be picking up a lot of ambient noise. If it is too insensitive, the microphone may be rejecting speech as just noise.

The recognizer can't recognize speech right after it starts listening for the first time. ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

The

recognizer_instance.energy_threshold

The solution is to decrease this threshold, or call

recognizer_instance.adjust_for_ambient_noise

The recognizer doesn't understand my particular language/dialect. ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Try setting the recognition language to your language/dialect. To do this, see the documentation for

recognizer_instance.recognize_sphinx

recognizer_instance.recognize_google

recognizer_instance.recognize_wit

recognizer_instance.recognize_bing

recognizer_instance.recognize_api

recognizer_instance.recognize_houndify

recognizer_instance.recognize_ibm

For example, if your language/dialect is British English, it is better to use

"en-GB"

"en-US"

The recognizer hangs on

recognizer_instance.listen

Microphone.MicrophoneStream.read

This usually happens when you're using a Raspberry Pi board, which doesn't have audio input capabilities by itself. This causes the default microphone used by PyAudio to simply block when we try to read it. If you happen to be using a Raspberry Pi, you'll need a USB sound card (or USB microphone).

Once you do this, change all instances of

Microphone()

Microphone(device_index=MICROPHONE_INDEX)

MICROPHONE_INDEX

To figure out what the value of

MICROPHONE_INDEX

.. code:: python

import speech_recognition as sr
for index, name in enumerate(sr.Microphone.list_microphone_names()):
    print("Microphone with name \"{1}\" found for `Microphone(device_index={0})`".format(index, name))

This will print out something like the following:

::

Microphone with name "HDA Intel HDMI: 0 (hw:0,3)" found for `Microphone(device_index=0)`
Microphone with name "HDA Intel HDMI: 1 (hw:0,7)" found for `Microphone(device_index=1)`
Microphone with name "HDA Intel HDMI: 2 (hw:0,8)" found for `Microphone(device_index=2)`
Microphone with name "Blue Snowball: USB Audio (hw:1,0)" found for `Microphone(device_index=3)`
Microphone with name "hdmi" found for `Microphone(device_index=4)`
Microphone with name "pulse" found for `Microphone(device_index=5)`
Microphone with name "default" found for `Microphone(device_index=6)`

Now, to use the Snowball microphone, you would change

Microphone()

Microphone(device_index=3)

Calling

Microphone()

IOError: No Default Input Device Available

As the error says, the program doesn't know which microphone to use.

To proceed, either use

Microphone(device_index=MICROPHONE_INDEX, ...)

Microphone(...)

MICROPHONE_INDEX

The code examples raise

UnicodeEncodeError: 'ascii' codec can't encode character

When you're using Python 2, and your language uses non-ASCII characters, and the terminal or file-like object you're printing to only supports ASCII, an error is raised when trying to write non-ASCII characters.

This is because in Python 2,

recognizer_instance.recognize_sphinx

recognizer_instance.recognize_google

recognizer_instance.recognize_wit

recognizer_instance.recognize_bing

recognizer_instance.recognize_api

recognizer_instance.recognize_houndify

recognizer_instance.recognize_ibm

u"something"

"something"

To make printing of unicode strings work in Python 2 as well, replace all print statements in your code of the following form:

.. code:: python

print SOME_UNICODE_STRING

With the following:

.. code:: python

print SOME_UNICODE_STRING.encode("utf8")

This change, however, will prevent the code from working in Python 3.

The program doesn't run when compiled with

PyInstaller 

As of PyInstaller version 3.0, SpeechRecognition is supported out of the box. If you're getting weird issues when compiling your program using PyInstaller, simply update PyInstaller.

You can easily do this by running

pip install --upgrade pyinstaller

On Ubuntu/Debian, I get annoying output in the terminal saying things like "btaudioservice_open: [...] Connection refused" and various others. ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

The "btaudioservice_open" error means that you have a Bluetooth audio device, but as a physical device is not currently connected, we can't actually use it - if you're not using a Bluetooth microphone, then this can be safely ignored. If you are, and audio isn't working, then double check to make sure your microphone is actually connected. There does not seem to be a simple way to disable these messages.

For errors of the form "ALSA lib [...] Unknown PCM", see

this StackOverflow answer 

pcm.rear cards.pcm.rear

/usr/share/alsa/alsa.conf

~/.asoundrc

/etc/asound.conf

For "jack server is not running or cannot be started" or "connect(2) call to /dev/shm/jack-1000/default/jack0 failed (err=No such file or directory)" or "attempt to connect to server failed", these are caused by ALSA trying to connect to JACK, and can be safely ignored. I'm not aware of any simple way to turn those messages off at this time, besides `entirely disabling printing while starting the microphone <https://github.com/Uberi/speechrecognition/issues/182#issuecomment-266256337>`__.

On OS X, I get a

ChildProcessError

Installing

FLAC for OS X 

Installing FLAC using

Homebrew 

brew install flac

Developing

To hack on this library, first make sure you have all the requirements listed in the "Requirements" section.

• Most of the library code lives in

  speech_recognition/__init__.py

  .
• Examples live under the

  examples/

  directory 

  , and the demo script lives in ``speech_recognition/main__.py``.
• The FLAC encoder binaries are in the

  speech_recognition/

  directory 

  __.
• Documentation can be found in the

  reference/

  directory 

  __.
• Third-party libraries, utilities, and reference material are in the

  third-party/

  directory 

  __.

To install/reinstall the library locally, run

python setup.py install

root directory 

Before a release, the version number is bumped in

README.rst

speech_recognition/__init__.py

git config gpg.program gpg2 && git config user.signingkey DB45F6C431DE7C2DCD99FF7904882258A4063489 && git tag -s VERSION_GOES_HERE -m "Version VERSION_GOES_HERE"

Releases are done by running

make-release.sh VERSION_GOES_HERE

Testing ~~~~~~~

To run all the tests:

.. code:: bash

python -m unittest discover --verbose

Testing is also done automatically by TravisCI, upon every push. To set up the environment for offline/local Travis-like testing on a Debian-like system:

.. code:: bash

sudo docker run --volume "$(pwd):/speech_recognition" --interactive --tty quay.io/travisci/travis-python:latest /bin/bash
su - travis && cd /speech_recognition
sudo apt-get update && sudo apt-get install swig libpulse-dev
pip install --user pocketsphinx monotonic && pip install --user flake8 rstcheck && pip install --user -e .
python -m unittest discover --verbose # run unit tests
python -m flake8 --ignore=E501,E701 speech_recognition tests examples setup.py # ignore errors for long lines and multi-statement lines
python -m rstcheck README.rst reference/*.rst # ensure RST is well-formed

FLAC Executables ~~~~~~~~~~~~~~~~

The included

flac-win32

official FLAC 1.3.2 32-bit Windows binary 

The included

flac-linux-x86

flac-linux-x86_64

FLAC 1.3.2 source code 

Manylinux 

The built FLAC executables should be bit-for-bit reproducible. To rebuild them, run the following inside the project directory on a Debian-like system:

.. code:: bash

# download and extract the FLAC source code
cd third-party
sudo apt-get install --yes docker.io

build FLAC inside the Manylinux i686 Docker image
tar xf flac-1.3.2.tar.xz
sudo docker run --tty --interactive --rm --volume "$(pwd):/root" quay.io/pypa/manylinux1_i686:latest bash
    cd /root/flac-1.3.2
    ./configure LDFLAGS=-static # compiler flags to make a static build
    make
exit
cp flac-1.3.2/src/flac/flac ../speech_recognition/flac-linux-x86 && sudo rm -rf flac-1.3.2/
build FLAC inside the Manylinux x86_64 Docker image
tar xf flac-1.3.2.tar.xz
sudo docker run --tty --interactive --rm --volume "$(pwd):/root" quay.io/pypa/manylinux1_x86_64:latest bash
    cd /root/flac-1.3.2
    ./configure LDFLAGS=-static # compiler flags to make a static build
    make
exit
cp flac-1.3.2/src/flac/flac ../speech_recognition/flac-linux-x86_64 && sudo rm -r flac-1.3.2/

The included

flac-mac

xACT 2.39 

xACT 2.39/xACT.app/Contents/Resources/flac

xACT2.39.zip

Authors

::

Uberi  (Anthony Zhang)
bobsayshilol
arvindch  (Arvind Chembarpu)
kevinismith  (Kevin Smith)
haas85
DelightRun 
maverickagm
kamushadenes  (Kamus Hadenes)
sbraden  (Sarah Braden)
tb0hdan (Bohdan Turkynewych)
Thynix  (Steve Dougherty)
beeedy  (Broderick Carlin)

Please report bugs and suggestions at the

issue tracker 

How to cite this library (APA style):

Zhang, A. (2017). Speech Recognition (Version 3.8) [Software]. Available from https://github.com/Uberi/speech_recognition#readme.

How to cite this library (Chicago style):

Zhang, Anthony. 2017. *Speech Recognition* (version 3.8).

Also check out the

Python Baidu Yuyin API 

Baidu Yuyin 

License

Copyright 2014-2017

Anthony Zhang (Uberi) 

GitHub 

SpeechRecognition is made available under the 3-clause BSD license. See

LICENSE.txt

root directory 

For convenience, all the official distributions of SpeechRecognition already include a copy of the necessary copyright notices and licenses. In your project, you can simply say that licensing information for SpeechRecognition can be found within the SpeechRecognition README, and make sure SpeechRecognition is visible to users if they wish to see it.

SpeechRecognition distributes source code, binaries, and language files from

CMU Sphinx 

and

SpeechRecognition distributes source code and binaries from

PyAudio 

third-party/LICENSE-PyAudio.txt

SpeechRecognition distributes binaries from

FLAC 

speech_recognition/flac-win32.exe

speech_recognition/flac-linux-x86

speech_recognition/flac-mac

aggregate 

separate programs 

LICENSE-FLAC.txt