IBM Watson connector for Algolia InstantSearch.js

IBM Watson connector for Algolia InstantSearch.js allows you to easily add Speech to Text (STT) as a widget to your Algolia search.

This repo is initially developed by Lextenso, open to the community ♥️ and isn't affiliated or supported by IBM or Algolia.

PLEASE NOTE : This current version 0.8.0 still in beta, please use carefully. As of July 1, 2019, this project is no longer being maintained. Feel free to fork it!

Built with IBM Watson Speech Services

This is a middleware between Algolia InstantSearch.js and IBM Watson. This Algolia connector is bundled with the NPM package watson-speech/speech-to-text/recognize-microphone and instantsearch.js/es/connectors/connectSearchBox.

The connector handle :

Microphone browser authorization
Stream voice to Watson (via WebSocket)
Output text results in search input
Refine Algolia search with new values in realtime

Requirements

This connector doesn't inject any templates, you have to develop your own HTML element to trigger Watson with this connector.

You also need Algolia and IBM Watson credentials. (Elementary, my dear Watson)

Dependencies

instantsearch.js : 2.10.4
watson-speech : 0.35.4

Installation

Standalone

Pre-compiled bundle is available on jsdelivr.com CDN :

<script src="https://cdn.jsdelivr.net/gh/Lextenso/IBM-Watson-Algolia-connector-instantsearch.js@0.8.0/dist/IBMWatsonAlgoliaConnector.js"></script>

Or build the connector with Webpack :

sher-lock:IBM-watson-algolia-connector-instantsearch.js$ npm run build

ES Module with Webpack

Import the IBMWatsonAlgoliaConnector module which is available in the /src directory.

import IBMWatsonAlgoliaConnector from './IBMWatsonAlgoliaConnector';

Configuration

All attributes are listed and detailed in the specifications section.

Standalone

<script src="https://cdn.jsdelivr.net/gh/Lextenso/IBM-Watson-Algolia-connector-instantsearch.js@0.8.0/dist/IBMWatsonAlgoliaConnector.js"></script>
<script type="text/javascript">
const search = instantsearch(config);

// [...]

search.addWidget(
    IBMWatsonAlgoliaConnector({
        container: {
            searchInput: [string],
            voiceButton: [string]
        },
        template: {
            onActiveClass: [string],
            onInactiveClass: [string],
            // OR
            onStateChange: [function (state => 'active' || 'inactive')]
        },
        watsonConfig: {
            tokenURL: [string],
            model: [string],
            continuous: [boolean]
        }
    })
);

// [...]

search.start();
</script>

NPM - Webpack

import InstantSearch from 'instantsearch.js/es/';
import IBMWatsonAlgoliaConnector from './IBMWatsonAlgoliaConnector';

const search = InstantSearch(config);

// [...]

search.addWidget(
    IBMWatsonAlgoliaConnector({
        container: {
            searchInput: [string],
            voiceButton: [string],
        },
        template: {
            onActiveClass: [string],
            onInactiveClass: [string],
            // OR
            onStateChange: [function (state => 'active' || 'inactive')]
        },
        watsonConfig: {
            tokenURL: [string],
            model: [string],
            continuous: [boolean]
        }
    })
);

// [...]

search.start();

Build examples

Two examples are available : standalone and ES Module. Each example require a server-side endpoint to fetch Watson's token, you can find examples here

Standalone

Change the API endpoint to fetch Watson's token in the example/standalone/app.js file.

search.addWidget(
    IBMWatsonAlgoliaConnector.default({
        // [...]
        watsonConfig: {
            tokenURL: 'https://local.example.dev/api/watson/get-token',
            // [...]
        }
    })
);

Then

sher-lock:IBM-watson-algolia-connector-instantsearch.js$ npm run build-example

ES Module with Webpack

Change the API endpoint to fetch Watson's token in the example/es/src/main.js file.

search.addWidget(
    IBMWatsonAlgoliaConnector({
        // [...]
        watsonConfig: {
            tokenURL: 'https://local.example.dev/api/watson/get-token',
            // [...]
        }
    })
);

Then

sher-lock:IBM-watson-algolia-connector-instantsearch.js$ npm run build-example

Specifications

Attributes			Required ?	Comment
container
	searchInput	[string]	Yes	This string must be a valid CSS selector string.
	voiceButton	[string]	Yes	This string must be a valid CSS selector string.
template
	onActiveClass	[string]	Yes (except if `onStateChange` is set)
	onInactiveClass	[string]	Yes (except if `onStateChange` is set)
	onErrorClass	[string]	No (if NOT set `onInactiveClass` will be used)
	onStateChange	[function (state => active \|\| inactive \|\| error)]	Yes (Only if `on{state}Class` are not enouth for your needs)	This callback will be triggered every time the state of Watson change. Possible values: active OR inactive NOTE : This callback function override `onInactiveClass`, `onActiveClass` and `onErrorClass`
autoHideContainer		[boolean \|\| string]	No	Hide the container voiceButton if MediaRecorder isn't supported. It can be a valid CSS selector string, if you want to hide parent container.
watsonConfig				Watson configuration (see doc) NOTE : 'token' and 'outputElement' will be overridden on connector start
	tokenURL	[string]	Yes (if `getWatsonToken` isn't set)	Must be an URL to a back-end service
	getWatsonToken	[function]	No	Must be a Promise returning only the token as a string NOTE : This callback function override `tokenURL`
	model	[string]	No	Check possible values here
	continuous	[boolean]	No	Watson stop listening when it detects final sentence

Todo

NPM publish
Better cross-browser testing
Improve documentation

Author

Julien Madiot (@Madi-Ji)

IBM®, IBM Watson® and Watson™ are United States trademarks owned by International Business Machines Corporation ("IBM") and might also be trademarks or registered trademarks in other countries. (Copyright and trademark information)

Algolia and all other trademarks, service marks, graphics and logos used are trademarks or registered trademarks of Algolia or Algolia’s licensors. (Acceptable use policy)