FAQ - GaseousIce/wallpaper-scraper GitHub Wiki

Frequently Asked Questions (FAQ)

This page addresses common questions about the Wallpaper Scraper tool.

General Questions

What is Wallpaper Scraper?

Wallpaper Scraper is a Python-based tool that allows you to download high-quality wallpapers from multiple sources like Unsplash, Wallhaven, and Pixabay while respecting their rate limits and usage policies.

Which wallpaper sources are supported?

Currently, the tool supports:

Additional sources can be added by implementing new scrapers.

Is this tool free to use?

Yes, the Wallpaper Scraper is open-source and free to use. However, you will need to obtain your own API keys from the respective wallpaper providers.

What are the system requirements?

  • Python 3.8 or higher
  • Required Python packages (installed via requirements.txt)
  • Internet connection
  • About 20MB of disk space for the tool (plus space for downloaded wallpapers)

Usage Questions

Do I need API keys to use this tool?

Yes, you need API keys for the wallpaper sources you want to use. Each source has its own API key:

  • Unsplash API key
  • Wallhaven API key
  • Pixabay API key

See the API Keys guide for instructions on obtaining these keys.

How many wallpapers can I download?

The number of wallpapers you can download depends on the API rate limits of each source:

  • Unsplash: 50 requests per hour on the free plan
  • Wallhaven: More lenient but still has rate limits
  • Pixabay: Up to 5,000 requests per hour

The tool implements rate limiting to respect these constraints automatically.

How do I search for specific types of wallpapers?

You can use the --query parameter to search for specific keywords:

python main.py --source unsplash --query "mountains sunset"

You can also filter by orientation and resolution:

python main.py --source wallhaven --query "cyberpunk" --orientation landscape --resolution 1920x1080

Can I download wallpapers in specific resolutions?

Yes, use the --resolution parameter:

python main.py --source wallhaven --resolution 3840x2160

Note that availability of specific resolutions depends on the source.

How do I download anime wallpapers?

Use the --anime flag to download anime wallpapers:

python main.py --source wallhaven --anime

Wallhaven provides the best support for anime wallpapers due to its dedicated anime category. For other sources, the tool will add "anime" to your search query.

Which source is best for anime wallpapers?

Wallhaven is the recommended source for anime wallpapers, as it has a dedicated anime category. Pixabay has some anime content, while Unsplash has very limited anime-related imagery since it focuses on photography.

Can I combine the anime filter with other options?

Yes, you can combine the --anime flag with other options:

# Download anime wallpapers with a specific query
python main.py --source wallhaven --anime --query "fantasy"

# Download high-resolution anime wallpapers
python main.py --source wallhaven --anime --resolution 1920x1080

Where are wallpapers saved?

By default, wallpapers are saved to the directory specified in your config.json file (defaults to ~/Pictures/Wallpapers). You can specify a different location with the --output parameter:

python main.py --source unsplash --output ~/Downloads/Wallpapers

Can I automate wallpaper downloads?

Yes, you can set up cron jobs (on Linux/Mac) or scheduled tasks (on Windows) to automate downloads. See the Examples page for automation scripts.

Technical Questions

How does the rate limiting work?

The tool implements rate limiting by waiting a specified amount of time between API requests. This prevents overloading the API servers and helps avoid getting your API key blocked.

You can adjust the rate limit in your config.json file or with the --rate-limit parameter:

python main.py --source unsplash --rate-limit 2.0

This sets a 2-second delay between requests.

Does the tool download duplicates?

By default, the tool checks if a file with the same name already exists and skips downloading duplicates. This behavior can be controlled with the skip_existing setting in your configuration file.

Can I use a proxy with this tool?

The tool doesn't have built-in proxy support, but you can set up system-wide proxy settings that Python will use:

export HTTP_PROXY="http://proxy.example.com:8080"
export HTTPS_PROXY="http://proxy.example.com:8080"
python main.py --source unsplash

Is there a graphical user interface (GUI)?

Currently, the tool is command-line only. A GUI version might be developed in the future. If you're interested in contributing a GUI, check the Contributing guide.

Troubleshooting Questions

Why am I getting "No API key provided" errors?

You need to set up API keys for each source you want to use. See the API Keys guide for instructions.

Why are my downloads very slow?

Slow downloads can be caused by:

  • Network connection issues
  • Rate limiting (either by the tool or the API)
  • Too many concurrent downloads

Try adjusting the max_concurrent_downloads setting:

python main.py --source pixabay --max-concurrent 3

Why do some downloads fail?

Downloads might fail due to:

  • Network interruptions
  • API rate limits being exceeded
  • Temporary server issues
  • Invalid or expired API keys

Use the --verbose flag to get more detailed error information:

python main.py --source unsplash --verbose

How do I report bugs or request features?

You can report bugs or request features by:

  1. Opening an issue on the GitHub repository
  2. Including detailed information about the bug or feature request

Privacy and Legal Questions

Does this tool collect any personal information?

No, the Wallpaper Scraper doesn't collect any personal information. It only communicates with the wallpaper source APIs using the API keys you provide.

Is it legal to download wallpapers with this tool?

The tool is designed to work with legitimate wallpaper sources through their official APIs, which ensures that usage is legal and respects the terms of service. Always ensure you're following the terms of service for each wallpaper source.

Can I use downloaded wallpapers commercially?

Usage rights depend on the source:

  • Unsplash: Generally allows commercial use without attribution (but attribution is appreciated)
  • Wallhaven: Varies by image, check individual image licenses
  • Pixabay: Most images are free for commercial use without attribution

Always check the specific license for each image before commercial use.

Extension and Development

Can I add support for additional wallpaper sources?

Yes, you can create new scraper classes that implement the BaseScraper interface. See the Contributing guide for details on adding new scrapers.

How can I contribute to this project?

Contributions are welcome! See the Contributing guide for details on how to contribute code, documentation, or bug reports.

Can I use parts of this code in my own project?

Yes, as long as you comply with the project's license. See the LICENSE file in the repository for details.

Next Steps