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`
  Builder for `BufferConfiguration` instances.

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

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

- ## 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 final Parcelable.Creator<BufferConfiguration>`
  `CREATOR`
  Creator for Parcelable.
  `static final boolean`
  `DEFAULT_AUDIO_FEED_YIELD`
  The default behaviour for audio renderer when feeding decoder.
  `static final long`
  `DEFAULT_BACK_BUFFER_LENGTH_MS`
  The default minimum back buffer length.
  `static final int`
  `DEFAULT_BUFFER_SEGMENT_SIZE`
  The default buffer segment size.
  `static final int`
  `DEFAULT_BUFFER_SIZE`
  The default buffer size in bytes.
  `static final boolean`
  `DEFAULT_DRAIN_WHILE_CHARGING`
  The default behaviour when charging.
  `static final long`
  `DEFAULT_HIGH_MEDIA_TIME`
  The default value for `highMediaTimeMs`.
  `static final long`
  `DEFAULT_LOW_MEDIA_TIME`
  The default value for `lowMediaTimeMs`.
  `static final int`
  `DEFAULT_MIN_PLAYBACK_START_MS`
  The default minimum playback start buffer.
  `static final int`
  `DEFAULT_MIN_REBUFFER_START_MS`
  The default minimum rebuffer start buffer.
  `static final boolean`
  `DEFAULT_PRIORITIZE_INSTREAM_OVER_MANIFEST_DURATION`
  The default value indicating whether the buffered duration is evaluated based on playlist (manifest) tags like duration or based on audio and video data segments durations
  `static final boolean`
  `DEFAULT_PRIORITIZE_TIME_OVER_SIZE_THRESHOLDS`
  The default value indicating whether the buffer time constraints are prioritized over buffer size constraints
  `static final 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`
  `prioritizeInstreamOverManifestDuration`
  Flag indicating whether the buffered duration is evaluated based on playlist (manifest) tags like duration or based on audio/video data segments durations.
  `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

  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 Details

  - ### 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

  - ### DEFAULT_PRIORITIZE_INSTREAM_OVER_MANIFEST_DURATION

    public static final boolean DEFAULT_PRIORITIZE_INSTREAM_OVER_MANIFEST_DURATION
    The default value indicating whether the buffered duration is evaluated based on playlist (manifest) tags like duration or based on audio and video data segments durations
    See Also:
      - Constant Field Values

  - ### CREATOR

    public static final Parcelable.Creator<BufferConfiguration> CREATOR
    Creator for Parcelable.

  - ### 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.

  - ### prioritizeInstreamOverManifestDuration

    public boolean prioritizeInstreamOverManifestDuration
    Flag indicating whether the buffered duration is evaluated based on playlist (manifest) tags like duration or based on audio/video data segments durations. The playlist and audio/video durations could become significantly different (seconds) after continuous playback (hours) and when the durations from manifest are not matching the audio/video segment durations. It is recommended to use true which is the default, in order for the player not to get into the stalled state after continuous playback.

  - ### 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 Details

  - ### 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 Details

  - ### 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`