Skip to content

README.md

Latest commit

 

History

History
110 lines (75 loc) · 7.03 KB

README.md

File metadata and controls

110 lines (75 loc) · 7.03 KB
Raw

📸 Party Photobooth - uses PHP hosted file and image storage with a mobile phone.

A self-contained, single-file web photobooth for parties and events, that uses the phone/laptop's selfie camera and provides access to a downloadable compositied image.

Why

I couldn't find an app that was easy for the person being photographed to get the photo digitally and in realtime.

How it works

  1. Press 'Tap to begin' on the camera phone
  2. Tap 'start'
  3. 4 photos are taken with a 2 second gap
  4. A processing screen appears for 3-4 seconds
  5. The user scans unique QR code with their phone, which opens the link to the hosted image via their browser, and they can save or share etc.
  6. The tool resets after 30 seconds or via a manual tap of 'restart'

Notes

  • This does store the processed photo on your webserver (as a hashed filename), you'll need to manually delete or crontab a cleanup process.

  • By deafult it overlays a creative frame, but you can override this in the settings, or make your own (I used Gemini AI to create the overlays, as PNG with alpha mask).

Built to run on basic LAMP hosting (PHP + Apache/Nginx). No database, no build step, no dependencies to install on the server.

Example overlay frame 1 Example overlay frame 2

I used a cheap selfie-light-tripod which made it easy to mount and light. Example stand

Features

  • 📱 Works on any device — uses the browser's native camera via getUserMedia, mirrored for a natural selfie feel
  • ⏱️ Guided 4-shot sequence — big on-screen countdown (3‑2‑1 for the first shot, 1‑0 between the rest) with a flash effect
  • 🖼️ Square crop, centred — each shot is cropped to a square from the centre of the frame, so results are consistent regardless of device aspect ratio
  • 🧩 2×2 grid composite — the four shots are laid out in a square grid with a white border, ready for an optional decorative overlay
  • 🎨 Optional PNG frame overlay — drop in your own transparent PNG (e.g. a themed border) and it's composited on top of the grid automatically
  • 🔗 Instant QR code — the finished JPEG is uploaded to the server and a QR code pointing to it is shown immediately, so guests scan and save to their own phone
  • ⏳ Auto-reset — the result screen automatically returns to the welcome screen after a configurable countdown, ready for the next guest
  • 🎛️ One config block — shot count, JPEG quality, border size, overlay file, and reset timing are all adjustable from a single CONFIG object at the top of the script
  • 🪶 Single PHP file — the entire app (server-side save endpoint + client-side HTML/CSS/JS) lives in one file for the simplest possible deployment

Demo flow

  1. Welcome screen — big "tap to begin" button
  2. Camera screen — live square-cropped preview, animated call-to-action button
  3. Countdown & capture — 4 shots with countdown and flash
  4. Processing — photos are composited into a square grid (+ overlay, if enabled) and uploaded
  5. Result screen — grid preview + QR code to scan and download; auto-resets after 30s (configurable)

Requirements

  • Any standard LAMP/LEMP host with PHP support (PHP 7.4+ recommended)
  • HTTPS — required by browsers for camera access via getUserMedia. Camera will not work over plain HTTP (except on localhost for local testing)
  • Write permissions for the web server user to create a photos/ subdirectory

Installation

  1. Upload photobooth.php to your web server (anywhere publicly accessible over HTTPS)
  2. If you want a decorative frame, upload your overlay PNG to the same directory and update CONFIG.overlayFilename in the script (see below)
  3. Make sure the directory is writable by PHP so it can create photos/ on first use — or create it manually and chmod 755 photos
  4. Visit https://yourdomain.com/photobooth.php on any phone or laptop and you're ready to go

That's it — no composer install, no npm install, no build pipeline.

Configuration

All the settings you're likely to want to change live in one place near the top of the <script> block in photobooth.php:

const CONFIG = {
  totalShots:        4,          // number of photos per session
  overlayEnabled:    true,       // draw a PNG frame on top of the grid?
  overlayFilename:   'frame-overlay-example.png', // must sit next to photobooth.php
  autoResetSeconds:  30,         // seconds before the result screen resets itself
  jpegQuality:       0.92,       // 0–1, output JPEG compression quality
  borderPercent:     0.10,       // white border as a % of each photo's width
};

Note: the on-screen shot-counter pills and the 2×2 grid layout are currently built for exactly 4 shots. If you change totalShots, you'll also need to adjust the pill markup and the grid layout logic in buildStrip().

Using your own overlay frame

The overlay should be a square, transparent PNG the same aspect ratio as the output grid, with "windows" cut out where each photo should show through (see frame-overlay-example.png for a working example). Drop it next to photobooth.php, point CONFIG.overlayFilename at it, and it will be drawn on top of the composited grid at full canvas size before the JPEG is saved.

Set overlayEnabled: false to skip this step entirely and ship a plain grid with just the white border.

How it works

  • Capture: each frame is drawn to an off-screen <canvas>, cropped to a square from the centre of the raw camera feed, and un-mirrored so the saved image reads correctly (the live preview is mirrored for a natural selfie experience, but the actual photo isn't)
  • Compositing: the four square photos are drawn into a 2×2 grid on a white canvas with proportional borders, then the overlay PNG (if enabled) is drawn on top
  • Upload: the finished JPEG is POSTed as a base64 data URL to the same PHP file, which decodes it, saves it under photos/ with a random filename, and returns a public URL
  • QR code: generated client-side via the free api.qrserver.com API, pointing at the uploaded file's URL
  • Fallback: if the upload fails for any reason (e.g. server misconfiguration), the app still shows the composited image so nothing is lost — it just can't generate a QR code without a hosted URL

Known limitations

  • Camera access requires HTTPS (a browser/OS restriction, not something this app can work around)
  • The photos/ directory will grow over time — there's no automatic cleanup. Add a cron job if you want old files purged after your event
  • Designed and tested for a 4-shot / 2×2 grid layout out of the box; other shot counts need manual layout changes

License

MIT — see LICENSE. Use it, fork it, theme it for your own event.

Contributing

Issues and pull requests are welcome. This started as a single-event tool, so there's plenty of room to generalise (configurable shot counts/layouts, cloud storage options, printing support, etc.) if you'd like to help extend it.