DOCSEARCHbyAlgolia
Submit Docs

gphotosdl

repository·master·Indexed 41 days ago

https://github.com/rclone/gphotosdl

A proxy tool for rclone that enables downloading original-resolution Google Photos images and videos with full EXIF data. It bypasses standard Google Photos API limitations by simulating a browser session via a headless browser and HTTP server, requiring rclone v1.69 or later.

Tokens
1.4K
Snippets
6
Records
8
Agent score
50%

What's inside gphotosdl

  1. Debug gphotosdl proxy

    master

    If you encounter issues with the proxy, use the following flags to gather more information:

    • -debug: Provides detailed debug information in the terminal.
    • -show: Forces the browser used by the proxy to be visible (instead of headless), which is essential for troubleshooting browser-level issues.
    gphotosdl -debug -show

  2. Set up gphotosdl to download original resolution Google Photos

    master

    The standard Google Photos API often delivers lower-resolution images or missing EXIF data. gphotosdl acts as a proxy that runs a headless browser and an HTTP server, allowing rclone to access the Google Photos website directly to fetch original, unchanged images.

    Prerequisites

    • rclone: Version v1.69 or later must be installed and configured with Google Photos.
    • gphotosdl binary: Download the latest version from the releases page.

    Setup Steps

    1. Authenticate: Run the login command to open a browser window. Log in to your Google Photos account, then close the browser window once complete.
      gphotosdl -login
    2. Start the Proxy: Run the proxy server in the background.
      gphotosdl
    3. Run rclone with the Proxy: Use the --gphotos-proxy flag in your rclone command to route requests through the gphotosdl server (defaulting to http://localhost:8282).
    rclone copy -vvP --gphotos-proxy "http://localhost:8282" "gPhotos:media/by-month/2024/2024-09/" "/tmp/high-res-media/"

  3. How to authenticate with Google Photos

    master

    Because gphotosdl uses a browser instance to interact with Google Photos, you must authenticate via a browser session.

    1. Run the command with the -login flag: gphotosdl -login.
    2. A browser window will open to the Google login page. Perform your login manually.
    3. Close the browser window once login is complete.
    4. Re-run the command without the -login flag. The application will now use the stored browser profile to access your photos.
    gphotosdl -login

  4. Troubleshoot browser launch errors

    master

    If you receive the error browser launch: [launcher] Failed to get the debug url: Opening in existing browser session., it means you cannot run more than one proxy instance at once.

    To resolve this:

    1. Check if another gphotosdl process is already running.
    2. If no process is visible, look for and kill any orphan browser processes that may be holding the session.

  5. Reference gphotosdl CLI flags

    master

    The following flags are available for the gphotosdl binary:

    • -login: Opens a browser window for Google Photos authentication.
    • -debug: Enables debug logging.
    • -show: Displays the browser being used by the proxy.

  6. Gphotos Type and Download Method

    master

    The Gphotos type manages a browser instance and a web server to facilitate photo downloads.

    New() (*Gphotos, error)

    Initializes a new Gphotos instance, starts the browser, and starts the web server. It checks if the user is already authenticated by navigating to the Google Photos URL.

    Download(photoID string) (string, error)

    Downloads a specific photo using its ID.

    • Mechanism: It opens a new browser tab, navigates to the photo URL (https://photos.google.com/lr/photo/{photoID}), waits for the network response, and simulates a Shift+D keypress to trigger the high-resolution download.
    • Concurrency: Only one download can occur at a time due to internal locking.
    • Returns: The local file path to the downloaded photo. This file is intended to be temporary and should be deleted after use.
    // Example of calling the Download method
path, err := g.Download("YOUR_PHOTO_ID")
if err != nil {
    log.Fatal(err)
}
// Use path, then delete it

  7. Web Server API Reference

    master

    When running, gphotosdl starts a web server at the address specified by -addr (default localhost:8282). This server is designed to be used by tools like rclone to fetch photos via HTTP.

    GET /

    Returns a simple HTML landing page describing the tool.

    GET /id/{photoID}

    Fetches a photo by its ID.

    • Behavior: This endpoint triggers the Download method. Once the file is downloaded to the local temporary directory, the server streams the file to the requester and then deletes the local copy.
    • Usage: This is the primary endpoint used for integration with rclone to download full-resolution images.
    GET /id/{photoID}

Example URL: http://localhost:8282/id/AF1QipNJVLe7d5mOh-b4CzFAob1UW-6EpFd0HnCBT3c6

  8. CLI Flags for gphotosdl

    master

    The gphotosdl CLI provides several flags to control its behavior, including authentication, visibility, and logging:

    • -debug: Enables debug-level logging messages.
    • -login: Launches a standalone browser window for Google login. After logging in and closing the browser, you must re-run the command without this flag.
    • -show: Runs the browser in non-headless mode (visible) instead of the default headless mode.
    • -addr: Sets the address for the local web server (default: localhost:8282).
    • -json: Configures the logger to output in JSON format.
    gphotosdl -login
gphotosdl -debug -show
gphotosdl -addr "0.0.0.0:9000" -json