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 17 package android.media; 18 19 import android.annotation.NonNull; 20 import android.annotation.Nullable; 21 import android.annotation.StringDef; 22 import android.graphics.Bitmap; 23 import android.media.update.ApiLoader; 24 import android.media.update.MediaMetadata2Provider; 25 import android.net.Uri; 26 import android.os.Bundle; 27 28 import java.lang.annotation.Retention; 29 import java.lang.annotation.RetentionPolicy; 30 import java.util.Set; 31 32 /** 33 * @hide 34 * Contains metadata about an item, such as the title, artist, etc. 35 */ 36 // New version of MediaMetadata with following changes 37 // - Don't implement Parcelable for updatable support. 38 // - Also support MediaDescription features. MediaDescription is deprecated instead because 39 // it was insufficient for controller to display media contents. 40 public final class MediaMetadata2 { 41 /** 42 * The metadata key for a {@link CharSequence} or {@link String} typed value to retrieve the 43 * information about the title of the media. 44 * 45 * @see Builder#putText(String, CharSequence) 46 * @see Builder#putString(String, String) 47 * @see #getText(String) 48 * @see #getString(String) 49 */ 50 public static final String METADATA_KEY_TITLE = "android.media.metadata.TITLE"; 51 52 /** 53 * The metadata key for a {@link CharSequence} or {@link String} typed value to retrieve the 54 * information about the artist of the media. 55 * 56 * @see Builder#putText(String, CharSequence) 57 * @see Builder#putString(String, String) 58 * @see #getText(String) 59 * @see #getString(String) 60 */ 61 public static final String METADATA_KEY_ARTIST = "android.media.metadata.ARTIST"; 62 63 /** 64 * The metadata key for a {@link Long} typed value to retrieve the information about the 65 * duration of the media in ms. A negative duration indicates that the duration is unknown 66 * (or infinite). 67 * 68 * @see Builder#putLong(String, long) 69 * @see #getLong(String) 70 */ 71 public static final String METADATA_KEY_DURATION = "android.media.metadata.DURATION"; 72 73 /** 74 * The metadata key for a {@link CharSequence} or {@link String} typed value to retrieve the 75 * information about the album title for the media. 76 * 77 * @see Builder#putText(String, CharSequence) 78 * @see Builder#putString(String, String) 79 * @see #getText(String) 80 * @see #getString(String) 81 */ 82 public static final String METADATA_KEY_ALBUM = "android.media.metadata.ALBUM"; 83 84 /** 85 * The metadata key for a {@link CharSequence} or {@link String} typed value to retrieve the 86 * information about the author of the media. 87 * 88 * @see Builder#putText(String, CharSequence) 89 * @see Builder#putString(String, String) 90 * @see #getText(String) 91 * @see #getString(String) 92 */ 93 public static final String METADATA_KEY_AUTHOR = "android.media.metadata.AUTHOR"; 94 95 /** 96 * The metadata key for a {@link CharSequence} or {@link String} typed value to retrieve the 97 * information about the writer of the media. 98 * 99 * @see Builder#putText(String, CharSequence) 100 * @see Builder#putString(String, String) 101 * @see #getText(String) 102 * @see #getString(String) 103 */ 104 public static final String METADATA_KEY_WRITER = "android.media.metadata.WRITER"; 105 106 /** 107 * The metadata key for a {@link CharSequence} or {@link String} typed value to retrieve the 108 * information about the composer of the media. 109 * 110 * @see Builder#putText(String, CharSequence) 111 * @see Builder#putString(String, String) 112 * @see #getText(String) 113 * @see #getString(String) 114 */ 115 public static final String METADATA_KEY_COMPOSER = "android.media.metadata.COMPOSER"; 116 117 /** 118 * The metadata key for a {@link CharSequence} or {@link String} typed value to retrieve the 119 * information about the compilation status of the media. 120 * 121 * @see Builder#putText(String, CharSequence) 122 * @see Builder#putString(String, String) 123 * @see #getText(String) 124 * @see #getString(String) 125 */ 126 public static final String METADATA_KEY_COMPILATION = "android.media.metadata.COMPILATION"; 127 128 /** 129 * The metadata key for a {@link CharSequence} or {@link String} typed value to retrieve the 130 * information about the date the media was created or published. 131 * The format is unspecified but RFC 3339 is recommended. 132 * 133 * @see Builder#putText(String, CharSequence) 134 * @see Builder#putString(String, String) 135 * @see #getText(String) 136 * @see #getString(String) 137 */ 138 public static final String METADATA_KEY_DATE = "android.media.metadata.DATE"; 139 140 /** 141 * The metadata key for a {@link Long} typed value to retrieve the information about the year 142 * the media was created or published. 143 * 144 * @see Builder#putLong(String, long) 145 * @see #getLong(String) 146 */ 147 public static final String METADATA_KEY_YEAR = "android.media.metadata.YEAR"; 148 149 /** 150 * The metadata key for a {@link CharSequence} or {@link String} typed value to retrieve the 151 * information about the genre of the media. 152 * 153 * @see Builder#putText(String, CharSequence) 154 * @see Builder#putString(String, String) 155 * @see #getText(String) 156 * @see #getString(String) 157 */ 158 public static final String METADATA_KEY_GENRE = "android.media.metadata.GENRE"; 159 160 /** 161 * The metadata key for a {@link Long} typed value to retrieve the information about the 162 * track number for the media. 163 * 164 * @see Builder#putLong(String, long) 165 * @see #getLong(String) 166 */ 167 public static final String METADATA_KEY_TRACK_NUMBER = "android.media.metadata.TRACK_NUMBER"; 168 169 /** 170 * The metadata key for a {@link Long} typed value to retrieve the information about the 171 * number of tracks in the media's original source. 172 * 173 * @see Builder#putLong(String, long) 174 * @see #getLong(String) 175 */ 176 public static final String METADATA_KEY_NUM_TRACKS = "android.media.metadata.NUM_TRACKS"; 177 178 /** 179 * The metadata key for a {@link Long} typed value to retrieve the information about the 180 * disc number for the media's original source. 181 * 182 * @see Builder#putLong(String, long) 183 * @see #getLong(String) 184 */ 185 public static final String METADATA_KEY_DISC_NUMBER = "android.media.metadata.DISC_NUMBER"; 186 187 /** 188 * The metadata key for a {@link CharSequence} or {@link String} typed value to retrieve the 189 * information about the artist for the album of the media's original source. 190 * 191 * @see Builder#putText(String, CharSequence) 192 * @see Builder#putString(String, String) 193 * @see #getText(String) 194 * @see #getString(String) 195 */ 196 public static final String METADATA_KEY_ALBUM_ARTIST = "android.media.metadata.ALBUM_ARTIST"; 197 198 /** 199 * The metadata key for a {@link Bitmap} typed value to retrieve the information about the 200 * artwork for the media. 201 * The artwork should be relatively small and may be scaled down if it is too large. 202 * For higher resolution artwork, {@link #METADATA_KEY_ART_URI} should be used instead. 203 * 204 * @see Builder#putBitmap(String, Bitmap) 205 * @see #getBitmap(String) 206 */ 207 public static final String METADATA_KEY_ART = "android.media.metadata.ART"; 208 209 /** 210 * The metadata key for a {@link CharSequence} or {@link String} typed value to retrieve the 211 * information about Uri of the artwork for the media. 212 * 213 * @see Builder#putText(String, CharSequence) 214 * @see Builder#putString(String, String) 215 * @see #getText(String) 216 * @see #getString(String) 217 */ 218 public static final String METADATA_KEY_ART_URI = "android.media.metadata.ART_URI"; 219 220 /** 221 * The metadata key for a {@link Bitmap} typed value to retrieve the information about the 222 * artwork for the album of the media's original source. 223 * The artwork should be relatively small and may be scaled down if it is too large. 224 * For higher resolution artwork, {@link #METADATA_KEY_ALBUM_ART_URI} should be used instead. 225 * 226 * @see Builder#putBitmap(String, Bitmap) 227 * @see #getBitmap(String) 228 */ 229 public static final String METADATA_KEY_ALBUM_ART = "android.media.metadata.ALBUM_ART"; 230 231 /** 232 * The metadata key for a {@link CharSequence} or {@link String} typed value to retrieve the 233 * information about the Uri of the artwork for the album of the media's original source. 234 * 235 * @see Builder#putText(String, CharSequence) 236 * @see Builder#putString(String, String) 237 * @see #getText(String) 238 * @see #getString(String) 239 */ 240 public static final String METADATA_KEY_ALBUM_ART_URI = "android.media.metadata.ALBUM_ART_URI"; 241 242 /** 243 * The metadata key for a {@link Rating2} typed value to retrieve the information about the 244 * user's rating for the media. 245 * 246 * @see Builder#putRating(String, Rating2) 247 * @see #getRating(String) 248 */ 249 public static final String METADATA_KEY_USER_RATING = "android.media.metadata.USER_RATING"; 250 251 /** 252 * The metadata key for a {@link Rating2} typed value to retrieve the information about the 253 * overall rating for the media. 254 * 255 * @see Builder#putRating(String, Rating2) 256 * @see #getRating(String) 257 */ 258 public static final String METADATA_KEY_RATING = "android.media.metadata.RATING"; 259 260 /** 261 * The metadata key for a {@link CharSequence} or {@link String} typed value to retrieve the 262 * information about the title that is suitable for display to the user. 263 * It will generally be the same as {@link #METADATA_KEY_TITLE} but may differ for some formats. 264 * When displaying media described by this metadata, this should be preferred if present. 265 * 266 * @see Builder#putText(String, CharSequence) 267 * @see Builder#putString(String, String) 268 * @see #getText(String) 269 * @see #getString(String) 270 */ 271 public static final String METADATA_KEY_DISPLAY_TITLE = "android.media.metadata.DISPLAY_TITLE"; 272 273 /** 274 * The metadata key for a {@link CharSequence} or {@link String} typed value to retrieve the 275 * information about the subtitle that is suitable for display to the user. 276 * When displaying a second line for media described by this metadata, this should be preferred 277 * to other fields if present. 278 * 279 * @see Builder#putText(String, CharSequence) 280 * @see Builder#putString(String, String) 281 * @see #getText(String) 282 * @see #getString(String) 283 */ 284 public static final String METADATA_KEY_DISPLAY_SUBTITLE 285 = "android.media.metadata.DISPLAY_SUBTITLE"; 286 287 /** 288 * The metadata key for a {@link CharSequence} or {@link String} typed value to retrieve the 289 * information about the description that is suitable for display to the user. 290 * When displaying more information for media described by this metadata, 291 * this should be preferred to other fields if present. 292 * 293 * @see Builder#putText(String, CharSequence) 294 * @see Builder#putString(String, String) 295 * @see #getText(String) 296 * @see #getString(String) 297 */ 298 public static final String METADATA_KEY_DISPLAY_DESCRIPTION 299 = "android.media.metadata.DISPLAY_DESCRIPTION"; 300 301 /** 302 * The metadata key for a {@link Bitmap} typed value to retrieve the information about the icon 303 * or thumbnail that is suitable for display to the user. 304 * When displaying an icon for media described by this metadata, this should be preferred to 305 * other fields if present. 306 * <p> 307 * The icon should be relatively small and may be scaled down if it is too large. 308 * For higher resolution artwork, {@link #METADATA_KEY_DISPLAY_ICON_URI} should be used instead. 309 * 310 * @see Builder#putBitmap(String, Bitmap) 311 * @see #getBitmap(String) 312 */ 313 public static final String METADATA_KEY_DISPLAY_ICON = "android.media.metadata.DISPLAY_ICON"; 314 315 /** 316 * The metadata key for a {@link CharSequence} or {@link String} typed value to retrieve the 317 * information about the Uri of icon or thumbnail that is suitable for display to the user. 318 * When displaying more information for media described by this metadata, the 319 * display description should be preferred to other fields when present. 320 * 321 * @see Builder#putText(String, CharSequence) 322 * @see Builder#putString(String, String) 323 * @see #getText(String) 324 * @see #getString(String) 325 */ 326 public static final String METADATA_KEY_DISPLAY_ICON_URI 327 = "android.media.metadata.DISPLAY_ICON_URI"; 328 329 /** 330 * The metadata key for a {@link CharSequence} or {@link String} typed value to retrieve the 331 * information about the media ID of the content. This value is specific to the 332 * service providing the content. If used, this should be a persistent 333 * unique key for the underlying content. It may be used with 334 * {@link MediaController2#playFromMediaId(String, Bundle)} 335 * to initiate playback when provided by a {@link MediaBrowser2} connected to 336 * the same app. 337 * 338 * @see Builder#putText(String, CharSequence) 339 * @see Builder#putString(String, String) 340 * @see #getText(String) 341 * @see #getString(String) 342 */ 343 public static final String METADATA_KEY_MEDIA_ID = "android.media.metadata.MEDIA_ID"; 344 345 /** 346 * The metadata key for a {@link CharSequence} or {@link String} typed value to retrieve the 347 * information about the Uri of the content. This value is specific to the service providing the 348 * content. It may be used with {@link MediaController2#playFromUri(Uri, Bundle)} 349 * to initiate playback when provided by a {@link MediaBrowser2} connected to the same app. 350 * 351 * @see Builder#putText(String, CharSequence) 352 * @see Builder#putString(String, String) 353 * @see #getText(String) 354 * @see #getString(String) 355 */ 356 public static final String METADATA_KEY_MEDIA_URI = "android.media.metadata.MEDIA_URI"; 357 358 /** 359 * The metadata key for a {@link Long} typed value to retrieve the information about the 360 * bluetooth folder type of the media specified in the section 6.10.2.2 of the Bluetooth 361 * AVRCP 1.5. It should be one of the following: 362 * <ul> 363 * <li>{@link #BT_FOLDER_TYPE_MIXED}</li> 364 * <li>{@link #BT_FOLDER_TYPE_TITLES}</li> 365 * <li>{@link #BT_FOLDER_TYPE_ALBUMS}</li> 366 * <li>{@link #BT_FOLDER_TYPE_ARTISTS}</li> 367 * <li>{@link #BT_FOLDER_TYPE_GENRES}</li> 368 * <li>{@link #BT_FOLDER_TYPE_PLAYLISTS}</li> 369 * <li>{@link #BT_FOLDER_TYPE_YEARS}</li> 370 * </ul> 371 * 372 * @see Builder#putLong(String, long) 373 * @see #getLong(String) 374 */ 375 public static final String METADATA_KEY_BT_FOLDER_TYPE 376 = "android.media.metadata.BT_FOLDER_TYPE"; 377 378 /** 379 * The type of folder that is unknown or contains media elements of mixed types as specified in 380 * the section 6.10.2.2 of the Bluetooth AVRCP 1.5. 381 */ 382 public static final long BT_FOLDER_TYPE_MIXED = 0; 383 384 /** 385 * The type of folder that contains media elements only as specified in the section 6.10.2.2 of 386 * the Bluetooth AVRCP 1.5. 387 */ 388 public static final long BT_FOLDER_TYPE_TITLES = 1; 389 390 /** 391 * The type of folder that contains folders categorized by album as specified in the section 392 * 6.10.2.2 of the Bluetooth AVRCP 1.5. 393 */ 394 public static final long BT_FOLDER_TYPE_ALBUMS = 2; 395 396 /** 397 * The type of folder that contains folders categorized by artist as specified in the section 398 * 6.10.2.2 of the Bluetooth AVRCP 1.5. 399 */ 400 public static final long BT_FOLDER_TYPE_ARTISTS = 3; 401 402 /** 403 * The type of folder that contains folders categorized by genre as specified in the section 404 * 6.10.2.2 of the Bluetooth AVRCP 1.5. 405 */ 406 public static final long BT_FOLDER_TYPE_GENRES = 4; 407 408 /** 409 * The type of folder that contains folders categorized by playlist as specified in the section 410 * 6.10.2.2 of the Bluetooth AVRCP 1.5. 411 */ 412 public static final long BT_FOLDER_TYPE_PLAYLISTS = 5; 413 414 /** 415 * The type of folder that contains folders categorized by year as specified in the section 416 * 6.10.2.2 of the Bluetooth AVRCP 1.5. 417 */ 418 public static final long BT_FOLDER_TYPE_YEARS = 6; 419 420 /** 421 * The metadata key for a {@link Long} typed value to retrieve the information about whether 422 * the media is an advertisement. A value of 0 indicates it is not an advertisement. 423 * A value of 1 or non-zero indicates it is an advertisement. 424 * If not specified, this value is set to 0 by default. 425 * 426 * @see Builder#putLong(String, long) 427 * @see #getLong(String) 428 */ 429 public static final String METADATA_KEY_ADVERTISEMENT = "android.media.metadata.ADVERTISEMENT"; 430 431 /** 432 * The metadata key for a {@link Long} typed value to retrieve the information about the 433 * download status of the media which will be used for later offline playback. It should be 434 * one of the following: 435 * 436 * <ul> 437 * <li>{@link #STATUS_NOT_DOWNLOADED}</li> 438 * <li>{@link #STATUS_DOWNLOADING}</li> 439 * <li>{@link #STATUS_DOWNLOADED}</li> 440 * </ul> 441 * 442 * @see Builder#putLong(String, long) 443 * @see #getLong(String) 444 */ 445 public static final String METADATA_KEY_DOWNLOAD_STATUS = 446 "android.media.metadata.DOWNLOAD_STATUS"; 447 448 /** 449 * The status value to indicate the media item is not downloaded. 450 * 451 * @see #METADATA_KEY_DOWNLOAD_STATUS 452 */ 453 public static final long STATUS_NOT_DOWNLOADED = 0; 454 455 /** 456 * The status value to indicate the media item is being downloaded. 457 * 458 * @see #METADATA_KEY_DOWNLOAD_STATUS 459 */ 460 public static final long STATUS_DOWNLOADING = 1; 461 462 /** 463 * The status value to indicate the media item is downloaded for later offline playback. 464 * 465 * @see #METADATA_KEY_DOWNLOAD_STATUS 466 */ 467 public static final long STATUS_DOWNLOADED = 2; 468 469 /** 470 * A {@link Bundle} extra. 471 */ 472 public static final String METADATA_KEY_EXTRAS = "android.media.metadata.EXTRAS"; 473 474 /** 475 * @hide 476 */ 477 @StringDef({METADATA_KEY_TITLE, METADATA_KEY_ARTIST, METADATA_KEY_ALBUM, METADATA_KEY_AUTHOR, 478 METADATA_KEY_WRITER, METADATA_KEY_COMPOSER, METADATA_KEY_COMPILATION, 479 METADATA_KEY_DATE, METADATA_KEY_GENRE, METADATA_KEY_ALBUM_ARTIST, METADATA_KEY_ART_URI, 480 METADATA_KEY_ALBUM_ART_URI, METADATA_KEY_DISPLAY_TITLE, METADATA_KEY_DISPLAY_SUBTITLE, 481 METADATA_KEY_DISPLAY_DESCRIPTION, METADATA_KEY_DISPLAY_ICON_URI, 482 METADATA_KEY_MEDIA_ID, METADATA_KEY_MEDIA_URI}) 483 @Retention(RetentionPolicy.SOURCE) 484 public @interface TextKey {} 485 486 /** 487 * @hide 488 */ 489 @StringDef({METADATA_KEY_DURATION, METADATA_KEY_YEAR, METADATA_KEY_TRACK_NUMBER, 490 METADATA_KEY_NUM_TRACKS, METADATA_KEY_DISC_NUMBER, METADATA_KEY_BT_FOLDER_TYPE, 491 METADATA_KEY_ADVERTISEMENT, METADATA_KEY_DOWNLOAD_STATUS}) 492 @Retention(RetentionPolicy.SOURCE) 493 public @interface LongKey {} 494 495 /** 496 * @hide 497 */ 498 @StringDef({METADATA_KEY_ART, METADATA_KEY_ALBUM_ART, METADATA_KEY_DISPLAY_ICON}) 499 @Retention(RetentionPolicy.SOURCE) 500 public @interface BitmapKey {} 501 502 /** 503 * @hide 504 */ 505 @StringDef({METADATA_KEY_USER_RATING, METADATA_KEY_RATING}) 506 @Retention(RetentionPolicy.SOURCE) 507 public @interface RatingKey {} 508 509 /** 510 * @hide 511 */ 512 // TODO(jaewan): Add predefined float key. 513 @Retention(RetentionPolicy.SOURCE) 514 public @interface FloatKey {} 515 516 private final MediaMetadata2Provider mProvider; 517 518 /** 519 * @hide 520 */ 521 public MediaMetadata2(MediaMetadata2Provider provider) { 522 mProvider = provider; 523 } 524 525 /** 526 * Returns true if the given key is contained in the metadata 527 * 528 * @param key a String key 529 * @return true if the key exists in this metadata, false otherwise 530 */ 531 public boolean containsKey(@NonNull String key) { 532 return mProvider.containsKey_impl(key); 533 } 534 535 /** 536 * Returns the value associated with the given key, or null if no mapping of 537 * the desired type exists for the given key or a null value is explicitly 538 * associated with the key. 539 * 540 * @param key The key the value is stored under 541 * @return a CharSequence value, or null 542 */ 543 public @Nullable CharSequence getText(@NonNull @TextKey String key) { 544 return mProvider.getText_impl(key); 545 } 546 547 /** 548 * Returns the media id, or {@code null} if the id doesn't exist. 549 *<p> 550 * This is equivalent to the {@link #getString(String)} with the {@link #METADATA_KEY_MEDIA_ID}. 551 * 552 * @return media id. Can be {@code null} 553 * @see #METADATA_KEY_MEDIA_ID 554 */ 555 public @Nullable String getMediaId() { 556 return mProvider.getMediaId_impl(); 557 } 558 559 /** 560 * Returns the value associated with the given key, or null if no mapping of 561 * the desired type exists for the given key or a null value is explicitly 562 * associated with the key. 563 * 564 * @param key The key the value is stored under 565 * @return a String value, or null 566 */ 567 public @Nullable String getString(@NonNull @TextKey String key) { 568 return mProvider.getString_impl(key); 569 } 570 571 /** 572 * Returns the value associated with the given key, or 0L if no long exists 573 * for the given key. 574 * 575 * @param key The key the value is stored under 576 * @return a long value 577 */ 578 public long getLong(@NonNull @LongKey String key) { 579 return mProvider.getLong_impl(key); 580 } 581 582 /** 583 * Return a {@link Rating2} for the given key or null if no rating exists for 584 * the given key. 585 * <p> 586 * For the {@link #METADATA_KEY_USER_RATING}, A {@code null} return value means that user rating 587 * cannot be set by {@link MediaController2}. 588 * 589 * @param key The key the value is stored under 590 * @return A {@link Rating2} or {@code null} 591 */ 592 public @Nullable Rating2 getRating(@NonNull @RatingKey String key) { 593 return mProvider.getRating_impl(key); 594 } 595 596 /** 597 * Return a {@link Bitmap} for the given key or null if no bitmap exists for 598 * the given key. 599 * 600 * @param key The key the value is stored under 601 * @return A {@link Bitmap} or null 602 */ 603 public @Nullable Bitmap getBitmap(@NonNull @BitmapKey String key) { 604 return mProvider.getBitmap_impl(key); 605 } 606 607 /** 608 * Return the value associated with the given key, or 0.0f if no long exists 609 * for the given key. 610 * 611 * @param key The key the value is stored under 612 * @return a float value 613 */ 614 public float getFloat(@NonNull @FloatKey String key) { 615 return mProvider.getFloat_impl(key); 616 } 617 618 /** 619 * Get the extra {@link Bundle} from the metadata object. 620 * 621 * @return A {@link Bundle} or {@code null} 622 */ 623 public @Nullable Bundle getExtras() { 624 return mProvider.getExtras_impl(); 625 } 626 627 /** 628 * Get the number of fields in this metadata. 629 * 630 * @return The number of fields in the metadata. 631 */ 632 public int size() { 633 return mProvider.size_impl(); 634 } 635 636 /** 637 * Returns a Set containing the Strings used as keys in this metadata. 638 * 639 * @return a Set of String keys 640 */ 641 public @NonNull Set<String> keySet() { 642 return mProvider.keySet_impl(); 643 } 644 645 /** 646 * Gets the bundle backing the metadata object. This is available to support 647 * backwards compatibility. Apps should not modify the bundle directly. 648 * 649 * @return The Bundle backing this metadata. 650 */ 651 public @NonNull Bundle toBundle() { 652 return mProvider.toBundle_impl(); 653 } 654 655 /** 656 * Creates the {@link MediaMetadata2} from the bundle that previously returned by 657 * {@link #toBundle()}. 658 * 659 * @param bundle bundle for the metadata 660 * @return a new MediaMetadata2 661 */ 662 public static @NonNull MediaMetadata2 fromBundle(@Nullable Bundle bundle) { 663 return ApiLoader.getProvider().fromBundle_MediaMetadata2(bundle); 664 } 665 666 /** 667 * Use to build MediaMetadata2 objects. The system defined metadata keys must 668 * use the appropriate data type. 669 */ 670 public static final class Builder { 671 private final MediaMetadata2Provider.BuilderProvider mProvider; 672 673 /** 674 * Create an empty Builder. Any field that should be included in the 675 * {@link MediaMetadata2} must be added. 676 */ 677 public Builder() { 678 mProvider = ApiLoader.getProvider().createMediaMetadata2Builder(this); 679 } 680 681 /** 682 * Create a Builder using a {@link MediaMetadata2} instance to set the 683 * initial values. All fields in the source metadata will be included in 684 * the new metadata. Fields can be overwritten by adding the same key. 685 * 686 * @param source 687 */ 688 public Builder(@NonNull MediaMetadata2 source) { 689 mProvider = ApiLoader.getProvider().createMediaMetadata2Builder(this, source); 690 } 691 692 /** 693 * @hide 694 */ 695 public Builder(@NonNull MediaMetadata2Provider.BuilderProvider provider) { 696 mProvider = provider; 697 } 698 699 /** 700 * Put a CharSequence value into the metadata. Custom keys may be used, 701 * but if the METADATA_KEYs defined in this class are used they may only 702 * be one of the following: 703 * <ul> 704 * <li>{@link #METADATA_KEY_TITLE}</li> 705 * <li>{@link #METADATA_KEY_ARTIST}</li> 706 * <li>{@link #METADATA_KEY_ALBUM}</li> 707 * <li>{@link #METADATA_KEY_AUTHOR}</li> 708 * <li>{@link #METADATA_KEY_WRITER}</li> 709 * <li>{@link #METADATA_KEY_COMPOSER}</li> 710 * <li>{@link #METADATA_KEY_DATE}</li> 711 * <li>{@link #METADATA_KEY_GENRE}</li> 712 * <li>{@link #METADATA_KEY_ALBUM_ARTIST}</li> 713 * <li>{@link #METADATA_KEY_ART_URI}</li> 714 * <li>{@link #METADATA_KEY_ALBUM_ART_URI}</li> 715 * <li>{@link #METADATA_KEY_DISPLAY_TITLE}</li> 716 * <li>{@link #METADATA_KEY_DISPLAY_SUBTITLE}</li> 717 * <li>{@link #METADATA_KEY_DISPLAY_DESCRIPTION}</li> 718 * <li>{@link #METADATA_KEY_DISPLAY_ICON_URI}</li> 719 * </ul> 720 * 721 * @param key The key for referencing this value 722 * @param value The CharSequence value to store 723 * @return The Builder to allow chaining 724 */ 725 public @NonNull Builder putText(@NonNull @TextKey String key, 726 @Nullable CharSequence value) { 727 return mProvider.putText_impl(key, value); 728 } 729 730 /** 731 * Put a String value into the metadata. Custom keys may be used, but if 732 * the METADATA_KEYs defined in this class are used they may only be one 733 * of the following: 734 * <ul> 735 * <li>{@link #METADATA_KEY_TITLE}</li> 736 * <li>{@link #METADATA_KEY_ARTIST}</li> 737 * <li>{@link #METADATA_KEY_ALBUM}</li> 738 * <li>{@link #METADATA_KEY_AUTHOR}</li> 739 * <li>{@link #METADATA_KEY_WRITER}</li> 740 * <li>{@link #METADATA_KEY_COMPOSER}</li> 741 * <li>{@link #METADATA_KEY_DATE}</li> 742 * <li>{@link #METADATA_KEY_GENRE}</li> 743 * <li>{@link #METADATA_KEY_ALBUM_ARTIST}</li> 744 * <li>{@link #METADATA_KEY_ART_URI}</li> 745 * <li>{@link #METADATA_KEY_ALBUM_ART_URI}</li> 746 * <li>{@link #METADATA_KEY_DISPLAY_TITLE}</li> 747 * <li>{@link #METADATA_KEY_DISPLAY_SUBTITLE}</li> 748 * <li>{@link #METADATA_KEY_DISPLAY_DESCRIPTION}</li> 749 * <li>{@link #METADATA_KEY_DISPLAY_ICON_URI}</li> 750 * </ul> 751 * 752 * @param key The key for referencing this value 753 * @param value The String value to store 754 * @return The Builder to allow chaining 755 */ 756 public @NonNull Builder putString(@NonNull @TextKey String key, 757 @Nullable String value) { 758 return mProvider.putString_impl(key, value); 759 } 760 761 /** 762 * Put a long value into the metadata. Custom keys may be used, but if 763 * the METADATA_KEYs defined in this class are used they may only be one 764 * of the following: 765 * <ul> 766 * <li>{@link #METADATA_KEY_DURATION}</li> 767 * <li>{@link #METADATA_KEY_TRACK_NUMBER}</li> 768 * <li>{@link #METADATA_KEY_NUM_TRACKS}</li> 769 * <li>{@link #METADATA_KEY_DISC_NUMBER}</li> 770 * <li>{@link #METADATA_KEY_YEAR}</li> 771 * <li>{@link #METADATA_KEY_BT_FOLDER_TYPE}</li> 772 * <li>{@link #METADATA_KEY_ADVERTISEMENT}</li> 773 * <li>{@link #METADATA_KEY_DOWNLOAD_STATUS}</li> 774 * </ul> 775 * 776 * @param key The key for referencing this value 777 * @param value The String value to store 778 * @return The Builder to allow chaining 779 */ 780 public @NonNull Builder putLong(@NonNull @LongKey String key, long value) { 781 return mProvider.putLong_impl(key, value); 782 } 783 784 /** 785 * Put a {@link Rating2} into the metadata. Custom keys may be used, but 786 * if the METADATA_KEYs defined in this class are used they may only be 787 * one of the following: 788 * <ul> 789 * <li>{@link #METADATA_KEY_RATING}</li> 790 * <li>{@link #METADATA_KEY_USER_RATING}</li> 791 * </ul> 792 * 793 * @param key The key for referencing this value 794 * @param value The String value to store 795 * @return The Builder to allow chaining 796 */ 797 public @NonNull Builder putRating(@NonNull @RatingKey String key, @Nullable Rating2 value) { 798 return mProvider.putRating_impl(key, value); 799 } 800 801 /** 802 * Put a {@link Bitmap} into the metadata. Custom keys may be used, but 803 * if the METADATA_KEYs defined in this class are used they may only be 804 * one of the following: 805 * <ul> 806 * <li>{@link #METADATA_KEY_ART}</li> 807 * <li>{@link #METADATA_KEY_ALBUM_ART}</li> 808 * <li>{@link #METADATA_KEY_DISPLAY_ICON}</li> 809 * </ul> 810 * Large bitmaps may be scaled down by the system when 811 * {@link android.media.session.MediaSession#setMetadata} is called. 812 * To pass full resolution images {@link Uri Uris} should be used with 813 * {@link #putString}. 814 * 815 * @param key The key for referencing this value 816 * @param value The Bitmap to store 817 * @return The Builder to allow chaining 818 */ 819 public @NonNull Builder putBitmap(@NonNull @BitmapKey String key, @Nullable Bitmap value) { 820 return mProvider.putBitmap_impl(key, value); 821 } 822 823 /** 824 * Put a float value into the metadata. Custom keys may be used. 825 * 826 * @param key The key for referencing this value 827 * @param value The float value to store 828 * @return The Builder to allow chaining 829 */ 830 public @NonNull Builder putFloat(@NonNull @LongKey String key, float value) { 831 return mProvider.putFloat_impl(key, value); 832 } 833 834 /** 835 * Set a bundle of extras. 836 * 837 * @param extras The extras to include with this description or null. 838 * @return The Builder to allow chaining 839 */ 840 public Builder setExtras(@Nullable Bundle extras) { 841 return mProvider.setExtras_impl(extras); 842 } 843 844 /** 845 * Creates a {@link MediaMetadata2} instance with the specified fields. 846 * 847 * @return The new MediaMetadata2 instance 848 */ 849 public @NonNull MediaMetadata2 build() { 850 return mProvider.build_impl(); 851 } 852 } 853 } 854 855
