mirror of
https://github.com/home-assistant/home-assistant.io.git
synced 2025-07-15 05:16:49 +00:00
Update tts docs (#27077)
This commit is contained in:
Martin Hjelmare
GitHub
parent
ec654f97c3
commit
b16779cd4b
@ -6,6 +6,7 @@ ha_category:
|
||||
- Text-to-speech
|
||||
ha_release: 0.35
|
||||
ha_codeowners:
|
||||
- '@home-assistant/core'
|
||||
- '@pvizeli'
|
||||
ha_domain: tts
|
||||
ha_quality_scale: internal
|
||||
@ -16,83 +17,27 @@ ha_integration_type: entity
|
||||
|
||||
Text-to-Speech (TTS) enables Home Assistant to speak to you.
|
||||
|
||||
## Configuring a `tts` platform
|
||||
## Services
|
||||
|
||||
To get started, add the following lines to your `configuration.yaml` (example for Google):
|
||||
### Service speak
|
||||
|
||||
Modern platforms will create entities under the `tts` domain, where each entity represents one text-to-speech service provider. These entities may be used as targets for the `tts.speak` service.
|
||||
|
||||
The `tts.speak` service supports `language` and on some platforms also `options` for settings, e.g., *voice, motion, speed, etc*. The text that should be spoken is set with `message`, and the media player that should output the sound is selected with `media_player_entity_id`.
|
||||
|
||||
```yaml
|
||||
# Example configuration.yaml entry for Google TTS service
|
||||
tts:
|
||||
- platform: google_translate
|
||||
service: tts.speak
|
||||
target: tts.example
|
||||
data:
|
||||
media_player_entity_id: media_player.kitchen
|
||||
message: "May the force be with you."
|
||||
```
|
||||
|
||||
<div class='note'>
|
||||
### Service say (legacy)
|
||||
|
||||
Depending on your setup, you might need to set an external URL (`external_url`) inside the [configuration](/docs/configuration/basic/) or in the parameters of this component.
|
||||
The `say` service supports `language` and on some platforms also `options` for settings, e.g., *voice, motion, speed, etc*. The text that should be spoken is set with `message`. Since release 0.92, service name can be defined in configuration `service_name` option.
|
||||
|
||||
</div>
|
||||
|
||||
The following optional parameters can be used with any platform. However, the TTS integration will only look for global settings under the configuration of the first configured platform:
|
||||
|
||||
{% configuration %}
|
||||
cache:
|
||||
description: Allow TTS to cache voice file to local storage.
|
||||
required: false
|
||||
type: boolean
|
||||
default: true
|
||||
cache_dir:
|
||||
description: Folder name or path to a folder for caching files.
|
||||
required: false
|
||||
type: string
|
||||
default: tts
|
||||
time_memory:
|
||||
description: Time to hold the voice data inside memory for fast play on a media player. Minimum is 60 s and the maximum 57600 s (16 hours).
|
||||
required: false
|
||||
type: integer
|
||||
default: 300
|
||||
service_name:
|
||||
description: Define the service name.
|
||||
required: false
|
||||
type: string
|
||||
default: The service name default set to <platform>_say. For example, for google_translate TTS, its service name default is `google_translate_say`.
|
||||
{% endconfiguration %}
|
||||
|
||||
The extended example from above would look like the following sample:
|
||||
|
||||
```yaml
|
||||
# Example configuration.yaml entry for Google Translate TTS service
|
||||
tts:
|
||||
- platform: google_translate
|
||||
cache: true
|
||||
cache_dir: /tmp/tts
|
||||
time_memory: 300
|
||||
service_name: google_say
|
||||
```
|
||||
|
||||
|
||||
The following sections describe some of the problems encountered with media devices.
|
||||
|
||||
### Self-signed certificates
|
||||
|
||||
This problem occurs when your Home Assistant instance is configured to be accessed through SSL, and you are using a self-signed certificate on your internal URL.
|
||||
|
||||
The `tts` service will send an `https://` URL to the media device, which will check the certificate, and reject it. So it won't play your file. If you could make the device accept your certificate, it would play the file. However, many media devices do not allow changing settings to accept self-signed certificates. Ultimately, your option may be to serve files to local devices as `http://` rather than `https://`.
|
||||
|
||||
### Google cast devices
|
||||
|
||||
The Google cast devices (Google Home, Chromecast, etc.) present the following problems:
|
||||
|
||||
* They [reject self-signed certificates](#self-signed-certificates).
|
||||
|
||||
* They do not work with URLs that contain hostnames established by local naming means. Let's say your Home Assistant instance is running on a machine made known locally as `ha`. All your machines on your local network are able to access it as `ha`. However, try as you may, your cast device won't download the media files from your `ha` machine. That's because your cast device ignores your local naming setup. In this example, the `say` service creates a URL like `http://ha/path/to/media.mp3` (or `https://...` if you are using SSL). If you are _not_ using SSL then setting an internal URL that contains the IP address of your server works around this issue. By using an IP address, the cast device does not have to resolve the hostname.
|
||||
|
||||
* If you are using an SSL (e.g., `https://yourhost.example.org/...`) then you _must_ use the hostname in the certificate (e.g., `external_url: https://yourhost.example.org`). You cannot use an IP address since the certificate won't be valid for the IP address, and the cast device will refuse the connection.
|
||||
|
||||
## Service say
|
||||
|
||||
The `say` service support `language` and on some platforms also `options` for set, i.e., *voice, motion, speed, etc*. The text for speech is set with `message`. Since release 0.92, service name can be defined in configuration `service_name` option.
|
||||
|
||||
Say to all `media_player` device entities:
|
||||
Say to all `media_player` entities:
|
||||
|
||||
```yaml
|
||||
# Replace google_translate_say with <platform>_say when you use a different platform.
|
||||
@ -102,7 +47,7 @@ data:
|
||||
message: "May the force be with you."
|
||||
```
|
||||
|
||||
Say to the `media_player.floor` device entity:
|
||||
Say to the `media_player.floor` entity:
|
||||
|
||||
```yaml
|
||||
service: tts.google_translate_say
|
||||
@ -111,7 +56,7 @@ data:
|
||||
message: "May the force be with you."
|
||||
```
|
||||
|
||||
Say to the `media_player.floor` device entity in French:
|
||||
Say to the `media_player.floor` entity in French:
|
||||
|
||||
```yaml
|
||||
service: tts.google_translate_say
|
||||
@ -136,17 +81,17 @@ data:
|
||||
|
||||
## Cache
|
||||
|
||||
The integration has two caches. Both caches can be controlled with the `cache` option in the platform configuration or the service call `say`. A long time cache will be located on the file system. The in-memory cache for fast responses to media players will be auto-cleaned after a short period.
|
||||
The integration cache can be controlled with the `cache` option in the service call to `speak` or `say`. A long time cache will be located on the file system. The in-memory cache for fast responses to media players will be auto-cleaned after a short period.
|
||||
|
||||
## REST API
|
||||
|
||||
### POST `/api/tts_get_url`
|
||||
|
||||
Returns a URL to the generated TTS file. Platform and message are required.
|
||||
Returns a URL to the generated TTS file. The `engine_id` or `platform` parameter together with `message` are required.
|
||||
|
||||
```json
|
||||
{
|
||||
"platform": "amazon_polly",
|
||||
"engine_id": "tts.amazon_polly",
|
||||
"message": "I am speaking now"
|
||||
}
|
||||
```
|
||||
@ -155,8 +100,8 @@ The return code is 200 if the file is generated. The message body will contain a
|
||||
|
||||
```json
|
||||
{
|
||||
"path": "/api/tts_proxy/265944c108cbb00b2a621be5930513e03a0bb2cd_en_-_demo.mp3",
|
||||
"url": "http://127.0.0.1:8123/api/tts_proxy/265944c108cbb00b2a621be5930513e03a0bb2cd_en_-_demo.mp3"
|
||||
"path": "/api/tts_proxy/265944c108cbb00b2a621be5930513e03a0bb2cd_en_-_tts.demo.mp3",
|
||||
"url": "http://127.0.0.1:8123/api/tts_proxy/265944c108cbb00b2a621be5930513e03a0bb2cd_en_-_tts.demo.mp3"
|
||||
}
|
||||
```
|
||||
|
||||
@ -165,6 +110,32 @@ Sample `curl` command:
|
||||
```bash
|
||||
$ curl -X POST -H "Authorization: Bearer <ACCESS TOKEN>" \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{"message": "I am speaking now", "platform": "amazon_polly"}' \
|
||||
-d '{"message": "I am speaking now", "engine_id": "amazon_polly"}' \
|
||||
http://localhost:8123/api/tts_get_url
|
||||
```
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
<div class='note'>
|
||||
|
||||
Depending on your setup, you might need to set an external URL (`external_url`) inside the [configuration](/docs/configuration/basic/).
|
||||
|
||||
</div>
|
||||
|
||||
The following sections describe some of the problems encountered with media devices.
|
||||
|
||||
### Self-signed certificates
|
||||
|
||||
This problem occurs when your Home Assistant instance is configured to be accessed through SSL, and you are using a self-signed certificate on your internal URL.
|
||||
|
||||
The `tts` service will send an `https://` URL to the media device, which will check the certificate, and reject it. So it won't play your file. If you could make the device accept your certificate, it would play the file. However, many media devices do not allow changing settings to accept self-signed certificates. Ultimately, your option may be to serve files to local devices as `http://` rather than `https://`.
|
||||
|
||||
### Google cast devices
|
||||
|
||||
The Google cast devices (Google Home, Chromecast, etc.) present the following problems:
|
||||
|
||||
* They [reject self-signed certificates](#self-signed-certificates).
|
||||
|
||||
* They do not work with URLs that contain hostnames established by local naming means. Let's say your Home Assistant instance is running on a machine made known locally as `ha`. All your machines on your local network are able to access it as `ha`. However, try as you may, your cast device won't download the media files from your `ha` machine. That's because your cast device ignores your local naming setup. In this example, the `say` service creates a URL like `http://ha/path/to/media.mp3` (or `https://...` if you are using SSL). If you are _not_ using SSL then setting an internal URL that contains the IP address of your server works around this issue. By using an IP address, the cast device does not have to resolve the hostname.
|
||||
|
||||
* If you are using SSL (e.g., `https://yourhost.example.org/...`) then you _must_ use the hostname in the certificate (e.g., `external_url: https://yourhost.example.org`). You cannot use an IP address since the certificate won't be valid for the IP address, and the cast device will refuse the connection.
|
||||
|
||||
Loading…
x
Reference in New Issue
Block a user