Metadata API

The Metadata API provides interfaces and methods for extracting metadata information from a media file.

The following functionality is provided:

  • Extract selected metadata from a file

Remark: In order to access files, a proper privilege has to be defined additionally:

For more information about how to use Metadata API, see Metadata Guide.

Since: 6.0

Table of Contents

Summary of Interfaces and Methods

Interface Method
MetadataObject
MetadataManager
MetadataFileHandle
DOMString get (MetadataType type)
Blob getFrameAtTime (unsigned long timestamp, optional boolean? isAccurate)
MetadataSyncLyrics getSyncLyrics (unsigned long index)
void release ()
MetadataSyncLyrics

1. Type Definitions

1.1. MetadataType

Specifies the type of a metadata. 
  enum MetadataType { "ALBUM", "ALBUM_ARTIST", "ALTITUDE", "ARTIST", "AUDIO_BITPERSAMPLE", "AUDIO_BITRATE", "AUDIO_CHANNELS",
    "AUDIO_CODEC", "AUDIO_SAMPLERATE", "CLASSIFICATION", "COMMENT", "COMPOSER", "CONDUCTOR", "COPYRIGHT", "DATE", "DESCRIPTION", "DURATION",
    "GENRE", "HAS_AUDIO", "HAS_VIDEO", "LATITUDE", "LONGITUDE", "MODE_360", "RATING", "RECDATE", "ROTATE", "SYNCLYRICS_NUM", "TITLE",
    "TRACK_NUM", "UNSYNCLYRICS", "VIDEO_BITRATE", "VIDEO_CODEC", "VIDEO_FPS", "VIDEO_HEIGHT", "VIDEO_WIDTH" };

Since: 6.0

The types are:

  • ALBUM - album
  • ALBUM_ARTIST - album artist
  • ALTITUDE - altitude
  • ARTIST - artist
  • AUDIO_BITPERSAMPLE - audio bits per sample
  • AUDIO_BITRATE - audio bitrate
  • AUDIO_CHANNELS - audio channels
  • AUDIO_CODEC - audio codec
  • AUDIO_SAMPLERATE - audio sample rate
  • CLASSIFICATION - classification of a content
  • COMMENT - comment
  • COMPOSER - composer
  • CONDUCTOR - conductor
  • COPYRIGHT - copyright
  • DATE - date
  • DESCRIPTION - description
  • DURATION - duration (in milliseconds)
  • GENRE - genre
  • HAS_AUDIO - audio stream count
  • HAS_VIDEO - video stream count
  • LATITUDE - latitude
  • LONGITUDE - longitude
  • MODE_360 - flag indicating if the video is a spherical video
  • RATING - rating of a content
  • RECDATE - recording date
  • ROTATE - rotation (orientation) of a content
  • SYNCLYRICS_NUM - synchronized lyrics (time/lyric set) number
  • TITLE - title
  • TRACK_NUM - track number information
  • UNSYNCLYRICS - unsynchronized lyrics
  • VIDEO_BITRATE - video bitrate
  • VIDEO_CODEC - video codec
  • VIDEO_FPS - video frame rate
  • VIDEO_HEIGHT - video height
  • VIDEO_WIDTH - video width

2. Interfaces

2.1. MetadataObject

The MetadataObject interface defines what is instantiated in the tizen object. 
  [NoInterfaceObject] interface MetadataObject {
    readonly attribute MetadataManager metadata;
  };
  Tizen implements MetadataObject;

Since: 6.0

The tizen.metadata object provides access to the functionality of the Metadata API.

Attributes

  • readonly MetadataManager metadata
    Object representing a Metadata manager.

    Since: 6.0

2.2. MetadataManager

The MetadataManager interface is the top-level interface for the Metadata API. 
  [NoInterfaceObject] interface MetadataManager {
    MetadataFileHandle createFileHandle(Path path) raises(WebAPIException);
  };

Since: 6.0

Methods

createFileHandle
Creates representation of file for metadata operations. 
MetadataFileHandle createFileHandle(Path path);

Since: 6.0

Handle is used for optimization of a process of reading multiple metadata from file. Creation of a handle does not open a file yet. For memory management optimization, handle should be released after reading all needed metadata.

Parameters:

  • path: Path to the file.

Return value:

    MetadataFileHandle: A handle for metadata operations.

Exceptions:

  • WebAPIException

    • with error type NotFoundError, if the path does not point to an existing file.

    • with error type SecurityError, if the application does not have privilege to access the storage. For more information, see Storage privileges.

    • with error type AbortError, if any other error occurs.

Code example:

try
{
  var fileHandle = tizen.metadata.createFileHandle("videos/sample_video.mp4");
  console.log("Created handle for file: " + fileHandle.uri);
}
catch (e)
{
  console.log("Error " + JSON.stringify(e));
}

Output example:

Created handle for file: file:///opt/usr/home/owner/media/Videos/sample_video.mp4

2.3. MetadataFileHandle

Object representing a file for metadata operations. 
  [NoInterfaceObject] interface MetadataFileHandle {
    readonly attribute DOMString uri;
    DOMString get(MetadataType type) raises(WebAPIException);
    Blob getArtwork() raises(WebAPIException);
    Blob getThumbnailFrame() raises(WebAPIException);
    Blob getFrameAtTime(unsigned long timestamp, optional boolean? isAccurate) raises(WebAPIException);
    MetadataSyncLyrics getSyncLyrics(unsigned long index) raises(WebAPIException);
    void release() raises(WebAPIException);
  };

Since: 6.0

Attributes

Methods

get
Extracts a metadata of a given type. 
DOMString get(MetadataType type);

Since: 6.0

Parameters:

  • type: A type of metadata to be extracted.

Return value:

    DOMString: A value of extracted metadata.

Exceptions:

  • WebAPIException

    • with error type TypeMismatchError, if the input parameter is not compatible with the expected type for that parameter.

    • with error type SecurityError, if the application does not have privilege to access the storage. For more information, see Storage privileges.

    • with error type AbortError, if any other error occurs.

Code example:

try
{
  var fileHandle = tizen.metadata.createFileHandle("videos/sample_video.mp4");
  console.log("Video duration is: " + fileHandle.get("DURATION") + " milliseconds");
  console.log("Video title is: " + fileHandle.get("TITLE"));
  fileHandle.release();
}
catch (e)
{
  console.log("Error " + JSON.stringify(e));
}

Output example:

Video duration is: 70138 milliseconds
Video title is: Sample Video
getArtwork
Gets the artwork image included in a media file. 
Blob getArtwork();

Since: 6.5

Return value:

    Blob: A Blob representing artwork.

Exceptions:

  • WebAPIException

    • with error type SecurityError, if the application does not have privilege to access the storage. For more information, see Storage privileges.

    • with error type AbortError, if any other error occurs.

Code example:

/* precondition - path needs to point to a file with a non-empty artwork */
var path = "music/sample.mp3";
var fileHandle = tizen.metadata.createFileHandle(path);
var artwork = fileHandle.getArtwork();
console.log(artwork);

Output example:

Blob {size: 102117, type: "image/jpeg"}
getThumbnailFrame
Gets the thumbnail frame of a video file. 
Blob getThumbnailFrame();

Since: 6.5

Return value:

    Blob: A Blob (image/jpeg) representing a thumbnail frame.

Exceptions:

  • WebAPIException

    • with error type SecurityError, if the application does not have privilege to access the storage. For more information, see Storage privileges.

    • with error type AbortError, if any other error occurs.

Code example:

/* precondition - path needs to point to a video file */
var path = "videos/sample_video.mp4";
var fileHandle = tizen.metadata.createFileHandle(path);
var frame = fileHandle.getFrame();
console.log(frame);

Output example:

Blob {size: 15228, type: "image/jpeg"}
getFrameAtTime
Gets the frame of a video file for a specified time. 
Blob getFrameAtTime(unsigned long timestamp, optional boolean? isAccurate);

Since: 6.5

Parameters:

  • timestamp: A timestamp of a frame to gather in milliseconds.
  • isAccurate [optional] [nullable]: A flag indicating accuracy. When the value is true, flag indicates extracting an exact frame for the given time. When the value is false, flag indicates extracting an I-frame nearest to the given time. Gathering nearest I-frame has better performance.

Return value:

    Blob: A Blob (image/jpeg) representing a frame.

Exceptions:

  • WebAPIException

    • with error type SecurityError, if the application does not have privilege to access the storage. For more information, see Storage privileges.

    • with error type AbortError, if any other error occurs.

Code example:

/* precondition - path needs to point to a video file */
var path = "videos/sample_video.mp4";
var fileHandle = tizen.metadata.createFileHandle(path);
var frame = fileHandle.getFrameAtTime(2000, true);
console.log(frame);

Output example:

Blob {size: 15186, type: "image/jpeg"}
getSyncLyrics
Gets synchronized lyrics saved in multimedia file. 
MetadataSyncLyrics getSyncLyrics(unsigned long index);

Since: 6.5

Parameters:

  • index: An index of lyrics saved in the file. Number of available indexes is available as "SYNCLYRICS_NUM" metadata value.

Return value:

    MetadataSyncLyrics: An object representing synchronized lyrics for a given index.

Exceptions:

  • WebAPIException

    • with error type InvalidValuesError, if input index exceeds a maximum index for the file.

    • with error type SecurityError, if the application does not have privilege to access the storage. For more information, see Storage privileges.

    • with error type AbortError, if any other error occurs.

Code example:

/* precondition - path needs to point to a file with SYLT metadata included */
var path = "music/sample.mp3";
var fileHandle = tizen.metadata.createFileHandle(path);
var lyricsNum = fileHandle.get("SYNCLYRICS_NUM");
for (var i = 0; i < lyricsNum; ++i)
{
  var lyrics = fileHandle.getSyncLyrics(i);
  console.log("Lyrics " + i + " (" + lyrics.timestamp + "ms): " + lyrics.lyrics);
}

Output example:

Lyrics 0 (100ms): TEST lyrics 1
Lyrics 1 (2000ms): TEST lyrics 2
Lyrics 2 (4000ms): TEST lyrics 3
release
Releases all resources related to the handle and marks handle as invalid. 
void release();

Since: 6.0

Exceptions:

  • WebAPIException

    • with error type AbortError, if any error occurs.

Code example:

try
{
  var fileHandle = tizen.metadata.createFileHandle("videos/sample_video.mp4");
  /* Read metadata here */
  console.log("Video duration is: " + fileHandle.get("DURATION") + " milliseconds");
  /* File is no longer needed, release related resources */
  fileHandle.release();
}
catch (e)
{
  console.log("Error " + JSON.stringify(e));
}

Output example:

Video duration is: 70138 milliseconds

2.4. MetadataSyncLyrics

Object representing synchronized lyrics with associated timestamp. The lyrics need to be included in a multimedia file as SYLT metadata tag. Supported formats of encoding are at least UTF-8 and ISO-8859-1. Other formats can be ignored depending on the platform. 
  [NoInterfaceObject] interface MetadataSyncLyrics {
    readonly attribute unsigned long timestamp;
    readonly attribute DOMString lyrics;
  };

Since: 6.5

Attributes

  • readonly unsigned long timestamp
    Time information about lyrics in milliseconds.

    Since: 6.5

  • readonly DOMString lyrics
    Lyrics stored as simple text.

    Since: 6.5

3. Full WebIDL

module Metadata {
  enum MetadataType { "ALBUM", "ALBUM_ARTIST", "ALTITUDE", "ARTIST", "AUDIO_BITPERSAMPLE", "AUDIO_BITRATE", "AUDIO_CHANNELS",
    "AUDIO_CODEC", "AUDIO_SAMPLERATE", "CLASSIFICATION", "COMMENT", "COMPOSER", "CONDUCTOR", "COPYRIGHT", "DATE", "DESCRIPTION", "DURATION",
    "GENRE", "HAS_AUDIO", "HAS_VIDEO", "LATITUDE", "LONGITUDE", "MODE_360", "RATING", "RECDATE", "ROTATE", "SYNCLYRICS_NUM", "TITLE",
    "TRACK_NUM", "UNSYNCLYRICS", "VIDEO_BITRATE", "VIDEO_CODEC", "VIDEO_FPS", "VIDEO_HEIGHT", "VIDEO_WIDTH" };
  Tizen implements MetadataObject;
  [NoInterfaceObject] interface MetadataObject {
    readonly attribute MetadataManager metadata;
  };
  [NoInterfaceObject] interface MetadataManager {
    MetadataFileHandle createFileHandle(Path path) raises(WebAPIException);
  };
  [NoInterfaceObject] interface MetadataFileHandle {
    readonly attribute DOMString uri;
    DOMString get(MetadataType type) raises(WebAPIException);
    Blob getArtwork() raises(WebAPIException);
    Blob getThumbnailFrame() raises(WebAPIException);
    Blob getFrameAtTime(unsigned long timestamp, optional boolean? isAccurate) raises(WebAPIException);
    MetadataSyncLyrics getSyncLyrics(unsigned long index) raises(WebAPIException);
    void release() raises(WebAPIException);
  };
  [NoInterfaceObject] interface MetadataSyncLyrics {
    readonly attribute unsigned long timestamp;
    readonly attribute DOMString lyrics;
  };
};
Except as noted, this content - excluding the Code Examples - is licensed under Creative Commons Attribution 3.0 and all of the Code Examples contained herein are licensed under BSD-3-Clause.
For details, see the Content License.