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 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,
                 @Nullable String hliIdList)
          throws InterpretationException
        Interprets the passed string using a particular HLI service and the default locale.
        Parameters:
        text - The text to interpret
        hliIdList - 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 service
        stt - the speech-to-text service to use or null to use the default service
        tts - the text-to-speech service to use or null to use the default service
        hli - the human language text interpreter to use or null to use the default service
        source - the audio source to use or null to use the default source
        sink - the audio sink to use or null to use the default sink
        locale - the locale to use or null to use the default locale
        keyword - the keyword to use during keyword spotting or null to use the default keyword
        listeningItem - 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 service
        stt - the speech-to-text service to use or null to use the default service
        tts - the text-to-speech service to use or null to use the default service
        voice - the voice to use or null to use the default voice or any voice provided by the text-to-speech service matching the locale
        hlis - list of human language text interpreters to use, they are executed in order until the first successful response, or empty to use the default service
        source - the audio source to use or null to use the default source
        sink - the audio sink to use or null to use the default sink
        locale - the locale to use or null to use the default locale
        keyword - the keyword to use during keyword spotting or null to use the default keyword
        listeningItem - 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 service
        tts - the text-to-speech service to use or null to use the default service
        voice - the voice to use or null to use the default voice or any voice provided by the text-to-speech service matching the locale
        hlis - list of human language text interpreters to use, they are executed in order until the first successful response, or empty to use the default service
        source - the audio source to use or null to use the default source
        sink - the audio sink to use or null to use the default sink
        locale - the locale to use or null to use the default locale
        listeningItem - 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

      • 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