hermes-javascript
A javascript wrapper around the hermes protocol
Context
The hermes-javascript
library provides bindings for the Hermes protocol that Snips components use to communicate together. hermes-javascript
allows you to interface seamlessly with the Snips platform and create Voice applications with ease!
hermes-javascript
abstracts away the connection to the MQTT bus and the parsing of incoming and outcoming messages from and to the components of the platform and provides a high-level API as well.
Setup
npm install hermes-javascript
Hermes-javascript
uses a dynamic library generated by the hermes rust code under the hood.
The installation process will automagically download the file if your os and architecture is supported.
⚠️ Unsupported platforms / architectures
If the setup could not infer the library file version, it will attempt to build it from the sources.
Please note that rust
and git
are required in order to build the library!
If you want to force this behaviour, you can also define the HERMES_BUILD_FROM_SOURCES
environment variable before running npm install
.
env HERMES_BUILD_FROM_SOURCES=true npm install hermes-javascript
Usage
Minimal use case
const withHermes = /* A small js context manager that sets up an infinite loop to prevent the process from exiting, and exposes an instance of the Hermes class.*/
Expanded use case
const withHermes = /* The 'withHermes' function exposes a done() function that can be called to clean up the context loop and exit.*/
API
Sections:
- Context loop
- Hermes class
- Common ApiSubset methods
- Dialog Api Subset
- DialogFlow
- Injection Api Subset
- Feedback Api Subset
- Tts Api Subset
Context loop
Back ⬆️
An hermes client should implement a context loop that will prevent the program from exiting.
Using withHermes
const withHermes = // Check the Hermes class documentation (next section) for available options.const hermesOptions = /* ... */ /*The withHermes function automatically sets up the context loop. Arguments: - hermes is a freshly created instance of the Hermes class - call done() to exit the loop and destroy() the hermes instance*/
Instantiate Hermes and use the keepAlive tool
In case you want to create and manage the lifetime of the Hermes instance yourself, you can
use keepAlive
and killKeepAlive
to prevent the node.js
process from exiting.
const Hermes tools: keepAlive killKeepAlive = const hermes = /* options, see below (next section) */ // Sleeps for 60000 miliseconds between each loop cycle to prevent heavy CPU usageconst keepAliveRef = // Call done to free the Hermes instance resources and stop the loop { hermes } /* ... */
Hermes class
The Hermes class provides foreign function interface bindings to the Hermes protocol library.
⚠️ Important: Except for very specific use cases, you should have only a single instance of the Hermes class in your program. It can either be provided by the withHermes
function OR created by calling new Hermes()
.
Just keep a single reference to the Hermes instance and pass it around.
The technical reason is that the shared hermes library is read and FFI bindings are created every time you call new Hermes
or withHermes
, which is really inefficient.
Back ⬆️
// The broker address (default localhost:1883) address: 'localhost:1883' // Enables or disables stdout logs (default true). // Use it in conjunction with the RUST_LOG environment variable. (env RUST_LOG=debug ...) logs: true // Path to the hermes FFI dynamic library file. // Defaults to the hermes-javascript package folder, usually equivalent to: libraryPath: 'node_modules/hermes-javascript/libhermes_mqtt_ffi' // Username used when connecting to the broker. username: 'user name' // Password used when connecting to the broker password: 'password' // Hostname to use for the TLS configuration. If set, enables TLS. tls_hostname: 'hostname' // CA files to use if TLS is enabled. tls_ca_file: 'my-cert.cert' // CA paths to use if TLS is enabled. tls_ca_path: '/ca/path' '/ca/other/path' // Client key to use if TLS is enabled. tls_client_key: 'my-key.key' // Client cert to use if TLS is enabled. tls_client_cert: 'client-cert.cert' // Boolean indicating if the root store should be disabled if TLS is enabled. tls_disable_root_store: false
dialog()
Use the Dialog Api Subset.
const dialog = hermes
injection()
Use the Injection Api Subset.
const injection = hermes
feedback()
Use the Sound Feedback Api Subset.
const feedback = hermes
tts()
Use the text-to-speech Api Subset.
const tts = hermes
destroy()
Release all the resources associated with this Hermes instance.
hermes
Common ApiSubset methods
Back ⬆️
Check out the hermes protocol documentation for more details on the event names.
on(eventName, listener)
Subscribes to an event on the bus.
const dialog = hermes dialog
once(eventName, listener)
Subscribes to an event on the bus, then unsubscribes after the first event is received.
const dialog = hermes dialog
off(eventName, listener)
Unsubscribe an already existing event.
const dialog = hermes const handler = { /* ... */} // Subscribesdialog // Unsubscribesdialog
publish(eventName, message)
Publish an event programatically.
const Enums = const dialog = hermes dialog
Dialog Api Subset
Back ⬆️
The dialog manager.
Events available for publishing
- start_session
Start a new dialog session.
const Enums = // Start a 'notification type' session that will say whatever is in the "text" field and terminate. dialog // Start an 'action type' session that will initiate a dialogue with the user. dialog
- continue_session
Continue a dialog session.
dialog
- end_session
Finish a dialog session.
dialog
- configure
Configure intents that can trigger a session start.
dialog
Events available for subscribing
- intent/[intentName]
An intent was recognized.
- session_ended
A dialog session has ended.
- session_queued
A dialog session has been put in the queue.
- session_started
A dialog session has started.
- intent_not_recognized
No intents were recognized.
Note that the dialog session must have been started or continued with the sendIntentNotRecognized
flag in order for this to work.
DialogFlow
Back ⬆️
The Dialog API Subset exposes a small API that makes managing complex dialog flows a breeze.
flow(intent, action)
Starts a new dialog flow.
const dialog = hermes dialog // You can also return an object that will be used for// the 'continue_session' or 'end_session' parameters. dialog // If you need to perform asynchronous calculations// Just return a promise and the flow actions will// be performed afterwards. dialog
flows([{ intent, action }])
Same as flow()
, but with multiple starting intents.
Useful when designing speech patterns with loops ((intentOne or intentTwo) -> intentTwo -> intentOne -> intentTwo -> ...
,
so that the starting intents callbacks will not get called multiple times if a session is already in progress.
const intents = intent: 'intentOne' { /* ... */ } intent: 'intentTwo' { /* ... */ } dialog
sessionFlow(id, action)
Advanced, for basic purposes use flow() or flows().
Creates a dialog flow that will trigger when the target session starts. Useful when initiating a session programmatically.
// The id should match the customData value specified on the start_session message.dialog
flow.continue(intentName, action, { slotFiller })
Subscribes to an intent for the next dialog step.
dialog
slotFiller
option
About the Set the slot filler for the current dialogue round with a given slot name.
Requires flow.continue() to be called exactly once in the current round.
If set, the dialogue engine will not run the the intent classification on the user response and go straight to
slot filling, assuming the intent is the one passed in the continue
, and searching the value of the given slot.
// The slot filler is called with value 'slotName' for intent 'myIntent'.flow
flow.notRecognized(action)
Add a callback that is going to be executed if the intents failed to be recognized.
dialog
flow.end()
Ends the dialog flow.
dialog
Injection Api Subset
Back ⬆️
Vocabulary injection for the speech recognition.
Events available for publishing
- injection_request
Requests custom payload to be injected.
const Enums = injection
- injection_status_request
Will request that a new status message will be sent.
Note that you should subscribe to injection_status
beforehand in order to receive the message.
injection
- injection_reset_request
Will clear all the previously injected values.
injection
Events available for subscribing
- injection_status
Get the status of the last injection request.
- injection_complete
When an injection request completes.
- injection_reset_complete
When an injection reset request completes.
Feedback Api Subset
Back ⬆️
Control the sound feedback.
Events available for publishing
- notification_on
Turn the notification sound on.
feedback
- notification_off
Turn the notification sound off.
feedback
TTS Api Subset
Back ⬆️
Exposes text-to-speech options.
Events available for publishing
- register_sound
Register a sound file and makes the TTS able to play it in addition to pure speech.
You can interpolate a text-to-speech string with the following tag: [[sound:soundId]]
const wavBuffer = // A Buffer object containing a wav file. tts
License
Apache 2.0/MIT
Licensed under either of
-
Apache License, Version 2.0 (LICENSE-APACHE or http://www.apache.org/licenses/LICENSE-2.0)
-
MIT license (LICENSE-MIT or http://opensource.org/licenses/MIT)
at your option.
Contribution
Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in the work by you, as defined in the Apache-2.0 license, shall be dual licensed as above, without any additional terms or conditions.