Merge pull request #3524 from Ideefixze/master

Added hot-word boosting doc

doc/HotWordBoosting-Examples.rst

@@ -0,0 +1,56 @@
+Hot-word boosting API Usage example
+===================================
+
+With DeepSpeech 0.9 release a new API feature was introduced that allows boosting probability from the scorer of given words. It is exposed in all bindings (C, Python, JS, Java and .Net). 
+
+Currently, it provides three methods for the Model class:
+
+- ``AddHotWord(word, boost)``
+- ``EraseHotWord(word)`` 
+- ``ClearHotWords()``
+
+Exact API binding for the language you are using can be found in API Reference.
+
+General usage
+-------------
+
+It is worth noting that boosting non-existent words in scorer (mostly proper nouns) or a word that share no phonetic prefix with other word in the input audio don't change the final transcription. Additionally, hot-word that has a space will not be taken into consideration, meaning that combination of words can not be boosted and each word must be added as hot-word separately. 
+
+Adjusting the boosting value
+----------------------------
+
+For hot-word boosting it is hard to determine what the optimal value that one might be searching for is. Additionally, this is dependant on the input audio file. In practice, as it was reported by DeepSpeech users, the value should be not bigger than 20.0 for positive value boosting. Nevertheless, each usecase is different and you might need to adjust values on your own.
+
+There is a user contributed script available on ``DeepSpeech-examples`` repository for adjusting boost values:
+
+`https://github.com/mozilla/DeepSpeech-examples/tree/master/hotword_adjusting <https://github.com/mozilla/DeepSpeech-examples/tree/master/hotword_adjusting>`_.
+
+
+Positive value boosting
+-----------------------
+
+By adding a positive boost value to one of the words it is possible to increase the probability of the word occurence. This is particularly useful for detecting speech that is expected by the system. 
+
+In the output, overextensive positive boost value (e.g. 250.0 but it does vary) may cause a word following the boosted hot-word to be split into separate letters. This problem is related to the scorer structure and currently only way to avoid it is to tune boost to a lower value.  
+
+Negative value boosting
+-----------------------
+
+Respectively, applying negative boost value might cause the selected word to occur less frequently. Keep in mind that words forming similar sound of a boosted word might be used instead (e.g. homophones "accept" as "except") or it will be split into separate parts (e.g. "another" into "an other").
+
+Previously mentioned problem where extensive boost value caused letter splitting doesn't arise for negative boost values.
+
+Example 
+-------
+
+To use hot-word boosting just add hot-words of your choice before performing an inference to a ``Model``. You can also erase boosting of a chosen word or clear it for all hot-words.
+
+.. code-block:: python
+
+	ds = Model(args.model)
+	...
+	ds.addHotWord(word, boosting)
+	...
+	print(ds.stt(audio))
+	
+Adding boost value to a word repeatedly or erasing hot-word without previously boosting it results in an error.

doc/index.rst

@@ -111,6 +111,8 @@ See the output of ``deepspeech -h`` for more information on the use of ``deepspe
    NodeJS-Examples
 
    Python-Examples
+   
+   HotWordBoosting-Examples
 
    Contributed-Examples
 

native_client/deepspeech.h

@@ -163,9 +163,11 @@ int DS_EnableExternalScorer(ModelState* aCtx,
 /**
  * @brief Add a hot-word and its boost.
  *
+ * Words that don't occur in the scorer (e.g. proper nouns) or strings that contain spaces won't be taken into account.
+ *
  * @param aCtx The ModelState pointer for the model being changed.
  * @param word The hot-word.
- * @param boost The boost.
+ * @param boost The boost. Positive value increases and negative reduces chance of a word occuring in a transcription. Excessive positive boost might lead to splitting up of letters of the word following the hot-word.
  *
  * @return Zero on success, non-zero on failure (invalid arguments).
  */

native_client/dotnet/DeepSpeechClient/DeepSpeech.cs

@@ -76,9 +76,11 @@ namespace DeepSpeechClient
 
         /// <summary>
         /// Add a hot-word.
+        /// 
+        /// Words that don't occur in the scorer (e.g. proper nouns) or strings that contain spaces won't be taken into account.
         /// </summary>
         /// <param name="aWord">Some word</param>
-        /// <param name="aBoost">Some boost</param>
+        /// <param name="aBoost">Some boost. Positive value increases and negative reduces chance of a word occuring in a transcription. Excessive positive boost might lead to splitting up of letters of the word following the hot-word.</param>
         /// <exception cref="ArgumentException">Thrown on failure.</exception>
         public unsafe void AddHotWord(string aWord, float aBoost)
         {

native_client/java/libdeepspeech/src/main/java/org/deepspeech/libdeepspeech/DeepSpeechModel.java

@@ -216,10 +216,12 @@ public class DeepSpeechModel {
         return impl.FinishStreamWithMetadata(ctx.get(), num_results);
     }
     /**
-     * @brief Add a hot-word
+     * @brief Add a hot-word.
+     *
+     * Words that don't occur in the scorer (e.g. proper nouns) or strings that contain spaces won't be taken into account.
      *
      * @param word
-     * @param boost
+     * @param boost Positive value increases and negative reduces chance of a word occuring in a transcription. Excessive positive boost might lead to splitting up of letters of the word following the hot-word.
      *
      * @throws RuntimeException on failure.
      *
@@ -228,7 +230,7 @@ public class DeepSpeechModel {
         evaluateErrorCode(impl.AddHotWord(this._msp, word, boost));
     }
     /**
-     * @brief Erase a hot-word
+     * @brief Erase a hot-word.
      *
      * @param word
      *

native_client/javascript/index.ts

@@ -189,10 +189,12 @@ export class Model {
     }
 
     /**
-     * Add a hot-word and its boost
+     * Add a hot-word and its boost.
+     *
+     * Words that don't occur in the scorer (e.g. proper nouns) or strings that contain spaces won't be taken into account.
      *
      * @param aWord word
-     * @param aBoost boost
+     * @param aBoost boost Positive value increases and negative reduces chance of a word occuring in a transcription. Excessive positive boost might lead to splitting up of letters of the word following the hot-word.
      *
      * @throws on error
      */

native_client/python/__init__.py

@@ -98,11 +98,13 @@ class Model(object):
     def addHotWord(self, word, boost):
         """
         Add a word and its boost for decoding.
+        
+        Words that don't occur in the scorer (e.g. proper nouns) or strings that contain spaces won't be taken into account.
 
         :param word: the hot-word
         :type word: str
 
-        :param boost: the boost
+        :param boost: Positive boost value increases and negative reduces chance of a word occuring in a transcription. Excessive positive boost might lead to splitting up of letters of the word following the hot-word.
         :type boost: float
 
         :throws: RuntimeError on error