1 /*
2  * Copyright 2017 The Android Open Source Project
3  *
4  * Licensed under the Apache License, Version 2.0 (the "License");
5  * you may not use this file except in compliance with the License.
6  * You may obtain a copy of the License at
7  *
8  *      http://www.apache.org/licenses/LICENSE-2.0
9  *
10  * Unless required by applicable law or agreed to in writing, software
11  * distributed under the License is distributed on an "AS IS" BASIS,
12  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13  * See the License for the specific language governing permissions and
14  * limitations under the License.
15  */
16 
17 package android.media;
18 
19 import android.os.Parcel;
20 import android.os.Parcelable;
21 
22 /**
23  * Structure for source buffering management params.
24  *
25  * Used by {@link MediaPlayer#getBufferingParams()} and
26  * {@link MediaPlayer#setBufferingParams(BufferingParams)}
27  * to control source buffering behavior.
28  *
29  * <p>There are two stages of source buffering in {@link MediaPlayer}: initial buffering
30  * (when {@link MediaPlayer} is being prepared) and rebuffering (when {@link MediaPlayer}
31  * is playing back source). {@link BufferingParams} includes corresponding marks for each
32  * stage of source buffering. The marks are time based (in milliseconds).
33  *
34  * <p>{@link MediaPlayer} source component has default marks which can be queried by
35  * calling {@link MediaPlayer#getBufferingParams()} before any change is made by
36  * {@link MediaPlayer#setBufferingParams()}.
37  * <ul>
38  * <li><strong>initial buffering:</strong> initialMarkMs is used when
39  * {@link MediaPlayer} is being prepared. When cached data amount exceeds this mark
40  * {@link MediaPlayer} is prepared. </li>
41  * <li><strong>rebuffering during playback:</strong> resumePlaybackMarkMs is used when
42  * {@link MediaPlayer} is playing back content.
43  * <ul>
44  * <li> {@link MediaPlayer} has internal mark, namely pausePlaybackMarkMs, to decide when
45  * to pause playback if cached data amount runs low. This internal mark varies based on
46  * type of data source. </li>
47  * <li> When cached data amount exceeds resumePlaybackMarkMs, {@link MediaPlayer} will
48  * resume playback if it has been paused due to low cached data amount. The internal mark
49  * pausePlaybackMarkMs shall be less than resumePlaybackMarkMs. </li>
50  * <li> {@link MediaPlayer} has internal mark, namely pauseRebufferingMarkMs, to decide
51  * when to pause rebuffering. Apparently, this internal mark shall be no less than
52  * resumePlaybackMarkMs. </li>
53  * <li> {@link MediaPlayer} has internal mark, namely resumeRebufferingMarkMs, to decide
54  * when to resume buffering. This internal mark varies based on type of data source. This
55  * mark shall be larger than pausePlaybackMarkMs, and less than pauseRebufferingMarkMs.
56  * </li>
57  * </ul> </li>
58  * </ul>
59  * <p>Users should use {@link Builder} to change {@link BufferingParams}.
60  * @hide
61  */
62 public final class BufferingParams implements Parcelable {
63     private static final int BUFFERING_NO_MARK = -1;
64 
65     // params
66     private int mInitialMarkMs = BUFFERING_NO_MARK;
67 
68     private int mResumePlaybackMarkMs = BUFFERING_NO_MARK;
69 
BufferingParams()70     private BufferingParams() {
71     }
72 
73     /**
74      * Return initial buffering mark in milliseconds.
75      * @return initial buffering mark in milliseconds
76      */
getInitialMarkMs()77     public int getInitialMarkMs() {
78         return mInitialMarkMs;
79     }
80 
81     /**
82      * Return the mark in milliseconds for resuming playback.
83      * @return the mark for resuming playback in milliseconds
84      */
getResumePlaybackMarkMs()85     public int getResumePlaybackMarkMs() {
86         return mResumePlaybackMarkMs;
87     }
88 
89     /**
90      * Builder class for {@link BufferingParams} objects.
91      * <p> Here is an example where <code>Builder</code> is used to define the
92      * {@link BufferingParams} to be used by a {@link MediaPlayer} instance:
93      *
94      * <pre class="prettyprint">
95      * BufferingParams myParams = mediaplayer.getDefaultBufferingParams();
96      * myParams = new BufferingParams.Builder(myParams)
97      *         .setInitialMarkMs(10000)
98      *         .setResumePlaybackMarkMs(15000)
99      *         .build();
100      * mediaplayer.setBufferingParams(myParams);
101      * </pre>
102      */
103     public static class Builder {
104         private int mInitialMarkMs = BUFFERING_NO_MARK;
105         private int mResumePlaybackMarkMs = BUFFERING_NO_MARK;
106 
107         /**
108          * Constructs a new Builder with the defaults.
109          * By default, all marks are -1.
110          */
Builder()111         public Builder() {
112         }
113 
114         /**
115          * Constructs a new Builder from a given {@link BufferingParams} instance
116          * @param bp the {@link BufferingParams} object whose data will be reused
117          * in the new Builder.
118          */
Builder(BufferingParams bp)119         public Builder(BufferingParams bp) {
120             mInitialMarkMs = bp.mInitialMarkMs;
121             mResumePlaybackMarkMs = bp.mResumePlaybackMarkMs;
122         }
123 
124         /**
125          * Combines all of the fields that have been set and return a new
126          * {@link BufferingParams} object. <code>IllegalStateException</code> will be
127          * thrown if there is conflict between fields.
128          * @return a new {@link BufferingParams} object
129          */
build()130         public BufferingParams build() {
131             BufferingParams bp = new BufferingParams();
132             bp.mInitialMarkMs = mInitialMarkMs;
133             bp.mResumePlaybackMarkMs = mResumePlaybackMarkMs;
134 
135             return bp;
136         }
137 
138         /**
139          * Sets the time based mark in milliseconds for initial buffering.
140          * @param markMs time based mark in milliseconds
141          * @return the same Builder instance.
142          */
setInitialMarkMs(int markMs)143         public Builder setInitialMarkMs(int markMs) {
144             mInitialMarkMs = markMs;
145             return this;
146         }
147 
148         /**
149          * Sets the time based mark in milliseconds for resuming playback.
150          * @param markMs time based mark in milliseconds for resuming playback
151          * @return the same Builder instance.
152          */
setResumePlaybackMarkMs(int markMs)153         public Builder setResumePlaybackMarkMs(int markMs) {
154             mResumePlaybackMarkMs = markMs;
155             return this;
156         }
157     }
158 
BufferingParams(Parcel in)159     private BufferingParams(Parcel in) {
160         mInitialMarkMs = in.readInt();
161         mResumePlaybackMarkMs = in.readInt();
162     }
163 
164     public static final @android.annotation.NonNull Parcelable.Creator<BufferingParams> CREATOR =
165             new Parcelable.Creator<BufferingParams>() {
166                 @Override
167                 public BufferingParams createFromParcel(Parcel in) {
168                     return new BufferingParams(in);
169                 }
170 
171                 @Override
172                 public BufferingParams[] newArray(int size) {
173                     return new BufferingParams[size];
174                 }
175             };
176 
177 
178     @Override
describeContents()179     public int describeContents() {
180         return 0;
181     }
182 
183     @Override
writeToParcel(Parcel dest, int flags)184     public void writeToParcel(Parcel dest, int flags) {
185         dest.writeInt(mInitialMarkMs);
186         dest.writeInt(mResumePlaybackMarkMs);
187     }
188 }
189