piq-phraim 0.0.112
Digital Picture Frame System for Raspberry Pi, powered by Immich
Requires Python: >=3.9
Keywords: raspberry-pi, digital-photo-frame, immich, slideshow, photo-display, picture-frame, home-automation

# piq-phraim - Digital Picture Frame System

[![GitHub Sponsors](https://img.shields.io/github/sponsors/PureGrain?label=Sponsor&logo=GitHub-Sponsors&style=for-the-badge)](https://github.com/sponsors/PureGrain)
[![Buy Me A Coffee](https://img.shields.io/badge/Buy%20Me%20A%20Coffee-Support-yellow?style=for-the-badge&logo=buy-me-a-coffee)](https://buymeacoffee.com/puregrain)
[![Build & Scan](https://github.com/PureGrain/piq-phraim/actions/workflows/build-and-scan-immich.yml/badge.svg)](https://github.com/PureGrain/piq-phraim/actions/workflows/build-and-scan-immich.yml)
[![Last Commit](https://img.shields.io/github/last-commit/PureGrain/piq-phraim)](https://github.com/PureGrain/piq-phraim/commits/main)
[![Repo Size](https://img.shields.io/github/repo-size/PureGrain/piq-phraim)](https://github.com/PureGrain/piq-phraim)
[![Issues](https://img.shields.io/github/issues/PureGrain/piq-phraim)](https://github.com/PureGrain/piq-phraim/issues)

**Version:** 0.0.112  
**Release Date:** 10/27/2025  
**License:** See [LICENSE](LICENSE) (dual-license: Polyform Noncommercial + commercial)

---

## About piq-phraim Pi Client

Transform your Raspberry Pi into a smart digital picture frame powered by your Immich photo library.

## Overview

piq-phraim is a complete digital picture frame solution for Raspberry Pi that seamlessly integrates with Immich photo management servers. It features automatic photo synchronization, smooth transitions, and a web-based control interface.

### Key Features

- 🖼️ **Immich Integration** - Directly displays photos from your Immich server albums
- 🎨 **Smooth Transitions** - Multiple transition effects (fade, slide, zoom, wipe)
- 🌐 **Web Control Interface** - Manage your slideshow from any device on your network
- 💾 **Smart Caching** - Local photo caching for optimal performance
- 🔄 **Auto-refresh** - Automatically syncs new photos from your Immich albums
- 🎲 **Shuffle Mode** - Random or sequential playback options
- 📊 **System Monitoring** - Real-time CPU, memory, and temperature monitoring

## Components

### Core Files

- **slideshow.py** - Main Python slideshow application
- **web-control/** - Go-based web control interface
- **requirements.txt** - Python package dependencies
- **config.json.template** - Configuration template
- **install.sh** - Automated installation script
- **LICENSE** - MIT license

## Requirements

### Hardware

- Raspberry Pi 4 or 5 (2GB+ RAM recommended)
- HDMI-compatible display
- MicroSD card (16GB+ recommended)
- Stable network connection

### Software

- Raspberry Pi OS (Desktop version, 64-bit recommended)
- Python 3.9+
- Active Immich server (v1.88.0+)

## Installation

### Quick Install

Run the automated installer:

```bash
git clone https://github.com/PureGrain/piq-phraim.git
cd piq-phraim/pi-client
chmod +x install.sh
./install.sh
```

The installer will:

- Install all required dependencies
- Set up the slideshow service
- Build and install the web control interface
- Configure systemd services for auto-start
- Create necessary directories and permissions

### Configuration

1. **Edit the configuration file:**

   ```bash
   sudo nano /etc/piq-phraim/config.json
   ```

2. **Update with your Immich server details:**

   ```json
   {
       "immich_server_url": "http://YOUR_IMMICH_SERVER:2283",
       "immich_api_key": "YOUR_API_KEY_HERE",
       "album_name": "frame",
       "interval": 30,
       "transition": "fade",
       "shuffle": true,
       "fullscreen": true,
       "cache_dir": "<system temp dir>/piq-phraim-cache",
       "cache_max_size_mb": 500
   }
   ```

3. **Create an album in Immich:**
   - Log into your Immich web interface
   - Create an album (default name: "frame")
   - Add photos you want to display
   - Note: You can use any album name, just update the config

## Usage

### Service Management

```bash
# Start services
sudo systemctl start piq-phraim-slideshow
sudo systemctl start piq-phraim-web

# Stop services
sudo systemctl stop piq-phraim-slideshow
sudo systemctl stop piq-phraim-web

# Enable auto-start on boot
sudo systemctl enable piq-phraim-slideshow
sudo systemctl enable piq-phraim-web

# Check service status
sudo systemctl status piq-phraim-slideshow
sudo systemctl status piq-phraim-web

# View logs
sudo journalctl -u piq-phraim-slideshow -f
sudo journalctl -u piq-phraim-web -f
```

### Web Control Interface

Access the web interface at: `http://YOUR_PI_IP:8080`

Features available:

- Start/Stop/Pause slideshow
- Skip to next/previous photo
- Adjust slideshow settings (interval, transitions, shuffle)
- Monitor system resources
- Apply preset configurations

### Keyboard Controls

When running in desktop mode:

- **ESC** - Exit slideshow
- **Space/K** - Pause/Resume
- **Right/N** - Next photo
- **Left/P** - Previous photo

## Configuration Options

| Option | Description | Default |
|--------|-------------|---------|
| `immich_server_url` | Your Immich server URL | Required |
| `immich_api_key` | Immich API key | Required |
| `album_name` | Album to display photos from | "frame" |
| `interval` | Seconds between photos | 30 |
| `transition` | Transition effect (fade/slide/zoom/wipe/none) | "fade" |
| `shuffle` | Random photo order | true |
| `fullscreen` | Full screen mode | true |
| `cache_dir` | Local cache directory | "system temp dir/piq-phraim-cache" |
| `cache_max_size_mb` | Maximum cache size in MB | 500 |
| `refresh_interval` | Album refresh interval (seconds) | 300 |

## Troubleshooting

### Common Issues

**No photos displaying:**

- Verify the album exists in Immich and contains photos
- Check the album name matches your configuration
- Ensure the API key has read permissions

**Connection errors:**

- Confirm Immich server URL is accessible from the Pi
- Test API key validity using Immich web interface
- Check network connectivity: `ping YOUR_IMMICH_SERVER`

**Display issues:**

- Verify HDMI connection
- Check display compatibility
- Try different display modes in config

**Web interface not accessible:**

- Ensure the web service is running: `sudo systemctl status piq-phraim-web`
- Check firewall settings
- Verify you're using the correct IP and port (8080)

### Getting Help

- Check service logs: `sudo journalctl -u piq-phraim-slideshow -n 50`
- View web interface logs: `sudo journalctl -u piq-phraim-web -n 50`
- Report issues: [GitHub Issues](https://github.com/PureGrain/PiqPhraim/issues)

### License & Usage

Piq-Phraim is free for personal, educational, and non-profit use. If you want to use it for a business, sell it, or include it in something that makes money, you need a commercial license. See the LICENSE file for details and how to get a commercial license.

**Important:** The Immich server container and files in the `immich_server/` folder are just a helpful add-on. They are not covered by the Piq-Phraim license. We do not provide any warranty or license for those files. If you use the Immich container, you must follow Immich’s own license and rules. See the `immich_server/LICENSE` for more info.

## Author

**PureGrain** at SLA Ops, LLC

- GitHub: [@PureGrain](https://github.com/PureGrain)
- Support: [GitHub Sponsors](https://github.com/sponsors/PureGrain)

## Version

0.0.112

---

For more information about the complete PiqPhraim system, see the main [project documentation](https://github.com/PureGrain/PiqPhraim).

## Installation from PyPI

### Install via pip

The easiest way to install piq-phraim is from PyPI:

```bash
# Basic installation
pip install piq-phraim

# With HEIF support for iPhone photos
pip install piq-phraim[heif]

# With web interface support
pip install piq-phraim[web]

# Full installation with all features
pip install piq-phraim[all]
```

### Manual Installation from Source

You can also install from the GitHub repository:

```bash
git clone https://github.com/PureGrain/piq-phraim.git
cd piq-phraim
chmod +x install.sh
./install.sh
```

The installer script will set up everything you need, including system services and the web control interface.

### First-Time Setup

After installation, create your configuration file:

```bash
# Create config directory
sudo mkdir -p /etc/piq-phraim

# Copy template
sudo cp $(python -c "import piq_phraim; print(piq_phraim.__path__[0])")/config.json.template /etc/piq-phraim/config.json

# Edit with your Immich server details
sudo nano /etc/piq-phraim/config.json
```

### Running piq-phraim

```bash
# Run directly
piq-phraim --config /etc/piq-phraim/config.json

# Or with Python module
python -m piq_phraim --config /etc/piq-phraim/config.json

# Enable debug mode
piq-phraim --config /etc/piq-phraim/config.json --debug
```

---