adding support for STT profanity_filter & documenting keywords and words_alternatives options

Author: nfriedly

README.md

@@ -8,7 +8,8 @@ Allows you to easily add voice recognition and synthesis to any web app with min
 
 **Warning** This library is still has a few rough edges and may yet see breaking changes.
 
-**For Web Browsers Only** This library is primarily intended for use in browsers. 
+###  For Web Browsers Only
+This library is primarily intended for use in browsers. 
 Check out [watson-developer-cloud](https://www.npmjs.com/package/watson-developer-cloud) to use Watson services (speech and others) from Node.js.
 
 However, a server-side component is required to generate auth tokens. 
@@ -17,15 +18,23 @@ The examples/ folder includes example Node.js and Python servers, and SDKs are a
 [Python](https://github.com/watson-developer-cloud/python-sdk/blob/master/examples/authorization_v1.py), 
 and there is also a [REST API](http://www.ibm.com/smarterplanet/us/en/ibmwatson/developercloud/doc/getting_started/gs-tokens.shtml).
 
+### Examples
 See several examples at https://github.com/watson-developer-cloud/speech-javascript-sdk/tree/master/examples
 
-This library is built with [browserify](http://browserify.org/) and easy to use in browserify-based projects (`npm install --save watson-speech`), but you can also grab the compiled bundle from the 
-`dist/` folder and use it as a standalone library.
+### Installation - npm
 
-Basic API
+This library is built with [browserify](http://browserify.org/) and easy to use in browserify-based projects :
+
+    npm install --save watson-speech
+
+### Installation - standalone
+
+Pre-compiled bundles are also available from on GitHub Releases: https://github.com/watson-developer-cloud/speech-javascript-sdk/releases
+
+API
 ---------
 
-Complete API docs should be published at http://watson-developer-cloud.github.io/speech-javascript-sdk/
+The basic API is outlined here, see complete API docs at http://watson-developer-cloud.github.io/speech-javascript-sdk/
 
 All API methods require an auth token that must be [generated server-side](https://github.com/watson-developer-cloud/node-sdk#authorization). 
 (Snp teee examples/token-server.js for a basic example.)
@@ -43,11 +52,6 @@ Options:
 * voice - the desired playback voice's name - see .getVoices(). Note that the voices are language-specific.
 * autoPlay - set to false to prevent the audio from automatically playing
 
-### `.getVoices()` -> Promise
-
-Returns a promise that resolves to an array of objects containing the name, language, gender, and other details for each voice.
-
-Requires[window.fetch](https://developer.mozilla.org/en-US/docs/Web/API/Fetch_API), a [pollyfill](https://www.npmjs.com/package/whatwg-fetch) for IE/Edge and older Chrome/Firefox.
 
 ## `WatsonSpeech.SpeechToText` 
 
@@ -140,6 +144,7 @@ Accepts input from `RecognizeStream()` and friends, writes text to supplied `out
 * Removed `SpeechToText.recognizeElement()` due to quality issues
 * Added `options.element` to TextToSpeech.synthesize() to support playing through exiting elements
 * Fixed a couple of bugs in the TimingStream
+* Added support for STT profanity_filter &  documented keywords and words_alternatives options.
 
 ### v0.14
 * Moved getUserMedia shim to a [standalone library](https://www.npmjs.com/package/get-user-media-promise)

speech-to-text/recognize-stream.js

@@ -26,7 +26,7 @@ var defaults = require('defaults');
 var qs = require('../util/querystring.js');
 
 var OPENING_MESSAGE_PARAMS_ALLOWED = ['continuous', 'max_alternatives', 'timestamps', 'word_confidence', 'inactivity_timeout',
-  'content-type', 'interim_results', 'keywords', 'keywords_threshold', 'word_alternatives_threshold'];
+  'content-type', 'interim_results', 'keywords', 'keywords_threshold', 'word_alternatives_threshold', 'profanity_filter'];
 
 var QUERY_PARAMS_ALLOWED = ['model', 'watson-token']; // , 'X-Watson-Learning-Opt-Out' - should be allowed but currently isn't due to a service bug
 
@@ -38,7 +38,9 @@ var QUERY_PARAMS_ALLOWED = ['model', 'watson-token']; // , 'X-Watson-Learning-Op
  *
  * By default, only finalized text is emitted in the data events, however in `readableObjectMode` (usually just `objectMode` when using a helper method).
  *
- *  An interim result looks like this (assuming all features are enabled):
+ * Todo: add keywords, word_alternatives to examples
+ *
+ *  An interim result looks like this:
  ```js
  { alternatives:
    [ { timestamps:
@@ -62,7 +64,7 @@ var QUERY_PARAMS_ALLOWED = ['model', 'watson-token']; // , 'X-Watson-Learning-Op
   result_index: 3 }
  ```
 
- While a final result looks like this (again, assuming all features are enabled):
+ While a final result looks like this (some features only appear in final results):
  ```js
   { alternatives:
      [ { word_confidence:
@@ -104,9 +106,7 @@ var QUERY_PARAMS_ALLOWED = ['model', 'watson-token']; // , 'X-Watson-Learning-Op
     final: true,
     result_index: 3 }
  ```
-
-
-
+ 
  *
  * @param {Object} options
  * @param {String} [options.model='en-US_BroadbandModel'] - voice model to use. Microphone streaming only supports broadband models.
@@ -117,9 +117,13 @@ var QUERY_PARAMS_ALLOWED = ['model', 'watson-token']; // , 'X-Watson-Learning-Op
  * @param {Boolean} [options.word_confidence=false] - include confidence scores with results. Defaults to true when in objectMode.
  * @param {Boolean} [options.timestamps=false] - include timestamps with results. Defaults to true when in objectMode.
  * @param {Number} [options.max_alternatives=1] - maximum number of alternative transcriptions to include. Defaults to 3 when in objectMode.
+ * @param {Array<String>} [options.keywords] - a list of keywords to search for in the audio
+ * @param {Number} [options.keywords_threshold] - Number between 0 and 1 representing the minimum confidence before including a keyword in the results. Required when options.keywords is set
+ * @param {Number} [options.word_alternatives_threshold] - Number between 0 and 1 representing the minimum confidence before including an alternative word in the results. Must be set to enable word alternatives,
+ * @param {Boolean} [options.profanity_filter=false] - set to true to filter out profanity and replace the words with *'s
  * @param {Number} [options.inactivity_timeout=30] - how many seconds of silence before automatically closing the stream (even if continuous is true). use -1 for infinity
  * @param {Boolean} [options.readableObjectMode=false] - emit `result` objects instead of string Buffers for the `data` events. Changes several other defaults.
- * @param {Number} [options.X-WDC-PL-OPT-OUT=0] set to 1 to opt-out of allowing Watson to use this request to improve it's services
+ * @param {Number} [options.X-WDC-PL-OPT-OUT=0] - set to 1 to opt-out of allowing Watson to use this request to improve it's services
  *
  * //todo: investigate other options at http://www.ibm.com/smarterplanet/us/en/ibmwatson/developercloud/apis/#!/speech-to-text/recognizeSessionless
  *