Package ej.audio

Class AudioSink

  • All Implemented Interfaces:
    Closeable, AutoCloseable
    public class AudioSink
extends Object
implements Closeable
    Represents an audio playback stream.

    An audio sink allocates a native buffer when it is opened. The audio sink should be closed with the close() method in order to free the native allocation.

    While the audio sink is open, the native implementation reads audio data continuously from the buffer and plays it on the output device. The writeBuffer(byte[], int, int) method can be used to write a chunk of audio data in the buffer. If audio data is not written fast enough by the application, the output device may play undesired silences. The waitForBufferFlushed() method can be used to wait until all the audio data written in the buffer has been played back.

    The volume of the playback can be configured by calling setVolume(float).

    • Constructor Detail

      • AudioSink

        public AudioSink​(AudioFormat format,
                 int bufferSize)
        Creates and opens an audio sink.
        Parameters:
        format - the format.
        bufferSize - the buffer size (in bytes).
        Throws:
        IllegalArgumentException - if the given buffer size is less than or equal to zero.
        AudioException - if the audio sink could not be opened.
        SecurityException - if a security manager exists and does not allow the caller to create an audio sink.

    • Method Detail

      • getFormat

        public AudioFormat getFormat()
        Returns the format of this audio sink.
        Returns:
        the format.

      • getBufferSize

        public int getBufferSize()
        Returns the buffer size of this audio sink.
        Returns:
        the buffer size (in bytes).

      • isClosed

        public boolean isClosed()
        Returns whether this audio sink is closed.
        Returns:
        whether this audio sink is closed.

      • close

        public void close()
        Closes this audio sink.

        This method releases the native resources allocated when opening this audio sink. This method does nothing if this audio sink is already closed.

        Specified by:
        close in interface AutoCloseable
        Specified by:
        close in interface Closeable

      • setVolume

        public void setVolume​(float gain)
        Sets the volume of this audio sink.
        Parameters:
        gain - the gain (between 0.0f and 1.0f).

      • writeBuffer

        public int writeBuffer​(byte[] array,
                       int offset,
                       int size)
        Writes audio data in the buffer of this audio sink.

        This method blocks until the requested size has been written, until this audio sink is closed or until the thread is interrupted.

        The number of bytes written may be different from the given size if this audio sink is closed or until the thread is interrupted.

        Parameters:
        array - the array containing the data to write.
        offset - the offset in the array of the first byte to write.
        size - the maximum number of bytes to write.
        Returns:
        the number of bytes written.
        Throws:
        IndexOutOfBoundsException - if the given offset or the given size is invalid.
        SecurityException - if a security manager exists and does not allow the caller to write in the buffer.

      • waitForBufferFlushed

        public boolean waitForBufferFlushed()
        Waits for the buffer of this audio sink to be flushed.

        This method blocks until the buffer is empty (until all the audio data has been played back), until this audio sink is closed or until the thread is interrupted.

        Returns:
        true if the buffer is empty, false if this audio sink is closed or the thread is interrupted.
        Throws:
        SecurityException - if a security manager exists and does not allow the caller to wait for the buffer.