IPTC Studio

Manage and certify large photo batches with a self-hosted, metadata-first workflow. IPTC Studio lets you import images, apply presets, validate metadata, and export clean deliverables without relying on third-party services or databases.

---

Table of Contents

1. Highlights
2. Quick Start
3. System Requirements
4. Project Layout
5. Configuration
6. Working With Metadata
7. AI-Assisted Captioning
8. Troubleshooting
9. Contributing
10. Contact & License

---

Highlights

• 📦 Batch-focused import/export that keeps files and state on disk for air-gapped or on-premise deployments.
• ✍️ Rich metadata editor for IPTC, XMP, and EXIF fields with preset application and validation flow.
• 🤖 Optional AI assistance via Google Gemini—bring your own prompt to generate first-pass captions.
• ⚙️ Vanilla stack: HTML, CSS, and JavaScript on the frontend; a lightweight PHP JSON API on the backend.
• 🗃️ Zero external databases required—storage directories hold presets, batches, exports, and working state.

---

Quick Start

1. Clone the repository

   git clone https://github.com/<your-org>/iptc-studio.git
   cd iptc-studio

2. Prepare environment

   cp .env.example .env
   # Only required when enabling AI assistance
   # export GOOGLE_GEMINI_API_KEY="your-key"

3. Ensure writable storage

   mkdir -p storage/batches storage/exports
   chmod -R 775 storage

4. Run locally

   php -S 127.0.0.1:8000 -t .

5. Visit http://127.0.0.1:8000 and start uploading your photo batches.

---

System Requirements

Component	Details
PHP	8.2+ with json, mbstring, exif, fileinfo, gd extensions
CLI tools	exiftool v12 or newer in PATH
Web server	Apache, Nginx + PHP-FPM, Caddy, or PHP built-in server for local runs
Optional	Node.js for front-end tooling, Composer for additional PHP packages

Grant the web/PHP user write access to storage/ and its subdirectories.

---

Project Layout

.
├── api/               # JSON endpoints for uploads, updates, exports, AI, presets
├── assets/            # Vanilla JS UI logic and CSS stylesheets
├── src/               # Domain services (BatchStore, MetadataService, PresetStore…)
├── storage/           # Batches, exports, presets, and working state (state.json)
├── index.php          # Frontend bootstrap shell
├── preset.php         # Preset editor interface
└── README.md          # You are here

---

Configuration

• GOOGLE_GEMINI_API_KEY — only required when enabling AI-assisted metadata generation.
• storage/preset.json — optional JSON file to preload metadata fields like creator, credit, usageTerms, etc. Leave values empty for manual entry.
• PHP ini values upload_max_filesize and post_max_size should accommodate your batch sizes.

Document your presets and environment values alongside deployment notes for faster onboarding.

---

Working With Metadata

• Upload images via drag-and-drop or file dialog; batches live under storage/batches/{batchId} with a state.json descriptor.
• Edit metadata using the in-browser editor; the backend synchronizes updates through api/update.php.
• Validate by applying presets, reviewing AI suggestions (if enabled), and running the apply step to rewrite IPTC, XMP, and EXIF data via exiftool.
• Export either processed images (api/export_images.php) or structured datasets (api/export.php) in JSON/CSV formats.

---

AI-Assisted Captioning

• Implement your own prompt in api/ai_generate.php via the buildGeminiPrompt function.
• Provide descriptive context (who, what, when, where, why) per asset for better caption quality.
• The backend queues Gemini calls, merges results, and flags assets as aiGenerated for easy review before applying metadata changes.

---

Troubleshooting

• ❌ Uploads failing? Check PHP upload_max_filesize/post_max_size and write permissions on storage/batches.
• ❌ Preset not applying? Confirm storage/preset.json exists, is readable, and contains the expected keys.
• ❌ AI errors? Validate your Gemini API key and that outbound HTTPS is allowed from the server.
• ❌ Missing thumbnails? Ensure the PHP gd extension is enabled.

---

Contributing

Contributions are welcome! Open a pull request describing the problem you solve, include testing notes, and update documentation when behavior changes. Follow PSR-12 formatting and run php -l on modified files.

---

Contact & License

• 📫 Questions or commercial inquiries: polgebenjamin(at)outlook.com
• 📄 Licensed under the GNU Affero General Public License v3. Commercial SaaS hosting or resale requires written permission from Benjamin Polge.