docs: unify bilingual README/LIESMICH, logo, and repo cleanup

This commit is contained in:
Jannik committed 2026-11-18 00:56:47 +01:00
1 parent 94f690046a
commit a479f07928
2 files changed
+420 -107

No files matched your search

+249
View File
@@ -0,0 +1,249 @@
<p align="center">
<img src="Icon.png" alt="Schnappix Logo" width="128" />
</p>
<h1 align="center">Schnappix</h1>
<p align="center"><strong>Tablet-optimierte Android-Photobooth-App mit React Native und Expo – inklusive Kiosk-Modus, lautlosem IPP-Direktdruck, USB-Kamera-Support, Fotorahmen und Sticker-Editor.</strong></p>
<p align="center">
<a href="README.md">🇬🇧 English</a> · <a href="LIESMICH.md">🇩🇪 Deutsch</a>
</p>
---
## Überblick
Schnappix ist eine für Tablets optimierte Photobooth-Anwendung auf Basis von React Native und Expo (Android-Paketname `de.orfel.schnappix`). Sie bietet ein interaktives, offline-fähiges Fotobox-Erlebnis für Events – mit Countdown, Serienbild-Modus, Collagen, transparenten PNG-Fotorahmen, einem Social-Media-artigen Sticker-Editor, lautlosem Netzwerkdruck über IPP, nativem Android-Device-Owner-Kiosk-Modus, externer USB-Kamera-Unterstützung sowie einem integrierten Admin-Dashboard.
---
## Funktionen
- **Photobooth-Erlebnis**: Intuitiver Ablauf vom Startbildschirm über Countdown und Blitz-Auslösung bis zur Vorschau – `CameraScreen` bleibt im Hintergrund permanent gemountet, um Android-Kamera-Hardware-Abstürze zu verhindern.
- **Mehrere Fotos & Collagen**: Aufnahme von Einzelbildern oder Serien (bis zu 4 Fotos für Collagen) mit direkter Nachbearbeitung.
- **Sticker- & Emoji-Editor**: Party-Emojis sowie dynamische Datums-, Uhrzeit- und Event-Text-Sticker frei verschieben, per Pinch vergrößern/verkleinern und mit zwei Fingern drehen.
- **Fotorahmen**: Transparente PNG-Rahmen als Overlay (12 integrierte Vorlagen unter `assets/frames/`). Im Admin-Bereich zwischen *Aus*, *Immer an* und *Verfügbar* umschaltbar.
- **Serienbild-Modus (Burst Mode)**: Automatische Aufnahme von 1–5 Fotos hintereinander mit konfigurierbarem Intervall für den Collagen-Druck.
- **Datum-/Uhrzeit- & Event-Einblendung**: Optionaler Stempel mit Datum oder Datum + Uhrzeit sowie Event-Namen auf jedem Foto.
- **Kamera-Blitzeffekt**: Vollbild-Blitzanimation bei jeder Auslösung für echtes Fotobox-Feeling.
- **Direkter Netzwerkdruck (IPP)**: Integrierter Internet-Printing-Protocol-Client (`ipp-encoder`), der `image/jpeg`-Druckaufträge lautlos ohne Systemdialog direkt an Port `631` (`/ipp/print`) sendet – inklusive exponentiellem Retry-Backoff (3 Versuche). Eine leere Drucker-IP aktiviert den rein digitalen Modus.
- **Kiosk-Modus (Lock Task Mode)**: Eigenes natives Android-Modul (`modules/kiosk-mode`) samt Config-Plugin (`plugins/withKioskAdmin`), um das Tablet als Device Owner ohne Bestätigungsdialoge vollständig auf Schnappix zu sperren.
- **USB- & Frontkamera-Support**: Unterstützt sowohl interne Front-/Rückkameras als auch externe UVC-USB-Kameras über das native Modul (`modules/usb-camera`) und `plugins/withUsbCamera`.
- **Admin-Dashboard**: PIN-geschützter Einstellungsbildschirm (`AdminScreen`), über den alle Parameter im laufenden Betrieb geändert und in `settings.json` gespeichert werden.
- **Offline-Speicherung (MediaStore API)**: Speichert Originale und finale Collagen direkt strukturiert in der Android-Galerie (`Schnappix - <EventName> - Originale` und `Schnappix - <EventName> - Collagen`).
---
## Funktionsweise & Tech-Stack
### Tech-Stack
| Ebene | Technologie |
|---|---|
| **Framework** | [React Native](https://reactnative.dev/) (`0.81.5`) & [Expo](https://expo.dev/) (SDK `54`, New Architecture aktiviert) |
| **Sprache** | TypeScript (`^5.3.0`) & React (`19.1.0`) |
| **Kamera & Medien** | `expo-camera`, `expo-image`, `expo-image-manipulator`, `expo-file-system`, `expo-media-library` |
| **Editor & Capture** | `react-native-view-shot`, `react-native-gesture-handler`, `react-native-reanimated`, `react-native-worklets`, `expo-linear-gradient` |
| **Drucken** | `ipp-encoder` (`^5.0.0`) + `buffer` (rohe IPP-v1.1-`Print-Job`-Anfragen per HTTP `POST` auf `:631/ipp/print`) |
| **Icons** | `@fortawesome/react-native-fontawesome` (`fa-solid`), `react-native-svg` |
| **Native Module & Plugins** | Lokale Expo-Module (`kiosk-mode`, `usb-camera`) & Config-Plugins (`withKioskAdmin`, `withUsbCamera`, `withLocalAars`, `withRemoveMediaPermissions`, `withProguardRules`, `withAndroidSigning`, `withOptimization`, `withMmkvForce`) |
| **Android-Ziel** | `compileSdkVersion 36`, `targetSdkVersion 36`, `ndkVersion 28.0.12932649`, Querformat (`landscape`) |
### Design-Theme (`src/styles/theme.ts`)
Die App nutzt eine **Neon-Synthwave-Ästhetik** passend zum App-Icon (`Icon.png`):
- **Primärfarbe**: Elektrisches Magenta `#ff2bd6` (Verlauf `#ff2bd6` → `#a033ff` → `#28dfff`)
- **Akzentfarbe**: Cyan-Blau `#28dfff`
- **Hintergrund**: Tiefes Dunkelblau/Schwarz `#050510` (`surface`: `#0D0D1A`, `surfaceSecondary`: `#151528`)
- **Effekte**: Neon-Glow-Schatten und Glassmorphismus-Overlays (`rgba(13, 13, 26, 0.85)`)
- **Icons**: Font Awesome (Solid) im Neon-Design
### Fotospeicherung (MediaStore API)
`src/services/storage.ts` speichert Fotos über die native Hilfsfunktion `KioskMode.saveImageToAlbum` (Android 10+ MediaStore mit `RELATIVE_PATH`), sodass keine veralteten Speicherberechtigungs-Dialoge erscheinen:
- Alben: `Schnappix - <EventName> - Originale` (Rohaufnahmen) und `Schnappix - <EventName> - Collagen` (fertige Druck-/Speicherausgaben)
- Dateinamen: `<SafeEventName>_YYYY-MM-DD_HH-mm-ss_<Raw|Collage>.<ext>`
> [!CAUTION]
> Versuche unter Android 13+ **nicht**, `WRITE_EXTERNAL_STORAGE` oder `READ_EXTERNAL_STORAGE` zu erzwingen; `plugins/withRemoveMediaPermissions.js` entfernt nicht konforme Medien-Berechtigungen bewusst für moderne Android-Versionen und den Play Store.
---
## Voraussetzungen & Installation
### Voraussetzungen
- Node.js (`v18+`) und `npm`
- Expo CLI / EAS CLI (`>= 19.1.0` für EAS-Builds)
- Android Studio & Android SDK / NDK (`28.0.12932649`) zum Bauen der nativen Android-App
### Lokale Einrichtung
1. Repository klonen:
```bash
git clone https://git.orfel.de/Jannik/Schnappix.git
cd Schnappix
```
2. Abhängigkeiten installieren:
```bash
npm install
```
3. Natives Android-Projekt generieren (erforderlich wegen der eigenen nativen Module und Plugins):
```bash
npx expo prebuild --clean --platform android
```
4. App auf einem Android-Gerät oder Emulator starten:
```bash
npm run android
```
### Entwicklungs- & Build-Regeln
Schnappix folgt festen Versionierungs- und Build-Vorgaben:
1. **Versionierung**: Das Versionsformat lautet `23.01.X`, wobei `X` dem `android.versionCode` in `app.json` entspricht (aktuell `23.01.78` / `versionCode: 78`).
2. **Build-Artefakte**: Releases müssen immer **sowohl** als `.apk` als auch als `.aab` gebaut werden (`Schnappix_v23.01.X.apk` und `Schnappix_v23.01.X.aab`).
3. **Paketname**: Muss zwingend `de.orfel.schnappix` bleiben.
> [!NOTE]
> Hinweis zur Einstellungs-Persistenz (`src/services/settings.ts`): Erkennt `Application.getLastUpdateTimeAsync()` ein App-Update oder eine Neuinstallation (bzw. fehlt `appLastUpdate`), setzt `loadSettings()` die `settings.json` auf `DEFAULT_SETTINGS` zurück.
---
## Konfiguration
Tippe auf dem Startbildschirm auf das Zahnrad-Symbol (⚙️) und gib das Admin-Passwort ein (Standard: `1234`), um das **Admin-Dashboard** zu öffnen.
### Übersicht der Admin-Einstellungen (`src/services/settings.ts`)
| Einstellung | Interner Schlüssel | Beschreibung | Standard |
|---|---|---|---|
| **Drucker IP-Adresse** | `printerIp` | Lokale IP des IPP-Druckers (z. B. Canon Selphy CP1300). Leer = rein digitaler Modus | `192.168.0.1` |
| **Countdown-Dauer** | `countdownDuration` | Sekunden vor der Fotoaufnahme | `3` |
| **Admin-Passwort** | `adminPassword` | PIN für den Zugang zum Admin-Dashboard | `1234` |
| **Begrüßungstext** | `welcomeText` | Überschrift auf dem Startbildschirm | `Zeit für ein Erinnerungsfoto!` |
| **Footer-Text** | `footerText` | Fußzeilentext auf dem Startbildschirm | `Display tippen! • Lächeln! • Foto schnappen!` |
| **Event-Name** | `eventText` | Event-Text für Datums-Sticker & Ordnernamen (wird beim Start abgefragt, falls leer) | `""` *(leer)* |
| **Serienbild-Anzahl** | `burstCount` | Anzahl der Fotos pro Auslösung (`1` = Einzelbild, `2–5` = Serie) | `1` |
| **Serienbild-Abstand** | `burstIntervalSec` | Sekunden zwischen den Serienbild-Aufnahmen | `5` |
| **Fotorahmen-Modus** | `frameMode` | `off` (*Aus*) / `always` (*Immer an*) / `available` (*Verfügbar*) | `available` |
| **Datum-Einblendung** | `dateOverlay` | `off` (*Aus*) / `date` (*Nur Datum*) / `datetime` (*Datum + Uhrzeit*) | `off` |
| **Kiosk-Modus** | `kioskModeEnabled` | Sperrt das Tablet auf Schnappix (startet bei Aktivierung automatisch beim App-Start) | `false` (*Aus*) |
| **Frontkamera nutzen** | `useFrontCamera` | Wechselt zwischen Frontkamera und Rück-/USB-Kamera | `true` (*An*) |
| **Logs aktivieren** | `enableLogs` | Aktiviert detaillierte App-Protokolle | `true` (*An*) |
### Kiosk-Modus (Android Device Owner) einrichten
Für den **echten Kiosk-Modus** (Lock Task Mode) ohne System-Rückfragen und ohne externe MDM-Software muss Schnappix als Android **Device Owner** eingerichtet werden:
**Voraussetzungen:**
1. Auf dem Android-Tablet dürfen **keine Konten** (z. B. Google-Konto) eingerichtet sein – am besten mit einem frisch zurückgesetzten Gerät starten.
2. **Entwickleroptionen** und **USB-Debugging** auf dem Tablet aktivieren.
3. Die Schnappix-APK auf dem Tablet installieren.
**Setup-Befehl:**
```bash
adb shell dpm set-device-owner de.orfel.schnappix/expo.modules.kioskmode.AdminReceiver
```
Bei Erfolg erscheint:
`Success: Device owner set to package de.orfel.schnappix`
Danach kann das USB-Kabel getrennt und der **Kiosk-Modus** direkt im Admin-Dashboard aktiviert werden.
> [!WARNING]
> Sobald die App als Device Owner registriert ist, lässt sie sich nicht mehr regulär deinstallieren. Zum Entfernen ist ein Werksreset oder ein programmgesteuertes Aufheben des Device-Owner-Status nötig.
### Fotorahmen – Anleitung (`src/data/frames.ts`)
Schnappix unterstützt eigene transparente PNG-Fotorahmen, die vor dem Speichern und Drucken über die Fotos gelegt werden.
| Eigenschaft | Anforderung |
|---|---|
| **Format** | PNG mit **Alphakanal** (Transparenz) |
| **Auflösung** | **1500 × 1000 px** (Seitenverhältnis 3:2 Querformat, passend zu Display & Druck) |
| **Transparenz** | Der Fotobereich **muss vollständig transparent sein** (`Alpha = 0`) |
| **Dateigröße** | Möglichst unter **500 KB** für schnelles Rendering |
| **Benennung** | `frame_<name>.png` (z. B. `frame_balloons.png`) |
**Neuen Rahmen hinzufügen:**
1. PNG-Datei in `assets/frames/` ablegen.
2. Rahmen in `src/data/frames.ts` registrieren:
```typescript
export const FRAMES: FrameDefinition[] = [
{ id: 'balloons', name: 'Luftballons', asset: require('../../assets/frames/frame_balloons.png') },
];
```
3. App neu bauen (`npx expo prebuild --clean --platform android` & `npm run android`).
4. Rahmen-Modus (`Immer an` oder `Verfügbar`) im Admin-Dashboard wählen.
---
## Nutzung
### Ablauf für Gäste
1. **Startbildschirm**: Tippen auf das Display startet die Aufnahme (ist noch kein `Event-Name` gesetzt, fragt ein Modal diesen zuerst ab).
2. **Aufnahme**: Der Countdown läuft ab (`countdownDuration`), der Bildschirm-Blitz leuchtet auf und es wird ein Einzelbild oder eine Serie (`1–5` Fotos) aufgenommen.
3. **Vorschau & Sticker-Editor**:
- Über **Sticker** öffnet sich der `StickerTray` mit ausgewählten Party-Emojis.
- Sticker frei verschieben, per Pinch skalieren und mit zwei Fingern drehen (`DraggableSticker`).
- Zum Löschen einen Sticker antippen und auf `×` drücken.
- Dynamische Datums-, Uhrzeit- und Event-Sticker werden automatisch gemäß Admin-Einstellungen erzeugt.
- Im `FramePicker` (bei Modus `Verfügbar`) einen Fotorahmen auswählen oder weitere Fotos für eine Collage aufnehmen.
- Speichern in die Geräte-Galerie (`MediaStore`) und lautloses Drucken per IPP auslösen.
### Nützliche npm-Skripte
- `npm start` – Expo-Entwicklungsserver starten
- `npm run android` – Native Android-App bauen und ausführen (`expo run:android`)
- `npm run ios` – iOS-Build starten (`expo run:ios`)
- `npm run web` – Web-Vorschau starten (`expo start --web`)
---
## Projektstruktur
```text
Schnappix/
├── assets/
│ ├── frames/ # 12 mitgelieferte transparente PNG-Fotorahmen (1500×1000)
│ └── graphics/ # Store- und Beispielgrafiken
├── modules/
│ ├── kiosk-mode/ # Natives Android-Lock-Task- & MediaStore-Modul
│ └── usb-camera/ # Natives Android-UVC-USB-Kamera-Modul inkl. AARs
├── plugins/ # Expo-Config-Plugins (Kiosk, USB, AARs, Signing, ProGuard usw.)
├── src/
│ ├── components/ # DraggableSticker, FrameOverlay, FramePicker, GradientButton, Icon, StickerTray
│ ├── data/
│ │ └── frames.ts # Registrierung der integrierten Fotorahmen
│ ├── screens/
│ │ ├── CameraScreen.tsx # Startansicht, Countdown, Blitz, Kamera-/USB-Aufnahme
│ │ ├── PreviewScreen.tsx # Collagenansicht, Rahmenwahl, Sticker-Editor, Druck & Speichern
│ │ └── AdminScreen.tsx # PIN-geschütztes Admin-Dashboard
│ ├── services/
│ │ ├── logger.ts # Persistenter Datei-Logger
│ │ ├── printer.ts # Lautloser IPP-v1.1-JPEG-Netzwerkdruck
│ │ ├── settings.ts # settings.json-Persistenz & Update-Reset-Logik
│ │ └── storage.ts # Android-MediaStore-Albumspeicherung
│ ├── styles/
│ │ └── theme.ts # Neon-Synthwave-Farben, Abstände & Verläufe
│ └── types/
│ └── ipp-encoder.d.ts # TypeScript-Deklarationen für ipp-encoder
├── App.tsx # Haupt-Zustandssteuerung & persistenter CameraScreen-Host
├── app.json # Expo-Konfiguration (Version 23.01.78, de.orfel.schnappix)
├── eas.json # EAS-Build-Profile (development, preview APK, production)
├── Icon.png # App-Icon
├── package.json # Abhängigkeiten & Skripte
└── withAndroidSigning.js # Android-Release-Keystore-Signing-Plugin
```
---
## Lizenz
Lizenziert unter der MIT-Lizenz – Details siehe [LICENSE](LICENSE).
+171 -107
View File
@@ -1,50 +1,87 @@
# Schnappix
<p align="center">
<img src="Icon.png" alt="Schnappix Logo" width="128" />
</p>
Schnappix is a tablet-optimized Photobooth application built with React Native and Expo. It provides a full-featured, interactive photo capturing experience, complete with external hardware support, image editing, and an administrative interface.
<h1 align="center">Schnappix</h1>
<p align="center"><strong>Tablet-optimized Android Photobooth app built with React Native and Expo, featuring Kiosk Mode, silent IPP printing, USB cameras, photo frames, and a sticker editor.</strong></p>
<p align="center">
<a href="README.md">🇬🇧 English</a> · <a href="LIESMICH.md">🇩🇪 Deutsch</a>
</p>
---
## Overview
Schnappix is a tablet-optimized Photobooth application built with React Native and Expo (Android package `de.orfel.schnappix`). It delivers an interactive, offline-first photo-capturing experience for events—complete with countdown, burst mode, generated collages, custom PNG photo frames, a social-media-style sticker editor, silent network printing over IPP, native Android Device Owner Kiosk Mode, external USB camera support, and an on-device Admin Dashboard.
---
## Features
- **Photobooth Experience**: Intuitive flow from start screen to countdown, photo capture, and final preview.
- **Multiple Photos & Collages**: Capture single or multiple photos and review them in a generated collage.
- **Sticker / Emoji Editor**: Add emojis, date/time stamps, and event text as draggable, resizable, rotatable stickers on your photos — just like on social media.
- **Photo Frames**: Overlay transparent PNG frames on photos. Admin can set frames to off, always-on, or user-selectable.
- **Continuous Shooting (Burst Mode)**: Automatically capture multiple photos in sequence (1–5 shots, configurable interval) for collage printing.
- **Date/Time Overlay**: Optionally stamp the date and/or time on every photo, with configurable position.
- **Camera Flash Effect**: Full-screen white flash animation on every capture for an authentic photo booth feel.
- **Direct Printing**: Built-in support for IPP (Internet Printing Protocol) network printers to instantly print captured moments.
- **Kiosk Mode**: Custom native Android implementation to lock the tablet down to the Schnappix app, preventing users from exiting the photobooth.
- **USB & Front Camera Support**: Extends standard camera capabilities to support external USB cameras or standard device front/rear cameras, toggleable in settings.
- **Admin Dashboard**: Secure administrative screen (protected by an admin password) to configure all settings on the fly.
- **Offline Storage (MediaStore API)**: Saves captured photos directly to the device's local gallery (`Schnappix - <EventName> - Collagen` and `Schnappix - <EventName> - Originale`).
- **Photobooth Experience**: Intuitive flow from welcome screen to countdown, photo capture, and final preview—with `CameraScreen` kept mounted in the background to prevent Android camera hardware crashes.
- **Multiple Photos & Collages**: Capture single shots or multi-photo sequences (up to 4 photos kept for collages) and review/edit them together.
- **Sticker & Emoji Editor**: Add curated party emojis and dynamic date/time/event stickers that can be dragged, pinched to resize, and rotated with two fingers.
- **Photo Frames**: Overlay transparent PNG frames (12 built-in designs in `assets/frames/`). Admins can set frames to off, always-on, or guest-selectable.
- **Continuous Shooting (Burst Mode)**: Automatically capture 1–5 shots in sequence with a configurable interval for collage printing.
- **Date/Time & Event Overlay**: Optionally stamp the date or date + time and configured event name onto photos with adjustable transform.
- **Camera Flash Effect**: Full-screen white flash animation on every capture for an authentic photobooth feel.
- **Direct Silent Printing (IPP)**: Built-in Internet Printing Protocol (`ipp-encoder`) client sending `image/jpeg` print jobs directly to port `631` (`/ipp/print`) with exponential backoff retries (up to 3 attempts), bypassing OS print dialogs. Leaving the printer IP empty enables digital-only mode.
- **Kiosk Mode (Lock Task Mode)**: Custom native Android module (`modules/kiosk-mode`) and config plugin (`plugins/withKioskAdmin`) to lock the tablet down to Schnappix without confirmation prompts when configured as Device Owner.
- **USB & Front Camera Support**: Supports internal front/rear cameras as well as external UVC USB cameras via custom native module (`modules/usb-camera`) and plugin (`plugins/withUsbCamera`).
- **Admin Dashboard**: PIN-protected settings screen (`AdminScreen`) to configure all parameters on the fly, persisted in `settings.json`.
- **Offline Gallery Storage (MediaStore API)**: Saves originals and final collages directly into structured Android gallery albums (`Schnappix - <EventName> - Originale` and `Schnappix - <EventName> - Collagen`).
## Tech Stack
---
- **Framework**: [React Native](https://reactnative.dev/) (v0.81.5) & [Expo](https://expo.dev/) (SDK 54)
- **Language**: TypeScript
- **Key Libraries**:
- `expo-camera`: Camera interface
- `expo-media-library` & `expo-file-system`: Photo storage
- `ipp-encoder`: Network printing integration
- `react-native-view-shot`: Capturing collages as images
- `react-native-gesture-handler`: Sticker drag, pinch, and rotate gestures
- `@fortawesome/react-native-fontawesome`: All in-app icons via Font Awesome
- `react-native-svg`: SVG rendering for icon support
- Custom native Expo plugins (`withKioskAdmin`, `withUsbCamera`, `withLocalAars`) for extended Android capabilities.
## How It Works & Tech Stack
## Getting Started
### Tech Stack
| Layer | Technology |
|---|---|
| **Framework** | [React Native](https://reactnative.dev/) (`0.81.5`) & [Expo](https://expo.dev/) (SDK `54`, New Architecture enabled) |
| **Language** | TypeScript (`^5.3.0`) & React (`19.1.0`) |
| **Camera & Media** | `expo-camera`, `expo-image`, `expo-image-manipulator`, `expo-file-system`, `expo-media-library` |
| **Editing & Capture** | `react-native-view-shot`, `react-native-gesture-handler`, `react-native-reanimated`, `react-native-worklets`, `expo-linear-gradient` |
| **Printing** | `ipp-encoder` (`^5.0.0`) + `buffer` (raw IPP v1.1 `Print-Job` over HTTP `POST` to `:631/ipp/print`) |
| **Icons** | `@fortawesome/react-native-fontawesome` (`fa-solid`), `react-native-svg` |
| **Native Modules & Plugins** | Local Expo modules (`kiosk-mode`, `usb-camera`) and config plugins (`withKioskAdmin`, `withUsbCamera`, `withLocalAars`, `withRemoveMediaPermissions`, `withProguardRules`, `withAndroidSigning`, `withOptimization`, `withMmkvForce`) |
| **Android Target** | `compileSdkVersion 36`, `targetSdkVersion 36`, `ndkVersion 28.0.12932649`, landscape orientation |
### Design Theme (`src/styles/theme.ts`)
Schnappix uses a **neon synthwave** aesthetic matching `Icon.png`:
- **Primary**: Electric magenta `#ff2bd6` (gradient stops `#ff2bd6` → `#a033ff` → `#28dfff`)
- **Accent**: Cyan blue `#28dfff`
- **Background**: Deep navy/black `#050510` (surface `#0D0D1A`, secondary `#151528`)
- **Effects**: Neon glow shadows and glassmorphism overlays (`rgba(13, 13, 26, 0.85)`)
- **Icons**: Font Awesome Solid icons with neon styling
### Photo Saving (MediaStore API)
`src/services/storage.ts` saves images via the native `KioskMode.saveImageToAlbum` MediaStore helper (Android 10+ `RELATIVE_PATH`), avoiding legacy storage permission prompts:
- Albums: `Schnappix - <EventName> - Originale` (raw shots) and `Schnappix - <EventName> - Collagen` (final exports)
- Filenames: `<SafeEventName>_YYYY-MM-DD_HH-mm-ss_<Raw|Collage>.<ext>`
> [!CAUTION]
> Do **not** attempt to force legacy `WRITE_EXTERNAL_STORAGE` or `READ_EXTERNAL_STORAGE` permissions on Android 13+; `plugins/withRemoveMediaPermissions.js` intentionally strips incompatible media permissions for Play Store and modern Android compliance.
---
## Prerequisites & Installation
### Prerequisites
- Node.js (v18+)
- npm or yarn
- Expo CLI
- Android Studio / Android SDK (for building the native Android app, as it uses custom native modules)
- Node.js (`v18+`) and `npm`
- Expo CLI / EAS CLI (`>= 19.1.0` for EAS builds)
- Android Studio & Android SDK / NDK (`28.0.12932649`) for building the native Android project
### Installation
### Local Setup
1. Clone the repository:
```bash
git clone <repository-url>
git clone https://git.orfel.de/Jannik/Schnappix.git
cd Schnappix
```
@@ -53,7 +90,7 @@ Schnappix is a tablet-optimized Photobooth application built with React Native a
npm install
```
3. Prebuild the native Android project (required due to custom native plugins):
3. Prebuild the native Android project (required due to custom native modules and config plugins):
```bash
npx expo prebuild --clean --platform android
```
@@ -63,123 +100,150 @@ Schnappix is a tablet-optimized Photobooth application built with React Native a
npm run android
```
## Development & Build Rules
### Development & Build Rules
Schnappix follows strict architecture and workflow rules:
Schnappix follows strict versioning and release conventions:
1. **Versioning**: Versioning format is `23.01.X`, where `X` matches the `versionCode` in `app.json`.
2. **Build Outputs**: Apps must always be built as BOTH `.apk` and `.aab`. Naming syntax is `Schnappix_v23.01.X.apk` and `Schnappix_v23.01.X.aab`.
1. **Versioning**: Version format is `23.01.X`, where `X` matches `expo.android.versionCode` in `app.json` (currently `23.01.78` / `versionCode: 78`).
2. **Build Outputs**: Production releases must always be built as **both** `.apk` and `.aab`, named `Schnappix_v23.01.X.apk` and `Schnappix_v23.01.X.aab`.
3. **Package Name**: Must strictly remain `de.orfel.schnappix`.
4. **Git Workflow**: Always commit and push at the end of interactions (`git add .`, `git commit`, `git push`). Retry `git push` if it fails due to authentication errors.
## Configuration
When the app is first launched, you can access the **Admin Dashboard** by tapping the settings icon (⚙️) on the Home screen and entering the admin password (default: `1234`).
### Admin Settings Overview
| Setting | Description | Default |
|---|---|---|
| **Drucker IP-Adresse** | Local IP of the IPP printer (e.g., Canon CP1300) | `192.168.1.100` |
| **Countdown-Dauer** | Seconds before photo capture | `3` |
| **Admin-Passwort** | PIN to access admin panel | `1234` |
| **Begrüßungstext** | Welcome text on the home screen | `Zeit für ein Erinnerungsfoto!` |
| **Footer-Text** | Footer text on the home screen | `Display tippen! • Lächeln! • Foto schnappen!` |
| **Event-Name** | Event text for the date sticker & generated folder names | _(empty)_ |
| **Serienbild-Anzahl** | Number of photos per burst (1 = single shot, 2-5 = burst) | `1` |
| **Serienbild-Abstand** | Seconds between burst shots | `5` |
| **Fotorahmen-Modus** | `Aus` / `Immer an` / `Verfügbar` | `Verfügbar` |
| **Datum-Einblendung** | `Aus` / `Nur Datum` / `Datum + Uhrzeit` | `Aus` |
| **Kiosk-Modus** | Lock the tablet to the Schnappix app | `Aus` |
| **Frontkamera nutzen** | Toggles between front and rear/USB camera | `Aus` |
| **Logs aktivieren** | Enables detailed app logging | `An` |
> [!NOTE]
> Note on settings persistence (`src/services/settings.ts`): When `Application.getLastUpdateTimeAsync()` detects that the app was updated or freshly installed (or `appLastUpdate` is missing), `loadSettings()` resets `settings.json` to `DEFAULT_SETTINGS`.
---
## Kiosk Mode (Device Owner) Setup
## Configuration
To use the **true Kiosk Mode** (Lock Task Mode) without system confirmation prompts, the Schnappix app must be set as the Android "Device Owner". It does NOT use external MDM software.
Tap the settings icon (⚙️) on the home screen and enter the admin PIN (default: `1234`) to open the **Admin Dashboard**.
### Admin Settings Overview (`src/services/settings.ts`)
| Setting | Internal Key | Description | Default |
|---|---|---|---|
| **Drucker IP-Adresse** | `printerIp` | Local IP of the IPP printer (e.g. Canon Selphy CP1300). Leave empty for digital-only mode | `192.168.0.1` |
| **Countdown-Dauer** | `countdownDuration` | Seconds before photo capture | `3` |
| **Admin-Passwort** | `adminPassword` | PIN to access the Admin Dashboard | `1234` |
| **Begrüßungstext** | `welcomeText` | Welcome headline on the home screen | `Zeit für ein Erinnerungsfoto!` |
| **Footer-Text** | `footerText` | Footer text on the home screen | `Display tippen! • Lächeln! • Foto schnappen!` |
| **Event-Name** | `eventText` | Event title for date stickers & album folder names (prompted via modal if empty) | `""` *(empty)* |
| **Serienbild-Anzahl** | `burstCount` | Number of photos per burst (`1` = single shot, `2–5` = burst) | `1` |
| **Serienbild-Abstand** | `burstIntervalSec` | Seconds between burst shots | `5` |
| **Fotorahmen-Modus** | `frameMode` | `off` (*Aus*) / `always` (*Immer an*) / `available` (*Verfügbar*) | `available` |
| **Datum-Einblendung** | `dateOverlay` | `off` (*Aus*) / `date` (*Nur Datum*) / `datetime` (*Datum + Uhrzeit*) | `off` |
| **Kiosk-Modus** | `kioskModeEnabled` | Locks the tablet to Schnappix (auto-starts on launch if enabled) | `false` (*Aus*) |
| **Frontkamera nutzen** | `useFrontCamera` | Toggles between front camera and rear/USB camera | `true` (*An*) |
| **Logs aktivieren** | `enableLogs` | Enables detailed in-app file logging | `true` (*An*) |
### Kiosk Mode (Android Device Owner) Setup
To use **true Kiosk Mode** (Lock Task Mode) without system confirmation prompts and without external MDM software, Schnappix must be registered as the Android **Device Owner**:
**Prerequisites:**
1. The Android tablet must have no other accounts (like a Google Account) configured. It is highly recommended to start with a factory-reset device.
2. Developer Options and USB Debugging must be enabled on the tablet.
3. The Schnappix APK must be installed on the tablet.
1. The Android tablet must have **no accounts** (such as a Google Account) configured—ideally start from a factory-reset device.
2. Enable **Developer Options** and **USB Debugging** on the tablet.
3. Install the Schnappix APK on the tablet.
**Setup Command:**
Run the following command in your terminal/command prompt while the tablet is connected:
```bash
adb shell dpm set-device-owner de.orfel.schnappix/expo.modules.kioskmode.AdminReceiver
```
If successful, the terminal will output `Success: Device owner set to package de.orfel.schnappix`. You can now safely disconnect the tablet and toggle the Kiosk Mode in the app's Admin Dashboard.
Expected confirmation:
`Success: Device owner set to package de.orfel.schnappix`
*Note: Once set as Device Owner, the app cannot be uninstalled normally. You must either factory reset the device or implement a programmatic way to remove the active admin status.*
You can now disconnect USB and toggle **Kiosk-Modus** in the Admin Dashboard.
---
> [!WARNING]
> Once set as Device Owner, Android prevents normal uninstallation of Schnappix. You must either factory-reset the device or remove Device Owner status programmatically.
## Photo Saving (MediaStore API)
### Photo Frames — Setup Guide (`src/data/frames.ts`)
Schnappix uses modern Android MediaStore API (`writeOnly = true` via `expo-media-library`) to save photos directly to the gallery, avoiding legacy file permission prompts.
Photos are neatly organized into two directories based on your configured `Event-Name`:
- `Schnappix - <EventName> - Collagen`
- `Schnappix - <EventName> - Originale`
*Note: Do NOT attempt to force legacy `WRITE_EXTERNAL_STORAGE` or `READ_EXTERNAL_STORAGE` on Android 13+, as it will fail.*
---
## Photo Frames — Setup Guide
Schnappix supports custom photo frame overlays. Frames are transparent PNG images that are layered on top of photos before saving or printing.
### Frame Requirements
Custom photo frames are transparent PNG overlays rendered on top of captured photos before saving or printing.
| Property | Requirement |
|---|---|
| **Format** | PNG with **alpha channel** (transparency) |
| **Resolution** | **1500 × 1000 px** (3:2 landscape ratio, matches tablet display and print output) |
| **Transparency** | The photo area **must be fully transparent** (alpha = 0) |
| **Resolution** | **1500 × 1000 px** (3:2 landscape ratio, matching tablet display and print output) |
| **Transparency** | The photo area **must be fully transparent** (`alpha = 0`) |
| **File size** | Keep each file under **500 KB** for fast rendering |
| **Naming** | `frame_<name>.png` (e.g. `frame_balloons.png`) |
### How to Add Frames
1. **Place the file** in the `assets/frames/` directory.
2. **Register the frame** in `src/data/frames.ts`:
**Adding a new frame:**
1. Place the PNG file into `assets/frames/`.
2. Register it in `src/data/frames.ts`:
```typescript
export const FRAMES: FrameDefinition[] = [
{ id: 'balloons', name: 'Luftballons', asset: require('../../assets/frames/frame_balloons.png') },
];
```
3. **Rebuild the app** (`npx expo prebuild --clean --platform android` & `npm run android`).
4. **Select the frame mode** in the Admin Dashboard.
3. Rebuild the Android app (`npx expo prebuild --clean --platform android` and `npm run android`).
4. Select the frame mode (`always` or `available`) in the Admin Dashboard.
---
## Sticker Editing
## Usage
The preview screen includes a social-media-style sticker editor. Guests can:
### Guest Photobooth Flow
- **Add emojis**: Tap the "Sticker" button to open the emoji tray with curated party emojis.
- **Transform**: Drag stickers anywhere, pinch to resize, and two-finger rotate.
- **Delete**: Tap to select, then press × to delete.
- **Dynamic Stickers**: Date, Time, and Event text automatically generate based on your Admin settings.
1. **Welcome Screen**: Guest taps the screen to start (if `Event-Name` is empty, the Admin modal prompts for an event name first).
2. **Capture**: Countdown runs (`countdownDuration`), white screen flash fires, and either a single shot or burst sequence (`1–5` photos) is captured.
3. **Preview & Sticker Editor**:
- Tap **Sticker** to open `StickerTray` and add curated party emojis.
- Drag stickers anywhere, pinch to resize, and use two fingers to rotate (`DraggableSticker`).
- Tap a sticker to select it and press `×` to delete it.
- Dynamic date, time, and event-name stickers render automatically according to Admin settings.
- Choose a photo frame via `FramePicker` (when `frameMode` is `available`) or add more photos to build a collage.
- Save directly to the device gallery (`MediaStore`) and print silently via IPP.
All stickers are rendered inside the capture area, so they appear in the saved and printed output.
### Useful npm Scripts
- `npm start` — Start Expo dev server
- `npm run android` — Build and run native Android app (`expo run:android`)
- `npm run ios` — Run iOS build (`expo run:ios`)
- `npm run web` — Run web preview (`expo start --web`)
---
## Design Theme
## Project Structure
The app uses a **neon synthwave** aesthetic matching the app icon:
```text
Schnappix/
├── assets/
│ ├── frames/ # 12 built-in transparent PNG photo frames (1500×1000)
│ └── graphics/ # Store & sample promotional graphics
├── modules/
│ ├── kiosk-mode/ # Native Android Lock Task + MediaStore saving module
│ └── usb-camera/ # Native Android UVC USB camera module & AARs
├── plugins/ # Expo config plugins (kiosk, USB, AARs, signing, ProGuard, etc.)
├── src/
│ ├── components/ # DraggableSticker, FrameOverlay, FramePicker, GradientButton, Icon, StickerTray
│ ├── data/
│ │ └── frames.ts # Built-in photo frame registry
│ ├── screens/
│ │ ├── CameraScreen.tsx # Welcome overlay, countdown, flash, camera/USB capture
│ │ ├── PreviewScreen.tsx # Collage view, frame picker, sticker editor, print & save
│ │ └── AdminScreen.tsx # PIN-protected configuration dashboard
│ ├── services/
│ │ ├── logger.ts # Persistent file logger
│ │ ├── printer.ts # Silent IPP v1.1 JPEG network printing
│ │ ├── settings.ts # settings.json persistence & update-reset logic
│ │ └── storage.ts # Android MediaStore album saving
│ ├── styles/
│ │ └── theme.ts # Neon synthwave colors, spacing & gradients
│ └── types/
│ └── ipp-encoder.d.ts # TypeScript declarations for ipp-encoder
├── App.tsx # Root state machine & persistent CameraScreen host
├── app.json # Expo configuration (version 23.01.78, de.orfel.schnappix)
├── eas.json # EAS Build profiles (development, preview APK, production)
├── Icon.png # App icon
├── package.json # Dependencies and scripts
└── withAndroidSigning.js # Android release keystore signing plugin
```
- **Primary**: Electric magenta `#ff2bd6`
- **Accent**: Cyan blue `#28dfff`
- **Background**: Deep navy/black `#050510`
- **Effects**: Neon glow shadows, glassmorphism overlays
- **Icons**: Font Awesome (solid) with neon coloring
---
## License
See the [LICENSE](LICENSE) file for more information.
Licensed under the MIT License — see [LICENSE](LICENSE) for details.