Package org.openhab.core.audio

Interface AudioManager

@NonNullByDefault public interface AudioManager
This service provides functionality around audio services and is the central service to be used directly by others.
Author:
Karel Goderis - Initial contribution, Kai Kreuzer - removed unwanted dependencies, Christoph Weitkamp - Added parameter to adjust the volume, Wouter Born - Added methods for getting all sinks and sources

  • Field Details

    • SOUND_DIR

      static final String SOUND_DIR
      Name of the sub-directory of the config folder, holding sound files.
      See Also:

  • Method Details

    • play

      void play(@Nullable AudioStream audioStream)
      Plays the passed audio stream using the default audio sink.
      Parameters:
      audioStream - The audio stream to play or null if streaming should be stopped

    • play

      void play(@Nullable AudioStream audioStream, @Nullable String sinkId)
      Plays the passed audio stream on the given sink.
      Parameters:
      audioStream - The audio stream to play or null if streaming should be stopped
      sinkId - The id of the audio sink to use or null for the default

    • play

      void play(@Nullable AudioStream audioStream, @Nullable String sinkId, @Nullable PercentType volume)
      Plays the passed audio stream on the given sink.
      Parameters:
      audioStream - The audio stream to play or null if streaming should be stopped
      sinkId - The id of the audio sink to use or null for the default
      volume - The volume to be used or null if the default notification volume should be used

    • playFile

      void playFile(String fileName) throws AudioException
      Plays an audio file from the "sounds" folder using the default audio sink.
      Parameters:
      fileName - The file from the "sounds" folder
      Throws:
      AudioException - in case the file does not exist or cannot be opened

    • playFile

      void playFile(String fileName, @Nullable PercentType volume) throws AudioException
      Plays an audio file with the given volume from the "sounds" folder using the default audio sink.
      Parameters:
      fileName - The file from the "sounds" folder
      volume - The volume to be used or null if the default notification volume should be used
      Throws:
      AudioException - in case the file does not exist or cannot be opened

    • playFile

      void playFile(String fileName, @Nullable String sinkId) throws AudioException
      Plays an audio file from the "sounds" folder using the given audio sink.
      Parameters:
      fileName - The file from the "sounds" folder
      sinkId - The id of the audio sink to use or null for the default
      Throws:
      AudioException - in case the file does not exist or cannot be opened

    • playFile

      void playFile(String fileName, @Nullable String sinkId, @Nullable PercentType volume) throws AudioException
      Plays an audio file with the given volume from the "sounds" folder using the given audio sink.
      Parameters:
      fileName - The file from the "sounds" folder
      sinkId - The id of the audio sink to use or null for the default
      volume - The volume to be used or null if the default notification volume should be used
      Throws:
      AudioException - in case the file does not exist or cannot be opened

    • stream

      void stream(@Nullable String url) throws AudioException
      Stream audio from the passed url using the default audio sink.
      Parameters:
      url - The url to stream from or null if streaming should be stopped
      Throws:
      AudioException - in case the url stream cannot be opened

    • stream

      void stream(@Nullable String url, @Nullable String sinkId) throws AudioException
      Stream audio from the passed url to the given sink
      Parameters:
      url - The url to stream from or null if streaming should be stopped
      sinkId - The id of the audio sink to use or null for the default
      Throws:
      AudioException - in case the url stream cannot be opened

    • playMelody

      void playMelody(String melody)
      Parse and synthesize a melody and play it into the default sink. The melody should be a spaced separated list of note names or silences (character 0 or O). You can optionally add the character "'" to increase the note one octave. You can optionally add ":ms" where ms is an int value to customize the note/silence milliseconds duration (defaults to 200ms).
      Parameters:
      melody - The url to stream from or null if streaming should be stopped.

    • playMelody

      void playMelody(String melody, @Nullable String sinkId)
      Parse and synthesize a melody and play it into the given sink. The melody should be a spaced separated list of note names or silences (character 0 or O). You can optionally add the character "'" to increase the note one octave. You can optionally add ":ms" where ms is an int value to customize the note/silence milliseconds duration (defaults to 200ms).
      Parameters:
      melody - The url to stream from or null if streaming should be stopped.
      sinkId - The id of the audio sink to use or null for the default.

    • playMelody

      void playMelody(String melody, @Nullable String sinkId, @Nullable PercentType volume)
      Parse and synthesize a melody and play it into the given sink at the desired volume. The melody should be a spaced separated list of note names or silences (character 0 or O). You can optionally add the character "'" to increase the note one octave. You can optionally add ":ms" where ms is an int value to customize the note/silence milliseconds duration (defaults to 200ms).
      Parameters:
      melody - The url to stream from or null if streaming should be stopped.
      sinkId - The id of the audio sink to use or null for the default.
      volume - The volume to be used or null if the default notification volume should be used

    • getVolume

      PercentType getVolume(@Nullable String sinkId) throws IOException
      Retrieves the current volume of a sink
      Parameters:
      sinkId - the sink to get the volume for or null for the default
      Returns:
      the volume as a value between 0 and 100
      Throws:
      IOException - if the sink is not able to determine the volume

    • setVolume

      void setVolume(PercentType volume, @Nullable String sinkId) throws IOException
      Sets the volume for a sink.
      Parameters:
      volume - the volume to set as a value between 0 and 100
      sinkId - the sink to set the volume for or null for the default
      Throws:
      IOException - if the sink is not able to set the volume

    • getSourceId

      @Nullable String getSourceId()
      Retrieves the default AudioSource id if any.

    • getSource

      @Nullable AudioSource getSource()
      Retrieves an AudioSource. If a default name is configured and the service available, this is returned. If no default name is configured, the first available service is returned, if one exists. If no service with the default name is found, null is returned.
      Returns:
      an AudioSource or null, if no service is available or if a default is configured, but no according service is found

    • getAllSources

      Set<AudioSource> getAllSources()
      Retrieves all audio sources
      Returns:
      all audio sources

    • getSource

      @Nullable AudioSource getSource(@Nullable String sourceId)
      Retrieves the audio sources for a given id
      Parameters:
      sourceId - the id of the audio sources or null for the default
      Returns:
      the audio sources for the id or the default audio sources

    • getSourceIds

      Set<String> getSourceIds(String pattern)
      Get a list of source ids that match a given pattern
      Parameters:
      pattern - pattern to search, can include `*` and `?` placeholders
      Returns:
      ids of matching sources

    • getSinkId

      @Nullable String getSinkId()
      Retrieves the default AudioSink id if any.

    • getSink

      @Nullable AudioSink getSink()
      Retrieves an AudioSink. If a default name is configured and the service available, this is returned. If no default name is configured, the first available service is returned, if one exists. If no service with the default name is found, null is returned.
      Returns:
      an AudioSink or null, if no service is available or if a default is configured, but no according service is found

    • getAllSinks

      Set<AudioSink> getAllSinks()
      Retrieves all audio sinks
      Returns:
      all audio sinks

    • getSink

      @Nullable AudioSink getSink(@Nullable String sinkId)
      Retrieves the sink for a given id
      Parameters:
      sinkId - the id of the sink or null for the default
      Returns:
      the sink instance for the id or the default sink

    • getSinkIds

      Set<String> getSinkIds(String pattern)
      Get a list of sink ids that match a given pattern
      Parameters:
      pattern - pattern to search, can include `*` and `?` placeholders
      Returns:
      ids of matching sinks

    • handleVolumeCommand

      Runnable handleVolumeCommand(@Nullable PercentType volume, AudioSink sink)
      Handles a volume command change and returns a Runnable to restore it. Returning a Runnable allows us to have a no-op Runnable if changing volume back is not needed, and conveniently keeping it as one liner usable in a chain for the caller.
      Parameters:
      volume - The volume to set
      sink - The sink to set the volume to
      Returns:
      A runnable to restore the volume to its previous value, or no-operation if no change is required.