Package org.openhab.core.voice
Interface VoiceManager
-
@NonNullByDefault public interface VoiceManager
This service provides functionality around voice services and is the central service to be used directly by others.- Author:
- Kai Kreuzer - Initial contribution, Christoph Weitkamp - Added parameter to adjust the volume, Laurent Garnier - Updated methods startDialog and added method stopDialog
-
-
Method Summary
All Methods Instance Methods Abstract Methods Deprecated Methods Modifier and Type Method Description Set<Voice>
getAllVoices()
Returns a sorted set of all available voices in the system from all TTS services.@Nullable Voice
getDefaultVoice()
Returns the default voice used for TTS.@Nullable HumanLanguageInterpreter
getHLI()
Retrieves a HumanLanguageInterpreter.@Nullable HumanLanguageInterpreter
getHLI(String id)
Retrieves a HumanLanguageInterpreter with the given id.Collection<HumanLanguageInterpreter>
getHLIs()
Retrieves all HumanLanguageInterpreters.List<HumanLanguageInterpreter>
getHLIsByIds(String ids)
Retrieves a HumanLanguageInterpreter collection.List<HumanLanguageInterpreter>
getHLIsByIds(List<String> ids)
Retrieves a HumanLanguageInterpreter collection.@Nullable KSService
getKS()
Retrieves a KS service.@Nullable KSService
getKS(String id)
Retrieves a KS service with the given id.Collection<KSService>
getKSs()
Retrieves all KS services.@Nullable Voice
getPreferredVoice(Set<Voice> voices)
Determines the preferred voice for the currently set locale@Nullable STTService
getSTT()
Retrieves a STT service.@Nullable STTService
getSTT(String id)
Retrieves a STT service with the given id.Collection<STTService>
getSTTs()
Retrieves all STT services.@Nullable TTSService
getTTS()
Retrieves a TTS service.@Nullable TTSService
getTTS(String id)
Retrieves a TTS service with the given id.Collection<TTSService>
getTTSs()
Retrieves all TTS services.String
interpret(String text)
Interprets the passed string using the default services for HLI and locale.String
interpret(String text, @Nullable String hliIdList)
Interprets the passed string using a particular HLI service and the default locale.void
listenAndAnswer()
Executes a simple dialog sequence without keyword spotting using all default services: default audio source listening to retrieve a question or a command (default Speech to Text service), interpretation and handling of the command, and finally playback of the answer on the default audio sink (default Text to Speech service).void
listenAndAnswer(@Nullable STTService stt, @Nullable TTSService tts, @Nullable Voice voice, List<HumanLanguageInterpreter> hlis, @Nullable AudioSource source, @Nullable AudioSink sink, @Nullable Locale locale, @Nullable String listeningItem)
Executes a simple dialog sequence without keyword spotting: audio source listening to retrieve a question or a command (Speech to Text service), interpretation and handling of the command, and finally playback of the answer on the audio sink (Text to Speech service).void
say(String text)
Speaks the passed string using the default TTS service and default audio sink.void
say(String text, @Nullable String voiceId, @Nullable String sinkId)
Speaks the passed string using the provided voiceId and the given audio sink.void
say(String text, @Nullable String voiceId, @Nullable String sinkId, @Nullable PercentType volume)
Speaks the passed string with the given volume using the provided voiceId and the given audio sink.void
say(String text, @Nullable String voiceId, @Nullable PercentType volume)
Speaks the passed string with the given volume using the provided voiceId and the default audio sink.void
say(String text, @Nullable PercentType volume)
Speaks the passed string with the given volume using the default TTS service and default audio sink.void
say(String text, String voiceId)
Speaks the passed string using the provided voiceId and the default audio sink.void
startDialog()
Starts an infinite dialog sequence using all default services: keyword spotting on the default audio source, audio source listening to retrieve a question or a command (default Speech to Text service), interpretation and handling of the command, and finally playback of the answer on the default audio sink (default Text to Speech service).void
startDialog(@Nullable KSService ks, @Nullable STTService stt, @Nullable TTSService tts, @Nullable HumanLanguageInterpreter hli, @Nullable AudioSource source, @Nullable AudioSink sink, @Nullable Locale locale, @Nullable String keyword, @Nullable String listeningItem)
Deprecated.void
startDialog(@Nullable KSService ks, @Nullable STTService stt, @Nullable TTSService tts, @Nullable Voice voice, List<HumanLanguageInterpreter> hlis, @Nullable AudioSource source, @Nullable AudioSink sink, @Nullable Locale locale, @Nullable String keyword, @Nullable String listeningItem)
Starts an infinite dialog sequence: keyword spotting on the audio source, audio source listening to retrieve a question or a command (Speech to Text service), interpretation and handling of the command, and finally playback of the answer on the audio sink (Text to Speech service).void
stopDialog(@Nullable AudioSource source)
Stop the dialog associated to an audio source
-
-
-
Method Detail
-
say
void say(String text)
Speaks the passed string using the default TTS service and default audio sink.- Parameters:
text
- The text to say
-
say
void say(String text, @Nullable PercentType volume)
Speaks the passed string with the given volume using the default TTS service and default audio sink.- Parameters:
text
- The text to sayvolume
- The volume to be used or null if the default notification volume should be used
-
say
void say(String text, String voiceId)
Speaks the passed string using the provided voiceId and the default audio sink. If the voiceId is fully qualified (i.e. with a tts prefix), the according TTS service will be used, otherwise the voiceId is assumed to be available on the default TTS service.- Parameters:
text
- The text to sayvoiceId
- The id of the voice to use (either with or without prefix)
-
say
void say(String text, @Nullable String voiceId, @Nullable PercentType volume)
Speaks the passed string with the given volume using the provided voiceId and the default audio sink. If the voiceId is fully qualified (i.e. with a tts prefix), the according TTS service will be used, otherwise the voiceId is assumed to be available on the default TTS service.- Parameters:
text
- The text to sayvoiceId
- The id of the voice to use (either with or without prefix) or nullvolume
- The volume to be used or null if the default notification volume should be used
-
say
void say(String text, @Nullable String voiceId, @Nullable String sinkId)
Speaks the passed string using the provided voiceId and the given audio sink. If the voiceId is fully qualified (i.e. with a tts prefix), the according TTS service will be used, otherwise the voiceId is assumed to be available on the default TTS service.- Parameters:
text
- The text to sayvoiceId
- The id of the voice to use (either with or without prefix) or nullsinkId
- The id of the audio sink to use or null
-
say
void say(String text, @Nullable String voiceId, @Nullable String sinkId, @Nullable PercentType volume)
Speaks the passed string with the given volume using the provided voiceId and the given audio sink. If the voiceId is fully qualified (i.e. with a tts prefix), the according TTS service will be used, otherwise the voiceId is assumed to be available on the default TTS service.- Parameters:
text
- The text to sayvoiceId
- The id of the voice to use (either with or without prefix) or nullsinkId
- The id of the audio sink to use or nullvolume
- The volume to be used or null if the default notification volume should be used
-
interpret
String interpret(String text) throws InterpretationException
Interprets the passed string using the default services for HLI and locale.- Parameters:
text
- The text to interpret- Returns:
- a human language response
- Throws:
InterpretationException
-
interpret
String interpret(String text, @Nullable String hliIdList) throws InterpretationException
Interprets the passed string using a particular HLI service and the default locale.- Parameters:
text
- The text to interprethliIdList
- Comma separated list of HLI service ids to use or null- Returns:
- a human language response
- Throws:
InterpretationException
-
getPreferredVoice
@Nullable Voice getPreferredVoice(Set<Voice> voices)
Determines the preferred voice for the currently set locale- Parameters:
voices
- a set of voices to chose from- Returns:
- the preferred voice for the current locale, or null if no voice can be found
-
startDialog
void startDialog() throws IllegalStateException
Starts an infinite dialog sequence using all default services: keyword spotting on the default audio source, audio source listening to retrieve a question or a command (default Speech to Text service), interpretation and handling of the command, and finally playback of the answer on the default audio sink (default Text to Speech service). Only one dialog can be started for the default audio source.- Throws:
IllegalStateException
- if required services are not all available or the default locale is not supported by all these services or a dialog is already started for the default audio source
-
startDialog
@Deprecated void startDialog(@Nullable KSService ks, @Nullable STTService stt, @Nullable TTSService tts, @Nullable HumanLanguageInterpreter hli, @Nullable AudioSource source, @Nullable AudioSink sink, @Nullable Locale locale, @Nullable String keyword, @Nullable String listeningItem) throws IllegalStateException
Deprecated.Starts an infinite dialog sequence: keyword spotting on the audio source, audio source listening to retrieve a question or a command (Speech to Text service), interpretation and handling of the command, and finally playback of the answer on the audio sink (Text to Speech service). Only one dialog can be started for an audio source.- Parameters:
ks
- the keyword spotting service to use or null to use the default servicestt
- the speech-to-text service to use or null to use the default servicetts
- the text-to-speech service to use or null to use the default servicehli
- the human language text interpreter to use or null to use the default servicesource
- the audio source to use or null to use the default sourcesink
- the audio sink to use or null to use the default sinklocale
- the locale to use or null to use the default localekeyword
- the keyword to use during keyword spotting or null to use the default keywordlisteningItem
- the item to switch ON while listening to a question- Throws:
IllegalStateException
- if required services are not all available or the provided locale is not supported by all these services or a dialog is already started for this audio source
-
startDialog
void startDialog(@Nullable KSService ks, @Nullable STTService stt, @Nullable TTSService tts, @Nullable Voice voice, List<HumanLanguageInterpreter> hlis, @Nullable AudioSource source, @Nullable AudioSink sink, @Nullable Locale locale, @Nullable String keyword, @Nullable String listeningItem) throws IllegalStateException
Starts an infinite dialog sequence: keyword spotting on the audio source, audio source listening to retrieve a question or a command (Speech to Text service), interpretation and handling of the command, and finally playback of the answer on the audio sink (Text to Speech service). Only one dialog can be started for an audio source.- Parameters:
ks
- the keyword spotting service to use or null to use the default servicestt
- the speech-to-text service to use or null to use the default servicetts
- the text-to-speech service to use or null to use the default servicevoice
- the voice to use or null to use the default voice or any voice provided by the text-to-speech service matching the localehlis
- list of human language text interpreters to use, they are executed in order until the first successful response, or empty to use the default servicesource
- the audio source to use or null to use the default sourcesink
- the audio sink to use or null to use the default sinklocale
- the locale to use or null to use the default localekeyword
- the keyword to use during keyword spotting or null to use the default keywordlisteningItem
- the item to switch ON while listening to a question- Throws:
IllegalStateException
- if required services are not all available or the provided locale is not supported by all these services or a dialog is already started for this audio source
-
stopDialog
void stopDialog(@Nullable AudioSource source) throws IllegalStateException
Stop the dialog associated to an audio source- Parameters:
source
- the audio source or null to consider the default audio source- Throws:
IllegalStateException
- if no dialog is started for the audio source
-
listenAndAnswer
void listenAndAnswer() throws IllegalStateException
Executes a simple dialog sequence without keyword spotting using all default services: default audio source listening to retrieve a question or a command (default Speech to Text service), interpretation and handling of the command, and finally playback of the answer on the default audio sink (default Text to Speech service). Only possible if no dialog processor is already started for the default audio source.- Throws:
IllegalStateException
- if required services are not all available or the provided default locale is not supported by all these services or a dialog is already started for the default audio source
-
listenAndAnswer
void listenAndAnswer(@Nullable STTService stt, @Nullable TTSService tts, @Nullable Voice voice, List<HumanLanguageInterpreter> hlis, @Nullable AudioSource source, @Nullable AudioSink sink, @Nullable Locale locale, @Nullable String listeningItem) throws IllegalStateException
Executes a simple dialog sequence without keyword spotting: audio source listening to retrieve a question or a command (Speech to Text service), interpretation and handling of the command, and finally playback of the answer on the audio sink (Text to Speech service). Only possible if no dialog processor is already started for the audio source.- Parameters:
stt
- the speech-to-text service to use or null to use the default servicetts
- the text-to-speech service to use or null to use the default servicevoice
- the voice to use or null to use the default voice or any voice provided by the text-to-speech service matching the localehlis
- list of human language text interpreters to use, they are executed in order until the first successful response, or empty to use the default servicesource
- the audio source to use or null to use the default sourcesink
- the audio sink to use or null to use the default sinklocale
- the locale to use or null to use the default localelisteningItem
- the item to switch ON while listening to a question- Throws:
IllegalStateException
- if required services are not all available or the provided locale is not supported by all these services or a dialog is already started for this audio source
-
getTTS
@Nullable TTSService getTTS()
Retrieves a TTS service. If a default name is configured and the service available, this is returned. Otherwise, the first available service is returned.- Returns:
- a TTS service or null, if no service is available or if a default is configured, but no according service is found
-
getTTS
@Nullable TTSService getTTS(String id)
Retrieves a TTS service with the given id.- Parameters:
id
- the id of the TTS service- Returns:
- a TTS service or null, if no service with this id exists
-
getTTSs
Collection<TTSService> getTTSs()
Retrieves all TTS services.- Returns:
- a collection of TTS services
-
getSTT
@Nullable STTService getSTT()
Retrieves a STT service. If a default name is configured and the service available, this is returned. Otherwise, the first available service is returned.- Returns:
- a STT service or null, if no service is available or if a default is configured, but no according service is found
-
getSTT
@Nullable STTService getSTT(String id)
Retrieves a STT service with the given id.- Parameters:
id
- the id of the STT service- Returns:
- a STT service or null, if no service with this id exists
-
getSTTs
Collection<STTService> getSTTs()
Retrieves all STT services.- Returns:
- a collection of STT services
-
getKS
@Nullable KSService getKS()
Retrieves a KS service. If a default name is configured and the service available, this is returned. Otherwise, the first available service is returned.- Returns:
- a KS service or null, if no service is available or if a default is configured, but no according service is found
-
getKS
@Nullable KSService getKS(String id)
Retrieves a KS service with the given id.- Parameters:
id
- the id of the KS service- Returns:
- a KS service or null, if no service with this id exists
-
getKSs
Collection<KSService> getKSs()
Retrieves all KS services.- Returns:
- a collection of KS services
-
getHLIsByIds
List<HumanLanguageInterpreter> getHLIsByIds(String ids)
Retrieves a HumanLanguageInterpreter collection. If no services are available returns an empty list.- Parameters:
ids
- Comma separated list of HLI service ids to use- Returns:
- a List
or empty, if none of the services is available
-
getHLIsByIds
List<HumanLanguageInterpreter> getHLIsByIds(List<String> ids)
Retrieves a HumanLanguageInterpreter collection. If no services are available returns an empty list.- Parameters:
ids
- List of HLI service ids to use or null- Returns:
- a List
or empty, if none of the services is available
-
getHLI
@Nullable HumanLanguageInterpreter getHLI()
Retrieves a HumanLanguageInterpreter. If a default name is configured and the service available, this is returned. Otherwise, the first available service is returned.- Returns:
- a HumanLanguageInterpreter or null, if no service is available or if a default is configured, but no according service is found
-
getHLI
@Nullable HumanLanguageInterpreter getHLI(String id)
Retrieves a HumanLanguageInterpreter with the given id.- Parameters:
id
- the id of the HumanLanguageInterpreter- Returns:
- a HumanLanguageInterpreter or null, if no interpreter with this id exists
-
getHLIs
Collection<HumanLanguageInterpreter> getHLIs()
Retrieves all HumanLanguageInterpreters.- Returns:
- a collection of HumanLanguageInterpreters
-
getAllVoices
Set<Voice> getAllVoices()
Returns a sorted set of all available voices in the system from all TTS services. The voices in the set are sorted by:- Voice TTSService label (localized with the default locale)
- Voice locale display name (localized with the default locale)
- Voice label
- Returns:
- a sorted set of available voices
-
getDefaultVoice
@Nullable Voice getDefaultVoice()
Returns the default voice used for TTS.- Returns:
- the default voice or null, if no default voice is configured or if a default is configured, but no according service is found
-
-