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 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.</p> 114 <p>Regardless of where the music files are actually on the disk (and where 115 the xml file says they are), they are mapped into an Artist/Album/Track 116 hierarchy like iTunes does by default. This mapping doesn't always work 117 perfectly, so there are two things to note for Apps trying to match the 118 xml file with files in the gallery.</p> 119 <p>If the filenames for tracks within an album are not unique, they will be 120 uniquified by adding the track id in parentheses before the extension, and 121 if there is a colon or a slash in the artist, album, or track name, they are 122 turned into underscore characters.</p> 123 124 <h2 id="Picasa">Picasa</h2> 125 126 <p>If present, the user's Picasa library can also be accessed as a media 127 gallery. Directories on the filesystem scanned by Picasa are presented under 128 folders/. Picasa Albums are presented under albums/.</p> 129 <p>Albums and Folders that have duplicate names and dates will be uniquified 130 using an incrementing integer in parenthesis before the extension.</p> 131 <p>Duplicate filenames within the same Album will also be uniquified using an 132 incrementing integer in parenthesis before the extension.</p> 133 134 <h2 id="iPhoto">iPhoto</h2> 135 136 <p>If present, the user's iPhoto library can be accessed as a media gallery. 137 The files are structured within a subdirectory called "Albums/". Within that 138 subdirectory, each album in the user's iPhoto library will appear as a 139 subdirectory by name, and contain file entries for the photos in that album. 140 </p> 141 <p>Duplicate album names or image filenames within albums will get a 142 disambiguating suffix like "(NN)" where NN is a unique number.</p> 143 <p>Any items appearing in multiple albums in iPhoto will appear in all those 144 albums in the gallery.</p> 145 <p>If the user has modified any images within an album, there will be an 146 additional subdirectory called "originals/" within the album directory. 147 It will contain the original image with the same filename as in the parent 148 album subdirectory. The file as it appears in the parrent album directory 149 will be the one the user has invested time cropping, rotating, or 150 otherwise editing.</p> 151 152
