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

iPhoto

If present, the user's iPhoto library can be accessed as a media gallery. The files are structured within a subdirectory called "Albums/". Within that subdirectory, each album in the user's iPhoto library will appear as a subdirectory by name, and contain file entries for the photos in that album.

Duplicate album names or image filenames within albums will get a disambiguating suffix like "(NN)" where NN is a unique number.

Any items appearing in multiple albums in iPhoto will appear in all those albums in the gallery.

If the user has modified any images within an album, there will be an additional subdirectory called "originals/" within the album directory. It will contain the original image with the same filename as in the parent album subdirectory. The file as it appears in the parrent album directory will be the one the user has invested time cropping, rotating, or otherwise editing.

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

dropPermissionForMediaFileSystem

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

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

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) xResolution Defined for images only.
double (optional) yResolution
double (optional) duration Defined for audio and video. In seconds.
integer (optional) rotation Defined for images and video. In degrees.
string (optional) cameraMake Defined for images only.
string (optional) cameraModel
double (optional) exposureTimeSeconds
boolean (optional) flashFired
double (optional) fNumber
double (optional) focalLengthMm
double (optional) isoEquivalent
string (optional) album Defined for audio and video only.
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.

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