The media galleries API allows you to access media files (images, video, audio) from the user's local disks (with the user's consent).

Using the API, you can prompt the user for permission to access the media galleries. The permission dialog will contain common media locations for the platform and will allow the user to add 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, and the type of access (read-only, read-write, add-files).

On the location axis, specifying no location-type permission parameters means that no media galleries are accessible until the user grants permission to specific media galleries at runtime using the media gallery configuration dialog. This dialog can be programmatically triggered. Alternatively, specifying the "allAutoDetected" permission parameter grants access to all auto-detected media galleries on the user's computer. However, this permission displays an install time prompt indicating that the extension will have access to all of the user's media files.

On the access type axis, the "read" permission parameter grants the extension the right to read files. This permission does not trigger an install time permission prompt because the user must still grant access to particular galleries, either with the "allAutoDetected" permission parameter or at runtime by using the media gallery management dialog. For example:

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

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

Currently "read" is the only access type supported by this API. Read-write and add-file access with be implemented soon.