• Home
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
1 /*
2  * Copyright (C) 2006 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 static android.Manifest.permission.BIND_IMS_SERVICE;
20 import static android.content.pm.PackageManager.PERMISSION_GRANTED;
21 
22 import android.annotation.IntDef;
23 import android.annotation.NonNull;
24 import android.annotation.Nullable;
25 import android.annotation.RequiresPermission;
26 import android.annotation.SystemApi;
27 import android.app.ActivityThread;
28 import android.compat.annotation.UnsupportedAppUsage;
29 import android.content.AttributionSource;
30 import android.content.AttributionSource.ScopedParcelState;
31 import android.content.ContentProvider;
32 import android.content.ContentResolver;
33 import android.content.Context;
34 import android.content.res.AssetFileDescriptor;
35 import android.graphics.SurfaceTexture;
36 import android.media.SubtitleController.Anchor;
37 import android.media.SubtitleTrack.RenderingWidget;
38 import android.net.Uri;
39 import android.os.Build;
40 import android.os.Bundle;
41 import android.os.FileUtils;
42 import android.os.Handler;
43 import android.os.HandlerThread;
44 import android.os.IBinder;
45 import android.os.Looper;
46 import android.os.Message;
47 import android.os.Parcel;
48 import android.os.ParcelFileDescriptor;
49 import android.os.Parcelable;
50 import android.os.PersistableBundle;
51 import android.os.PowerManager;
52 import android.os.Process;
53 import android.os.SystemProperties;
54 import android.provider.Settings;
55 import android.system.ErrnoException;
56 import android.system.Os;
57 import android.system.OsConstants;
58 import android.util.ArrayMap;
59 import android.util.Log;
60 import android.util.Pair;
61 import android.view.Surface;
62 import android.view.SurfaceHolder;
63 import android.widget.VideoView;
64 
65 import com.android.internal.annotations.GuardedBy;
66 import com.android.internal.util.Preconditions;
67 
68 import libcore.io.IoBridge;
69 import libcore.io.Streams;
70 
71 import java.io.ByteArrayOutputStream;
72 import java.io.File;
73 import java.io.FileDescriptor;
74 import java.io.FileInputStream;
75 import java.io.IOException;
76 import java.io.InputStream;
77 import java.lang.annotation.Retention;
78 import java.lang.annotation.RetentionPolicy;
79 import java.lang.ref.WeakReference;
80 import java.net.CookieHandler;
81 import java.net.CookieManager;
82 import java.net.HttpCookie;
83 import java.net.HttpURLConnection;
84 import java.net.InetSocketAddress;
85 import java.net.URL;
86 import java.nio.ByteOrder;
87 import java.util.Arrays;
88 import java.util.BitSet;
89 import java.util.HashMap;
90 import java.util.List;
91 import java.util.Map;
92 import java.util.Objects;
93 import java.util.Scanner;
94 import java.util.Set;
95 import java.util.UUID;
96 import java.util.Vector;
97 import java.util.concurrent.Executor;
98 
99 /**
100  * MediaPlayer class can be used to control playback of audio/video files and streams.
101  *
102  * <p>MediaPlayer is not thread-safe. Creation of and all access to player instances
103  * should be on the same thread. If registering <a href="#Callbacks">callbacks</a>,
104  * the thread must have a Looper.
105  *
106  * <p>Topics covered here are:
107  * <ol>
108  * <li><a href="#StateDiagram">State Diagram</a>
109  * <li><a href="#Valid_and_Invalid_States">Valid and Invalid States</a>
110  * <li><a href="#Permissions">Permissions</a>
111  * <li><a href="#Callbacks">Register informational and error callbacks</a>
112  * </ol>
113  *
114  * <div class="special reference">
115  * <h3>Developer Guides</h3>
116  * <p>For more information about how to use MediaPlayer, read the
117  * <a href="{@docRoot}guide/topics/media/mediaplayer.html">Media Playback</a> developer guide.</p>
118  * </div>
119  *
120  * <a name="StateDiagram"></a>
121  * <h3>State Diagram</h3>
122  *
123  * <p>Playback control of audio/video files and streams is managed as a state
124  * machine. The following diagram shows the life cycle and the states of a
125  * MediaPlayer object driven by the supported playback control operations.
126  * The ovals represent the states a MediaPlayer object may reside
127  * in. The arcs represent the playback control operations that drive the object
128  * state transition. There are two types of arcs. The arcs with a single arrow
129  * head represent synchronous method calls, while those with
130  * a double arrow head represent asynchronous method calls.</p>
131  *
132  * <p><img src="../../../images/mediaplayer_state_diagram.gif"
133  *         alt="MediaPlayer State diagram"
134  *         border="0" /></p>
135  *
136  * <p>From this state diagram, one can see that a MediaPlayer object has the
137  *    following states:</p>
138  * <ul>
139  *     <li>When a MediaPlayer object is just created using <code>new</code> or
140  *         after {@link #reset()} is called, it is in the <em>Idle</em> state; and after
141  *         {@link #release()} is called, it is in the <em>End</em> state. Between these
142  *         two states is the life cycle of the MediaPlayer object.
143  *         <ul>
144  *         <li>There is a subtle but important difference between a newly constructed
145  *         MediaPlayer object and the MediaPlayer object after {@link #reset()}
146  *         is called. It is a programming error to invoke methods such
147  *         as {@link #getCurrentPosition()},
148  *         {@link #getDuration()}, {@link #getVideoHeight()},
149  *         {@link #getVideoWidth()}, {@link #setAudioAttributes(AudioAttributes)},
150  *         {@link #setLooping(boolean)},
151  *         {@link #setVolume(float, float)}, {@link #pause()}, {@link #start()},
152  *         {@link #stop()}, {@link #seekTo(long, int)}, {@link #prepare()} or
153  *         {@link #prepareAsync()} in the <em>Idle</em> state for both cases. If any of these
154  *         methods is called right after a MediaPlayer object is constructed,
155  *         the user supplied callback method OnErrorListener.onError() won't be
156  *         called by the internal player engine and the object state remains
157  *         unchanged; but if these methods are called right after {@link #reset()},
158  *         the user supplied callback method OnErrorListener.onError() will be
159  *         invoked by the internal player engine and the object will be
160  *         transfered to the <em>Error</em> state. </li>
161  *         <li>You must keep a reference to a MediaPlayer instance to prevent it from being garbage
162  *         collected. If a MediaPlayer instance is garbage collected, {@link #release} will be
163  *         called, causing any ongoing playback to stop.
164  *         <li>You must call {@link #release()} once you have finished using an instance to release
165  *         acquired resources, such as memory and codecs. Once you have called {@link #release}, you
166  *         must no longer interact with the released instance.
167  *         <li>MediaPlayer objects created using <code>new</code> is in the
168  *         <em>Idle</em> state, while those created with one
169  *         of the overloaded convenient <code>create</code> methods are <em>NOT</em>
170  *         in the <em>Idle</em> state. In fact, the objects are in the <em>Prepared</em>
171  *         state if the creation using <code>create</code> method is successful.
172  *         </li>
173  *         </ul>
174  *         </li>
175  *     <li>In general, some playback control operation may fail due to various
176  *         reasons, such as unsupported audio/video format, poorly interleaved
177  *         audio/video, resolution too high, streaming timeout, and the like.
178  *         Thus, error reporting and recovery is an important concern under
179  *         these circumstances. Sometimes, due to programming errors, invoking a playback
180  *         control operation in an invalid state may also occur. Under all these
181  *         error conditions, the internal player engine invokes a user supplied
182  *         OnErrorListener.onError() method if an OnErrorListener has been
183  *         registered beforehand via
184  *         {@link #setOnErrorListener(android.media.MediaPlayer.OnErrorListener)}.
185  *         <ul>
186  *         <li>It is important to note that once an error occurs, the
187  *         MediaPlayer object enters the <em>Error</em> state (except as noted
188  *         above), even if an error listener has not been registered by the application.</li>
189  *         <li>In order to reuse a MediaPlayer object that is in the <em>
190  *         Error</em> state and recover from the error,
191  *         {@link #reset()} can be called to restore the object to its <em>Idle</em>
192  *         state.</li>
193  *         <li>It is good programming practice to have your application
194  *         register a OnErrorListener to look out for error notifications from
195  *         the internal player engine.</li>
196  *         <li>IllegalStateException is
197  *         thrown to prevent programming errors such as calling {@link #prepare()},
198  *         {@link #prepareAsync()}, or one of the overloaded <code>setDataSource
199  *         </code> methods in an invalid state. </li>
200  *         </ul>
201  *         </li>
202  *     <li>Calling
203  *         {@link #setDataSource(FileDescriptor)}, or
204  *         {@link #setDataSource(String)}, or
205  *         {@link #setDataSource(Context, Uri)}, or
206  *         {@link #setDataSource(FileDescriptor, long, long)}, or
207  *         {@link #setDataSource(MediaDataSource)} transfers a
208  *         MediaPlayer object in the <em>Idle</em> state to the
209  *         <em>Initialized</em> state.
210  *         <ul>
211  *         <li>An IllegalStateException is thrown if
212  *         setDataSource() is called in any other state.</li>
213  *         <li>It is good programming
214  *         practice to always look out for <code>IllegalArgumentException</code>
215  *         and <code>IOException</code> that may be thrown from the overloaded
216  *         <code>setDataSource</code> methods.</li>
217  *         </ul>
218  *         </li>
219  *     <li>A MediaPlayer object must first enter the <em>Prepared</em> state
220  *         before playback can be started.
221  *         <ul>
222  *         <li>There are two ways (synchronous vs.
223  *         asynchronous) that the <em>Prepared</em> state can be reached:
224  *         either a call to {@link #prepare()} (synchronous) which
225  *         transfers the object to the <em>Prepared</em> state once the method call
226  *         returns, or a call to {@link #prepareAsync()} (asynchronous) which
227  *         first transfers the object to the <em>Preparing</em> state after the
228  *         call returns (which occurs almost right away) while the internal
229  *         player engine continues working on the rest of preparation work
230  *         until the preparation work completes. When the preparation completes or when {@link #prepare()} call returns,
231  *         the internal player engine then calls a user supplied callback method,
232  *         onPrepared() of the OnPreparedListener interface, if an
233  *         OnPreparedListener is registered beforehand via {@link
234  *         #setOnPreparedListener(android.media.MediaPlayer.OnPreparedListener)}.</li>
235  *         <li>It is important to note that
236  *         the <em>Preparing</em> state is a transient state, and the behavior
237  *         of calling any method with side effect while a MediaPlayer object is
238  *         in the <em>Preparing</em> state is undefined.</li>
239  *         <li>An IllegalStateException is
240  *         thrown if {@link #prepare()} or {@link #prepareAsync()} is called in
241  *         any other state.</li>
242  *         <li>While in the <em>Prepared</em> state, properties
243  *         such as audio/sound volume, screenOnWhilePlaying, looping can be
244  *         adjusted by invoking the corresponding set methods.</li>
245  *         </ul>
246  *         </li>
247  *     <li>To start the playback, {@link #start()} must be called. After
248  *         {@link #start()} returns successfully, the MediaPlayer object is in the
249  *         <em>Started</em> state. {@link #isPlaying()} can be called to test
250  *         whether the MediaPlayer object is in the <em>Started</em> state.
251  *         <ul>
252  *         <li>While in the <em>Started</em> state, the internal player engine calls
253  *         a user supplied OnBufferingUpdateListener.onBufferingUpdate() callback
254  *         method if a OnBufferingUpdateListener has been registered beforehand
255  *         via {@link #setOnBufferingUpdateListener(OnBufferingUpdateListener)}.
256  *         This callback allows applications to keep track of the buffering status
257  *         while streaming audio/video.</li>
258  *         <li>Calling {@link #start()} has no effect
259  *         on a MediaPlayer object that is already in the <em>Started</em> state.</li>
260  *         </ul>
261  *         </li>
262  *     <li>Playback can be paused and stopped, and the current playback position
263  *         can be adjusted. Playback can be paused via {@link #pause()}. When the call to
264  *         {@link #pause()} returns, the MediaPlayer object enters the
265  *         <em>Paused</em> state. Note that the transition from the <em>Started</em>
266  *         state to the <em>Paused</em> state and vice versa happens
267  *         asynchronously in the player engine. It may take some time before
268  *         the state is updated in calls to {@link #isPlaying()}, and it can be
269  *         a number of seconds in the case of streamed content.
270  *         <ul>
271  *         <li>Calling {@link #start()} to resume playback for a paused
272  *         MediaPlayer object, and the resumed playback
273  *         position is the same as where it was paused. When the call to
274  *         {@link #start()} returns, the paused MediaPlayer object goes back to
275  *         the <em>Started</em> state.</li>
276  *         <li>Calling {@link #pause()} has no effect on
277  *         a MediaPlayer object that is already in the <em>Paused</em> state.</li>
278  *         </ul>
279  *         </li>
280  *     <li>Calling  {@link #stop()} stops playback and causes a
281  *         MediaPlayer in the <em>Started</em>, <em>Paused</em>, <em>Prepared
282  *         </em> or <em>PlaybackCompleted</em> state to enter the
283  *         <em>Stopped</em> state.
284  *         <ul>
285  *         <li>Once in the <em>Stopped</em> state, playback cannot be started
286  *         until {@link #prepare()} or {@link #prepareAsync()} are called to set
287  *         the MediaPlayer object to the <em>Prepared</em> state again.</li>
288  *         <li>Calling {@link #stop()} has no effect on a MediaPlayer
289  *         object that is already in the <em>Stopped</em> state.</li>
290  *         </ul>
291  *         </li>
292  *     <li>The playback position can be adjusted with a call to
293  *         {@link #seekTo(long, int)}.
294  *         <ul>
295  *         <li>Although the asynchronuous {@link #seekTo(long, int)}
296  *         call returns right away, the actual seek operation may take a while to
297  *         finish, especially for audio/video being streamed. When the actual
298  *         seek operation completes, the internal player engine calls a user
299  *         supplied OnSeekComplete.onSeekComplete() if an OnSeekCompleteListener
300  *         has been registered beforehand via
301  *         {@link #setOnSeekCompleteListener(OnSeekCompleteListener)}.</li>
302  *         <li>Please
303  *         note that {@link #seekTo(long, int)} can also be called in the other states,
304  *         such as <em>Prepared</em>, <em>Paused</em> and <em>PlaybackCompleted
305  *         </em> state. When {@link #seekTo(long, int)} is called in those states,
306  *         one video frame will be displayed if the stream has video and the requested
307  *         position is valid.
308  *         </li>
309  *         <li>Furthermore, the actual current playback position
310  *         can be retrieved with a call to {@link #getCurrentPosition()}, which
311  *         is helpful for applications such as a Music player that need to keep
312  *         track of the playback progress.</li>
313  *         </ul>
314  *         </li>
315  *     <li>When the playback reaches the end of stream, the playback completes.
316  *         <ul>
317  *         <li>If the looping mode was being set to <var>true</var> with
318  *         {@link #setLooping(boolean)}, the MediaPlayer object shall remain in
319  *         the <em>Started</em> state.</li>
320  *         <li>If the looping mode was set to <var>false
321  *         </var>, the player engine calls a user supplied callback method,
322  *         OnCompletion.onCompletion(), if a OnCompletionListener is registered
323  *         beforehand via {@link #setOnCompletionListener(OnCompletionListener)}.
324  *         The invoke of the callback signals that the object is now in the <em>
325  *         PlaybackCompleted</em> state.</li>
326  *         <li>While in the <em>PlaybackCompleted</em>
327  *         state, calling {@link #start()} can restart the playback from the
328  *         beginning of the audio/video source.</li>
329  * </ul>
330  *
331  *
332  * <a name="Valid_and_Invalid_States"></a>
333  * <h3>Valid and invalid states</h3>
334  *
335  * <table border="0" cellspacing="0" cellpadding="0">
336  * <tr><td>Method Name </p></td>
337  *     <td>Valid States </p></td>
338  *     <td>Invalid States </p></td>
339  *     <td>Comments </p></td></tr>
340  * <tr><td>attachAuxEffect </p></td>
341  *     <td>{Initialized, Prepared, Started, Paused, Stopped, PlaybackCompleted} </p></td>
342  *     <td>{Idle, Error} </p></td>
343  *     <td>This method must be called after setDataSource.
344  *     Calling it does not change the object state. </p></td></tr>
345  * <tr><td>getAudioSessionId </p></td>
346  *     <td>any </p></td>
347  *     <td>{} </p></td>
348  *     <td>This method can be called in any state and calling it does not change
349  *         the object state. </p></td></tr>
350  * <tr><td>getCurrentPosition </p></td>
351  *     <td>{Idle, Initialized, Prepared, Started, Paused, Stopped,
352  *         PlaybackCompleted} </p></td>
353  *     <td>{Error}</p></td>
354  *     <td>Successful invoke of this method in a valid state does not change the
355  *         state. Calling this method in an invalid state transfers the object
356  *         to the <em>Error</em> state. </p></td></tr>
357  * <tr><td>getDuration </p></td>
358  *     <td>{Prepared, Started, Paused, Stopped, PlaybackCompleted} </p></td>
359  *     <td>{Idle, Initialized, Error} </p></td>
360  *     <td>Successful invoke of this method in a valid state does not change the
361  *         state. Calling this method in an invalid state transfers the object
362  *         to the <em>Error</em> state. </p></td></tr>
363  * <tr><td>getVideoHeight </p></td>
364  *     <td>{Idle, Initialized, Prepared, Started, Paused, Stopped,
365  *         PlaybackCompleted}</p></td>
366  *     <td>{Error}</p></td>
367  *     <td>Successful invoke of this method in a valid state does not change the
368  *         state. Calling this method in an invalid state transfers the object
369  *         to the <em>Error</em> state.  </p></td></tr>
370  * <tr><td>getVideoWidth </p></td>
371  *     <td>{Idle, Initialized, Prepared, Started, Paused, Stopped,
372  *         PlaybackCompleted}</p></td>
373  *     <td>{Error}</p></td>
374  *     <td>Successful invoke of this method in a valid state does not change
375  *         the state. Calling this method in an invalid state transfers the
376  *         object to the <em>Error</em> state. </p></td></tr>
377  * <tr><td>isPlaying </p></td>
378  *     <td>{Idle, Initialized, Prepared, Started, Paused, Stopped,
379  *          PlaybackCompleted}</p></td>
380  *     <td>{Error}</p></td>
381  *     <td>Successful invoke of this method in a valid state does not change
382  *         the state. Calling this method in an invalid state transfers the
383  *         object to the <em>Error</em> state. </p></td></tr>
384  * <tr><td>pause </p></td>
385  *     <td>{Started, Paused, PlaybackCompleted}</p></td>
386  *     <td>{Idle, Initialized, Prepared, Stopped, Error}</p></td>
387  *     <td>Successful invoke of this method in a valid state transfers the
388  *         object to the <em>Paused</em> state. Calling this method in an
389  *         invalid state transfers the object to the <em>Error</em> state.</p></td></tr>
390  * <tr><td>prepare </p></td>
391  *     <td>{Initialized, Stopped} </p></td>
392  *     <td>{Idle, Prepared, Started, Paused, PlaybackCompleted, Error} </p></td>
393  *     <td>Successful invoke of this method in a valid state transfers the
394  *         object to the <em>Prepared</em> state. Calling this method in an
395  *         invalid state throws an IllegalStateException.</p></td></tr>
396  * <tr><td>prepareAsync </p></td>
397  *     <td>{Initialized, Stopped} </p></td>
398  *     <td>{Idle, Prepared, Started, Paused, PlaybackCompleted, Error} </p></td>
399  *     <td>Successful invoke of this method in a valid state transfers the
400  *         object to the <em>Preparing</em> state. Calling this method in an
401  *         invalid state throws an IllegalStateException.</p></td></tr>
402  * <tr><td>release </p></td>
403  *     <td>any </p></td>
404  *     <td>{} </p></td>
405  *     <td>After {@link #release()}, you must not interact with the object. </p></td></tr>
406  * <tr><td>reset </p></td>
407  *     <td>{Idle, Initialized, Prepared, Started, Paused, Stopped,
408  *         PlaybackCompleted, Error}</p></td>
409  *     <td>{}</p></td>
410  *     <td>After {@link #reset()}, the object is like being just created.</p></td></tr>
411  * <tr><td>seekTo </p></td>
412  *     <td>{Prepared, Started, Paused, PlaybackCompleted} </p></td>
413  *     <td>{Idle, Initialized, Stopped, Error}</p></td>
414  *     <td>Successful invoke of this method in a valid state does not change
415  *         the state. Calling this method in an invalid state transfers the
416  *         object to the <em>Error</em> state. </p></td></tr>
417  * <tr><td>setAudioAttributes </p></td>
418  *     <td>{Idle, Initialized, Stopped, Prepared, Started, Paused,
419  *          PlaybackCompleted}</p></td>
420  *     <td>{Error}</p></td>
421  *     <td>Successful invoke of this method does not change the state. In order for the
422  *         target audio attributes type to become effective, this method must be called before
423  *         prepare() or prepareAsync().</p></td></tr>
424  * <tr><td>setAudioSessionId </p></td>
425  *     <td>{Idle} </p></td>
426  *     <td>{Initialized, Prepared, Started, Paused, Stopped, PlaybackCompleted,
427  *          Error} </p></td>
428  *     <td>This method must be called in idle state as the audio session ID must be known before
429  *         calling setDataSource. Calling it does not change the object state. </p></td></tr>
430  * <tr><td>setAudioStreamType (deprecated)</p></td>
431  *     <td>{Idle, Initialized, Stopped, Prepared, Started, Paused,
432  *          PlaybackCompleted}</p></td>
433  *     <td>{Error}</p></td>
434  *     <td>Successful invoke of this method does not change the state. In order for the
435  *         target audio stream type to become effective, this method must be called before
436  *         prepare() or prepareAsync().</p></td></tr>
437  * <tr><td>setAuxEffectSendLevel </p></td>
438  *     <td>any</p></td>
439  *     <td>{} </p></td>
440  *     <td>Calling this method does not change the object state. </p></td></tr>
441  * <tr><td>setDataSource </p></td>
442  *     <td>{Idle} </p></td>
443  *     <td>{Initialized, Prepared, Started, Paused, Stopped, PlaybackCompleted,
444  *          Error} </p></td>
445  *     <td>Successful invoke of this method in a valid state transfers the
446  *         object to the <em>Initialized</em> state. Calling this method in an
447  *         invalid state throws an IllegalStateException.</p></td></tr>
448  * <tr><td>setDisplay </p></td>
449  *     <td>any </p></td>
450  *     <td>{} </p></td>
451  *     <td>This method can be called in any state and calling it does not change
452  *         the object state. </p></td></tr>
453  * <tr><td>setSurface </p></td>
454  *     <td>any </p></td>
455  *     <td>{} </p></td>
456  *     <td>This method can be called in any state and calling it does not change
457  *         the object state. </p></td></tr>
458  * <tr><td>setVideoScalingMode </p></td>
459  *     <td>{Initialized, Prepared, Started, Paused, Stopped, PlaybackCompleted} </p></td>
460  *     <td>{Idle, Error}</p></td>
461  *     <td>Successful invoke of this method does not change the state.</p></td></tr>
462  * <tr><td>setLooping </p></td>
463  *     <td>{Idle, Initialized, Stopped, Prepared, Started, Paused,
464  *         PlaybackCompleted}</p></td>
465  *     <td>{Error}</p></td>
466  *     <td>Successful invoke of this method in a valid state does not change
467  *         the state. Calling this method in an
468  *         invalid state transfers the object to the <em>Error</em> state.</p></td></tr>
469  * <tr><td>isLooping </p></td>
470  *     <td>any </p></td>
471  *     <td>{} </p></td>
472  *     <td>This method can be called in any state and calling it does not change
473  *         the object state. </p></td></tr>
474  * <tr><td>setOnBufferingUpdateListener </p></td>
475  *     <td>any </p></td>
476  *     <td>{} </p></td>
477  *     <td>This method can be called in any state and calling it does not change
478  *         the object state. </p></td></tr>
479  * <tr><td>setOnCompletionListener </p></td>
480  *     <td>any </p></td>
481  *     <td>{} </p></td>
482  *     <td>This method can be called in any state and calling it does not change
483  *         the object state. </p></td></tr>
484  * <tr><td>setOnErrorListener </p></td>
485  *     <td>any </p></td>
486  *     <td>{} </p></td>
487  *     <td>This method can be called in any state and calling it does not change
488  *         the object state. </p></td></tr>
489  * <tr><td>setOnPreparedListener </p></td>
490  *     <td>any </p></td>
491  *     <td>{} </p></td>
492  *     <td>This method can be called in any state and calling it does not change
493  *         the object state. </p></td></tr>
494  * <tr><td>setOnSeekCompleteListener </p></td>
495  *     <td>any </p></td>
496  *     <td>{} </p></td>
497  *     <td>This method can be called in any state and calling it does not change
498  *         the object state. </p></td></tr>
499  * <tr><td>setPlaybackParams</p></td>
500  *     <td>{Initialized, Prepared, Started, Paused, PlaybackCompleted, Error}</p></td>
501  *     <td>{Idle, Stopped} </p></td>
502  *     <td>This method will change state in some cases, depending on when it's called.
503  *         </p></td></tr>
504  * <tr><td>setScreenOnWhilePlaying</></td>
505  *     <td>any </p></td>
506  *     <td>{} </p></td>
507  *     <td>This method can be called in any state and calling it does not change
508  *         the object state.  </p></td></tr>
509  * <tr><td>setVolume </p></td>
510  *     <td>{Idle, Initialized, Stopped, Prepared, Started, Paused,
511  *          PlaybackCompleted}</p></td>
512  *     <td>{Error}</p></td>
513  *     <td>Successful invoke of this method does not change the state.
514  * <tr><td>setWakeMode </p></td>
515  *     <td>any </p></td>
516  *     <td>{} </p></td>
517  *     <td>This method can be called in any state and calling it does not change
518  *         the object state.</p></td></tr>
519  * <tr><td>start </p></td>
520  *     <td>{Prepared, Started, Paused, PlaybackCompleted}</p></td>
521  *     <td>{Idle, Initialized, Stopped, Error}</p></td>
522  *     <td>Successful invoke of this method in a valid state transfers the
523  *         object to the <em>Started</em> state. Calling this method in an
524  *         invalid state transfers the object to the <em>Error</em> state.</p></td></tr>
525  * <tr><td>stop </p></td>
526  *     <td>{Prepared, Started, Stopped, Paused, PlaybackCompleted}</p></td>
527  *     <td>{Idle, Initialized, Error}</p></td>
528  *     <td>Successful invoke of this method in a valid state transfers the
529  *         object to the <em>Stopped</em> state. Calling this method in an
530  *         invalid state transfers the object to the <em>Error</em> state.</p></td></tr>
531  * <tr><td>getTrackInfo </p></td>
532  *     <td>{Prepared, Started, Stopped, Paused, PlaybackCompleted}</p></td>
533  *     <td>{Idle, Initialized, Error}</p></td>
534  *     <td>Successful invoke of this method does not change the state.</p></td></tr>
535  * <tr><td>addTimedTextSource </p></td>
536  *     <td>{Prepared, Started, Stopped, Paused, PlaybackCompleted}</p></td>
537  *     <td>{Idle, Initialized, Error}</p></td>
538  *     <td>Successful invoke of this method does not change the state.</p></td></tr>
539  * <tr><td>selectTrack </p></td>
540  *     <td>{Prepared, Started, Stopped, Paused, PlaybackCompleted}</p></td>
541  *     <td>{Idle, Initialized, Error}</p></td>
542  *     <td>Successful invoke of this method does not change the state.</p></td></tr>
543  * <tr><td>deselectTrack </p></td>
544  *     <td>{Prepared, Started, Stopped, Paused, PlaybackCompleted}</p></td>
545  *     <td>{Idle, Initialized, Error}</p></td>
546  *     <td>Successful invoke of this method does not change the state.</p></td></tr>
547  *
548  * </table>
549  *
550  * <a name="Permissions"></a>
551  * <h3>Permissions</h3>
552  * <p>One may need to declare a corresponding WAKE_LOCK permission {@link
553  * android.R.styleable#AndroidManifestUsesPermission &lt;uses-permission&gt;}
554  * element.
555  *
556  * <p>This class requires the {@link android.Manifest.permission#INTERNET} permission
557  * when used with network-based content.
558  *
559  * <a name="Callbacks"></a>
560  * <h3>Callbacks</h3>
561  * <p>Applications may want to register for informational and error
562  * events in order to be informed of some internal state update and
563  * possible runtime errors during playback or streaming. Registration for
564  * these events is done by properly setting the appropriate listeners (via calls
565  * to
566  * {@link #setOnPreparedListener(OnPreparedListener) setOnPreparedListener},
567  * {@link #setOnVideoSizeChangedListener(OnVideoSizeChangedListener) setOnVideoSizeChangedListener},
568  * {@link #setOnSeekCompleteListener(OnSeekCompleteListener) setOnSeekCompleteListener},
569  * {@link #setOnCompletionListener(OnCompletionListener) setOnCompletionListener},
570  * {@link #setOnBufferingUpdateListener(OnBufferingUpdateListener) setOnBufferingUpdateListener},
571  * {@link #setOnInfoListener(OnInfoListener) setOnInfoListener},
572  * {@link #setOnErrorListener(OnErrorListener) setOnErrorListener}, etc).
573  * In order to receive the respective callback
574  * associated with these listeners, applications are required to create
575  * MediaPlayer objects on a thread with its own Looper running (main UI
576  * thread by default has a Looper running).
577  *
578  */
579 public class MediaPlayer extends PlayerBase
580                          implements SubtitleController.Listener
581                                   , VolumeAutomation
582                                   , AudioRouting
583 {
584     /**
585        Constant to retrieve only the new metadata since the last
586        call.
587        // FIXME: unhide.
588        // FIXME: add link to getMetadata(boolean, boolean)
589        {@hide}
590      */
591     public static final boolean METADATA_UPDATE_ONLY = true;
592 
593     /**
594        Constant to retrieve all the metadata.
595        // FIXME: unhide.
596        // FIXME: add link to getMetadata(boolean, boolean)
597        {@hide}
598      */
599     @UnsupportedAppUsage
600     public static final boolean METADATA_ALL = false;
601 
602     /**
603        Constant to enable the metadata filter during retrieval.
604        // FIXME: unhide.
605        // FIXME: add link to getMetadata(boolean, boolean)
606        {@hide}
607      */
608     public static final boolean APPLY_METADATA_FILTER = true;
609 
610     /**
611        Constant to disable the metadata filter during retrieval.
612        // FIXME: unhide.
613        // FIXME: add link to getMetadata(boolean, boolean)
614        {@hide}
615      */
616     @UnsupportedAppUsage
617     public static final boolean BYPASS_METADATA_FILTER = false;
618 
619     static {
620         System.loadLibrary("media_jni");
native_init()621         native_init();
622     }
623 
624     private final static String TAG = "MediaPlayer";
625     // Name of the remote interface for the media player. Must be kept
626     // in sync with the 2nd parameter of the IMPLEMENT_META_INTERFACE
627     // macro invocation in IMediaPlayer.cpp
628     private final static String IMEDIA_PLAYER = "android.media.IMediaPlayer";
629 
630     private long mNativeContext; // accessed by native methods
631     private long mNativeSurfaceTexture;  // accessed by native methods
632     private int mListenerContext; // accessed by native methods
633     private SurfaceHolder mSurfaceHolder;
634     @UnsupportedAppUsage
635     private EventHandler mEventHandler;
636     private PowerManager.WakeLock mWakeLock = null;
637     private boolean mScreenOnWhilePlaying;
638     private boolean mStayAwake;
639     private int mStreamType = AudioManager.USE_DEFAULT_STREAM_TYPE;
640 
641     // Modular DRM
642     private UUID mDrmUUID;
643     private final Object mDrmLock = new Object();
644     private DrmInfo mDrmInfo;
645     private MediaDrm mDrmObj;
646     private byte[] mDrmSessionId;
647     private boolean mDrmInfoResolved;
648     private boolean mActiveDrmScheme;
649     private boolean mDrmConfigAllowed;
650     private boolean mDrmProvisioningInProgress;
651     private boolean mPrepareDrmInProgress;
652     private ProvisioningThread mDrmProvisioningThread;
653 
654     /**
655      * Default constructor.
656      *
657      * <p>Consider using one of the create() methods for synchronously instantiating a MediaPlayer
658      * from a Uri or resource.
659      *
660      * <p>You must call {@link #release()} when you are finished using the instantiated instance.
661      * Doing so frees any resources you have previously acquired.
662      */
MediaPlayer()663     public MediaPlayer() {
664         this(/*context=*/null, AudioSystem.AUDIO_SESSION_ALLOCATE);
665     }
666 
667 
668     /**
669      * Default constructor with context.
670      *
671      *  <p>Consider using one of the create() methods for synchronously instantiating a
672      *  MediaPlayer from a Uri or resource.
673      *
674      * @param context non-null context. This context will be used to pull information,
675      *  such as {@link android.content.AttributionSource} and device specific session ids, which
676      *  will be associated with the {@link MediaPlayer}.
677      *  However, the context itself will not be retained by the MediaPlayer.
678      */
MediaPlayer(@onNull Context context)679     public MediaPlayer(@NonNull Context context) {
680         this(Objects.requireNonNull(context), AudioSystem.AUDIO_SESSION_ALLOCATE);
681     }
682 
MediaPlayer(Context context, int sessionId)683     private MediaPlayer(Context context, int sessionId) {
684         super(new AudioAttributes.Builder().build(),
685                 AudioPlaybackConfiguration.PLAYER_TYPE_JAM_MEDIAPLAYER);
686 
687         Looper looper;
688         if ((looper = Looper.myLooper()) != null) {
689             mEventHandler = new EventHandler(this, looper);
690         } else if ((looper = Looper.getMainLooper()) != null) {
691             mEventHandler = new EventHandler(this, looper);
692         } else {
693             mEventHandler = null;
694         }
695 
696         mTimeProvider = new TimeProvider(this);
697         mOpenSubtitleSources = new Vector<InputStream>();
698 
699         AttributionSource attributionSource =
700                 context == null ? AttributionSource.myAttributionSource()
701                         : context.getAttributionSource();
702         // set the package name to empty if it was null
703         if (attributionSource.getPackageName() == null) {
704             attributionSource = attributionSource.withPackageName("");
705         }
706 
707         /* Native setup requires a weak reference to our object.
708          * It's easier to create it here than in C++.
709          */
710         try (ScopedParcelState attributionSourceState = attributionSource.asScopedParcelState()) {
711             native_setup(new WeakReference<>(this), attributionSourceState.getParcel(),
712                     resolvePlaybackSessionId(context, sessionId));
713         }
714         baseRegisterPlayer(getAudioSessionId());
715     }
716 
createPlayerIIdParcel()717     private Parcel createPlayerIIdParcel() {
718         Parcel parcel = newRequest();
719         parcel.writeInt(INVOKE_ID_SET_PLAYER_IID);
720         parcel.writeInt(mPlayerIId);
721         return parcel;
722     }
723 
724     /*
725      * Update the MediaPlayer SurfaceTexture.
726      * Call after setting a new display surface.
727      */
_setVideoSurface(Surface surface)728     private native void _setVideoSurface(Surface surface);
729 
730     /* Do not change these values (starting with INVOKE_ID) without updating
731      * their counterparts in include/media/mediaplayer.h!
732      */
733     private static final int INVOKE_ID_GET_TRACK_INFO = 1;
734     private static final int INVOKE_ID_ADD_EXTERNAL_SOURCE = 2;
735     private static final int INVOKE_ID_ADD_EXTERNAL_SOURCE_FD = 3;
736     private static final int INVOKE_ID_SELECT_TRACK = 4;
737     private static final int INVOKE_ID_DESELECT_TRACK = 5;
738     private static final int INVOKE_ID_SET_VIDEO_SCALE_MODE = 6;
739     private static final int INVOKE_ID_GET_SELECTED_TRACK = 7;
740     private static final int INVOKE_ID_SET_PLAYER_IID = 8;
741 
742     /**
743      * Create a request parcel which can be routed to the native media
744      * player using {@link #invoke(Parcel, Parcel)}. The Parcel
745      * returned has the proper InterfaceToken set. The caller should
746      * not overwrite that token, i.e it can only append data to the
747      * Parcel.
748      *
749      * @return A parcel suitable to hold a request for the native
750      * player.
751      * {@hide}
752      */
753     @UnsupportedAppUsage
newRequest()754     public Parcel newRequest() {
755         Parcel parcel = Parcel.obtain();
756         parcel.writeInterfaceToken(IMEDIA_PLAYER);
757         return parcel;
758     }
759 
760     /**
761      * Invoke a generic method on the native player using opaque
762      * parcels for the request and reply. Both payloads' format is a
763      * convention between the java caller and the native player.
764      * Must be called after setDataSource to make sure a native player
765      * exists. On failure, a RuntimeException is thrown.
766      *
767      * @param request Parcel with the data for the extension. The
768      * caller must use {@link #newRequest()} to get one.
769      *
770      * @param reply Output parcel with the data returned by the
771      * native player.
772      * {@hide}
773      */
774     @UnsupportedAppUsage
invoke(Parcel request, Parcel reply)775     public void invoke(Parcel request, Parcel reply) {
776         int retcode = native_invoke(request, reply);
777         reply.setDataPosition(0);
778         if (retcode != 0) {
779             throw new RuntimeException("failure code: " + retcode);
780         }
781     }
782 
783     /**
784      * Sets the {@link SurfaceHolder} to use for displaying the video
785      * portion of the media.
786      *
787      * Either a surface holder or surface must be set if a display or video sink
788      * is needed.  Not calling this method or {@link #setSurface(Surface)}
789      * when playing back a video will result in only the audio track being played.
790      * A null surface holder or surface will result in only the audio track being
791      * played.
792      *
793      * @param sh the SurfaceHolder to use for video display
794      * @throws IllegalStateException if the internal player engine has not been
795      * initialized or has been released.
796      */
setDisplay(SurfaceHolder sh)797     public void setDisplay(SurfaceHolder sh) {
798         mSurfaceHolder = sh;
799         Surface surface;
800         if (sh != null) {
801             surface = sh.getSurface();
802         } else {
803             surface = null;
804         }
805         _setVideoSurface(surface);
806         updateSurfaceScreenOn();
807     }
808 
809     /**
810      * Sets the {@link Surface} to be used as the sink for the video portion of
811      * the media. This is similar to {@link #setDisplay(SurfaceHolder)}, but
812      * does not support {@link #setScreenOnWhilePlaying(boolean)}.  Setting a
813      * Surface will un-set any Surface or SurfaceHolder that was previously set.
814      * A null surface will result in only the audio track being played.
815      *
816      * If the Surface sends frames to a {@link SurfaceTexture}, the timestamps
817      * returned from {@link SurfaceTexture#getTimestamp()} will have an
818      * unspecified zero point.  These timestamps cannot be directly compared
819      * between different media sources, different instances of the same media
820      * source, or multiple runs of the same program.  The timestamp is normally
821      * monotonically increasing and is unaffected by time-of-day adjustments,
822      * but it is reset when the position is set.
823      *
824      * @param surface The {@link Surface} to be used for the video portion of
825      * the media.
826      * @throws IllegalStateException if the internal player engine has not been
827      * initialized or has been released.
828      */
setSurface(Surface surface)829     public void setSurface(Surface surface) {
830         if (mScreenOnWhilePlaying && surface != null) {
831             Log.w(TAG, "setScreenOnWhilePlaying(true) is ineffective for Surface");
832         }
833         mSurfaceHolder = null;
834         _setVideoSurface(surface);
835         updateSurfaceScreenOn();
836     }
837 
838     /* Do not change these video scaling mode values below without updating
839      * their counterparts in system/window.h! Please do not forget to update
840      * {@link #isVideoScalingModeSupported} when new video scaling modes
841      * are added.
842      */
843     /**
844      * Specifies a video scaling mode. The content is stretched to the
845      * surface rendering area. When the surface has the same aspect ratio
846      * as the content, the aspect ratio of the content is maintained;
847      * otherwise, the aspect ratio of the content is not maintained when video
848      * is being rendered. Unlike {@link #VIDEO_SCALING_MODE_SCALE_TO_FIT_WITH_CROPPING},
849      * there is no content cropping with this video scaling mode.
850      */
851     public static final int VIDEO_SCALING_MODE_SCALE_TO_FIT = 1;
852 
853     /**
854      * Specifies a video scaling mode. The content is scaled, maintaining
855      * its aspect ratio. The whole surface area is always used. When the
856      * aspect ratio of the content is the same as the surface, no content
857      * is cropped; otherwise, content is cropped to fit the surface.
858      */
859     public static final int VIDEO_SCALING_MODE_SCALE_TO_FIT_WITH_CROPPING = 2;
860     /**
861      * Sets video scaling mode. To make the target video scaling mode
862      * effective during playback, this method must be called after
863      * data source is set. If not called, the default video
864      * scaling mode is {@link #VIDEO_SCALING_MODE_SCALE_TO_FIT}.
865      *
866      * <p> The supported video scaling modes are:
867      * <ul>
868      * <li> {@link #VIDEO_SCALING_MODE_SCALE_TO_FIT}
869      * <li> {@link #VIDEO_SCALING_MODE_SCALE_TO_FIT_WITH_CROPPING}
870      * </ul>
871      *
872      * @param mode target video scaling mode. Must be one of the supported
873      * video scaling modes; otherwise, IllegalArgumentException will be thrown.
874      *
875      * @see MediaPlayer#VIDEO_SCALING_MODE_SCALE_TO_FIT
876      * @see MediaPlayer#VIDEO_SCALING_MODE_SCALE_TO_FIT_WITH_CROPPING
877      */
setVideoScalingMode(int mode)878     public void setVideoScalingMode(int mode) {
879         if (!isVideoScalingModeSupported(mode)) {
880             final String msg = "Scaling mode " + mode + " is not supported";
881             throw new IllegalArgumentException(msg);
882         }
883         Parcel request = Parcel.obtain();
884         Parcel reply = Parcel.obtain();
885         try {
886             request.writeInterfaceToken(IMEDIA_PLAYER);
887             request.writeInt(INVOKE_ID_SET_VIDEO_SCALE_MODE);
888             request.writeInt(mode);
889             invoke(request, reply);
890         } finally {
891             request.recycle();
892             reply.recycle();
893         }
894     }
895 
896     /**
897      * Convenience method to create a MediaPlayer for a given Uri.
898      * On success, {@link #prepare()} will already have been called and must not be called again.
899      *
900      * <p>You must call {@link #release()} when you are finished using the created instance. Doing
901      * so frees any resources you have previously acquired.
902      *
903      * <p>Note that since {@link #prepare()} is called automatically in this method,
904      * you cannot change the audio
905      * session ID (see {@link #setAudioSessionId(int)}) or audio attributes
906      * (see {@link #setAudioAttributes(AudioAttributes)} of the new MediaPlayer.</p>
907      *
908      * @param context the Context to use
909      * @param uri the Uri from which to get the datasource
910      * @return a MediaPlayer object, or null if creation failed
911      */
create(Context context, Uri uri)912     public static MediaPlayer create(Context context, Uri uri) {
913         return create (context, uri, null);
914     }
915 
916     /**
917      * Convenience method to create a MediaPlayer for a given Uri.
918      * On success, {@link #prepare()} will already have been called and must not be called again.
919      *
920      * <p>You must call {@link #release()} when you are finished using the created instance. Doing
921      * so frees any resources you have previously acquired.
922      *
923      * <p>Note that since {@link #prepare()} is called automatically in this method,
924      * you cannot change the audio
925      * session ID (see {@link #setAudioSessionId(int)}) or audio attributes
926      * (see {@link #setAudioAttributes(AudioAttributes)} of the new MediaPlayer.</p>
927      *
928      * @param context the Context to use
929      * @param uri the Uri from which to get the datasource
930      * @param holder the SurfaceHolder to use for displaying the video
931      * @return a MediaPlayer object, or null if creation failed
932      */
create(Context context, Uri uri, SurfaceHolder holder)933     public static MediaPlayer create(Context context, Uri uri, SurfaceHolder holder) {
934         return create(context, uri, holder, null, AudioSystem.AUDIO_SESSION_ALLOCATE);
935     }
936 
937     /**
938      * Same factory method as {@link #create(Context, Uri, SurfaceHolder)} but that lets you specify
939      * the audio attributes and session ID to be used by the new MediaPlayer instance.
940      * @param context the Context to use
941      * @param uri the Uri from which to get the datasource
942      * @param holder the SurfaceHolder to use for displaying the video, may be null.
943      * @param audioAttributes the {@link AudioAttributes} to be used by the media player.
944      * @param audioSessionId the audio session ID to be used by the media player,
945      *     see {@link AudioManager#generateAudioSessionId()} to obtain a new session.
946      * @return a MediaPlayer object, or null if creation failed
947      */
create(Context context, Uri uri, SurfaceHolder holder, AudioAttributes audioAttributes, int audioSessionId)948     public static MediaPlayer create(Context context, Uri uri, SurfaceHolder holder,
949             AudioAttributes audioAttributes, int audioSessionId) {
950 
951         try {
952             MediaPlayer mp = new MediaPlayer(context, audioSessionId);
953             final AudioAttributes aa = audioAttributes != null ? audioAttributes :
954                 new AudioAttributes.Builder().build();
955             mp.setAudioAttributes(aa);
956             mp.setDataSource(context, uri);
957             if (holder != null) {
958                 mp.setDisplay(holder);
959             }
960             mp.prepare();
961             return mp;
962         } catch (IOException ex) {
963             Log.d(TAG, "create failed:", ex);
964             // fall through
965         } catch (IllegalArgumentException ex) {
966             Log.d(TAG, "create failed:", ex);
967             // fall through
968         } catch (SecurityException ex) {
969             Log.d(TAG, "create failed:", ex);
970             // fall through
971         }
972 
973         return null;
974     }
975 
976     // Note no convenience method to create a MediaPlayer with SurfaceTexture sink.
977 
978     /**
979      * Convenience method to create a MediaPlayer for a given resource id.
980      * On success, {@link #prepare()} will already have been called and must not be called again.
981      *
982      * <p>You must call {@link #release()} when you are finished using the created instance. Doing
983      * so frees any resources you have previously acquired.
984      *
985      * <p>Note that since {@link #prepare()} is called automatically in this method,
986      * you cannot change the audio
987      * session ID (see {@link #setAudioSessionId(int)}) or audio attributes
988      * (see {@link #setAudioAttributes(AudioAttributes)} of the new MediaPlayer.</p>
989      *
990      * @param context the Context to use
991      * @param resid the raw resource id (<var>R.raw.&lt;something></var>) for
992      *              the resource to use as the datasource
993      * @return a MediaPlayer object, or null if creation failed
994      */
create(Context context, int resid)995     public static MediaPlayer create(Context context, int resid) {
996         return create(context, resid, null, AudioSystem.AUDIO_SESSION_ALLOCATE);
997     }
998 
999     /**
1000      * Same factory method as {@link #create(Context, int)} but that lets you specify the audio
1001      * attributes and session ID to be used by the new MediaPlayer instance.
1002      * @param context the Context to use
1003      * @param resid the raw resource id (<var>R.raw.&lt;something></var>) for
1004      *              the resource to use as the datasource
1005      * @param audioAttributes the {@link AudioAttributes} to be used by the media player.
1006      * @param audioSessionId the audio session ID to be used by the media player,
1007      *     see {@link AudioManager#generateAudioSessionId()} to obtain a new session.
1008      * @return a MediaPlayer object, or null if creation failed
1009      */
create(Context context, int resid, AudioAttributes audioAttributes, int audioSessionId)1010     public static MediaPlayer create(Context context, int resid,
1011             AudioAttributes audioAttributes, int audioSessionId) {
1012         try {
1013             AssetFileDescriptor afd = context.getResources().openRawResourceFd(resid);
1014             if (afd == null) return null;
1015 
1016             MediaPlayer mp = new MediaPlayer(context, audioSessionId);
1017 
1018             final AudioAttributes aa = audioAttributes != null ? audioAttributes :
1019                 new AudioAttributes.Builder().build();
1020             mp.setAudioAttributes(aa);
1021             mp.setDataSource(afd.getFileDescriptor(), afd.getStartOffset(), afd.getLength());
1022             afd.close();
1023             mp.prepare();
1024             return mp;
1025         } catch (IOException ex) {
1026             Log.d(TAG, "create failed:", ex);
1027             // fall through
1028         } catch (IllegalArgumentException ex) {
1029             Log.d(TAG, "create failed:", ex);
1030            // fall through
1031         } catch (SecurityException ex) {
1032             Log.d(TAG, "create failed:", ex);
1033             // fall through
1034         }
1035         return null;
1036     }
1037 
1038     /**
1039      * Sets the data source as a content Uri.
1040      *
1041      * @param context the Context to use when resolving the Uri
1042      * @param uri the Content URI of the data you want to play
1043      * @throws IllegalStateException if it is called in an invalid state
1044      */
setDataSource(@onNull Context context, @NonNull Uri uri)1045     public void setDataSource(@NonNull Context context, @NonNull Uri uri)
1046             throws IOException, IllegalArgumentException, SecurityException, IllegalStateException {
1047         setDataSource(context, uri, null, null);
1048     }
1049 
1050     /**
1051      * Sets the data source as a content Uri.
1052      *
1053      * To provide cookies for the subsequent HTTP requests, you can install your own default cookie
1054      * handler and use other variants of setDataSource APIs instead. Alternatively, you can use
1055      * this API to pass the cookies as a list of HttpCookie. If the app has not installed
1056      * a CookieHandler already, this API creates a CookieManager and populates its CookieStore with
1057      * the provided cookies. If the app has installed its own handler already, this API requires the
1058      * handler to be of CookieManager type such that the API can update the manager's CookieStore.
1059      *
1060      * <p><strong>Note</strong> that the cross domain redirection is allowed by default,
1061      * but that can be changed with key/value pairs through the headers parameter with
1062      * "android-allow-cross-domain-redirect" as the key and "0" or "1" as the value to
1063      * disallow or allow cross domain redirection.
1064      *
1065      * @param context the Context to use when resolving the Uri
1066      * @param uri the Content URI of the data you want to play
1067      * @param headers the headers to be sent together with the request for the data
1068      *                The headers must not include cookies. Instead, use the cookies param.
1069      * @param cookies the cookies to be sent together with the request
1070      * @throws IllegalArgumentException if cookies are provided and the installed handler is not
1071      *                                  a CookieManager
1072      * @throws IllegalStateException    if it is called in an invalid state
1073      * @throws NullPointerException     if context or uri is null
1074      * @throws IOException              if uri has a file scheme and an I/O error occurs
1075      */
setDataSource(@onNull Context context, @NonNull Uri uri, @Nullable Map<String, String> headers, @Nullable List<HttpCookie> cookies)1076     public void setDataSource(@NonNull Context context, @NonNull Uri uri,
1077             @Nullable Map<String, String> headers, @Nullable List<HttpCookie> cookies)
1078             throws IOException {
1079         if (context == null) {
1080             throw new NullPointerException("context param can not be null.");
1081         }
1082 
1083         if (uri == null) {
1084             throw new NullPointerException("uri param can not be null.");
1085         }
1086 
1087         if (cookies != null) {
1088             CookieHandler cookieHandler = CookieHandler.getDefault();
1089             if (cookieHandler != null && !(cookieHandler instanceof CookieManager)) {
1090                 throw new IllegalArgumentException("The cookie handler has to be of CookieManager "
1091                         + "type when cookies are provided.");
1092             }
1093         }
1094 
1095         // The context and URI usually belong to the calling user. Get a resolver for that user
1096         // and strip out the userId from the URI if present.
1097         final ContentResolver resolver = context.getContentResolver();
1098         final String scheme = uri.getScheme();
1099         final String authority = ContentProvider.getAuthorityWithoutUserId(uri.getAuthority());
1100         if (ContentResolver.SCHEME_FILE.equals(scheme)) {
1101             setDataSource(uri.getPath());
1102             return;
1103         } else if (ContentResolver.SCHEME_CONTENT.equals(scheme)
1104                 && Settings.AUTHORITY.equals(authority)) {
1105             // Try cached ringtone first since the actual provider may not be
1106             // encryption aware, or it may be stored on CE media storage
1107             final int type = RingtoneManager.getDefaultType(uri);
1108             final Uri cacheUri = RingtoneManager.getCacheForType(type, context.getUserId());
1109             final Uri actualUri = RingtoneManager.getActualDefaultRingtoneUri(context, type);
1110             if (attemptDataSource(resolver, cacheUri)) {
1111                 return;
1112             } else if (attemptDataSource(resolver, actualUri)) {
1113                 return;
1114             } else {
1115                 setDataSource(uri.toString(), headers, cookies);
1116             }
1117         } else {
1118             // Try requested Uri locally first, or fallback to media server
1119             if (attemptDataSource(resolver, uri)) {
1120                 return;
1121             } else {
1122                 setDataSource(uri.toString(), headers, cookies);
1123             }
1124         }
1125     }
1126 
1127     /**
1128      * Sets the data source as a content Uri.
1129      *
1130      * <p><strong>Note</strong> that the cross domain redirection is allowed by default,
1131      * but that can be changed with key/value pairs through the headers parameter with
1132      * "android-allow-cross-domain-redirect" as the key and "0" or "1" as the value to
1133      * disallow or allow cross domain redirection.
1134      *
1135      * @param context the Context to use when resolving the Uri
1136      * @param uri the Content URI of the data you want to play
1137      * @param headers the headers to be sent together with the request for the data
1138      * @throws IllegalStateException if it is called in an invalid state
1139      */
setDataSource(@onNull Context context, @NonNull Uri uri, @Nullable Map<String, String> headers)1140     public void setDataSource(@NonNull Context context, @NonNull Uri uri,
1141             @Nullable Map<String, String> headers)
1142             throws IOException, IllegalArgumentException, SecurityException, IllegalStateException {
1143         setDataSource(context, uri, headers, null);
1144     }
1145 
attemptDataSource(ContentResolver resolver, Uri uri)1146     private boolean attemptDataSource(ContentResolver resolver, Uri uri) {
1147         boolean optimize = SystemProperties.getBoolean("fuse.sys.transcode_player_optimize",
1148                 false);
1149         Bundle opts = new Bundle();
1150         opts.putBoolean("android.provider.extra.ACCEPT_ORIGINAL_MEDIA_FORMAT", true);
1151         try (AssetFileDescriptor afd = optimize
1152                 ? resolver.openTypedAssetFileDescriptor(uri, "*/*", opts)
1153                 : resolver.openAssetFileDescriptor(uri, "r")) {
1154             setDataSource(afd);
1155             return true;
1156         } catch (NullPointerException | SecurityException | IOException ex) {
1157             Log.w(TAG, "Error setting data source via ContentResolver", ex);
1158             return false;
1159         }
1160     }
1161 
1162     /**
1163      * Sets the data source (file-path or http/rtsp URL) to use.
1164      *
1165      * <p>When <code>path</code> refers to a local file, the file may actually be opened by a
1166      * process other than the calling application.  This implies that the pathname
1167      * should be an absolute path (as any other process runs with unspecified current working
1168      * directory), and that the pathname should reference a world-readable file.
1169      * As an alternative, the application could first open the file for reading,
1170      * and then use the file descriptor form {@link #setDataSource(FileDescriptor)}.
1171      *
1172      * @param path the path of the file, or the http/rtsp URL of the stream you want to play
1173      * @throws IllegalStateException if it is called in an invalid state
1174      */
setDataSource(String path)1175     public void setDataSource(String path)
1176             throws IOException, IllegalArgumentException, SecurityException, IllegalStateException {
1177         setDataSource(path, null, null);
1178     }
1179 
1180     /**
1181      * Sets the data source (file-path or http/rtsp URL) to use.
1182      *
1183      * @param path the path of the file, or the http/rtsp URL of the stream you want to play
1184      * @param headers the headers associated with the http request for the stream you want to play
1185      * @throws IllegalStateException if it is called in an invalid state
1186      * @hide pending API council
1187      */
1188     @UnsupportedAppUsage
setDataSource(String path, Map<String, String> headers)1189     public void setDataSource(String path, Map<String, String> headers)
1190             throws IOException, IllegalArgumentException, SecurityException, IllegalStateException {
1191         setDataSource(path, headers, null);
1192     }
1193 
1194     @UnsupportedAppUsage(maxTargetSdk = Build.VERSION_CODES.R, trackingBug = 170729553)
setDataSource(String path, Map<String, String> headers, List<HttpCookie> cookies)1195     private void setDataSource(String path, Map<String, String> headers, List<HttpCookie> cookies)
1196             throws IOException, IllegalArgumentException, SecurityException, IllegalStateException
1197     {
1198         String[] keys = null;
1199         String[] values = null;
1200 
1201         if (headers != null) {
1202             keys = new String[headers.size()];
1203             values = new String[headers.size()];
1204 
1205             int i = 0;
1206             for (Map.Entry<String, String> entry: headers.entrySet()) {
1207                 keys[i] = entry.getKey();
1208                 values[i] = entry.getValue();
1209                 ++i;
1210             }
1211         }
1212         setDataSource(path, keys, values, cookies);
1213     }
1214 
1215     @UnsupportedAppUsage(maxTargetSdk = Build.VERSION_CODES.R, trackingBug = 170729553)
setDataSource(String path, String[] keys, String[] values, List<HttpCookie> cookies)1216     private void setDataSource(String path, String[] keys, String[] values,
1217             List<HttpCookie> cookies)
1218             throws IOException, IllegalArgumentException, SecurityException, IllegalStateException {
1219         final Uri uri = Uri.parse(path);
1220         final String scheme = uri.getScheme();
1221         if ("file".equals(scheme)) {
1222             path = uri.getPath();
1223         } else if (scheme != null) {
1224             // handle non-file sources
1225             nativeSetDataSource(
1226                 MediaHTTPService.createHttpServiceBinderIfNecessary(path, cookies),
1227                 path,
1228                 keys,
1229                 values);
1230             return;
1231         }
1232 
1233         final File file = new File(path);
1234         try (FileInputStream is = new FileInputStream(file)) {
1235             setDataSource(is.getFD());
1236         }
1237     }
1238 
nativeSetDataSource( IBinder httpServiceBinder, String path, String[] keys, String[] values)1239     private native void nativeSetDataSource(
1240         IBinder httpServiceBinder, String path, String[] keys, String[] values)
1241         throws IOException, IllegalArgumentException, SecurityException, IllegalStateException;
1242 
1243     /**
1244      * Sets the data source (AssetFileDescriptor) to use. It is the caller's
1245      * responsibility to close the file descriptor. It is safe to do so as soon
1246      * as this call returns.
1247      *
1248      * @param afd the AssetFileDescriptor for the file you want to play
1249      * @throws IllegalStateException if it is called in an invalid state
1250      * @throws IllegalArgumentException if afd is not a valid AssetFileDescriptor
1251      * @throws IOException if afd can not be read
1252      */
setDataSource(@onNull AssetFileDescriptor afd)1253     public void setDataSource(@NonNull AssetFileDescriptor afd)
1254             throws IOException, IllegalArgumentException, IllegalStateException {
1255         Preconditions.checkNotNull(afd);
1256         // Note: using getDeclaredLength so that our behavior is the same
1257         // as previous versions when the content provider is returning
1258         // a full file.
1259         if (afd.getDeclaredLength() < 0) {
1260             setDataSource(afd.getFileDescriptor());
1261         } else {
1262             setDataSource(afd.getFileDescriptor(), afd.getStartOffset(), afd.getDeclaredLength());
1263         }
1264     }
1265 
1266     /**
1267      * Sets the data source (FileDescriptor) to use. It is the caller's responsibility
1268      * to close the file descriptor. It is safe to do so as soon as this call returns.
1269      *
1270      * @param fd the FileDescriptor for the file you want to play
1271      * @throws IllegalStateException if it is called in an invalid state
1272      * @throws IllegalArgumentException if fd is not a valid FileDescriptor
1273      * @throws IOException if fd can not be read
1274      */
setDataSource(FileDescriptor fd)1275     public void setDataSource(FileDescriptor fd)
1276             throws IOException, IllegalArgumentException, IllegalStateException {
1277         // intentionally less than LONG_MAX
1278         setDataSource(fd, 0, 0x7ffffffffffffffL);
1279     }
1280 
1281     /**
1282      * Sets the data source (FileDescriptor) to use.  The FileDescriptor must be
1283      * seekable (N.B. a LocalSocket is not seekable). It is the caller's responsibility
1284      * to close the file descriptor. It is safe to do so as soon as this call returns.
1285      *
1286      * @param fd the FileDescriptor for the file you want to play
1287      * @param offset the offset into the file where the data to be played starts, in bytes
1288      * @param length the length in bytes of the data to be played
1289      * @throws IllegalStateException if it is called in an invalid state
1290      * @throws IllegalArgumentException if fd is not a valid FileDescriptor
1291      * @throws IOException if fd can not be read
1292      */
setDataSource(FileDescriptor fd, long offset, long length)1293     public void setDataSource(FileDescriptor fd, long offset, long length)
1294             throws IOException, IllegalArgumentException, IllegalStateException {
1295         try (ParcelFileDescriptor modernFd = FileUtils.convertToModernFd(fd)) {
1296             if (modernFd == null) {
1297                 _setDataSource(fd, offset, length);
1298             } else {
1299                 _setDataSource(modernFd.getFileDescriptor(), offset, length);
1300             }
1301         } catch (IOException e) {
1302             Log.w(TAG, "Ignoring IO error while setting data source", e);
1303         }
1304     }
1305 
_setDataSource(FileDescriptor fd, long offset, long length)1306     private native void _setDataSource(FileDescriptor fd, long offset, long length)
1307             throws IOException, IllegalArgumentException, IllegalStateException;
1308 
1309     /**
1310      * Sets the data source (MediaDataSource) to use.
1311      *
1312      * @param dataSource the MediaDataSource for the media you want to play
1313      * @throws IllegalStateException if it is called in an invalid state
1314      * @throws IllegalArgumentException if dataSource is not a valid MediaDataSource
1315      */
setDataSource(MediaDataSource dataSource)1316     public void setDataSource(MediaDataSource dataSource)
1317             throws IllegalArgumentException, IllegalStateException {
1318         _setDataSource(dataSource);
1319     }
1320 
_setDataSource(MediaDataSource dataSource)1321     private native void _setDataSource(MediaDataSource dataSource)
1322           throws IllegalArgumentException, IllegalStateException;
1323 
1324     /**
1325      * Prepares the player for playback, synchronously.
1326      *
1327      * After setting the datasource and the display surface, you need to either
1328      * call prepare() or prepareAsync(). For files, it is OK to call prepare(),
1329      * which blocks until MediaPlayer is ready for playback.
1330      *
1331      * @throws IllegalStateException if it is called in an invalid state
1332      */
prepare()1333     public void prepare() throws IOException, IllegalStateException {
1334         Parcel piidParcel = createPlayerIIdParcel();
1335         try {
1336             int retCode = _prepare(piidParcel);
1337             if (retCode != 0) {
1338                 Log.w(TAG, "prepare(): could not set piid " + mPlayerIId);
1339             }
1340         } finally {
1341             piidParcel.recycle();
1342         }
1343         scanInternalSubtitleTracks();
1344 
1345         // DrmInfo, if any, has been resolved by now.
1346         synchronized (mDrmLock) {
1347             mDrmInfoResolved = true;
1348         }
1349 
1350     }
1351 
1352     /** Returns the result of sending the {@code piidParcel} to the MediaPlayerService. */
_prepare(Parcel piidParcel)1353     private native int _prepare(Parcel piidParcel) throws IOException, IllegalStateException;
1354 
1355     /**
1356      * Prepares the player for playback, asynchronously.
1357      *
1358      * After setting the datasource and the display surface, you need to either
1359      * call prepare() or prepareAsync(). For streams, you should call prepareAsync(),
1360      * which returns immediately, rather than blocking until enough data has been
1361      * buffered.
1362      *
1363      * @throws IllegalStateException if it is called in an invalid state
1364      */
prepareAsync()1365     public void prepareAsync() throws IllegalStateException {
1366         Parcel piidParcel = createPlayerIIdParcel();
1367         try {
1368             int retCode = _prepareAsync(piidParcel);
1369             if (retCode != 0) {
1370                 Log.w(TAG, "prepareAsync(): could not set piid " + mPlayerIId);
1371             }
1372         } finally {
1373             piidParcel.recycle();
1374         }
1375     }
1376 
1377     /** Returns the result of sending the {@code piidParcel} to the MediaPlayerService. */
_prepareAsync(Parcel piidParcel)1378     private native int _prepareAsync(Parcel piidParcel) throws IllegalStateException;
1379 
1380     /**
1381      * Starts or resumes playback. If playback had previously been paused,
1382      * playback will continue from where it was paused. If playback had
1383      * been stopped, or never started before, playback will start at the
1384      * beginning.
1385      *
1386      * @throws IllegalStateException if it is called in an invalid state
1387      */
start()1388     public void start() throws IllegalStateException {
1389         //FIXME use lambda to pass startImpl to superclass
1390         final int delay = getStartDelayMs();
1391         if (delay == 0) {
1392             startImpl();
1393         } else {
1394             new Thread() {
1395                 public void run() {
1396                     try {
1397                         Thread.sleep(delay);
1398                     } catch (InterruptedException e) {
1399                         e.printStackTrace();
1400                     }
1401                     baseSetStartDelayMs(0);
1402                     try {
1403                         startImpl();
1404                     } catch (IllegalStateException e) {
1405                         // fail silently for a state exception when it is happening after
1406                         // a delayed start, as the player state could have changed between the
1407                         // call to start() and the execution of startImpl()
1408                     }
1409                 }
1410             }.start();
1411         }
1412     }
1413 
startImpl()1414     private void startImpl() {
1415         baseStart(0); // unknown device at this point
1416         stayAwake(true);
1417         tryToEnableNativeRoutingCallback();
1418         _start();
1419     }
1420 
_start()1421     private native void _start() throws IllegalStateException;
1422 
1423 
getAudioStreamType()1424     private int getAudioStreamType() {
1425         if (mStreamType == AudioManager.USE_DEFAULT_STREAM_TYPE) {
1426             mStreamType = _getAudioStreamType();
1427         }
1428         return mStreamType;
1429     }
1430 
_getAudioStreamType()1431     private native int _getAudioStreamType() throws IllegalStateException;
1432 
1433     /**
1434      * Stops playback after playback has been started or paused.
1435      *
1436      * @throws IllegalStateException if the internal player engine has not been
1437      * initialized.
1438      */
stop()1439     public void stop() throws IllegalStateException {
1440         stayAwake(false);
1441         _stop();
1442         baseStop();
1443         tryToDisableNativeRoutingCallback();
1444     }
1445 
_stop()1446     private native void _stop() throws IllegalStateException;
1447 
1448     /**
1449      * Pauses playback. Call start() to resume.
1450      *
1451      * @throws IllegalStateException if the internal player engine has not been
1452      * initialized.
1453      */
pause()1454     public void pause() throws IllegalStateException {
1455         stayAwake(false);
1456         _pause();
1457         basePause();
1458     }
1459 
_pause()1460     private native void _pause() throws IllegalStateException;
1461 
1462     @Override
playerStart()1463     void playerStart() {
1464         start();
1465     }
1466 
1467     @Override
playerPause()1468     void playerPause() {
1469         pause();
1470     }
1471 
1472     @Override
playerStop()1473     void playerStop() {
1474         stop();
1475     }
1476 
1477     @Override
playerApplyVolumeShaper( @onNull VolumeShaper.Configuration configuration, @NonNull VolumeShaper.Operation operation)1478     /* package */ int playerApplyVolumeShaper(
1479             @NonNull VolumeShaper.Configuration configuration,
1480             @NonNull VolumeShaper.Operation operation) {
1481         return native_applyVolumeShaper(configuration, operation);
1482     }
1483 
1484     @Override
playerGetVolumeShaperState(int id)1485     /* package */ @Nullable VolumeShaper.State playerGetVolumeShaperState(int id) {
1486         return native_getVolumeShaperState(id);
1487     }
1488 
1489     @Override
createVolumeShaper( @onNull VolumeShaper.Configuration configuration)1490     public @NonNull VolumeShaper createVolumeShaper(
1491             @NonNull VolumeShaper.Configuration configuration) {
1492         return new VolumeShaper(configuration, this);
1493     }
1494 
native_applyVolumeShaper( @onNull VolumeShaper.Configuration configuration, @NonNull VolumeShaper.Operation operation)1495     private native int native_applyVolumeShaper(
1496             @NonNull VolumeShaper.Configuration configuration,
1497             @NonNull VolumeShaper.Operation operation);
1498 
native_getVolumeShaperState(int id)1499     private native @Nullable VolumeShaper.State native_getVolumeShaperState(int id);
1500 
1501     //--------------------------------------------------------------------------
1502     // Explicit Routing
1503     //--------------------
1504     private AudioDeviceInfo mPreferredDevice = null;
1505 
1506     /**
1507      * Specifies an audio device (via an {@link AudioDeviceInfo} object) to route
1508      * the output from this MediaPlayer.
1509      * @param deviceInfo The {@link AudioDeviceInfo} specifying the audio sink or source.
1510      *  If deviceInfo is null, default routing is restored.
1511      * @return true if succesful, false if the specified {@link AudioDeviceInfo} is non-null and
1512      * does not correspond to a valid audio device.
1513      */
1514     @Override
setPreferredDevice(AudioDeviceInfo deviceInfo)1515     public boolean setPreferredDevice(AudioDeviceInfo deviceInfo) {
1516         if (deviceInfo != null && !deviceInfo.isSink()) {
1517             return false;
1518         }
1519         int preferredDeviceId = deviceInfo != null ? deviceInfo.getId() : 0;
1520         boolean status = native_setOutputDevice(preferredDeviceId);
1521         if (status == true) {
1522             synchronized (this) {
1523                 mPreferredDevice = deviceInfo;
1524             }
1525         }
1526         return status;
1527     }
1528 
1529     /**
1530      * Returns the selected output specified by {@link #setPreferredDevice}. Note that this
1531      * is not guaranteed to correspond to the actual device being used for playback.
1532      */
1533     @Override
getPreferredDevice()1534     public AudioDeviceInfo getPreferredDevice() {
1535         synchronized (this) {
1536             return mPreferredDevice;
1537         }
1538     }
1539 
1540     /**
1541      * Returns an {@link AudioDeviceInfo} identifying the current routing of this MediaPlayer
1542      * Note: The query is only valid if the MediaPlayer is currently playing.
1543      * If the player is not playing, the returned device can be null or correspond to previously
1544      * selected device when the player was last active.
1545      */
1546     @Override
getRoutedDevice()1547     public AudioDeviceInfo getRoutedDevice() {
1548         int deviceId = native_getRoutedDeviceId();
1549         if (deviceId == 0) {
1550             return null;
1551         }
1552         return AudioManager.getDeviceForPortId(deviceId, AudioManager.GET_DEVICES_OUTPUTS);
1553     }
1554 
1555 
1556     /**
1557      * Sends device list change notification to all listeners.
1558      */
broadcastRoutingChange()1559     private void broadcastRoutingChange() {
1560         AudioManager.resetAudioPortGeneration();
1561         synchronized (mRoutingChangeListeners) {
1562             // Prevent the case where an event is triggered by registering a routing change
1563             // listener via the media player.
1564             if (mEnableSelfRoutingMonitor) {
1565                 baseUpdateDeviceId(getRoutedDevice());
1566             }
1567             for (NativeRoutingEventHandlerDelegate delegate
1568                     : mRoutingChangeListeners.values()) {
1569                 delegate.notifyClient();
1570             }
1571         }
1572     }
1573 
1574     /**
1575      * Call BEFORE adding a routing callback handler and when enabling self routing listener
1576      * @return returns true for success, false otherwise.
1577      */
1578     @GuardedBy("mRoutingChangeListeners")
testEnableNativeRoutingCallbacksLocked()1579     private boolean testEnableNativeRoutingCallbacksLocked() {
1580         if (mRoutingChangeListeners.size() == 0 && !mEnableSelfRoutingMonitor) {
1581             try {
1582                 native_enableDeviceCallback(true);
1583                 return true;
1584             } catch (IllegalStateException e) {
1585                 if (Log.isLoggable(TAG, Log.DEBUG)) {
1586                     Log.d(TAG, "testEnableNativeRoutingCallbacks failed", e);
1587                 }
1588             }
1589         }
1590         return false;
1591     }
1592 
tryToEnableNativeRoutingCallback()1593     private void  tryToEnableNativeRoutingCallback() {
1594         synchronized (mRoutingChangeListeners) {
1595             if (!mEnableSelfRoutingMonitor) {
1596                 mEnableSelfRoutingMonitor = testEnableNativeRoutingCallbacksLocked();
1597             }
1598         }
1599     }
1600 
tryToDisableNativeRoutingCallback()1601     private void tryToDisableNativeRoutingCallback() {
1602         synchronized (mRoutingChangeListeners) {
1603             if (mEnableSelfRoutingMonitor) {
1604                 mEnableSelfRoutingMonitor = false;
1605                 testDisableNativeRoutingCallbacksLocked();
1606             }
1607         }
1608     }
1609 
1610     /*
1611      * Call AFTER removing a routing callback handler and when disabling self routing listener
1612      */
1613     @GuardedBy("mRoutingChangeListeners")
testDisableNativeRoutingCallbacksLocked()1614     private void testDisableNativeRoutingCallbacksLocked() {
1615         if (mRoutingChangeListeners.size() == 0 && !mEnableSelfRoutingMonitor) {
1616             try {
1617                 native_enableDeviceCallback(false);
1618             } catch (IllegalStateException e) {
1619                 // Fail silently as media player state could have changed in between stop
1620                 // and disabling routing callback
1621             }
1622         }
1623     }
1624 
1625     /**
1626      * The list of AudioRouting.OnRoutingChangedListener interfaces added (with
1627      * {@link #addOnRoutingChangedListener(android.media.AudioRouting.OnRoutingChangedListener, Handler)}
1628      * by an app to receive (re)routing notifications.
1629      */
1630     @GuardedBy("mRoutingChangeListeners")
1631     private ArrayMap<AudioRouting.OnRoutingChangedListener,
1632             NativeRoutingEventHandlerDelegate> mRoutingChangeListeners = new ArrayMap<>();
1633 
1634     @GuardedBy("mRoutingChangeListeners")
1635     private boolean mEnableSelfRoutingMonitor;
1636 
1637     /**
1638      * Adds an {@link AudioRouting.OnRoutingChangedListener} to receive notifications of routing
1639      * changes on this MediaPlayer.
1640      * @param listener The {@link AudioRouting.OnRoutingChangedListener} interface to receive
1641      * notifications of rerouting events.
1642      * @param handler  Specifies the {@link Handler} object for the thread on which to execute
1643      * the callback. If <code>null</code>, the handler on the main looper will be used.
1644      */
1645     @Override
addOnRoutingChangedListener(AudioRouting.OnRoutingChangedListener listener, Handler handler)1646     public void addOnRoutingChangedListener(AudioRouting.OnRoutingChangedListener listener,
1647             Handler handler) {
1648         synchronized (mRoutingChangeListeners) {
1649             if (listener != null && !mRoutingChangeListeners.containsKey(listener)) {
1650                 mEnableSelfRoutingMonitor = testEnableNativeRoutingCallbacksLocked();
1651                 mRoutingChangeListeners.put(
1652                         listener, new NativeRoutingEventHandlerDelegate(this, listener,
1653                                 handler != null ? handler : mEventHandler));
1654             }
1655         }
1656     }
1657 
1658     /**
1659      * Removes an {@link AudioRouting.OnRoutingChangedListener} which has been previously added
1660      * to receive rerouting notifications.
1661      * @param listener The previously added {@link AudioRouting.OnRoutingChangedListener} interface
1662      * to remove.
1663      */
1664     @Override
removeOnRoutingChangedListener(AudioRouting.OnRoutingChangedListener listener)1665     public void removeOnRoutingChangedListener(AudioRouting.OnRoutingChangedListener listener) {
1666         synchronized (mRoutingChangeListeners) {
1667             if (mRoutingChangeListeners.containsKey(listener)) {
1668                 mRoutingChangeListeners.remove(listener);
1669             }
1670             testDisableNativeRoutingCallbacksLocked();
1671         }
1672     }
1673 
native_setOutputDevice(int deviceId)1674     private native final boolean native_setOutputDevice(int deviceId);
native_getRoutedDeviceId()1675     private native final int native_getRoutedDeviceId();
native_enableDeviceCallback(boolean enabled)1676     private native final void native_enableDeviceCallback(boolean enabled);
1677 
1678     /**
1679      * Set the low-level power management behavior for this MediaPlayer.  This
1680      * can be used when the MediaPlayer is not playing through a SurfaceHolder
1681      * set with {@link #setDisplay(SurfaceHolder)} and thus can use the
1682      * high-level {@link #setScreenOnWhilePlaying(boolean)} feature.
1683      *
1684      * <p>This function has the MediaPlayer access the low-level power manager
1685      * service to control the device's power usage while playing is occurring.
1686      * The parameter is a combination of {@link android.os.PowerManager} wake flags.
1687      * Use of this method requires {@link android.Manifest.permission#WAKE_LOCK}
1688      * permission.
1689      * By default, no attempt is made to keep the device awake during playback.
1690      *
1691      * @param context the Context to use
1692      * @param mode    the power/wake mode to set
1693      * @see android.os.PowerManager
1694      */
setWakeMode(Context context, int mode)1695     public void setWakeMode(Context context, int mode) {
1696         boolean washeld = false;
1697 
1698         /* Disable persistant wakelocks in media player based on property */
1699         if (SystemProperties.getBoolean("audio.offload.ignore_setawake", false) == true) {
1700             Log.w(TAG, "IGNORING setWakeMode " + mode);
1701             return;
1702         }
1703 
1704         if (mWakeLock != null) {
1705             if (mWakeLock.isHeld()) {
1706                 washeld = true;
1707                 mWakeLock.release();
1708             }
1709             mWakeLock = null;
1710         }
1711 
1712         PowerManager pm = (PowerManager)context.getSystemService(Context.POWER_SERVICE);
1713         mWakeLock = pm.newWakeLock(mode|PowerManager.ON_AFTER_RELEASE, MediaPlayer.class.getName());
1714         mWakeLock.setReferenceCounted(false);
1715         if (washeld) {
1716             mWakeLock.acquire();
1717         }
1718     }
1719 
1720     /**
1721      * Control whether we should use the attached SurfaceHolder to keep the
1722      * screen on while video playback is occurring.  This is the preferred
1723      * method over {@link #setWakeMode} where possible, since it doesn't
1724      * require that the application have permission for low-level wake lock
1725      * access.
1726      *
1727      * @param screenOn Supply true to keep the screen on, false to allow it
1728      * to turn off.
1729      */
setScreenOnWhilePlaying(boolean screenOn)1730     public void setScreenOnWhilePlaying(boolean screenOn) {
1731         if (mScreenOnWhilePlaying != screenOn) {
1732             if (screenOn && mSurfaceHolder == null) {
1733                 Log.w(TAG, "setScreenOnWhilePlaying(true) is ineffective without a SurfaceHolder");
1734             }
1735             mScreenOnWhilePlaying = screenOn;
1736             updateSurfaceScreenOn();
1737         }
1738     }
1739 
stayAwake(boolean awake)1740     private void stayAwake(boolean awake) {
1741         if (mWakeLock != null) {
1742             if (awake && !mWakeLock.isHeld()) {
1743                 mWakeLock.acquire();
1744             } else if (!awake && mWakeLock.isHeld()) {
1745                 mWakeLock.release();
1746             }
1747         }
1748         mStayAwake = awake;
1749         updateSurfaceScreenOn();
1750     }
1751 
updateSurfaceScreenOn()1752     private void updateSurfaceScreenOn() {
1753         if (mSurfaceHolder != null) {
1754             mSurfaceHolder.setKeepScreenOn(mScreenOnWhilePlaying && mStayAwake);
1755         }
1756     }
1757 
1758     /**
1759      * Returns the width of the video.
1760      *
1761      * @return the width of the video, or 0 if there is no video,
1762      * no display surface was set, or the width has not been determined
1763      * yet. The OnVideoSizeChangedListener can be registered via
1764      * {@link #setOnVideoSizeChangedListener(OnVideoSizeChangedListener)}
1765      * to provide a notification when the width is available.
1766      */
getVideoWidth()1767     public native int getVideoWidth();
1768 
1769     /**
1770      * Returns the height of the video.
1771      *
1772      * @return the height of the video, or 0 if there is no video,
1773      * no display surface was set, or the height has not been determined
1774      * yet. The OnVideoSizeChangedListener can be registered via
1775      * {@link #setOnVideoSizeChangedListener(OnVideoSizeChangedListener)}
1776      * to provide a notification when the height is available.
1777      */
getVideoHeight()1778     public native int getVideoHeight();
1779 
1780     /**
1781      * Return Metrics data about the current player.
1782      *
1783      * @return a {@link PersistableBundle} containing the set of attributes and values
1784      * available for the media being handled by this instance of MediaPlayer
1785      * The attributes are descibed in {@link MetricsConstants}.
1786      *
1787      *  Additional vendor-specific fields may also be present in
1788      *  the return value.
1789      */
getMetrics()1790     public PersistableBundle getMetrics() {
1791         PersistableBundle bundle = native_getMetrics();
1792         return bundle;
1793     }
1794 
native_getMetrics()1795     private native PersistableBundle native_getMetrics();
1796 
1797     /**
1798      * Checks whether the MediaPlayer is playing.
1799      *
1800      * @return true if currently playing, false otherwise
1801      * @throws IllegalStateException if the internal player engine has not been
1802      * initialized or has been released.
1803      */
isPlaying()1804     public native boolean isPlaying();
1805 
1806     /**
1807      * Change playback speed of audio by resampling the audio.
1808      * <p>
1809      * Specifies resampling as audio mode for variable rate playback, i.e.,
1810      * resample the waveform based on the requested playback rate to get
1811      * a new waveform, and play back the new waveform at the original sampling
1812      * frequency.
1813      * When rate is larger than 1.0, pitch becomes higher.
1814      * When rate is smaller than 1.0, pitch becomes lower.
1815      *
1816      * @hide
1817      */
1818     public static final int PLAYBACK_RATE_AUDIO_MODE_RESAMPLE = 2;
1819 
1820     /**
1821      * Change playback speed of audio without changing its pitch.
1822      * <p>
1823      * Specifies time stretching as audio mode for variable rate playback.
1824      * Time stretching changes the duration of the audio samples without
1825      * affecting its pitch.
1826      * <p>
1827      * This mode is only supported for a limited range of playback speed factors,
1828      * e.g. between 1/2x and 2x.
1829      *
1830      * @hide
1831      */
1832     public static final int PLAYBACK_RATE_AUDIO_MODE_STRETCH = 1;
1833 
1834     /**
1835      * Change playback speed of audio without changing its pitch, and
1836      * possibly mute audio if time stretching is not supported for the playback
1837      * speed.
1838      * <p>
1839      * Try to keep audio pitch when changing the playback rate, but allow the
1840      * system to determine how to change audio playback if the rate is out
1841      * of range.
1842      *
1843      * @hide
1844      */
1845     public static final int PLAYBACK_RATE_AUDIO_MODE_DEFAULT = 0;
1846 
1847     /** @hide */
1848     @IntDef(
1849         value = {
1850             PLAYBACK_RATE_AUDIO_MODE_DEFAULT,
1851             PLAYBACK_RATE_AUDIO_MODE_STRETCH,
1852             PLAYBACK_RATE_AUDIO_MODE_RESAMPLE,
1853     })
1854     @Retention(RetentionPolicy.SOURCE)
1855     public @interface PlaybackRateAudioMode {}
1856 
1857     /**
1858      * Sets playback rate and audio mode.
1859      *
1860      * @param rate the ratio between desired playback rate and normal one.
1861      * @param audioMode audio playback mode. Must be one of the supported
1862      * audio modes.
1863      *
1864      * @throws IllegalStateException if the internal player engine has not been
1865      * initialized.
1866      * @throws IllegalArgumentException if audioMode is not supported.
1867      *
1868      * @hide
1869      */
1870     @NonNull
easyPlaybackParams(float rate, @PlaybackRateAudioMode int audioMode)1871     public PlaybackParams easyPlaybackParams(float rate, @PlaybackRateAudioMode int audioMode) {
1872         PlaybackParams params = new PlaybackParams();
1873         params.allowDefaults();
1874         switch (audioMode) {
1875         case PLAYBACK_RATE_AUDIO_MODE_DEFAULT:
1876             params.setSpeed(rate).setPitch(1.0f);
1877             break;
1878         case PLAYBACK_RATE_AUDIO_MODE_STRETCH:
1879             params.setSpeed(rate).setPitch(1.0f)
1880                     .setAudioFallbackMode(params.AUDIO_FALLBACK_MODE_FAIL);
1881             break;
1882         case PLAYBACK_RATE_AUDIO_MODE_RESAMPLE:
1883             params.setSpeed(rate).setPitch(rate);
1884             break;
1885         default:
1886             final String msg = "Audio playback mode " + audioMode + " is not supported";
1887             throw new IllegalArgumentException(msg);
1888         }
1889         return params;
1890     }
1891 
1892     /**
1893      * Sets playback rate using {@link PlaybackParams}. The object sets its internal
1894      * PlaybackParams to the input, except that the object remembers previous speed
1895      * when input speed is zero. This allows the object to resume at previous speed
1896      * when start() is called. Calling it before the object is prepared does not change
1897      * the object state. After the object is prepared, calling it with zero speed is
1898      * equivalent to calling pause(). After the object is prepared, calling it with
1899      * non-zero speed is equivalent to calling start().
1900      *
1901      * @param params the playback params.
1902      *
1903      * @throws IllegalStateException if the internal player engine has not been
1904      * initialized or has been released.
1905      * @throws IllegalArgumentException if params is not supported.
1906      */
setPlaybackParams(@onNull PlaybackParams params)1907     public native void setPlaybackParams(@NonNull PlaybackParams params);
1908 
1909     /**
1910      * Gets the playback params, containing the current playback rate.
1911      *
1912      * @return the playback params.
1913      * @throws IllegalStateException if the internal player engine has not been
1914      * initialized.
1915      */
1916     @NonNull
getPlaybackParams()1917     public native PlaybackParams getPlaybackParams();
1918 
1919     /**
1920      * Sets A/V sync mode.
1921      *
1922      * @param params the A/V sync params to apply
1923      *
1924      * @throws IllegalStateException if the internal player engine has not been
1925      * initialized.
1926      * @throws IllegalArgumentException if params are not supported.
1927      */
setSyncParams(@onNull SyncParams params)1928     public native void setSyncParams(@NonNull SyncParams params);
1929 
1930     /**
1931      * Gets the A/V sync mode.
1932      *
1933      * @return the A/V sync params
1934      *
1935      * @throws IllegalStateException if the internal player engine has not been
1936      * initialized.
1937      */
1938     @NonNull
getSyncParams()1939     public native SyncParams getSyncParams();
1940 
1941     /**
1942      * Seek modes used in method seekTo(long, int) to move media position
1943      * to a specified location.
1944      *
1945      * Do not change these mode values without updating their counterparts
1946      * in include/media/IMediaSource.h!
1947      */
1948     /**
1949      * This mode is used with {@link #seekTo(long, int)} to move media position to
1950      * a sync (or key) frame associated with a data source that is located
1951      * right before or at the given time.
1952      *
1953      * @see #seekTo(long, int)
1954      */
1955     public static final int SEEK_PREVIOUS_SYNC    = 0x00;
1956     /**
1957      * This mode is used with {@link #seekTo(long, int)} to move media position to
1958      * a sync (or key) frame associated with a data source that is located
1959      * right after or at the given time.
1960      *
1961      * @see #seekTo(long, int)
1962      */
1963     public static final int SEEK_NEXT_SYNC        = 0x01;
1964     /**
1965      * This mode is used with {@link #seekTo(long, int)} to move media position to
1966      * a sync (or key) frame associated with a data source that is located
1967      * closest to (in time) or at the given time.
1968      *
1969      * @see #seekTo(long, int)
1970      */
1971     public static final int SEEK_CLOSEST_SYNC     = 0x02;
1972     /**
1973      * This mode is used with {@link #seekTo(long, int)} to move media position to
1974      * a frame (not necessarily a key frame) associated with a data source that
1975      * is located closest to or at the given time.
1976      *
1977      * @see #seekTo(long, int)
1978      */
1979     public static final int SEEK_CLOSEST          = 0x03;
1980 
1981     /** @hide */
1982     @IntDef(
1983         value = {
1984             SEEK_PREVIOUS_SYNC,
1985             SEEK_NEXT_SYNC,
1986             SEEK_CLOSEST_SYNC,
1987             SEEK_CLOSEST,
1988     })
1989     @Retention(RetentionPolicy.SOURCE)
1990     public @interface SeekMode {}
1991 
_seekTo(long msec, int mode)1992     private native final void _seekTo(long msec, int mode);
1993 
1994     /**
1995      * Moves the media to specified time position by considering the given mode.
1996      * <p>
1997      * When seekTo is finished, the user will be notified via OnSeekComplete supplied by the user.
1998      * There is at most one active seekTo processed at any time. If there is a to-be-completed
1999      * seekTo, new seekTo requests will be queued in such a way that only the last request
2000      * is kept. When current seekTo is completed, the queued request will be processed if
2001      * that request is different from just-finished seekTo operation, i.e., the requested
2002      * position or mode is different.
2003      *
2004      * @param msec the offset in milliseconds from the start to seek to.
2005      * When seeking to the given time position, there is no guarantee that the data source
2006      * has a frame located at the position. When this happens, a frame nearby will be rendered.
2007      * If msec is negative, time position zero will be used.
2008      * If msec is larger than duration, duration will be used.
2009      * @param mode the mode indicating where exactly to seek to.
2010      * Use {@link #SEEK_PREVIOUS_SYNC} if one wants to seek to a sync frame
2011      * that has a timestamp earlier than or the same as msec. Use
2012      * {@link #SEEK_NEXT_SYNC} if one wants to seek to a sync frame
2013      * that has a timestamp later than or the same as msec. Use
2014      * {@link #SEEK_CLOSEST_SYNC} if one wants to seek to a sync frame
2015      * that has a timestamp closest to or the same as msec. Use
2016      * {@link #SEEK_CLOSEST} if one wants to seek to a frame that may
2017      * or may not be a sync frame but is closest to or the same as msec.
2018      * {@link #SEEK_CLOSEST} often has larger performance overhead compared
2019      * to the other options if there is no sync frame located at msec.
2020      * @throws IllegalStateException if the internal player engine has not been
2021      * initialized
2022      * @throws IllegalArgumentException if the mode is invalid.
2023      */
seekTo(long msec, @SeekMode int mode)2024     public void seekTo(long msec, @SeekMode int mode) {
2025         if (mode < SEEK_PREVIOUS_SYNC || mode > SEEK_CLOSEST) {
2026             final String msg = "Illegal seek mode: " + mode;
2027             throw new IllegalArgumentException(msg);
2028         }
2029         // TODO: pass long to native, instead of truncating here.
2030         if (msec > Integer.MAX_VALUE) {
2031             Log.w(TAG, "seekTo offset " + msec + " is too large, cap to " + Integer.MAX_VALUE);
2032             msec = Integer.MAX_VALUE;
2033         } else if (msec < Integer.MIN_VALUE) {
2034             Log.w(TAG, "seekTo offset " + msec + " is too small, cap to " + Integer.MIN_VALUE);
2035             msec = Integer.MIN_VALUE;
2036         }
2037         _seekTo(msec, mode);
2038     }
2039 
2040     /**
2041      * Seeks to specified time position.
2042      * Same as {@link #seekTo(long, int)} with {@code mode = SEEK_PREVIOUS_SYNC}.
2043      *
2044      * @param msec the offset in milliseconds from the start to seek to
2045      * @throws IllegalStateException if the internal player engine has not been
2046      * initialized
2047      */
seekTo(int msec)2048     public void seekTo(int msec) throws IllegalStateException {
2049         seekTo(msec, SEEK_PREVIOUS_SYNC /* mode */);
2050     }
2051 
2052     /**
2053      * Get current playback position as a {@link MediaTimestamp}.
2054      * <p>
2055      * The MediaTimestamp represents how the media time correlates to the system time in
2056      * a linear fashion using an anchor and a clock rate. During regular playback, the media
2057      * time moves fairly constantly (though the anchor frame may be rebased to a current
2058      * system time, the linear correlation stays steady). Therefore, this method does not
2059      * need to be called often.
2060      * <p>
2061      * To help users get current playback position, this method always anchors the timestamp
2062      * to the current {@link System#nanoTime system time}, so
2063      * {@link MediaTimestamp#getAnchorMediaTimeUs} can be used as current playback position.
2064      *
2065      * @return a MediaTimestamp object if a timestamp is available, or {@code null} if no timestamp
2066      *         is available, e.g. because the media player has not been initialized.
2067      *
2068      * @see MediaTimestamp
2069      */
2070     @Nullable
getTimestamp()2071     public MediaTimestamp getTimestamp()
2072     {
2073         try {
2074             // TODO: get the timestamp from native side
2075             return new MediaTimestamp(
2076                     getCurrentPosition() * 1000L,
2077                     System.nanoTime(),
2078                     isPlaying() ? getPlaybackParams().getSpeed() : 0.f);
2079         } catch (IllegalStateException e) {
2080             return null;
2081         }
2082     }
2083 
2084     /**
2085      * Gets the current playback position.
2086      *
2087      * @return the current position in milliseconds
2088      */
getCurrentPosition()2089     public native int getCurrentPosition();
2090 
2091     /**
2092      * Gets the duration of the file.
2093      *
2094      * @return the duration in milliseconds, if no duration is available
2095      *         (for example, if streaming live content), -1 is returned.
2096      */
getDuration()2097     public native int getDuration();
2098 
2099     /**
2100      * Gets the media metadata.
2101      *
2102      * @param update_only controls whether the full set of available
2103      * metadata is returned or just the set that changed since the
2104      * last call. See {@see #METADATA_UPDATE_ONLY} and {@see
2105      * #METADATA_ALL}.
2106      *
2107      * @param apply_filter if true only metadata that matches the
2108      * filter is returned. See {@see #APPLY_METADATA_FILTER} and {@see
2109      * #BYPASS_METADATA_FILTER}.
2110      *
2111      * @return The metadata, possibly empty. null if an error occured.
2112      // FIXME: unhide.
2113      * {@hide}
2114      */
2115     @UnsupportedAppUsage
getMetadata(final boolean update_only, final boolean apply_filter)2116     public Metadata getMetadata(final boolean update_only,
2117                                 final boolean apply_filter) {
2118         Parcel reply = Parcel.obtain();
2119         Metadata data = new Metadata();
2120 
2121         if (!native_getMetadata(update_only, apply_filter, reply)) {
2122             reply.recycle();
2123             return null;
2124         }
2125 
2126         // Metadata takes over the parcel, don't recycle it unless
2127         // there is an error.
2128         if (!data.parse(reply)) {
2129             reply.recycle();
2130             return null;
2131         }
2132         return data;
2133     }
2134 
2135     /**
2136      * Set a filter for the metadata update notification and update
2137      * retrieval. The caller provides 2 set of metadata keys, allowed
2138      * and blocked. The blocked set always takes precedence over the
2139      * allowed one.
2140      * Metadata.MATCH_ALL and Metadata.MATCH_NONE are 2 sets available as
2141      * shorthands to allow/block all or no metadata.
2142      *
2143      * By default, there is no filter set.
2144      *
2145      * @param allow Is the set of metadata the client is interested
2146      *              in receiving new notifications for.
2147      * @param block Is the set of metadata the client is not interested
2148      *              in receiving new notifications for.
2149      * @return The call status code.
2150      *
2151      // FIXME: unhide.
2152      * {@hide}
2153      */
setMetadataFilter(Set<Integer> allow, Set<Integer> block)2154     public int setMetadataFilter(Set<Integer> allow, Set<Integer> block) {
2155         // Do our serialization manually instead of calling
2156         // Parcel.writeArray since the sets are made of the same type
2157         // we avoid paying the price of calling writeValue (used by
2158         // writeArray) which burns an extra int per element to encode
2159         // the type.
2160         Parcel request =  newRequest();
2161 
2162         // The parcel starts already with an interface token. There
2163         // are 2 filters. Each one starts with a 4bytes number to
2164         // store the len followed by a number of int (4 bytes as well)
2165         // representing the metadata type.
2166         int capacity = request.dataSize() + 4 * (1 + allow.size() + 1 + block.size());
2167 
2168         if (request.dataCapacity() < capacity) {
2169             request.setDataCapacity(capacity);
2170         }
2171 
2172         request.writeInt(allow.size());
2173         for(Integer t: allow) {
2174             request.writeInt(t);
2175         }
2176         request.writeInt(block.size());
2177         for(Integer t: block) {
2178             request.writeInt(t);
2179         }
2180         return native_setMetadataFilter(request);
2181     }
2182 
2183     /**
2184      * Set the MediaPlayer to start when this MediaPlayer finishes playback
2185      * (i.e. reaches the end of the stream).
2186      * The media framework will attempt to transition from this player to
2187      * the next as seamlessly as possible. The next player can be set at
2188      * any time before completion, but shall be after setDataSource has been
2189      * called successfully. The next player must be prepared by the
2190      * app, and the application should not call start() on it.
2191      * The next MediaPlayer must be different from 'this'. An exception
2192      * will be thrown if next == this.
2193      * The application may call setNextMediaPlayer(null) to indicate no
2194      * next player should be started at the end of playback.
2195      * If the current player is looping, it will keep looping and the next
2196      * player will not be started.
2197      *
2198      * @param next the player to start after this one completes playback.
2199      *
2200      */
setNextMediaPlayer(MediaPlayer next)2201     public native void setNextMediaPlayer(MediaPlayer next);
2202 
2203     /**
2204      * Releases resources associated with this MediaPlayer object.
2205      *
2206      * <p>You must call this method once the instance is no longer required.
2207      */
release()2208     public void release() {
2209         baseRelease();
2210         stayAwake(false);
2211         updateSurfaceScreenOn();
2212         mOnPreparedListener = null;
2213         mOnBufferingUpdateListener = null;
2214         mOnCompletionListener = null;
2215         mOnSeekCompleteListener = null;
2216         mOnErrorListener = null;
2217         mOnInfoListener = null;
2218         mOnVideoSizeChangedListener = null;
2219         mOnTimedTextListener = null;
2220         mOnRtpRxNoticeListener = null;
2221         mOnRtpRxNoticeExecutor = null;
2222         synchronized (mTimeProviderLock) {
2223             if (mTimeProvider != null) {
2224                 mTimeProvider.close();
2225                 mTimeProvider = null;
2226             }
2227         }
2228         synchronized(this) {
2229             mSubtitleDataListenerDisabled = false;
2230             mExtSubtitleDataListener = null;
2231             mExtSubtitleDataHandler = null;
2232             mOnMediaTimeDiscontinuityListener = null;
2233             mOnMediaTimeDiscontinuityHandler = null;
2234         }
2235 
2236         // Modular DRM clean up
2237         mOnDrmConfigHelper = null;
2238         mOnDrmInfoHandlerDelegate = null;
2239         mOnDrmPreparedHandlerDelegate = null;
2240         resetDrmState();
2241 
2242         _release();
2243     }
2244 
_release()2245     private native void _release();
2246 
2247     /**
2248      * Resets the MediaPlayer to its uninitialized state. After calling
2249      * this method, you will have to initialize it again by setting the
2250      * data source and calling prepare().
2251      */
reset()2252     public void reset() {
2253         mSelectedSubtitleTrackIndex = -1;
2254         synchronized(mOpenSubtitleSources) {
2255             for (final InputStream is: mOpenSubtitleSources) {
2256                 try {
2257                     is.close();
2258                 } catch (IOException e) {
2259                 }
2260             }
2261             mOpenSubtitleSources.clear();
2262         }
2263         if (mSubtitleController != null) {
2264             mSubtitleController.reset();
2265         }
2266         synchronized (mTimeProviderLock) {
2267             if (mTimeProvider != null) {
2268                 mTimeProvider.close();
2269                 mTimeProvider = null;
2270             }
2271         }
2272 
2273         stayAwake(false);
2274         _reset();
2275         // make sure none of the listeners get called anymore
2276         if (mEventHandler != null) {
2277             mEventHandler.removeCallbacksAndMessages(null);
2278         }
2279 
2280         synchronized (mIndexTrackPairs) {
2281             mIndexTrackPairs.clear();
2282             mInbandTrackIndices.clear();
2283         };
2284 
2285         resetDrmState();
2286     }
2287 
_reset()2288     private native void _reset();
2289 
2290     /**
2291      * Set up a timer for {@link #TimeProvider}. {@link #TimeProvider} will be
2292      * notified when the presentation time reaches (becomes greater than or equal to)
2293      * the value specified.
2294      *
2295      * @param mediaTimeUs presentation time to get timed event callback at
2296      * @hide
2297      */
notifyAt(long mediaTimeUs)2298     public void notifyAt(long mediaTimeUs) {
2299         _notifyAt(mediaTimeUs);
2300     }
2301 
_notifyAt(long mediaTimeUs)2302     private native void _notifyAt(long mediaTimeUs);
2303 
2304     /**
2305      * Sets the audio stream type for this MediaPlayer. See {@link AudioManager}
2306      * for a list of stream types. Must call this method before prepare() or
2307      * prepareAsync() in order for the target stream type to become effective
2308      * thereafter.
2309      *
2310      * @param streamtype the audio stream type
2311      * @deprecated use {@link #setAudioAttributes(AudioAttributes)}
2312      * @see android.media.AudioManager
2313      */
setAudioStreamType(int streamtype)2314     public void setAudioStreamType(int streamtype) {
2315         deprecateStreamTypeForPlayback(streamtype, "MediaPlayer", "setAudioStreamType()");
2316         baseUpdateAudioAttributes(
2317                 new AudioAttributes.Builder().setInternalLegacyStreamType(streamtype).build());
2318         _setAudioStreamType(streamtype);
2319         mStreamType = streamtype;
2320     }
2321 
_setAudioStreamType(int streamtype)2322     private native void _setAudioStreamType(int streamtype);
2323 
2324     // Keep KEY_PARAMETER_* in sync with include/media/mediaplayer.h
2325     private final static int KEY_PARAMETER_AUDIO_ATTRIBUTES = 1400;
2326     /**
2327      * Sets the parameter indicated by key.
2328      * @param key key indicates the parameter to be set.
2329      * @param value value of the parameter to be set.
2330      * @return true if the parameter is set successfully, false otherwise
2331      * {@hide}
2332      */
2333     @UnsupportedAppUsage
setParameter(int key, Parcel value)2334     private native boolean setParameter(int key, Parcel value);
2335 
2336     /**
2337      * Sets the audio attributes for this MediaPlayer.
2338      * See {@link AudioAttributes} for how to build and configure an instance of this class.
2339      * You must call this method before {@link #prepare()} or {@link #prepareAsync()} in order
2340      * for the audio attributes to become effective thereafter.
2341      * @param attributes a non-null set of audio attributes
2342      */
setAudioAttributes(AudioAttributes attributes)2343     public void setAudioAttributes(AudioAttributes attributes) throws IllegalArgumentException {
2344         if (attributes == null) {
2345             final String msg = "Cannot set AudioAttributes to null";
2346             throw new IllegalArgumentException(msg);
2347         }
2348         baseUpdateAudioAttributes(attributes);
2349         Parcel pattributes = Parcel.obtain();
2350         attributes.writeToParcel(pattributes, AudioAttributes.FLATTEN_TAGS);
2351         setParameter(KEY_PARAMETER_AUDIO_ATTRIBUTES, pattributes);
2352         pattributes.recycle();
2353     }
2354 
2355     /**
2356      * Sets the player to be looping or non-looping.
2357      *
2358      * @param looping whether to loop or not
2359      */
setLooping(boolean looping)2360     public native void setLooping(boolean looping);
2361 
2362     /**
2363      * Checks whether the MediaPlayer is looping or non-looping.
2364      *
2365      * @return true if the MediaPlayer is currently looping, false otherwise
2366      */
isLooping()2367     public native boolean isLooping();
2368 
2369     /**
2370      * Sets the volume on this player.
2371      * This API is recommended for balancing the output of audio streams
2372      * within an application. Unless you are writing an application to
2373      * control user settings, this API should be used in preference to
2374      * {@link AudioManager#setStreamVolume(int, int, int)} which sets the volume of ALL streams of
2375      * a particular type. Note that the passed volume values are raw scalars in range 0.0 to 1.0.
2376      * UI controls should be scaled logarithmically.
2377      *
2378      * @param leftVolume left volume scalar
2379      * @param rightVolume right volume scalar
2380      */
2381     /*
2382      * FIXME: Merge this into javadoc comment above when setVolume(float) is not @hide.
2383      * The single parameter form below is preferred if the channel volumes don't need
2384      * to be set independently.
2385      */
setVolume(float leftVolume, float rightVolume)2386     public void setVolume(float leftVolume, float rightVolume) {
2387         baseSetVolume(leftVolume, rightVolume);
2388     }
2389 
2390     @Override
playerSetVolume(boolean muting, float leftVolume, float rightVolume)2391     void playerSetVolume(boolean muting, float leftVolume, float rightVolume) {
2392         _setVolume(muting ? 0.0f : leftVolume, muting ? 0.0f : rightVolume);
2393     }
2394 
_setVolume(float leftVolume, float rightVolume)2395     private native void _setVolume(float leftVolume, float rightVolume);
2396 
2397     /**
2398      * Similar, excepts sets volume of all channels to same value.
2399      * @hide
2400      */
setVolume(float volume)2401     public void setVolume(float volume) {
2402         setVolume(volume, volume);
2403     }
2404 
2405     /**
2406      * Sets the audio session ID.
2407      *
2408      * @param sessionId the audio session ID.
2409      * The audio session ID is a system wide unique identifier for the audio stream played by
2410      * this MediaPlayer instance.
2411      * The primary use of the audio session ID  is to associate audio effects to a particular
2412      * instance of MediaPlayer: if an audio session ID is provided when creating an audio effect,
2413      * this effect will be applied only to the audio content of media players within the same
2414      * audio session and not to the output mix.
2415      * When created, a MediaPlayer instance automatically generates its own audio session ID.
2416      * However, it is possible to force this player to be part of an already existing audio session
2417      * by calling this method.
2418      * This method must be called before one of the overloaded <code> setDataSource </code> methods.
2419      * Note that session id set using this method will override device-specific audio session id,
2420      * if the {@link MediaPlayer} was instantiated using device-specific {@link Context} -
2421      * see {@link MediaPlayer#MediaPlayer(Context)}.
2422      * @throws IllegalStateException if it is called in an invalid state
2423      */
setAudioSessionId(int sessionId)2424     public void setAudioSessionId(int sessionId)
2425             throws IllegalArgumentException, IllegalStateException {
2426         native_setAudioSessionId(sessionId);
2427         baseUpdateSessionId(sessionId);
2428     }
2429 
native_setAudioSessionId(int sessionId)2430     private native void native_setAudioSessionId(int sessionId);
2431 
2432     /**
2433      * Returns the audio session ID.
2434      *
2435      * @return the audio session ID. {@see #setAudioSessionId(int)}
2436      * Note that the audio session ID is 0 only if a problem occured when the MediaPlayer was contructed.
2437      */
getAudioSessionId()2438     public native int getAudioSessionId();
2439 
2440     /**
2441      * Attaches an auxiliary effect to the player. A typical auxiliary effect is a reverberation
2442      * effect which can be applied on any sound source that directs a certain amount of its
2443      * energy to this effect. This amount is defined by setAuxEffectSendLevel().
2444      * See {@link #setAuxEffectSendLevel(float)}.
2445      * <p>After creating an auxiliary effect (e.g.
2446      * {@link android.media.audiofx.EnvironmentalReverb}), retrieve its ID with
2447      * {@link android.media.audiofx.AudioEffect#getId()} and use it when calling this method
2448      * to attach the player to the effect.
2449      * <p>To detach the effect from the player, call this method with a null effect id.
2450      * <p>This method must be called after one of the overloaded <code> setDataSource </code>
2451      * methods.
2452      * @param effectId system wide unique id of the effect to attach
2453      */
attachAuxEffect(int effectId)2454     public native void attachAuxEffect(int effectId);
2455 
2456 
2457     /**
2458      * Sets the send level of the player to the attached auxiliary effect.
2459      * See {@link #attachAuxEffect(int)}. The level value range is 0 to 1.0.
2460      * <p>By default the send level is 0, so even if an effect is attached to the player
2461      * this method must be called for the effect to be applied.
2462      * <p>Note that the passed level value is a raw scalar. UI controls should be scaled
2463      * logarithmically: the gain applied by audio framework ranges from -72dB to 0dB,
2464      * so an appropriate conversion from linear UI input x to level is:
2465      * x == 0 -> level = 0
2466      * 0 < x <= R -> level = 10^(72*(x-R)/20/R)
2467      * @param level send level scalar
2468      */
setAuxEffectSendLevel(float level)2469     public void setAuxEffectSendLevel(float level) {
2470         baseSetAuxEffectSendLevel(level);
2471     }
2472 
2473     @Override
playerSetAuxEffectSendLevel(boolean muting, float level)2474     int playerSetAuxEffectSendLevel(boolean muting, float level) {
2475         _setAuxEffectSendLevel(muting ? 0.0f : level);
2476         return AudioSystem.SUCCESS;
2477     }
2478 
_setAuxEffectSendLevel(float level)2479     private native void _setAuxEffectSendLevel(float level);
2480 
2481     /*
2482      * @param request Parcel destinated to the media player. The
2483      *                Interface token must be set to the IMediaPlayer
2484      *                one to be routed correctly through the system.
2485      * @param reply[out] Parcel that will contain the reply.
2486      * @return The status code.
2487      */
native_invoke(Parcel request, Parcel reply)2488     private native final int native_invoke(Parcel request, Parcel reply);
2489 
2490 
2491     /*
2492      * @param update_only If true fetch only the set of metadata that have
2493      *                    changed since the last invocation of getMetadata.
2494      *                    The set is built using the unfiltered
2495      *                    notifications the native player sent to the
2496      *                    MediaPlayerService during that period of
2497      *                    time. If false, all the metadatas are considered.
2498      * @param apply_filter  If true, once the metadata set has been built based on
2499      *                     the value update_only, the current filter is applied.
2500      * @param reply[out] On return contains the serialized
2501      *                   metadata. Valid only if the call was successful.
2502      * @return The status code.
2503      */
native_getMetadata(boolean update_only, boolean apply_filter, Parcel reply)2504     private native final boolean native_getMetadata(boolean update_only,
2505                                                     boolean apply_filter,
2506                                                     Parcel reply);
2507 
2508     /*
2509      * @param request Parcel with the 2 serialized lists of allowed
2510      *                metadata types followed by the one to be
2511      *                dropped. Each list starts with an integer
2512      *                indicating the number of metadata type elements.
2513      * @return The status code.
2514      */
native_setMetadataFilter(Parcel request)2515     private native final int native_setMetadataFilter(Parcel request);
2516 
native_init()2517     private static native final void native_init();
native_setup(Object mediaplayerThis, @NonNull Parcel attributionSource, int audioSessionId)2518     private native void native_setup(Object mediaplayerThis,
2519             @NonNull Parcel attributionSource, int audioSessionId);
native_finalize()2520     private native final void native_finalize();
2521 
2522     /**
2523      * Class for MediaPlayer to return each audio/video/subtitle track's metadata.
2524      *
2525      * @see android.media.MediaPlayer#getTrackInfo
2526      */
2527     // The creator needs to be pulic, which requires removing the @UnsupportedAppUsage
2528     @SuppressWarnings("ParcelableCreator")
2529     static public class TrackInfo implements Parcelable {
2530         /**
2531          * Gets the track type.
2532          * @return TrackType which indicates if the track is video, audio, timed text.
2533          */
getTrackType()2534         public @TrackType int getTrackType() {
2535             return mTrackType;
2536         }
2537 
2538         /**
2539          * Gets the language code of the track.
2540          * @return a language code in either way of ISO-639-1 or ISO-639-2.
2541          * When the language is unknown or could not be determined,
2542          * ISO-639-2 language code, "und", is returned.
2543          */
getLanguage()2544         public String getLanguage() {
2545             String language = mFormat.getString(MediaFormat.KEY_LANGUAGE);
2546             return language == null ? "und" : language;
2547         }
2548 
2549         /**
2550          * Returns whether this track contains haptic channels in the audio track.
2551          * @hide
2552          */
hasHapticChannels()2553         public boolean hasHapticChannels() {
2554             return mFormat != null && mFormat.containsKey(MediaFormat.KEY_HAPTIC_CHANNEL_COUNT)
2555                     && mFormat.getInteger(MediaFormat.KEY_HAPTIC_CHANNEL_COUNT) > 0;
2556         }
2557 
2558         /**
2559          * Gets the {@link MediaFormat} of the track.  If the format is
2560          * unknown or could not be determined, null is returned.
2561          */
getFormat()2562         public MediaFormat getFormat() {
2563             // Note: The format isn't exposed for audio because it is incomplete.
2564             if (mTrackType == MEDIA_TRACK_TYPE_TIMEDTEXT
2565                     || mTrackType == MEDIA_TRACK_TYPE_SUBTITLE) {
2566                 return mFormat;
2567             }
2568             return null;
2569         }
2570 
2571         public static final int MEDIA_TRACK_TYPE_UNKNOWN = 0;
2572         public static final int MEDIA_TRACK_TYPE_VIDEO = 1;
2573         public static final int MEDIA_TRACK_TYPE_AUDIO = 2;
2574         public static final int MEDIA_TRACK_TYPE_TIMEDTEXT = 3;
2575         public static final int MEDIA_TRACK_TYPE_SUBTITLE = 4;
2576         public static final int MEDIA_TRACK_TYPE_METADATA = 5;
2577 
2578         /** @hide */
2579         @IntDef(flag = false, prefix = "MEDIA_TRACK_TYPE", value = {
2580                 MEDIA_TRACK_TYPE_UNKNOWN,
2581                 MEDIA_TRACK_TYPE_VIDEO,
2582                 MEDIA_TRACK_TYPE_AUDIO,
2583                 MEDIA_TRACK_TYPE_TIMEDTEXT,
2584                 MEDIA_TRACK_TYPE_SUBTITLE,
2585                 MEDIA_TRACK_TYPE_METADATA }
2586         )
2587         @Retention(RetentionPolicy.SOURCE)
2588         public @interface TrackType {}
2589 
2590 
2591         final int mTrackType;
2592         final MediaFormat mFormat;
2593 
TrackInfo(Parcel in)2594         TrackInfo(Parcel in) {
2595             mTrackType = in.readInt();
2596             // TODO: parcel in the full MediaFormat; currently we are using createSubtitleFormat
2597             // even for audio/video tracks, meaning we only set the mime and language.
2598             String mime = in.readString();
2599             String language = in.readString();
2600             mFormat = MediaFormat.createSubtitleFormat(mime, language);
2601 
2602             if (mTrackType == MEDIA_TRACK_TYPE_SUBTITLE) {
2603                 mFormat.setInteger(MediaFormat.KEY_IS_AUTOSELECT, in.readInt());
2604                 mFormat.setInteger(MediaFormat.KEY_IS_DEFAULT, in.readInt());
2605                 mFormat.setInteger(MediaFormat.KEY_IS_FORCED_SUBTITLE, in.readInt());
2606             } else if (mTrackType == MEDIA_TRACK_TYPE_AUDIO) {
2607                 boolean hasHapticChannels = in.readBoolean();
2608                 if (hasHapticChannels) {
2609                     mFormat.setInteger(MediaFormat.KEY_HAPTIC_CHANNEL_COUNT, in.readInt());
2610                 }
2611             }
2612         }
2613 
2614         /** @hide */
TrackInfo(int type, MediaFormat format)2615         TrackInfo(int type, MediaFormat format) {
2616             mTrackType = type;
2617             mFormat = format;
2618         }
2619 
2620         /**
2621          * {@inheritDoc}
2622          */
2623         @Override
describeContents()2624         public int describeContents() {
2625             return 0;
2626         }
2627 
2628         /**
2629          * {@inheritDoc}
2630          */
2631         @Override
writeToParcel(Parcel dest, int flags)2632         public void writeToParcel(Parcel dest, int flags) {
2633             dest.writeInt(mTrackType);
2634             dest.writeString(mFormat.getString(MediaFormat.KEY_MIME));
2635             dest.writeString(getLanguage());
2636 
2637             if (mTrackType == MEDIA_TRACK_TYPE_SUBTITLE) {
2638                 dest.writeInt(mFormat.getInteger(MediaFormat.KEY_IS_AUTOSELECT));
2639                 dest.writeInt(mFormat.getInteger(MediaFormat.KEY_IS_DEFAULT));
2640                 dest.writeInt(mFormat.getInteger(MediaFormat.KEY_IS_FORCED_SUBTITLE));
2641             } else if (mTrackType == MEDIA_TRACK_TYPE_AUDIO) {
2642                 boolean hasHapticChannels =
2643                         mFormat.containsKey(MediaFormat.KEY_HAPTIC_CHANNEL_COUNT);
2644                 dest.writeBoolean(hasHapticChannels);
2645                 if (hasHapticChannels) {
2646                     dest.writeInt(mFormat.getInteger(MediaFormat.KEY_HAPTIC_CHANNEL_COUNT));
2647                 }
2648             }
2649         }
2650 
2651         @Override
toString()2652         public String toString() {
2653             StringBuilder out = new StringBuilder(128);
2654             out.append(getClass().getName());
2655             out.append('{');
2656             switch (mTrackType) {
2657             case MEDIA_TRACK_TYPE_VIDEO:
2658                 out.append("VIDEO");
2659                 break;
2660             case MEDIA_TRACK_TYPE_AUDIO:
2661                 out.append("AUDIO");
2662                 break;
2663             case MEDIA_TRACK_TYPE_TIMEDTEXT:
2664                 out.append("TIMEDTEXT");
2665                 break;
2666             case MEDIA_TRACK_TYPE_SUBTITLE:
2667                 out.append("SUBTITLE");
2668                 break;
2669             default:
2670                 out.append("UNKNOWN");
2671                 break;
2672             }
2673             out.append(", " + mFormat.toString());
2674             out.append("}");
2675             return out.toString();
2676         }
2677 
2678         /**
2679          * Used to read a TrackInfo from a Parcel.
2680          */
2681         @UnsupportedAppUsage
2682         static final @android.annotation.NonNull Parcelable.Creator<TrackInfo> CREATOR
2683                 = new Parcelable.Creator<TrackInfo>() {
2684                     @Override
2685                     public TrackInfo createFromParcel(Parcel in) {
2686                         return new TrackInfo(in);
2687                     }
2688 
2689                     @Override
2690                     public TrackInfo[] newArray(int size) {
2691                         return new TrackInfo[size];
2692                     }
2693                 };
2694 
2695     };
2696 
2697     // We would like domain specific classes with more informative names than the `first` and `second`
2698     // in generic Pair, but we would also like to avoid creating new/trivial classes. As a compromise
2699     // we document the meanings of `first` and `second` here:
2700     //
2701     // Pair.first - inband track index; non-null iff representing an inband track.
2702     // Pair.second - a SubtitleTrack registered with mSubtitleController; non-null iff representing
2703     //               an inband subtitle track or any out-of-band track (subtitle or timedtext).
2704     private Vector<Pair<Integer, SubtitleTrack>> mIndexTrackPairs = new Vector<>();
2705     private BitSet mInbandTrackIndices = new BitSet();
2706 
2707     /**
2708      * Returns an array of track information.
2709      *
2710      * @return Array of track info. The total number of tracks is the array length.
2711      * Must be called again if an external timed text source has been added after any of the
2712      * addTimedTextSource methods are called.
2713      * @throws IllegalStateException if it is called in an invalid state.
2714      */
getTrackInfo()2715     public TrackInfo[] getTrackInfo() throws IllegalStateException {
2716         TrackInfo trackInfo[] = getInbandTrackInfo();
2717         // add out-of-band tracks
2718         synchronized (mIndexTrackPairs) {
2719             TrackInfo allTrackInfo[] = new TrackInfo[mIndexTrackPairs.size()];
2720             for (int i = 0; i < allTrackInfo.length; i++) {
2721                 Pair<Integer, SubtitleTrack> p = mIndexTrackPairs.get(i);
2722                 if (p.first != null) {
2723                     // inband track
2724                     allTrackInfo[i] = trackInfo[p.first];
2725                 } else {
2726                     SubtitleTrack track = p.second;
2727                     allTrackInfo[i] = new TrackInfo(track.getTrackType(), track.getFormat());
2728                 }
2729             }
2730             return allTrackInfo;
2731         }
2732     }
2733 
getInbandTrackInfo()2734     private TrackInfo[] getInbandTrackInfo() throws IllegalStateException {
2735         Parcel request = Parcel.obtain();
2736         Parcel reply = Parcel.obtain();
2737         try {
2738             request.writeInterfaceToken(IMEDIA_PLAYER);
2739             request.writeInt(INVOKE_ID_GET_TRACK_INFO);
2740             invoke(request, reply);
2741             TrackInfo trackInfo[] = reply.createTypedArray(TrackInfo.CREATOR);
2742             return trackInfo;
2743         } finally {
2744             request.recycle();
2745             reply.recycle();
2746         }
2747     }
2748 
2749     /* Do not change these values without updating their counterparts
2750      * in include/media/stagefright/MediaDefs.h and media/libstagefright/MediaDefs.cpp!
2751      */
2752     /**
2753      * MIME type for SubRip (SRT) container. Used in addTimedTextSource APIs.
2754      * @deprecated use {@link MediaFormat#MIMETYPE_TEXT_SUBRIP}
2755      */
2756     public static final String MEDIA_MIMETYPE_TEXT_SUBRIP = MediaFormat.MIMETYPE_TEXT_SUBRIP;
2757 
2758     /**
2759      * MIME type for WebVTT subtitle data.
2760      * @hide
2761      * @deprecated
2762      */
2763     public static final String MEDIA_MIMETYPE_TEXT_VTT = MediaFormat.MIMETYPE_TEXT_VTT;
2764 
2765     /**
2766      * MIME type for CEA-608 closed caption data.
2767      * @hide
2768      * @deprecated
2769      */
2770     public static final String MEDIA_MIMETYPE_TEXT_CEA_608 = MediaFormat.MIMETYPE_TEXT_CEA_608;
2771 
2772     /**
2773      * MIME type for CEA-708 closed caption data.
2774      * @hide
2775      * @deprecated
2776      */
2777     public static final String MEDIA_MIMETYPE_TEXT_CEA_708 = MediaFormat.MIMETYPE_TEXT_CEA_708;
2778 
2779     /*
2780      * A helper function to check if the mime type is supported by media framework.
2781      */
availableMimeTypeForExternalSource(String mimeType)2782     private static boolean availableMimeTypeForExternalSource(String mimeType) {
2783         if (MEDIA_MIMETYPE_TEXT_SUBRIP.equals(mimeType)) {
2784             return true;
2785         }
2786         return false;
2787     }
2788 
2789     private SubtitleController mSubtitleController;
2790 
2791     /** @hide */
2792     @UnsupportedAppUsage
setSubtitleAnchor( SubtitleController controller, SubtitleController.Anchor anchor)2793     public void setSubtitleAnchor(
2794             SubtitleController controller,
2795             SubtitleController.Anchor anchor) {
2796         // TODO: create SubtitleController in MediaPlayer
2797         mSubtitleController = controller;
2798         mSubtitleController.setAnchor(anchor);
2799     }
2800 
2801     /**
2802      * The private version of setSubtitleAnchor is used internally to set mSubtitleController if
2803      * necessary when clients don't provide their own SubtitleControllers using the public version
2804      * {@link #setSubtitleAnchor(SubtitleController, Anchor)} (e.g. {@link VideoView} provides one).
2805      */
setSubtitleAnchor()2806     private synchronized void setSubtitleAnchor() {
2807         if ((mSubtitleController == null) && (ActivityThread.currentApplication() != null)) {
2808             final TimeProvider timeProvider = (TimeProvider) getMediaTimeProvider();
2809             final HandlerThread thread = new HandlerThread("SetSubtitleAnchorThread");
2810             thread.start();
2811             Handler handler = new Handler(thread.getLooper());
2812             handler.post(new Runnable() {
2813                 @Override
2814                 public void run() {
2815                     Context context = ActivityThread.currentApplication();
2816                     mSubtitleController =
2817                             new SubtitleController(context, timeProvider, MediaPlayer.this);
2818                     mSubtitleController.setAnchor(new Anchor() {
2819                         @Override
2820                         public void setSubtitleWidget(RenderingWidget subtitleWidget) {
2821                         }
2822 
2823                         @Override
2824                         public Looper getSubtitleLooper() {
2825                             return timeProvider.mEventHandler.getLooper();
2826                         }
2827                     });
2828                     thread.getLooper().quitSafely();
2829                 }
2830             });
2831             try {
2832                 thread.join();
2833             } catch (InterruptedException e) {
2834                 Thread.currentThread().interrupt();
2835                 Log.w(TAG, "failed to join SetSubtitleAnchorThread");
2836             }
2837         }
2838     }
2839 
2840     private int mSelectedSubtitleTrackIndex = -1;
2841     private Vector<InputStream> mOpenSubtitleSources;
2842 
2843     private final OnSubtitleDataListener mIntSubtitleDataListener = new OnSubtitleDataListener() {
2844         @Override
2845         public void onSubtitleData(MediaPlayer mp, SubtitleData data) {
2846             int index = data.getTrackIndex();
2847             synchronized (mIndexTrackPairs) {
2848                 for (Pair<Integer, SubtitleTrack> p : mIndexTrackPairs) {
2849                     if (p.first != null && p.first == index && p.second != null) {
2850                         // inband subtitle track that owns data
2851                         SubtitleTrack track = p.second;
2852                         track.onData(data);
2853                     }
2854                 }
2855             }
2856         }
2857     };
2858 
2859     /** @hide */
2860     @Override
onSubtitleTrackSelected(SubtitleTrack track)2861     public void onSubtitleTrackSelected(SubtitleTrack track) {
2862         if (mSelectedSubtitleTrackIndex >= 0) {
2863             try {
2864                 selectOrDeselectInbandTrack(mSelectedSubtitleTrackIndex, false);
2865             } catch (IllegalStateException e) {
2866             }
2867             mSelectedSubtitleTrackIndex = -1;
2868         }
2869         synchronized (this) {
2870             mSubtitleDataListenerDisabled = true;
2871         }
2872         if (track == null) {
2873             return;
2874         }
2875 
2876         synchronized (mIndexTrackPairs) {
2877             for (Pair<Integer, SubtitleTrack> p : mIndexTrackPairs) {
2878                 if (p.first != null && p.second == track) {
2879                     // inband subtitle track that is selected
2880                     mSelectedSubtitleTrackIndex = p.first;
2881                     break;
2882                 }
2883             }
2884         }
2885 
2886         if (mSelectedSubtitleTrackIndex >= 0) {
2887             try {
2888                 selectOrDeselectInbandTrack(mSelectedSubtitleTrackIndex, true);
2889             } catch (IllegalStateException e) {
2890             }
2891             synchronized (this) {
2892                 mSubtitleDataListenerDisabled = false;
2893             }
2894         }
2895         // no need to select out-of-band tracks
2896     }
2897 
2898     /** @hide */
2899     @UnsupportedAppUsage
addSubtitleSource(InputStream is, MediaFormat format)2900     public void addSubtitleSource(InputStream is, MediaFormat format)
2901             throws IllegalStateException
2902     {
2903         final InputStream fIs = is;
2904         final MediaFormat fFormat = format;
2905 
2906         if (is != null) {
2907             // Ensure all input streams are closed.  It is also a handy
2908             // way to implement timeouts in the future.
2909             synchronized(mOpenSubtitleSources) {
2910                 mOpenSubtitleSources.add(is);
2911             }
2912         } else {
2913             Log.w(TAG, "addSubtitleSource called with null InputStream");
2914         }
2915 
2916         getMediaTimeProvider();
2917 
2918         // process each subtitle in its own thread
2919         final HandlerThread thread = new HandlerThread("SubtitleReadThread",
2920               Process.THREAD_PRIORITY_BACKGROUND + Process.THREAD_PRIORITY_MORE_FAVORABLE);
2921         thread.start();
2922         Handler handler = new Handler(thread.getLooper());
2923         handler.post(new Runnable() {
2924             private int addTrack() {
2925                 if (fIs == null || mSubtitleController == null) {
2926                     return MEDIA_INFO_UNSUPPORTED_SUBTITLE;
2927                 }
2928 
2929                 SubtitleTrack track = mSubtitleController.addTrack(fFormat);
2930                 if (track == null) {
2931                     return MEDIA_INFO_UNSUPPORTED_SUBTITLE;
2932                 }
2933 
2934                 // TODO: do the conversion in the subtitle track
2935                 Scanner scanner = new Scanner(fIs, "UTF-8");
2936                 String contents = scanner.useDelimiter("\\A").next();
2937                 synchronized(mOpenSubtitleSources) {
2938                     mOpenSubtitleSources.remove(fIs);
2939                 }
2940                 scanner.close();
2941                 synchronized (mIndexTrackPairs) {
2942                     mIndexTrackPairs.add(Pair.<Integer, SubtitleTrack>create(null, track));
2943                 }
2944                 synchronized (mTimeProviderLock) {
2945                     if (mTimeProvider != null) {
2946                         Handler h = mTimeProvider.mEventHandler;
2947                         int what = TimeProvider.NOTIFY;
2948                         int arg1 = TimeProvider.NOTIFY_TRACK_DATA;
2949                         Pair<SubtitleTrack, byte[]> trackData =
2950                                 Pair.create(track, contents.getBytes());
2951                         Message m = h.obtainMessage(what, arg1, 0, trackData);
2952                         h.sendMessage(m);
2953                     }
2954                 }
2955                 return MEDIA_INFO_EXTERNAL_METADATA_UPDATE;
2956             }
2957 
2958             public void run() {
2959                 int res = addTrack();
2960                 if (mEventHandler != null) {
2961                     Message m = mEventHandler.obtainMessage(MEDIA_INFO, res, 0, null);
2962                     mEventHandler.sendMessage(m);
2963                 }
2964                 thread.getLooper().quitSafely();
2965             }
2966         });
2967     }
2968 
scanInternalSubtitleTracks()2969     private void scanInternalSubtitleTracks() {
2970         setSubtitleAnchor();
2971 
2972         populateInbandTracks();
2973 
2974         if (mSubtitleController != null) {
2975             mSubtitleController.selectDefaultTrack();
2976         }
2977     }
2978 
populateInbandTracks()2979     private void populateInbandTracks() {
2980         TrackInfo[] tracks = getInbandTrackInfo();
2981         synchronized (mIndexTrackPairs) {
2982             for (int i = 0; i < tracks.length; i++) {
2983                 if (mInbandTrackIndices.get(i)) {
2984                     continue;
2985                 } else {
2986                     mInbandTrackIndices.set(i);
2987                 }
2988 
2989                 if (tracks[i] == null) {
2990                     Log.w(TAG, "unexpected NULL track at index " + i);
2991                 }
2992                 // newly appeared inband track
2993                 if (tracks[i] != null
2994                         && tracks[i].getTrackType() == TrackInfo.MEDIA_TRACK_TYPE_SUBTITLE) {
2995                     SubtitleTrack track = mSubtitleController.addTrack(
2996                             tracks[i].getFormat());
2997                     mIndexTrackPairs.add(Pair.create(i, track));
2998                 } else {
2999                     mIndexTrackPairs.add(Pair.<Integer, SubtitleTrack>create(i, null));
3000                 }
3001             }
3002         }
3003     }
3004 
3005     /* TODO: Limit the total number of external timed text source to a reasonable number.
3006      */
3007     /**
3008      * Adds an external timed text source file.
3009      *
3010      * Currently supported format is SubRip with the file extension .srt, case insensitive.
3011      * Note that a single external timed text source may contain multiple tracks in it.
3012      * One can find the total number of available tracks using {@link #getTrackInfo()} to see what
3013      * additional tracks become available after this method call.
3014      *
3015      * @param path The file path of external timed text source file.
3016      * @param mimeType The mime type of the file. Must be one of the mime types listed above.
3017      * @throws IOException if the file cannot be accessed or is corrupted.
3018      * @throws IllegalArgumentException if the mimeType is not supported.
3019      * @throws IllegalStateException if called in an invalid state.
3020      */
addTimedTextSource(String path, String mimeType)3021     public void addTimedTextSource(String path, String mimeType)
3022             throws IOException, IllegalArgumentException, IllegalStateException {
3023         if (!availableMimeTypeForExternalSource(mimeType)) {
3024             final String msg = "Illegal mimeType for timed text source: " + mimeType;
3025             throw new IllegalArgumentException(msg);
3026         }
3027 
3028         final File file = new File(path);
3029         try (FileInputStream is = new FileInputStream(file)) {
3030             addTimedTextSource(is.getFD(), mimeType);
3031         }
3032     }
3033 
3034     /**
3035      * Adds an external timed text source file (Uri).
3036      *
3037      * Currently supported format is SubRip with the file extension .srt, case insensitive.
3038      * Note that a single external timed text source may contain multiple tracks in it.
3039      * One can find the total number of available tracks using {@link #getTrackInfo()} to see what
3040      * additional tracks become available after this method call.
3041      *
3042      * @param context the Context to use when resolving the Uri
3043      * @param uri the Content URI of the data you want to play
3044      * @param mimeType The mime type of the file. Must be one of the mime types listed above.
3045      * @throws IOException if the file cannot be accessed or is corrupted.
3046      * @throws IllegalArgumentException if the mimeType is not supported.
3047      * @throws IllegalStateException if called in an invalid state.
3048      */
addTimedTextSource(Context context, Uri uri, String mimeType)3049     public void addTimedTextSource(Context context, Uri uri, String mimeType)
3050             throws IOException, IllegalArgumentException, IllegalStateException {
3051         String scheme = uri.getScheme();
3052         if(scheme == null || scheme.equals("file")) {
3053             addTimedTextSource(uri.getPath(), mimeType);
3054             return;
3055         }
3056 
3057         AssetFileDescriptor fd = null;
3058         try {
3059             boolean optimize = SystemProperties.getBoolean("fuse.sys.transcode_player_optimize",
3060                     false);
3061             ContentResolver resolver = context.getContentResolver();
3062             Bundle opts = new Bundle();
3063             opts.putBoolean("android.provider.extra.ACCEPT_ORIGINAL_MEDIA_FORMAT", true);
3064             fd = optimize ? resolver.openTypedAssetFileDescriptor(uri, "*/*", opts)
3065                     : resolver.openAssetFileDescriptor(uri, "r");
3066             if (fd == null) {
3067                 return;
3068             }
3069             addTimedTextSource(fd.getFileDescriptor(), mimeType);
3070             return;
3071         } catch (SecurityException ex) {
3072         } catch (IOException ex) {
3073         } finally {
3074             if (fd != null) {
3075                 fd.close();
3076             }
3077         }
3078     }
3079 
3080     /**
3081      * Adds an external timed text source file (FileDescriptor).
3082      *
3083      * It is the caller's responsibility to close the file descriptor.
3084      * It is safe to do so as soon as this call returns.
3085      *
3086      * Currently supported format is SubRip. Note that a single external timed text source may
3087      * contain multiple tracks in it. One can find the total number of available tracks
3088      * using {@link #getTrackInfo()} to see what additional tracks become available
3089      * after this method call.
3090      *
3091      * @param fd the FileDescriptor for the file you want to play
3092      * @param mimeType The mime type of the file. Must be one of the mime types listed above.
3093      * @throws IllegalArgumentException if the mimeType is not supported.
3094      * @throws IllegalStateException if called in an invalid state.
3095      */
addTimedTextSource(FileDescriptor fd, String mimeType)3096     public void addTimedTextSource(FileDescriptor fd, String mimeType)
3097             throws IllegalArgumentException, IllegalStateException {
3098         // intentionally less than LONG_MAX
3099         addTimedTextSource(fd, 0, 0x7ffffffffffffffL, mimeType);
3100     }
3101 
3102     /**
3103      * Adds an external timed text file (FileDescriptor).
3104      *
3105      * It is the caller's responsibility to close the file descriptor.
3106      * It is safe to do so as soon as this call returns.
3107      *
3108      * Currently supported format is SubRip. Note that a single external timed text source may
3109      * contain multiple tracks in it. One can find the total number of available tracks
3110      * using {@link #getTrackInfo()} to see what additional tracks become available
3111      * after this method call.
3112      *
3113      * @param fd the FileDescriptor for the file you want to play
3114      * @param offset the offset into the file where the data to be played starts, in bytes
3115      * @param length the length in bytes of the data to be played
3116      * @param mime The mime type of the file. Must be one of the mime types listed above.
3117      * @throws IllegalArgumentException if the mimeType is not supported.
3118      * @throws IllegalStateException if called in an invalid state.
3119      */
addTimedTextSource(FileDescriptor fd, long offset, long length, String mime)3120     public void addTimedTextSource(FileDescriptor fd, long offset, long length, String mime)
3121             throws IllegalArgumentException, IllegalStateException {
3122         if (!availableMimeTypeForExternalSource(mime)) {
3123             throw new IllegalArgumentException("Illegal mimeType for timed text source: " + mime);
3124         }
3125 
3126         final FileDescriptor dupedFd;
3127         try {
3128             dupedFd = Os.dup(fd);
3129         } catch (ErrnoException ex) {
3130             Log.e(TAG, ex.getMessage(), ex);
3131             throw new RuntimeException(ex);
3132         }
3133 
3134         final MediaFormat fFormat = new MediaFormat();
3135         fFormat.setString(MediaFormat.KEY_MIME, mime);
3136         fFormat.setInteger(MediaFormat.KEY_IS_TIMED_TEXT, 1);
3137 
3138         // A MediaPlayer created by a VideoView should already have its mSubtitleController set.
3139         if (mSubtitleController == null) {
3140             setSubtitleAnchor();
3141         }
3142 
3143         if (!mSubtitleController.hasRendererFor(fFormat)) {
3144             // test and add not atomic
3145             Context context = ActivityThread.currentApplication();
3146             mSubtitleController.registerRenderer(new SRTRenderer(context, mEventHandler));
3147         }
3148         final SubtitleTrack track = mSubtitleController.addTrack(fFormat);
3149         synchronized (mIndexTrackPairs) {
3150             mIndexTrackPairs.add(Pair.<Integer, SubtitleTrack>create(null, track));
3151         }
3152 
3153         getMediaTimeProvider();
3154 
3155         final long offset2 = offset;
3156         final long length2 = length;
3157         final HandlerThread thread = new HandlerThread(
3158                 "TimedTextReadThread",
3159                 Process.THREAD_PRIORITY_BACKGROUND + Process.THREAD_PRIORITY_MORE_FAVORABLE);
3160         thread.start();
3161         Handler handler = new Handler(thread.getLooper());
3162         handler.post(new Runnable() {
3163             private int addTrack() {
3164                 final ByteArrayOutputStream bos = new ByteArrayOutputStream();
3165                 try {
3166                     Os.lseek(dupedFd, offset2, OsConstants.SEEK_SET);
3167                     byte[] buffer = new byte[4096];
3168                     for (long total = 0; total < length2;) {
3169                         int bytesToRead = (int) Math.min(buffer.length, length2 - total);
3170                         int bytes = IoBridge.read(dupedFd, buffer, 0, bytesToRead);
3171                         if (bytes < 0) {
3172                             break;
3173                         } else {
3174                             bos.write(buffer, 0, bytes);
3175                             total += bytes;
3176                         }
3177                     }
3178                     synchronized (mTimeProviderLock) {
3179                         if (mTimeProvider != null) {
3180                             Handler h = mTimeProvider.mEventHandler;
3181                             int what = TimeProvider.NOTIFY;
3182                             int arg1 = TimeProvider.NOTIFY_TRACK_DATA;
3183                             Pair<SubtitleTrack, byte[]> trackData =
3184                                     Pair.create(track, bos.toByteArray());
3185                             Message m = h.obtainMessage(what, arg1, 0, trackData);
3186                             h.sendMessage(m);
3187                         }
3188                     }
3189                     return MEDIA_INFO_EXTERNAL_METADATA_UPDATE;
3190                 } catch (Exception e) {
3191                     Log.e(TAG, e.getMessage(), e);
3192                     return MEDIA_INFO_TIMED_TEXT_ERROR;
3193                 } finally {
3194                     try {
3195                         Os.close(dupedFd);
3196                     } catch (ErrnoException e) {
3197                         Log.e(TAG, e.getMessage(), e);
3198                     }
3199                 }
3200             }
3201 
3202             public void run() {
3203                 int res = addTrack();
3204                 if (mEventHandler != null) {
3205                     Message m = mEventHandler.obtainMessage(MEDIA_INFO, res, 0, null);
3206                     mEventHandler.sendMessage(m);
3207                 }
3208                 thread.getLooper().quitSafely();
3209             }
3210         });
3211     }
3212 
3213     /**
3214      * Returns the index of the audio, video, or subtitle track currently selected for playback,
3215      * The return value is an index into the array returned by {@link #getTrackInfo()}, and can
3216      * be used in calls to {@link #selectTrack(int)} or {@link #deselectTrack(int)}.
3217      *
3218      * @param trackType should be one of {@link TrackInfo#MEDIA_TRACK_TYPE_VIDEO},
3219      * {@link TrackInfo#MEDIA_TRACK_TYPE_AUDIO}, or
3220      * {@link TrackInfo#MEDIA_TRACK_TYPE_SUBTITLE}
3221      * @return index of the audio, video, or subtitle track currently selected for playback;
3222      * a negative integer is returned when there is no selected track for {@code trackType} or
3223      * when {@code trackType} is not one of audio, video, or subtitle.
3224      * @throws IllegalStateException if called after {@link #release()}
3225      *
3226      * @see #getTrackInfo()
3227      * @see #selectTrack(int)
3228      * @see #deselectTrack(int)
3229      */
getSelectedTrack(int trackType)3230     public int getSelectedTrack(int trackType) throws IllegalStateException {
3231         if (mSubtitleController != null
3232                 && (trackType == TrackInfo.MEDIA_TRACK_TYPE_SUBTITLE
3233                 || trackType == TrackInfo.MEDIA_TRACK_TYPE_TIMEDTEXT)) {
3234             SubtitleTrack subtitleTrack = mSubtitleController.getSelectedTrack();
3235             if (subtitleTrack != null) {
3236                 synchronized (mIndexTrackPairs) {
3237                     for (int i = 0; i < mIndexTrackPairs.size(); i++) {
3238                         Pair<Integer, SubtitleTrack> p = mIndexTrackPairs.get(i);
3239                         if (p.second == subtitleTrack && subtitleTrack.getTrackType() == trackType) {
3240                             return i;
3241                         }
3242                     }
3243                 }
3244             }
3245         }
3246 
3247         Parcel request = Parcel.obtain();
3248         Parcel reply = Parcel.obtain();
3249         try {
3250             request.writeInterfaceToken(IMEDIA_PLAYER);
3251             request.writeInt(INVOKE_ID_GET_SELECTED_TRACK);
3252             request.writeInt(trackType);
3253             invoke(request, reply);
3254             int inbandTrackIndex = reply.readInt();
3255             synchronized (mIndexTrackPairs) {
3256                 for (int i = 0; i < mIndexTrackPairs.size(); i++) {
3257                     Pair<Integer, SubtitleTrack> p = mIndexTrackPairs.get(i);
3258                     if (p.first != null && p.first == inbandTrackIndex) {
3259                         return i;
3260                     }
3261                 }
3262             }
3263             return -1;
3264         } finally {
3265             request.recycle();
3266             reply.recycle();
3267         }
3268     }
3269 
3270     /**
3271      * Selects a track.
3272      * <p>
3273      * If a MediaPlayer is in invalid state, it throws an IllegalStateException exception.
3274      * If a MediaPlayer is in <em>Started</em> state, the selected track is presented immediately.
3275      * If a MediaPlayer is not in Started state, it just marks the track to be played.
3276      * </p>
3277      * <p>
3278      * In any valid state, if it is called multiple times on the same type of track (ie. Video,
3279      * Audio, Timed Text), the most recent one will be chosen.
3280      * </p>
3281      * <p>
3282      * The first audio and video tracks are selected by default if available, even though
3283      * this method is not called. However, no timed text track will be selected until
3284      * this function is called.
3285      * </p>
3286      * <p>
3287      * Currently, only timed text, subtitle or audio tracks can be selected via this method.
3288      * In addition, the support for selecting an audio track at runtime is pretty limited
3289      * in that an audio track can only be selected in the <em>Prepared</em> state.
3290      * </p>
3291      * @param index the index of the track to be selected. The valid range of the index
3292      * is 0..total number of track - 1. The total number of tracks as well as the type of
3293      * each individual track can be found by calling {@link #getTrackInfo()} method.
3294      * @throws IllegalStateException if called in an invalid state.
3295      *
3296      * @see android.media.MediaPlayer#getTrackInfo
3297      */
selectTrack(int index)3298     public void selectTrack(int index) throws IllegalStateException {
3299         selectOrDeselectTrack(index, true /* select */);
3300     }
3301 
3302     /**
3303      * Deselect a track.
3304      * <p>
3305      * Currently, the track must be a timed text track and no audio or video tracks can be
3306      * deselected. If the timed text track identified by index has not been
3307      * selected before, it throws an exception.
3308      * </p>
3309      * @param index the index of the track to be deselected. The valid range of the index
3310      * is 0..total number of tracks - 1. The total number of tracks as well as the type of
3311      * each individual track can be found by calling {@link #getTrackInfo()} method.
3312      * @throws IllegalStateException if called in an invalid state.
3313      *
3314      * @see android.media.MediaPlayer#getTrackInfo
3315      */
deselectTrack(int index)3316     public void deselectTrack(int index) throws IllegalStateException {
3317         selectOrDeselectTrack(index, false /* select */);
3318     }
3319 
selectOrDeselectTrack(int index, boolean select)3320     private void selectOrDeselectTrack(int index, boolean select)
3321             throws IllegalStateException {
3322         // handle subtitle track through subtitle controller
3323         populateInbandTracks();
3324 
3325         Pair<Integer,SubtitleTrack> p = null;
3326         try {
3327             p = mIndexTrackPairs.get(index);
3328         } catch (ArrayIndexOutOfBoundsException e) {
3329             // ignore bad index
3330             return;
3331         }
3332 
3333         SubtitleTrack track = p.second;
3334         if (track == null) {
3335             // inband (de)select
3336             selectOrDeselectInbandTrack(p.first, select);
3337             return;
3338         }
3339 
3340         if (mSubtitleController == null) {
3341             return;
3342         }
3343 
3344         if (!select) {
3345             // out-of-band deselect
3346             if (mSubtitleController.getSelectedTrack() == track) {
3347                 mSubtitleController.selectTrack(null);
3348             } else {
3349                 Log.w(TAG, "trying to deselect track that was not selected");
3350             }
3351             return;
3352         }
3353 
3354         // out-of-band select
3355         if (track.getTrackType() == TrackInfo.MEDIA_TRACK_TYPE_TIMEDTEXT) {
3356             int ttIndex = getSelectedTrack(TrackInfo.MEDIA_TRACK_TYPE_TIMEDTEXT);
3357             synchronized (mIndexTrackPairs) {
3358                 if (ttIndex >= 0 && ttIndex < mIndexTrackPairs.size()) {
3359                     Pair<Integer,SubtitleTrack> p2 = mIndexTrackPairs.get(ttIndex);
3360                     if (p2.first != null && p2.second == null) {
3361                         // deselect inband counterpart
3362                         selectOrDeselectInbandTrack(p2.first, false);
3363                     }
3364                 }
3365             }
3366         }
3367         mSubtitleController.selectTrack(track);
3368     }
3369 
selectOrDeselectInbandTrack(int index, boolean select)3370     private void selectOrDeselectInbandTrack(int index, boolean select)
3371             throws IllegalStateException {
3372         Parcel request = Parcel.obtain();
3373         Parcel reply = Parcel.obtain();
3374         try {
3375             request.writeInterfaceToken(IMEDIA_PLAYER);
3376             request.writeInt(select? INVOKE_ID_SELECT_TRACK: INVOKE_ID_DESELECT_TRACK);
3377             request.writeInt(index);
3378             invoke(request, reply);
3379         } finally {
3380             request.recycle();
3381             reply.recycle();
3382         }
3383     }
3384 
3385 
3386     /**
3387      * @param reply Parcel with audio/video duration info for battery
3388                     tracking usage
3389      * @return The status code.
3390      * {@hide}
3391      */
native_pullBatteryData(Parcel reply)3392     public native static int native_pullBatteryData(Parcel reply);
3393 
3394     /**
3395      * Sets the target UDP re-transmit endpoint for the low level player.
3396      * Generally, the address portion of the endpoint is an IP multicast
3397      * address, although a unicast address would be equally valid.  When a valid
3398      * retransmit endpoint has been set, the media player will not decode and
3399      * render the media presentation locally.  Instead, the player will attempt
3400      * to re-multiplex its media data using the Android@Home RTP profile and
3401      * re-transmit to the target endpoint.  Receiver devices (which may be
3402      * either the same as the transmitting device or different devices) may
3403      * instantiate, prepare, and start a receiver player using a setDataSource
3404      * URL of the form...
3405      *
3406      * aahRX://&lt;multicastIP&gt;:&lt;port&gt;
3407      *
3408      * to receive, decode and render the re-transmitted content.
3409      *
3410      * setRetransmitEndpoint may only be called before setDataSource has been
3411      * called; while the player is in the Idle state.
3412      *
3413      * @param endpoint the address and UDP port of the re-transmission target or
3414      * null if no re-transmission is to be performed.
3415      * @throws IllegalStateException if it is called in an invalid state
3416      * @throws IllegalArgumentException if the retransmit endpoint is supplied,
3417      * but invalid.
3418      *
3419      * {@hide} pending API council
3420      */
3421     @UnsupportedAppUsage
setRetransmitEndpoint(InetSocketAddress endpoint)3422     public void setRetransmitEndpoint(InetSocketAddress endpoint)
3423             throws IllegalStateException, IllegalArgumentException
3424     {
3425         String addrString = null;
3426         int port = 0;
3427 
3428         if (null != endpoint) {
3429             addrString = endpoint.getAddress().getHostAddress();
3430             port = endpoint.getPort();
3431         }
3432 
3433         int ret = native_setRetransmitEndpoint(addrString, port);
3434         if (ret != 0) {
3435             throw new IllegalArgumentException("Illegal re-transmit endpoint; native ret " + ret);
3436         }
3437     }
3438 
native_setRetransmitEndpoint(String addrString, int port)3439     private native final int native_setRetransmitEndpoint(String addrString, int port);
3440 
3441     @Override
finalize()3442     protected void finalize() {
3443         tryToDisableNativeRoutingCallback();
3444         baseRelease();
3445         native_finalize();
3446     }
3447 
3448     /* Do not change these values without updating their counterparts
3449      * in include/media/mediaplayer.h!
3450      */
3451     private static final int MEDIA_NOP = 0; // interface test message
3452     private static final int MEDIA_PREPARED = 1;
3453     private static final int MEDIA_PLAYBACK_COMPLETE = 2;
3454     private static final int MEDIA_BUFFERING_UPDATE = 3;
3455     private static final int MEDIA_SEEK_COMPLETE = 4;
3456     private static final int MEDIA_SET_VIDEO_SIZE = 5;
3457     private static final int MEDIA_STARTED = 6;
3458     private static final int MEDIA_PAUSED = 7;
3459     private static final int MEDIA_STOPPED = 8;
3460     private static final int MEDIA_SKIPPED = 9;
3461     private static final int MEDIA_NOTIFY_TIME = 98;
3462     private static final int MEDIA_TIMED_TEXT = 99;
3463     private static final int MEDIA_ERROR = 100;
3464     private static final int MEDIA_INFO = 200;
3465     private static final int MEDIA_SUBTITLE_DATA = 201;
3466     private static final int MEDIA_META_DATA = 202;
3467     private static final int MEDIA_DRM_INFO = 210;
3468     private static final int MEDIA_TIME_DISCONTINUITY = 211;
3469     private static final int MEDIA_RTP_RX_NOTICE = 300;
3470     private static final int MEDIA_AUDIO_ROUTING_CHANGED = 10000;
3471 
3472     private TimeProvider mTimeProvider;
3473     private final Object mTimeProviderLock = new Object();
3474 
3475     /** @hide */
3476     @UnsupportedAppUsage
getMediaTimeProvider()3477     public MediaTimeProvider getMediaTimeProvider() {
3478         synchronized (mTimeProviderLock) {
3479             if (mTimeProvider == null) {
3480                 mTimeProvider = new TimeProvider(this);
3481             }
3482             return mTimeProvider;
3483         }
3484     }
3485 
3486     private class EventHandler extends Handler
3487     {
3488         private MediaPlayer mMediaPlayer;
3489 
EventHandler(MediaPlayer mp, Looper looper)3490         public EventHandler(MediaPlayer mp, Looper looper) {
3491             super(looper);
3492             mMediaPlayer = mp;
3493         }
3494 
3495         @Override
handleMessage(Message msg)3496         public void handleMessage(Message msg) {
3497             if (mMediaPlayer.mNativeContext == 0) {
3498                 Log.w(TAG, "mediaplayer went away with unhandled events");
3499                 return;
3500             }
3501             switch(msg.what) {
3502             case MEDIA_PREPARED:
3503                 try {
3504                     scanInternalSubtitleTracks();
3505                 } catch (RuntimeException e) {
3506                     // send error message instead of crashing;
3507                     // send error message instead of inlining a call to onError
3508                     // to avoid code duplication.
3509                     Message msg2 = obtainMessage(
3510                             MEDIA_ERROR, MEDIA_ERROR_UNKNOWN, MEDIA_ERROR_UNSUPPORTED, null);
3511                     sendMessage(msg2);
3512                 }
3513 
3514                 OnPreparedListener onPreparedListener = mOnPreparedListener;
3515                 if (onPreparedListener != null)
3516                     onPreparedListener.onPrepared(mMediaPlayer);
3517                 return;
3518 
3519             case MEDIA_DRM_INFO:
3520                 Log.v(TAG, "MEDIA_DRM_INFO " + mOnDrmInfoHandlerDelegate);
3521 
3522                 if (msg.obj == null) {
3523                     Log.w(TAG, "MEDIA_DRM_INFO msg.obj=NULL");
3524                 } else if (msg.obj instanceof Parcel) {
3525                     // The parcel was parsed already in postEventFromNative
3526                     DrmInfo drmInfo = null;
3527 
3528                     OnDrmInfoHandlerDelegate onDrmInfoHandlerDelegate;
3529                     synchronized (mDrmLock) {
3530                         if (mOnDrmInfoHandlerDelegate != null && mDrmInfo != null) {
3531                             drmInfo = mDrmInfo.makeCopy();
3532                         }
3533                         // local copy while keeping the lock
3534                         onDrmInfoHandlerDelegate = mOnDrmInfoHandlerDelegate;
3535                     }
3536 
3537                     // notifying the client outside the lock
3538                     if (onDrmInfoHandlerDelegate != null) {
3539                         onDrmInfoHandlerDelegate.notifyClient(drmInfo);
3540                     }
3541                 } else {
3542                     Log.w(TAG, "MEDIA_DRM_INFO msg.obj of unexpected type " + msg.obj);
3543                 }
3544                 return;
3545 
3546             case MEDIA_PLAYBACK_COMPLETE:
3547                 {
3548                     mOnCompletionInternalListener.onCompletion(mMediaPlayer);
3549                     OnCompletionListener onCompletionListener = mOnCompletionListener;
3550                     if (onCompletionListener != null)
3551                         onCompletionListener.onCompletion(mMediaPlayer);
3552                 }
3553                 stayAwake(false);
3554                 return;
3555 
3556             case MEDIA_STOPPED:
3557                 {
3558                     TimeProvider timeProvider = mTimeProvider;
3559                     if (timeProvider != null) {
3560                         timeProvider.onStopped();
3561                     }
3562                 }
3563                 break;
3564 
3565             case MEDIA_STARTED:
3566                 // fall through
3567             case MEDIA_PAUSED:
3568                 {
3569                     TimeProvider timeProvider = mTimeProvider;
3570                     if (timeProvider != null) {
3571                         timeProvider.onPaused(msg.what == MEDIA_PAUSED);
3572                     }
3573                 }
3574                 break;
3575 
3576             case MEDIA_BUFFERING_UPDATE:
3577                 OnBufferingUpdateListener onBufferingUpdateListener = mOnBufferingUpdateListener;
3578                 if (onBufferingUpdateListener != null)
3579                     onBufferingUpdateListener.onBufferingUpdate(mMediaPlayer, msg.arg1);
3580                 return;
3581 
3582             case MEDIA_SEEK_COMPLETE:
3583                 OnSeekCompleteListener onSeekCompleteListener = mOnSeekCompleteListener;
3584                 if (onSeekCompleteListener != null) {
3585                     onSeekCompleteListener.onSeekComplete(mMediaPlayer);
3586                 }
3587                 // fall through
3588 
3589             case MEDIA_SKIPPED:
3590                 {
3591                     TimeProvider timeProvider = mTimeProvider;
3592                     if (timeProvider != null) {
3593                         timeProvider.onSeekComplete(mMediaPlayer);
3594                     }
3595                 }
3596                 return;
3597 
3598             case MEDIA_SET_VIDEO_SIZE:
3599                 OnVideoSizeChangedListener onVideoSizeChangedListener = mOnVideoSizeChangedListener;
3600                 if (onVideoSizeChangedListener != null) {
3601                     onVideoSizeChangedListener.onVideoSizeChanged(
3602                         mMediaPlayer, msg.arg1, msg.arg2);
3603                 }
3604                 return;
3605 
3606             case MEDIA_ERROR:
3607                 Log.e(TAG, "Error (" + msg.arg1 + "," + msg.arg2 + ")");
3608                 boolean error_was_handled = false;
3609                 OnErrorListener onErrorListener = mOnErrorListener;
3610                 if (onErrorListener != null) {
3611                     error_was_handled = onErrorListener.onError(mMediaPlayer, msg.arg1, msg.arg2);
3612                 }
3613                 {
3614                     mOnCompletionInternalListener.onCompletion(mMediaPlayer);
3615                     OnCompletionListener onCompletionListener = mOnCompletionListener;
3616                     if (onCompletionListener != null && ! error_was_handled) {
3617                         onCompletionListener.onCompletion(mMediaPlayer);
3618                     }
3619                 }
3620                 stayAwake(false);
3621                 return;
3622 
3623             case MEDIA_INFO:
3624                 switch (msg.arg1) {
3625                 case MEDIA_INFO_VIDEO_TRACK_LAGGING:
3626                     Log.i(TAG, "Info (" + msg.arg1 + "," + msg.arg2 + ")");
3627                     break;
3628                 case MEDIA_INFO_METADATA_UPDATE:
3629                     try {
3630                         scanInternalSubtitleTracks();
3631                     } catch (RuntimeException e) {
3632                         Message msg2 = obtainMessage(
3633                                 MEDIA_ERROR, MEDIA_ERROR_UNKNOWN, MEDIA_ERROR_UNSUPPORTED, null);
3634                         sendMessage(msg2);
3635                     }
3636                     // fall through
3637 
3638                 case MEDIA_INFO_EXTERNAL_METADATA_UPDATE:
3639                     msg.arg1 = MEDIA_INFO_METADATA_UPDATE;
3640                     // update default track selection
3641                     if (mSubtitleController != null) {
3642                         mSubtitleController.selectDefaultTrack();
3643                     }
3644                     break;
3645                 case MEDIA_INFO_BUFFERING_START:
3646                 case MEDIA_INFO_BUFFERING_END:
3647                     TimeProvider timeProvider = mTimeProvider;
3648                     if (timeProvider != null) {
3649                         timeProvider.onBuffering(msg.arg1 == MEDIA_INFO_BUFFERING_START);
3650                     }
3651                     break;
3652                 }
3653 
3654                 OnInfoListener onInfoListener = mOnInfoListener;
3655                 if (onInfoListener != null) {
3656                     onInfoListener.onInfo(mMediaPlayer, msg.arg1, msg.arg2);
3657                 }
3658                 // No real default action so far.
3659                 return;
3660 
3661             case MEDIA_NOTIFY_TIME:
3662                     TimeProvider timeProvider = mTimeProvider;
3663                     if (timeProvider != null) {
3664                         timeProvider.onNotifyTime();
3665                     }
3666                 return;
3667 
3668             case MEDIA_TIMED_TEXT:
3669                 OnTimedTextListener onTimedTextListener = mOnTimedTextListener;
3670                 if (onTimedTextListener == null)
3671                     return;
3672                 if (msg.obj == null) {
3673                     onTimedTextListener.onTimedText(mMediaPlayer, null);
3674                 } else {
3675                     if (msg.obj instanceof Parcel) {
3676                         Parcel parcel = (Parcel)msg.obj;
3677                         TimedText text = new TimedText(parcel);
3678                         parcel.recycle();
3679                         onTimedTextListener.onTimedText(mMediaPlayer, text);
3680                     }
3681                 }
3682                 return;
3683 
3684             case MEDIA_SUBTITLE_DATA:
3685                 final OnSubtitleDataListener extSubtitleListener;
3686                 final Handler extSubtitleHandler;
3687                 synchronized(this) {
3688                     if (mSubtitleDataListenerDisabled) {
3689                         return;
3690                     }
3691                     extSubtitleListener = mExtSubtitleDataListener;
3692                     extSubtitleHandler = mExtSubtitleDataHandler;
3693                 }
3694                 if (msg.obj instanceof Parcel) {
3695                     Parcel parcel = (Parcel) msg.obj;
3696                     final SubtitleData data = new SubtitleData(parcel);
3697                     parcel.recycle();
3698 
3699                     mIntSubtitleDataListener.onSubtitleData(mMediaPlayer, data);
3700 
3701                     if (extSubtitleListener != null) {
3702                         if (extSubtitleHandler == null) {
3703                             extSubtitleListener.onSubtitleData(mMediaPlayer, data);
3704                         } else {
3705                             extSubtitleHandler.post(new Runnable() {
3706                                 @Override
3707                                 public void run() {
3708                                     extSubtitleListener.onSubtitleData(mMediaPlayer, data);
3709                                 }
3710                             });
3711                         }
3712                     }
3713                 }
3714                 return;
3715 
3716             case MEDIA_META_DATA:
3717                 OnTimedMetaDataAvailableListener onTimedMetaDataAvailableListener =
3718                     mOnTimedMetaDataAvailableListener;
3719                 if (onTimedMetaDataAvailableListener == null) {
3720                     return;
3721                 }
3722                 if (msg.obj instanceof Parcel) {
3723                     Parcel parcel = (Parcel) msg.obj;
3724                     TimedMetaData data = TimedMetaData.createTimedMetaDataFromParcel(parcel);
3725                     parcel.recycle();
3726                     onTimedMetaDataAvailableListener.onTimedMetaDataAvailable(mMediaPlayer, data);
3727                 }
3728                 return;
3729 
3730             case MEDIA_NOP: // interface test message - ignore
3731                 break;
3732 
3733             case MEDIA_AUDIO_ROUTING_CHANGED:
3734                     broadcastRoutingChange();
3735                     return;
3736 
3737             case MEDIA_TIME_DISCONTINUITY:
3738                 final OnMediaTimeDiscontinuityListener mediaTimeListener;
3739                 final Handler mediaTimeHandler;
3740                 synchronized(this) {
3741                     mediaTimeListener = mOnMediaTimeDiscontinuityListener;
3742                     mediaTimeHandler = mOnMediaTimeDiscontinuityHandler;
3743                 }
3744                 if (mediaTimeListener == null) {
3745                     return;
3746                 }
3747                 if (msg.obj instanceof Parcel) {
3748                     Parcel parcel = (Parcel) msg.obj;
3749                     parcel.setDataPosition(0);
3750                     long anchorMediaUs = parcel.readLong();
3751                     long anchorRealUs = parcel.readLong();
3752                     float playbackRate = parcel.readFloat();
3753                     parcel.recycle();
3754                     final MediaTimestamp timestamp;
3755                     if (anchorMediaUs != -1 && anchorRealUs != -1) {
3756                         timestamp = new MediaTimestamp(
3757                                 anchorMediaUs /*Us*/, anchorRealUs * 1000 /*Ns*/, playbackRate);
3758                     } else {
3759                         timestamp = MediaTimestamp.TIMESTAMP_UNKNOWN;
3760                     }
3761                     if (mediaTimeHandler == null) {
3762                         mediaTimeListener.onMediaTimeDiscontinuity(mMediaPlayer, timestamp);
3763                     } else {
3764                         mediaTimeHandler.post(new Runnable() {
3765                             @Override
3766                             public void run() {
3767                                 mediaTimeListener.onMediaTimeDiscontinuity(mMediaPlayer, timestamp);
3768                             }
3769                         });
3770                     }
3771                 }
3772                 return;
3773 
3774             case MEDIA_RTP_RX_NOTICE:
3775                 final OnRtpRxNoticeListener rtpRxNoticeListener = mOnRtpRxNoticeListener;
3776                 if (rtpRxNoticeListener == null) {
3777                     return;
3778                 }
3779                 if (msg.obj instanceof Parcel) {
3780                     Parcel parcel = (Parcel) msg.obj;
3781                     parcel.setDataPosition(0);
3782                     int noticeType;
3783                     int[] data;
3784                     try {
3785                         noticeType = parcel.readInt();
3786                         int numOfArgs = parcel.dataAvail() / 4;
3787                         data = new int[numOfArgs];
3788                         for (int i = 0; i < numOfArgs; i++) {
3789                             data[i] = parcel.readInt();
3790                         }
3791                     } finally {
3792                         parcel.recycle();
3793                     }
3794                     mOnRtpRxNoticeExecutor.execute(() ->
3795                             rtpRxNoticeListener
3796                                     .onRtpRxNotice(mMediaPlayer, noticeType, data));
3797                 }
3798                 return;
3799 
3800             default:
3801                 Log.e(TAG, "Unknown message type " + msg.what);
3802                 return;
3803             }
3804         }
3805     }
3806 
3807     /*
3808      * Called from native code when an interesting event happens.  This method
3809      * just uses the EventHandler system to post the event back to the main app thread.
3810      * We use a weak reference to the original MediaPlayer object so that the native
3811      * code is safe from the object disappearing from underneath it.  (This is
3812      * the cookie passed to native_setup().)
3813      */
postEventFromNative(Object mediaplayer_ref, int what, int arg1, int arg2, Object obj)3814     private static void postEventFromNative(Object mediaplayer_ref,
3815                                             int what, int arg1, int arg2, Object obj)
3816     {
3817         final MediaPlayer mp = (MediaPlayer)((WeakReference)mediaplayer_ref).get();
3818         if (mp == null) {
3819             return;
3820         }
3821 
3822         switch (what) {
3823         case MEDIA_INFO:
3824             if (arg1 == MEDIA_INFO_STARTED_AS_NEXT) {
3825                 new Thread(new Runnable() {
3826                     @Override
3827                     public void run() {
3828                         // this acquires the wakelock if needed, and sets the client side state
3829                         mp.start();
3830                     }
3831                 }).start();
3832                 Thread.yield();
3833             }
3834             break;
3835 
3836         case MEDIA_DRM_INFO:
3837             // We need to derive mDrmInfo before prepare() returns so processing it here
3838             // before the notification is sent to EventHandler below. EventHandler runs in the
3839             // notification looper so its handleMessage might process the event after prepare()
3840             // has returned.
3841             Log.v(TAG, "postEventFromNative MEDIA_DRM_INFO");
3842             if (obj instanceof Parcel) {
3843                 Parcel parcel = (Parcel)obj;
3844                 DrmInfo drmInfo = new DrmInfo(parcel);
3845                 synchronized (mp.mDrmLock) {
3846                     mp.mDrmInfo = drmInfo;
3847                 }
3848             } else {
3849                 Log.w(TAG, "MEDIA_DRM_INFO msg.obj of unexpected type " + obj);
3850             }
3851             break;
3852 
3853         case MEDIA_PREPARED:
3854             // By this time, we've learned about DrmInfo's presence or absence. This is meant
3855             // mainly for prepareAsync() use case. For prepare(), this still can run to a race
3856             // condition b/c MediaPlayerNative releases the prepare() lock before calling notify
3857             // so we also set mDrmInfoResolved in prepare().
3858             synchronized (mp.mDrmLock) {
3859                 mp.mDrmInfoResolved = true;
3860             }
3861             break;
3862 
3863         }
3864 
3865         if (mp.mEventHandler != null) {
3866             Message m = mp.mEventHandler.obtainMessage(what, arg1, arg2, obj);
3867             mp.mEventHandler.sendMessage(m);
3868         }
3869     }
3870 
3871     /**
3872      * Interface definition for a callback to be invoked when the media
3873      * source is ready for playback.
3874      */
3875     public interface OnPreparedListener
3876     {
3877         /**
3878          * Called when the media file is ready for playback.
3879          *
3880          * @param mp the MediaPlayer that is ready for playback
3881          */
onPrepared(MediaPlayer mp)3882         void onPrepared(MediaPlayer mp);
3883     }
3884 
3885     /**
3886      * Register a callback to be invoked when the media source is ready
3887      * for playback.
3888      *
3889      * @param listener the callback that will be run
3890      */
setOnPreparedListener(OnPreparedListener listener)3891     public void setOnPreparedListener(OnPreparedListener listener)
3892     {
3893         mOnPreparedListener = listener;
3894     }
3895 
3896     @UnsupportedAppUsage
3897     private OnPreparedListener mOnPreparedListener;
3898 
3899     /**
3900      * Interface definition for a callback to be invoked when playback of
3901      * a media source has completed.
3902      */
3903     public interface OnCompletionListener
3904     {
3905         /**
3906          * Called when the end of a media source is reached during playback.
3907          *
3908          * @param mp the MediaPlayer that reached the end of the file
3909          */
onCompletion(MediaPlayer mp)3910         void onCompletion(MediaPlayer mp);
3911     }
3912 
3913     /**
3914      * Register a callback to be invoked when the end of a media source
3915      * has been reached during playback.
3916      *
3917      * @param listener the callback that will be run
3918      */
setOnCompletionListener(OnCompletionListener listener)3919     public void setOnCompletionListener(OnCompletionListener listener)
3920     {
3921         mOnCompletionListener = listener;
3922     }
3923 
3924     @UnsupportedAppUsage
3925     private OnCompletionListener mOnCompletionListener;
3926 
3927     /**
3928      * @hide
3929      * Internal completion listener to update PlayerBase of the play state. Always "registered".
3930      */
3931     private final OnCompletionListener mOnCompletionInternalListener = new OnCompletionListener() {
3932         @Override
3933         public void onCompletion(MediaPlayer mp) {
3934             tryToDisableNativeRoutingCallback();
3935             baseStop();
3936         }
3937     };
3938 
3939     /**
3940      * Interface definition of a callback to be invoked indicating buffering
3941      * status of a media resource being streamed over the network.
3942      */
3943     public interface OnBufferingUpdateListener
3944     {
3945         /**
3946          * Called to update status in buffering a media stream received through
3947          * progressive HTTP download. The received buffering percentage
3948          * indicates how much of the content has been buffered or played.
3949          * For example a buffering update of 80 percent when half the content
3950          * has already been played indicates that the next 30 percent of the
3951          * content to play has been buffered.
3952          *
3953          * @param mp      the MediaPlayer the update pertains to
3954          * @param percent the percentage (0-100) of the content
3955          *                that has been buffered or played thus far
3956          */
onBufferingUpdate(MediaPlayer mp, int percent)3957         void onBufferingUpdate(MediaPlayer mp, int percent);
3958     }
3959 
3960     /**
3961      * Register a callback to be invoked when the status of a network
3962      * stream's buffer has changed.
3963      *
3964      * @param listener the callback that will be run.
3965      */
setOnBufferingUpdateListener(OnBufferingUpdateListener listener)3966     public void setOnBufferingUpdateListener(OnBufferingUpdateListener listener)
3967     {
3968         mOnBufferingUpdateListener = listener;
3969     }
3970 
3971     private OnBufferingUpdateListener mOnBufferingUpdateListener;
3972 
3973     /**
3974      * Interface definition of a callback to be invoked indicating
3975      * the completion of a seek operation.
3976      */
3977     public interface OnSeekCompleteListener
3978     {
3979         /**
3980          * Called to indicate the completion of a seek operation.
3981          *
3982          * @param mp the MediaPlayer that issued the seek operation
3983          */
onSeekComplete(MediaPlayer mp)3984         public void onSeekComplete(MediaPlayer mp);
3985     }
3986 
3987     /**
3988      * Register a callback to be invoked when a seek operation has been
3989      * completed.
3990      *
3991      * @param listener the callback that will be run
3992      */
setOnSeekCompleteListener(OnSeekCompleteListener listener)3993     public void setOnSeekCompleteListener(OnSeekCompleteListener listener)
3994     {
3995         mOnSeekCompleteListener = listener;
3996     }
3997 
3998     @UnsupportedAppUsage
3999     private OnSeekCompleteListener mOnSeekCompleteListener;
4000 
4001     /**
4002      * Interface definition of a callback to be invoked when the
4003      * video size is first known or updated
4004      */
4005     public interface OnVideoSizeChangedListener
4006     {
4007         /**
4008          * Called to indicate the video size
4009          *
4010          * The video size (width and height) could be 0 if there was no video,
4011          * no display surface was set, or the value was not determined yet.
4012          *
4013          * @param mp        the MediaPlayer associated with this callback
4014          * @param width     the width of the video
4015          * @param height    the height of the video
4016          */
onVideoSizeChanged(MediaPlayer mp, int width, int height)4017         public void onVideoSizeChanged(MediaPlayer mp, int width, int height);
4018     }
4019 
4020     /**
4021      * Register a callback to be invoked when the video size is
4022      * known or updated.
4023      *
4024      * @param listener the callback that will be run
4025      */
setOnVideoSizeChangedListener(OnVideoSizeChangedListener listener)4026     public void setOnVideoSizeChangedListener(OnVideoSizeChangedListener listener)
4027     {
4028         mOnVideoSizeChangedListener = listener;
4029     }
4030 
4031     private OnVideoSizeChangedListener mOnVideoSizeChangedListener;
4032 
4033     /**
4034      * Interface definition of a callback to be invoked when a
4035      * timed text is available for display.
4036      */
4037     public interface OnTimedTextListener
4038     {
4039         /**
4040          * Called to indicate an avaliable timed text
4041          *
4042          * @param mp             the MediaPlayer associated with this callback
4043          * @param text           the timed text sample which contains the text
4044          *                       needed to be displayed and the display format.
4045          */
onTimedText(MediaPlayer mp, TimedText text)4046         public void onTimedText(MediaPlayer mp, TimedText text);
4047     }
4048 
4049     /**
4050      * Register a callback to be invoked when a timed text is available
4051      * for display.
4052      *
4053      * @param listener the callback that will be run
4054      */
setOnTimedTextListener(OnTimedTextListener listener)4055     public void setOnTimedTextListener(OnTimedTextListener listener)
4056     {
4057         mOnTimedTextListener = listener;
4058     }
4059 
4060     @UnsupportedAppUsage
4061     private OnTimedTextListener mOnTimedTextListener;
4062 
4063     /**
4064      * Interface definition of a callback to be invoked when a player subtitle track has new
4065      * subtitle data available.
4066      * See the {@link MediaPlayer#setOnSubtitleDataListener(OnSubtitleDataListener, Handler)}
4067      * method for the description of which track will report data through this listener.
4068      */
4069     public interface OnSubtitleDataListener {
4070         /**
4071          * Method called when new subtitle data is available
4072          * @param mp the player that reports the new subtitle data
4073          * @param data the subtitle data
4074          */
onSubtitleData(@onNull MediaPlayer mp, @NonNull SubtitleData data)4075         public void onSubtitleData(@NonNull MediaPlayer mp, @NonNull SubtitleData data);
4076     }
4077 
4078     /**
4079      * Sets the listener to be invoked when a subtitle track has new data available.
4080      * The subtitle data comes from a subtitle track previously selected with
4081      * {@link #selectTrack(int)}. Use {@link #getTrackInfo()} to determine which tracks are
4082      * subtitles (of type {@link TrackInfo#MEDIA_TRACK_TYPE_SUBTITLE}), Subtitle track encodings
4083      * can be determined by {@link TrackInfo#getFormat()}).<br>
4084      * See {@link SubtitleData} for an example of querying subtitle encoding.
4085      * @param listener the listener called when new data is available
4086      * @param handler the {@link Handler} that receives the listener events
4087      */
setOnSubtitleDataListener(@onNull OnSubtitleDataListener listener, @NonNull Handler handler)4088     public void setOnSubtitleDataListener(@NonNull OnSubtitleDataListener listener,
4089             @NonNull Handler handler) {
4090         if (listener == null) {
4091             throw new IllegalArgumentException("Illegal null listener");
4092         }
4093         if (handler == null) {
4094             throw new IllegalArgumentException("Illegal null handler");
4095         }
4096         setOnSubtitleDataListenerInt(listener, handler);
4097     }
4098     /**
4099      * Sets the listener to be invoked when a subtitle track has new data available.
4100      * The subtitle data comes from a subtitle track previously selected with
4101      * {@link #selectTrack(int)}. Use {@link #getTrackInfo()} to determine which tracks are
4102      * subtitles (of type {@link TrackInfo#MEDIA_TRACK_TYPE_SUBTITLE}), Subtitle track encodings
4103      * can be determined by {@link TrackInfo#getFormat()}).<br>
4104      * See {@link SubtitleData} for an example of querying subtitle encoding.<br>
4105      * The listener will be called on the same thread as the one in which the MediaPlayer was
4106      * created.
4107      * @param listener the listener called when new data is available
4108      */
setOnSubtitleDataListener(@onNull OnSubtitleDataListener listener)4109     public void setOnSubtitleDataListener(@NonNull OnSubtitleDataListener listener)
4110     {
4111         if (listener == null) {
4112             throw new IllegalArgumentException("Illegal null listener");
4113         }
4114         setOnSubtitleDataListenerInt(listener, null);
4115     }
4116 
4117     /**
4118      * Clears the listener previously set with
4119      * {@link #setOnSubtitleDataListener(OnSubtitleDataListener)} or
4120      * {@link #setOnSubtitleDataListener(OnSubtitleDataListener, Handler)}.
4121      */
clearOnSubtitleDataListener()4122     public void clearOnSubtitleDataListener() {
4123         setOnSubtitleDataListenerInt(null, null);
4124     }
4125 
setOnSubtitleDataListenerInt( @ullable OnSubtitleDataListener listener, @Nullable Handler handler)4126     private void setOnSubtitleDataListenerInt(
4127             @Nullable OnSubtitleDataListener listener, @Nullable Handler handler) {
4128         synchronized (this) {
4129             mExtSubtitleDataListener = listener;
4130             mExtSubtitleDataHandler = handler;
4131         }
4132     }
4133 
4134     private boolean mSubtitleDataListenerDisabled;
4135     /** External OnSubtitleDataListener, the one set by {@link #setOnSubtitleDataListener}. */
4136     private OnSubtitleDataListener mExtSubtitleDataListener;
4137     private Handler mExtSubtitleDataHandler;
4138 
4139     /**
4140      * Interface definition of a callback to be invoked when discontinuity in the normal progression
4141      * of the media time is detected.
4142      * The "normal progression" of media time is defined as the expected increase of the playback
4143      * position when playing media, relative to the playback speed (for instance every second, media
4144      * time increases by two seconds when playing at 2x).<br>
4145      * Discontinuities are encountered in the following cases:
4146      * <ul>
4147      * <li>when the player is starved for data and cannot play anymore</li>
4148      * <li>when the player encounters a playback error</li>
4149      * <li>when the a seek operation starts, and when it's completed</li>
4150      * <li>when the playback speed changes</li>
4151      * <li>when the playback state changes</li>
4152      * <li>when the player is reset</li>
4153      * </ul>
4154      * See the
4155      * {@link MediaPlayer#setOnMediaTimeDiscontinuityListener(OnMediaTimeDiscontinuityListener, Handler)}
4156      * method to set a listener for these events.
4157      */
4158     public interface OnMediaTimeDiscontinuityListener {
4159         /**
4160          * Called to indicate a time discontinuity has occured.
4161          * @param mp the MediaPlayer for which the discontinuity has occured.
4162          * @param mts the timestamp that correlates media time, system time and clock rate,
4163          *     or {@link MediaTimestamp#TIMESTAMP_UNKNOWN} in an error case.
4164          */
onMediaTimeDiscontinuity(@onNull MediaPlayer mp, @NonNull MediaTimestamp mts)4165         public void onMediaTimeDiscontinuity(@NonNull MediaPlayer mp, @NonNull MediaTimestamp mts);
4166     }
4167 
4168     /**
4169      * Sets the listener to be invoked when a media time discontinuity is encountered.
4170      * @param listener the listener called after a discontinuity
4171      * @param handler the {@link Handler} that receives the listener events
4172      */
setOnMediaTimeDiscontinuityListener( @onNull OnMediaTimeDiscontinuityListener listener, @NonNull Handler handler)4173     public void setOnMediaTimeDiscontinuityListener(
4174             @NonNull OnMediaTimeDiscontinuityListener listener, @NonNull Handler handler) {
4175         if (listener == null) {
4176             throw new IllegalArgumentException("Illegal null listener");
4177         }
4178         if (handler == null) {
4179             throw new IllegalArgumentException("Illegal null handler");
4180         }
4181         setOnMediaTimeDiscontinuityListenerInt(listener, handler);
4182     }
4183 
4184     /**
4185      * Sets the listener to be invoked when a media time discontinuity is encountered.
4186      * The listener will be called on the same thread as the one in which the MediaPlayer was
4187      * created.
4188      * @param listener the listener called after a discontinuity
4189      */
setOnMediaTimeDiscontinuityListener( @onNull OnMediaTimeDiscontinuityListener listener)4190     public void setOnMediaTimeDiscontinuityListener(
4191             @NonNull OnMediaTimeDiscontinuityListener listener)
4192     {
4193         if (listener == null) {
4194             throw new IllegalArgumentException("Illegal null listener");
4195         }
4196         setOnMediaTimeDiscontinuityListenerInt(listener, null);
4197     }
4198 
4199     /**
4200      * Clears the listener previously set with
4201      * {@link #setOnMediaTimeDiscontinuityListener(OnMediaTimeDiscontinuityListener)}
4202      * or {@link #setOnMediaTimeDiscontinuityListener(OnMediaTimeDiscontinuityListener, Handler)}
4203      */
clearOnMediaTimeDiscontinuityListener()4204     public void clearOnMediaTimeDiscontinuityListener() {
4205         setOnMediaTimeDiscontinuityListenerInt(null, null);
4206     }
4207 
setOnMediaTimeDiscontinuityListenerInt( @ullable OnMediaTimeDiscontinuityListener listener, @Nullable Handler handler)4208     private void setOnMediaTimeDiscontinuityListenerInt(
4209             @Nullable OnMediaTimeDiscontinuityListener listener, @Nullable Handler handler) {
4210         synchronized (this) {
4211             mOnMediaTimeDiscontinuityListener = listener;
4212             mOnMediaTimeDiscontinuityHandler = handler;
4213         }
4214     }
4215 
4216     private OnMediaTimeDiscontinuityListener mOnMediaTimeDiscontinuityListener;
4217     private Handler mOnMediaTimeDiscontinuityHandler;
4218 
4219     /**
4220      * Interface definition of a callback to be invoked when a
4221      * track has timed metadata available.
4222      *
4223      * @see MediaPlayer#setOnTimedMetaDataAvailableListener(OnTimedMetaDataAvailableListener)
4224      */
4225     public interface OnTimedMetaDataAvailableListener
4226     {
4227         /**
4228          * Called to indicate avaliable timed metadata
4229          * <p>
4230          * This method will be called as timed metadata is extracted from the media,
4231          * in the same order as it occurs in the media. The timing of this event is
4232          * not controlled by the associated timestamp.
4233          *
4234          * @param mp             the MediaPlayer associated with this callback
4235          * @param data           the timed metadata sample associated with this event
4236          */
onTimedMetaDataAvailable(MediaPlayer mp, TimedMetaData data)4237         public void onTimedMetaDataAvailable(MediaPlayer mp, TimedMetaData data);
4238     }
4239 
4240     /**
4241      * Interface definition of a callback to be invoked when
4242      * RTP Rx connection has a notice.
4243      *
4244      * @see #setOnRtpRxNoticeListener
4245      *
4246      * @hide
4247      */
4248     @SystemApi
4249     public interface OnRtpRxNoticeListener
4250     {
4251         /**
4252          * Called when an RTP Rx connection has a notice.
4253          * <p>
4254          * Basic format. All TYPE and ARG are 4 bytes unsigned integer in native byte order.
4255          * <pre>{@code
4256          * 0                4               8                12
4257          * +----------------+---------------+----------------+----------------+
4258          * |      TYPE      |      ARG1     |      ARG2      |      ARG3      |
4259          * +----------------+---------------+----------------+----------------+
4260          * |      ARG4      |      ARG5     |      ...
4261          * +----------------+---------------+-------------
4262          * 16               20              24
4263          *
4264          *
4265          * TYPE 100 - A notice of the first rtp packet received. No ARGs.
4266          * 0
4267          * +----------------+
4268          * |      100       |
4269          * +----------------+
4270          *
4271          *
4272          * TYPE 101 - A notice of the first rtcp packet received. No ARGs.
4273          * 0
4274          * +----------------+
4275          * |      101       |
4276          * +----------------+
4277          *
4278          *
4279          * TYPE 102 - A periodic report of a RTP statistics.
4280          * TYPE 103 - An emergency report when serious packet loss has been detected
4281          *            in between TYPE 102 events.
4282          * 0                4               8                12
4283          * +----------------+---------------+----------------+----------------+
4284          * |   102 or 103   |   FB type=0   |    Bitrate     |   Top #.Seq    |
4285          * +----------------+---------------+----------------+----------------+
4286          * |   Base #.Seq   |Prev Expt #.Pkt|   Recv #.Pkt   |Prev Recv #.Pkt |
4287          * +----------------+---------------+----------------+----------------+
4288          * Feedback (FB) type
4289          *      - always 0.
4290          * Bitrate
4291          *      - amount of data received in this period.
4292          * Top number of sequence
4293          *      - highest RTP sequence number received in this period.
4294          *      - monotonically increasing value.
4295          * Base number of sequence
4296          *      - the first RTP sequence number of the media stream.
4297          * Previous Expected number of Packets
4298          *      - expected count of packets received in the previous report.
4299          * Received number of packet
4300          *      - actual count of packets received in this report.
4301          * Previous Received number of packet
4302          *      - actual count of packets received in the previous report.
4303          *
4304          *
4305          * TYPE 205 - Transport layer Feedback message. (RFC-5104 Sec.4.2)
4306          * 0                4               8                12
4307          * +----------------+---------------+----------------+----------------+
4308          * |      205       |FB type(1 or 3)|      SSRC      |      Value     |
4309          * +----------------+---------------+----------------+----------------+
4310          * Feedback (FB) type: determines the type of the event.
4311          *      - if 1, we received a NACK request from the remote side.
4312          *      - if 3, we received a TMMBR (Temporary Maximum Media Stream Bit Rate Request) from
4313          *        the remote side.
4314          * SSRC
4315          *      - Remote side's SSRC value of the media sender (RFC-3550 Sec.5.1)
4316          * Value: the FCI (Feedback Control Information) depending on the value of FB type
4317          *      - if FB type is 1, the Generic NACK as specified in RFC-4585 Sec.6.2.1
4318          *      - if FB type is 3, the TMMBR as specified in RFC-5104 Sec.4.2.1.1
4319          *
4320          *
4321          * TYPE 206 - Payload-specific Feedback message. (RFC-5104 Sec.4.3)
4322          * 0                4               8
4323          * +----------------+---------------+----------------+
4324          * |      206       |FB type(1 or 4)|      SSRC      |
4325          * +----------------+---------------+----------------+
4326          * Feedback (FB) type: determines the type of the event.
4327          *      - if 1, we received a PLI request from the remote side.
4328          *      - if 4, we received a FIR request from the remote side.
4329          * SSRC
4330          *      - Remote side's SSRC value of the media sender (RFC-3550 Sec.5.1)
4331          *
4332          *
4333          * TYPE 300 - CVO (RTP Extension) message.
4334          * 0                4
4335          * +----------------+---------------+
4336          * |      101       |     value     |
4337          * +----------------+---------------+
4338          * value
4339          *      - clockwise rotation degrees of a received video (6.2.3 of 3GPP R12 TS 26.114).
4340          *      - can be 0 (degree 0), 1 (degree 90), 2 (degree 180) or 3 (degree 270).
4341          *
4342          *
4343          * TYPE 400 - Socket failed during receive. No ARGs.
4344          * 0
4345          * +----------------+
4346          * |      400       |
4347          * +----------------+
4348          * }</pre>
4349          *
4350          * @param mp the {@code MediaPlayer} associated with this callback.
4351          * @param noticeType TYPE of the event.
4352          * @param params RTP Rx media data serialized as int[] array.
4353          */
onRtpRxNotice(@onNull MediaPlayer mp, int noticeType, @NonNull int[] params)4354         void onRtpRxNotice(@NonNull MediaPlayer mp, int noticeType, @NonNull int[] params);
4355     }
4356 
4357     /**
4358      * Sets the listener to be invoked when an RTP Rx connection has a notice.
4359      * The listener is required if MediaPlayer is configured for RTPSource by
4360      * MediaPlayer.setDataSource(String8 rtpParams) of mediaplayer.h.
4361      *
4362      * @see OnRtpRxNoticeListener
4363      *
4364      * @param listener the listener called after a notice from RTP Rx.
4365      * @param executor the {@link Executor} on which to post RTP Tx events.
4366      * @hide
4367      */
4368     @SystemApi
4369     @RequiresPermission(BIND_IMS_SERVICE)
setOnRtpRxNoticeListener( @onNull Context context, @NonNull Executor executor, @NonNull OnRtpRxNoticeListener listener)4370     public void setOnRtpRxNoticeListener(
4371             @NonNull Context context,
4372             @NonNull Executor executor,
4373             @NonNull OnRtpRxNoticeListener listener) {
4374         Objects.requireNonNull(context);
4375         Preconditions.checkArgument(
4376                 context.checkSelfPermission(BIND_IMS_SERVICE) == PERMISSION_GRANTED,
4377                 BIND_IMS_SERVICE + " permission not granted.");
4378         mOnRtpRxNoticeListener = Objects.requireNonNull(listener);
4379         mOnRtpRxNoticeExecutor = Objects.requireNonNull(executor);
4380     }
4381 
4382     private OnRtpRxNoticeListener mOnRtpRxNoticeListener;
4383     private Executor mOnRtpRxNoticeExecutor;
4384 
4385     /**
4386      * Register a callback to be invoked when a selected track has timed metadata available.
4387      * <p>
4388      * Currently only HTTP live streaming data URI's embedded with timed ID3 tags generates
4389      * {@link TimedMetaData}.
4390      *
4391      * @see MediaPlayer#selectTrack(int)
4392      * @see MediaPlayer.OnTimedMetaDataAvailableListener
4393      * @see TimedMetaData
4394      *
4395      * @param listener the callback that will be run
4396      */
setOnTimedMetaDataAvailableListener(OnTimedMetaDataAvailableListener listener)4397     public void setOnTimedMetaDataAvailableListener(OnTimedMetaDataAvailableListener listener)
4398     {
4399         mOnTimedMetaDataAvailableListener = listener;
4400     }
4401 
4402     private OnTimedMetaDataAvailableListener mOnTimedMetaDataAvailableListener;
4403 
4404     /* Do not change these values without updating their counterparts
4405      * in include/media/mediaplayer.h!
4406      */
4407     /** Unspecified media player error.
4408      * @see android.media.MediaPlayer.OnErrorListener
4409      */
4410     public static final int MEDIA_ERROR_UNKNOWN = 1;
4411 
4412     /** Media server died. In this case, the application must release the
4413      * MediaPlayer object and instantiate a new one.
4414      * @see android.media.MediaPlayer.OnErrorListener
4415      */
4416     public static final int MEDIA_ERROR_SERVER_DIED = 100;
4417 
4418     /** The video is streamed and its container is not valid for progressive
4419      * playback i.e the video's index (e.g moov atom) is not at the start of the
4420      * file.
4421      * @see android.media.MediaPlayer.OnErrorListener
4422      */
4423     public static final int MEDIA_ERROR_NOT_VALID_FOR_PROGRESSIVE_PLAYBACK = 200;
4424 
4425     /** File or network related operation errors. */
4426     public static final int MEDIA_ERROR_IO = -1004;
4427     /** Bitstream is not conforming to the related coding standard or file spec. */
4428     public static final int MEDIA_ERROR_MALFORMED = -1007;
4429     /** Bitstream is conforming to the related coding standard or file spec, but
4430      * the media framework does not support the feature. */
4431     public static final int MEDIA_ERROR_UNSUPPORTED = -1010;
4432     /** Some operation takes too long to complete, usually more than 3-5 seconds. */
4433     public static final int MEDIA_ERROR_TIMED_OUT = -110;
4434 
4435     /** Unspecified low-level system error. This value originated from UNKNOWN_ERROR in
4436      * system/core/include/utils/Errors.h
4437      * @see android.media.MediaPlayer.OnErrorListener
4438      * @hide
4439      */
4440     public static final int MEDIA_ERROR_SYSTEM = -2147483648;
4441 
4442     /**
4443      * Interface definition of a callback to be invoked when there
4444      * has been an error during an asynchronous operation (other errors
4445      * will throw exceptions at method call time).
4446      */
4447     public interface OnErrorListener
4448     {
4449         /**
4450          * Called to indicate an error.
4451          *
4452          * @param mp      the MediaPlayer the error pertains to
4453          * @param what    the type of error that has occurred:
4454          * <ul>
4455          * <li>{@link #MEDIA_ERROR_UNKNOWN}
4456          * <li>{@link #MEDIA_ERROR_SERVER_DIED}
4457          * </ul>
4458          * @param extra an extra code, specific to the error. Typically
4459          * implementation dependent.
4460          * <ul>
4461          * <li>{@link #MEDIA_ERROR_IO}
4462          * <li>{@link #MEDIA_ERROR_MALFORMED}
4463          * <li>{@link #MEDIA_ERROR_UNSUPPORTED}
4464          * <li>{@link #MEDIA_ERROR_TIMED_OUT}
4465          * <li><code>MEDIA_ERROR_SYSTEM (-2147483648)</code> - low-level system error.
4466          * </ul>
4467          * @return True if the method handled the error, false if it didn't.
4468          * Returning false, or not having an OnErrorListener at all, will
4469          * cause the OnCompletionListener to be called.
4470          */
onError(MediaPlayer mp, int what, int extra)4471         boolean onError(MediaPlayer mp, int what, int extra);
4472     }
4473 
4474     /**
4475      * Register a callback to be invoked when an error has happened
4476      * during an asynchronous operation.
4477      *
4478      * @param listener the callback that will be run
4479      */
setOnErrorListener(OnErrorListener listener)4480     public void setOnErrorListener(OnErrorListener listener)
4481     {
4482         mOnErrorListener = listener;
4483     }
4484 
4485     @UnsupportedAppUsage
4486     private OnErrorListener mOnErrorListener;
4487 
4488 
4489     /* Do not change these values without updating their counterparts
4490      * in include/media/mediaplayer.h!
4491      */
4492     /** Unspecified media player info.
4493      * @see android.media.MediaPlayer.OnInfoListener
4494      */
4495     public static final int MEDIA_INFO_UNKNOWN = 1;
4496 
4497     /** The player was started because it was used as the next player for another
4498      * player, which just completed playback.
4499      * @see android.media.MediaPlayer#setNextMediaPlayer(MediaPlayer)
4500      * @see android.media.MediaPlayer.OnInfoListener
4501      */
4502     public static final int MEDIA_INFO_STARTED_AS_NEXT = 2;
4503 
4504     /** The player just pushed the very first video frame for rendering.
4505      * @see android.media.MediaPlayer.OnInfoListener
4506      */
4507     public static final int MEDIA_INFO_VIDEO_RENDERING_START = 3;
4508 
4509     /** The video is too complex for the decoder: it can't decode frames fast
4510      *  enough. Possibly only the audio plays fine at this stage.
4511      * @see android.media.MediaPlayer.OnInfoListener
4512      */
4513     public static final int MEDIA_INFO_VIDEO_TRACK_LAGGING = 700;
4514 
4515     /** MediaPlayer is temporarily pausing playback internally in order to
4516      * buffer more data.
4517      * @see android.media.MediaPlayer.OnInfoListener
4518      */
4519     public static final int MEDIA_INFO_BUFFERING_START = 701;
4520 
4521     /** MediaPlayer is resuming playback after filling buffers.
4522      * @see android.media.MediaPlayer.OnInfoListener
4523      */
4524     public static final int MEDIA_INFO_BUFFERING_END = 702;
4525 
4526     /** Estimated network bandwidth information (kbps) is available; currently this event fires
4527      * simultaneously as {@link #MEDIA_INFO_BUFFERING_START} and {@link #MEDIA_INFO_BUFFERING_END}
4528      * when playing network files.
4529      * @see android.media.MediaPlayer.OnInfoListener
4530      * @hide
4531      */
4532     public static final int MEDIA_INFO_NETWORK_BANDWIDTH = 703;
4533 
4534     /** Bad interleaving means that a media has been improperly interleaved or
4535      * not interleaved at all, e.g has all the video samples first then all the
4536      * audio ones. Video is playing but a lot of disk seeks may be happening.
4537      * @see android.media.MediaPlayer.OnInfoListener
4538      */
4539     public static final int MEDIA_INFO_BAD_INTERLEAVING = 800;
4540 
4541     /** The media cannot be seeked (e.g live stream)
4542      * @see android.media.MediaPlayer.OnInfoListener
4543      */
4544     public static final int MEDIA_INFO_NOT_SEEKABLE = 801;
4545 
4546     /** A new set of metadata is available.
4547      * @see android.media.MediaPlayer.OnInfoListener
4548      */
4549     public static final int MEDIA_INFO_METADATA_UPDATE = 802;
4550 
4551     /** A new set of external-only metadata is available.  Used by
4552      *  JAVA framework to avoid triggering track scanning.
4553      * @hide
4554      */
4555     @UnsupportedAppUsage(maxTargetSdk = Build.VERSION_CODES.R, trackingBug = 170729553)
4556     public static final int MEDIA_INFO_EXTERNAL_METADATA_UPDATE = 803;
4557 
4558     /** Informs that audio is not playing. Note that playback of the video
4559      * is not interrupted.
4560      * @see android.media.MediaPlayer.OnInfoListener
4561      */
4562     public static final int MEDIA_INFO_AUDIO_NOT_PLAYING = 804;
4563 
4564     /** Informs that video is not playing. Note that playback of the audio
4565      * is not interrupted.
4566      * @see android.media.MediaPlayer.OnInfoListener
4567      */
4568     public static final int MEDIA_INFO_VIDEO_NOT_PLAYING = 805;
4569 
4570     /** Failed to handle timed text track properly.
4571      * @see android.media.MediaPlayer.OnInfoListener
4572      *
4573      * {@hide}
4574      */
4575     @UnsupportedAppUsage(maxTargetSdk = Build.VERSION_CODES.R, trackingBug = 170729553)
4576     public static final int MEDIA_INFO_TIMED_TEXT_ERROR = 900;
4577 
4578     /** Subtitle track was not supported by the media framework.
4579      * @see android.media.MediaPlayer.OnInfoListener
4580      */
4581     public static final int MEDIA_INFO_UNSUPPORTED_SUBTITLE = 901;
4582 
4583     /** Reading the subtitle track takes too long.
4584      * @see android.media.MediaPlayer.OnInfoListener
4585      */
4586     public static final int MEDIA_INFO_SUBTITLE_TIMED_OUT = 902;
4587 
4588     /**
4589      * Interface definition of a callback to be invoked to communicate some
4590      * info and/or warning about the media or its playback.
4591      */
4592     public interface OnInfoListener
4593     {
4594         /**
4595          * Called to indicate an info or a warning.
4596          *
4597          * @param mp      the MediaPlayer the info pertains to.
4598          * @param what    the type of info or warning.
4599          * <ul>
4600          * <li>{@link #MEDIA_INFO_UNKNOWN}
4601          * <li>{@link #MEDIA_INFO_VIDEO_TRACK_LAGGING}
4602          * <li>{@link #MEDIA_INFO_VIDEO_RENDERING_START}
4603          * <li>{@link #MEDIA_INFO_BUFFERING_START}
4604          * <li>{@link #MEDIA_INFO_BUFFERING_END}
4605          * <li><code>MEDIA_INFO_NETWORK_BANDWIDTH (703)</code> -
4606          *     bandwidth information is available (as <code>extra</code> kbps)
4607          * <li>{@link #MEDIA_INFO_BAD_INTERLEAVING}
4608          * <li>{@link #MEDIA_INFO_NOT_SEEKABLE}
4609          * <li>{@link #MEDIA_INFO_METADATA_UPDATE}
4610          * <li>{@link #MEDIA_INFO_UNSUPPORTED_SUBTITLE}
4611          * <li>{@link #MEDIA_INFO_SUBTITLE_TIMED_OUT}
4612          * </ul>
4613          * @param extra an extra code, specific to the info. Typically
4614          * implementation dependent.
4615          * @return True if the method handled the info, false if it didn't.
4616          * Returning false, or not having an OnInfoListener at all, will
4617          * cause the info to be discarded.
4618          */
onInfo(MediaPlayer mp, int what, int extra)4619         boolean onInfo(MediaPlayer mp, int what, int extra);
4620     }
4621 
4622     /**
4623      * Register a callback to be invoked when an info/warning is available.
4624      *
4625      * @param listener the callback that will be run
4626      */
setOnInfoListener(OnInfoListener listener)4627     public void setOnInfoListener(OnInfoListener listener)
4628     {
4629         mOnInfoListener = listener;
4630     }
4631 
4632     @UnsupportedAppUsage
4633     private OnInfoListener mOnInfoListener;
4634 
4635     // Modular DRM begin
4636 
4637     /**
4638      * Interface definition of a callback to be invoked when the app
4639      * can do DRM configuration (get/set properties) before the session
4640      * is opened. This facilitates configuration of the properties, like
4641      * 'securityLevel', which has to be set after DRM scheme creation but
4642      * before the DRM session is opened.
4643      *
4644      * The only allowed DRM calls in this listener are {@code getDrmPropertyString}
4645      * and {@code setDrmPropertyString}.
4646      *
4647      */
4648     public interface OnDrmConfigHelper
4649     {
4650         /**
4651          * Called to give the app the opportunity to configure DRM before the session is created
4652          *
4653          * @param mp the {@code MediaPlayer} associated with this callback
4654          */
onDrmConfig(MediaPlayer mp)4655         public void onDrmConfig(MediaPlayer mp);
4656     }
4657 
4658     /**
4659      * Register a callback to be invoked for configuration of the DRM object before
4660      * the session is created.
4661      * The callback will be invoked synchronously during the execution
4662      * of {@link #prepareDrm(UUID uuid)}.
4663      *
4664      * @param listener the callback that will be run
4665      */
setOnDrmConfigHelper(OnDrmConfigHelper listener)4666     public void setOnDrmConfigHelper(OnDrmConfigHelper listener)
4667     {
4668         synchronized (mDrmLock) {
4669             mOnDrmConfigHelper = listener;
4670         } // synchronized
4671     }
4672 
4673     private OnDrmConfigHelper mOnDrmConfigHelper;
4674 
4675     /**
4676      * Interface definition of a callback to be invoked when the
4677      * DRM info becomes available
4678      */
4679     public interface OnDrmInfoListener
4680     {
4681         /**
4682          * Called to indicate DRM info is available
4683          *
4684          * @param mp the {@code MediaPlayer} associated with this callback
4685          * @param drmInfo DRM info of the source including PSSH, and subset
4686          *                of crypto schemes supported by this device
4687          */
onDrmInfo(MediaPlayer mp, DrmInfo drmInfo)4688         public void onDrmInfo(MediaPlayer mp, DrmInfo drmInfo);
4689     }
4690 
4691     /**
4692      * Register a callback to be invoked when the DRM info is
4693      * known.
4694      *
4695      * @param listener the callback that will be run
4696      */
setOnDrmInfoListener(OnDrmInfoListener listener)4697     public void setOnDrmInfoListener(OnDrmInfoListener listener)
4698     {
4699         setOnDrmInfoListener(listener, null);
4700     }
4701 
4702     /**
4703      * Register a callback to be invoked when the DRM info is
4704      * known.
4705      *
4706      * @param listener the callback that will be run
4707      */
setOnDrmInfoListener(OnDrmInfoListener listener, Handler handler)4708     public void setOnDrmInfoListener(OnDrmInfoListener listener, Handler handler)
4709     {
4710         synchronized (mDrmLock) {
4711             if (listener != null) {
4712                 mOnDrmInfoHandlerDelegate = new OnDrmInfoHandlerDelegate(this, listener, handler);
4713             } else {
4714                 mOnDrmInfoHandlerDelegate = null;
4715             }
4716         } // synchronized
4717     }
4718 
4719     private OnDrmInfoHandlerDelegate mOnDrmInfoHandlerDelegate;
4720 
4721 
4722     /**
4723      * The status codes for {@link OnDrmPreparedListener#onDrmPrepared} listener.
4724      * <p>
4725      *
4726      * DRM preparation has succeeded.
4727      */
4728     public static final int PREPARE_DRM_STATUS_SUCCESS = 0;
4729 
4730     /**
4731      * The device required DRM provisioning but couldn't reach the provisioning server.
4732      */
4733     public static final int PREPARE_DRM_STATUS_PROVISIONING_NETWORK_ERROR = 1;
4734 
4735     /**
4736      * The device required DRM provisioning but the provisioning server denied the request.
4737      */
4738     public static final int PREPARE_DRM_STATUS_PROVISIONING_SERVER_ERROR = 2;
4739 
4740     /**
4741      * The DRM preparation has failed .
4742      */
4743     public static final int PREPARE_DRM_STATUS_PREPARATION_ERROR = 3;
4744 
4745 
4746     /** @hide */
4747     @IntDef({
4748         PREPARE_DRM_STATUS_SUCCESS,
4749         PREPARE_DRM_STATUS_PROVISIONING_NETWORK_ERROR,
4750         PREPARE_DRM_STATUS_PROVISIONING_SERVER_ERROR,
4751         PREPARE_DRM_STATUS_PREPARATION_ERROR,
4752     })
4753     @Retention(RetentionPolicy.SOURCE)
4754     public @interface PrepareDrmStatusCode {}
4755 
4756     /**
4757      * Interface definition of a callback to notify the app when the
4758      * DRM is ready for key request/response
4759      */
4760     public interface OnDrmPreparedListener
4761     {
4762         /**
4763          * Called to notify the app that prepareDrm is finished and ready for key request/response
4764          *
4765          * @param mp the {@code MediaPlayer} associated with this callback
4766          * @param status the result of DRM preparation which can be
4767          * {@link #PREPARE_DRM_STATUS_SUCCESS},
4768          * {@link #PREPARE_DRM_STATUS_PROVISIONING_NETWORK_ERROR},
4769          * {@link #PREPARE_DRM_STATUS_PROVISIONING_SERVER_ERROR}, or
4770          * {@link #PREPARE_DRM_STATUS_PREPARATION_ERROR}.
4771          */
onDrmPrepared(MediaPlayer mp, @PrepareDrmStatusCode int status)4772         public void onDrmPrepared(MediaPlayer mp, @PrepareDrmStatusCode int status);
4773     }
4774 
4775     /**
4776      * Register a callback to be invoked when the DRM object is prepared.
4777      *
4778      * @param listener the callback that will be run
4779      */
setOnDrmPreparedListener(OnDrmPreparedListener listener)4780     public void setOnDrmPreparedListener(OnDrmPreparedListener listener)
4781     {
4782         setOnDrmPreparedListener(listener, null);
4783     }
4784 
4785     /**
4786      * Register a callback to be invoked when the DRM object is prepared.
4787      *
4788      * @param listener the callback that will be run
4789      * @param handler the Handler that will receive the callback
4790      */
setOnDrmPreparedListener(OnDrmPreparedListener listener, Handler handler)4791     public void setOnDrmPreparedListener(OnDrmPreparedListener listener, Handler handler)
4792     {
4793         synchronized (mDrmLock) {
4794             if (listener != null) {
4795                 mOnDrmPreparedHandlerDelegate = new OnDrmPreparedHandlerDelegate(this,
4796                                                             listener, handler);
4797             } else {
4798                 mOnDrmPreparedHandlerDelegate = null;
4799             }
4800         } // synchronized
4801     }
4802 
4803     private OnDrmPreparedHandlerDelegate mOnDrmPreparedHandlerDelegate;
4804 
4805 
4806     private class OnDrmInfoHandlerDelegate {
4807         private MediaPlayer mMediaPlayer;
4808         private OnDrmInfoListener mOnDrmInfoListener;
4809         private Handler mHandler;
4810 
OnDrmInfoHandlerDelegate(MediaPlayer mp, OnDrmInfoListener listener, Handler handler)4811         OnDrmInfoHandlerDelegate(MediaPlayer mp, OnDrmInfoListener listener, Handler handler) {
4812             mMediaPlayer = mp;
4813             mOnDrmInfoListener = listener;
4814 
4815             // find the looper for our new event handler
4816             if (handler != null) {
4817                 mHandler = handler;
4818             } else {
4819                 // handler == null
4820                 // Will let OnDrmInfoListener be called in mEventHandler similar to other
4821                 // legacy notifications. This is because MEDIA_DRM_INFO's notification has to be
4822                 // sent before MEDIA_PREPARED's (i.e., in the same order they are issued by
4823                 // mediaserver). As a result, the callback has to be called directly by
4824                 // EventHandler.handleMessage similar to onPrepared.
4825             }
4826         }
4827 
notifyClient(DrmInfo drmInfo)4828         void notifyClient(DrmInfo drmInfo) {
4829             if (mHandler != null) {
4830                 mHandler.post(new Runnable() {
4831                     @Override
4832                     public void run() {
4833                        mOnDrmInfoListener.onDrmInfo(mMediaPlayer, drmInfo);
4834                     }
4835                 });
4836             }
4837             else {  // no handler: direct call by mEventHandler
4838                 mOnDrmInfoListener.onDrmInfo(mMediaPlayer, drmInfo);
4839             }
4840         }
4841     }
4842 
4843     private class OnDrmPreparedHandlerDelegate {
4844         private MediaPlayer mMediaPlayer;
4845         private OnDrmPreparedListener mOnDrmPreparedListener;
4846         private Handler mHandler;
4847 
OnDrmPreparedHandlerDelegate(MediaPlayer mp, OnDrmPreparedListener listener, Handler handler)4848         OnDrmPreparedHandlerDelegate(MediaPlayer mp, OnDrmPreparedListener listener,
4849                 Handler handler) {
4850             mMediaPlayer = mp;
4851             mOnDrmPreparedListener = listener;
4852 
4853             // find the looper for our new event handler
4854             if (handler != null) {
4855                 mHandler = handler;
4856             } else if (mEventHandler != null) {
4857                 // Otherwise, use mEventHandler
4858                 mHandler = mEventHandler;
4859             } else {
4860                 Log.e(TAG, "OnDrmPreparedHandlerDelegate: Unexpected null mEventHandler");
4861             }
4862         }
4863 
notifyClient(int status)4864         void notifyClient(int status) {
4865             if (mHandler != null) {
4866                 mHandler.post(new Runnable() {
4867                     @Override
4868                     public void run() {
4869                         mOnDrmPreparedListener.onDrmPrepared(mMediaPlayer, status);
4870                     }
4871                 });
4872             } else {
4873                 Log.e(TAG, "OnDrmPreparedHandlerDelegate:notifyClient: Unexpected null mHandler");
4874             }
4875         }
4876     }
4877 
4878     /**
4879      * Retrieves the DRM Info associated with the current source
4880      *
4881      * @throws IllegalStateException if called before prepare()
4882      */
getDrmInfo()4883     public DrmInfo getDrmInfo()
4884     {
4885         DrmInfo drmInfo = null;
4886 
4887         // there is not much point if the app calls getDrmInfo within an OnDrmInfoListenet;
4888         // regardless below returns drmInfo anyway instead of raising an exception
4889         synchronized (mDrmLock) {
4890             if (!mDrmInfoResolved && mDrmInfo == null) {
4891                 final String msg = "The Player has not been prepared yet";
4892                 Log.v(TAG, msg);
4893                 throw new IllegalStateException(msg);
4894             }
4895 
4896             if (mDrmInfo != null) {
4897                 drmInfo = mDrmInfo.makeCopy();
4898             }
4899         }   // synchronized
4900 
4901         return drmInfo;
4902     }
4903 
4904 
4905     /**
4906      * Prepares the DRM for the current source
4907      * <p>
4908      * If {@code OnDrmConfigHelper} is registered, it will be called during
4909      * preparation to allow configuration of the DRM properties before opening the
4910      * DRM session. Note that the callback is called synchronously in the thread that called
4911      * {@code prepareDrm}. It should be used only for a series of {@code getDrmPropertyString}
4912      * and {@code setDrmPropertyString} calls and refrain from any lengthy operation.
4913      * <p>
4914      * If the device has not been provisioned before, this call also provisions the device
4915      * which involves accessing the provisioning server and can take a variable time to
4916      * complete depending on the network connectivity.
4917      * If {@code OnDrmPreparedListener} is registered, prepareDrm() runs in non-blocking
4918      * mode by launching the provisioning in the background and returning. The listener
4919      * will be called when provisioning and preparation has finished. If a
4920      * {@code OnDrmPreparedListener} is not registered, prepareDrm() waits till provisioning
4921      * and preparation has finished, i.e., runs in blocking mode.
4922      * <p>
4923      * If {@code OnDrmPreparedListener} is registered, it is called to indicate the DRM
4924      * session being ready. The application should not make any assumption about its call
4925      * sequence (e.g., before or after prepareDrm returns), or the thread context that will
4926      * execute the listener (unless the listener is registered with a handler thread).
4927      * <p>
4928      *
4929      * @param uuid The UUID of the crypto scheme. If not known beforehand, it can be retrieved
4930      * from the source through {@code getDrmInfo} or registering a {@code onDrmInfoListener}.
4931      *
4932      * @throws IllegalStateException              if called before prepare(), or the DRM was
4933      *                                            prepared already
4934      * @throws UnsupportedSchemeException         if the crypto scheme is not supported
4935      * @throws ResourceBusyException              if required DRM resources are in use
4936      * @throws ProvisioningNetworkErrorException  if provisioning is required but failed due to a
4937      *                                            network error
4938      * @throws ProvisioningServerErrorException   if provisioning is required but failed due to
4939      *                                            the request denied by the provisioning server
4940      */
prepareDrm(@onNull UUID uuid)4941     public void prepareDrm(@NonNull UUID uuid)
4942             throws UnsupportedSchemeException, ResourceBusyException,
4943                    ProvisioningNetworkErrorException, ProvisioningServerErrorException
4944     {
4945         Log.v(TAG, "prepareDrm: uuid: " + uuid + " mOnDrmConfigHelper: " + mOnDrmConfigHelper);
4946 
4947         boolean allDoneWithoutProvisioning = false;
4948         // get a snapshot as we'll use them outside the lock
4949         OnDrmPreparedHandlerDelegate onDrmPreparedHandlerDelegate = null;
4950 
4951         synchronized (mDrmLock) {
4952 
4953             // only allowing if tied to a protected source; might relax for releasing offline keys
4954             if (mDrmInfo == null) {
4955                 final String msg = "prepareDrm(): Wrong usage: The player must be prepared and " +
4956                         "DRM info be retrieved before this call.";
4957                 Log.e(TAG, msg);
4958                 throw new IllegalStateException(msg);
4959             }
4960 
4961             if (mActiveDrmScheme) {
4962                 final String msg = "prepareDrm(): Wrong usage: There is already " +
4963                         "an active DRM scheme with " + mDrmUUID;
4964                 Log.e(TAG, msg);
4965                 throw new IllegalStateException(msg);
4966             }
4967 
4968             if (mPrepareDrmInProgress) {
4969                 final String msg = "prepareDrm(): Wrong usage: There is already " +
4970                         "a pending prepareDrm call.";
4971                 Log.e(TAG, msg);
4972                 throw new IllegalStateException(msg);
4973             }
4974 
4975             if (mDrmProvisioningInProgress) {
4976                 final String msg = "prepareDrm(): Unexpectd: Provisioning is already in progress.";
4977                 Log.e(TAG, msg);
4978                 throw new IllegalStateException(msg);
4979             }
4980 
4981             // shouldn't need this; just for safeguard
4982             cleanDrmObj();
4983 
4984             mPrepareDrmInProgress = true;
4985             // local copy while the lock is held
4986             onDrmPreparedHandlerDelegate = mOnDrmPreparedHandlerDelegate;
4987 
4988             try {
4989                 // only creating the DRM object to allow pre-openSession configuration
4990                 prepareDrm_createDrmStep(uuid);
4991             } catch (Exception e) {
4992                 Log.w(TAG, "prepareDrm(): Exception ", e);
4993                 mPrepareDrmInProgress = false;
4994                 throw e;
4995             }
4996 
4997             mDrmConfigAllowed = true;
4998         }   // synchronized
4999 
5000 
5001         // call the callback outside the lock
5002         if (mOnDrmConfigHelper != null)  {
5003             mOnDrmConfigHelper.onDrmConfig(this);
5004         }
5005 
5006         synchronized (mDrmLock) {
5007             mDrmConfigAllowed = false;
5008             boolean earlyExit = false;
5009 
5010             try {
5011                 prepareDrm_openSessionStep(uuid);
5012 
5013                 mDrmUUID = uuid;
5014                 mActiveDrmScheme = true;
5015 
5016                 allDoneWithoutProvisioning = true;
5017             } catch (IllegalStateException e) {
5018                 final String msg = "prepareDrm(): Wrong usage: The player must be " +
5019                         "in the prepared state to call prepareDrm().";
5020                 Log.e(TAG, msg);
5021                 earlyExit = true;
5022                 throw new IllegalStateException(msg);
5023             } catch (NotProvisionedException e) {
5024                 Log.w(TAG, "prepareDrm: NotProvisionedException");
5025 
5026                 // handle provisioning internally; it'll reset mPrepareDrmInProgress
5027                 int result = HandleProvisioninig(uuid);
5028 
5029                 // if blocking mode, we're already done;
5030                 // if non-blocking mode, we attempted to launch background provisioning
5031                 if (result != PREPARE_DRM_STATUS_SUCCESS) {
5032                     earlyExit = true;
5033                     String msg;
5034 
5035                     switch (result) {
5036                     case PREPARE_DRM_STATUS_PROVISIONING_NETWORK_ERROR:
5037                         msg = "prepareDrm: Provisioning was required but failed " +
5038                                 "due to a network error.";
5039                         Log.e(TAG, msg);
5040                         throw new ProvisioningNetworkErrorException(msg);
5041 
5042                     case PREPARE_DRM_STATUS_PROVISIONING_SERVER_ERROR:
5043                         msg = "prepareDrm: Provisioning was required but the request " +
5044                                 "was denied by the server.";
5045                         Log.e(TAG, msg);
5046                         throw new ProvisioningServerErrorException(msg);
5047 
5048                     case PREPARE_DRM_STATUS_PREPARATION_ERROR:
5049                     default: // default for safeguard
5050                         msg = "prepareDrm: Post-provisioning preparation failed.";
5051                         Log.e(TAG, msg);
5052                         throw new IllegalStateException(msg);
5053                     }
5054                 }
5055                 // nothing else to do;
5056                 // if blocking or non-blocking, HandleProvisioninig does the re-attempt & cleanup
5057             } catch (Exception e) {
5058                 Log.e(TAG, "prepareDrm: Exception " + e);
5059                 earlyExit = true;
5060                 throw e;
5061             } finally {
5062                 if (!mDrmProvisioningInProgress) {// if early exit other than provisioning exception
5063                     mPrepareDrmInProgress = false;
5064                 }
5065                 if (earlyExit) {    // cleaning up object if didn't succeed
5066                     cleanDrmObj();
5067                 }
5068             } // finally
5069         }   // synchronized
5070 
5071 
5072         // if finished successfully without provisioning, call the callback outside the lock
5073         if (allDoneWithoutProvisioning) {
5074             if (onDrmPreparedHandlerDelegate != null)
5075                 onDrmPreparedHandlerDelegate.notifyClient(PREPARE_DRM_STATUS_SUCCESS);
5076         }
5077 
5078     }
5079 
5080 
_releaseDrm()5081     private native void _releaseDrm();
5082 
5083     /**
5084      * Releases the DRM session
5085      * <p>
5086      * The player has to have an active DRM session and be in stopped, or prepared
5087      * state before this call is made.
5088      * A {@code reset()} call will release the DRM session implicitly.
5089      *
5090      * @throws NoDrmSchemeException if there is no active DRM session to release
5091      */
releaseDrm()5092     public void releaseDrm()
5093             throws NoDrmSchemeException
5094     {
5095         Log.v(TAG, "releaseDrm:");
5096 
5097         synchronized (mDrmLock) {
5098             if (!mActiveDrmScheme) {
5099                 Log.e(TAG, "releaseDrm(): No active DRM scheme to release.");
5100                 throw new NoDrmSchemeException("releaseDrm: No active DRM scheme to release.");
5101             }
5102 
5103             try {
5104                 // we don't have the player's state in this layer. The below call raises
5105                 // exception if we're in a non-stopped/prepared state.
5106 
5107                 // for cleaning native/mediaserver crypto object
5108                 _releaseDrm();
5109 
5110                 // for cleaning client-side MediaDrm object; only called if above has succeeded
5111                 cleanDrmObj();
5112 
5113                 mActiveDrmScheme = false;
5114             } catch (IllegalStateException e) {
5115                 Log.w(TAG, "releaseDrm: Exception ", e);
5116                 throw new IllegalStateException("releaseDrm: The player is not in a valid state.");
5117             } catch (Exception e) {
5118                 Log.e(TAG, "releaseDrm: Exception ", e);
5119             }
5120         }   // synchronized
5121     }
5122 
5123 
5124     /**
5125      * A key request/response exchange occurs between the app and a license server
5126      * to obtain or release keys used to decrypt encrypted content.
5127      * <p>
5128      * getKeyRequest() is used to obtain an opaque key request byte array that is
5129      * delivered to the license server.  The opaque key request byte array is returned
5130      * in KeyRequest.data.  The recommended URL to deliver the key request to is
5131      * returned in KeyRequest.defaultUrl.
5132      * <p>
5133      * After the app has received the key request response from the server,
5134      * it should deliver to the response to the DRM engine plugin using the method
5135      * {@link #provideKeyResponse}.
5136      *
5137      * @param keySetId is the key-set identifier of the offline keys being released when keyType is
5138      * {@link MediaDrm#KEY_TYPE_RELEASE}. It should be set to null for other key requests, when
5139      * keyType is {@link MediaDrm#KEY_TYPE_STREAMING} or {@link MediaDrm#KEY_TYPE_OFFLINE}.
5140      *
5141      * @param initData is the container-specific initialization data when the keyType is
5142      * {@link MediaDrm#KEY_TYPE_STREAMING} or {@link MediaDrm#KEY_TYPE_OFFLINE}. Its meaning is
5143      * interpreted based on the mime type provided in the mimeType parameter.  It could
5144      * contain, for example, the content ID, key ID or other data obtained from the content
5145      * metadata that is required in generating the key request.
5146      * When the keyType is {@link MediaDrm#KEY_TYPE_RELEASE}, it should be set to null.
5147      *
5148      * @param mimeType identifies the mime type of the content
5149      *
5150      * @param keyType specifies the type of the request. The request may be to acquire
5151      * keys for streaming, {@link MediaDrm#KEY_TYPE_STREAMING}, or for offline content
5152      * {@link MediaDrm#KEY_TYPE_OFFLINE}, or to release previously acquired
5153      * keys ({@link MediaDrm#KEY_TYPE_RELEASE}), which are identified by a keySetId.
5154      *
5155      * @param optionalParameters are included in the key request message to
5156      * allow a client application to provide additional message parameters to the server.
5157      * This may be {@code null} if no additional parameters are to be sent.
5158      *
5159      * @throws NoDrmSchemeException if there is no active DRM session
5160      */
5161     @NonNull
getKeyRequest(@ullable byte[] keySetId, @Nullable byte[] initData, @Nullable String mimeType, @MediaDrm.KeyType int keyType, @Nullable Map<String, String> optionalParameters)5162     public MediaDrm.KeyRequest getKeyRequest(@Nullable byte[] keySetId, @Nullable byte[] initData,
5163             @Nullable String mimeType, @MediaDrm.KeyType int keyType,
5164             @Nullable Map<String, String> optionalParameters)
5165             throws NoDrmSchemeException
5166     {
5167         Log.v(TAG, "getKeyRequest: "
5168                 + " keySetId: " + Arrays.toString(keySetId)
5169                 + " initData:" + Arrays.toString(initData)
5170                 + " mimeType: " + mimeType
5171                 + " keyType: " + keyType
5172                 + " optionalParameters: " + optionalParameters);
5173 
5174         synchronized (mDrmLock) {
5175             if (!mActiveDrmScheme) {
5176                 Log.e(TAG, "getKeyRequest NoDrmSchemeException");
5177                 throw new NoDrmSchemeException("getKeyRequest: Has to set a DRM scheme first.");
5178             }
5179 
5180             try {
5181                 byte[] scope = (keyType != MediaDrm.KEY_TYPE_RELEASE) ?
5182                         mDrmSessionId : // sessionId for KEY_TYPE_STREAMING/OFFLINE
5183                         keySetId;       // keySetId for KEY_TYPE_RELEASE
5184 
5185                 HashMap<String, String> hmapOptionalParameters =
5186                                                 (optionalParameters != null) ?
5187                                                 new HashMap<String, String>(optionalParameters) :
5188                                                 null;
5189 
5190                 MediaDrm.KeyRequest request = mDrmObj.getKeyRequest(scope, initData, mimeType,
5191                                                               keyType, hmapOptionalParameters);
5192                 Log.v(TAG, "getKeyRequest:   --> request: " + request);
5193 
5194                 return request;
5195 
5196             } catch (NotProvisionedException e) {
5197                 Log.w(TAG, "getKeyRequest NotProvisionedException: " +
5198                         "Unexpected. Shouldn't have reached here.");
5199                 throw new IllegalStateException("getKeyRequest: Unexpected provisioning error.");
5200             } catch (Exception e) {
5201                 Log.w(TAG, "getKeyRequest Exception " + e);
5202                 throw e;
5203             }
5204 
5205         }   // synchronized
5206     }
5207 
5208 
5209     /**
5210      * A key response is received from the license server by the app, then it is
5211      * provided to the DRM engine plugin using provideKeyResponse. When the
5212      * response is for an offline key request, a key-set identifier is returned that
5213      * can be used to later restore the keys to a new session with the method
5214      * {@ link # restoreKeys}.
5215      * When the response is for a streaming or release request, null is returned.
5216      *
5217      * @param keySetId When the response is for a release request, keySetId identifies
5218      * the saved key associated with the release request (i.e., the same keySetId
5219      * passed to the earlier {@ link # getKeyRequest} call. It MUST be null when the
5220      * response is for either streaming or offline key requests.
5221      *
5222      * @param response the byte array response from the server
5223      *
5224      * @throws NoDrmSchemeException if there is no active DRM session
5225      * @throws DeniedByServerException if the response indicates that the
5226      * server rejected the request
5227      */
provideKeyResponse(@ullable byte[] keySetId, @NonNull byte[] response)5228     public byte[] provideKeyResponse(@Nullable byte[] keySetId, @NonNull byte[] response)
5229             throws NoDrmSchemeException, DeniedByServerException
5230     {
5231         Log.v(TAG, "provideKeyResponse: keySetId: " + Arrays.toString(keySetId)
5232                 + " response: " + Arrays.toString(response));
5233 
5234         synchronized (mDrmLock) {
5235 
5236             if (!mActiveDrmScheme) {
5237                 Log.e(TAG, "getKeyRequest NoDrmSchemeException");
5238                 throw new NoDrmSchemeException("getKeyRequest: Has to set a DRM scheme first.");
5239             }
5240 
5241             try {
5242                 byte[] scope = (keySetId == null) ?
5243                                 mDrmSessionId :     // sessionId for KEY_TYPE_STREAMING/OFFLINE
5244                                 keySetId;           // keySetId for KEY_TYPE_RELEASE
5245 
5246                 byte[] keySetResult = mDrmObj.provideKeyResponse(scope, response);
5247 
5248                 Log.v(TAG, "provideKeyResponse: keySetId: " + Arrays.toString(keySetId)
5249                         + " response: " + Arrays.toString(response)
5250                         + " --> " + Arrays.toString(keySetResult));
5251 
5252 
5253                 return keySetResult;
5254 
5255             } catch (NotProvisionedException e) {
5256                 Log.w(TAG, "provideKeyResponse NotProvisionedException: " +
5257                         "Unexpected. Shouldn't have reached here.");
5258                 throw new IllegalStateException("provideKeyResponse: " +
5259                         "Unexpected provisioning error.");
5260             } catch (Exception e) {
5261                 Log.w(TAG, "provideKeyResponse Exception " + e);
5262                 throw e;
5263             }
5264         }   // synchronized
5265     }
5266 
5267 
5268     /**
5269      * Restore persisted offline keys into a new session.  keySetId identifies the
5270      * keys to load, obtained from a prior call to {@link #provideKeyResponse}.
5271      *
5272      * @param keySetId identifies the saved key set to restore
5273      */
restoreKeys(@onNull byte[] keySetId)5274     public void restoreKeys(@NonNull byte[] keySetId)
5275             throws NoDrmSchemeException
5276     {
5277         Log.v(TAG, "restoreKeys: keySetId: " + Arrays.toString(keySetId));
5278 
5279         synchronized (mDrmLock) {
5280 
5281             if (!mActiveDrmScheme) {
5282                 Log.w(TAG, "restoreKeys NoDrmSchemeException");
5283                 throw new NoDrmSchemeException("restoreKeys: Has to set a DRM scheme first.");
5284             }
5285 
5286             try {
5287                 mDrmObj.restoreKeys(mDrmSessionId, keySetId);
5288             } catch (Exception e) {
5289                 Log.w(TAG, "restoreKeys Exception " + e);
5290                 throw e;
5291             }
5292 
5293         }   // synchronized
5294     }
5295 
5296 
5297     /**
5298      * Read a DRM engine plugin String property value, given the property name string.
5299      * <p>
5300      * @param propertyName the property name
5301      *
5302      * Standard fields names are:
5303      * {@link MediaDrm#PROPERTY_VENDOR}, {@link MediaDrm#PROPERTY_VERSION},
5304      * {@link MediaDrm#PROPERTY_DESCRIPTION}, {@link MediaDrm#PROPERTY_ALGORITHMS}
5305      */
5306     @NonNull
getDrmPropertyString(@onNull @ediaDrm.StringProperty String propertyName)5307     public String getDrmPropertyString(@NonNull @MediaDrm.StringProperty String propertyName)
5308             throws NoDrmSchemeException
5309     {
5310         Log.v(TAG, "getDrmPropertyString: propertyName: " + propertyName);
5311 
5312         String value;
5313         synchronized (mDrmLock) {
5314 
5315             if (!mActiveDrmScheme && !mDrmConfigAllowed) {
5316                 Log.w(TAG, "getDrmPropertyString NoDrmSchemeException");
5317                 throw new NoDrmSchemeException("getDrmPropertyString: Has to prepareDrm() first.");
5318             }
5319 
5320             try {
5321                 value = mDrmObj.getPropertyString(propertyName);
5322             } catch (Exception e) {
5323                 Log.w(TAG, "getDrmPropertyString Exception " + e);
5324                 throw e;
5325             }
5326         }   // synchronized
5327 
5328         Log.v(TAG, "getDrmPropertyString: propertyName: " + propertyName + " --> value: " + value);
5329 
5330         return value;
5331     }
5332 
5333 
5334     /**
5335      * Set a DRM engine plugin String property value.
5336      * <p>
5337      * @param propertyName the property name
5338      * @param value the property value
5339      *
5340      * Standard fields names are:
5341      * {@link MediaDrm#PROPERTY_VENDOR}, {@link MediaDrm#PROPERTY_VERSION},
5342      * {@link MediaDrm#PROPERTY_DESCRIPTION}, {@link MediaDrm#PROPERTY_ALGORITHMS}
5343      */
setDrmPropertyString(@onNull @ediaDrm.StringProperty String propertyName, @NonNull String value)5344     public void setDrmPropertyString(@NonNull @MediaDrm.StringProperty String propertyName,
5345                                      @NonNull String value)
5346             throws NoDrmSchemeException
5347     {
5348         Log.v(TAG, "setDrmPropertyString: propertyName: " + propertyName + " value: " + value);
5349 
5350         synchronized (mDrmLock) {
5351 
5352             if ( !mActiveDrmScheme && !mDrmConfigAllowed ) {
5353                 Log.w(TAG, "setDrmPropertyString NoDrmSchemeException");
5354                 throw new NoDrmSchemeException("setDrmPropertyString: Has to prepareDrm() first.");
5355             }
5356 
5357             try {
5358                 mDrmObj.setPropertyString(propertyName, value);
5359             } catch ( Exception e ) {
5360                 Log.w(TAG, "setDrmPropertyString Exception " + e);
5361                 throw e;
5362             }
5363         }   // synchronized
5364     }
5365 
5366     /**
5367      * Encapsulates the DRM properties of the source.
5368      */
5369     public static final class DrmInfo {
5370         private Map<UUID, byte[]> mapPssh;
5371         private UUID[] supportedSchemes;
5372 
5373         /**
5374          * Returns the PSSH info of the data source for each supported DRM scheme.
5375          */
getPssh()5376         public Map<UUID, byte[]> getPssh() {
5377             return mapPssh;
5378         }
5379 
5380         /**
5381          * Returns the intersection of the data source and the device DRM schemes.
5382          * It effectively identifies the subset of the source's DRM schemes which
5383          * are supported by the device too.
5384          */
getSupportedSchemes()5385         public UUID[] getSupportedSchemes() {
5386             return supportedSchemes;
5387         }
5388 
DrmInfo(Map<UUID, byte[]> Pssh, UUID[] SupportedSchemes)5389         private DrmInfo(Map<UUID, byte[]> Pssh, UUID[] SupportedSchemes) {
5390             mapPssh = Pssh;
5391             supportedSchemes = SupportedSchemes;
5392         }
5393 
DrmInfo(Parcel parcel)5394         private DrmInfo(Parcel parcel) {
5395             Log.v(TAG, "DrmInfo(" + parcel + ") size " + parcel.dataSize());
5396 
5397             int psshsize = parcel.readInt();
5398             byte[] pssh = new byte[psshsize];
5399             parcel.readByteArray(pssh);
5400 
5401             Log.v(TAG, "DrmInfo() PSSH: " + arrToHex(pssh));
5402             mapPssh = parsePSSH(pssh, psshsize);
5403             Log.v(TAG, "DrmInfo() PSSH: " + mapPssh);
5404 
5405             int supportedDRMsCount = parcel.readInt();
5406             supportedSchemes = new UUID[supportedDRMsCount];
5407             for (int i = 0; i < supportedDRMsCount; i++) {
5408                 byte[] uuid = new byte[16];
5409                 parcel.readByteArray(uuid);
5410 
5411                 supportedSchemes[i] = bytesToUUID(uuid);
5412 
5413                 Log.v(TAG, "DrmInfo() supportedScheme[" + i + "]: " +
5414                       supportedSchemes[i]);
5415             }
5416 
5417             Log.v(TAG, "DrmInfo() Parcel psshsize: " + psshsize +
5418                   " supportedDRMsCount: " + supportedDRMsCount);
5419         }
5420 
makeCopy()5421         private DrmInfo makeCopy() {
5422             return new DrmInfo(this.mapPssh, this.supportedSchemes);
5423         }
5424 
arrToHex(byte[] bytes)5425         private String arrToHex(byte[] bytes) {
5426             String out = "0x";
5427             for (int i = 0; i < bytes.length; i++) {
5428                 out += String.format("%02x", bytes[i]);
5429             }
5430 
5431             return out;
5432         }
5433 
bytesToUUID(byte[] uuid)5434         private UUID bytesToUUID(byte[] uuid) {
5435             long msb = 0, lsb = 0;
5436             for (int i = 0; i < 8; i++) {
5437                 msb |= ( ((long)uuid[i]   & 0xff) << (8 * (7 - i)) );
5438                 lsb |= ( ((long)uuid[i+8] & 0xff) << (8 * (7 - i)) );
5439             }
5440 
5441             return new UUID(msb, lsb);
5442         }
5443 
parsePSSH(byte[] pssh, int psshsize)5444         private Map<UUID, byte[]> parsePSSH(byte[] pssh, int psshsize) {
5445             Map<UUID, byte[]> result = new HashMap<UUID, byte[]>();
5446 
5447             final int UUID_SIZE = 16;
5448             final int DATALEN_SIZE = 4;
5449 
5450             int len = psshsize;
5451             int numentries = 0;
5452             int i = 0;
5453 
5454             while (len > 0) {
5455                 if (len < UUID_SIZE) {
5456                     Log.w(TAG, String.format("parsePSSH: len is too short to parse " +
5457                                              "UUID: (%d < 16) pssh: %d", len, psshsize));
5458                     return null;
5459                 }
5460 
5461                 byte[] subset = Arrays.copyOfRange(pssh, i, i + UUID_SIZE);
5462                 UUID uuid = bytesToUUID(subset);
5463                 i += UUID_SIZE;
5464                 len -= UUID_SIZE;
5465 
5466                 // get data length
5467                 if (len < 4) {
5468                     Log.w(TAG, String.format("parsePSSH: len is too short to parse " +
5469                                              "datalen: (%d < 4) pssh: %d", len, psshsize));
5470                     return null;
5471                 }
5472 
5473                 subset = Arrays.copyOfRange(pssh, i, i+DATALEN_SIZE);
5474                 int datalen = (ByteOrder.nativeOrder() == ByteOrder.LITTLE_ENDIAN) ?
5475                     ((subset[3] & 0xff) << 24) | ((subset[2] & 0xff) << 16) |
5476                     ((subset[1] & 0xff) <<  8) |  (subset[0] & 0xff)          :
5477                     ((subset[0] & 0xff) << 24) | ((subset[1] & 0xff) << 16) |
5478                     ((subset[2] & 0xff) <<  8) |  (subset[3] & 0xff) ;
5479                 i += DATALEN_SIZE;
5480                 len -= DATALEN_SIZE;
5481 
5482                 if (len < datalen) {
5483                     Log.w(TAG, String.format("parsePSSH: len is too short to parse " +
5484                                              "data: (%d < %d) pssh: %d", len, datalen, psshsize));
5485                     return null;
5486                 }
5487 
5488                 byte[] data = Arrays.copyOfRange(pssh, i, i+datalen);
5489 
5490                 // skip the data
5491                 i += datalen;
5492                 len -= datalen;
5493 
5494                 Log.v(TAG, String.format("parsePSSH[%d]: <%s, %s> pssh: %d",
5495                                          numentries, uuid, arrToHex(data), psshsize));
5496                 numentries++;
5497                 result.put(uuid, data);
5498             }
5499 
5500             return result;
5501         }
5502 
5503     };  // DrmInfo
5504 
5505     /**
5506      * Thrown when a DRM method is called before preparing a DRM scheme through prepareDrm().
5507      * Extends MediaDrm.MediaDrmException
5508      */
5509     public static final class NoDrmSchemeException extends MediaDrmException {
NoDrmSchemeException(String detailMessage)5510         public NoDrmSchemeException(String detailMessage) {
5511             super(detailMessage);
5512         }
5513     }
5514 
5515     /**
5516      * Thrown when the device requires DRM provisioning but the provisioning attempt has
5517      * failed due to a network error (Internet reachability, timeout, etc.).
5518      * Extends MediaDrm.MediaDrmException
5519      */
5520     public static final class ProvisioningNetworkErrorException extends MediaDrmException {
ProvisioningNetworkErrorException(String detailMessage)5521         public ProvisioningNetworkErrorException(String detailMessage) {
5522             super(detailMessage);
5523         }
5524     }
5525 
5526     /**
5527      * Thrown when the device requires DRM provisioning but the provisioning attempt has
5528      * failed due to the provisioning server denying the request.
5529      * Extends MediaDrm.MediaDrmException
5530      */
5531     public static final class ProvisioningServerErrorException extends MediaDrmException {
ProvisioningServerErrorException(String detailMessage)5532         public ProvisioningServerErrorException(String detailMessage) {
5533             super(detailMessage);
5534         }
5535     }
5536 
5537 
_prepareDrm(@onNull byte[] uuid, @NonNull byte[] drmSessionId)5538     private native void _prepareDrm(@NonNull byte[] uuid, @NonNull byte[] drmSessionId);
5539 
5540         // Modular DRM helpers
5541 
prepareDrm_createDrmStep(@onNull UUID uuid)5542     private void prepareDrm_createDrmStep(@NonNull UUID uuid)
5543             throws UnsupportedSchemeException {
5544         Log.v(TAG, "prepareDrm_createDrmStep: UUID: " + uuid);
5545 
5546         try {
5547             mDrmObj = new MediaDrm(uuid);
5548             Log.v(TAG, "prepareDrm_createDrmStep: Created mDrmObj=" + mDrmObj);
5549         } catch (Exception e) { // UnsupportedSchemeException
5550             Log.e(TAG, "prepareDrm_createDrmStep: MediaDrm failed with " + e);
5551             throw e;
5552         }
5553     }
5554 
prepareDrm_openSessionStep(@onNull UUID uuid)5555     private void prepareDrm_openSessionStep(@NonNull UUID uuid)
5556             throws NotProvisionedException, ResourceBusyException {
5557         Log.v(TAG, "prepareDrm_openSessionStep: uuid: " + uuid);
5558 
5559         // TODO: don't need an open session for a future specialKeyReleaseDrm mode but we should do
5560         // it anyway so it raises provisioning error if needed. We'd rather handle provisioning
5561         // at prepareDrm/openSession rather than getKeyRequest/provideKeyResponse
5562         try {
5563             mDrmSessionId = mDrmObj.openSession();
5564             Log.v(TAG, "prepareDrm_openSessionStep: mDrmSessionId="
5565                     + Arrays.toString(mDrmSessionId));
5566 
5567             // Sending it down to native/mediaserver to create the crypto object
5568             // This call could simply fail due to bad player state, e.g., after start().
5569             _prepareDrm(getByteArrayFromUUID(uuid), mDrmSessionId);
5570             Log.v(TAG, "prepareDrm_openSessionStep: _prepareDrm/Crypto succeeded");
5571 
5572         } catch (Exception e) { //ResourceBusyException, NotProvisionedException
5573             Log.e(TAG, "prepareDrm_openSessionStep: open/crypto failed with " + e);
5574             throw e;
5575         }
5576 
5577     }
5578 
5579     private class ProvisioningThread extends Thread
5580     {
5581         public static final int TIMEOUT_MS = 60000;
5582 
5583         private UUID uuid;
5584         private String urlStr;
5585         private Object drmLock;
5586         private OnDrmPreparedHandlerDelegate onDrmPreparedHandlerDelegate;
5587         private MediaPlayer mediaPlayer;
5588         private int status;
5589         private boolean finished;
status()5590         public  int status() {
5591             return status;
5592         }
5593 
initialize(MediaDrm.ProvisionRequest request, UUID uuid, MediaPlayer mediaPlayer)5594         public ProvisioningThread initialize(MediaDrm.ProvisionRequest request,
5595                                           UUID uuid, MediaPlayer mediaPlayer) {
5596             // lock is held by the caller
5597             drmLock = mediaPlayer.mDrmLock;
5598             onDrmPreparedHandlerDelegate = mediaPlayer.mOnDrmPreparedHandlerDelegate;
5599             this.mediaPlayer = mediaPlayer;
5600 
5601             urlStr = request.getDefaultUrl() + "&signedRequest=" + new String(request.getData());
5602             this.uuid = uuid;
5603 
5604             status = PREPARE_DRM_STATUS_PREPARATION_ERROR;
5605 
5606             Log.v(TAG, "HandleProvisioninig: Thread is initialised url: " + urlStr);
5607             return this;
5608         }
5609 
run()5610         public void run() {
5611 
5612             byte[] response = null;
5613             boolean provisioningSucceeded = false;
5614             try {
5615                 URL url = new URL(urlStr);
5616                 final HttpURLConnection connection = (HttpURLConnection) url.openConnection();
5617                 try {
5618                     connection.setRequestMethod("POST");
5619                     connection.setDoOutput(false);
5620                     connection.setDoInput(true);
5621                     connection.setConnectTimeout(TIMEOUT_MS);
5622                     connection.setReadTimeout(TIMEOUT_MS);
5623 
5624                     connection.connect();
5625                     response = Streams.readFully(connection.getInputStream());
5626 
5627                     Log.v(TAG, "HandleProvisioninig: Thread run: response " +
5628                             response.length + " " + Arrays.toString(response));
5629                 } catch (Exception e) {
5630                     status = PREPARE_DRM_STATUS_PROVISIONING_NETWORK_ERROR;
5631                     Log.w(TAG, "HandleProvisioninig: Thread run: connect " + e + " url: " + url);
5632                 } finally {
5633                     connection.disconnect();
5634                 }
5635             } catch (Exception e)   {
5636                 status = PREPARE_DRM_STATUS_PROVISIONING_NETWORK_ERROR;
5637                 Log.w(TAG, "HandleProvisioninig: Thread run: openConnection " + e);
5638             }
5639 
5640             if (response != null) {
5641                 try {
5642                     mDrmObj.provideProvisionResponse(response);
5643                     Log.v(TAG, "HandleProvisioninig: Thread run: " +
5644                             "provideProvisionResponse SUCCEEDED!");
5645 
5646                     provisioningSucceeded = true;
5647                 } catch (Exception e) {
5648                     status = PREPARE_DRM_STATUS_PROVISIONING_SERVER_ERROR;
5649                     Log.w(TAG, "HandleProvisioninig: Thread run: " +
5650                             "provideProvisionResponse " + e);
5651                 }
5652             }
5653 
5654             boolean succeeded = false;
5655 
5656             // non-blocking mode needs the lock
5657             if (onDrmPreparedHandlerDelegate != null) {
5658 
5659                 synchronized (drmLock) {
5660                     // continuing with prepareDrm
5661                     if (provisioningSucceeded) {
5662                         succeeded = mediaPlayer.resumePrepareDrm(uuid);
5663                         status = (succeeded) ?
5664                                 PREPARE_DRM_STATUS_SUCCESS :
5665                                 PREPARE_DRM_STATUS_PREPARATION_ERROR;
5666                     }
5667                     mediaPlayer.mDrmProvisioningInProgress = false;
5668                     mediaPlayer.mPrepareDrmInProgress = false;
5669                     if (!succeeded) {
5670                         cleanDrmObj();  // cleaning up if it hasn't gone through while in the lock
5671                     }
5672                 } // synchronized
5673 
5674                 // calling the callback outside the lock
5675                 onDrmPreparedHandlerDelegate.notifyClient(status);
5676             } else {   // blocking mode already has the lock
5677 
5678                 // continuing with prepareDrm
5679                 if (provisioningSucceeded) {
5680                     succeeded = mediaPlayer.resumePrepareDrm(uuid);
5681                     status = (succeeded) ?
5682                             PREPARE_DRM_STATUS_SUCCESS :
5683                             PREPARE_DRM_STATUS_PREPARATION_ERROR;
5684                 }
5685                 mediaPlayer.mDrmProvisioningInProgress = false;
5686                 mediaPlayer.mPrepareDrmInProgress = false;
5687                 if (!succeeded) {
5688                     cleanDrmObj();  // cleaning up if it hasn't gone through
5689                 }
5690             }
5691 
5692             finished = true;
5693         }   // run()
5694 
5695     }   // ProvisioningThread
5696 
HandleProvisioninig(UUID uuid)5697     private int HandleProvisioninig(UUID uuid)
5698     {
5699         // the lock is already held by the caller
5700 
5701         if (mDrmProvisioningInProgress) {
5702             Log.e(TAG, "HandleProvisioninig: Unexpected mDrmProvisioningInProgress");
5703             return PREPARE_DRM_STATUS_PREPARATION_ERROR;
5704         }
5705 
5706         MediaDrm.ProvisionRequest provReq = mDrmObj.getProvisionRequest();
5707         if (provReq == null) {
5708             Log.e(TAG, "HandleProvisioninig: getProvisionRequest returned null.");
5709             return PREPARE_DRM_STATUS_PREPARATION_ERROR;
5710         }
5711 
5712         Log.v(TAG, "HandleProvisioninig provReq "
5713                 + " data: " + Arrays.toString(provReq.getData())
5714                 + " url: " + provReq.getDefaultUrl());
5715 
5716         // networking in a background thread
5717         mDrmProvisioningInProgress = true;
5718 
5719         mDrmProvisioningThread = new ProvisioningThread().initialize(provReq, uuid, this);
5720         mDrmProvisioningThread.start();
5721 
5722         int result;
5723 
5724         // non-blocking: this is not the final result
5725         if (mOnDrmPreparedHandlerDelegate != null) {
5726             result = PREPARE_DRM_STATUS_SUCCESS;
5727         } else {
5728             // if blocking mode, wait till provisioning is done
5729             try {
5730                 mDrmProvisioningThread.join();
5731             } catch (Exception e) {
5732                 Log.w(TAG, "HandleProvisioninig: Thread.join Exception " + e);
5733             }
5734             result = mDrmProvisioningThread.status();
5735             // no longer need the thread
5736             mDrmProvisioningThread = null;
5737         }
5738 
5739         return result;
5740     }
5741 
resumePrepareDrm(UUID uuid)5742     private boolean resumePrepareDrm(UUID uuid)
5743     {
5744         Log.v(TAG, "resumePrepareDrm: uuid: " + uuid);
5745 
5746         // mDrmLock is guaranteed to be held
5747         boolean success = false;
5748         try {
5749             // resuming
5750             prepareDrm_openSessionStep(uuid);
5751 
5752             mDrmUUID = uuid;
5753             mActiveDrmScheme = true;
5754 
5755             success = true;
5756         } catch (Exception e) {
5757             Log.w(TAG, "HandleProvisioninig: Thread run _prepareDrm resume failed with " + e);
5758             // mDrmObj clean up is done by the caller
5759         }
5760 
5761         return success;
5762     }
5763 
resetDrmState()5764     private void resetDrmState()
5765     {
5766         synchronized (mDrmLock) {
5767             Log.v(TAG, "resetDrmState: " +
5768                     " mDrmInfo=" + mDrmInfo +
5769                     " mDrmProvisioningThread=" + mDrmProvisioningThread +
5770                     " mPrepareDrmInProgress=" + mPrepareDrmInProgress +
5771                     " mActiveDrmScheme=" + mActiveDrmScheme);
5772 
5773             mDrmInfoResolved = false;
5774             mDrmInfo = null;
5775 
5776             if (mDrmProvisioningThread != null) {
5777                 // timeout; relying on HttpUrlConnection
5778                 try {
5779                     mDrmProvisioningThread.join();
5780                 }
5781                 catch (InterruptedException e) {
5782                     Log.w(TAG, "resetDrmState: ProvThread.join Exception " + e);
5783                 }
5784                 mDrmProvisioningThread = null;
5785             }
5786 
5787             mPrepareDrmInProgress = false;
5788             mActiveDrmScheme = false;
5789 
5790             cleanDrmObj();
5791         }   // synchronized
5792     }
5793 
cleanDrmObj()5794     private void cleanDrmObj()
5795     {
5796         // the caller holds mDrmLock
5797         Log.v(TAG, "cleanDrmObj: mDrmObj=" + mDrmObj
5798                 + " mDrmSessionId=" + Arrays.toString(mDrmSessionId));
5799 
5800         if (mDrmSessionId != null)    {
5801             mDrmObj.closeSession(mDrmSessionId);
5802             mDrmSessionId = null;
5803         }
5804         if (mDrmObj != null) {
5805             mDrmObj.release();
5806             mDrmObj = null;
5807         }
5808     }
5809 
getByteArrayFromUUID(@onNull UUID uuid)5810     private static final byte[] getByteArrayFromUUID(@NonNull UUID uuid) {
5811         long msb = uuid.getMostSignificantBits();
5812         long lsb = uuid.getLeastSignificantBits();
5813 
5814         byte[] uuidBytes = new byte[16];
5815         for (int i = 0; i < 8; ++i) {
5816             uuidBytes[i] = (byte)(msb >>> (8 * (7 - i)));
5817             uuidBytes[8 + i] = (byte)(lsb >>> (8 * (7 - i)));
5818         }
5819 
5820         return uuidBytes;
5821     }
5822 
5823     // Modular DRM end
5824 
5825     /*
5826      * Test whether a given video scaling mode is supported.
5827      */
isVideoScalingModeSupported(int mode)5828     private boolean isVideoScalingModeSupported(int mode) {
5829         return (mode == VIDEO_SCALING_MODE_SCALE_TO_FIT ||
5830                 mode == VIDEO_SCALING_MODE_SCALE_TO_FIT_WITH_CROPPING);
5831     }
5832 
5833     /** @hide */
5834     static class TimeProvider implements MediaPlayer.OnSeekCompleteListener,
5835             MediaTimeProvider {
5836         private static final String TAG = "MTP";
5837         private static final long MAX_NS_WITHOUT_POSITION_CHECK = 5000000000L;
5838         private static final long MAX_EARLY_CALLBACK_US = 1000;
5839         private static final long TIME_ADJUSTMENT_RATE = 2;  /* meaning 1/2 */
5840         private long mLastTimeUs = 0;
5841         private MediaPlayer mPlayer;
5842         private boolean mPaused = true;
5843         private boolean mStopped = true;
5844         private boolean mBuffering;
5845         private long mLastReportedTime;
5846         // since we are expecting only a handful listeners per stream, there is
5847         // no need for log(N) search performance
5848         private MediaTimeProvider.OnMediaTimeListener mListeners[];
5849         private long mTimes[];
5850         private Handler mEventHandler;
5851         private boolean mRefresh = false;
5852         private boolean mPausing = false;
5853         private boolean mSeeking = false;
5854         private static final int NOTIFY = 1;
5855         private static final int NOTIFY_TIME = 0;
5856         private static final int NOTIFY_STOP = 2;
5857         private static final int NOTIFY_SEEK = 3;
5858         private static final int NOTIFY_TRACK_DATA = 4;
5859         private HandlerThread mHandlerThread;
5860 
5861         /** @hide */
5862         public boolean DEBUG = false;
5863 
TimeProvider(MediaPlayer mp)5864         public TimeProvider(MediaPlayer mp) {
5865             mPlayer = mp;
5866             try {
5867                 getCurrentTimeUs(true, false);
5868             } catch (IllegalStateException e) {
5869                 // we assume starting position
5870                 mRefresh = true;
5871             }
5872 
5873             Looper looper;
5874             if ((looper = Looper.myLooper()) == null &&
5875                 (looper = Looper.getMainLooper()) == null) {
5876                 // Create our own looper here in case MP was created without one
5877                 mHandlerThread = new HandlerThread("MediaPlayerMTPEventThread",
5878                       Process.THREAD_PRIORITY_FOREGROUND);
5879                 mHandlerThread.start();
5880                 looper = mHandlerThread.getLooper();
5881             }
5882             mEventHandler = new EventHandler(looper);
5883 
5884             mListeners = new MediaTimeProvider.OnMediaTimeListener[0];
5885             mTimes = new long[0];
5886             mLastTimeUs = 0;
5887         }
5888 
scheduleNotification(int type, long delayUs)5889         private void scheduleNotification(int type, long delayUs) {
5890             // ignore time notifications until seek is handled
5891             if (mSeeking && type == NOTIFY_TIME) {
5892                 return;
5893             }
5894 
5895             if (DEBUG) Log.v(TAG, "scheduleNotification " + type + " in " + delayUs);
5896             mEventHandler.removeMessages(NOTIFY);
5897             Message msg = mEventHandler.obtainMessage(NOTIFY, type, 0);
5898             mEventHandler.sendMessageDelayed(msg, (int) (delayUs / 1000));
5899         }
5900 
5901         /** @hide */
close()5902         public void close() {
5903             mEventHandler.removeMessages(NOTIFY);
5904             if (mHandlerThread != null) {
5905                 mHandlerThread.quitSafely();
5906                 mHandlerThread = null;
5907             }
5908         }
5909 
5910         /** @hide */
finalize()5911         protected void finalize() {
5912             if (mHandlerThread != null) {
5913                 mHandlerThread.quitSafely();
5914             }
5915         }
5916 
5917         /** @hide */
onNotifyTime()5918         public void onNotifyTime() {
5919             synchronized (this) {
5920                 if (DEBUG) Log.d(TAG, "onNotifyTime: ");
5921                 scheduleNotification(NOTIFY_TIME, 0 /* delay */);
5922             }
5923         }
5924 
5925         /** @hide */
onPaused(boolean paused)5926         public void onPaused(boolean paused) {
5927             synchronized(this) {
5928                 if (DEBUG) Log.d(TAG, "onPaused: " + paused);
5929                 if (mStopped) { // handle as seek if we were stopped
5930                     mStopped = false;
5931                     mSeeking = true;
5932                     scheduleNotification(NOTIFY_SEEK, 0 /* delay */);
5933                 } else {
5934                     mPausing = paused;  // special handling if player disappeared
5935                     mSeeking = false;
5936                     scheduleNotification(NOTIFY_TIME, 0 /* delay */);
5937                 }
5938             }
5939         }
5940 
5941         /** @hide */
onBuffering(boolean buffering)5942         public void onBuffering(boolean buffering) {
5943             synchronized (this) {
5944                 if (DEBUG) Log.d(TAG, "onBuffering: " + buffering);
5945                 mBuffering = buffering;
5946                 scheduleNotification(NOTIFY_TIME, 0 /* delay */);
5947             }
5948         }
5949 
5950         /** @hide */
onStopped()5951         public void onStopped() {
5952             synchronized(this) {
5953                 if (DEBUG) Log.d(TAG, "onStopped");
5954                 mPaused = true;
5955                 mStopped = true;
5956                 mSeeking = false;
5957                 mBuffering = false;
5958                 scheduleNotification(NOTIFY_STOP, 0 /* delay */);
5959             }
5960         }
5961 
5962         /** @hide */
5963         @Override
onSeekComplete(MediaPlayer mp)5964         public void onSeekComplete(MediaPlayer mp) {
5965             synchronized(this) {
5966                 mStopped = false;
5967                 mSeeking = true;
5968                 scheduleNotification(NOTIFY_SEEK, 0 /* delay */);
5969             }
5970         }
5971 
5972         /** @hide */
onNewPlayer()5973         public void onNewPlayer() {
5974             if (mRefresh) {
5975                 synchronized(this) {
5976                     mStopped = false;
5977                     mSeeking = true;
5978                     mBuffering = false;
5979                     scheduleNotification(NOTIFY_SEEK, 0 /* delay */);
5980                 }
5981             }
5982         }
5983 
notifySeek()5984         private synchronized void notifySeek() {
5985             mSeeking = false;
5986             try {
5987                 long timeUs = getCurrentTimeUs(true, false);
5988                 if (DEBUG) Log.d(TAG, "onSeekComplete at " + timeUs);
5989 
5990                 for (MediaTimeProvider.OnMediaTimeListener listener: mListeners) {
5991                     if (listener == null) {
5992                         break;
5993                     }
5994                     listener.onSeek(timeUs);
5995                 }
5996             } catch (IllegalStateException e) {
5997                 // we should not be there, but at least signal pause
5998                 if (DEBUG) Log.d(TAG, "onSeekComplete but no player");
5999                 mPausing = true;  // special handling if player disappeared
6000                 notifyTimedEvent(false /* refreshTime */);
6001             }
6002         }
6003 
notifyTrackData(Pair<SubtitleTrack, byte[]> trackData)6004         private synchronized void notifyTrackData(Pair<SubtitleTrack, byte[]> trackData) {
6005             SubtitleTrack track = trackData.first;
6006             byte[] data = trackData.second;
6007             track.onData(data, true /* eos */, ~0 /* runID: keep forever */);
6008         }
6009 
notifyStop()6010         private synchronized void notifyStop() {
6011             for (MediaTimeProvider.OnMediaTimeListener listener: mListeners) {
6012                 if (listener == null) {
6013                     break;
6014                 }
6015                 listener.onStop();
6016             }
6017         }
6018 
registerListener(MediaTimeProvider.OnMediaTimeListener listener)6019         private int registerListener(MediaTimeProvider.OnMediaTimeListener listener) {
6020             int i = 0;
6021             for (; i < mListeners.length; i++) {
6022                 if (mListeners[i] == listener || mListeners[i] == null) {
6023                     break;
6024                 }
6025             }
6026 
6027             // new listener
6028             if (i >= mListeners.length) {
6029                 MediaTimeProvider.OnMediaTimeListener[] newListeners =
6030                     new MediaTimeProvider.OnMediaTimeListener[i + 1];
6031                 long[] newTimes = new long[i + 1];
6032                 System.arraycopy(mListeners, 0, newListeners, 0, mListeners.length);
6033                 System.arraycopy(mTimes, 0, newTimes, 0, mTimes.length);
6034                 mListeners = newListeners;
6035                 mTimes = newTimes;
6036             }
6037 
6038             if (mListeners[i] == null) {
6039                 mListeners[i] = listener;
6040                 mTimes[i] = MediaTimeProvider.NO_TIME;
6041             }
6042             return i;
6043         }
6044 
notifyAt( long timeUs, MediaTimeProvider.OnMediaTimeListener listener)6045         public void notifyAt(
6046                 long timeUs, MediaTimeProvider.OnMediaTimeListener listener) {
6047             synchronized(this) {
6048                 if (DEBUG) Log.d(TAG, "notifyAt " + timeUs);
6049                 mTimes[registerListener(listener)] = timeUs;
6050                 scheduleNotification(NOTIFY_TIME, 0 /* delay */);
6051             }
6052         }
6053 
scheduleUpdate(MediaTimeProvider.OnMediaTimeListener listener)6054         public void scheduleUpdate(MediaTimeProvider.OnMediaTimeListener listener) {
6055             synchronized(this) {
6056                 if (DEBUG) Log.d(TAG, "scheduleUpdate");
6057                 int i = registerListener(listener);
6058 
6059                 if (!mStopped) {
6060                     mTimes[i] = 0;
6061                     scheduleNotification(NOTIFY_TIME, 0 /* delay */);
6062                 }
6063             }
6064         }
6065 
cancelNotifications( MediaTimeProvider.OnMediaTimeListener listener)6066         public void cancelNotifications(
6067                 MediaTimeProvider.OnMediaTimeListener listener) {
6068             synchronized(this) {
6069                 int i = 0;
6070                 for (; i < mListeners.length; i++) {
6071                     if (mListeners[i] == listener) {
6072                         System.arraycopy(mListeners, i + 1,
6073                                 mListeners, i, mListeners.length - i - 1);
6074                         System.arraycopy(mTimes, i + 1,
6075                                 mTimes, i, mTimes.length - i - 1);
6076                         mListeners[mListeners.length - 1] = null;
6077                         mTimes[mTimes.length - 1] = NO_TIME;
6078                         break;
6079                     } else if (mListeners[i] == null) {
6080                         break;
6081                     }
6082                 }
6083 
6084                 scheduleNotification(NOTIFY_TIME, 0 /* delay */);
6085             }
6086         }
6087 
notifyTimedEvent(boolean refreshTime)6088         private synchronized void notifyTimedEvent(boolean refreshTime) {
6089             // figure out next callback
6090             long nowUs;
6091             try {
6092                 nowUs = getCurrentTimeUs(refreshTime, true);
6093             } catch (IllegalStateException e) {
6094                 // assume we paused until new player arrives
6095                 mRefresh = true;
6096                 mPausing = true; // this ensures that call succeeds
6097                 nowUs = getCurrentTimeUs(refreshTime, true);
6098             }
6099             long nextTimeUs = nowUs;
6100 
6101             if (mSeeking) {
6102                 // skip timed-event notifications until seek is complete
6103                 return;
6104             }
6105 
6106             if (DEBUG) {
6107                 StringBuilder sb = new StringBuilder();
6108                 sb.append("notifyTimedEvent(").append(mLastTimeUs).append(" -> ")
6109                         .append(nowUs).append(") from {");
6110                 boolean first = true;
6111                 for (long time: mTimes) {
6112                     if (time == NO_TIME) {
6113                         continue;
6114                     }
6115                     if (!first) sb.append(", ");
6116                     sb.append(time);
6117                     first = false;
6118                 }
6119                 sb.append("}");
6120                 Log.d(TAG, sb.toString());
6121             }
6122 
6123             Vector<MediaTimeProvider.OnMediaTimeListener> activatedListeners =
6124                 new Vector<MediaTimeProvider.OnMediaTimeListener>();
6125             for (int ix = 0; ix < mTimes.length; ix++) {
6126                 if (mListeners[ix] == null) {
6127                     break;
6128                 }
6129                 if (mTimes[ix] <= NO_TIME) {
6130                     // ignore, unless we were stopped
6131                 } else if (mTimes[ix] <= nowUs + MAX_EARLY_CALLBACK_US) {
6132                     activatedListeners.add(mListeners[ix]);
6133                     if (DEBUG) Log.d(TAG, "removed");
6134                     mTimes[ix] = NO_TIME;
6135                 } else if (nextTimeUs == nowUs || mTimes[ix] < nextTimeUs) {
6136                     nextTimeUs = mTimes[ix];
6137                 }
6138             }
6139 
6140             if (nextTimeUs > nowUs && !mPaused) {
6141                 // schedule callback at nextTimeUs
6142                 if (DEBUG) Log.d(TAG, "scheduling for " + nextTimeUs + " and " + nowUs);
6143                 mPlayer.notifyAt(nextTimeUs);
6144             } else {
6145                 mEventHandler.removeMessages(NOTIFY);
6146                 // no more callbacks
6147             }
6148 
6149             for (MediaTimeProvider.OnMediaTimeListener listener: activatedListeners) {
6150                 listener.onTimedEvent(nowUs);
6151             }
6152         }
6153 
getCurrentTimeUs(boolean refreshTime, boolean monotonic)6154         public long getCurrentTimeUs(boolean refreshTime, boolean monotonic)
6155                 throws IllegalStateException {
6156             synchronized (this) {
6157                 // we always refresh the time when the paused-state changes, because
6158                 // we expect to have received the pause-change event delayed.
6159                 if (mPaused && !refreshTime) {
6160                     return mLastReportedTime;
6161                 }
6162 
6163                 try {
6164                     mLastTimeUs = mPlayer.getCurrentPosition() * 1000L;
6165                     mPaused = !mPlayer.isPlaying() || mBuffering;
6166                     if (DEBUG) Log.v(TAG, (mPaused ? "paused" : "playing") + " at " + mLastTimeUs);
6167                 } catch (IllegalStateException e) {
6168                     if (mPausing) {
6169                         // if we were pausing, get last estimated timestamp
6170                         mPausing = false;
6171                         if (!monotonic || mLastReportedTime < mLastTimeUs) {
6172                             mLastReportedTime = mLastTimeUs;
6173                         }
6174                         mPaused = true;
6175                         if (DEBUG) Log.d(TAG, "illegal state, but pausing: estimating at " + mLastReportedTime);
6176                         return mLastReportedTime;
6177                     }
6178                     // TODO get time when prepared
6179                     throw e;
6180                 }
6181                 if (monotonic && mLastTimeUs < mLastReportedTime) {
6182                     /* have to adjust time */
6183                     if (mLastReportedTime - mLastTimeUs > 1000000) {
6184                         // schedule seeked event if time jumped significantly
6185                         // TODO: do this properly by introducing an exception
6186                         mStopped = false;
6187                         mSeeking = true;
6188                         scheduleNotification(NOTIFY_SEEK, 0 /* delay */);
6189                     }
6190                 } else {
6191                     mLastReportedTime = mLastTimeUs;
6192                 }
6193 
6194                 return mLastReportedTime;
6195             }
6196         }
6197 
6198         private class EventHandler extends Handler {
EventHandler(Looper looper)6199             public EventHandler(Looper looper) {
6200                 super(looper);
6201             }
6202 
6203             @Override
handleMessage(Message msg)6204             public void handleMessage(Message msg) {
6205                 if (msg.what == NOTIFY) {
6206                     switch (msg.arg1) {
6207                     case NOTIFY_TIME:
6208                         notifyTimedEvent(true /* refreshTime */);
6209                         break;
6210                     case NOTIFY_STOP:
6211                         notifyStop();
6212                         break;
6213                     case NOTIFY_SEEK:
6214                         notifySeek();
6215                         break;
6216                     case NOTIFY_TRACK_DATA:
6217                         notifyTrackData((Pair<SubtitleTrack, byte[]>)msg.obj);
6218                         break;
6219                     }
6220                 }
6221             }
6222         }
6223     }
6224 
6225     public final static class MetricsConstants
6226     {
MetricsConstants()6227         private MetricsConstants() {}
6228 
6229         /**
6230          * Key to extract the MIME type of the video track
6231          * from the {@link MediaPlayer#getMetrics} return value.
6232          * The value is a String.
6233          */
6234         public static final String MIME_TYPE_VIDEO = "android.media.mediaplayer.video.mime";
6235 
6236         /**
6237          * Key to extract the codec being used to decode the video track
6238          * from the {@link MediaPlayer#getMetrics} return value.
6239          * The value is a String.
6240          */
6241         public static final String CODEC_VIDEO = "android.media.mediaplayer.video.codec";
6242 
6243         /**
6244          * Key to extract the width (in pixels) of the video track
6245          * from the {@link MediaPlayer#getMetrics} return value.
6246          * The value is an integer.
6247          */
6248         public static final String WIDTH = "android.media.mediaplayer.width";
6249 
6250         /**
6251          * Key to extract the height (in pixels) of the video track
6252          * from the {@link MediaPlayer#getMetrics} return value.
6253          * The value is an integer.
6254          */
6255         public static final String HEIGHT = "android.media.mediaplayer.height";
6256 
6257         /**
6258          * Key to extract the count of video frames played
6259          * from the {@link MediaPlayer#getMetrics} return value.
6260          * The value is an integer.
6261          */
6262         public static final String FRAMES = "android.media.mediaplayer.frames";
6263 
6264         /**
6265          * Key to extract the count of video frames dropped
6266          * from the {@link MediaPlayer#getMetrics} return value.
6267          * The value is an integer.
6268          */
6269         public static final String FRAMES_DROPPED = "android.media.mediaplayer.dropped";
6270 
6271         /**
6272          * Key to extract the MIME type of the audio track
6273          * from the {@link MediaPlayer#getMetrics} return value.
6274          * The value is a String.
6275          */
6276         public static final String MIME_TYPE_AUDIO = "android.media.mediaplayer.audio.mime";
6277 
6278         /**
6279          * Key to extract the codec being used to decode the audio track
6280          * from the {@link MediaPlayer#getMetrics} return value.
6281          * The value is a String.
6282          */
6283         public static final String CODEC_AUDIO = "android.media.mediaplayer.audio.codec";
6284 
6285         /**
6286          * Key to extract the duration (in milliseconds) of the
6287          * media being played
6288          * from the {@link MediaPlayer#getMetrics} return value.
6289          * The value is a long.
6290          */
6291         public static final String DURATION = "android.media.mediaplayer.durationMs";
6292 
6293         /**
6294          * Key to extract the playing time (in milliseconds) of the
6295          * media being played
6296          * from the {@link MediaPlayer#getMetrics} return value.
6297          * The value is a long.
6298          */
6299         public static final String PLAYING = "android.media.mediaplayer.playingMs";
6300 
6301         /**
6302          * Key to extract the count of errors encountered while
6303          * playing the media
6304          * from the {@link MediaPlayer#getMetrics} return value.
6305          * The value is an integer.
6306          */
6307         public static final String ERRORS = "android.media.mediaplayer.err";
6308 
6309         /**
6310          * Key to extract an (optional) error code detected while
6311          * playing the media
6312          * from the {@link MediaPlayer#getMetrics} return value.
6313          * The value is an integer.
6314          */
6315         public static final String ERROR_CODE = "android.media.mediaplayer.errcode";
6316 
6317     }
6318 }
6319