Raspberry Pi 4B Photo Frame Application

.gitignore

@@ -1,9 +1,6 @@
-*.iml
-.gradle
-/local.properties
-/.idea/workspace.xml
-/.idea/libraries
-.DS_Store
-/build
-/captures
-.externalNativeBuild
+venv/
+__pycache__/
+*.pyc
+.env
+client_secret.json
+token.json

README.md

@@ -0,0 +1,81 @@
+# Raspberry Pi Photo Frame
+
+A Python application that turns a Raspberry Pi 4B into a digital photo frame, fetching photos from a specific Google Photos album.
+
+## Features
+- **Random Shuffle**: Randomly picks photos from a specified album.
+- **Interval Rotation**: Changes photos every 30 seconds (configurable).
+- **Night Mode**: Turns off the display (via `vcgencmd`) between 10 PM and 7 AM to save power.
+- **Caching**: Caches downloaded images locally to reduce network usage.
+- **PyGame**: Uses hardware-accelerated PyGame for smooth full-screen rendering.
+
+## Requirements
+- Raspberry Pi (running Raspberry Pi OS)
+- Python 3
+- Google Cloud Project with Photos Library API enabled.
+
+## Setup
+
+### 1. Google Cloud Setup
+1. Go to [Google Cloud Console](https://console.cloud.google.com/).
+2. Create a new project.
+3. Enable **Google Photos Library API**.
+4. Go to **APIs & Services > OAuth consent screen**.
+   - User Type: **External**.
+   - Add Test Users: Add your email address.
+   - Scopes: Add `.../auth/photoslibrary.readonly`.
+5. Go to **Credentials**.
+   - Create Credentials -> **OAuth Client ID**.
+   - Application Type: **Desktop App**.
+   - Download the JSON file and save it as `client_secret.json` in the project root.
+
+### 2. Installation
+1. Clone this repository.
+2. Install dependencies:
+   ```bash
+   # If you need system dependencies for pygame/pillow:
+   sudo apt-get install libsdl2-2.0-0 libsdl2-image-2.0-0 libsdl2-mixer-2.0-0 libsdl2-ttf-2.0-0 libjpeg-dev zlib1g-dev
+
+   # Install python deps
+   python3 -m venv venv
+   source venv/bin/activate
+   pip install -r requirements.txt
+   ```
+
+### 3. Configuration
+- Open `main.py` and set `ALBUM_TITLE` to the name of the album you want to display.
+- Adjust `ROTATION_INTERVAL_MS` if desired.
+- Adjust `START_HOUR` and `END_HOUR` in `scheduler.py` for night mode.
+
+### 4. First Run (Authentication)
+Run the authentication script once to generate the token:
+```bash
+python3 auth.py
+```
+Follow the instructions in the console to authorize the app. This will create `token.json`.
+
+### 5. Run the Frame
+```bash
+python3 main.py
+```
+
+### 6. Autostart on Boot (Raspberry Pi)
+Create an autostart entry:
+```bash
+mkdir -p ~/.config/autostart
+nano ~/.config/autostart/photoframe.desktop
+```
+Content:
+```ini
+[Desktop Entry]
+Type=Application
+Name=PhotoFrame
+Exec=/path/to/your/venv/bin/python3 /path/to/your/main.py
+StartupNotify=false
+Terminal=false
+```
+
+## Troubleshooting
+- **Display not turning off**: Ensure `vcgencmd` works on your system. It is standard on Raspberry Pi OS.
+- **No photos**: Check the album name match exactly in `main.py`.
+- **PyGame video driver**: If running from SSH without a desktop, you might need to set `os.environ["SDL_VIDEODRIVER"] = "dummy"` for testing, or ensure you are running in the desktop environment.