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:	Since Chrome 35.
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.

iPhoto

iPhoto support was removed in Chrome 51.

Summary

Methods
getMediaFileSystems − `chrome.mediaGalleries.getMediaFileSystems(object details, function callback)`
addUserSelectedFolder − `chrome.mediaGalleries.addUserSelectedFolder(function callback)`
dropPermissionForMediaFileSystem − `chrome.mediaGalleries.dropPermissionForMediaFileSystem(string galleryId, 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)`
addGalleryWatch − `chrome.mediaGalleries.addGalleryWatch(string galleryId, function callback)`
removeGalleryWatch − `chrome.mediaGalleries.removeGalleryWatch(string galleryId)`
getAllGalleryWatch − `chrome.mediaGalleries.getAllGalleryWatch(function callback)`
removeAllGalleryWatch − `chrome.mediaGalleries.removeAllGalleryWatch()`
Events
onGalleryChanged
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

dropPermissionForMediaFileSystem


              chrome.mediaGalleries.dropPermissionForMediaFileSystem(string galleryId, function callback)

Deprecated since Chrome 51. The user can manually drop access to galleries via the permissions dialog.

Give up access to a given media gallery.

Parameters
string	galleryId
function	(optional) callback	If you specify the callback parameter, it should be a function that looks like this: `function() {...};`

startMediaScan


              chrome.mediaGalleries.startMediaScan()

Deprecated since Chrome 51. The mediaGalleries API no longer supports scanning.

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()

Deprecated since Chrome 51. The mediaGalleries API no longer supports scanning.

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)

Deprecated since Chrome 51. The mediaGalleries API no longer supports scanning.

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)

Deprecated since Chrome 51. Use getMediaFileSystemMetadata instead.

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)

Since Chrome 38.

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

Since Chrome 35.

object

(optional) options

Since Chrome 35.

enum of "all", "mimeTypeAndTags", or "mimeTypeOnly"

(optional) metadataType

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

all: Retrieve the mime type, metadata tags, and attached images.

mimeTypeAndTags: Retrieve only the mime type and the metadata tags.

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 video. In pixels.

integer

(optional) width

double

(optional) duration

Defined for audio and video. In seconds.

integer

(optional) rotation

Defined for video. In degrees.

string

(optional) album

Defined for audio and video.

string

(optional) artist

string

(optional) comment

string

(optional) copyright

integer

(optional) disc

string

(optional) genre

string

(optional) language

string

(optional) title

integer

(optional) track

array of object

rawTags

All the metadata in the media file. For formats with multiple streams, stream order will be preserved. Container metadata is the first element.

Properties of each object

string	type	Describes format of container or codec of stream, i.e. "mp3", "h264".
object	tags	An unfiltered string->string dictionary of tags for the stream.

array of Blob

attachedImages

The images embedded in the media file's metadata. This is most often used for album art or video thumbnails.

Properties of each object

addGalleryWatch


              chrome.mediaGalleries.addGalleryWatch(string galleryId, function callback)

Since Chrome 39.

Adds a gallery watch for the gallery with the specified gallery ID. The given callback is then fired with a success or failure result.

Parameters

string galleryId

function

callback

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

function(object result) {...};

object

result

string	galleryId
boolean	success

removeGalleryWatch


              chrome.mediaGalleries.removeGalleryWatch(string galleryId)

Since Chrome 39.

Removes a gallery watch for the gallery with the specified gallery ID.

Parameters
string	galleryId

getAllGalleryWatch


              chrome.mediaGalleries.getAllGalleryWatch(function callback)

Deprecated since Chrome 51. Applications should store their own gallery watches as they are added.

Notifies which galleries are being watched via the given callback.

Parameters

function

callback

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

function(array of string galleryIds) {...};

array of string

galleryIds

removeAllGalleryWatch


              chrome.mediaGalleries.removeAllGalleryWatch()

Deprecated since Chrome 51. Use removeGalleryWatch instead.

Removes all gallery watches.

Events

onGalleryChanged

Since Chrome 38.

Fired when a media gallery is changed or a gallery watch is dropped.

addListener


                    chrome.mediaGalleries.onGalleryChanged.addListener(function callback)

Parameters

function

callback

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

function(object details) {...};

object

details

enum of "contents_changed", or "watch_dropped"

type

Type of change event.

contents_changed: The contents of the gallery have changed.

watch_dropped: The watch has been dropped because the device has been detached, the gallery permission has been removed, or any other reason.

string

galleryId

Identifies the modified gallery.

onScanProgress

Deprecated since Chrome 51. The mediaGalleries API no longer supports scanning.

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