lighter default options and example of output

Author: nfriedly

speech-to-text/recognize-stream.js

@@ -32,12 +32,86 @@ var QUERY_PARAMS_ALLOWED = ['model', 'watson-token']; //, 'X-Watson-Learning-Opt
 
 
 /**
- * pipe()-able Node.js Readable/Writeable stream - accepts binary audio and emits text in it's `data` events.
- * Also emits `results` events with interim results and other data.
+ * pipe()-able Node.js Readable/Writeable stream - accepts binary audio and emits text/objects in it's `data` events.
  *
  * Cannot be instantiated directly, instead reated by calling #createRecognizeStream()
  *
  * Uses WebSockets under the hood. For audio with no recognizable speech, no `data` events are emitted.
+ *
+ * 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):
+ ```js
+ { results:
+    [ { alternatives:
+         [ { timestamps:
+              [ [ 'it', 20.9, 21.04 ],
+                [ 'is', 21.04, 21.17 ],
+                [ 'a', 21.17, 21.25 ],
+                [ 'site', 21.25, 21.56 ],
+                [ 'that', 21.56, 21.7 ],
+                [ 'hardly', 21.7, 22.06 ],
+                [ 'anyone', 22.06, 22.49 ],
+                [ 'can', 22.49, 22.67 ],
+                [ 'behold', 22.67, 23.13 ],
+                [ 'without', 23.13, 23.46 ],
+                [ 'some', 23.46, 23.67 ],
+                [ 'sort', 23.67, 23.91 ],
+                [ 'of', 23.91, 24 ],
+                [ 'unwanted', 24, 24.58 ],
+                [ 'emotion', 24.58, 25.1 ] ],
+             transcript: 'it is a site that hardly anyone can behold without some sort of unwanted emotion ' } ],
+        final: false } ],
+   result_index: 3 }
+ ```
+
+ While a final result looks like this (again, assuming all features are enabled):
+ ```js
+ { results:
+    [ { alternatives:
+         [ { word_confidence:
+              [ [ 'it', 1 ],
+                [ 'is', 0.956286624429304 ],
+                [ 'a', 0.8105753725270362 ],
+                [ 'site', 1 ],
+                [ 'that', 1 ],
+                [ 'hardly', 1 ],
+                [ 'anyone', 1 ],
+                [ 'can', 1 ],
+                [ 'behold', 0.5273598005406737 ],
+                [ 'without', 1 ],
+                [ 'some', 1 ],
+                [ 'sort', 1 ],
+                [ 'of', 1 ],
+                [ 'unwanted', 1 ],
+                [ 'emotion', 0.49401837076320887 ] ],
+             confidence: 0.881,
+             transcript: 'it is a site that hardly anyone can behold without some sort of unwanted emotion ',
+             timestamps:
+              [ [ 'it', 20.9, 21.04 ],
+                [ 'is', 21.04, 21.17 ],
+                [ 'a', 21.17, 21.25 ],
+                [ 'site', 21.25, 21.56 ],
+                [ 'that', 21.56, 21.7 ],
+                [ 'hardly', 21.7, 22.06 ],
+                [ 'anyone', 22.06, 22.49 ],
+                [ 'can', 22.49, 22.67 ],
+                [ 'behold', 22.67, 23.13 ],
+                [ 'without', 23.13, 23.46 ],
+                [ 'some', 23.46, 23.67 ],
+                [ 'sort', 23.67, 23.91 ],
+                [ 'of', 23.91, 24 ],
+                [ 'unwanted', 24, 24.58 ],
+                [ 'emotion', 24.58, 25.1 ] ] },
+           { transcript: 'it is a sight that hardly anyone can behold without some sort of unwanted emotion ' },
+           { transcript: 'it is a site that hardly anyone can behold without some sort of unwanted emotions ' } ],
+        final: true } ],
+   result_index: 3 }
+ ```
+
+
+
+ *
  * @param options
  * @param {String} [options.model='en-US_BroadbandModel'] - voice model to use. Microphone streaming only supports broadband models.
  * @param {String} [options.url='wss://stream.watsonplatform.net/speech-to-text/api'] base URL for service
@@ -120,9 +194,9 @@ RecognizeStream.prototype.initialize = function () {
     continuous: true,
     inactivity_timeout: 30,
     interim_results: true,
-    word_confidence: true,
-    timestamps: true,
-    max_alternatives: 3
+    word_confidence: false,
+    timestamps: false,
+    max_alternatives: 1
   };
 
   var openingMessage = defaults(