Package com.castlabs.android.player

## Class BufferConfiguration

- java.lang.Object
- - com.castlabs.android.player.BufferConfiguration

- All Implemented Interfaces:
    `Parcelable`

      public class BufferConfiguration
      extends Object
      implements Parcelable

  Container object that stores the buffer configuration.

  The primary parameter of the configuration is the buffer size in bytes (see `bufferSizeBytes`.

  Beside the size, you can use this class to configure the parameters that are used to control the buffer state and when downloading data is permitted. The buffer internally maintains two states: "fill" and "drain". If the buffer is in "fill" state, it will permit downloading and adding data to the buffer until both "memory" and "time" are above their upper bounds. Once that happens, the buffer will switch to "drain" mode and no more downloads are permitted until either "time" or "memory" goes below their low values. Once "time" or "memory" are below their lower bounds, the buffer will switch to "fill" mode again.

  The reason why the buffer is not constantly allowing downloads is that during the "drain" phase, the operating system can decide to deactivate the devices network interfaces periodically and safe battery. You can use `PlayerController.setBufferConfiguration(BufferConfiguration)` if you manually start the playback (note this has to be called before you call `PlayerController.open(PlayerConfig)`. Alternatively you can use the Bundle key `SdkConsts.INTENT_BUFFER_CONFIGURATION` and pass a configuration to `PlayerController.open(Bundle)`.

  Since:
    3.3.0

- - ### Nested Class Summary

    Nested Classes
    Modifier and Type | Class | Description
    --- | --- | ---
    `static class` | `BufferConfiguration.Builder` |

    - ### Nested classes/interfaces inherited from interface android.os.Parcelable

      `Parcelable.ClassLoaderCreator<T extends Object>, Parcelable.Creator<T extends Object>`

  - ### Field Summary

    Fields
    Modifier and Type | Field | Description
    --- | --- | ---
    `boolean` | `audioFeedYieldEnabled` | The behaviour for audio renderer when feeding decoder.
    `long` | `backBufferDurationMs` | Maximum duration of the back buffer.
    `int` | `bufferSegmentSize` | The internal buffer is divided into segment and this specifies the size of a single buffer segment.
    `int` | `bufferSizeBytes` | The buffer size in bytes
    `static Parcelable.Creator<BufferConfiguration>` | `CREATOR` |
    `static boolean` | `DEFAULT_AUDIO_FEED_YIELD` | The default behaviour for audio renderer when feeding decoder.
    `static long` | `DEFAULT_BACK_BUFFER_LENGTH_MS` | The default minimum back buffer length.
    `static int` | `DEFAULT_BUFFER_SEGMENT_SIZE` | The default buffer segment size.
    `static int` | `DEFAULT_BUFFER_SIZE` | The default buffer size in bytes.
    `static boolean` | `DEFAULT_DRAIN_WHILE_CHARGING` | The default behaviour when charging.
    `static long` | `DEFAULT_HIGH_MEDIA_TIME` | The default value for `highMediaTimeMs`.
    `static long` | `DEFAULT_LOW_MEDIA_TIME` | The default value for `lowMediaTimeMs`.
    `static int` | `DEFAULT_MIN_PLAYBACK_START_MS` | The default minimum playback start buffer.
    `static int` | `DEFAULT_MIN_REBUFFER_START_MS` | The default minimum rebuffer start buffer.
    `static boolean` | `DEFAULT_PRIORITIZE_TIME_OVER_SIZE_THRESHOLDS` | The default value indicating whether the buffer time constraints are prioritized over buffer size constraints
    `static boolean` | `DEFAULT_VIDEO_FEED_YIELD` | The default behaviour for video renderer when feeding decoder.
    `boolean` | `drainWhileCharging` | Flag indicating whether the buffer should be drained (until `minPlaybackStartMs` is reached) or not.
    `long` | `highMediaTimeMs` | Time in milliseconds that will be used by the buffer controls to determine if the buffer can be drained.
    `long` | `lowMediaTimeMs` | Time in milliseconds that will be used by the buffer controls to determine if the buffer needs to be filled.
    `long` | `minPlaybackStartMs` | The minimum duration of data that must be buffered for playback to start or resume following a user action such as a seek.
    `long` | `minRebufferStartMs` | The minimum duration of data that must be buffered for playback to resume after a player invoked rebuffer (i.e.
    `boolean` | `prioritizeTimeOverSizeThresholds` | Flag indicating whether the buffer time constraints are prioritized over buffer size constraints `lowMediaTimeMs` and `highMediaTimeMs`.
    `boolean` | `videoFeedYieldEnabled` | The behaviour for video renderer when feeding decoder.

    - ### Fields inherited from interface android.os.Parcelable

      `CONTENTS_FILE_DESCRIPTOR, PARCELABLE_WRITE_RETURN_VALUE`

  - ### Constructor Summary

    Constructors
    Constructor | Description
    --- | ---
    `BufferConfiguration()` | Create a new buffer configuration using the default values
    `BufferConfiguration​(int bufferSizeBytes, long lowMediaTimeMs, long highMediaTimeMs)` | Create a new buffer configuration

  - ### Method Summary

    All Methods Instance Methods Concrete Methods
    Modifier and Type | Method | Description
    --- | --- | ---
    `void` | `apply​(BufferConfiguration source)` | Copies the values from the given buffer configuration to this configuration
    `int` | `describeContents()` |
    `boolean` | `equals​(Object obj)` |
    `int` | `hashCode()` |
    `String` | `toString()` |
    `void` | `writeToParcel​(Parcel dest, int flags)` |

    - ### Methods inherited from class java.lang.Object

      `getClass, notify, notifyAll, wait, wait, wait`

- - ### Field Detail

    - #### DEFAULT_BUFFER_SIZE

          public static final int DEFAULT_BUFFER_SIZE

      The default buffer size in bytes. The default is 16 MB.
      See Also:
        Constant Field Values

    - #### DEFAULT_LOW_MEDIA_TIME

          public static final long DEFAULT_LOW_MEDIA_TIME

      The default value for `lowMediaTimeMs`. The default is 15 seconds.
      See Also:
        Constant Field Values

    - #### DEFAULT_HIGH_MEDIA_TIME

          public static final long DEFAULT_HIGH_MEDIA_TIME

      The default value for `highMediaTimeMs`. The default is 60 seconds.
      See Also:
        Constant Field Values

    - #### DEFAULT_BUFFER_SEGMENT_SIZE

          public static final int DEFAULT_BUFFER_SEGMENT_SIZE

      The default buffer segment size. The default is 64 KB
      See Also:
        Constant Field Values

    - #### DEFAULT_MIN_PLAYBACK_START_MS

          public static final int DEFAULT_MIN_PLAYBACK_START_MS

      The default minimum playback start buffer. Default is 2.5 seconds.
      See Also:
        Constant Field Values

    - #### DEFAULT_MIN_REBUFFER_START_MS

          public static final int DEFAULT_MIN_REBUFFER_START_MS

      The default minimum rebuffer start buffer. Default is 5 seconds.
      See Also:
        Constant Field Values

    - #### DEFAULT_DRAIN_WHILE_CHARGING

          public static final boolean DEFAULT_DRAIN_WHILE_CHARGING

      The default behaviour when charging. Default is false.
      See Also:
        Constant Field Values

    - #### DEFAULT_BACK_BUFFER_LENGTH_MS

          public static final long DEFAULT_BACK_BUFFER_LENGTH_MS

      The default minimum back buffer length. Default is 0 seconds.
      See Also:
        Constant Field Values

    - #### DEFAULT_AUDIO_FEED_YIELD

          public static final boolean DEFAULT_AUDIO_FEED_YIELD

      The default behaviour for audio renderer when feeding decoder. Default is `true` meaning audio renderer will not block other renderers (video) when feeding decoder.
      See Also:
        Constant Field Values

    - #### DEFAULT_VIDEO_FEED_YIELD

          public static final boolean DEFAULT_VIDEO_FEED_YIELD

      The default behaviour for video renderer when feeding decoder. Default is `true` meaning video renderer will not block other renderers (audio) when feeding decoder.
      See Also:
        Constant Field Values

    - #### DEFAULT_PRIORITIZE_TIME_OVER_SIZE_THRESHOLDS

          public static final boolean DEFAULT_PRIORITIZE_TIME_OVER_SIZE_THRESHOLDS

      The default value indicating whether the buffer time constraints are prioritized over buffer size constraints
      See Also:
        Constant Field Values

    - #### CREATOR

          public static final Parcelable.Creator<BufferConfiguration> CREATOR

    - #### bufferSizeBytes

          public int bufferSizeBytes

      The buffer size in bytes

    - #### lowMediaTimeMs

          public long lowMediaTimeMs

      Time in milliseconds that will be used by the buffer controls to determine if the buffer needs to be filled. If the buffer contains data that accumulate to less than this time, the buffer can be put in "fill" state.

    - #### highMediaTimeMs

          public long highMediaTimeMs

      Time in milliseconds that will be used by the buffer controls to determine if the buffer can be drained. If the buffer contains data that accumulate to more than this time, the buffer can be put in "drain" state.

    - #### bufferSegmentSize

          public int bufferSegmentSize

      The internal buffer is divided into segment and this specifies the size of a single buffer segment.

    - #### minPlaybackStartMs

          public long minPlaybackStartMs

      The minimum duration of data that must be buffered for playback to start or resume following a user action such as a seek.

    - #### minRebufferStartMs

          public long minRebufferStartMs

      The minimum duration of data that must be buffered for playback to resume after a player invoked rebuffer (i.e. a rebuffer that occurs due to buffer depletion, and not due to a user action such as starting playback or seeking).

    - #### prioritizeTimeOverSizeThresholds

          public boolean prioritizeTimeOverSizeThresholds

      Flag indicating whether the buffer time constraints are prioritized over buffer size constraints `lowMediaTimeMs` and `highMediaTimeMs`. Use `false` to reduce the buffer size up to the value of `bufferSizeBytes` and do not use the mentioned above time constraints.

      Note, however, when set to `false` the buffer size may still go temporarily above the `bufferSizeBytes` in order to put the complete chunk into the buffer. Also, the buffer size will increase always in order to fill `#minPlaybackStartMs` and to allow playback uninterruptedly continue.

    - #### drainWhileCharging

          public boolean drainWhileCharging

      Flag indicating whether the buffer should be drained (until `minPlaybackStartMs` is reached) or not.

      If `false` the buffer will "bounce" around the max state and never reach its min state. This can potentially reduce the chances of hitting a buffer underrun if the battery is charging.

      Since:
        4.1.11

    - #### backBufferDurationMs

          public long backBufferDurationMs

      Maximum duration of the back buffer. In other words, how much time are already played segments to remain in the buffer.

      Note that this value is independent and does not take into account other "forward" buffer parameters such as `bufferSizeBytes`. If this value is too high, it can lead to memory exhaustion.

      Since:
        4.2.0

    - #### audioFeedYieldEnabled

          public boolean audioFeedYieldEnabled

      The behaviour for audio renderer when feeding decoder. Set to `true` in order audio renderer not to block other renderers (video) when feeding decoder.

    - #### videoFeedYieldEnabled

          public boolean videoFeedYieldEnabled

      The behaviour for video renderer when feeding decoder. Set to `true` in order video renderer not to block other renderers (audio) when feeding decoder.

  - ### Constructor Detail

    - #### BufferConfiguration

          public BufferConfiguration()

      Create a new buffer configuration using the default values

    - #### BufferConfiguration

          public BufferConfiguration​(int bufferSizeBytes,
                                     long lowMediaTimeMs,
                                     long highMediaTimeMs)

      Create a new buffer configuration
      Parameters:
        `bufferSizeBytes` - The buffer size in bytes
        `lowMediaTimeMs` - The media time that is considered "low"
        `highMediaTimeMs` - The media time that is considered "high"

  - ### Method Detail

    - #### describeContents

          public int describeContents()

      Specified by:
        `describeContents` in interface `Parcelable`

    - #### writeToParcel

          public void writeToParcel​(Parcel dest,
                                    int flags)

      Specified by:
        `writeToParcel` in interface `Parcelable`

    - #### apply

          public void apply​(BufferConfiguration source)

      Copies the values from the given buffer configuration to this configuration
      Parameters:
        `source` - the source

    - #### toString

          public String toString()

      Overrides:
        `toString` in class `Object`

    - #### hashCode

          public int hashCode()

      Overrides:
        `hashCode` in class `Object`

    - #### equals

          public boolean equals​(Object obj)

      Overrides:
        `equals` in class `Object`