What is the purpose of this change?

Add new gphotosmobile backend that interfaces with Google Photos using the reverse-engineered mobile API (the same API the Android Google Photos app uses). This bypasses all restrictions of the official REST API — download any photo/video at original quality, upload, trash items, full metadata with SHA1 hashes, and read/write descriptions (captions).

Was the change discussed in an issue or in the forum before?

No

Checklist

• I have read the contribution guidelines.
• I have added tests for all changes in this PR if appropriate.
• I have added documentation for the changes if appropriate.
• All commit messages are in house style.
• I'm done, this Pull Request is ready for review :-)

Summary

• Add new gphotosmobile backend that interfaces with Google Photos using the reverse-engineered mobile API (the same API the Android Google Photos app uses)
• This bypasses all restrictions of the official REST API -- download any photo/video at original quality, upload, trash items, full metadata
• Rich metadata support: read location, camera info, EXIF, timestamps, flags; write description (caption)
• Backend command set-description for standalone caption editing
• Includes full documentation (with autogenerated options via make backenddocs), backend YAML, integration test scaffolding
• Unit tests for protowire encode/decode, parser, float conversions, and helpers
• Extensive in-code protocol documentation for maintainers: API endpoints, auth flow, sync protocol, protobuf field maps, request/response structures

What it does

Architecture

rclone <-> gphotosmobile backend <-> Google Photos Mobile API (protobuf)
                |
                +-> SQLite cache (<cache-dir>/gphotosmobile/<remote>.db)

• Auth: Android device tokens -> bearer tokens via android.googleapis.com/auth
• Library sync: Full initial sync + fast incremental deltas, cached in local SQLite
• Protobuf: Raw wire format encode/decode (no compiled .proto files)
• Downloads: Direct HTTP stream by default; optional temp file download cache for seeking (opt-in via download_cache = true)
• Uploads: SHA1 dedup check -> streaming upload via temp file (no in-memory buffering)
• Metadata: Read rich metadata (location, EXIF, timestamps, flags) from cache; write description via SetCaption API
• Retry: fs.Pacer with pacer.NewGoogleDrive for all API calls; standard shouldRetry(ctx, err) pattern with retryErrorCodes (429, 500, 502, 503, 509)
• Types: api/types.go subpackage with MediaItem and Error types (standard rclone convention used by 25+ backends)
• No lib/rest: Justified — all API calls use raw protobuf over HTTPS, not JSON/XML REST

Metadata support

The backend implements fs.Metadataer and fs.SetMetadataer:

Backend commands

The backend implements fs.Commander with:

• set-description: Set or clear the caption of a media item

  rclone backend set-description remote:media/photo.jpg -o description="Sunset at the beach"
  rclone backend set-description remote:media/photo.jpg -o description=""  # clear
  

Configuration options

Standard options

Advanced options

Files added

Protocol documentation (in-code)

Every source file has a detailed package-level or file-level doc comment explaining the inner workings for maintainers:

• api.go -- Full protocol overview: authentication flow (device tokens to bearer tokens), list of all API endpoints with their numeric path IDs (including SetCaption), transport details (raw protobuf over HTTPS), justification for not using lib/rest
• gphotosmobile.go -- Library sync protocol: initial sync vs incremental sync state machine, state_token/page_token semantics, sync throttling, virtual filesystem layout, duplicate filename handling, metadata field mapping
• parser.go -- Complete protobuf field map for sync responses: every field path for media items (metadata, type info, location, EXIF), deletion entries, and pagination tokens
• request_builders.go -- Request structure: field mask pattern (how the client tells the server which fields to return), top-level request layout shared across the three sync request types, upload commit, trash, and caption request formats
• download_cache.go -- Download cache architecture: why it exists (no HTTP Range support), how shared downloads work, reference counting, known limitations
• protowire_utils.go -- Why raw wire format instead of compiled protos, encoding/decoding approach, relationship to Python's blackboxprotobuf
• cache.go -- SQLite schema, WAL mode, cache location, crash recovery via persisted page_token
• api/types.go -- Key identifier types (media_key vs dedup_key vs SHA1Hash) and their uses

Contributing guide compliance

• Uses fshttp.NewClient(ctx) for HTTP transport (respects --proxy, --timeout, --dump, --tpslimit)
• context.Context propagated to all HTTP requests (supports cancellation)
• fs.Shutdowner implemented -- closes SQLite cache and cleans up temp files
• fs.Commander implemented -- set-description backend command for standalone caption editing
• fs.Pacer with pacer.NewGoogleDrive for all API retry logic (standard rclone pattern)
• shouldRetry(ctx, err) (bool, error) with retryErrorCodes -- matches standard naming used across all backends
• api/types.go subpackage with MediaItem and Error types (matches 25+ other backends)
• All HTTP methods (GetUploadToken, DownloadFile, getAuthToken) wrapped in pacer.Call() with shouldRetry
• All non-2xx HTTP responses return *api.Error for consistent retry logic
• NewObject properly distinguishes "not found" (sql.ErrNoRows) from real database errors, handles dedup-suffixed filenames
• SetModTime returns fs.ErrorCantSetModTime (API does not support modtime changes)
• Precision returns fs.ModTimeNotSupported
• Put populates full metadata from cache after upload
• lib/encoder support for path encoding
• golangci-lint v2 passes with 0 issues
• Backend YAML (docs/data/backends/gphotosmobile.yaml) with correct features and precision
• Doc file with autogenerated options (populated via bin/make_backend_docs.py)
• Added to README.md, docs.md, _index.md, navbar.html, make_manual.py -- all in correct alphabetical order by full name
• Integration test file + fstest/test_all/config.yaml entry
• Unit tests for protowire encode/decode, parser, float conversions, helpers (26 tests)
• Cache stored in rclone's --cache-dir (not custom location)
• Option Help texts follow single-sentence-with-period format
• Package name gphotosmobile (no underscores), matches directory name and FileName() output
• Extensive in-code protocol documentation for maintainability
• Download cache is opt-in (download_cache config option, default false)
• APK version and Android API level are configurable (apk_version, android_api)
• Sentinel errors for non-removable virtual directories (matching googlephotos pattern)
• Download cache background goroutine uses detached context (won't cancel shared downloads)
• fs.Metadataer + fs.SetMetadataer implemented -- rich read metadata, writable description
• MetadataInfo registered with systemMetadataInfo map listing all 19 metadata keys
• ReadMetadata + WriteMetadata feature flags set
• lib/rest not used -- justified (protobuf binary protocol, not JSON REST), documented on MobileAPI struct

Testing done

• rclone about mygphotos: -- quota display works
• rclone ls mygphotos:media/ -- lists all ~35K items
• rclone copy mygphotos:media/video.mp4 /local/ -- downloads at original quality
• rclone copy /local/photo.jpg mygphotos:media/ -- uploads with streaming SHA1 + dedup
• rclone delete mygphotos:media/file.mp4 -- moves to trash
• rclone mount mygphotos: G: --vfs-cache-mode full -- mount works, file browsing and sequential reads work. Seeking requires --gphotosmobile-download-cache=true
• rclone lsjson mygphotos:media/photo.jpg --metadata -- returns all metadata fields
• rclone backend set-description mygphotos: media/photo.jpg -o description="test" -- sets caption
• go test -v -run "Test[^I]" ./backend/gphotosmobile/... -- 26 unit tests pass
• golangci-lint v2 run ./backend/gphotosmobile/... -- 0 issues
• go vet ./backend/gphotosmobile/... -- passes
• Full binary build with -tags cmount -- passes
• bin/make_backend_docs.py gphotosmobile -- autogenerated options populated successfully