From 4e49d58fe5d75f6a7ae7e3411db244bf4da7c550 Mon Sep 17 00:00:00 2001 From: Janek <27jf@pm.me> Date: Thu, 22 Oct 2020 22:13:04 +0200 Subject: [PATCH] Improve instructions & make links relative in README --- README.rst | 58 +++++++++++++++++++++++++----------------------------- 1 file changed, 27 insertions(+), 31 deletions(-) diff --git a/README.rst b/README.rst index 0d0322b9..9a4b23bd 100644 --- a/README.rst +++ b/README.rst @@ -37,7 +37,7 @@ Speech recognition engine/API support: **Quickstart:** ``pip install SpeechRecognition``. See the "Installing" section for more details. -To quickly try it out, run ``python -m speech_recognition`` after installing. +To quickly try it out, run ``python -m speech_recognition`` after installing (which additionally requires the ``pyaudio`` package). Project links: @@ -48,22 +48,22 @@ Project links: Library Reference ----------------- -The `library reference `__ documents every publicly accessible object in the library. This document is also included under ``reference/library-reference.rst``. +The `library reference `__ documents every publicly accessible object in the library. -See `Notes on using PocketSphinx `__ for information about installing languages, compiling PocketSphinx, and building language packs from online resources. This document is also included under ``reference/pocketsphinx.rst``. +See `Notes on using PocketSphinx `__ for information about installing languages, compiling PocketSphinx, and building language packs from online resources. Examples -------- -See the ``examples/`` `directory `__ in the repository root for usage examples: +See the `examples directory `__ in the repository root for usage examples: -- `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 `__ +- `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 ---------- @@ -81,24 +81,19 @@ 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``) +* **Python** `2.6, 2.7, or 3.3+ `__ (required) +* **PyAudio** 0.2.11+ (required only if you use microphone input, ``Microphone``) +* **PocketSphinx** (required only if you use the Sphinx recognizer, ``recognizer_instance.recognize_sphinx``) +* **Google API Client Library for Python** (required only if you 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. +* 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+ `__. This is required to use the library. - PyAudio (for microphone users) ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -114,20 +109,20 @@ The installation instructions on the PyAudio website are quite good - for conven * 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 `__ for common 64-bit Python versions on Windows and Linux are included for convenience, under the ``third-party/`` `directory `__ in the repository root. To install, simply run ``pip install wheel`` followed by ``pip install ./third-party/WHEEL_FILENAME`` (replace ``pip`` with ``pip3`` if using Python 3) in the repository `root directory `__. +PyAudio `wheel packages `__ for common 64-bit Python versions on Windows and Linux are included for convenience, under the ``third-party/`` `directory `__ in the repository root. To install, simply run ``pip install wheel`` followed by ``pip install ./third-party/WHEEL_FILENAME`` (replace ``pip`` with ``pip3`` if using Python 3) in the repository root directory. PocketSphinx-Python (for Sphinx users) ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ `PocketSphinx-Python `__ is **required if and only if you want to use the Sphinx recognizer** (``recognizer_instance.recognize_sphinx``). -PocketSphinx-Python `wheel packages `__ for 64-bit Python 2.7, 3.4, and 3.5 on Windows are included for convenience, under the ``third-party/`` `directory `__. To install, simply run ``pip install wheel`` followed by ``pip install ./third-party/WHEEL_FILENAME`` (replace ``pip`` with ``pip3`` if using Python 3) in the SpeechRecognition folder. +PocketSphinx-Python `wheel packages `__ for 64-bit Python 2.7, 3.4, and 3.5 on Windows are included for convenience, under the ``third-party/`` `directory `__. To install, simply run ``pip install wheel`` followed by ``pip install ./third-party/WHEEL_FILENAME`` (replace ``pip`` with ``pip3`` if using Python 3) in the SpeechRecognition folder. -On Linux and other POSIX systems (such as OS X), follow the instructions under "Building PocketSphinx-Python from source" in `Notes on using PocketSphinx `__ for installation instructions. +On Linux and other POSIX systems (such as OS X), follow the instructions under "Building PocketSphinx-Python from source" in `Notes on using PocketSphinx `__ for installation instructions. 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 `__ for information about installing languages, compiling PocketSphinx, and building language packs from online resources. This document is also included under ``reference/pocketsphinx.rst``. +See `Notes on using PocketSphinx `__ for information about installing languages, compiling PocketSphinx, and building language packs from online resources. This document is also included under ``reference/pocketsphinx.rst``. Google Cloud Speech Library for Python (for Google Cloud Speech API users) ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -268,12 +263,12 @@ 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 `__. +- 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`` in the project `root directory `__. +To install/reinstall the library locally, run ``python setup.py install`` in the project root directory. Before a release, the version number is bumped in ``README.rst`` and ``speech_recognition/__init__.py``. Version tags are then created using ``git config gpg.program gpg2 && git config user.signingkey DB45F6C431DE7C2DCD99FF7904882258A4063489 && git tag -s VERSION_GOES_HERE -m "Version VERSION_GOES_HERE"``. @@ -368,7 +363,8 @@ Also check out the `Python Baidu Yuyin API `__. The source code for this library is available online at `GitHub `__. +Copyright 2014-2017 `Anthony Zhang (Uberi) `__. +The source code for this library is available online at `GitHub `__. SpeechRecognition is made available under the 3-clause BSD license. See ``LICENSE.txt`` in the project's `root directory `__ for more information.