ASCII Photobooth

A Linux webcam photobooth that converts live frames to ASCII art in the terminal, and can optionally send captures to a parallel-port needle/dot-matrix printer.

There are two front ends:

• photobooth.py — a curses TUI. Grabs frames directly via OpenCV/v4l2 (no per-frame process spawn), converts them with the ascii-image-converter binary, and supports live brightness/exposure adjustment. This is the actively developed front end.
• exec-cycle.sh / webcam2ascii.sh — a simpler bash implementation of the same live-preview loop, built around fswebcam and ascii-image-converter.

Both read the same webcam.conf / ascii.conf / keybinds.conf / printer.conf files, so you only need to configure your hardware once.

Requirements

• fswebcam, ascii-image-converter, v4l-utils
• python-opencv (for photobooth.py)
• A V4L2-compatible webcam
• Optionally, a parallel-port printer wired up via parport/parport_pc/lp kernel modules, for hardcopy prints

Install everything with the script for your distro:

./install_deps_arch.sh    # Arch Linux / other pacman+AUR distros
./install_deps_debian.sh  # Debian, Ubuntu, and other apt-based distros
./install_deps_fedora.sh  # Fedora and other dnf-based distros

install_deps_arch.sh installs yay if needed and pulls ascii-image-converter from the AUR. The Debian/Fedora scripts build ascii-image-converter with go install instead, since it isn't packaged for apt/dnf. All three install the required packages, add your user to the lp group (needed to write to /dev/lp0), and load the parallel-port kernel modules.

Usage

Run the TUI (recommended):

./photobooth.py

Or the bash live-preview loop:

./exec-cycle.sh

Controls

Configurable in keybinds.conf; defaults shown below.

Key	Action
space	Capture a photo
+ / -	Adjust brightness
. / ,	Adjust exposure
r	Reset brightness/exposure to defaults
q	Quit (photobooth.py only; exec-cycle.sh quits on Ctrl+C)

Captures are saved as photo-<timestamp>.jpg and ascii-img-<timestamp>.txt, and are automatically sent to the printer via txt2printr.sh if one is configured.

Configuration

File	Purpose
webcam.conf	Capture device, resolution, JPEG quality, default brightness/exposure, and the v4l2 control names/IDs used to adjust them
ascii.conf	ascii-image-converter options: output size, character map/complexity, grayscale, negative, flips, and whether the live-preview viewfinder mirrors the print output's aspect ratio (REAL_VIEWFINDER)
keybinds.conf	Single-character key bindings for capture/brightness/exposure/reset/quit
printer.conf	Printer device, A4 landscape rotation (PRINTER_A4), and per-page capacity (PRINTER_MAX_LINES/PRINTER_MAX_COLS)

Printing

txt2printr.sh sends an ASCII art text file to a parallel-port printer (/dev/lp0 by default, override with PRINTER_DEV). Needle/dot-matrix printers have no hardware landscape mode, so setting PRINTER_A4=true in printer.conf rotates the art in software before printing (turn the printed page 90° to read it); photobooth.py instead rotates the source image before ASCII conversion for better quality, and sets PRINTER_MAX_LINES=0 to signal a roll/continuous-feed printer with no fixed page length.

Printer page capacity varies by hardware and isn't reliably predictable from paper geometry — measure it with pagetest.sh:

./pagetest.sh              # numbered lines, to find lines-per-page
./pagetest.sh ruler        # a column ruler, to find chars-per-line
PRINTER_A4=false ./txt2printr.sh pagetest.txt

Read the last line/column that printed on page 1 and set PRINTER_MAX_LINES/PRINTER_MAX_COLS in printer.conf accordingly. printer.conf.hpold.bak and printer.conf.rollpaper.bak are example configs for a couple of previously-tested printers.

Other scripts

• yay-installer.sh — installs the yay AUR helper (used by install_deps_arch.sh) script (LUKS2/btrfs/FIDO2), unrelated to the photobooth itself, was origin