📸 PyCheese

A robust, feature-rich photo booth application built with Python, PyQt6, and OpenCV. It mimics the functionality of the classic "Cheese" Linux application but adds modern features like AI background replacement and real-time filters. Since it is written in PyQT, it looks better in QT based desktop environments.

✨ Features

• Real-time Filters: Mirror, Bulge (Distortion), Sepia, Emboss, Edges, and Grayscale.
• AI Background Replacement: Automatically blur or replace your background without a green screen (powered by MediaPipe).
• Filter Stacking: Apply multiple effects simultaneously (e.g., Sepia + Mirror + Bulge).
• Camera Controls: Select specific cameras, change resolutions (VGA to 4K), and switch encoding (MJPG vs YUYV) for smooth framerates.
• Tools: Countdown timer (Instant, 3s, 10s) and flash effect.
• Format Support: Save photos as PNG, JPG, WEBP, or AVIF.

🛠️ Installation & Setup

📦 Distro-Specific Packages

If you are on Arch Linux or OpenMandriva, you can use pre-built packages instead of manually setting up a virtual environment.

• Arch Linux (AUR):
  A package is available in the Arch User Repository. You can install it using an AUR helper (like yay or paru) or manually.
  https://aur.archlinux.org/packages/pycheese

yay -S pycheese

• OpenMandriva:
  An RPM package is available directly in the Releases section of this repository.

---

🐍 Manual Installation (Virtual Environment)

For other distributions, or if you prefer manual control, using a virtual environment (venv) is highly recommended to avoid conflicts with your system's package manager.

1. Create a Virtual Environment

1. Create a Virtual Environment

Open your terminal and run:

# Create the directory if it doesn't exist
mkdir -p ~/.local/venvs

# Create the virtual environment
python3 -m venv ~/.local/venvs/my_cheese_env

# Activate the environment
source ~/.local/venvs/my_cheese_env/bin/activate

2. Install Dependencies

We specifically use "numpy<2" because the latest NumPy 2.0 release can currently cause compatibility issues with OpenCV and MediaPipe.

Run this command inside your activated venv:

pip install PyQt6 opencv-python "numpy<2" mediapipe

(Note: mediapipe is optional but required for the Background Replacement filter. If you skip it, that specific filter will be disabled automatically.)

3. Running the App

Make sure your script (e.g., pycheese.py) is in the folder, then run:

python pycheese.py

---

🐧 Linux Desktop Integration

To launch the app from your system menu (like GNOME or KDE application launcher) instead of the terminal, you can create a .desktop file.

Step 1: Create the file

Open a text editor and create a file named pycheese.desktop in ~/.local/share/applications/.

nano ~/.local/share/applications/pycheese.desktop

Step 2: Paste the Configuration

Paste the following content. Be sure to replace /home/YOUR_USERNAME/pycheese with the actual path to your folder.

[Desktop Entry]
Version=1.0
Name=PyCheese Photo Booth
Comment=Take photos with webcam filters
# Point this to the python executable INSIDE your venv
Exec=/home/YOUR_USERNAME/.local/venvs/my_cheese_env/bin/python /home/YOUR_USERNAME/path/to/pycheese.py
# Point this to the folder containing the script
Path=/home/YOUR_USERNAME/path/to/script_folder
# You can use a generic icon or download a camera icon
Icon=camera-photo
Terminal=false
Type=Application
Categories=AudioVideo;Video;Recorder;> 

Step 3: Make it Executable (Optional)

Usually, simply saving it in that folder is enough, but you can ensure permissions are correct:

chmod +x ~/.local/share/applications/pycheese.desktop

You should now see "PyCheese Photo Booth" in your applications menu!

---

⚠️ Troubleshooting

• AVIF & Camera Names: As of the time of writing, AVIF support is more likely to work outside of a venv (using system libraries), whereas cameras are more likely to be recognized and named correctly (e.g., "Logitech C920" vs "Camera 1") inside a venv due to Python package versions.
• "QtMultimedia" Warning: If you see a warning about camera names not loading, it is due to a version mismatch between PyQt6 and your system libraries. The app will automatically fallback to "Camera 0", "Camera 1" so it remains usable.
• Laggy Video: If high resolutions (like 1080p) are laggy, look for the "Format" dropdown in the app and switch it to "Motion JPEG (Fast)".
• Background Filter Error: If the background filter displays text "MediaPipe Missing", ensure you installed it inside the venv using the pip command above.