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 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.
"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)

Since Chrome 34.

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)

Since Chrome 26.

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 33.

object (optional) options

Since Chrome 33.

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

Since Chrome 34.

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