The framework supports some base [functions](https://openhab.org/javadoc/latest/org/openhab/core/model/script/actions/audio#method.summary) to control the audio sinks' volume.
openHAB is able to play sound either from the file system (files need to be put in the folder `$OPENHAB_CONF/sounds`), from URLs (e.g. Internet radio streams) or generated by text-to-speech engines (which are available as optional [Voice add-ons](/addons/#voice)).
| `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 | Convenient, 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. Obviously, the browser needs to be opened and have a compatible openHAB UI running. Currently, this feature is supported by Main UI, Basic UI and HABPanel. |
Alternatively the [`playSound()`](https://www.openhab.org/javadoc/latest/org/openhab/core/model/script/actions/audio#playSound(java.lang.String)) or [`playStream()`](https://www.openhab.org/javadoc/latest/org/openhab/core/model/script/actions/audio#playStream(java.lang.String)) functions can be used in DSL rules:
You can define a default TTS service and a default voice to use either by textual configuration in `$OPENHAB_CONF/services/runtime.cfg` or in the UI in `Settings->Voice`.
Alternatively you can execute such commands within DSL rules by using the [`say()`](https://www.openhab.org/javadoc/latest/org/openhab/core/model/script/actions/voice#say(java.lang.Object)) function:
Spotting a keyword is usually the first step to trigger a dialogue with a voice assistant.
In order to spot keyword, you need to install at least one [Keyword Spotter service](/addons/#voice).
#### Console Commands
To check which Keyword Spotter services are available, you can use the console:
```text
openhab> openhab:voice keywordspotters
* Porcupine (porcupineks)
```
You can define a default Keyword Spotter service to use either by textual configuration in `$OPENHAB_CONF/services/runtime.cfg` or in the UI in `Settings->Voice`.
| `rulehli` | Rule-based Interpreter | This mimics the behavior of the Android app - it sends the string as a command to a (configurable, default is "VoiceCommand") item and expects a rule to pick it up and further process it. |
| `system` | Built-in Interpreter | This is a simple implementation that understands basic home automation commands like "turn on the light" or "stop the music". It currently supports only English, German, French and Spanish and the vocabulary is still very limited. The exact syntax still needs to be documented, for the moment you need to refer to the [source code](https://github.com/openhab/openhab-core/blob/main/bundles/org.openhab.core.voice/src/main/java/org/openhab/core/voice/internal/text/StandardInterpreter.java#L42). |
| `opennlp` | HABot OpenNLP Interpreter | A machine-learning natural language processor based on Apache OpenNLP for intent classification and entity extraction. |
To check which human language interpreters are available, you can use the console:
```text
openhab> openhab:voice interpreters
Built-in Interpreter (system)
* Rule-based Interpreter (rulehli)
```
You can define a default human language interpreter to use either by textual configuration in `$OPENHAB_CONF/services/runtime.cfg` or in the UI in `Settings->Voice`.
Alternatively you can execute such commands within DSL rules using the [`interpret()`](https://www.openhab.org/javadoc/latest/org/openhab/core/model/script/actions/voice#interpret(java.lang.Object)) function:
The human language interpreter(s) parameter must be the ID of an installed interpreter or a comma separated list of interpreter IDs; each provided interpreter is executed in the provided order until one is able to interpret the command.
The audio sink parameter is used when the interpretation fails; in this case, the error message is said using the default voice and the provided audio sink.
If the provided audio sink is set to null, the error message will not be said.
openHAB embeds a dialog processor based on the services previously presented on this page.
With this dialog processor and these services, openHAB can become a voice assistant dedicated to home automation.
Here are the components needed to instantiate a voice assistant:
- an audio source: the audio device that will listen for user speaking,
- a keyword spotter: this will detect the keyword defined by the user to start a dialogue,
- a Speech-to-Text service: captured audio will be converted into text,
- one (or more) interpreter(s): the text will be analyzed and converted into commands in the automation system and a response will be produced,
- a Text-to-Speech service: the text response will be converted into an audio file,
- an audio sink: the audio file will be played to be heard by the user.
The quality of the voice assistant will of course depend on the quality of each of the selected components.
Your openHAB server can run multiple voice assistants but can only run one voice assistant for a given audio source.
After you start a voice assistant, it will live until you stop it, which means it will continue to detect keyword and handle dialogues.
However, there is a special mode that allows handling a single dialogue, bypassing keyword detection and starting to listen for user request immediately after running it.
You do not need to stop it, it stops automatically after handling the user request.
It's something you could run in a rule triggered by a particular user action, for example.
This mode is executed using the `listenAndAnswer`command.
#### Console Commands
To start and stop a voice assistant, you can enter such commands on the console:
The commands expect parameters in a specific order; so for example, if you want to provide the interpreter as a parameter, you will have to provide the audio source and the audio sink before.
When a parameter is not provided in the command line, the default from the voice settings is used.
If no default value is set in voice settings, the command will fail.
You can select particular human language interpreter(s).
This parameter must be the ID of an installed interpreter or a comma separated list of interpreter IDs; each provided interpreter is executed in the provided order until one is able to interpret the command.
If the language is defined in the regional settings, it is used as the language for the voice assistant; if not set, the system default locale is assumed.
To not fail, the keyword spotter, the Speech-to-Text and Text-to-Speech services, and the interpreters must support this language.
You can select a particular voice for the Text-to-Speech service.
If no voice is provided, the voice defined in the regional settings is preferred.
If this voice is not associated with the selected Text-to-Speech service or not applicable to the language used, any voice from the selected Text-to-Speech service applicable to the language being used will be selected.
if the default listening switch is set in the voice settings, it is used.
#### Actions
Alternatively you can execute such commands within DSL rules using the [`startDialog()`](https://www.openhab.org/javadoc/latest/org/openhab/core/model/script/actions/voice#startDialog(java.lang.String,java.lang.String)), [`stopDialog()`](https://www.openhab.org/javadoc/latest/org/openhab/core/model/script/actions/voice#stopDialog(java.lang.String)) and [`listenAndAnswer()`](https://www.openhab.org/javadoc/latest/org/openhab/core/model/script/actions/voice#listenAndAnswer(java.lang.String,java.lang.String)) functions:
-`startDialog(String source, String sink)` : starts dialog processing for a given audio source
Each parameter can be `null`; in this case, the default from the voice settings is used.
If no default value is set in the voice settings, the action will fail.
You can select particular human language interpreter(s).
The `interpreters` parameter for `startDialog` and `listenAndAnswer` must be the ID of an installed interpreter or a comma separated list of interpreter IDs; each provided interpreter is executed in the provided order until one is able to interpret the command.
The `locale` parameter for `startDialog` and `listenAndAnswer` is the language to be used by the voice assistant.
If `null` is provided, the language defined in the regional settings is used; if not set, the system default locale is assumed.
To not fail, the keyword spotter, the Speech-to-Text and Text-to-Speech services, and the interpreters must support this language.
The `voice` parameter for `startDialog` and `listenAndAnswer` is the voice to be used by the Text-to-Speech service.
If `null` is provided, the voice defined in the regional settings is preferred.
If this voice is not associated with the selected Text-to-Speech service or not applicable to the language used, any voice from the selected Text-to-Speech service applicable to the language being used will be selected.
