Features
Media files often contain metadata. This extension extracts metadata from media files and makes them available. The metadata can be extracted from physically existing files as well as from streaming files (e.g. "https://...mp3). All data can be completed by program.
The UrsMediaNotification extension can accept the retrieved metadata directly (later !!!). An album image contained in the metadata can be saved or passed directly to an Image component.
| Version | Adjustments |
|---|---|
| 1.0 (2021-07-06) | Initial version |
| 1.1 (2024-09-04) | Adaptations to Android 14 |
Download
The UrsAI2MediaHelper ZIP archive for download. The archive contains the source code, the compiled binary for uploading to the App Inventor and a sample application.
Usage
The extension is a wrapper for the Android MediaMetadataRetriever class.
Test data
A test file with metadata is available at the address https://ullisroboterseite.de/test.mp3. The example contains the same file as an asset file.
Laod data
The main methods are LoadMetaData and LoadMetaDataAsync. These two methods extract the metadata from a media file. The following values are valid for the Source parameter :
| Type | Prefix | Example |
|---|---|---|
| URL | http or https | https://ullisroboterseite.de/test.mp3 |
| Asset | // or nothing | //test.mp3 or test.mp3 |
| File, relative path | / | /data/user/0/edu.mit.appinventor.aicompanion3/test.mp3 |
| File, absolute path | file:/// | file:///Android/data/edu.mit.appinventor.aicompanion3/test.mp3 |
If an invalid file specification is entered, the specified file does not exist or is not a media file, it can take up to 30 seconds for the MediaMetadataRetriever to recognize this and return. This is especially true when the files are obtained from the Internet. The Timeout property can be used to define the maximum time to wait for the response.
LoadMetaData waits for the response from the MediaMetadataRetriever and returns whether the process was successful. The application remains inactive for this time. LoadMetaDataAsync loads the metadata in a separate thread and reports the result via the AfterLoadMetaData event. The application remains active while the metadata is being retrieved. However, you have to make sure that you do not access the data before the event has been triggered with the parameter Success = true.
Note: It is not the case that all metadata is always present in each media file.
Album image
The following values are valid for property AlbumImageFile;
| Type | Prefix | Example |
|---|---|---|
| URL | http or https | https://ullisroboterseite.de/ulli.png |
| Asset | // or nothing | //ulli.png or ulli.png |
| File, relative path | / | /data/user/0/edu.mit.appinventor.aicompanion3/ulli.png |
| Fiel, absolute path | file:/// | file:///Android/data/edu.mit.appinventor.aicompanion3/ulli.png |
When specifying an URL, the image is loaded synchronously. This can take some time with large files or slow connections. Another possibility is to use an extension that enables an asynchronous (concurrent) download of the file ( e.g. the ImageLoader extension ).
The properties AlbumImageWidthDip, AlbumImageHeightDip, AlbumImageWidthRaw and AlbumImageHeightRaw return informations on the size of the graphic. The size of the graphic can be adjusted with the methods ResizeAlbumImageDip or ResizeAlbumImageRaw. The SaveAlbumImage and SaveAlbumImageToAppDir methods save the graphic as a file and can be made available to other file-based components.
The ToImageBlock method displays the graphic in the specified Image component.
File support
For an easy access to files you can use:
- GetVolumes: returns a list of the root directories of the data strorages
- GetAppDataDir: returns the path to the private application directory
- GetDownloadDir: returns the path to the download directory
- GetFileList: returns a list with the names of files in a directory
- RemoveFile: removes the specified file
- RemoveFileFromAppDir: removes a file in the private application directory
Error handling
Errors are reported via the Screen.ErrorOccurred event.
| Code | Text | Bedeutung | Anmerkung |
|---|---|---|---|
| 17510 | Album image not found. | The specified album image could not be loaded. | Affected function is AlbumImageFile. |
| 17511 | Invalid size. | Invalid size, width or height ≤ 0. | Affected functions are ResizeAlbumImageDip and ResizeAlbumImageRaw. |
| 17512 | IO error & Fehlergrund. | File could not be written or deleted. | Affected functions are SaveAlbumImage, SaveAlbumImageToAppDir, RemoveFile and RemoveFileFromAppDir. |
| 17513 | Invalid format. | The value for parameter Format is invalid. 0 or 1 is allowed. | Affected functions are SaveAlbumImage and SaveAlbumImageToAppDir. |
| 17514 | Invalid component type. | The specified component is not of type Image. | Affected function is ToImageBlock. |
Reference
Properties
- Album
- Gests or sets the album title for the media.
- AlbumImageFile
- Reads the album image from the specified file. The file name can only valid if it is set by program. After calling
LoadMetaData or
LoadMetaDataAsync, this field is empty.
If the album image cannot be loaded, the Screen.ErrorOccurred event is triggered with the error number 17500. - AlbumImageHeightDip
- Gets the height of the album image in DIP (Device Independent Pixel) units.
- AlbumImageHeightRaw
- Gets the height of the album image in units of pixels.
- AlbumImageWidthDip
- Gets the width of the album image in DIP (Device Independent Pixel) units.
- AlbumImageWidthRaw
- Gets the width of the album image in units of pixels.
- Artist
- Gets or sets the artist / performer.
- Author
- Gets or sets the author.
- Duration
- Gets or sets the duration in milliseconds.
- DurationFormattedLong
- Gets the duration as text in the format H:MM:SS.
- DurationFormattedShort
- Gets the duration as text in the format M:SS.
- DurationSeconds
- Gets or sets the duration in seconds.
- Genre
- Gets or sets the genre of the media.
- HasAlbumImage
- Returns whether there is a valid album image.
- MimeType
- Gets or sets the MIME type.
- Timeout
- Specifies how long (in seconds) to wait for metadata to be loaded from the Internet. The default is 3 seconds.
- Title
- Gets or sets the title of the media file.
- Writer
- Gets or sets the writer of the media file.
- Year
- Gets or sets the year of creation.
Methods
- GetAppDataDir (Prefix)
- Returns the path for the app sepcific directory. Calling
GetAppDataDir()on my test device (in the example below) returns the following result:
file:///data/user/0/edu.mit.appinventor.aicompanion3/ - GetDownloadDir (Prefix)
- Returns the path for the download directory. Prefix is placed in front of
the name. Calling
GetDownloadDir("file://")on my test device (in the example below) returns the following result:
file:///storage/emulated/0/Download - GetFileList (Directory)
- Returns a list with the names of the files in the specified directory. The file://
prefix for the Directory parameter is optional. Subdirectory names are preceded by "D:". Calling
GetFileList(GetAppDataDir())on my test device for the example program returns a list with the following elements:
- GetVolumes (Prefix)
- Returns a list of the installed volumes. The internal memory can usually be found under index 1, the external
SD card under index 2. Prefix is placed in front of the name. Calling
getVolumes("file://)on my test device returns the following items :
file:///storage/emulated/
file:///storage/F277-0260/ - LoadMetaData (Source)
- Loads media metadata from the specified media file. For valid values for the parameter
Source, see Load data. The return value is
true if the metadata could be loaded successfully, otherwise
false.
The application is blocked during readout (see also Load data and Timeout property). - LoadMetaDataAsync (Source)
- Loads media metadata from the specified media file in a separate thread. For valid values for the parameter
Source, see Load data. After the retrieving process is complete,
the AfterLoadMetaData event is triggered. No
valid metadata is available before the event has been triggered with the parameter
Success = true.
The application is not blocked during the readout (see also Load data and Timeout property). - RemoveFile (Path)
- Deletes the specified file. The prefix file:// for the parameter
Path is optional.
If the file could not be deleted, the Screen.ErrorOccurred is triggered with the error number 17512. - RemoveFileFromAppDir (Filename)
- Deletes the specified file in the private application directory. Filename
can contain subdirectories relative to the private application directory (see
GetAppDataDir).
If the file could not be deleted, the Screen.ErrorOccurred is triggered with the error number 17512. - ResizeAlbumImageDip (NewWidth, NewHeight)
- Resizes the album image. The size data is given in the unit DIP (Device
Independent Pixel).
If one of the size specifications is ≤ 0, the Screen.ErrorOccurred event is triggered with the error number 17511. - ResizeAlbumImageRaw (NewWidth, NewHeight)
- Resizes the album image.
The size data is given in the unit Pixel.
If one of the size specifications is ≤ 0, the Screen.ErrorOccurred event is triggered with the error number 17511. - SaveAlbumImage (Path, Format)
- Saves the album image under the specified file path. Format: 0:
PNG, 1: JPEG. The file extension
.png or .jpg is not added automatically, but must
be specified appropriately in parameter Path. The prefix
file:// for the parameter Path is optional.
If the file could not be written, the Screen.ErrorOccurred is triggered with the error number 17512.
If the Format parameter has a value other than 0 or 1, the Screen.ErrorOccurred is triggered with the error number 17513. - SaveAlbumImageToAppDir (Filename, Format)
- Saves the file relative to the private application directory (see
GetAppDataDir). Format: 0:
PNG, 1: JPEG. The file extension
.png or .jpg is not added automatically, but must
be specified appropriately in parameter Path.
If the file could not be written, the Screen.ErrorOccurred is triggered with the error number 17512.
If the Format parameter has a value other than 0 or 1, the Screen.ErrorOccurred is triggered with the error number 17513. - ToImageBlock (ImageBlock)
- If present, displays the album image in the specified
Image component.
If the specified component is not of the type Image, the Screen.ErrorOccurred is triggered with the error number 17514.
Events
- AfterLoadMetaData (Success)
- The event is triggered when the result of the retrieving process is available after calling LoadMetaDataAsync. Success has the value true if metadata could be read in, otherwise the value false.
Example
The download archive contains a sample project:
MediaHelper Test
The example can load media metadata synchronously (Load Media Metadata) and asynchronously (Load Media Metadata async). The album image can be saved in the private folder of the app (Save album image) and deleted (Remove file). The List files button lists the files in the app's private folder.
Tools
I have collected a few tips for creating your own extensions: AI2 FAQ: Developing extensions .