chrome.mediaGalleries

Description:	Use the `chrome.mediaGalleries` API to access media files (audio, images, video) from the user's local disks (with the user's consent).
Availability:	Stable since Chrome 23.
Permissions:	{"mediaGalleries": ["accessType1", "accessType2", ...]} {"mediaGalleries": ["accessType1", "accessType2", ..., "allAutoDetected"]} See Manifest below for more information.
Learn More:	Chrome Office Hours: The Media Galleries API

Usage

The mediaGalleries API lets you prompt the user for permission to access media galleries on the user's computer. The permission dialog contains common media locations for the platform and allows the user to specify additional locations. From those locations, only media files will be present in the file system objects.

Manifest

The media galleries API has two axes of permission parameters:

the locations that can be accessed
the type of access

These two axes and the permission parameters on each axis are described in the table below:

Axis	Parameter	Effect
Locations	none	If you do not specify a location permission parameter, your app will not be able to access any media galleries until the user grants permission to access specific media galleries at runtime using the media gallery permission dialog.
Locations	"allAutoDetected"	Grants your app access to all auto-detected media galleries on the user's computer. This permission causes an install-time prompt to be displayed indicating that the app will have access to the user's media files.
Access type	"read"	Grants your app the right to read files in media galleries.
	"delete"	Grants your app the right to delete files from media galleries. "read" permission is a prerequisite for "delete". Specify both "read" and "delete" to obtain both types of permissions to media galleries.
	"copyTo"	Grants your app the right to copy files into media galleries. Only valid media files that Chrome is capable of playing or displaying are permitted; files that Chrome is not able to validate will result in a security error. "read" and "delete" permissions are prerequisites for "copyTo". Specify "read", "delete" and "copyTo" to obtain all three types of permissions to media galleries.

Notes:

The media gallery permission dialog can be triggered programmatically. The user may have alternate media locations, so even if you specify "allAutoDetected" permsission, it is still important to provide a mechanism to open the permission dialog in your app.
There is no write access to media galleries due to the file validation requirement. However, you can write files to a different file system like the temporary file system, and then copy the files into the desired media gallery.
Access type permissions do not trigger an install-time prompt by themselves. However, the type of access will be reflected in the media gallery permission dialog, as well as the install-time prompt if "allAutoDetected" permission is requested.

Below is an example of a manifest file with mediaGalleries permissions:

      {
        "name": "My app",
        ...
        "permissions": [
          { "mediaGalleries": ["read", "allAutoDetected"] }
        ],
        ...
      }

This example manifest file will trigger an install-time permission prompt, and let the app read from all auto-detected media galleries on the user's computer. The user may add or remove galleries using the media gallery permission dialog, after which the app will be able to read all the media files from galleries that the user selected.

iTunes

If present, the user's iTunes library can be accessed as a media gallery. In addition to the media files in the library, the "iTunes Music Library.xml" file is also presented. Regardless of where the music files are actually on the disk (and where the xml file says they are), they are mapping into an Artist/Album/Track hierarchy like iTunes does by default. This mapping doesn't always work perfectly, so there are two things to note for Apps trying to match the xml file with files in the gallery. If the filenames for tracks within an album are not unique, they will be uniquified by adding the track id in parentheses before the extension, and if there is a colon or a slash in the artist, album, or track name, they are turned into underscore characters.

Picasa

If present, the user's Picasa library can also be accessed as a media gallery. Directories on the filesystem scanned by Picasa are presented under folders/. Picasa Albums are presented under albums/. Albums and Folders that have duplicate names and dates will be uniquified using an incrementing integer in parenthesis before the extension. Duplicate filenames within the same Album will also be uniquified using an incrementing integer in parenthesis before the extension.

Summary

Methods
getMediaFileSystems − `chrome.mediaGalleries.getMediaFileSystems(object details, function callback)`
addUserSelectedFolder − `chrome.mediaGalleries.addUserSelectedFolder(function callback)`
startMediaScan − `chrome.mediaGalleries.startMediaScan()`
cancelMediaScan − `chrome.mediaGalleries.cancelMediaScan()`
addScanResults − `chrome.mediaGalleries.addScanResults(function callback)`
getMediaFileSystemMetadata − `object chrome.mediaGalleries.getMediaFileSystemMetadata(DOMFileSystem mediaFileSystem)`
getAllMediaFileSystemMetadata − `chrome.mediaGalleries.getAllMediaFileSystemMetadata(function callback)`
getMetadata − `chrome.mediaGalleries.getMetadata(Blob mediaFile, object options, function callback)`
Events
onScanProgress

Methods

getMediaFileSystems


              chrome.mediaGalleries.getMediaFileSystems(object details, function callback)

Get the media galleries configured in this user agent. If none are configured or available, the callback will receive an empty array.

Parameters

object

(optional) details

enum of "no", "yes", or "if_needed"

(optional) interactive

Whether to prompt the user for permission to additional media galleries before returning the permitted set. Default is silent. If the value 'yes' is passed, or if the application has not been granted access to any media galleries and the value 'if_needed' is passed, then the media gallery configuration dialog will be displayed.

no: Do not act interactively.

yes: Ask the user to manage permitted media galleries.

if_needed: Ask the user to manage permitted galleries only if the return set would otherwise be empty.

function

callback

The callback parameter should be a function that looks like this:

function(array of DOMFileSystem mediaFileSystems) {...};

array of DOMFileSystem

mediaFileSystems

Properties of each object

addUserSelectedFolder


              chrome.mediaGalleries.addUserSelectedFolder(function callback)

Present a directory picker to the user and add the selected directory as a gallery. If the user cancels the picker, selectedFileSystemName will be empty. A user gesture is required for the dialog to display. Without a user gesture, the callback will run as though the user canceled.

Parameters

function

callback

The callback parameter should be a function that looks like this:

function(array of DOMFileSystem mediaFileSystems, string selectedFileSystemName) {...};

array of DOMFileSystem

mediaFileSystems

Properties of each object

string

selectedFileSystemName

startMediaScan


              chrome.mediaGalleries.startMediaScan()

Start a scan of the user's hard disks for directories containing media. The scan may take a long time so progress and completion is communicated by events. No permission is granted as a result of the scan, see addScanResults.

cancelMediaScan


              chrome.mediaGalleries.cancelMediaScan()

Cancel any pending media scan. Well behaved apps should provide a way for the user to cancel scans they start.

addScanResults


              chrome.mediaGalleries.addScanResults(function callback)

Show the user the scan results and let them add any or all of them as galleries. This should be used after the 'finish' onScanProgress() event has happened. All galleries the app has access to are returned, not just the newly added galleries.

Parameters

function

callback

The callback parameter should be a function that looks like this:

function(array of DOMFileSystem mediaFileSystems) {...};

array of DOMFileSystem

mediaFileSystems

Properties of each object

getMediaFileSystemMetadata


              object
              chrome.mediaGalleries.getMediaFileSystemMetadata(DOMFileSystem mediaFileSystem)

Get metadata about a specific media file system.

Parameters
DOMFileSystem	mediaFileSystem

Returns

string	name	The name of the file system.
string	galleryId	A unique and persistent id for the media gallery.
string	(optional) deviceId	If the media gallery is on a removable device, a unique id for the device while the device is online.
boolean	isRemovable	True if the media gallery is on a removable device.
boolean	isMediaDevice	True if the device the media gallery is on was detected as a media device. i.e. a PTP or MTP device, or a DCIM directory is present.
boolean	isAvailable	True if the device is currently available.

getAllMediaFileSystemMetadata


              chrome.mediaGalleries.getAllMediaFileSystemMetadata(function callback)

Get metadata for all available media galleries.

Parameters

function

callback

The callback parameter should be a function that looks like this:

function(array of object metadata) {...};

array of object

metadata

Properties of each object

string	name	The name of the file system.
string	galleryId	A unique and persistent id for the media gallery.
string	(optional) deviceId	If the media gallery is on a removable device, a unique id for the device while the device is online.
boolean	isRemovable	True if the media gallery is on a removable device.
boolean	isMediaDevice	True if the device the media gallery is on was detected as a media device. i.e. a PTP or MTP device, or a DCIM directory is present.
boolean	isAvailable	True if the device is currently available.

getMetadata


              chrome.mediaGalleries.getMetadata(Blob mediaFile, object options, function callback)

Gets the media-specific metadata for a media file. This should work for files in media galleries as well as other DOM filesystems.

Parameters

Blob mediaFile

object

(optional) options

enum of "all", or "mimeTypeOnly"

(optional) metadataType

Specifies which subset of the metadata to retrieve. Defaults to 'all' if the option is omitted.

all: Retrieve all available metadata.

mimeTypeOnly: Retrieve only the mime type.

function

callback

The callback parameter should be a function that looks like this:

function(object metadata) {...};

object

metadata

string	mimeType	The browser sniffed mime type.
integer	(optional) height	Defined for images and video. In pixels.
integer	(optional) width
double	(optional) duration	Defined for audio and video. In seconds.
integer	(optional) rotation	Defined for images and video. In degrees.
string	(optional) album	Generic metadata tags.
string	(optional) artist
string	(optional) comment
string	(optional) copyright
integer	(optional) disc
string	(optional) genre
string	(optional) language
string	(optional) title
integer	(optional) track

Events

onScanProgress

The pending media scan has changed state. See details for more information.

addListener


                    chrome.mediaGalleries.onScanProgress.addListener(function callback)

Parameters

function

callback

The callback parameter should be a function that looks like this:

function(object details) {...};

object

details

enum of `"start"`, `"cancel"`, `"finish"`, or `"error"`	type	The type of progress event, i.e. start, finish, etc. start The scan started. cancel The scan was cancelled. finish The scan finished but none of the result have been added, addScanResults() has to be called to ask the user for permission. error The scan encountered an error and could not proceed.
integer	(optional) galleryCount	The number of Galleries found.
integer	(optional) audioCount	Appoximate number of media files found; some file types can be either audio or video and are included in both counts.
integer	(optional) imageCount
integer	(optional) videoCount