MajoorWaldi-ComfyUI-Majoor-AssetsManager/docs/USER_GUIDE.md

Majoor Assets Manager - Comprehensive User Guide

Table of Contents

1. Introduction
2. Installation & Setup
3. Core Features
4. Search & Filtering
5. Metadata & Viewer
6. Ratings, Tags & Collections
7. Drag & Drop Functionality
8. Hotkeys & Shortcuts
9. Settings & Configuration
10. Troubleshooting

Introduction

The Majoor Assets Manager is an advanced asset browser for ComfyUI that provides a comprehensive solution for managing, organizing, and viewing your generated assets. It integrates directly into ComfyUI, offering features like full-text search, metadata extraction, rating and tagging systems, and advanced viewing capabilities.

Key Benefits

• Browse output, input, and custom directories directly in ComfyUI
• High Performance: Virtualized grid for browsing 10k+ assets and GPU-accelerated video viewer.
• Powerful search with full-text indexing
• Rich metadata extraction from generated assets
• Rating and tagging systems for organization
• Collections for grouping related assets
• Advanced viewer with comparison tools
• Drag-and-drop integration with ComfyUI canvas

Installation & Setup

Prerequisites

• ComfyUI installation
• Python 3.8 or higher

Installation Methods

Method 1: Using ComfyUI Manager (Recommended)

1. Open ComfyUI Manager
2. Search for "Majoor Assets Manager"
3. Install the extension
4. Restart ComfyUI

Method 2: Manual Installation

cd ComfyUI/custom_nodes
git clone https://github.com/MajoorWaldi/ComfyUI-Majoor-AssetsManager ComfyUI-Majoor-AssetsManager
pip install -r ComfyUI-Majoor-AssetsManager/requirements.txt

Restart ComfyUI.

Optional Dependencies (Highly Recommended)

For enhanced metadata extraction and file tagging capabilities, install these tools:

Windows

Using Scoop:

scoop install ffmpeg exiftool

Using Chocolatey:

choco install -y ffmpeg exiftool

Using WinGet:

winget install -e --id Gyan.FFmpeg
winget install -e --id PhilHarvey.ExifTool

macOS

brew install ffmpeg exiftool

Linux (Ubuntu/Debian)

sudo apt-get update
sudo apt-get install -y ffmpeg exiftool

Verify installation:

exiftool -ver
ffprobe -version

If tools are not in PATH, set environment variables:

• MAJOOR_EXIFTOOL_PATH - Path to exiftool executable
• MAJOOR_FFPROBE_PATH - Path to ffprobe executable

Core Features

Asset Browser Interface

The Assets Manager provides a tabbed interface with four main scopes:

• Outputs: Browse your ComfyUI output directory
• Inputs: Browse your ComfyUI input directory
• Custom: Browse user-defined directories
• Collections: Browse saved collections of assets

Initial Setup

1. Open the Assets Manager panel in ComfyUI
2. Select a scope (Outputs, Inputs, Custom, or Collections)
3. The interface will automatically scan and index assets in the selected scope
4. Use search and filters to narrow down results

Navigation

• Click on asset cards to select them
• Double-click on asset cards to open the viewer
• Right-click on asset cards for context menu options
• Use pagination controls to navigate through large result sets

Search & Filtering

Full-Text Search

The Assets Manager uses SQLite FTS5 with BM25 ranking for powerful search capabilities:

• Type any text in the search box to search across all indexed assets
• Search looks through filenames, metadata, prompts, and other text fields
• Results are ranked by relevance using BM25 algorithm
• Search works across all scopes (Outputs, Inputs, Custom, Collections)

Advanced Filters

Kind Filter

Filter by file type:

• Images (PNG, JPG, WEBP, etc.)
• Videos (MP4, MOV, AVI, etc.)
• Workflows (JSON, PNG with embedded workflows)

Rating Filter

• Show only assets with minimum rating (1-5 stars)
• Useful for quickly finding your best results

Workflow Filter

• Filter to show only assets with embedded workflow information
• Helpful when looking for specific generation parameters

Date Filters

• Filter by creation/modification dates
• Useful for finding recent or historical assets

Sorting Options

• Sort by name, date, size, rating, or relevance
• Toggle ascending/descending order

Search Tips

• Use quotes for exact phrase matching: "landscape portrait"
• Combine multiple terms for broader search: character landscape
• Use the summary line to see total assets and current selection count

Metadata & Viewer

Metadata Extraction

The Assets Manager extracts rich metadata from your assets:

Image Metadata

• Generation parameters (prompt, negative prompt, model, sampling parameters)
• Workflow information (with minimap preview)
• Technical details (resolution, file size, format)
• Custom tags and ratings

Video Metadata

• Duration, frame rate, resolution
• Audio information if present
• Generation parameters if embedded

Extraction Backends

The system uses multiple backends for metadata extraction:

• ExifTool: Most comprehensive, handles all formats
• FFprobe: Specialized for video/audio
• Built-in: Basic extraction when external tools unavailable

Advanced Viewer

Single View Mode

• Zoom and pan functionality
• 1:1 pixel view for detail inspection
• Exposure adjustment (EV controls)
• Gamma correction
• Channel isolation (RGB/R/G/B/Alpha/Luma)
• Analysis tools (false color, zebra patterns)

Comparison Modes

• Side-by-side: Compare two assets visually
• A/B Compare: Toggle between two assets
• Wipe: Slider to reveal one asset over another
• Difference: Show mathematical difference between assets

Video Player

• Loop/once playback options
• Seek controls with timeline
• In/Out point markers for segment playback
• Frame-by-frame stepping
• Adjustable playback speed

Overlays

• Grid overlays (thirds, center, safe area, golden ratio)
• Pixel probe for color values
• Loupe magnification
• Histogram and waveform scopes

Export Options

• Save current frame as PNG
• Copy to clipboard (best-effort)
• Download original file

Context Menu Actions

Right-click on any asset to access:

• Add/remove from collections
• Rate the asset (0-5 stars)
• Tag the asset
• Open in folder
• Copy file path
• Rename file
• Delete file
• Refresh metadata

Ratings, Tags & Collections

Rating System

• Rate assets from 0 to 5 stars
• Ratings are stored in the index database
• Optionally synced to file metadata when external tools are available
• Filter by minimum rating to quickly find your best results

Tagging System

• Add custom tags to organize assets
• Tags are stored in the index database
• Optionally synced to file metadata when external tools are available
• Search by tags to find related assets
• Bulk tagging for multiple selections

Collections

Collections allow you to group related assets:

Creating Collections

1. Select one or more assets
2. Right-click and choose "Add to Collection"
3. Choose an existing collection or create a new one
4. Name your collection appropriately

Managing Collections

• View all collections in the Collections tab
• Add or remove items from collections
• Rename or delete collections
• Collections are stored as JSON files in the index directory

Collection Features

• Duplicate items are automatically skipped
• Large collections are capped for performance (default 50,000 items)
• Collections can span multiple directories
• Share collections by sharing the JSON files

Drag & Drop Functionality

Drag to ComfyUI Canvas

• Drag assets directly onto the ComfyUI canvas
• Assets are automatically staged to compatible input nodes
• File paths are injected into appropriate nodes
• Works with single or multiple selections

Drag to Operating System

• Drag assets to your file explorer/desktop
• Single files are opened directly
• Multiple selections are packaged into a ZIP file
• ZIP files are created on-demand and cleaned up automatically
• Supports DownloadURL and text/uri-list protocols

Filename Collision Indicator

• When multiple assets share the same filename, the extension badge shows EXT+ (e.g., PNG+)
• Helps identify duplicate filenames in your asset collection

Hotkeys & Shortcuts

Global Hotkeys

These work throughout the Assets Manager interface:

• Ctrl/Cmd+S: Trigger index scan for current scope
• D: Toggle details sidebar for current selection
• 0-5: Set rating for current selection (when interacting with grid)

Viewer Hotkeys

These work only when the viewer is open:

• Esc: Close viewer
• 0-5: Set rating (single view)
• Shift+Arrow: Step video frames (single video)
• F: Toggle false color analysis
• Z: Toggle zebra patterns
• G: Cycle through grid overlays (off → thirds → center → safe → golden)
• I: Toggle pixel probe
• L: Toggle loupe magnification
• C: Copy last probed color hex value
• Alt+1: Toggle 1:1 zoom

Notes

• Hotkeys are ignored while typing in input fields
• Viewer hotkeys are captured and don't leak to ComfyUI or global handlers

Settings & Configuration

Browser-Based Settings

Stored in localStorage under mjrSettings:

Display Settings

• Page size: Number of assets loaded per request
• Sidebar position: Left or right placement
• Hide PNG siblings: Hide PNG files when video previews exist
• Auto-scan: Automatically scan on open/startup

Performance Settings

• Status poll interval: How often to check background tasks
• Tags cache TTL: Time-to-live for tag caching (milliseconds)

Viewer Settings

• Media probe backend: Auto, ExifTool, FFprobe, or both
• Workflow minimap display: Toggle elements in workflow preview
• Observability: Enable request logging

Backend Configuration

Environment Variables

Configure the backend using environment variables:

# Override output directory
export MAJOOR_OUTPUT_DIRECTORY="/path/to/output"

# Specify tool paths if not in PATH
export MAJOOR_EXIFTOOL_PATH="/path/to/exiftool"
export MAJOOR_FFPROBE_PATH="/path/to/ffprobe"

# Set media probe backend
export MAJOOR_MEDIA_PROBE_BACKEND="auto"  # auto, exiftool, ffprobe, both

# Enable file watcher for auto-reindexing
export MAJOOR_ENABLE_FILE_WATCHER=true

# Database tuning
export MAJOOR_DB_TIMEOUT=30.0
export MAJOOR_DB_MAX_CONNECTIONS=8
export MAJOOR_DB_QUERY_TIMEOUT=30.0

# Watcher settings
export MAJOOR_WATCHER_INTERVAL=15.0
export MAJOOR_WATCHER_JOIN_TIMEOUT=5.0

# Collection limits
export MJR_COLLECTION_MAX_ITEMS=50000

# Allow symlinks in custom roots
export MJR_ALLOW_SYMLINKS=on

Troubleshooting

Common Issues

Missing Dependencies

If you see warnings about missing dependencies:

1. Check that all requirements are installed: pip install -r requirements.txt
2. Install optional tools (ExifTool, FFprobe) for full functionality
3. Verify tools are in your system PATH or set environment variables

Slow Performance

• Large collections may take time to load
• Increase page size for fewer requests
• Ensure external tools (ExifTool, FFprobe) are properly installed
• Adjust database connection settings if needed

Index Not Updating

• Use Ctrl/Cmd+S to manually trigger a scan
• Enable file watcher for automatic updates
• Check permissions on output directory

Metadata Extraction Issues

• Verify ExifTool and FFprobe are installed and accessible
• Check file permissions for metadata access
• Some file formats may not contain embedded metadata

File Locations

• Index Database: <output>/_mjr_index/assets.sqlite
• Custom Roots: <output>/_mjr_index/custom_roots.json
• Collections: <output>/_mjr_index/collections/*.json
• Temporary ZIPs: <output>/_mjr_batch_zips/ (auto-cleaned)

Security Considerations

• CSRF protection on state-changing endpoints
• Rate limiting on expensive operations
• Path validation to prevent directory traversal
• Trusted proxy configuration for forwarded headers

Best Practices

Organization

• Use collections to group related assets
• Apply consistent tagging schemes
• Regularly rate your assets to identify quality results
• Clean up unused collections periodically

Performance

• Keep collections reasonably sized (under 50,000 items)
• Use filters to narrow down large result sets
• Periodically optimize the database through the maintenance tools
• Monitor index size and rebuild if needed

Workflow Integration

• Use drag-and-drop to quickly incorporate assets into workflows
• Leverage metadata to reproduce good results
• Share collections with team members
• Use the viewer to compare different generation approaches

---

Documentation Version: 1.0
Last Updated: January 2026