GoogleUnlimited

Automated, cross-platform media synchronization utility for Google Photos.
Runs as a lightweight native background watcher on Windows, macOS, and Linux to automatically sync photos and videos using Google Pixel device emulation powered by xob0t/gotohp — without virtual machines, Android emulators, Windows Subsystem for Android (WSA), or WSL.

• Overview
• Features
• Requirements
• Quick Start
  • Windows
  • macOS
  • Linux
• Authentication and Account Setup
• Commands Reference
• Folder Monitoring & Supported Media
  • Monitored Folders
  • Custom Watch Folders (watch_dirs.txt)
  • Supported Media Formats
  • File Readiness & Lock Detection
• Background Operation
  • Windows (VBScript & Startup Folder)
  • macOS (launchd LaunchAgent)
  • Linux (systemd User Service)
  • Single-Instance Protection
• Data Storage, Privacy, and Security
• Troubleshooting
• Limitations and Disclaimer
• Credits and License

GoogleUnlimited monitors local folders on your computer and automatically synchronizes eligible photos and videos to your Google Photos library. It pairs native operating system event watchers (PowerShell on Windows, fswatch on macOS, and inotify-tools on Linux) with an embedded SQLite database (gphotos.db) and the standalone gotohp CLI binary.

The upload engine communicates directly with Google's mobile upload endpoints using Google Pixel device emulation. Because the requests present as a Pixel device, media backed up through this mechanism is processed according to Google Photos Pixel backup rules.

• Real-Time Filesystem Monitoring:
  • Windows: Uses .NET FileSystemWatcher with an expanded 64 KB event buffer and a 1.5-second debounce window to prevent redundant uploads on burst writes.
  • macOS: Uses fswatch for continuous low-latency filesystem event streaming.
  • Linux: Uses inotifywait (inotify-tools) listening to close_write, moved_to, and create kernel events.
• Initial Sync & Periodic Safety Sweeps:
  • Traverses all monitored directories at startup (Phase 1) to upload any existing unrecorded media.
  • Runs periodic background safety sweeps (every 30 seconds on Windows, every 15 minutes on macOS/Linux) to detect offline camera imports or files added while the watcher was paused.
• Cross-Platform Content-Hash Deduplication:
  • Tracks all uploaded files in a local SQLite database (gphotos.db) using WAL mode.
  • Lookups use both file paths and a combined filename|filesize key paired with a SHA-256 content_hash. This prevents duplicate re-uploads on dual-boot machines or shared external drives where paths differ between operating systems.
• Active Download & Lock Detection:
  • Verifies file size stability across multiple sampling checks and tests for exclusive write access before uploading. This prevents uploading partial files during active web downloads, screen recordings (OBS, Xbox Game Bar), or video rendering exports.
• Automatic Retry Queue:
  • Upload failures are stored in a persistent retry_queue table and automatically retried every 30 seconds for up to 3 attempts before logging a permanent failure.
• Background Startup Automation:
  • Windows: One-click startup shortcut creation via VBScript (StartPhotosWatcher.vbs) for invisible, zero-console background execution.
  • macOS: Native user launchd LaunchAgent service management.
  • Linux: Native systemd user service with lingering session support (loginctl enable-linger).
• Single-Instance Protection:
  • On Windows, a named system mutex (Local\GoogleUnlimited_Watcher_<path>) prevents multiple concurrent watcher instances from running against the same installation directory.
  • On Unix, dedicated PID tracking (.watcher.pid) and process inspection prevent conflicting background processes.
• Security & Privacy Hardening:
  • Credentials (gotohp.config) and database files are restricted to owner-only permissions (chmod 600 on Unix).
  • OAuth tokens can be entered interactively with hidden console echo, preventing exposure in shell history or process tables.
  • Official release binaries are checked against trusted SHA-256 checksums during setup.
  • Direct connection to Google endpoints (photoslibrary.googleapis.com); zero telemetry and no intermediate servers.

• gotohp-cli-x64.exe: 64-bit Windows command-line upload engine (gotohp v0.11.0).
• gotohp-x64.exe: Windows desktop GUI helper for Google OAuth sign-in.
• gotohp-cli_amd64: Native Linux x86_64 binary.
• macOS Universal and Linux ARM64 binaries are downloaded automatically from official releases and verified with SHA-256 during ./google-unlimited.sh setup.

1. Clone the repository:

   git clone https://github.com/shishir0x/GoogleUnlimited.git
   cd GoogleUnlimited

2. Sign in to Google Photos:
   • Double-click gotohp-x64.exe.
   • Click Add Google account → Open Google sign-in → sign in → click I agree.
   • Press F12 in your browser → Application tab (or Storage in Firefox) → Cookies (https://accounts.google.com) → copy the oauth_token value.
   • Paste the token into gotohp and click Connect account, then close the window.
3. Start syncing:
   • Double-click GoogleUnlimited.bat and select [1] Start Live Watcher, or run:

     GoogleUnlimited.bat watch

1. Clone the repository:

   git clone https://github.com/shishir0x/GoogleUnlimited.git
   cd GoogleUnlimited

2. Run the setup script:

   chmod +x google-unlimited.sh
   ./google-unlimited.sh setup

   (Installs fswatch, sqlite3, downloads the universal binary, and verifies SHA-256 integrity).
3. Sign in to Google Photos:
   • Open https://accounts.google.com/embedded/setup/v2/android in your browser.
   • Sign in and click I agree (it is normal for the page to remain loading).
   • Press Option + Command + I → Application tab → Cookies → copy the oauth_token cookie value.
   • Run:

     ./google-unlimited.sh creds add

     Paste your token when prompted (input is hidden for security).
4. Start syncing:

   ./google-unlimited.sh watch

1. Clone the repository:

   git clone https://github.com/shishir0x/GoogleUnlimited.git
   cd GoogleUnlimited

2. Run the setup script:

   chmod +x google-unlimited.sh
   ./google-unlimited.sh setup

   (Installs inotify-tools, sqlite3, and curl using your system package manager).
3. Sign in to Google Photos:
   • Open https://accounts.google.com/embedded/setup/v2/android in your browser.
   • Sign in and click I agree (page buffering indefinitely is expected).
   • Press F12 → Application or Storage tab → Cookies → copy the oauth_token value.
   • Run:

     ./google-unlimited.sh creds add

     Paste the token into the hidden prompt. Alternatively, pipe the token:

     echo "<oauth_token>" | ./google-unlimited.sh creds add -

4. Start syncing:

   ./google-unlimited.sh watch

GoogleUnlimited uses Google's Embedded Setup workflow to authenticate as an Android Google Photos client. This enables the mobile upload endpoint required for Google Pixel emulation.

When you log in through https://accounts.google.com/embedded/setup/v2/android and click I agree, Google expects a physical Android device to acknowledge the connection. In a web browser, the page will buffer or spin indefinitely. This is completely normal and expected. The authentication cookie has already been issued.

1. Open Developer Tools (F12, or right-click → Inspect).
2. Open the cookie storage inspector:
   • Chrome, Edge, Brave, Opera: Application tab → Storage → Cookies → https://accounts.google.com.
   • Firefox: Storage tab → Cookies → https://accounts.google.com.
   • Safari: Storage tab → Cookies → accounts.google.com.
3. Locate the cookie named oauth_token and copy its entire string value.

• Credentials are saved locally to gotohp.config in the root repository directory.
• gotohp.config is excluded by .gitignore and must never be committed to version control.
• On macOS and Linux, the script automatically applies chmod 600 so only your user account can read or write the file.
• When entering tokens via ./google-unlimited.sh creds add, terminal echo is disabled to prevent the token from appearing in terminal history, process listings (ps), or shoulder surfing.

# List all configured accounts (the active account is marked with an asterisk *)
./google-unlimited.sh creds list

# Switch the active upload account
./google-unlimited.sh creds set user@gmail.com

# Remove a configured account
./google-unlimited.sh creds remove user@gmail.com

On Windows, you can also manage accounts via GoogleUnlimited.bat account or by selecting option [9] from the menu.

Running GoogleUnlimited.bat without arguments opens the interactive management menu:

==========================================================
  *  Google Unlimited Photos Auto-Sync (Windows)
==========================================================
  [1] Start Live Watcher (Interactive progress)
  [2] Start Background Watcher (Silent, zero window)
  [3] Check Backup Status
  [4] View Activity Logs
  [5] Enable Auto-Start on Windows Boot
  [6] Disable Auto-Start on Windows Boot
  [7] Stop Background Watcher
  [8] Manage Watched Folders (Add/List custom folders)
  [9] Manage Google Accounts (List/Switch account)
  [10] Force Re-scan & Sync All Media
  [0] Exit
==========================================================

You can also run commands directly from the command prompt or terminal:

Running ./google-unlimited.sh without arguments in an interactive terminal opens the Unix manager menu:

==========================================================
  *  GoogleUnlimited - Unix Manager (Linux/Darwin)
==========================================================
  [1] Start Live Watcher (Foreground)
  [2] Check Backup Status
  [3] View Activity Logs
  [4] Run Setup & Dependency Installer
  [5] Enable Auto-Start on Boot (launchd / systemd)
  [6] Disable Auto-Start on Boot
  [7] Stop Background Watcher
  [8] Verify Binary Integrity
  [0] Exit
==========================================================

You can execute any command directly from the shell:

• Windows: The watcher automatically monitors standard photo and download directories:
  • Pictures (user Pictures folder)
  • Downloads (resolved via registry or %USERPROFILE%\Downloads)
  • Cloud folders if they exist on the filesystem:
    • OneDrive: %USERPROFILE%\OneDrive\Pictures, %USERPROFILE%\OneDrive\Pictures\Camera Roll
    • iCloud: %USERPROFILE%\Pictures\iCloud Photos\Photos
    • Google Drive: %USERPROFILE%\Google Drive\Google Photos, %USERPROFILE%\Google Photos (Note: Other Windows folders like Desktop, Videos, Documents, and Music can be added easily using GoogleUnlimited.bat dirs).
• macOS & Linux: Automatically detects and monitors existing directories among:
  • $HOME/Pictures
  • $HOME/Downloads
  • $HOME/Google Photos
  • $HOME/OneDrive/Pictures
  • $HOME/Pictures/iCloud Photos/Photos (If none exist, $HOME/Pictures is created and watched).

When a watch_dirs.txt file exists in the repository root, the watcher switches to custom mode and monitors only the directories specified in that file (plus any directories passed via command-line arguments).

1. Create or edit watch_dirs.txt in the repository root (or use GoogleUnlimited.bat dirs on Windows).
2. Add one absolute path per line. Lines starting with # are ignored as comments. Environment variables are automatically expanded:

   # Standard media directories
   %USERPROFILE%\Pictures
   %USERPROFILE%\Downloads
   
   # External drives or SD cards
   D:\Camera_Imports
   E:\Sony_A7_Media
   
   # macOS / Linux paths
   # /Volumes/ExternalSSD/Photos
   # /home/username/Media
   

3. You can also specify directories ad-hoc when launching:

   GoogleUnlimited.bat watch "D:\Photos" "E:\Videos"

   ./google-unlimited.sh watch /Volumes/ExternalSSD/Photos /Volumes/ExternalSSD/Videos

Files are checked against a verified whitelist of extensions (case-insensitive) and must be at least 10 KB in size:

• Standard Photos & Images (14):
  .jpg, .jpeg, .png, .heic, .heif, .webp, .gif, .bmp, .tiff, .tif, .svg, .ico, .jfif, .avif
• Camera RAW Formats (11):
  .dng, .raw, .cr2, .cr3 (Canon), .nef (Nikon), .arw (Sony), .orf (Olympus), .rw2 (Panasonic), .pef (Pentax), .srw (Samsung), .raf (Fujifilm)
• Videos (16):
  .mp4, .mov (Apple QuickTime/iPhone), .mkv, .avi, .m4v, .3gp, .3g2, .wmv, .webm, .mpg, .mpeg, .mts, .m2ts, .ts, .flv, .vob

Files with temporary or partial extensions (such as .tmp, .crdownload, .part, .db, .config) and files inside Modules/ are strictly excluded.

To prevent corrupt or partial uploads:

1. When a new media file is detected, the watcher checks whether the file is still growing or being written by another application (e.g., a browser download or video rendering export).
2. The readiness algorithm tests write-exclusivity:
   • Windows: Attempts to open the file stream with exclusive sharing locks.
   • Unix: Uses lsof or fuser to verify no other process holds an open write handle.
3. If a file remains locked or is actively growing, it is queued and reassessed every few seconds until the file is complete.

• Silent Launch: Run GoogleUnlimited.bat silent or option [2]. This invokes StartPhotosWatcher.vbs, which launches WatchAndUpload.ps1 with -WindowStyle Hidden via the Windows Script Host (wscript.exe), creating no visible console window.
• Auto-Start on Boot: Run GoogleUnlimited.bat enable or option [5]. This creates a Windows shortcut named GoogleUnlimited.lnk in your user Startup directory:

  %APPDATA%\Microsoft\Windows\Start Menu\Programs\Startup\GoogleUnlimited.lnk
  

  The shortcut points to StartPhotosWatcher.vbs in your repository folder.
• Disable Auto-Start: Run GoogleUnlimited.bat disable or option [6] to delete the shortcut.
• Stop Background Process: Run GoogleUnlimited.bat stop or option [7]. This terminates any active PowerShell processes running WatchAndUpload.ps1 or StartPhotosWatcher.vbs.

• Auto-Start on Login: Run ./google-unlimited.sh enable or option [5].
  • Verifies that valid Google credentials exist.
  • Generates a user LaunchAgent property list at:

    ~/Library/LaunchAgents/com.googleunlimited.watcher.plist
    

  • Loads the service using launchctl load -w. The watcher will start automatically when you log in to macOS and restart if it unexpectedly exits.
• Disable Auto-Start: Run ./google-unlimited.sh disable or option [6]. This unloads the service with launchctl unload -w and removes the .plist file.
• Stop Running Watcher: Run ./google-unlimited.sh stop or option [7]. Stops the LaunchAgent, signals the running PID recorded in .watcher.pid, and stops active fswatch processes.

• Auto-Start on Boot: Run ./google-unlimited.sh enable or option [5].
  • Verifies that valid Google credentials exist.
  • Generates a systemd user service unit at:

    ~/.config/systemd/user/google-unlimited.service
    

  • Executes systemctl --user daemon-reload, enables, and starts the service.
  • Enables lingering sessions using loginctl enable-linger (if available), allowing the background sync service to run even before graphical login.
• Check systemd Service Status:

  systemctl --user status google-unlimited.service

• Disable Auto-Start: Run ./google-unlimited.sh disable or option [6]. Stops and disables the service and removes the unit file.
• Stop Running Watcher: Run ./google-unlimited.sh stop or option [7]. Stops the systemd service, terminates the PID in .watcher.pid, and stops any background inotifywait instances.

• Windows: WatchAndUpload.ps1 uses a named Windows Mutex (Local\GoogleUnlimited_Watcher_<cleanBase>). If an existing watcher instance is already running for the current directory, subsequent invocations exit immediately with code 0. Both GoogleUnlimited.bat silent and StartPhotosWatcher.vbs execute a -CheckRunning validation to ensure duplicate processes are never spawned.
• macOS & Linux: The watcher script writes its active process ID to .watcher.pid. The stop command inspects .watcher.pid and checks process listings (pgrep) to cleanly terminate active watchers and listeners without affecting other system tasks.

All synchronization history is tracked locally in SQLite using WAL (Write-Ahead Logging) mode:

-- Tracks uploaded media files
CREATE TABLE uploads (
    path         TEXT PRIMARY KEY,
    media_key    TEXT,
    uploaded_at  TEXT NOT NULL DEFAULT (datetime('now','localtime')),
    file_name    TEXT,
    file_size    INTEGER,
    content_hash TEXT
);

-- Tracks files pending retry
CREATE TABLE retry_queue (
    path         TEXT PRIMARY KEY,
    attempts     INTEGER NOT NULL DEFAULT 0,
    last_attempt TEXT
);

-- Operational activity logs (auto-purged after 30 days)
CREATE TABLE logs (
    id        INTEGER PRIMARY KEY AUTOINCREMENT,
    timestamp TEXT NOT NULL DEFAULT (datetime('now','localtime')),
    level     TEXT NOT NULL,
    message   TEXT NOT NULL
);

• Direct Connection Only: Uploads and authentication communicate directly from your computer to official Google APIs (accounts.google.com and photoslibrary.googleapis.com). There are no third-party telemetry, metrics, or relay servers.
• Local Credentials: OAuth tokens and Android client parameters are stored strictly in gotohp.config.
• Git Protection: The repository's .gitignore protects sensitive data:

  *.db
  *.db-wal
  *.db-shm
  gphotos.db
  watch_dirs.txt
  gotohp.config
  *.config
  *.token
  *.log

  Personal database records, credentials, and local watch folder lists are never committed to git.

• Cause: No credentials exist in gotohp.config, or no account is marked as active.
• Resolution:
  • Windows: Run GoogleUnlimited.bat account → Option [2] to open gotohp-x64.exe, sign in, and connect.
  • macOS / Linux: Retrieve your oauth_token cookie via browser DevTools, then run:

    ./google-unlimited.sh creds add

  • Verify that an account with an asterisk (*) is displayed:

    ./google-unlimited.sh creds list

• Cause: A background watcher instance is already running and owns the system mutex.
• Resolution:
  • Run GoogleUnlimited.bat status to check if the background watcher is active.
  • To stop it, run GoogleUnlimited.bat stop (or select option [7]).

• Cause: A media file was detected while a download, export, or screen recording was in progress.
• Resolution: No manual intervention is needed. GoogleUnlimited automatically holds locked or growing files in the retry queue and processes them once the writing process closes the file.

• Cause: macOS applies a quarantine flag (com.apple.quarantine) to downloaded binaries.
• Resolution:
  • Run ./google-unlimited.sh setup to automatically strip quarantine flags and set execution permissions (chmod 700).
  • Ensure your terminal has Full Disk Access permissions in macOS System Settings → Privacy & Security if monitoring external drives or protected folders like Downloads.

• Cause: Default Windows PowerShell configuration may restrict unsigned script execution.
• Resolution: GoogleUnlimited.bat automatically passes -ExecutionPolicy Bypass. If running WatchAndUpload.ps1 directly, run:

  powershell.exe -ExecutionPolicy Bypass -File .\WatchAndUpload.ps1

• To inspect recent sync errors or warnings:
  • Windows: GoogleUnlimited.bat logs (or menu option [4]).
  • macOS / Linux: ./google-unlimited.sh logs (or menu option [3]).
• Note: Do not delete gphotos.db to troubleshoot minor issues. Deleting gphotos.db resets your local upload history and will cause GoogleUnlimited to re-evaluate and re-upload all existing media.

• Unofficial Utility: GoogleUnlimited is an independent open-source utility and is not affiliated with, maintained, sponsored, or endorsed by Google LLC or Alphabet Inc.
• Service & Policy Changes: The project relies on Google Photos mobile endpoints and device spoofing implemented in gotohp. Google may modify its APIs, authentication mechanisms, device eligibility criteria, or storage policies at any time. No guarantee of permanent, uninterrupted service or indefinite zero-quota storage can be made.
• Cloud Placeholders: Files stored only as cloud placeholders (e.g., OneDrive "Files On-Demand" or iCloud "Optimize Storage" files that have not been downloaded to local disk) cannot be read by the watcher until they are downloaded locally.
• Removable Media: External drives and SD cards added to watch_dirs.txt are monitored while mounted. If an external drive is disconnected, monitoring will resume once reconnected and rescanned.
• Independent Backups: Users are strongly advised to keep independent, permanent backups of their important photos and personal media.

• Google Photos Engine: Powered by xob0t/gotohp by xob0t (licensed under the GNU General Public License v3.0).
• Windows SQLite Engine: Powered by PSSQLite by RamblingCookieMonster (licensed under the Apache License 2.0).
• Issues & Contributions: Report bugs, suggest enhancements, or submit pull requests on GitHub:
  👉 GoogleUnlimited Issue Tracker