Package com.google.android.exoplayer2.audio

## Interface AudioSink

- All Known Implementing Classes:
    `CapturingAudioSink`, `DefaultAudioSink`, `ForwardingAudioSink`

      public interface AudioSink

  A sink that consumes audio data.

  Before starting playback, specify the input audio format by calling `configure(Format, int, int[])`.

  Call `handleBuffer(ByteBuffer, long, int)` to write data, and `handleDiscontinuity()` when the data being fed is discontinuous. Call `play()` to start playing the written data.

  Call `configure(Format, int, int[])` whenever the input format changes. The sink will be reinitialized on the next call to `handleBuffer(ByteBuffer, long, int)`.

  Call `flush()` to prepare the sink to receive audio data from a new playback position.

  Call `playToEndOfStream()` repeatedly to play out all data when no more input buffers will be provided via `handleBuffer(ByteBuffer, long, int)` until the next `flush()`. Call `reset()` when the instance is no longer required.

  The implementation may be backed by a platform `AudioTrack`. In this case, `setAudioSessionId(int)`, `setAudioAttributes(AudioAttributes)`, `enableTunnelingV21()` and `disableTunneling()` may be called before writing data to the sink. These methods may also be called after writing data to the sink, in which case it will be reinitialized as required. For implementations that are not based on platform `AudioTrack`s, calling methods relating to audio sessions, audio attributes, and tunneling may have no effect.

- - ### Nested Class Summary

    Nested Classes
    Modifier and Type | Interface | Description
    --- | --- | ---
    `static class` | `AudioSink.ConfigurationException` | Thrown when a failure occurs configuring the sink.
    `static class` | `AudioSink.InitializationException` | Thrown when a failure occurs initializing the sink.
    `static interface` | `AudioSink.Listener` | Listener for audio sink events.
    `static interface` | `AudioSink.SinkFormatSupport` | The level of support the sink provides for a format.
    `static class` | `AudioSink.UnexpectedDiscontinuityException` | Thrown when the sink encounters an unexpected timestamp discontinuity.
    `static class` | `AudioSink.WriteException` | Thrown when a failure occurs writing to the sink.

  - ### Field Summary

    Fields
    Modifier and Type | Field | Description
    --- | --- | ---
    `static long` | `CURRENT_POSITION_NOT_SET` | Returned by `getCurrentPositionUs(boolean)` when the position is not set.
    `static int` | `SINK_FORMAT_SUPPORTED_DIRECTLY` | The sink supports the format directly, without the need for internal transcoding.
    `static int` | `SINK_FORMAT_SUPPORTED_WITH_TRANSCODING` | The sink supports the format, but needs to transcode it internally to do so.
    `static int` | `SINK_FORMAT_UNSUPPORTED` | The sink does not support the format.

  - ### Method Summary

    All Methods Instance Methods Abstract Methods Default Methods
    Modifier and Type | Method | Description
    --- | --- | ---
    `void` | `configure​(Format inputFormat, int specifiedBufferSize, int[] outputChannels)` | Configures (or reconfigures) the sink.
    `void` | `disableTunneling()` | Disables tunneling.
    `void` | `enableTunnelingV21()` | Enables tunneling, if possible.
    `void` | `experimentalFlushWithoutAudioTrackRelease()` | Flushes the sink, after which it is ready to receive buffers from a new playback position.
    `void` | `flush()` | Flushes the sink, after which it is ready to receive buffers from a new playback position.
    `AudioAttributes` | `getAudioAttributes()` | Returns the audio attributes used for audio playback, or `null` if the sink does not use audio attributes.
    `long` | `getCurrentPositionUs​(boolean sourceEnded)` | Returns the playback position in the stream starting at zero, in microseconds, or `CURRENT_POSITION_NOT_SET` if it is not yet available.
    `@com.google.android.exoplayer2.audio.AudioSink.SinkFormatSupport int` | `getFormatSupport​(Format format)` | Returns the level of support that the sink provides for a given `Format`.
    `PlaybackParameters` | `getPlaybackParameters()` | Returns the active `PlaybackParameters`.
    `boolean` | `getSkipSilenceEnabled()` | Returns whether silences are skipped in the audio stream.
    `boolean` | `handleBuffer​(ByteBuffer buffer, long presentationTimeUs, int encodedAccessUnitCount)` | Attempts to process data from a `ByteBuffer`, starting from its current position and ending at its limit (exclusive).
    `void` | `handleDiscontinuity()` | Signals to the sink that the next buffer may be discontinuous with the previous buffer.
    `boolean` | `hasPendingData()` | Returns whether the sink has data pending that has not been consumed yet.
    `boolean` | `isEnded()` | Returns whether `playToEndOfStream()` has been called and all buffers have been processed.
    `void` | `pause()` | Pauses playback.
    `void` | `play()` | Starts or resumes consuming audio if initialized.
    `void` | `playToEndOfStream()` | Processes any remaining data.
    `void` | `reset()` | Resets the sink, releasing any resources that it currently holds.
    `void` | `setAudioAttributes​(AudioAttributes audioAttributes)` | Sets attributes for audio playback.
    `void` | `setAudioSessionId​(int audioSessionId)` | Sets the audio session id.
    `void` | `setAuxEffectInfo​(AuxEffectInfo auxEffectInfo)` | Sets the auxiliary effect.
    `void` | `setListener​(AudioSink.Listener listener)` | Sets the listener for sink events, which should be the audio renderer.
    `default void` | `setOutputStreamOffsetUs​(long outputStreamOffsetUs)` | Sets the offset that is added to the media timestamp before it is passed as `presentationTimeUs` in `handleBuffer(ByteBuffer, long, int)`.
    `void` | `setPlaybackParameters​(PlaybackParameters playbackParameters)` | Attempts to set the playback parameters.
    `default void` | `setPlayerId​(PlayerId playerId)` | Sets the `PlayerId` of the player using this audio sink.
    `default void` | `setPreferredDevice​(AudioDeviceInfo audioDeviceInfo)` | Sets the preferred audio device.
    `void` | `setSkipSilenceEnabled​(boolean skipSilenceEnabled)` | Sets whether silences should be skipped in the audio stream.
    `void` | `setVolume​(float volume)` | Sets the playback volume.
    `boolean` | `supportsFormat​(Format format)` | Returns whether the sink supports a given `Format`.

- - ### Field Detail

    - #### SINK_FORMAT_SUPPORTED_DIRECTLY

          static final int SINK_FORMAT_SUPPORTED_DIRECTLY

      The sink supports the format directly, without the need for internal transcoding.
      See Also:
        Constant Field Values

    - #### SINK_FORMAT_SUPPORTED_WITH_TRANSCODING

          static final int SINK_FORMAT_SUPPORTED_WITH_TRANSCODING

      The sink supports the format, but needs to transcode it internally to do so. Internal transcoding may result in lower quality and higher CPU load in some cases.
      See Also:
        Constant Field Values

    - #### SINK_FORMAT_UNSUPPORTED

          static final int SINK_FORMAT_UNSUPPORTED

      The sink does not support the format.
      See Also:
        Constant Field Values

    - #### CURRENT_POSITION_NOT_SET

          static final long CURRENT_POSITION_NOT_SET

      Returned by `getCurrentPositionUs(boolean)` when the position is not set.
      See Also:
        Constant Field Values

  - ### Method Detail

    - #### setListener

          void setListener​(AudioSink.Listener listener)

      Sets the listener for sink events, which should be the audio renderer.
      Parameters:
        `listener` - The listener for sink events, which should be the audio renderer.

    - #### setPlayerId

          default void setPlayerId​(@Nullable
                                   PlayerId playerId)

      Sets the `PlayerId` of the player using this audio sink.
      Parameters:
        `playerId` - The `PlayerId`, or null to clear a previously set id.

    - #### supportsFormat

          boolean supportsFormat​(Format format)

      Returns whether the sink supports a given `Format`.
      Parameters:
        `format` - The format.
      Returns:
        Whether the sink supports the format.

    - #### getFormatSupport

          @com.google.android.exoplayer2.audio.AudioSink.SinkFormatSupport int getFormatSupport​(Format format)

      Returns the level of support that the sink provides for a given `Format`.
      Parameters:
        `format` - The format.
      Returns:
        The level of support provided.

    - #### getCurrentPositionUs

          long getCurrentPositionUs​(boolean sourceEnded)

      Returns the playback position in the stream starting at zero, in microseconds, or `CURRENT_POSITION_NOT_SET` if it is not yet available.
      Parameters:
        `sourceEnded` - Specify `true` if no more input buffers will be provided.
      Returns:
        The playback position relative to the start of playback, in microseconds.

    - #### configure

          void configure​(Format inputFormat,
                         int specifiedBufferSize,
                         @Nullable
                         int[] outputChannels)
                  throws AudioSink.ConfigurationException

      Configures (or reconfigures) the sink.
      Parameters:
        `inputFormat` - The format of audio data provided in the input buffers.
        `specifiedBufferSize` - A specific size for the playback buffer in bytes, or 0 to infer a suitable buffer size.
        `outputChannels` - A mapping from input to output channels that is applied to this sink's input as a preprocessing step, if handling PCM input. Specify `null` to leave the input unchanged. Otherwise, the element at index `i` specifies index of the input channel to map to output channel `i` when preprocessing input buffers. After the map is applied the audio data will have `outputChannels.length` channels.
      Throws:
        `AudioSink.ConfigurationException` - If an error occurs configuring the sink.

    - #### play

          void play()

      Starts or resumes consuming audio if initialized.

    - #### handleDiscontinuity

          void handleDiscontinuity()

      Signals to the sink that the next buffer may be discontinuous with the previous buffer.

    - #### handleBuffer

          boolean handleBuffer​(ByteBuffer buffer,
                               long presentationTimeUs,
                               int encodedAccessUnitCount)
                        throws AudioSink.InitializationException,
                               AudioSink.WriteException

      Attempts to process data from a `ByteBuffer`, starting from its current position and ending at its limit (exclusive). The position of the `ByteBuffer` is advanced by the number of bytes that were handled. `AudioSink.Listener.onPositionDiscontinuity()` will be called if `presentationTimeUs` is discontinuous with the last buffer handled since the last reset.

      Returns whether the data was handled in full. If the data was not handled in full then the same `ByteBuffer` must be provided to subsequent calls until it has been fully consumed, except in the case of an intervening call to `flush()` (or to `configure(Format, int, int[])` that causes the sink to be flushed).

      Parameters:
        `buffer` - The buffer containing audio data.
        `presentationTimeUs` - The presentation timestamp of the buffer in microseconds.
        `encodedAccessUnitCount` - The number of encoded access units in the buffer, or 1 if the buffer contains PCM audio. This allows batching multiple encoded access units in one buffer.
      Returns:
        Whether the buffer was handled fully.
      Throws:
        `AudioSink.InitializationException` - If an error occurs initializing the sink.
        `AudioSink.WriteException` - If an error occurs writing the audio data.

    - #### playToEndOfStream

          void playToEndOfStream()
                          throws AudioSink.WriteException

      Processes any remaining data. `isEnded()` will return `true` when no data remains.
      Throws:
        `AudioSink.WriteException` - If an error occurs draining data to the sink.

    - #### isEnded

          boolean isEnded()

      Returns whether `playToEndOfStream()` has been called and all buffers have been processed.

    - #### hasPendingData

          boolean hasPendingData()

      Returns whether the sink has data pending that has not been consumed yet.

    - #### setPlaybackParameters

          void setPlaybackParameters​(PlaybackParameters playbackParameters)

      Attempts to set the playback parameters. The audio sink may override these parameters if they are not supported.
      Parameters:
        `playbackParameters` - The new playback parameters to attempt to set.

    - #### getPlaybackParameters

          PlaybackParameters getPlaybackParameters()

      Returns the active `PlaybackParameters`.

    - #### setSkipSilenceEnabled

          void setSkipSilenceEnabled​(boolean skipSilenceEnabled)

      Sets whether silences should be skipped in the audio stream.

    - #### getSkipSilenceEnabled

          boolean getSkipSilenceEnabled()

      Returns whether silences are skipped in the audio stream.

    - #### setAudioAttributes

          void setAudioAttributes​(AudioAttributes audioAttributes)

      Sets attributes for audio playback. If the attributes have changed and if the sink is not configured for use with tunneling, then it is reset and the audio session id is cleared.

      If the sink is configured for use with tunneling then the audio attributes are ignored. The sink is not reset and the audio session id is not cleared. The passed attributes will be used if the sink is later re-configured into non-tunneled mode.

      Parameters:
        `audioAttributes` - The attributes for audio playback.

    - #### getAudioAttributes

          @Nullable
          AudioAttributes getAudioAttributes()

      Returns the audio attributes used for audio playback, or `null` if the sink does not use audio attributes.

    - #### setAudioSessionId

          void setAudioSessionId​(int audioSessionId)

      Sets the audio session id.

    - #### setAuxEffectInfo

          void setAuxEffectInfo​(AuxEffectInfo auxEffectInfo)

      Sets the auxiliary effect.

    - #### setPreferredDevice

          @RequiresApi(23)
          default void setPreferredDevice​(@Nullable
                                          AudioDeviceInfo audioDeviceInfo)

      Sets the preferred audio device.
      Parameters:
        `audioDeviceInfo` - The preferred audio device, or null to restore the default.

    - #### setOutputStreamOffsetUs

          default void setOutputStreamOffsetUs​(long outputStreamOffsetUs)

      Sets the offset that is added to the media timestamp before it is passed as `presentationTimeUs` in `handleBuffer(ByteBuffer, long, int)`.
      Parameters:
        `outputStreamOffsetUs` - The output stream offset in microseconds.

    - #### enableTunnelingV21

          void enableTunnelingV21()

      Enables tunneling, if possible. The sink is reset if tunneling was previously disabled. Enabling tunneling is only possible if the sink is based on a platform `AudioTrack`, and requires platform API version 21 onwards.
      Throws:
        `IllegalStateException` - Thrown if enabling tunneling on platform API version < 21.

    - #### disableTunneling

          void disableTunneling()

      Disables tunneling. If tunneling was previously enabled then the sink is reset and any audio session id is cleared.

    - #### setVolume

          void setVolume​(float volume)

      Sets the playback volume.
      Parameters:
        `volume` - Linear output gain to apply to all channels. Should be in the range [0.0, 1.0].

    - #### pause

          void pause()

      Pauses playback.

    - #### flush

          void flush()

      Flushes the sink, after which it is ready to receive buffers from a new playback position.

      The audio session may remain active until `reset()` is called.

    - #### experimentalFlushWithoutAudioTrackRelease

          void experimentalFlushWithoutAudioTrackRelease()

      Flushes the sink, after which it is ready to receive buffers from a new playback position.

      Does not release the `AudioTrack` held by the sink.

      This method is experimental, and will be renamed or removed in a future release.

      Only for experimental use as part of `MediaCodecAudioRenderer.experimentalSetEnableKeepAudioTrackOnSeek(boolean)`.

    - #### reset

          void reset()

      Resets the sink, releasing any resources that it currently holds.