PixHeap

FastAPI media browser with background thumbnailing.

Setup

1. Create and activate venv:
   • python3 -m venv .venv
   • source .venv/bin/activate
2. Install deps:
   • pip install -r requirements.txt
3. Edit config.json and set media_root to your pictures/videos folder.
4. Run:
   • uvicorn main:app --reload

Open http://localhost:8000

Authentication

PixHeap can require logins and block public media access. Add an auth section to config.json:

{
  "auth": {
    "enabled": true,
    "secret": "change-me-to-a-long-random-string",
    "session_ttl_seconds": 86400,
    "cookie_secure": false,
    "users": {
      "admin": {
        "password_hash": "hex-encoded-hash",
        "salt": "random-salt",
        "can_upload": true
      },
      "viewer": {
        "password_hash": "hex-encoded-hash",
        "salt": "random-salt",
        "can_upload": false
      }
    }
  }
}

Generate a password hash + salt with:

python3 - <<'PY'
import os, hashlib
password = "your-password"
salt = os.urandom(16).hex()
hash_ = hashlib.pbkdf2_hmac("sha256", password.encode(), salt.encode(), 120_000).hex()
print("salt:", salt)
print("password_hash:", hash_)
PY

Set cookie_secure to true when you serve PixHeap over HTTPS.

User management helper

Manage users in config.json with scripts/manage_users.py:

python3 scripts/manage_users.py add admin --upload
python3 scripts/manage_users.py add viewer --no-upload
python3 scripts/manage_users.py passwd admin
python3 scripts/manage_users.py set-upload viewer --allow
python3 scripts/manage_users.py list
python3 scripts/manage_users.py delete viewer

Video previews

Install ffmpeg to generate short preview clips and posters for videos. Without it, videos will still open in a new tab, but no preview will be shown.

You can limit concurrent preview generation with ffmpeg_max_workers in config.json.

Uploads

Use the sidebar upload button to open the upload screen. Files are first saved to upload_tmp, then moved under media_root/YYYY/YYYY-MM-DD based on EXIF (images) or creation_time (videos). You can edit the destination path before moving. If EXIF/metadata is missing, file mtime is used.