Package org.openhab.core.audio

Interface AudioSink

All Known Implementing Classes:
AudioSinkAsync, AudioSinkSync
@NonNullByDefault public interface AudioSink
Definition of an audio output like headphones, a speaker or for writing to a file / clip.
Author:
Harald Kuhn - Initial contribution, Kelly Davis - Modified to match discussion in #584, Christoph Weitkamp - Added getSupportedStreams() and UnsupportedAudioStreamException

  • Method Details

    • getId

      String getId()
      Returns a simple string that uniquely identifies this service
      Returns:
      an id that identifies this service

    • getLabel

      @Nullable String getLabel(@Nullable Locale locale)
      Returns a localized human readable label that can be used within UIs.
      Parameters:
      locale - the locale to provide the label for
      Returns:
      a localized string to be used in UIs

    • process

      @Deprecated void process(@Nullable AudioStream audioStream) throws UnsupportedAudioFormatException, UnsupportedAudioStreamException
      Deprecated.
      Use processAndComplete(AudioStream)
      Processes the passed AudioStream If the passed AudioStream is not supported by this instance, an UnsupportedAudioStreamException is thrown. If the passed AudioStream has an AudioFormat not supported by this instance, an UnsupportedAudioFormatException is thrown. In case the audioStream is null, this should be interpreted as a request to end any currently playing stream. When the stream is not needed anymore, if the stream implements the Disposable interface, the sink should hereafter get rid of it by calling the dispose method.
      Parameters:
      audioStream - the audio stream to play or null to keep quiet
      Throws:
      UnsupportedAudioFormatException - If audioStream format is not supported
      UnsupportedAudioStreamException - If audioStream is not supported

    • processAndComplete

      default CompletableFuture<@Nullable Void> processAndComplete(@Nullable AudioStream audioStream)
      Processes the passed AudioStream, and returns a CompletableFuture that should complete when the sound is fully played. It is the sink responsibility to complete this future. If the passed AudioStream is not supported by this instance, an UnsupportedAudioStreamException is thrown. If the passed AudioStream has an AudioFormat not supported by this instance, an UnsupportedAudioFormatException is thrown. In case the audioStream is null, this should be interpreted as a request to end any currently playing stream. When the stream is not needed anymore, if the stream implements the Disposable interface, the sink should hereafter get rid of it by calling the dispose method.
      Parameters:
      audioStream - the audio stream to play or null to keep quiet
      Returns:
      A future completed when the sound is fully played. The method can instead complete with UnsupportedAudioFormatException if the audioStream format is not supported, or UnsupportedAudioStreamException If audioStream is not supported

    • getSupportedFormats

      Set<AudioFormat> getSupportedFormats()
      Gets a set containing all supported audio formats
      Returns:
      A Set containing all supported audio formats

    • getSupportedStreams

      Set<Class<? extends AudioStream>> getSupportedStreams()
      Gets a set containing all supported audio stream formats
      Returns:
      A Set containing all supported audio stream formats

    • getVolume

      PercentType getVolume() throws IOException
      Gets the volume
      Returns:
      a PercentType value between 0 and 100 representing the actual volume
      Throws:
      IOException - if the volume can not be determined

    • setVolume

      void setVolume(PercentType volume) throws IOException
      Sets the volume
      Parameters:
      volume - a PercentType value between 0 and 100 representing the desired volume
      Throws:
      IOException - if the volume can not be set