1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
|
/*
* 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.annotation.TestApi;
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
*/
@TestApi
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 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);
}
}
|
