mirror of
https://github.com/snapotter-hq/SnapOtter.git
synced 2026-08-03 07:46:42 +02:00
docs: add design spec for edit metadata tool
Design spec for new edit-metadata tool (issue #15). Covers common EXIF field editing, GPS clearing, granular per-field stripping, and shared metadata infrastructure extracted from strip-metadata.
This commit is contained in:
Siddharth Kumar Sah
@@ -0,0 +1,202 @@
|
||||
# Edit Metadata Tool - Design Spec
|
||||
|
||||
**Date:** 2026-04-06
|
||||
**Issue:** [stirling-image/stirling-image#15](https://github.com/stirling-image/stirling-image/issues/15)
|
||||
**Approach:** Shared metadata infrastructure (Approach 2)
|
||||
|
||||
## Overview
|
||||
|
||||
A new tool for editing and selectively removing EXIF metadata from images. Covers common editable fields (description, artist, copyright, software, dates), GPS clearing, and granular per-field stripping. Builds on shared infrastructure extracted from the existing strip-metadata tool.
|
||||
|
||||
## Scope
|
||||
|
||||
**In scope:**
|
||||
- Edit common EXIF fields: description, artist, copyright, software, date modified, date taken
|
||||
- GPS clear via checkbox
|
||||
- Granular strip: per-field removal of any displayed EXIF tag
|
||||
- Read-only display of current metadata (EXIF, GPS, XMP)
|
||||
- Pre-population of edit form from current values
|
||||
- Dirty tracking to distinguish untouched/edited/cleared fields
|
||||
- Shared metadata parsing and UI components extracted from strip-metadata
|
||||
|
||||
**Out of scope (potential future work):**
|
||||
- Arbitrary advanced EXIF field editing (camera make/model, lens, exposure, etc.)
|
||||
- XMP/ICC profile editing
|
||||
- Batch-specific metadata (different values per file)
|
||||
|
||||
## Architecture
|
||||
|
||||
### File changes
|
||||
|
||||
```
|
||||
packages/image-engine/
|
||||
src/utils/metadata.ts EXTEND add parseExif(), parseGps(), parseXmp(), sanitizeValue()
|
||||
src/operations/edit-metadata.ts NEW editMetadata() function
|
||||
src/types.ts EXTEND add EditMetadataOptions
|
||||
src/index.ts EXTEND export new operation
|
||||
|
||||
apps/api/
|
||||
src/routes/tools/edit-metadata.ts NEW /inspect + /edit endpoints
|
||||
src/routes/tools/strip-metadata.ts REFACTOR swap local parsing helpers for shared imports
|
||||
src/routes/tools/index.ts EXTEND register new tool
|
||||
|
||||
apps/web/
|
||||
src/components/common/collapsible-section.tsx NEW extract from strip-metadata
|
||||
src/components/common/metadata-grid.tsx NEW extract from strip-metadata
|
||||
src/lib/metadata-utils.ts NEW EXIF_LABELS, SKIP_KEYS, formatExifValue, exifStr
|
||||
src/components/tools/edit-metadata-settings.tsx NEW main component
|
||||
src/components/tools/strip-metadata-settings.tsx REFACTOR use shared imports
|
||||
src/lib/tool-registry.tsx EXTEND register new tool
|
||||
|
||||
packages/shared/
|
||||
src/constants.ts EXTEND add tool entry
|
||||
src/i18n/en.ts EXTEND add i18n strings
|
||||
```
|
||||
|
||||
### Image-engine layer
|
||||
|
||||
**Extended `utils/metadata.ts`** adds four parsing functions alongside the existing `getImageInfo()`:
|
||||
|
||||
- `sanitizeValue(v)` - makes EXIF values JSON-safe (Dates to ISO strings, Buffers to arrays or `<binary N bytes>`, recursion for nested objects)
|
||||
- `parseExif(exifBuffer)` - calls `exif-reader`, returns `{ image, photo, iop }` sections with sanitized values
|
||||
- `parseGps(gpsInfo)` - extracts DMS coordinates to decimal `{ latitude, longitude, altitude }`
|
||||
- `parseXmp(xmpBuffer)` - regex extraction of key/value pairs from XMP XML
|
||||
|
||||
**New `operations/edit-metadata.ts`** - `editMetadata(image, options)`:
|
||||
|
||||
- Maps common option fields (artist, copyright, imageDescription, software, dateTime, dateTimeOriginal) to their IFD0/IFD2 EXIF tag names
|
||||
- Accepts `fieldsToRemove: string[]` for granular strip
|
||||
- Logic:
|
||||
- If `clearGps` or `fieldsToRemove` has entries: read existing EXIF, rebuild the EXIF object minus the removed fields/GPS, merge in edits, then `withExif()` (full replace)
|
||||
- If only edits (no removals): `withExifMerge()` (non-destructive merge)
|
||||
- If nothing to do: `keepMetadata()` (passthrough)
|
||||
|
||||
**New type:**
|
||||
```ts
|
||||
interface EditMetadataOptions {
|
||||
artist?: string;
|
||||
copyright?: string;
|
||||
imageDescription?: string;
|
||||
software?: string;
|
||||
dateTime?: string;
|
||||
dateTimeOriginal?: string;
|
||||
clearGps?: boolean;
|
||||
fieldsToRemove?: string[];
|
||||
}
|
||||
```
|
||||
|
||||
### API route design
|
||||
|
||||
**`POST /api/v1/tools/edit-metadata/inspect`** - custom endpoint:
|
||||
- Accepts multipart file upload
|
||||
- Calls shared parsing functions from image-engine
|
||||
- Returns:
|
||||
```json
|
||||
{
|
||||
"filename": "photo.jpg",
|
||||
"fileSize": 2048000,
|
||||
"exif": { "Artist": "John", "Software": "Lightroom", ... },
|
||||
"gps": { "GPSLatitude": [...], "_latitude": 51.5074, "_longitude": -0.1278, ... },
|
||||
"xmp": { "dc:creator": "John", ... }
|
||||
}
|
||||
```
|
||||
|
||||
**`POST /api/v1/tools/edit-metadata`** - via `createToolRoute` factory:
|
||||
- Settings schema:
|
||||
```ts
|
||||
z.object({
|
||||
artist: z.string().optional(),
|
||||
copyright: z.string().optional(),
|
||||
imageDescription: z.string().optional(),
|
||||
software: z.string().optional(),
|
||||
dateTime: z.string().optional(),
|
||||
dateTimeOriginal: z.string().optional(),
|
||||
clearGps: z.boolean().default(false),
|
||||
fieldsToRemove: z.array(z.string()).default([]),
|
||||
})
|
||||
```
|
||||
- Process function: reads format, calls `editMetadata(image, settings)`, re-encodes in original format, returns `{ buffer, filename, contentType }`
|
||||
|
||||
### UI component design
|
||||
|
||||
**Shared extractions (from strip-metadata):**
|
||||
- `CollapsibleSection` to `components/common/collapsible-section.tsx` - unchanged from strip-metadata
|
||||
- `MetadataGrid` to `components/common/metadata-grid.tsx` - extended with optional `onRemove?: (key: string) => void` and `removedKeys?: Set<string>` props. When `onRemove` is provided, each row shows a trash icon. When a key is in `removedKeys`, the row renders with strikethrough + muted styling. Strip-metadata passes neither prop (read-only behavior preserved).
|
||||
- `EXIF_LABELS`, `SKIP_KEYS`, `formatExifValue()`, `exifStr()` to `lib/metadata-utils.ts`
|
||||
|
||||
**`EditMetadataSettings` - three sections:**
|
||||
|
||||
**1. Current Metadata (read-only + granular strip)**
|
||||
- Auto-fetched via `/inspect` on file selection (per-file cache, AbortController cleanup)
|
||||
- EXIF: `CollapsibleSection` with `MetadataGrid`. String-typed and safely-serializable fields get a trash icon for granular removal. Binary blobs (MakerNote, PrintImageMatching) and complex array fields are displayed read-only without a remove option - this avoids data corruption from lossy EXIF round-trips through `withExif()`. Clicking a trash icon toggles the tag into `fieldsToRemove` set (strikethrough + muted styling).
|
||||
- GPS: `CollapsibleSection` with warning styling if GPS detected, coordinates displayed
|
||||
|
||||
**2. Edit Fields**
|
||||
- Common fields: Description, Artist, Copyright, Software, Date Modified, Date Taken as `LabeledInput` components, pre-populated from inspect data
|
||||
- Dirty tracking: store initial values from inspect. On submit, compare current to initial. Changed + has value = include in settings. Changed + empty = add to `fieldsToRemove`. Untouched = skip.
|
||||
- GPS: "Remove GPS location data" checkbox with coordinate display if present
|
||||
|
||||
**3. Submit / Download**
|
||||
- Submit via `useToolProcessor("edit-metadata")`
|
||||
- `ProgressCard` during processing, download link after
|
||||
|
||||
**Display mode:** `"no-comparison"` in tool registry.
|
||||
|
||||
**Edit + remove conflict resolution:** If a user marks a field for removal in the metadata view AND edits the same field in the edit form, the edit wins. Submit logic checks edit fields first, only adds to `fieldsToRemove` tags that aren't being written.
|
||||
|
||||
## Data Flow
|
||||
|
||||
1. User drops image into dropzone
|
||||
2. Component auto-calls `/inspect`, parses response, pre-populates form, stores initial values
|
||||
3. User edits fields and/or marks tags for removal in metadata view
|
||||
4. On submit: dirty-diff builds settings object (e.g. `{ artist: "New Name", fieldsToRemove: ["Software", "MeteringMode"], clearGps: true }`)
|
||||
5. Tool factory receives file + settings, calls `editMetadata()`, re-encodes, returns download URL
|
||||
6. User downloads modified image
|
||||
|
||||
## Error Handling
|
||||
|
||||
- **Inspect fails** (corrupt file, unsupported format): inline warning "Could not read metadata", form fields start empty, user can still write new metadata
|
||||
- **No EXIF in image**: "No metadata found" in current metadata section, form fields start empty, editing still works (writes fresh EXIF)
|
||||
- **Format with limited EXIF support** (PNG): no special handling. Sharp writes what the format supports, silently drops what it doesn't. Matches strip-metadata behavior.
|
||||
- **Processing fails**: tool factory returns 422, component displays error from response
|
||||
- **No changes submitted**: `keepMetadata()` passthrough, image re-encoded with metadata preserved
|
||||
|
||||
## Testing
|
||||
|
||||
### Unit tests (image-engine)
|
||||
- `editMetadata` writes common fields, readable back via `exif-reader`
|
||||
- `editMetadata` with `clearGps: true` removes GPS, preserves other EXIF
|
||||
- `editMetadata` with `fieldsToRemove` drops specific tags, preserves others
|
||||
- `editMetadata` with no options preserves metadata
|
||||
- Edit + remove conflict: edit wins
|
||||
- Works through `processImage` pipeline
|
||||
|
||||
### Unit tests (web utilities)
|
||||
- Dirty tracking: detects changed fields, cleared fields, ignores untouched
|
||||
- Settings builder: correctly splits edits vs removals
|
||||
- `formatExifValue` and `exifStr` tests (moved from fork's tests to shared location)
|
||||
|
||||
### Integration tests (API)
|
||||
- `/inspect` returns parsed EXIF/GPS/XMP for test JPEG with known metadata
|
||||
- `/inspect` returns nulls for metadata-free PNG
|
||||
- `/inspect` rejects no-file and invalid-file requests
|
||||
- Edit endpoint writes metadata, returns downloadable file
|
||||
- Edit endpoint with `fieldsToRemove` strips specific tags
|
||||
- Edit endpoint with `clearGps` removes GPS
|
||||
- Edit endpoint with empty settings preserves original metadata
|
||||
|
||||
### Strip-metadata regression
|
||||
- Re-run all existing strip-metadata tests after the shared extraction refactor to confirm no behavioral changes
|
||||
|
||||
### E2e tests (Playwright)
|
||||
- Tool appears in tool list and is navigable
|
||||
- Upload image, verify metadata displays
|
||||
- Edit a field, submit, download, re-upload and verify
|
||||
- Mark a field for removal, submit, verify removal
|
||||
- Add to `tools-all.spec.ts`
|
||||
|
||||
### Docker + Playwright GUI verification
|
||||
- Docker rebuild with cache
|
||||
- Spin up container
|
||||
- Playwright headed/GUI mode against running container
|
||||
- Manual verification: navigate to tool, upload test image with known EXIF/GPS, confirm metadata displays, edit fields, mark tags for removal, submit, download, re-upload to confirm changes persisted
|
||||
Reference in New Issue
Block a user