experiments/STT
1
0
Fork 0
Code Issues Pull Requests Projects Releases Wiki Activity

Merge pull request #1908 from mozilla/nc-readme

Browse Source 
Cleaning up the native_client README
This commit is contained in:
Josh Meyer 2019-03-20 03:26:34 +06:00 committed by GitHub
commit 7d2bd422dd
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
1 changed files with 62 additions and 47 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

109
native_client/README.md
View File

@ -1,23 +1,12 @@
# DeepSpeech native client, language bindings and custom decoder
# DeepSpeech native client, language bindings, and custom decoder
This folder contains a native client for running queries on an exported DeepSpeech model, bindings for Python and Node.JS for using an exported DeepSpeech model programatically, and a CTC beam search decoder implementation that scores beams using a language model, needed for training a DeepSpeech model. We provide pre-built binaries for Linux and macOS.
This folder contains the following:
## Installation
1. A native client for running queries on an exported DeepSpeech model
2. Python and Node.JS bindings for using an exported DeepSpeech model programatically
3. A CTC beam search decoder which uses a language model (N.B - the decoder is also required for training DeepSpeech)
To download the pre-built binaries, use `util/taskcluster.py`:
```
python util/taskcluster.py --target /path/to/destination/folder
```
If you need some binaries different than current master, like `v0.2.0-alpha.6`, you can use `--branch`:
```bash
python3 util/taskcluster.py --branch "v0.2.0-alpha.6"
```
This will download and extract `native_client.tar.xz` which includes the deepspeech binary and associated libraries as well as the custom decoder OP. `taskcluster.py` will download binaries for the architecture of the host by default, but you can override that behavior with the `--arch` parameter. See the help info with `python util/taskcluster.py -h` for more details.
If you want the CUDA capable version of the binaries, use `--arch gpu`. Note that for now we don't publish CUDA-capable macOS binaries.
We provide pre-built binaries for Linux and macOS.
## Required Dependencies
@ -29,7 +18,28 @@ Running inference might require some runtime dependencies to be already installe
Please refer to your system's documentation on how to install those dependencies.
## Installing the language bindings
## Installing our Pre-built Binaries
To download the pre-built binaries, use `util/taskcluster.py`:
```
python util/taskcluster.py --target /path/to/destination/folder
```
If you need binaries which are different than current master (e.g. `v0.2.0-alpha.6`) you can use the `--branch` flag:
```bash
python3 util/taskcluster.py --branch "v0.2.0-alpha.6"
```
`util/taskcluster.py` will download and extract `native_client.tar.xz`. `native_client.tar.xz` includes (1) the `deepspeech` binary and (2) associated libraries. `taskcluster.py` will download binaries for the architecture of the host by default, but you can override that behavior with the `--arch` parameter. See `python util/taskcluster.py -h` for more details.
If you want the CUDA capable version of the binaries, use `--arch gpu`. Note that for now we don't publish CUDA-capable macOS binaries.
## Installing our Pre-built language bindings
### Python bindings
For the Python bindings, you can use `pip`:
@ -45,9 +55,10 @@ For Node.JS bindings, use `npm install deepspeech` to install it. Please note th
Check the [main README](../README.md) for more details.
## Build Requirements
If you'd like to build the binaries yourself, you'll need the following pre-requisites downloaded/installed:
## Building & Installing your own Binaries
If you'd like to build the binaries yourself, you'll need the following pre-requisites downloaded and installed:
* [TensorFlow requirements](https://www.tensorflow.org/install/install_sources)
* [TensorFlow `r1.12` sources](https://github.com/mozilla/tensorflow/tree/r1.12)
@ -60,20 +71,18 @@ If you'd like to build the language bindings or the decoder package, you'll also
* [SWIG](http://www.swig.org/)
* [node-pre-gyp](https://github.com/mapbox/node-pre-gyp) (for Node.JS bindings only)
## Preparation
Create a symbolic link in your TensorFlow checkout to the DeepSpeech `native_client` directory. If your DeepSpeech and TensorFlow checkouts are side by side in the same directory, do:
### Building your own Binaries
Firstly, you should create a symbolic link in your TensorFlow checkout to the DeepSpeech `native_client` directory. If your DeepSpeech and TensorFlow checkouts are side by side in the same directory, do:
```
cd tensorflow
ln -s ../DeepSpeech/native_client ./
```
## Building
Before building the DeepSpeech client libraries, you will need to prepare your environment to configure and build TensorFlow.
Preferably, checkout the version of tensorflow which is currently supported by DeepSpeech (see requirements.txt), and use the bazel version recommended by TensorFlow for that version.
Then, follow the [instructions](https://www.tensorflow.org/install/install_sources) on the TensorFlow site for your platform, up to the end of 'Configure the installation'.
Next, you will need to prepare your environment to configure and build TensorFlow. Clone from `https://github.com/mozilla/tensorflow`, and then (preferably) checkout the version of `tensorflow` which is currently supported by DeepSpeech (see requirements.txt), and use the `bazel` version recommended by TensorFlow for that version. Follow the [instructions](https://www.tensorflow.org/install/install_sources) on the TensorFlow site for your platform, up to the end of ["Configure the Build"](https://www.tensorflow.org/install/source#configure_the_build).
After that, you can build the Tensorflow and DeepSpeech libraries using the following command.
@ -81,7 +90,7 @@ After that, you can build the Tensorflow and DeepSpeech libraries using the foll
bazel build --config=monolithic -c opt --copt=-O3 --copt="-D_GLIBCXX_USE_CXX11_ABI=0" --copt=-fvisibility=hidden //native_client:libdeepspeech.so //native_client:generate_trie
```
If your build target requires extra flags, add them, like, for example --config=cuda if you do a CUDA build. Note that the generated binaries will show up under `bazel-bin/native_client/` (e.g., including `generate_trie` in case the `//native_client:generate_trie` option was present).
If your build target requires extra flags, add them. For example `--config=cuda` if you want a CUDA build. Note that the generated binaries will show up under `bazel-bin/native_client/` (e.g., including `generate_trie` in case the `//native_client:generate_trie` option was present).
Finally, you can change to the `native_client` directory and use the `Makefile`. By default, the `Makefile` will assume there is a TensorFlow checkout in a directory above the DeepSpeech checkout. If that is not the case, set the environment variable `TFDIR` to point to the right directory.
@ -90,26 +99,29 @@ cd ../DeepSpeech/native_client
make deepspeech
```
### Cross-building for RPi3 ARMv7 / LePotato ARM64
### Cross-building for RPi3 ARMv7 and LePotato ARM64
We do support cross-compilation. Please refer to our `mozilla/tensorflow` fork, where we define the following `--config` flags:
We do support cross-compilation ; please refer to our `mozilla/tensorflow` fork, where we define the following `--config` flags:
- `--config=rpi3` and `--config=rpi3_opt` for Raspbian / ARMv7
- `--config=rpi3-armv8` and `--config=rpi3-armv8_opt` for ARMBian / ARM64
So your command line for RPi3 / ARMv7 should look like:
So your command line for `RPi3` and `ARMv7` should look like:
```
bazel build --config=monolithic --config=rpi3 --config=rpi3_opt -c opt --copt=-O3 --copt=-fvisibility=hidden //native_client:libdeepspeech.so //native_client:generate_trie
```
And your command line for LePotato / ARM64 should look like:
And your command line for `LePotato` and `ARM64` should look like:
```
bazel build --config=monolithic --config=rpi3-armv8 --config=rpi3-armv8_opt -c opt --copt=-O3 --copt=-fvisibility=hidden //native_client:libdeepspeech.so //native_client:generate_trie
```
While we test only on RPi3 Raspbian Stretch / LePotato ARMBian stretch, anything compatible with `armv7-a cortex-a53` / `armv8-a cortex-a53` should be fine.
While we test only on RPi3 Raspbian Stretch and LePotato ARMBian stretch, anything compatible with `armv7-a cortex-a53` or `armv8-a cortex-a53` should be fine.
The `deepspeech` binary can also be cross-built, with `TARGET=rpi3` or `TARGET=rpi3-armv8`. This might require you to setup a system tree using the tool `multistrap` and the multitrap configuration files: `native_client/multistrap_armbian64_stretch.conf` and `native_client/multistrap_raspbian_stretch.conf`.
The path of the system tree can be overridden from the default values defined in `definitions.mk` through `RASPBIAN` make variable.
The path of the system tree can be overridden from the default values defined in `definitions.mk` through the `RASPBIAN` `make` variable.
```
cd ../DeepSpeech/native_client
@ -118,7 +130,7 @@ make TARGET=<system> deepspeech
### Android devices
We have preliminary support for Android relying on TensorFlow Lite, with Java / JNI bindinds. For more details on how to experiment with those, please refer to `native_client/java/README.md`.
We have preliminary support for Android relying on TensorFlow Lite, with Java and JNI bindinds. For more details on how to experiment with those, please refer to `native_client/java/README.md`.
Please refer to TensorFlow documentation on how to setup the environment to build for Android (SDK and NDK required).
@ -129,6 +141,7 @@ bazel build --config=monolithic --config=android --config=android_arm --define=r
```
Or (ARM64):
```
bazel build --config=monolithic --config=android --config=android_arm64 --define=runtime=tflite --action_env ANDROID_NDK_API_LEVEL=21 --cxxopt=-std=c++11 --copt=-D_GLIBCXX_USE_C99 //native_client:libdeepspeech.so
```
@ -141,12 +154,13 @@ $ANDROID_NDK_HOME/ndk-build APP_PLATFORM=android-21 APP_BUILD_SCRIPT=$(pwd)/Andr
```
And (ARM64):
```
cd ../DeepSpeech/native_client
$ANDROID_NDK_HOME/ndk-build APP_PLATFORM=android-21 APP_BUILD_SCRIPT=$(pwd)/Android.mk NDK_PROJECT_PATH=$(pwd) APP_STL=c++_shared TFDIR=$(pwd)/../../tensorflowx/ TARGET_ARCH_ABI=arm64-v8a
```
## Installing
### Installing your own Binaries
After building, the library files and binary can optionally be installed to a system path for ease of development. This is also a required step for bindings generation.
@ -156,15 +170,7 @@ PREFIX=/usr/local sudo make install
It is assumed that `$PREFIX/lib` is a valid library path, otherwise you may need to alter your environment.
## Running
The client can be run via the `Makefile`. The client will accept audio of any format your installation of SoX supports.
```
ARGS="--model /path/to/output_graph.pbmm --alphabet /path/to/alphabet.txt --audio /path/to/audio/file.wav" make run
```
## Python bindings
#### Python bindings
Included are a set of generated Python bindings. After following the above build and installation instructions, these can be installed by executing the following commands (or equivalent on your system):
@ -176,7 +182,7 @@ pip install dist/deepspeech*
The API mirrors the C++ API and is demonstrated in [client.py](python/client.py). Refer to [deepspeech.h](deepspeech.h) for documentation.
## Node.JS bindings
#### Node.JS bindings
After following the above build and installation instructions, the Node.JS bindings can be built:
@ -188,7 +194,7 @@ make npm-pack
This will create the package `deepspeech-VERSION.tgz` in `native_client/javascript`.
## Building the CTC decoder package
#### Building the CTC decoder package
To build the `ds_ctcdecoder` package, you'll need the general requirements listed above (in particular SWIG). The command below builds the bindings using 8 processes for compilation. Adjust the parameter accordingly for more or less parallelism.
@ -197,3 +203,12 @@ cd native_client/ctcdecode
make bindings NUM_PROCESSES=8
pip install dist/*.whl
```
## Running
The client can be run via the `Makefile`. The client will accept audio of any format your installation of SoX supports.
```
ARGS="--model /path/to/output_graph.pbmm --alphabet /path/to/alphabet.txt --audio /path/to/audio/file.wav" make run
```