Platform Android Studio Google Play Jetpack Kotlin Docs News
Overview Guides Reference Samples Design & Quality
Android Dev Summit, October 23-24: two days of technical content, directly from the Android team. Sign-up for livestream updates.

MediaMetadata

public final class MediaMetadata
extends Object implements VersionedParcelable

java.lang.Object
   ↳ androidx.media2.common.MediaMetadata

Contains metadata about an item, such as the title, artist, etc. This is optional, but you'd better to provide this as much as possible when you're using media widget and/or session APIs.

The media widget components build its UI based on the metadata here. For an example, MediaControlView will show title from the metadata.

The MediaLibraryService.MediaLibrarySession would require some metadata values when it provides MediaItems to MediaBrowser.

Topics covered here:

  1. Media ID
  2. Browsable type
  3. Playable
  4. Duration
  5. User rating

Media ID

If set, the media ID must be the persistent key for the underlying media contents, so MediaController and MediaBrowser can store the information and reuse it later. Some APIs requires a media ID (e.g. MediaController.setRating(String, Rating), so you'd better specify one.

Typical example of using media ID is the URI of the contents, but use it with the caution because the metadata is shared across the process in plain text.

The MediaLibraryService.MediaLibrarySession would require it for the library root, so MediaBrowser can call subsequent MediaBrowser.getChildren(String, int, int, MediaLibraryService.LibraryParams) with the ID.

Browsable type

Browsable defines whether the media item has children and type of children if any. With this, MediaBrowser can know whether the subsequent MediaBrowser.getChildren(String, int, int, MediaLibraryService.LibraryParams) would successfully run.

The MediaLibraryService.MediaLibrarySession would require the explicit browsable type for the media items returned by the MediaLibraryService.MediaLibrarySession.MediaLibrarySessionCallback.

Playable type

Playable defines whether the media item can be played or not. It may be possible for a playlist to contain a media item which isn't playable in order to show a disabled media item.

The MediaLibraryService.MediaLibrarySession would require the explicit playable value for the media items returned by the MediaLibraryService.MediaLibrarySession.MediaLibrarySessionCallback.

  • Duration The duration is the length of the contents. The MediaController can only get the duration through the metadata. This tells when would the playback ends, and also tells about the allowed range of MediaController.seekTo(long).

    If it's not set by developer, MediaSession would update the duration in the metadata with the SessionPlayer.getDuration().

  • User rating

    Prefer to have unrated user rating instead of null, so MediaController can know the possible user rating type for calling MediaController.setRating(String, Rating).

    Summary

    Nested classes

    class MediaMetadata.Builder

    Use to build MediaMetadatax objects. 

    Constants

    long BROWSABLE_TYPE_ALBUMS

    The type of browsable that contains browsable items categorized by album.

    long BROWSABLE_TYPE_ARTISTS

    The type of browsable that contains browsable items categorized by artist.

    long BROWSABLE_TYPE_GENRES

    The type of browsable that contains browsable items categorized by genre.

    long BROWSABLE_TYPE_MIXED

    The type of browsable that is unknown or contains media items of mixed types.

    long BROWSABLE_TYPE_NONE

    The type of browsable for non-browsable media item.

    long BROWSABLE_TYPE_PLAYLISTS

    The type of browsable that contains browsable items categorized by playlist.

    long BROWSABLE_TYPE_TITLES

    The type of browsable that only contains playable media items.

    long BROWSABLE_TYPE_YEARS

    The type of browsable that contains browsable items categorized by year.

    String METADATA_KEY_ADVERTISEMENT

    The metadata key for a Long typed value to retrieve the information about whether the media is an advertisement.

    String METADATA_KEY_ALBUM

    The metadata key for a CharSequence or String typed value to retrieve the information about the album title for the media.

    String METADATA_KEY_ALBUM_ART

    The metadata key for a Bitmap typed value to retrieve the information about the artwork for the album of the media's original source.

    String METADATA_KEY_ALBUM_ARTIST

    The metadata key for a CharSequence or String typed value to retrieve the information about the artist for the album of the media's original source.

    String METADATA_KEY_ALBUM_ART_URI

    The metadata key for a CharSequence or String typed value to retrieve the information about the Uri of the artwork for the album of the media's original source.

    String METADATA_KEY_ART

    The metadata key for a Bitmap typed value to retrieve the information about the artwork for the media.

    String METADATA_KEY_ARTIST

    The metadata key for a CharSequence or String typed value to retrieve the information about the artist of the media.

    String METADATA_KEY_ART_URI

    The metadata key for a CharSequence or String typed value to retrieve the information about Uri of the artwork for the media.

    String METADATA_KEY_AUTHOR

    The metadata key for a CharSequence or String typed value to retrieve the information about the author of the media.

    String METADATA_KEY_BROWSABLE

    The metadata key for a Long typed value to retrieve the information about the type of browsable.

    String METADATA_KEY_COMPILATION

    The metadata key for a CharSequence or String typed value to retrieve the information about the compilation status of the media.

    String METADATA_KEY_COMPOSER

    The metadata key for a CharSequence or String typed value to retrieve the information about the composer of the media.

    String METADATA_KEY_DATE

    The metadata key for a CharSequence or String typed value to retrieve the information about the date the media was created or published.

    String METADATA_KEY_DISC_NUMBER

    The metadata key for a Long typed value to retrieve the information about the disc number for the media's original source.

    String METADATA_KEY_DISPLAY_DESCRIPTION

    The metadata key for a CharSequence or String typed value to retrieve the information about the description that is suitable for display to the user.

    String METADATA_KEY_DISPLAY_ICON

    The metadata key for a Bitmap typed value to retrieve the information about the icon or thumbnail that is suitable for display to the user.

    String METADATA_KEY_DISPLAY_ICON_URI

    The metadata key for a CharSequence or String typed value to retrieve the information about the Uri of icon or thumbnail that is suitable for display to the user.

    String METADATA_KEY_DISPLAY_SUBTITLE

    The metadata key for a CharSequence or String typed value to retrieve the information about the subtitle that is suitable for display to the user.

    String METADATA_KEY_DISPLAY_TITLE

    The metadata key for a CharSequence or String typed value to retrieve the information about the title that is suitable for display to the user.

    String METADATA_KEY_DOWNLOAD_STATUS

    The metadata key for a Long typed value to retrieve the information about the download status of the media which will be used for later offline playback.

    String METADATA_KEY_DURATION

    The metadata key for a Long typed value to retrieve the information about the duration of the media in ms.

    String METADATA_KEY_EXTRAS

    A Bundle extra.

    String METADATA_KEY_GENRE

    The metadata key for a CharSequence or String typed value to retrieve the information about the genre of the media.

    String METADATA_KEY_MEDIA_ID

    The metadata key for a CharSequence or String typed value to retrieve the information about the media ID of the content.

    String METADATA_KEY_MEDIA_URI

    The metadata key for a CharSequence or String typed value to retrieve the information about the Uri of the content.

    String METADATA_KEY_NUM_TRACKS

    The metadata key for a Long typed value to retrieve the information about the number of tracks in the media's original source.

    String METADATA_KEY_PLAYABLE

    The metadata key for a Long typed value to retrieve the information about whether the media is playable.

    String METADATA_KEY_RATING

    The metadata key for a Rating typed value to retrieve the information about the overall rating for the media.

    String METADATA_KEY_TITLE

    The metadata key for a CharSequence or String typed value to retrieve the information about the title of the media.

    String METADATA_KEY_TRACK_NUMBER

    The metadata key for a Long typed value to retrieve the information about the track number for the media.

    String METADATA_KEY_USER_RATING

    The metadata key for a Rating typed value to retrieve the information about the user's rating for the media.

    String METADATA_KEY_WRITER

    The metadata key for a CharSequence or String typed value to retrieve the information about the writer of the media.

    String METADATA_KEY_YEAR

    The metadata key for a Long typed value to retrieve the information about the year the media was created or published.

    long STATUS_DOWNLOADED

    The status value to indicate the media item is downloaded for later offline playback.

    long STATUS_DOWNLOADING

    The status value to indicate the media item is being downloaded.

    long STATUS_NOT_DOWNLOADED

    The status value to indicate the media item is not downloaded.

    Public methods

    boolean containsKey(String key)

    Returns true if the given key is contained in the metadata

    Bitmap getBitmap(String key)

    Return a Bitmap for the given key or null if no bitmap exists for the given key.

    Bundle getExtras()

    Get the extra Bundle from the metadata object.

    float getFloat(String key)

    Return the value associated with the given key, or 0.0f if no long exists for the given key.

    long getLong(String key)

    Returns the value associated with the given key, or 0L if no long exists for the given key.

    String getMediaId()

    Returns the media id, or null if the id doesn't exist.

    Rating getRating(String key)

    Return a Rating for the given key or null if no rating exists for the given key.

    String getString(String key)

    Returns the value associated with the given key, or null if no mapping of the desired type exists for the given key or a null value is explicitly associated with the key.

    CharSequence getText(String key)

    Returns the value associated with the given key, or null if no mapping of the desired type exists for the given key or a null value is explicitly associated with the key.

    Set<String> keySet()

    Returns a Set containing the Strings used as keys in this metadata.

    int size()

    Get the number of fields in this metadata.

    String toString()

    Inherited methods

    Constants

    BROWSABLE_TYPE_ALBUMS

    public static final long BROWSABLE_TYPE_ALBUMS

    The type of browsable that contains browsable items categorized by album.

    This value matches with the folder type 'Albums' as specified in the section 6.10.2.2 of the Bluetooth AVRCP 1.5.

    Constant Value: 2 (0x0000000000000002)

    BROWSABLE_TYPE_ARTISTS

    public static final long BROWSABLE_TYPE_ARTISTS

    The type of browsable that contains browsable items categorized by artist.

    This value matches with the folder type 'Artists' as specified in the section 6.10.2.2 of the Bluetooth AVRCP 1.5.

    Constant Value: 3 (0x0000000000000003)

    BROWSABLE_TYPE_GENRES

    public static final long BROWSABLE_TYPE_GENRES

    The type of browsable that contains browsable items categorized by genre.

    This value matches with the folder type 'Genres' as specified in the section 6.10.2.2 of the Bluetooth AVRCP 1.5.

    Constant Value: 4 (0x0000000000000004)

    BROWSABLE_TYPE_MIXED

    public static final long BROWSABLE_TYPE_MIXED

    The type of browsable that is unknown or contains media items of mixed types.

    This value matches with the folder type 'Mixed' as specified in the section 6.10.2.2 of the Bluetooth AVRCP 1.5.

    Constant Value: 0 (0x0000000000000000)

    BROWSABLE_TYPE_NONE

    public static final long BROWSABLE_TYPE_NONE

    The type of browsable for non-browsable media item.

    Constant Value: -1 (0xffffffffffffffff)

    BROWSABLE_TYPE_PLAYLISTS

    public static final long BROWSABLE_TYPE_PLAYLISTS

    The type of browsable that contains browsable items categorized by playlist.

    This value matches with the folder type 'Playlists' as specified in the section 6.10.2.2 of the Bluetooth AVRCP 1.5.

    Constant Value: 5 (0x0000000000000005)

    BROWSABLE_TYPE_TITLES

    public static final long BROWSABLE_TYPE_TITLES

    The type of browsable that only contains playable media items.

    This value matches with the folder type 'Titles' as specified in the section 6.10.2.2 of the Bluetooth AVRCP 1.5.

    Constant Value: 1 (0x0000000000000001)

    BROWSABLE_TYPE_YEARS

    public static final long BROWSABLE_TYPE_YEARS

    The type of browsable that contains browsable items categorized by year.

    This value matches with the folder type 'Years' as specified in the section 6.10.2.2 of the Bluetooth AVRCP 1.5.

    Constant Value: 6 (0x0000000000000006)

    METADATA_KEY_ADVERTISEMENT

    public static final String METADATA_KEY_ADVERTISEMENT

    The metadata key for a Long typed value to retrieve the information about whether the media is an advertisement. A value of 0 indicates it is not an advertisement. A value of 1 or non-zero indicates it is an advertisement. If not specified, this value is set to 0 by default.

    Constant Value: "androidx.media2.metadata.ADVERTISEMENT"

    METADATA_KEY_ALBUM

    public static final String METADATA_KEY_ALBUM

    The metadata key for a CharSequence or String typed value to retrieve the information about the album title for the media.

    Constant Value: "android.media.metadata.ALBUM"

    METADATA_KEY_ALBUM_ART

    public static final String METADATA_KEY_ALBUM_ART

    The metadata key for a Bitmap typed value to retrieve the information about the artwork for the album of the media's original source. The artwork should be relatively small and may be scaled down if it is too large. For higher resolution artwork, METADATA_KEY_ALBUM_ART_URI should be used instead.

    Constant Value: "android.media.metadata.ALBUM_ART"

    METADATA_KEY_ALBUM_ARTIST

    public static final String METADATA_KEY_ALBUM_ARTIST

    The metadata key for a CharSequence or String typed value to retrieve the information about the artist for the album of the media's original source.

    Constant Value: "android.media.metadata.ALBUM_ARTIST"

    METADATA_KEY_ALBUM_ART_URI

    public static final String METADATA_KEY_ALBUM_ART_URI

    The metadata key for a CharSequence or String typed value to retrieve the information about the Uri of the artwork for the album of the media's original source.

    Constant Value: "android.media.metadata.ALBUM_ART_URI"

    METADATA_KEY_ART

    public static final String METADATA_KEY_ART

    The metadata key for a Bitmap typed value to retrieve the information about the artwork for the media. The artwork should be relatively small and may be scaled down if it is too large. For higher resolution artwork, METADATA_KEY_ART_URI should be used instead.

    Constant Value: "android.media.metadata.ART"

    METADATA_KEY_ARTIST

    public static final String METADATA_KEY_ARTIST

    The metadata key for a CharSequence or String typed value to retrieve the information about the artist of the media.

    Constant Value: "android.media.metadata.ARTIST"

    METADATA_KEY_ART_URI

    public static final String METADATA_KEY_ART_URI

    The metadata key for a CharSequence or String typed value to retrieve the information about Uri of the artwork for the media.

    Constant Value: "android.media.metadata.ART_URI"

    METADATA_KEY_AUTHOR

    public static final String METADATA_KEY_AUTHOR

    The metadata key for a CharSequence or String typed value to retrieve the information about the author of the media.

    Constant Value: "android.media.metadata.AUTHOR"

    METADATA_KEY_BROWSABLE

    public static final String METADATA_KEY_BROWSABLE

    The metadata key for a Long typed value to retrieve the information about the type of browsable. It should be one of the following:

    The values other than BROWSABLE_TYPE_NONE mean that the media item has children.[

    This matches with the bluetooth folder type of the media specified in the section 6.10.2.2 of the Bluetooth AVRCP 1.5.

    Constant Value: "androidx.media2.metadata.BROWSABLE"

    METADATA_KEY_COMPILATION

    public static final String METADATA_KEY_COMPILATION

    The metadata key for a CharSequence or String typed value to retrieve the information about the compilation status of the media.

    Constant Value: "android.media.metadata.COMPILATION"

    METADATA_KEY_COMPOSER

    public static final String METADATA_KEY_COMPOSER

    The metadata key for a CharSequence or String typed value to retrieve the information about the composer of the media.

    Constant Value: "android.media.metadata.COMPOSER"

    METADATA_KEY_DATE

    public static final String METADATA_KEY_DATE

    The metadata key for a CharSequence or String typed value to retrieve the information about the date the media was created or published. The format is unspecified but RFC 3339 is recommended.

    Constant Value: "android.media.metadata.DATE"

    METADATA_KEY_DISC_NUMBER

    public static final String METADATA_KEY_DISC_NUMBER

    The metadata key for a Long typed value to retrieve the information about the disc number for the media's original source.

    Constant Value: "android.media.metadata.DISC_NUMBER"

    METADATA_KEY_DISPLAY_DESCRIPTION

    public static final String METADATA_KEY_DISPLAY_DESCRIPTION

    The metadata key for a CharSequence or String typed value to retrieve the information about the description that is suitable for display to the user. When displaying more information for media described by this metadata, this should be preferred to other fields if present.

    Constant Value: "android.media.metadata.DISPLAY_DESCRIPTION"

    METADATA_KEY_DISPLAY_ICON

    public static final String METADATA_KEY_DISPLAY_ICON

    The metadata key for a Bitmap typed value to retrieve the information about the icon or thumbnail that is suitable for display to the user. When displaying an icon for media described by this metadata, this should be preferred to other fields if present.

    The icon should be relatively small and may be scaled down if it is too large. For higher resolution artwork, METADATA_KEY_DISPLAY_ICON_URI should be used instead.

    Constant Value: "android.media.metadata.DISPLAY_ICON"

    METADATA_KEY_DISPLAY_ICON_URI

    public static final String METADATA_KEY_DISPLAY_ICON_URI

    The metadata key for a CharSequence or String typed value to retrieve the information about the Uri of icon or thumbnail that is suitable for display to the user. When displaying more information for media described by this metadata, the display description should be preferred to other fields when present.

    Constant Value: "android.media.metadata.DISPLAY_ICON_URI"

    METADATA_KEY_DISPLAY_SUBTITLE

    public static final String METADATA_KEY_DISPLAY_SUBTITLE

    The metadata key for a CharSequence or String typed value to retrieve the information about the subtitle that is suitable for display to the user. When displaying a second line for media described by this metadata, this should be preferred to other fields if present.

    Constant Value: "android.media.metadata.DISPLAY_SUBTITLE"

    METADATA_KEY_DISPLAY_TITLE

    public static final String METADATA_KEY_DISPLAY_TITLE

    The metadata key for a CharSequence or String typed value to retrieve the information about the title that is suitable for display to the user. It will generally be the same as METADATA_KEY_TITLE but may differ for some formats. When displaying media described by this metadata, this should be preferred if present.

    Constant Value: "android.media.metadata.DISPLAY_TITLE"

    METADATA_KEY_DOWNLOAD_STATUS

    public static final String METADATA_KEY_DOWNLOAD_STATUS

    The metadata key for a Long typed value to retrieve the information about the download status of the media which will be used for later offline playback. It should be one of the following:

    Constant Value: "androidx.media2.metadata.DOWNLOAD_STATUS"

    METADATA_KEY_DURATION

    public static final String METADATA_KEY_DURATION

    The metadata key for a Long typed value to retrieve the information about the duration of the media in ms. A negative duration indicates that the duration is unknown (or infinite).

    Constant Value: "android.media.metadata.DURATION"

    METADATA_KEY_EXTRAS

    public static final String METADATA_KEY_EXTRAS

    A Bundle extra.

    Constant Value: "androidx.media2.metadata.EXTRAS"

    METADATA_KEY_GENRE

    public static final String METADATA_KEY_GENRE

    The metadata key for a CharSequence or String typed value to retrieve the information about the genre of the media.

    Constant Value: "android.media.metadata.GENRE"

    METADATA_KEY_MEDIA_ID

    public static final String METADATA_KEY_MEDIA_ID

    The metadata key for a CharSequence or String typed value to retrieve the information about the media ID of the content. This value is specific to the service providing the content. If used, this should be a persistent key for the underlying content. This ID is used by MediaController and MediaBrowser.

    Constant Value: "android.media.metadata.MEDIA_ID"

    METADATA_KEY_MEDIA_URI

    public static final String METADATA_KEY_MEDIA_URI

    The metadata key for a CharSequence or String typed value to retrieve the information about the Uri of the content. This value is specific to the service providing the content.

    Constant Value: "android.media.metadata.MEDIA_URI"

    METADATA_KEY_NUM_TRACKS

    public static final String METADATA_KEY_NUM_TRACKS

    The metadata key for a Long typed value to retrieve the information about the number of tracks in the media's original source.

    Constant Value: "android.media.metadata.NUM_TRACKS"

    METADATA_KEY_PLAYABLE

    public static final String METADATA_KEY_PLAYABLE

    The metadata key for a Long typed value to retrieve the information about whether the media is playable. A value of 0 indicates it is not a playable item. A value of 1 or non-zero indicates it is playable.

    Constant Value: "androidx.media2.metadata.PLAYABLE"

    METADATA_KEY_RATING

    public static final String METADATA_KEY_RATING

    The metadata key for a Rating typed value to retrieve the information about the overall rating for the media.

    Constant Value: "android.media.metadata.RATING"

    METADATA_KEY_TITLE

    public static final String METADATA_KEY_TITLE

    The metadata key for a CharSequence or String typed value to retrieve the information about the title of the media.

    Constant Value: "android.media.metadata.TITLE"

    METADATA_KEY_TRACK_NUMBER

    public static final String METADATA_KEY_TRACK_NUMBER

    The metadata key for a Long typed value to retrieve the information about the track number for the media.

    Constant Value: "android.media.metadata.TRACK_NUMBER"

    METADATA_KEY_USER_RATING

    public static final String METADATA_KEY_USER_RATING

    The metadata key for a Rating typed value to retrieve the information about the user's rating for the media. Prefer to have unrated user rating instead of null, so MediaController can know the possible user rating type.

    Constant Value: "android.media.metadata.USER_RATING"

    METADATA_KEY_WRITER

    public static final String METADATA_KEY_WRITER

    The metadata key for a CharSequence or String typed value to retrieve the information about the writer of the media.

    Constant Value: "android.media.metadata.WRITER"

    METADATA_KEY_YEAR

    public static final String METADATA_KEY_YEAR

    The metadata key for a Long typed value to retrieve the information about the year the media was created or published.

    Constant Value: "android.media.metadata.YEAR"

    STATUS_DOWNLOADED

    public static final long STATUS_DOWNLOADED

    The status value to indicate the media item is downloaded for later offline playback.

    Constant Value: 2 (0x0000000000000002)

    STATUS_DOWNLOADING

    public static final long STATUS_DOWNLOADING

    The status value to indicate the media item is being downloaded.

    Constant Value: 1 (0x0000000000000001)

    STATUS_NOT_DOWNLOADED

    public static final long STATUS_NOT_DOWNLOADED

    The status value to indicate the media item is not downloaded.

    Constant Value: 0 (0x0000000000000000)

    Public methods

    containsKey

    public boolean containsKey (String key)

    Returns true if the given key is contained in the metadata

    Parameters
    key String: a String key
    Returns
    boolean true if the key exists in this metadata, false otherwise

    getBitmap

    public Bitmap getBitmap (String key)

    Return a Bitmap for the given key or null if no bitmap exists for the given key.

    Parameters
    key String: The key the value is stored under
    Returns
    Bitmap A Bitmap or null

    getExtras

    public Bundle getExtras ()

    Get the extra Bundle from the metadata object.

    Returns
    Bundle A Bundle or null

    getFloat

    public float getFloat (String key)

    Return the value associated with the given key, or 0.0f if no long exists for the given key.

    Parameters
    key String: The key the value is stored under
    Returns
    float a float value

    getLong

    public long getLong (String key)

    Returns the value associated with the given key, or 0L if no long exists for the given key.

    Parameters
    key String: The key the value is stored under
    Returns
    long a long value

    getMediaId

    public String getMediaId ()

    Returns the media id, or null if the id doesn't exist.

    This is equivalent to the getString(String) with the METADATA_KEY_MEDIA_ID.

    Returns
    String media id. Can be null

    getRating

    public Rating getRating (String key)

    Return a Rating for the given key or null if no rating exists for the given key.

    For the METADATA_KEY_USER_RATING, A null return value means that user rating cannot be set by MediaController.

    Parameters
    key String: The key the value is stored under
    Returns
    Rating A Rating or null

    getString

    public String getString (String key)

    Returns the value associated with the given key, or null if no mapping of the desired type exists for the given key or a null value is explicitly associated with the key.

    Parameters
    key String: The key the value is stored under
    Returns
    String a String value, or null

    getText

    public CharSequence getText (String key)

    Returns the value associated with the given key, or null if no mapping of the desired type exists for the given key or a null value is explicitly associated with the key.

    Parameters
    key String: The key the value is stored under
    Returns
    CharSequence a CharSequence value, or null

    keySet

    public Set<String> keySet ()

    Returns a Set containing the Strings used as keys in this metadata.

    Returns
    Set<String> a Set of String keys

    size

    public int size ()

    Get the number of fields in this metadata.

    Returns
    int The number of fields in the metadata.

    toString

    public String toString ()

    Returns
    String