docs: add an example and a test for tts over websocket

Author: dpopp07

README.md

@@ -602,7 +602,7 @@ fs.createReadStream('./resources/speech.wav')
 
 ### Text to Speech
 
-Use the [Text to Speech][text_to_speech] service to synthesize text into a .wav file.
+Use the [Text to Speech][text_to_speech] service to synthesize text into an audio file.
 
 ```js
 var TextToSpeechV1 = require('watson-developer-cloud/text-to-speech/v1');
@@ -632,8 +632,16 @@ textToSpeech
     fs.writeFileSync('audio.wav', audio);
     console.log('audio.wav written with a corrected wav header');
 });
+
+
+// or, using WebSockets
+textToSpeech.synthesizeUsingWebSocket(params);
+synthStream.pipe(fs.createWriteStream('./audio.ogg'));
+// see more information in examples/text_to_speech_websocket.js
 ```
 
+
+
 ### Tone Analyzer
 
 Use the [Tone Analyzer][tone_analyzer] service to analyze the

examples/.eslintrc.js

@@ -1,5 +1,5 @@
 module.exports = {
-  "parserOptions": { "ecmaVersion": 5 },
+  "parserOptions": { "ecmaVersion": 6 },
   "rules": {
     "no-console": "off",
     "node/no-missing-require": "off",

examples/text_to_speech_websocket.js

@@ -0,0 +1,51 @@
+'use strict';
+
+const fs = require('fs');
+const TextToSpeechV1 = require('watson-developer-cloud/text-to-speech/v1');
+
+const textToSpeech = new TextToSpeechV1({
+  // if left unspecified here, the SDK will fall back to the TEXT_TO_SPEECH_USERNAME and TEXT_TO_SPEECH_PASSWORD
+  // environment properties, and then IBM Cloud's VCAP_SERVICES environment property
+  // username: 'INSERT YOUR USERNAME FOR THE SERVICE HERE',
+  // password: 'INSERT YOUR PASSWORD FOR THE SERVICE HERE'
+});
+
+// specify the text to synthesize
+const params = {
+  text: 'Hello, world.',
+  accept: 'audio/ogg;codecs=opus',
+};
+
+// synthesizeUsingWebSocket returns a Readable Stream that can be piped or listened to
+const synthesizeStream = textToSpeech.synthesizeUsingWebSocket(params);
+
+// the output of the stream can be piped to any writable stream, like an audio file
+synthesizeStream.pipe(fs.createWriteStream('./speech.ogg'));
+
+// if the stream is not being piped anywhere and is only being listened to, the stream needs
+//   to be explicitly set to flowing mode:
+
+// synthesizeStream.resume();
+
+// the 'message' event is emitted when data is processed and returned from the service
+// the 'message' parameter is the entire response frame of information returned from the
+//   service. it is mainly useful for debugging
+// the 'data' parameter is the data payload contained within the message. it is typically
+//   binary audio data, but if the text includes SSML marks or the request includes the
+//   'timings' parameter, 'data' could be a string containing marks or timing information
+synthesizeStream.on('message', (message, data) => {
+  console.log(data);
+});
+
+// the 'error' event is emitted if there is an error during the connection
+// 'err' is the Error object describing the error
+synthesizeStream.on('error', err => {
+  console.log(err);
+});
+
+// the 'close' event is emitted once, when the connection is terminated by the service
+// the 'code' parameter is the status code. 1000 is the code for a normal termination
+// the 'reason' parameter provides a string description of how the connection closed
+synthesizeStream.on('close', (code, reason) => {
+  console.log(code);
+});

test/integration/text_to_speech.test.js

@@ -16,17 +16,39 @@ describe('text_to_speech_integration', function() {
     text_to_speech.voices(null, done);
   });
 
-  it('synthesize()', function(done) {
+  describe('synthesize', function() {
     const params = {
       text: 'test',
       accept: 'audio/wav',
     };
-    // wav.Reader parses the wav header and will throw if it isn't valid
-    const reader = new wav.Reader();
-    text_to_speech
-      .synthesize(params)
-      .pipe(reader)
-      .on('format', done.bind(null, null));
+
+    it('synthesize using http', function(done) {
+      // wav.Reader parses the wav header and will throw if it isn't valid
+      const reader = new wav.Reader();
+      text_to_speech
+        .synthesize(params)
+        .pipe(reader)
+        .on('format', done.bind(null, null));
+    });
+
+    it('synthesize using websocket', function(done) {
+      const synthStream = text_to_speech.synthesizeUsingWebSocket(params);
+      synthStream.resume();
+
+      synthStream.on('message', function(message, data) {
+        expect(data).not.toBeNull();
+      });
+
+      synthStream.on('error', function(err) {
+        // fail assertation
+        throw err;
+      });
+
+      synthStream.on('close', function(code, reason) {
+        expect(code).toBe(1000);
+        done();
+      });
+    });
   });
 
   it('pronunciation()', function(done) {