interface window.MediaFileSystems {

// Get the media file systems configured in this user agent. Calling

// getMediaFileSystems or openMediaFileSystemsManager will trigger a

// permission prompt for any origin that has not yet been granted

// permission.


// The FileSystem objects returned by this method should be filtered so

// that only media files are present.  If the user tries to write a

// filename that conflicts with a non-media file, the attempt must fail.


// It is recommended that media file systems include standard system

// media directories for the current user such as ‘My Pictures’, ‘My

// Videos’ and ‘Shared Pictures’.


// When a removable media device is inserted it is recommended that the

// device be exposed as a media file system in the body of a web intent.

void getMediaFileSystems(FileSystemsCallback successCallback,

optional ErrorCallback errorCallback);

// Request that the user agent should its media file system

// configuration UI.  If the user agent is able to determine that the

// call is the call of a legitimate user request, it must show

// configuration UI. However, if the origin hasn’t been granted access

// to any media file systems, a standard permission prompt may be

// presented instead of the configuration UI.

void openMediaFileSystemsManager();

// Get any thumbnails contained in the passed media file. The resulting

// directory reader refers to a virtual directory that can not be

// navigated to. If the file was previously indexed the embedded

// thumbnails may be cached by the user agent, making this function

// complete faster.

DirectoryReader extractEmbeddedThumbnails(FileEntry mediaFile);

// If the user agent is able to create thumbnail from the passed media

// file, create a high quality scaling of the original content bound

// by the specified size (i.e. requesting 128x128 on a 4:3 aspect

// source file will produce a 128x96 result).

void getCustomThumbnail(FileEntry mediaFile,

number width, number height,

FileCallback successCallback,

optional ErrorCallback errorCallback);

// Create a new Blob consisting of the passed content and metadata,

// overriding any existing metadata in the input blob. If the user agent

// does not recognize the blob as a supported file format the error

// callback must be called.

void assembleMediaFile(Blob mediaFileContents,

Metadata metadata,

BlobCallback successCallback,

optional ErrorCallback errorCallback);


[Callback=FunctionOnly, NoInterfaceObject]

interface FileSystemsCallback {

void handleEvent(FileSystem[] mediaFileSystems);


[Callback=FunctionOnly, NoInterfaceObject]

interface BlobCallback {

void handleEvent(Blob mediaFile);


The following are additions to the file system api.

interface FileSystem {

// Asynchronously scan the file system for files matching the passed

// mime-type glob (things like image/*, and */* are valid).  For any

// matching files the user agent must extract any metadata it

// understands from inside the file to populate the Metadata attribute.

// If the Metadata attributes already exist, they are

// overwritten/updated. The user agent may continue to keep the metadata

// up to date after MetadataExtractionStatus has signalled completion.

// The user agent may use this function as a signal to create an index

// of the metadata attributes to increase the performance of

// searchMetadata().

MetadataExtractionStatus extractMetadata(DomString mimeType);


interface DirectoryEntry {

// Search the metadata entries in this directory.  If recursive is true,

// also search descendant directories.  All criterion in filters must

// match for a result to be returned. OrderBy indicates the order the

// entries should be returned. The first list entry is the primary sort

// order. If orderBy is absent, the natural ordering of the files will

// be used (usually by filename).

SearchResultReader searchMetadata(Bool recursive,

SearchCriteria filters,

optional SortCriteria orderBy);


interface Entry {

// Add or update the values in the Metadata attribute.  This function

// does not alter the file but updates the user agent view of the

// metadata. This enables storage of metadata not supported by the

// underlying file format, however if the file is moved by the user with

// a file manager, etc, the extra metadata may be lost.  To alter the

// metadata within a file, create a new file with the metadata you want

// and overwrite the existing file.  This function can only change

// attributes added by a extractMetadata or storeMetadata.

void storeMetadata(Metadata metadata);



interface Metadata {

// This specification extends the metadata interface to allow arbitrary

// attributes.  The following generic attribute names are recommended

// for metadata extracted from media files.

attribute DomString mimeType;

attribute number averageBitRate;

attribute DomString codec;

attribute number durationInSeconds;

attribute number framesPerSecond;

attribute number heightInPixels;

attribute number widthInPixels;

attribute number trackCount;

attribute DomString advisoryRating;

attribute DomString album;

attribute DomString artist;

attribute DomString comment;

attribute DomString genre;

attribute DomString[] keywords;        

attribute DomString language; // IETF language code of the material.

attribute number productionYear;

attribute DomString title;

attribute number trackNumber;

// If both source and destination positions are known, the

// destination position is reported here.

attribute number altitude; // Meters above sea level.

attribute number bearing;  // Degrees [0-360).

attribute number latitude; // Decimal latitude with north being pos.

attribute number logitude; // Decimal longitude with east being pos.

attribute number speed;    // Speed in kilometers per hour.

// If the filetype uses a particular metadata format that the user agent

// understands, it should include an object attribute named for the

// metadata format and include all of the data from that format in the

// object i.e. exif.apertureValue.

// The following extended attributes do not correspond to known file

// format structures, but may be used and stored by applications.

// A number indicating this file’s position in the natural sort order

// of all files in the directory.

attribute number directoryPosition;

// Value is an number from 1 (bad) to 5 (good) inclusive.

attribute number userRating;

// Entity tags are to tag people, objects, or items of interest in

// the media file.

attribute EntityTag[] tags;



interface MetadataExtractionStatus {

void abort();

const unsigned short INIT = 0;
unsigned short EXTRACTING = 1;
unsigned short DONE = 2;
readonly attribute
unsigned short readyState;

[TreatNonCallableAsNull] attribute Function onExtractionStart;

[TreatNonCallableAsNull] attribute Function onProgress;

[TreatNonCallableAsNull] attribute Function onExtractionComplete;

[TreatNonCallableAsNull] attribute Function onError;

[TreatNonCallableAsNull] attribute Function onAbort;


// This interface is like DirectoryReader but the entries may be from

// different directories.


interface SearchResultReader {

// Get the next set of results that are available. An empty array will

// be produced when there are no more results.

void readResults(EntriesCallback successCallback,

optional ErrorCallback errorCallback);

// Cancel the search.  All further calls to readResults will produce an

// empty array.

void cancel();


[Callback, NoInterfaceObject]

interface SearchCriterion {

// Values for op attributes.


// Search operation for strict equality. Works for string or numeric

// types.

const unsigned short EQUALS_OP = 0;


// The value for a STRING_MATCH_OP search should be a glob-style

// string to match against a string field. If the field is not a

// string, this will match against the stringified field value when

// possible.  ‘?’ will match a single character and ‘*’ will match

// any number of characters.

const unsigned short STRING_MATCH_OP = 1;

// Takes a value that is an array or array-like container of possible

// values and returns any entry that matches one of the values.

const unsigned short CONTAINS_OP = 2;

// The value for a RANGE_OP search should be an array or array-like

// container with 2 elements. The first element should be the lower

// bound (inclusive) and the second element should be the upper bound

// (inclusive). For an unbounded search (e.g. less than or greater

// than), pass undefined for the unbounded end. Both ends must not be

// unbounded.

const unsigned short RANGE_OP = 3;

// Valid names are any attribute of Metadata. Fields which are objects

// can be dereferenced using ‘.’, for example “exif.apertureValue” is a

// valid sort criterion name.

readonly attribute DomString name;

readonly attribute number op;

readonly attribute DomString|number|DomString[]|number[] value;


typedef SearchCriterion[] SearchCriteria;

// A sort criterion. The name specifies the name of a metadata field for

// sorting in ascending order. Reverse indicates if the field is to be

// sorted in descending order.

[NoInterfaceObject, NoInterfaceObject]

interface SortCriterion {

readonly attribute DomString name;

readonly attribute boolean reverse;


// A list of sort criteria

typedef SortCriterion[] SortCriteria;

[Callback, NoInterfaceObject]

interface EntityTag {

attribute bool isPerson;

attribute bool isLandmark;

attribute bool isComment;

attribute DomString Name;

// Assuming a top left origin.

attribute number positionLeft;

attribute number positionTop;

attribute number positionWidth;

attribute number positionHeight;

attribute number startTime;

attribute number endTime;


It would be great if there was a way to add online galleries to the system but we don’t think it makes sense at this juncture to propose a standardized interface to online media providers.  To that end, sser agents may implement a user agent specific API to allow extension or plugins to inject online galleries.  The above API has been influenced by the possibility of an online gallery.


// Get media file systems and pass them to a function that adds them to the UI.

function useMediaFSs(fsa) {

// fsa is an array of media file systems and can be used like other file

// system objects.

for (var i = 0; i < fsa.length; i++) {

var reader = fsa[i].createReader();

addGalleryToUI(fsa[i].name, reader);




// Find images in a media file system that are between 256 and 1024 pixels wide and sort them in reverse

// chronological order.

function findMidSizedPicturesByDate(fs, resultReader) {

var metadataExtractor = fs.extractMetadata(‘image/*’);

metadata.Extractor.onExtractionComplete = function() {

var midSizedImageSelector = [

{‘name’: ‘widthInPixels’,

‘op’: SearchCriterion.RANGE_OP,

‘value’: [256, 1024]},

{‘name’: ‘mimeType’,

‘op’: SearchCriterion.STRING_MATCH_OP,

‘value’: ‘image/*’}];

var dateSorter = [{‘name’: ‘modificationTime’, ‘reverse’: true}];

var result = fs.root.searchMetadata(true, midSizeImageSelector,





Possible permission and configuration UI: