nodes/MajoorWaldi-ComfyUI-Majoor-AssetsManager
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity
Files
834ef1fef35aa06c32fb5afaeb8a0a600fe95cb8
MajoorWaldi-ComfyUI-Majoor-…/docs/DOCUMENTATION_INDEX.md
T
MajoorWaldi 834ef1fef3 feat(docs): comprehensive AI features guide and new documentation 
- Added new AI_FEATURES.md guide covering all AI-powered capabilities
- Updated DOCUMENTATION_INDEX.md to include new AI features guide
- Added AI Features section to README.md with overview and models used
- Improved backfill warning information in README.md
- Updated reset index / delete DB procedures in DB_MAINTENANCE.md
- Added configuration options for AI features in README.md
2026-03-06 12:43:46 +01:00

470 lines
15 KiB
Markdown
Raw Blame History

# Majoor Assets Manager - Documentation Index
Welcome to the comprehensive documentation for the **Majoor Assets Manager** for ComfyUI. This collection of guides covers all features, from basic usage to advanced configuration and development.
**Current Version**: 2.4.0
**Last Updated**: March 5, 2026
---
## 🚀 Quick Start
### New Users
1. **[Installation Guide](INSTALLATION.md)** — Install and set up the extension
2. **[User Guide (HTML)](../user_guide.html)** — Visual walkthrough with screenshots
3. **[Hotkeys & Shortcuts](HOTKEYS_SHORTCUTS.md)** — Essential keyboard shortcuts
4. **[Basic Search](SEARCH_FILTERING.md)** — Find your assets quickly
### Returning Users (v2.4.0)
- **[AI Features Guide](AI_FEATURES.md)** — NEW comprehensive AI capabilities
- **[Majoor Floating Viewer](VIEWER_FEATURE_TUTORIAL.md#majoor-floating-viewer-mfv)** — NEW real-time preview panel
- **[Changelog](../CHANGELOG.md)** — What's new in this version
- **[Linux Support](INSTALLATION.md#linux-installation)** — Now fully supported on Linux
---
## 📚 Documentation Categories
### Getting Started
| Document | Description |
|----------|-------------|
| **[INSTALLATION.md](INSTALLATION.md)** | Detailed installation instructions (Manager + Manual) |
| **[USER_GUIDE.md](../user_guide.html)** | Full HTML user guide with visual examples |
| **[HOTKEYS_SHORTCUTS.md](HOTKEYS_SHORTCUTS.md)** | Keyboard shortcuts and hotkeys reference |
| **[SHORTCUTS.md](SHORTCUTS.md)** | Additional shortcuts and gestures |
### Core Features
| Document | Description |
|----------|-------------|
| **[SEARCH_FILTERING.md](SEARCH_FILTERING.md)** | Full-text search, filters, and sorting |
| **[VIEWER_FEATURE_TUTORIAL.md](VIEWER_FEATURE_TUTORIAL.md)** | Advanced viewer, MFV, and analysis tools |
| **[RATINGS_TAGS_COLLECTIONS.md](RATINGS_TAGS_COLLECTIONS.md)** | Organization with ratings, tags, and collections |
| **[DRAG_DROP.md](DRAG_DROP.md)** | Drag & drop to canvas and OS |
| **[AI_FEATURES.md](AI_FEATURES.md)** | 🆕 AI-powered semantic search, auto-tags, and more |
### Configuration & Settings
| Document | Description |
|----------|-------------|
| **[SETTINGS_CONFIGURATION.md](SETTINGS_CONFIGURATION.md)** | Browser settings and UI configuration |
| **[SECURITY_ENV_VARS.md](SECURITY_ENV_VARS.md)** | Environment variables and security model |
| **[SECURITY_ENV_VARS.md#api-security](SECURITY_ENV_VARS.md#api-security)** | API token and remote access setup |
### Maintenance & Troubleshooting
| Document | Description |
|----------|-------------|
| **[DB_MAINTENANCE.md](DB_MAINTENANCE.md)** | Database maintenance, corruption recovery |
| **[TESTING.md](TESTING.md)** | Running tests and reading reports |
| **[INSTALLATION.md#troubleshooting](INSTALLATION.md#troubleshooting)** | Common installation issues |
### Advanced Documentation
| Document | Description |
|----------|-------------|
| **[API_REFERENCE.md](API_REFERENCE.md)** | Complete API endpoint reference |
| **[THREAT_MODEL.md](THREAT_MODEL.md)** | Security architecture and threat analysis |
| **[ADR/](adr/)** | Architecture Decision Records |
---
## 🎯 Feature-Specific Guides
### Majoor Floating Viewer (MFV) — NEW! 🎉
**[VIEWER_FEATURE_TUTORIAL.md](VIEWER_FEATURE_TUTORIAL.md)** — Complete guide to the floating viewer:
- Live Stream Mode for real-time generation tracking
- Compare modes (Simple, A/B, Side-by-Side)
- Node tracking for LoadImage/SaveImage preview
- Pan, zoom, and gen info overlay
- Keyboard shortcuts and controls
### Asset Browser
**[SEARCH_FILTERING.md](SEARCH_FILTERING.md)** — Browse and filter your assets:
- Full-text search with FTS5 and BM25 ranking
- Kind filter (image, video, audio, model3d)
- Rating, workflow, and date filters
- Inline attribute filters (`rating:5`, `ext:png`)
- Sort options and pagination
### Viewer & Analysis Tools
**[VIEWER_FEATURE_TUTORIAL.md](VIEWER_FEATURE_TUTORIAL.md)** — Advanced viewing and analysis:
- Image enhancement (exposure, gamma, channel isolation)
- Analysis tools (false color, zebra, histogram, waveform, vectorscope)
- Visual overlays (grid, pixel probe, loupe)
- Video playback controls and in/out points
- Export capabilities (save frame, copy to clipboard)
### Organization System
**[RATINGS_TAGS_COLLECTIONS.md](RATINGS_TAGS_COLLECTIONS.md)** — Organize your assets:
- 5-star rating system with Windows sync
- Custom hierarchical tags
- Collections for grouping assets
- Bulk operations and synchronization
### Drag & Drop
**[DRAG_DROP.md](DRAG_DROP.md)** — Drag and drop functionality:
- Drag to ComfyUI canvas (single/multiple)
- Drag to OS (auto-ZIP for multi-select)
- Node compatibility and staging
- File transfer mechanisms
### AI Features — NEW! 🎉
**[AI_FEATURES.md](AI_FEATURES.md)** — Complete guide to AI-powered capabilities:
- **Semantic Search**: Natural language search across your library
- **Find Similar**: Discover visually similar assets
- **AI Auto-Tags**: Automatic tag suggestions (portrait, landscape, cyberpunk, etc.)
- **Enhanced Captions**: Florence-2 generated image descriptions
- **Prompt Alignment Score**: Measure image-prompt matching quality
- **Smart Collections**: Auto-group assets by visual similarity
- **Discover Groups**: Cluster library by visual themes
- Models: SigLIP2 (image/text), X-CLIP (video), Florence-2 (caption)
- Configuration, tuning, and troubleshooting
---
## 🔧 Configuration Guides
### Browser Settings (localStorage)
**[SETTINGS_CONFIGURATION.md](SETTINGS_CONFIGURATION.md)** — UI and performance settings:
- Page size and sidebar position
- Auto-scan and poll intervals
- Hide PNG siblings option
- Tags cache TTL
### Environment Variables (Backend)
**[SECURITY_ENV_VARS.md](SECURITY_ENV_VARS.md)** — Server-side configuration:
#### Directory & Tools
```bash
MAJOOR_OUTPUT_DIRECTORY="/path/to/output"
MAJOOR_EXIFTOOL_PATH="/path/to/exiftool"
MAJOOR_FFPROBE_PATH="/path/to/ffprobe"
MAJOOR_MEDIA_PROBE_BACKEND="auto"
```
#### Database Tuning
```bash
MAJOOR_DB_TIMEOUT=60.0
MAJOOR_DB_MAX_CONNECTIONS=12
MAJOOR_DB_QUERY_TIMEOUT=45.0
```
#### Security & API
```bash
MAJOOR_API_TOKEN="your-secret-token"
MAJOOR_REQUIRE_AUTH=1
MAJOOR_TRUSTED_PROXIES=127.0.0.1,192.168.1.0/24
MAJOOR_ALLOW_REMOTE_WRITE=1 # ⚠️ Unsafe
```
#### Safe Mode Operations
```bash
MAJOOR_SAFE_MODE=0
MAJOOR_ALLOW_DELETE=1
MAJOOR_ALLOW_RENAME=1
```
---
## 🗄️ Database & Maintenance
### Index Database
**[DB_MAINTENANCE.md](DB_MAINTENANCE.md)** — Database management:
- Location: `<output>/_mjr_index/assets.sqlite`
- Reset Index button (requires readable DB)
- Delete DB button (works on corrupted DB)
- Optimize endpoint (`PRAGMA optimize`)
### Corruption Recovery
**[DB_MAINTENANCE.md#delete-db-emergency-recovery](DB_MAINTENANCE.md#delete-db-emergency-recovery)**:
1. Click **Delete DB** button in UI
2. Or manually delete SQLite files
3. Restart ComfyUI for rebuild
### Data Locations
| Data Type | Location |
|-----------|----------|
| Index DB | `<output>/_mjr_index/assets.sqlite` |
| Custom Roots | `<output>/_mjr_index/custom_roots.json` |
| Collections | `<output>/_mjr_index/collections/*.json` |
| Batch ZIPs | `<output>/_mjr_batch_zips/` |
---
## 🔒 Security Documentation
### Security Model
**[SECURITY_ENV_VARS.md](SECURITY_ENV_VARS.md)** — Comprehensive security guide:
- Authentication & authorization
- CSRF protection and origin validation
- Rate limiting on expensive endpoints
- Path containment and traversal prevention
- File operation security
### Threat Model
**[THREAT_MODEL.md](THREAT_MODEL.md)** — Security architecture:
- Identified threats and mitigations
- Attack vectors and protections
- Security monitoring and logging
- Incident response procedures
### API Security
**[SECURITY_ENV_VARS.md#api-security](SECURITY_ENV_VARS.md#api-security)**:
- Token-based authentication
- Safe Mode for write operations
- Remote access configuration
- Trusted proxy support
---
## 🧪 Testing & Development
### Running Tests
**[TESTING.md](TESTING.md)** — Test suite documentation:
#### Backend (pytest)
```bash
# All tests
python -m pytest tests/ -q
# Single file
python -m pytest tests/core/test_index.py -v
# With coverage
pytest tests/ --cov=mjr_am_backend --cov-report=html
```
#### Frontend (Vitest)
```bash
npm run test:js
npm run test:js:watch
```
#### Windows Batch Runners
```bat
run_tests.bat # Full suite
run_tests_quick.bat # Quick suite (skips slow tests)
```
### Test Reports
- Location: `tests/__reports__/index.html`
- Formats: JUnit XML + HTML report
### Test Categories
**[tests/README.md](../tests/README.md)** — Test structure:
- `core/` — Core functionality (index, search, routes)
- `metadata/` — Metadata extraction (ExifTool, FFprobe, geninfo)
- `features/` — Feature tests (collections, batch ZIP, viewer)
- `database/` — Database schema and migrations
- `security/` — Security and configuration tests
- `regressions/` — Regression tests for bug fixes
### Code Quality
```bash
mypy mjr_am_backend/ # Type checking
flake8 mjr_am_backend/ # Linting
radon cc mjr_am_backend/ # Complexity
bandit -r mjr_am_backend/ # Security audit
pip-audit # Dependency audit
```
---
## 📖 API Reference
**[API_REFERENCE.md](API_REFERENCE.md)** — Complete API documentation:
### Core Endpoints
| Method | Path | Purpose |
|--------|------|---------|
| `GET` | `/mjr/am/health` | Health summary |
| `GET` | `/mjr/am/health/counters` | Indexed counters |
| `GET` | `/mjr/am/health/db` | DB diagnostics |
| `GET` | `/mjr/am/config` | Runtime config |
| `GET` | `/mjr/am/version` | Version info |
| `GET` | `/mjr/am/tools/status` | Tool availability |
### Search & Assets
| Method | Path | Purpose |
|--------|------|---------|
| `GET` | `/mjr/am/search` | Search with filters |
| `GET` | `/mjr/am/asset/{id}` | Asset details |
| `POST` | `/mjr/am/scan` | Scan scope/root |
| `POST` | `/mjr/am/index/reset` | Reset index |
| `POST` | `/mjr/am/assets/delete` | Bulk delete |
### Operations
| Method | Path | Purpose |
|--------|------|---------|
| `POST` | `/mjr/am/asset/rating` | Update rating |
| `POST` | `/mjr/am/asset/tags` | Update tags |
| `POST` | `/mjr/am/asset/rename` | Rename file |
| `POST` | `/mjr/am/open-in-folder` | Open location |
| `POST` | `/mjr/am/stage-to-input` | Stage to input |
### Collections & Custom
| Method | Path | Purpose |
|--------|------|---------|
| `GET` | `/mjr/am/collections` | List collections |
| `POST` | `/mjr/am/collections/*` | Manage collections |
| `GET` | `/mjr/am/custom-roots` | List custom roots |
| `POST` | `/mjr/am/custom-roots` | Manage custom roots |
### Utilities
| Method | Path | Purpose |
|--------|------|---------|
| `GET` | `/mjr/am/download` | Download asset |
| `POST` | `/mjr/am/batch-zip` | Create batch ZIP |
| `GET` | `/mjr/am/date-histogram` | Calendar histogram |
| `POST` | `/mjr/am/db/optimize` | Optimize DB |
| `POST` | `/mjr/am/db/force-delete` | Force-delete DB |
---
## 🎯 Workflow-Specific Guides
### Modern Workflow Support
The metadata parser now understands:
- **Flux** (Advanced/GGUF variants)
- **WanVideo/Kijai** workflows
- **HunyuanVideo/Kijai** workflows
- **Qwen** (Edit workflows)
- **Marigold** (Depth estimation)
- **AC-Step** (Ace Step custom node)
- **Stable Audio** and TTS workflows
### Video & Audio
- Video metadata extraction via FFprobe
- Audio file staging for TTS workflows
- Timeline controls and in/out points
- Frame extraction and export
---
## 🌍 Internationalization
Supported languages (UI):
- 🇺🇸 English
- 🇨🇳 Chinese
- 🇰🇷 Korean
- 🇷🇺 Russian
- 🇮🇳 Hindi
- 🇪🇸 Spanish
- 🇫🇷 French
Language selection via ComfyUI settings.
---
## 🐛 Troubleshooting Quick Reference
### Common Issues
| Issue | Solution | Reference |
|-------|----------|-----------|
| Extension not appearing | Check console, reinstall dependencies | [INSTALLATION.md](INSTALLATION.md#troubleshooting) |
| Database corrupted | Use Delete DB button | [DB_MAINTENANCE.md](DB_MAINTENANCE.md) |
| External tools not found | Install ExifTool/FFprobe | [INSTALLATION.md](INSTALLATION.md#optional-dependencies) |
| Slow performance | Reduce page size, exclude large dirs | [SEARCH_FILTERING.md](SEARCH_FILTERING.md#performance) |
| Search not working | Trigger scan (Ctrl+S) | [SEARCH_FILTERING.md](SEARCH_FILTERING.md#troubleshooting) |
| Drag & drop fails | Check browser support | [DRAG_DROP.md](DRAG_DROP.md#troubleshooting) |
| API access denied | Configure API token | [SECURITY_ENV_VARS.md](SECURITY_ENV_VARS.md#api-security) |
### Diagnostic Commands
```bash
# Verify tools
exiftool -ver
ffprobe -version
# Check dependencies
pip list | grep -E "aiohttp|aiosqlite|pillow"
# Run tests
python -m pytest tests/ -q
```
---
## 📦 Compatibility
### System Requirements
- **ComfyUI**: ≥ 0.13.0
- **Python**: 3.10, 3.11, 3.12 (3.13 compatible)
- **Operating Systems**:
- Windows 10/11
- macOS 10.15+
- Linux (Ubuntu 22.04+, Fedora, Debian)
- **Browsers**: Modern browsers with ES2020+ support
### Optional Dependencies
- **ExifTool**: Metadata extraction (images, documents)
- **FFprobe**: Video/audio metadata extraction
- **tkinter**: Native folder browser (included in standard Python)
---
## 🔗 External Resources
### Official Links
- **GitHub Repository**: [Majoor Assets Manager](https://github.com/MajoorWaldi/ComfyUI-Majoor-AssetsManager)
- **ComfyUI Manager**: [Extension Listing](https://github.com/ltdrdata/ComfyUI-Manager)
- **Issue Tracker**: [Report Bugs](https://github.com/MajoorWaldi/ComfyUI-Majoor-AssetsManager/issues)
- **Discussions**: [Community Forum](https://github.com/MajoorWaldi/ComfyUI-Majoor-AssetsManager/discussions)
### Support the Developer
- **Ko-fi**: [Buy a White Monster Drink](https://ko-fi.com/majoorwaldi)
### ComfyUI Ecosystem
- **ComfyUI**: [Official Repository](https://github.com/comfyanonymous/ComfyUI)
- **ComfyUI Manager**: [Manager Repository](https://github.com/ltdrdata/ComfyUI-Manager)
- **ComfyUI Custom Nodes**: [Node Directory](https://comfyworkflows.com/)
---
## 📝 Documentation Maintenance
### Updating Documentation
When adding new features or changing behavior:
1. Update relevant feature guides
2. Update API reference if endpoints change
3. Update changelog with version and date
4. Update this index if new documents are added
5. Cross-reference between documents
### Documentation Standards
- Use clear, concise language
- Include code examples where applicable
- Provide troubleshooting sections
- Link to related documents
- Keep version information current
---
## 📋 Checklist for Users
### First-Time Setup
- [ ] Install extension via ComfyUI Manager
- [ ] Install ExifTool and FFprobe (optional but recommended)
- [ ] Restart ComfyUI
- [ ] Open Assets Manager tab
- [ ] Trigger initial scan (Ctrl+S)
- [ ] Browse outputs and test search
### Power User Setup
- [ ] Configure environment variables for tuning
- [ ] Set up API token for remote access
- [ ] Create custom roots for additional directories
- [ ] Set up ratings and tags system
- [ ] Create collections for frequently used assets
- [ ] Learn keyboard shortcuts for efficiency
### Development Setup
- [ ] Clone repository to custom_nodes
- [ ] Install dev dependencies (`pip install -r requirements.txt`)
- [ ] Run test suite (`run_tests.bat`)
- [ ] Review architecture decision records (ADR)
- [ ] Set up pre-commit hooks
---
*Documentation Index Version: 2.0*
*Last Updated: February 28, 2026*
*Maintained by: MajoorWaldi*
Reference in New Issue View Git Blame Copy Permalink