openhab-docs/configuration/multimedia.md

---
layout: documentation
title: Multimedia
---

{% include base.html %}

# Multimedia

## Volume

The framework supports some base [functions](https://www.eclipse.org/smarthome/documentation/javadoc/org/eclipse/smarthome/model/script/actions/Audio.html#getMasterVolume--) to control the audio sinks' volume.

### Actions

- `setMasterVolume(float volume)` : Sets the volume of the host machine (volume in range 0-1)
- `setMasterVolume(PercentType percent)` : Sets the volume of the host machine
- `increaseMasterVolume(float percent)` : Increases the volume by the given percent
- `decreaseMasterVolume(float percent)` : Decreases the volume by the given percent
- `float getMasterVolume()` : Returns the current volume as a float between 0 and 1

## Audio

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)).

There are different options for output devices (so called audio sinks):

The distribution comes with these options built-in:

| 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                         | 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 Paper UI and HABPanel. |

Additionally, certain bindings register their supported devices as audio sinks, e.g. Sonos speakers.

### Console commands

To check, which audio sinks are available, you can use the console:

```text
openhab> smarthome:audio sinks
enhancedjavasound
javasound
webaudio
```

You can define the default audio sink either by textual configuration in `$OPENHAB_CONF/services/runtime.cfg` or in the Paper UI in `Configuration->System->Audio`.

In order to play a sound, you can use the following command on the console:

```text
openhab> smarthome:audio play doorbell.mp3

openhab> smarthome:audio stream example.com
```

### Actions

Alternatively the [`playSound()`](https://www.eclipse.org/smarthome/documentation/javadoc/org/eclipse/smarthome/model/script/actions/Audio.html#playSound-java.lang.String-) or [`playStream()`](https://www.eclipse.org/smarthome/documentation/javadoc/org/eclipse/smarthome/model/script/actions/Audio.html#playStream-java.lang.String-) functions can be used in DSL rules:

- `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, String filename)` :	plays a sound from the sounds folder to the given sink(s)
- `playSound(String sink, String 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)

#### Examples

```java
playSound("doorbell.mp3")
playSound("doorbell.mp3", new PercentType(25))
playSound("sonos:PLAY5:kitchen", "doorbell.mp3")
playSound("sonos:PLAY5:kitchen", "doorbell.mp3", new PercentType(25))

playStream("example.com")
playStream("sonos:PLAY5:kitchen", "example.com")
```

## Voice

### Text-to-Speech

In order to use text-to-speech, you need to install at least one [TTS service](/addons/#voice).

### Console Commands

Once you have done so, you will find voices available in your system:

```text
openhab> smarthome:voice voices
mactts:Jorge Jorge (es_ES)
mactts:Moira Moira (en_IE)
mactts:Alice Alice (it_IT)
mactts:Ioana Ioana (ro_RO)
mactts:Kanya Kanya (th_TH)
```

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 Paper UI in `Configuration->System->Voice`.

In order to say a text, you can enter such a command on the console (The default voice and default audio sink will be used):

```text
openhab> smarthome:voice say Hello world!
```

### Actions

Alternatively you can execute such commands within DSL rules by using the [`say()`](https://www.eclipse.org/smarthome/documentation/javadoc/org/eclipse/smarthome/core/voice/VoiceManager.html#say-java.lang.String-) function:

```java
say("Hello world!")
say("Hello world!", new PercentType(25))
say("Hello world!", "voicerss:enGB")
say("Hello world!", "voicerss:enGB", new PercentType(25))
say("Hello world!", "voicerss:enUS", "sonos:PLAY5:kitchen")
say("Hello world!", "voicerss:enUS", "sonos:PLAY5:kitchen", new PercentType(25))
```

You can select a particular voice (second parameter) and a particular audio sink (third parameter).
If no voice or no audio sink is provided, the default voice and default audio sink will be used.

### Speech-to-Text

Although there are already interfaces defined in openHAB for speech-to-text, up to now there is no add-on available for this functionality.
So the only choice that is available right now is to use the Android voice recognition feature that is built into the openHAB Android app.

The Android app is [not yet adapted to the openHAB 2 voice features](https://github.com/openhab/openhab-android/issues/242).
To still use the voice feature you will need to have a String item with the name "VoiceCommand" defined, to which the app sends any recognized text as a string command.

### Human Language Interpreter

Human language interpreters are meant to process prose that e.g. is a result of voice recognition or from other sources.

There are two implementations available by default:

| Interpreter | Type                   | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
|-------------|------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `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 and French 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/eclipse/smarthome/blob/master/bundles/core/org.eclipse.smarthome.core.voice/src/main/java/org/eclipse/smarthome/core/voice/internal/text/StandardInterpreter.java#L37). |

To test the interpreter, you can enter such a command on the console (assuming you have an item with label 'light'):

```text
openhab> smarthome:voice interpret turn on the light
```

The default human language interpreter will be used.
In case of interpretation error, the error message will be said using the default voice and default audio sink.

Again, such a command can also be entered within DSL rules (using the [`interpret()`](https://www.eclipse.org/smarthome/documentation/javadoc/org/eclipse/smarthome/core/voice/VoiceManager.html#interpret-java.lang.String-) function)

```java
interpret("turn on the light")
var String result = interpret("turn on the light", "system")
result = interpret("turn on the light", "system", null)
result = interpret(VoiceCommand.state, "system", "sonos:PLAY5:kitchen")
```

You can select a particular human language interpreter (second parameter) and a particular audio sink (third parameter).
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.
If no human language interpreter or no audio sink is provided, the default human language interpreter and default audio sink will be used.
The interpretation result is returned as a string.
Note that this result is always a null string with the rule-based Interpreter (rulehli).