Skip to content
LotargoPublic

About

Local-first media library for ComfyUI. Browse images and videos, inspect embedded prompts and workflows, and remix images with ComfyUI.

Topics

Resources

Stars

1 star

Watchers

0 watching

Forks

Latest commit

 

History

574 Commits

Folders and files

Repository files navigation

VEIL banner

Visual Editing & Imaging Laboratory
Beyond what meets the eye.

Version Python Platform Flask SQLite License

Features • Status • Quick Start • Screenshots • Documentation • API


Overview

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.

Key capabilities

  • 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

Design decisions

  • 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 localhost with 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.

Feature Status

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.

Features

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.

Metadata Metadata Extraction
Prompts, settings, models, LoRA, EXIF
Workflow Workflow Visualization
Interactive SVG graph of ComfyUI nodes
Folder Folder Scanning
In-place scan with incremental caching
Gallery Gallery & Lightbox
Cached 4K previews, cursor zoom, click-drag pan, and full-original access
Search Fuzzy Search
Search by filename, prompt, model, sampler
Cutout Object Cutout
Auto background removal, transparent PNG
Keyboard Keyboard Shortcuts
14 shortcuts + Help Center
Folders Live Source Index
Watcher + periodic reconciliation
Diagnostics Diagnostics
System stats in Help Center

Screenshots

Interface

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 View Lightbox Detail

Motion Demos

Gallery browsing
Smooth scrolling through large galleries with lazy-loaded thumbnails.
Workflow inspection
Zoom, pan, and inspect individual ComfyUI node parameters.
Gallery Scroll Lightbox Workflow

Quick Start

Prerequisites

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)

Installation

# 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

Running

# 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.sh

The launcher opens the desktop window. Browser mode (start.bat --web or ./start.sh --web) is available at http://localhost:7860.

Usage

  1. Connect a folder - use Open Folder, then toggle monitoring or recursive subfolder scanning from the source card
  2. Browse media - use the Media sidebar to show images, videos, or both; click an item to preview it
  3. View metadata - Summary tab shows prompt + settings
  4. Explore workflow - Workflow tab shows the ComfyUI node graph
  5. Search - Ctrl+F to fuzzy search across all metadata
  6. Cutout - Select an image and generate a transparent PNG
  7. 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
  8. 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.
  9. Remix - open an image from the lightbox in Create's Variation mode, then start generation when ready.

Known Limitations

  • 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 on PATH or explicit MEDIASTUDIO_FFMPEG / MEDIASTUDIO_FFPROBE paths.
  • Platform Support: Primary release platform is Windows; cross-platform validation is performed via GitHub Actions CI for Linux and macOS.

Tech Stack

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

Documentation

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

API Reference

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.

Representative public endpoints

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.


Keyboard Shortcuts

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


Configuration

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


Contributing

See Development Guide for setup instructions and code style.

Adding a new public API endpoint

  1. Add the route to the owning public module (app/main.py, app/ai/routes.py, app/comfyui/routes.py, app/comfyui/simple_routes.py, or app/integrations/social/routes.py).
  2. Add Pydantic request/response validation where useful.
  3. Add the operation to site/api/openapi.json with its method, path parameters, tags, summary, and unique operationId.
  4. Document detailed behavior in docs/core/api.md.
  5. Add/update a frontend wrapper only when the browser UI consumes the endpoint.
  6. Run poetry run python -m pytest tests -q; tests/test_openapi_contract.py rejects 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.

Adding a new frontend feature

  1. Create module in app/static/js/features/
  2. Create styles in app/static/css/features/
  3. Import in app.js
  4. Document in docs/core/features.md

License

GNU Affero General Public License v3.0 only. See LICENSE.


Acknowledgments

About

Local-first media library for ComfyUI. Browse images and videos, inspect embedded prompts and workflows, and remix images with ComfyUI.

Topics

Resources

Stars

1 star

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages