Introduction

Tip: edit docs/DOCUMENTATION_INDEX.md to change the curated order, then regenerate with python scripts/build_user_guide_html.py.

DOCUMENTATION_INDEX.md

Documentation index (curated list)

Majoor Assets Manager - Documentation Index

Welcome to the comprehensive documentation for the Majoor Assets Manager for ComfyUI. This collection of guides will help you understand and utilize all features of the extension.

Documentation Files

Getting Started

USER_GUIDE.md - Comprehensive overview and introduction
../user_guide.html - Full HTML user guide (styled)
INSTALLATION.md - Detailed installation and setup instructions

Core Features

SEARCH_FILTERING.md - Full-text search and filtering capabilities
METADATA_VIEWER.md - Metadata extraction and advanced viewer features
RATINGS_TAGS_COLLECTIONS.md - Organization tools (ratings, tags, collections)
DRAG_DROP.md - Drag and drop functionality

Configuration & Usage

HOTKEYS_SHORTCUTS.md - Keyboard shortcuts and hotkeys
SETTINGS_CONFIGURATION.md - Settings and configuration options
SECURITY_ENV_VARS.md - Security model and environment variables
TESTING.md - Running tests and reading reports

Complete Guides

COMPLETE_USER_GUIDE.md - Step-by-step user guide with workflows

Quick Start

Install: Follow the instructions in INSTALLATION.md
Explore: Open Assets Manager in ComfyUI and browse your outputs
Organize: Use ratings, tags, and collections to organize your assets
Search: Use the powerful search and filtering features
Integrate: Drag assets directly to your ComfyUI canvas

Key Features Overview

Advanced Asset Browser: Browse outputs, inputs, custom directories, and collections
Powerful Search: Full-text search with FTS5 and BM25 ranking
Rich Metadata: Extract generation info from PNG/WEBP/video files
Advanced Viewer: With comparison tools, analysis features, and enhancement controls
Organization Tools: Ratings (0-5 stars), custom tags, and collections
Drag & Drop: To ComfyUI canvas or to your operating system
Cross-Platform: Works on Windows, macOS, and Linux

Optional Dependencies (Highly Recommended)

For full functionality including metadata extraction and file tagging:

ExifTool: For comprehensive metadata extraction
FFprobe: For video/audio metadata extraction

See INSTALLATION.md for detailed installation instructions.

Support

If you encounter issues:

Check the troubleshooting sections in the relevant documentation
Verify your installation and dependencies
Consult the original README.md for additional information
Check the ComfyUI console for error messages

Contributing

These documentation files are provided as a comprehensive guide to help users make the most of the Majoor Assets Manager. If you find inaccuracies or have suggestions for improvements, please contribute to the community knowledge.

Documentation Index Version: 1.0 Last Updated: January 2026

Source: docs/DOCUMENTATION_INDEX.md

USER_GUIDE.md

Comprehensive overview and introduction

Majoor Assets Manager - Comprehensive User Guide

Introduction
Installation & Setup
Core Features
Search & Filtering
Metadata & Viewer
Ratings, Tags & Collections
Drag & Drop Functionality
Hotkeys & Shortcuts
Settings & Configuration
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 outputs, inputs, and custom directories directly in ComfyUI
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)

Open ComfyUI Manager
Search for "Majoor Assets Manager"
Install the extension
Restart ComfyUI

Method 2: Manual Installation

cd ComfyUI/custom_nodes\ngit clone https://github.com/MajoorWaldi/ComfyUI-Majoor-AssetsManager ComfyUI-Majoor-AssetsManager\npip 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\nwinget install -e --id PhilHarvey.ExifTool

macOS

brew install ffmpeg exiftool

Linux (Ubuntu/Debian)

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

Verify installation:

exiftool -ver\nffprobe -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

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

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

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

Select one or more assets
Right-click and choose "Add to Collection"
Choose an existing collection or create a new one
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\nexport MAJOOR_OUTPUT_DIRECTORY="/path/to/output"\n\n# Specify tool paths if not in PATH\nexport MAJOOR_EXIFTOOL_PATH="/path/to/exiftool"\nexport MAJOOR_FFPROBE_PATH="/path/to/ffprobe"\n\n# Set media probe backend\nexport MAJOOR_MEDIA_PROBE_BACKEND="auto"  # auto, exiftool, ffprobe, both\n\n# Enable file watcher for auto-reindexing\nexport MAJOOR_ENABLE_FILE_WATCHER=true\n\n# Database tuning\nexport MAJOOR_DB_TIMEOUT=30.0\nexport MAJOOR_DB_MAX_CONNECTIONS=8\nexport MAJOOR_DB_QUERY_TIMEOUT=30.0\n\n# Watcher settings\nexport MAJOOR_WATCHER_INTERVAL=15.0\nexport MAJOOR_WATCHER_JOIN_TIMEOUT=5.0\n\n# Collection limits\nexport MJR_COLLECTION_MAX_ITEMS=50000\n\n# Allow symlinks in custom roots\nexport MJR_ALLOW_SYMLINKS=on

Troubleshooting

Common Issues

Missing Dependencies

If you see warnings about missing dependencies:

Check that all requirements are installed: pip install -r requirements.txt
Install optional tools (ExifTool, FFprobe) for full functionality
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

Source: docs/USER_GUIDE.md

INSTALLATION.md

Detailed installation and setup instructions

Majoor Assets Manager - Installation Guide

Overview

This guide provides detailed instructions for installing and configuring the Majoor Assets Manager for ComfyUI. Follow these steps to get the extension up and running with all its features.

Prerequisites

System Requirements

ComfyUI installation
Python 3.8 or higher
At least 500MB free disk space for the extension and dependencies
Administrator privileges (for installation and optional tool installations)

Supported Platforms

Windows 10/11
macOS 10.15 or higher
Linux (Ubuntu 20.04+, Debian 11+, or equivalent)

Quick Installation (Recommended)

Using ComfyUI Manager

Open ComfyUI Manager in your browser
Find "Majoor Assets Manager" in the extensions list
Click "Install" next to the extension
Wait for the installation to complete
Restart ComfyUI completely
The extension should now be available in the Assets Manager tab

Manual Installation

Step 1: Clone the Repository

Open your terminal/command prompt and navigate to your ComfyUI custom_nodes directory:

cd /path/to/your/ComfyUI/custom_nodes

Clone the repository:

git clone https://github.com/MajoorWaldi/ComfyUI-Majoor-AssetsManager ComfyUI-Majoor-AssetsManager

Step 2: Install Python Dependencies

Navigate to the extension directory and install the required packages:

cd ComfyUI-Majoor-AssetsManager\npip install -r requirements.txt

Step 3: Restart ComfyUI

Stop your ComfyUI server completely and restart it to load the new extension.

Optional Dependencies (Highly Recommended)

For full functionality including metadata extraction and file tagging, install these external tools:

Windows Installation

Option A: Using Scoop Package Manager

Install Scoop if you don't have it:

   Set-ExecutionPolicy RemoteSigned -Scope CurrentUser\n   irm get.scoop.sh | iex

Install the required tools:

   scoop install ffmpeg exiftool

Option B: Using Chocolatey Package Manager

Install Chocolatey if you don't have it:

   Set-ExecutionPolicy Bypass -Scope Process -Force\n   [System.Net.ServicePointManager]::SecurityProtocol = [System.Net.ServicePointManager]::SecurityProtocol -bor 3072\n   iex ((New-Object System.Net.WebClient).DownloadString('https://community.chocolatey.org/install.ps1'))

Install the required tools:

   choco install -y ffmpeg exiftool

Option C: Using WinGet

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

Option D: Manual Installation

FFmpeg: Download from https://www.gyan.dev/ffmpeg/builds/

Extract to a folder (e.g., C:\ffmpeg)
Add C:\ffmpeg\bin to your system PATH

ExifTool: Download from https://exiftool.org/

Download exiftool-#.##.zip
Extract to a folder (e.g., C:\exiftool)
Add C:\exiftool to your system PATH

macOS Installation

Using Homebrew (Recommended)

Install Homebrew if you don't have it:

   /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

Install the required tools:

   brew install ffmpeg exiftool

Linux Installation

Ubuntu/Debian

sudo apt update\nsudo apt install -y ffmpeg libimage-exiftool-perl

Fedora/RHEL

sudo dnf install -y ffmpeg perl-Image-ExifTool

Arch Linux

sudo pacman -S ffmpeg exiftool

Verification Steps

After installation, verify everything is working:

Step 1: Check Extension Loading

Start ComfyUI
Look for the Assets Manager tab in the interface
Check the console/logs for any error messages during startup

Step 2: Verify External Tools (if installed)

Open a terminal/command prompt and run:

exiftool -ver\nffprobe -version

Both commands should return version information without errors.

Step 3: Test Basic Functionality

Open the Assets Manager in ComfyUI
Switch between different scopes (Outputs, Inputs, Custom, Collections)
Perform a simple search to verify indexing is working
Try opening the viewer for an asset

Configuration

Environment Variables

You can configure the extension using environment variables. Add these to your shell profile or set them before starting ComfyUI:

# Override default output directory\nexport MAJOOR_OUTPUT_DIRECTORY="/path/to/your/output"\n\n# Specify tool paths if not in system PATH\nexport MAJOOR_EXIFTOOL_PATH="/path/to/exiftool"\nexport MAJOOR_FFPROBE_PATH="/path/to/ffprobe"\n\n# Set media probe backend (auto, exiftool, ffprobe, both)\nexport MAJOOR_MEDIA_PROBE_BACKEND="auto"\n\n# Enable file watching for automatic reindexing\nexport MAJOOR_ENABLE_FILE_WATCHER=true\n\n# Set watcher interval (in seconds)\nexport MAJOOR_WATCHER_INTERVAL=15.0

Windows Batch File Example

Create a batch file to set environment variables and start ComfyUI:

@echo off\nset MAJOOR_MEDIA_PROBE_BACKEND=auto\nset MAJOOR_ENABLE_FILE_WATCHER=true\nset MAJOOR_WATCHER_INTERVAL=15.0\n\nREM Start ComfyUI with the environment variables\ncd /d "C:\path\to\ComfyUI"\npython main.py --auto-launch\npause

Troubleshooting

Extension Not Appearing

Verify the folder is named correctly: ComfyUI-Majoor-AssetsManager
Check that all files were downloaded properly
Ensure ComfyUI was restarted after installation
Look for error messages in the ComfyUI console

Missing Dependencies Error

If you see messages about missing dependencies:

# Navigate to the extension directory\ncd ComfyUI-Majoor-AssetsManager\npip install -r requirements.txt

External Tools Not Found

If metadata extraction isn't working:

Verify tools are installed: exiftool -ver and ffprobe -version
Check if tools are in your system PATH
Set environment variables to point to the executables directly

Permission Errors

Ensure ComfyUI has read/write access to the output directory
On Windows, run as administrator if needed
On Unix systems, check file permissions with ls -la

Slow Performance

The first scan may take time for large directories
Subsequent scans will be faster due to incremental indexing
Consider excluding very large directories that don't contain relevant assets

Post-Installation Setup

First-Time Usage

Open ComfyUI and navigate to the Assets Manager tab
The extension will automatically begin indexing your output directory
Wait for the initial scan to complete (progress shown in status bar)
Use the search bar to find assets
Right-click on assets to access context menus

Adding Custom Directories

Right-click in the Assets Manager interface
Select "Add Custom Root"
Enter the path to your custom directory
The directory will be added to the Custom scope

Creating Your First Collection

Select one or more assets
Right-click and choose "Add to Collection"
Create a new collection or add to an existing one
Access your collections from the Collections tab

Updates

Using ComfyUI Manager

Updates will be available through the ComfyUI Manager interface when released.

Manual Updates

cd ComfyUI/custom_nodes/ComfyUI-Majoor-AssetsManager\ngit pull origin main\npip install -r requirements.txt --upgrade

Remember to restart ComfyUI after updating.

Uninstallation

Using ComfyUI Manager

Simply click "Uninstall" in the ComfyUI Manager interface.

Manual Removal

Delete the ComfyUI-Majoor-AssetsManager folder from custom_nodes
Restart ComfyUI
The extension will be completely removed

Installation Guide Version: 1.0 Last Updated: January 2026

Source: docs/INSTALLATION.md

SEARCH_FILTERING.md

Full-text search and filtering capabilities

Majoor Assets Manager - Search & Filtering Guide

Overview

The Majoor Assets Manager provides powerful search and filtering capabilities to help you quickly find and organize your assets. This guide explains all the search and filtering features available in the extension.

Full-Text Search

How It Works

The Assets Manager uses SQLite FTS5 with BM25 ranking to provide fast and accurate search results. The search indexes:

Filenames and file extensions
Embedded metadata (prompts, models, parameters)
Workflow information
Tags and ratings
File content where applicable

Basic Search

Locate the search bar at the top of the Assets Manager interface
Type any text you want to search for
Press Enter or wait for results to appear automatically
Results are displayed with relevance ranking

Search Syntax

Simple Terms

Type any word or phrase to search for it
Example: landscape finds all assets with "landscape" in their metadata

Exact Phrases

Use quotes to search for exact phrases
Example: "fantasy character" finds assets with that exact phrase

Multiple Terms

Search for multiple terms simultaneously
Results containing more terms rank higher
Example: portrait fantasy digital finds assets matching any or all terms

Search Scopes

Search works across all available scopes:

Outputs: Search in your ComfyUI output directory
Inputs: Search in your ComfyUI input directory
Custom: Search in user-defined directories
Collections: Search within saved collections

Filtering Options

Kind Filter

Filter assets by file type:

Image Formats

PNG: Portable Network Graphics files
JPG/JPEG: Joint Photographic Experts Group files
WEBP: Modern image format with compression
GIF: Animated or static graphics interchange format
BMP: Bitmap image files
TIFF/TIF: Tagged Image File Format

Video Formats

MP4: MPEG-4 Part 14 video files
MOV: Apple QuickTime movie files
AVI: Audio Video Interleave files
MKV: Matroska video files
WEBM: WebM video files
FLV: Flash video files

Workflow Formats

JSON: Workflow definition files
PNG: PNG files with embedded workflows

Rating Filter

Filter by star ratings (0-5 stars):

Click the rating filter dropdown
Select minimum rating threshold
Only assets with equal or higher ratings will be displayed
Useful for quickly finding your best results

Workflow Filter

Toggle to show only assets with embedded workflow information:

Shows only assets that contain workflow data
Helpful when looking for specific generation parameters
Particularly useful for reproducible results

Date Filters

Filter assets by creation or modification dates:

Open the date filter panel
Select date range using calendar pickers
Apply the filter to narrow results
Useful for finding recent work or historical assets

Advanced Filters

Hide PNG Siblings

When working with video generations that include PNG previews:

Enable this option to hide PNG files when video previews exist
Reduces clutter from duplicate content in different formats
Keeps your view focused on the primary asset type

Sort Options

Sort results by various criteria:

Relevance: Based on search term matching (default)
Name: Alphabetical by filename
Date: Chronological by creation/modification date
Size: By file size (ascending/descending)
Rating: By star rating (ascending/descending)
Kind: By file type

Search Tips & Best Practices

Effective Search Strategies

Be Specific: Use specific terms for better results

Instead of: character
Try: "fantasy warrior" or "cyberpunk city"

Combine Filters: Use multiple filters together

Rating + Date + Kind filters can quickly narrow results

Use Quotes: For exact phrase matching

"negative prompt: ugly" finds assets with that exact phrase

Leverage Metadata: Search for model names, samplers, or parameters

model:SDXL finds assets generated with SDXL
steps:30 finds assets with 30 sampling steps

Performance Considerations

First search in a scope may take longer as indexing occurs
Subsequent searches are faster due to cached indexes
Very large directories may take time to scan initially
Results are loaded in pages for smooth performance

Search Result Information

Each search result displays:

Thumbnail: Visual preview of the asset
Filename: Original file name
Extension Badge: File type with collision indicator (e.g., PNG+ for duplicates)
Rating: Star rating if assigned
Tags: Preview of assigned tags
Metadata: Brief generation information when available

Using Filters Together

Sequential Filtering

Apply filters in sequence for refined results:

Start with a broad search term
Apply kind filter to narrow by file type
Use rating filter to show only quality results
Apply date filter to focus on timeframe
Sort results by preference

Resetting Filters

Click the "Clear All Filters" button to reset all active filters
Or individually disable filters using their respective controls
Search terms remain unless cleared separately

Collections Integration

Searching Within Collections

Switch to the Collections scope to search within saved collections
Individual collections can be searched independently
Cross-collection searches are also supported

Adding Filtered Results to Collections

Apply your desired search and filters
Select the results you want to save
Right-click and choose "Add to Collection"
Create a new collection or add to existing one
The filtered results are preserved in the collection

Troubleshooting Search Issues

No Results Found

Check spelling of search terms
Try broader terms or synonyms
Verify the correct scope is selected
Ensure the directory has been scanned (trigger with Ctrl/Cmd+S)

Too Many Results

Add more specific search terms
Apply kind filters to narrow by file type
Use rating filters to show only quality results
Apply date filters to focus on recent work

Slow Search Performance

First search in a large directory takes longer
Subsequent searches are faster with cached indexes
Consider excluding very large directories that don't contain relevant assets
Check system resources and close other applications if needed

Missing Metadata in Search

Verify external tools (ExifTool, FFprobe) are installed
Check file permissions for metadata access
Some file formats may not contain embeddable metadata
Re-index the directory if metadata should be present

Advanced Search Techniques

Boolean Operations

While direct boolean operators aren't supported, you can achieve similar results:

AND: Include multiple terms (results must contain all terms)
OR: Use broader terms that match any of your interests
NOT: Manually exclude unwanted results after searching

Pattern Recognition

Search for common patterns in your workflow names
Use recurring artist/model names as search terms
Look for specific parameter combinations in metadata

Workflow-Based Searching

Search for specific sampler names: euler, ddim, dpm++
Find results from particular models: realisticvision, dreamshaper
Locate generations with specific settings: cfg_scale:7, steps:40

Search Statistics

Result Count Display

The interface shows:

Total assets in current scope
Number of assets matching current filters
Current page and total pages
Time taken for the search operation

Performance Metrics

Search duration is displayed for each query
Indexing status shows when background processes are running
Memory usage indicators help monitor performance

Search & Filtering Guide Version: 1.0 Last Updated: January 2026

Source: docs/SEARCH_FILTERING.md

METADATA_VIEWER.md

Metadata extraction and advanced viewer features

Majoor Assets Manager - Metadata & Viewer Guide

Overview

The Majoor Assets Manager provides comprehensive metadata extraction and an advanced viewer with powerful analysis tools. This guide covers all features related to metadata handling and the advanced viewer capabilities.

Metadata Extraction

Supported File Types

The system extracts metadata from various file formats:

Image Files

PNG: Full metadata including generation parameters, workflow, and custom tags
JPG/JPEG: EXIF data, camera information, and embedded generation parameters
WEBP: Metadata from AI generation tools and standard EXIF data
TIFF: Professional imaging metadata and generation parameters

Video Files

MP4: Codec information, duration, frame rate, audio tracks
MOV: QuickTime metadata and generation parameters
AVI: Container information and basic video properties
MKV: Full multimedia metadata including embedded generation data

Workflow Files

JSON: Complete workflow definitions and node configurations
PNG with embedded workflows: Extracted workflow data from image files

Extraction Backends

ExifTool (Primary)

Most comprehensive metadata extraction
Supports hundreds of file formats
Handles custom tags and ratings
Provides detailed technical information

FFprobe (Video/Audio Focus)

Specialized for video and audio files
Detailed codec and stream information
Frame-level metadata for video analysis
Audio track information and properties

Built-in Extraction

Basic metadata when external tools unavailable
Filename and filesystem metadata
Size, creation date, and modification time
Format-specific basic information

Metadata Categories

Generation Information

Prompt: Full positive prompt used for generation
Negative Prompt: Negative prompt applied during generation
Model: Base model used for generation
Sampler: Sampling algorithm employed
Steps: Number of sampling steps
CFG Scale: Classifier-Free Guidance scale value
Seed: Random seed used for generation
Width/Height: Output dimensions
Clip Skip: CLIP model layer skipping value

Technical Parameters

Resolution: Width and height of the generated image
File Size: On-disk size of the file
Format: File format and compression details
Color Profile: Color space and profile information
Compression: Compression algorithm and settings

Workflow Data

Node Configuration: Complete workflow node setup
Connection Map: Input/output connections between nodes
Parameter Values: All node parameter settings
Workflow Minimap: Visual representation of the workflow

Advanced Viewer

Viewer Access

Double-click on any asset card to open the viewer
Right-click and select "Open in Viewer" from context menu
Use keyboard shortcut when asset is selected

Single View Mode

Pan: Click and drag to move around the image
Zoom: Mouse wheel to zoom in/out
Fit to Screen: Automatically scales image to fit window
Actual Size: View image at 1:1 pixel ratio (Alt+1)

Image Enhancement Tools

Exposure Adjustment (EV)

Adjust exposure compensation from -5 to +5 EV
Real-time preview of exposure changes
Useful for evaluating details in shadows/highlights
Preserves color relationships while adjusting brightness

Gamma Correction

Adjust gamma curve from 0.25 to 4.0
Alters midtone brightness without affecting highlights/shadows as much
Useful for fine-tuning contrast in specific tonal ranges
Real-time application with live preview

Channel Isolation

RGB: View all color channels combined
R: View only red channel information
G: View only green channel information
B: View only blue channel information
Alpha: View transparency/alpha channel
Luma: View luminance information only

Analysis Tools

False Color Mode (F)

Visualizes overexposed and underexposed areas
Highlights clipped highlights (typically white/magenta)
Shows blocked shadows (typically blue/black)
Helps evaluate dynamic range and exposure

Zebra Patterns (Z)

Displays 100% IRE (95% for Rec.2020) areas as zebra stripes
Helps identify areas approaching clipping
Adjustable threshold levels
Useful for maintaining highlight detail

Comparison Modes

Side-by-Side Comparison

View two assets next to each other
Independent zoom and pan for each image
Synchronized zoom/pan option available
Perfect for comparing different generation parameters

A/B Toggle Mode

Quickly switch between two assets
Single view area showing one asset at a time
Instant toggle between assets
Useful for subtle difference evaluation

Wipe Comparison (Slider)

Overlay one image over another with adjustable slider
Reveal one asset over another progressively
Clear visualization of differences
Adjustable transition line

Difference Mode

Mathematical difference between two assets
Highlights all variations between images
Positive differences in one color, negative in another
Excellent for identifying subtle changes

Video Player Features

Playback Controls

Play/Pause: Standard play/pause functionality
Loop/Once: Toggle between continuous and single playback
Speed Control: Adjustable playback speed (0.25x to 4x)
Frame Stepping: Precise frame-by-frame navigation (Shift+Arrow keys)

Timeline Features

Seek Bar: Drag to jump to specific points in video
Current Time: Display of current playback position
Duration: Total video duration display
Frame Counter: Current frame number display

In/Out Points

Set In Point: Mark start of desired segment (I key)
Set Out Point: Mark end of desired segment (O key)
Segment Playback: Play only the marked segment
Clear Points: Remove In/Out markers

Visual Overlays

Grid Overlays (G)

Cycle through different grid types:

Off: No grid overlay
Thirds: Rule of thirds grid lines
Center: Center crosshair
Safe Area: TV broadcast safe area guides
Golden Ratio: Golden ratio composition guides

Pixel Probe (I)

Hover to see exact pixel coordinates
Display RGB/RGBA values at cursor position
Hex color code display
Luminance value information
Copy color value to clipboard (C key)

Loupe Magnification (L)

Magnified view of area around cursor
Adjustable magnification level
Shows fine detail at pixel level
Helpful for quality assessment

Scopes

Histogram: RGB histogram showing tonal distribution
Waveform: Luminance waveform for exposure evaluation
Vectorscope: Color information display
Real-time updates as you pan/zoom

Export Capabilities

Save Current Frame

Capture current video frame as PNG
Preserves full resolution and quality
Saves to default output directory
Includes generation metadata if available

Copy to Clipboard

Copy current view to system clipboard
Best-effort format selection
May not work on all platforms
Useful for quick sharing

Download Original

Download the original asset file
Maintains original format and quality
Preserves embedded metadata
Safe file transfer protocol

Viewer Hotkeys

All viewer hotkeys are captured and don't affect ComfyUI or browser:

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
I: Toggle pixel probe
L: Toggle loupe magnification
C: Copy last probed color hex value
Alt+1: Toggle 1:1 zoom

Metadata Panel

Generation Info Section

Detailed information about how the asset was created:

Prompt Information

Positive Prompt: Full text of generation prompt
Negative Prompt: Negative conditioning text
Prompt Weights: Attention weights and emphasis
Prompt Scheduling: Temporal prompt changes if applicable

Model & Sampling

Base Model: Primary model used for generation
VAE: Variational Autoencoder used for decoding
Sampler: Algorithm used for denoising
Scheduler: Noise schedule type
Steps: Number of denoising iterations
CFG Scale: Guidance strength parameter

Image Parameters

Dimensions: Width and height of output
Seed: Random seed value used
ControlNet: Applied ControlNet configurations
LoRA: Active LoRA models and strengths
T2I Adapter: Applied adapter models

Technical Details

File Format: Container and compression details
Color Space: Working color space during generation
Precision: Bit depth and floating-point precision
Hardware Used: GPU/CPU information if available

Workflow Visualization

Node Graph: Visual representation of the workflow
Connection Lines: Input/output relationships
Node Types: Different colors for different node categories
Parameter Values: Key parameters displayed on nodes
Zoom/Pan: Interactive workflow exploration

Metadata Refresh

Manual Refresh: Force reload of metadata
Retry Failed Loads: Attempt to recover from errors
Error Details: Information about extraction failures
Fallback Handling: Graceful degradation when tools unavailable

Rating & Tagging

Rate Asset: Assign 0-5 star rating
Edit Tags: Add/remove custom tags
Quick Tags: Predefined tag suggestions

Collection Management

Add to Collection: Add to existing or new collection
Remove from Collection: Remove from current collection
Show in Collection: Navigate to containing collection

File Operations

Open in Folder: Reveal file in system file browser
Copy Path: Copy file path to clipboard
Rename File: Change filename with validation
Delete File: Remove file with confirmation
Move File: Relocate to different directory

Export Options

Save Current Frame: Capture current view as image
Export Metadata: Save metadata as JSON file
Share Link: Generate shareable link if supported

Performance Optimization

Loading Strategies

Progressive Loading: Thumbnails load first, full data follows
Lazy Loading: Metadata loaded only when viewed
Caching: Frequently accessed data kept in memory
Background Processing: Non-critical tasks run asynchronously

Resource Management

Memory Limits: Prevents excessive memory consumption
Threading: CPU-intensive tasks run on background threads
Timeout Handling: Prevents hanging on problematic files
Error Recovery: Graceful handling of corrupted files

Troubleshooting

Metadata Extraction Issues

Missing Tools: Install ExifTool and FFprobe for full functionality
Permission Errors: Check file permissions for metadata access
Corrupted Files: Some files may have damaged metadata sections
Unsupported Formats: Some proprietary formats may not extract well

Viewer Problems

Slow Performance: Large files may take time to load
Memory Issues: Close other applications if experiencing problems
Codec Problems: Install appropriate codecs for video files
Browser Compatibility: Ensure using supported browsers

Common Solutions

Refresh Index: Use Ctrl/Cmd+S to rescan and refresh metadata
Clear Cache: Clear browser cache if interface seems stuck
Check Logs: Look at ComfyUI console for detailed error messages
Update Tools: Ensure ExifTool and FFprobe are current versions

Best Practices

Metadata Management

Regularly refresh metadata when tools are updated
Use consistent tagging schemes for better organization
Maintain backup copies of important metadata
Verify metadata accuracy periodically

Viewer Usage

Use comparison modes for parameter evaluation
Leverage analysis tools for quality assessment
Take advantage of export features for sharing
Use keyboard shortcuts for efficiency

Performance Tips

Close viewer tabs when not actively using them
Use lower resolution previews when possible
Organize assets into collections to reduce load times
Keep frequently accessed assets in smaller collections

Metadata & Viewer Guide Version: 1.0 Last Updated: January 2026

Source: docs/METADATA_VIEWER.md

RATINGS_TAGS_COLLECTIONS.md

Organization tools (ratings, tags, collections)

Majoor Assets Manager - Ratings, Tags & Collections Guide

Overview

The Majoor Assets Manager provides powerful organizational tools including ratings, tags, and collections to help you manage and organize your generated assets. This guide covers all features related to asset organization and categorization.

Rating System

Understanding Ratings

The rating system allows you to assign star ratings from 0 to 5 stars to your assets:

0 Stars: Poor quality or unusable
1 Star: Below average quality
2 Stars: Average quality
3 Stars: Good quality
4 Stars: Very good quality
5 Stars: Excellent quality

Setting Ratings

Right-click on an asset card
Select "Rate" from the context menu
Choose the desired star rating (0-5)
The rating is saved immediately

Via Keyboard Shortcuts

Select an asset card
Press the corresponding number key (0-5)
The rating is applied instantly

Via Rating Editor

Click on the rating stars directly on the asset card
Select the desired number of stars
The rating is saved automatically

Rating Features

Bulk Rating

Select multiple assets using Ctrl/Cmd+click or Shift+click
Apply the same rating to all selected assets
Right-click and choose "Rate" to apply to all selections

Rating Filters

Filter assets by minimum rating threshold
Show only assets rated 3 stars or higher
Quickly find your best results using rating filters

Rating Persistence

Ratings are stored in the SQLite index database
Ratings persist between ComfyUI sessions
Ratings can be synchronized to file metadata (when external tools available)

Rating Synchronization

When ExifTool is available, ratings can be synced to file metadata:

Ratings stored in file metadata for portability
Maintains ratings when files are moved/copied
Compatible with other applications that read ratings
Enabled/disabled via settings

Tagging System

Understanding Tags

Tags are customizable keywords that help categorize and organize your assets:

Free-form text labels (e.g., "character", "landscape", "fantasy")
Multiple tags per asset
Hierarchical tagging support (e.g., "style:anime", "color:warm")
Searchable across all assets

Adding Tags

Right-click on an asset card
Select "Edit Tags" from the context menu
Type tags separated by commas or spaces
Press Enter to save

Via Tags Editor

Click on an asset to select it
Open the details sidebar (press 'D')
Find the tags section
Add or remove tags as needed

Bulk Tagging

Select multiple assets
Right-click and choose "Edit Tags"
Add tags that apply to all selected assets
Tags are applied to all selected items

Managing Tags

Tag Suggestions

System suggests previously used tags
Intelligent autocomplete for faster tagging
Recently used tags appear at the top of suggestions

Tag Validation

Prevents duplicate tags on the same asset
Validates tag format and content
Sanitizes special characters when needed

Tag Search

Search for assets by specific tags
Combine tag searches with other filters
Use partial tag names for broader results

Tag Features

Tag Hierarchy

Use colons to create hierarchical tags: "subject:person:face"
Organize tags in logical groups
Facilitate more granular categorization

Tag Colors

Visual indication of different tag types
Customizable tag appearance
Consistent color coding across the interface

Tag Statistics

View tag frequency across your collection
Identify most commonly used tags
Analyze your tagging patterns

Tag Synchronization

When ExifTool is available, tags can be synced to file metadata:

Tags stored in file metadata for portability
Maintains tags when files are moved/copied
Compatible with other applications that read tags
Enabled/disabled via settings

Collections System

Understanding Collections

Collections are user-created groups of assets that can span multiple directories:

Named groups of related assets
Can include assets from different scopes (Outputs, Inputs, Custom)
Persistent storage in JSON format
Shareable between users

Creating Collections

From Selected Assets

Select one or more assets
Right-click and choose "Add to Collection"
Select an existing collection or create a new one
Name your new collection appropriately
Assets are added to the collection

From Search Results

Apply search and filters to find desired assets
Select all results (Ctrl+A or Cmd+A)
Right-click and choose "Add to Collection"
Create a new collection for the filtered results

Empty Collections

Right-click in the Collections tab
Choose "Create New Collection"
Name your collection
Add assets later as needed

Managing Collections

Collection Operations

Rename: Change collection name via context menu
Delete: Remove entire collection (doesn't delete assets)
Clear: Remove all items from collection (doesn't delete assets)
Export: Save collection as JSON file for sharing
Import: Load collection from JSON file

Item Management

Add Items: Add assets to existing collections
Remove Items: Remove specific assets from collections
Bulk Operations: Add/remove multiple items at once
Duplicate Prevention: Automatic detection of duplicates

Collection Features

Smart Collections

Dynamic collections based on criteria
Automatically updated as new assets match criteria
Based on tags, ratings, date ranges, or other attributes

Nested Collections

Collections within collections (hierarchical)
Organize large collections into subcategories
Flexible organization structures

Export collections as JSON files
Import collections from other users
Share curated sets of assets
Collaborative collection building

Collection Limits

Maximum 50,000 items per collection (configurable)
Performance optimization for large collections
Warning when approaching limits
Suggestions for splitting large collections

Collection Views

Grid View

Thumbnail display of collection contents
Visual browsing of assets
Consistent with main interface design

List View

Detailed information display
Sortable columns (name, date, size, rating)
More information per asset

Compact View

Dense layout for many items
Efficient space utilization
Quick scanning of large collections

Integration with Other Features

Search Integration

Search within specific collections
Cross-collection search capability
Filter search results by collection membership
Search for assets across all collections

Filtering Integration

Filter by collection membership
Combine collection filters with other filters
Show only assets from specific collections
Exclude assets from certain collections

Viewer Integration

View collection context in viewer
Navigate between collection items
Show collection information in metadata panel
Maintain collection context during comparisons

Rating and Tag Integration

Apply ratings/tags to entire collections
Filter collections by ratings/tags
Bulk operations on collection contents
Maintain rating/tag statistics per collection

Best Practices

Rating Best Practices

Establish consistent rating criteria
Use ratings consistently across similar assets
Regularly review and adjust ratings as needed
Use rating filters to quickly find quality assets

Tagging Best Practices

Develop a consistent tagging vocabulary
Use specific but not overly granular tags
Maintain tag hierarchy for organization
Regularly review and consolidate similar tags
Use tags that will be meaningful later

Collection Best Practices

Create collections based on clear criteria
Use descriptive names for collections
Regularly clean up unused collections
Split large collections into more manageable groups
Share valuable collections with others

Performance Considerations

Large Collections

Collections with many items may take longer to load
Interface remains responsive during loading
Pagination helps manage large collections
Consider splitting very large collections

Tag Performance

Many tags per asset don't significantly impact performance
Tag search remains fast regardless of quantity
Regular cleanup of unused tags improves performance

Rating Performance

Rating operations are nearly instantaneous
Rating filters apply quickly to large datasets
Bulk rating operations are optimized

Troubleshooting

Rating Issues

Ratings not saving: Check database permissions
Ratings not displaying: Refresh the view or rescan
Sync issues: Verify ExifTool installation for file sync

Tagging Issues

Tags not appearing: Check for typos or special characters
Tag search not working: Ensure proper tag format
Sync issues: Verify ExifTool installation for file sync

Collection Issues

Collection not saving: Check write permissions to index directory
Items not adding: Verify collection limits haven't been reached
Collection not loading: Check JSON file integrity

Common Solutions

Refresh Index: Use Ctrl/Cmd+S to rescan and refresh
Clear Cache: Clear browser cache if interface seems stuck
Check Logs: Look at ComfyUI console for detailed error messages
Database Maintenance: Run optimization tools periodically

Advanced Features

Tag Expressions

Complex tag queries using boolean logic
Combine tags with AND/OR operations
Parentheses for complex expressions
Negation operators for exclusions

Rating Statistics

View rating distributions across collections
Track rating trends over time
Identify most/least rated assets
Generate reports on rating patterns

Collection Analytics

View collection usage statistics
Track most accessed collections
Identify underutilized collections
Analyze collection overlap and relationships

Automation Possibilities

Script-based tag assignment
Automated rating based on criteria
Scheduled collection maintenance
Integration with external tools

Security & Privacy

Local Storage

Ratings and tags stored locally
No external data transmission
Full control over your organizational data
Backup your index database regularly

File Metadata

Optional synchronization to file metadata
Controlled via settings
Respects file permissions
Preserves existing file metadata

Ratings, Tags & Collections Guide Version: 1.0 Last Updated: January 2026

Source: docs/RATINGS_TAGS_COLLECTIONS.md

DRAG_DROP.md

Drag and drop functionality

Majoor Assets Manager - Drag & Drop Guide

Overview

The Majoor Assets Manager provides seamless drag and drop functionality that integrates with both ComfyUI and your operating system. This guide covers all aspects of drag and drop operations within the extension.

Drag to ComfyUI Canvas

Basic Drag Operation

Select one or more assets in the Assets Manager
Click and hold on an asset card
Drag the asset onto the ComfyUI canvas
Release the mouse button to drop the asset

Single Asset Drag

Drag any single asset to the canvas
The asset path is automatically injected into compatible nodes
Compatible nodes include LoadImage, LoadLatent, and similar input nodes
The asset is staged for immediate use in your workflow

Multiple Asset Drag

Select multiple assets using Ctrl/Cmd+click or Shift+click
Drag any selected asset to the canvas
Multiple file paths are handled appropriately
Some nodes support multiple inputs, others will use the first path

Node Compatibility

The system intelligently identifies compatible nodes:

Image Input Nodes

LoadImage: Accepts image file paths
LoadImageMask: For mask images
PreviewImage: For direct preview
LoadLatent: For latent files

Video Input Nodes

LoadVideo: For video file paths
VideoLoad: For various video formats

Workflow Input Nodes

LoadWorkflow: For workflow files
ImportWorkflow: For external workflow files

Staging Mechanism

Assets are staged temporarily when dragged to canvas
Paths are injected into appropriate input fields
No permanent changes to workflow until execution
Allows for experimentation without committing to changes

Drag to Operating System

Single File Drag

Select an asset in the Assets Manager
Click and drag the asset outside the browser window
Drop onto your file explorer, desktop, or another application
The original file is transferred to the destination

Multiple File Drag

Select multiple assets using Ctrl/Cmd+click or Shift+click
Drag any selected asset outside the browser window
A ZIP file is automatically created containing all selected assets
Drop the ZIP file onto your destination

ZIP Creation Process

ZIP files are created on-demand when dragging multiple items
Files are streamed directly from disk (no temporary copies)
ZIPs are flat (no directory structure maintained)
ZIP files are automatically cleaned up after transfer

Protocol Support

The system supports multiple drag protocols:

DownloadURL Protocol

Used for single file transfers
Direct file download to destination
Maintains original filename and extension

text/uri-list Protocol

Used for multiple file transfers
Properly formatted URI list for operating system
Compatible with most file managers and applications

Drag Operations

Starting a Drag

Click and hold on any asset card for a moment
A visual indicator appears showing the drag is active
The cursor changes to indicate drag operation
Selection remains active during drag

Drag Indicators

Visual Outline: Selected assets show a highlighted border
Cursor Change: Cursor changes to indicate drag capability
Preview: Small preview of dragged asset(s) follows cursor
Count Display: For multiple selections, shows number of items

Drag Targets

The system recognizes different drag targets:

Valid Targets

ComfyUI canvas area
Compatible input nodes
Browser address bar (downloads)
File explorer windows
Desktop
Email attachments
Other applications accepting files

Invalid Targets

Text input fields (unless specifically designed for file drops)
Non-compatible areas of the interface
Applications that don't accept the file type

File Transfer Mechanisms

Direct File Transfer

Single files are transferred directly
Maintains original file properties
Preserves embedded metadata
No quality loss during transfer

Batch ZIP Transfer

Multiple files are packaged into a ZIP archive
ZIP created dynamically during drag operation
No temporary files written to disk
Automatic cleanup after transfer completion

Streaming Transfer

Files are streamed directly from disk
No intermediate copies created
Memory efficient for large files
Maintains file integrity during transfer

Filename Collision Indicator

Understanding the Indicator

When multiple assets share the same filename, the extension badge shows EXT+
For example: image.png becomes PNG+ when duplicates exist
Helps identify potential conflicts during drag operations

Handling Collisions

Collisions don't prevent drag operations
ZIP files handle duplicate names automatically
Individual file drops may require manual renaming
Consider renaming files to avoid confusion

Drag Performance

Optimizations

Lightweight preview during drag
Asynchronous file operations
Memory-efficient streaming
Responsive interface during drag operations

Performance Considerations

Large files may take time to initiate transfer
Multiple large files in ZIP may take longer to create
Network drives may affect performance
System resources impact drag responsiveness

Advanced Drag Features

Drag Preview

Live preview of dragged assets
Shows thumbnail of the primary dragged item
Displays count for multiple selections
Updates in real-time during drag

Drag Validation

Validates target compatibility before allowing drop
Provides visual feedback for valid/invalid targets
Prevents invalid operations
Shows appropriate cursors for different states

Drag Cancellation

Cancel drag by releasing over invalid target
Escape key cancels active drag operation
Clicking elsewhere cancels drag
Drag automatically cancels if window loses focus

Integration with Other Features

Selection Integration

Drag operations work with current selection
Multiple selections enable batch operations
Selection filters apply to drag operations
Search results can be dragged directly

Collection Integration

Assets from collections can be dragged normally
Entire collections can be exported via drag
Collection organization preserved in transfers
Cross-collection drags work seamlessly

Rating/Tag Integration

Rated and tagged assets maintain metadata during drag
Tags and ratings preserved in file transfers (when supported)
Filtered views can be dragged directly
Quality indicators visible during drag

Troubleshooting

Common Drag Issues

Drag Not Initiating

Ensure you're clicking and holding long enough
Check that the asset is properly selected
Verify no JavaScript errors in console
Try refreshing the Assets Manager

Drag Target Not Recognized

Ensure target application accepts file drops
Check if target area is actually droppable
Verify file type compatibility with target
Try dragging to a different application

ZIP Creation Failure

Check available disk space
Verify write permissions to temporary directory
Ensure no antivirus interference
Try dragging fewer files at once

File Transfer Problems

Large files may timeout during transfer
Network drives may cause delays
Antivirus software may interfere
Check file permissions at destination

Browser-Specific Issues

Chrome/Chromium

May require specific security settings for file downloads
Extensions might interfere with drag operations
Incognito mode may behave differently

Firefox

Security settings may restrict file operations
Enhanced Tracking Protection might interfere
Check privacy settings for file handling

Safari

May require additional permissions for file access
Security restrictions could limit functionality
Check website permissions for file handling

Operating System Issues

Windows

UAC (User Account Control) may interfere
Antivirus software may block operations
File permissions may restrict transfers

macOS

Gatekeeper may restrict file operations
Privacy settings may limit access
Sandboxing could affect functionality

Linux

File permissions are strictly enforced
Desktop environment may affect drag behavior
Security modules might restrict operations

Security Considerations

File Access Security

Drag operations respect file system permissions
No files can be accessed that the user can't read
Temporary files are created with restricted permissions
ZIP files are cleaned up automatically

Cross-Origin Security

Drag operations confined to same origin
No cross-site data leakage possible
File system access limited to allowed directories
Path validation prevents directory traversal

Malicious File Protection

No automatic execution of dragged files
Files transferred in their original form
No modification during drag operations
Integrity preserved throughout transfer

Performance Optimization

Large File Handling

Stream large files instead of loading entirely
Progress indicators for long operations
Asynchronous operations to maintain interface responsiveness
Memory management for multiple large files

Multiple File Optimization

Efficient ZIP creation algorithms
Parallel processing where possible
Memory buffering for optimal performance
Cleanup operations scheduled appropriately

Interface Responsiveness

Drag operations don't block UI thread
Smooth animations during drag
Immediate feedback for user actions
Graceful degradation for slower systems

Best Practices

Efficient Drag Operations

Use multiple selection for batch operations
Organize assets in collections for easier access
Use search and filters to find assets quickly
Verify target compatibility before initiating drag

File Organization

Maintain consistent naming conventions
Use collections to group related assets
Apply tags for easy retrieval
Regular cleanup of unused assets

Workflow Integration

Use drag operations to accelerate workflow creation
Stage frequently used assets in collections
Leverage drag to canvas for rapid prototyping
Combine with other Assets Manager features

Performance Tips

Close unnecessary browser tabs during large operations
Ensure sufficient system resources
Use wired connections for network drives
Regular maintenance of index database

Advanced Usage

Scripted Operations

Combine drag operations with automation scripts
Use collections for automated workflows
Integrate with external tools via file operations
Batch processing using drag interfaces

Power User Techniques

Master keyboard shortcuts with drag operations
Use multiple monitors for efficient transfers
Leverage search and filters for precise selection
Combine collections with drag for complex operations

Drag & Drop Guide Version: 1.0 Last Updated: January 2026

Source: docs/DRAG_DROP.md

HOTKEYS_SHORTCUTS.md

Keyboard shortcuts and hotkeys

Majoor Assets Manager - Hotkeys & Keyboard Shortcuts Guide

Overview

The Majoor Assets Manager includes numerous keyboard shortcuts to enhance productivity and streamline your workflow. This guide covers all available hotkeys and keyboard shortcuts organized by functionality.

Global Hotkeys

These hotkeys work when interacting with the asset grid:

Selection Controls

Ctrl+A / Cmd+A: Select all visible assets
Ctrl+Click / Cmd+Click: Add/remove individual asset from selection
Shift+Click: Select range from last selected to clicked asset
Escape: Clear current selection

Rating Controls

0: Set rating to 0 stars
1: Set rating to 1 star
2: Set rating to 2 stars
3: Set rating to 3 stars
4: Set rating to 4 stars
5: Set rating to 5 stars

Up Arrow: Move selection up one row
Down Arrow: Move selection down one row
Left Arrow: Move selection left one column
Right Arrow: Move selection right one column
Page Up: Move selection up one page
Page Down: Move selection down one page
Home: Move to first asset in grid
End: Move to last asset in grid

Interface Controls

Ctrl+S / Cmd+S: Trigger index scan for current scope
D: Toggle details sidebar for current selection
Enter: Open viewer for selected asset
Delete / Backspace: Delete selected asset(s) (with confirmation)
F2: Rename selected asset
Ctrl+F / Cmd+F: Focus search input field

Viewer Hotkeys

Viewer Controls

These hotkeys only work when the viewer is open and focused:

Viewer Management

Escape: Close viewer and return to grid
Tab: Cycle focus between viewer controls
Space: Toggle play/pause (for video content)

Rating Controls (in Viewer)

0: Set rating to 0 stars
1: Set rating to 1 star
2: Set rating to 2 stars
3: Set rating to 3 stars
4: Set rating to 4 stars
5: Set rating to 5 stars

Video Controls

Shift+Left Arrow: Step backward one frame
Shift+Right Arrow: Step forward one frame
Shift+Up Arrow: Increase playback speed
Shift+Down Arrow: Decrease playback speed
I: Set In point for segment playback
O: Set Out point for segment playback
P: Toggle loop/once playback mode

Image Enhancement

F: Toggle false color analysis mode
Z: Toggle zebra pattern overlay
G: Cycle through grid overlays (off → thirds → center → safe → golden)
I: Toggle pixel probe overlay
L: Toggle loupe magnification
C: Copy last probed color hex value to clipboard
H: Toggle histogram display
W: Toggle waveform display

Zoom Controls

+ / =: Zoom in
-: Zoom out
0: Fit image to screen
1 / Alt+1: Toggle 1:1 pixel view
R: Reset zoom and pan position
Mouse Wheel: Zoom in/out while hovering over image

Pan Controls

Arrow Keys: Pan image in corresponding direction (small increments)
Shift+Arrow Keys: Pan image in corresponding direction (larger increments)
Click and Drag: Pan image while holding mouse button
Middle Click and Drag: Pan image with middle mouse button

Comparison Mode Controls

Left Arrow: Switch to previous asset in comparison
Right Arrow: Switch to next asset in comparison
T: Toggle between comparison modes
M: Toggle wipe/difference mode

Search and Filter Hotkeys

Search Controls

Ctrl+K / Cmd+K: Focus search input field
Ctrl+H / Cmd+H: Clear search field
Enter: Submit search (when in search field)
Up Arrow: Navigate search history (when in search field)
Down Arrow: Navigate search history (when in search field)

Filter Controls

Ctrl+R / Cmd+R: Reset all filters
Ctrl+D / Cmd+D: Toggle date filter panel
Ctrl+T / Cmd+T: Toggle tag filter panel
Ctrl+N / Cmd+N: Toggle kind (file type) filter panel

Keyboard-Accessible Actions

When an asset is selected, these hotkeys provide quick access to context menu functions:

Collection Operations

Ctrl+E / Cmd+E: Add to collection
Ctrl+Shift+E: Remove from collection
Ctrl+U / Cmd+U: Open in folder
Ctrl+P / Cmd+P: Copy file path to clipboard

Asset Management

Ctrl+R / Cmd+R: Rename selected asset
Ctrl+D / Cmd+D: Delete selected asset(s)
Ctrl+T / Cmd+T: Edit tags for selected asset(s)
Ctrl+I / Cmd+I: Show asset information

Browser-Specific Behavior

Hotkey Restrictions

Hotkeys are disabled when typing in text input fields
Hotkeys don't activate when focus is on form elements
Some browser extensions may intercept hotkeys
Fullscreen mode may affect hotkey behavior

Platform Differences

Hotkeys are optimized for each platform:

Windows/Linux

Uses Ctrl modifier for most shortcuts
Ctrl+S for scan triggering
Ctrl+F for search focus

macOS

Uses Cmd modifier instead of Ctrl
Cmd+S for scan triggering
Cmd+F for search focus
Native feel with standard macOS shortcuts

Advanced Hotkey Techniques

Combining Hotkeys

Use selection hotkeys followed by rating hotkeys for bulk operations
Combine navigation with rating for quick review sessions
Use filter hotkeys with selection hotkeys for targeted operations

Power User Sequences

Ctrl+A, 5: Select all and rate everything 5 stars
Ctrl+F, [search term], Enter, Ctrl+A, Ctrl+E: Search, select all, add to collection
D, [adjust filters], Enter: Toggle details, adjust filters, apply

Workflow Acceleration

Learn rating hotkeys for quick asset evaluation
Master navigation hotkeys for efficient browsing
Combine search and selection for targeted operations

Customization Options

Current Limitations

Hotkeys are currently hardcoded and not user-configurable
All users receive the same hotkey mappings
No profile-specific hotkey settings

Potential Future Enhancements

User-configurable hotkey mappings
Profile-specific hotkey sets
Import/export hotkey configurations
Conflict detection with browser/system hotkeys

Troubleshooting Hotkeys

Common Issues

Hotkeys Not Working

Check if focus is on a text input field
Verify no browser extensions are intercepting keys
Ensure Assets Manager interface is active
Try refreshing the browser page

Conflicting Hotkeys

Some browser extensions may conflict with hotkeys
Other web applications in tabs may intercept keys
System-level hotkeys may interfere
Try using a different browser for testing

Platform-Specific Issues

Mac users should use Cmd instead of Ctrl
Some hotkeys may not work in certain browsers
Browser security settings may restrict hotkey functionality
Accessibility features may affect hotkey behavior

Browser Compatibility

Hotkeys work across major browsers but may have slight variations:

Chrome/Chromium

Full hotkey support
May conflict with browser extensions
Works in both regular and incognito mode

Firefox

Full hotkey support
Enhanced Tracking Protection usually doesn't affect hotkeys
May require accessibility settings adjustments

Safari

Full hotkey support
May require website permissions for full functionality
Works with standard macOS shortcuts

Edge

Full hotkey support
Similar to Chrome behavior
May inherit Windows system hotkeys

Productivity Tips

Learning Hotkeys Effectively

Start with basic navigation and rating hotkeys
Practice one category of hotkeys at a time
Use hotkeys consistently to build muscle memory
Focus on hotkeys that match your most frequent actions

Efficiency Improvements

Use selection hotkeys to operate on multiple assets
Combine search with hotkeys for targeted operations
Learn viewer hotkeys for detailed asset examination
Master the rating system for quick quality assessment

Workflow Integration

Integrate hotkeys into your regular asset management routine
Use hotkeys to speed up repetitive tasks
Combine with other Assets Manager features for maximum efficiency
Share hotkey knowledge with team members for consistency

Reference Summary

Essential Hotkeys

Action	Windows/Linux	macOS
Scan current scope	Ctrl+S	Cmd+S
Toggle details sidebar	D	D
Rate 5 stars	5	5
Select all	Ctrl+A	Cmd+A
Focus search	Ctrl+K	Cmd+K
Close viewer	Esc	Esc
Toggle false color	F	F
Toggle zebra	Z	Z
Toggle grid	G	G
Toggle pixel probe	I	I
Toggle loupe	L	L
Copy color	C	C
Actual size	Alt+1	Alt+1

Viewer Hotkeys

Action	Hotkey
Close viewer	Esc
Play/pause video	Space
Step frame back	Shift+Left
Step frame forward	Shift+Right
Set In point	I
Set Out point	O
Toggle loop	P
Zoom in	+ or =
Zoom out	-
Fit to screen	0
Actual size	1 or Alt+1
Reset view	R
Toggle false color	F
Toggle zebra	Z
Cycle grids	G
Toggle pixel probe	I
Toggle loupe	L
Copy color	C
Toggle histogram	H
Toggle waveform	W

Hotkeys & Keyboard Shortcuts Guide Version: 1.0 Last Updated: January 2026

Source: docs/HOTKEYS_SHORTCUTS.md

SETTINGS_CONFIGURATION.md

Settings and configuration options

Majoor Assets Manager - Settings & Configuration Guide

Overview

The Majoor Assets Manager offers extensive configuration options to customize the interface, performance, and functionality to match your workflow. This guide covers all available settings and configuration options.

Browser-Based Settings

Storage Location

Browser-based settings are stored in localStorage under the mjrSettings key:

Settings persist between browser sessions
Settings are specific to each browser/computer
Settings don't sync across different browsers or devices
Settings are tied to the specific domain where ComfyUI is hosted

Accessing Settings

Settings are primarily adjusted through the user interface:

Open the Assets Manager in ComfyUI
Look for settings icons or configuration panels
Adjust settings as needed
Settings are saved automatically

Display Settings

Page Size

Purpose: Controls how many assets are loaded per request
Default: Usually 50-100 assets per page
Range: Typically 10-500 assets per page
Impact: Larger pages mean fewer requests but more memory usage
Recommendation: Adjust based on your system resources and usage patterns

Options: Left or Right
Default: Usually Right
Purpose: Controls where the details sidebar appears
Impact: Affects layout and workflow depending on screen orientation
Recommendation: Choose based on your screen setup and preferences

Hide PNG Siblings

Purpose: Hide PNG files when video previews exist
Default: Usually Off/Disabled
Function: Reduces clutter from duplicate content in different formats
Impact: Cleaner interface when working with video generations that include PNG previews
Recommendation: Enable if you frequently work with video generations

Performance Settings

Auto-Scan Options

Auto-scan on Open: Automatically scan when opening the Assets Manager
Auto-scan on Startup: Automatically scan when ComfyUI starts
Default: Usually Disabled to save resources
Impact: Ensures fresh index but uses system resources
Recommendation: Enable for frequently updated directories

Status Poll Interval

Purpose: How often to check background tasks and status
Default: Usually 1-5 seconds
Range: 0.5-30 seconds
Impact: More frequent polling provides more responsive status updates but uses more resources
Recommendation: 1-2 seconds for good balance of responsiveness and resource usage

Tags Cache TTL

Purpose: Time-to-live for tag caching in milliseconds
Default: Usually 30,000ms (30 seconds)
Range: 1,000ms to 300,000ms (1 second to 5 minutes)
Impact: Longer TTL means fewer requests but potentially stale data
Recommendation: 30,000ms (30 seconds) for good balance

Metadata & Viewer Settings

Media Probe Backend

Auto: Automatically choose the best available backend
ExifTool: Use ExifTool exclusively for metadata extraction
FFprobe: Use FFprobe exclusively (especially for video)
Both: Use both tools when available
Default: Auto
Impact: Affects metadata extraction speed and completeness
Recommendation: Keep as Auto unless troubleshooting specific issues

Workflow Minimap Display

Show Node Labels: Display text labels on workflow minimap
Show Connection Lines: Display connections between nodes
Show Parameter Values: Display parameter values on nodes
Minimap Size: Adjust the size of the workflow minimap
Default: Varies by preference
Impact: Affects readability of workflow previews
Recommendation: Enable based on your need for workflow detail

Observability

Request Logging: Enable detailed logging of API requests
Performance Metrics: Track timing and performance data
Debug Information: Enable additional debugging output
Default: Usually Disabled
Impact: Provides detailed information for troubleshooting but increases log volume
Recommendation: Enable only when troubleshooting issues

File System Settings

File Watching

Enable File Watcher: Automatically reindex when files change
Watcher Interval: How often to check for file changes
Join Timeout: Time to wait before processing multiple changes together
Watched Paths: Which directories to monitor for changes
Default: Usually Disabled to save resources
Impact: Keeps index current but uses system resources
Recommendation: Enable for actively used output directories

Custom Roots

Adding Custom Directories: Add additional directories to browse
Path Validation: Ensures paths are valid and accessible
Symlink Support: Allow symbolic links in custom roots (if enabled)
Access Permissions: Respects file system permissions
Default: None initially
Impact: Expands browsing capabilities beyond standard directories
Recommendation: Add directories you frequently access

Database Settings

Connection Management

Max Connections: Maximum simultaneous database connections
Connection Timeout: Time to wait for database operations
Query Timeout: Maximum time for individual queries
Default: Usually 8 connections, 30-second timeouts
Impact: Affects performance with concurrent operations
Recommendation: Adjust based on system resources and usage patterns

Optimization

Auto-Optimize: Automatically optimize database periodically
Manual Optimization: Run optimization tools manually
Maintenance Schedule: When optimization occurs
Default: Usually Manual
Impact: Improves performance but requires temporary locking
Recommendation: Schedule during low-usage periods

Advanced Configuration

Environment Variables (Backend)

Directory Configuration

MAJOOR_OUTPUT_DIRECTORY: Override default output directory

Default: ComfyUI's output directory
Format: Full path to directory
Impact: Changes where the indexer looks for assets
Example: MAJOOR_OUTPUT_DIRECTORY=/path/to/my/output

External Tool Paths

MAJOOR_EXIFTOOL_PATH / MAJOOR_EXIFTOOL_BIN: Path to ExifTool executable

Default: exiftool (assumes in PATH)
Format: Full path to exiftool executable
Impact: Used for metadata extraction and file tagging
Example: MAJOOR_EXIFTOOL_PATH=/usr/local/bin/exiftool

MAJOOR_FFPROBE_PATH / MAJOOR_FFPROBE_BIN: Path to FFprobe executable

Default: ffprobe (assumes in PATH)
Format: Full path to ffprobe executable
Impact: Used for video/audio metadata extraction
Example: MAJOOR_FFPROBE_PATH=/usr/local/bin/ffprobe

Media Processing

MAJOOR_MEDIA_PROBE_BACKEND: Media extraction backend selection

Options: auto, exiftool, ffprobe, both
Default: auto
Impact: Determines which tools are used for metadata extraction
Example: MAJOOR_MEDIA_PROBE_BACKEND=both

File Watching

MAJOOR_ENABLE_FILE_WATCHER: Enable automatic reindexing

Options: true, false, 1, 0
Default: false
Impact: Automatically updates index when files change
Example: MAJOOR_ENABLE_FILE_WATCHER=true

MAJOOR_WATCHER_INTERVAL: File watching interval in seconds

Default: 15.0
Range: 1.0 to 300.0
Impact: How frequently the system checks for changes
Example: MAJOOR_WATCHER_INTERVAL=10.0

MAJOOR_WATCHER_JOIN_TIMEOUT: Coalescing timeout for file events

Default: 5.0 seconds
Range: 0.1 to 60.0
Impact: Time to wait before processing grouped file changes
Example: MAJOOR_WATCHER_JOIN_TIMEOUT=3.0

MAJOOR_WATCHER_PATHS: Directories to watch (colon-separated on Unix, semicolon on Windows)

Default: Output directory
Format: Path separators depend on OS
Impact: Which directories are monitored for changes
Example: MAJOOR_WATCHER_PATHS=/path/to/output:/path/to/inputs

Database Tuning

MAJOOR_DB_TIMEOUT: Database operation timeout in seconds

Default: 30.0
Range: 1.0 to 300.0
Impact: Maximum time to wait for database operations
Example: MAJOOR_DB_TIMEOUT=60.0

MAJOOR_DB_MAX_CONNECTIONS: Maximum database connections

Default: 8
Range: 1 to 50
Impact: Concurrency level for database operations
Example: MAJOOR_DB_MAX_CONNECTIONS=12

MAJOOR_DB_QUERY_TIMEOUT: Maximum query execution time

Default: 30.0 seconds
Range: 1.0 to 300.0
Impact: Prevents long-running queries from blocking
Example: MAJOOR_DB_QUERY_TIMEOUT=45.0

Performance Tuning

MAJOOR_TO_THREAD_TIMEOUT: Timeout for background thread operations

Default: 30 seconds
Range: 10 to 600 seconds
Impact: Maximum time for background operations
Example: MAJOOR_TO_THREAD_TIMEOUT=60

MAJOOR_MAX_METADATA_JSON_BYTES: Maximum metadata JSON size

Default: 2097152 (2MB)
Range: 1024 to 104857600 (100MB)
Impact: Limits memory usage for metadata storage
Example: MAJOOR_MAX_METADATA_JSON_BYTES=4194304

Collection Management

MJR_COLLECTION_MAX_ITEMS: Maximum items per collection

Default: 50000
Range: 1000 to 1000000
Impact: Prevents extremely large collections from impacting performance
Example: MJR_COLLECTION_MAX_ITEMS=100000

Security & Networking

MJR_ALLOW_SYMLINKS: Allow symbolic links in custom roots

Options: on, off, true, false
Default: off
Impact: Enables browsing of linked directories
Example: MJR_ALLOW_SYMLINKS=on

MAJOOR_TRUSTED_PROXIES: IPs/CIDRs allowed for forwarded headers

Default: 127.0.0.1,::1
Format: Comma-separated IP addresses or CIDR blocks
Impact: Security setting for proxy environments
Example: MAJOOR_TRUSTED_PROXIES=127.0.0.1,192.168.1.0/24

Dependency Management

MJR_AM_NO_AUTO_PIP: Disable automatic dependency installation

Options: 1, true, yes, on to disable
Default: Automatic installation enabled
Impact: Prevents automatic pip installs at startup
Example: MJR_AM_NO_AUTO_PIP=1

Setting Up Environment Variables

Windows

Create a batch file to set environment variables:

@echo off\nset MAJOOR_MEDIA_PROBE_BACKEND=auto\nset MAJOOR_ENABLE_FILE_WATCHER=true\nset MAJOOR_WATCHER_INTERVAL=15.0\nset MAJOOR_DB_TIMEOUT=60.0\n\nREM Start ComfyUI with the environment variables\ncd /d "C:\path\to\ComfyUI"\npython main.py --auto-launch\npause

Unix/Linux/macOS

Create a shell script to set environment variables:

#!/bin/bash\nexport MAJOOR_MEDIA_PROBE_BACKEND=auto\nexport MAJOOR_ENABLE_FILE_WATCHER=true\nexport MAJOOR_WATCHER_INTERVAL=15.0\nexport MAJOOR_DB_TIMEOUT=60.0\n\n# Start ComfyUI with the environment variables\ncd /path/to/ComfyUI\npython main.py --auto-launch

Or add to your shell profile (.bashrc, .zshrc, etc.):

export MAJOOR_MEDIA_PROBE_BACKEND=auto\nexport MAJOOR_ENABLE_FILE_WATCHER=true\nexport MAJOOR_WATCHER_INTERVAL=15.0\nexport MAJOOR_DB_TIMEOUT=60.0

Configuration Best Practices

Performance Optimization

Adjust page size based on your system's RAM
Enable file watching only for actively used directories
Set appropriate timeouts based on your storage speed
Monitor database performance and adjust connections as needed

Security Considerations

Keep default security settings unless you have specific requirements
Only enable symlink support if you trust the linked directories
Configure trusted proxies appropriately in networked environments
Regularly update external tools (ExifTool, FFprobe) for security

Resource Management

Monitor memory usage with large collections
Adjust cache settings based on available RAM
Set appropriate timeouts for your storage system
Consider SSD storage for better database performance

Backup and Recovery

Regularly backup the index database (assets.sqlite)
Backup custom root configurations
Maintain copies of important collections
Document your configuration settings for recovery

Troubleshooting Configuration Issues

Common Problems

Settings Not Saving

Clear browser cache and cookies
Check browser localStorage quota
Verify no browser extensions are interfering
Try a different browser

Performance Issues

Reduce page size if experiencing slowdowns
Disable auto-scan if not needed
Adjust database connection settings
Check system resources (RAM, disk space)

External Tool Issues

Verify tools are in PATH or set explicit paths
Check tool permissions and access rights
Ensure tools are properly installed
Test tools independently before using with Assets Manager

File Watching Problems

Check directory permissions
Verify the watched directories exist and are accessible
Monitor system resources (file watching can be resource-intensive)
Adjust intervals if causing performance issues

Diagnostic Steps

Check ComfyUI console for error messages
Verify all required dependencies are installed
Test external tools independently
Review environment variable settings
Try default settings to isolate configuration issues

Migration and Updates

Settings Preservation

Browser settings are preserved across updates
Environment variables need to be reapplied after system restarts
Custom root configurations are stored in the index directory
Collections are preserved as JSON files

Configuration Updates

New settings are added with sensible defaults
Old settings remain unchanged during updates
Review new settings after updates to optimize functionality
Check release notes for configuration changes

Settings & Configuration Guide Version: 1.0 Last Updated: January 2026

Source: docs/SETTINGS_CONFIGURATION.md

SECURITY_ENV_VARS.md

Security model and environment variables

Majoor Assets Manager - Security Model & Environment Variables Guide

Overview

The Majoor Assets Manager implements a comprehensive security model to protect your system while providing powerful asset management capabilities. This guide covers the security architecture, threat models, and security-related environment variables.

Security Architecture

Defense Layers

The Assets Manager employs multiple layers of security:

Application Layer Security

Input validation and sanitization
Path containment and validation
File type verification
Access control mechanisms

Network Layer Security

CSRF protection on state-changing endpoints
Origin validation for sensitive requests
Rate limiting on expensive operations
Secure communication protocols

File System Security

Root containment validation
Path traversal prevention
Permission checking
Symlink handling controls

Trust Model

User Input: All user input is validated and sanitized
File System: Only allowed directories are accessible
External Tools: Tools run with limited privileges
Network: Requests validated against origin policies

Authentication & Authorization

Session Management

No persistent authentication required
All operations happen within ComfyUI session
No external accounts or credentials needed
Access limited to ComfyUI user permissions

Access Control

File access limited to ComfyUI's allowed directories
No direct access to system files outside allowed paths
Permission inheritance from ComfyUI's file system access
No elevation of privileges possible

CSRF Protection

Request Validation

All state-changing endpoints require additional validation:

XMLHttpRequest Header

Requests must include X-Requested-With: XMLHttpRequest
Prevents simple form submissions from external sites
Standard technique for AJAX endpoint protection

CSRF Token Alternative

Alternative validation using X-CSRF-Token header
Provides fallback for different client implementations
Tokens validated against session state

Origin Validation

When Origin header is present, it's validated against Host
Prevents cross-origin requests from unauthorized domains
Protects against certain types of cross-site attacks

Rate Limiting

Per-Client Limits

Rate limiting is implemented on expensive endpoints:

Affected Endpoints

Search operations (/mjr/am/search)
Index scanning (/mjr/am/scan)
Metadata extraction (/mjr/am/metadata)
Batch ZIP operations (/mjr/am/batch-zip)

Limit Configuration

Implemented in-memory per-client
Client identity based on IP address
Configurable thresholds for different operations
Resets after specified time intervals

Trusted Proxy Support

X-Forwarded-For header honored only from trusted proxies
Controlled by MAJOOR_TRUSTED_PROXIES environment variable
Prevents IP spoofing in proxy environments

Path Safety & Containment

Root Validation

All file operations validate root containment:

Allowed Roots

ComfyUI output directory
ComfyUI input directory
Custom roots defined by user
Collections directory

Path Validation Process

Normalize the requested path
Resolve to absolute path
Verify path starts with allowed root
Reject if outside allowed boundaries

Symlink Handling

Symlinks are handled carefully to prevent directory traversal
Optional symlink support via MJR_ALLOW_SYMLINKS environment variable
Disabled by default for security
When enabled, still validates final resolved path

Path Traversal Prevention

Input paths are normalized to prevent ../ attacks
Absolute path resolution ensures final location is verified
Multiple validation layers prevent bypass attempts

File Operation Security

Safe File Operations

All file operations go through security validation
Read operations limited to allowed directories
Write operations limited to index and temporary directories
Delete operations require additional confirmation

Batch ZIP Security

ZIP building streams directly from file handles
Prevents TOCTOU (Time-of-Check-Time-of-Use) race conditions
No temporary file copies created during ZIP building
Automatic cleanup of temporary ZIP files

File Type Validation

File types validated before processing
Dangerous file types blocked from certain operations
MIME type checking where possible
Extension validation for security-sensitive operations

Network Security

HTTP Security Headers

Applied to Majoor API endpoints only:

Content Security Policy

Content-Security-Policy: default-src 'none'
Prevents execution of injected content
Applies only to API responses

Content Type Options

X-Content-Type-Options: nosniff
Prevents MIME-type confusion attacks
Ensures content is treated as declared type

Frame Options

X-Frame-Options: DENY
Prevents embedding in iframes
Protects against clickjacking

Referrer Policy

Referrer-Policy: strict-origin-when-cross-origin
Limits referrer information leakage
Balances privacy with functionality

API Versioning Security

Versioned routes redirect to canonical endpoints
/mjr/am/v1/... redirects to /mjr/am/... using 308
Maintains security headers across versions
Preserves method and query parameters

External Tool Security

Tool Execution Safety

External tools (ExifTool, FFprobe) run with limited privileges
Input validation before passing to external tools
Timeout enforcement to prevent hanging operations
Output validation after tool execution

Path Validation for Tools

File paths validated before passing to external tools
No direct shell execution, only tool invocation
Input sanitization for all tool parameters
Tool output parsing with validation

Tool Location Security

Tools can be specified via environment variables
Default to system PATH for security
No arbitrary tool execution possible
Tool paths validated at startup

Environment Variable Security

Secure Configuration

Environment variables provide secure configuration without code changes:

Configuration Validation

Environment variables validated at startup
Invalid values fall back to defaults safely
No unsafe defaults used
Clear error messages for invalid configurations

Sensitive Information Handling

No passwords or secrets stored in environment
File paths validated for security
No direct system command execution via environment
Configuration changes logged appropriately

Trusted Proxy Configuration

MAJOOR_TRUSTED_PROXIES controls proxy trust
Default: 127.0.0.1,::1 (localhost only)
Prevents IP spoofing in proxy environments
Critical for rate limiting effectiveness

Threat Model

Identified Threats

Information Disclosure

Unauthorized access to file metadata
Exposure of file system structure
Leakage of generation parameters
Mitigation: Path validation, access controls

Path Traversal

Access to files outside allowed directories
Reading system files or other users' data
Writing to unauthorized locations
Mitigation: Path containment, normalization

Resource Exhaustion

Denial of service through expensive operations
Memory exhaustion via large metadata
Database locking through concurrent operations
Mitigation: Rate limiting, timeouts, resource limits

Code Execution

Arbitrary command execution through file operations
Injection through file names or paths
Malicious file content processing
Mitigation: Input validation, sandboxing

Cross-Site Attacks

CSRF attacks on API endpoints
XSS through metadata injection
Clickjacking of interface elements
Mitigation: CSRF tokens, security headers

Attack Vectors

Direct API Access

Unauthorized access to HTTP endpoints
Brute force attempts on protected endpoints
Protection: Origin validation, rate limiting

File System Manipulation

Creation of malicious file names
Symlink attacks in custom roots
Protection: Path validation, containment

Input Injection

Malformed metadata in files
Special characters in file names
Protection: Input sanitization, validation

Security Monitoring

Request Logging

Optional request logging via observability settings
Logs include client IP, endpoint, and timestamp
Sensitive data not logged (file contents, metadata)
Helpful for detecting unusual access patterns

Error Handling

Secure error messages that don't leak system information
Internal errors logged but not exposed to users
Validation errors provide guidance without revealing internals
Stack traces hidden from end users

Audit Trail

File operations logged with appropriate detail
Configuration changes tracked where applicable
Access patterns monitored for anomalies
Retention policies for security logs

Security Best Practices

Deployment Security

Network Isolation

Run ComfyUI behind appropriate firewalls
Limit network access to trusted users
Use VPN or other secure access methods
Monitor network traffic for anomalies

File System Permissions

Run ComfyUI with minimal required privileges
Restrict file system permissions appropriately
Regular permission audits
Separate user accounts for different functions

Regular Updates

Keep Assets Manager updated to latest version
Update external tools (ExifTool, FFprobe) regularly
Apply security patches promptly
Test updates in non-production environments first

Configuration Security

Principle of Least Privilege

Grant only necessary file system access
Disable unnecessary features
Use restrictive default settings
Regular security configuration reviews

Environment Hardening

Secure environment variable storage
Validate all configuration inputs
Use secure defaults where possible
Regular security configuration audits

Operational Security

Access Control

Limit access to authorized users
Regular access reviews
Session management best practices
Audit user activities appropriately

Monitoring and Detection

Monitor for unusual access patterns
Alert on security-relevant events
Regular security log reviews
Incident response procedures

Trusted Proxy Configuration

MAJOOR_TRUSTED_PROXIES

Purpose: IPs/CIDRs allowed to supply X-Forwarded-For/X-Real-IP
Default: 127.0.0.1,::1
Format: Comma-separated IPs or CIDR blocks
Security Impact: Controls which proxies can affect rate limiting
Example: MAJOOR_TRUSTED_PROXIES=127.0.0.1,192.168.1.0/24,10.0.0.0/8

Symlink Controls

MJR_ALLOW_SYMLINKS

Purpose: Allow symlink/junction custom roots
Default: off (disabled)
Options: on, off, true, false
Security Impact: Controls directory traversal risk
Example: MJR_ALLOW_SYMLINKS=on

Database Security

MAJOOR_DB_TIMEOUT

Purpose: Database operation timeout
Default: 30.0 seconds
Security Impact: Prevents resource exhaustion
Example: MAJOOR_DB_TIMEOUT=60.0

MAJOOR_DB_QUERY_TIMEOUT

Purpose: Maximum query execution time
Default: 30.0 seconds
Security Impact: Prevents long-running queries
Example: MAJOOR_DB_QUERY_TIMEOUT=45.0

Resource Limits

MAJOOR_MAX_METADATA_JSON_BYTES

Purpose: Maximum metadata JSON size stored in DB/cache
Default: 2097152 (2MB)
Security Impact: Prevents memory exhaustion
Example: MAJOOR_MAX_METADATA_JSON_BYTES=4194304

MJR_COLLECTION_MAX_ITEMS

Purpose: Max items per collection JSON
Default: 50000
Security Impact: Prevents resource exhaustion
Example: MJR_COLLECTION_MAX_ITEMS=100000

Dependency Management

MJR_AM_NO_AUTO_PIP

Purpose: Disable best-effort dependency auto-install on startup
Default: Auto-install enabled
Security Impact: Controls external package installation
Options: 1, true, yes, on to disable
Example: MJR_AM_NO_AUTO_PIP=1

Security Testing

Self-Assessment Checklist

Regularly verify security configuration:

Access Controls

[ ] File system access limited to intended directories
[ ] Custom roots validated and secure
[ ] No unauthorized file access possible

Network Security

[ ] CSRF protection active on state-changing endpoints
[ ] Rate limiting functioning properly
[ ] Security headers applied correctly

Input Validation

[ ] Path traversal prevented
[ ] File type validation working
[ ] External tool inputs sanitized

Penetration Testing Considerations

When performing security testing:

Authorized Testing Only

Ensure proper authorization before testing
Test in isolated environments when possible
Document and report findings appropriately

Testing Areas

Path traversal attempts
Input validation bypasses
Authentication bypasses
Resource exhaustion attacks
Cross-site scripting attempts

Incident Response

Security Event Classification

Low Risk: Minor configuration issues
Medium Risk: Potential information disclosure
High Risk: System compromise or data breach
Critical Risk: Active exploitation in progress

Response Procedures

Isolate affected systems
Document the incident
Assess scope and impact
Apply immediate mitigations
Investigate root cause
Implement permanent fixes
Communicate appropriately
Review and improve procedures

Security Model & Environment Variables Guide Version: 1.0 Last Updated: January 2026

Source: docs/SECURITY_ENV_VARS.md

TESTING.md

Running tests and reading reports

Testing

This project uses pytest. On Windows, batch runners are provided for convenience and generate both:

JUnit XML (.xml)
a styled HTML report (.html)

Reports are written to:

tests/__reports__/

Open the index:

tests/__reports__/index.html

Quick commands

From the repo root:

python -m pytest -q

Run a single folder:

python -m pytest tests/metadata -q

Batch runners (Windows)

From the repo root:

Full suite: run_tests.bat (delegates to tests/run_tests_all.bat)
Quick suite (skips test_comfy_output): run_tests_quick.bat
Metadata / parser suite: run_tests_parser.bat

Category runners:

tests/config/run_tests_config.bat
tests/core/run_tests_core.bat
tests/database/run_tests_database.bat
tests/features/run_tests_features.bat
tests/metadata/run_tests_metadata.bat
tests/rating_tags/run_tests_rating_tags.bat
tests/regressions/run_tests_regressions.bat

All batch runners support /nopause for non-interactive runs:

run_tests_quick.bat /nopause

Test artifacts (DB/WAL/SHM)

Some tests create SQLite files. Pytest temp files are stored under:

tests/__pytest_tmp__/

This includes .db, .db-wal, *.db-shm, and other runtime artifacts.

Parser samples (metadata extraction)

tests/metadata/test_parser_folder_scan.py scans every file under:

tests/parser/ (recursive)

If you don't want to commit large samples, you can point the test to an external folder:

$env:MJR_TEST_PARSER_DIR = "C:\path\to\parser"\npython -m pytest tests/metadata/test_parser_folder_scan.py -q

Source: docs/TESTING.md

COMPLETE_USER_GUIDE.md

Step-by-step user guide with workflows

Majoor Assets Manager - Complete User Guide

Getting Started
Basic Operations
Advanced Features
Workflow Integration
Organization Strategies
Troubleshooting
Tips & Tricks

Getting Started

Prerequisites

Before starting with the Majoor Assets Manager, ensure you have:

ComfyUI installed and running
The Majoor Assets Manager extension installed
(Optional but recommended) ExifTool and FFprobe installed for full metadata functionality

First Launch

Start ComfyUI as usual
Open your browser and navigate to the ComfyUI interface
Look for the "Assets Manager" tab or panel
Click on the Assets Manager tab to open the interface

Initial Interface Overview

When you first open the Assets Manager, you'll see:

Top Navigation: Tabs for Outputs, Inputs, Custom, and Collections
Search Bar: For searching across all assets
Filter Panel: For applying filters and sorting
Asset Grid: Main display area showing asset thumbnails
Status Bar: Showing current status and scan progress

Initial Scan

The first time you open each scope (Outputs, Inputs, Custom), the system will automatically begin scanning:

Wait for the initial scan to complete (shown in status bar)
The asset grid will populate with thumbnails
Use the search bar to find specific assets
Apply filters to narrow down results

Basic Operations

Browsing Assets

Switching Between Scopes

Click on the "Outputs" tab to browse generated outputs
Click on the "Inputs" tab to browse input images
Click on the "Custom" tab to browse custom directories
Click on the "Collections" tab to browse saved collections

Viewing Assets

Browse through the asset grid by scrolling
Click on any asset to select it
Double-click on an asset to open the viewer
Use the pagination controls to navigate through pages

Searching for Assets

Basic Search

Click in the search bar at the top
Type your search term (e.g., "landscape", "character")
Press Enter or wait for results to appear
Results will be highlighted and ranked by relevance

Advanced Search

Use quotes for exact phrases: "fantasy warrior"
Combine terms for broader search: portrait fantasy
Use filters in combination with search for refined results

Applying Filters

Filter by File Type

Click the "Kind" filter dropdown
Select the file types you want to see (Images, Videos, Workflows)
The asset grid will update to show only selected types

Filter by Rating

Click the "Rating" filter dropdown
Select minimum rating (e.g., "3 stars or higher")
Only assets meeting the rating threshold will be shown

Filter by Date

Click the date filter icon
Select a date range using the calendar
Apply the filter to see assets from the selected period

Sorting Results

Click the sort dropdown (usually shows "Relevance" by default)
Select your preferred sort order (Name, Date, Size, Rating, etc.)
Toggle ascending/descending order if needed

Advanced Features

Using the Viewer

Opening the Viewer

Double-click on any asset in the grid
Or right-click and select "Open in Viewer"
The advanced viewer will open in a modal window

Use mouse wheel to zoom in/out
Click and drag to pan around the image
Press "0" to fit image to screen
Press "1" or "Alt+1" for 1:1 pixel view

Image Analysis Tools

Press "F" to toggle false color mode
Press "Z" to toggle zebra patterns
Press "G" to cycle through grid overlays
Press "I" to toggle pixel probe
Press "L" to toggle loupe magnification

Video Playback

Use play/pause button to control playback
Drag the timeline slider to seek to specific points
Press "Shift+Left/Right" to step through frames
Set In/Out points with "I" and "O" keys

Rating and Tagging Assets

Rating an Asset

Right-click on an asset
Select "Rate" from the context menu
Choose the number of stars (0-5)
Or press the corresponding number key (0-5) when asset is selected

Adding Tags

Right-click on an asset
Select "Edit Tags" from the context menu
Type your tags separated by commas
Press Enter to save the tags

Bulk Operations

Hold Ctrl/Cmd and click to select multiple assets
Or click one asset, hold Shift, and click another to select a range
Right-click on any selected asset
Apply rating or tags to all selected items

Creating and Managing Collections

Creating a New Collection

Select one or more assets
Right-click and choose "Add to Collection"
Select "Create New Collection"
Give your collection a name
The collection is created and assets are added

Adding to Existing Collection

Select one or more assets
Right-click and choose "Add to Collection"
Select an existing collection from the list
Assets are added (duplicates are automatically skipped)

Managing Collections

Switch to the "Collections" tab
Right-click on a collection name
Choose from options like Rename, Delete, or Clear
To view a collection's contents, simply click on its name

Using Drag and Drop

Dragging to ComfyUI Canvas

Select one or more assets
Click and hold on an asset thumbnail
Drag the asset onto the ComfyUI canvas
Release to drop - the asset path will be injected into compatible nodes

Dragging to Operating System

Select one or more assets
Click and drag an asset outside the browser window
For single files: drops the original file
For multiple files: creates and drops a ZIP file

Workflow Integration

Integrating Assets into Workflows

Loading Assets into Nodes

Find the asset you want to use in Assets Manager
Drag it directly onto the ComfyUI canvas
The asset path will be automatically injected into compatible nodes
Common compatible nodes: LoadImage, LoadVideo, etc.

Using Collections for Workflow Elements

Create collections for different types of assets (characters, backgrounds, etc.)
Organize assets by project or style
Use collections to quickly access frequently used assets
Share collections with team members

Metadata-Driven Workflows

Examining Generation Parameters

Open an asset in the viewer
Look at the metadata panel for generation details
Note the model, sampler, steps, CFG scale, etc.
Use this information to recreate or modify results

Reproducing Results

Find a result you like in Assets Manager
Note the seed value in the metadata
Use the same parameters with the same seed to reproduce
Or slightly modify parameters for variations

Quality Assessment Workflow

Rating System for Quality Control

Establish consistent rating criteria for your workflow
Rate assets as you review them (0-5 stars)
Use rating filters to quickly find high-quality results
Focus your attention on top-rated assets

Tagging for Organization

Develop a consistent tagging system
Tag assets by subject, style, quality, or other relevant categories
Use tags to quickly find assets with specific characteristics
Combine tags with other filters for precise searching

Organization Strategies

Effective Tagging Systems

Hierarchical Tagging

Use colons to create hierarchy: "subject:person:face:portrait"
Organize tags in logical groups
Use consistent terminology across your collection
Create tag templates for common categories

Project-Based Tagging

Tag assets by project: "project:client_name"
Use status tags: "status:approved", "status:rejected", "status:review"
Add version tags: "version:v1", "version:final"
Include collaboration tags: "collaborator:designer_name"

Collection Organization

Thematic Collections

Create collections based on themes or subjects
Group similar styles together
Separate experimental work from production assets
Create mood boards as collections

Workflow Collections

Create collections for different stages of your workflow
"Reference" collection for inspiration
"To Review" collection for pending evaluation
"Approved" collection for final assets

Client/Project Collections

Create separate collections for each client or project
Use consistent naming conventions
Include version information in collection names
Archive old project collections when appropriate

Rating Strategies

Consistent Rating Criteria

Define what each star rating means for your work
Apply ratings consistently across similar asset types
Revisit and adjust ratings periodically as needed
Use ratings to identify your most successful techniques

Quality Filtering

Use rating filters to focus on high-quality results
Set minimum rating thresholds for different purposes
Regularly review low-rated assets for improvement opportunities
Use ratings to track improvement over time

Troubleshooting

Common Issues and Solutions

Assets Not Appearing

Problem: Assets don't show up in the grid Solution:

Check if the correct scope is selected (Outputs, Inputs, Custom, Collections)
Trigger a manual scan with Ctrl/Cmd+S
Verify the directory contains assets in supported formats
Check ComfyUI console for error messages

Slow Performance

Problem: Interface is slow or unresponsive Solution:

Reduce page size in settings
Apply more specific filters to reduce results
Close other browser tabs to free memory
Restart ComfyUI if the issue persists

Metadata Not Loading

Problem: Metadata panel shows "Loading..." indefinitely Solution:

Verify ExifTool and FFprobe are installed and in PATH
Check file permissions for the asset files
Try refreshing the metadata manually
Check if the file format is supported

Search Not Working

Problem: Search returns no results or unexpected results Solution:

Wait for initial indexing to complete
Trigger a manual scan with Ctrl/Cmd+S
Try simpler search terms
Check that the correct scope is selected

Advanced Troubleshooting

Index Database Issues

Problem: Assets Manager behaves unexpectedly or shows old data Solution:

Clear the index database (backup first if needed)
Trigger a full rescan of your directories
Check the index database file permissions
Verify disk space is available

File Permission Issues

Problem: Cannot access certain files or directories Solution:

Check that ComfyUI has read access to the directories
Verify file ownership and permissions
Run ComfyUI with appropriate user privileges
Check for any security software blocking access

External Tool Issues

Problem: Metadata extraction or file tagging not working Solution:

Verify ExifTool and FFprobe are properly installed
Test the tools independently from command line
Set explicit paths using environment variables if needed
Check that the tools have appropriate file access permissions

Tips & Tricks

Productivity Boosters

Keyboard Shortcuts Mastery

Learn rating shortcuts (0-5 keys) for quick evaluation
Use Ctrl+A to select all visible assets
Master navigation keys (arrows, Page Up/Down) for efficient browsing
Use D key to toggle details sidebar quickly

Search Efficiency

Use specific terms rather than generic ones
Combine search with filters for precise results
Use quotes for exact phrase matching
Leverage metadata fields in searches (e.g., "model:SDXL")

Batch Operations

Select multiple assets using Ctrl/Cmd+click or Shift+click
Apply ratings or tags to multiple assets at once
Drag multiple assets to ComfyUI canvas simultaneously
Use collections for batch operations

Advanced Techniques

Power User Workflow

Use Collections to create reusable asset libraries
Develop consistent tagging schemes for your work
Leverage metadata to understand what parameters produce good results
Use the viewer's analysis tools for quality assessment

Integration with External Tools

Export collections as JSON for use in other applications
Use drag-and-drop to integrate with design software
Leverage metadata for automated processing pipelines
Share assets and collections with collaborators

Customization and Optimization

Adjust page size based on your system's capabilities
Configure auto-scan settings for your workflow
Set up custom roots for frequently accessed directories
Fine-tune performance settings based on your hardware

Best Practices

Organization Best Practices

Establish consistent naming conventions
Regularly clean up unused collections
Maintain a manageable number of tags
Use hierarchical tags for complex organization

Performance Best Practices

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

Collaboration Best Practices

Share consistent tagging schemes with team members
Use standardized collection naming conventions
Document your rating criteria for consistency
Export and share valuable collections

Quick Reference

Essential Keyboard Shortcuts

Ctrl+S / Cmd+S: Trigger index scan
D: Toggle details sidebar
0-5: Rate selected asset (0-5 stars)
Enter: Open viewer for selected asset
Ctrl+A / Cmd+A: Select all visible assets
Ctrl+F / Cmd+F: Focus search bar
Escape: Close viewer or clear selection

Common Tasks Quick Steps

Find Recent High-Quality Assets

Click "Outputs" tab
Set rating filter to "4 stars or higher"
Set date filter to last week
Sort by date (descending)

Create a Mood Board Collection

Browse and select relevant assets
Right-click and choose "Add to Collection"
Create new collection named "Mood Board YYYY-MM-DD"
Continue adding assets as needed

Evaluate a Batch of Results

Apply relevant filters to isolate results
Select all with Ctrl+A
Use rating shortcuts to quickly assess quality
Create a collection of top-rated items

Create a collection with the assets to share
Export the collection as JSON
Send the JSON file to recipients
They can import the collection to access the assets

Complete User Guide Version: 1.0 Last Updated: January 2026

Source: docs/COMPLETE_USER_GUIDE.md

AUDIT_ISSUES.md

Additional documentation

ComfyUI-Majoor-AssetsManager - Audit Issues

Generated: 2026-01-23 | Version: 2.1.1

CRITICAL (Fix Immediately)

1. Memory Leak - Event Handlers Not Cleaned Up

File: js/entry.js (lines 149-155)
Issue: Event handlers stored on api._mjrExecutedHandler and api._mjrRtHandlers are never cleared when extension is destroyed. Multiple reloads cause handler accumulation.
Fix: Use AbortController or implement cleanup on extension unload.
Status: FIXED (2026-01-23) — runtime AbortController + timer tracking + handler cleanup.

2. Memory Leak - Hydration Queue Global State

File: js/features/grid/GridView.js (line 26)
Issue: Global RT_HYDRATE_QUEUE never cleared when grid is destroyed. Stale jobs from destroyed grids could run on new grids.
Fix: Associate queue with specific grid via WeakMap.
Status: FIXED (2026-01-23) — per-grid WeakMap queue + cleanup on dispose.

3. Error Message Information Leak

File: backend/routes/handlers/search.py (lines 668-670)
Issue: Full exception details exposed in workflow-quick endpoint response.
Fix: Use safe_error_message() wrapper.
Status: FIXED (2026-01-23) — response uses safe_error_message(...) (logs may still contain exception details, by design).

HIGH PRIORITY

4. Missing Rate Limiting on Search Endpoints

Files: backend/routes/handlers/search.py
Issue: /mjr/am/list and /mjr/am/search have NO rate limits - bulk queries could exhaust database.
Fix: Add rate limiting similar to metadata endpoint (e.g., 50/60s).
Status: FIXED (2026-01-23) — 50 requests / 60s per endpoint key.

5. Monolithic Function - VideoControls

File: js/components/VideoControls.js
Issue: mountVideoControls function is 1295 lines - impossible to test/maintain.
Fix: Split into 5-10 smaller functions (state, UI, handlers, etc.).
Status: FIXED (2026-01-24) — extracted preview + option parsing into helpers and reduced mountVideoControls complexity (manual QA still recommended).

6. Workflow Cache Unbounded Growth

File: js/features/dnd/DragDrop.js (lines 34-51)
Issue: No time-based eviction. Cache cleared only on size limit, not TTL.
Fix: Add TTL check on cache hit, evict expired entries.
Status: ALREADY IMPLEMENTED — WORKFLOW_CACHE_TTL_MS + TTL check on hit + eviction on trim.

7. O(n) Pagination Performance

File: backend/routes/handlers/filesystem.py (line 360)
Issue: filtered_entries[offset: offset + limit] is O(offset) - poor for large offsets.
Fix: Implement keyset/cursor-based pagination.
Status: MITIGATED (2026-01-23) — builds only the requested page (no full filtered list + slicing); true keyset pagination deferred.

8. Thread Pool Exhaustion Risk

File: backend/routes/handlers/scan.py (lines 721-749)
Issue: Each staged file spawns separate asyncio.to_thread(link_or_copy).
Fix: Batch into single thread pool task.
Status: FIXED (2026-01-23) — batched staging operations into one to_thread call.

9. Error Message Leak in Tags Handler

File: backend/routes/handlers/assets.py (line 399)
Issue: f"Failed to update tags: {exc}" exposes exception details.
Fix: Use safe_error_message(exc, "Failed to update tags").
Status: FIXED (2026-01-23) — uses safe error message wrapper.

MEDIUM PRIORITY

10. Output Directory Cache Never Invalidates

File: js/app/config.js (line 16)
Issue: Output directory cached forever. If user changes it in ComfyUI, extension won't detect.
Fix: Add cache TTL or event-driven invalidation.
Status: FIXED (2026-01-23) — TTL cache + invalidateOutputDirectoryCache().

11. Race Condition - Rapid Rating Clicks

File: js/components/RatingEditor.js (line 44)
Issue: Multiple rapid clicks trigger concurrent backend requests without locking.
Fix: Add request-in-flight flag or debounce.
Status: FIXED (2026-01-23) — in-flight lock + disables stars during save.

12. Timer Memory Leak in VideoControls

File: js/components/VideoControls.js (line 495)
Issue: _stepFlashTimer could be orphaned if controls destroyed during timeout.
Fix: Use AbortController for timeout cancellation.
Status: FIXED (2026-01-24) — timer is abortable (AbortController) and cancelled on destroy; no orphaned timeouts.

13. Timer Memory Leak in TagsEditor

File: js/components/TagsEditor.js (lines 409-411)
Issue: setTimeout stored but not cleared if element removed before timeout fires.
Fix: Store timer reference and clear in cleanup.
Status: FIXED (2026-01-23) — guarded timers + cleanup, plus RAF-based listener binding.

14. Race Condition - File Stat/Mtime

File: backend/routes/handlers/assets.py (line 728)
Issue: stat().st_mtime called after resolve(strict=True) - file could be deleted between operations.
Fix: Add race condition handling with try/except.
Status: FIXED (2026-01-23) — stat/race handled defensively.

15. Unbounded Rename Counter

File: backend/routes/handlers/scan.py (line 132)
Issue: Counter-based rename collision handling has no limit - could loop indefinitely.
Fix: Add counter limit (e.g., 1000) and return error if exceeded.
Status: FIXED (2026-01-23) — bounded by MJR_MAX_RENAME_ATTEMPTS (default 1000).

16. TypeError Treated as Retryable

File: js/api/client.js (line 66)
Issue: TypeError includes code errors, not just network failures - masks actual bugs.
Fix: Only retry on specific network errors (ECONNREFUSED, etc.).
Status: FIXED (2026-01-23) — retries only on fetch/network-like TypeError messages.

17. Missing Tag Input Validation

File: js/components/TagsEditor.js (line 174)
Issue: No validation of tag content (special chars, length) on frontend.
Fix: Add length/character restrictions before sending to backend.
Status: FIXED (2026-01-23) — validation + max tags, blocks control chars and separators.

18. Excessive DOM Updates on Video Seek

File: js/components/VideoControls.js (lines 728-758)
Issue: Frame labels rebuilt on every seek - O(n) DOM operations for long videos.
Fix: Use CSS-based positioning or virtual rendering.
Status: FIXED (2026-01-23) — seek labels rebuild is cached by key (skips rebuild when unchanged).

19. Video Thumbnail Memory Management

File: js/components/Card.js (lines 106-135)
Issue: Up to 6 concurrent videos allowed, but no cleanup on container removal.
Fix: Implement cleanup in IntersectionObserver disconnect.
Status: FIXED (2026-01-23) — explicit cleanup exported and called from grid disposal.

20. Duplicated safeCall Utilities

Files: js/features/viewer/lifecycle.js, panzoom.js, mediaFactory.js
Issue: safeCall/safeAddListener implemented in multiple files.
Fix: Extract to shared utility module js/utils/safeCall.js.
Status: FIXED (2026-01-23) — shared js/utils/safeCall.js used by viewer modules.

LOW PRIORITY

21. Unused metadata_cache Table

File: backend/adapters/db/schema.py (lines 73-79)
Issue: Table appears unused in codebase - adds maintenance burden.
Fix: Remove if confirmed unused after testing.
Status: NOT AN ISSUE — metadata_cache is used by the indexing pipeline (scanner/enricher/helpers) and invalidated on asset ops.

22. Magic Numbers Throughout Code

Files: Multiple
Examples:

js/entry.js - UI_BOOT_DELAY_MS (default 1500ms) and AUTO_REFRESH_DEBOUNCE_MS
js/entry.js - RAF_STABILIZE_FRAMES (layout stabilization)
js/components/VideoControls.js - MAX_MINOR_TICKS (tick cap)
backend/routes/handlers/filesystem.py - BG_SCAN_FAILURE_HISTORY_MAX (default 50) and SCAN_PENDING_MAX

Fix: Extract to named constants in config files.
Status: FIXED (2026-01-24) - extracted thresholds/limits/timeouts into named constants (env-configurable where it makes sense); remaining numeric literals are intentional (UI styling, RGBA values, standard codes).

23. Inconsistent Asset ID Type

Files: Frontend modules
Issue: assetId sometimes Number, sometimes String. RootId uses root_id, rootId, custom_root_id.
Fix: Standardize on one type/naming convention throughout.
Status: FIXED (2026-01-24) — frontend now normalizes IDs via js/utils/ids.js and uses root_id consistently; legacy aliases remain accepted at boundaries.

24. Z-Index Hardcoding

File: js/components/RatingEditor.js (line 163)
Issue: z-index: 2147483647 (max int32) hardcoded.
Fix: Use CSS variable or configuration constant.
Status: FIXED (2026-01-23) — uses shared MENU_Z_INDEX constant.

25. Path String Comparison on Windows

File: backend/routes/handlers/search.py (lines 299-301)
Issue: Manual string comparison for path containment could fail with UNC paths.
Fix: Use pathlib operations instead of string comparisons.
Status: FIXED (2026-01-23) — uses robust path containment via commonpath / Path normalization.

26. Inefficient Badge Updates

File: js/features/grid/GridView.js (line 73)
Issue: Full DOM replacement of rating badge instead of attribute updates.
Fix: Only update text/visibility of existing badge elements.
Status: FIXED (2026-01-23) — updates in place.

27. Missing isConnected Check

File: js/features/grid/GridView.js (line 67)
Issue: _updateCardRatingTagsBadges called without checking if card still in DOM.
Fix: Check card.isConnected before mutation.
Status: FIXED (2026-01-23) — guards with card.isConnected.

28. Directory Listing Cache Invalidation

File: backend/routes/handlers/filesystem.py (lines 165-167)
Issue: Directory mtime_ns check doesn't account for newly added files on some filesystems.
Fix: Consider inotify/FSEvents for filesystem-based updates.
Status: FIXED (2026-01-24) — watchdog-based invalidation token prevents stale cache when directory mtime is unreliable.

TESTING GAPS

Missing Test Coverage

Area	Priority
Concurrent access patterns	High
Path traversal attack attempts	High
Frontend unit tests	High
Large file handling (>500MB)	Medium
Symlink/junction edge cases	Medium
Unicode filename handling	Medium
Malformed request handling	Low

CONFIGURATION RECOMMENDATIONS

Add These Environment Variables

MJR_MAX_RENAME_ATTEMPTS=1000    # Limit for rename collision handling (implemented)\n# Recommended (not implemented yet): MJR_RATE_LIMIT_WINDOW, MJR_CLEANUP_INTERVAL, MJR_QUERY_TIMEOUT_MS

QUICK REFERENCE

Priority	Count	Estimated Effort
Critical	0	done
High	0	done
Medium	0	done
Low	0	done
Total	0	done

Source: docs/AUDIT_ISSUES.md

Majoor Assets Manager • Documentation • January 2026

Introduction

DOCUMENTATION_INDEX.md

Majoor Assets Manager - Documentation Index

Documentation Files

Getting Started

Core Features

Configuration & Usage

Complete Guides

Quick Start

Key Features Overview

Optional Dependencies (Highly Recommended)

Support

Contributing

USER_GUIDE.md

Majoor Assets Manager - Comprehensive User Guide

Table of Contents

Introduction

Key Benefits

Installation & Setup

Prerequisites

Installation Methods

Method 1: Using ComfyUI Manager (Recommended)

Method 2: Manual Installation

Optional Dependencies (Highly Recommended)

Windows

macOS

Linux (Ubuntu/Debian)

Core Features

Asset Browser Interface

Initial Setup

Navigation

Search & Filtering

Full-Text Search

Advanced Filters

Kind Filter

Rating Filter

Workflow Filter

Date Filters

Sorting Options

Search Tips

Metadata & Viewer

Metadata Extraction

Image Metadata

Video Metadata

Extraction Backends

Advanced Viewer

Single View Mode

Comparison Modes

Video Player

Overlays

Export Options

Context Menu Actions

Ratings, Tags & Collections

Rating System

Tagging System

Collections

Creating Collections

Managing Collections

Collection Features

Drag & Drop Functionality

Drag to ComfyUI Canvas

Drag to Operating System

Filename Collision Indicator

Hotkeys & Shortcuts

Global Hotkeys

Viewer Hotkeys

Notes

Settings & Configuration

Browser-Based Settings

Display Settings

Performance Settings

Viewer Settings

Backend Configuration

Environment Variables

Troubleshooting

Common Issues

Missing Dependencies

Slow Performance

Index Not Updating

Metadata Extraction Issues