Home | History | Annotate | Download | only in intros 
      1 <h2 id="usage">Usage</h2>
      2 
      3 <p>The mediaGalleries API lets you prompt the user for permission to access
      4 media galleries on the user's computer. The permission dialog contains common
      5 media locations for the platform and allows the user to specify additional
      6 locations. From those locations, only media files will be present in the file
      7 system objects.</p>
      8 
      9 <h2 id="manifest">Manifest</h2>
     10 
     11 <p>The media galleries API has two axes of permission parameters:</p>
     12 
     13 <ul>
     14   <li>the locations that can be accessed</li>
     15   <li>the type of access</li>
     16 </ul>
     17 
     18 <p>These two axes and the permission parameters on each axis are described
     19 in the table below:</p>
     20 
     21 <table>
     22     <tr>
     23       <th>Axis</th>
     24       <th>Parameter</th>
     25       <th>Effect</th>
     26     </tr>
     27     <tr>
     28       <td rowspan="2">Locations</td>
     29       <td>none</td>
     30       <td>
     31         If you do not specify a location permission parameter, your app will
     32         not be able to access any media galleries until the user grants
     33         permission to access specific media galleries at runtime using the
     34         media gallery permission dialog.
     35       </td>
     36     </tr>
     37     <tr>
     38       <td>"allAutoDetected"</td>
     39       <td>
     40         Grants your app access to all auto-detected media galleries on the
     41         user's computer. This permission causes an install-time prompt to be
     42         displayed indicating that the app will have access to the user's media
     43         files.
     44       </td>
     45     </tr>
     46     <tr>
     47       <td rowspan="3">Access&nbsp;type</td>
     48       <td>"read"</td>
     49       <td>Grants your app the right to read files in media galleries.</td>
     50     </tr>
     51     <tr>
     52       <td>"delete"</td>
     53       <td>
     54         Grants your app the right to delete files from media galleries.
     55         "read" permission is a prerequisite for "delete". Specify both "read"
     56         and "delete" to obtain both types of permissions to media galleries.
     57       </td>
     58     </tr>
     59     <tr>
     60       <td>"copyTo"</td>
     61       <td>
     62         Grants your app the right to copy files into media galleries.
     63         Only valid media files that Chrome is capable of playing or displaying
     64         are permitted; files that Chrome is not able to validate will result
     65         in a security error. "read" and "delete" permissions are prerequisites
     66         for "copyTo". Specify "read", "delete" and "copyTo" to obtain all three
     67         types of permissions to media galleries.
     68       </td>
     69     </tr>
     70 </table>
     71 
     72 <p>Notes:</p>
     73 <ul>
     74   <li>The media gallery permission dialog can be triggered programmatically.
     75   The user may have alternate media locations, so even if you specify
     76   "allAutoDetected" permsission, it is still important to provide a mechanism
     77   to open the permission dialog in your app.</li>
     78 
     79   <li>There is no write access to media galleries due to the
     80   file validation requirement. However, you can write files to
     81   a different file system like the temporary file system, and then copy
     82   the files into the desired media gallery.</li>
     83 
     84   <li>Access type permissions do not trigger an install-time prompt
     85   by themselves. However, the type of access will be reflected in the
     86   media gallery permission dialog, as well as the install-time prompt if
     87   "allAutoDetected" permission is requested.</li>
     88 </ul>
     89 
     90 <p>Below is an example of a manifest file with mediaGalleries permissions:</p>
     91 
     92 <pre data-filename="manifest.json">
     93 {
     94   "name": "My app",
     95   ...
     96   "permissions": [
     97     <b>{ "mediaGalleries": ["read", "allAutoDetected"] }</b>
     98   ],
     99   ...
    100 }
    101 </pre>
    102 
    103 <p>This example manifest file will trigger an install-time permission prompt,
    104 and let the app read from all auto-detected media galleries on the
    105 user's computer. The user may add or remove galleries using the
    106 media gallery permission dialog, after which the app will be able
    107 to read all the media files from galleries that the user selected.</p>
    108 
    109 <h2 id="iTunes">iTunes</h2>
    110 
    111 <p>If present, the user's iTunes library can be accessed as a media gallery.
    112 In addition to the media files in the library, the "iTunes Music Library.xml"
    113 file is also presented. Regardless of where the music files are actually on the
    114 disk (and where the xml file says they are), they are mapping into an
    115 Artist/Album/Track hierarchy like iTunes does by default.  This mapping doesn't
    116 always work perfectly, so there are two things to note for Apps trying to match
    117 the xml file with files in the gallery. If the filenames for tracks within an
    118 album are not unique, they will be uniquified by adding the track id in
    119 parentheses before the extension, and if there is a colon or a slash in the
    120 artist, album, or track name, they are turned into underscore characters.</p>
    121 
    122 <h2 id="Picasa">Picasa</h2>
    123 
    124 <p>If present, the user's Picasa library can also be accessed as a media
    125 gallery. Directories on the filesystem scanned by Picasa are presented under
    126 folders/. Picasa Albums are presented under albums/. Albums and Folders that
    127 have duplicate names and dates will be uniquified using an incrementing
    128 integer in parenthesis before the extension. Duplicate filenames within the
    129 same Album will also be uniquified using an incrementing integer in parenthesis
    130 before the extension.</p>
    131