tilt-shift-camera/tiltshift-spec.md

# Tilt-Shift Camera App Specification

## Overview

A camera app that applies real-time tilt-shift (miniature) effects to photos and videos. The effect is applied live during preview and capture, with the final output matching what the user sees on screen.

## Target Platform

- **Minimum API**: 35 (Android 15)
- **Devices**: Phones (tablet support optional)

---

## Core Features

### Blur Modes

#### Linear Mode
- Horizontal band of focus with blur above and below
- Freely rotatable (0–360°)
- Adjustable position (drag anywhere on screen)
- Adjustable band width

#### Radial/Elliptical Mode
- Central focus point with blur radiating outward
- Adjustable shape: circle to ellipse (aspect ratio control)
- Freely rotatable
- Adjustable position (drag anywhere on screen)
- Adjustable focus region size

### Blur Parameters (both modes)
- **Intensity**: Strength of the blur effect (0–100%)
- **Falloff**: Transition sharpness from focused to blurred (sharp edge ↔ gradual gradient)

---

## Camera Features

### Capture Modes
- **Photo**: Full-resolution still capture with effect applied
- **Video**: Real-time recording with effect applied, audio pass-through

### Zoom
- Smooth continuous zoom gesture (pinch)
- Snap points at each available physical lens (wide, main, telephoto as available)
- Lens indicator showing current zoom level / active lens
- Behaviour matches native camera app

### Cameras
- Front and rear camera support
- Camera switch button

---

## User Interface

### Live Preview
- Full-screen camera preview
- Effect applied in real-time
- What you see is what you get (preview matches output exactly)

### Focus Region Overlay
- Visual indicator showing current focus region while adjusting
- Semi-transparent mask or outline showing blur zone
- Hides after adjustment (or stays subtle)

### Gesture Controls
| Gesture | Action |
|---------|--------|
| Drag (one finger) | Move focus region |
| Pinch (two finger) | Resize focus region |
| Rotate (two finger) | Rotate focus region / ellipse |
| Pinch (on preview, outside focus region) | Zoom camera |

### On-Screen Controls
- Mode toggle: Linear / Radial
- Blur intensity slider
- Falloff slider
- Ellipse aspect ratio slider (radial mode only)
- Shutter button (photo)
- Record button (video)
- Camera flip button
- Zoom level indicator
- Settings access

### Optional Enhancements (Future)
- Saturation boost slider
- Contrast adjustment
- Vignette toggle/strength
- Presets (quick settings combinations)

---

## Output

### Photos
- **Resolution**: Full sensor resolution
- **Format**: JPEG
- **Location**: Default system pictures directory (DCIM or Pictures)
- **Metadata**: Full EXIF preserved from camera
- **GPS**: Location embedded if device permissions granted
- **Storage**: Processed image only (original not kept)

### Videos
- **Resolution**: Up to sensor max (may need to cap for real-time performance)
- **Format**: MP4 (H.264 or H.265)
- **Audio**: Pass-through from device microphone
- **Location**: Default system video directory
- **Metadata**: Standard video metadata with location if permitted
- **Storage**: Processed video only

---

## Permissions Required

- `CAMERA` – camera access
- `RECORD_AUDIO` – video recording
- `ACCESS_FINE_LOCATION` – GPS tagging (optional, prompt user)
- `WRITE_EXTERNAL_STORAGE` – not needed for API 35 (scoped storage)

---

## Technical Approach

### Camera
- CameraX (Camera2 interop if needed for manual controls)
- Preview bound to OpenGL surface for shader processing

### Graphics Pipeline
- OpenGL ES 3.0
- Camera frames → texture → blur shader → display/encode
- Two-pass Gaussian blur with distance-based mask
- Same shader path for preview and capture (guarantees match)

### Video Encoding
- MediaCodec surface input
- Rendered frames go directly to encoder
- May need resolution/framerate limits for smooth real-time performance on lower-end devices

### Storage
- MediaStore API for saving to standard locations
- ExifInterface for photo metadata
- Location services for GPS coordinates

---

## Design Decisions

- **Orientation**: Portrait and landscape supported, UI adapts
- **Aspect ratio**: Native sensor ratio only, no crop options
- **Flash/torch**: Not included
- **Manual exposure**: Not included
- **Reference device**: Pixel 7 Pro (minimum performance target)
- **Zoom during recording**: Locked at recording start
- **Settings persistence**: No, reset to defaults each launch
- **Weaker devices**: No fallback, let them struggle

---

## Out of Scope (v1)

- Path/curve-based focus regions
- Multiple focus points
- Filter presets or other effects beyond tilt-shift
- RAW capture
- Pro manual controls (ISO, shutter speed, focus)
- Cloud/social sharing integration

---

## Success Criteria

1. Live preview blur matches saved output exactly
2. Smooth 30fps preview with effect on mid-range devices
3. Video recording at minimum 1080p30 with real-time effect
4. Sub-second capture latency for photos
5. Intuitive gesture controls requiring no tutorial