The Device APIs Working Group is currently not pursuing the approach outlined in this draft, so it should be considered historical. Please treat this document with caution and do not reference it or use it as the basis for implementation. The domain covered by this document is still within the scope of the Working Group as defined in its Charter. The Working Group may pursue an alternative API design that is based on the current Web browser security model.

This specification defines an Application Programming Interface (API) that provides access to media gallery located on the device.

Introduction

The Gallery API defines a high-level interface for accessing media gallery located on the device. A media gallery is a collection of media objects such as video, audio and image.

Usage Examples

Further examples are required to give better understanding concerning the overall functions of the gallery API.

The following code extracts illustrate how to work with a gallery API in the device:

				  		
				// append images with a title matching 'foobar' from galleries 
				// not older than 3 months to the document.body

				var gallery = navigator.service.gallery;

				function getGalleriesSuccess(galleryInfoObjs) {
				    var galleries = [];
				    for (var i in galleryInfoObjs) {
				        if ((new Date().getTime())-galleryInfoObjs[i].createDate < 100*60*60*24*3) {
				            galleries.push(galleryInfoObjs[i]);
				        }
				    }
				    appendMedia(galleries);
				}

				function appendMedia(galleries) {
				    function findSuccess(mediaObjs) {
				        var container = document.createElement("div");
				        for (var i in mediaObjs) {
				            var img = document.createElement("img");
				            var title = document.createElement("div");
				            title.innerHTML = "Title: " + mediaObjs[i].title;
				            // create blob URI using window.createObjectURL():
				            // http://dev.w3.org/2006/webapi/FileAPI/#creating-revoking
				            img.src = createObjectURL(mediaObjs[i]);
				            container.appendChild(img);
				            container.appendChild(title);
				        }
				        document.body.appendChild(container);
				    }
					
				    function findError() {
				        console.log('whoops, something went wrong!');
				    }
					
				    gallery.find(['title', 'uri'], findSuccess, findError,
				            {filter: 'foobar', galleries: galleries, mediaType: gallery.IMAGE_TYPE });
				}

				gallery.getGalleries(getGalleriesSuccess);

			

Security and Privacy Considerations

This section is under development.

The API defined in this specification can be used to add, update, find and delete media objects from user's media gallery. This information can potentially compromise user privacy and a conforming implementation of this specification MUST provide a mechanism that protects the user's privacy and this mechanism should ensure that such operations MUST be authenticated.

Privacy considerations for implementers of Gallery API

A conforming implementation of this specification MUST provide a mechanism that protects the user's privacy and this mechanism SHOULD ensure that privacy information is not revealed without user's informed consent.

API Description

MediaObject interface

MediaObject interface offer access to information regarding an each media object. A media object is a media file belonged to the gallery, that is an video, audio or image file.

readonly attribute unsigned long id
Unique id of media object. This id is a unique numeric identifiers of the object. This id is persistent while the gallery is opened.
readonly attribute GalleryInfo gallery
gallery information associated to the media object.
readonly attribute DOMString? title
The title of the media object.
readonly attribute DOMString? language
The language used in the media object.
readonly attribute DOMString? locator
The logical address at which the media object can be accessed.
readonly attribute DOMString? contributor
The contributor related with the media object. e.g., actor, cameraman, director, singer, author, artist, etc.
readonly attribute DOMString? creator
The author of the media object.
readonly attribute Date? CreateDate
The date and time the media object was originally created.
readonly attribute DOMString? location
The description where the media object has been created, developed, recorded, or otherwise authored.
readonly attribute DOMString? description
A free-form text describing the content of the media object.
readonly attribute DOMString? keyword
A concept, descriptive phrase or keyword that specifies the topic of the media object.
readonly attribute DOMString? genre
The category of the content of the media object.
readonly attribute unsigned long? rating
The rating value related with the media object.
readonly attribute DOMString? relation
The description related with resource that the current media object is related with.
readonly attribute DOMString? collection
The name of the collection from which the media object originates or to which it belongs.
readonly attribute DOMString? copyright
The copyright statement. Identification of the copyrights holder.
readonly attribute DOMString? policy
A policy statement (typically human-readable) associated with the media object.
readonly attribute DOMString? publisher
The publisher of a media object.
readonly attribute DOMString? argetAudience
The classification information related with media object including the issuer of the classification (e.g., a parental guidance issuing agency, or a targeted geographical region).
readonly attribute DOMString? fragment
A fragment identifier. A fragment is a portion of the resource
readonly attribute DOMString? namedFragment
A named fragment identifier.
readonly attribute unsigned long? frameSize
The frame size of the media object (e.g., width and height of 720 and 480 units, respectively).
readonly attribute DOMString? compression
The compression type used.
readonly attribute unsigned long? duration
The actual duration of the media object.
readonly attribute DOMString? format
The MIME type of the media object (e.g., wrapper or bucket media types).
readonly attribute unsigned long? samplingRate
The audio sampling rate.
readonly attribute unsigned long? framerate
The video frame rate.
readonly attribute unsigned long? averageBitRate
The average bit rate.
readonly attribute unsigned short? numTracks
The number of tracks of a resource.

GalleryInfo interface

GalleryInfo interface capture generic metadata information of a gallery.

supportedMediaObjectType attribute is required? Other attribute could be taken into account.

readonly attribute DOMString title
The title of the gallery.
readonly attribute Date createdDate
The date and time the gallery was originally created.
readonly attribute DOMString location
The location the gallery is located on.
readonly attribute DOMString[] description
>The description of the gallery.
readonly attribute DOMString[] supportedMediaObjectType
A list of media object type supported by this gallery.

GalleryFindOptions interface

GalleryFindOptions interface describe the options that can be applied to media object searching and displaying.

attribute DOMString? filter
A DOMString-based search filter with which to search. It's working based on the metadata of media object.
attribute short? mediaType
Specify the scope of media type for finding the media object
attribute GalleryInfo[]? gallery
Specify the scope of gallery for finding the media object
attribute short? order
Specify wheither media objects are ordered in ascending or descending order. Default is an ascending order.
attribute short? firstSortOption
Primary criteria to order the media object of the gallery.
attribute short? secondSortOption
Second criteria to order the media object of the gallery.
attribute Date? startDate
Start date for performing the search. Media object with date previous to that date will not be returned.
attribute Date? endDate
End date for performing the search. Media object with date later to that date will not be returned.

GalleryFindCB interface

void onSuccess (in MediaObject[] mediaObjectObjs)
MediaObject[] mediaObjectObjs
The Media Object resulting from the given Gallery find() method.

GalleryInfoCB interface

void onSuccess (in GalleryInfo[] galleryInfoObjs)
GalleryInfo[] galleryInfoObjs
The GalleryInfo Objects resulting from the given Gallery getGalleries() method.

GalleryErrorCB interface

void onError ()
GalleryError error
The Gallery API related error object.

GalleryError interface

The GalleryError interface encapsulates all errors in the Gallery API.

More error codes to be defined here.

const unsigned short UNKNOWN_ERROR = 0
An unknown error occurred.
const unsigned short INVALID_ARGUMENT_ERROR = 1
An invalid parameter was provided when the requested method was invoked.
const unsigned short TIMEOUT_ERROR = 2
The requested method timed out before it could be completed.
const unsigned short PENDING_OPERATION_ERROR = 3
If the user agent is currently waiting for a callback on a current find() operation, as defined in this specification.
const unsigned short IO_ERROR = 4
An error occurred in communication with the underlying implementation that meant the requested method could not complete.
const unsigned short NOT_SUPPORTED_ERROR = 5
The requested method is not supported by the current implementation.
const unsigned short PERMISSION_DENIED_ERROR = 20
Access to the requested method was denied at the implementation or by the user.
readonly attribute unsigned short code
An error code assigned by an implementation when an error has occurred in Gallery API processing.

Use Cases and Requirements

Use Cases

Use Case 1:

While uploading a photo to a web site, I'd like the photos that are relevant in that context to be represented to me to select from. E.g. if I'm uploading a photo to a travel blog about Paris I'm probably only interested in photos from that area, thus I'd like those to be shown to me very prominently (I should still be able to select photos from other areas, if I want to).

Use Case 2: Picture album application

When user executes picture album app, this should list up the albums those were available from handset memory, external memory and even flickr, facebook. There are a lot of different albums. Thus user would like to sort these by the specific metadata property like title, created date, location, etc. Typically when one album has a lot of pictures, user would like to search a picture by the specific metadata information. In addtion, user wants to reorder pictures by the some metadata information. And user would like to take a look at some pictures those were taken in special place.

Requirements

The Gallery API:

Related documents

The API described in this document took inspiration from the following documents:

Features for Future Consideration

This is a list of features that have been discussed with respect to this version of the API but for which it has been decided that if they are included it will be in a future revision.

Acknowledgements

Many thanks to OMTP BONDI who provided the initial input into this specification.