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

Method Summary

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.
@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 hliId)	Interprets the passed string using a particular HLI service and the default locale.
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 listening for the keyword that starts a dialog
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)	Starts listening for the keyword that starts a dialog

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 say

volume - 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 say

voiceId - 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 say

voiceId - The id of the voice to use (either with or without prefix) or null

volume - 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 say

voiceId - The id of the voice to use (either with or without prefix) or null

sinkId - 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 say

voiceId - The id of the voice to use (either with or without prefix) or null

sinkId - The id of the audio sink to use or null

volume - 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 hliId)
          throws InterpretationException

Interprets the passed string using a particular HLI service and the default locale.

Parameters:

text - The text to interpret

hliId - The id of the HLI service 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()

Starts listening for the keyword that starts a dialog

Throws:

IllegalStateException - if required services are not available

startDialog

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)

Starts listening for the keyword that starts a dialog

Throws:

IllegalStateException - if required services are not available

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

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:

1. Voice TTSService label (localized with the default locale)
2. Voice locale display name (localized with the default locale)
3. 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