Audio & Voice

Eclipse SmartHome provides a modular architecture that enables all kinds of different use cases. At its core, there is the notion of an audio stream. Audio streams are provided by audio sources and consumed by audio sinks. Each binding for handling and controlling audio services can implement an audio sink to provide their supported devices to the framework to be used as sound output. An audio sink is identified by an unique id which in general is similar to the thing type id. The framework itself can handle multiple audio sinks at the same time. You can define a default sink for your purpose (e.g. in the Paper UI).

Audio

The distribution comes with these built-in audio sinks options:

Output device Audio sink Description
javasound System Speaker This uses the JRE sound drivers to play audio to the local sound interface.
enhancedjavasound System Speaker (with mp3 support) This uses the JRE sound drivers plus an additional 3rd party library, which adds support for mp3 files.
webaudio Web Audio If sounds should not be played on the server but on the client: This sink sends the audio stream through HTTP to web clients, which then cause it to be played back by the browser. The browser needs to be opened and have a compatible UI running. Currently this feature is supported by Paper UI and HABPanel.

The framework is able to play sound either from the file system, from URLs (e.g. Internet radio streams) or generated by text-to-speech engines (which are available as optional Voice add-ons). There are two different ways to play or stream audio:

  • using built-in functions within DSL rules;
  • using text console commands: smarthome:audio;

Built-in functions within DSL rules

Command Description
playSound(String filename) plays a sound from the sounds folder to the default sink
playSound(String filename, PercentType volume) plays a sound with the given volume from the sounds folder to the default sink
playSound(String sink, filename) plays a sound from the sounds folder to the given sink(s)
playSound(String sink, filename, PercentType volume) plays a sound with the given volume from the sounds folder to the given sink(s)
playStream(String url) plays an audio stream from an url to the default sink (set url to null if streaming should be stopped)
playStream(String sink, String url) plays an audio stream from an url to the given sink(s) (set url to null if streaming should be stopped)
float getMasterVolume() gets the master volume, returns the volume as a float in the range [0,1]
setMasterVolume(float volume) sets the master volume, volume in the range [0,1]
setMasterVolume(PercentType percent) sets the master volume
increaseMasterVolume(float percent) increases the master volume, percent in the range (0,100]
decreaseMasterVolume(float percent) increases the master volume, percent in the range (0,100]

Text console commands

Command Description
smarthome:audio play [<sink>] <filename> plays a sound file from the conf/sounds folder through the optionally specified audio sink(s)
smarthome:audio play <sink> <filename> <volume> plays a sound file from the conf/sounds folder through the specified audio sink(s) with the specified volume
smarthome:audio stream [<sink>] <url> streams the sound from the url through the optionally specified audio sink(s)
smarthome:audio sources lists the audio sources
smarthome:audio sinks lists the audio sinks

Voice

Voice services are separate bindings with the ability to synthesize written text to speech using a given voice. In order to use text-to-speech, you need to install at least one TTS service. Once you have done so, you will find different voices available in your system. Each voice supports exactly one language. You can define a default TTS service and a default voice to use (e.g. in the Paper UI). How to use TTS:

  • using built-in functions within DSL rules;
  • using text console commands: smarthome:voice;
  • using REST API methods (only for HLI);

Built-in functions within DSL rules

Command Description
String interpret(Object text) interprets a given text by the default human language interpreter, human language response
String interpret(Object text, String interpreter) interprets a given text by a given human language interpreter, human language response
say(Object text) says a given text with the default voice
say(Object text, PercentType volume) says a given text with the default voice and the given volume
say(Object text, String voice) says a given text with a given voice
say(Object text, String voice, PercentType volume) says a given text with a given voice and the given volume
say(Object text, String voice, String sink) says a given text with a given voice through the given sink
say(Object text, String voice, String sink, PercentType volume) says a given text with a given voice and the given volume through the given sink

Text console commands

Command Description
smarthome:voice say <text> speaks a text on the default audio sink with the default TTS and voice
smarthome:voice voices lists available voices of the active TTS services
smarthome:voice interpret <command> interprets a human language command

REST API

  • GET /voice/interpreters Get the list of all interpreters.
  • POST /voice/interpreters Sends a text to the default human language interpreter.
  • GET /voice/interpreters/{id} Gets a single interpreters.
  • POST /voice/interpreters/{id} Sends a text to a given human language interpreter.