Example

After the user successfully captured or selected an existing media file, the format properties of the file can be retrieved as follow:

var captureInput = document.getElementById('capture');
// Accessing the file object from the input element with id capture
var file = captureInput.files[0];
if (file) {
  // getting format data asynchronously
  file.getFormatData(displayFormatData, errorHandler);
}

// success callback when getting format data
function displayFormatData(formatData) {  
  var mainType = file.type.split("/")[0]; // "image", "video" or "audio"
  var mediaDescriptionNode = document.createElement("p");
  if (mainType === "image") {
    mediaDescriptionNode.appendChild(document.createTextNode("This is an image of dimensions " + formatData.width + "x" + formatData.height);
  } else {
    mediaDescriptionNode.appendChild(document.createTextNode("Duration: " + formatData.duration  + "s");
  }
  captureInput.parentNode.insertBefore(mediaDescriptionNode, captureInput);
}

// error callback if getting format data fails
function errorHandler(error) {
  alert("Couldn’t retrieve format properties for the selected file (error code " + error.code + ")");
}

MediaFileData interface

MediaFileData encapsulates format information of a media file.

The relationship between this MediaFileData interface and the properties made available through the API for Media Resource 1.0 [[MEDIAONT-API]] needs further investigation.

attribute DOMString codecs

The type attribute of the Blob interface (inherited from the File interface) is not sufficient to determine the format of the content since it only specifies the container type. The codecs attribute represents the actual format that the audio and video of the content. The codecs attribute MUST conform to the [[!RFC4281]]. For example, a valid value for H.263 video and AAC low complexity would be codecs="s263, mp4a.40.2".

This could be turned into a list of DOMString rather than keeping it as a comma-separated values list; this needs some care with regard to the RFC ref.

attribute unsigned long bitrate

The codecs attribute only specifies the profile and level of the encoded content which doesn't specify the actual bitrate. It only specifies the maximum encoded bitrate, thus this bitrate attribute is the average bitrate of the content. In the case of an image this attribute has value 0.

attribute unsigned long height

The height attribute represents height of the image or video in pixels. In the case of a sound clip this attribute has value 0.

attribute unsigned long width

The width attribute represents width of the image or video in pixels. In the case of a sound clip this attribute has value 0.

attribute float duration

The duration attribute represents length of the video or sound clip in seconds. In the case of an image this attribute has value 0.

Some of the proposed attributes of the MediaFileData interface could possibly be integrated as parameters of the MIME type, or as MIME options object.

MediaFile interface

MediaFile encapsulates a single photo, video or sound from the device. It inherits from File [[!FILE-API]].

void getFormatData (in MediaFileDataSuccessCallback successCallback, in optional MediaFileDataErrorCallback errorCallback)

The getFormatData() method takes one or two arguments. When called, it returns immediately and then asynchronously attempts to obtain the format data of the given media file. If the attempt is successful, the successCallback is invoked with a new MediaFileData object, reflecting the format data of the file. If the attempt fails, the errorCallback is invoked with a new MediaFileDataError object, reflecting the reason for the failure.

MediaFileDataSuccessCallback interface

void onSuccess()

MediaFileData formatData

The MediaFileData object describing the relevant properties of the given media file.

MediaFileDataErrorCallback interface

void onError()

MediaFileDataError error

The MediaFileDataError object describing the error encountered while retrieving the format data.

MediaFileDataError interface

The MediaFileDataError interface encapsulates all errors in the retrieval of format data associated with a MediaFile object.

const unsigned short UNKNOWN_ERROR = 0

An unknown error occurred.

const unsigned short TIMEOUT_ERROR = 1

The requested method timed out before it could be completed.

readonly attribute unsigned short code

An error code assigned by an implementation when an error has occurred in retrieving format data.