Package org.openhab.core.audio

Interface AudioHTTPServer

@NonNullByDefault public interface AudioHTTPServer
This is an interface that is implemented by AudioServlet and which allows exposing audio streams through HTTP. Streams are only served a single time and then discarded.
Author:
Kai Kreuzer - Initial contribution

  • Method Details

    • serve

      @Deprecated String serve(AudioStream stream)
      Deprecated.
      Use serve(AudioStream, int, boolean)
      Creates a relative url for a given AudioStream where it can be requested a single time. Note that the HTTP header only contains "Content-length", if the passed stream is an instance of SizeableAudioStream. If the client that requests the url expects this header field to be present, make sure to pass such an instance. Streams are closed after having been served.
      Parameters:
      stream - the stream to serve on HTTP
      Returns:
      the relative URL to access the stream starting with a '/'

    • serve

      @Deprecated String serve(AudioStream stream, int seconds)
      Deprecated.
      Use serve(AudioStream, int, boolean)
      Creates a relative url for a given AudioStream where it can be requested multiple times within the given time frame. This method accepts all AudioStreams, but it is better to use ClonableAudioStreams. If generic AudioStream is used, the method tries to add the Clonable capability by storing it in a small memory buffer, e.g ByteArrayAudioStream, or in a cached file if the stream reached the buffer capacity, or fails if the stream is too long. Streams are closed, once they expire.
      Parameters:
      stream - the stream to serve on HTTP
      seconds - number of seconds for which the stream is available through HTTP
      Returns:
      the relative URL to access the stream starting with a '/'

    • serve

      StreamServed serve(AudioStream stream, int seconds, boolean multiTimeStream) throws IOException
      Creates a relative url for a given AudioStream where it can be requested one or multiple times within the given time frame. This method accepts all AudioStreams, but if multiTimeStream is set to true it is better to use ClonableAudioStreams. Otherwise, if a generic AudioStream is used, the method will then try to add the Clonable capability by storing it in a small memory buffer, e.g ByteArrayAudioStream, or in a cached file if the stream reached the buffer capacity, or fails to render the sound completely if the stream is too long. A CompletableFuture is used to inform the caller that the playback ends in order to clean resources and run delayed task, such as restoring volume. Streams are closed, once they expire.
      Parameters:
      stream - the stream to serve on HTTP
      seconds - number of seconds for which the stream is available through HTTP. The stream will be deleted only if not started, so you can set a duration shorter than the track's duration.
      multiTimeStream - set to true if this stream should be played multiple time, and thus needs to be made Cloneable if it is not already.
      Returns:
      information about the StreamServed, including the relative URL to access the stream starting with a '/', and a CompletableFuture to know when the playback ends.
      Throws:
      IOException - when the stream is not a ClonableAudioStream and we cannot get or store it on disk.