GoogleUnlimited README

项目的 README,来自 github.com/shishir0x/GoogleUnlimited。合并为一个 markdown 文件:README.md。

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.

GoogleUnlimited Showcase


Table of Contents


Overview

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.


Features


Requirements

Platform Requirements

Platform OS Version / Arch Runtime & Shell Required Dependencies Dependency Installation
Windows Windows 10 / 11 (64-bit) PowerShell 5.1 or PowerShell 7+ (pwsh) PSSQLite module Bundled in Modules/PSSQLite/; auto-installs via PowerShell Gallery if missing
macOS macOS 11 (Big Sur)+
Apple Silicon (M1–M4) & Intel x64
Bash fswatch, sqlite3, curl Auto-installed via Homebrew during ./google-unlimited.sh setup
Linux Modern Linux distributions
x86_64 or aarch64/arm64
Bash inotify-tools, sqlite3, curl Auto-installed via apt, dnf, pacman, or zypper during ./google-unlimited.sh setup

Binaries Included in Repository


Quick Start

Windows Quick Start

  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
      

macOS Quick Start

  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
    

Linux Quick Start

  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
    

Authentication and Account Setup

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.

Why does the setup page buffer indefinitely?

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.

Retrieving the oauth_token

  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.

Credential Storage & Security

Managing Multiple Accounts

# 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 [email protected]

# Remove a configured account
./google-unlimited.sh creds remove [email protected]

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


Commands Reference

Windows (GoogleUnlimited.bat / PowerShell)

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
  [11] Check / Update Application (Keep configs safe)
  [0] Exit
==========================================================

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

Batch Command Underlying PowerShell Flag Menu Option Description
GoogleUnlimited.bat watch [dirs...] .\WatchAndUpload.ps1 [dirs...] [1] Start the live foreground watcher with dynamic progress bars and ETAs.
GoogleUnlimited.bat silent powershell.exe -WindowStyle Hidden -File .\WatchAndUpload.ps1 [2] Start the background watcher silently (zero console window).
GoogleUnlimited.bat status .\WatchAndUpload.ps1 -StatusOnly [3] View total uploads, pending retries, service state, and last 10 uploads.
GoogleUnlimited.bat logs .\WatchAndUpload.ps1 -ShowLogs [4] Display the last 30 sync activity entries from the database.
GoogleUnlimited.bat enable .\WatchAndUpload.ps1 -EnableStartup [5] Create a shortcut in the Windows Startup folder to run on boot.
GoogleUnlimited.bat disable .\WatchAndUpload.ps1 -DisableStartup [6] Remove the shortcut from the Windows Startup folder.
GoogleUnlimited.bat stop .\WatchAndUpload.ps1 -StopWatcher [7] Terminate any active background watcher processes.
GoogleUnlimited.bat dirs .\WatchAndUpload.ps1 -ManageDirs [8] Open the interactive folder manager or Windows folder browser dialog.
GoogleUnlimited.bat account gotohp-cli creds [9] List configured accounts, switch the active account, or open the GUI.
GoogleUnlimited.bat resync .\WatchAndUpload.ps1 -ForceResync [10] Perform a full scan and force re-sync of all media across watched directories.
GoogleUnlimited.bat update .\WatchAndUpload.ps1 -UpdateApp [11] Check and apply application updates safely while preserving configs & database.

macOS & Linux (google-unlimited.sh)

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
  [9] Check / Update Application (Keep configs safe)
  [0] Exit
==========================================================

You can execute any command directly from the shell:

Shell Command Menu Option Description
./google-unlimited.sh watch [dirs...] [1] Start the live sync watcher in the foreground.
./google-unlimited.sh status [2] Display upload statistics, retry queue count, and recent sync records.
./google-unlimited.sh logs [3] View the last 30 sync activity log records with color-coded severity.
./google-unlimited.sh setup [4] Install platform dependencies, download missing binaries, and set file permissions.
./google-unlimited.sh enable [5] Enable auto-start on login (launchd on macOS, systemd user service on Linux).
./google-unlimited.sh disable [6] Disable and remove the auto-start background service.
./google-unlimited.sh stop [7] Stop all active background watcher instances and filesystem listeners.
./google-unlimited.sh verify [8] Verify the cryptographic SHA-256 integrity of the gotohp-cli binary.
./google-unlimited.sh update [9] Check and apply application updates safely while preserving configs & database.
./google-unlimited.sh creds [subcommand] — Manage accounts: creds add, creds list, creds set <email>, creds remove <email>.
./google-unlimited.sh menu — Explicitly open the interactive terminal menu.
./google-unlimited.sh help — Display command-line usage information.

Folder Monitoring & Supported Media

Monitored Folders

Default Behavior (When watch_dirs.txt does not exist):


Custom Watch Folders (watch_dirs.txt)

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
    $HOME/Google Photos
    ${HOME}/Media
    ~/Pictures
    /Volumes/ExternalSSD/Photos
    
    On macOS and Linux, $VAR, ${VAR}, and a leading ~ are expanded. Unknown variables are left unchanged, and shell expressions are never executed.
  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
    

Supported Media Formats (41 Formats)

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

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


File Readiness & Lock Detection

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.

Background Operation

Windows Background Operation


macOS Background Operation


Linux Background Operation


Single-Instance Protection


Data Storage, Privacy, and Security

Local Database Schema (gphotos.db)

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
);

Privacy & Network Destinations


Troubleshooting

1. "ACTION REQUIRED: No Google Account Logged In!"

2. "Another instance is already running" (Windows)

3. File Locked or Still Downloading

4. macOS Gatekeeper / Permission Issues

5. PowerShell Execution Policy Restrictions (Windows)

6. Checking Diagnostic Logs

7. Video Streaming, Seeking, and Android TV Playback

8. Antivirus Warnings & False Positives ("Virus Detected" / Browser Block)


Limitations and Disclaimer


Credits and License

GoogleUnlimited (shishir0x/GoogleUnlimited)

正在搜索数据库…

这是什么?GoogleUnlimited 是一个跨平台的后台工具,它会监视本地文件夹,并通过模拟 Google Pixel 设备,自动将照片和视频上传到 Google Photos,目标是在不使用虚拟机或 Android 模拟器的情况下,获得无限制画质的备份上传。
这是一个应用窗口,还是在后台无界面运行?它以轻量级的原生后台监视程序运行(Windows 上为 PowerShell,macOS 上为 fswatch,Linux 上为 inotify-tools),通过命令行或菜单控制;没有常驻图形界面,只有一个在 Windows 上用于 Google 登录的小型一次性图形辅助程序。
我该如何让它运行起来?克隆仓库,然后在 Windows 上双击 gotohp-x64.exe 登录,再双击 GoogleUnlimited.bat 开始监视;在 macOS/Linux 上运行 ./google-unlimited.sh setup 安装依赖并下载二进制文件,然后完成身份验证并运行 watch。
我需要先安装什么?Windows 需要 PowerShell 5.1+(或 pwsh 7)以及 PSSQLite 模块;macOS 需要通过 Homebrew 安装 fswatch、sqlite3 和 curl;Linux 需要通过 apt/dnf/pacman/zypper 安装 inotify-tools、sqlite3 和 curl。安装脚本会自动安装所有这些组件。
我是否需要以某种方式用我平时的 Google 账号登录?需要,但这是一个手动操作技巧:打开 Google 登录页面,点击“I agree”,然后忽略页面一直加载中的状态(这是正常现象),接着从浏览器的 DevTools 中获取 oauthtoken Cookie,并将其粘贴到 gotohp 或安装脚本的隐藏提示框中。
它能在 Apple Silicon 芯片的 Mac 和 ARM 架构的 Linux 上运行吗,还是只支持 x86?两者都支持:macOS 支持 Big Sur 及更高版本,涵盖 Apple Silicon(M1–M4)和 Intel x64;Linux 支持基于 x86_64 或 aarch64/arm64 的主流发行版;Windows 同时支持 64 位的 Windows 10/11。
我的照片数据会经过开发者自己的服务器吗?不会,它直接连接 Google 自身的 API 端点,没有任何遥测,中间也不经过任何服务器。
它如何避免同一张照片被重复上传两次?它会在本地保存一个 SQLite 数据库(gphotos.db),记录已上传的文件,匹配依据是文件路径,以及 filename|filesize 键和 SHA-256 内容哈希的组合,因此在双系统或共享驱动器上出现的重复文件会被跳过。
如果上传失败会怎样?上传失败的文件会进入一个持久化的重试队列表,每 30 秒自动重试一次,最多重试 3 次;如果仍然失败,则会被记录为永久失败。
开机时能自动启动吗?可以:在 Windows 上,它会通过 VBScript 在“启动”文件夹中创建快捷方式,运行时不显示任何控制台窗口;在 macOS 上,它会注册一个 launchd LaunchAgent;在 Linux 上,它会以 systemd 用户服务的方式运行,并启用 lingering 会话。
默认会监视哪些文件夹中的新照片?在 Windows 上,它会自动监视“图片”和“下载”文件夹,以及磁盘上已存在的云端文件夹,如 OneDrive Pictures/Camera Roll 和 iCloud;也可以通过 watchdirs.txt 添加自定义文件夹。
作者
shishir0x
大小
19.7 MB
星标
417
更新
提交Nov 14
时长
1个月
提交 · 90 天