github.com/ncw/rclone@v1.48.1-0.20190724201158-a35aa1360e3e/docs/content/googlephotos.md

github.com/ncw/rclone@v1.48.1-0.20190724201158-a35aa1360e3e/docs/content/googlephotos.md (about)

1 ---
2 title: "Google Photos"
3 description: "Rclone docs for Google Photos"
4 date: "2019-06-25"
5 ---
6
7 <i class="fa fa-photo"></i> Google Photos
8 -------------------------------------------------
9
10 The rclone backend for [Google Photos](https://www.google.com/photos/about/) is
11 a specialized backend for transferring photos and videos to and from
12 Google Photos.
13
14 **NB** The Google Photos API which rclone uses has quite a few
15 limitations, so please read the [limitations section](#limitations)
16 carefully to make sure it is suitable for your use.
17
18 ## Configuring Google Photos
19
20 The initial setup for google cloud storage involves getting a token from Google Photos
21 which you need to do in your browser. `rclone config` walks you
22 through it.
23
24 Here is an example of how to make a remote called `remote`. First run:
25
26 rclone config
27
28 This will guide you through an interactive setup process:
29
30 ```
31 No remotes found - make a new one
32 n) New remote
33 s) Set configuration password
34 q) Quit config
35 n/s/q> n
36 name> remote
37 Type of storage to configure.
38 Enter a string value. Press Enter for the default ("").
39 Choose a number from below, or type in your own value
40 [snip]
41 13 / Google Photos
42 \ "google photos"
43 [snip]
44 Storage> google photos
45 ** See help for google photos backend at: https://rclone.org/googlephotos/ **
46
47 Google Application Client Id
48 Leave blank normally.
49 Enter a string value. Press Enter for the default ("").
50 client_id>
51 Google Application Client Secret
52 Leave blank normally.
53 Enter a string value. Press Enter for the default ("").
54 client_secret>
55 Set to make the Google Photos backend read only.
56
57 If you choose read only then rclone will only request read only access
58 to your photos, otherwise rclone will request full access.
59 Enter a boolean value (true or false). Press Enter for the default ("false").
60 read_only>
61 Edit advanced config? (y/n)
62 y) Yes
63 n) No
64 y/n> n
65 Remote config
66 Use auto config?
67 * Say Y if not sure
68 * Say N if you are working on a remote or headless machine
69 y) Yes
70 n) No
71 y/n> y
72 If your browser doesn't open automatically go to the following link: http://127.0.0.1:53682/auth
73 Log in and authorize rclone for access
74 Waiting for code...
75 Got code
76
77 *** IMPORTANT: All media items uploaded to Google Photos with rclone
78 *** are stored in full resolution at original quality. These uploads
79 *** will count towards storage in your Google Account.
80
81 --------------------
82 [remote]
83 type = google photos
84 token = {"access_token":"XXX","token_type":"Bearer","refresh_token":"XXX","expiry":"2019-06-28T17:38:04.644930156+01:00"}
85 --------------------
86 y) Yes this is OK
87 e) Edit this remote
88 d) Delete this remote
89 y/e/d> y
90 ```
91
92 Note that rclone runs a webserver on your local machine to collect the
93 token as returned from Google if you use auto config mode. This only
94 runs from the moment it opens your browser to the moment you get back
95 the verification code. This is on `http://127.0.0.1:53682/` and this
96 may require you to unblock it temporarily if you are running a host
97 firewall, or use manual mode.
98
99 This remote is called `remote` and can now be used like this
100
101 See all the albums in your photos
102
103 rclone lsd remote:album
104
105 Make a new album
106
107 rclone mkdir remote:album/newAlbum
108
109 List the contents of an album
110
111 rclone ls remote:album/newAlbum
112
113 Sync `/home/local/images` to the Google Photos, removing any excess
114 files in the album.
115
116 rclone sync /home/local/image remote:album/newAlbum
117
118 ## Layout
119
120 As Google Photos is not a general purpose cloud storage system the
121 backend is laid out to help you navigate it.
122
123 The directories under `media` show different ways of categorizing the
124 media. Each file will appear multiple times. So if you want to make
125 a backup of your google photos you might choose to backup
126 `remote:media/by-month`. (**NB** `remote:media/by-day` is rather slow
127 at the moment so avoid for syncing.)
128
129 Note that all your photos and videos will appear somewhere under
130 `media`, but they may not appear under `album` unless you've put them
131 into albums.
132
133 ```
134 /
135 - upload
136 - file1.jpg
137 - file2.jpg
138 - ...
139 - media
140 - all
141 - file1.jpg
142 - file2.jpg
143 - ...
144 - by-year
145 - 2000
146 - file1.jpg
147 - ...
148 - 2001
149 - file2.jpg
150 - ...
151 - ...
152 - by-month
153 - 2000
154 - 2000-01
155 - file1.jpg
156 - ...
157 - 2000-02
158 - file2.jpg
159 - ...
160 - ...
161 - by-day
162 - 2000
163 - 2000-01-01
164 - file1.jpg
165 - ...
166 - 2000-01-02
167 - file2.jpg
168 - ...
169 - ...
170 - album
171 - album name
172 - album name/sub
173 - shared-album
174 - album name
175 - album name/sub
176 ```
177
178 There are two writable parts of the tree, the `upload` directory and
179 sub directories of the the `album` directory.
180
181 The `upload` directory is for uploading files you don't want to put
182 into albums. This will be empty to start with and will contain the
183 files you've uploaded for one rclone session only, becoming empty
184 again when you restart rclone. The use case for this would be if you
185 have a load of files you just want to once off dump into Google
186 Photos. For repeated syncing, uploading to `album` will work better.
187
188 Directories within the `album` directory are also writeable and you
189 may create new directories (albums) under `album`. If you copy files
190 with a directory hierarchy in there then rclone will create albums
191 with the `/` character in them. For example if you do
192
193 rclone copy /path/to/images remote:album/images
194
195 and the images directory contains
196
197 ```
198 images
199 - file1.jpg
200 dir
201 file2.jpg
202 dir2
203 dir3
204 file3.jpg
205 ```
206
207 Then rclone will create the following albums with the following files in
208
209 - images
210 - file1.jpg
211 - images/dir
212 - file2.jpg
213 - images/dir2/dir3
214 - file3.jpg
215
216 This means that you can use the `album` path pretty much like a normal
217 filesystem and it is a good target for repeated syncing.
218
219 The `shared-album` directory shows albums shared with you or by you.
220 This is similar to the Sharing tab in the Google Photos web interface.
221
222 ## Limitations
223
224 Only images and videos can be uploaded. If you attempt to upload non
225 videos or images or formats that Google Photos doesn't understand,
226 rclone will upload the file, then Google Photos will give an error
227 when it is put turned into a media item.
228
229 Note that all media items uploaded to Google Photos through the API
230 are stored in full resolution at "original quality" and **will** count
231 towards your storage quota in your Google Account. The API does
232 **not** offer a way to upload in "high quality" mode..
233
234 ### Downloading Images
235
236 When Images are downloaded this strips EXIF location (according to the
237 docs and my tests). This is a limitation of the Google Photos API and
238 is covered by [bug #112096115](https://issuetracker.google.com/issues/112096115).
239
240 ### Downloading Videos
241
242 When videos are downloaded they are downloaded in a really compressed
243 version of the video compared to downloading it via the Google Photos
244 web interface. This is covered by [bug #113672044](https://issuetracker.google.com/issues/113672044).
245
246 ### Duplicates
247
248 If a file name is duplicated in a directory then rclone will add the
249 file ID into its name. So two files called `file.jpg` would then
250 appear as `file {123456}.jpg` and `file {ABCDEF}.jpg` (the actual IDs
251 are a lot longer alas!).
252
253 If you upload the same image (with the same binary data) twice then
254 Google Photos will deduplicate it. However it will retain the
255 filename from the first upload which may confuse rclone. For example
256 if you uploaded an image to `upload` then uploaded the same image to
257 `album/my_album` the filename of the image in `album/my_album` will be
258 what it was uploaded with initially, not what you uploaded it with to
259 `album`. In practise this shouldn't cause too many problems.
260
261 ### Modified time
262
263 The date shown of media in Google Photos is the creation date as
264 determined by the EXIF information, or the upload date if that is not
265 known.
266
267 This is not changeable by rclone and is not the modification date of
268 the media on local disk. This means that rclone cannot use the dates
269 from Google Photos for syncing purposes.
270
271 ### Size
272
273 The Google Photos API does not return the size of media. This means
274 that when syncing to Google Photos, rclone can only do a file
275 existence check.
276
277 It is possible to read the size of the media, but this needs an extra
278 HTTP HEAD request per media item so is very slow and uses up a lot of
279 transactions. This can be enabled with the `--gphotos-read-size`
280 option or the `read_size = true` config parameter.
281
282 If you want to use the backend with `rclone mount` you will need to
283 enable this flag otherwise you will not be able to read media off the
284 mount.
285
286 ### Albums
287
288 Rclone can only upload files to albums it created. This is a
289 [limitation of the Google Photos API](https://developers.google.com/photos/library/guides/manage-albums).
290
291 Rclone can remove files it uploaded from albums it created only.
292
293 ### Deleting files
294
295 Rclone can remove files from albums it created, but note that the
296 Google Photos API does not allow media to be deleted permanently so
297 this media will still remain. See [bug #109759781](https://issuetracker.google.com/issues/109759781).
298
299 Rclone cannot delete files anywhere except under `album`.
300
301 ### Deleting albums
302
303 The Google Photos API does not support deleting albums - see [bug #135714733](https://issuetracker.google.com/issues/135714733).
304
305 
306 ### Standard Options
307
308 Here are the standard options specific to google photos (Google Photos).
309
310 #### --gphotos-client-id
311
312 Google Application Client Id
313 Leave blank normally.
314
315 - Config: client_id
316 - Env Var: RCLONE_GPHOTOS_CLIENT_ID
317 - Type: string
318 - Default: ""
319
320 #### --gphotos-client-secret
321
322 Google Application Client Secret
323 Leave blank normally.
324
325 - Config: client_secret
326 - Env Var: RCLONE_GPHOTOS_CLIENT_SECRET
327 - Type: string
328 - Default: ""
329
330 #### --gphotos-read-only
331
332 Set to make the Google Photos backend read only.
333
334 If you choose read only then rclone will only request read only access
335 to your photos, otherwise rclone will request full access.
336
337 - Config: read_only
338 - Env Var: RCLONE_GPHOTOS_READ_ONLY
339 - Type: bool
340 - Default: false
341
342 ### Advanced Options
343
344 Here are the advanced options specific to google photos (Google Photos).
345
346 #### --gphotos-read-size
347
348 Set to read the size of media items.
349
350 Normally rclone does not read the size of media items since this takes
351 another transaction. This isn't necessary for syncing. However
352 rclone mount needs to know the size of files in advance of reading
353 them, so setting this flag when using rclone mount is recommended if
354 you want to read the media.
355
356 - Config: read_size
357 - Env Var: RCLONE_GPHOTOS_READ_SIZE
358 - Type: bool
359 - Default: false
360
361