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 Detail

      • SOUND_DIR

        static final String SOUND_DIR
        Name of the sub-directory of the config folder, holding sound files.
        See Also:
        Constant Field Values
    • Method Detail

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