chrome/common/extensions/docs/templates/intros/mediaGalleries.html

<h2 id="usage">Usage</h2>

<p>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.</p>

<h2 id="manifest">Manifest</h2>

<p>The media galleries API has two axes of permission parameters:</p>

<ul>
  <li>the locations that can be accessed</li>
  <li>the type of access</li>
</ul>

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

<table>
    <tr>
      <th>Axis</th>
      <th>Parameter</th>
      <th>Effect</th>
    </tr>
    <tr>
      <td rowspan="2">Locations</td>
      <td>none</td>
      <td>
        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.
      </td>
    </tr>
    <tr>
      <td>"allAutoDetected"</td>
      <td>
        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.
      </td>
    </tr>
    <tr>
      <td rowspan="2">Access&nbsp;type</td>
      <td>"read"</td>
      <td>Grants your app the right to read files in media galleries.</td>
    </tr>
    <tr>
      <td>"copyTo"</td>
      <td>
        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" permission is a prerequisite for "copyTo".
        Specify both "read" and "copyTo" to obtain both types of permissions to
        media galleries.
      </td>
    </tr>
</table>

<p>Notes:</p>
<ul>
  <li>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.</li>

  <li>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.</li>

  <li>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.</li>
</ul>

<p>Below is an example of a manifest file with mediaGalleries permissions:</p>

<pre data-filename="manifest.json">
{
  "name": "My app",
  ...
  "permissions": [
    <b>{ "mediaGalleries": ["read", "allAutoDetected"] }</b>
  ],
  ...
}
</pre>

<p>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.</p>

<h2 id="iTunes">iTunes</h2>

<p>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.</p>