media/apex/java/android/media/BufferingParams.java

/*
 * Copyright 2017 The Android Open Source Project
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 *      http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */

package android.media;

import android.annotation.IntDef;
import android.os.Parcel;
import android.os.Parcelable;

import java.lang.annotation.Retention;
import java.lang.annotation.RetentionPolicy;

/**
 * Structure for source buffering management params.
 *
 * Used by {@link MediaPlayer#getBufferingParams()} and
 * {@link MediaPlayer#setBufferingParams(BufferingParams)}
 * to control source buffering behavior.
 *
 * <p>There are two stages of source buffering in {@link MediaPlayer}: initial buffering
 * (when {@link MediaPlayer} is being prepared) and rebuffering (when {@link MediaPlayer}
 * is playing back source). {@link BufferingParams} includes corresponding marks for each
 * stage of source buffering. The marks are time based (in milliseconds).
 *
 * <p>{@link MediaPlayer} source component has default marks which can be queried by
 * calling {@link MediaPlayer#getBufferingParams()} before any change is made by
 * {@link MediaPlayer#setBufferingParams()}.
 * <ul>
 * <li><strong>initial buffering:</strong> initialMarkMs is used when
 * {@link MediaPlayer} is being prepared. When cached data amount exceeds this mark
 * {@link MediaPlayer} is prepared. </li>
 * <li><strong>rebuffering during playback:</strong> resumePlaybackMarkMs is used when
 * {@link MediaPlayer} is playing back content.
 * <ul>
 * <li> {@link MediaPlayer} has internal mark, namely pausePlaybackMarkMs, to decide when
 * to pause playback if cached data amount runs low. This internal mark varies based on
 * type of data source. </li>
 * <li> When cached data amount exceeds resumePlaybackMarkMs, {@link MediaPlayer} will
 * resume playback if it has been paused due to low cached data amount. The internal mark
 * pausePlaybackMarkMs shall be less than resumePlaybackMarkMs. </li>
 * <li> {@link MediaPlayer} has internal mark, namely pauseRebufferingMarkMs, to decide
 * when to pause rebuffering. Apparently, this internal mark shall be no less than
 * resumePlaybackMarkMs. </li>
 * <li> {@link MediaPlayer} has internal mark, namely resumeRebufferingMarkMs, to decide
 * when to resume buffering. This internal mark varies based on type of data source. This
 * mark shall be larger than pausePlaybackMarkMs, and less than pauseRebufferingMarkMs.
 * </li>
 * </ul> </li>
 * </ul>
 * <p>Users should use {@link Builder} to change {@link BufferingParams}.
 * @hide
 */
public final class BufferingParams implements Parcelable {
    private static final int BUFFERING_NO_MARK = -1;

    // params
    private int mInitialMarkMs = BUFFERING_NO_MARK;

    private int mResumePlaybackMarkMs = BUFFERING_NO_MARK;

    private BufferingParams() {
    }

    /**
     * Return initial buffering mark in milliseconds.
     * @return initial buffering mark in milliseconds
     */
    public int getInitialMarkMs() {
        return mInitialMarkMs;
    }

    /**
     * Return the mark in milliseconds for resuming playback.
     * @return the mark for resuming playback in milliseconds
     */
    public int getResumePlaybackMarkMs() {
        return mResumePlaybackMarkMs;
    }

    /**
     * Builder class for {@link BufferingParams} objects.
     * <p> Here is an example where <code>Builder</code> is used to define the
     * {@link BufferingParams} to be used by a {@link MediaPlayer} instance:
     *
     * <pre class="prettyprint">
     * BufferingParams myParams = mediaplayer.getDefaultBufferingParams();
     * myParams = new BufferingParams.Builder(myParams)
     *         .setInitialMarkMs(10000)
     *         .setResumePlaybackMarkMs(15000)
     *         .build();
     * mediaplayer.setBufferingParams(myParams);
     * </pre>
     */
    public static class Builder {
        private int mInitialMarkMs = BUFFERING_NO_MARK;
        private int mResumePlaybackMarkMs = BUFFERING_NO_MARK;

        /**
         * Constructs a new Builder with the defaults.
         * By default, all marks are -1.
         */
        public Builder() {
        }

        /**
         * Constructs a new Builder from a given {@link BufferingParams} instance
         * @param bp the {@link BufferingParams} object whose data will be reused
         * in the new Builder.
         */
        public Builder(BufferingParams bp) {
            mInitialMarkMs = bp.mInitialMarkMs;
            mResumePlaybackMarkMs = bp.mResumePlaybackMarkMs;
        }

        /**
         * Combines all of the fields that have been set and return a new
         * {@link BufferingParams} object. <code>IllegalStateException</code> will be
         * thrown if there is conflict between fields.
         * @return a new {@link BufferingParams} object
         */
        public BufferingParams build() {
            BufferingParams bp = new BufferingParams();
            bp.mInitialMarkMs = mInitialMarkMs;
            bp.mResumePlaybackMarkMs = mResumePlaybackMarkMs;

            return bp;
        }

        /**
         * Sets the time based mark in milliseconds for initial buffering.
         * @param markMs time based mark in milliseconds
         * @return the same Builder instance.
         */
        public Builder setInitialMarkMs(int markMs) {
            mInitialMarkMs = markMs;
            return this;
        }

        /**
         * Sets the time based mark in milliseconds for resuming playback.
         * @param markMs time based mark in milliseconds for resuming playback
         * @return the same Builder instance.
         */
        public Builder setResumePlaybackMarkMs(int markMs) {
            mResumePlaybackMarkMs = markMs;
            return this;
        }
    }

    private BufferingParams(Parcel in) {
        mInitialMarkMs = in.readInt();
        mResumePlaybackMarkMs = in.readInt();
    }

    public static final @android.annotation.NonNull Parcelable.Creator<BufferingParams> CREATOR =
            new Parcelable.Creator<BufferingParams>() {
                @Override
                public BufferingParams createFromParcel(Parcel in) {
                    return new BufferingParams(in);
                }

                @Override
                public BufferingParams[] newArray(int size) {
                    return new BufferingParams[size];
                }
            };


    @Override
    public int describeContents() {
        return 0;
    }

    @Override
    public void writeToParcel(Parcel dest, int flags) {
        dest.writeInt(mInitialMarkMs);
        dest.writeInt(mResumePlaybackMarkMs);
    }
}