1/* 2 * Copyright 2018 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 17package androidx.media; 18 19import static androidx.annotation.RestrictTo.Scope.LIBRARY_GROUP; 20 21import android.annotation.TargetApi; 22import android.graphics.SurfaceTexture; 23import android.media.AudioAttributes; 24import android.media.DeniedByServerException; 25import android.media.MediaDrm; 26import android.media.MediaDrmException; 27import android.media.MediaFormat; 28import android.media.MediaTimestamp; 29import android.media.PlaybackParams; 30import android.media.ResourceBusyException; 31import android.media.SubtitleData; 32import android.media.SyncParams; 33import android.media.TimedMetaData; 34import android.media.UnsupportedSchemeException; 35import android.os.Build; 36import android.os.PersistableBundle; 37import android.view.Surface; 38 39import androidx.annotation.IntDef; 40import androidx.annotation.NonNull; 41import androidx.annotation.Nullable; 42import androidx.annotation.RestrictTo; 43 44import java.lang.annotation.Retention; 45import java.lang.annotation.RetentionPolicy; 46import java.util.List; 47import java.util.Map; 48import java.util.UUID; 49import java.util.concurrent.Executor; 50 51/** 52 * MediaPlayer2 class can be used to control playback of audio/video files and streams. 53 * 54 * <p>Topics covered here are: 55 * <ol> 56 * <li><a href="#StateDiagram">State Diagram</a> 57 * <li><a href="#Permissions">Permissions</a> 58 * <li><a href="#Callbacks">Register informational and error callbacks</a> 59 * </ol> 60 * 61 * <a name="StateDiagram"></a> 62 * <h3>State Diagram</h3> 63 * 64 * <p>Playback control of audio/video files and streams is managed as a state 65 * machine. The following diagram shows the life cycle and the states of a 66 * MediaPlayer2 object driven by the supported playback control operations. 67 * The ovals represent the states a MediaPlayer2 object may reside 68 * in. The arcs represent the playback control operations that drive the object 69 * state transition. There are two types of arcs. The arcs with a single arrow 70 * head represent synchronous method calls, while those with 71 * a double arrow head represent asynchronous method calls.</p> 72 * 73 * <p><img src="../../../images/mediaplayer_state_diagram.gif" 74 * alt="MediaPlayer State diagram" 75 * border="0" /></p> 76 * 77 * <p>From this state diagram, one can see that a MediaPlayer2 object has the 78 * following states:</p> 79 * <ul> 80 * <li>When a MediaPlayer2 object is just created using {@link #create()} or 81 * after {@link #reset()} is called, it is in the <strong>Idle</strong> state; and Once 82 * {@link #close()} is called, it can no longer be used and there is no way to bring it 83 * back to any other state. 84 * <ul> 85 * <li>Calling {@link #setDataSource(DataSourceDesc)} and {@link #prepare()} transfers a 86 * MediaPlayer2 object in the <strong>Idle</strong> state to the <strong>Paused</strong> 87 * state. It is good programming practice to register a event callback for 88 * {@link MediaPlayer2EventCallback#onCallCompleted} and 89 * look out for {@link #CALL_STATUS_BAD_VALUE} and {@link #CALL_STATUS_ERROR_IO} that may be 90 * caused from {@link #setDataSource}. 91 * </li> 92 * <li>It is also recommended that once 93 * a MediaPlayer2 object is no longer being used, call {@link #close()} immediately 94 * so that resources used by the internal player engine associated with the 95 * MediaPlayer2 object can be released immediately. Resource may include 96 * singleton resources such as hardware acceleration components and 97 * failure to call {@link #close()} may cause subsequent instances of 98 * MediaPlayer2 objects to fallback to software implementations or fail 99 * altogether. </li> 100 * </ul> 101 * </li> 102 * <li>In general, some playback control operation may fail due to various 103 * reasons, such as unsupported audio/video format, poorly interleaved 104 * audio/video, resolution too high, streaming timeout, and the like. 105 * Thus, error reporting and recovery is an important concern under 106 * these circumstances. Sometimes, due to programming errors, invoking a playback 107 * control operation in an invalid state may also occur. Under all these 108 * error conditions, the player goes to <strong>Error</strong> state and invokes a user 109 * supplied {@link MediaPlayer2EventCallback#onError}} method if an event callback has been 110 * registered beforehand via {@link #setMediaPlayer2EventCallback}. 111 * <ul> 112 * <li>It is important to note that once an error occurs, the 113 * MediaPlayer2 object enters the <strong>Error</strong> state (except as noted 114 * above), even if a callback has not been registered by the application.</li> 115 * <li>In order to reuse a MediaPlayer2 object that is in the <strong> 116 * Error</strong> state and recover from the error, 117 * {@link #reset()} can be called to restore the object to its <strong>Idle</strong> 118 * state.</li> 119 * <li>It is good programming practice to have your application 120 * register a {@link MediaPlayer2EventCallback} to look out for error callbacks from 121 * the internal player engine.</li> 122 * <li> {@link MediaPlayer2EventCallback#onCallCompleted} is called with 123 * {@link #CALL_STATUS_INVALID_OPERATION} on programming errors such as calling 124 * {@link #prepare()} and {@link #setDataSource(DataSourceDesc)} methods in an invalid 125 * state. </li> 126 * </ul> 127 * </li> 128 * <li>A MediaPlayer2 object must first enter the <strong>Paused</strong> state 129 * before playback can be started. 130 * <ul> 131 * <li>The <strong>Paused</strong> state can be reached by calling {@link #prepare()}. Note 132 * that {@link #prepare()} is asynchronous. When the preparation completes, 133 * the internal player engine then calls a user supplied callback method, 134 * {@link MediaPlayer2EventCallback#onInfo} interface with {@link #MEDIA_INFO_PREPARED}, 135 * if a MediaPlayer2EventCallback is registered beforehand via 136 * {@link #setMediaPlayer2EventCallback(Executor, MediaPlayer2EventCallback)}.</li> 137 * <li>The player also goes to <strong>Paused</strong> state when {@link #pause()} is called 138 * to pause the ongoing playback. Note that {@link #pause()} is asynchronous. Once 139 * {@link #pause()} is processed successfully by the internal media engine, 140 * <strong>Paused</strong> state will be notified with 141 * {@link MediaPlayerInterface.PlayerEventCallback#onPlayerStateChanged} callback. 142 * In addition to the callback, {@link #getMediaPlayer2State()} can also be used to test 143 * whether the MediaPlayer2 object is in the <strong>Paused</strong> state. 144 * </li> 145 * <li>While in the <em>Paused</em> state, properties such as audio/sound volume, looping 146 * can be adjusted by invoking the corresponding set methods.</li> 147 * </ul> 148 * </li> 149 * <li>To start the playback, {@link #play()} must be called. Once {@link #play()} is processed 150 * successfully by the internal media engine, <strong>Playing</strong> state will be 151 * notified with {@link MediaPlayerInterface.PlayerEventCallback#onPlayerStateChanged} 152 * callback. 153 * In addition to the callback, {@link #getMediaPlayer2State()} can be called to test 154 * whether the MediaPlayer2 object is in the <strong>Started</strong> state. 155 * <ul> 156 * <li>While in the <strong>Playing</strong> state, the internal player engine calls 157 * a user supplied callback method MediaPlayer2EventCallback.onInfo() with 158 * {@link #MEDIA_INFO_BUFFERING_UPDATE} if an MediaPlayer2EventCallback has been 159 * registered beforehand via 160 * {@link #setMediaPlayer2EventCallback(Executor, MediaPlayer2EventCallback)}. 161 * This callback allows applications to keep track of the buffering status 162 * while streaming audio/video.</li> 163 * <li>Calling {@link #play()} has not effect 164 * on a MediaPlayer2 object that is already in the <strong>Playing</strong> state.</li> 165 * </ul> 166 * </li> 167 * <li>The playback position can be adjusted with a call to {@link #seekTo}. 168 * <ul> 169 * <li>Although the asynchronous {@link #seekTo} call returns right away, 170 * the actual seek operation may take a while to 171 * finish, especially for audio/video being streamed. When the actual 172 * seek operation completes, the internal player engine calls a user 173 * supplied MediaPlayer2EventCallback.onCallCompleted() with 174 * {@link #CALL_COMPLETED_SEEK_TO} 175 * if an MediaPlayer2EventCallback has been registered beforehand via 176 * {@link #setMediaPlayer2EventCallback(Executor, MediaPlayer2EventCallback)}.</li> 177 * <li>Please note that {@link #seekTo(long, int)} can also be called in 178 * <strong>Paused</strong> state. When {@link #seekTo(long, int)} is called in those states, 179 * one video frame will be displayed if the stream has video and the requested 180 * position is valid. 181 * </li> 182 * <li>Furthermore, the actual current playback position 183 * can be retrieved with a call to {@link #getCurrentPosition()}, which 184 * is helpful for applications such as a Music player that need to keep 185 * track of the playback progress.</li> 186 * </ul> 187 * </li> 188 * <li>When the playback reaches the end of stream, the playback completes. 189 * <ul> 190 * <li>If current source is set to loop by {@link #loopCurrent(boolean)}, 191 * the MediaPlayer2 object shall remain in the <strong>Playing</strong> state.</li> 192 * <li>If the looping mode was set to <var>false 193 * </var>, the player engine calls a user supplied callback method, 194 * {@link MediaPlayer2EventCallback#onInfo} with {@link #MEDIA_INFO_PLAYBACK_COMPLETE}, 195 * if an MediaPlayer2EventCallback is registered beforehand via 196 * {@link #setMediaPlayer2EventCallback(Executor, MediaPlayer2EventCallback)}. 197 * The invoke of the callback signals that the object is now in the <strong>Paused</strong> 198 * state.</li> 199 * <li>While in the <strong>Paused</strong> state, calling {@link #play()} can restart the 200 * playback from the beginning of the audio/video source.</li> 201 * </ul> 202 * 203 * <a name="Permissions"></a> 204 * <h3>Permissions</h3> 205 * <p>This class requires the {@link android.Manifest.permission#INTERNET} permission 206 * when used with network-based content. 207 * 208 * <a name="Callbacks"></a> 209 * <h3>Callbacks</h3> 210 * <p>Applications may want to register for informational and error 211 * events in order to be informed of some internal state update and 212 * possible runtime errors during playback or streaming. Registration for 213 * these events is done by properly setting the appropriate listeners (via calls 214 * to 215 * {@link #setMediaPlayer2EventCallback(Executor, MediaPlayer2EventCallback)}, 216 * {@link #setDrmEventCallback(Executor, DrmEventCallback)}). 217 * In order to receive the respective callback 218 * associated with these listeners, applications are required to create 219 * MediaPlayer2 objects on a thread with its own Looper running (main UI 220 * thread by default has a Looper running). 221 * 222 */ 223@TargetApi(Build.VERSION_CODES.P) 224public abstract class MediaPlayer2 { 225 /** 226 * Create a MediaPlayer2 object. 227 * 228 * @return A MediaPlayer2 object created 229 */ 230 public static final MediaPlayer2 create() { 231 return new MediaPlayer2Impl(); 232 } 233 234 /** 235 * @hide 236 */ 237 @RestrictTo(LIBRARY_GROUP) 238 public MediaPlayer2() { } 239 240 /** 241 * Returns a {@link MediaPlayerInterface} implementation which runs based on 242 * this MediaPlayer2 instance. 243 */ 244 public abstract MediaPlayerInterface getMediaPlayerInterface(); 245 246 /** 247 * Releases the resources held by this {@code MediaPlayer2} object. 248 * 249 * It is considered good practice to call this method when you're 250 * done using the MediaPlayer2. In particular, whenever an Activity 251 * of an application is paused (its onPause() method is called), 252 * or stopped (its onStop() method is called), this method should be 253 * invoked to release the MediaPlayer2 object, unless the application 254 * has a special need to keep the object around. In addition to 255 * unnecessary resources (such as memory and instances of codecs) 256 * being held, failure to call this method immediately if a 257 * MediaPlayer2 object is no longer needed may also lead to 258 * continuous battery consumption for mobile devices, and playback 259 * failure for other applications if no multiple instances of the 260 * same codec are supported on a device. Even if multiple instances 261 * of the same codec are supported, some performance degradation 262 * may be expected when unnecessary multiple instances are used 263 * at the same time. 264 */ 265 // This is a synchronous call. 266 public abstract void close(); 267 268 /** 269 * Starts or resumes playback. If playback had previously been paused, 270 * playback will continue from where it was paused. If playback had 271 * reached end of stream and been paused, or never started before, 272 * playback will start at the beginning. If the source had not been 273 * prepared, the player will prepare the source and play. 274 * 275 */ 276 // This is an asynchronous call. 277 public abstract void play(); 278 279 /** 280 * Prepares the player for playback, asynchronously. 281 * 282 * After setting the datasource and the display surface, you need to 283 * call prepare(). 284 * 285 */ 286 // This is an asynchronous call. 287 public abstract void prepare(); 288 289 /** 290 * Pauses playback. Call play() to resume. 291 */ 292 // This is an asynchronous call. 293 public abstract void pause(); 294 295 /** 296 * Tries to play next data source if applicable. 297 */ 298 // This is an asynchronous call. 299 public abstract void skipToNext(); 300 301 /** 302 * Moves the media to specified time position. 303 * Same as {@link #seekTo(long, int)} with {@code mode = SEEK_PREVIOUS_SYNC}. 304 * 305 * @param msec the offset in milliseconds from the start to seek to 306 */ 307 // This is an asynchronous call. 308 public void seekTo(long msec) { 309 seekTo(msec, SEEK_PREVIOUS_SYNC /* mode */); 310 } 311 312 /** 313 * Gets the current playback position. 314 * 315 * @return the current position in milliseconds 316 */ 317 public abstract long getCurrentPosition(); 318 319 /** 320 * Gets the duration of the file. 321 * 322 * @return the duration in milliseconds, if no duration is available 323 * (for example, if streaming live content), -1 is returned. 324 */ 325 public abstract long getDuration(); 326 327 /** 328 * Gets the current buffered media source position received through progressive downloading. 329 * The received buffering percentage indicates how much of the content has been buffered 330 * or played. For example a buffering update of 80 percent when half the content 331 * has already been played indicates that the next 30 percent of the 332 * content to play has been buffered. 333 * 334 * @return the current buffered media source position in milliseconds 335 */ 336 public abstract long getBufferedPosition(); 337 338 /** 339 * Gets the current MediaPlayer2 state. 340 * 341 * @return the current MediaPlayer2 state. 342 */ 343 public abstract @MediaPlayer2State int getMediaPlayer2State(); 344 345 /** 346 * Sets the audio attributes for this MediaPlayer2. 347 * See {@link AudioAttributes} for how to build and configure an instance of this class. 348 * You must call this method before {@link #prepare()} in order 349 * for the audio attributes to become effective thereafter. 350 * @param attributes a non-null set of audio attributes 351 */ 352 // This is an asynchronous call. 353 public abstract void setAudioAttributes(@NonNull AudioAttributesCompat attributes); 354 355 /** 356 * Gets the audio attributes for this MediaPlayer2. 357 * @return attributes a set of audio attributes 358 */ 359 public abstract @Nullable AudioAttributesCompat getAudioAttributes(); 360 361 /** 362 * Sets the data source as described by a DataSourceDesc. 363 * 364 * @param dsd the descriptor of data source you want to play 365 */ 366 // This is an asynchronous call. 367 public abstract void setDataSource(@NonNull DataSourceDesc dsd); 368 369 /** 370 * Sets a single data source as described by a DataSourceDesc which will be played 371 * after current data source is finished. 372 * 373 * @param dsd the descriptor of data source you want to play after current one 374 */ 375 // This is an asynchronous call. 376 public abstract void setNextDataSource(@NonNull DataSourceDesc dsd); 377 378 /** 379 * Sets a list of data sources to be played sequentially after current data source is done. 380 * 381 * @param dsds the list of data sources you want to play after current one 382 */ 383 // This is an asynchronous call. 384 public abstract void setNextDataSources(@NonNull List<DataSourceDesc> dsds); 385 386 /** 387 * Gets the current data source as described by a DataSourceDesc. 388 * 389 * @return the current DataSourceDesc 390 */ 391 public abstract @NonNull DataSourceDesc getCurrentDataSource(); 392 393 /** 394 * Configures the player to loop on the current data source. 395 * @param loop true if the current data source is meant to loop. 396 */ 397 // This is an asynchronous call. 398 public abstract void loopCurrent(boolean loop); 399 400 /** 401 * Sets the playback speed. 402 * A value of 1.0f is the default playback value. 403 * A negative value indicates reverse playback, check {@link #isReversePlaybackSupported()} 404 * before using negative values.<br> 405 * After changing the playback speed, it is recommended to query the actual speed supported 406 * by the player, see {@link #getPlaybackSpeed()}. 407 * @param speed the desired playback speed 408 */ 409 // This is an asynchronous call. 410 public abstract void setPlaybackSpeed(float speed); 411 412 /** 413 * Returns the actual playback speed to be used by the player when playing. 414 * Note that it may differ from the speed set in {@link #setPlaybackSpeed(float)}. 415 * @return the actual playback speed 416 */ 417 public float getPlaybackSpeed() { 418 return 1.0f; 419 } 420 421 /** 422 * Indicates whether reverse playback is supported. 423 * Reverse playback is indicated by negative playback speeds, see 424 * {@link #setPlaybackSpeed(float)}. 425 * @return true if reverse playback is supported. 426 */ 427 public boolean isReversePlaybackSupported() { 428 return false; 429 } 430 431 /** 432 * Sets the volume of the audio of the media to play, expressed as a linear multiplier 433 * on the audio samples. 434 * Note that this volume is specific to the player, and is separate from stream volume 435 * used across the platform.<br> 436 * A value of 0.0f indicates muting, a value of 1.0f is the nominal unattenuated and unamplified 437 * gain. See {@link #getMaxPlayerVolume()} for the volume range supported by this player. 438 * @param volume a value between 0.0f and {@link #getMaxPlayerVolume()}. 439 */ 440 // This is an asynchronous call. 441 public abstract void setPlayerVolume(float volume); 442 443 /** 444 * Returns the current volume of this player to this player. 445 * Note that it does not take into account the associated stream volume. 446 * @return the player volume. 447 */ 448 public abstract float getPlayerVolume(); 449 450 /** 451 * @return the maximum volume that can be used in {@link #setPlayerVolume(float)}. 452 */ 453 public float getMaxPlayerVolume() { 454 return 1.0f; 455 } 456 457 /** 458 * Insert a task in the command queue to help the client to identify whether a batch 459 * of commands has been finished. When this command is processed, a notification 460 * {@code MediaPlayer2EventCallback.onCommandLabelReached} will be fired with the 461 * given {@code label}. 462 * 463 * @see MediaPlayer2EventCallback#onCommandLabelReached 464 * 465 * @param label An application specific Object used to help to identify the completeness 466 * of a batch of commands. 467 */ 468 // This is an asynchronous call. 469 public void notifyWhenCommandLabelReached(@NonNull Object label) { } 470 471 /** 472 * Sets the {@link Surface} to be used as the sink for the video portion of 473 * the media. Setting a 474 * Surface will un-set any Surface or SurfaceHolder that was previously set. 475 * A null surface will result in only the audio track being played. 476 * 477 * If the Surface sends frames to a {@link SurfaceTexture}, the timestamps 478 * returned from {@link SurfaceTexture#getTimestamp()} will have an 479 * unspecified zero point. These timestamps cannot be directly compared 480 * between different media sources, different instances of the same media 481 * source, or multiple runs of the same program. The timestamp is normally 482 * monotonically increasing and is unaffected by time-of-day adjustments, 483 * but it is reset when the position is set. 484 * 485 * @param surface The {@link Surface} to be used for the video portion of 486 * the media. 487 * @throws IllegalStateException if the internal player engine has not been 488 * initialized or has been released. 489 */ 490 // This is an asynchronous call. 491 public abstract void setSurface(Surface surface); 492 493 /* Do not change these video scaling mode values below without updating 494 * their counterparts in system/window.h! Please do not forget to update 495 * {@link #isVideoScalingModeSupported} when new video scaling modes 496 * are added. 497 */ 498 /** 499 * Specifies a video scaling mode. The content is stretched to the 500 * surface rendering area. When the surface has the same aspect ratio 501 * as the content, the aspect ratio of the content is maintained; 502 * otherwise, the aspect ratio of the content is not maintained when video 503 * is being rendered. 504 * There is no content cropping with this video scaling mode. 505 */ 506 public static final int VIDEO_SCALING_MODE_SCALE_TO_FIT = 1; 507 508 /** 509 * Discards all pending commands. 510 */ 511 // This is a synchronous call. 512 public abstract void clearPendingCommands(); 513 514 /** 515 * Returns the width of the video. 516 * 517 * @return the width of the video, or 0 if there is no video, 518 * no display surface was set, or the width has not been determined 519 * yet. The {@code MediaPlayer2EventCallback} can be registered via 520 * {@link #setMediaPlayer2EventCallback(Executor, MediaPlayer2EventCallback)} to provide a 521 * notification {@code MediaPlayer2EventCallback.onVideoSizeChanged} when the width 522 * is available. 523 */ 524 public abstract int getVideoWidth(); 525 526 /** 527 * Returns the height of the video. 528 * 529 * @return the height of the video, or 0 if there is no video, 530 * no display surface was set, or the height has not been determined 531 * yet. The {@code MediaPlayer2EventCallback} can be registered via 532 * {@link #setMediaPlayer2EventCallback(Executor, MediaPlayer2EventCallback)} to provide a 533 * notification {@code MediaPlayer2EventCallback.onVideoSizeChanged} when the height is 534 * available. 535 */ 536 public abstract int getVideoHeight(); 537 538 /** 539 * Return Metrics data about the current player. 540 * 541 * @return a {@link PersistableBundle} containing the set of attributes and values 542 * available for the media being handled by this instance of MediaPlayer2 543 * The attributes are descibed in {@link MetricsConstants}. 544 * 545 * Additional vendor-specific fields may also be present in 546 * the return value. 547 */ 548 public abstract PersistableBundle getMetrics(); 549 550 /** 551 * Sets playback rate using {@link PlaybackParams}. The object sets its internal 552 * PlaybackParams to the input, except that the object remembers previous speed 553 * when input speed is zero. This allows the object to resume at previous speed 554 * when play() is called. Calling it before the object is prepared does not change 555 * the object state. After the object is prepared, calling it with zero speed is 556 * equivalent to calling pause(). After the object is prepared, calling it with 557 * non-zero speed is equivalent to calling play(). 558 * 559 * @param params the playback params. 560 */ 561 // This is an asynchronous call. 562 public abstract void setPlaybackParams(@NonNull PlaybackParams params); 563 564 /** 565 * Gets the playback params, containing the current playback rate. 566 * 567 * @return the playback params. 568 */ 569 @NonNull 570 public abstract PlaybackParams getPlaybackParams(); 571 572 /** 573 * Sets A/V sync mode. 574 * 575 * @param params the A/V sync params to apply 576 */ 577 // This is an asynchronous call. 578 public abstract void setSyncParams(@NonNull SyncParams params); 579 580 /** 581 * Gets the A/V sync mode. 582 * 583 * @return the A/V sync params 584 */ 585 @NonNull 586 public abstract SyncParams getSyncParams(); 587 588 /** 589 * Seek modes used in method seekTo(long, int) to move media position 590 * to a specified location. 591 * 592 * Do not change these mode values without updating their counterparts 593 * in include/media/IMediaSource.h! 594 */ 595 /** 596 * This mode is used with {@link #seekTo(long, int)} to move media position to 597 * a sync (or key) frame associated with a data source that is located 598 * right before or at the given time. 599 * 600 * @see #seekTo(long, int) 601 */ 602 public static final int SEEK_PREVIOUS_SYNC = 0x00; 603 /** 604 * This mode is used with {@link #seekTo(long, int)} to move media position to 605 * a sync (or key) frame associated with a data source that is located 606 * right after or at the given time. 607 * 608 * @see #seekTo(long, int) 609 */ 610 public static final int SEEK_NEXT_SYNC = 0x01; 611 /** 612 * This mode is used with {@link #seekTo(long, int)} to move media position to 613 * a sync (or key) frame associated with a data source that is located 614 * closest to (in time) or at the given time. 615 * 616 * @see #seekTo(long, int) 617 */ 618 public static final int SEEK_CLOSEST_SYNC = 0x02; 619 /** 620 * This mode is used with {@link #seekTo(long, int)} to move media position to 621 * a frame (not necessarily a key frame) associated with a data source that 622 * is located closest to or at the given time. 623 * 624 * @see #seekTo(long, int) 625 */ 626 public static final int SEEK_CLOSEST = 0x03; 627 628 /** @hide */ 629 @IntDef(flag = false, /*prefix = "SEEK",*/ value = { 630 SEEK_PREVIOUS_SYNC, 631 SEEK_NEXT_SYNC, 632 SEEK_CLOSEST_SYNC, 633 SEEK_CLOSEST, 634 }) 635 @Retention(RetentionPolicy.SOURCE) 636 @RestrictTo(LIBRARY_GROUP) 637 public @interface SeekMode {} 638 639 /** 640 * Moves the media to specified time position by considering the given mode. 641 * <p> 642 * When seekTo is finished, the user will be notified via 643 * {@link MediaPlayer2EventCallback#onInfo} with {@link #CALL_COMPLETED_SEEK_TO}. 644 * There is at most one active seekTo processed at any time. If there is a to-be-completed 645 * seekTo, new seekTo requests will be queued in such a way that only the last request 646 * is kept. When current seekTo is completed, the queued request will be processed if 647 * that request is different from just-finished seekTo operation, i.e., the requested 648 * position or mode is different. 649 * 650 * @param msec the offset in milliseconds from the start to seek to. 651 * When seeking to the given time position, there is no guarantee that the data source 652 * has a frame located at the position. When this happens, a frame nearby will be rendered. 653 * If msec is negative, time position zero will be used. 654 * If msec is larger than duration, duration will be used. 655 * @param mode the mode indicating where exactly to seek to. 656 */ 657 // This is an asynchronous call. 658 public abstract void seekTo(long msec, @SeekMode int mode); 659 660 /** 661 * Gets current playback position as a {@link MediaTimestamp}. 662 * <p> 663 * The MediaTimestamp represents how the media time correlates to the system time in 664 * a linear fashion using an anchor and a clock rate. During regular playback, the media 665 * time moves fairly constantly (though the anchor frame may be rebased to a current 666 * system time, the linear correlation stays steady). Therefore, this method does not 667 * need to be called often. 668 * <p> 669 * To help users get current playback position, this method always anchors the timestamp 670 * to the current {@link System#nanoTime system time}, so 671 * {@link MediaTimestamp#getAnchorMediaTimeUs} can be used as current playback position. 672 * 673 * @return a MediaTimestamp object if a timestamp is available, or {@code null} if no timestamp 674 * is available, e.g. because the media player has not been initialized. 675 * 676 * @see MediaTimestamp 677 */ 678 @Nullable 679 public abstract MediaTimestamp getTimestamp(); 680 681 /** 682 * Resets the MediaPlayer2 to its uninitialized state. After calling 683 * this method, you will have to initialize it again by setting the 684 * data source and calling prepare(). 685 */ 686 // This is a synchronous call. 687 public abstract void reset(); 688 689 /** 690 * Sets the audio session ID. 691 * 692 * @param sessionId the audio session ID. 693 * The audio session ID is a system wide unique identifier for the audio stream played by 694 * this MediaPlayer2 instance. 695 * The primary use of the audio session ID is to associate audio effects to a particular 696 * instance of MediaPlayer2: if an audio session ID is provided when creating an audio effect, 697 * this effect will be applied only to the audio content of media players within the same 698 * audio session and not to the output mix. 699 * When created, a MediaPlayer2 instance automatically generates its own audio session ID. 700 * However, it is possible to force this player to be part of an already existing audio session 701 * by calling this method. 702 * This method must be called before one of the overloaded <code> setDataSource </code> methods. 703 */ 704 // This is an asynchronous call. 705 public abstract void setAudioSessionId(int sessionId); 706 707 /** 708 * Returns the audio session ID. 709 * 710 * @return the audio session ID. {@see #setAudioSessionId(int)} 711 * Note that the audio session ID is 0 only if a problem occured when the MediaPlayer2 was 712 * contructed. 713 */ 714 public abstract int getAudioSessionId(); 715 716 /** 717 * Attaches an auxiliary effect to the player. A typical auxiliary effect is a reverberation 718 * effect which can be applied on any sound source that directs a certain amount of its 719 * energy to this effect. This amount is defined by setAuxEffectSendLevel(). 720 * See {@link #setAuxEffectSendLevel(float)}. 721 * <p>After creating an auxiliary effect (e.g. 722 * {@link android.media.audiofx.EnvironmentalReverb}), retrieve its ID with 723 * {@link android.media.audiofx.AudioEffect#getId()} and use it when calling this method 724 * to attach the player to the effect. 725 * <p>To detach the effect from the player, call this method with a null effect id. 726 * <p>This method must be called after one of the overloaded <code> setDataSource </code> 727 * methods. 728 * @param effectId system wide unique id of the effect to attach 729 */ 730 // This is an asynchronous call. 731 public abstract void attachAuxEffect(int effectId); 732 733 734 /** 735 * Sets the send level of the player to the attached auxiliary effect. 736 * See {@link #attachAuxEffect(int)}. The level value range is 0 to 1.0. 737 * <p>By default the send level is 0, so even if an effect is attached to the player 738 * this method must be called for the effect to be applied. 739 * <p>Note that the passed level value is a raw scalar. UI controls should be scaled 740 * logarithmically: the gain applied by audio framework ranges from -72dB to 0dB, 741 * so an appropriate conversion from linear UI input x to level is: 742 * x == 0 -> level = 0 743 * 0 < x <= R -> level = 10^(72*(x-R)/20/R) 744 * @param level send level scalar 745 */ 746 // This is an asynchronous call. 747 public abstract void setAuxEffectSendLevel(float level); 748 749 /** 750 * Class for MediaPlayer2 to return each audio/video/subtitle track's metadata. 751 * 752 * @see MediaPlayer2#getTrackInfo 753 */ 754 public abstract static class TrackInfo { 755 /** 756 * Gets the track type. 757 * @return TrackType which indicates if the track is video, audio, timed text. 758 */ 759 public abstract int getTrackType(); 760 761 /** 762 * Gets the language code of the track. 763 * @return a language code in either way of ISO-639-1 or ISO-639-2. 764 * When the language is unknown or could not be determined, 765 * ISO-639-2 language code, "und", is returned. 766 */ 767 public abstract String getLanguage(); 768 769 /** 770 * Gets the {@link MediaFormat} of the track. If the format is 771 * unknown or could not be determined, null is returned. 772 */ 773 public abstract MediaFormat getFormat(); 774 775 public static final int MEDIA_TRACK_TYPE_UNKNOWN = 0; 776 public static final int MEDIA_TRACK_TYPE_VIDEO = 1; 777 public static final int MEDIA_TRACK_TYPE_AUDIO = 2; 778 779 /** @hide */ 780 @RestrictTo(LIBRARY_GROUP) 781 public static final int MEDIA_TRACK_TYPE_TIMEDTEXT = 3; 782 783 public static final int MEDIA_TRACK_TYPE_SUBTITLE = 4; 784 public static final int MEDIA_TRACK_TYPE_METADATA = 5; 785 786 @Override 787 public abstract String toString(); 788 }; 789 790 /** 791 * Returns a List of track information. 792 * 793 * @return List of track info. The total number of tracks is the array length. 794 * Must be called again if an external timed text source has been added after 795 * addTimedTextSource method is called. 796 */ 797 public abstract List<TrackInfo> getTrackInfo(); 798 799 /** 800 * Returns the index of the audio, video, or subtitle track currently selected for playback, 801 * The return value is an index into the array returned by {@link #getTrackInfo()}, and can 802 * be used in calls to {@link #selectTrack(int)} or {@link #deselectTrack(int)}. 803 * 804 * @param trackType should be one of {@link TrackInfo#MEDIA_TRACK_TYPE_VIDEO}, 805 * {@link TrackInfo#MEDIA_TRACK_TYPE_AUDIO}, or 806 * {@link TrackInfo#MEDIA_TRACK_TYPE_SUBTITLE} 807 * @return index of the audio, video, or subtitle track currently selected for playback; 808 * a negative integer is returned when there is no selected track for {@code trackType} or 809 * when {@code trackType} is not one of audio, video, or subtitle. 810 * @throws IllegalStateException if called after {@link #close()} 811 * 812 * @see #getTrackInfo() 813 * @see #selectTrack(int) 814 * @see #deselectTrack(int) 815 */ 816 public abstract int getSelectedTrack(int trackType); 817 818 /** 819 * Selects a track. 820 * <p> 821 * If a MediaPlayer2 is in invalid state, {@link #CALL_STATUS_INVALID_OPERATION} will be 822 * reported with {@link MediaPlayer2EventCallback#onCallCompleted}. 823 * If a MediaPlayer2 is in <em>Playing</em> state, the selected track is presented immediately. 824 * If a MediaPlayer2 is not in Started state, it just marks the track to be played. 825 * </p> 826 * <p> 827 * In any valid state, if it is called multiple times on the same type of track (ie. Video, 828 * Audio, Timed Text), the most recent one will be chosen. 829 * </p> 830 * <p> 831 * The first audio and video tracks are selected by default if available, even though 832 * this method is not called. However, no timed text track will be selected until 833 * this function is called. 834 * </p> 835 * <p> 836 * Currently, only timed text tracks or audio tracks can be selected via this method. 837 * </p> 838 * @param index the index of the track to be selected. The valid range of the index 839 * is 0..total number of track - 1. The total number of tracks as well as the type of 840 * each individual track can be found by calling {@link #getTrackInfo()} method. 841 * 842 * @see MediaPlayer2#getTrackInfo 843 */ 844 // This is an asynchronous call. 845 public abstract void selectTrack(int index); 846 847 /** 848 * Deselects a track. 849 * <p> 850 * Currently, the track must be a timed text track and no audio or video tracks can be 851 * deselected. If the timed text track identified by index has not been 852 * selected before, it throws an exception. 853 * </p> 854 * @param index the index of the track to be deselected. The valid range of the index 855 * is 0..total number of tracks - 1. The total number of tracks as well as the type of 856 * each individual track can be found by calling {@link #getTrackInfo()} method. 857 * 858 * @see MediaPlayer2#getTrackInfo 859 */ 860 // This is an asynchronous call. 861 public abstract void deselectTrack(int index); 862 863 /** 864 * Interface definition for callbacks to be invoked when the player has the corresponding 865 * events. 866 */ 867 public abstract static class MediaPlayer2EventCallback { 868 /** 869 * Called to indicate the video size 870 * 871 * The video size (width and height) could be 0 if there was no video, 872 * no display surface was set, or the value was not determined yet. 873 * 874 * @param mp the MediaPlayer2 associated with this callback 875 * @param dsd the DataSourceDesc of this data source 876 * @param width the width of the video 877 * @param height the height of the video 878 */ 879 public void onVideoSizeChanged( 880 MediaPlayer2 mp, DataSourceDesc dsd, int width, int height) { } 881 882 /** 883 * Called to indicate available timed metadata 884 * <p> 885 * This method will be called as timed metadata is extracted from the media, 886 * in the same order as it occurs in the media. The timing of this event is 887 * not controlled by the associated timestamp. 888 * <p> 889 * Currently only HTTP live streaming data URI's embedded with timed ID3 tags generates 890 * {@link TimedMetaData}. 891 * 892 * @see MediaPlayer2#selectTrack(int) 893 * @see TimedMetaData 894 * 895 * @param mp the MediaPlayer2 associated with this callback 896 * @param dsd the DataSourceDesc of this data source 897 * @param data the timed metadata sample associated with this event 898 */ 899 public void onTimedMetaDataAvailable( 900 MediaPlayer2 mp, DataSourceDesc dsd, TimedMetaData data) { } 901 902 /** 903 * Called to indicate an error. 904 * 905 * @param mp the MediaPlayer2 the error pertains to 906 * @param dsd the DataSourceDesc of this data source 907 * @param what the type of error that has occurred. 908 * @param extra an extra code, specific to the error. Typically 909 * implementation dependent. 910 */ 911 public void onError( 912 MediaPlayer2 mp, DataSourceDesc dsd, @MediaError int what, int extra) { } 913 914 /** 915 * Called to indicate an info or a warning. 916 * 917 * @param mp the MediaPlayer2 the info pertains to. 918 * @param dsd the DataSourceDesc of this data source 919 * @param what the type of info or warning. 920 * @param extra an extra code, specific to the info. Typically 921 * implementation dependent. 922 */ 923 public void onInfo(MediaPlayer2 mp, DataSourceDesc dsd, @MediaInfo int what, int extra) { } 924 925 /** 926 * Called to acknowledge an API call. 927 * 928 * @param mp the MediaPlayer2 the call was made on. 929 * @param dsd the DataSourceDesc of this data source 930 * @param what the enum for the API call. 931 * @param status the returned status code for the call. 932 */ 933 public void onCallCompleted( 934 MediaPlayer2 mp, DataSourceDesc dsd, @CallCompleted int what, 935 @CallStatus int status) { } 936 937 /** 938 * Called when a discontinuity in the normal progression of the media time is detected. 939 * The "normal progression" of media time is defined as the expected increase of the 940 * playback position when playing media, relative to the playback speed (for instance every 941 * second, media time increases by two seconds when playing at 2x).<br> 942 * Discontinuities are encountered in the following cases: 943 * <ul> 944 * <li>when the player is starved for data and cannot play anymore</li> 945 * <li>when the player encounters a playback error</li> 946 * <li>when the a seek operation starts, and when it's completed</li> 947 * <li>when the playback speed changes</li> 948 * <li>when the playback state changes</li> 949 * <li>when the player is reset</li> 950 * </ul> 951 * 952 * @param mp the MediaPlayer2 the media time pertains to. 953 * @param dsd the DataSourceDesc of this data source 954 * @param timestamp the timestamp that correlates media time, system time and clock rate, 955 * or {@link MediaTimestamp#TIMESTAMP_UNKNOWN} in an error case. 956 */ 957 public void onMediaTimeDiscontinuity( 958 MediaPlayer2 mp, DataSourceDesc dsd, MediaTimestamp timestamp) { } 959 960 /** 961 * Called to indicate {@link #notifyWhenCommandLabelReached(Object)} has been processed. 962 * 963 * @param mp the MediaPlayer2 {@link #notifyWhenCommandLabelReached(Object)} was called on. 964 * @param label the application specific Object given by 965 * {@link #notifyWhenCommandLabelReached(Object)}. 966 */ 967 public void onCommandLabelReached(MediaPlayer2 mp, @NonNull Object label) { } 968 969 /** 970 * Called when when a player subtitle track has new subtitle data available. 971 * @param mp the player that reports the new subtitle data 972 * @param dsd the DataSourceDesc of this data source 973 * @param data the subtitle data 974 */ 975 public void onSubtitleData( 976 MediaPlayer2 mp, DataSourceDesc dsd, @NonNull SubtitleData data) { } 977 } 978 979 /** 980 * Sets the callback to be invoked when the media source is ready for playback. 981 * 982 * @param eventCallback the callback that will be run 983 * @param executor the executor through which the callback should be invoked 984 */ 985 // This is a synchronous call. 986 public abstract void setMediaPlayer2EventCallback( 987 @NonNull Executor executor, @NonNull MediaPlayer2EventCallback eventCallback); 988 989 /** 990 * Clears the {@link MediaPlayer2EventCallback}. 991 */ 992 // This is a synchronous call. 993 public abstract void clearMediaPlayer2EventCallback(); 994 995 /** 996 * MediaPlayer2 has not been prepared or just has been reset. 997 * In this state, MediaPlayer2 doesn't fetch data. 998 */ 999 public static final int MEDIAPLAYER2_STATE_IDLE = 1001; 1000 1001 /** 1002 * MediaPlayer2 has been just prepared. 1003 * In this state, MediaPlayer2 just fetches data from media source, 1004 * but doesn't actively render data. 1005 */ 1006 public static final int MEDIAPLAYER2_STATE_PREPARED = 1002; 1007 1008 /** 1009 * MediaPlayer2 is paused. 1010 * In this state, MediaPlayer2 doesn't actively render data. 1011 */ 1012 public static final int MEDIAPLAYER2_STATE_PAUSED = 1003; 1013 1014 /** 1015 * MediaPlayer2 is actively playing back data. 1016 */ 1017 public static final int MEDIAPLAYER2_STATE_PLAYING = 1004; 1018 1019 /** 1020 * MediaPlayer2 has hit some fatal error and cannot continue playback. 1021 */ 1022 public static final int MEDIAPLAYER2_STATE_ERROR = 1005; 1023 1024 /** @hide */ 1025 @IntDef(flag = false, value = { 1026 MEDIAPLAYER2_STATE_IDLE, 1027 MEDIAPLAYER2_STATE_PREPARED, 1028 MEDIAPLAYER2_STATE_PAUSED, 1029 MEDIAPLAYER2_STATE_PLAYING, 1030 MEDIAPLAYER2_STATE_ERROR }) 1031 @Retention(RetentionPolicy.SOURCE) 1032 @RestrictTo(LIBRARY_GROUP) 1033 public @interface MediaPlayer2State {} 1034 1035 /* Do not change these values without updating their counterparts 1036 * in include/media/mediaplayer2.h! 1037 */ 1038 /** Unspecified media player error. 1039 * @see MediaPlayer2.MediaPlayer2EventCallback#onError 1040 */ 1041 public static final int MEDIA_ERROR_UNKNOWN = 1; 1042 1043 /** The video is streamed and its container is not valid for progressive 1044 * playback i.e the video's index (e.g moov atom) is not at the start of the 1045 * file. 1046 * @see MediaPlayer2.MediaPlayer2EventCallback#onError 1047 */ 1048 public static final int MEDIA_ERROR_NOT_VALID_FOR_PROGRESSIVE_PLAYBACK = 200; 1049 1050 /** File or network related operation errors. */ 1051 public static final int MEDIA_ERROR_IO = -1004; 1052 /** Bitstream is not conforming to the related coding standard or file spec. */ 1053 public static final int MEDIA_ERROR_MALFORMED = -1007; 1054 /** Bitstream is conforming to the related coding standard or file spec, but 1055 * the media framework does not support the feature. */ 1056 public static final int MEDIA_ERROR_UNSUPPORTED = -1010; 1057 /** Some operation takes too long to complete, usually more than 3-5 seconds. */ 1058 public static final int MEDIA_ERROR_TIMED_OUT = -110; 1059 1060 /** Unspecified low-level system error. This value originated from UNKNOWN_ERROR in 1061 * system/core/include/utils/Errors.h 1062 * @see MediaPlayer2.MediaPlayer2EventCallback#onError 1063 * @hide 1064 */ 1065 @RestrictTo(LIBRARY_GROUP) 1066 public static final int MEDIA_ERROR_SYSTEM = -2147483648; 1067 1068 /** 1069 * @hide 1070 */ 1071 @IntDef(flag = false, /*prefix = "MEDIA_ERROR",*/ value = { 1072 MEDIA_ERROR_UNKNOWN, 1073 MEDIA_ERROR_NOT_VALID_FOR_PROGRESSIVE_PLAYBACK, 1074 MEDIA_ERROR_IO, 1075 MEDIA_ERROR_MALFORMED, 1076 MEDIA_ERROR_UNSUPPORTED, 1077 MEDIA_ERROR_TIMED_OUT, 1078 MEDIA_ERROR_SYSTEM 1079 }) 1080 @Retention(RetentionPolicy.SOURCE) 1081 @RestrictTo(LIBRARY_GROUP) 1082 public @interface MediaError {} 1083 1084 /* Do not change these values without updating their counterparts 1085 * in include/media/mediaplayer2.h! 1086 */ 1087 /** Unspecified media player info. 1088 * @see MediaPlayer2.MediaPlayer2EventCallback#onInfo 1089 */ 1090 public static final int MEDIA_INFO_UNKNOWN = 1; 1091 1092 /** The player switched to this datas source because it is the 1093 * next-to-be-played in the playlist. 1094 * @see MediaPlayer2.MediaPlayer2EventCallback#onInfo 1095 * @hide 1096 */ 1097 @RestrictTo(LIBRARY_GROUP) 1098 public static final int MEDIA_INFO_STARTED_AS_NEXT = 2; 1099 1100 /** The player just pushed the very first video frame for rendering. 1101 * @see MediaPlayer2.MediaPlayer2EventCallback#onInfo 1102 */ 1103 public static final int MEDIA_INFO_VIDEO_RENDERING_START = 3; 1104 1105 /** The player just rendered the very first audio sample. 1106 * @see MediaPlayer2.MediaPlayer2EventCallback#onInfo 1107 */ 1108 public static final int MEDIA_INFO_AUDIO_RENDERING_START = 4; 1109 1110 /** The player just completed the playback of this data source. 1111 * @see MediaPlayer2.MediaPlayer2EventCallback#onInfo 1112 */ 1113 public static final int MEDIA_INFO_PLAYBACK_COMPLETE = 5; 1114 1115 /** The player just completed the playback of the full playlist. 1116 * @see MediaPlayer2.MediaPlayer2EventCallback#onInfo 1117 */ 1118 public static final int MEDIA_INFO_PLAYLIST_END = 6; 1119 1120 /** The player just prepared a data source. 1121 * @see MediaPlayer2.MediaPlayer2EventCallback#onInfo 1122 */ 1123 public static final int MEDIA_INFO_PREPARED = 100; 1124 1125 /** The video is too complex for the decoder: it can't decode frames fast 1126 * enough. Possibly only the audio plays fine at this stage. 1127 * @see MediaPlayer2.MediaPlayer2EventCallback#onInfo 1128 */ 1129 public static final int MEDIA_INFO_VIDEO_TRACK_LAGGING = 700; 1130 1131 /** MediaPlayer2 is temporarily pausing playback internally in order to 1132 * buffer more data. 1133 * @see MediaPlayer2.MediaPlayer2EventCallback#onInfo 1134 */ 1135 public static final int MEDIA_INFO_BUFFERING_START = 701; 1136 1137 /** MediaPlayer2 is resuming playback after filling buffers. 1138 * @see MediaPlayer2.MediaPlayer2EventCallback#onInfo 1139 */ 1140 public static final int MEDIA_INFO_BUFFERING_END = 702; 1141 1142 /** Estimated network bandwidth information (kbps) is available; currently this event fires 1143 * simultaneously as {@link #MEDIA_INFO_BUFFERING_START} and {@link #MEDIA_INFO_BUFFERING_END} 1144 * when playing network files. 1145 * @see MediaPlayer2.MediaPlayer2EventCallback#onInfo 1146 * @hide 1147 */ 1148 @RestrictTo(LIBRARY_GROUP) 1149 public static final int MEDIA_INFO_NETWORK_BANDWIDTH = 703; 1150 1151 /** 1152 * Update status in buffering a media source received through progressive downloading. 1153 * The received buffering percentage indicates how much of the content has been buffered 1154 * or played. For example a buffering update of 80 percent when half the content 1155 * has already been played indicates that the next 30 percent of the 1156 * content to play has been buffered. 1157 * 1158 * The {@code extra} parameter in {@code MediaPlayer2EventCallback.onInfo} is the 1159 * percentage (0-100) of the content that has been buffered or played thus far. 1160 * @see MediaPlayer2.MediaPlayer2EventCallback#onInfo 1161 */ 1162 public static final int MEDIA_INFO_BUFFERING_UPDATE = 704; 1163 1164 /** Bad interleaving means that a media has been improperly interleaved or 1165 * not interleaved at all, e.g has all the video samples first then all the 1166 * audio ones. Video is playing but a lot of disk seeks may be happening. 1167 * @see MediaPlayer2.MediaPlayer2EventCallback#onInfo 1168 */ 1169 public static final int MEDIA_INFO_BAD_INTERLEAVING = 800; 1170 1171 /** The media cannot be seeked (e.g live stream) 1172 * @see MediaPlayer2.MediaPlayer2EventCallback#onInfo 1173 */ 1174 public static final int MEDIA_INFO_NOT_SEEKABLE = 801; 1175 1176 /** A new set of metadata is available. 1177 * @see MediaPlayer2.MediaPlayer2EventCallback#onInfo 1178 */ 1179 public static final int MEDIA_INFO_METADATA_UPDATE = 802; 1180 1181 /** A new set of external-only metadata is available. Used by 1182 * JAVA framework to avoid triggering track scanning. 1183 * @hide 1184 */ 1185 @RestrictTo(LIBRARY_GROUP) 1186 public static final int MEDIA_INFO_EXTERNAL_METADATA_UPDATE = 803; 1187 1188 /** Informs that audio is not playing. Note that playback of the video 1189 * is not interrupted. 1190 * @see MediaPlayer2.MediaPlayer2EventCallback#onInfo 1191 */ 1192 public static final int MEDIA_INFO_AUDIO_NOT_PLAYING = 804; 1193 1194 /** Informs that video is not playing. Note that playback of the audio 1195 * is not interrupted. 1196 * @see MediaPlayer2.MediaPlayer2EventCallback#onInfo 1197 */ 1198 public static final int MEDIA_INFO_VIDEO_NOT_PLAYING = 805; 1199 1200 /** Failed to handle timed text track properly. 1201 * @see MediaPlayer2.MediaPlayer2EventCallback#onInfo 1202 * {@hide} 1203 */ 1204 @RestrictTo(LIBRARY_GROUP) 1205 public static final int MEDIA_INFO_TIMED_TEXT_ERROR = 900; 1206 1207 /** Subtitle track was not supported by the media framework. 1208 * @see MediaPlayer2.MediaPlayer2EventCallback#onInfo 1209 */ 1210 public static final int MEDIA_INFO_UNSUPPORTED_SUBTITLE = 901; 1211 1212 /** Reading the subtitle track takes too long. 1213 * @see MediaPlayer2.MediaPlayer2EventCallback#onInfo 1214 */ 1215 public static final int MEDIA_INFO_SUBTITLE_TIMED_OUT = 902; 1216 1217 /** 1218 * @hide 1219 */ 1220 @IntDef(flag = false, /*prefix = "MEDIA_INFO",*/ value = { 1221 MEDIA_INFO_UNKNOWN, 1222 MEDIA_INFO_STARTED_AS_NEXT, 1223 MEDIA_INFO_VIDEO_RENDERING_START, 1224 MEDIA_INFO_AUDIO_RENDERING_START, 1225 MEDIA_INFO_PLAYBACK_COMPLETE, 1226 MEDIA_INFO_PLAYLIST_END, 1227 MEDIA_INFO_PREPARED, 1228 MEDIA_INFO_VIDEO_TRACK_LAGGING, 1229 MEDIA_INFO_BUFFERING_START, 1230 MEDIA_INFO_BUFFERING_END, 1231 MEDIA_INFO_NETWORK_BANDWIDTH, 1232 MEDIA_INFO_BUFFERING_UPDATE, 1233 MEDIA_INFO_BAD_INTERLEAVING, 1234 MEDIA_INFO_NOT_SEEKABLE, 1235 MEDIA_INFO_METADATA_UPDATE, 1236 MEDIA_INFO_EXTERNAL_METADATA_UPDATE, 1237 MEDIA_INFO_AUDIO_NOT_PLAYING, 1238 MEDIA_INFO_VIDEO_NOT_PLAYING, 1239 MEDIA_INFO_TIMED_TEXT_ERROR, 1240 MEDIA_INFO_UNSUPPORTED_SUBTITLE, 1241 MEDIA_INFO_SUBTITLE_TIMED_OUT 1242 }) 1243 @Retention(RetentionPolicy.SOURCE) 1244 @RestrictTo(LIBRARY_GROUP) 1245 public @interface MediaInfo {} 1246 1247 //-------------------------------------------------------------------------- 1248 /** The player just completed a call {@link #attachAuxEffect}. 1249 * @see MediaPlayer2.MediaPlayer2EventCallback#onCallCompleted 1250 */ 1251 public static final int CALL_COMPLETED_ATTACH_AUX_EFFECT = 1; 1252 1253 /** The player just completed a call {@link #deselectTrack}. 1254 * @see MediaPlayer2.MediaPlayer2EventCallback#onCallCompleted 1255 */ 1256 public static final int CALL_COMPLETED_DESELECT_TRACK = 2; 1257 1258 /** The player just completed a call {@link #loopCurrent}. 1259 * @see MediaPlayer2.MediaPlayer2EventCallback#onCallCompleted 1260 */ 1261 public static final int CALL_COMPLETED_LOOP_CURRENT = 3; 1262 1263 /** The player just completed a call {@link #pause}. 1264 * @see MediaPlayer2.MediaPlayer2EventCallback#onCallCompleted 1265 */ 1266 public static final int CALL_COMPLETED_PAUSE = 4; 1267 1268 /** The player just completed a call {@link #play}. 1269 * @see MediaPlayer2.MediaPlayer2EventCallback#onCallCompleted 1270 */ 1271 public static final int CALL_COMPLETED_PLAY = 5; 1272 1273 /** The player just completed a call {@link #prepare}. 1274 * @see MediaPlayer2.MediaPlayer2EventCallback#onCallCompleted 1275 */ 1276 public static final int CALL_COMPLETED_PREPARE = 6; 1277 1278 /** The player just completed a call {@link #seekTo}. 1279 * @see MediaPlayer2.MediaPlayer2EventCallback#onCallCompleted 1280 */ 1281 public static final int CALL_COMPLETED_SEEK_TO = 14; 1282 1283 /** The player just completed a call {@link #selectTrack}. 1284 * @see MediaPlayer2.MediaPlayer2EventCallback#onCallCompleted 1285 */ 1286 public static final int CALL_COMPLETED_SELECT_TRACK = 15; 1287 1288 /** The player just completed a call {@link #setAudioAttributes}. 1289 * @see MediaPlayer2.MediaPlayer2EventCallback#onCallCompleted 1290 */ 1291 public static final int CALL_COMPLETED_SET_AUDIO_ATTRIBUTES = 16; 1292 1293 /** The player just completed a call {@link #setAudioSessionId}. 1294 * @see MediaPlayer2.MediaPlayer2EventCallback#onCallCompleted 1295 */ 1296 public static final int CALL_COMPLETED_SET_AUDIO_SESSION_ID = 17; 1297 1298 /** The player just completed a call {@link #setAuxEffectSendLevel}. 1299 * @see MediaPlayer2.MediaPlayer2EventCallback#onCallCompleted 1300 */ 1301 public static final int CALL_COMPLETED_SET_AUX_EFFECT_SEND_LEVEL = 18; 1302 1303 /** The player just completed a call {@link #setDataSource}. 1304 * @see MediaPlayer2.MediaPlayer2EventCallback#onCallCompleted 1305 */ 1306 public static final int CALL_COMPLETED_SET_DATA_SOURCE = 19; 1307 1308 /** The player just completed a call {@link #setNextDataSource}. 1309 * @see MediaPlayer2.MediaPlayer2EventCallback#onCallCompleted 1310 */ 1311 public static final int CALL_COMPLETED_SET_NEXT_DATA_SOURCE = 22; 1312 1313 /** The player just completed a call {@link #setNextDataSources}. 1314 * @see MediaPlayer2.MediaPlayer2EventCallback#onCallCompleted 1315 */ 1316 public static final int CALL_COMPLETED_SET_NEXT_DATA_SOURCES = 23; 1317 1318 /** The player just completed a call {@link #setPlaybackParams}. 1319 * @see MediaPlayer2.MediaPlayer2EventCallback#onCallCompleted 1320 */ 1321 public static final int CALL_COMPLETED_SET_PLAYBACK_PARAMS = 24; 1322 1323 /** The player just completed a call {@link #setPlaybackSpeed}. 1324 * @see MediaPlayer2.MediaPlayer2EventCallback#onCallCompleted 1325 */ 1326 public static final int CALL_COMPLETED_SET_PLAYBACK_SPEED = 25; 1327 1328 /** The player just completed a call {@link #setPlayerVolume}. 1329 * @see MediaPlayer2.MediaPlayer2EventCallback#onCallCompleted 1330 */ 1331 public static final int CALL_COMPLETED_SET_PLAYER_VOLUME = 26; 1332 1333 /** The player just completed a call {@link #setSurface}. 1334 * @see MediaPlayer2.MediaPlayer2EventCallback#onCallCompleted 1335 */ 1336 public static final int CALL_COMPLETED_SET_SURFACE = 27; 1337 1338 /** The player just completed a call {@link #setSyncParams}. 1339 * @see MediaPlayer2.MediaPlayer2EventCallback#onCallCompleted 1340 */ 1341 public static final int CALL_COMPLETED_SET_SYNC_PARAMS = 28; 1342 1343 /** The player just completed a call {@link #skipToNext}. 1344 * @see MediaPlayer2.MediaPlayer2EventCallback#onCallCompleted 1345 */ 1346 public static final int CALL_COMPLETED_SKIP_TO_NEXT = 29; 1347 1348 /** The player just completed a call {@code notifyWhenCommandLabelReached}. 1349 * @see MediaPlayer2.MediaPlayer2EventCallback#onCommandLabelReached 1350 * @hide 1351 */ 1352 @RestrictTo(LIBRARY_GROUP) 1353 public static final int CALL_COMPLETED_NOTIFY_WHEN_COMMAND_LABEL_REACHED = 1003; 1354 1355 /** 1356 * @hide 1357 */ 1358 @IntDef(flag = false, /*prefix = "CALL_COMPLETED",*/ value = { 1359 CALL_COMPLETED_ATTACH_AUX_EFFECT, 1360 CALL_COMPLETED_DESELECT_TRACK, 1361 CALL_COMPLETED_LOOP_CURRENT, 1362 CALL_COMPLETED_PAUSE, 1363 CALL_COMPLETED_PLAY, 1364 CALL_COMPLETED_PREPARE, 1365 CALL_COMPLETED_SEEK_TO, 1366 CALL_COMPLETED_SELECT_TRACK, 1367 CALL_COMPLETED_SET_AUDIO_ATTRIBUTES, 1368 CALL_COMPLETED_SET_AUDIO_SESSION_ID, 1369 CALL_COMPLETED_SET_AUX_EFFECT_SEND_LEVEL, 1370 CALL_COMPLETED_SET_DATA_SOURCE, 1371 CALL_COMPLETED_SET_NEXT_DATA_SOURCE, 1372 CALL_COMPLETED_SET_NEXT_DATA_SOURCES, 1373 CALL_COMPLETED_SET_PLAYBACK_PARAMS, 1374 CALL_COMPLETED_SET_PLAYBACK_SPEED, 1375 CALL_COMPLETED_SET_PLAYER_VOLUME, 1376 CALL_COMPLETED_SET_SURFACE, 1377 CALL_COMPLETED_SET_SYNC_PARAMS, 1378 CALL_COMPLETED_SKIP_TO_NEXT, 1379 CALL_COMPLETED_NOTIFY_WHEN_COMMAND_LABEL_REACHED 1380 }) 1381 @Retention(RetentionPolicy.SOURCE) 1382 @RestrictTo(LIBRARY_GROUP) 1383 public @interface CallCompleted {} 1384 1385 /** Status code represents that call is completed without an error. 1386 * @see MediaPlayer2.MediaPlayer2EventCallback#onCallCompleted 1387 */ 1388 public static final int CALL_STATUS_NO_ERROR = 0; 1389 1390 /** Status code represents that call is ended with an unknown error. 1391 * @see MediaPlayer2.MediaPlayer2EventCallback#onCallCompleted 1392 */ 1393 public static final int CALL_STATUS_ERROR_UNKNOWN = Integer.MIN_VALUE; 1394 1395 /** Status code represents that the player is not in valid state for the operation. 1396 * @see MediaPlayer2.MediaPlayer2EventCallback#onCallCompleted 1397 */ 1398 public static final int CALL_STATUS_INVALID_OPERATION = 1; 1399 1400 /** Status code represents that the argument is illegal. 1401 * @see MediaPlayer2.MediaPlayer2EventCallback#onCallCompleted 1402 */ 1403 public static final int CALL_STATUS_BAD_VALUE = 2; 1404 1405 /** Status code represents that the operation is not allowed. 1406 * @see MediaPlayer2.MediaPlayer2EventCallback#onCallCompleted 1407 */ 1408 public static final int CALL_STATUS_PERMISSION_DENIED = 3; 1409 1410 /** Status code represents a file or network related operation error. 1411 * @see MediaPlayer2.MediaPlayer2EventCallback#onCallCompleted 1412 */ 1413 public static final int CALL_STATUS_ERROR_IO = 4; 1414 1415 /** 1416 * @hide 1417 */ 1418 @IntDef(flag = false, /*prefix = "CALL_STATUS",*/ value = { 1419 CALL_STATUS_NO_ERROR, 1420 CALL_STATUS_ERROR_UNKNOWN, 1421 CALL_STATUS_INVALID_OPERATION, 1422 CALL_STATUS_BAD_VALUE, 1423 CALL_STATUS_PERMISSION_DENIED, 1424 CALL_STATUS_ERROR_IO}) 1425 @Retention(RetentionPolicy.SOURCE) 1426 @RestrictTo(LIBRARY_GROUP) 1427 public @interface CallStatus {} 1428 1429 // Modular DRM begin 1430 1431 /** 1432 * Interface definition of a callback to be invoked when the app 1433 * can do DRM configuration (get/set properties) before the session 1434 * is opened. This facilitates configuration of the properties, like 1435 * 'securityLevel', which has to be set after DRM scheme creation but 1436 * before the DRM session is opened. 1437 * 1438 * The only allowed DRM calls in this listener are {@link #getDrmPropertyString} 1439 * and {@link #setDrmPropertyString}. 1440 */ 1441 public interface OnDrmConfigHelper { 1442 /** 1443 * Called to give the app the opportunity to configure DRM before the session is created 1444 * 1445 * @param mp the {@code MediaPlayer2} associated with this callback 1446 * @param dsd the DataSourceDesc of this data source 1447 */ 1448 void onDrmConfig(MediaPlayer2 mp, DataSourceDesc dsd); 1449 } 1450 1451 /** 1452 * Register a callback to be invoked for configuration of the DRM object before 1453 * the session is created. 1454 * The callback will be invoked synchronously during the execution 1455 * of {@link #prepareDrm(UUID uuid)}. 1456 * 1457 * @param listener the callback that will be run 1458 */ 1459 // This is a synchronous call. 1460 public abstract void setOnDrmConfigHelper(OnDrmConfigHelper listener); 1461 1462 /** 1463 * Interface definition for callbacks to be invoked when the player has the corresponding 1464 * DRM events. 1465 */ 1466 public abstract static class DrmEventCallback { 1467 /** 1468 * Called to indicate DRM info is available 1469 * 1470 * @param mp the {@code MediaPlayer2} associated with this callback 1471 * @param dsd the DataSourceDesc of this data source 1472 * @param drmInfo DRM info of the source including PSSH, and subset 1473 * of crypto schemes supported by this device 1474 */ 1475 public void onDrmInfo(MediaPlayer2 mp, DataSourceDesc dsd, DrmInfo drmInfo) { } 1476 1477 /** 1478 * Called to notify the client that {@link #prepareDrm} is finished and ready for 1479 * key request/response. 1480 * 1481 * @param mp the {@code MediaPlayer2} associated with this callback 1482 * @param dsd the DataSourceDesc of this data source 1483 * @param status the result of DRM preparation. 1484 */ 1485 public void onDrmPrepared( 1486 MediaPlayer2 mp, DataSourceDesc dsd, @PrepareDrmStatusCode int status) { } 1487 } 1488 1489 /** 1490 * Sets the callback to be invoked when the media source is ready for playback. 1491 * 1492 * @param eventCallback the callback that will be run 1493 * @param executor the executor through which the callback should be invoked 1494 */ 1495 // This is a synchronous call. 1496 public abstract void setDrmEventCallback(@NonNull Executor executor, 1497 @NonNull DrmEventCallback eventCallback); 1498 1499 /** 1500 * Clears the {@link DrmEventCallback}. 1501 */ 1502 // This is a synchronous call. 1503 public abstract void clearDrmEventCallback(); 1504 1505 /** 1506 * The status codes for {@link DrmEventCallback#onDrmPrepared} listener. 1507 * <p> 1508 * 1509 * DRM preparation has succeeded. 1510 */ 1511 public static final int PREPARE_DRM_STATUS_SUCCESS = 0; 1512 1513 /** 1514 * The device required DRM provisioning but couldn't reach the provisioning server. 1515 */ 1516 public static final int PREPARE_DRM_STATUS_PROVISIONING_NETWORK_ERROR = 1; 1517 1518 /** 1519 * The device required DRM provisioning but the provisioning server denied the request. 1520 */ 1521 public static final int PREPARE_DRM_STATUS_PROVISIONING_SERVER_ERROR = 2; 1522 1523 /** 1524 * The DRM preparation has failed . 1525 */ 1526 public static final int PREPARE_DRM_STATUS_PREPARATION_ERROR = 3; 1527 1528 1529 /** @hide */ 1530 @IntDef(flag = false, /*prefix = "PREPARE_DRM_STATUS",*/ value = { 1531 PREPARE_DRM_STATUS_SUCCESS, 1532 PREPARE_DRM_STATUS_PROVISIONING_NETWORK_ERROR, 1533 PREPARE_DRM_STATUS_PROVISIONING_SERVER_ERROR, 1534 PREPARE_DRM_STATUS_PREPARATION_ERROR, 1535 }) 1536 @Retention(RetentionPolicy.SOURCE) 1537 @RestrictTo(LIBRARY_GROUP) 1538 public @interface PrepareDrmStatusCode {} 1539 1540 /** 1541 * Retrieves the DRM Info associated with the current source 1542 * 1543 * @throws IllegalStateException if called before being prepared 1544 */ 1545 public abstract DrmInfo getDrmInfo(); 1546 1547 /** 1548 * Prepares the DRM for the current source 1549 * <p> 1550 * If {@link OnDrmConfigHelper} is registered, it will be called during 1551 * preparation to allow configuration of the DRM properties before opening the 1552 * DRM session. Note that the callback is called synchronously in the thread that called 1553 * {@link #prepareDrm}. It should be used only for a series of {@code getDrmPropertyString} 1554 * and {@code setDrmPropertyString} calls and refrain from any lengthy operation. 1555 * <p> 1556 * If the device has not been provisioned before, this call also provisions the device 1557 * which involves accessing the provisioning server and can take a variable time to 1558 * complete depending on the network connectivity. 1559 * If {@code OnDrmPreparedListener} is registered, prepareDrm() runs in non-blocking 1560 * mode by launching the provisioning in the background and returning. The listener 1561 * will be called when provisioning and preparation has finished. If a 1562 * {@code OnDrmPreparedListener} is not registered, prepareDrm() waits till provisioning 1563 * and preparation has finished, i.e., runs in blocking mode. 1564 * <p> 1565 * If {@code OnDrmPreparedListener} is registered, it is called to indicate the DRM 1566 * session being ready. The application should not make any assumption about its call 1567 * sequence (e.g., before or after prepareDrm returns), or the thread context that will 1568 * execute the listener (unless the listener is registered with a handler thread). 1569 * <p> 1570 * 1571 * @param uuid The UUID of the crypto scheme. If not known beforehand, it can be retrieved 1572 * from the source through {@code getDrmInfo} or registering a {@code onDrmInfoListener}. 1573 * 1574 * @throws IllegalStateException if called before being prepared or the DRM was 1575 * prepared already 1576 * @throws UnsupportedSchemeException if the crypto scheme is not supported 1577 * @throws ResourceBusyException if required DRM resources are in use 1578 * @throws ProvisioningNetworkErrorException if provisioning is required but failed due to a 1579 * network error 1580 * @throws ProvisioningServerErrorException if provisioning is required but failed due to 1581 * the request denied by the provisioning server 1582 */ 1583 // This is a synchronous call. 1584 public abstract void prepareDrm(@NonNull UUID uuid) 1585 throws UnsupportedSchemeException, ResourceBusyException, 1586 ProvisioningNetworkErrorException, ProvisioningServerErrorException; 1587 1588 /** 1589 * Releases the DRM session 1590 * <p> 1591 * The player has to have an active DRM session and be in stopped, or prepared 1592 * state before this call is made. 1593 * A {@code reset()} call will release the DRM session implicitly. 1594 * 1595 * @throws NoDrmSchemeException if there is no active DRM session to release 1596 */ 1597 // This is an asynchronous call. 1598 public abstract void releaseDrm() throws NoDrmSchemeException; 1599 1600 /** 1601 * A key request/response exchange occurs between the app and a license server 1602 * to obtain or release keys used to decrypt encrypted content. 1603 * <p> 1604 * getDrmKeyRequest() is used to obtain an opaque key request byte array that is 1605 * delivered to the license server. The opaque key request byte array is returned 1606 * in KeyRequest.data. The recommended URL to deliver the key request to is 1607 * returned in KeyRequest.defaultUrl. 1608 * <p> 1609 * After the app has received the key request response from the server, 1610 * it should deliver to the response to the DRM engine plugin using the method 1611 * {@link #provideDrmKeyResponse}. 1612 * 1613 * @param keySetId is the key-set identifier of the offline keys being released when keyType is 1614 * {@link MediaDrm#KEY_TYPE_RELEASE}. It should be set to null for other key requests, when 1615 * keyType is {@link MediaDrm#KEY_TYPE_STREAMING} or {@link MediaDrm#KEY_TYPE_OFFLINE}. 1616 * 1617 * @param initData is the container-specific initialization data when the keyType is 1618 * {@link MediaDrm#KEY_TYPE_STREAMING} or {@link MediaDrm#KEY_TYPE_OFFLINE}. Its meaning is 1619 * interpreted based on the mime type provided in the mimeType parameter. It could 1620 * contain, for example, the content ID, key ID or other data obtained from the content 1621 * metadata that is required in generating the key request. 1622 * When the keyType is {@link MediaDrm#KEY_TYPE_RELEASE}, it should be set to null. 1623 * 1624 * @param mimeType identifies the mime type of the content 1625 * 1626 * @param keyType specifies the type of the request. The request may be to acquire 1627 * keys for streaming, {@link MediaDrm#KEY_TYPE_STREAMING}, or for offline content 1628 * {@link MediaDrm#KEY_TYPE_OFFLINE}, or to release previously acquired 1629 * keys ({@link MediaDrm#KEY_TYPE_RELEASE}), which are identified by a keySetId. 1630 * 1631 * @param optionalParameters are included in the key request message to 1632 * allow a client application to provide additional message parameters to the server. 1633 * This may be {@code null} if no additional parameters are to be sent. 1634 * 1635 * @throws NoDrmSchemeException if there is no active DRM session 1636 */ 1637 @NonNull 1638 public abstract MediaDrm.KeyRequest getDrmKeyRequest( 1639 @Nullable byte[] keySetId, @Nullable byte[] initData, 1640 @Nullable String mimeType, int keyType, 1641 @Nullable Map<String, String> optionalParameters) 1642 throws NoDrmSchemeException; 1643 1644 /** 1645 * A key response is received from the license server by the app, then it is 1646 * provided to the DRM engine plugin using provideDrmKeyResponse. When the 1647 * response is for an offline key request, a key-set identifier is returned that 1648 * can be used to later restore the keys to a new session with the method 1649 * {@ link # restoreDrmKeys}. 1650 * When the response is for a streaming or release request, null is returned. 1651 * 1652 * @param keySetId When the response is for a release request, keySetId identifies 1653 * the saved key associated with the release request (i.e., the same keySetId 1654 * passed to the earlier {@ link # getDrmKeyRequest} call. It MUST be null when the 1655 * response is for either streaming or offline key requests. 1656 * 1657 * @param response the byte array response from the server 1658 * 1659 * @throws NoDrmSchemeException if there is no active DRM session 1660 * @throws DeniedByServerException if the response indicates that the 1661 * server rejected the request 1662 */ 1663 // This is a synchronous call. 1664 public abstract byte[] provideDrmKeyResponse( 1665 @Nullable byte[] keySetId, @NonNull byte[] response) 1666 throws NoDrmSchemeException, DeniedByServerException; 1667 1668 /** 1669 * Restore persisted offline keys into a new session. keySetId identifies the 1670 * keys to load, obtained from a prior call to {@link #provideDrmKeyResponse}. 1671 * 1672 * @param keySetId identifies the saved key set to restore 1673 */ 1674 // This is an asynchronous call. 1675 public abstract void restoreDrmKeys(@NonNull byte[] keySetId) 1676 throws NoDrmSchemeException; 1677 1678 /** 1679 * Read a DRM engine plugin String property value, given the property name string. 1680 * <p> 1681 * @param propertyName the property name 1682 * 1683 * Standard fields names are: 1684 * {@link MediaDrm#PROPERTY_VENDOR}, {@link MediaDrm#PROPERTY_VERSION}, 1685 * {@link MediaDrm#PROPERTY_DESCRIPTION}, {@link MediaDrm#PROPERTY_ALGORITHMS} 1686 */ 1687 @NonNull 1688 public abstract String getDrmPropertyString( 1689 @NonNull String propertyName) 1690 throws NoDrmSchemeException; 1691 1692 /** 1693 * Set a DRM engine plugin String property value. 1694 * <p> 1695 * @param propertyName the property name 1696 * @param value the property value 1697 * 1698 * Standard fields names are: 1699 * {@link MediaDrm#PROPERTY_VENDOR}, {@link MediaDrm#PROPERTY_VERSION}, 1700 * {@link MediaDrm#PROPERTY_DESCRIPTION}, {@link MediaDrm#PROPERTY_ALGORITHMS} 1701 */ 1702 // This is a synchronous call. 1703 public abstract void setDrmPropertyString( 1704 @NonNull String propertyName, @NonNull String value) 1705 throws NoDrmSchemeException; 1706 1707 /** 1708 * Encapsulates the DRM properties of the source. 1709 */ 1710 public abstract static class DrmInfo { 1711 /** 1712 * Returns the PSSH info of the data source for each supported DRM scheme. 1713 */ 1714 public abstract Map<UUID, byte[]> getPssh(); 1715 1716 /** 1717 * Returns the intersection of the data source and the device DRM schemes. 1718 * It effectively identifies the subset of the source's DRM schemes which 1719 * are supported by the device too. 1720 */ 1721 public abstract List<UUID> getSupportedSchemes(); 1722 }; // DrmInfo 1723 1724 /** 1725 * Thrown when a DRM method is called before preparing a DRM scheme through prepareDrm(). 1726 * Extends MediaDrm.MediaDrmException 1727 */ 1728 public static class NoDrmSchemeException extends MediaDrmException { 1729 public NoDrmSchemeException(String detailMessage) { 1730 super(detailMessage); 1731 } 1732 } 1733 1734 /** 1735 * Thrown when the device requires DRM provisioning but the provisioning attempt has 1736 * failed due to a network error (Internet reachability, timeout, etc.). 1737 * Extends MediaDrm.MediaDrmException 1738 */ 1739 public static class ProvisioningNetworkErrorException extends MediaDrmException { 1740 public ProvisioningNetworkErrorException(String detailMessage) { 1741 super(detailMessage); 1742 } 1743 } 1744 1745 /** 1746 * Thrown when the device requires DRM provisioning but the provisioning attempt has 1747 * failed due to the provisioning server denying the request. 1748 * Extends MediaDrm.MediaDrmException 1749 */ 1750 public static class ProvisioningServerErrorException extends MediaDrmException { 1751 public ProvisioningServerErrorException(String detailMessage) { 1752 super(detailMessage); 1753 } 1754 } 1755 1756 /** 1757 * Definitions for the metrics that are reported via the {@link #getMetrics} call. 1758 */ 1759 public static final class MetricsConstants { 1760 private MetricsConstants() {} 1761 1762 /** 1763 * Key to extract the MIME type of the video track 1764 * from the {@link MediaPlayer2#getMetrics} return value. 1765 * The value is a String. 1766 */ 1767 public static final String MIME_TYPE_VIDEO = "android.media.mediaplayer.video.mime"; 1768 1769 /** 1770 * Key to extract the codec being used to decode the video track 1771 * from the {@link MediaPlayer2#getMetrics} return value. 1772 * The value is a String. 1773 */ 1774 public static final String CODEC_VIDEO = "android.media.mediaplayer.video.codec"; 1775 1776 /** 1777 * Key to extract the width (in pixels) of the video track 1778 * from the {@link MediaPlayer2#getMetrics} return value. 1779 * The value is an integer. 1780 */ 1781 public static final String WIDTH = "android.media.mediaplayer.width"; 1782 1783 /** 1784 * Key to extract the height (in pixels) of the video track 1785 * from the {@link MediaPlayer2#getMetrics} return value. 1786 * The value is an integer. 1787 */ 1788 public static final String HEIGHT = "android.media.mediaplayer.height"; 1789 1790 /** 1791 * Key to extract the count of video frames played 1792 * from the {@link MediaPlayer2#getMetrics} return value. 1793 * The value is an integer. 1794 */ 1795 public static final String FRAMES = "android.media.mediaplayer.frames"; 1796 1797 /** 1798 * Key to extract the count of video frames dropped 1799 * from the {@link MediaPlayer2#getMetrics} return value. 1800 * The value is an integer. 1801 */ 1802 public static final String FRAMES_DROPPED = "android.media.mediaplayer.dropped"; 1803 1804 /** 1805 * Key to extract the MIME type of the audio track 1806 * from the {@link MediaPlayer2#getMetrics} return value. 1807 * The value is a String. 1808 */ 1809 public static final String MIME_TYPE_AUDIO = "android.media.mediaplayer.audio.mime"; 1810 1811 /** 1812 * Key to extract the codec being used to decode the audio track 1813 * from the {@link MediaPlayer2#getMetrics} return value. 1814 * The value is a String. 1815 */ 1816 public static final String CODEC_AUDIO = "android.media.mediaplayer.audio.codec"; 1817 1818 /** 1819 * Key to extract the duration (in milliseconds) of the 1820 * media being played 1821 * from the {@link MediaPlayer2#getMetrics} return value. 1822 * The value is a long. 1823 */ 1824 public static final String DURATION = "android.media.mediaplayer.durationMs"; 1825 1826 /** 1827 * Key to extract the playing time (in milliseconds) of the 1828 * media being played 1829 * from the {@link MediaPlayer2#getMetrics} return value. 1830 * The value is a long. 1831 */ 1832 public static final String PLAYING = "android.media.mediaplayer.playingMs"; 1833 1834 /** 1835 * Key to extract the count of errors encountered while 1836 * playing the media 1837 * from the {@link MediaPlayer2#getMetrics} return value. 1838 * The value is an integer. 1839 */ 1840 public static final String ERRORS = "android.media.mediaplayer.err"; 1841 1842 /** 1843 * Key to extract an (optional) error code detected while 1844 * playing the media 1845 * from the {@link MediaPlayer2#getMetrics} return value. 1846 * The value is an integer. 1847 */ 1848 public static final String ERROR_CODE = "android.media.mediaplayer.errcode"; 1849 1850 } 1851} 1852