settings.yml
This part of the documentation explains the main configuration of Kalliope placed in the settings.yml
file.
Kalliope will look for the settings file in the order bellow:
- From you current folder, E.g
/home/pi/my_kalliope/settings.yml
- From
/etc/kalliope/settings.yml
- From the default
settings.yml
located in the root of the project tree.
Triggers configuration
default_trigger
The trigger is the engine in charge of detecting the hotword that will wake up Kalliope. Common usage of hotword include "Alexa" on Amazon Echo, "OK Google" on some Android devices and "Hey Siri" on iPhones.
Specify the name of the trigger module you want to use.
default_trigger: "trigger_name"
E.g
default_trigger: "snowboy"
triggers
The hotword (also called a wake word or trigger word) detector is the engine in charge of waking up Kalliope.
Each Trigger has it own configuration. This configuration is passed as argument following the syntax bellow
triggers:
- trigger_name:
parameter_name: "value"
E.g, the default Snowboy trigger configuration is
triggers:
- snowboy:
pmdl_file: "trigger/snowboy/resources/model.pmdl"
Settings example
default_trigger: "snowboy"
triggers:
- snowboy:
pmdl_file: "trigger/snowboy/resources/model.pmdl"
Available trigger engine
Doc | Note |
---|---|
snowboy | Based on Snowboy software |
Players configuration
The player is the library/software used to make Kalliope talk. With Kalliope project, you can set whatever sound player you want to use.
default_player
Specify the name of the player module you want to use.
default_player: "player_name"
E.g
default_player: "mplayer"
players
Each Players has it own configuration. This configuration is passed as argument following the syntax bellow
players:
- player_name:
parameter_name: "value"
When no parameters are required set an empty object:
players:
- mplayer: {}
Settings example
players:
- mplayer: {}
- pyalsaaudio:
device: "default"
convert_to_wav: True
- pyaudioplayer:
convert_to_wav: True
- sounddeviceplayer:
convert_to_wav: True
Note: Sometime, parameters will be necessary to use an engine. Click on a Player engine link in the
Current CORE Available Players
section to know which parameter are required.Note: A player which does not ask for input parameters need to be declared as an empty dict. E.g:
- player_name: {}
Note: Core players are already packaged with the installation of Kalliope an can be used out of the box.
Note: Most cloud based TTS generate a file in MP3 format. Some players are not able to read this format and then a conversion to wav is needed.
Available players
Core Players are already packaged with the installation of Kalliope an can be used out of the box.
Doc | Note |
---|---|
mplayer | Based on mplayer software |
pyalsaaudio | Based on pyalsaaudio lib |
pyaudioplayer | Based on pyaudio lib |
sounddeviceplayer | Based on sounddevice lib |
Speech to text configuration
default_speech_to_text
A Speech To Text(STT) is an engine used to translate what you say into a text that can be processed by Kalliope core. By default, Kalliope uses google STT engine.
The following syntax is used to provide the engine name:
default_speech_to_text: "stt_name"
E.g
default_speech_to_text: "google"
speech_to_text
Each STT has it own configuration. This configuration is passed as argument as shown bellow
speech_to_text:
- stt_name:
parameter_name: "value"
E.g:
speech_to_text:
- google:
language: "fr-FR"
- bing
Settings example
default_speech_to_text: "google"
speech_to_text:
- google:
language: "fr-FR"
- wit:
key: "MYKEYS"
- bing:
key: "MYKEYS"
- apiai:
key: "MYKEYS"
language: "fr"
- houndify:
key: "MYKEYS"
client_id: "MYCLIENTID"
Available STT
Core STTs are already packaged with the installation of Kalliope an can be used out of the box.
Name | Type |
---|---|
apiai | Cloud based |
Bing | Cloud based |
CMUSphinx | Self hosted |
Cloud based | |
Houndify | Cloud based |
wit.ai | Cloud based |
Text to speech configuration
default_text_to_speech
A Text To Speech is an engine used to translate written text into a speech, into an audio stream. By default, Kalliope use Pico2wave TTS engine.
The following syntax is used to provide the TTS engine name
default_text_to_speech: "tts_name"
Eg
default_text_to_speech: "pico2wave"
text_to_speech
Each TTS has it own configuration. This configuration is passed as argument following the syntax bellow
text_to_speech:
- tts_name:
parameter_name: "value"
E.g
text_to_speech:
- pico2wave:
language: "fr-FR"
- googletts:
language: "fr"
cache_path
TTS engines work all the same, we give them a text, they give back an audio file and we play the audio file. The generated audio file is placed in cache until it is played by the audio player. Before generating a new audio file, Kalliope will take a look to the cache to load it directly without having to call the TSS engine if the file has been generated before.
You must set a path where the cache will be saved in the tag cache_path
. This one is placed in /tmp by default.
cache_path: "/tmp/kalliope_tts_cache"
Note: The path must be a valid path, and the current user must has enough right to read and write in it.
Note: The consumed disk space can dramatically increase in the cache path folder. It is recommended to set your neuron correctly to clean up automatically generated audio files that will not be played more than once.
Settings example
default_text_to_speech: "voicerss"
cache_path: "/tmp/kalliope_tts_cache"
text_to_speech:
- pico2wave:
language: "fr-FR"
cache: True
- acapela:
language: "sonid15"
voice: "Manon"
cache: False
- googletts:
language: "fr"
- voicerss:
language: "fr-fr"
cache: True
Available TTS
Core TTSs are already packaged with the installation of Kalliope an can be used out of the box.
Name | Type |
---|---|
espeak | Self hosted |
googletts | Cloud based |
marytts | Self hosted |
pico2wave | Self hosted |
voicerss | Cloud based |
watson | Cloud based |
Hooks
Hooking allow to bind actions to events based on the lifecycle of Kalliope. For example, it's useful to know when Kalliope has detected the hotword from the trigger engine and make her spell out loud that she's ready to listen your order.
To use a hook, attach the name of the hook to a synapse (or list of synapse) which exists in your brain.
Syntax:
hooks:
hook_name1: synapse_name
hook_name2:
- synapse_name_1
- synapse_name_2
E.g.
hooks:
on_start: "on-start-synapse"
List of available hook
Hook name | Description |
---|---|
on_start | When kalliope is started. This hook will only be triggered once |
on_waiting_for_trigger | When Kalliope waits for the hotword detection |
on_triggered | When the hotword has been detected |
on_start_listening | When the Speech to Text engine is listening for an order |
on_stop_listening | When the Speech to Text engine stop listening for an order |
on_order_found | When the pronounced order has been found in the brain |
on_order_not_found | When the pronounced order has not been found in the brain |
on_processed_synapses | When all neurons in synapses have been processed |
on_deaf | When Kalliope switches from non deaf to deaf |
on_undeaf | When Kalliope switches from deaf to non deaf |
on_mute | When Kalliope switches from non mute to mute |
on_unmute | When Kalliope switches from mute to non mute |
on_start_speaking | When Kalliope starts speaking via the text to speech engine |
on_stop_speaking | When Kalliope stops speaking |
on_stt_error | When an error appeared during the STT processing |
Settings example
Example: You want to hear a random answer when the hotword has been triggered
settings.yml
hooks:
on_triggered: "on-triggered-synapse"
brain.yml
- name: "on-triggered-synapse"
signals: []
neurons:
- say:
message:
- "yes sir?"
- "I'm listening"
- "I'm listening to you"
- "sir?"
- "what can i do for you?"
- "Speaking"
- "how can i help you?"
Example: You want to know that your order has not been found
settings.yml
hooks:
on_order_not_found: "order-not-found-synapse"
brain.yml
- name: "order-not-found-synapse"
signals: []
neurons:
- say:
message:
- "I haven't understood"
- "I don't know this order"
- "Please renew your order"
- "Would you please reword your order"
- "Can ou please reformulate your order"
- "I don't recognize that order"
Example: You are running Kalliope on a Rpi. You've made a script that turn on or off a led. You can call this script every time kalliope start or stop speaking
settings.yaml
hooks:
on_start_speaking: "turn-on-led"
on_stop_speaking: "turn-off-led"
brain.yml
- name: "turn-on-led"
signals: []
neurons:
- script:
path: "/path/to/script.sh on"
- name: "turn-off-led"
signals: []
neurons:
- script:
path: "/path/to/script.sh off"
Note: You cannot use a neurotransmitter neuron inside a synapse called from a hook. You cannot use the "say" neuron inside the "on_start_speaking" or "on_stop_speaking" or it will create an infinite loop
Rest API
A Rest API can be activated in order to:
- List synapses
- Get synapse's detail
- Run a synapse
- Update settings
- Update the brain
For the complete API ref see the REST API documentation
Settings examples:
rest_api:
active: True
port: 5000
password_protected: True
login: admin
password: secret
allowed_cors_origin: "*"
parameter | type | comment |
---|---|---|
active | boolean | To enable the rest api server |
port | integer | TThe listening port of the web server. Must be an integer in range 1024-65535 |
password_protected | boolean | If True , the whole api will be password protected |
login | string | Login used by the basic HTTP authentication. Must be provided if password_protected is True |
password | string | Password used by the basic HTTP authentication. Must be provided if password_protected is True |
allowed_cors_origin | string | Allow request from external application. See examples bellow |
Cors request
If you want to allow request from external application, you'll need to enable the CORS requests settings by defining authorized origins. To do so, just indicated the origins that are allowed to leverage the API. The authorize values are:
False to forbid CORS request.
allowed_cors_origin: False
or either a string or a list:
allowed_cors_origin: "*"
(in case of "*", all origins are accepted). or
allowed_cors_origin:
- 'http://mydomain.com/*'
- 'http://localhost:4200/*'
Remember that an origin is composed of the scheme (http(s)), the port (eg: 80, 4200,…) and the domain (mydomain.com, localhost).
Resources directory
The resources directory is the path where Kalliope will try to load community modules like Neurons, STTs or TTSs. Set a valid path is required if you want to install community neuron. The path can be relative or absolute.
resource_directory:
resource_name: "path"
E.g
resource_directory:
neuron: "resources/neurons"
stt: "resources/stt"
tts: "resources/tts"
trigger: "/full/path/to/trigger"
Global Variables
The Global Variables paths list where to load the global variables. Those variables can be reused in neuron parameters within double brackets.
E.g
var_files:
- variables.yml
- variables2.yml
Note: If a variable is defined in different files, the last file defines the value.
In the files the variables are defined by key/value:
variable: 60
baseURL: "http://blabla.com/"
password: "secret"
And use variables in your neurons:
- name: "run-simple-sleep"
signals:
- order: "Wait for me "
neurons:
- uri:
url: "{{baseURL}}get/1"
user: "admin"
password: "{{password}}"
Note: Because YAML format does no allow double braces not surrounded by quotes: you must use the variable between double quotes.
A global variable can be a dictionary. Example:
contacts:
nico: "1234"
tibo: "5678"
And a synapse that use this dict:
- name: "test-var"
signals:
- order: "give me the number of {{ contact_to_search }}"
neurons:
- say:
message:
- "the number is {{ contacts[contact_to_search] }}"
Options
Options that can be defined for Kalliope.
Example config
options:
mute: True
deaf: False
Available options:
Option | Default | Description |
---|---|---|
mute | False | When mute, the STT engine will not be used to make Kalliope talking during neurons execution |
deaf | False | When deaf, the trigger engine is not started. Kalliope will not listen for a wake up word |
recognizer_multiplier | 1.0 | The multiplier acts on the Threshold |
recognizer_energy_ratio | 1.5 | Is used in speech recognition to identify characteristics of audio, such as whether a person has stopped or started speaking |
recognizer_recording_timeout | 15.0 | The maximum seconds a phrase can be recorded, provided there is noise the entire time |
recognizer_recording_timeout_with_silence | 3.0 | The maximum time it will continue to record silence when not enough noise has been detected |
send_anonymous_usage_stats
This flag allow Kalliope to send some stats in order to anonymously evaluate the global usage of Kalliope app by users.
Syntax:
send_anonymous_usage_stats: <boolean>
E.g:
send_anonymous_usage_stats: False