github.com/xhghs/rclone@v1.51.1-0.20200430155106-e186a28cced8/docs/content/googlephotos.md

github.com/xhghs/rclone@v1.51.1-0.20200430155106-e186a28cced8/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-images"></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 XX / 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 **The current google API does not allow photos to be downloaded at original resolution. This is very important if you are, for example, relying on "Google Photos" as a backup of your photos. You will not be able to use rclone to redownload original images. You could use 'google takeout' to recover the original photos as a last resort**
241
242 ### Downloading Videos
243
244 When videos are downloaded they are downloaded in a really compressed
245 version of the video compared to downloading it via the Google Photos
246 web interface. This is covered by [bug #113672044](https://issuetracker.google.com/issues/113672044).
247
248 ### Duplicates
249
250 If a file name is duplicated in a directory then rclone will add the
251 file ID into its name. So two files called `file.jpg` would then
252 appear as `file {123456}.jpg` and `file {ABCDEF}.jpg` (the actual IDs
253 are a lot longer alas!).
254
255 If you upload the same image (with the same binary data) twice then
256 Google Photos will deduplicate it. However it will retain the
257 filename from the first upload which may confuse rclone. For example
258 if you uploaded an image to `upload` then uploaded the same image to
259 `album/my_album` the filename of the image in `album/my_album` will be
260 what it was uploaded with initially, not what you uploaded it with to
261 `album`. In practise this shouldn't cause too many problems.
262
263 ### Modified time
264
265 The date shown of media in Google Photos is the creation date as
266 determined by the EXIF information, or the upload date if that is not
267 known.
268
269 This is not changeable by rclone and is not the modification date of
270 the media on local disk. This means that rclone cannot use the dates
271 from Google Photos for syncing purposes.
272
273 ### Size
274
275 The Google Photos API does not return the size of media. This means
276 that when syncing to Google Photos, rclone can only do a file
277 existence check.
278
279 It is possible to read the size of the media, but this needs an extra
280 HTTP HEAD request per media item so is **very slow** and uses up a lot of
281 transactions. This can be enabled with the `--gphotos-read-size`
282 option or the `read_size = true` config parameter.
283
284 If you want to use the backend with `rclone mount` you may need to
285 enable this flag (depending on your OS and application using the
286 photos) otherwise you may not be able to read media off the mount.
287 You'll need to experiment to see if it works for you without the flag.
288
289 ### Albums
290
291 Rclone can only upload files to albums it created. This is a
292 [limitation of the Google Photos API](https://developers.google.com/photos/library/guides/manage-albums).
293
294 Rclone can remove files it uploaded from albums it created only.
295
296 ### Deleting files
297
298 Rclone can remove files from albums it created, but note that the
299 Google Photos API does not allow media to be deleted permanently so
300 this media will still remain. See [bug #109759781](https://issuetracker.google.com/issues/109759781).
301
302 Rclone cannot delete files anywhere except under `album`.
303
304 ### Deleting albums
305
306 The Google Photos API does not support deleting albums - see [bug #135714733](https://issuetracker.google.com/issues/135714733).
307
308 
309 ### Standard Options
310
311 Here are the standard options specific to google photos (Google Photos).
312
313 #### --gphotos-client-id
314
315 Google Application Client Id
316 Leave blank normally.
317
318 - Config: client_id
319 - Env Var: RCLONE_GPHOTOS_CLIENT_ID
320 - Type: string
321 - Default: ""
322
323 #### --gphotos-client-secret
324
325 Google Application Client Secret
326 Leave blank normally.
327
328 - Config: client_secret
329 - Env Var: RCLONE_GPHOTOS_CLIENT_SECRET
330 - Type: string
331 - Default: ""
332
333 #### --gphotos-read-only
334
335 Set to make the Google Photos backend read only.
336
337 If you choose read only then rclone will only request read only access
338 to your photos, otherwise rclone will request full access.
339
340 - Config: read_only
341 - Env Var: RCLONE_GPHOTOS_READ_ONLY
342 - Type: bool
343 - Default: false
344
345 ### Advanced Options
346
347 Here are the advanced options specific to google photos (Google Photos).
348
349 #### --gphotos-read-size
350
351 Set to read the size of media items.
352
353 Normally rclone does not read the size of media items since this takes
354 another transaction. This isn't necessary for syncing. However
355 rclone mount needs to know the size of files in advance of reading
356 them, so setting this flag when using rclone mount is recommended if
357 you want to read the media.
358
359 - Config: read_size
360 - Env Var: RCLONE_GPHOTOS_READ_SIZE
361 - Type: bool
362 - Default: false
363
364