MediaMetadataRetriever
open class MediaMetadataRetriever : AutoCloseable
kotlin.Any | |
↳ | android.media.MediaMetadataRetriever |
MediaMetadataRetriever class provides a unified interface for retrieving frame and meta data from an input media file.
Summary
Nested classes | |
---|---|
Constants | |
---|---|
static Int |
The metadata key to retrieve the information about the album title of the data source. |
static Int |
The metadata key to retrieve the information about the performers or artist associated with the data source. |
static Int |
The metadata key to retrieve the information about the artist of the data source. |
static Int |
The metadata key to retrieve the information about the author of the data source. |
static Int |
This key retrieves the average bitrate (in bits/sec), if available. |
static Int |
This key retrieves the bits per sample in numbers of bits, if available. |
static Int |
This key retrieves the original capture framerate, if it's available. |
static Int |
The metadata key to retrieve the numeric string describing the order of the audio data source on its original recording. |
static Int |
This key retrieves the color range, if available. |
static Int |
This key retrieves the color standard, if available. |
static Int |
This key retrieves the color transfer, if available. |
static Int |
The metadata key to retrieve the music album compilation status. |
static Int |
The metadata key to retrieve the information about the composer of the data source. |
static Int |
The metadata key to retrieve the date when the data source was created or modified. |
static Int |
The metadata key to retrieve the numberic string that describes which part of a set the audio data source comes from. |
static Int |
The metadata key to retrieve the playback duration (in ms) of the data source. |
static Int |
If the media contains EXIF data, this key retrieves the length (in bytes) of the data. |
static Int |
If the media contains EXIF data, this key retrieves the offset (in bytes) of the data. |
static Int |
The metadata key to retrieve the content type or genre of the data source. |
static Int |
If this key exists the media contains audio content. |
static Int |
If this key exists the media contains still image content. |
static Int |
If this key exists the media contains video content. |
static Int |
If the media contains still images, this key retrieves the number of still images. |
static Int |
If the media contains still images, this key retrieves the height of the primary image. |
static Int |
If the media contains still images, this key retrieves the image index of the primary image. |
static Int |
If the media contains still images, this key retrieves the rotation angle (in degrees clockwise) of the primary image. |
static Int |
If the media contains still images, this key retrieves the width of the primary image. |
static Int |
This key retrieves the location information, if available. |
static Int |
The metadata key to retrieve the mime type of the data source. |
static Int |
The metadata key to retrieve the number of tracks, such as audio, video, text, in the data source, such as a mp4 or 3gpp file. |
static Int |
This key retrieves the sample rate in Hz, if available. |
static Int |
The metadata key to retrieve the data source title. |
static Int |
If the media contains video and this key exists, it retrieves the total number of frames in the video sequence. |
static Int |
If the media contains video, this key retrieves its height. |
static Int |
This key retrieves the video rotation angle in degrees, if available. |
static Int |
If the media contains video, this key retrieves its width. |
static Int |
The metadata key to retrieve the information of the writer (such as lyricist) of the data source. |
static Int |
If the media contains XMP data, this key retrieves the length (in bytes) of the data. |
static Int |
If the media contains XMP data, this key retrieves the offset (in bytes) of the data. |
static Int |
The metadata key to retrieve the year when the data source was created or modified. |
static Int |
This option is used with |
static Int |
This option is used with |
static Int |
This option is used with |
static Int |
This option is used with |
Public constructors | |
---|---|
Public methods | |
---|---|
open Unit |
close() Releases any acquired resources. |
open String? |
extractMetadata(keyCode: Int) Call this method after setDataSource(). |
open ByteArray? |
Call this method after setDataSource(). |
open Bitmap? |
getFrameAtIndex(frameIndex: Int, params: MediaMetadataRetriever.BitmapParams) This method retrieves a video frame by its index. |
open Bitmap? |
getFrameAtIndex(frameIndex: Int) This method is similar to |
open Bitmap? |
getFrameAtTime(timeUs: Long, option: Int) This method is similar to |
open Bitmap? |
getFrameAtTime(timeUs: Long, option: Int, params: MediaMetadataRetriever.BitmapParams) Call this method after setDataSource(). |
open Bitmap? |
getFrameAtTime(timeUs: Long) Call this method after setDataSource(). |
open Bitmap? |
Call this method after setDataSource(). |
open MutableList<Bitmap!> |
getFramesAtIndex(frameIndex: Int, numFrames: Int, params: MediaMetadataRetriever.BitmapParams) This method retrieves a consecutive set of video frames starting at the specified index. |
open MutableList<Bitmap!> |
getFramesAtIndex(frameIndex: Int, numFrames: Int) This method is similar to |
open Bitmap? |
getImageAtIndex(imageIndex: Int, params: MediaMetadataRetriever.BitmapParams) This method retrieves a still image by its index. |
open Bitmap? |
getImageAtIndex(imageIndex: Int) This method is similar to |
open Bitmap? |
This method retrieves the primary image of the media content. |
open Bitmap? |
This method is similar to |
open Bitmap? |
getScaledFrameAtTime(timeUs: Long, option: Int, dstWidth: Int, dstHeight: Int) This method is similar to |
open Bitmap? |
getScaledFrameAtTime(timeUs: Long, option: Int, dstWidth: Int, dstHeight: Int, params: MediaMetadataRetriever.BitmapParams) Retrieve a video frame near a given timestamp scaled to a desired size. |
open Unit |
release() Releases any acquired resources. |
open Unit |
setDataSource(path: String!) Sets the data source (file pathname) to use. |
open Unit |
setDataSource(uri: String!, headers: MutableMap<String!, String!>!) Sets the data source (URI) to use. |
open Unit |
setDataSource(fd: FileDescriptor!, offset: Long, length: Long) Sets the data source (FileDescriptor) to use. |
open Unit |
setDataSource(fd: FileDescriptor!) Sets the data source (FileDescriptor) to use. |
open Unit |
setDataSource(context: Context!, uri: Uri!) Sets the data source as a content Uri. |
open Unit |
setDataSource(dataSource: MediaDataSource!) Sets the data source (MediaDataSource) to use. |
Protected methods | |
---|---|
open Unit |
finalize() |
Constants
METADATA_KEY_ALBUM
static val METADATA_KEY_ALBUM: Int
The metadata key to retrieve the information about the album title of the data source.
Value: 1
METADATA_KEY_ALBUMARTIST
static val METADATA_KEY_ALBUMARTIST: Int
The metadata key to retrieve the information about the performers or artist associated with the data source.
Value: 13
METADATA_KEY_ARTIST
static val METADATA_KEY_ARTIST: Int
The metadata key to retrieve the information about the artist of the data source.
Value: 2
METADATA_KEY_AUTHOR
static val METADATA_KEY_AUTHOR: Int
The metadata key to retrieve the information about the author of the data source.
Value: 3
METADATA_KEY_BITRATE
static val METADATA_KEY_BITRATE: Int
This key retrieves the average bitrate (in bits/sec), if available.
Value: 20
METADATA_KEY_BITS_PER_SAMPLE
static val METADATA_KEY_BITS_PER_SAMPLE: Int
This key retrieves the bits per sample in numbers of bits, if available. This is a signed 32-bit integer formatted as a string in base 10.
Value: 39
METADATA_KEY_CAPTURE_FRAMERATE
static val METADATA_KEY_CAPTURE_FRAMERATE: Int
This key retrieves the original capture framerate, if it's available. The capture framerate will be a floating point number.
Value: 25
METADATA_KEY_CD_TRACK_NUMBER
static val METADATA_KEY_CD_TRACK_NUMBER: Int
The metadata key to retrieve the numeric string describing the order of the audio data source on its original recording.
Value: 0
METADATA_KEY_COLOR_RANGE
static val METADATA_KEY_COLOR_RANGE: Int
This key retrieves the color range, if available.
Value: 37
METADATA_KEY_COLOR_STANDARD
static val METADATA_KEY_COLOR_STANDARD: Int
This key retrieves the color standard, if available.
Value: 35
METADATA_KEY_COLOR_TRANSFER
static val METADATA_KEY_COLOR_TRANSFER: Int
This key retrieves the color transfer, if available.
Value: 36
METADATA_KEY_COMPILATION
static val METADATA_KEY_COMPILATION: Int
The metadata key to retrieve the music album compilation status.
Value: 15
METADATA_KEY_COMPOSER
static val METADATA_KEY_COMPOSER: Int
The metadata key to retrieve the information about the composer of the data source.
Value: 4
METADATA_KEY_DATE
static val METADATA_KEY_DATE: Int
The metadata key to retrieve the date when the data source was created or modified.
Value: 5
METADATA_KEY_DISC_NUMBER
static val METADATA_KEY_DISC_NUMBER: Int
The metadata key to retrieve the numberic string that describes which part of a set the audio data source comes from.
Value: 14
METADATA_KEY_DURATION
static val METADATA_KEY_DURATION: Int
The metadata key to retrieve the playback duration (in ms) of the data source.
Value: 9
METADATA_KEY_EXIF_LENGTH
static val METADATA_KEY_EXIF_LENGTH: Int
If the media contains EXIF data, this key retrieves the length (in bytes) of the data.
Value: 34
METADATA_KEY_EXIF_OFFSET
static val METADATA_KEY_EXIF_OFFSET: Int
If the media contains EXIF data, this key retrieves the offset (in bytes) of the data.
Value: 33
METADATA_KEY_GENRE
static val METADATA_KEY_GENRE: Int
The metadata key to retrieve the content type or genre of the data source.
Value: 6
METADATA_KEY_HAS_AUDIO
static val METADATA_KEY_HAS_AUDIO: Int
If this key exists the media contains audio content.
Value: 16
METADATA_KEY_HAS_IMAGE
static val METADATA_KEY_HAS_IMAGE: Int
If this key exists the media contains still image content.
Value: 26
METADATA_KEY_HAS_VIDEO
static val METADATA_KEY_HAS_VIDEO: Int
If this key exists the media contains video content.
Value: 17
METADATA_KEY_IMAGE_COUNT
static val METADATA_KEY_IMAGE_COUNT: Int
If the media contains still images, this key retrieves the number of still images.
Value: 27
METADATA_KEY_IMAGE_HEIGHT
static val METADATA_KEY_IMAGE_HEIGHT: Int
If the media contains still images, this key retrieves the height of the primary image.
Value: 30
METADATA_KEY_IMAGE_PRIMARY
static val METADATA_KEY_IMAGE_PRIMARY: Int
If the media contains still images, this key retrieves the image index of the primary image.
Value: 28
METADATA_KEY_IMAGE_ROTATION
static val METADATA_KEY_IMAGE_ROTATION: Int
If the media contains still images, this key retrieves the rotation angle (in degrees clockwise) of the primary image. The image rotation angle must be one of 0, 90, 180, or 270 degrees.
Value: 31
METADATA_KEY_IMAGE_WIDTH
static val METADATA_KEY_IMAGE_WIDTH: Int
If the media contains still images, this key retrieves the width of the primary image.
Value: 29
METADATA_KEY_LOCATION
static val METADATA_KEY_LOCATION: Int
This key retrieves the location information, if available. The location should be specified according to ISO-6709 standard, under a mp4/3gp box "@xyz". Location with longitude of -90 degrees and latitude of 180 degrees will be retrieved as "+180.0000-90.0000/", for instance.
Value: 23
METADATA_KEY_MIMETYPE
static val METADATA_KEY_MIMETYPE: Int
The metadata key to retrieve the mime type of the data source. Some example mime types include: "video/mp4", "audio/mp4", "audio/amr-wb", etc.
Value: 12
METADATA_KEY_NUM_TRACKS
static val METADATA_KEY_NUM_TRACKS: Int
The metadata key to retrieve the number of tracks, such as audio, video, text, in the data source, such as a mp4 or 3gpp file.
Value: 10
METADATA_KEY_SAMPLERATE
static val METADATA_KEY_SAMPLERATE: Int
This key retrieves the sample rate in Hz, if available. This is a signed 32-bit integer formatted as a string in base 10.
Value: 38
METADATA_KEY_TITLE
static val METADATA_KEY_TITLE: Int
The metadata key to retrieve the data source title.
Value: 7
METADATA_KEY_VIDEO_FRAME_COUNT
static val METADATA_KEY_VIDEO_FRAME_COUNT: Int
If the media contains video and this key exists, it retrieves the total number of frames in the video sequence.
Value: 32
METADATA_KEY_VIDEO_HEIGHT
static val METADATA_KEY_VIDEO_HEIGHT: Int
If the media contains video, this key retrieves its height.
Value: 19
METADATA_KEY_VIDEO_ROTATION
static val METADATA_KEY_VIDEO_ROTATION: Int
This key retrieves the video rotation angle in degrees, if available. The video rotation angle may be 0, 90, 180, or 270 degrees.
Value: 24
METADATA_KEY_VIDEO_WIDTH
static val METADATA_KEY_VIDEO_WIDTH: Int
If the media contains video, this key retrieves its width.
Value: 18
METADATA_KEY_WRITER
static val METADATA_KEY_WRITER: Int
The metadata key to retrieve the information of the writer (such as lyricist) of the data source.
Value: 11
METADATA_KEY_XMP_LENGTH
static val METADATA_KEY_XMP_LENGTH: Int
If the media contains XMP data, this key retrieves the length (in bytes) of the data.
Value: 42
METADATA_KEY_XMP_OFFSET
static val METADATA_KEY_XMP_OFFSET: Int
If the media contains XMP data, this key retrieves the offset (in bytes) of the data.
Value: 41
METADATA_KEY_YEAR
static val METADATA_KEY_YEAR: Int
The metadata key to retrieve the year when the data source was created or modified.
Value: 8
OPTION_CLOSEST
static val OPTION_CLOSEST: Int
This option is used with getFrameAtTime(long,int)
to retrieve a frame (not necessarily a key frame) associated with a data source that is located closest to or at the given time.
Value: 3
See Also
OPTION_CLOSEST_SYNC
static val OPTION_CLOSEST_SYNC: Int
This option is used with getFrameAtTime(long,int)
to retrieve a sync (or key) frame associated with a data source that is located closest to (in time) or at the given time.
Value: 2
See Also
OPTION_NEXT_SYNC
static val OPTION_NEXT_SYNC: Int
This option is used with getFrameAtTime(long,int)
to retrieve a sync (or key) frame associated with a data source that is located right after or at the given time.
Value: 1
See Also
OPTION_PREVIOUS_SYNC
static val OPTION_PREVIOUS_SYNC: Int
This option is used with getFrameAtTime(long,int)
to retrieve a sync (or key) frame associated with a data source that is located right before or at the given time.
Value: 0
See Also
Public constructors
Public methods
close
open fun close(): Unit
Releases any acquired resources. Call it when done with the object.
Exceptions | |
---|---|
java.lang.Exception |
if this resource cannot be closed |
java.io.IOException |
When an IOException is thrown while closing a MediaDataSource passed to setDataSource(android.media.MediaDataSource) . This throws clause exists since API android.os.Build.VERSION_CODES#TIRAMISU , but this method can throw in earlier API versions where the exception is not declared. |
extractMetadata
open fun extractMetadata(keyCode: Int): String?
Call this method after setDataSource(). This method retrieves the meta data value associated with the keyCode. The keyCode currently supported is listed below as METADATA_XXX constants. With any other value, it returns a null pointer.
Parameters | |
---|---|
keyCode |
Int: One of the constants listed below at the end of the class. |
Return | |
---|---|
String? |
The meta data value associate with the given keyCode on success; null on failure. |
getEmbeddedPicture
open fun getEmbeddedPicture(): ByteArray?
Call this method after setDataSource(). This method finds the optional graphic or album/cover art associated associated with the data source. If there are more than one pictures, (any) one of them is returned.
Return | |
---|---|
ByteArray? |
null if no such graphic is found. |
getFrameAtIndex
open fun getFrameAtIndex(
frameIndex: Int,
params: MediaMetadataRetriever.BitmapParams
): Bitmap?
This method retrieves a video frame by its index. It should only be called after #setDataSource. After the bitmap is returned, you can query the actual parameters that were used to create the bitmap from the BitmapParams
argument, for instance to query the bitmap config used for the bitmap with BitmapParams#getActualConfig
.
Parameters | |
---|---|
frameIndex |
Int: 0-based index of the video frame. The frame index must be that of a valid frame. The total number of frames available for retrieval can be queried via the METADATA_KEY_VIDEO_FRAME_COUNT key. |
params |
MediaMetadataRetriever.BitmapParams: BitmapParams that controls the returned bitmap config (such as pixel formats). This value cannot be null . |
Return | |
---|---|
Bitmap? |
A Bitmap containing the requested video frame, or null if the retrieval fails. |
Exceptions | |
---|---|
java.lang.IllegalStateException |
if the container doesn't contain video or image sequences. |
java.lang.IllegalArgumentException |
if the requested frame index does not exist. |
getFrameAtIndex
open fun getFrameAtIndex(frameIndex: Int): Bitmap?
This method is similar to getFrameAtIndex(int,android.media.MediaMetadataRetriever.BitmapParams)
except that the default for BitmapParams
will be used.
Parameters | |
---|---|
frameIndex |
Int: 0-based index of the video frame. The frame index must be that of a valid frame. The total number of frames available for retrieval can be queried via the METADATA_KEY_VIDEO_FRAME_COUNT key. |
Return | |
---|---|
Bitmap? |
A Bitmap containing the requested video frame, or null if the retrieval fails. |
Exceptions | |
---|---|
java.lang.IllegalStateException |
if the container doesn't contain video or image sequences. |
java.lang.IllegalArgumentException |
if the requested frame index does not exist. |
getFrameAtTime
open fun getFrameAtTime(
timeUs: Long,
option: Int
): Bitmap?
This method is similar to getFrameAtTime(long,int,android.media.MediaMetadataRetriever.BitmapParams)
except that the device will choose the actual Bitmap.Config
to use.
Parameters | |
---|---|
timeUs |
Long: The time position where the frame will be retrieved. When retrieving the frame at the given time position, there is no guarantee that the data source has a frame located at the position. When this happens, a frame nearby will be returned. If timeUs is negative, time position and option will ignored, and any frame that the implementation considers as representative may be returned. |
option |
Int: a hint on how the frame is found. Use OPTION_PREVIOUS_SYNC if one wants to retrieve a sync frame that has a timestamp earlier than or the same as timeUs. Use OPTION_NEXT_SYNC if one wants to retrieve a sync frame that has a timestamp later than or the same as timeUs. Use OPTION_CLOSEST_SYNC if one wants to retrieve a sync frame that has a timestamp closest to or the same as timeUs. Use OPTION_CLOSEST if one wants to retrieve a frame that may or may not be a sync frame but is closest to or the same as timeUs. OPTION_CLOSEST often has larger performance overhead compared to the other options if there is no sync frame located at timeUs. Value is android.media.MediaMetadataRetriever#OPTION_PREVIOUS_SYNC , android.media.MediaMetadataRetriever#OPTION_NEXT_SYNC , android.media.MediaMetadataRetriever#OPTION_CLOSEST_SYNC , or android.media.MediaMetadataRetriever#OPTION_CLOSEST |
Return | |
---|---|
Bitmap? |
A Bitmap containing a representative video frame, which can be null, if such a frame cannot be retrieved. Bitmap#getConfig() can be used to query the actual Bitmap.Config . |
getFrameAtTime
open fun getFrameAtTime(
timeUs: Long,
option: Int,
params: MediaMetadataRetriever.BitmapParams
): Bitmap?
Call this method after setDataSource(). This method finds a representative frame close to the given time position by considering the given option if possible, and returns it as a bitmap.
If you don't need a full-resolution frame (for example, because you need a thumbnail image), use #getScaledFrameAtTime instead of this method.
Parameters | |
---|---|
timeUs |
Long: The time position where the frame will be retrieved. When retrieving the frame at the given time position, there is no guarantee that the data source has a frame located at the position. When this happens, a frame nearby will be returned. If timeUs is negative, time position and option will ignored, and any frame that the implementation considers as representative may be returned. |
option |
Int: a hint on how the frame is found. Use OPTION_PREVIOUS_SYNC if one wants to retrieve a sync frame that has a timestamp earlier than or the same as timeUs. Use OPTION_NEXT_SYNC if one wants to retrieve a sync frame that has a timestamp later than or the same as timeUs. Use OPTION_CLOSEST_SYNC if one wants to retrieve a sync frame that has a timestamp closest to or the same as timeUs. Use OPTION_CLOSEST if one wants to retrieve a frame that may or may not be a sync frame but is closest to or the same as timeUs. OPTION_CLOSEST often has larger performance overhead compared to the other options if there is no sync frame located at timeUs. Value is android.media.MediaMetadataRetriever#OPTION_PREVIOUS_SYNC , android.media.MediaMetadataRetriever#OPTION_NEXT_SYNC , android.media.MediaMetadataRetriever#OPTION_CLOSEST_SYNC , or android.media.MediaMetadataRetriever#OPTION_CLOSEST |
params |
MediaMetadataRetriever.BitmapParams: BitmapParams that controls the returned bitmap config (such as pixel formats). This value cannot be null . |
Return | |
---|---|
Bitmap? |
A Bitmap containing a representative video frame, which can be null, if such a frame cannot be retrieved. |
See Also
getFrameAtTime
open fun getFrameAtTime(timeUs: Long): Bitmap?
Call this method after setDataSource(). This method finds a representative frame close to the given time position if possible, and returns it as a bitmap. Call this method if one does not care how the frame is found as long as it is close to the given time; otherwise, please call getFrameAtTime(long,int)
.
If you don't need a full-resolution frame (for example, because you need a thumbnail image), use #getScaledFrameAtTime instead of this method.
Parameters | |
---|---|
timeUs |
Long: The time position where the frame will be retrieved. When retrieving the frame at the given time position, there is no guarentee that the data source has a frame located at the position. When this happens, a frame nearby will be returned. If timeUs is negative, time position and option will ignored, and any frame that the implementation considers as representative may be returned. |
Return | |
---|---|
Bitmap? |
A Bitmap of size dst_widthxdst_height containing a representative video frame, which can be null, if such a frame cannot be retrieved. |
See Also
getFrameAtTime
open fun getFrameAtTime(): Bitmap?
Call this method after setDataSource(). This method finds a representative frame at any time position if possible, and returns it as a bitmap. Call this method if one does not care about where the frame is located; otherwise, please call getFrameAtTime(long)
or getFrameAtTime(long,int)
If you don't need a full-resolution frame (for example, because you need a thumbnail image), use #getScaledFrameAtTime instead of this method.
Return | |
---|---|
Bitmap? |
A Bitmap containing a representative video frame, which can be null, if such a frame cannot be retrieved. |
getFramesAtIndex
open fun getFramesAtIndex(
frameIndex: Int,
numFrames: Int,
params: MediaMetadataRetriever.BitmapParams
): MutableList<Bitmap!>
This method retrieves a consecutive set of video frames starting at the specified index. It should only be called after #setDataSource. If the caller intends to retrieve more than one consecutive video frames, this method is preferred over getFrameAtIndex(int,android.media.MediaMetadataRetriever.BitmapParams)
for efficiency. After the bitmaps are returned, you can query the actual parameters that were used to create the bitmaps from the BitmapParams
argument, for instance to query the bitmap config used for the bitmaps with BitmapParams#getActualConfig
.
Parameters | |
---|---|
frameIndex |
Int: 0-based index of the first video frame to retrieve. The frame index must be that of a valid frame. The total number of frames available for retrieval can be queried via the METADATA_KEY_VIDEO_FRAME_COUNT key. |
numFrames |
Int: number of consecutive video frames to retrieve. Must be a positive value. The stream must contain at least numFrames frames starting at frameIndex. |
params |
MediaMetadataRetriever.BitmapParams: BitmapParams that controls the returned bitmap config (such as pixel formats). This value cannot be null . |
Return | |
---|---|
MutableList<Bitmap!> |
An list of Bitmaps containing the requested video frames. The returned array could contain less frames than requested if the retrieval fails. This value cannot be null . |
Exceptions | |
---|---|
java.lang.IllegalStateException |
if the container doesn't contain video or image sequences. |
java.lang.IllegalArgumentException |
if the frameIndex or numFrames is invalid, or the stream doesn't contain at least numFrames starting at frameIndex. |
getFramesAtIndex
open fun getFramesAtIndex(
frameIndex: Int,
numFrames: Int
): MutableList<Bitmap!>
This method is similar to getFramesAtIndex(int,int,android.media.MediaMetadataRetriever.BitmapParams)
except that the default for BitmapParams
will be used.
Parameters | |
---|---|
frameIndex |
Int: 0-based index of the first video frame to retrieve. The frame index must be that of a valid frame. The total number of frames available for retrieval can be queried via the METADATA_KEY_VIDEO_FRAME_COUNT key. |
numFrames |
Int: number of consecutive video frames to retrieve. Must be a positive value. The stream must contain at least numFrames frames starting at frameIndex. |
Return | |
---|---|
MutableList<Bitmap!> |
An list of Bitmaps containing the requested video frames. The returned array could contain less frames than requested if the retrieval fails. This value cannot be null . |
Exceptions | |
---|---|
java.lang.IllegalStateException |
if the container doesn't contain video or image sequences. |
java.lang.IllegalArgumentException |
if the frameIndex or numFrames is invalid, or the stream doesn't contain at least numFrames starting at frameIndex. |
getImageAtIndex
open fun getImageAtIndex(
imageIndex: Int,
params: MediaMetadataRetriever.BitmapParams
): Bitmap?
This method retrieves a still image by its index. It should only be called after #setDataSource. After the bitmap is returned, you can query the actual parameters that were used to create the bitmap from the BitmapParams
argument, for instance to query the bitmap config used for the bitmap with BitmapParams#getActualConfig
.
Parameters | |
---|---|
imageIndex |
Int: 0-based index of the image. |
params |
MediaMetadataRetriever.BitmapParams: BitmapParams that controls the returned bitmap config (such as pixel formats). This value cannot be null . |
Return | |
---|---|
Bitmap? |
the requested still image, or null if the image cannot be retrieved. |
Exceptions | |
---|---|
java.lang.IllegalStateException |
if the container doesn't contain still images. |
java.lang.IllegalArgumentException |
if the requested image does not exist. |
getImageAtIndex
open fun getImageAtIndex(imageIndex: Int): Bitmap?
This method is similar to getImageAtIndex(int,android.media.MediaMetadataRetriever.BitmapParams)
except that the default for BitmapParams
will be used.
Parameters | |
---|---|
imageIndex |
Int: 0-based index of the image. |
Return | |
---|---|
Bitmap? |
the requested still image, or null if the image cannot be retrieved. |
Exceptions | |
---|---|
java.lang.IllegalStateException |
if the container doesn't contain still images. |
java.lang.IllegalArgumentException |
if the requested image does not exist. |
getPrimaryImage
open fun getPrimaryImage(params: MediaMetadataRetriever.BitmapParams): Bitmap?
This method retrieves the primary image of the media content. It should only be called after #setDataSource. After the bitmap is returned, you can query the actual parameters that were used to create the bitmap from the BitmapParams
argument, for instance to query the bitmap config used for the bitmap with BitmapParams#getActualConfig
.
Parameters | |
---|---|
params |
MediaMetadataRetriever.BitmapParams: BitmapParams that controls the returned bitmap config (such as pixel formats). This value cannot be null . |
Return | |
---|---|
Bitmap? |
the primary image, or null if it cannot be retrieved. |
Exceptions | |
---|---|
java.lang.IllegalStateException |
if the container doesn't contain still images. |
getPrimaryImage
open fun getPrimaryImage(): Bitmap?
This method is similar to getPrimaryImage(android.media.MediaMetadataRetriever.BitmapParams)
except that the default for BitmapParams
will be used.
Return | |
---|---|
Bitmap? |
the primary image, or null if it cannot be retrieved. |
Exceptions | |
---|---|
java.lang.IllegalStateException |
if the container doesn't contain still images. |
getScaledFrameAtTime
open fun getScaledFrameAtTime(
timeUs: Long,
option: Int,
dstWidth: Int,
dstHeight: Int
): Bitmap?
This method is similar to getScaledFrameAtTime(long,int,int,int,android.media.MediaMetadataRetriever.BitmapParams)
except that the device will choose the actual Bitmap.Config
to use.
Parameters | |
---|---|
timeUs |
Long: The time position in microseconds where the frame will be retrieved. When retrieving the frame at the given time position, there is no guarantee that the data source has a frame located at the position. When this happens, a frame nearby will be returned. If timeUs is negative, time position and option will ignored, and any frame that the implementation considers as representative may be returned. |
option |
Int: a hint on how the frame is found. Use OPTION_PREVIOUS_SYNC if one wants to retrieve a sync frame that has a timestamp earlier than or the same as timeUs. Use OPTION_NEXT_SYNC if one wants to retrieve a sync frame that has a timestamp later than or the same as timeUs. Use OPTION_CLOSEST_SYNC if one wants to retrieve a sync frame that has a timestamp closest to or the same as timeUs. Use OPTION_CLOSEST if one wants to retrieve a frame that may or may not be a sync frame but is closest to or the same as timeUs. OPTION_CLOSEST often has larger performance overhead compared to the other options if there is no sync frame located at timeUs. Value is android.media.MediaMetadataRetriever#OPTION_PREVIOUS_SYNC , android.media.MediaMetadataRetriever#OPTION_NEXT_SYNC , android.media.MediaMetadataRetriever#OPTION_CLOSEST_SYNC , or android.media.MediaMetadataRetriever#OPTION_CLOSEST |
dstWidth |
Int: expected output bitmap width Value is 1 or greater |
dstHeight |
Int: expected output bitmap height Value is 1 or greater |
Return | |
---|---|
Bitmap? |
A Bitmap containing a representative video frame, which can be null, if such a frame cannot be retrieved. Bitmap#getConfig() can be used to query the actual Bitmap.Config . |
Exceptions | |
---|---|
java.lang.IllegalArgumentException |
if passed in invalid option or width by height is less than or equal to 0. |
getScaledFrameAtTime
open fun getScaledFrameAtTime(
timeUs: Long,
option: Int,
dstWidth: Int,
dstHeight: Int,
params: MediaMetadataRetriever.BitmapParams
): Bitmap?
Retrieve a video frame near a given timestamp scaled to a desired size. Call this method after setDataSource(). This method finds a representative frame close to the given time position by considering the given option if possible, and returns it as a bitmap with same aspect ratio as the source while scaling it so that it fits into the desired size of dst_width by dst_height. This is useful for generating a thumbnail for an input data source or just to obtain a scaled frame at the given time position.
Parameters | |
---|---|
timeUs |
Long: The time position in microseconds where the frame will be retrieved. When retrieving the frame at the given time position, there is no guarantee that the data source has a frame located at the position. When this happens, a frame nearby will be returned. If timeUs is negative, time position and option will ignored, and any frame that the implementation considers as representative may be returned. |
option |
Int: a hint on how the frame is found. Use OPTION_PREVIOUS_SYNC if one wants to retrieve a sync frame that has a timestamp earlier than or the same as timeUs. Use OPTION_NEXT_SYNC if one wants to retrieve a sync frame that has a timestamp later than or the same as timeUs. Use OPTION_CLOSEST_SYNC if one wants to retrieve a sync frame that has a timestamp closest to or the same as timeUs. Use OPTION_CLOSEST if one wants to retrieve a frame that may or may not be a sync frame but is closest to or the same as timeUs. OPTION_CLOSEST often has larger performance overhead compared to the other options if there is no sync frame located at timeUs. Value is android.media.MediaMetadataRetriever#OPTION_PREVIOUS_SYNC , android.media.MediaMetadataRetriever#OPTION_NEXT_SYNC , android.media.MediaMetadataRetriever#OPTION_CLOSEST_SYNC , or android.media.MediaMetadataRetriever#OPTION_CLOSEST |
dstWidth |
Int: expected output bitmap width Value is 1 or greater |
dstHeight |
Int: expected output bitmap height Value is 1 or greater |
params |
MediaMetadataRetriever.BitmapParams: BitmapParams that controls the returned bitmap config (such as pixel formats). This value cannot be null . |
Return | |
---|---|
Bitmap? |
A Bitmap of size not larger than dstWidth by dstHeight containing a scaled video frame, which can be null, if such a frame cannot be retrieved. |
Exceptions | |
---|---|
java.lang.IllegalArgumentException |
if passed in invalid option or width by height is less than or equal to 0. |
release
open fun release(): Unit
Releases any acquired resources. Call it when done with the object.
Exceptions | |
---|---|
java.io.IOException |
When an IOException is thrown while closing a MediaDataSource passed to setDataSource(android.media.MediaDataSource) . This throws clause exists since API android.os.Build.VERSION_CODES#TIRAMISU , but this method can throw in earlier API versions where the exception is not declared. |
setDataSource
open fun setDataSource(path: String!): Unit
Sets the data source (file pathname) to use. Call this method before the rest of the methods in this class. This method may be time-consuming.
Parameters | |
---|---|
path |
String!: The path, or the URI (doesn't support streaming source currently) of the input media file. |
Exceptions | |
---|---|
java.lang.IllegalArgumentException |
If the path is invalid. |
setDataSource
open fun setDataSource(
uri: String!,
headers: MutableMap<String!, String!>!
): Unit
Sets the data source (URI) to use. Call this method before the rest of the methods in this class. This method may be time-consuming.
Parameters | |
---|---|
uri |
String!: The URI of the input media. |
headers |
MutableMap<String!, String!>!: the headers to be sent together with the request for the data |
Exceptions | |
---|---|
java.lang.IllegalArgumentException |
If the URI is invalid. |
setDataSource
open fun setDataSource(
fd: FileDescriptor!,
offset: Long,
length: Long
): Unit
Sets the data source (FileDescriptor) to use. It is the caller's responsibility to close the file descriptor. It is safe to do so as soon as this call returns. Call this method before the rest of the methods in this class. This method may be time-consuming.
Parameters | |
---|---|
fd |
FileDescriptor!: the FileDescriptor for the file you want to play |
offset |
Long: the offset into the file where the data to be played starts, in bytes. It must be non-negative |
length |
Long: the length in bytes of the data to be played. It must be non-negative. |
Exceptions | |
---|---|
java.lang.IllegalArgumentException |
if the arguments are invalid |
setDataSource
open fun setDataSource(fd: FileDescriptor!): Unit
Sets the data source (FileDescriptor) to use. It is the caller's responsibility to close the file descriptor. It is safe to do so as soon as this call returns. Call this method before the rest of the methods in this class. This method may be time-consuming.
Parameters | |
---|---|
fd |
FileDescriptor!: the FileDescriptor for the file you want to play |
Exceptions | |
---|---|
java.lang.IllegalArgumentException |
if the FileDescriptor is invalid |
setDataSource
open fun setDataSource(
context: Context!,
uri: Uri!
): Unit
Sets the data source as a content Uri. Call this method before the rest of the methods in this class. This method may be time-consuming.
Parameters | |
---|---|
context |
Context!: the Context to use when resolving the Uri |
uri |
Uri!: the Content URI of the data you want to play |
Exceptions | |
---|---|
java.lang.IllegalArgumentException |
if the Uri is invalid |
java.lang.SecurityException |
if the Uri cannot be used due to lack of permission. |
setDataSource
open fun setDataSource(dataSource: MediaDataSource!): Unit
Sets the data source (MediaDataSource) to use.
Parameters | |
---|---|
dataSource |
MediaDataSource!: the MediaDataSource for the media you want to play |
Protected methods
finalize
protected open fun finalize(): Unit
Exceptions | |
---|---|
java.lang.Throwable |
the Exception raised by this method |