media/java/android/media/MediaPlayer.java

   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 android.annotation.IntDef;
  20 import android.annotation.NonNull;
  21 import android.annotation.Nullable;
  22 import android.app.ActivityThread;
  23 import android.content.ContentResolver;
  24 import android.content.Context;
  25 import android.content.res.AssetFileDescriptor;
  26 import android.net.Uri;
  27 import android.os.Handler;
  28 import android.os.HandlerThread;
  29 import android.os.IBinder;
  30 import android.os.Looper;
  31 import android.os.Message;
  32 import android.os.Parcel;
  33 import android.os.Parcelable;
  34 import android.os.Process;
  35 import android.os.PowerManager;
  36 import android.os.SystemProperties;
  37 import android.provider.Settings;
  38 import android.system.ErrnoException;
  39 import android.system.OsConstants;
  40 import android.util.Log;
  41 import android.util.Pair;
  42 import android.view.Surface;
  43 import android.view.SurfaceHolder;
  44 import android.widget.VideoView;
  45 import android.graphics.SurfaceTexture;
  46 import android.media.AudioManager;
  47 import android.media.MediaFormat;
  48 import android.media.MediaTimeProvider;
  49 import android.media.PlaybackParams;
  50 import android.media.SubtitleController;
  51 import android.media.SubtitleController.Anchor;
  52 import android.media.SubtitleData;
  53 import android.media.SubtitleTrack.RenderingWidget;
  54 import android.media.SyncParams;
  55
  56 import com.android.internal.util.Preconditions;
  57
  58 import libcore.io.IoBridge;
  59 import libcore.io.Libcore;
  60
  61 import java.io.ByteArrayOutputStream;
  62 import java.io.File;
  63 import java.io.FileDescriptor;
  64 import java.io.FileInputStream;
  65 import java.io.IOException;
  66 import java.io.InputStream;
  67 import java.lang.Runnable;
  68 import java.lang.annotation.Retention;
  69 import java.lang.annotation.RetentionPolicy;
  70 import java.net.InetSocketAddress;
  71 import java.util.BitSet;
  72 import java.util.Map;
  73 import java.util.Scanner;
  74 import java.util.Set;
  75 import java.util.Vector;
  76 import java.lang.ref.WeakReference;
  77
  78 /**
  79  * MediaPlayer class can be used to control playback
  80  * of audio/video files and streams. An example on how to use the methods in
  81  * this class can be found in {@link android.widget.VideoView}.
  82  *
  83  * <p>Topics covered here are:
  84  * <ol>
  85  * <li><a href="#StateDiagram">State Diagram</a>
  86  * <li><a href="#Valid_and_Invalid_States">Valid and Invalid States</a>
  87  * <li><a href="#Permissions">Permissions</a>
  88  * <li><a href="#Callbacks">Register informational and error callbacks</a>
  89  * </ol>
  90  *
  91  * <div class="special reference">
  92  * <h3>Developer Guides</h3>
  93  * <p>For more information about how to use MediaPlayer, read the
  94  * <a href="{@docRoot}guide/topics/media/mediaplayer.html">Media Playback</a> developer guide.</p>
  95  * </div>
  96  *
  97  * <a name="StateDiagram"></a>
  98  * <h3>State Diagram</h3>
  99  *
 100  * <p>Playback control of audio/video files and streams is managed as a state
 101  * machine. The following diagram shows the life cycle and the states of a
 102  * MediaPlayer object driven by the supported playback control operations.
 103  * The ovals represent the states a MediaPlayer object may reside
 104  * in. The arcs represent the playback control operations that drive the object
 105  * state transition. There are two types of arcs. The arcs with a single arrow
 106  * head represent synchronous method calls, while those with
 107  * a double arrow head represent asynchronous method calls.</p>
 108  *
 109  * <p><img src="../../../images/mediaplayer_state_diagram.gif"
 110  *         alt="MediaPlayer State diagram"
 111  *         border="0" /></p>
 112  *
 113  * <p>From this state diagram, one can see that a MediaPlayer object has the
 114  *    following states:</p>
 115  * <ul>
 116  *     <li>When a MediaPlayer object is just created using <code>new</code> or
 117  *         after {@link #reset()} is called, it is in the <em>Idle</em> state; and after
 118  *         {@link #release()} is called, it is in the <em>End</em> state. Between these
 119  *         two states is the life cycle of the MediaPlayer object.
 120  *         <ul>
 121  *         <li>There is a subtle but important difference between a newly constructed
 122  *         MediaPlayer object and the MediaPlayer object after {@link #reset()}
 123  *         is called. It is a programming error to invoke methods such
 124  *         as {@link #getCurrentPosition()},
 125  *         {@link #getDuration()}, {@link #getVideoHeight()},
 126  *         {@link #getVideoWidth()}, {@link #setAudioStreamType(int)},
 127  *         {@link #setLooping(boolean)},
 128  *         {@link #setVolume(float, float)}, {@link #pause()}, {@link #start()},
 129  *         {@link #stop()}, {@link #seekTo(int)}, {@link #prepare()} or
 130  *         {@link #prepareAsync()} in the <em>Idle</em> state for both cases. If any of these
 131  *         methods is called right after a MediaPlayer object is constructed,
 132  *         the user supplied callback method OnErrorListener.onError() won't be
 133  *         called by the internal player engine and the object state remains
 134  *         unchanged; but if these methods are called right after {@link #reset()},
 135  *         the user supplied callback method OnErrorListener.onError() will be
 136  *         invoked by the internal player engine and the object will be
 137  *         transfered to the <em>Error</em> state. </li>
 138  *         <li>It is also recommended that once
 139  *         a MediaPlayer object is no longer being used, call {@link #release()} immediately
 140  *         so that resources used by the internal player engine associated with the
 141  *         MediaPlayer object can be released immediately. Resource may include
 142  *         singleton resources such as hardware acceleration components and
 143  *         failure to call {@link #release()} may cause subsequent instances of
 144  *         MediaPlayer objects to fallback to software implementations or fail
 145  *         altogether. Once the MediaPlayer
 146  *         object is in the <em>End</em> state, it can no longer be used and
 147  *         there is no way to bring it back to any other state. </li>
 148  *         <li>Furthermore,
 149  *         the MediaPlayer objects created using <code>new</code> is in the
 150  *         <em>Idle</em> state, while those created with one
 151  *         of the overloaded convenient <code>create</code> methods are <em>NOT</em>
 152  *         in the <em>Idle</em> state. In fact, the objects are in the <em>Prepared</em>
 153  *         state if the creation using <code>create</code> method is successful.
 154  *         </li>
 155  *         </ul>
 156  *         </li>
 157  *     <li>In general, some playback control operation may fail due to various
 158  *         reasons, such as unsupported audio/video format, poorly interleaved
 159  *         audio/video, resolution too high, streaming timeout, and the like.
 160  *         Thus, error reporting and recovery is an important concern under
 161  *         these circumstances. Sometimes, due to programming errors, invoking a playback
 162  *         control operation in an invalid state may also occur. Under all these
 163  *         error conditions, the internal player engine invokes a user supplied
 164  *         OnErrorListener.onError() method if an OnErrorListener has been
 165  *         registered beforehand via
 166  *         {@link #setOnErrorListener(android.media.MediaPlayer.OnErrorListener)}.
 167  *         <ul>
 168  *         <li>It is important to note that once an error occurs, the
 169  *         MediaPlayer object enters the <em>Error</em> state (except as noted
 170  *         above), even if an error listener has not been registered by the application.</li>
 171  *         <li>In order to reuse a MediaPlayer object that is in the <em>
 172  *         Error</em> state and recover from the error,
 173  *         {@link #reset()} can be called to restore the object to its <em>Idle</em>
 174  *         state.</li>
 175  *         <li>It is good programming practice to have your application
 176  *         register a OnErrorListener to look out for error notifications from
 177  *         the internal player engine.</li>
 178  *         <li>IllegalStateException is
 179  *         thrown to prevent programming errors such as calling {@link #prepare()},
 180  *         {@link #prepareAsync()}, or one of the overloaded <code>setDataSource
 181  *         </code> methods in an invalid state. </li>
 182  *         </ul>
 183  *         </li>
 184  *     <li>Calling
 185  *         {@link #setDataSource(FileDescriptor)}, or
 186  *         {@link #setDataSource(String)}, or
 187  *         {@link #setDataSource(Context, Uri)}, or
 188  *         {@link #setDataSource(FileDescriptor, long, long)}, or
 189  *         {@link #setDataSource(MediaDataSource)} transfers a
 190  *         MediaPlayer object in the <em>Idle</em> state to the
 191  *         <em>Initialized</em> state.
 192  *         <ul>
 193  *         <li>An IllegalStateException is thrown if
 194  *         setDataSource() is called in any other state.</li>
 195  *         <li>It is good programming
 196  *         practice to always look out for <code>IllegalArgumentException</code>
 197  *         and <code>IOException</code> that may be thrown from the overloaded
 198  *         <code>setDataSource</code> methods.</li>
 199  *         </ul>
 200  *         </li>
 201  *     <li>A MediaPlayer object must first enter the <em>Prepared</em> state
 202  *         before playback can be started.
 203  *         <ul>
 204  *         <li>There are two ways (synchronous vs.
 205  *         asynchronous) that the <em>Prepared</em> state can be reached:
 206  *         either a call to {@link #prepare()} (synchronous) which
 207  *         transfers the object to the <em>Prepared</em> state once the method call
 208  *         returns, or a call to {@link #prepareAsync()} (asynchronous) which
 209  *         first transfers the object to the <em>Preparing</em> state after the
 210  *         call returns (which occurs almost right way) while the internal
 211  *         player engine continues working on the rest of preparation work
 212  *         until the preparation work completes. When the preparation completes or when {@link #prepare()} call returns,
 213  *         the internal player engine then calls a user supplied callback method,
 214  *         onPrepared() of the OnPreparedListener interface, if an
 215  *         OnPreparedListener is registered beforehand via {@link
 216  *         #setOnPreparedListener(android.media.MediaPlayer.OnPreparedListener)}.</li>
 217  *         <li>It is important to note that
 218  *         the <em>Preparing</em> state is a transient state, and the behavior
 219  *         of calling any method with side effect while a MediaPlayer object is
 220  *         in the <em>Preparing</em> state is undefined.</li>
 221  *         <li>An IllegalStateException is
 222  *         thrown if {@link #prepare()} or {@link #prepareAsync()} is called in
 223  *         any other state.</li>
 224  *         <li>While in the <em>Prepared</em> state, properties
 225  *         such as audio/sound volume, screenOnWhilePlaying, looping can be
 226  *         adjusted by invoking the corresponding set methods.</li>
 227  *         </ul>
 228  *         </li>
 229  *     <li>To start the playback, {@link #start()} must be called. After
 230  *         {@link #start()} returns successfully, the MediaPlayer object is in the
 231  *         <em>Started</em> state. {@link #isPlaying()} can be called to test
 232  *         whether the MediaPlayer object is in the <em>Started</em> state.
 233  *         <ul>
 234  *         <li>While in the <em>Started</em> state, the internal player engine calls
 235  *         a user supplied OnBufferingUpdateListener.onBufferingUpdate() callback
 236  *         method if a OnBufferingUpdateListener has been registered beforehand
 237  *         via {@link #setOnBufferingUpdateListener(OnBufferingUpdateListener)}.
 238  *         This callback allows applications to keep track of the buffering status
 239  *         while streaming audio/video.</li>
 240  *         <li>Calling {@link #start()} has not effect
 241  *         on a MediaPlayer object that is already in the <em>Started</em> state.</li>
 242  *         </ul>
 243  *         </li>
 244  *     <li>Playback can be paused and stopped, and the current playback position
 245  *         can be adjusted. Playback can be paused via {@link #pause()}. When the call to
 246  *         {@link #pause()} returns, the MediaPlayer object enters the
 247  *         <em>Paused</em> state. Note that the transition from the <em>Started</em>
 248  *         state to the <em>Paused</em> state and vice versa happens
 249  *         asynchronously in the player engine. It may take some time before
 250  *         the state is updated in calls to {@link #isPlaying()}, and it can be
 251  *         a number of seconds in the case of streamed content.
 252  *         <ul>
 253  *         <li>Calling {@link #start()} to resume playback for a paused
 254  *         MediaPlayer object, and the resumed playback
 255  *         position is the same as where it was paused. When the call to
 256  *         {@link #start()} returns, the paused MediaPlayer object goes back to
 257  *         the <em>Started</em> state.</li>
 258  *         <li>Calling {@link #pause()} has no effect on
 259  *         a MediaPlayer object that is already in the <em>Paused</em> state.</li>
 260  *         </ul>
 261  *         </li>
 262  *     <li>Calling  {@link #stop()} stops playback and causes a
 263  *         MediaPlayer in the <em>Started</em>, <em>Paused</em>, <em>Prepared
 264  *         </em> or <em>PlaybackCompleted</em> state to enter the
 265  *         <em>Stopped</em> state.
 266  *         <ul>
 267  *         <li>Once in the <em>Stopped</em> state, playback cannot be started
 268  *         until {@link #prepare()} or {@link #prepareAsync()} are called to set
 269  *         the MediaPlayer object to the <em>Prepared</em> state again.</li>
 270  *         <li>Calling {@link #stop()} has no effect on a MediaPlayer
 271  *         object that is already in the <em>Stopped</em> state.</li>
 272  *         </ul>
 273  *         </li>
 274  *     <li>The playback position can be adjusted with a call to
 275  *         {@link #seekTo(int)}.
 276  *         <ul>
 277  *         <li>Although the asynchronuous {@link #seekTo(int)}
 278  *         call returns right way, the actual seek operation may take a while to
 279  *         finish, especially for audio/video being streamed. When the actual
 280  *         seek operation completes, the internal player engine calls a user
 281  *         supplied OnSeekComplete.onSeekComplete() if an OnSeekCompleteListener
 282  *         has been registered beforehand via
 283  *         {@link #setOnSeekCompleteListener(OnSeekCompleteListener)}.</li>
 284  *         <li>Please
 285  *         note that {@link #seekTo(int)} can also be called in the other states,
 286  *         such as <em>Prepared</em>, <em>Paused</em> and <em>PlaybackCompleted
 287  *         </em> state.</li>
 288  *         <li>Furthermore, the actual current playback position
 289  *         can be retrieved with a call to {@link #getCurrentPosition()}, which
 290  *         is helpful for applications such as a Music player that need to keep
 291  *         track of the playback progress.</li>
 292  *         </ul>
 293  *         </li>
 294  *     <li>When the playback reaches the end of stream, the playback completes.
 295  *         <ul>
 296  *         <li>If the looping mode was being set to <var>true</var>with
 297  *         {@link #setLooping(boolean)}, the MediaPlayer object shall remain in
 298  *         the <em>Started</em> state.</li>
 299  *         <li>If the looping mode was set to <var>false
 300  *         </var>, the player engine calls a user supplied callback method,
 301  *         OnCompletion.onCompletion(), if a OnCompletionListener is registered
 302  *         beforehand via {@link #setOnCompletionListener(OnCompletionListener)}.
 303  *         The invoke of the callback signals that the object is now in the <em>
 304  *         PlaybackCompleted</em> state.</li>
 305  *         <li>While in the <em>PlaybackCompleted</em>
 306  *         state, calling {@link #start()} can restart the playback from the
 307  *         beginning of the audio/video source.</li>
 308  * </ul>
 309  *
 310  *
 311  * <a name="Valid_and_Invalid_States"></a>
 312  * <h3>Valid and invalid states</h3>
 313  *
 314  * <table border="0" cellspacing="0" cellpadding="0">
 315  * <tr><td>Method Name </p></td>
 316  *     <td>Valid Sates </p></td>
 317  *     <td>Invalid States </p></td>
 318  *     <td>Comments </p></td></tr>
 319  * <tr><td>attachAuxEffect </p></td>
 320  *     <td>{Initialized, Prepared, Started, Paused, Stopped, PlaybackCompleted} </p></td>
 321  *     <td>{Idle, Error} </p></td>
 322  *     <td>This method must be called after setDataSource.
 323  *     Calling it does not change the object state. </p></td></tr>
 324  * <tr><td>getAudioSessionId </p></td>
 325  *     <td>any </p></td>
 326  *     <td>{} </p></td>
 327  *     <td>This method can be called in any state and calling it does not change
 328  *         the object state. </p></td></tr>
 329  * <tr><td>getCurrentPosition </p></td>
 330  *     <td>{Idle, Initialized, Prepared, Started, Paused, Stopped,
 331  *         PlaybackCompleted} </p></td>
 332  *     <td>{Error}</p></td>
 333  *     <td>Successful invoke of this method in a valid state does not change the
 334  *         state. Calling this method in an invalid state transfers the object
 335  *         to the <em>Error</em> state. </p></td></tr>
 336  * <tr><td>getDuration </p></td>
 337  *     <td>{Prepared, Started, Paused, Stopped, PlaybackCompleted} </p></td>
 338  *     <td>{Idle, Initialized, Error} </p></td>
 339  *     <td>Successful invoke of this method in a valid state does not change the
 340  *         state. Calling this method in an invalid state transfers the object
 341  *         to the <em>Error</em> state. </p></td></tr>
 342  * <tr><td>getVideoHeight </p></td>
 343  *     <td>{Idle, Initialized, Prepared, Started, Paused, Stopped,
 344  *         PlaybackCompleted}</p></td>
 345  *     <td>{Error}</p></td>
 346  *     <td>Successful invoke of this method in a valid state does not change the
 347  *         state. Calling this method in an invalid state transfers the object
 348  *         to the <em>Error</em> state.  </p></td></tr>
 349  * <tr><td>getVideoWidth </p></td>
 350  *     <td>{Idle, Initialized, Prepared, Started, Paused, Stopped,
 351  *         PlaybackCompleted}</p></td>
 352  *     <td>{Error}</p></td>
 353  *     <td>Successful invoke of this method in a valid state does not change
 354  *         the state. Calling this method in an invalid state transfers the
 355  *         object to the <em>Error</em> state. </p></td></tr>
 356  * <tr><td>isPlaying </p></td>
 357  *     <td>{Idle, Initialized, Prepared, Started, Paused, Stopped,
 358  *          PlaybackCompleted}</p></td>
 359  *     <td>{Error}</p></td>
 360  *     <td>Successful invoke of this method in a valid state does not change
 361  *         the state. Calling this method in an invalid state transfers the
 362  *         object to the <em>Error</em> state. </p></td></tr>
 363  * <tr><td>pause </p></td>
 364  *     <td>{Started, Paused, PlaybackCompleted}</p></td>
 365  *     <td>{Idle, Initialized, Prepared, Stopped, Error}</p></td>
 366  *     <td>Successful invoke of this method in a valid state transfers the
 367  *         object to the <em>Paused</em> state. Calling this method in an
 368  *         invalid state transfers the object to the <em>Error</em> state.</p></td></tr>
 369  * <tr><td>prepare </p></td>
 370  *     <td>{Initialized, Stopped} </p></td>
 371  *     <td>{Idle, Prepared, Started, Paused, PlaybackCompleted, Error} </p></td>
 372  *     <td>Successful invoke of this method in a valid state transfers the
 373  *         object to the <em>Prepared</em> state. Calling this method in an
 374  *         invalid state throws an IllegalStateException.</p></td></tr>
 375  * <tr><td>prepareAsync </p></td>
 376  *     <td>{Initialized, Stopped} </p></td>
 377  *     <td>{Idle, Prepared, Started, Paused, PlaybackCompleted, Error} </p></td>
 378  *     <td>Successful invoke of this method in a valid state transfers the
 379  *         object to the <em>Preparing</em> state. Calling this method in an
 380  *         invalid state throws an IllegalStateException.</p></td></tr>
 381  * <tr><td>release </p></td>
 382  *     <td>any </p></td>
 383  *     <td>{} </p></td>
 384  *     <td>After {@link #release()}, the object is no longer available. </p></td></tr>
 385  * <tr><td>reset </p></td>
 386  *     <td>{Idle, Initialized, Prepared, Started, Paused, Stopped,
 387  *         PlaybackCompleted, Error}</p></td>
 388  *     <td>{}</p></td>
 389  *     <td>After {@link #reset()}, the object is like being just created.</p></td></tr>
 390  * <tr><td>seekTo </p></td>
 391  *     <td>{Prepared, Started, Paused, PlaybackCompleted} </p></td>
 392  *     <td>{Idle, Initialized, Stopped, Error}</p></td>
 393  *     <td>Successful invoke of this method in a valid state does not change
 394  *         the state. Calling this method in an invalid state transfers the
 395  *         object to the <em>Error</em> state. </p></td></tr>
 396  * <tr><td>setAudioAttributes </p></td>
 397  *     <td>{Idle, Initialized, Stopped, Prepared, Started, Paused,
 398  *          PlaybackCompleted}</p></td>
 399  *     <td>{Error}</p></td>
 400  *     <td>Successful invoke of this method does not change the state. In order for the
 401  *         target audio attributes type to become effective, this method must be called before
 402  *         prepare() or prepareAsync().</p></td></tr>
 403  * <tr><td>setAudioSessionId </p></td>
 404  *     <td>{Idle} </p></td>
 405  *     <td>{Initialized, Prepared, Started, Paused, Stopped, PlaybackCompleted,
 406  *          Error} </p></td>
 407  *     <td>This method must be called in idle state as the audio session ID must be known before
 408  *         calling setDataSource. Calling it does not change the object state. </p></td></tr>
 409  * <tr><td>setAudioStreamType </p></td>
 410  *     <td>{Idle, Initialized, Stopped, Prepared, Started, Paused,
 411  *          PlaybackCompleted}</p></td>
 412  *     <td>{Error}</p></td>
 413  *     <td>Successful invoke of this method does not change the state. In order for the
 414  *         target audio stream type to become effective, this method must be called before
 415  *         prepare() or prepareAsync().</p></td></tr>
 416  * <tr><td>setAuxEffectSendLevel </p></td>
 417  *     <td>any</p></td>
 418  *     <td>{} </p></td>
 419  *     <td>Calling this method does not change the object state. </p></td></tr>
 420  * <tr><td>setDataSource </p></td>
 421  *     <td>{Idle} </p></td>
 422  *     <td>{Initialized, Prepared, Started, Paused, Stopped, PlaybackCompleted,
 423  *          Error} </p></td>
 424  *     <td>Successful invoke of this method in a valid state transfers the
 425  *         object to the <em>Initialized</em> state. Calling this method in an
 426  *         invalid state throws an IllegalStateException.</p></td></tr>
 427  * <tr><td>setDisplay </p></td>
 428  *     <td>any </p></td>
 429  *     <td>{} </p></td>
 430  *     <td>This method can be called in any state and calling it does not change
 431  *         the object state. </p></td></tr>
 432  * <tr><td>setSurface </p></td>
 433  *     <td>any </p></td>
 434  *     <td>{} </p></td>
 435  *     <td>This method can be called in any state and calling it does not change
 436  *         the object state. </p></td></tr>
 437  * <tr><td>setVideoScalingMode </p></td>
 438  *     <td>{Initialized, Prepared, Started, Paused, Stopped, PlaybackCompleted} </p></td>
 439  *     <td>{Idle, Error}</p></td>
 440  *     <td>Successful invoke of this method does not change the state.</p></td></tr>
 441  * <tr><td>setLooping </p></td>
 442  *     <td>{Idle, Initialized, Stopped, Prepared, Started, Paused,
 443  *         PlaybackCompleted}</p></td>
 444  *     <td>{Error}</p></td>
 445  *     <td>Successful invoke of this method in a valid state does not change
 446  *         the state. Calling this method in an
 447  *         invalid state transfers the object to the <em>Error</em> state.</p></td></tr>
 448  * <tr><td>isLooping </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>setOnBufferingUpdateListener </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>setOnCompletionListener </p></td>
 459  *     <td>any </p></td>
 460  *     <td>{} </p></td>
 461  *     <td>This method can be called in any state and calling it does not change
 462  *         the object state. </p></td></tr>
 463  * <tr><td>setOnErrorListener </p></td>
 464  *     <td>any </p></td>
 465  *     <td>{} </p></td>
 466  *     <td>This method can be called in any state and calling it does not change
 467  *         the object state. </p></td></tr>
 468  * <tr><td>setOnPreparedListener </p></td>
 469  *     <td>any </p></td>
 470  *     <td>{} </p></td>
 471  *     <td>This method can be called in any state and calling it does not change
 472  *         the object state. </p></td></tr>
 473  * <tr><td>setOnSeekCompleteListener </p></td>
 474  *     <td>any </p></td>
 475  *     <td>{} </p></td>
 476  *     <td>This method can be called in any state and calling it does not change
 477  *         the object state. </p></td></tr>
 478  * <tr><td>setPlaybackParams</p></td>
 479  *     <td>{Initialized, Prepared, Started, Paused, PlaybackCompleted, Error}</p></td>
 480  *     <td>{Idle, Stopped} </p></td>
 481  *     <td>This method will change state in some cases, depending on when it's called.
 482  *         </p></td></tr>
 483  * <tr><td>setScreenOnWhilePlaying</></td>
 484  *     <td>any </p></td>
 485  *     <td>{} </p></td>
 486  *     <td>This method can be called in any state and calling it does not change
 487  *         the object state.  </p></td></tr>
 488  * <tr><td>setVolume </p></td>
 489  *     <td>{Idle, Initialized, Stopped, Prepared, Started, Paused,
 490  *          PlaybackCompleted}</p></td>
 491  *     <td>{Error}</p></td>
 492  *     <td>Successful invoke of this method does not change the state.
 493  * <tr><td>setWakeMode </p></td>
 494  *     <td>any </p></td>
 495  *     <td>{} </p></td>
 496  *     <td>This method can be called in any state and calling it does not change
 497  *         the object state.</p></td></tr>
 498  * <tr><td>start </p></td>
 499  *     <td>{Prepared, Started, Paused, PlaybackCompleted}</p></td>
 500  *     <td>{Idle, Initialized, Stopped, Error}</p></td>
 501  *     <td>Successful invoke of this method in a valid state transfers the
 502  *         object to the <em>Started</em> state. Calling this method in an
 503  *         invalid state transfers the object to the <em>Error</em> state.</p></td></tr>
 504  * <tr><td>stop </p></td>
 505  *     <td>{Prepared, Started, Stopped, Paused, PlaybackCompleted}</p></td>
 506  *     <td>{Idle, Initialized, Error}</p></td>
 507  *     <td>Successful invoke of this method in a valid state transfers the
 508  *         object to the <em>Stopped</em> state. Calling this method in an
 509  *         invalid state transfers the object to the <em>Error</em> state.</p></td></tr>
 510  * <tr><td>getTrackInfo </p></td>
 511  *     <td>{Prepared, Started, Stopped, Paused, PlaybackCompleted}</p></td>
 512  *     <td>{Idle, Initialized, Error}</p></td>
 513  *     <td>Successful invoke of this method does not change the state.</p></td></tr>
 514  * <tr><td>addTimedTextSource </p></td>
 515  *     <td>{Prepared, Started, Stopped, Paused, PlaybackCompleted}</p></td>
 516  *     <td>{Idle, Initialized, Error}</p></td>
 517  *     <td>Successful invoke of this method does not change the state.</p></td></tr>
 518  * <tr><td>selectTrack </p></td>
 519  *     <td>{Prepared, Started, Stopped, Paused, PlaybackCompleted}</p></td>
 520  *     <td>{Idle, Initialized, Error}</p></td>
 521  *     <td>Successful invoke of this method does not change the state.</p></td></tr>
 522  * <tr><td>deselectTrack </p></td>
 523  *     <td>{Prepared, Started, Stopped, Paused, PlaybackCompleted}</p></td>
 524  *     <td>{Idle, Initialized, Error}</p></td>
 525  *     <td>Successful invoke of this method does not change the state.</p></td></tr>
 526  *
 527  * </table>
 528  *
 529  * <a name="Permissions"></a>
 530  * <h3>Permissions</h3>
 531  * <p>One may need to declare a corresponding WAKE_LOCK permission {@link
 532  * android.R.styleable#AndroidManifestUsesPermission &lt;uses-permission&gt;}
 533  * element.
 534  *
 535  * <p>This class requires the {@link android.Manifest.permission#INTERNET} permission
 536  * when used with network-based content.
 537  *
 538  * <a name="Callbacks"></a>
 539  * <h3>Callbacks</h3>
 540  * <p>Applications may want to register for informational and error
 541  * events in order to be informed of some internal state update and
 542  * possible runtime errors during playback or streaming. Registration for
 543  * these events is done by properly setting the appropriate listeners (via calls
 544  * to
 545  * {@link #setOnPreparedListener(OnPreparedListener)}setOnPreparedListener,
 546  * {@link #setOnVideoSizeChangedListener(OnVideoSizeChangedListener)}setOnVideoSizeChangedListener,
 547  * {@link #setOnSeekCompleteListener(OnSeekCompleteListener)}setOnSeekCompleteListener,
 548  * {@link #setOnCompletionListener(OnCompletionListener)}setOnCompletionListener,
 549  * {@link #setOnBufferingUpdateListener(OnBufferingUpdateListener)}setOnBufferingUpdateListener,
 550  * {@link #setOnInfoListener(OnInfoListener)}setOnInfoListener,
 551  * {@link #setOnErrorListener(OnErrorListener)}setOnErrorListener, etc).
 552  * In order to receive the respective callback
 553  * associated with these listeners, applications are required to create
 554  * MediaPlayer objects on a thread with its own Looper running (main UI
 555  * thread by default has a Looper running).
 556  *
 557  */
 558 public class MediaPlayer extends PlayerBase
 559                          implements SubtitleController.Listener
 560 {
 561     /**
 562        Constant to retrieve only the new metadata since the last
 563        call.
 564        // FIXME: unhide.
 565        // FIXME: add link to getMetadata(boolean, boolean)
 566        {@hide}
 567      */
 568     public static final boolean METADATA_UPDATE_ONLY = true;
 569
 570     /**
 571        Constant to retrieve all the metadata.
 572        // FIXME: unhide.
 573        // FIXME: add link to getMetadata(boolean, boolean)
 574        {@hide}
 575      */
 576     public static final boolean METADATA_ALL = false;
 577
 578     /**
 579        Constant to enable the metadata filter during retrieval.
 580        // FIXME: unhide.
 581        // FIXME: add link to getMetadata(boolean, boolean)
 582        {@hide}
 583      */
 584     public static final boolean APPLY_METADATA_FILTER = true;
 585
 586     /**
 587        Constant to disable the metadata filter during retrieval.
 588        // FIXME: unhide.
 589        // FIXME: add link to getMetadata(boolean, boolean)
 590        {@hide}
 591      */
 592     public static final boolean BYPASS_METADATA_FILTER = false;
 593
 594     static {
 595         System.loadLibrary("media_jni");
 596         native_init();
 597     }
 598
 599     private final static String TAG = "MediaPlayer";
 600     // Name of the remote interface for the media player. Must be kept
 601     // in sync with the 2nd parameter of the IMPLEMENT_META_INTERFACE
 602     // macro invocation in IMediaPlayer.cpp
 603     private final static String IMEDIA_PLAYER = "android.media.IMediaPlayer";
 604
 605     private long mNativeContext; // accessed by native methods
 606     private long mNativeSurfaceTexture;  // accessed by native methods
 607     private int mListenerContext; // accessed by native methods
 608     private SurfaceHolder mSurfaceHolder;
 609     private EventHandler mEventHandler;
 610     private PowerManager.WakeLock mWakeLock = null;
 611     private boolean mScreenOnWhilePlaying;
 612     private boolean mStayAwake;
 613     private int mStreamType = AudioManager.USE_DEFAULT_STREAM_TYPE;
 614     private int mUsage = -1;
 615     private boolean mBypassInterruptionPolicy;
 616
 617     /**
 618      * Default constructor. Consider using one of the create() methods for
 619      * synchronously instantiating a MediaPlayer from a Uri or resource.
 620      * <p>When done with the MediaPlayer, you should call  {@link #release()},
 621      * to free the resources. If not released, too many MediaPlayer instances may
 622      * result in an exception.</p>
 623      */
 624     public MediaPlayer() {
 625         super(new AudioAttributes.Builder().build());
 626
 627         Looper looper;
 628         if ((looper = Looper.myLooper()) != null) {
 629             mEventHandler = new EventHandler(this, looper);
 630         } else if ((looper = Looper.getMainLooper()) != null) {
 631             mEventHandler = new EventHandler(this, looper);
 632         } else {
 633             mEventHandler = null;
 634         }
 635
 636         mTimeProvider = new TimeProvider(this);
 637         mOpenSubtitleSources = new Vector<InputStream>();
 638
 639         /* Native setup requires a weak reference to our object.
 640          * It's easier to create it here than in C++.
 641          */
 642         native_setup(new WeakReference<MediaPlayer>(this));
 643     }
 644
 645     /*
 646      * Update the MediaPlayer SurfaceTexture.
 647      * Call after setting a new display surface.
 648      */
 649     private native void _setVideoSurface(Surface surface);
 650
 651     /* Do not change these values (starting with INVOKE_ID) without updating
 652      * their counterparts in include/media/mediaplayer.h!
 653      */
 654     private static final int INVOKE_ID_GET_TRACK_INFO = 1;
 655     private static final int INVOKE_ID_ADD_EXTERNAL_SOURCE = 2;
 656     private static final int INVOKE_ID_ADD_EXTERNAL_SOURCE_FD = 3;
 657     private static final int INVOKE_ID_SELECT_TRACK = 4;
 658     private static final int INVOKE_ID_DESELECT_TRACK = 5;
 659     private static final int INVOKE_ID_SET_VIDEO_SCALE_MODE = 6;
 660     private static final int INVOKE_ID_GET_SELECTED_TRACK = 7;
 661
 662     /**
 663      * Create a request parcel which can be routed to the native media
 664      * player using {@link #invoke(Parcel, Parcel)}. The Parcel
 665      * returned has the proper InterfaceToken set. The caller should
 666      * not overwrite that token, i.e it can only append data to the
 667      * Parcel.
 668      *
 669      * @return A parcel suitable to hold a request for the native
 670      * player.
 671      * {@hide}
 672      */
 673     public Parcel newRequest() {
 674         Parcel parcel = Parcel.obtain();
 675         parcel.writeInterfaceToken(IMEDIA_PLAYER);
 676         return parcel;
 677     }
 678
 679     /**
 680      * Invoke a generic method on the native player using opaque
 681      * parcels for the request and reply. Both payloads' format is a
 682      * convention between the java caller and the native player.
 683      * Must be called after setDataSource to make sure a native player
 684      * exists. On failure, a RuntimeException is thrown.
 685      *
 686      * @param request Parcel with the data for the extension. The
 687      * caller must use {@link #newRequest()} to get one.
 688      *
 689      * @param reply Output parcel with the data returned by the
 690      * native player.
 691      * {@hide}
 692      */
 693     public void invoke(Parcel request, Parcel reply) {
 694         int retcode = native_invoke(request, reply);
 695         reply.setDataPosition(0);
 696         if (retcode != 0) {
 697             throw new RuntimeException("failure code: " + retcode);
 698         }
 699     }
 700
 701     /**
 702      * Sets the {@link SurfaceHolder} to use for displaying the video
 703      * portion of the media.
 704      *
 705      * Either a surface holder or surface must be set if a display or video sink
 706      * is needed.  Not calling this method or {@link #setSurface(Surface)}
 707      * when playing back a video will result in only the audio track being played.
 708      * A null surface holder or surface will result in only the audio track being
 709      * played.
 710      *
 711      * @param sh the SurfaceHolder to use for video display
 712      * @throws IllegalStateException if the internal player engine has not been
 713      * initialized or has been released.
 714      */
 715     public void setDisplay(SurfaceHolder sh) {
 716         mSurfaceHolder = sh;
 717         Surface surface;
 718         if (sh != null) {
 719             surface = sh.getSurface();
 720         } else {
 721             surface = null;
 722         }
 723         _setVideoSurface(surface);
 724         updateSurfaceScreenOn();
 725     }
 726
 727     /**
 728      * Sets the {@link Surface} to be used as the sink for the video portion of
 729      * the media. This is similar to {@link #setDisplay(SurfaceHolder)}, but
 730      * does not support {@link #setScreenOnWhilePlaying(boolean)}.  Setting a
 731      * Surface will un-set any Surface or SurfaceHolder that was previously set.
 732      * A null surface will result in only the audio track being played.
 733      *
 734      * If the Surface sends frames to a {@link SurfaceTexture}, the timestamps
 735      * returned from {@link SurfaceTexture#getTimestamp()} will have an
 736      * unspecified zero point.  These timestamps cannot be directly compared
 737      * between different media sources, different instances of the same media
 738      * source, or multiple runs of the same program.  The timestamp is normally
 739      * monotonically increasing and is unaffected by time-of-day adjustments,
 740      * but it is reset when the position is set.
 741      *
 742      * @param surface The {@link Surface} to be used for the video portion of
 743      * the media.
 744      * @throws IllegalStateException if the internal player engine has not been
 745      * initialized or has been released.
 746      */
 747     public void setSurface(Surface surface) {
 748         if (mScreenOnWhilePlaying && surface != null) {
 749             Log.w(TAG, "setScreenOnWhilePlaying(true) is ineffective for Surface");
 750         }
 751         mSurfaceHolder = null;
 752         _setVideoSurface(surface);
 753         updateSurfaceScreenOn();
 754     }
 755
 756     /* Do not change these video scaling mode values below without updating
 757      * their counterparts in system/window.h! Please do not forget to update
 758      * {@link #isVideoScalingModeSupported} when new video scaling modes
 759      * are added.
 760      */
 761     /**
 762      * Specifies a video scaling mode. The content is stretched to the
 763      * surface rendering area. When the surface has the same aspect ratio
 764      * as the content, the aspect ratio of the content is maintained;
 765      * otherwise, the aspect ratio of the content is not maintained when video
 766      * is being rendered. Unlike {@link #VIDEO_SCALING_MODE_SCALE_TO_FIT_WITH_CROPPING},
 767      * there is no content cropping with this video scaling mode.
 768      */
 769     public static final int VIDEO_SCALING_MODE_SCALE_TO_FIT = 1;
 770
 771     /**
 772      * Specifies a video scaling mode. The content is scaled, maintaining
 773      * its aspect ratio. The whole surface area is always used. When the
 774      * aspect ratio of the content is the same as the surface, no content
 775      * is cropped; otherwise, content is cropped to fit the surface.
 776      */
 777     public static final int VIDEO_SCALING_MODE_SCALE_TO_FIT_WITH_CROPPING = 2;
 778     /**
 779      * Sets video scaling mode. To make the target video scaling mode
 780      * effective during playback, this method must be called after
 781      * data source is set. If not called, the default video
 782      * scaling mode is {@link #VIDEO_SCALING_MODE_SCALE_TO_FIT}.
 783      *
 784      * <p> The supported video scaling modes are:
 785      * <ul>
 786      * <li> {@link #VIDEO_SCALING_MODE_SCALE_TO_FIT}
 787      * <li> {@link #VIDEO_SCALING_MODE_SCALE_TO_FIT_WITH_CROPPING}
 788      * </ul>
 789      *
 790      * @param mode target video scaling mode. Must be one of the supported
 791      * video scaling modes; otherwise, IllegalArgumentException will be thrown.
 792      *
 793      * @see MediaPlayer#VIDEO_SCALING_MODE_SCALE_TO_FIT
 794      * @see MediaPlayer#VIDEO_SCALING_MODE_SCALE_TO_FIT_WITH_CROPPING
 795      */
 796     public void setVideoScalingMode(int mode) {
 797         if (!isVideoScalingModeSupported(mode)) {
 798             final String msg = "Scaling mode " + mode + " is not supported";
 799             throw new IllegalArgumentException(msg);
 800         }
 801         Parcel request = Parcel.obtain();
 802         Parcel reply = Parcel.obtain();
 803         try {
 804             request.writeInterfaceToken(IMEDIA_PLAYER);
 805             request.writeInt(INVOKE_ID_SET_VIDEO_SCALE_MODE);
 806             request.writeInt(mode);
 807             invoke(request, reply);
 808         } finally {
 809             request.recycle();
 810             reply.recycle();
 811         }
 812     }
 813
 814     /**
 815      * Convenience method to create a MediaPlayer for a given Uri.
 816      * On success, {@link #prepare()} will already have been called and must not be called again.
 817      * <p>When done with the MediaPlayer, you should call  {@link #release()},
 818      * to free the resources. If not released, too many MediaPlayer instances will
 819      * result in an exception.</p>
 820      * <p>Note that since {@link #prepare()} is called automatically in this method,
 821      * you cannot change the audio stream type (see {@link #setAudioStreamType(int)}), audio
 822      * session ID (see {@link #setAudioSessionId(int)}) or audio attributes
 823      * (see {@link #setAudioAttributes(AudioAttributes)} of the new MediaPlayer.</p>
 824      *
 825      * @param context the Context to use
 826      * @param uri the Uri from which to get the datasource
 827      * @return a MediaPlayer object, or null if creation failed
 828      */
 829     public static MediaPlayer create(Context context, Uri uri) {
 830         return create (context, uri, null);
 831     }
 832
 833     /**
 834      * Convenience method to create a MediaPlayer for a given Uri.
 835      * On success, {@link #prepare()} will already have been called and must not be called again.
 836      * <p>When done with the MediaPlayer, you should call  {@link #release()},
 837      * to free the resources. If not released, too many MediaPlayer instances will
 838      * result in an exception.</p>
 839      * <p>Note that since {@link #prepare()} is called automatically in this method,
 840      * you cannot change the audio stream type (see {@link #setAudioStreamType(int)}), audio
 841      * session ID (see {@link #setAudioSessionId(int)}) or audio attributes
 842      * (see {@link #setAudioAttributes(AudioAttributes)} of the new MediaPlayer.</p>
 843      *
 844      * @param context the Context to use
 845      * @param uri the Uri from which to get the datasource
 846      * @param holder the SurfaceHolder to use for displaying the video
 847      * @return a MediaPlayer object, or null if creation failed
 848      */
 849     public static MediaPlayer create(Context context, Uri uri, SurfaceHolder holder) {
 850         int s = AudioSystem.newAudioSessionId();
 851         return create(context, uri, holder, null, s > 0 ? s : 0);
 852     }
 853
 854     /**
 855      * Same factory method as {@link #create(Context, Uri, SurfaceHolder)} but that lets you specify
 856      * the audio attributes and session ID to be used by the new MediaPlayer instance.
 857      * @param context the Context to use
 858      * @param uri the Uri from which to get the datasource
 859      * @param holder the SurfaceHolder to use for displaying the video, may be null.
 860      * @param audioAttributes the {@link AudioAttributes} to be used by the media player.
 861      * @param audioSessionId the audio session ID to be used by the media player,
 862      *     see {@link AudioManager#generateAudioSessionId()} to obtain a new session.
 863      * @return a MediaPlayer object, or null if creation failed
 864      */
 865     public static MediaPlayer create(Context context, Uri uri, SurfaceHolder holder,
 866             AudioAttributes audioAttributes, int audioSessionId) {
 867
 868         try {
 869             MediaPlayer mp = new MediaPlayer();
 870             final AudioAttributes aa = audioAttributes != null ? audioAttributes :
 871                 new AudioAttributes.Builder().build();
 872             mp.setAudioAttributes(aa);
 873             mp.setAudioSessionId(audioSessionId);
 874             mp.setDataSource(context, uri);
 875             if (holder != null) {
 876                 mp.setDisplay(holder);
 877             }
 878             mp.prepare();
 879             return mp;
 880         } catch (IOException ex) {
 881             Log.d(TAG, "create failed:", ex);
 882             // fall through
 883         } catch (IllegalArgumentException ex) {
 884             Log.d(TAG, "create failed:", ex);
 885             // fall through
 886         } catch (SecurityException ex) {
 887             Log.d(TAG, "create failed:", ex);
 888             // fall through
 889         }
 890
 891         return null;
 892     }
 893
 894     // Note no convenience method to create a MediaPlayer with SurfaceTexture sink.
 895
 896     /**
 897      * Convenience method to create a MediaPlayer for a given resource id.
 898      * On success, {@link #prepare()} will already have been called and must not be called again.
 899      * <p>When done with the MediaPlayer, you should call  {@link #release()},
 900      * to free the resources. If not released, too many MediaPlayer instances will
 901      * result in an exception.</p>
 902      * <p>Note that since {@link #prepare()} is called automatically in this method,
 903      * you cannot change the audio stream type (see {@link #setAudioStreamType(int)}), audio
 904      * session ID (see {@link #setAudioSessionId(int)}) or audio attributes
 905      * (see {@link #setAudioAttributes(AudioAttributes)} of the new MediaPlayer.</p>
 906      *
 907      * @param context the Context to use
 908      * @param resid the raw resource id (<var>R.raw.&lt;something></var>) for
 909      *              the resource to use as the datasource
 910      * @return a MediaPlayer object, or null if creation failed
 911      */
 912     public static MediaPlayer create(Context context, int resid) {
 913         int s = AudioSystem.newAudioSessionId();
 914         return create(context, resid, null, s > 0 ? s : 0);
 915     }
 916
 917     /**
 918      * Same factory method as {@link #create(Context, int)} but that lets you specify the audio
 919      * attributes and session ID to be used by the new MediaPlayer instance.
 920      * @param context the Context to use
 921      * @param resid the raw resource id (<var>R.raw.&lt;something></var>) for
 922      *              the resource to use as the datasource
 923      * @param audioAttributes the {@link AudioAttributes} to be used by the media player.
 924      * @param audioSessionId the audio session ID to be used by the media player,
 925      *     see {@link AudioManager#generateAudioSessionId()} to obtain a new session.
 926      * @return a MediaPlayer object, or null if creation failed
 927      */
 928     public static MediaPlayer create(Context context, int resid,
 929             AudioAttributes audioAttributes, int audioSessionId) {
 930         try {
 931             AssetFileDescriptor afd = context.getResources().openRawResourceFd(resid);
 932             if (afd == null) return null;
 933
 934             MediaPlayer mp = new MediaPlayer();
 935
 936             final AudioAttributes aa = audioAttributes != null ? audioAttributes :
 937                 new AudioAttributes.Builder().build();
 938             mp.setAudioAttributes(aa);
 939             mp.setAudioSessionId(audioSessionId);
 940
 941             mp.setDataSource(afd.getFileDescriptor(), afd.getStartOffset(), afd.getLength());
 942             afd.close();
 943             mp.prepare();
 944             return mp;
 945         } catch (IOException ex) {
 946             Log.d(TAG, "create failed:", ex);
 947             // fall through
 948         } catch (IllegalArgumentException ex) {
 949             Log.d(TAG, "create failed:", ex);
 950            // fall through
 951         } catch (SecurityException ex) {
 952             Log.d(TAG, "create failed:", ex);
 953             // fall through
 954         }
 955         return null;
 956     }
 957
 958     /**
 959      * Sets the data source as a content Uri.
 960      *
 961      * @param context the Context to use when resolving the Uri
 962      * @param uri the Content URI of the data you want to play
 963      * @throws IllegalStateException if it is called in an invalid state
 964      */
 965     public void setDataSource(@NonNull Context context, @NonNull Uri uri)
 966             throws IOException, IllegalArgumentException, SecurityException, IllegalStateException {
 967         setDataSource(context, uri, null);
 968     }
 969
 970     /**
 971      * Sets the data source as a content Uri.
 972      *
 973      * @param context the Context to use when resolving the Uri
 974      * @param uri the Content URI of the data you want to play
 975      * @param headers the headers to be sent together with the request for the data
 976      *                Note that the cross domain redirection is allowed by default, but that can be
 977      *                changed with key/value pairs through the headers parameter with
 978      *                "android-allow-cross-domain-redirect" as the key and "0" or "1" as the value
 979      *                to disallow or allow cross domain redirection.
 980      * @throws IllegalStateException if it is called in an invalid state
 981      */
 982     public void setDataSource(@NonNull Context context, @NonNull Uri uri,
 983             @Nullable Map<String, String> headers) throws IOException, IllegalArgumentException,
 984                     SecurityException, IllegalStateException {
 985         final ContentResolver resolver = context.getContentResolver();
 986         final String scheme = uri.getScheme();
 987         if (ContentResolver.SCHEME_FILE.equals(scheme)) {
 988             setDataSource(uri.getPath());
 989             return;
 990         } else if (ContentResolver.SCHEME_CONTENT.equals(scheme)
 991                 && Settings.AUTHORITY.equals(uri.getAuthority())) {
 992             // Try cached ringtone first since the actual provider may not be
 993             // encryption aware, or it may be stored on CE media storage
 994             final int type = RingtoneManager.getDefaultType(uri);
 995             final Uri cacheUri = RingtoneManager.getCacheForType(type);
 996             final Uri actualUri = RingtoneManager.getActualDefaultRingtoneUri(context, type);
 997             if (attemptDataSource(resolver, cacheUri)) {
 998                 return;
 999             } else if (attemptDataSource(resolver, actualUri)) {
1000                 return;
1001             } else {
1002                 setDataSource(uri.toString(), headers);
1003             }
1004         } else {
1005             // Try requested Uri locally first, or fallback to media server
1006             if (attemptDataSource(resolver, uri)) {
1007                 return;
1008             } else {
1009                 setDataSource(uri.toString(), headers);
1010             }
1011         }
1012     }
1013
1014     private boolean attemptDataSource(ContentResolver resolver, Uri uri) {
1015         try (AssetFileDescriptor afd = resolver.openAssetFileDescriptor(uri, "r")) {
1016             setDataSource(afd);
1017             return true;
1018         } catch (NullPointerException | SecurityException | IOException ex) {
1019             Log.w(TAG, "Couldn't open " + uri + ": " + ex);
1020             return false;
1021         }
1022     }
1023
1024     /**
1025      * Sets the data source (file-path or http/rtsp URL) to use.
1026      *
1027      * @param path the path of the file, or the http/rtsp URL of the stream you want to play
1028      * @throws IllegalStateException if it is called in an invalid state
1029      *
1030      * <p>When <code>path</code> refers to a local file, the file may actually be opened by a
1031      * process other than the calling application.  This implies that the pathname
1032      * should be an absolute path (as any other process runs with unspecified current working
1033      * directory), and that the pathname should reference a world-readable file.
1034      * As an alternative, the application could first open the file for reading,
1035      * and then use the file descriptor form {@link #setDataSource(FileDescriptor)}.
1036      */
1037     public void setDataSource(String path)
1038             throws IOException, IllegalArgumentException, SecurityException, IllegalStateException {
1039         setDataSource(path, null, null);
1040     }
1041
1042     /**
1043      * Sets the data source (file-path or http/rtsp URL) to use.
1044      *
1045      * @param path the path of the file, or the http/rtsp URL of the stream you want to play
1046      * @param headers the headers associated with the http request for the stream you want to play
1047      * @throws IllegalStateException if it is called in an invalid state
1048      * @hide pending API council
1049      */
1050     public void setDataSource(String path, Map<String, String> headers)
1051             throws IOException, IllegalArgumentException, SecurityException, IllegalStateException
1052     {
1053         String[] keys = null;
1054         String[] values = null;
1055
1056         if (headers != null) {
1057             keys = new String[headers.size()];
1058             values = new String[headers.size()];
1059
1060             int i = 0;
1061             for (Map.Entry<String, String> entry: headers.entrySet()) {
1062                 keys[i] = entry.getKey();
1063                 values[i] = entry.getValue();
1064                 ++i;
1065             }
1066         }
1067         setDataSource(path, keys, values);
1068     }
1069
1070     private void setDataSource(String path, String[] keys, String[] values)
1071             throws IOException, IllegalArgumentException, SecurityException, IllegalStateException {
1072         final Uri uri = Uri.parse(path);
1073         final String scheme = uri.getScheme();
1074         if ("file".equals(scheme)) {
1075             path = uri.getPath();
1076         } else if (scheme != null) {
1077             // handle non-file sources
1078             nativeSetDataSource(
1079                 MediaHTTPService.createHttpServiceBinderIfNecessary(path),
1080                 path,
1081                 keys,
1082                 values);
1083             return;
1084         }
1085
1086         final File file = new File(path);
1087         if (file.exists()) {
1088             FileInputStream is = new FileInputStream(file);
1089             FileDescriptor fd = is.getFD();
1090             setDataSource(fd);
1091             is.close();
1092         } else {
1093             throw new IOException("setDataSource failed.");
1094         }
1095     }
1096
1097     private native void nativeSetDataSource(
1098         IBinder httpServiceBinder, String path, String[] keys, String[] values)
1099         throws IOException, IllegalArgumentException, SecurityException, IllegalStateException;
1100
1101     /**
1102      * Sets the data source (AssetFileDescriptor) to use. It is the caller's
1103      * responsibility to close the file descriptor. It is safe to do so as soon
1104      * as this call returns.
1105      *
1106      * @param afd the AssetFileDescriptor for the file you want to play
1107      * @throws IllegalStateException if it is called in an invalid state
1108      * @throws IllegalArgumentException if afd is not a valid AssetFileDescriptor
1109      * @throws IOException if afd can not be read
1110      */
1111     public void setDataSource(@NonNull AssetFileDescriptor afd)
1112             throws IOException, IllegalArgumentException, IllegalStateException {
1113         Preconditions.checkNotNull(afd);
1114         // Note: using getDeclaredLength so that our behavior is the same
1115         // as previous versions when the content provider is returning
1116         // a full file.
1117         if (afd.getDeclaredLength() < 0) {
1118             setDataSource(afd.getFileDescriptor());
1119         } else {
1120             setDataSource(afd.getFileDescriptor(), afd.getStartOffset(), afd.getDeclaredLength());
1121         }
1122     }
1123
1124     /**
1125      * Sets the data source (FileDescriptor) to use. It is the caller's responsibility
1126      * to close the file descriptor. It is safe to do so as soon as this call returns.
1127      *
1128      * @param fd the FileDescriptor for the file you want to play
1129      * @throws IllegalStateException if it is called in an invalid state
1130      * @throws IllegalArgumentException if fd is not a valid FileDescriptor
1131      * @throws IOException if fd can not be read
1132      */
1133     public void setDataSource(FileDescriptor fd)
1134             throws IOException, IllegalArgumentException, IllegalStateException {
1135         // intentionally less than LONG_MAX
1136         setDataSource(fd, 0, 0x7ffffffffffffffL);
1137     }
1138
1139     /**
1140      * Sets the data source (FileDescriptor) to use.  The FileDescriptor must be
1141      * seekable (N.B. a LocalSocket is not seekable). It is the caller's responsibility
1142      * to close the file descriptor. It is safe to do so as soon as this call returns.
1143      *
1144      * @param fd the FileDescriptor for the file you want to play
1145      * @param offset the offset into the file where the data to be played starts, in bytes
1146      * @param length the length in bytes of the data to be played
1147      * @throws IllegalStateException if it is called in an invalid state
1148      * @throws IllegalArgumentException if fd is not a valid FileDescriptor
1149      * @throws IOException if fd can not be read
1150      */
1151     public void setDataSource(FileDescriptor fd, long offset, long length)
1152             throws IOException, IllegalArgumentException, IllegalStateException {
1153         _setDataSource(fd, offset, length);
1154     }
1155
1156     private native void _setDataSource(FileDescriptor fd, long offset, long length)
1157             throws IOException, IllegalArgumentException, IllegalStateException;
1158
1159     /**
1160      * Sets the data source (MediaDataSource) to use.
1161      *
1162      * @param dataSource the MediaDataSource for the media you want to play
1163      * @throws IllegalStateException if it is called in an invalid state
1164      * @throws IllegalArgumentException if dataSource is not a valid MediaDataSource
1165      */
1166     public void setDataSource(MediaDataSource dataSource)
1167             throws IllegalArgumentException, IllegalStateException {
1168         _setDataSource(dataSource);
1169     }
1170
1171     private native void _setDataSource(MediaDataSource dataSource)
1172           throws IllegalArgumentException, IllegalStateException;
1173
1174     /**
1175      * Prepares the player for playback, synchronously.
1176      *
1177      * After setting the datasource and the display surface, you need to either
1178      * call prepare() or prepareAsync(). For files, it is OK to call prepare(),
1179      * which blocks until MediaPlayer is ready for playback.
1180      *
1181      * @throws IllegalStateException if it is called in an invalid state
1182      */
1183     public void prepare() throws IOException, IllegalStateException {
1184         _prepare();
1185         scanInternalSubtitleTracks();
1186     }
1187
1188     private native void _prepare() throws IOException, IllegalStateException;
1189
1190     /**
1191      * Prepares the player for playback, asynchronously.
1192      *
1193      * After setting the datasource and the display surface, you need to either
1194      * call prepare() or prepareAsync(). For streams, you should call prepareAsync(),
1195      * which returns immediately, rather than blocking until enough data has been
1196      * buffered.
1197      *
1198      * @throws IllegalStateException if it is called in an invalid state
1199      */
1200     public native void prepareAsync() throws IllegalStateException;
1201
1202     /**
1203      * Starts or resumes playback. If playback had previously been paused,
1204      * playback will continue from where it was paused. If playback had
1205      * been stopped, or never started before, playback will start at the
1206      * beginning.
1207      *
1208      * @throws IllegalStateException if it is called in an invalid state
1209      */
1210     public void start() throws IllegalStateException {
1211         baseStart();
1212         stayAwake(true);
1213         _start();
1214     }
1215
1216     private native void _start() throws IllegalStateException;
1217
1218
1219     private int getAudioStreamType() {
1220         if (mStreamType == AudioManager.USE_DEFAULT_STREAM_TYPE) {
1221             mStreamType = _getAudioStreamType();
1222         }
1223         return mStreamType;
1224     }
1225
1226     private native int _getAudioStreamType() throws IllegalStateException;
1227
1228     /**
1229      * Stops playback after playback has been stopped or paused.
1230      *
1231      * @throws IllegalStateException if the internal player engine has not been
1232      * initialized.
1233      */
1234     public void stop() throws IllegalStateException {
1235         stayAwake(false);
1236         _stop();
1237     }
1238
1239     private native void _stop() throws IllegalStateException;
1240
1241     /**
1242      * Pauses playback. Call start() to resume.
1243      *
1244      * @throws IllegalStateException if the internal player engine has not been
1245      * initialized.
1246      */
1247     public void pause() throws IllegalStateException {
1248         stayAwake(false);
1249         _pause();
1250     }
1251
1252     private native void _pause() throws IllegalStateException;
1253
1254     /**
1255      * Set the low-level power management behavior for this MediaPlayer.  This
1256      * can be used when the MediaPlayer is not playing through a SurfaceHolder
1257      * set with {@link #setDisplay(SurfaceHolder)} and thus can use the
1258      * high-level {@link #setScreenOnWhilePlaying(boolean)} feature.
1259      *
1260      * <p>This function has the MediaPlayer access the low-level power manager
1261      * service to control the device's power usage while playing is occurring.
1262      * The parameter is a combination of {@link android.os.PowerManager} wake flags.
1263      * Use of this method requires {@link android.Manifest.permission#WAKE_LOCK}
1264      * permission.
1265      * By default, no attempt is made to keep the device awake during playback.
1266      *
1267      * @param context the Context to use
1268      * @param mode    the power/wake mode to set
1269      * @see android.os.PowerManager
1270      */
1271     public void setWakeMode(Context context, int mode) {
1272         boolean washeld = false;
1273
1274         /* Disable persistant wakelocks in media player based on property */
1275         if (SystemProperties.getBoolean("audio.offload.ignore_setawake", false) == true) {
1276             Log.w(TAG, "IGNORING setWakeMode " + mode);
1277             return;
1278         }
1279
1280         if (mWakeLock != null) {
1281             if (mWakeLock.isHeld()) {
1282                 washeld = true;
1283                 mWakeLock.release();
1284             }
1285             mWakeLock = null;
1286         }
1287
1288         PowerManager pm = (PowerManager)context.getSystemService(Context.POWER_SERVICE);
1289         mWakeLock = pm.newWakeLock(mode|PowerManager.ON_AFTER_RELEASE, MediaPlayer.class.getName());
1290         mWakeLock.setReferenceCounted(false);
1291         if (washeld) {
1292             mWakeLock.acquire();
1293         }
1294     }
1295
1296     /**
1297      * Control whether we should use the attached SurfaceHolder to keep the
1298      * screen on while video playback is occurring.  This is the preferred
1299      * method over {@link #setWakeMode} where possible, since it doesn't
1300      * require that the application have permission for low-level wake lock
1301      * access.
1302      *
1303      * @param screenOn Supply true to keep the screen on, false to allow it
1304      * to turn off.
1305      */
1306     public void setScreenOnWhilePlaying(boolean screenOn) {
1307         if (mScreenOnWhilePlaying != screenOn) {
1308             if (screenOn && mSurfaceHolder == null) {
1309                 Log.w(TAG, "setScreenOnWhilePlaying(true) is ineffective without a SurfaceHolder");
1310             }
1311             mScreenOnWhilePlaying = screenOn;
1312             updateSurfaceScreenOn();
1313         }
1314     }
1315
1316     private void stayAwake(boolean awake) {
1317         if (mWakeLock != null) {
1318             if (awake && !mWakeLock.isHeld()) {
1319                 mWakeLock.acquire();
1320             } else if (!awake && mWakeLock.isHeld()) {
1321                 mWakeLock.release();
1322             }
1323         }
1324         mStayAwake = awake;
1325         updateSurfaceScreenOn();
1326     }
1327
1328     private void updateSurfaceScreenOn() {
1329         if (mSurfaceHolder != null) {
1330             mSurfaceHolder.setKeepScreenOn(mScreenOnWhilePlaying && mStayAwake);
1331         }
1332     }
1333
1334     /**
1335      * Returns the width of the video.
1336      *
1337      * @return the width of the video, or 0 if there is no video,
1338      * no display surface was set, or the width has not been determined
1339      * yet. The OnVideoSizeChangedListener can be registered via
1340      * {@link #setOnVideoSizeChangedListener(OnVideoSizeChangedListener)}
1341      * to provide a notification when the width is available.
1342      */
1343     public native int getVideoWidth();
1344
1345     /**
1346      * Returns the height of the video.
1347      *
1348      * @return the height of the video, or 0 if there is no video,
1349      * no display surface was set, or the height has not been determined
1350      * yet. The OnVideoSizeChangedListener can be registered via
1351      * {@link #setOnVideoSizeChangedListener(OnVideoSizeChangedListener)}
1352      * to provide a notification when the height is available.
1353      */
1354     public native int getVideoHeight();
1355
1356     /**
1357      * Checks whether the MediaPlayer is playing.
1358      *
1359      * @return true if currently playing, false otherwise
1360      * @throws IllegalStateException if the internal player engine has not been
1361      * initialized or has been released.
1362      */
1363     public native boolean isPlaying();
1364
1365     /**
1366      * Change playback speed of audio by resampling the audio.
1367      * <p>
1368      * Specifies resampling as audio mode for variable rate playback, i.e.,
1369      * resample the waveform based on the requested playback rate to get
1370      * a new waveform, and play back the new waveform at the original sampling
1371      * frequency.
1372      * When rate is larger than 1.0, pitch becomes higher.
1373      * When rate is smaller than 1.0, pitch becomes lower.
1374      *
1375      * @hide
1376      */
1377     public static final int PLAYBACK_RATE_AUDIO_MODE_RESAMPLE = 2;
1378
1379     /**
1380      * Change playback speed of audio without changing its pitch.
1381      * <p>
1382      * Specifies time stretching as audio mode for variable rate playback.
1383      * Time stretching changes the duration of the audio samples without
1384      * affecting its pitch.
1385      * <p>
1386      * This mode is only supported for a limited range of playback speed factors,
1387      * e.g. between 1/2x and 2x.
1388      *
1389      * @hide
1390      */
1391     public static final int PLAYBACK_RATE_AUDIO_MODE_STRETCH = 1;
1392
1393     /**
1394      * Change playback speed of audio without changing its pitch, and
1395      * possibly mute audio if time stretching is not supported for the playback
1396      * speed.
1397      * <p>
1398      * Try to keep audio pitch when changing the playback rate, but allow the
1399      * system to determine how to change audio playback if the rate is out
1400      * of range.
1401      *
1402      * @hide
1403      */
1404     public static final int PLAYBACK_RATE_AUDIO_MODE_DEFAULT = 0;
1405
1406     /** @hide */
1407     @IntDef(
1408         value = {
1409             PLAYBACK_RATE_AUDIO_MODE_DEFAULT,
1410             PLAYBACK_RATE_AUDIO_MODE_STRETCH,
1411             PLAYBACK_RATE_AUDIO_MODE_RESAMPLE,
1412     })
1413     @Retention(RetentionPolicy.SOURCE)
1414     public @interface PlaybackRateAudioMode {}
1415
1416     /**
1417      * Sets playback rate and audio mode.
1418      *
1419      * @param rate the ratio between desired playback rate and normal one.
1420      * @param audioMode audio playback mode. Must be one of the supported
1421      * audio modes.
1422      *
1423      * @throws IllegalStateException if the internal player engine has not been
1424      * initialized.
1425      * @throws IllegalArgumentException if audioMode is not supported.
1426      *
1427      * @hide
1428      */
1429     @NonNull
1430     public PlaybackParams easyPlaybackParams(float rate, @PlaybackRateAudioMode int audioMode) {
1431         PlaybackParams params = new PlaybackParams();
1432         params.allowDefaults();
1433         switch (audioMode) {
1434         case PLAYBACK_RATE_AUDIO_MODE_DEFAULT:
1435             params.setSpeed(rate).setPitch(1.0f);
1436             break;
1437         case PLAYBACK_RATE_AUDIO_MODE_STRETCH:
1438             params.setSpeed(rate).setPitch(1.0f)
1439                     .setAudioFallbackMode(params.AUDIO_FALLBACK_MODE_FAIL);
1440             break;
1441         case PLAYBACK_RATE_AUDIO_MODE_RESAMPLE:
1442             params.setSpeed(rate).setPitch(rate);
1443             break;
1444         default:
1445             final String msg = "Audio playback mode " + audioMode + " is not supported";
1446             throw new IllegalArgumentException(msg);
1447         }
1448         return params;
1449     }
1450
1451     /**
1452      * Sets playback rate using {@link PlaybackParams}. The object sets its internal
1453      * PlaybackParams to the input, except that the object remembers previous speed
1454      * when input speed is zero. This allows the object to resume at previous speed
1455      * when start() is called. Calling it before the object is prepared does not change
1456      * the object state. After the object is prepared, calling it with zero speed is
1457      * equivalent to calling pause(). After the object is prepared, calling it with
1458      * non-zero speed is equivalent to calling start().
1459      *
1460      * @param params the playback params.
1461      *
1462      * @throws IllegalStateException if the internal player engine has not been
1463      * initialized or has been released.
1464      * @throws IllegalArgumentException if params is not supported.
1465      */
1466     public native void setPlaybackParams(@NonNull PlaybackParams params);
1467
1468     /**
1469      * Gets the playback params, containing the current playback rate.
1470      *
1471      * @return the playback params.
1472      * @throws IllegalStateException if the internal player engine has not been
1473      * initialized.
1474      */
1475     @NonNull
1476     public native PlaybackParams getPlaybackParams();
1477
1478     /**
1479      * Sets A/V sync mode.
1480      *
1481      * @param params the A/V sync params to apply
1482      *
1483      * @throws IllegalStateException if the internal player engine has not been
1484      * initialized.
1485      * @throws IllegalArgumentException if params are not supported.
1486      */
1487     public native void setSyncParams(@NonNull SyncParams params);
1488
1489     /**
1490      * Gets the A/V sync mode.
1491      *
1492      * @return the A/V sync params
1493      *
1494      * @throws IllegalStateException if the internal player engine has not been
1495      * initialized.
1496      */
1497     @NonNull
1498     public native SyncParams getSyncParams();
1499
1500     /**
1501      * Seeks to specified time position.
1502      *
1503      * @param msec the offset in milliseconds from the start to seek to
1504      * @throws IllegalStateException if the internal player engine has not been
1505      * initialized
1506      */
1507     public native void seekTo(int msec) throws IllegalStateException;
1508
1509     /**
1510      * Get current playback position as a {@link MediaTimestamp}.
1511      * <p>
1512      * The MediaTimestamp represents how the media time correlates to the system time in
1513      * a linear fashion using an anchor and a clock rate. During regular playback, the media
1514      * time moves fairly constantly (though the anchor frame may be rebased to a current
1515      * system time, the linear correlation stays steady). Therefore, this method does not
1516      * need to be called often.
1517      * <p>
1518      * To help users get current playback position, this method always anchors the timestamp
1519      * to the current {@link System#nanoTime system time}, so
1520      * {@link MediaTimestamp#getAnchorMediaTimeUs} can be used as current playback position.
1521      *
1522      * @return a MediaTimestamp object if a timestamp is available, or {@code null} if no timestamp
1523      *         is available, e.g. because the media player has not been initialized.
1524      *
1525      * @see MediaTimestamp
1526      */
1527     @Nullable
1528     public MediaTimestamp getTimestamp()
1529     {
1530         try {
1531             // TODO: get the timestamp from native side
1532             return new MediaTimestamp(
1533                     getCurrentPosition() * 1000L,
1534                     System.nanoTime(),
1535                     isPlaying() ? getPlaybackParams().getSpeed() : 0.f);
1536         } catch (IllegalStateException e) {
1537             return null;
1538         }
1539     }
1540
1541     /**
1542      * Gets the current playback position.
1543      *
1544      * @return the current position in milliseconds
1545      */
1546     public native int getCurrentPosition();
1547
1548     /**
1549      * Gets the duration of the file.
1550      *
1551      * @return the duration in milliseconds, if no duration is available
1552      *         (for example, if streaming live content), -1 is returned.
1553      */
1554     public native int getDuration();
1555
1556     /**
1557      * Gets the media metadata.
1558      *
1559      * @param update_only controls whether the full set of available
1560      * metadata is returned or just the set that changed since the
1561      * last call. See {@see #METADATA_UPDATE_ONLY} and {@see
1562      * #METADATA_ALL}.
1563      *
1564      * @param apply_filter if true only metadata that matches the
1565      * filter is returned. See {@see #APPLY_METADATA_FILTER} and {@see
1566      * #BYPASS_METADATA_FILTER}.
1567      *
1568      * @return The metadata, possibly empty. null if an error occured.
1569      // FIXME: unhide.
1570      * {@hide}
1571      */
1572     public Metadata getMetadata(final boolean update_only,
1573                                 final boolean apply_filter) {
1574         Parcel reply = Parcel.obtain();
1575         Metadata data = new Metadata();
1576
1577         if (!native_getMetadata(update_only, apply_filter, reply)) {
1578             reply.recycle();
1579             return null;
1580         }
1581
1582         // Metadata takes over the parcel, don't recycle it unless
1583         // there is an error.
1584         if (!data.parse(reply)) {
1585             reply.recycle();
1586             return null;
1587         }
1588         return data;
1589     }
1590
1591     /**
1592      * Set a filter for the metadata update notification and update
1593      * retrieval. The caller provides 2 set of metadata keys, allowed
1594      * and blocked. The blocked set always takes precedence over the
1595      * allowed one.
1596      * Metadata.MATCH_ALL and Metadata.MATCH_NONE are 2 sets available as
1597      * shorthands to allow/block all or no metadata.
1598      *
1599      * By default, there is no filter set.
1600      *
1601      * @param allow Is the set of metadata the client is interested
1602      *              in receiving new notifications for.
1603      * @param block Is the set of metadata the client is not interested
1604      *              in receiving new notifications for.
1605      * @return The call status code.
1606      *
1607      // FIXME: unhide.
1608      * {@hide}
1609      */
1610     public int setMetadataFilter(Set<Integer> allow, Set<Integer> block) {
1611         // Do our serialization manually instead of calling
1612         // Parcel.writeArray since the sets are made of the same type
1613         // we avoid paying the price of calling writeValue (used by
1614         // writeArray) which burns an extra int per element to encode
1615         // the type.
1616         Parcel request =  newRequest();
1617
1618         // The parcel starts already with an interface token. There
1619         // are 2 filters. Each one starts with a 4bytes number to
1620         // store the len followed by a number of int (4 bytes as well)
1621         // representing the metadata type.
1622         int capacity = request.dataSize() + 4 * (1 + allow.size() + 1 + block.size());
1623
1624         if (request.dataCapacity() < capacity) {
1625             request.setDataCapacity(capacity);
1626         }
1627
1628         request.writeInt(allow.size());
1629         for(Integer t: allow) {
1630             request.writeInt(t);
1631         }
1632         request.writeInt(block.size());
1633         for(Integer t: block) {
1634             request.writeInt(t);
1635         }
1636         return native_setMetadataFilter(request);
1637     }
1638
1639     /**
1640      * Set the MediaPlayer to start when this MediaPlayer finishes playback
1641      * (i.e. reaches the end of the stream).
1642      * The media framework will attempt to transition from this player to
1643      * the next as seamlessly as possible. The next player can be set at
1644      * any time before completion. The next player must be prepared by the
1645      * app, and the application should not call start() on it.
1646      * The next MediaPlayer must be different from 'this'. An exception
1647      * will be thrown if next == this.
1648      * The application may call setNextMediaPlayer(null) to indicate no
1649      * next player should be started at the end of playback.
1650      * If the current player is looping, it will keep looping and the next
1651      * player will not be started.
1652      *
1653      * @param next the player to start after this one completes playback.
1654      *
1655      */
1656     public native void setNextMediaPlayer(MediaPlayer next);
1657
1658     /**
1659      * Releases resources associated with this MediaPlayer object.
1660      * It is considered good practice to call this method when you're
1661      * done using the MediaPlayer. In particular, whenever an Activity
1662      * of an application is paused (its onPause() method is called),
1663      * or stopped (its onStop() method is called), this method should be
1664      * invoked to release the MediaPlayer object, unless the application
1665      * has a special need to keep the object around. In addition to
1666      * unnecessary resources (such as memory and instances of codecs)
1667      * being held, failure to call this method immediately if a
1668      * MediaPlayer object is no longer needed may also lead to
1669      * continuous battery consumption for mobile devices, and playback
1670      * failure for other applications if no multiple instances of the
1671      * same codec are supported on a device. Even if multiple instances
1672      * of the same codec are supported, some performance degradation
1673      * may be expected when unnecessary multiple instances are used
1674      * at the same time.
1675      */
1676     public void release() {
1677         baseRelease();
1678         stayAwake(false);
1679         updateSurfaceScreenOn();
1680         mOnPreparedListener = null;
1681         mOnBufferingUpdateListener = null;
1682         mOnCompletionListener = null;
1683         mOnSeekCompleteListener = null;
1684         mOnErrorListener = null;
1685         mOnInfoListener = null;
1686         mOnVideoSizeChangedListener = null;
1687         mOnTimedTextListener = null;
1688         if (mTimeProvider != null) {
1689             mTimeProvider.close();
1690             mTimeProvider = null;
1691         }
1692         mOnSubtitleDataListener = null;
1693         _release();
1694     }
1695
1696     private native void _release();
1697
1698     /**
1699      * Resets the MediaPlayer to its uninitialized state. After calling
1700      * this method, you will have to initialize it again by setting the
1701      * data source and calling prepare().
1702      */
1703     public void reset() {
1704         mSelectedSubtitleTrackIndex = -1;
1705         synchronized(mOpenSubtitleSources) {
1706             for (final InputStream is: mOpenSubtitleSources) {
1707                 try {
1708                     is.close();
1709                 } catch (IOException e) {
1710                 }
1711             }
1712             mOpenSubtitleSources.clear();
1713         }
1714         if (mSubtitleController != null) {
1715             mSubtitleController.reset();
1716         }
1717         if (mTimeProvider != null) {
1718             mTimeProvider.close();
1719             mTimeProvider = null;
1720         }
1721
1722         stayAwake(false);
1723         _reset();
1724         // make sure none of the listeners get called anymore
1725         if (mEventHandler != null) {
1726             mEventHandler.removeCallbacksAndMessages(null);
1727         }
1728
1729         synchronized (mIndexTrackPairs) {
1730             mIndexTrackPairs.clear();
1731             mInbandTrackIndices.clear();
1732         };
1733     }
1734
1735     private native void _reset();
1736
1737     /**
1738      * Sets the audio stream type for this MediaPlayer. See {@link AudioManager}
1739      * for a list of stream types. Must call this method before prepare() or
1740      * prepareAsync() in order for the target stream type to become effective
1741      * thereafter.
1742      *
1743      * @param streamtype the audio stream type
1744      * @see android.media.AudioManager
1745      */
1746     public void setAudioStreamType(int streamtype) {
1747         baseUpdateAudioAttributes(
1748                 new AudioAttributes.Builder().setInternalLegacyStreamType(streamtype).build());
1749         _setAudioStreamType(streamtype);
1750         mStreamType = streamtype;
1751     }
1752
1753     private native void _setAudioStreamType(int streamtype);
1754
1755     // Keep KEY_PARAMETER_* in sync with include/media/mediaplayer.h
1756     private final static int KEY_PARAMETER_AUDIO_ATTRIBUTES = 1400;
1757     /**
1758      * Sets the parameter indicated by key.
1759      * @param key key indicates the parameter to be set.
1760      * @param value value of the parameter to be set.
1761      * @return true if the parameter is set successfully, false otherwise
1762      * {@hide}
1763      */
1764     private native boolean setParameter(int key, Parcel value);
1765
1766     /**
1767      * Sets the audio attributes for this MediaPlayer.
1768      * See {@link AudioAttributes} for how to build and configure an instance of this class.
1769      * You must call this method before {@link #prepare()} or {@link #prepareAsync()} in order
1770      * for the audio attributes to become effective thereafter.
1771      * @param attributes a non-null set of audio attributes
1772      */
1773     public void setAudioAttributes(AudioAttributes attributes) throws IllegalArgumentException {
1774         if (attributes == null) {
1775             final String msg = "Cannot set AudioAttributes to null";
1776             throw new IllegalArgumentException(msg);
1777         }
1778         baseUpdateAudioAttributes(attributes);
1779         mUsage = attributes.getUsage();
1780         mBypassInterruptionPolicy = (attributes.getAllFlags()
1781                 & AudioAttributes.FLAG_BYPASS_INTERRUPTION_POLICY) != 0;
1782         Parcel pattributes = Parcel.obtain();
1783         attributes.writeToParcel(pattributes, AudioAttributes.FLATTEN_TAGS);
1784         setParameter(KEY_PARAMETER_AUDIO_ATTRIBUTES, pattributes);
1785         pattributes.recycle();
1786     }
1787
1788     /**
1789      * Sets the player to be looping or non-looping.
1790      *
1791      * @param looping whether to loop or not
1792      */
1793     public native void setLooping(boolean looping);
1794
1795     /**
1796      * Checks whether the MediaPlayer is looping or non-looping.
1797      *
1798      * @return true if the MediaPlayer is currently looping, false otherwise
1799      */
1800     public native boolean isLooping();
1801
1802     /**
1803      * Sets the volume on this player.
1804      * This API is recommended for balancing the output of audio streams
1805      * within an application. Unless you are writing an application to
1806      * control user settings, this API should be used in preference to
1807      * {@link AudioManager#setStreamVolume(int, int, int)} which sets the volume of ALL streams of
1808      * a particular type. Note that the passed volume values are raw scalars in range 0.0 to 1.0.
1809      * UI controls should be scaled logarithmically.
1810      *
1811      * @param leftVolume left volume scalar
1812      * @param rightVolume right volume scalar
1813      */
1814     /*
1815      * FIXME: Merge this into javadoc comment above when setVolume(float) is not @hide.
1816      * The single parameter form below is preferred if the channel volumes don't need
1817      * to be set independently.
1818      */
1819     public void setVolume(float leftVolume, float rightVolume) {
1820         baseSetVolume(leftVolume, rightVolume);
1821     }
1822
1823     @Override
1824     void playerSetVolume(float leftVolume, float rightVolume) {
1825         _setVolume(leftVolume, rightVolume);
1826     }
1827
1828     private native void _setVolume(float leftVolume, float rightVolume);
1829
1830     /**
1831      * Similar, excepts sets volume of all channels to same value.
1832      * @hide
1833      */
1834     public void setVolume(float volume) {
1835         setVolume(volume, volume);
1836     }
1837
1838     /**
1839      * Sets the audio session ID.
1840      *
1841      * @param sessionId the audio session ID.
1842      * The audio session ID is a system wide unique identifier for the audio stream played by
1843      * this MediaPlayer instance.
1844      * The primary use of the audio session ID  is to associate audio effects to a particular
1845      * instance of MediaPlayer: if an audio session ID is provided when creating an audio effect,
1846      * this effect will be applied only to the audio content of media players within the same
1847      * audio session and not to the output mix.
1848      * When created, a MediaPlayer instance automatically generates its own audio session ID.
1849      * However, it is possible to force this player to be part of an already existing audio session
1850      * by calling this method.
1851      * This method must be called before one of the overloaded <code> setDataSource </code> methods.
1852      * @throws IllegalStateException if it is called in an invalid state
1853      */
1854     public native void setAudioSessionId(int sessionId)  throws IllegalArgumentException, IllegalStateException;
1855
1856     /**
1857      * Returns the audio session ID.
1858      *
1859      * @return the audio session ID. {@see #setAudioSessionId(int)}
1860      * Note that the audio session ID is 0 only if a problem occured when the MediaPlayer was contructed.
1861      */
1862     public native int getAudioSessionId();
1863
1864     /**
1865      * Attaches an auxiliary effect to the player. A typical auxiliary effect is a reverberation
1866      * effect which can be applied on any sound source that directs a certain amount of its
1867      * energy to this effect. This amount is defined by setAuxEffectSendLevel().
1868      * See {@link #setAuxEffectSendLevel(float)}.
1869      * <p>After creating an auxiliary effect (e.g.
1870      * {@link android.media.audiofx.EnvironmentalReverb}), retrieve its ID with
1871      * {@link android.media.audiofx.AudioEffect#getId()} and use it when calling this method
1872      * to attach the player to the effect.
1873      * <p>To detach the effect from the player, call this method with a null effect id.
1874      * <p>This method must be called after one of the overloaded <code> setDataSource </code>
1875      * methods.
1876      * @param effectId system wide unique id of the effect to attach
1877      */
1878     public native void attachAuxEffect(int effectId);
1879
1880
1881     /**
1882      * Sets the send level of the player to the attached auxiliary effect.
1883      * See {@link #attachAuxEffect(int)}. The level value range is 0 to 1.0.
1884      * <p>By default the send level is 0, so even if an effect is attached to the player
1885      * this method must be called for the effect to be applied.
1886      * <p>Note that the passed level value is a raw scalar. UI controls should be scaled
1887      * logarithmically: the gain applied by audio framework ranges from -72dB to 0dB,
1888      * so an appropriate conversion from linear UI input x to level is:
1889      * x == 0 -> level = 0
1890      * 0 < x <= R -> level = 10^(72*(x-R)/20/R)
1891      * @param level send level scalar
1892      */
1893     public void setAuxEffectSendLevel(float level) {
1894         baseSetAuxEffectSendLevel(level);
1895     }
1896
1897     @Override
1898     int playerSetAuxEffectSendLevel(float level) {
1899         _setAuxEffectSendLevel(level);
1900         return AudioSystem.SUCCESS;
1901     }
1902
1903     private native void _setAuxEffectSendLevel(float level);
1904
1905     /*
1906      * @param request Parcel destinated to the media player. The
1907      *                Interface token must be set to the IMediaPlayer
1908      *                one to be routed correctly through the system.
1909      * @param reply[out] Parcel that will contain the reply.
1910      * @return The status code.
1911      */
1912     private native final int native_invoke(Parcel request, Parcel reply);
1913
1914
1915     /*
1916      * @param update_only If true fetch only the set of metadata that have
1917      *                    changed since the last invocation of getMetadata.
1918      *                    The set is built using the unfiltered
1919      *                    notifications the native player sent to the
1920      *                    MediaPlayerService during that period of
1921      *                    time. If false, all the metadatas are considered.
1922      * @param apply_filter  If true, once the metadata set has been built based on
1923      *                     the value update_only, the current filter is applied.
1924      * @param reply[out] On return contains the serialized
1925      *                   metadata. Valid only if the call was successful.
1926      * @return The status code.
1927      */
1928     private native final boolean native_getMetadata(boolean update_only,
1929                                                     boolean apply_filter,
1930                                                     Parcel reply);
1931
1932     /*
1933      * @param request Parcel with the 2 serialized lists of allowed
1934      *                metadata types followed by the one to be
1935      *                dropped. Each list starts with an integer
1936      *                indicating the number of metadata type elements.
1937      * @return The status code.
1938      */
1939     private native final int native_setMetadataFilter(Parcel request);
1940
1941     private static native final void native_init();
1942     private native final void native_setup(Object mediaplayer_this);
1943     private native final void native_finalize();
1944
1945     /**
1946      * Class for MediaPlayer to return each audio/video/subtitle track's metadata.
1947      *
1948      * @see android.media.MediaPlayer#getTrackInfo
1949      */
1950     static public class TrackInfo implements Parcelable {
1951         /**
1952          * Gets the track type.
1953          * @return TrackType which indicates if the track is video, audio, timed text.
1954          */
1955         public int getTrackType() {
1956             return mTrackType;
1957         }
1958
1959         /**
1960          * Gets the language code of the track.
1961          * @return a language code in either way of ISO-639-1 or ISO-639-2.
1962          * When the language is unknown or could not be determined,
1963          * ISO-639-2 language code, "und", is returned.
1964          */
1965         public String getLanguage() {
1966             String language = mFormat.getString(MediaFormat.KEY_LANGUAGE);
1967             return language == null ? "und" : language;
1968         }
1969
1970         /**
1971          * Gets the {@link MediaFormat} of the track.  If the format is
1972          * unknown or could not be determined, null is returned.
1973          */
1974         public MediaFormat getFormat() {
1975             if (mTrackType == MEDIA_TRACK_TYPE_TIMEDTEXT
1976                     || mTrackType == MEDIA_TRACK_TYPE_SUBTITLE) {
1977                 return mFormat;
1978             }
1979             return null;
1980         }
1981
1982         public static final int MEDIA_TRACK_TYPE_UNKNOWN = 0;
1983         public static final int MEDIA_TRACK_TYPE_VIDEO = 1;
1984         public static final int MEDIA_TRACK_TYPE_AUDIO = 2;
1985         public static final int MEDIA_TRACK_TYPE_TIMEDTEXT = 3;
1986         public static final int MEDIA_TRACK_TYPE_SUBTITLE = 4;
1987         public static final int MEDIA_TRACK_TYPE_METADATA = 5;
1988
1989         final int mTrackType;
1990         final MediaFormat mFormat;
1991
1992         TrackInfo(Parcel in) {
1993             mTrackType = in.readInt();
1994             // TODO: parcel in the full MediaFormat; currently we are using createSubtitleFormat
1995             // even for audio/video tracks, meaning we only set the mime and language.
1996             String mime = in.readString();
1997             String language = in.readString();
1998             mFormat = MediaFormat.createSubtitleFormat(mime, language);
1999
2000             if (mTrackType == MEDIA_TRACK_TYPE_SUBTITLE) {
2001                 mFormat.setInteger(MediaFormat.KEY_IS_AUTOSELECT, in.readInt());
2002                 mFormat.setInteger(MediaFormat.KEY_IS_DEFAULT, in.readInt());
2003                 mFormat.setInteger(MediaFormat.KEY_IS_FORCED_SUBTITLE, in.readInt());
2004             }
2005         }
2006
2007         /** @hide */
2008         TrackInfo(int type, MediaFormat format) {
2009             mTrackType = type;
2010             mFormat = format;
2011         }
2012
2013         /**
2014          * {@inheritDoc}
2015          */
2016         @Override
2017         public int describeContents() {
2018             return 0;
2019         }
2020
2021         /**
2022          * {@inheritDoc}
2023          */
2024         @Override
2025         public void writeToParcel(Parcel dest, int flags) {
2026             dest.writeInt(mTrackType);
2027             dest.writeString(getLanguage());
2028
2029             if (mTrackType == MEDIA_TRACK_TYPE_SUBTITLE) {
2030                 dest.writeString(mFormat.getString(MediaFormat.KEY_MIME));
2031                 dest.writeInt(mFormat.getInteger(MediaFormat.KEY_IS_AUTOSELECT));
2032                 dest.writeInt(mFormat.getInteger(MediaFormat.KEY_IS_DEFAULT));
2033                 dest.writeInt(mFormat.getInteger(MediaFormat.KEY_IS_FORCED_SUBTITLE));
2034             }
2035         }
2036
2037         @Override
2038         public String toString() {
2039             StringBuilder out = new StringBuilder(128);
2040             out.append(getClass().getName());
2041             out.append('{');
2042             switch (mTrackType) {
2043             case MEDIA_TRACK_TYPE_VIDEO:
2044                 out.append("VIDEO");
2045                 break;
2046             case MEDIA_TRACK_TYPE_AUDIO:
2047                 out.append("AUDIO");
2048                 break;
2049             case MEDIA_TRACK_TYPE_TIMEDTEXT:
2050                 out.append("TIMEDTEXT");
2051                 break;
2052             case MEDIA_TRACK_TYPE_SUBTITLE:
2053                 out.append("SUBTITLE");
2054                 break;
2055             default:
2056                 out.append("UNKNOWN");
2057                 break;
2058             }
2059             out.append(", " + mFormat.toString());
2060             out.append("}");
2061             return out.toString();
2062         }
2063
2064         /**
2065          * Used to read a TrackInfo from a Parcel.
2066          */
2067         static final Parcelable.Creator<TrackInfo> CREATOR
2068                 = new Parcelable.Creator<TrackInfo>() {
2069                     @Override
2070                     public TrackInfo createFromParcel(Parcel in) {
2071                         return new TrackInfo(in);
2072                     }
2073
2074                     @Override
2075                     public TrackInfo[] newArray(int size) {
2076                         return new TrackInfo[size];
2077                     }
2078                 };
2079
2080     };
2081
2082     // We would like domain specific classes with more informative names than the `first` and `second`
2083     // in generic Pair, but we would also like to avoid creating new/trivial classes. As a compromise
2084     // we document the meanings of `first` and `second` here:
2085     //
2086     // Pair.first - inband track index; non-null iff representing an inband track.
2087     // Pair.second - a SubtitleTrack registered with mSubtitleController; non-null iff representing
2088     //               an inband subtitle track or any out-of-band track (subtitle or timedtext).
2089     private Vector<Pair<Integer, SubtitleTrack>> mIndexTrackPairs = new Vector<>();
2090     private BitSet mInbandTrackIndices = new BitSet();
2091
2092     /**
2093      * Returns an array of track information.
2094      *
2095      * @return Array of track info. The total number of tracks is the array length.
2096      * Must be called again if an external timed text source has been added after any of the
2097      * addTimedTextSource methods are called.
2098      * @throws IllegalStateException if it is called in an invalid state.
2099      */
2100     public TrackInfo[] getTrackInfo() throws IllegalStateException {
2101         TrackInfo trackInfo[] = getInbandTrackInfo();
2102         // add out-of-band tracks
2103         synchronized (mIndexTrackPairs) {
2104             TrackInfo allTrackInfo[] = new TrackInfo[mIndexTrackPairs.size()];
2105             for (int i = 0; i < allTrackInfo.length; i++) {
2106                 Pair<Integer, SubtitleTrack> p = mIndexTrackPairs.get(i);
2107                 if (p.first != null) {
2108                     // inband track
2109                     allTrackInfo[i] = trackInfo[p.first];
2110                 } else {
2111                     SubtitleTrack track = p.second;
2112                     allTrackInfo[i] = new TrackInfo(track.getTrackType(), track.getFormat());
2113                 }
2114             }
2115             return allTrackInfo;
2116         }
2117     }
2118
2119     private TrackInfo[] getInbandTrackInfo() throws IllegalStateException {
2120         Parcel request = Parcel.obtain();
2121         Parcel reply = Parcel.obtain();
2122         try {
2123             request.writeInterfaceToken(IMEDIA_PLAYER);
2124             request.writeInt(INVOKE_ID_GET_TRACK_INFO);
2125             invoke(request, reply);
2126             TrackInfo trackInfo[] = reply.createTypedArray(TrackInfo.CREATOR);
2127             return trackInfo;
2128         } finally {
2129             request.recycle();
2130             reply.recycle();
2131         }
2132     }
2133
2134     /* Do not change these values without updating their counterparts
2135      * in include/media/stagefright/MediaDefs.h and media/libstagefright/MediaDefs.cpp!
2136      */
2137     /**
2138      * MIME type for SubRip (SRT) container. Used in addTimedTextSource APIs.
2139      */
2140     public static final String MEDIA_MIMETYPE_TEXT_SUBRIP = "application/x-subrip";
2141
2142     /**
2143      * MIME type for WebVTT subtitle data.
2144      * @hide
2145      */
2146     public static final String MEDIA_MIMETYPE_TEXT_VTT = "text/vtt";
2147
2148     /**
2149      * MIME type for CEA-608 closed caption data.
2150      * @hide
2151      */
2152     public static final String MEDIA_MIMETYPE_TEXT_CEA_608 = "text/cea-608";
2153
2154     /**
2155      * MIME type for CEA-708 closed caption data.
2156      * @hide
2157      */
2158     public static final String MEDIA_MIMETYPE_TEXT_CEA_708 = "text/cea-708";
2159
2160     /*
2161      * A helper function to check if the mime type is supported by media framework.
2162      */
2163     private static boolean availableMimeTypeForExternalSource(String mimeType) {
2164         if (MEDIA_MIMETYPE_TEXT_SUBRIP.equals(mimeType)) {
2165             return true;
2166         }
2167         return false;
2168     }
2169
2170     private SubtitleController mSubtitleController;
2171
2172     /** @hide */
2173     public void setSubtitleAnchor(
2174             SubtitleController controller,
2175             SubtitleController.Anchor anchor) {
2176         // TODO: create SubtitleController in MediaPlayer
2177         mSubtitleController = controller;
2178         mSubtitleController.setAnchor(anchor);
2179     }
2180
2181     /**
2182      * The private version of setSubtitleAnchor is used internally to set mSubtitleController if
2183      * necessary when clients don't provide their own SubtitleControllers using the public version
2184      * {@link #setSubtitleAnchor(SubtitleController, Anchor)} (e.g. {@link VideoView} provides one).
2185      */
2186     private synchronized void setSubtitleAnchor() {
2187         if (mSubtitleController == null) {
2188             final HandlerThread thread = new HandlerThread("SetSubtitleAnchorThread");
2189             thread.start();
2190             Handler handler = new Handler(thread.getLooper());
2191             handler.post(new Runnable() {
2192                 @Override
2193                 public void run() {
2194                     Context context = ActivityThread.currentApplication();
2195                     mSubtitleController = new SubtitleController(context, mTimeProvider, MediaPlayer.this);
2196                     mSubtitleController.setAnchor(new Anchor() {
2197                         @Override
2198                         public void setSubtitleWidget(RenderingWidget subtitleWidget) {
2199                         }
2200
2201                         @Override
2202                         public Looper getSubtitleLooper() {
2203                             return Looper.getMainLooper();
2204                         }
2205                     });
2206                     thread.getLooper().quitSafely();
2207                 }
2208             });
2209             try {
2210                 thread.join();
2211             } catch (InterruptedException e) {
2212                 Thread.currentThread().interrupt();
2213                 Log.w(TAG, "failed to join SetSubtitleAnchorThread");
2214             }
2215         }
2216     }
2217
2218     private int mSelectedSubtitleTrackIndex = -1;
2219     private Vector<InputStream> mOpenSubtitleSources;
2220
2221     private OnSubtitleDataListener mSubtitleDataListener = new OnSubtitleDataListener() {
2222         @Override
2223         public void onSubtitleData(MediaPlayer mp, SubtitleData data) {
2224             int index = data.getTrackIndex();
2225             synchronized (mIndexTrackPairs) {
2226                 for (Pair<Integer, SubtitleTrack> p : mIndexTrackPairs) {
2227                     if (p.first != null && p.first == index && p.second != null) {
2228                         // inband subtitle track that owns data
2229                         SubtitleTrack track = p.second;
2230                         track.onData(data);
2231                     }
2232                 }
2233             }
2234         }
2235     };
2236
2237     /** @hide */
2238     @Override
2239     public void onSubtitleTrackSelected(SubtitleTrack track) {
2240         if (mSelectedSubtitleTrackIndex >= 0) {
2241             try {
2242                 selectOrDeselectInbandTrack(mSelectedSubtitleTrackIndex, false);
2243             } catch (IllegalStateException e) {
2244             }
2245             mSelectedSubtitleTrackIndex = -1;
2246         }
2247         setOnSubtitleDataListener(null);
2248         if (track == null) {
2249             return;
2250         }
2251
2252         synchronized (mIndexTrackPairs) {
2253             for (Pair<Integer, SubtitleTrack> p : mIndexTrackPairs) {
2254                 if (p.first != null && p.second == track) {
2255                     // inband subtitle track that is selected
2256                     mSelectedSubtitleTrackIndex = p.first;
2257                     break;
2258                 }
2259             }
2260         }
2261
2262         if (mSelectedSubtitleTrackIndex >= 0) {
2263             try {
2264                 selectOrDeselectInbandTrack(mSelectedSubtitleTrackIndex, true);
2265             } catch (IllegalStateException e) {
2266             }
2267             setOnSubtitleDataListener(mSubtitleDataListener);
2268         }
2269         // no need to select out-of-band tracks
2270     }
2271
2272     /** @hide */
2273     public void addSubtitleSource(InputStream is, MediaFormat format)
2274             throws IllegalStateException
2275     {
2276         final InputStream fIs = is;
2277         final MediaFormat fFormat = format;
2278
2279         if (is != null) {
2280             // Ensure all input streams are closed.  It is also a handy
2281             // way to implement timeouts in the future.
2282             synchronized(mOpenSubtitleSources) {
2283                 mOpenSubtitleSources.add(is);
2284             }
2285         } else {
2286             Log.w(TAG, "addSubtitleSource called with null InputStream");
2287         }
2288
2289         getMediaTimeProvider();
2290
2291         // process each subtitle in its own thread
2292         final HandlerThread thread = new HandlerThread("SubtitleReadThread",
2293               Process.THREAD_PRIORITY_BACKGROUND + Process.THREAD_PRIORITY_MORE_FAVORABLE);
2294         thread.start();
2295         Handler handler = new Handler(thread.getLooper());
2296         handler.post(new Runnable() {
2297             private int addTrack() {
2298                 if (fIs == null || mSubtitleController == null) {
2299                     return MEDIA_INFO_UNSUPPORTED_SUBTITLE;
2300                 }
2301
2302                 SubtitleTrack track = mSubtitleController.addTrack(fFormat);
2303                 if (track == null) {
2304                     return MEDIA_INFO_UNSUPPORTED_SUBTITLE;
2305                 }
2306
2307                 // TODO: do the conversion in the subtitle track
2308                 Scanner scanner = new Scanner(fIs, "UTF-8");
2309                 String contents = scanner.useDelimiter("\\A").next();
2310                 synchronized(mOpenSubtitleSources) {
2311                     mOpenSubtitleSources.remove(fIs);
2312                 }
2313                 scanner.close();
2314                 synchronized (mIndexTrackPairs) {
2315                     mIndexTrackPairs.add(Pair.<Integer, SubtitleTrack>create(null, track));
2316                 }
2317                 Handler h = mTimeProvider.mEventHandler;
2318                 int what = TimeProvider.NOTIFY;
2319                 int arg1 = TimeProvider.NOTIFY_TRACK_DATA;
2320                 Pair<SubtitleTrack, byte[]> trackData = Pair.create(track, contents.getBytes());
2321                 Message m = h.obtainMessage(what, arg1, 0, trackData);
2322                 h.sendMessage(m);
2323                 return MEDIA_INFO_EXTERNAL_METADATA_UPDATE;
2324             }
2325
2326             public void run() {
2327                 int res = addTrack();
2328                 if (mEventHandler != null) {
2329                     Message m = mEventHandler.obtainMessage(MEDIA_INFO, res, 0, null);
2330                     mEventHandler.sendMessage(m);
2331                 }
2332                 thread.getLooper().quitSafely();
2333             }
2334         });
2335     }
2336
2337     private void scanInternalSubtitleTracks() {
2338         if (mSubtitleController == null) {
2339             Log.d(TAG, "setSubtitleAnchor in MediaPlayer");
2340             setSubtitleAnchor();
2341         }
2342
2343         populateInbandTracks();
2344
2345         if (mSubtitleController != null) {
2346             mSubtitleController.selectDefaultTrack();
2347         }
2348     }
2349
2350     private void populateInbandTracks() {
2351         TrackInfo[] tracks = getInbandTrackInfo();
2352         synchronized (mIndexTrackPairs) {
2353             for (int i = 0; i < tracks.length; i++) {
2354                 if (mInbandTrackIndices.get(i)) {
2355                     continue;
2356                 } else {
2357                     mInbandTrackIndices.set(i);
2358                 }
2359
2360                 // newly appeared inband track
2361                 if (tracks[i].getTrackType() == TrackInfo.MEDIA_TRACK_TYPE_SUBTITLE) {
2362                     SubtitleTrack track = mSubtitleController.addTrack(
2363                             tracks[i].getFormat());
2364                     mIndexTrackPairs.add(Pair.create(i, track));
2365                 } else {
2366                     mIndexTrackPairs.add(Pair.<Integer, SubtitleTrack>create(i, null));
2367                 }
2368             }
2369         }
2370     }
2371
2372     /* TODO: Limit the total number of external timed text source to a reasonable number.
2373      */
2374     /**
2375      * Adds an external timed text source file.
2376      *
2377      * Currently supported format is SubRip with the file extension .srt, case insensitive.
2378      * Note that a single external timed text source may contain multiple tracks in it.
2379      * One can find the total number of available tracks using {@link #getTrackInfo()} to see what
2380      * additional tracks become available after this method call.
2381      *
2382      * @param path The file path of external timed text source file.
2383      * @param mimeType The mime type of the file. Must be one of the mime types listed above.
2384      * @throws IOException if the file cannot be accessed or is corrupted.
2385      * @throws IllegalArgumentException if the mimeType is not supported.
2386      * @throws IllegalStateException if called in an invalid state.
2387      */
2388     public void addTimedTextSource(String path, String mimeType)
2389             throws IOException, IllegalArgumentException, IllegalStateException {
2390         if (!availableMimeTypeForExternalSource(mimeType)) {
2391             final String msg = "Illegal mimeType for timed text source: " + mimeType;
2392             throw new IllegalArgumentException(msg);
2393         }
2394
2395         File file = new File(path);
2396         if (file.exists()) {
2397             FileInputStream is = new FileInputStream(file);
2398             FileDescriptor fd = is.getFD();
2399             addTimedTextSource(fd, mimeType);
2400             is.close();
2401         } else {
2402             // We do not support the case where the path is not a file.
2403             throw new IOException(path);
2404         }
2405     }
2406
2407     /**
2408      * Adds an external timed text source file (Uri).
2409      *
2410      * Currently supported format is SubRip with the file extension .srt, case insensitive.
2411      * Note that a single external timed text source may contain multiple tracks in it.
2412      * One can find the total number of available tracks using {@link #getTrackInfo()} to see what
2413      * additional tracks become available after this method call.
2414      *
2415      * @param context the Context to use when resolving the Uri
2416      * @param uri the Content URI of the data you want to play
2417      * @param mimeType The mime type of the file. Must be one of the mime types listed above.
2418      * @throws IOException if the file cannot be accessed or is corrupted.
2419      * @throws IllegalArgumentException if the mimeType is not supported.
2420      * @throws IllegalStateException if called in an invalid state.
2421      */
2422     public void addTimedTextSource(Context context, Uri uri, String mimeType)
2423             throws IOException, IllegalArgumentException, IllegalStateException {
2424         String scheme = uri.getScheme();
2425         if(scheme == null || scheme.equals("file")) {
2426             addTimedTextSource(uri.getPath(), mimeType);
2427             return;
2428         }
2429
2430         AssetFileDescriptor fd = null;
2431         try {
2432             ContentResolver resolver = context.getContentResolver();
2433             fd = resolver.openAssetFileDescriptor(uri, "r");
2434             if (fd == null) {
2435                 return;
2436             }
2437             addTimedTextSource(fd.getFileDescriptor(), mimeType);
2438             return;
2439         } catch (SecurityException ex) {
2440         } catch (IOException ex) {
2441         } finally {
2442             if (fd != null) {
2443                 fd.close();
2444             }
2445         }
2446     }
2447
2448     /**
2449      * Adds an external timed text source file (FileDescriptor).
2450      *
2451      * It is the caller's responsibility to close the file descriptor.
2452      * It is safe to do so as soon as this call returns.
2453      *
2454      * Currently supported format is SubRip. Note that a single external timed text source may
2455      * contain multiple tracks in it. One can find the total number of available tracks
2456      * using {@link #getTrackInfo()} to see what additional tracks become available
2457      * after this method call.
2458      *
2459      * @param fd the FileDescriptor for the file you want to play
2460      * @param mimeType The mime type of the file. Must be one of the mime types listed above.
2461      * @throws IllegalArgumentException if the mimeType is not supported.
2462      * @throws IllegalStateException if called in an invalid state.
2463      */
2464     public void addTimedTextSource(FileDescriptor fd, String mimeType)
2465             throws IllegalArgumentException, IllegalStateException {
2466         // intentionally less than LONG_MAX
2467         addTimedTextSource(fd, 0, 0x7ffffffffffffffL, mimeType);
2468     }
2469
2470     /**
2471      * Adds an external timed text file (FileDescriptor).
2472      *
2473      * It is the caller's responsibility to close the file descriptor.
2474      * It is safe to do so as soon as this call returns.
2475      *
2476      * Currently supported format is SubRip. Note that a single external timed text source may
2477      * contain multiple tracks in it. One can find the total number of available tracks
2478      * using {@link #getTrackInfo()} to see what additional tracks become available
2479      * after this method call.
2480      *
2481      * @param fd the FileDescriptor for the file you want to play
2482      * @param offset the offset into the file where the data to be played starts, in bytes
2483      * @param length the length in bytes of the data to be played
2484      * @param mime The mime type of the file. Must be one of the mime types listed above.
2485      * @throws IllegalArgumentException if the mimeType is not supported.
2486      * @throws IllegalStateException if called in an invalid state.
2487      */
2488     public void addTimedTextSource(FileDescriptor fd, long offset, long length, String mime)
2489             throws IllegalArgumentException, IllegalStateException {
2490         if (!availableMimeTypeForExternalSource(mime)) {
2491             throw new IllegalArgumentException("Illegal mimeType for timed text source: " + mime);
2492         }
2493
2494         FileDescriptor fd2;
2495         try {
2496             fd2 = Libcore.os.dup(fd);
2497         } catch (ErrnoException ex) {
2498             Log.e(TAG, ex.getMessage(), ex);
2499             throw new RuntimeException(ex);
2500         }
2501
2502         final MediaFormat fFormat = new MediaFormat();
2503         fFormat.setString(MediaFormat.KEY_MIME, mime);
2504         fFormat.setInteger(MediaFormat.KEY_IS_TIMED_TEXT, 1);
2505
2506         // A MediaPlayer created by a VideoView should already have its mSubtitleController set.
2507         if (mSubtitleController == null) {
2508             setSubtitleAnchor();
2509         }
2510
2511         if (!mSubtitleController.hasRendererFor(fFormat)) {
2512             // test and add not atomic
2513             Context context = ActivityThread.currentApplication();
2514             mSubtitleController.registerRenderer(new SRTRenderer(context, mEventHandler));
2515         }
2516         final SubtitleTrack track = mSubtitleController.addTrack(fFormat);
2517         synchronized (mIndexTrackPairs) {
2518             mIndexTrackPairs.add(Pair.<Integer, SubtitleTrack>create(null, track));
2519         }
2520
2521         getMediaTimeProvider();
2522
2523         final FileDescriptor fd3 = fd2;
2524         final long offset2 = offset;
2525         final long length2 = length;
2526         final HandlerThread thread = new HandlerThread(
2527                 "TimedTextReadThread",
2528                 Process.THREAD_PRIORITY_BACKGROUND + Process.THREAD_PRIORITY_MORE_FAVORABLE);
2529         thread.start();
2530         Handler handler = new Handler(thread.getLooper());
2531         handler.post(new Runnable() {
2532             private int addTrack() {
2533                 InputStream is = null;
2534                 final ByteArrayOutputStream bos = new ByteArrayOutputStream();
2535                 try {
2536                     Libcore.os.lseek(fd3, offset2, OsConstants.SEEK_SET);
2537                     byte[] buffer = new byte[4096];
2538                     for (long total = 0; total < length2;) {
2539                         int bytesToRead = (int) Math.min(buffer.length, length2 - total);
2540                         int bytes = IoBridge.read(fd3, buffer, 0, bytesToRead);
2541                         if (bytes < 0) {
2542                             break;
2543                         } else {
2544                             bos.write(buffer, 0, bytes);
2545                             total += bytes;
2546                         }
2547                     }
2548                     Handler h = mTimeProvider.mEventHandler;
2549                     int what = TimeProvider.NOTIFY;
2550                     int arg1 = TimeProvider.NOTIFY_TRACK_DATA;
2551                     Pair<SubtitleTrack, byte[]> trackData = Pair.create(track, bos.toByteArray());
2552                     Message m = h.obtainMessage(what, arg1, 0, trackData);
2553                     h.sendMessage(m);
2554                     return MEDIA_INFO_EXTERNAL_METADATA_UPDATE;
2555                 } catch (Exception e) {
2556                     Log.e(TAG, e.getMessage(), e);
2557                     return MEDIA_INFO_TIMED_TEXT_ERROR;
2558                 } finally {
2559                     if (is != null) {
2560                         try {
2561                             is.close();
2562                         } catch (IOException e) {
2563                             Log.e(TAG, e.getMessage(), e);
2564                         }
2565                     }
2566                 }
2567             }
2568
2569             public void run() {
2570                 int res = addTrack();
2571                 if (mEventHandler != null) {
2572                     Message m = mEventHandler.obtainMessage(MEDIA_INFO, res, 0, null);
2573                     mEventHandler.sendMessage(m);
2574                 }
2575                 thread.getLooper().quitSafely();
2576             }
2577         });
2578     }
2579
2580     /**
2581      * Returns the index of the audio, video, or subtitle track currently selected for playback,
2582      * The return value is an index into the array returned by {@link #getTrackInfo()}, and can
2583      * be used in calls to {@link #selectTrack(int)} or {@link #deselectTrack(int)}.
2584      *
2585      * @param trackType should be one of {@link TrackInfo#MEDIA_TRACK_TYPE_VIDEO},
2586      * {@link TrackInfo#MEDIA_TRACK_TYPE_AUDIO}, or
2587      * {@link TrackInfo#MEDIA_TRACK_TYPE_SUBTITLE}
2588      * @return index of the audio, video, or subtitle track currently selected for playback;
2589      * a negative integer is returned when there is no selected track for {@code trackType} or
2590      * when {@code trackType} is not one of audio, video, or subtitle.
2591      * @throws IllegalStateException if called after {@link #release()}
2592      *
2593      * @see #getTrackInfo()
2594      * @see #selectTrack(int)
2595      * @see #deselectTrack(int)
2596      */
2597     public int getSelectedTrack(int trackType) throws IllegalStateException {
2598         if (mSubtitleController != null
2599                 && (trackType == TrackInfo.MEDIA_TRACK_TYPE_SUBTITLE
2600                 || trackType == TrackInfo.MEDIA_TRACK_TYPE_TIMEDTEXT)) {
2601             SubtitleTrack subtitleTrack = mSubtitleController.getSelectedTrack();
2602             if (subtitleTrack != null) {
2603                 synchronized (mIndexTrackPairs) {
2604                     for (int i = 0; i < mIndexTrackPairs.size(); i++) {
2605                         Pair<Integer, SubtitleTrack> p = mIndexTrackPairs.get(i);
2606                         if (p.second == subtitleTrack && subtitleTrack.getTrackType() == trackType) {
2607                             return i;
2608                         }
2609                     }
2610                 }
2611             }
2612         }
2613
2614         Parcel request = Parcel.obtain();
2615         Parcel reply = Parcel.obtain();
2616         try {
2617             request.writeInterfaceToken(IMEDIA_PLAYER);
2618             request.writeInt(INVOKE_ID_GET_SELECTED_TRACK);
2619             request.writeInt(trackType);
2620             invoke(request, reply);
2621             int inbandTrackIndex = reply.readInt();
2622             synchronized (mIndexTrackPairs) {
2623                 for (int i = 0; i < mIndexTrackPairs.size(); i++) {
2624                     Pair<Integer, SubtitleTrack> p = mIndexTrackPairs.get(i);
2625                     if (p.first != null && p.first == inbandTrackIndex) {
2626                         return i;
2627                     }
2628                 }
2629             }
2630             return -1;
2631         } finally {
2632             request.recycle();
2633             reply.recycle();
2634         }
2635     }
2636
2637     /**
2638      * Selects a track.
2639      * <p>
2640      * If a MediaPlayer is in invalid state, it throws an IllegalStateException exception.
2641      * If a MediaPlayer is in <em>Started</em> state, the selected track is presented immediately.
2642      * If a MediaPlayer is not in Started state, it just marks the track to be played.
2643      * </p>
2644      * <p>
2645      * In any valid state, if it is called multiple times on the same type of track (ie. Video,
2646      * Audio, Timed Text), the most recent one will be chosen.
2647      * </p>
2648      * <p>
2649      * The first audio and video tracks are selected by default if available, even though
2650      * this method is not called. However, no timed text track will be selected until
2651      * this function is called.
2652      * </p>
2653      * <p>
2654      * Currently, only timed text tracks or audio tracks can be selected via this method.
2655      * In addition, the support for selecting an audio track at runtime is pretty limited
2656      * in that an audio track can only be selected in the <em>Prepared</em> state.
2657      * </p>
2658      * @param index the index of the track to be selected. The valid range of the index
2659      * is 0..total number of track - 1. The total number of tracks as well as the type of
2660      * each individual track can be found by calling {@link #getTrackInfo()} method.
2661      * @throws IllegalStateException if called in an invalid state.
2662      *
2663      * @see android.media.MediaPlayer#getTrackInfo
2664      */
2665     public void selectTrack(int index) throws IllegalStateException {
2666         selectOrDeselectTrack(index, true /* select */);
2667     }
2668
2669     /**
2670      * Deselect a track.
2671      * <p>
2672      * Currently, the track must be a timed text track and no audio or video tracks can be
2673      * deselected. If the timed text track identified by index has not been
2674      * selected before, it throws an exception.
2675      * </p>
2676      * @param index the index of the track to be deselected. The valid range of the index
2677      * is 0..total number of tracks - 1. The total number of tracks as well as the type of
2678      * each individual track can be found by calling {@link #getTrackInfo()} method.
2679      * @throws IllegalStateException if called in an invalid state.
2680      *
2681      * @see android.media.MediaPlayer#getTrackInfo
2682      */
2683     public void deselectTrack(int index) throws IllegalStateException {
2684         selectOrDeselectTrack(index, false /* select */);
2685     }
2686
2687     private void selectOrDeselectTrack(int index, boolean select)
2688             throws IllegalStateException {
2689         // handle subtitle track through subtitle controller
2690         populateInbandTracks();
2691
2692         Pair<Integer,SubtitleTrack> p = null;
2693         try {
2694             p = mIndexTrackPairs.get(index);
2695         } catch (ArrayIndexOutOfBoundsException e) {
2696             // ignore bad index
2697             return;
2698         }
2699
2700         SubtitleTrack track = p.second;
2701         if (track == null) {
2702             // inband (de)select
2703             selectOrDeselectInbandTrack(p.first, select);
2704             return;
2705         }
2706
2707         if (mSubtitleController == null) {
2708             return;
2709         }
2710
2711         if (!select) {
2712             // out-of-band deselect
2713             if (mSubtitleController.getSelectedTrack() == track) {
2714                 mSubtitleController.selectTrack(null);
2715             } else {
2716                 Log.w(TAG, "trying to deselect track that was not selected");
2717             }
2718             return;
2719         }
2720
2721         // out-of-band select
2722         if (track.getTrackType() == TrackInfo.MEDIA_TRACK_TYPE_TIMEDTEXT) {
2723             int ttIndex = getSelectedTrack(TrackInfo.MEDIA_TRACK_TYPE_TIMEDTEXT);
2724             synchronized (mIndexTrackPairs) {
2725                 if (ttIndex >= 0 && ttIndex < mIndexTrackPairs.size()) {
2726                     Pair<Integer,SubtitleTrack> p2 = mIndexTrackPairs.get(ttIndex);
2727                     if (p2.first != null && p2.second == null) {
2728                         // deselect inband counterpart
2729                         selectOrDeselectInbandTrack(p2.first, false);
2730                     }
2731                 }
2732             }
2733         }
2734         mSubtitleController.selectTrack(track);
2735     }
2736
2737     private void selectOrDeselectInbandTrack(int index, boolean select)
2738             throws IllegalStateException {
2739         Parcel request = Parcel.obtain();
2740         Parcel reply = Parcel.obtain();
2741         try {
2742             request.writeInterfaceToken(IMEDIA_PLAYER);
2743             request.writeInt(select? INVOKE_ID_SELECT_TRACK: INVOKE_ID_DESELECT_TRACK);
2744             request.writeInt(index);
2745             invoke(request, reply);
2746         } finally {
2747             request.recycle();
2748             reply.recycle();
2749         }
2750     }
2751
2752
2753     /**
2754      * @param reply Parcel with audio/video duration info for battery
2755                     tracking usage
2756      * @return The status code.
2757      * {@hide}
2758      */
2759     public native static int native_pullBatteryData(Parcel reply);
2760
2761     /**
2762      * Sets the target UDP re-transmit endpoint for the low level player.
2763      * Generally, the address portion of the endpoint is an IP multicast
2764      * address, although a unicast address would be equally valid.  When a valid
2765      * retransmit endpoint has been set, the media player will not decode and
2766      * render the media presentation locally.  Instead, the player will attempt
2767      * to re-multiplex its media data using the Android@Home RTP profile and
2768      * re-transmit to the target endpoint.  Receiver devices (which may be
2769      * either the same as the transmitting device or different devices) may
2770      * instantiate, prepare, and start a receiver player using a setDataSource
2771      * URL of the form...
2772      *
2773      * aahRX://&lt;multicastIP&gt;:&lt;port&gt;
2774      *
2775      * to receive, decode and render the re-transmitted content.
2776      *
2777      * setRetransmitEndpoint may only be called before setDataSource has been
2778      * called; while the player is in the Idle state.
2779      *
2780      * @param endpoint the address and UDP port of the re-transmission target or
2781      * null if no re-transmission is to be performed.
2782      * @throws IllegalStateException if it is called in an invalid state
2783      * @throws IllegalArgumentException if the retransmit endpoint is supplied,
2784      * but invalid.
2785      *
2786      * {@hide} pending API council
2787      */
2788     public void setRetransmitEndpoint(InetSocketAddress endpoint)
2789             throws IllegalStateException, IllegalArgumentException
2790     {
2791         String addrString = null;
2792         int port = 0;
2793
2794         if (null != endpoint) {
2795             addrString = endpoint.getAddress().getHostAddress();
2796             port = endpoint.getPort();
2797         }
2798
2799         int ret = native_setRetransmitEndpoint(addrString, port);
2800         if (ret != 0) {
2801             throw new IllegalArgumentException("Illegal re-transmit endpoint; native ret " + ret);
2802         }
2803     }
2804
2805     private native final int native_setRetransmitEndpoint(String addrString, int port);
2806
2807     @Override
2808     protected void finalize() {
2809         baseRelease();
2810         native_finalize();
2811     }
2812
2813     /* Do not change these values without updating their counterparts
2814      * in include/media/mediaplayer.h!
2815      */
2816     private static final int MEDIA_NOP = 0; // interface test message
2817     private static final int MEDIA_PREPARED = 1;
2818     private static final int MEDIA_PLAYBACK_COMPLETE = 2;
2819     private static final int MEDIA_BUFFERING_UPDATE = 3;
2820     private static final int MEDIA_SEEK_COMPLETE = 4;
2821     private static final int MEDIA_SET_VIDEO_SIZE = 5;
2822     private static final int MEDIA_STARTED = 6;
2823     private static final int MEDIA_PAUSED = 7;
2824     private static final int MEDIA_STOPPED = 8;
2825     private static final int MEDIA_SKIPPED = 9;
2826     private static final int MEDIA_TIMED_TEXT = 99;
2827     private static final int MEDIA_ERROR = 100;
2828     private static final int MEDIA_INFO = 200;
2829     private static final int MEDIA_SUBTITLE_DATA = 201;
2830     private static final int MEDIA_META_DATA = 202;
2831
2832     private TimeProvider mTimeProvider;
2833
2834     /** @hide */
2835     public MediaTimeProvider getMediaTimeProvider() {
2836         if (mTimeProvider == null) {
2837             mTimeProvider = new TimeProvider(this);
2838         }
2839         return mTimeProvider;
2840     }
2841
2842     private class EventHandler extends Handler
2843     {
2844         private MediaPlayer mMediaPlayer;
2845
2846         public EventHandler(MediaPlayer mp, Looper looper) {
2847             super(looper);
2848             mMediaPlayer = mp;
2849         }
2850
2851         @Override
2852         public void handleMessage(Message msg) {
2853             if (mMediaPlayer.mNativeContext == 0) {
2854                 Log.w(TAG, "mediaplayer went away with unhandled events");
2855                 return;
2856             }
2857             switch(msg.what) {
2858             case MEDIA_PREPARED:
2859                 try {
2860                     scanInternalSubtitleTracks();
2861                 } catch (RuntimeException e) {
2862                     // send error message instead of crashing;
2863                     // send error message instead of inlining a call to onError
2864                     // to avoid code duplication.
2865                     Message msg2 = obtainMessage(
2866                             MEDIA_ERROR, MEDIA_ERROR_UNKNOWN, MEDIA_ERROR_UNSUPPORTED, null);
2867                     sendMessage(msg2);
2868                 }
2869                 OnPreparedListener onPreparedListener = mOnPreparedListener;
2870                 if (onPreparedListener != null)
2871                     onPreparedListener.onPrepared(mMediaPlayer);
2872                 return;
2873
2874             case MEDIA_PLAYBACK_COMPLETE:
2875                 {
2876                     OnCompletionListener onCompletionListener = mOnCompletionListener;
2877                     if (onCompletionListener != null)
2878                         onCompletionListener.onCompletion(mMediaPlayer);
2879                 }
2880                 stayAwake(false);
2881                 return;
2882
2883             case MEDIA_STOPPED:
2884                 {
2885                     TimeProvider timeProvider = mTimeProvider;
2886                     if (timeProvider != null) {
2887                         timeProvider.onStopped();
2888                     }
2889                 }
2890                 break;
2891
2892             case MEDIA_STARTED:
2893             case MEDIA_PAUSED:
2894                 {
2895                     TimeProvider timeProvider = mTimeProvider;
2896                     if (timeProvider != null) {
2897                         timeProvider.onPaused(msg.what == MEDIA_PAUSED);
2898                     }
2899                 }
2900                 break;
2901
2902             case MEDIA_BUFFERING_UPDATE:
2903                 OnBufferingUpdateListener onBufferingUpdateListener = mOnBufferingUpdateListener;
2904                 if (onBufferingUpdateListener != null)
2905                     onBufferingUpdateListener.onBufferingUpdate(mMediaPlayer, msg.arg1);
2906                 return;
2907
2908             case MEDIA_SEEK_COMPLETE:
2909                 OnSeekCompleteListener onSeekCompleteListener = mOnSeekCompleteListener;
2910                 if (onSeekCompleteListener != null) {
2911                     onSeekCompleteListener.onSeekComplete(mMediaPlayer);
2912                 }
2913                 // fall through
2914
2915             case MEDIA_SKIPPED:
2916                 {
2917                     TimeProvider timeProvider = mTimeProvider;
2918                     if (timeProvider != null) {
2919                         timeProvider.onSeekComplete(mMediaPlayer);
2920                     }
2921                 }
2922                 return;
2923
2924             case MEDIA_SET_VIDEO_SIZE:
2925                 OnVideoSizeChangedListener onVideoSizeChangedListener = mOnVideoSizeChangedListener;
2926                 if (onVideoSizeChangedListener != null) {
2927                     onVideoSizeChangedListener.onVideoSizeChanged(
2928                         mMediaPlayer, msg.arg1, msg.arg2);
2929                 }
2930                 return;
2931
2932             case MEDIA_ERROR:
2933                 Log.e(TAG, "Error (" + msg.arg1 + "," + msg.arg2 + ")");
2934                 boolean error_was_handled = false;
2935                 OnErrorListener onErrorListener = mOnErrorListener;
2936                 if (onErrorListener != null) {
2937                     error_was_handled = onErrorListener.onError(mMediaPlayer, msg.arg1, msg.arg2);
2938                 }
2939                 {
2940                     OnCompletionListener onCompletionListener = mOnCompletionListener;
2941                     if (onCompletionListener != null && ! error_was_handled) {
2942                         onCompletionListener.onCompletion(mMediaPlayer);
2943                     }
2944                 }
2945                 stayAwake(false);
2946                 return;
2947
2948             case MEDIA_INFO:
2949                 switch (msg.arg1) {
2950                 case MEDIA_INFO_VIDEO_TRACK_LAGGING:
2951                     Log.i(TAG, "Info (" + msg.arg1 + "," + msg.arg2 + ")");
2952                     break;
2953                 case MEDIA_INFO_METADATA_UPDATE:
2954                     try {
2955                         scanInternalSubtitleTracks();
2956                     } catch (RuntimeException e) {
2957                         Message msg2 = obtainMessage(
2958                                 MEDIA_ERROR, MEDIA_ERROR_UNKNOWN, MEDIA_ERROR_UNSUPPORTED, null);
2959                         sendMessage(msg2);
2960                     }
2961                     // fall through
2962
2963                 case MEDIA_INFO_EXTERNAL_METADATA_UPDATE:
2964                     msg.arg1 = MEDIA_INFO_METADATA_UPDATE;
2965                     // update default track selection
2966                     if (mSubtitleController != null) {
2967                         mSubtitleController.selectDefaultTrack();
2968                     }
2969                     break;
2970                 case MEDIA_INFO_BUFFERING_START:
2971                 case MEDIA_INFO_BUFFERING_END:
2972                     TimeProvider timeProvider = mTimeProvider;
2973                     if (timeProvider != null) {
2974                         timeProvider.onBuffering(msg.arg1 == MEDIA_INFO_BUFFERING_START);
2975                     }
2976                     break;
2977                 }
2978
2979                 OnInfoListener onInfoListener = mOnInfoListener;
2980                 if (onInfoListener != null) {
2981                     onInfoListener.onInfo(mMediaPlayer, msg.arg1, msg.arg2);
2982                 }
2983                 // No real default action so far.
2984                 return;
2985             case MEDIA_TIMED_TEXT:
2986                 OnTimedTextListener onTimedTextListener = mOnTimedTextListener;
2987                 if (onTimedTextListener == null)
2988                     return;
2989                 if (msg.obj == null) {
2990                     onTimedTextListener.onTimedText(mMediaPlayer, null);
2991                 } else {
2992                     if (msg.obj instanceof Parcel) {
2993                         Parcel parcel = (Parcel)msg.obj;
2994                         TimedText text = new TimedText(parcel);
2995                         parcel.recycle();
2996                         onTimedTextListener.onTimedText(mMediaPlayer, text);
2997                     }
2998                 }
2999                 return;
3000
3001             case MEDIA_SUBTITLE_DATA:
3002                 OnSubtitleDataListener onSubtitleDataListener = mOnSubtitleDataListener;
3003                 if (onSubtitleDataListener == null) {
3004                     return;
3005                 }
3006                 if (msg.obj instanceof Parcel) {
3007                     Parcel parcel = (Parcel) msg.obj;
3008                     SubtitleData data = new SubtitleData(parcel);
3009                     parcel.recycle();
3010                     onSubtitleDataListener.onSubtitleData(mMediaPlayer, data);
3011                 }
3012                 return;
3013
3014             case MEDIA_META_DATA:
3015                 OnTimedMetaDataAvailableListener onTimedMetaDataAvailableListener =
3016                     mOnTimedMetaDataAvailableListener;
3017                 if (onTimedMetaDataAvailableListener == null) {
3018                     return;
3019                 }
3020                 if (msg.obj instanceof Parcel) {
3021                     Parcel parcel = (Parcel) msg.obj;
3022                     TimedMetaData data = TimedMetaData.createTimedMetaDataFromParcel(parcel);
3023                     parcel.recycle();
3024                     onTimedMetaDataAvailableListener.onTimedMetaDataAvailable(mMediaPlayer, data);
3025                 }
3026                 return;
3027
3028             case MEDIA_NOP: // interface test message - ignore
3029                 break;
3030
3031             default:
3032                 Log.e(TAG, "Unknown message type " + msg.what);
3033                 return;
3034             }
3035         }
3036     }
3037
3038     /*
3039      * Called from native code when an interesting event happens.  This method
3040      * just uses the EventHandler system to post the event back to the main app thread.
3041      * We use a weak reference to the original MediaPlayer object so that the native
3042      * code is safe from the object disappearing from underneath it.  (This is
3043      * the cookie passed to native_setup().)
3044      */
3045     private static void postEventFromNative(Object mediaplayer_ref,
3046                                             int what, int arg1, int arg2, Object obj)
3047     {
3048         MediaPlayer mp = (MediaPlayer)((WeakReference)mediaplayer_ref).get();
3049         if (mp == null) {
3050             return;
3051         }
3052
3053         if (what == MEDIA_INFO && arg1 == MEDIA_INFO_STARTED_AS_NEXT) {
3054             // this acquires the wakelock if needed, and sets the client side state
3055             mp.start();
3056         }
3057         if (mp.mEventHandler != null) {
3058             Message m = mp.mEventHandler.obtainMessage(what, arg1, arg2, obj);
3059             mp.mEventHandler.sendMessage(m);
3060         }
3061     }
3062
3063     /**
3064      * Interface definition for a callback to be invoked when the media
3065      * source is ready for playback.
3066      */
3067     public interface OnPreparedListener
3068     {
3069         /**
3070          * Called when the media file is ready for playback.
3071          *
3072          * @param mp the MediaPlayer that is ready for playback
3073          */
3074         void onPrepared(MediaPlayer mp);
3075     }
3076
3077     /**
3078      * Register a callback to be invoked when the media source is ready
3079      * for playback.
3080      *
3081      * @param listener the callback that will be run
3082      */
3083     public void setOnPreparedListener(OnPreparedListener listener)
3084     {
3085         mOnPreparedListener = listener;
3086     }
3087
3088     private OnPreparedListener mOnPreparedListener;
3089
3090     /**
3091      * Interface definition for a callback to be invoked when playback of
3092      * a media source has completed.
3093      */
3094     public interface OnCompletionListener
3095     {
3096         /**
3097          * Called when the end of a media source is reached during playback.
3098          *
3099          * @param mp the MediaPlayer that reached the end of the file
3100          */
3101         void onCompletion(MediaPlayer mp);
3102     }
3103
3104     /**
3105      * Register a callback to be invoked when the end of a media source
3106      * has been reached during playback.
3107      *
3108      * @param listener the callback that will be run
3109      */
3110     public void setOnCompletionListener(OnCompletionListener listener)
3111     {
3112         mOnCompletionListener = listener;
3113     }
3114
3115     private OnCompletionListener mOnCompletionListener;
3116
3117     /**
3118      * Interface definition of a callback to be invoked indicating buffering
3119      * status of a media resource being streamed over the network.
3120      */
3121     public interface OnBufferingUpdateListener
3122     {
3123         /**
3124          * Called to update status in buffering a media stream received through
3125          * progressive HTTP download. The received buffering percentage
3126          * indicates how much of the content has been buffered or played.
3127          * For example a buffering update of 80 percent when half the content
3128          * has already been played indicates that the next 30 percent of the
3129          * content to play has been buffered.
3130          *
3131          * @param mp      the MediaPlayer the update pertains to
3132          * @param percent the percentage (0-100) of the content
3133          *                that has been buffered or played thus far
3134          */
3135         void onBufferingUpdate(MediaPlayer mp, int percent);
3136     }
3137
3138     /**
3139      * Register a callback to be invoked when the status of a network
3140      * stream's buffer has changed.
3141      *
3142      * @param listener the callback that will be run.
3143      */
3144     public void setOnBufferingUpdateListener(OnBufferingUpdateListener listener)
3145     {
3146         mOnBufferingUpdateListener = listener;
3147     }
3148
3149     private OnBufferingUpdateListener mOnBufferingUpdateListener;
3150
3151     /**
3152      * Interface definition of a callback to be invoked indicating
3153      * the completion of a seek operation.
3154      */
3155     public interface OnSeekCompleteListener
3156     {
3157         /**
3158          * Called to indicate the completion of a seek operation.
3159          *
3160          * @param mp the MediaPlayer that issued the seek operation
3161          */
3162         public void onSeekComplete(MediaPlayer mp);
3163     }
3164
3165     /**
3166      * Register a callback to be invoked when a seek operation has been
3167      * completed.
3168      *
3169      * @param listener the callback that will be run
3170      */
3171     public void setOnSeekCompleteListener(OnSeekCompleteListener listener)
3172     {
3173         mOnSeekCompleteListener = listener;
3174     }
3175
3176     private OnSeekCompleteListener mOnSeekCompleteListener;
3177
3178     /**
3179      * Interface definition of a callback to be invoked when the
3180      * video size is first known or updated
3181      */
3182     public interface OnVideoSizeChangedListener
3183     {
3184         /**
3185          * Called to indicate the video size
3186          *
3187          * The video size (width and height) could be 0 if there was no video,
3188          * no display surface was set, or the value was not determined yet.
3189          *
3190          * @param mp        the MediaPlayer associated with this callback
3191          * @param width     the width of the video
3192          * @param height    the height of the video
3193          */
3194         public void onVideoSizeChanged(MediaPlayer mp, int width, int height);
3195     }
3196
3197     /**
3198      * Register a callback to be invoked when the video size is
3199      * known or updated.
3200      *
3201      * @param listener the callback that will be run
3202      */
3203     public void setOnVideoSizeChangedListener(OnVideoSizeChangedListener listener)
3204     {
3205         mOnVideoSizeChangedListener = listener;
3206     }
3207
3208     private OnVideoSizeChangedListener mOnVideoSizeChangedListener;
3209
3210     /**
3211      * Interface definition of a callback to be invoked when a
3212      * timed text is available for display.
3213      */
3214     public interface OnTimedTextListener
3215     {
3216         /**
3217          * Called to indicate an avaliable timed text
3218          *
3219          * @param mp             the MediaPlayer associated with this callback
3220          * @param text           the timed text sample which contains the text
3221          *                       needed to be displayed and the display format.
3222          */
3223         public void onTimedText(MediaPlayer mp, TimedText text);
3224     }
3225
3226     /**
3227      * Register a callback to be invoked when a timed text is available
3228      * for display.
3229      *
3230      * @param listener the callback that will be run
3231      */
3232     public void setOnTimedTextListener(OnTimedTextListener listener)
3233     {
3234         mOnTimedTextListener = listener;
3235     }
3236
3237     private OnTimedTextListener mOnTimedTextListener;
3238
3239     /**
3240      * Interface definition of a callback to be invoked when a
3241      * track has data available.
3242      *
3243      * @hide
3244      */
3245     public interface OnSubtitleDataListener
3246     {
3247         public void onSubtitleData(MediaPlayer mp, SubtitleData data);
3248     }
3249
3250     /**
3251      * Register a callback to be invoked when a track has data available.
3252      *
3253      * @param listener the callback that will be run
3254      *
3255      * @hide
3256      */
3257     public void setOnSubtitleDataListener(OnSubtitleDataListener listener)
3258     {
3259         mOnSubtitleDataListener = listener;
3260     }
3261
3262     private OnSubtitleDataListener mOnSubtitleDataListener;
3263
3264     /**
3265      * Interface definition of a callback to be invoked when a
3266      * track has timed metadata available.
3267      *
3268      * @see MediaPlayer#setOnTimedMetaDataAvailableListener(OnTimedMetaDataAvailableListener)
3269      */
3270     public interface OnTimedMetaDataAvailableListener
3271     {
3272         /**
3273          * Called to indicate avaliable timed metadata
3274          * <p>
3275          * This method will be called as timed metadata is extracted from the media,
3276          * in the same order as it occurs in the media. The timing of this event is
3277          * not controlled by the associated timestamp.
3278          *
3279          * @param mp             the MediaPlayer associated with this callback
3280          * @param data           the timed metadata sample associated with this event
3281          */
3282         public void onTimedMetaDataAvailable(MediaPlayer mp, TimedMetaData data);
3283     }
3284
3285     /**
3286      * Register a callback to be invoked when a selected track has timed metadata available.
3287      * <p>
3288      * Currently only HTTP live streaming data URI's embedded with timed ID3 tags generates
3289      * {@link TimedMetaData}.
3290      *
3291      * @see MediaPlayer#selectTrack(int)
3292      * @see MediaPlayer.OnTimedMetaDataAvailableListener
3293      * @see TimedMetaData
3294      *
3295      * @param listener the callback that will be run
3296      */
3297     public void setOnTimedMetaDataAvailableListener(OnTimedMetaDataAvailableListener listener)
3298     {
3299         mOnTimedMetaDataAvailableListener = listener;
3300     }
3301
3302     private OnTimedMetaDataAvailableListener mOnTimedMetaDataAvailableListener;
3303
3304     /* Do not change these values without updating their counterparts
3305      * in include/media/mediaplayer.h!
3306      */
3307     /** Unspecified media player error.
3308      * @see android.media.MediaPlayer.OnErrorListener
3309      */
3310     public static final int MEDIA_ERROR_UNKNOWN = 1;
3311
3312     /** Media server died. In this case, the application must release the
3313      * MediaPlayer object and instantiate a new one.
3314      * @see android.media.MediaPlayer.OnErrorListener
3315      */
3316     public static final int MEDIA_ERROR_SERVER_DIED = 100;
3317
3318     /** The video is streamed and its container is not valid for progressive
3319      * playback i.e the video's index (e.g moov atom) is not at the start of the
3320      * file.
3321      * @see android.media.MediaPlayer.OnErrorListener
3322      */
3323     public static final int MEDIA_ERROR_NOT_VALID_FOR_PROGRESSIVE_PLAYBACK = 200;
3324
3325     /** File or network related operation errors. */
3326     public static final int MEDIA_ERROR_IO = -1004;
3327     /** Bitstream is not conforming to the related coding standard or file spec. */
3328     public static final int MEDIA_ERROR_MALFORMED = -1007;
3329     /** Bitstream is conforming to the related coding standard or file spec, but
3330      * the media framework does not support the feature. */
3331     public static final int MEDIA_ERROR_UNSUPPORTED = -1010;
3332     /** Some operation takes too long to complete, usually more than 3-5 seconds. */
3333     public static final int MEDIA_ERROR_TIMED_OUT = -110;
3334
3335     /** Unspecified low-level system error. This value originated from UNKNOWN_ERROR in
3336      * system/core/include/utils/Errors.h
3337      * @see android.media.MediaPlayer.OnErrorListener
3338      * @hide
3339      */
3340     public static final int MEDIA_ERROR_SYSTEM = -2147483648;
3341
3342     /**
3343      * Interface definition of a callback to be invoked when there
3344      * has been an error during an asynchronous operation (other errors
3345      * will throw exceptions at method call time).
3346      */
3347     public interface OnErrorListener
3348     {
3349         /**
3350          * Called to indicate an error.
3351          *
3352          * @param mp      the MediaPlayer the error pertains to
3353          * @param what    the type of error that has occurred:
3354          * <ul>
3355          * <li>{@link #MEDIA_ERROR_UNKNOWN}
3356          * <li>{@link #MEDIA_ERROR_SERVER_DIED}
3357          * </ul>
3358          * @param extra an extra code, specific to the error. Typically
3359          * implementation dependent.
3360          * <ul>
3361          * <li>{@link #MEDIA_ERROR_IO}
3362          * <li>{@link #MEDIA_ERROR_MALFORMED}
3363          * <li>{@link #MEDIA_ERROR_UNSUPPORTED}
3364          * <li>{@link #MEDIA_ERROR_TIMED_OUT}
3365          * <li><code>MEDIA_ERROR_SYSTEM (-2147483648)</code> - low-level system error.
3366          * </ul>
3367          * @return True if the method handled the error, false if it didn't.
3368          * Returning false, or not having an OnErrorListener at all, will
3369          * cause the OnCompletionListener to be called.
3370          */
3371         boolean onError(MediaPlayer mp, int what, int extra);
3372     }
3373
3374     /**
3375      * Register a callback to be invoked when an error has happened
3376      * during an asynchronous operation.
3377      *
3378      * @param listener the callback that will be run
3379      */
3380     public void setOnErrorListener(OnErrorListener listener)
3381     {
3382         mOnErrorListener = listener;
3383     }
3384
3385     private OnErrorListener mOnErrorListener;
3386
3387
3388     /* Do not change these values without updating their counterparts
3389      * in include/media/mediaplayer.h!
3390      */
3391     /** Unspecified media player info.
3392      * @see android.media.MediaPlayer.OnInfoListener
3393      */
3394     public static final int MEDIA_INFO_UNKNOWN = 1;
3395
3396     /** The player was started because it was used as the next player for another
3397      * player, which just completed playback.
3398      * @see android.media.MediaPlayer.OnInfoListener
3399      * @hide
3400      */
3401     public static final int MEDIA_INFO_STARTED_AS_NEXT = 2;
3402
3403     /** The player just pushed the very first video frame for rendering.
3404      * @see android.media.MediaPlayer.OnInfoListener
3405      */
3406     public static final int MEDIA_INFO_VIDEO_RENDERING_START = 3;
3407
3408     /** The video is too complex for the decoder: it can't decode frames fast
3409      *  enough. Possibly only the audio plays fine at this stage.
3410      * @see android.media.MediaPlayer.OnInfoListener
3411      */
3412     public static final int MEDIA_INFO_VIDEO_TRACK_LAGGING = 700;
3413
3414     /** MediaPlayer is temporarily pausing playback internally in order to
3415      * buffer more data.
3416      * @see android.media.MediaPlayer.OnInfoListener
3417      */
3418     public static final int MEDIA_INFO_BUFFERING_START = 701;
3419
3420     /** MediaPlayer is resuming playback after filling buffers.
3421      * @see android.media.MediaPlayer.OnInfoListener
3422      */
3423     public static final int MEDIA_INFO_BUFFERING_END = 702;
3424
3425     /** Estimated network bandwidth information (kbps) is available; currently this event fires
3426      * simultaneously as {@link #MEDIA_INFO_BUFFERING_START} and {@link #MEDIA_INFO_BUFFERING_END}
3427      * when playing network files.
3428      * @see android.media.MediaPlayer.OnInfoListener
3429      * @hide
3430      */
3431     public static final int MEDIA_INFO_NETWORK_BANDWIDTH = 703;
3432
3433     /** Bad interleaving means that a media has been improperly interleaved or
3434      * not interleaved at all, e.g has all the video samples first then all the
3435      * audio ones. Video is playing but a lot of disk seeks may be happening.
3436      * @see android.media.MediaPlayer.OnInfoListener
3437      */
3438     public static final int MEDIA_INFO_BAD_INTERLEAVING = 800;
3439
3440     /** The media cannot be seeked (e.g live stream)
3441      * @see android.media.MediaPlayer.OnInfoListener
3442      */
3443     public static final int MEDIA_INFO_NOT_SEEKABLE = 801;
3444
3445     /** A new set of metadata is available.
3446      * @see android.media.MediaPlayer.OnInfoListener
3447      */
3448     public static final int MEDIA_INFO_METADATA_UPDATE = 802;
3449
3450     /** A new set of external-only metadata is available.  Used by
3451      *  JAVA framework to avoid triggering track scanning.
3452      * @hide
3453      */
3454     public static final int MEDIA_INFO_EXTERNAL_METADATA_UPDATE = 803;
3455
3456     /** Failed to handle timed text track properly.
3457      * @see android.media.MediaPlayer.OnInfoListener
3458      *
3459      * {@hide}
3460      */
3461     public static final int MEDIA_INFO_TIMED_TEXT_ERROR = 900;
3462
3463     /** Subtitle track was not supported by the media framework.
3464      * @see android.media.MediaPlayer.OnInfoListener
3465      */
3466     public static final int MEDIA_INFO_UNSUPPORTED_SUBTITLE = 901;
3467
3468     /** Reading the subtitle track takes too long.
3469      * @see android.media.MediaPlayer.OnInfoListener
3470      */
3471     public static final int MEDIA_INFO_SUBTITLE_TIMED_OUT = 902;
3472
3473     /**
3474      * Interface definition of a callback to be invoked to communicate some
3475      * info and/or warning about the media or its playback.
3476      */
3477     public interface OnInfoListener
3478     {
3479         /**
3480          * Called to indicate an info or a warning.
3481          *
3482          * @param mp      the MediaPlayer the info pertains to.
3483          * @param what    the type of info or warning.
3484          * <ul>
3485          * <li>{@link #MEDIA_INFO_UNKNOWN}
3486          * <li>{@link #MEDIA_INFO_VIDEO_TRACK_LAGGING}
3487          * <li>{@link #MEDIA_INFO_VIDEO_RENDERING_START}
3488          * <li>{@link #MEDIA_INFO_BUFFERING_START}
3489          * <li>{@link #MEDIA_INFO_BUFFERING_END}
3490          * <li><code>MEDIA_INFO_NETWORK_BANDWIDTH (703)</code> -
3491          *     bandwidth information is available (as <code>extra</code> kbps)
3492          * <li>{@link #MEDIA_INFO_BAD_INTERLEAVING}
3493          * <li>{@link #MEDIA_INFO_NOT_SEEKABLE}
3494          * <li>{@link #MEDIA_INFO_METADATA_UPDATE}
3495          * <li>{@link #MEDIA_INFO_UNSUPPORTED_SUBTITLE}
3496          * <li>{@link #MEDIA_INFO_SUBTITLE_TIMED_OUT}
3497          * </ul>
3498          * @param extra an extra code, specific to the info. Typically
3499          * implementation dependent.
3500          * @return True if the method handled the info, false if it didn't.
3501          * Returning false, or not having an OnInfoListener at all, will
3502          * cause the info to be discarded.
3503          */
3504         boolean onInfo(MediaPlayer mp, int what, int extra);
3505     }
3506
3507     /**
3508      * Register a callback to be invoked when an info/warning is available.
3509      *
3510      * @param listener the callback that will be run
3511      */
3512     public void setOnInfoListener(OnInfoListener listener)
3513     {
3514         mOnInfoListener = listener;
3515     }
3516
3517     private OnInfoListener mOnInfoListener;
3518
3519     /*
3520      * Test whether a given video scaling mode is supported.
3521      */
3522     private boolean isVideoScalingModeSupported(int mode) {
3523         return (mode == VIDEO_SCALING_MODE_SCALE_TO_FIT ||
3524                 mode == VIDEO_SCALING_MODE_SCALE_TO_FIT_WITH_CROPPING);
3525     }
3526
3527     /** @hide */
3528     static class TimeProvider implements MediaPlayer.OnSeekCompleteListener,
3529             MediaTimeProvider {
3530         private static final String TAG = "MTP";
3531         private static final long MAX_NS_WITHOUT_POSITION_CHECK = 5000000000L;
3532         private static final long MAX_EARLY_CALLBACK_US = 1000;
3533         private static final long TIME_ADJUSTMENT_RATE = 2;  /* meaning 1/2 */
3534         private long mLastTimeUs = 0;
3535         private MediaPlayer mPlayer;
3536         private boolean mPaused = true;
3537         private boolean mStopped = true;
3538         private boolean mBuffering;
3539         private long mLastReportedTime;
3540         private long mTimeAdjustment;
3541         // since we are expecting only a handful listeners per stream, there is
3542         // no need for log(N) search performance
3543         private MediaTimeProvider.OnMediaTimeListener mListeners[];
3544         private long mTimes[];
3545         private long mLastNanoTime;
3546         private Handler mEventHandler;
3547         private boolean mRefresh = false;
3548         private boolean mPausing = false;
3549         private boolean mSeeking = false;
3550         private static final int NOTIFY = 1;
3551         private static final int NOTIFY_TIME = 0;
3552         private static final int REFRESH_AND_NOTIFY_TIME = 1;
3553         private static final int NOTIFY_STOP = 2;
3554         private static final int NOTIFY_SEEK = 3;
3555         private static final int NOTIFY_TRACK_DATA = 4;
3556         private HandlerThread mHandlerThread;
3557
3558         /** @hide */
3559         public boolean DEBUG = false;
3560
3561         public TimeProvider(MediaPlayer mp) {
3562             mPlayer = mp;
3563             try {
3564                 getCurrentTimeUs(true, false);
3565             } catch (IllegalStateException e) {
3566                 // we assume starting position
3567                 mRefresh = true;
3568             }
3569
3570             Looper looper;
3571             if ((looper = Looper.myLooper()) == null &&
3572                 (looper = Looper.getMainLooper()) == null) {
3573                 // Create our own looper here in case MP was created without one
3574                 mHandlerThread = new HandlerThread("MediaPlayerMTPEventThread",
3575                       Process.THREAD_PRIORITY_FOREGROUND);
3576                 mHandlerThread.start();
3577                 looper = mHandlerThread.getLooper();
3578             }
3579             mEventHandler = new EventHandler(looper);
3580
3581             mListeners = new MediaTimeProvider.OnMediaTimeListener[0];
3582             mTimes = new long[0];
3583             mLastTimeUs = 0;
3584             mTimeAdjustment = 0;
3585         }
3586
3587         private void scheduleNotification(int type, long delayUs) {
3588             // ignore time notifications until seek is handled
3589             if (mSeeking &&
3590                     (type == NOTIFY_TIME || type == REFRESH_AND_NOTIFY_TIME)) {
3591                 return;
3592             }
3593
3594             if (DEBUG) Log.v(TAG, "scheduleNotification " + type + " in " + delayUs);
3595             mEventHandler.removeMessages(NOTIFY);
3596             Message msg = mEventHandler.obtainMessage(NOTIFY, type, 0);
3597             mEventHandler.sendMessageDelayed(msg, (int) (delayUs / 1000));
3598         }
3599
3600         /** @hide */
3601         public void close() {
3602             mEventHandler.removeMessages(NOTIFY);
3603             if (mHandlerThread != null) {
3604                 mHandlerThread.quitSafely();
3605                 mHandlerThread = null;
3606             }
3607         }
3608
3609         /** @hide */
3610         protected void finalize() {
3611             if (mHandlerThread != null) {
3612                 mHandlerThread.quitSafely();
3613             }
3614         }
3615
3616         /** @hide */
3617         public void onPaused(boolean paused) {
3618             synchronized(this) {
3619                 if (DEBUG) Log.d(TAG, "onPaused: " + paused);
3620                 if (mStopped) { // handle as seek if we were stopped
3621                     mStopped = false;
3622                     mSeeking = true;
3623                     scheduleNotification(NOTIFY_SEEK, 0 /* delay */);
3624                 } else {
3625                     mPausing = paused;  // special handling if player disappeared
3626                     mSeeking = false;
3627                     scheduleNotification(REFRESH_AND_NOTIFY_TIME, 0 /* delay */);
3628                 }
3629             }
3630         }
3631
3632         /** @hide */
3633         public void onBuffering(boolean buffering) {
3634             synchronized (this) {
3635                 if (DEBUG) Log.d(TAG, "onBuffering: " + buffering);
3636                 mBuffering = buffering;
3637                 scheduleNotification(REFRESH_AND_NOTIFY_TIME, 0 /* delay */);
3638             }
3639         }
3640
3641         /** @hide */
3642         public void onStopped() {
3643             synchronized(this) {
3644                 if (DEBUG) Log.d(TAG, "onStopped");
3645                 mPaused = true;
3646                 mStopped = true;
3647                 mSeeking = false;
3648                 mBuffering = false;
3649                 scheduleNotification(NOTIFY_STOP, 0 /* delay */);
3650             }
3651         }
3652
3653         /** @hide */
3654         @Override
3655         public void onSeekComplete(MediaPlayer mp) {
3656             synchronized(this) {
3657                 mStopped = false;
3658                 mSeeking = true;
3659                 scheduleNotification(NOTIFY_SEEK, 0 /* delay */);
3660             }
3661         }
3662
3663         /** @hide */
3664         public void onNewPlayer() {
3665             if (mRefresh) {
3666                 synchronized(this) {
3667                     mStopped = false;
3668                     mSeeking = true;
3669                     mBuffering = false;
3670                     scheduleNotification(NOTIFY_SEEK, 0 /* delay */);
3671                 }
3672             }
3673         }
3674
3675         private synchronized void notifySeek() {
3676             mSeeking = false;
3677             try {
3678                 long timeUs = getCurrentTimeUs(true, false);
3679                 if (DEBUG) Log.d(TAG, "onSeekComplete at " + timeUs);
3680
3681                 for (MediaTimeProvider.OnMediaTimeListener listener: mListeners) {
3682                     if (listener == null) {
3683                         break;
3684                     }
3685                     listener.onSeek(timeUs);
3686                 }
3687             } catch (IllegalStateException e) {
3688                 // we should not be there, but at least signal pause
3689                 if (DEBUG) Log.d(TAG, "onSeekComplete but no player");
3690                 mPausing = true;  // special handling if player disappeared
3691                 notifyTimedEvent(false /* refreshTime */);
3692             }
3693         }
3694
3695         private synchronized void notifyTrackData(Pair<SubtitleTrack, byte[]> trackData) {
3696             SubtitleTrack track = trackData.first;
3697             byte[] data = trackData.second;
3698             track.onData(data, true /* eos */, ~0 /* runID: keep forever */);
3699         }
3700
3701         private synchronized void notifyStop() {
3702             for (MediaTimeProvider.OnMediaTimeListener listener: mListeners) {
3703                 if (listener == null) {
3704                     break;
3705                 }
3706                 listener.onStop();
3707             }
3708         }
3709
3710         private int registerListener(MediaTimeProvider.OnMediaTimeListener listener) {
3711             int i = 0;
3712             for (; i < mListeners.length; i++) {
3713                 if (mListeners[i] == listener || mListeners[i] == null) {
3714                     break;
3715                 }
3716             }
3717
3718             // new listener
3719             if (i >= mListeners.length) {
3720                 MediaTimeProvider.OnMediaTimeListener[] newListeners =
3721                     new MediaTimeProvider.OnMediaTimeListener[i + 1];
3722                 long[] newTimes = new long[i + 1];
3723                 System.arraycopy(mListeners, 0, newListeners, 0, mListeners.length);
3724                 System.arraycopy(mTimes, 0, newTimes, 0, mTimes.length);
3725                 mListeners = newListeners;
3726                 mTimes = newTimes;
3727             }
3728
3729             if (mListeners[i] == null) {
3730                 mListeners[i] = listener;
3731                 mTimes[i] = MediaTimeProvider.NO_TIME;
3732             }
3733             return i;
3734         }
3735
3736         public void notifyAt(
3737                 long timeUs, MediaTimeProvider.OnMediaTimeListener listener) {
3738             synchronized(this) {
3739                 if (DEBUG) Log.d(TAG, "notifyAt " + timeUs);
3740                 mTimes[registerListener(listener)] = timeUs;
3741                 scheduleNotification(NOTIFY_TIME, 0 /* delay */);
3742             }
3743         }
3744
3745         public void scheduleUpdate(MediaTimeProvider.OnMediaTimeListener listener) {
3746             synchronized(this) {
3747                 if (DEBUG) Log.d(TAG, "scheduleUpdate");
3748                 int i = registerListener(listener);
3749
3750                 if (!mStopped) {
3751                     mTimes[i] = 0;
3752                     scheduleNotification(NOTIFY_TIME, 0 /* delay */);
3753                 }
3754             }
3755         }
3756
3757         public void cancelNotifications(
3758                 MediaTimeProvider.OnMediaTimeListener listener) {
3759             synchronized(this) {
3760                 int i = 0;
3761                 for (; i < mListeners.length; i++) {
3762                     if (mListeners[i] == listener) {
3763                         System.arraycopy(mListeners, i + 1,
3764                                 mListeners, i, mListeners.length - i - 1);
3765                         System.arraycopy(mTimes, i + 1,
3766                                 mTimes, i, mTimes.length - i - 1);
3767                         mListeners[mListeners.length - 1] = null;
3768                         mTimes[mTimes.length - 1] = NO_TIME;
3769                         break;
3770                     } else if (mListeners[i] == null) {
3771                         break;
3772                     }
3773                 }
3774
3775                 scheduleNotification(NOTIFY_TIME, 0 /* delay */);
3776             }
3777         }
3778
3779         private synchronized void notifyTimedEvent(boolean refreshTime) {
3780             // figure out next callback
3781             long nowUs;
3782             try {
3783                 nowUs = getCurrentTimeUs(refreshTime, true);
3784             } catch (IllegalStateException e) {
3785                 // assume we paused until new player arrives
3786                 mRefresh = true;
3787                 mPausing = true; // this ensures that call succeeds
3788                 nowUs = getCurrentTimeUs(refreshTime, true);
3789             }
3790             long nextTimeUs = nowUs;
3791
3792             if (mSeeking) {
3793                 // skip timed-event notifications until seek is complete
3794                 return;
3795             }
3796
3797             if (DEBUG) {
3798                 StringBuilder sb = new StringBuilder();
3799                 sb.append("notifyTimedEvent(").append(mLastTimeUs).append(" -> ")
3800                         .append(nowUs).append(") from {");
3801                 boolean first = true;
3802                 for (long time: mTimes) {
3803                     if (time == NO_TIME) {
3804                         continue;
3805                     }
3806                     if (!first) sb.append(", ");
3807                     sb.append(time);
3808                     first = false;
3809                 }
3810                 sb.append("}");
3811                 Log.d(TAG, sb.toString());
3812             }
3813
3814             Vector<MediaTimeProvider.OnMediaTimeListener> activatedListeners =
3815                 new Vector<MediaTimeProvider.OnMediaTimeListener>();
3816             for (int ix = 0; ix < mTimes.length; ix++) {
3817                 if (mListeners[ix] == null) {
3818                     break;
3819                 }
3820                 if (mTimes[ix] <= NO_TIME) {
3821                     // ignore, unless we were stopped
3822                 } else if (mTimes[ix] <= nowUs + MAX_EARLY_CALLBACK_US) {
3823                     activatedListeners.add(mListeners[ix]);
3824                     if (DEBUG) Log.d(TAG, "removed");
3825                     mTimes[ix] = NO_TIME;
3826                 } else if (nextTimeUs == nowUs || mTimes[ix] < nextTimeUs) {
3827                     nextTimeUs = mTimes[ix];
3828                 }
3829             }
3830
3831             if (nextTimeUs > nowUs && !mPaused) {
3832                 // schedule callback at nextTimeUs
3833                 if (DEBUG) Log.d(TAG, "scheduling for " + nextTimeUs + " and " + nowUs);
3834                 scheduleNotification(NOTIFY_TIME, nextTimeUs - nowUs);
3835             } else {
3836                 mEventHandler.removeMessages(NOTIFY);
3837                 // no more callbacks
3838             }
3839
3840             for (MediaTimeProvider.OnMediaTimeListener listener: activatedListeners) {
3841                 listener.onTimedEvent(nowUs);
3842             }
3843         }
3844
3845         private long getEstimatedTime(long nanoTime, boolean monotonic) {
3846             if (mPaused) {
3847                 mLastReportedTime = mLastTimeUs + mTimeAdjustment;
3848             } else {
3849                 long timeSinceRead = (nanoTime - mLastNanoTime) / 1000;
3850                 mLastReportedTime = mLastTimeUs + timeSinceRead;
3851                 if (mTimeAdjustment > 0) {
3852                     long adjustment =
3853                         mTimeAdjustment - timeSinceRead / TIME_ADJUSTMENT_RATE;
3854                     if (adjustment <= 0) {
3855                         mTimeAdjustment = 0;
3856                     } else {
3857                         mLastReportedTime += adjustment;
3858                     }
3859                 }
3860             }
3861             return mLastReportedTime;
3862         }
3863
3864         public long getCurrentTimeUs(boolean refreshTime, boolean monotonic)
3865                 throws IllegalStateException {
3866             synchronized (this) {
3867                 // we always refresh the time when the paused-state changes, because
3868                 // we expect to have received the pause-change event delayed.
3869                 if (mPaused && !refreshTime) {
3870                     return mLastReportedTime;
3871                 }
3872
3873                 long nanoTime = System.nanoTime();
3874                 if (refreshTime ||
3875                         nanoTime >= mLastNanoTime + MAX_NS_WITHOUT_POSITION_CHECK) {
3876                     try {
3877                         mLastTimeUs = mPlayer.getCurrentPosition() * 1000L;
3878                         mPaused = !mPlayer.isPlaying() || mBuffering;
3879                         if (DEBUG) Log.v(TAG, (mPaused ? "paused" : "playing") + " at " + mLastTimeUs);
3880                     } catch (IllegalStateException e) {
3881                         if (mPausing) {
3882                             // if we were pausing, get last estimated timestamp
3883                             mPausing = false;
3884                             getEstimatedTime(nanoTime, monotonic);
3885                             mPaused = true;
3886                             if (DEBUG) Log.d(TAG, "illegal state, but pausing: estimating at " + mLastReportedTime);
3887                             return mLastReportedTime;
3888                         }
3889                         // TODO get time when prepared
3890                         throw e;
3891                     }
3892                     mLastNanoTime = nanoTime;
3893                     if (monotonic && mLastTimeUs < mLastReportedTime) {
3894                         /* have to adjust time */
3895                         mTimeAdjustment = mLastReportedTime - mLastTimeUs;
3896                         if (mTimeAdjustment > 1000000) {
3897                             // schedule seeked event if time jumped significantly
3898                             // TODO: do this properly by introducing an exception
3899                             mStopped = false;
3900                             mSeeking = true;
3901                             scheduleNotification(NOTIFY_SEEK, 0 /* delay */);
3902                         }
3903                     } else {
3904                         mTimeAdjustment = 0;
3905                     }
3906                 }
3907
3908                 return getEstimatedTime(nanoTime, monotonic);
3909             }
3910         }
3911
3912         private class EventHandler extends Handler {
3913             public EventHandler(Looper looper) {
3914                 super(looper);
3915             }
3916
3917             @Override
3918             public void handleMessage(Message msg) {
3919                 if (msg.what == NOTIFY) {
3920                     switch (msg.arg1) {
3921                     case NOTIFY_TIME:
3922                         notifyTimedEvent(false /* refreshTime */);
3923                         break;
3924                     case REFRESH_AND_NOTIFY_TIME:
3925                         notifyTimedEvent(true /* refreshTime */);
3926                         break;
3927                     case NOTIFY_STOP:
3928                         notifyStop();
3929                         break;
3930                     case NOTIFY_SEEK:
3931                         notifySeek();
3932                         break;
3933                     case NOTIFY_TRACK_DATA:
3934                         notifyTrackData((Pair<SubtitleTrack, byte[]>)msg.obj);
3935                         break;
3936                     }
3937                 }
3938             }
3939         }
3940     }
3941 }