pyspotlightarchiver 1.1.3

Fetch and download Windows Spotlight images automatically. Lightweight and easy to use.

pyspotlightarchiver

pyspotlightarchiver is a Python CLI tool for fetching, preserving, and managing Windows Spotlight images.

Inspired by Spotlight-Downloader.

🚀 Features

• List available Spotlight image URLs
• Download Spotlight images in 1080p or 4K resolution
• Filter by locale and orientation
• Embed EXIF metadata with exiftool
• Avoid duplicate downloads with perceptual hash and URL checks
• Automatic throttling to avoid rate limits

📦 Requirements

• Python 3.10 or higher (Download Python)
• exiftool (optional, required for --embed-exif)

⚖️ Installation

From PyPI (recommended)

pip install pyspotlightarchiver

From source (for development)

1. Clone the repository:

   git clone https://github.com/yell0wsuit/pyspotlightarchiver.git
   cd pyspotlightarchiver
   

   Or download as ZIP and extract it.

2. (Optional) Create a virtual environment:

   python -m venv venv
   .\venv\Scripts\activate  # On Windows
   source venv/bin/activate  # On Linux/Mac
   

   We recommend using a virtual environment to avoid conflicts with other Python packages.

3. Install dependencies:

   pip install -r requirements.txt
   

⚙️ Usage

Run the tool using:

pyspotlightarchiver [command] [options]

Available commands

list-url

List available Windows Spotlight image URLs.

pyspotlightarchiver list-url [options]

Option	Description
--api-ver	API version to use (3 for 1080p, 4 for 4K). Default: 3.
--locale	Locale code (e.g., en-us). Use all to include all locales. Default: en-us.
--orientation	Filter by image orientation: landscape, portrait, or both. Default: landscape.
--verbose	Enable verbose output.

download

Download Spotlight images to your computer.

pyspotlightarchiver download --single|--multiple [options]

Required:

• --single: Download a single image.

  • If --locale all, a random locale is selected.
  • If --orientation both, both orientations are downloaded.

• --multiple: Download all available images.

  • With --locale all, all locales are processed.
  • With --orientation both, both versions are downloaded.

Additional Options:

Option	Description
--api-ver	API version (3 or 4). Default: 3.
--locale	Locale code (e.g., en-us). Default: en-us.
--orientation	Image orientation: landscape, portrait, or both. Default: landscape.
--save-dir	Directory to save downloaded images. Default: downloaded_spotlight.
--embed-exif	Embed EXIF metadata using exiftool.
--exiftool-path	Path to exiftool. Required if not in system PATH.
--verbose	Show detailed logs.

📌 Notes

🔄 Locale throttling

When using --locale all, the tool throttles API requests to avoid rate limits.

• Locales are processed in chunks of 15.
• Delay increases after each chunk:
  • After 15 locales: wait 5 sec
  • After 30: wait 10 sec
  • After 45: wait 15 sec
  • ...up to a maximum of 180 seconds.

🔁 Download loop (with --multiple)

The tool continues downloading images until no new images are found after 50 consecutive attempts.

After every 10 attempts, delay increases gradually, capped at 180 seconds to avoid rate limiting.

📂 Caching & duplicates

• A local SQLite database tracks downloaded image URLs and perceptual hashes
• Located at: .cache/downloaded_images.sqlite
• Prevents redownloading of identical images.
• Detected perceptual duplicates are logged in: phash_duplicates_report.md

💡 Tip: Do not delete the cache database to preserve download history.

📄 License

This project is licensed under the GNU GPLv3.