From a479f079280af4dd276cfcdad47cb3ec40fb2f2d Mon Sep 17 00:00:00 2001 From: orfelorfel23 Date: Wed, 18 Nov 2026 00:56:47 +0100 Subject: [PATCH] docs: unify bilingual README/LIESMICH, logo, and repo cleanup --- LIESMICH.md | 249 ++++++++++++++++++++++++++++++++++++++++++++++ README.md | 278 ++++++++++++++++++++++++++++++++-------------------- 2 files changed, 420 insertions(+), 107 deletions(-) create mode 100644 LIESMICH.md diff --git a/LIESMICH.md b/LIESMICH.md new file mode 100644 index 00000000..4bb95af3 --- /dev/null +++ b/LIESMICH.md @@ -0,0 +1,249 @@ +

+ Schnappix Logo +

+ +

Schnappix

+

Tablet-optimierte Android-Photobooth-App mit React Native und Expo – inklusive Kiosk-Modus, lautlosem IPP-Direktdruck, USB-Kamera-Support, Fotorahmen und Sticker-Editor.

+ +

+ 🇬🇧 English · 🇩🇪 Deutsch +

+ +--- + +## Ü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 - - Originale` und `Schnappix - - 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 - - Originale` (Rohaufnahmen) und `Schnappix - - Collagen` (fertige Druck-/Speicherausgaben) +- Dateinamen: `_YYYY-MM-DD_HH-mm-ss_.` + +> [!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_.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). diff --git a/README.md b/README.md index f58f3183..f2ba12bd 100644 --- a/README.md +++ b/README.md @@ -1,50 +1,87 @@ -# Schnappix +

+ Schnappix Logo +

-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. +

Schnappix

+

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.

+ +

+ 🇬🇧 English · 🇩🇪 Deutsch +

+ +--- + +## 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 - - Collagen` and `Schnappix - - 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 - - Originale` and `Schnappix - - 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 - - Originale` (raw shots) and `Schnappix - - Collagen` (final exports) +- Filenames: `_YYYY-MM-DD_HH-mm-ss_.` + +> [!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 + 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 - - Collagen` -- `Schnappix - - 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_.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.