Skip to main content

chime_tts.say Parameters

The chime_tts.say action 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 defines the text that will be converted into TTS audio by the TTS platform (defined by the tts_platform parameter).

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:

action: 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:
    - tts: Greetings friend!
      tts_platform: amazon_polly
    - chime: bells_2
    - tts: Hola amigo!
      language: es
      options:
        tld: es
      offset: 500
    - delay: 1000
    - tts: G'day mate!
      cache: true
      tts_speed: 115
      options:
        tld: com.au
tts Segment Type​

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

Example usage:

action: 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:
    - tts: May I please have your attention?
      cache: true
    - tts: It is officially time to move the washing to the dryer
      offset: 3000
      options:
        tld: co.uk
    - tts: Vámonos!
      language: es
      options:
        tld: es
      tts_speed: 115
    - type: tts
      message: Let's go!
      tts_platform: amazon_polly

In the above example:

  • The 1st segment overrides the cache parameter, setting it to true for the segment.
  • The 2nd segment adds a 3 second delay before the TTS message and overrides the domain, setting it to the UK.
  • The 3rd segment overrides the language, setting it to Spanish with the domain accent of Spain, and sets the speech rate to 115%.
  • The 4th segment overrides the TTS platform, setting it to Amazon Polly.
Overriding Parameters:​

When a parameter is defined in a TTS segment, it overrides the corresponding "parent" parameter in the main set of parameters, if defined. When including the options parameter in a TTS segment, the included parameters will overwrite any corresponding options in the main options parameter. Any parameters not overwritten in the "parent" options parameter will be applied as defined.

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 value can be any value supported by the chime_path/end_chime_path parameters (see selecting chimes).

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

delay Segment Type​

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

action: chime_tts.say
target:
  entity_id: media_player.kitchen_speaker
data:
  tts_platform: google_translate
  message:
    - tts: Hey, do you hear that? Just listen.
    - delay: 1000
    - tts: Yep, sounds like clothes waiting to be moved to the dryer

repeat​

All message segment types can include a repeat parameter to specify the number of times to repeat the segment.

action: chime_tts.say
target:
  entity_id: media_player.macbook_air
data:
  tts_platform: google_translate
  message:
    - chime: https://www.zapsplat.com/wp-content/uploads/2015/sound-effects-three/household_clock_cuckoo_strike_001.mp3
      repeat: 3
      offset: -800
    - tts: It's 3 o'clock

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)
tts.eleven_labs_tts (ElevenLabs TTS)
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)

*To use a TTS platform not included in the list, simply set the custom TTS platform's action 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:
ba_dum_tss
bells
bells_2
bright
chirp
choir
chord
classical
crickets
ding_dong
drumroll
dun_dun_dun
error
fanfare
glockenspiel
hail
knock
marimba
mario_coin
microphone_tap
tada
toast
twenty_four
sad_trombone
soft
whistle
Example 2:One of your own custom chimes : My Custom Chime
(see Custom Chimes Folder)
Example 2:A local file:
/media/sounds/notification.mp3
Example 3:A file from a remote URL:
https://www.website.com/sounds/notification.ogg
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:
ba_dum_tss
bells
bells_2
bright
chirp
choir
chord
classical
crickets
ding_dong
drumroll
dun_dun_dun
error
fanfare
glockenspiel
hail
knock
marimba
mario_coin
microphone_tap
tada
toast
twenty_four
sad_trombone
soft
whistle
Example 2:One of your own custom chimes : My Custom Chime
(see Custom Chimes Folder)
Example 2:A local file:
/media/sounds/notification.mp3
Example 3:A file from a remote URL:
https://www.website.com/sounds/notification.ogg
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:

When using a negative value the audio components are overlaid:

crossfade​

Description:The duration of time (in milliseconds) to gradually decrease the volume of an audio segment while simultaneously increasing the volume of the next.
Required:No
Example 1:500 (Crossfades segments over a half second)
Default:0

final_delay​

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

tts_speed​

Description:The speed for the TTS audio, between from 1% - 500%
Required:No
Example:150
Default:100

tts_pitch​

Description:The pitch of the TTS audio, in semitones (positive values to increase the pitch and negative values to lower it)
Required:No
Example:2
Default:0

volume_level​

The volume_level parameter can be used to set the volume of the media_player/s included in the action call, and return the volume level back to the original value once completed.

Basic Usage​

When the volume_level parameter is defined as a float value, it will be applied to all media_player entities included in the action call.

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

Advanced Usage​

To set the volume level for each individual media_player, you can set the volume_level as a dictioary value, allowing you to set a specific volume_level for each media_player entity included in the action call.

Example:

volume_level:
  media_player.kitchen: 1.00
  media_player.bedroom: 0.45
  media_player.living_room: 0.75
  media_player.study: 0.5

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 action 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:Convert the audio to play correctly on Alexa media_players:
Alexa
Example 2:"Hard-code" the audio file's volume to be 200% of the original:
Volume 200%
Example 3:Any FFmpeg arguments, eg:
-y -ac 2 -codec:a libmp3lame -b:a 48k -ar 24000 -write_xing 0
Default:None

announce​

The announce feature works natively for supported media_player platforms, and is simulated by Chime TTS for unsupported platforms (such as the Homepod).

Description:Pauses any media currently playing on the media_player/s and resumes it after Chime TTS completes playback
Required:No
Example:true
Default:false

fade_audio​

Description:Fades out and pauses any media currently playing on the media_player/s and resumes it after Chime TTS completes playback with fade in
Required:No
Example:true
Default:false

options​

Description:YAML options field used by TTS actions
Required:No
Example:voice: Wendy
Default:None

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

voice​

Description:Set the voice to use for TTS audio (on supported TTS platforms)
Required:No
Example:TinaNeural
Default:None