Introduction
Cross-platform open source photo booth software. Capture your events in an easy and fun way!

Jump directly to installation steps
Jump directly to getting started guide
Features
- Capture images and collages
- Single capture
- Multi-capture
- Fixed layout – 2, 3, or 4 photos
- User chosen layout – shoot 4 photos and then select the ones you like to for a collage of 1, 2, 3, or 4 photos
- Manual collage creation – process pictures after untethered handheld shooting
- User friendly, touch-centered interface
- Beautiful animations
- Multi-language support
- Per project, a fixed language or a choice of languages for guests at multilingual events
- Different UI themes available
- Photo printing
- Visual print routing editor to decide which printer prints which print size, on what media and in which layout
- Combine multiple printers, e.g. to share the work or to print a photo in several ways at once
- Support for native printing method and dispatch to CUPS server
- Photo sharing using QR code with
ffsend - Theming with collage template images (background and foreground) and a live view overlay image
- Rich live view and capture options
- Select device with 1 click or select custom options & combinations
- Webcam
- You can use HDMI capture dongles that act as a webcam
- Digital camera
- Use any camera over USB that supports live view through libgphoto2, capture also required for high quality captures
- With Sony Imaging Edge Remote using AutoIt
- Quick debug options for when no hardware is available
- Gallery with created images
- Easily re-print or -share
- (beta) Analyse images and
- Order by # of people on picture
- Find your image with face recognition
- Keeps (local) use statistics – how many photos were taken, prints were made, …, in total and per project
- Easy administration
- Clear settings panel
- Keep organised with project directories
- Per project options, e.g. hiding the gallery or the QR code button
- Onboarding wizard for the first setup
- Command line options to open a project or start in full screen
- Health checks of external IPs/HTTP services with clear warning banners
- Notifies you of new releases and shows what changed
- Cross platform
- Windows (x64), macOS (Apple Silicon, macOS 15 or newer) and Linux (Flatpak for x86_64 and arm64, including the Raspberry Pi)
- Open source
- The About screen lists the licenses of all open source software MomentoBooth is built with
- Low system requirements
- Can run comfortably, even on old hardware
- Integrates with Home Assistant
- State communicated over MQTT
- Easy automation – e.g. WLED lights that respond to countdown and capture
- (experimental) Video messages
- Guests record a short video message for the hosts
- Transcription and summary through OpenAI-compatible endpoints, printed on a receipt printer
Planned
- Improve distribution options
- Windows arm64 distribution
- Maturing
- Provide choices in exception sharing
- Translate
- … to more languages
- … more parts of the app
- Test
- More cameras – get in touch!
- New features
- Backend/control API
- Physical button control options
- Voice/LLM control
- Remote monitoring
- Deep learning based background removal
- Video capture support
- Offer more control over collage layouts
- Allow generating reports for easier support
- More sharing options
- Backend/control API
Development
For development setup instructions, see the dev documentation.
Translations
MomentoBooth uses the awesome Weblate to manage translations. If you would like to add a new language or improve existing translations, please use Weblate to make suggestions — Weblate will automatically create a PR for you!
Currently supported languages are
| Language | State |
|---|---|
| 🇬🇧 English | ✅ Base language |
| 🇳🇱 Dutch | ✅ Fully checked |
| 🇫🇷 French | Mostly checked |
| 🇩🇪 German | ⚠️ Unchecked |
Links
The concept
This page will briefly explain the concept and user experience of MomentoBooth.
First of all, the central ideology behind MomentoBooth is to create a fun experience for everyone involved with the software. This philosophy shows itself in little things like the confetti that shows when a capture is completed, but also the control that organisers and users have over their own experience.
The interface is meant to be used with a touchscreen, though other ways of controlling the software are being considered. As any photobooth software, the main mechanic is to capture photos at the end of a countdown, present users with some themed version of that picture. Optionally this picture can be printed or downloaded.
MomentoBooth has two main capture modes: single capture and multi-capture.
Single capture
In single capture mode, the software only takes a single photo and presents the user with the result. Whether this is just the picture or a collage with 1 picture depends on the user’s project settings. The user can choose to retake a picture if the result is deemed unflattering. The system will ask whether they want to keep the old file or not.
Multi-capture
In multi-capture mode, multiple pictures are taken that are subsequently merged in a collage image. There are two ways to go about this: have a fixed number of images for a fixed layout, or offer the users a choice after shooting images.
Different layouts
MomentoBooth currently supports 4 different collage layouts, containing and corresponding to 1, 2, 3, or 4 pictures. The layouts are structured like this:

- Collage is landscape; the picture also in landscape position with some margin for theme material.
- Collage is portrait; the two pictures positioned above each other.
- Collage is portrait; the layout with 3 pictures is the one classically used by other photobooth softwares, and will be printed as two strips in one print. These can be cut automatically by supported printers.
- Collage is landscape; the 4 pictures are arranged in a grid.
Note
Here, all the layouts use the same template files, but they can be customized per layout.
In the future, we want to offer more customizability in the image placement layout.
Fixed number of captures
This is the classical modus operandi of photobooths. You hit start, the machine takes a number of pictures, and it presents the result. The organiser of the event can choose which version of the layouts they want, limiting the number of pictures taken to the number of images in the layout.
A slight difference with the classic photobooths is that MomentoBooth allows you to choose exactly how many prints you want, and one can optionally also choose the print size.
User collage choice
In the “user chooses” mode, 4 pictures are taken. Then, the users are presented with a collage creation screen where they can choose which pictures they want to include in their collage, and in which order. They can thus opt for a result that contains 1, 2, 3, or all 4 photos that were taking, resulting in the different layouts described above.
After finishing the selection process the users can optionally print or download their collage on the share screen.
Advanced: manual collage mode
This mode is not accessible from the normal usage flow, but can be entered from the menu or by pressing Ctrl+M. In the manual collage mode, the user (probably the moderator) is presented with a list of all captured input images, and can create new collages from this material at will. This allows, for example, the creation of multiple collages of the same 4 captures, or the creation of collages of manually shot pictures of the event.
Now, let’s move on to the getting started page to start capturing!
Installation
MomentoBooth is cross platform and supports Windows, Linux, and macOS. The installation steps differ per platform. Windows is as of yet the easiest.
Note
Just acquiring and executing the software is enough to use webcams, but digital cameras need additional driver configuration.
Windows
On Windows, there a few methods are available to acquire the software.
Important
In all cases, the Visual C++ Redistributable runtime libraries need to be installed for MomentoBooth to work on Windows.
Download from GitHub
When you go to the releases page on GitHub, a few assets are available per release.
Windows installer application
When you download the MomentoBooth-X.XX.X-XXX-Win-x64-Setup.exe file from the assets, you can execute it to install MomentoBooth as a system program. A start menu item will be created.
zip archive with portable application files inside
Just extract the files anywhere you want and run the photobooth.exe executable.
Using h3xup
The h3xup tool can be used to easily update and switch between different releases of MomentoBooth. Make sure that the h3xup command is available in the PATH and run the following command in the directory that you want the program files to reside in.
h3xup switch --s3-url https://nbg1.your-objectstorage.com/momentobooth-app --filestore-path-prefix Photobooth-Win-x64 release
Whenever a new release is available, just run
h3xup update
Set up development environment
This is not recommended if you just want to try out the software. However, if you want to make edits to the software or test in-development features, you can set up a development environment.
Linux
For Linux, MomentoBooth is distributed as a Flatpak. The releases page on GitHub has a bundle for x86_64 PCs (MomentoBooth-X.XX.X-XXX-Linux-x86_64.flatpak) and one for arm64 devices (MomentoBooth-X.XX.X-XXX-Linux-aarch64.flatpak), such as a Raspberry Pi with a 64-bit OS.
-
Make sure Flatpak is installed and the Flathub repository is added, see the Flathub setup guide for your distribution. MomentoBooth runs on the GNOME runtime, which is downloaded from Flathub during the installation.
-
Install the downloaded bundle:
flatpak install --user MomentoBooth-X.XX.X-XXX-Linux-x86_64.flatpak -
Start MomentoBooth from the application menu, or with
flatpak run io.github.momentobooth.MomentoBooth.
To update, download the bundle of the new release and install it in the same way.
Some notes on the Flatpak:
-
Settings and other application data are stored in
~/.var/app/io.github.momentobooth.MomentoBooth. -
MomentoBooth has access to USB devices and webcams, the home directory, and removable drives under
/mediaand/run/media. To use a folder elsewhere, give MomentoBooth access to it withflatpak override --user --filesystem=/path/to/folder io.github.momentobooth.MomentoBooth. -
Digital cameras (gPhoto2) need the udev rules of libgphoto2 on the system itself, which give the logged in user access to the camera. Most distributions install them along with the libgphoto2 package (e.g.
libgphoto2-6t64on Ubuntu). -
The ping health check of external systems only works when the system allows ping for regular users, as the Flatpak cannot use the elevated privileges the system’s own
pinghas. Some distributions, such as Ubuntu 24.04, do not allow it by default; the check then fails with “Operation not permitted”. To allow it, run:echo 'net.ipv4.ping_group_range = 0 2147483647' | sudo tee /etc/sysctl.d/60-ping-group-range.conf sudo sysctl --system -
The experimental recording of video message audio (through FFmpeg) is not available in the Flatpak.
You can also choose to set up the development environment.
macOS
For macOS, an automatic build pipeline is available for the application, but currently not in use. This is due to the fact that Apple requires all applications to be signed, and to do this an active Apple developers account is required, which costs $99 per year at the time of writing. Since we make no money with this software, doing this is not (yet) worth it. Therefore, right now unfortunately your only option is to set up the development environment and build it locally. We are looking into other options, however.
Getting started
Getting started with MomentoBooth is easy! You only need a computer/laptop with a webcam for a minimal setup. This pages lists our hardware recommendations and minimal software set up steps.
Minimal hardware
THe minimal setup mentioned above approximately consists of a computer that is not ancient with a webcam. You can check out specific details in the fly-out below.
A very basic (but useful for experimenting and developing) setup
- A computer
- OS either:
- Windows 10/11
- Windows 7/8/8.1 might work, but untested
- Linux
- Any recent distribution with Flatpak support, on x86_64 or arm64 (aarch64)
- macOS 15 (Sequoia) or newer
- Only on Macs with Apple Silicon, Intel Macs are not supported
- Windows 10/11
- CPU: Intel Core i5 (2nd gen) or equivalent
- Older might work, but untested
- GPU: Integrated or dedicated graphics by Intel/AMD/NVIDIA
- Anything > 2010 should work fine, a little older may also work
- Software rendering might work but untested
- Memory: 4 GB
- Disk: HDD with at least some space left for photo storage
- Monitor: Anything
- OS either:
- Webcam (optional)
graph LR
C{Computer} -- "USB (or Integrated)" --> W(Webcam)
Recommended hardware
If you want to provide the full experience to the people at your event, a decent computer with touch screen, digital camera, and maybe even a printer are required. See the fly-out below for our recommendations.
Recommended setup
- A computer
- OS either:
- Windows 10/11
- Linux
- Any recent distribution with Flatpak support, on x86_64 or arm64 (aarch64)
- macOS 15 (Sequoia) or newer, on a Mac with Apple Silicon
- CPU: Intel Core i3 (6th gen) or equivalent
- GPU: Integrated or dedicated graphics by Intel/AMD/NVIDIA
- Memory: 8 GB
- Disk: SSD with enough space left for photo storage
- Monitor: At least 1920×1080 px with touch
- OS either:
- Digital camera
- Live view: Supported directly by gPhoto2, or using HDMI out and a USB HDMI capture device (which can act like a webcam)
- Capturing: Supported directly by gPhoto2
- Optional: Photo printer
- Optional: Internet connection
graph LR
C{Computer} -- USB --> A(Camera)
H["HDMI capture device (optional)"] -- USB --> C{Computer}
A -- HDMI --> H
M -- "USB (touchscreen)" --> C
C{Computer} -- VGA/DVI/HDMI/DP --> M(Monitor)
C{Computer} -- "USB/(W)LAN" --> P(Photo printer)
Running the application
Getting up and running is quite simple, and the process looks mostly like this:
graph LR
I(Install MomentoBooth) --> IS(Select image source <br> e.g. webcam) --> O(Open project folder) --> T(Place template image file) --> C(Start capturing)
Below is a step by step explanation of what to do.
- Download/install the latest MomentoBooth release for your OS, check the install instructions.
- It may be convenient to place a shortcut on your desktop.
- Run MomentoBooth.
- You will be greeted by the onboarding wizard to run some checks and get some things set up.
- In the imaging device page, you can select which webcam or camera you want to use. Optionally you can use one of the debug options for testing if you do not have appropriate hardware available.
- If you have a file with setting presets to use, drop the file or text in the box on the respective page of the onboarding wizard and press accept.
- During the wizard you will be prompted to open your first project folder. This folder is used to look for templates and store the captures, output images/collages. We will come back to it later.
Tip
Optionally, you can change your imaging in the settings panel.
- Use the menubar or press
Ctrl+Sto open the settings panel. → See all shortcuts. - Go to the hardware tab
- Scroll down to Live view and capture and select your device from the list.
- If you do not have a webcam available you can also select e.g. “Static image” as a live view source for testing.
- Press
Ctrl+Sagain or click outside the settings to exit the settings screen.
- Once you complete the wizard, you will see the start screen, with the text “Touch to start” and the image from the webcam/camera/test method on the background.
- Go to your project directory (using your file explorer or by using the menubar), go to the
Templatessubdirectory, and place a background image (in portrait orientation) calledback-template.jpgorback-template.png. See template setup - You are now ready to shoot your first pictures!
Once you have the basics up and running you can try connecting a camera, adding a printer, or designing a beautiful template for your next event.
Current limitations
Warning
While the application has been used and tested at different kinds of events, this is open source software made by people in their free time. Please read the list of limitations.
- Webcam support may not be working in some cases (depending on OS and frame format used by the webcam).
- As of 2024 Q3 there is are some bugs in the library that is used for this functionality, these will be resolved in future versions.
- Due to this bug, HDMI capture also might not work. As such camera’s which don’t support live view over USB through gPhoto2 but do support live view using HDMI out (e.g. Nikon D3100) current might not work.
- Workaround: Use a camera which supports live view using USB, or try another OS.
- Live view through gPhoto2: Currently only Nikon D3400 and Sony α6400 have been tested.
- As many Nikon cameras use the same commands for activating and deactivating live view, other Nikon DSLR models which support live view over USB may work.
- Many mirrorless (non-DSLR) cameras may work fine anyway due to live view mode being activated automatically (e.g. Sony α6400).
- The camera handling code is written with future special cases for different brands and models in mind, however we do not have any devices available for development and testing currently.
- Workaround: Try the different options available in the settings screen. If these don’t work, your help might needed to fix the issue if possible at all. Please let us know by raising an issue on GitHub. Be sure to first check whether your model is listed on the gPhoto2 compatibility list. We might be able to expand the compatibility of the application with some remote testing. No guarantees however.
Peripherals
Check out the pages listed under this page in the side bar for information about hardware peripherals such as cameras and printers.
Hardware compatibility
Warning
Make sure to use good quality USB and HDMI cables and preferably connect any USB devices without extension cords. There have been reports of freezes in camera handling due to bad cables. Try different USB ports and/or hubs if any problems arise. Also make sure to power your devices properly for long time usage.
Tested cameras
MomentoBooth utilizes the great gPhoto2 library for communicating with supported digital cameras. Due to this MomentoBooth should support a broad range of cameras from a broad range of vendors.
These are the ones that we have tested ourselves or have received a report about. If you have tested a camera which is not on this list, please report on GitHub and we will happily update can update this list.
| Brand | Model | Live view | Capture | Remarks |
|---|---|---|---|---|
| Nikon | D34001 | ✅ | ✅ | Live view stops after 30 minutes, still needs an automatic workaround (manual workaround: press Ctrl/Cmd+R) |
| Sony | Alpha 64002 | ✅ | ✅ | Also known as ILCE-6400 |
Tested printers
MomentoBooth uses the printing library for Flutter to print to any printer(s) installed on your computer and as such should offer the same compatibility as applications like your Office suite and web browser. Alternatively, it can print to any printer that is available as a queue on a CUPS server. See the printer setup page for how to set up print routing.
If you have any printers to add or any special remarks about your printer, please let us know using a GitHub issue.
| Brand | Model | Works | Remarks |
|---|---|---|---|
| Canon | SELPHY CP1300 | ✅ | Works using USB (recommended) as well as WiFi; look here for sample settings |
| Canon | SELPHY CP1500 | ✅ | Works using WiFi, not at all using USB (at least on Windows); look here for sample settings |
| Kodak | 6850 | ✅ | Only has USB; works both with native and CUPS printer nodes; look here for sample settings |
-
Set Use Special Handling to ‘Nikon DSLR’ ↩
-
Set Use Special Handling to ‘None’ ↩
Camera
Camera usage within MomentoBooth constists of two parts:
- Live view
- Photo capture
For both aspects a few options are available. In general you either work with a webcam, or a separate camera.
Webcam
This is the easiest option to set up. Connect a supported webcam, and use it for both live view and photo capture. This method does not usually result in great image quality, but is great for testing.
Camera
For using a external camera, two methods are available at the moment.
- Using the
gphoto2implementation - Using a vendor remote tethering program (Windows only)
gphoto2
Camera support overview – Needs at least capture support and liveview.
Alternatively, see the libgphoto2 supported cameras – Needs at least Image Capture and Liveview.
Using the gphoto2 implementation is very convenient, as it allows for both live view and high quality photo capture through a single USB connection. Check the above link for which cameras are supported.
Vendor tethering
When a camera is not suported by gphoto2, it may be an option to use a vendor tethering program for photo capture through an AutoIt script. This works as long as the vendor program writes JPG images to a specified directory.
Live view must then be obtained from a camera feed.
- This can either be with a video capture device (usually HDMI) You need the capture device and camera video out cable.
- or by capturing the tethering software with OBS Studio and working with the OSB virtual webcam output.
The right webcam source can then be selected in the live view settings.
To activate the AutoIt script, select Sony Imaging Edge Remote as capture source and set the image input directory.
Physical camera set-up
When running a photo booth at an event, the camera will likely need to be turned on for several hours. A normal battery will not be able to supply energy for that long. It is therefore recommended to get a dc dummy battery, which is connected to an external power supply. The most convenient solution is one that works with USB C Power Delivery, as it can be connected to any PD power supply and so does not require a specific adapter. These usually run between €15~€30.
It is also recommended to mount your camera firmly on either a big or a small tripod so it is stable and can be aimed in the right direction.
Printer
Printing your photos and having a physical reminder of an awesome event is one of the most fun parts of having a photo booth. Therefore MomentoBooth has well-configurable printer support! Which printer prints which print size, on what media and in which layout is set up on the Print routing settings page. This page walks you through setting it up, with some common set-ups as examples. For collage dimensions, also see the template settings.
Getting the print settings right requires quite a bit of trial and error. Ideally a print shows the full collage without parts being cut-off or white borders. For this purpose you probably want to use borderless printing.
Print systems
MomentoBooth supports two ways of printing, and you can combine them in one set-up:
- Native printing uses the printing package to print to the printers installed on your computer, like any other application does. This is the easiest way to get started.
- CUPS printing sends the prints to a queue on a CUPS server, which can run on the same computer or elsewhere on the network. The server is configured in the hardware settings. With CUPS, MomentoBooth can list the media sizes each queue supports, so you do not have to enter the paper size yourself. On Windows, native printers list the papers of their driver too.
Basic set-up
- Install the printer on your computer (native), or add it as a queue to your CUPS server (CUPS), and print a test page from there to be sure it works.
- Open the settings with the menubar or
Ctrl+Sand go to the Print routing page. A new installation already has the Normal output of the source connected to a single printer node. If the printer was connected after opening the page, click Refresh printers in the side panel. - Configure the printer node:
- Give it a Label, e.g. the name of the printer and the paper, so you can recognise it in the routes overview.
- Choose the Backend: Native or CUPS.
- Select the Printer (native) or Queue (CUPS).
- For a CUPS printer, select the Media; the size follows from it. For a native printer on Windows, select the Paper in the same way. For a native printer on macOS or Linux, enter the Size of the paper in mm.
- Leave the Margins at 0 for now.
- Check the Routes in the side panel: Normal should list your printer, and the Problems list should be empty.
- Make sure the project setting Enable printing is on.
- Take a photo and print it. Tune the margins of the printer node until the print shows the full collage without white borders: increase a margin when the printer cuts off part of the photo on that side, decrease it when a white border remains. The last printed sheet is also saved as
latest-print.pdfin the output folder of the project.
Print sizes that are not routed to a printer are not offered in the print dialog. So with the basic set-up, users can only choose the normal print size.
Example set-ups
The examples below show only the relevant part of the routing. Arrows are connections; each printer node is a printer configuration with its own printer or queue and media size.
One printer for normal prints
The basic set-up: every normal print goes to one printer, so the Normal output of the source connects straight to the printer node.
graph LR
S["Source"] -- Normal --> P["Printer: Selphy 100×148"]
Two printers sharing the work
When one printer cannot keep up, put a round-robin node between the source and the printers. Copies are distributed over the printers in turn: when a user prints four copies, each printer prints two of them.
graph LR
S["Source"] -- Normal --> R["Round-robin"]
R --> P1["Printer: Selphy 1"]
R --> P2["Printer: Selphy 2"]
M["Margins"] -.-> P1
M -.-> P2
When both printers are of the same type, connect a margins node to the margins input of both printers, so you only have to tune the margins once. If one of the printers is not configured yet, it is skipped and the other one prints everything.
Small prints, tiled 2×2
Small and tiny prints put several copies of a photo on one sheet, e.g. to hand out to a group. Route the Small output through a tile layout node with 2 columns and 2 rows to a printer, and every sheet holds four copies of the photo. The print dialog shows how many copies a user gets at a time.
graph LR
S["Source"] -- Normal --> P1["Printer: 4×6"]
S -- Small --> T["Tile layout: 2 columns, 2 rows"]
T -- Sheet --> P2["Printer: 4×6 (small)"]
A printer node accepts photos as well as tiled sheets, so the tile layout could also be connected to the first printer node. A separate printer node, using the same printer or queue, is needed when the tiled prints use different media or margins. The photos are turned to fill the tiles best automatically, so the grid decides how they lie: with 1 column and 2 rows on portrait media, landscape photos lie horizontally, one above the other. See tile layout for more examples.
A normal print plus a tiled copy
A duplicate node sends every copy to all its outputs. This way a user gets a normal print and a sheet with small copies to share, from one press of the print button.
graph LR
S["Source"] -- Normal --> D["Duplicate"]
D --> P1["Printer: 4×6"]
D --> T["Tile layout: 1 column, 2 rows"]
T -- Sheet --> P2["Printer: 2×6"]
Split prints for three-photo collages
A collage of three photos holds the photos twice, side by side, so it can be printed as two strips. When the Split output is routed, a three-photo collage printed at normal size follows the Split route: the left and right halves are printed as two separate pages, e.g. on 2×6“ media. When Split is not routed, the collage follows the Normal route and is printed as a whole, to be cut apart afterwards.
graph LR
S["Source"] -- Normal --> P1["Printer: Kodak 4×6"]
S -- Split --> P2["Printer: Kodak 2×6"]
Split prints are always printed in halves, so tile layouts on their route are not used.
Recommended settings for Canon Selphy CP1300/CP1500
The Canon Selphy series of cheap and compact photo printers. The Selphy printers are quite convenient for photo booth purposes, as long as the volume of prints is not too big, since they have a limited and ink roll paper storage volume.
Here are settings that are known to be approximately right for using this type of printer, with a native printer node.
| Property | Value |
|---|---|
| Collage aspect ratio | 1.48 |
| Collage padding | 10 |
| Printer node: Backend | Native |
| Printer node: Size (mm) | W 100 × H 148 |
| Printer node: Margins | Top 0.0, Right 1.6, Bottom 0.5, Left 1.6 |
| Use printer settings for native printers | On |
Make sure to set the default settings of the printer to portrait mode, borderless, and the right paper-size.
Recommended settings for Kodak 6850
Another photo printer that has been used is the Kodak 6850. This printer can handle a lot larger volume with its higher paper/ink capacity and speed.
The Kodak has been tested with CUPS printer nodes, where the following settings work well.
| Property | Value |
|---|---|
| Collage aspect ratio | 1.49 |
| Collage padding | 10 |
| Printer node: Backend | CUPS |
| Printer node: Media | 4×6 |
| Printer node: Margins | Top 0.0, Right 0.0, Bottom 1.5, Left 0.0 |
For the other print sizes, add a printer node per media size, all with the Kodak’s queue:
- Small: a tile layout with 1 column and 2 rows, to a printer node with 4×6 media.
- Tiny: a tile layout with 1 column and 2 rows, to a printer node with 2×6 media.
- Split: directly to a printer node with 2×6 media.
Templates
MomentoBooth works with a simple templating system to thematize your photos.
A collage output is constructed of 3 layers:
- Background template image
- Collage photos
- Foreground template image
Together with the shape and resolution modifying settings in templating settings the template-images define the look of your collage photos. It is recommended to get the template settings right before designing your template images. This avoids extra work to incorporate a different resolution, padding, or aspect ratio.
Tip
See the guide for desiging templates for a step-by-step tutorial on how to design your templates.
Template-file selection
The application will search for template files in the configured template directory. Different templates can be supplied for different collage layouts (1 photo, 2 photos, 3 photos, 4 photos, 0 no photos selected yet).
The template search & selection for a 3 photo collage, for example, works as follows:
- Is there a
back-template-3.png? - Is there a
back-template-3.jpg? - Is there a
back-template.png? - Is there a
back-template.jpg? - No background.
The same is repeated for the foreground with front-template.
A general background and foreground can thus be specified which are overriden by collage-specific back- and foregrounds.
Guide for designing templates
This guide will help you create and test templates for your event that features a MomentoBooth photobooth.
First, get the application to run as described in the getting started guide. If you haven’t done so, read the general concept behind the capture modes and collages.
Tip
You don’t need a webcam or webcam for developing templates, but it is fun to test your creations. If you don’t have one, you can select one of the debug options for the live view method.
Setting up your print layout
If the photobooth setup at your event will feature a printer, you must set up the correct printing layout to ensure your design will fit the paper. If not, skip to design your templates.
Use existing settings
If you are using an existing setup with known settings, you can import the settings preset file.
- Open the settings with the menubar or
Ctrl+Sand go to the templating tab. - Go to the import tab.
- Import the settings preset you need to use and hit accept.
If pre-exported template guide images are available, you can use those. If not, follow the guide below.
Create new settings
- Open the settings with the menubar or
Ctrl+Sand go to the templating tab. - Set the right aspect ratio and padding according to the printer that you will use (see e.g. recommended settings for printers). When not using a printer, you can leave these as-is. Set the output resolution multiplier to a sufficient value, e.g.
4. - Go to the output tab and set the output format to
png. - Get template guide image files
- Go back to the templating tab, scroll down to the template preview, and turn off the back- and foreground. You can choose if you want to include the middle ground with placeholder images.
- Hit
export. - You will find your guide images in the collage export folder you set-up in the getting started guide.
- Optionally, go to the output tab again and set the output format back to
jpg.
Design your templates
Using the guide images, you can design your templates using your favourite image editor.
The guide images have the following structure:
- The red border in the guide image is the padding for printing, this part will be cut-off, so don’t put important elements here. Note that it will still show up in the digital images.
- The white border shows the gap size to clearly distinguish the border regions. This part is printed.
To use your templates:
- Place your files in the templates subdirectory of your project folder. See the templates page on how to name your files.
- You can check the result using the template preview in the templates tab, by shooting a collage, or using the manual collage screen (see menubar, or use
Ctrl+M). If you made changes to your templates, go to a different settings tab and back to the templates tab to reload the images.
Checklist
To take
- Computer gear
- PC
- (Touch) screen and cables
- Power cables
- Camera gear
- Camera
- Tripod
- Battery dummy
- Battery dummy power adapter
- USB cable
- HDMI cable & capture device
- Printer gear
- Printer
- Paper
- Ink cardridges
- USB cable
- Lights
- Backdrop
Preparation
- Develop template materials
- Make sure to set up the print routing first (media sizes and margins) so you have the correct dimensions.
- Check if the camera is functioning well
- Set camera settings correctly
- Check if the printers are functioning well
- Set up the print routing correctly
- Set template settings correctly
- Check stability
Set-up
- Physical
- Connected all the cables
- Turn everything on
- Get internet connectivity
- Camera
- Check camera settings (ISO, shutter, aperature, single/multi-shot, capture format, …)
- Check lighting
- Software
- Latest version
- Check the print routing and the “Enable printing” project setting
- Check camera settings
- Check template settings
- Set directory settings correctly (input/output)
- Reset statistics
- Do a test run
Settings panel
Warning
The overview of the settings is not entirely up to date anymore. Most of the settings’ purpose and options will be clear from the application’s UI, however.
The settings panel can be opened using the menubar or by pressing Ctrl+S. When opened you will be greeted by a screen with a few tabs. These tabs are:
- Project
- Import
- General
- Hardware
- Print routing
- Output
- User interface
- Templating
- MQTT integration
- Face recognition
- Subsystem status
- Debug
- Log
Project settings
In the project settings tab, you can set options to themify MomentoBooth and customize some behaviours for your event. These settings are project-specific. As such, the settings are saved in your project directory, so the settings are also used when the project is opened on another computer.
Primary Color
This color is used for various UI elements in the app, such as buttons, input elements, and backgrounds.
Display Confetti 🎉
This setting controls the display of a confetti shower on the share screen within the photo booth application.
Colorize Confetti to Theme Color
If enabled, the colors of the confetti will will be various shades of the theme color (darker to lighter). Else, random colors will be used.
Alternative ‘Touch to Start’ Text
Text inserted in this setting field will override the text that will be shown on the Start screen instead of ‘Touch to start’. Leave empty to show the default text from the translations data.
Enable Printing
This setting determines whether users can print photos in this project.
If enabled, the print button is shown on the share and photo detail screens, provided at least one print size is routed to a printer on the Print routing page. If disabled, the print button is hidden, regardless of the print routing.
This setting can also be toggled with the Printing quick action in the settings panel, for example to quickly stop printing when the paper runs out.
Treat Single Photo as Collage
This setting determines how a single photo is processed within the photo booth application.
If enabled, a single picture will be treated as if it were a collage with 1 photo selected. This means that the photo will undergo collage processing, even though it contains only one photo.
If disabled, the single photo will be used unaltered.
Settings import
This settings panel contains a UI to import a settings fragment and apply the settings in the fragment over your existing settings. This can be handy to, for example, copy someone else’s print routing. Before the settings are applied, a pop-up will appear to show you the settings that will be changed if the ‘overlay’ is applied. Changes are highlighted in bold.
A settings fragment can be supplied through dragging and dropping a .toml file, plain text, or browsing for a .toml file.
The same UI is also presented in the onboarding wizard.
General settings
In the general settings, you will find settings that influence the behaviour of the program.
Capture delay
This settings specifies the capture delay, a.k.a. countdown time, that is used when making photo captures.
Unit: Seconds
Load Last Project On Start
This setting determines whether the last opened project should be automaticlaly opened when the app starts.
When enabled, MomentoBooth will load the last opened project when it starts.
If disabled, a project must be opened manually each time.
Hotkeys
| Hotkey | Effect |
|---|---|
Ctrl+S | Toggle the settings screen. |
Ctrl+O | Browse for and open a project folder. |
Ctrl+F, Alt+Enter | Toggle fullscreen mode. |
Ctrl+M | Go to the manual collage creation screen. |
Ctrl+H | Return to the home screen. |
Hardware settings
In the hardware settings, you will find settings related to live view, photo capture and printing. Everything related to the hardware the program interfaces with.
General
Rotate Image
This setting determines whether the preview and capture images should be rotated. Rotation direction is clockwise, but is applied before the flip image`* setting.
Available Options:
- No rotation
- 90 degrees
- 180 degrees
- 270 degrees
Default: No rotation
Flip Image – Live View
This setting determines whether the preview image (not the final picture) should be flipped along none, one, or both axes within the photo booth application.
Available Options:
- None
- Horizontal
- Vertical
- Both
Default: Horizontal
Flip Image – Capture
This setting determines whether the captured images (not the final picture) should be flipped along none, one, or both axes within the photo booth application.
Available Options:
- None
- Horizontal
- Vertical
- Both
Default: Horizontal
Live View
Live View Method
This setting determines the method used for live previewing within the photo booth application.
Available Options:
- Debug – Static noise
- Webcam
- gPhoto2
Selected Option: [Option]
Please note that the selected option is based on the current configuration and can be changed by the user.
Webcam
This setting allows you to pick the webcam to use for live view when Webcam is selected for live view. It can also be used for capture by selecting Live view as capture method.
Photo Capture
Capture Method
This setting determines the method used for capturing the images within the photo booth application.
Available Options:
- Live view source
- Sony Imaging Edge Desktop automation
- gPhoto2
Capture Delay for Sony Camera
This setting specifies the capture delay for Sony cameras when using Sony Imaging Edge Desktop automation as the capture method. Please note that this setting is only visible when the Sony Imaging Edge Desktop automation is selected as the capture method.
Unit: Milliseconds (ms)
Description:
The capture delay is the time delay applied before the photo capture takes place. Sensible values for the capture delay are between 165 ms (for manual focus) and 500 ms.
Capture Delay for gPhoto2 Camera
This setting specifies the capture delay for cameras controlled using gPhoto2 as the capture method. Please note that this setting is only visible when the gPhoto2 is selected as the capture method.
Unit: Milliseconds (ms)
Description:
The capture delay is the time delay applied before the photo capture takes place.
Camera (gPhoto2)
This setting allows you to pick the camera to use for capturing within the photo booth application when gPhoto2 is selected for live view or capture method.
Description:
The “gPhoto2 Camera” setting provides a list of available cameras recognized by the gPhoto2 library. You can select the desired camera to use for capturing live view and still frames.
Use Special Handling for Camera
This setting determines the kind of special handling used for the camera when using gPhoto2 as the capture or live view method. This mostly relates to special vendor-specific operations, such as re-activating live-view for Nikon cameras.
Available Options:
- None
- Nikon DSLR
Capture Location
This setting specifies the location where the photo booth application will look for images captured by an external tool, such as Sony Imaging Edge Desktop.
Note that this is not the same as the location where the output files produced by MomentoBooth are stored. This is in the
Outputsubdirectory of the project folder.
Description:
The “Capture Location” is the folder path where the photo booth application will search for images captured using external tools. This allows the photo booth to access and display images taken separately, for instance, with Sony Imaging Edge Desktop.
Printing
Printers and Print Sizes
Which printers print which print sizes, on what media, with which margins and in which layout is set on the Print routing page.
Use Printer Settings for Native Printers
This setting controls the usePrinterSettings property of the Flutter printing library, which lets the printer driver apply its own settings. It applies to all printer nodes with the Native backend on the Print routing page. This setting is Windows only, and makes a difference on some but not all printers, experiment.
Queue Warning Threshold
This setting specifies the number of photos in the OS’s printer queue before a “Printer queue is long” warning is shown to the user to indicate it may take a while for the picture to appear. This feature is currently only supported on Windows systems.
CUPS server
CUPS URI
The URI of the CUPS server that printer nodes with the CUPS backend print to, e.g. http://localhost:631/ for a CUPS server on the same computer. The CUPS queues and their media sizes shown on the Print routing page are read from this server.
Ignore TLS Errors
Whether to ignore TLS errors when connecting to the CUPS server. This is useful for the self-signed certificates that the CUPS service uses by default.
CUPS Username and Password
The username and password used to log in to the CUPS server, if it requires authentication. Leave them empty otherwise.
Print routing settings
The print routing page decides which printer prints which print size, on what media, with which margins and in which layout. It does so with a small node editor: you place nodes on a canvas and connect them, and every print follows those connections from the print size the user chose to one or more printers. For a step-by-step guide with common set-ups, see the printer setup page.
Like the hardware settings, print routing is an app setting: it is saved with the app’s settings rather than in the project folder. Every change is saved automatically, about half a second after your last edit.
How print routing works
When a user prints a photo, they choose a print size in the print dialog: Normal, Small or Tiny. The print starts at the output of that print size on the source node and follows the connections to the printer nodes it ends up at. On the way it can be distributed over several printers, duplicated, or laid out in a grid.
graph LR
S["Source"] -- Normal --> R["Round-robin"]
R --> P1["Printer A"]
R --> P2["Printer B"]
S -- Small --> T["Tile layout 2×2"]
T --> P3["Printer C"]
A few rules follow from this:
- A print size that is not routed to a usable printer disappears from the print dialog.
- The print button is only shown when the project setting Enable printing is on and the photo can be printed at one of the routed print sizes.
- The Split print size is not a choice in the print dialog. When a user prints a collage of three photos at Normal size and Split is routed, the print follows the Split route instead. When Split is not routed, the Normal route is used. A booth that only offers split prints can route Split alone: collages of three photos then offer Normal, which prints split, and other photos cannot be printed.
- Every copy is routed separately. When a user prints three copies, each copy follows its own route, so a round-robin node can send them to different printers.
- Branches that do not lead to a usable printer for the print size are skipped, so a print never ends up nowhere as long as one route works. When a printer fails while printing, a round-robin node lets its next output print the copy, and a duplicate node still prints on its other outputs. The print only fails when no printer takes a copy.
A new installation starts with a source whose Normal output is connected to a single printer node. That printer still has to be configured before anything can be printed.
The page
The page consists of four parts:
- The toolbar at the top with Undo, Redo and Fit view (which zooms the canvas to show all nodes), followed by a button per node type that adds that node in the middle of the view.
- The canvas with the nodes and their connections.
- The side panel on the right, which lists the routes, the problems and the printer refresh button, see routes, problems and printers.
- The status line at the bottom, which shows a short reminder of the mouse controls, or explains why a connection you are drawing is refused.
Node types
Each node has a coloured header with its name, ports on the left (inputs) and right (outputs), and, depending on the type, some fields. Problems with a node are shown as notes at the bottom of that node.
Source
The source node is where every print starts. It has an output per print size: Normal, Split, Small and Tiny. There is always exactly one source node: it cannot be deleted, copied or duplicated.
Each output takes a single connection. To send a print size to more than one place, connect it to a round-robin or duplicate node. Print sizes that are not routed to any printer are listed in a note on the source node, e.g. Not routed: Split, Tiny. This is information rather than a problem, as not every booth uses every print size.
Round-robin
A round-robin node distributes copies over all its connected outputs in turn: the first copy goes to the first output, the next copy to the second output, and so on. Use it to spread the load over several printers, for example two printers that each print half of the copies.
The node remembers whose turn it is until the print routing is changed or the app is restarted. Outputs that do not lead to a usable printer for the print size at hand are skipped. When the printer whose turn it is fails, the next output prints the copy, and the next copy starts after that output.
Duplicate
A duplicate node sends every copy to all its connected outputs, also when one of their printers fails. Use it to print one photo in several ways at once, for example as a normal print on one printer and as a tiled sheet of small photos on another. The number of copies shown in the print dialog takes this into account.
Round-robin and duplicate nodes have an In port, which takes a single connection, and an Out port, which accepts any number of connections. So such a node handles a single print size; print sizes only come together at a printer. To let two print sizes share the same printers, use a round-robin node for each print size and connect both to the printers. They carry either photos or sheets (see ports and connections), whichever is connected to them. A caption on the node shows what it carries: Carries photos, Carries sheets or Carries nothing yet.
Tile layout
A tile layout node places a photo several times on one sheet, in a grid. It takes a Photo and turns it into a Sheet, both with a single connection. Its fields are:
| Field | Meaning |
|---|---|
| Columns | The number of columns of the grid, at least 1. |
| Rows | The number of rows of the grid, at least 1. |
A tile layout has no size of its own. The grid is laid out on the media of the printer the sheet ends up at, within the margins of that printer: the printable area is divided into columns × rows tiles of equal size. The photo is fitted in each tile as a whole, centred and without cropping, so a tile only shows white space where its shape differs from that of the photo. There is no extra space between the tiles; the collage padding leaves room to cut them apart.
Each photo is turned to fill its tile best: a landscape photo in a portrait tile is turned a quarter turn, a landscape photo in a landscape tile is not. So the grid decides how the photos lie, together with the media. Take, for example, a landscape collage on portrait 4×6“ media (about 100 × 148 mm):
| Grid | Tiles | Photos |
|---|---|---|
| 1 column, 2 rows | 2 tiles of about 100 × 74 mm (landscape) | Lie horizontally, one above the other |
| 2 columns, 1 row | 2 tiles of about 50 × 148 mm (portrait) | Turned a quarter turn, side by side |
| 2 columns, 2 rows | 4 tiles of about 50 × 74 mm (portrait) | Turned a quarter turn |
Because the tiles follow the printer, one tile layout can feed printers with different media. Connected to a round-robin node with a 4×6“ and a 2×6“ printer behind it, the same 1 by 2 grid gives two landscape tiles on the 4×6“ media and two portrait tiles on the 2×6“ media, and the photos are turned to match on each.
The print dialog takes the grid into account: with 2 columns and 2 rows, every copy a user orders gives four photos on one sheet, and the dialog shows that it prints 4 copies at a time.
Split prints are always printed in halves, so a tile layout on the route of the Split print size is not used for them. The editor shows a warning when that happens. A tile layout with fewer than 1 column or row is an error; its connections are ignored.
Margins
A margins node holds a set of margins (top, right, bottom and left, in mm) that can be shared between printer nodes. Its Margins output can be connected to the margins input of any number of printers, so you only have to tune the margins of, say, three identical printers once.
Printer
A printer node is one printer configuration: one printer or CUPS queue with one media size. To print on different media with the same printer, for example 4×6“ for small prints and 2×6“ for tiny prints, add a printer node for each media size with the same printer or queue, and give them a label to tell them apart.
| Field | Meaning |
|---|---|
| Label | A name for this configuration, shown in the node header, the routes overview and the problems list. |
| Backend | Native prints through the operating system’s printers. CUPS prints to a queue on the CUPS server configured in the hardware settings. Changing the backend clears the printer and media, as they mean nothing to the other backend. |
| Printer / Queue | The printer (native) or CUPS queue to print to. The options are listed when the page opens, see Refresh printers. A saved printer that is not available at the moment is shown with (not found). |
| Media / Paper | The media to print on. For a CUPS printer (Media), chosen from the media the selected queue supports. For a native printer on Windows (Paper), chosen from the papers the printer driver supports, e.g. 4x6 (borderless); prints then use exactly that paper and keep the other settings of the driver, such as borderless printing. Papers that share a size, such as with and without border, are told apart. Changing the queue or printer clears the media, as media differ per printer. On macOS and Linux native printers have no Paper field. |
| Size (mm) | The width and height of the media. For CUPS printers and native printers on Windows they follow from the selected media. For native printers on macOS and Linux you enter these yourself; set them to the paper size you print on. |
| Margins | The margins (top, right, bottom and left, in mm) for this printer, see margins. These fields are hidden when a margins node is connected to the margins input; the caption then reads from the connected node. |
A printer node has two inputs. The Job input accepts photos as well as sheets and takes any number of connections. A photo that is connected directly, without a tile layout, is fitted on the sheet as a whole. The Margins input sits next to the margins fields and takes a single margins node.
A printer node only prints once it is complete: a native printer needs a printer and a media width and height; a CUPS printer needs a queue and media. A native printer on Windows whose size was set by hand, e.g. on another computer, still prints as before, without choosing a paper; select a Paper to print on that exact paper. A printer that receives prints while it is incomplete gets a warning and is skipped. So is a printer whose margins leave no room on its media. Unconnected printer nodes are fine, so you can keep configurations around for later use.
Ports and connections
The ports are coloured by what they carry:
| Colour | Type | Meaning |
|---|---|---|
| Blue | Photo | A photo at the print size the user chose. Comes from the source. |
| Orange | Sheet | A photo laid out on a sheet. Comes from a tile layout. |
| Green | Margins | A set of margins. Comes from a margins node. |
The ports of round-robin and duplicate nodes take the colour of what they carry, and are grey while nothing is connected to them yet. The job input of a printer takes the colour of what is connected to it. Connections take the colour of the port they start at.
To connect two nodes, drag from a port to a port of another node. Only matching ports can be connected: the editor refuses a connection that carries the wrong type or that would create a loop, and the status line at the bottom explains why when the colours do not already tell. A round-robin or duplicate node carries a single type, so it cannot mix photos and sheets.
Some ports take a single connection: the outputs of the source, the inputs of round-robin and duplicate nodes, both ports of a tile layout and the margins input of a printer. Connecting a new connection to such a port replaces the old one.
Routes, problems and printers
The side panel to the right of the canvas has three sections:
- Routes lists, per print size, the printers it can end up at by their label (or Unnamed printer), or Not printed when the print size is not routed.
- Problems lists the errors and warnings of all nodes. Click a problem to select and centre its node on the canvas. The same problems are shown as notes on the nodes themselves: red for errors, yellow for warnings.
- Printers has the Refresh printers button. The printers, CUPS queues, media and papers to choose from are listed when the page opens. Refresh them after connecting a printer, starting the CUPS server or changing the CUPS server settings.
Connections with errors are ignored, while the rest of the routing keeps working. The printing subsystem on the subsystem status page stays disabled until a printer is set up: until a printer node has a printer or queue and media, connected or not. It is also disabled when the project setting Enable printing is off. Once a printer is set up, the subsystem shows a warning when the routing has problems, when no print size reaches a configured printer, or when a printer failed during the last print.
| Message | Meaning |
|---|---|
| Select a printer and set the media size to print with it. | A native printer receives prints, but has no printer or media size set. It is skipped. |
| Select a queue and media to print with this printer. | A CUPS printer receives prints, but has no queue or media set. It is skipped. |
| The margins leave no room to print on the media. | The left and right margins together, or the top and bottom margins together, are as large as the media or larger. The printer is skipped. |
| Split prints are always printed in halves, so this layout is not used for them. | A tile layout is on the route of the Split print size. It is still used for the other print sizes. |
| Normal prints are not routed, so only collages of three photos can be printed. | Information on the source: Split is routed, but Normal is not. Photos that are not a collage of three photos cannot be printed. |
| Not routed: … | Information on the source: these print sizes are not routed to any printer and are not offered in the print dialog. |
| This input accepts a single connection. | More than one connection ends at a port that takes a single connection. |
| The connection from … carries the wrong type. | A connection carries photos where sheets are expected, or the other way around. |
| Connections form a loop. | The connections lead back to a node they came from. |
| Only one source is used, this one is ignored. | There is more than one source node. Only the first one routes prints. |
| There is no source node. | The routing has no source, so nothing can be printed. |
| Columns and rows must be at least 1. | A tile layout has an invalid grid. Its connections are ignored. |
| A stored connection is invalid and is ignored. / A connection is stored twice. / Two nodes share the ID “…”. | The saved routing is damaged, for example after editing the settings file by hand or importing settings. |
Editing
The mouse controls are:
| Action | Effect |
|---|---|
| Drag a node | Move the node. |
| Drag from a port | Draw a connection. |
| Right-click the canvas | Add a node at that spot. |
| Right-click a node | Delete the node. |
| Right-click a connection | Delete the connection. |
| Right-click a port | Disconnect all connections of that port. |
| Mouse wheel | Zoom. |
| Middle mouse button, or Space and drag | Pan the canvas. |
The keyboard shortcuts are:
| Shortcut | Effect |
|---|---|
Delete, Backspace | Delete the selected nodes. |
Esc | Clear the selection. |
Ctrl+A | Select all nodes. |
Ctrl+Z | Undo. |
Ctrl+Y, Ctrl+Shift+Z | Redo. |
Ctrl+C, Ctrl+X, Ctrl+V | Copy, cut and paste the selected nodes. |
Ctrl+D | Duplicate the selected nodes. |
| Arrow keys | Move the selected nodes by one grid step. |
Shift + arrow keys | Move the selected nodes by one pixel. |
The shortcuts do not apply while you are typing in a field of a node. The source node is left out when deleting, copying, cutting or duplicating a selection.
How prints are laid out
The printable area of a sheet is the media size of the printer minus its margins. The margins describe the part of the media that ends up visible on the print: increase a margin when the printer cuts off part of the photo on that side, and decrease it when a white border remains.
- Without a tile layout, the photo is fitted in the printable area as a whole, centred and without cropping. It is turned a quarter turn when its orientation does not match that of the area, so a landscape collage on portrait media is printed sideways to use the paper well.
- With a tile layout, the printable area is divided into equal tiles, and the photo is fitted in each tile, turned to fill the tile best, see tile layout.
- Split prints are printed as two pages: the left half of the collage on the first page and the right half on the second. Each half fills the height of the printable area. The margins between the halves (the right margin of the first page and the left margin of the second) are left out, so the halves line up when put together. Tile layouts are not used for split prints.
The last printed sheet is saved as latest-print.pdf in the output folder of the project, which is handy to check the layout without wasting paper. For more detail, turn on Enable extensive print job logging in the debug settings, which keeps the PDFs and details of every print job in a PrintJobs folder inside the output folder. To test the routing without printing at all, turn on Skip sending print jobs to printers in the same settings: prints are routed and rendered as usual, but not sent to a printer, and not counted in the statistics.
Output settings
In the output settings, you can customize the output file generation and sharing of the results.
Local
Output files will be saved to the Output subdirectory of your project folder.
Share using internet
Firefox Send URL
This setting specifies the Firefox Send server URL used to generate a QR code for easy image downloads to your phone using the Firefox Send service.
Image settings
Image File Type
This setting determines the type of image file to generate for image export within the photo booth application.
Available Options:
- JPG
- PNG
Default: JPG
JPG Quality
This setting specifies the export quality for JPG images within the photo booth application. Higher quality values result in larger file sizes, while lower values lead to smaller files with potentially reduced image quality.
Value Range:
Minimum: 1
Maximum: 100
Output Resolution Multiplier
This setting controls the image resolution multiplier within the photo booth application, which in turn controls the image resolution of the exported photos. A factor of 1.0 results in a resolution of 1000 pixels on the long side of the image and 1000/aspect ratio on the short side without padding.
The calculation of the total image height is as follows:resolutionMultiplier * (1000 + collagePaddingSetting * 2)
And the width:resolutionMultiplier * (1000/collageAspectRatioSetting + collagePaddingSetting * 2)
User interface settings
In the user interface settings, you will find settings related to live view, photo capture and printing. Everything related to the hardware the program interfaces with.
Language
This setting allows you to choose the language used for the app’s user interface (except for the settings screen).
Available Options:
- English
- Dutch
- German
Return to Home Timeout
The time in seconds before the app returns to the home screen. Set to 0 to disable.
Unit: Seconds
Default: 45
Animations
Screen Transition Animation
This setting determines the screen transition effect that occurs when navigating between different screens.
Available Options:
- None
- Fade and Scale (default)
- Fade and Slide
Advanced
Background Blur
Sets the background blur implementation. Currently there are no options for this setting except disabling it for testing.
Available Options:
- None
- Use texture blur (default)
Filter Quality for Screen Transitions
This setting controls the filter quality used during the screen transition scale animation.
Available Options:
- None
- Low (default)
- Medium
- High
Filter Quality for Live View
This setting controls the filter quality used for displaying the live view.
Available Options:
- None
- Low
- Medium (default)
- High
Templating settings
In the templating settings, you will find the settings related to the generation of collage images such as template images, shape and padding, resolution. This settings tab conveniently also features a template preview section.
Creative settings
Collage Aspect Ratio
This setting controls the aspect ratio of the generated collage images. Consider this aspect ratio in conjunction with the desired paper print size for optimal results. Typical values are 1.5 for 3/2 photos or the aspect ratio of your paper.
Collage Padding
This setting controls the padding around the aspect ratio of the generated collages images. Consider this padding in conjunction with the desired paper print size for optimal results.
Output Resolution Multiplier
This setting controls the image resolution multiplier within the photo booth application, which in turn controls the image resolution of the exported photos. A factor of 1.0 results in a resolution of 1000 pixels on the long side of the image and 1000/aspect ratio on the short side without padding.
The calculation of the total image height is as follows:resolutionMultiplier * (1000 + collagePaddingSetting * 2)
And the width:resolutionMultiplier * (1000/collageAspectRatioSetting + collagePaddingSetting * 2)
The above setting is repeated from output settings.
Template preview
The template preview section allows you to quickly check if your designed template images give the desired results. A placeholder image is inserted for every field that will contain user captures during operation.
Using the buttons you can select which collage type you want to see (no selection, 1, 2, 3, 4 photos) and export the result for further inspection. The background and foreground layers of the collage can be toggled on and off to see the individual effect of those layers, or for generating a clean and transparent reference to design around (see note below).
Please note that exporting generates the file type specified in the output settings. Select
pngfor file type if you want lossless images or transparency.
The red border shown in the preview is the printing padding added “collage padding” setting. If set correctly this will not be visible/cut-off on the print. The white border is the standard gap present for the collage grid. The section also shows the template files that are selected for the selected collage after searching the template directory.
To refresh the templates, switch to another settings tab and back.
MQTT integration settings
This settings panel allows setting up the MQTT integration feature.
If the integration is enabled, the application will publish MQTT messages to the specified broker and will subscribe for commands.
Connection
This section contains all settings related to the connection with and authentication for your MQTT broker. Set these up according to your broker settings.
Client
These settings specify the publication topic and client ID.
Home Assitant integration
Integration with Home Assistant is available, so automations can be created that respond to the state of the app in real time. Settings are available for the discovery topic (usually homeassistant), and the device ID.
Face recognition settings
This experimental feature uses the Python Image Analyzer to analyze the captured images/collage to allow easier sorting in the gallery by number of people in the picture and search for a picture by matching a face.
Subsystem status
This settings tab contains an overview to quickly check for and solve any issues that may arise in the functionality of the app. For this purpose, the status of each subsystem is shown, which can either be busy, ok, disabled, warning, error, or deferred. When a problem arises, the subsystem may present actions/fixes in through buttons to resolve the situation.
Statistics & Debug settings
In the statistics and debug settings panel, you will find fun statistics about app usage and some debug-related settings.
Statistics
The app keeps track of the following statistics:
-
Taps The number of taps in the app (outside settings).
-
Live view frames The number of live view frames processed from the start of the camera. Value shows: Valid frames / Undecodable frames.
-
Printed pictures The number of prints (e.g. 2 prints of the same pictures will count as 2 as well).
-
Uploaded pictures The number of uploaded pictures.
-
Captured photos The number of photo captures (e.g. a multi-capture picture would increase this by 4).
-
Created single shot pictures The number of single-capture pictures created.
-
Retakes The number of retakes for (single) photo captures.
-
Created multi shot pictures The number of multi-shot pictures created.
Debug
Report Fake Error
This button allows you to test the error reporting functionality. When you click the “Report Fake Error” button, the application will intentionally throw an exception, generating a fake error that will be reported to Sentry.
Log panel
The log panel simply displays the log that is also printed in the debug console to enable viewing the log in the field. The log shows the log level, time, message, and component.
Setup
Stack
- Languages: Dart, Rust, C++ (Windows, Linux), Swift (macOS)
- Dart <-> Rust glue: flutter_rust_bridge
- UI: Flutter
- Webcam: Nokhwa
- Printing: Printing
- Logging: Talker
- Data classes: Freezed
- Firefox Send client: ffsend-api
- JPEG decoding: zune-jpeg, encoding: jpeg-encoder
Requirements
For all languages, frameworks and tools, we support the latest versions.
For all platforms
-
flutter_rust_bridge_codegen-
Install using Cargo:
cargo install flutter_rust_bridge_codegen --version 2.13.0
-
-
cargo-bundle-licenses, used to collect the licenses of the Rust dependencies for the About screen-
Install using Cargo:
cargo install cargo-bundle-licenses --version 4.2.0
-
-
Flutter SDK 3.47.0+
- Be sure that the
fluttercommand is available globally asflutter_rust_bridge_codegenneeds it.
This is especially important when using Flutter SDK managers likeasdforfvm
- Be sure that the
-
Optional: For building the documentation mdBook and some extensions for mdBook are needed
-
Install using Cargo:
cargo install mdbook mdbook-mermaid
-
-
Be sure to read the docs for troubleshooting and workarounds
On Windows
- Visual Studio 2026 Build Tools
- Optional: full Visual Studio 2026 installation
- Select Desktop development with C++ under the Workloads tab
- Under installation details on the right panel, select the MSVC Build Tools, Windows 11 SDK, and C++ ATL (needed for Flutter secure storage plugin)
- Rust
- Recommended installation via
rustupto keep components up to date - Use default options (MSVC host, target, and toolchain)
- Recommended installation via
- LLVM, needed by bindgen to generate the Rust bindings for libgphoto2
- Install using
winget install LLVM.LLVM, or with the installer from the LLVM releases - If LLVM is not installed in the default location, set
LIBCLANG_PATHto the folder containinglibclang.dll
- Install using
- libgphoto2 and its dependencies are downloaded prebuilt from momentobooth/native-deps by
just get-native-deps(or runwindows/get_native_deps.ps1directly)- This also writes
.cargo/config.toml, which points Cargo to the downloaded libraries - The Windows build copies the libraries next to the executable, so no
PATHchanges are needed
- This also writes
On macOS
-
A Mac with Apple Silicon running macOS 15 or newer, Intel Macs are not supported
- The Xcode project and the Rust plugin exclude
x86_64(EXCLUDED_ARCHS), soflutter build macosonly builds for Apple Silicon
- The Xcode project and the Rust plugin exclude
-
Xcode
- Installing from the App Store is recommended (automatic updates)
-
Rust (
aarch64-apple-darwin) -
pkgconf, used by the Rust build scripts to find libgphoto2
-
Install with
brew install pkgconf
-
-
libgphoto2 and its dependencies are downloaded prebuilt from momentobooth/native-deps by
just get-native-deps(or runmacos/get_native_deps.shdirectly)- This also writes
.cargo/config.toml, which points Cargo to the downloaded libraries - The Xcode build copies the libraries into
MomentoBooth.app/Contents/Libs, for debug builds too, so a Homebrew installation of libgphoto2 is not needed and not used - The minimum macOS version is that of the downloaded libraries, see the native-deps README
- This also writes
-
Code signing certificates
- Both debug and release builds need a certificate and provisioning profile from the MomentoBooth certificates repository, see Code signing on macOS
On Linux
-
System packages
- See the Flutter documentation for a list of required packages
- Note: the installation command provided by Flutter may only work on Ubuntu — check your distro’s package names
-
Additional packages
llvm libssl-dev libdigest-sha-perl libcurl4-openssl-dev libasound2-dev libgphoto2-dev libsecret-1-dev libusb-1.0-0-dev liblzma-dev -
Rust (
x86_64-unknown-linux-gnuoraarch64-unknown-linux-gnu, depending on your architecture)- Recommended installation via
rustup
- Recommended installation via
Build steps
Using just (recommended)
Please note: This method expects global fvm to be available and just.
- Run
justfrom the root folder of the repository - Run
flutter runor use your IDE to run the application
Manually
Please note: Run all commands from the root folder of the repository, unless mentioned otherwise.
-
On Windows and macOS, download the native dependencies.
./windows/get_native_deps.ps1./macos/get_native_deps.sh -
Generate translation files.
flutter gen-l10n -
Generate Rust <-> Dart code
flutter_rust_bridge_codegen generate- Note: Make sure to re-run this command if you changed anything in the Rust subproject.
-
Generate Dart helper code
dart run build_runner build -
Generate the open source license overview (optional, the About screen shows a notice when it is missing)
dart run tool/generate_licenses.dart- Note: The toolchain and bundled native libraries are maintained by hand in
licenses/manual_licenses.toml. On Windows and macOS,libgphoto2and its dependencies are taken from the manifest of the downloaded native dependencies instead.
- Note: The toolchain and bundled native libraries are maintained by hand in
-
Build and run the app with
flutter runor use your IDE to run the application- Note: This will automatically build the Rust subproject before building the Flutter project, so no need to worry about that!
Linux Flatpak
Linux releases are distributed as a Flatpak, built from linux/packaging/flatpak/io.github.momentobooth.MomentoBooth.yml. The whole build runs inside the GNOME SDK, so the application is built against the same libraries (glibc, GTK) as it runs with, independent of the build machine. No development environment is needed on the host, only Flatpak with the Flathub repository.
-
Install flatpak-builder and the SDK with its extensions (once):
flatpak install --user flathub org.flatpak.Builder org.gnome.Sdk//51 org.gnome.Platform//51 org.freedesktop.Sdk.Extension.rust-stable//26.08 org.freedesktop.Sdk.Extension.llvm22//26.08 -
Build and install the Flatpak, from the root folder of the repository:
flatpak run org.flatpak.Builder --user --install --force-clean --disable-rofiles-fuse build/flatpak linux/packaging/flatpak/io.github.momentobooth.MomentoBooth.yml -
Run it with
flatpak run io.github.momentobooth.MomentoBooth.
To install the result on another machine, export a single-file bundle with flatpak build-bundle --runtime-repo=https://flathub.org/repo/flathub.flatpakrepo ~/.local/share/flatpak/repo MomentoBooth.flatpak io.github.momentobooth.MomentoBooth.
Notes on the manifest:
libgphoto2is built as a module with the same options as the prebuilt native dependencies of Windows and macOS. Its dependencies (libusb,libexif,libltdl) are part of the runtime.- The build tools (
flutter_rust_bridge_codegen,cargo-expand,cargo-bundle-licenses) and the Flutter SDK are separate modules, which flatpak-builder caches in.flatpak-builder/between builds and leaves out of the result. Only the application module is rebuilt when the sources change. - The build downloads pub packages, crates and the Flutter engine artifacts, so it needs network access. This is fine for self-hosted bundles, but not allowed on Flathub.
- Cargokit runs
cargothroughrustup, which the SDK does not have.linux/packaging/flatpak/rustupis a minimal stand-in for the calls it makes. - The CI writes the Sentry configuration to
linux/packaging/flatpak/dart-defines.json(not committed), which the build passes toflutter buildwhen it exists. --disable-rofiles-fuseis needed because flatpak-builder runs as a Flatpak itself, in which FUSE is not available.
libgphoto2 driver locations
Camera support in libgphoto2 is split into separate driver libraries, which it loads at runtime: camera drivers (camlibs, e.g. ptp2) and port drivers (iolibs, e.g. usb1). Each type is loaded from its own directory, which libgphoto2 determines as follows:
- If the environment variables
CAMLIBSandIOLIBSare set, it uses those directories. - Otherwise it uses the directories that were configured when
libgphoto2itself was compiled, e.g./usr/lib/x86_64-linux-gnu/libgphoto2/2.5.33. These only exist on the machine wherelibgphoto2was installed to that location, so this only works for a system-wide installation, not for a copy oflibgphoto2that is bundled with the application.
Release builds of MomentoBooth bundle
libgphoto2with its drivers.libgphoto2must be pointed to those bundled driver directories through the environment variables. MomentoBooth can do this itself: when the Dart definesIOLIBSandCAMLIBSare set at build time (--dart-define IOLIBS=... --dart-define CAMLIBS=...), or on Windows and macOS by default, the app resolves these paths relative to the executable’s directory and sets the environment variables of its own process before initializinglibgphoto2. The directories must exist, otherwise initializing gPhoto2 fails.
| Platform | Release builds | Development |
|---|---|---|
| Windows | Built-in default in the app, no Dart defines needed: libgphoto2_iolibs and libgphoto2_camlibs next to the executable. windows/CMakeLists.txt copies them there from .native_deps\windows-x64 (see just get-native-deps). | Same as release builds, as libgphoto2 is bundled in development too. The drivers end up in build\windows\x64\runner\Debug. |
| macOS | Built-in default in the app, no Dart defines needed: ../Libs/Iolibs and ../Libs/Camlibs, relative to MomentoBooth.app/Contents/MacOS. The Xcode build phase Embed native dependencies (macos/embed_native_deps.sh) copies them there from .native_deps/macos-arm64 (see just get-native-deps). | Same as release builds, as libgphoto2 is bundled in development too. The drivers end up in build/macos/Build/Products/Debug/MomentoBooth.app/Contents/Libs. |
| Linux | Nothing needed: the Flatpak manifest builds libgphoto2 with prefix /app, so its compiled-in directories (/app/lib/libgphoto2/<version> and /app/lib/libgphoto2_port/<version>) are where the drivers are inside the Flatpak. | Nothing needed, the system-wide installation of libgphoto2 uses its compiled-in directories. |
When Dart defines are set on Windows or macOS, they take precedence over the built-in default. Because the app always sets the environment variables on these platforms, setting IOLIBS or CAMLIBS yourself has no effect there.
Code signing on macOS
The macOS Xcode project uses manual code signing, so both debug and release builds need a certificate and a provisioning profile that are not part of this repository:
| Build configuration | Certificate | Provisioning profile |
|---|---|---|
Debug & Profile (flutter run) | Apple Development | match Development com.momentobooth.photobooth macos |
Release (flutter build macos) | Developer ID Application | match Direct com.momentobooth.photobooth macos |
These are shared through the private MomentoBooth certificates repository and are installed with fastlane match. You need read access to that repository — ask a maintainer if you do not have it.
One-time setup
-
Install the Ruby dependencies (this installs fastlane in the version this repository is tested with):
bundle install -
Copy
.env.exampleto.envin the root of the repository and fill in the values:MATCH_CERTIFICATES_GIT_URL=git@github.com:momentobooth/certificates.git MATCH_CERTIFICATES_GIT_FULL_NAME="Your Full Name" MATCH_CERTIFICATES_GIT_EMAIL=you@yourdomain.com APP_STORE_CONNECT_KEY_ID=ABCD123456 APP_STORE_CONNECT_ISSUER_ID=00000000-0000-0000-0000-000000000000 APP_STORE_CONNECT_KEY=base64-of-the-AuthKey_ABCD123456.p8-file- fastlane automatically picks up the
.envin the root of the repository .envis git ignored — never commit it- The match passphrase is not part of this file: fastlane asks for it the first time you run one of the lanes below and stores it in your macOS Keychain, so you only have to enter it once — ask a maintainer for it
- The App Store Connect API key values are the same ones CI uses, see On CI for where they come from — ask a maintainer rather than creating a second key
- fastlane automatically picks up the
-
Make sure the SSH key of your machine has access to the certificates repository (
ssh -T git@github.comshould greet you by name).
Installing the certificates
bundle exec fastlane install_dev_cert # needed to run debug builds
bundle exec fastlane install_release_cert # needed to make release builds
If you have fastlane installed globally, you can leave out the bundle exec prefix.
Both lanes authenticate with the App Store Connect API key, so they never ask you to log in interactively. They install what is in the certificates repository into your login keychain, and create or renew a certificate when the repository does not hold a valid one.
Certificates land in your login keychain, provisioning profiles in ~/Library/Developer/Xcode/UserData/Provisioning Profiles. To check what you have installed:
security find-identity -v -p codesigning
When a certificate has expired
install_dev_cert renews an expired development certificate by itself: it deletes the old one from the certificates repository, creates a new one, and pushes it back, so everybody else only has to run the lane again.
Renewing the Developer ID certificate can not be done this way. Apple only allows that with an Account Holder Apple ID (username and password), an API key does not have enough access for that certificate type. Apple also limits how many Developer ID certificates a team can have, so check with the other maintainers first, then run:
bundle exec fastlane match developer_id --renew_expired_certs true
Note that renewing does not revoke the old certificate on the Apple Developer portal, so it keeps occupying a certificate slot of the team. Use fastlane match nuke development to free slots up, but be careful: that revokes certificates for the whole team.
Troubleshooting
Service key is empty / Could not receive latest API key from App Store Connect
Apple removed the endpoint that fastlane uses to start an Apple ID login (https://appstoreconnect.apple.com/olympus/v1/app/config answers 404), which breaks every interactive login, including fastlane spaceauth. The lanes above avoid it by using the API key.
If you do need an interactive login, hand fastlane the key it cannot fetch itself — it uses the contents of this file when it exists:
printf '%s' '<authServiceKey>' > /tmp/spaceship_itc_service_key.txt
You can read that value from your browser: open App Store Connect, sign out, and in the network tab of the developer tools look up the X-Apple-Widget-Key request header of the call to idmsa.apple.com/appleauth/auth/signin.
Release builds and notarization
macOS only starts a downloaded app without warnings when Apple has notarized it: Apple scans the signed app and registers a ticket for it. The ticket is then stapled to the app and to the dmg, so that Gatekeeper also accepts them on a Mac without an internet connection.
The Xcode build of the Release configuration produces a signature that Apple accepts for this, through three build settings of the Runner target:
| Build setting | Effect |
|---|---|
ENABLE_HARDENED_RUNTIME = YES | Enables the hardened runtime, which notarization requires |
OTHER_CODE_SIGN_FLAGS = --timestamp | Gives every signature a secure timestamp. The scripts that embed the frameworks and the native dependencies (macos/embed_native_deps.sh) use this setting as well |
CODE_SIGN_INJECT_BASE_ENTITLEMENTS = NO | Keeps Xcode from adding the get-task-allow debugging entitlement, which notarization rejects |
Things to keep in mind:
- Do not change or re-sign the app bundle after the build. Signing it again without its entitlements removes them, after which the Keychain (secure storage) no longer works.
- With the hardened runtime, access to a protected resource needs an entitlement in
macos/Runner/Release.entitlements, like the one for the camera. Debug builds do not use the hardened runtime, so a missing entitlement only shows up in a release build. macos/ci_notarize.sh <app bundle or dmg>notarizes and staples. It uses the App Store Connect API key from the same environment variables as fastlane.- To check a build:
spctl -a -vv MomentoBooth.appprintsacceptedwithsource=Notarized Developer ID.
On CI
The release workflow builds the app, notarizes it, puts it in a dmg, and signs and notarizes the dmg. As notarization takes Apple 10 to 15+ minutes per submission, the PR CI workflow only notarizes when it is started manually (Run workflow in the Actions tab).
CI uses the ci_install_release_cert_using_api lane, which is the same as install_release_cert but additionally runs setup_ci to install everything into a temporary keychain. Do not run that lane on your own machine — the temporary keychain disappears again, and the certificates will not be where Xcode expects them.
Its secrets are configured on the repository in GitHub. The App Store Connect API key values come from App Store Connect → Users and Access → Integrations → App Store Connect API → Team Keys:
| Variable | Where to find it |
|---|---|
APP_STORE_CONNECT_KEY_ID | The Key ID column of the key (10 characters) |
APP_STORE_CONNECT_ISSUER_ID | The Issuer ID shown above the table |
APP_STORE_CONNECT_KEY | The downloaded .p8 file, base64 encoded: base64 -i AuthKey_XXXXXXXXXX.p8 |
Note that Apple only lets you download the .p8 file once, at the moment the key is created.
CUPS integration tests
The functions that print through a CUPS server (rust/src/api/cups.rs) are tested against a real CUPS server in Docker, so that changes to the IPP code or an update of the ipp crate are verified without a printer. The server is the ydkn/cups image, in which test/cups/setup.sh creates a paused queue MomentoBoothTest with the driver of a DNP DS620 photo printer. Jobs stay in the paused queue, so no device is needed.
Run them with Docker running:
just test-cups
This starts the server on port 6310 and runs the Rust tests (cargo test --lib) with the CUPS_TEST_URI, CUPS_TEST_USERNAME and CUPS_TEST_PASSWORD environment variables. Without CUPS_TEST_URI, the CUPS tests return immediately, so a plain cargo test does not need Docker. The server keeps running afterwards; its web interface is at http://localhost:6310 (user admin, password momentobooth), and docker rm -f momentobooth-cups-test removes it.
On CI, the workflow pr-ci-cups.yml runs the tests on pull requests that change rust/ or test/cups/.
Developing tips
When to re-run build steps
- If you have changed any code in the Dart or Rust project that could change the generated bridging code, you should re-run the
flutter_rust_bridge_codegen generateorjust gen-bridgecommand- You can also run
flutter_rust_bridge_codegen generate --watchorjust watch-bridgeto automatically regenerate the bridging code when you save a file - You might need to run
dart run build_runner build --delete-conflicting-outputsorjust gen-code
- You can also run
- If you have changed any code related to JSON or TOML serialization, or MobX, you should re-run the
dart run build_runner build --delete-conflicting-outputsorjust gen-codecommand- You can also run
dart run build_runner watch --delete-conflicting-outputsorjust watch-codeto automatically regenerate the code when you save a file
- You can also run
- If you have changed any code related to the localization, you should re-run the
flutter gen-l10nofjust gen-l10ncommand
Adding a new screen using the VS Code extension Template
- Make sure to have the Template extension installed
- Right click the
viewsfolder in VS Code Explorer - Click Template: Create New (with rename), pick the
viewtemplate - Pick a name, enter it in
{snake_case}_screenformat (e.g.settings_screenoremail_photo_screen), press Enter - Your new view should be available!
Widget overview
This page catalogs every reusable Flutter widget in lib/, grouped by folder. Check this list before adding a new widget — a similar one may already exist.
There is no lib/widgets/ directory. Widgets live under lib/views/, either in the generic, app-wide lib/views/components/ tree, or in a screen-local components/ subfolder next to the screen that uses them.
Each line follows the format path — WidgetClassName — description, to keep this page easy to grep.
Folders
lib/views/- components/ — generic, app-wide widgets with no screen-specific dependency.
- animations/ — reusable fade/rotate/Lottie animation wrappers.
- buttons/ — generic dialog-style buttons.
- config/ — widgets that adapt behavior to app configuration/settings.
- content/ — widgets that render document content such as Markdown.
- dialogs/ — generic modal dialogs used across the app.
- imaging/ — image/camera rendering and transform widgets.
- indicators/ — small status/progress indicator widgets.
- transitions/ — page-transition animation widgets.
- base/ — MVVM screen base classes and routing-page infrastructure.
- onboarding_screen/components/ — chrome for the first-run onboarding wizard.
photo_booth_screen/- components/ — top-level wrappers for the main booth screen (activity tracking, scaling, FPS overlay).
screens/- components/buttons/ — themed booth action/navigation button.
- components/text/ — auto-sizing themed title/subtitle text.
- gallery_screen/components/ — gallery-screen-local toolbar widgets.
- theme/*/components/ — decorative widgets specific to one visual theme.
settings_overlay/- components/ — chrome for the settings overlay (pages, sections, dialogs).
- components/settings/ — one row-widget per setting type, plus the “quick actions” grid buttons.
- components/print_routing_editor/ — node editor for the print routing graph.
- components/ — generic, app-wide widgets with no screen-specific dependency.
- Menus / app-level widgets — top-level
lib/widgets outside theviews/tree. - Known near-duplicates / naming overlaps — intentional or confusable look-alike widgets to check before adding a new one.
lib/views/components/
Generic, app-wide widgets with no screen-specific dependency.
lib/views/components/qr_code.dart—QrCode— renders a QR code of givendata/size.lib/views/components/cvs_simulation_filter.dart—CvsSimulationFilter— wrapschildin color filters to simulate color-vision deficiency.
lib/views/components/animations/
Reusable fade/rotate/Lottie animation wrappers.
animated_delayed_fade_in.dart—AnimatedDelayedFadeIn— fades inchildafter a configurable delay.fading_text_swticher.dart—FadingTextSwitcher— cycles through a list of strings with a fade + auto-resize animation.lottie_animation_wrapper.dart—LottieAnimationWrapper— overlays positioned/rotated Lottie animations on top ofchild.pulsating_opacity.dart—PulsatingOpacity— continuously fadeschildbetween a min and max opacity (e.g. a blinking “recording” dot).repeating_indicator.dart—RepeatingIndicator— periodically shows a Lottie animation at a random position (idle attention-grabber).rotating_collage_box.dart—RotatingCollageBox— animates rotation of a collage widget when theturnsprop changes.
lib/views/components/buttons/
Generic dialog-style buttons.
photo_booth_filled_button.dart—PhotoBoothFilledButton— dialog-style filled button with optional icon + title.photo_booth_outlined_button.dart—PhotoBoothOutlinedButton— outlined variant ofPhotoBoothFilledButton.
Note: these are generic dialog buttons, not the same as
PhotoBoothButtoninphoto_booth_screen/screens/components/buttons/(themed booth action/nav button). Three “PhotoBooth*Button” widgets exist across the codebase — pick carefully.
lib/views/components/config/
Widgets that adapt behavior to app configuration/settings.
set_scroll_configuration.dart—SetScrollConfiguration— wrapschildin aScrollConfigurationthat conditionally allows mouse-drag scrolling.
lib/views/components/content/
Widgets that render document content.
markdown_view.dart—MarkdownView— renders Markdown (viaflutter_markdown_plus) with a Fluent UI style sheet, opening links in the browser.
lib/views/components/dialogs/
Generic modal dialogs used across the app.
enter_pin_dialog.dart—EnterPinDialog— numeric keypad dialog for entering a PIN code.find_face_dialog.dart—FindFaceDialog— live view + countdown to capture a face photo for face-recognition lookup.gphoto2_camera_warning_dialog.dart—GPhoto2CameraWarningDialog— SD-card corruption warning shown the first time a camera model is selected for gPhoto2;confirmIfNeeded()also remembers confirmed models.language_choice_dialog.dart—LanguageChoiceDialog— dialog listing available languages to pick.loading_dialog.dart—LoadingDialog— generic loading dialog (.generic()spinner,.cameraDownload()Lottie).modal_dialog.dart—ModalDialog— base styled modal container (title, body, type icon, actions), builds onPhotoBoothDialog. Used by most other dialogs.no_project_open_dialog.dart—NoProjectOpenDialog— shown when no project is open, lists recent projects.photo_booth_dialog.dart—PhotoBoothDialog— lower-level rounded-card dialog shell (width/height/title/indicator/body/actions), used underneathModalDialog.printer_issue_dialog.dart—PrinterIssueDialog— reports a stuck/failed printer with stuck-job list and resume/ignore actions.printing_error_dialog.dart—PrintingErrorDialog— generic printing error dialog with Lottie animation; says so when some prints may have started.print_dialog.dart—PrintDialog— choose print size (only those the photo can be printed at) and copy count; also exportsPrintSizeChoice.qr_share_dialog.dart—QrShareDialog— upload progress + QR code for sharing photos.retake_dialog.dart—RetakeDialog— confirm delete/keep a photo before retaking.settings_import_dialog.dart—SettingsImportDialog— preview settings-import diffs before applying.
Note:
ModalDialogvsPhotoBoothDialog— two layered generic dialog shells.ModalDialogis the one most feature dialogs should build on;PhotoBoothDialogis the lower-level shell it wraps.
lib/views/components/imaging/
Image/camera rendering and transform widgets.
image_with_loader_fallback.dart—ImageWithLoaderFallback— image loader with placeholder/fallback while decoding,.memory()/.file()constructors, optional rotate/flip/crop.live_view.dart—LiveView— renders the live camera-preview texture with rotate/flip/crop, overlay image and filter settings; animates the crop aspect ratio to 16:9 while the recording layout is active.live_view_background.dart—LiveViewBackground— conditionally shows a blurred/live camera feed as a full-screen background depending on route/settings.photo_collage.dart—PhotoCollage— renders a full photo collage (background/middle/foreground layers, logo, layout) from captured photos.quote_collage.dart—QuoteCollage— receipt-width (576 px) column with a recording snapshot, the transcript summary and an optional separator template;QuoteCollageState.getCollageImage()screenshots it for the receipt printer.rotate_flip_crop.dart—RotateFlipCrop— applies rotate/flip/aspect-ratio crop transforms to achild.
lib/views/components/indicators/
Small status/progress indicator widgets.
capture_counter.dart—CaptureCounter— animated countdown-number display before/during capture.connection_state_indicator.dart—MqttConnectionStateIndicator— small colored dot for MQTT connection state.onboarding_version_info.dart—OnboardingVersionInfo— app/Flutter/Rust version info footer.subsystem_status_display.dart—SubsystemStatusDisplay— expandable tile with a subsystem’s status/message/recovery actions.subsystem_status_icon.dart—SubsystemStatusIcon— maps aSubsystemStatusto a colored icon.subsystem_status_list.dart—SubsystemStatusList— observable list ofSubsystemStatusDisplaytiles.time_counter.dart—TimeCounter— elapsed-time display (mm:ss:mmm, animated digits) counting up totargetDuration; started viaTimeCounterState.startTimer().
lib/views/components/transitions/
Page-transition animation widgets.
fade_and_scale_transition.dart—FadeAndScaleTransition— page-transition: fade + scale in/out.fade_and_slide_transition.dart—FadeAndSlideTransition— page-transition: fade + horizontal slide in/out.
Both are theme-selectable variants consumed by transition_page.dart.
lib/views/base/
MVVM screen base classes and routing-page infrastructure.
full_screen_dialog.dart—FullScreenPopup— rounded, shadowed container used as full-screen popup chrome.screen_base.dart—ScreenBase<TViewModel, TController, TView>— abstract baseStatefulWidgetfor the app’s MVVM screen pattern.photo_booth_dialog_page.dart—PhotoBoothDialogPage<T>— routing page with blur+fade+scale transition for dialog routes.transition_page.dart—TransitionPage— routing page providing themed screen-transition animations (delegates to the twoFadeAnd*Transitionwidgets above).
lib/views/onboarding_screen/components/
Chrome for the first-run onboarding wizard.
onboarding_wizard.dart—OnboardingWizard— acrylic-panel chrome wrapper for onboarding wizard content.wizard_page.dart—WizardPage— standard onboarding wizard page layout with back/next navigation.
lib/views/photo_booth_screen/components/
Top-level wrappers for the main booth screen (activity tracking, scaling, FPS overlay).
activity_monitor.dart—ActivityMonitor— tracks user (in)activity, triggers timeout/return-to-home navigation.app_scaler.dart—AppScaler— scaleschilduniformly to fit the window relative to a fixed 1920x1080 target resolution.framerate_monitor.dart—FramerateMonitor— conditionally overlays an on-screen FPS counter based on debug settings.
lib/views/photo_booth_screen/screens/components/buttons/
Themed booth action/navigation button.
photo_booth_button.dart—PhotoBoothButton— themed booth action/navigation button,.action()/.navigation()constructors, wrapsAutoSizeTextAndIcon.
lib/views/photo_booth_screen/screens/components/text/
Auto-sizing themed title/subtitle text.
auto_size_text_and_icon.dart—AutoSizeTextAndIcon— text (optionally with icon) that auto-sizes to fit its box.photo_booth_subtitle.dart—PhotoBoothSubtitle— themed subtitle text usingAutoSizeTextAndIcon.photo_booth_title.dart—PhotoBoothTitle— themed title text usingAutoSizeTextAndIcon.
lib/views/photo_booth_screen/screens/gallery_screen/components/
Gallery-screen-local toolbar widgets.
filter_bar.dart—FilterBar— gallery toolbar with sort-order chooser and “find my face”/clear-filter buttons.filter_choice.dart—FilterChoice— segmented button to choose gallery sort order.
lib/views/photo_booth_screen/theme/*/components/
Decorative widgets specific to one visual theme.
theme/hollywood/components/hollywood_stars.dart—HollywoodStars— animated twinkling-stars background.theme/wedding/components/wedding_wreath.dart—WeddingWreath— animated rotating Lottie wreath decoration.
lib/views/settings_overlay/components/
Chrome for the settings overlay (pages, sections, dialogs).
aspect_ratio_preview.dart—AspectRatioPreview— small bordered box previewing a given aspect ratio.external_system_check_edit_dialog.dart—ExternalSystemCheckEditDialog— create/edit an external system health check.external_system_check_tile.dart—ExternalSystemCheckTile— expandable tile for an external system health check.openai_endpoint_edit_dialog.dart—OpenAiEndpointEditDialog— create/edit an OpenAI-compatible endpoint (name, base URL, API key).openai_endpoint_tile.dart—OpenAiEndpointTile— tile for an OpenAI-compatible endpoint, showing whether an API key is stored.open_source_licenses_expander.dart—OpenSourceLicensesExpander— About-page expander listing third-party licenses as compact tables (name, version, license) in lazily built groups; clicking a row opens a dialog with the license text.import_field.dart—MyDropRegion— drag-and-drop / clipboard-paste region for importing a TOML settings file. (Placeholder-style name — actually settings-import specific, not a generic drop region.)settings_list_page.dart—SettingsListPage— settings page variant rendering a scrollable list of setting “blocks”.settings_page.dart—SettingsPage— base settings-page chrome (title, scroll-shadowed body, “auto-saved” info bar);SettingsPage.fixedfills the space with a non-scrolling body instead.settings_section.dart—SettingsSection— titled vertical group wrapper for a list of setting widgets.update_secret_dialog.dart—UpdateSecretDialog— enter/save a new secret value (API key/password).
lib/views/settings_overlay/components/print_routing_editor/
The fl_nodes_v2 node editor for the print routing graph on the “Print routing” settings page.
print_routing_editor.dart—PrintRoutingEditor— node canvas with toolbar, Fluent context menus and keyboard shortcuts, a side panel listing the routes per print size and the problems, and a status line explaining refused connections.print_routing_node_card.dart—RoutingNodeCard— body of one node: header, port labels coloured by type, Fluent fields (incl. queue and media combo boxes for CUPS queues and for native printers that list their papers, inline printer margins) and notes; its rows followRoutingNodeLayout.
lib/views/settings_overlay/components/settings/
One row-widget per setting type, plus the “quick actions” grid buttons.
All settings tiles are built on settings_tile.dart — SettingsTile (base card row: icon, title, subtitle, trailing control):
settings_action_tile.dart—SettingsActionTile— button that triggers an action.settings_color_pick_tile.dart—SettingsColorPickTile— color swatch that opens a color picker.settings_combo_box_tile.dart—SettingsComboBoxTile<TValue>— dropdown/combo-box selector.settings_file_select_tile.dart—SettingsFileSelectTile— file-picker field (optionally clearable).settings_folder_select_tile.dart—SettingsFolderSelectTile— folder-picker field.settings_number_edit_tile.dart—SettingsNumberEditTile<T extends num>— numeric stepper/edit field.settings_password_edit_tile.dart—SettingsPasswordEditTile— password-style masked text field.settings_secret_edit_tile.dart—SettingsSecretEditTile— button openingUpdateSecretDialogto set a secure-storage secret.settings_text_display_tile.dart—SettingsTextDisplayTile— read-only pill/badge-styled text value, built onsettings_value_chip.dart.settings_text_edit_tile.dart—SettingsTextEditTile— plain text edit field.settings_toggle_tile.dart—SettingsToggleTile— boolean on/off toggle switch.settings_tree_view_tile.dart—SettingsTreeViewTile<TValue>— multi-select tree view of items.
Standalone (no SettingsTile wrapper), used to display a read-only value, e.g. by settings_text_display_tile.dart or directly for multi-value rows like the statistics page:
settings_value_chip.dart—SettingsValueChip— read-only pill/badge-styled text value, with an optional override for its (default accent-colored) background color.
Outside the tile family (no SettingsTile wrapper), for the “quick actions” grid:
quick_action.dart—QuickAction— large icon+label outlined button.quick_toggle.dart—QuickToggle— large icon+label toggle button.
Menus / app-level widgets
Top-level lib/ widgets outside the views/ tree.
lib/views/photo_booth_screen/photo_booth.menu.dart—MomentoMenuBar— top application menu bar (File/recent projects/etc.).lib/widgetbook.dart—WidgetbookApp— root widget for the separate Widgetbook component-catalog dev tool (not part of the main app UI).
Known near-duplicates / naming overlaps
These exist on purpose but are easy to confuse — read the note before adding a new one:
PhotoBoothFilledButton/PhotoBoothOutlinedButton(generic dialog buttons) vsPhotoBoothButton(themed booth-screen action/nav button) — three different “PhotoBooth*Button” widgets, not interchangeable.ModalDialogvsPhotoBoothDialog—ModalDialogis the higher-level shell most dialogs should use;PhotoBoothDialogis the lower-level shell it wraps.FadeAndScaleTransitionvsFadeAndSlideTransition— parallel theme-selectable page-transition effects, same constructor shape.PhotoBoothTitlevsPhotoBoothSubtitle— intentional theme-driven pair, same shape.QuickActionvsQuickToggle— intentional button/toggle pair, same visual shape.MyDropRegion(settings_overlay/components/import_field.dart) has a generic/placeholder name but is specific to TOML settings import — don’t assume it’s a general-purpose drop target.CaptureCountervsTimeCounter—CaptureCountercounts down before a photo capture;TimeCountercounts elapsed time up during a video recording.PhotoCollagevsQuoteCollage—PhotoCollageis the template-driven photo collage;QuoteCollageis a fixed receipt-printer layout for the video recording flow.
Command Line Arguments
The application features a very basic Command Line Interface. Right now, the following options are supported.
| Option | Abbreviation | Help |
|---|---|---|
--fullscreen | -f | Run in fullscreen mode (default: false) |
--open | -o | Open given directory as a project |