Deutsche Version   Deutsche Version


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

Download

Usage

Test data

Load data

Album image

File support

Error handling

Reference

Properties

Methods

Events

Example

Tools

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:

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 .