Visual Editing & Imaging Laboratory
Beyond what meets the eye.
Features • Status • Quick Start • Screenshots • Documentation • API
VEIL is a local-first web application for viewing, organizing, and analyzing images generated by ComfyUI. Every generated file is treated as a carrier of reproducible intelligence: prompts, sampler settings, models, LoRAs, and the complete node graph are extracted from PNG text chunks, EXIF, and embedded ComfyUI workflow JSON - all in a fast, keyboard-driven interface.
Under the surface it is more than a gallery: metadata stays attached to the workflow that created it, the Media Library is a virtual database view over your real folders, AI prompting is compiled from layered model-aware skills instead of one universal system prompt, and the integrated ComfyUI runtime can turn an existing asset back into a queueable workflow - everything runs locally with no cloud dependency.
- Metadata extraction from PNG chunks, EXIF, and ComfyUI workflow JSON
- Interactive workflow graph visualization with color-coded nodes
- Live source monitoring for local and desktop-synced cloud folders, with no file copying
- Image and video uploads - drop supported media into the app; images stay lazy while videos receive technical metadata and a poster frame when FFmpeg tools are available
- Object cutout - automatic background removal with transparent PNG export
- SQLite persistence - all data survives restarts
- Media Library - virtual albums, favorites, ratings, tags, notes, and bulk selection without moving source files
- Unified image and video assets - shared sources, albums, favorites, previews, and technical metadata
- Unified media browsing - folders, albums, the central gallery, and the Media sidebar can show images and videos together or filter either type independently
- Create workspace - Moody Krea2 with From text, From photo, Variation, and Edit photo modes on local ComfyUI Desktop or Colab
- ComfyUI execution - integrated runtime setup, dependency preflight, queue state, cancellation, result import, and workflow provenance
- Remix - open a Viewer image in Create as a Variation without starting generation automatically
- Providers and models - local AI tools (OpenCode, Claude Code, Codex, Antigravity) and API providers from the models.dev catalog or any OpenAI-compatible endpoint, with OS-keyring or environment-variable keys; choose which models the pickers show and a default model
- Model-aware prompt compiler - layered family, operation, scenario, modifier, and output-contract instructions with strict structured results
- Keyboard-first workflow with 14 shortcuts
- Virtuality first - albums, favorites, ratings, tags, and notes live in the database as a view over the real folders: nothing is moved, renamed, or copied. Even a factory reset rebuilds the index without touching a single source file.
- In-place indexing - sources are scanned in place with an incremental cache, and desktop-synced cloud folders can be watched continuously without duplicating data on disk.
- Provenance as data - the original ComfyUI workflow graph is preserved per asset, rendered as an interactive color-coded node graph, and retained in its original metadata.
- Local & private - runs on
localhostwith no cloud dependency; AI provider credentials are stored masked in the OS keyring or environment variables, and authenticated local CLIs (OpenCode, Claude Code, Antigravity) are discovered automatically. - Model-aware AI tooling - prompting is compiled from layered family (FLUX / SDXL / Pony), operation, scenario, and modifier skills into strict structured output, guarded by deterministic intent judges and CLI-run benchmarks; the same engine powers AI prompt enhancement and vision reconstruction inside Create.
- ComfyUI-native execution - detects and can auto-start a local ComfyUI (including portable installs), queues generation, and imports results back with full provenance.
- Unified media - images and videos share one pipeline: uploads, previews (video poster frames need FFmpeg), a virtual library, and independent media-type filters.
Not every planned surface is wired into the running product yet. This section separates what works end-to-end today from what is laid out as infrastructure (scaffold) but not yet usable from the UI.
Implemented - works from the UI today:
- Core viewer - gallery & lightbox, metadata tabs, folder scan + live source monitoring, fuzzy search, object cutout, image/video uploads.
- Media Library - albums, favorites, ratings, tags, notes, bulk selection, deletion to the system trash.
- Unified image/video assets - shared sources, albums, previews, and media-type filters (video previews require FFmpeg).
- BYOK AI providers - API providers with keyring/env credentials and local CLI discovery (OpenCode, Claude Code, Antigravity); the prompt compiler, intent/quality benchmarks, and smoke runners are functional via CLI.
- ComfyUI runtime - auto-detection/auto-start, queue, cancellation, result import, and workflow provenance.
- Create - generation - one Moody Krea2 model with text, photo description, Variation and instruction editing; model setup, durable tasks and local/Colab execution.
- Remix - the Viewer lightbox attaches the original image in Create as a Variation; generation remains a separate user action.
Scaffold / partial - laid out, but not working end-to-end from the UI:
- Social publishing (VK / Telegram / Instagram) - provider cards render on the Integrations page, but publishing is unimplemented for all providers, and VK OAuth works only over port 80.
The Electron desktop version preserves the existing Flask UI. On Windows,
start.bat launches the desktop app; use start.bat --web for browser development.
Build and runtime details: Electron desktop.
|
Gallery view Masonry grid layout with thumbnails and quick metadata preview on hover. |
Lightbox with metadata Prompts, generation parameters, and model info at a glance. |
|
|
|
Gallery browsing Smooth scrolling through large galleries with lazy-loaded thumbnails. |
Workflow inspection Zoom, pan, and inspect individual ComfyUI node parameters. |
|
|
The Windows installer includes Electron, Python and the video tools. See desktop build and launch instructions for the local installer.
For development from source:
- Python 3.10+
- Poetry (for dependency management)
- Node.js and npm (for Electron)
# Clone the repository
git clone https://github.com/Lotargo/ComfyUI-Meta-Viewer.git
cd ComfyUI-Meta-Viewer
# Install dependencies
poetry config virtualenvs.in-project true --local
poetry install --no-root
npm ci# Start the server (opens browser automatically)
poetry run python -m app.main
# Desktop launcher (uses the built app when available on Windows)
# Windows:
start.bat
# Windows, always from source (ignores a built dist/ app):
desktop.bat
# Linux/macOS:
chmod +x start.sh
./start.shThe launcher opens the desktop window. Browser mode (start.bat --web or
./start.sh --web) is available at http://localhost:7860.
- Connect a folder - use Open Folder, then toggle monitoring or recursive subfolder scanning from the source card
- Browse media - use the Media sidebar to show images, videos, or both; click an item to preview it
- View metadata - Summary tab shows prompt + settings
- Explore workflow - Workflow tab shows the ComfyUI node graph
- Search - Ctrl+F to fuzzy search across all metadata
- Cutout - Select an image and generate a transparent PNG
- Configure AI - open the AI page, add an endpoint or import a detected local CLI, choose exact model IDs, and test text or image support
- Create - choose From text, From photo, Variation, or Edit photo; add the needed photos, choose an agent model, and press Create. Moody Krea2 runs locally or on Colab.
- Remix - open an image from the lightbox in Create's Variation mode, then start generation when ready.
- Custom Nodes & Workflows: Standard built-in workflow templates cover checkpoint-contained, Flux separate-components, Pony/SDXL GGUF, reference, and video pipelines. Highly customized third-party node workflows can be imported using the mapping wizard, but complex multi-pipeline graphs may require manual node binding or mapping adjustment.
- Desktop Distribution: The first Electron/Flask Windows build and NSIS installer are available locally. Public releases, signing, auto-update and native macOS/Linux desktop acceptance remain later stages.
- FFmpeg Dependency: Packaged desktop builds bundle
ffmpeg/ffprobe. Source/browser development requires those binaries onPATHor explicitMEDIASTUDIO_FFMPEG/MEDIASTUDIO_FFPROBEpaths. - Platform Support: Primary release platform is Windows; cross-platform validation is performed via GitHub Actions CI for Linux and macOS.
| Layer | Technology | Purpose |
|---|---|---|
| Backend | Python 3.10+ | Server logic |
| HTTP | Flask 3.1 | REST API + static files |
| Database | SQLite (WAL mode) | Metadata storage |
| Validation | Pydantic v2 | Request/response models |
| Images | Pillow 11.0 | Metadata extraction, thumbnails, cutout |
| Monitoring | Watchdog 6.0 | Cross-platform filesystem events |
| Secrets | Keyring 25.x | Windows Credential Manager, macOS Keychain, or Linux Secret Service |
| Frontend | Vanilla JS (ES modules) | SPA interface |
| CSS | Custom Properties | Modular styling |
| Search | Fuse.js 7.0 | Fuzzy search (vendored in app/static/js/vendor/) |
| Tracing | OpenTelemetry | Optional traces via OTLP exporter |
| Tests | pytest | Unit + integration suite (see tests/) |
| Dependencies | Poetry | Package management |
| Document | Description |
|---|---|
| Architecture | System overview, data flow, database schema |
| API Reference | Detailed supported REST endpoints, behavior and examples |
| Interactive API | Scalar portal backed directly by the public OpenAPI 3.1 contract |
| Features | Detailed feature descriptions |
| Configuration | Environment variables, paths, CLI flags |
| Development | Guide for contributors and public API synchronization rules |
| JS Architecture | Frontend module structure |
| CSS Architecture | Styling system and custom properties |
| Prompt intent benchmarks | Targeted raw-intent generation and model-judge evaluation |
| OpenCode smoke testing | Managed CLI execution, profiles, scenarios, and reports |
| AI prompt architecture | Canonical profiles, compilation, execution routing, persistence, and skill export |
| ComfyUI runtime | Runtime configuration and lifecycle; the old workflow editor has been removed |
| Roadmap | AI prompt compiler status, benchmark targets, and planned work |
VEIL exposes a local REST API at http://localhost:7860. The machine-readable public contract is site/api/openapi.json and the interactive Scalar portal is available at lotargo.github.io/ComfyUI-Meta-Viewer/api/.
The public contract covers every supported /api/* route. The old workflow editor, /api/editor/*, /editor/legacy, /settings/comfyui, and /api/ai/remix were removed on 2026-10-14. Shared Create execution, local/Colab downloads, saved history, and user template files are preserved.
| Area | Method | Endpoint | Description |
|---|---|---|---|
| Sources | POST |
/api/scan |
Connect and index a source directory |
| Sources | PATCH |
/api/folders/{id} |
Enable/disable a source or change recursion |
| Sources | POST |
/api/folders/{id}/reconcile |
Queue a full source reconciliation |
| Media | POST |
/api/upload |
Upload image or video files |
| Media | GET |
/api/images |
List paginated image/video assets |
| Media | GET |
/api/assets/{id} |
Get unified asset details and separated metadata layers |
| Library | GET |
/api/library/assets |
Query the virtual library with filters |
| Library | POST |
/api/library/assets/bulk |
Apply bulk virtual-library operations |
| Preview | GET |
/api/preview/{id} |
Get or generate a bounded display preview |
| AI | GET/POST |
/api/ai/providers |
Connect local AI tools and API providers |
| AI | GET |
/api/ai/models |
Models of the connected providers and which ones pickers show |
| AI | POST |
/api/ai/generate |
Generate a durable prompt draft |
| AI | POST |
/api/ai/translate |
Translate prompt text, optionally through SSE |
| AI | POST |
/api/ai/adapt |
Adapt a prompt to a target model family |
| AI | POST |
/api/ai/enhance |
Enhance prompt composition and detail |
| AI | POST |
/api/ai/reconstruct/analyze |
Analyze an indexed image into a SceneSpec |
| ComfyUI | GET |
/api/comfyui/status |
Read runtime and queue state |
| ComfyUI | POST |
/api/comfyui/start |
Start a managed local ComfyUI instance |
| Create | GET |
/api/simple/models |
List curated Simple Mode models |
| Create | POST |
/api/simple/generate |
Queue Simple Mode generation |
| Create | GET |
/api/simple/runs/{run_id} |
Refresh run state and imported outputs |
| Social | GET |
/api/social/status |
Inspect social integration capability/auth status |
| System | GET |
/api/diagnostics |
Read local diagnostics and cache statistics |
Full behavior and examples: docs/core/api.md.
| Key | Action |
|---|---|
← → |
Navigate images |
Enter |
Open lightbox |
Escape |
Close lightbox / panel |
Delete |
Delete image |
Ctrl+F |
Search |
G |
Toggle gallery/list |
? |
Help Center |
1 2 3 |
Switch meta tabs |
D |
Toggle meta panel |
S |
Toggle sidebar |
Full shortcuts list: docs/core/features.md#keyboard-shortcuts
| Variable | Default | Description |
|---|---|---|
MEDIASTUDIO_PORT |
7860 |
Server port |
MEDIASTUDIO_DATA_DIR |
.mediastudio_data |
Database and application data directory |
MEDIASTUDIO_CACHE_DIR |
cache |
Thumbnail, preview, and cutout cache directory |
MEDIASTUDIO_UPLOAD |
- | Legacy alias for MEDIASTUDIO_DATA_DIR |
Full configuration: docs/core/configuration.md
See Development Guide for setup instructions and code style.
- Add the route to the owning public module (
app/main.py,app/ai/routes.py,app/comfyui/routes.py,app/comfyui/simple_routes.py, orapp/integrations/social/routes.py). - Add Pydantic request/response validation where useful.
- Add the operation to
site/api/openapi.jsonwith its method, path parameters, tags, summary, and uniqueoperationId. - Document detailed behavior in
docs/core/api.md. - Add/update a frontend wrapper only when the browser UI consumes the endpoint.
- Run
poetry run python -m pytest tests -q;tests/test_openapi_contract.pyrejects public Flask/OpenAPI drift.
The pre-Simple-Mode editor and its /api/editor/* routes have been removed. Create uses app/comfyui/simple_routes.py and retains shared runtime inventory, durable tasks/runs, output import and local/Colab downloads.
- Create module in
app/static/js/features/ - Create styles in
app/static/css/features/ - Import in
app.js - Document in
docs/core/features.md
GNU Affero General Public License v3.0 only. See LICENSE.




