Feature: Download Queue, Hash Search & Enhanced UX

[slahiri]

Feature Request: Download Queue, Hash Search & Enhanced UX

Source

Inspired by hayden-fr/ComfyUI-Model-Manager

Overview

Enhance download management with a robust queue system, hash-based model discovery, and improved user experience through real-time updates and rich metadata.

---

1. Download Queue with Pause/Resume

Description

Implement a task-based download queue that supports pausing, resuming, and persisting state across restarts.

Features

• Persistent queue survives ComfyUI restarts
• Resume partial downloads with HTTP Range headers
• Queue multiple downloads, process sequentially
• Cancel/remove tasks from queue
• Task states: pending, downloading, paused, completed, error

Data Model

• task_id: Unique identifier
• filename: Target filename
• url: Download URL
• model_type: checkpoints, loras, etc.
• status: Current state
• downloaded_bytes / total_bytes: Progress tracking
• error: Error message if failed

---

2. Hash-based Model Search

Description

Calculate SHA256 hash of local models to find their source on CivitAI, enabling auto-discovery of metadata, previews, and trigger words.

API Endpoint

GET https://civitai.com/api/v1/model-versions/by-hash/{sha256_hash}

Use Cases

• "Scan Models" button to find sources for existing models
• Auto-populate missing previews and descriptions
• Link local models to their CivitAI pages
• Detect if model already exists before downloading

Returns

• model_id, version_id
• name, base_model
• trigger_words
• preview images
• model_page URL

---

3. Model Description Files

Description

Save rich metadata alongside models as Markdown files with YAML frontmatter.

Format

---
website: CivitAI
modelPage: https://civitai.com/models/12345
author: username
baseModel: SDXL 1.0
triggerWords:
  - word1
  - word2
hashes:
  SHA256: abc123...
---

# Trigger Words

word1, word2

# Description

Model description here...

Features

• YAML frontmatter for structured metadata
• Trigger words section for easy reference
• Model description and notes
• Parseable by other tools

---

4. Video Preview Support

Description

Support video previews (.mp4, .webm) in addition to images, with proper content-type handling.

Priority Order

1. .webm (animated, small size)
2. .mp4 (wide compatibility)
3. .webp (animated images)
4. .png, .jpg (static images)

Naming Convention

• model_name.mp4 - Direct match
• model_name.preview.webm - Preview variant

Benefits

• Animated previews for models
• Better visual representation
• Consistent with CivitAIs video previews

---

5. Secure API Key Storage

Description

Store API keys securely using encryption or obfuscation instead of plain text settings.

Features

• Keys stored in binary pickle format (not plain JSON)
• Masked display in UI: hf_a****xyz1
• Base64 encoding during transmission
• Separate from ComfyUI settings (not in settings.json)
• File: private.key in extension folder

---

6. Progress Callbacks via WebSocket

Description

Real-time download progress updates using ComfyUIs WebSocket infrastructure.

Event: download_progress

{
  "taskId": "abc123",
  "status": "downloading",
  "progress": 45.5,
  "downloadedBytes": 5368709120,
  "totalBytes": 11811160064,
  "bytesPerSecond": 52428800,
  "error": null
}

Features

• Real-time progress bars in UI
• Download speed display (bytes/sec)
• Status updates: pending -> downloading -> completed
• Error notifications
• Report interval: 500ms

---

Priority

High - Significantly improves download experience and model management

Implementation Order

1. Download Queue (foundation)
2. Progress Callbacks (UX)
3. Hash-based Search (discovery)
4. Model Descriptions (metadata)
5. Video Previews (enhancement)
6. Secure Key Storage (security)

Generated with Claude Code