Skip to content

chime_tts.say

Jump to bottom
Nimrod Dolev edited this page Mar 13, 2024 · 34 revisions

chime_tts.say Service

The chime_tts.say service joins together audio files ("chimes") and TTS audio, and then streams it to media_player target/s.

Please note that Chime TTS works with TTS Platform integrations, but you need to add them to your Home Assistant instance beforehand.

TTS Audio with Chime

You can add audio "chimes" before TTS audio (see chime_path) after TTS audio (see end_chime_path) as well as in between TTS audio (see message segments).

Chimes can be added via the UI in 3 ways:

1. From the chime list UI

Use the drop-down chime list in the UI to select a preset chime sound effect:

chime_options

or

2. From a local file or an external URL

  • Local File

    You can specify a local file path to your own audio files from your Home Assistant instance, in the media folder or any other folder on your file system.

    chime_path

  • Audio File URL

    You can also specify a URL to an audio file hosted online. Chime TTS will download the file and can save it to your chimes folder (if you enable the cache property).

    external_chime_path

or

3. Custom chime slots for the chime list UI

You can set up to 5 custom chime slots which appear at the end of the drop-down list in the UI, allowing you to easily select your custom chimes when creating automations. To configure the custom chime slots, open the Chime TTS configuration page and enter the full file path to your local custom audio file, or the URL to an audio file hosted online.

The configuration page is located at:

Settings --> Devices & services --> Chime TTS --> CONFIGURE

configuration

Once added, you can use your custom chimes by selecting them from the chime list UI:

custom

Parameters

The chime_tts.say service has standard parameters used by all TTS platforms, and additional parameters used by specific TTS platforms.

Standard Parameters

message

Basic Usage: Text

The message parameter is used to define the text the TTS platform uses to generate TTS audio.

Description: The text to be converted into TTS audio.
Required: Yes
Example: The washing's done!
Default: None

Advanced Usage: "Segment" sequences

The message parameter can also define a YAML sequence built from 3 different "segment" types: tts, chime and delay. These segments can be used together to create any combination, for example:

advanced_message_segments

service: chime_tts.say
target:
  entity_id: media_player.kitchen_speaker
data:
  chime_path: chord
  end_chime_path: tada
  offset: 0
  tts_platform: google_translate
  language: en
  message:
    - type: tts
      message: Greetings friend!
      tts_platform: amazon_polly
    - type: chime
      path: bells_2
    - type: tts
      message: Hola amigo!
      language: es
      options:
        tld: es
      offset: 500
    - type: delay
      length: 1000
    - type: tts
      message: G'day mate!
      cache: true
      tts_playback_speed: 115
      options:
        tld: com.au

tts Segment Type

The tts segment type supports the parameters: (options, tts_platform, tts_playback_speed, language, cache), offset, and audio_conversion which allow you to use different TTS providers, languages, voices, rates of speech and specific FFmpeg audio conversions on different TTS segments within the same message.

You can split your TTS text into static & dynamic segments, and cache the static phrases to save latency time, and also reduce API calls to paid TTS service providers, saving money.

Overriding Parameters:

When a parameter is defined in a TTS segment, it overrides the corresponding parameter in the main set of parameters, if defined. When including the options parameter in a TTS segment, the included parameters will overwrite the corresponding options in the main options parameter of the service call will be applied, if also included.

Example usage:

service: chime_tts.say
target:
  entity_id: media_player.kitchen_speaker
data:
  chime_path: classical
  end_chime_path: marimba
  tts_platform: google_translate
  cache: false
  language: en
  message:
    # Overrides the cache parameter to true
    - type: tts
      message: May I please have your attention?
      cache: true
    # Adds a 3 second delay before the TTS message and overrides the domain accent to the UK
    - type: tts
      offset: 3000
      message: It is officially time to move the washing to the dryer
      options:
        tld: co.uk
    # Overrides the language to Spanish with the domain accent of Spain, and sets the speech rate to 115%
    - type: tts
      message: Vámonos!
      language: es
      options:
        tld: es
      tts_playback_speed: 115
    # Overrides the TTS platform to Amazon Polly
    - type: tts
      message: Let's go!
      tts_platform: amazon_polly

chime Segment Type

The chime segment allows you to insert chimes anywhere in your messages, (not just at the start via chime_path) or end via end_chime_path), and supports the offset and audio_conversion parameters.

The chime path value can be set to a preset chime, a local path to your own custom files or a URL to a remote audio file.

service: chime_tts.say
target:
  entity_id: media_player.kitchen_speaker
data:
  chime_path: toast
  end_chime_path: tada
  offset: 250
  tts_platform: google_translate
  cache: false
  language: en
  message:
    - type: tts
      message: And the winner is, drumroll please
    - type: chime
      path: drumroll
      offset: 500
    - type: tts
      message: You!
      offset: 0
    - type: chime
      path: /config/media/sounds/my_chimes/hooray.mp3
    - type: tts
      message: You get to move the washing to the dryer!

delay Segment Type

The delay segment allows you to add additional delay/s into the message. This might be useful for repeating a message, or for dramatic effect 🎭

service: chime_tts.say
target:
  entity_id: media_player.kitchen_speaker
data:
  chime_path: toast
  end_chime_path: tada
  tts_platform: google_translate
  cache: false
  language: en
  message:
    - type: tts
      message: Hey, do you hear that? Just listen.
    - type: delay
      duration: 1000
    - type: tts
      message: Yep, sounds like clothes waiting to be moved to the dryer

tts_platform

Chime TTS works with TTS Platform integrations, but you need to add them to your Home Assistant instance yourself beforehand.

Description: TTS platform to be used to create TTS audio.
Required: Yes
Example: amazon_polly
Default: None
Possible Values*: amazon_polly (Amazon Polly)
baidu (Baidu)
edge_tts (Microsoft Edge TTS)
google_cloud (Google Cloud)
google_translate (Google Translate)
openai_tts (OpenAI TTS)
watson_tts (IBM Watson TTS)
marytts (MaryTTS)
microsoft (Microsoft Text-To-Speech)
cloud (Nabu Casa Cloud TTS)
picotts (Picto TTS)
tts.piper (Piper)
voicerss (VoiceRSS)
yandextts (Yandex TTS)

*If you wish to use a TTS platform not included in the list, simply set the custom TTS platform's service as the tts_platform parameter value.

chime_path

Description: The file path for the audio to insert before the TTS audio
Required: No
Example 1: One of the Chime TTS presets:
bells
bells_2
bright
chirp
choir
chord
classical
ding_dong
drumroll
dun_dun_dun
error
glockenspiel
hail
marimba
mario_coin
microphone_tap
tada
toast
twenty_four
sad_trombone
whistle
Example 2: Your own audio file from your local media library:
/media/sounds/notification.mp3
Default: None

end_chime_path

Description: The file path for the audio to insert after the TTS audio
Required: No
Example 1: One of the Chime TTS presets:
bells
bells_2
bright
chirp
choir
chord
classical
ding_dong
drumroll
dun_dun_dun
error
glockenspiel
hail
marimba
mario_coin
microphone_tap
tada
toast
twenty_four
sad_trombone
whistle
Example 2: Your own audio file from your local media library:
/media/sounds/notification.mp3
Default: None

offset

Description: Adds a delay between audio segments when value > 0, or overlays audio segments when value < 0.
Required: No
Example 1: 500 (Adds a 1 second delay between chimes & TTS audio)
Example 2: -500 (Moves the audio 1 second earlier, overlaying it with the previous chime/TTS audio)
Default: 450

When using a value greater than 0, a delay is added between audio components: delay

When using a negative value the audio components are overlaid: overlay

final_delay

Description: The delay (in milliseconds) to insert after the chimes and the TTS audio
Required: No
Example: 200
Default: 0

tts_playback_speed

Description: The playback speed for the TTS audio, between from 100% - 200%
Required: No
Example: 120
Default: 100

volume_level

Description: The volume level (between 0.0 - 1.0) to play the audio.
The original volume is restored after playback.
Required: No
Example: 0.75
Default: 1.0

join_players

Description: Play the audio simultaneously on multiple media_player entities (that support speaker groups).
Required: No
Example: true
Default: false

unjoin_players

Description: Unjoin the speakers after playback has completed.
Required: No
Example: true
Default: false

cache

Description: Save generated audio to the cache for reuse in future service calls.
Required: No
Example: true
Default: false

audio_conversion

Description: Convert the generated audio via FFmpeg to work with Alexa speakers, or convert with any FFmpeg arguments.
Required: No
Example 1: Alexa
Example 2: Any FFmpeg arguments, eg:
-y -ac 2 -codec:a libmp3lame -b:a 48k -ar 24000 -write_xing 0
Default: None

announce

Description: Current media paused the announcement and then resumed (on supported devices)
Required: No
Example: true
Default: false

options

Description: YAML options field used by TTS services
Required: No
Example: voice: Wendy

Additional Parameters

The following parameters can be used with select TTS platforms, as outlined below:

language

Description: The language to use for the TTS audio. This parameter is only supported by Google Translate and
Nabu Casa Cloud TTS. This parameter should also be used to set IBM Watson TTS's voice value.
Required: No
Example: en
Default: None

tld

Description: The domain region to use for a specific dialect/accent. Refer to the documentation for Google Translate
Required: No
Example: com.au
Default: None
Possible Values: com
co.uk
com.au
ca
co.in
ie
co.za
fr
com.br
pt
es

gender

Description: Use a male or female voice Nabu Casa Cloud TTS.
Required: No
Example: female
Default: None
Possible Values: male
female

YAML Examples

The following YAML examples cover additional features provided by the chime_tts.say service:

Basic TTS Audio

All service calls to chime_tts.say must include one or more media_player entity targets, and a data object with the TTS message and tts_platform values:

service: chime_tts.say
target:
  entity_id:
    - media_player.living_room
data:
  tts_platform: google_translate
  message: Hello world!

Use chime_path to play a chime before the TTS audio (using a 'Chime TTS' chime):

service: chime_tts.say
target:
  entity_id:
    - media_player.living_room
data:
  tts_platform: google_translate
  message: Hello world!
  chime_path: tada

Use end_chime_path to play a chime after the TTS audio (from your media folder)

service: chime_tts.say
target:
  entity_id:
    - media_player.living_room
data:
  tts_platform: google_translate
  message: Hello world!
  end_chime_path: /media/sounds/doorbell.mp3

Use chime_path and end_chime_path to play a chime before and after TTS audio

service: chime_tts.say
target:
  entity_id:
    - media_player.living_room
data:
  tts_platform: google_translate
  message: Hello world!
  chime_path: drumroll
  end_chime_path: /media/sounds/doorbell.mp3

More complex examples

Use tts_playback_speed to increase the TTS audio playback speed

service: chime_tts.say
data:
  chime_path: tada
  message: The washing's done!
  tts_platform: amazon_polly
  tts_playback_speed: 120
target:
  entity_id:
    - media_player.kitchen
    - media_player.dining_room

Use language and tld to play TTS audio with an Australian accent on the Google Translate TTS platform 

service: chime_tts.say
data:
  chime_path: tada
  message: The washing's done!
  tts_platform: google_translate
  language: en
  tld: com.au
target:
  entity_id:
    - media_player.kitchen
    - media_player.dining_room

Use join_players to hear the announcement across multiple speakers at the same time (only on supported speakers)

service: chime_tts.say
data:
  chime_path: tada
  message: The washing's done!
  tts_platform: amazon_polly
  join_players: true
  unjoin_players: true
target:
  entity_id:
    - media_player.kitchen
    - media_player.dining_room
    - media_player.bedroom

Full example

service: chime_tts.say
data:
  chime_path: drumroll
  end_chime_path: /media/sounds/cheer.mp3
  message: The washing's done!
  tts_platform: google_translate
  tts_playback_speed: 120
  volume_level: 0.7
  join_players: true
  unjoin_players: true
  cache: true
  announce: true
  language: en
  tld: com.au
target:
  entity_id:
    - media_player.kitchen
    - media_player.dining_room
    - media_player.bedroom

In this example:

  • A drumroll is heard before the TTS audio (in an Australian accent at 120% speed), followed by a cheer sound effect from the media folder.
  • The three speakers are joined together for simultaneous playback and unjoined afterwards.
  • The volume is set to 70% for the announcement, and restored afterwards.
  • The audio file generated is cached.
  • If music was playing on the speakers before the service was called, it will be resumed afterwards.
Clone this wiki locally