diff --git a/.gitignore b/.gitignore index f58cef7f..6a22ba05 100644 --- a/.gitignore +++ b/.gitignore @@ -16,3 +16,4 @@ dist/*.js dist/*.map gh-pages/ .idea +watson-speech-*.tgz diff --git a/.npmignore b/.npmignore index 17bcada1..1fa9418c 100644 --- a/.npmignore +++ b/.npmignore @@ -8,3 +8,12 @@ gh-pages/ scripts/ docs/ .env +.github/ +CHANGELOG.md +bower.json +karma.conf.js +speech-to-text +text-to-speech +util +webpack.config.js +watson-speech-*.tgz diff --git a/README.md b/README.md index 1eeed363..1c2cc057 100644 --- a/README.md +++ b/README.md @@ -1,5 +1,4 @@ -IBM Watson Speech Services for Web Browsers -=========================================== +# IBM Watson Speech Services for Web Browsers [![Build Status](https://travis-ci.org/watson-developer-cloud/speech-javascript-sdk.svg?branch=master)](https://travis-ci.org/watson-developer-cloud/speech-javascript-sdk) [![npm-version](https://img.shields.io/npm/v/watson-speech.svg)](https://www.npmjs.com/package/watson-speech) @@ -7,11 +6,11 @@ IBM Watson Speech Services for Web Browsers Allows you to easily add voice recognition and synthesis to any web app with minimal code. ### Built for Browsers + This library is primarily intended for use in web 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**. The `examples/` folder includes example Node.js and Python servers, and SDKs are available for [Node.js](https://github.com/watson-developer-cloud/node-sdk#authorization), [Java](https://github.com/watson-developer-cloud/java-sdk), [Python](https://github.com/watson-developer-cloud/python-sdk/blob/master/examples/authorization_v1.py), and there is also a [REST API](https://cloud.ibm.com/docs/services/watson?topic=watson-gs-tokens-watson-tokens). - ### Installation - standalone Pre-compiled bundles are available from on GitHub Releases - just download the file and drop it into your website: https://github.com/watson-developer-cloud/speech-javascript-sdk/releases @@ -61,19 +60,23 @@ See [CHANGELOG.md](CHANGELOG.md) for a complete list of changes. ## Development ### Use examples for development + The provided examples can be used to test developmental code in action: -* `cd examples/` -* `npm run dev` + +- `cd examples/` +- `npm run dev` This will build the local code, move the new bundle into the `examples/` directory, and start a new server at `localhost:3000` where the examples will be running. Note: This requires valid service credentials. ### Testing + The test suite is broken up into offline unit tests and integration tests that test against actual service instances. -* `npm test` will run the linter and the offline tests -* `npm run test-offline` will run the offline tests -* `npm run test-integration` will run the integration tests + +- `npm test` will run the linter and the offline tests +- `npm run test-offline` will run the offline tests +- `npm run test-integration` will run the integration tests To run the integration tests, a file with service credentials is required. This file must be called `stt-auth.json` and must be located in `/test/resources/`. There are tests for usage of both CF and RC service instances. For testing CF, the required keys in this configuration file are `username` and `password`. For testing RC, a key of either `iam_acess_token` or `iam_apikey` is required. Optionally, a service URL for an RC instance can be provided under the key `rc_service_url` if the service is available under a URL other than `https://stream.watsonplatform.net/speech-to-text/api`. diff --git a/docs/README.md b/docs/README.md index 837a4de8..d1328bbe 100644 --- a/docs/README.md +++ b/docs/README.md @@ -1,5 +1,4 @@ -API & Examples --------------- +## API & Examples The basic API is outlined below, see complete API docs at http://watson-developer-cloud.github.io/speech-javascript-sdk/master/ @@ -7,7 +6,7 @@ See several basic examples at http://watson-speech.mybluemix.net/ ([source](http See a more advanced example at https://speech-to-text-demo.mybluemix.net/ -All API methods require an auth token that must be [generated server-side](https://github.com/watson-developer-cloud/node-sdk#authorization). +All API methods require an auth token that must be [generated server-side](https://github.com/watson-developer-cloud/node-sdk#authorization). (See https://github.com/watson-developer-cloud/speech-javascript-sdk/tree/master/examples/ for a couple of basic examples in Node.js and Python.) -_NOTE_: The `token` parameter only works for CF instances of services. For RC services using IAM for authentication, the `access_token` parameter must be used. +_NOTE_: The `token` parameter only works for CF instances of services. For RC services using IAM for authentication, the `accessToken` parameter must be used. diff --git a/docs/SPEECH-TO-TEXT.md b/docs/SPEECH-TO-TEXT.md index 55891554..9f46828c 100644 --- a/docs/SPEECH-TO-TEXT.md +++ b/docs/SPEECH-TO-TEXT.md @@ -8,47 +8,47 @@ The core of the library is the [RecognizeStream] that performs the actual transc _NOTE_ The RecognizeStream class lives in the Watson Node SDK. Any option available on this class can be passed into the following methods. These parameters are documented at http://watson-developer-cloud.github.io/node-sdk/master/classes/recognizestream.html -### [`.recognizeMicrophone({token||access_token})`](http://watson-developer-cloud.github.io/speech-javascript-sdk/master/module-watson-speech_speech-to-text_recognize-microphone.html) -> Stream +### [`.recognizeMicrophone({token||accessToken})`](http://watson-developer-cloud.github.io/speech-javascript-sdk/master/module-watson-speech_speech-to-text_recognize-microphone.html) -> Stream -Options: -* `keepMicrophone`: if true, preserves the MicrophoneStream for subsequent calls, preventing additional permissions requests in Firefox -* `mediaStream`: Optionally pass in an existing media stream rather than prompting the user for microphone access. -* Other options passed to [RecognizeStream] -* Other options passed to [SpeakerStream] if `options.resultsbySpeaker` is set to true -* Other options passed to [FormatStream] if `options.format` is not set to false -* Other options passed to [WritableElementStream] if `options.outputElement` is set +Options: -Requires the `getUserMedia` API, so limited browser compatibility (see http://caniuse.com/#search=getusermedia) +- `keepMicrophone`: if true, preserves the MicrophoneStream for subsequent calls, preventing additional permissions requests in Firefox +- `mediaStream`: Optionally pass in an existing media stream rather than prompting the user for microphone access. +- Other options passed to [RecognizeStream] +- Other options passed to [SpeakerStream] if `options.resultsbySpeaker` is set to true +- Other options passed to [FormatStream] if `options.format` is not set to false +- Other options passed to [WritableElementStream] if `options.outputElement` is set + +Requires the `getUserMedia` API, so limited browser compatibility (see http://caniuse.com/#search=getusermedia) Also note that Chrome requires https (with a few exceptions for localhost and such) - see https://www.chromium.org/Home/chromium-security/prefer-secure-origins-for-powerful-new-features No more data will be set after `.stop()` is called on the returned stream, but additional results may be recieved for already-sent data. - -### [`.recognizeFile({data, token||access_token})`](http://watson-developer-cloud.github.io/speech-javascript-sdk/master/module-watson-speech_speech-to-text_recognize-file.html) -> Stream +### [`.recognizeFile({data, token||accessToken})`](http://watson-developer-cloud.github.io/speech-javascript-sdk/master/module-watson-speech_speech-to-text_recognize-file.html) -> Stream Can recognize and optionally attempt to play a URL, [File](https://developer.mozilla.org/en-US/docs/Web/API/File) or [Blob](https://developer.mozilla.org/en-US/docs/Web/API/Blob) (such as from an `` or from an ajax request.) -Options: -* `file`: a String URL or a `Blob` or `File` instance. Note that [CORS] restrictions apply to URLs. -* `play`: (optional, default=`false`) Attempt to also play the file locally while uploading it for transcription -* Other options passed to [RecognizeStream] -* Other options passed to [TimingStream] if `options.realtime` is true, or unset and `options.play` is true -* Other options passed to [SpeakerStream] if `options.resultsbySpeaker` is set to true -* Other options passed to [FormatStream] if `options.format` is not set to false -* Other options passed to [WritableElementStream] if `options.outputElement` is set +Options: -`play` requires that the browser support the format; most browsers support wav and ogg/opus, but not flac.) +- `file`: a String URL or a `Blob` or `File` instance. Note that [CORS] restrictions apply to URLs. +- `play`: (optional, default=`false`) Attempt to also play the file locally while uploading it for transcription +- Other options passed to [RecognizeStream] +- Other options passed to [TimingStream] if `options.realtime` is true, or unset and `options.play` is true +- Other options passed to [SpeakerStream] if `options.resultsbySpeaker` is set to true +- Other options passed to [FormatStream] if `options.format` is not set to false +- Other options passed to [WritableElementStream] if `options.outputElement` is set + +`play` requires that the browser support the format; most browsers support wav and ogg/opus, but not flac.) Will emit an `UNSUPPORTED_FORMAT` error on the RecognizeStream if playback fails. This error is special in that it does not stop the streaming of results. -Playback will automatically stop when `.stop()` is called on the returned stream. +Playback will automatically stop when `.stop()` is called on the returned stream. For Mobile Safari compatibility, a URL must be provided, and `recognizeFile()` must be called in direct response to a user interaction (so the token must be pre-loaded). -[RecognizeStream]: http://watson-developer-cloud.github.io/node-sdk/master/classes/recognizestream.html -[TimingStream]: http://watson-developer-cloud.github.io/speech-javascript-sdk/master/TimingStream.html -[FormatStream]: http://watson-developer-cloud.github.io/speech-javascript-sdk/master/FormatStream.html -[WritableElementStream]: http://watson-developer-cloud.github.io/speech-javascript-sdk/master/WritableElementStream.html -[SpeakerStream]: http://watson-developer-cloud.github.io/speech-javascript-sdk/master/SpeakerStream.html -[CORS]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Access_control_CORS - +[recognizestream]: http://watson-developer-cloud.github.io/node-sdk/master/classes/recognizestream.html +[timingstream]: http://watson-developer-cloud.github.io/speech-javascript-sdk/master/TimingStream.html +[formatstream]: http://watson-developer-cloud.github.io/speech-javascript-sdk/master/FormatStream.html +[writableelementstream]: http://watson-developer-cloud.github.io/speech-javascript-sdk/master/WritableElementStream.html +[speakerstream]: http://watson-developer-cloud.github.io/speech-javascript-sdk/master/SpeakerStream.html +[cors]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Access_control_CORS diff --git a/docs/TEXT-TO-SPEECH.md b/docs/TEXT-TO-SPEECH.md index b264506f..97ea9e14 100644 --- a/docs/TEXT-TO-SPEECH.md +++ b/docs/TEXT-TO-SPEECH.md @@ -2,17 +2,18 @@ ## [`WatsonSpeech.TextToSpeech`](http://watson-developer-cloud.github.io/speech-javascript-sdk/master/module-watson-speech_text-to-speech.html) -### [`.synthesize({text, token||access_token})`](http://watson-developer-cloud.github.io/speech-javascript-sdk/master/module-watson-speech_text-to-speech_synthesize.html) -> `