com.jogamp.opengl.util.av

## Interface AudioSink

-     public interface AudioSink

- - ### Nested Class Summary

    Nested Classes
    Modifier and Type | Interface and Description
    --- | ---
    `static class` | `AudioSink.AudioDataFrame`
    `static class` | `AudioSink.AudioFormat` Specifies the linear audio PCM format.
    `static class` | `AudioSink.AudioFrame`

  - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `static boolean` | `DEBUG`
    `static AudioSink.AudioFormat` | `DefaultFormat` Default `AudioSink.AudioFormat`, [type PCM, sampleRate 44100, sampleSize 16, channelCount 2, signed, fixedP, !planar, littleEndian].
    `static int` | `DefaultFrameDuration` Default frame duration in millisecond, i.e.
    `static int` | `DefaultInitialQueueSize` Initial audio queue size in milliseconds.
    `static int` | `DefaultQueueGrowAmount` Audio queue grow size in milliseconds.
    `static int` | `DefaultQueueLimitAudioOnly` Audio queue limit w/o video in milliseconds.
    `static int` | `DefaultQueueLimitWithVideo` Audio queue limit w/ video in milliseconds.

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `void` | `destroy()` Destroys this instance, i.e.
    `AudioSink.AudioFrame` | `enqueueData(int pts, ByteBuffer bytes, int byteCount)` Enqueue `byteCount` bytes of the remaining bytes of the given NIO `ByteBuffer` to this sink.
    `void` | `flush()` Flush all queued buffers, implies `pause()`.
    `AudioSink.AudioFormat` | `getChosenFormat()` Returns the `AudioSink.AudioFormat` as chosen by `init(AudioFormat, float, int, int, int)`, i.e.
    `int` | `getEnqueuedFrameCount()`
    `int` | `getFrameCount()` Returns the number of allocated buffers as requested by `init(AudioFormat, float, int, int, int)`.
    `int` | `getFreeFrameCount()` Returns the current number of frames in the sink available for writing.
    `int` | `getMaxSupportedChannels()` Return the maximum number of supported channels.
    `float` | `getPlaySpeed()` Returns the playback speed.
    `AudioSink.AudioFormat` | `getPreferredFormat()` Returns the preferred `AudioSink.AudioFormat` by this sink.
    `int` | `getPTS()` Return the current audio presentation timestamp (PTS) in milliseconds.
    `int` | `getQueuedByteCount()` Returns the current number of bytes queued for playing.
    `int` | `getQueuedFrameCount()` Returns the current number of frames queued for playing.
    `int` | `getQueuedTime()` Returns the current queued frame time in milliseconds for playing.
    `float` | `getVolume()` Returns the volume.
    `boolean` | `init(AudioSink.AudioFormat requestedFormat, float frameDuration, int initialQueueSize, int queueGrowAmount, int queueLimit)` Initializes the sink.
    `boolean` | `isInitialized()` Returns the `initialized state` of this instance.
    `boolean` | `isPlaying()` Returns true, if `play()` has been requested and the sink is still playing, otherwise false.
    `boolean` | `isSupported(AudioSink.AudioFormat format)` Returns true if the given format is supported by the sink, otherwise false.
    `void` | `pause()` Pause playing buffers while keeping enqueued data incl.
    `void` | `play()` Play buffers queued via `#enqueueData(AudioFrame)` from current internal position.
    `boolean` | `setPlaySpeed(float s)` Sets the playback speed.
    `boolean` | `setVolume(float v)` Sets the volume [0f..1f].

- - ### Field Detail

    - #### DEBUG

          static final boolean DEBUG

    - #### DefaultFrameDuration

          static final int DefaultFrameDuration

      Default frame duration in millisecond, i.e. 1 frame per 32 ms.
      See Also:
        Constant Field Values

    - #### DefaultInitialQueueSize

          static final int DefaultInitialQueueSize

      Initial audio queue size in milliseconds. 512 ms, i.e. 16 frames per 32 ms. See `init(AudioFormat, float, int, int, int)`.
      See Also:
        Constant Field Values

    - #### DefaultQueueGrowAmount

          static final int DefaultQueueGrowAmount

      Audio queue grow size in milliseconds. 512 ms, i.e. 16 frames per 32 ms. See `init(AudioFormat, float, int, int, int)`.
      See Also:
        Constant Field Values

    - #### DefaultQueueLimitWithVideo

          static final int DefaultQueueLimitWithVideo

      Audio queue limit w/ video in milliseconds. 3072 ms, i.e. 96 frames per 32 ms. See `init(AudioFormat, float, int, int, int)`.
      See Also:
        Constant Field Values

    - #### DefaultQueueLimitAudioOnly

          static final int DefaultQueueLimitAudioOnly

      Audio queue limit w/o video in milliseconds. 1024 ms, i.e. 32 frames per 32 ms. See `init(AudioFormat, float, int, int, int)`.
      See Also:
        Constant Field Values

    - #### DefaultFormat

          static final AudioSink.AudioFormat DefaultFormat

      Default `AudioSink.AudioFormat`, [type PCM, sampleRate 44100, sampleSize 16, channelCount 2, signed, fixedP, !planar, littleEndian].

  - ### Method Detail

    - #### isInitialized

          boolean isInitialized()

      Returns the `initialized state` of this instance.

      The `initialized state` is affected by this instance overall availability, i.e. after instantiation, as well as by `destroy()`.

    - #### getPlaySpeed

          float getPlaySpeed()

      Returns the playback speed.

    - #### setPlaySpeed

          boolean setPlaySpeed(float s)

      Sets the playback speed.

      To simplify test, play speed is normalized, i.e.

      - `1.0f`: if `Math.abs(1.0f - rate) < 0.01f`
      Returns:
        true if successful, otherwise false, i.e. due to unsupported value range of implementation.

    - #### getVolume

          float getVolume()

      Returns the volume.

    - #### setVolume

          boolean setVolume(float v)

      Sets the volume [0f..1f].

      To simplify test, volume is normalized, i.e.

      - `0.0f`: if `Math.abs(v) < 0.01f`
      - `1.0f`: if `Math.abs(1.0f - v) < 0.01f`
      Returns:
        true if successful, otherwise false, i.e. due to unsupported value range of implementation.

    - #### getPreferredFormat

          AudioSink.AudioFormat getPreferredFormat()

      Returns the preferred `AudioSink.AudioFormat` by this sink.

      The preferred format is guaranteed to be supported and shall reflect this sinks most native format, i.e. best performance w/o data conversion.

      Known `#AudioFormat` attributes considered by implementations:

      - ALAudioSink: `AudioSink.AudioFormat.sampleRate`.
      See Also:
        `#initSink(AudioFormat)`, `isSupported(AudioFormat)`

    - #### getMaxSupportedChannels

          int getMaxSupportedChannels()

      Return the maximum number of supported channels.

    - #### isSupported

          boolean isSupported(AudioSink.AudioFormat format)

      Returns true if the given format is supported by the sink, otherwise false.
      See Also:
        `#initSink(AudioFormat)`, `getPreferredFormat()`

    - #### init

          boolean init(AudioSink.AudioFormat requestedFormat,
                     float frameDuration,
                     int initialQueueSize,
                     int queueGrowAmount,
                     int queueLimit)

      Initializes the sink.

      Implementation must match the given `requestedFormat` `AudioSink.AudioFormat`.

      Caller shall validate `requestedFormat` via `isSupported(AudioFormat)` beforehand and try to find a suitable supported one. `getPreferredFormat()` and `getMaxSupportedChannels()` may help.

      Parameters:
        `requestedFormat` - the requested `AudioSink.AudioFormat`.
        `frameDuration` - average or fixed frame duration in milliseconds helping a caching `AudioSink.AudioFrame` based implementation to determine the frame count in the queue. See `DefaultFrameDuration`.
        `initialQueueSize` - initial time in milliseconds to queue in this sink, see `DefaultInitialQueueSize`.
        `queueGrowAmount` - time in milliseconds to grow queue if full, see `DefaultQueueGrowAmount`.
        `queueLimit` - maximum time in milliseconds the queue can hold (and grow), see `DefaultQueueLimitWithVideo` and `DefaultQueueLimitAudioOnly`.
      Returns:
        true if successful, otherwise false

    - #### getChosenFormat

          AudioSink.AudioFormat getChosenFormat()

      Returns the `AudioSink.AudioFormat` as chosen by `init(AudioFormat, float, int, int, int)`, i.e. it shall match the requestedFormat.

    - #### isPlaying

          boolean isPlaying()

      Returns true, if `play()` has been requested and the sink is still playing, otherwise false.

    - #### play

          void play()

      Play buffers queued via `#enqueueData(AudioFrame)` from current internal position. If no buffers are yet queued or the queue runs empty, playback is being continued when buffers are enqueued later on.
      See Also:
        `#enqueueData(AudioFrame)`, `pause()`

    - #### pause

          void pause()

      Pause playing buffers while keeping enqueued data incl. it's internal position.
      See Also:
        `play()`, `flush()`, `#enqueueData(AudioFrame)`

    - #### flush

          void flush()

      Flush all queued buffers, implies `pause()`.

      `init(AudioFormat, float, int, int, int)` must be called first.

      See Also:
        `play()`, `pause()`, `#enqueueData(AudioFrame)`

    - #### destroy

          void destroy()

      Destroys this instance, i.e. closes all streams and devices allocated.

    - #### getFrameCount

          int getFrameCount()

      Returns the number of allocated buffers as requested by `init(AudioFormat, float, int, int, int)`.

    - #### getEnqueuedFrameCount

          int getEnqueuedFrameCount()

      Returns:
        the current enqueued frames count since `init(AudioFormat, float, int, int, int)`.

    - #### getQueuedFrameCount

          int getQueuedFrameCount()

      Returns the current number of frames queued for playing.

      `init(AudioFormat, float, int, int, int)` must be called first.

    - #### getQueuedByteCount

          int getQueuedByteCount()

      Returns the current number of bytes queued for playing.

      `init(AudioFormat, float, int, int, int)` must be called first.

    - #### getQueuedTime

          int getQueuedTime()

      Returns the current queued frame time in milliseconds for playing.

      `init(AudioFormat, float, int, int, int)` must be called first.

    - #### getPTS

          int getPTS()

      Return the current audio presentation timestamp (PTS) in milliseconds.

    - #### getFreeFrameCount

          int getFreeFrameCount()

      Returns the current number of frames in the sink available for writing.

      `init(AudioFormat, float, int, int, int)` must be called first.

    - #### enqueueData

          AudioSink.AudioFrame enqueueData(int pts,
                                         ByteBuffer bytes,
                                         int byteCount)

      Enqueue `byteCount` bytes of the remaining bytes of the given NIO `ByteBuffer` to this sink.

      The data must comply with the chosen `AudioSink.AudioFormat` as returned by `#initSink(AudioFormat)`.

      `init(AudioFormat, float, int, int, int)` must be called first.

Copyright 2010 JogAmp Community.