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, Miguel Álvarez - New dialog methods using DialogContext, Miguel Álvarez - Add transcribe method

  • Method Details

    • 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

    • transcribe

      String transcribe(@Nullable String audioSourceId, @Nullable String sttId, @Nullable Locale locale)
      Run speech-to-text using the provided audio source.
      Parameters:
      audioSourceId - Audio source to listen.
      sttId - The id of the speech-to-text service to use or null to use the default.
      locale - The locale to use or null to use the default.
      Returns:
      a human language transcription or empty.

    • transcribe

      String transcribe(AudioStream audioStream, @Nullable String sttId, @Nullable Locale locale)
      Run speech-to-text over the provided audio stream.
      Parameters:
      audioStream - Audio stream to transcribe.
      sttId - The id of the speech-to-text service to use or null to use the default.
      locale - The locale to use or null to use the default.
      Returns:
      a human language transcription or empty.

    • 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 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

    • getDialogContextBuilder

      DialogContext.Builder getDialogContextBuilder()
      Returns a dialog context builder with the default required services and configurations for dialog processing
      Throws:
      IllegalStateException - if some required service is not available

    • getLastDialogContext

      @Nullable DialogContext getLastDialogContext()
      Returns an object with the services and configurations last used for dialog processing if any. The underling value is updated before an active dialog starts to interpret the transcription result.

    • getDialogsContexts

      List<DialogContext> getDialogsContexts()
      Returns a list with the contexts of all running dialogs.

    • startDialog

      void startDialog(DialogContext context) 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:
      context - with the configured services and options for the dialog
      Throws:
      IllegalStateException - if required services are not compatible 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

    • stopDialog

      void stopDialog(DialogContext context) throws IllegalStateException
      Stop the dialog associated to the audio source
      Parameters:
      context - with the configured services and options for the dialog
      Throws:
      IllegalStateException - if no dialog is started for the audio source

    • listenAndAnswer

      void listenAndAnswer(DialogContext context) 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:
      context - with the configured services and options for the dialog
      Throws:
      IllegalStateException - the provided locale is not supported by all these services or a dialog is already started for this audio source

    • registerDialog

      void registerDialog(DialogRegistration registration) throws IllegalStateException
      Register a dialog, so it will be persisted and started any time the required services are available. Only one registration can be done for an audio source.
      Parameters:
      registration - with the desired services ids and options for the dialog
      Throws:
      IllegalStateException - if there is another registration for the same source

    • unregisterDialog

      void unregisterDialog(DialogRegistration registration)
      Removes a dialog registration and stops the associate dialog.
      Parameters:
      registration - with the desired services ids and options for the dialog

    • unregisterDialog

      void unregisterDialog(String sourceId)
      Removes a dialog registration and stops the associate dialog.
      Parameters:
      sourceId - the registration audio source id.

    • getDialogRegistrations

      List<DialogRegistration> getDialogRegistrations()
      List current dialog registrations
      Returns:
      a list of DialogRegistration

    • 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(@Nullable 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(@Nullable 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(@Nullable 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(@Nullable 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(@Nullable 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