From 0c07d6bdc7cd06db1fe32a82ebd731b37db2e66a Mon Sep 17 00:00:00 2001 From: Eric Hiss Date: Fri, 19 Dec 2025 17:44:17 -0800 Subject: [PATCH] Remove internal working docs from public repo Moved to local dev/ folder (gitignored): - All BUGFIX_*.md files - All ENHANCEMENT_*.md files - Release notes and implementation notes - docs/archive/ folder - Testing guides These are internal development notes, not needed for end users. --- BUGFIX_PONY_FORMAT.md | 223 --------- BUGFIX_TEXT_TO_IMAGE_SEED.md | 233 --------- BUGFIX_VISION_FALLBACK.md | 319 ------------ ENHANCEMENT_COMPLETE_v1.8.1.md | 170 ------- ENHANCEMENT_v1.8.1.md | 145 ------ RELEASE_NOTES_v1.8.0.md | 279 ----------- WAN22_ALIGNMENT_ANALYSIS.md | 487 ------------------ docs/ADVANCED_NODE_REDESIGN.md | 362 -------------- docs/BUGFIX_ADVANCED_NODE.md | 237 --------- docs/BUGFIX_SUMMARY.md | 121 ----- docs/BUGFIX_V161.md | 236 --------- docs/TESTING_GUIDE_V161.md | 276 ----------- docs/archive/BUGFIX_AUTO_MODE.md | 160 ------ docs/archive/FILE_CHANGES.md | 294 ----------- docs/archive/GITHUB_PUBLICATION_COMPLETE.md | 376 -------------- docs/archive/README_OLD.md | 303 ----------- docs/archive/SETUP_COMPLETE.md | 268 ---------- docs/archive/UPDATE_NOTES.md | 202 -------- docs/archive/UPDATE_NOTES_V12.md | 295 ----------- docs/archive/UPDATE_V13.md | 278 ----------- docs/archive/UPDATE_V15.md | 193 -------- docs/archive/UPDATE_V16_ERIC.md | 344 ------------- docs/archive/UPDATE_V17_ENHANCED_CONTROLS.md | 496 ------------------- v1.9.0_IMPLEMENTATION_COMPLETE.md | 304 ------------ v1.9.1_ENHANCEMENTS.md | 363 -------------- 25 files changed, 6964 deletions(-) delete mode 100644 BUGFIX_PONY_FORMAT.md delete mode 100644 BUGFIX_TEXT_TO_IMAGE_SEED.md delete mode 100644 BUGFIX_VISION_FALLBACK.md delete mode 100644 ENHANCEMENT_COMPLETE_v1.8.1.md delete mode 100644 ENHANCEMENT_v1.8.1.md delete mode 100644 RELEASE_NOTES_v1.8.0.md delete mode 100644 WAN22_ALIGNMENT_ANALYSIS.md delete mode 100644 docs/ADVANCED_NODE_REDESIGN.md delete mode 100644 docs/BUGFIX_ADVANCED_NODE.md delete mode 100644 docs/BUGFIX_SUMMARY.md delete mode 100644 docs/BUGFIX_V161.md delete mode 100644 docs/TESTING_GUIDE_V161.md delete mode 100644 docs/archive/BUGFIX_AUTO_MODE.md delete mode 100644 docs/archive/FILE_CHANGES.md delete mode 100644 docs/archive/GITHUB_PUBLICATION_COMPLETE.md delete mode 100644 docs/archive/README_OLD.md delete mode 100644 docs/archive/SETUP_COMPLETE.md delete mode 100644 docs/archive/UPDATE_NOTES.md delete mode 100644 docs/archive/UPDATE_NOTES_V12.md delete mode 100644 docs/archive/UPDATE_V13.md delete mode 100644 docs/archive/UPDATE_V15.md delete mode 100644 docs/archive/UPDATE_V16_ERIC.md delete mode 100644 docs/archive/UPDATE_V17_ENHANCED_CONTROLS.md delete mode 100644 v1.9.0_IMPLEMENTATION_COMPLETE.md delete mode 100644 v1.9.1_ENHANCEMENTS.md diff --git a/BUGFIX_PONY_FORMAT.md b/BUGFIX_PONY_FORMAT.md deleted file mode 100644 index c7712b8..0000000 --- a/BUGFIX_PONY_FORMAT.md +++ /dev/null @@ -1,223 +0,0 @@ -# Pony Diffusion Format Fix - -## Issue -Pony Diffusion prompts were being generated with **underscore-separated tags** instead of **natural language descriptions**, resulting in unreadable output like: - -``` -score_9, score_8_up, score_7_up, 1girl, long_hair, brown_hair, intense_gaze, -red_backdrop, pink_lingerie, strapless_top, briefs, floral_embroidery, -star-shaped_navel_piercing, soft_lighting, even_lighting, subtle_shadows... -``` - -This format was treating Pony like a Danbooru tagging system, which is **incorrect**. - -## Root Cause -Multiple configuration errors: - -1. **platforms.py** - Pony config had wrong instructions: - - `"prompt_style": "booru_structured"` ❌ - - `"Use danbooru tag format"` ❌ - - `"Underscores instead of spaces in tags"` ❌ - - `"max_words": 75` ❌ (way too short) - -2. **text_to_image_node.py** - System prompt told LLM to use Danbooru format: - - "Use danbooru tag format (underscores, not spaces)" ❌ - - "Character/subject descriptions in tag format" ❌ - -3. **text_to_image_node.py** - `_add_keywords()` function converted Pony keywords to underscores: - - `if platform in ["pony", "illustrious"]: formatted_kw = [kw.replace(" ", "_")]` ❌ - -## Correct Pony Format - -**Score tags with underscores** (required at start): -``` -score_9, score_8_up, score_7_up -``` - -**Then natural language comma-separated descriptions** (150-200 words): -``` -score_9, score_8_up, score_7_up, a young woman with long flowing brown hair, -intense gaze directed at camera, standing against vibrant red studio backdrop, -wearing delicate pink lingerie set with intricate floral embroidery, -strapless bralette top and matching briefs, small star-shaped navel piercing, -soft even studio lighting creates subtle shadows, deliberate confident pose, -sensual and intimate mood, professional portrait photography, shallow depth of field -``` - -## Fixes Applied - -### 1. platforms.py - Pony Configuration - -**Changed:** -```python -"pony": { - "name": "Pony Diffusion", - "description": "Versatile model - Score tags required, then natural language", - "prompt_style": "natural_detailed", # Changed from "booru_structured" - "optimal_length": "extended (~150-200 words)", # Changed from 75 - "max_words": 200, # Changed from 75 - "max_tokens": 280, # Changed from 110 - "preferences": [ - "MUST start with: score_9, score_8_up, score_7_up", - "Then use natural language comma-separated descriptions", - "NO underscores in descriptive text (only in score tags)", - "Detailed character and scene descriptions", - "Specific quality and mood descriptors", - "Clear, readable phrases not technical tags" - ], - "avoid": [ - "Underscore_formatting in descriptive text", - "Danbooru-style tags (except score tags)", - "Missing score tags at start", - "Technical tag format instead of natural language" - ] -} -``` - -### 2. text_to_image_node.py - System Prompt Instructions - -**Changed:** -```python -if "pony" in platform_name.lower(): - prompt += """ -PONY DIFFUSION FORMAT (CRITICAL): -- MUST START with exactly: score_9, score_8_up, score_7_up -- After score tags, use NATURAL LANGUAGE descriptions (NO underscores) -- Comma-separated detailed phrases -- DO NOT use danbooru tag format (no long_hair, brown_eyes, etc.) -- Use readable text: "long flowing hair", "brown eyes", "red dress" -- Aim for 150-200 words of rich descriptive detail -- Example: score_9, score_8_up, score_7_up, a young woman with long flowing hair, - intense gaze, wearing elegant red dress, soft studio lighting, professional portrait -""" -``` - -### 3. text_to_image_node.py - Keyword Formatting - -**Changed:** -```python -# Before - WRONG for Pony -if platform in ["pony", "illustrious"]: - formatted_kw = [kw.replace(" ", "_") for kw in missing_keywords] - -# After - CORRECT -if platform in ["illustrious"]: # Only Illustrious uses underscores - formatted_kw = [kw.replace(" ", "_") for kw in missing_keywords] - return f"{prompt}, {', '.join(formatted_kw)}" -else: - # Natural language (including Pony) - return f"{prompt}, {', '.join(missing_keywords)}" -``` - -## Expected Output After Fix - -### Before (WRONG): -``` -score_9, score_8_up, score_7_up, 1girl, long_hair, brown_hair, intense_gaze, -red_backdrop, pink_lingerie, strapless_top, briefs, floral_embroidery -``` - -### After (CORRECT): -``` -score_9, score_8_up, score_7_up, a young woman with long flowing brown hair cascading -over her shoulders, intense penetrating gaze directed at the camera, standing -confidently against a vibrant solid red studio backdrop that fills the frame, -wearing delicate pink lingerie set with intricate floral embroidery details, -strapless bralette top and matching briefs showing refined craftsmanship, small -star-shaped navel piercing adding subtle detail, soft even studio lighting creates -gentle shadows and highlights, deliberate confident sensual pose conveying intimacy, -professional portrait photography aesthetic, shallow depth of field with subject -in sharp focus, warm color temperature, beautiful composition with centered framing -``` - -## Prompt Length Improvement - -**Before:** ~75 words (way too short, missing details) -**After:** 150-200 words (proper descriptive detail) - -The LLM now has proper token budget (280 instead of 110) to generate rich, detailed prompts that Pony Diffusion can actually use effectively. - -## Testing Checklist - -After restarting ComfyUI: - -- [ ] Pony prompts start with `score_9, score_8_up, score_7_up` -- [ ] NO underscores in descriptive text (only in score tags) -- [ ] Natural readable phrases like "long flowing hair" not "long_hair" -- [ ] Prompts are 150-200 words (not 75) -- [ ] Detailed descriptions of character, outfit, lighting, mood -- [ ] Comma-separated format maintained -- [ ] Keywords added as natural language (not underscored) - -## Example Comparison - -### Input: -``` -woman, red background, pink lingerie -``` - -### Old Output (BROKEN): -``` -score_9, score_8_up, score_7_up, 1girl, long_hair, brown_hair, intense_gaze, -red_backdrop, pink_lingerie, strapless_top, briefs, floral_embroidery -``` -**Problems:** -- Only ~15 words after score tags -- Underscore formatting -- Reads like database tags - -### New Output (FIXED): -``` -score_9, score_8_up, score_7_up, a beautiful young woman with long flowing -brown hair cascading over her shoulders, intense and captivating gaze directed -toward the viewer, standing gracefully against a vibrant solid red studio -backdrop that dominates the entire background, wearing an elegant pink lingerie -set featuring intricate floral embroidery and delicate lace details, strapless -bralette top paired with matching briefs, small decorative star-shaped navel -piercing, soft even studio lighting creates subtle shadows and gentle highlights -across her skin, confident and sensual pose with deliberate body language, -intimate and alluring mood, professional portrait photography style, shallow -depth of field keeping the subject in sharp focus while the red background -remains smooth, warm color temperature, centered composition -``` -**Improvements:** -- 150+ words of rich detail -- Natural readable language -- Proper descriptions not tags -- Much more useful for image generation - -## Files Modified - -1. **platforms.py** - - Updated Pony platform configuration - - Changed prompt_style from "booru_structured" to "natural_detailed" - - Increased max_words from 75 to 200 - - Increased max_tokens from 110 to 280 - - Rewrote preferences and avoid lists - -2. **text_to_image_node.py** - - Fixed Pony system prompt instructions - - Updated `_add_keywords()` to exclude Pony from underscore formatting - - Pony now uses natural language like SDXL/Flux - -## Version -- Previous: v1.9.9 (seed & vision caption fixes) -- Current: v1.9.10 (Pony format fix) - -## Backward Compatibility -✅ **Compatible for correct Pony usage** -⚠️ **Breaking change for users who were expecting Danbooru tags** (but that was never correct for Pony) - -If you were using the old broken format and have workflows that depend on it, consider switching to **Illustrious XL** platform which properly uses Danbooru tag format. - -## Next Steps -1. Restart ComfyUI -2. Test Pony platform with any prompt -3. Verify output uses natural language (not underscores) -4. Check prompt length is 150-200 words -5. Confirm score tags still appear at start - ---- - -**Status:** ✅ All fixes implemented and validated -**Impact:** Major improvement - Pony prompts will now work properly diff --git a/BUGFIX_TEXT_TO_IMAGE_SEED.md b/BUGFIX_TEXT_TO_IMAGE_SEED.md deleted file mode 100644 index 70d2422..0000000 --- a/BUGFIX_TEXT_TO_IMAGE_SEED.md +++ /dev/null @@ -1,233 +0,0 @@ -# Text-to-Image Node Bug Fixes - Seed & Vision Caption - -## Date -October 28, 2025 - -## Issues Fixed - -### 1. ❌ Seed Not Showing on GUI -**Problem:** Random seed value was calculated backend-only but not displayed on the node widget or updated between runs. - -**Root Cause:** ComfyUI requires seed values to be part of the node's OUTPUT to update the GUI widget. Internal state changes don't propagate to the UI. - -**Solution:** -- Added `seed_used` as 6th output (INT type) -- Returns the actual seed value used (from `_resolve_seed_value`) -- Allows users to see which seed was used for each generation -- Seed widget will now update automatically when using random/increment/decrement modes - -**Changes:** -```python -# Before -RETURN_TYPES = ("STRING", "STRING", "STRING", "STRING") -RETURN_NAMES = ("positive_prompt", "negative_prompt", "settings_used", "status") - -# After -RETURN_TYPES = ("STRING", "STRING", "STRING", "STRING", "STRING", "INT") -RETURN_NAMES = ("positive_prompt", "negative_prompt", "settings_used", "status", "vision_caption", "seed_used") -``` - -### 2. ❌ Missing Vision Caption Output -**Problem:** Vision captions were being generated from reference images but had no output connection, so users couldn't access them. - -**Root Cause:** RETURN_TYPES only included 4 outputs, missing the vision_caption output that was requested. - -**Solution:** -- Added `vision_caption` as 5th output (STRING type) -- Formats all vision captions from reference images into a readable string: - ``` - Reference 1: [caption text] - - Reference 2: [caption text] - ``` -- Returns empty string when no vision captions are available - -**Implementation:** -```python -# Extract vision captions from reference_meta -vision_captions_list = reference_meta.get("vision_captions", []) -if vision_captions_list: - vision_caption_output = "\n\n".join( - f"Reference {i+1}: {caption}" - for i, caption in enumerate(vision_captions_list) - ) -else: - vision_caption_output = "" -``` - -### 3. ❌ Node Sometimes Passes Input Unchanged -**Problem:** Even when seed updates and vision caption is generated, sometimes the node returns the original prompt without enhancement. - -**Root Causes:** -1. **LLM Failure:** When `llm.send_prompt()` returns `success=False` or empty response -2. **Silent Fallback:** Node falls back to original `text_prompt` without clear logging -3. **Cache Confusion:** User can't tell if it's a caching issue or LLM failure - -**Solution:** -- Added explicit logging when LLM succeeds vs. fails: - ```python - if main_llm_success and raw_llm_output: - enhanced_prompt = self._parse_llm_response(raw_llm_output, target_platform) - print(f"[Text-to-Image] LLM successfully enhanced prompt (length: {len(enhanced_prompt)} chars)") - else: - enhanced_prompt = text_prompt - print(f"[Text-to-Image] ⚠️ LLM failed or returned empty response - using original prompt") - if llm_error_message: - print(f"[Text-to-Image] Error details: {llm_error_message}") - ``` - -**Diagnostic Steps for Users:** -When the output matches the input exactly: -1. **Check ComfyUI console** - Look for the warning message -2. **LLM Backend Status:** - - Is LM Studio/Ollama running? - - Is a model loaded? - - Check API endpoint (default: http://localhost:1234/v1) -3. **Node Status Output:** - - Will show "⚠️" instead of "✅" on LLM failure - - Check "Main prompt LLM: responded" vs "failed" -4. **IS_CHANGED Working:** - - Seed updates properly (now visible in `seed_used` output) - - Cache invalidation working (timestamp-based for random/increment/decrement) - -## Updated Outputs - -### Output Connections (6 total) -1. **positive_prompt** (STRING) - Enhanced prompt for image generation -2. **negative_prompt** (STRING) - Platform-specific negative prompt -3. **settings_used** (STRING) - Detailed breakdown of all settings applied -4. **status** (STRING) - Execution status with LLM/reference/seed info -5. **vision_caption** (STRING) - ⭐ NEW - All vision captions from reference images -6. **seed_used** (INT) - ⭐ NEW - Actual seed value used (visible on GUI) - -## Seed Modes Explained - -### How Seed Modes Work Now - -**Random Mode:** -- Generates new random seed each run -- `IS_CHANGED` returns `float(time.time())` → forces re-execution -- `seed_used` output shows which seed was used -- GUI widget updates automatically - -**Increment Mode:** -- Starts from input seed value -- Each run: `seed = last_seed + 1` -- Wraps to 0 at max_seed (2,147,483,647) -- Continuity preserved across runs - -**Decrement Mode:** -- Starts from input seed value -- Each run: `seed = last_seed - 1` -- Wraps to max_seed when going below 0 -- Continuity preserved across runs - -**Fixed Mode:** -- Uses exact seed value from input -- `IS_CHANGED` returns seed value → enables caching when seed unchanged -- Allows reproducible generations - -## Vision Caption Usage - -### When Vision Captions Are Generated -- Reference Image 1 provided → caption in output -- Reference Image 2 provided → caption in output -- Override captions take precedence (manual captions) -- Qwen3-VL, LM Studio, or Ollama vision backends - -### Output Format -``` -Reference 1: The image features a young woman with long, dark brown hair and a direct, intense gaze, standing against a solid, vibrant red studio backdrop... - -Reference 2: A landscape scene showing mountains at sunset with dramatic lighting... -``` - -### Use Cases -- **Pass to Text Node:** Connect `vision_caption` output to text display -- **Debug Reference Processing:** Verify what the vision model saw -- **Manual Review:** Check if caption matches your intent -- **Downstream Processing:** Use caption in other nodes - -## Testing Checklist - -After restarting ComfyUI: - -- [ ] Seed widget visible on node GUI -- [ ] Random mode: seed changes each run (check `seed_used` output) -- [ ] Increment mode: seed increases by 1 each run -- [ ] Decrement mode: seed decreases by 1 each run -- [ ] Fixed mode: seed stays constant -- [ ] Vision caption output appears when reference images provided -- [ ] Console shows success/failure messages for LLM calls -- [ ] Node status shows "✅" on success, "⚠️" on LLM failure -- [ ] Original prompt only returned when LLM fails (check console) - -## Common Issues & Solutions - -### Seed Still Not Updating -**Check:** -1. Did you restart ComfyUI? -2. Is seed_mode set to "random", "increment", or "decrement"? -3. Connect the `seed_used` output to a viewer to confirm it's changing -4. Clear browser cache (Ctrl+F5) - -### Vision Caption Empty -**Check:** -1. Did you connect reference images? -2. Is vision_backend set to "auto" or a specific backend? -3. For qwen3_vl: Is model installed locally? -4. For lm_studio/ollama: Is vision model loaded? -5. Check node status for vision backend messages - -### Prompt Still Unchanged After These Fixes -**Check Console For:** -``` -[Text-to-Image] ⚠️ LLM failed or returned empty response - using original prompt -``` - -**If You See This:** -1. LLM backend not running or not responding -2. Model not loaded in LM Studio/Ollama -3. API endpoint incorrect -4. Network/firewall blocking localhost connection - -**Verify LLM:** -```powershell -# Test LM Studio endpoint -curl http://localhost:1234/v1/models - -# Test Ollama endpoint -curl http://localhost:11434/api/tags -``` - -## Files Modified - -- `text_to_image_node.py`: - - Updated `RETURN_TYPES` to include vision_caption (STRING) and seed_used (INT) - - Updated `RETURN_NAMES` to match - - Modified `enhance_prompt()` return statements (success and error cases) - - Added logging for LLM success/failure - - Added vision caption formatting logic - -## Version -- Previous: v1.9.8 -- Current: v1.9.9 (seed & vision caption fixes) - -## Backward Compatibility -✅ **Fully backward compatible** -- Existing workflows will continue to work -- New outputs are additive (existing outputs unchanged) -- Existing connections remain valid -- Old workflows get new outputs automatically - -## Next Steps -1. Restart ComfyUI completely -2. Test all 4 seed modes -3. Test with reference images to verify vision_caption output -4. Monitor console for LLM success/failure messages -5. Report any remaining issues with console logs - ---- - -**Status:** ✅ All fixes implemented and validated -**Testing Required:** User testing in ComfyUI environment diff --git a/BUGFIX_VISION_FALLBACK.md b/BUGFIX_VISION_FALLBACK.md deleted file mode 100644 index 1faf095..0000000 --- a/BUGFIX_VISION_FALLBACK.md +++ /dev/null @@ -1,319 +0,0 @@ -# Vision Failure Fallback Fix - -## Issue -When the vision model failed to initialize or process reference images, the **entire node would fail** and return the original input prompt unchanged - even though it could still expand the text prompt without vision captions. - -### User Report -> "the node fails when it can't find the vision model and just passes out the input prompt without any modification even though it could still expand the input prompt without the vision model response. The logic is terrible. It should always do what it can not just give up." - -**100% Correct Assessment** ✅ - -## Root Cause - -### Bad Architecture (Before Fix) -``` -try: - 1. Process reference images - 2. Call vision model - 3. Build reference guidance - 4. Expand text prompt with LLM - [ALL IN ONE BIG TRY BLOCK] -except Exception: - return original_prompt ❌ GIVES UP COMPLETELY -``` - -**Problem:** Any exception anywhere in the pipeline causes complete failure, even if only vision failed. - -**Impact:** -- Vision model not installed → **No prompt expansion at all** -- Vision model crashes → **No prompt expansion at all** -- Reference processing error → **No prompt expansion at all** -- LLM works fine but vision fails → **Still returns input unchanged** - -## The Fix - -### New Architecture (Resilient) -``` -1. Process reference images - try: - Call vision model - except: - Continue with heuristic analysis ✅ - -2. Build reference guidance - try: - Generate reference instructions - except: - Continue without reference guidance ✅ - -3. Expand text prompt with LLM - (Always runs regardless of vision status) ✅ -``` - -**Result:** Vision failures are isolated and logged, but text expansion **always happens**. - -## Changes Made - -### 1. Vision Processing Isolation - -**Location:** Lines 874-920 in `text_to_image_node.py` - -**Before:** -```python -image_analyses = [] -for entry in reference_images: - analysis = self._analyze_reference_image(...) # Could raise exception - image_analyses.append(analysis) -# If ANY analysis fails, exception propagates to outer catch-all -``` - -**After:** -```python -image_analyses = [] -try: - for entry in reference_images: - analysis = self._analyze_reference_image(...) - image_analyses.append(analysis) -except Exception as vision_exc: - # Vision failed - log error but continue - error_msg = f"Vision processing failed: {str(vision_exc)}" - print(f"[Text-to-Image] ⚠️ {error_msg}") - reference_warnings.append(error_msg) - - # Create fallback analyses - if not image_analyses and reference_images: - for entry in reference_images: - fallback = { - "label": label, - "summary": f"{label}: vision analysis failed, continuing with text expansion", - "details": ["Vision model unavailable"], - "warnings": [error_msg] - } - image_analyses.append(fallback) -``` - -### 2. Reference Guidance Isolation - -**Location:** Lines 927-971 in `text_to_image_node.py` - -**Before:** -```python -directive_analyses, directive_meta = self._run_reference_directive_analysis(...) -reference_guidance, reference_notes, guidance_meta = self._build_reference_guidance(...) -reference_meta = self._merge_reference_metadata(...) -# Any failure here stops the entire process -``` - -**After:** -```python -reference_guidance = "" -reference_notes = [] -reference_meta = {} - -try: - directive_analyses, directive_meta = self._run_reference_directive_analysis(...) - reference_guidance, reference_notes, guidance_meta = self._build_reference_guidance(...) - reference_meta = self._merge_reference_metadata(...) -except Exception as ref_exc: - # Reference guidance failed - log but continue - error_msg = f"Reference guidance generation failed: {str(ref_exc)}" - print(f"[Text-to-Image] ⚠️ {error_msg}") - reference_warnings.append(error_msg) - - # Initialize empty reference data - reference_meta = { - "analysis_method": "failed", - "reference_count": len(image_analyses), - "llm_queries": 0, - "llm_successes": 0, - "warnings": [error_msg] - } - -# Always update with vision info (even if guidance failed) -reference_meta.update({ - "vision_backend_requested": vision_backend_selection, - "vision_backend_resolved": vision_backend_mode, - ... -}) -``` - -### 3. Better Vision Initialization Logging - -**Location:** Lines 840-847 in `text_to_image_node.py` - -**Before:** -```python -except Exception as exc: - vision_backend_mode = "disabled" - vision_init_warning = f"Vision backend init failed: {exc}" - vision_llm = None -``` - -**After:** -```python -except Exception as exc: - vision_backend_mode = "disabled" - vision_init_warning = f"Vision backend init failed: {exc}" - print(f"[Text-to-Image] ⚠️ Vision backend '{vision_backend_selection}' initialization failed: {exc}") - print(f"[Text-to-Image] → Continuing with text expansion only (no vision captions)") - vision_llm = None -``` - -## Behavior After Fix - -### Scenario 1: Vision Model Not Installed -**Before:** -- Node returns input prompt unchanged ❌ -- No error message explaining what happened ❌ - -**After:** -- Console logs: `⚠️ Vision backend 'qwen3_vl' initialization failed: Model not found` -- Console logs: `→ Continuing with text expansion only (no vision captions)` -- Text prompt **IS expanded** normally ✅ -- Reference image warnings shown in settings_used output ✅ -- vision_caption output is empty (as expected) ✅ - -### Scenario 2: Vision Processing Crashes -**Before:** -- Node returns input prompt unchanged ❌ -- Exception buried in catch-all ❌ - -**After:** -- Console logs: `⚠️ Vision processing failed: [error details]` -- Text prompt **IS expanded** normally ✅ -- Fallback reference analysis created ✅ -- Node continues with heuristic image analysis ✅ - -### Scenario 3: Reference Guidance Generation Fails -**Before:** -- Node returns input prompt unchanged ❌ - -**After:** -- Console logs: `⚠️ Reference guidance generation failed: [error details]` -- Text prompt **IS expanded** without reference guidance ✅ -- reference_meta contains error information ✅ -- Main LLM still processes the text prompt ✅ - -### Scenario 4: Everything Works -**Before & After:** -- Vision captions generated ✅ -- Reference guidance created ✅ -- Text prompt expanded with vision context ✅ -- No difference in behavior ✅ - -## Console Output Examples - -### Vision Init Failure -``` -[Text-to-Image] ⚠️ Vision backend 'qwen3_vl' initialization failed: No module named 'transformers' -[Text-to-Image] → Continuing with text expansion only (no vision captions) -[Text-to-Image] LLM successfully enhanced prompt (length: 847 chars) -``` - -### Vision Processing Failure -``` -[Text-to-Image] ⚠️ Vision processing failed: CUDA out of memory -[Text-to-Image] LLM successfully enhanced prompt (length: 723 chars) -``` - -### Reference Guidance Failure -``` -[Text-to-Image] ⚠️ Reference guidance generation failed: LLM timeout -[Text-to-Image] LLM successfully enhanced prompt (length: 691 chars) -``` - -## What Users Will See - -### Node Status Output -``` -✅ Enhanced for Flux | Main prompt LLM: responded | Reference LLM: 0/0 responses | -References sent: 1 | Reference warnings: Vision processing failed: Model not found | -Seed: 12345 (random) | File: not saved -``` - -### Settings Used Output -``` -REFERENCE IMAGE NOTES: - • Guardrail: Blend reference guidance... - • Reference 1 (None): vision analysis failed, continuing with text expansion - • Vision processing failed: Model not found -``` - -### Vision Caption Output -``` -[Empty string - no vision captions available] -``` - -## Testing Checklist - -After restarting ComfyUI: - -- [ ] **Vision model not installed** → Text prompt still expands -- [ ] **Vision model crashes** → Text prompt still expands -- [ ] **Reference image provided but vision fails** → Prompt expands without vision context -- [ ] **Console shows warnings** when vision fails -- [ ] **Console confirms** text expansion succeeded -- [ ] **Node status** shows warnings but success (✅ not ❌) -- [ ] **Vision caption output** is empty when vision fails -- [ ] **Everything works** when vision model is available - -## Error Message Locations - -Users will see vision failure information in: - -1. **ComfyUI Console:** - - `⚠️ Vision backend initialization failed` - - `⚠️ Vision processing failed` - - `⚠️ Reference guidance generation failed` - -2. **Node Status Output:** - - `Reference warnings: Vision processing failed: [details]` - -3. **Settings Used Output:** - - Full warning details in "REFERENCE IMAGE NOTES" section - -4. **Vision Caption Output:** - - Empty string (no captions available) - -## Files Modified - -- `text_to_image_node.py`: - - Wrapped vision processing in isolated try/except (lines 874-920) - - Wrapped reference guidance in isolated try/except (lines 927-971) - - Added better logging for vision init failures (lines 840-847) - - All failures now log and continue instead of aborting - -## Version -- Previous: v1.9.10 (Pony format fix) -- Current: v1.9.11 (Vision failure fallback) - -## Backward Compatibility -✅ **Fully backward compatible** -- Existing workflows work exactly the same when vision succeeds -- New behavior only applies when vision fails (previously broken anyway) -- No API changes, no parameter changes - -## Impact - -### Before This Fix -- **Success rate when vision unavailable:** 0% (always fails) -- **User experience:** Frustrating - node appears broken -- **Error visibility:** Poor - buried in exceptions - -### After This Fix -- **Success rate when vision unavailable:** 100% (text expansion works) -- **User experience:** Node is resilient - always does what it can -- **Error visibility:** Excellent - clear console warnings - -## Philosophy Change - -**Old approach:** "If anything fails, give up completely" ❌ - -**New approach:** "Do as much as possible, log what failed, continue gracefully" ✅ - -This is how production software should behave - **graceful degradation** instead of catastrophic failure. - ---- - -**Status:** ✅ All fixes implemented and validated -**Testing:** Ready for user testing with missing/broken vision models diff --git a/ENHANCEMENT_COMPLETE_v1.8.1.md b/ENHANCEMENT_COMPLETE_v1.8.1.md deleted file mode 100644 index 4f07a33..0000000 --- a/ENHANCEMENT_COMPLETE_v1.8.1.md +++ /dev/null @@ -1,170 +0,0 @@ -# ✅ Enhancement v1.8.1 - COMPLETE - -## What Was Done - -Successfully enhanced the Advanced Prompt Expander Node with expanded creative controls and better organization! - ---- - -## 🎯 Changes Summary - -### 1. New `creative_randomness` Parameter ⭐ -- **Type**: Float slider (0.0 - 1.0) -- **Default**: 0.5 -- **Position**: Right after `detail_level` (logically grouped) -- **Purpose**: Fine-tune how creative vs. literal the LLM should be - -### 2. New `art_style` Parameter ⭐ -- **26 options** including famous artists and movements -- **Categories**: - - Classic: Picasso, Van Gogh, Monet, Dali, Rembrandt, Caravaggio - - Modern: Banksy, Warhol, Rockwell, Hopper - - Studios: Ghibli, Burton, Anderson, Pixar - - Movements: Renaissance, Baroque, Impressionist, Surrealist, Cubist, Pop Art - -### 3. New `scene_detail` Parameter ⭐ -- **9 options** controlling scene complexity -- Range: simple → minimalist → clean → detailed → intricate → cluttered → maximalist -- Separate from prompt `detail_level` - -### 4. Expanded `light_source` Menu -- **Before**: 10 options -- **After**: 20 options (+100%) -- **Added**: ambient, reflected, softbox, camera flash, neon lights, striplight, computer screen glow, flashlight, candlelight, spotlight - -### 5. Enhanced `lighting_quality` (renamed from `lighting_type`) -- **Before**: 13 options -- **After**: 18 options (+38%) -- **Added**: spotlight effect, dappled, cinematic, diffused, dramatic lighting - ---- - -## 📊 Statistics - -- **Total Parameters**: 32 (maintained, but 4 new + 1 renamed) -- **Total Menu Options Added**: ~34 new options across all menus -- **Code Changes**: - - Function signature updated - - `_gather_aesthetic_controls()` method updated - - All backward compatible - ---- - -## ✅ Quality Checks - -- ✅ No syntax errors detected -- ✅ All parameters properly integrated -- ✅ Function signatures updated correctly -- ✅ Aesthetic controls gathering updated -- ✅ Backward compatible with existing workflows -- ✅ Test script validates all changes -- ✅ Documentation created (3 new docs) - ---- - -## 📚 Documentation Created - -1. **ENHANCEMENT_v1.8.1.md** - Detailed technical documentation -2. **QUICK_REF_v1.8.1.md** - Quick reference with examples -3. **CHANGELOG.md** - Updated with v1.8.1 entry -4. **test_enhancements.py** - Validation script - ---- - -## 🚀 Example Use Cases - -### Cyberpunk Scene -``` -art_style: none -light_source: neon lights -lighting_quality: cinematic lighting -scene_detail: intricate detail -color_tone: saturated colors -``` - -### Van Gogh Landscape -``` -art_style: Van Gogh style -light_source: sunny lighting -lighting_quality: soft lighting -scene_detail: detailed scene -color_tone: saturated colors -``` - -### Film Noir Portrait -``` -preset: noir -light_source: practical lighting -lighting_quality: dramatic lighting -scene_detail: clean scene -color_tone: black and white -``` - -### Studio Ghibli Animation -``` -art_style: Studio Ghibli style -light_source: dappled lighting -lighting_quality: soft lighting -scene_detail: detailed scene -visual_style: 2D anime style -``` - ---- - -## 🎨 UI Organization (Top to Bottom) - -1. Core Inputs (5) - basic_prompt, operation_mode, preset, detail_level, **creative_randomness** -2. Lighting (3) - **light_source**, **lighting_quality**, time_of_day -3. Camera (5) - shot_size, composition, lens, angle, movement -4. Style (5) - color_tone, **art_style**, **scene_detail**, visual_style, visual_effect -5. Character (1) - character_emotion -6. LLM Config (4) -7. Keywords (2) -8. Output (3) -9. Optional (1) - reference_image - ---- - -## 🔄 Next Steps - -### To Test: -1. Restart ComfyUI to load updated node -2. Add Advanced Prompt Expander node to workflow -3. Test new parameters: - - Adjust `creative_randomness` slider - - Select different `art_style` options - - Try `scene_detail` variations - - Experiment with new lighting options - -### To Commit (Optional): -```bash -git add prompt_expander_node_advanced.py -git add ENHANCEMENT_v1.8.1.md QUICK_REF_v1.8.1.md -git add CHANGELOG.md -git commit -m "v1.8.1: Expanded creative controls - art_style, scene_detail, creative_randomness, enhanced lighting" -git push origin main -``` - ---- - -## 📝 Notes - -- **Backward Compatible**: Existing workflows will work without changes -- **New defaults**: All new params default to "auto" or 0.5 -- **No breaking changes**: Parameter rename is internal only -- **Models will recognize**: Famous artist names trigger learned style associations -- **Creative Control**: Users now have fine-grained control over every aspect - ---- - -## 🎉 Summary - -You now have a much more powerful Advanced Prompt Expander with: -- 📊 4 new major controls -- 🎨 34+ new menu options -- 🖌️ Famous artist styles -- 💡 Professional lighting setups -- 🎭 Scene complexity control -- 🎲 Creativity adjustment - -**Status**: ✅ READY TO USE! diff --git a/ENHANCEMENT_v1.8.1.md b/ENHANCEMENT_v1.8.1.md deleted file mode 100644 index 73a7422..0000000 --- a/ENHANCEMENT_v1.8.1.md +++ /dev/null @@ -1,145 +0,0 @@ -# Enhancement v1.8.1: Expanded Creative Controls - -## Date: October 24, 2025 - -## Summary -Enhanced the Advanced Prompt Expander node with significantly more creative options and better UI organization. - -## Changes Made - -### 1. New Parameter: `creative_randomness` -- **Type**: Float slider (0.0 to 1.0) -- **Default**: 0.5 -- **Location**: Positioned right after `detail_level` for logical grouping -- **Purpose**: Controls how much creative liberty the LLM takes when expanding prompts - - `0.0` = Stay very close to original prompt - - `0.5` = Balanced expansion - - `1.0` = Maximum creative interpretation - -### 2. Expanded `light_source` Menu -**Added 10 new lighting source options:** -- ambient lighting -- reflected lighting -- softbox lighting -- camera flash -- neon lights -- striplight -- computer screen glow -- flashlight -- candlelight -- spotlight - -**Total options**: 20 (including auto, none, and original 8) - -### 3. Renamed & Expanded `lighting_type` → `lighting_quality` -**Added 5 new lighting quality options:** -- spotlight effect -- dappled lighting -- cinematic lighting -- diffused lighting -- dramatic lighting - -**Total options**: 18 (including auto, none, and original 11) - -### 4. New Parameter: `art_style` -**Added dropdown with 24 famous artists and art movements:** -- **Individual Artists**: Picasso, Van Gogh, Monet, Salvador Dali, Banksy, Andy Warhol, Rembrandt, Caravaggio, Norman Rockwell, Edward Hopper -- **Studio/Director Styles**: Studio Ghibli, Tim Burton, Wes Anderson, Pixar -- **Art Movements**: Renaissance, Baroque, Art Nouveau, Expressionist, Impressionist, Surrealist, Cubist, Pop Art - -Models will recognize these styles and apply distinctive visual characteristics. - -### 5. New Parameter: `scene_detail` -**Controls the level of detail and complexity in the scene:** -- simple scene -- clean scene -- detailed scene -- cluttered scene -- intricate detail -- minimalist -- maximalist - -**Purpose**: Gives users control over composition complexity separate from prompt detail level. - -## Technical Changes - -### Function Signature Updates -- Added `creative_randomness: float` parameter -- Renamed `lighting_type` → `lighting_quality` -- Added `art_style: str` parameter -- Added `scene_detail: str` parameter - -### Updated Methods -- `expand_prompt()`: Updated signature and parameter passing -- `_gather_aesthetic_controls()`: Now includes `art_style` and `scene_detail` -- All aesthetic controls properly collected and passed to expansion engine - -## UI Organization Improvements - -### Parameter Order (Top to Bottom): -1. `basic_prompt` - Core input -2. `operation_mode` - How to process the prompt -3. `preset` - Style preset -4. `detail_level` - Output verbosity -5. **`creative_randomness`** ⭐ NEW - Positioned logically after detail controls -6. Lighting controls (source, quality, time_of_day) -7. Camera controls (shot_size, composition, lens, angle, movement) -8. Style controls (color_tone, **art_style** ⭐, **scene_detail** ⭐, visual_style, visual_effect) -9. Character emotion -10. LLM configuration -11. Keywords -12. Output options - -## Benefits - -### For Users: -- **More Creative Control**: Fine-tune how adventurous the LLM should be -- **Richer Lighting Options**: Professional lighting setups (softbox, dappled, etc.) -- **Artistic Styles**: Apply famous artist aesthetics recognized by AI models -- **Scene Complexity**: Control clutter vs. minimalism independently -- **Better Organization**: `creative_randomness` positioned where users expect it - -### For Prompt Quality: -- Artist names trigger model's learned associations with distinctive styles -- Specific lighting terms (dappled, softbox) produce more precise results -- Scene detail control prevents over/under-detailing -- Creative randomness allows balancing consistency vs. variation - -## Backward Compatibility -✅ **Fully backward compatible** -- All existing parameters retained -- New parameters have sensible defaults (`auto` for dropdowns, `0.5` for creative_randomness) -- Old workflows will continue to work without modification -- `lighting_type` internally renamed to `lighting_quality` (parameter name updated) - -## Testing Recommendations - -1. **Test creative_randomness range**: - - Try 0.0, 0.5, 1.0 with same prompt to see variation - -2. **Test new lighting sources**: - - "softbox lighting" for studio look - - "neon lights" for cyberpunk scenes - - "dappled lighting" for forest scenes - -3. **Test art_style**: - - "Van Gogh style" should add swirling, expressive brushwork - - "Wes Anderson style" should add symmetrical, pastel compositions - - "Studio Ghibli style" should add whimsical, hand-drawn anime aesthetics - -4. **Test scene_detail**: - - "minimalist" vs "intricate detail" with same subject - - "cluttered scene" for busy environments - -## Future Enhancement Ideas -- Add more contemporary artists (Zdzisław Beksiński, HR Giger, etc.) -- Add photography-specific styles (street photography, documentary, fashion) -- Consider adding time period styles (1920s, 1950s, 1980s, futuristic) -- Add weather conditions (foggy, rainy, snowy) as separate control - -## Files Modified -- `prompt_expander_node_advanced.py` - All changes - -## Version -- Previous: v1.8.0 -- Current: v1.8.1 (enhancement) diff --git a/RELEASE_NOTES_v1.8.0.md b/RELEASE_NOTES_v1.8.0.md deleted file mode 100644 index a584b5a..0000000 --- a/RELEASE_NOTES_v1.8.0.md +++ /dev/null @@ -1,279 +0,0 @@ -# Release Notes - v1.8.0 - -**Release Date:** October 24, 2025 - ---- - -## 🎉 Major Release: Advanced Node Redesign + Syntax Fixes - -This release includes a **complete redesign** of the Advanced Prompt Expander Node and critical syntax preservation fixes for all video nodes. - ---- - -## ⭐ Highlights - -### 1. Advanced Node Completely Redesigned - -The Advanced Prompt Expander Node has been rebuilt from the ground up to address three critical usability issues: - -**✅ Operation Modes** - Finally, you can modify existing prompts! -- `expand_from_idea` - Original expansion behavior -- `refine_existing` - Polish and improve existing prompts -- `modify_style` - Change aesthetic while keeping subject -- `add_details` - Add descriptive richness - -**✅ Clear Detail Levels** - No more confusing tiers! -- Renamed from "basic/enhanced/advanced/cinematic" to "concise/moderate/detailed/exhaustive" -- Added tooltips explaining each level -- Removed confusing "auto" mode -- Word counts clearly shown in tooltips - -**✅ Image Input Support** - Image-to-video actually works! -- Optional `reference_image` input -- Qwen3-VL vision analysis integration -- Automatic mode detection (text vs image-to-video) -- Status shows when image is being used - -### 2. Syntax Preservation for All Video Nodes - -Both video nodes now properly preserve special syntax: - -**Emphasis Syntax** - Control weights like Stable Diffusion -``` -(keyword:1.5) # Increase importance 1.5x -(keyword:0.5) # Decrease importance 0.5x -``` - -**Alternation Syntax** - Random selection for variety -``` -{cat|dog|rabbit} # Picks one randomly -{red|blue|green} dress # Random color -``` - ---- - -## 🔧 What Changed - -### Modified Files (Core Functionality) - -**Advanced Node** -- `prompt_expander_node_advanced.py` - Complete redesign - - Added operation modes - - Renamed tiers to detail levels - - Added optional image input - - Added Qwen3-VL integration - - Added `_apply_operation_mode()` method - - Added `_process_reference_image()` method - - Updated metadata and status messages - -**Basic Video Node** -- `prompt_expander_node.py` - Syntax preservation - - Added `_process_alternations()` method - - Added `_preserve_emphasis_syntax()` method - - Added `_restore_emphasis_syntax()` method - -**Engine Updates** -- `expansion_engine.py` - Backward compatibility - - Added tier name mapping (concise→basic, etc.) - - Supports both old and new naming - - Improved tier detection logic - -**Vision Backend** -- `qwen3_vl_backend.py` - NEW FILE - - Qwen3-VL integration for image analysis - - Support for multiple Qwen3-VL models - - Quantization options (4bit, 8bit) - -### Documentation Updates - -**New Documentation** -- `README.md` - Completely rewritten for clarity -- `docs/ADVANCED_NODE_REDESIGN.md` - Complete redesign details -- `docs/BUGFIX_ADVANCED_NODE.md` - Syntax preservation technical docs -- `docs/BUGFIX_SUMMARY.md` - Quick reference for all fixes -- `VISION_BACKEND_GUIDE.md` - Qwen3-VL setup guide -- `caption-instructions.md` - Vision backend usage - -**Updated Documentation** -- `CHANGELOG.md` - v1.8.0 entry added -- `docs/CONFIGURATION.md` - Updated for new parameters -- `docs/IMG2IMG_GUIDE.md` - Minor updates -- `docs/QUICKSTART.md` - Updated for v1.8 - -**Archived Documentation** (moved to `docs/archive/`) -- Old README -- UPDATE_NOTES.md (v1.0-1.1) -- UPDATE_NOTES_V12.md -- UPDATE_V13.md -- UPDATE_V15.md -- UPDATE_V16_ERIC.md -- UPDATE_V17_ENHANCED_CONTROLS.md (kept in main docs too) -- FILE_CHANGES.md -- SETUP_COMPLETE.md -- BUGFIX_AUTO_MODE.md -- GITHUB_PUBLICATION_COMPLETE.md - -### Support Files - -- `requirements.txt` - Added vision dependencies (optional) -- `.gitignore` - Already properly configured - ---- - -## 📦 Installation - -### For New Users - -```bash -cd ComfyUI/custom_nodes/ -git clone https://github.com/EricRollei/Local_LLM_Prompt_Enhancer.git video_prompter -cd video_prompter -pip install -r requirements.txt -``` - -### For Existing Users - -```bash -cd ComfyUI/custom_nodes/video_prompter -git pull -pip install -r requirements.txt --upgrade -``` - -Restart ComfyUI after updating. - -### Optional: Vision Support - -For image analysis features: - -```bash -pip install transformers>=4.42.0 accelerate>=0.30.0 huggingface_hub>=0.23.0 bitsandbytes>=0.43.0 -``` - ---- - -## 🚀 Migration Guide - -### Existing Workflows - -**Old Advanced Node Configuration:** -``` -expansion_tier: "advanced" -mode: "text-to-video" -basic_prompt: "your prompt here" -``` - -**New Equivalent:** -``` -detail_level: "detailed" -operation_mode: "expand_from_idea" -basic_prompt: "your prompt here" -reference_image: (empty/optional) -``` - -### Tier Name Mapping - -| Old Name | New Name | Still Works? | -|----------|----------|--------------| -| basic | concise | ✅ Yes (internally mapped) | -| enhanced | moderate | ✅ Yes (internally mapped) | -| advanced | detailed | ✅ Yes (internally mapped) | -| cinematic | exhaustive | ✅ Yes (internally mapped) | -| auto | (removed) | ❌ Choose explicitly now | - -### Mode Parameter Removed - -The manual "mode" dropdown is gone. Mode is now auto-detected: -- **No image** = text-to-video mode -- **With image** = image-to-video mode - ---- - -## 💡 New Workflows Enabled - -### 1. Refine Existing Prompt -``` -Node: Video Prompt Expander (Advanced) -Input: [Your existing 300-word prompt] -Operation: refine_existing -Detail: detailed -Result: Polished version with better flow -``` - -### 2. Change Style of Existing Prompt -``` -Node: Video Prompt Expander (Advanced) -Input: [Your existing prompt about a detective scene] -Operation: modify_style -Preset: noir (changed from cinematic) -Detail: detailed -Result: Same detective scene, now in noir style -``` - -### 3. Image-to-Video with Context -``` -Node: Video Prompt Expander (Advanced) -Reference Image: [Your reference image] -Input: "Make the subject move towards the camera dramatically" -Operation: expand_from_idea -Detail: detailed -Result: Detailed video prompt incorporating image analysis + your direction -``` - -### 4. Add More Detail to Good Prompt -``` -Node: Video Prompt Expander (Advanced) -Input: [Your working prompt that's a bit sparse] -Operation: add_details -Detail: exhaustive -Result: Same prompt but with atmospheric details, textures, emotions added -``` - ---- - -## 🐛 Known Issues - -None currently reported. - ---- - -## 🔜 Future Plans - -Possible future enhancements: -- Support for video input (Qwen3-VL can handle it) -- Multiple reference images -- Image directive modes (like text_to_image_node) -- Batch processing with different operation modes per prompt -- More vision backends - ---- - -## 🙏 Credits - -Special thanks to: -- Users who reported the confusing tier system -- Users who requested the ability to modify existing prompts -- Beta testers who helped validate the redesign -- The ComfyUI community for continued support - ---- - -## 📝 Full Changelog - -See [CHANGELOG.md](CHANGELOG.md) for complete version history. - ---- - -## 📚 Documentation - -- [README.md](README.md) - Main documentation -- [QUICKSTART.md](docs/QUICKSTART.md) - Get started quickly -- [ADVANCED_NODE_REDESIGN.md](docs/ADVANCED_NODE_REDESIGN.md) - Complete redesign details -- [VISION_BACKEND_GUIDE.md](VISION_BACKEND_GUIDE.md) - Image analysis setup -- [BUGFIX_SUMMARY.md](docs/BUGFIX_SUMMARY.md) - Quick reference - ---- - -**Version:** 1.8.0 -**Release Type:** Major Update -**Breaking Changes:** None (fully backward compatible) -**Recommended Action:** Update and restart ComfyUI diff --git a/WAN22_ALIGNMENT_ANALYSIS.md b/WAN22_ALIGNMENT_ANALYSIS.md deleted file mode 100644 index 73ba8ff..0000000 --- a/WAN22_ALIGNMENT_ANALYSIS.md +++ /dev/null @@ -1,487 +0,0 @@ -# Wan 2.2 Alignment Analysis & Recommendations - -## Date: October 24, 2025 - -## Executive Summary - -After reviewing the comprehensive Wan 2.2 Prompt Design Guide and Director System Prompt, I've identified **significant opportunities** to improve our video prompt generation to better align with Wan 2.2's capabilities. - -**Current Status**: 🟡 PARTIALLY ALIGNED -**Recommendation**: 🔧 MAJOR ENHANCEMENT NEEDED - ---- - -## Key Findings - -### ✅ What We're Doing Right - -1. **Camera Movement Vocabulary** - Our menus include most Wan 2.2-compatible terms: - - ✅ "camera pushes in," "camera pulls back" - - ✅ "camera pans right/left," "camera tilts up/down" - - ✅ "static shot," "tracking shot," "arc shot" - - ✅ "handheld camera," "dolly in/out" - -2. **Shot Size Control** - We have proper framing options: - - ✅ extreme close-up, close-up, medium shot, wide shot, etc. - -3. **Lighting & Time of Day** - Comprehensive options aligned with Wan guide - -4. **Aesthetic Controls** - Advanced node has granular control over cinematography - -### ❌ Critical Gaps - -#### 1. **No Shot Structure / Temporal Progression** 🚨 CRITICAL -**Wan 2.2 Requirement:** -- Prompts should be structured as Shot 1 → Shot 2 → Shot 3 (storyboard style) -- OR as 0-2s → 2-4s → 4-6s (continuous timed beats) -- Must include "Final wide reveal" or "Final shot" ending cue - -**Our Current Implementation:** -- Generates ONE CONTINUOUS PARAGRAPH description -- No temporal structure or shot progression -- No explicit ending instruction -- LLM instructions say: "Write as ONE continuous paragraph describing the scene" - -**Impact:** HIGH - Wan 2.2 expects temporal structure for best results - ---- - -#### 2. **Missing Parallax & Atmospheric Motion Cues** 🚨 CRITICAL -**Wan 2.2 Requirement:** -- Explicitly describe foreground/background depth -- Add atmospheric motion: "rain streaks past lens," "steam drifts," "mist rises," "fabric ripples," "particles drift in air" -- These create parallax and prevent static-looking output - -**Our Current Implementation:** -- Generic instruction to "describe textures, materials, motion characteristics" -- No specific requirement for atmospheric/environmental motion -- No explicit parallax language - -**Impact:** HIGH - Without this, videos look flat/static even with camera movement - ---- - -#### 3. **No Reference Image Mode Instructions** 🚨 CRITICAL -**Wan 2.2 Requirement:** -- When image reference is provided, MUST specify how to use it: - - "Use the provided image as exact character and costume reference..." - - "Match lighting/mood only, create new pose..." - - "Preserve face only, ignore background..." - - "Loosely base character, change outfit/setting..." - -**Our Current Implementation:** -- Image-to-video node uses vision model to caption image -- BUT: No explicit instruction about HOW to use the reference -- Vision caption is just appended to prompt without mode guidance - -**Impact:** HIGH - Wan may copy unwanted elements or drift identity - ---- - -#### 4. **Word Count Too Low for Detailed Tiers** -**Wan 2.2 Recommendation:** -- Advanced: 400-600 words -- Cinematic: 600-1000 words - -**Our Current Implementation:** -- Advanced: "400-600 words minimum" ✅ CORRECT -- Cinematic: "600-1000 words minimum" ✅ CORRECT -- BUT: Single paragraph format makes it hard to structure this much content coherently - -**Impact:** MEDIUM - Format issue, not length issue - ---- - -#### 5. **Missing Explicit Ending Instructions** -**Wan 2.2 Requirement:** -- Every prompt should end with clear termination cue: - - "Final wide reveal" - - "Final overhead shot" - - "Final establishing shot" - -**Our Current Implementation:** -- No requirement for ending instruction -- Prompts just... end - -**Impact:** MEDIUM - Videos may loop awkwardly or cut off abruptly - ---- - -#### 6. **Missing Identity Consistency Across Beats** -**Wan 2.2 Recommendation:** -- Repeat character capsule in each shot block: - - "Shot 1: the same woman in white Hanfu..." - - "Shot 2: the same woman in white Hanfu..." - -**Our Current Implementation:** -- Not applicable since we don't use shot blocks - -**Impact:** LOW (since we're single-paragraph) - Would become HIGH if we adopt shot structure - ---- - -## Detailed Comparison - -### Camera Movement Menus - -| Wan 2.2 Recommended | Our Advanced Node | Status | -|---------------------|-------------------|--------| -| camera pans left/right | ✅ camera pans left/right | ALIGNED | -| camera tilts up/down | ✅ camera tilts up/down | ALIGNED | -| slow dolly in/out | ✅ dolly in/out | ALIGNED | -| camera pulls back | ✅ camera pulls back | ALIGNED | -| tracking shot | ✅ tracking shot | ALIGNED | -| arc shot | ✅ arc shot | ALIGNED | -| crane shot | ✅ crane shot | ALIGNED | -| handheld camera | ✅ handheld camera | ALIGNED | -| steadicam | ✅ steadicam | ALIGNED | -| static shot | ✅ static shot | ALIGNED | -| **the camera orbits around her** | ❌ MISSING | **GAP** | -| **smooth glide** | ❌ MISSING | **GAP** | -| **locked-off shot** | ❌ MISSING | **GAP** | -| **crash zoom** | ❌ MISSING | **GAP** | -| **whip pan** | ✅ whip pan | ALIGNED | -| **compound move** | ✅ compound move | ALIGNED | -| **camera cranes up** | ⚠️ "crane shot" (less specific) | PARTIAL | - -### Shot/Angle Menus - -| Wan 2.2 Recommended | Our Advanced Node | Status | -|---------------------|-------------------|--------| -| extreme close-up | ✅ | ALIGNED | -| close-up | ✅ | ALIGNED | -| medium close-up | ✅ | ALIGNED | -| medium shot | ✅ | ALIGNED | -| medium wide shot | ✅ | ALIGNED | -| wide shot | ✅ | ALIGNED | -| extreme wide shot | ✅ | ALIGNED | -| establishing shot | ✅ | ALIGNED | -| over-the-shoulder | ✅ | ALIGNED | -| **first-person POV** | ❌ MISSING | **GAP** | -| **profile close-up** | ❌ MISSING | **GAP** | - -### Lighting (Well Covered) - -Our lighting options are comprehensive and aligned with Wan 2.2 guide. ✅ - ---- - -## LLM System Prompt Analysis - -### Current Expansion Engine Prompt - -``` -You are an expert AI video prompt engineer for Wan 2.2 video generation. - -CRITICAL OUTPUT RULES: -1. Output ONLY the enhanced prompt - no labels, no explanations -2. Do NOT repeat or echo the user's input -3. Do NOT include phrases like "Here is..." -4. Write as ONE continuous paragraph describing the scene ❌ WRONG FORMAT -5. Start directly with the description -``` - -### Wan 2.2 Director Prompt (From Guide) - -``` -You are a cinematic prompt director for Wan 2.2... - -Return the final prompt in this structure: - -[GLOBAL SETUP PARAGRAPH — 2-4 sentences] - -Shot 1: [framing, camera move, subject action, parallax, emotion] - -Shot 2: [new angle, escalation, new camera motion] - -Shot 3: [final reveal, include "Final shot" or "Final wide reveal"] - -[STYLE / TECH FOOTER] -``` - -### Critical Differences - -| Aspect | Our Current Prompt | Wan 2.2 Guide | Gap Severity | -|--------|-------------------|---------------|--------------| -| **Structure Format** | Single paragraph | Multi-shot blocks | 🚨 CRITICAL | -| **Temporal Progression** | Not mentioned | Required (Shot 1/2/3 or 0-2s/2-4s/4-6s) | 🚨 CRITICAL | -| **Ending Instruction** | Not mentioned | Required ("Final wide reveal") | 🚨 CRITICAL | -| **Parallax Cues** | Generic "motion" | Explicit atmospheric motion required | 🚨 CRITICAL | -| **Identity Repetition** | Not mentioned | Repeat character capsule per shot | ⚠️ MEDIUM | -| **Word Count** | Correct minimums | Correct | ✅ ALIGNED | -| **Camera Verbs** | Good coverage | Good coverage | ✅ ALIGNED | - ---- - -## Recommendations - -### 🔴 PRIORITY 1: Restructure LLM System Prompt - -**Action:** Replace single-paragraph format with shot-based structure - -**New Format Option A (Storyboard Style):** -``` -[GLOBAL SETUP - 2-4 sentences: subject, environment, mood, style] - -Shot 1: [Framing + Camera Move] -[Describe subject action, foreground/background parallax, atmospheric motion, emotional beat] -[2-3 sentences] - -Shot 2: [New Angle + Camera Move] -[Escalation, new details, continued motion, depth cues] -[2-3 sentences] - -Shot 3: [Final Reveal + Camera Move] -[Ending beat, pullback/crane/reveal, say "Final shot" or "Final wide reveal"] -[2-3 sentences] - -[STYLE/TECH FOOTER: 1-2 sentences with fps, resolution, style, negatives] -``` - -**New Format Option B (Continuous Timed):** -``` -[GLOBAL SETUP - 2-4 sentences] - -0-2s (Opening): -[Starting framing + camera move + initial action + atmospheric motion] - -2-4s (Development): -[Camera transition + escalation + new details + parallax cues] - -4-6s (Final): -[Ending move + reveal + "Final shot" termination cue] - -[STYLE/TECH FOOTER] -``` - -**Benefits:** -- ✅ Aligns with Wan 2.2's temporal expectations -- ✅ Forces inclusion of ending cue -- ✅ Easier to structure 400-1000 words coherently -- ✅ Better camera choreography across beats - ---- - -### 🔴 PRIORITY 2: Add Atmospheric Motion Requirements - -**Action:** Update tier instructions to mandate parallax/atmospheric elements - -**Add to ALL tier instructions:** -``` -YOU MUST INCLUDE ATMOSPHERIC MOTION & PARALLAX: -- Foreground elements: particles drifting, rain streaks past lens, steam blowing, fabric rippling -- Background depth: mist rising, clouds moving, reflections shimmering, distant motion -- Environmental animation: leaves falling, water flowing, smoke drifting, shadows moving -- These create depth and prevent static-looking output - -Examples: -- "rain streaks diagonally past the lens, catching neon light" -- "low mist rises from the lake surface and drifts across frame" -- "steam from street vents blows between camera and subject" -- "her long sleeves leave glowing trails as they sweep through air" -``` - ---- - -### 🔴 PRIORITY 3: Add Reference Image Mode Instructions - -**Action:** Update image-to-video node to include explicit mode selection - -**Add New Parameter to Image-to-Video Node:** -```python -"reference_mode": ([ - "recreate_exact", # Keep exact character, outfit, lighting - animate this - "style_transfer", # Match lighting/mood only, new pose/scene - "character_remix", # Use character but change outfit/setting - "face_only" # Preserve face identity, ignore background/lighting -], { - "default": "recreate_exact", - "tooltip": "How to use the reference image" -}) -``` - -**Update LLM Prompt to Include:** -``` -REFERENCE IMAGE MODE: {reference_mode} - -If recreate_exact: -"Use the provided image as the exact character and costume reference. Keep the same face, hair, outfit, and lighting. Animate this character without changing identity." - -If style_transfer: -"Match the lighting, color palette, and cinematic mood of the provided image, but create a new pose and new scene." - -If character_remix: -"Loosely base the main character on the provided image, but change the outfit and relocate them to a new setting." - -If face_only: -"Preserve ONLY the subject's face and body identity from the provided image. Ignore the original background and lighting. Place this character in the new described scene." -``` - ---- - -### 🟡 PRIORITY 4: Expand Camera Movement Options - -**Action:** Add missing Wan 2.2-recommended camera moves - -**Add to camera_movement dropdown:** -```python -"camera orbits around subject", -"smooth glide", -"locked-off shot", -"crash zoom in", -"camera cranes up", -"camera cranes down" -``` - -**Add to shot_size dropdown:** -```python -"first-person POV", -"profile close-up" -``` - ---- - -### 🟡 PRIORITY 5: Add Negative Prompt Blocks - -**Action:** Include Wan 2.2-recommended negatives based on style - -**In expansion_engine.py, add:** -```python -def _get_negative_prompt_block(self, visual_style: str) -> str: - """Generate Wan 2.2-optimized negative prompts""" - - if visual_style in ["photorealistic", "cinematic", "none", "auto"]: - return """ -Negative: no subtitles, no on-screen text, no watermarks, no logos, no extra limbs, no deformed hands, no distortion, not low quality -""" - elif "anime" in visual_style.lower() or "cartoon" in visual_style.lower(): - return """ -Negative: no photoreal skin texture, no live-action lighting, no watermarks, no subtitles, keep clean cel shading, no flicker, no jitter -""" - else: - return """ -Negative: no watermarks, no subtitles, no text overlay, no distortion -""" -``` - ---- - -## Implementation Roadmap - -### Phase 1: Critical Fixes (v1.9.0) -**Target: Next release** - -1. ✅ Restructure LLM system prompt to use shot-based format (Storyboard OR Continuous) -2. ✅ Add explicit ending instruction requirement ("Final shot") -3. ✅ Add atmospheric motion/parallax requirements to all tier instructions -4. ✅ Add reference_mode parameter to image-to-video node -5. ✅ Include reference mode instruction in LLM prompt - -**Estimated Work:** 4-6 hours -**Impact:** HIGH - Transforms output quality for Wan 2.2 - ---- - -### Phase 2: Enhancement (v1.9.1) -**Target: Follow-up release** - -1. ✅ Add missing camera movement options -2. ✅ Add missing shot/angle options -3. ✅ Implement negative prompt blocks -4. ✅ Add "creative_randomness" control (already done in v1.8.1) -5. ✅ Update documentation with Wan 2.2 best practices - -**Estimated Work:** 2-3 hours -**Impact:** MEDIUM - Completes Wan 2.2 alignment - ---- - -### Phase 3: Advanced Features (v2.0.0) -**Target: Future** - -1. ⚠️ Add multi-shot preview mode (show all 3 shots separately) -2. ⚠️ Add shot duration control (let user set 2s, 3s, 4s per shot) -3. ⚠️ Add "Director's Notes" field for extra instructions -4. ⚠️ Create Wan 2.2-specific preset library - -**Estimated Work:** 8-12 hours -**Impact:** MEDIUM - Power user features - ---- - -## Example: Before vs After - -### BEFORE (Current v1.8.1) - -**LLM Output (Single Paragraph):** -``` -A graceful woman in flowing white Hanfu dances at the edge of a moonlit lake at night, her long sleeves catching soft blue rim light as tiny birds of glowing spirit energy blossom from her fingertips and circle her in synchronized motion, leaving shimmering trails through the air while the dark water reflects their luminous glow and faint mist drifts across the scene, creating an ethereal wuxia fantasy atmosphere with cinematic realism and smooth motion at 24fps... -[continues for 400 words in one paragraph] -``` - -**Issues:** -- ❌ No temporal structure -- ❌ No explicit camera choreography progression -- ❌ No ending cue -- ❌ Limited parallax description -- ❌ Hard to parse for 400+ words - ---- - -### AFTER (Proposed v1.9.0) - -**LLM Output (Shot-Based Structure):** -``` -A graceful woman in flowing white Hanfu dances at the edge of a moonlit lake at night. Soft blue rim light outlines her sleeves, and faint mist drifts across the water. Glowing spirit-bird particles gather around her hands as she moves. Cinematic realism, ethereal wuxia fantasy mood. - -Shot 1: Close-up, Slow Dolly In -The camera starts in a close-up on her hands. She turns her wrists with elegant precision, and tiny birds of light blossom from her fingertips. Their wings glow softly and leave shimmering trails in the air. Slow dolly in toward her glowing fingertips, gentle handheld feel. - -Shot 2: Medium Shot, Orbital Arc -The camera eases back to a medium shot of her upper body and begins a smooth orbital arc around her to the left. Her long sleeves sweep through the air, leaving ribbons of light. The spirit birds circle her in synchronized motion, tracing spirals above the dark lake. Mist drifts between camera and subject. Her face is calm, focused, powerful. - -Shot 3: Overhead Crane Reveal (Final Shot) -The camera cranes upward and tilts down to an overhead view. The glowing birds form a radiant halo around her on the lakeshore, their reflections flickering on the black water. Moonlight and spirit-light merge into a swirling galaxy around her. Final wide reveal, majestic and otherworldly. - -24fps, 1280×720, cinematic realism, smooth motion. -Negative: no subtitles, no on-screen text, no watermarks, no extra limbs, no distorted hands. -``` - -**Improvements:** -- ✅ Clear temporal progression (Shot 1 → 2 → 3) -- ✅ Explicit camera choreography per beat -- ✅ "Final wide reveal" ending cue -- ✅ Atmospheric motion ("mist drifts between camera and subject") -- ✅ Parallax cues ("reflections flickering") -- ✅ Negative prompt block included -- ✅ Much easier to read and parse -- ✅ Direct match to Wan 2.2 Director System Prompt format - ---- - -## Conclusion - -Our current implementation is **70% aligned** with Wan 2.2 best practices. We have excellent camera vocabulary and aesthetic controls, but we're missing the **critical structural format** that Wan 2.2 expects. - -**The single biggest improvement** we can make is adopting the shot-based structure from the Wan 2.2 Director System Prompt. This alone will dramatically improve output quality. - -**Recommended Action:** -1. Implement Phase 1 changes immediately (v1.9.0) -2. Test with real Wan 2.2 generations -3. Iterate based on results -4. Document Wan 2.2-specific workflows in README - -**Risk Level:** LOW - Changes are additive and backward-compatible -**Expected Benefit:** HIGH - Output quality should improve significantly - ---- - -## Next Steps - -Would you like me to: -1. ✅ Implement Phase 1 changes now (restructure LLM prompts)? -2. ✅ Create new test examples with shot-based format? -3. ✅ Update documentation with Wan 2.2 best practices? -4. ✅ All of the above? - -Let me know how you'd like to proceed! diff --git a/docs/ADVANCED_NODE_REDESIGN.md b/docs/ADVANCED_NODE_REDESIGN.md deleted file mode 100644 index 7193567..0000000 --- a/docs/ADVANCED_NODE_REDESIGN.md +++ /dev/null @@ -1,362 +0,0 @@ -# Advanced Prompt Expander Node - Redesign (v1.8.0) - -## Overview - -The Advanced Prompt Expander Node has been completely redesigned to address three critical usability issues and improve its functionality for real-world workflows. - ---- - -## Problems Fixed - -### ❌ Problem 1: No Way to Modify Existing Prompts - -**Before:** -The node was designed only to "expand" short stub prompts like "a cat playing piano." If you had an existing detailed prompt that needed modification, refinement, or style changes, there was no way to tell the node to treat it differently. - -**Now: ✅ Operation Mode Selection** - -Added a new `operation_mode` dropdown with 4 modes: - -1. **expand_from_idea** (default) - - Original behavior: Take a short concept and expand it into full detail - - Use when: You have a simple idea that needs fleshing out - - Example: "a cat playing piano" → full cinematic description - -2. **refine_existing** - - Keep the core content but improve clarity, flow, and descriptive quality - - Use when: You have a working prompt that needs polishing - - Example: Improve grammar, enhance descriptions, better word choices - -3. **modify_style** - - Keep the subject/action but change aesthetic, mood, and cinematography - - Use when: You want the same scene but different visual treatment - - Example: Same cat scene, but change from "cinematic" to "noir" style - -4. **add_details** - - Keep everything that's there and add richer descriptions and sensory elements - - Use when: Your prompt is good but needs more depth - - Example: Add atmospheric details, textures, emotional beats - -**Implementation:** -```python -def _apply_operation_mode(self, prompt: str, operation_mode: str, image_context: str = "") -> str: - """ - Apply operation mode to modify how the prompt is processed - """ - if operation_mode == "refine_existing": - instruction = "\n\n[INSTRUCTION: This is an existing prompt to refine..." - return prompt + instruction + image_context - # ... etc -``` - -The node now adds specific instructions to the LLM based on the operation mode, guiding it on how to treat the input. - ---- - -### ❌ Problem 2: Confusing Tier System - -**Before:** -- Used terms like "basic", "enhanced", "advanced", "cinematic", "auto" -- Not clear what these mean or when to use them -- Word counts (150-250, 250-400, 400-600, 600-1000) were hidden from users -- "auto" tried to detect complexity but users didn't understand what it did - -**Now: ✅ Clear Detail Levels** - -Replaced `expansion_tier` with `detail_level` using intuitive names: - -1. **concise** (replaces "basic") - - ~150-200 words - - Brief, essential details only - - Use when: You want compact prompts - -2. **moderate** (replaces "enhanced") - - ~250-350 words - - Good balance of detail - - Use when: Standard detailed description - -3. **detailed** (replaces "advanced") - - ~400-500 words - - Rich, comprehensive description - - Use when: You want thorough detail (DEFAULT) - -4. **exhaustive** (replaces "cinematic") - - ~600-1000 words - - Maximum detail for cinematic quality - - Use when: Professional-grade video prompts - -**Added Tooltips:** -Each option now has a clear tooltip explaining what it does and when to use it. - -**Backward Compatibility:** -The expansion_engine.py now includes a mapping so old tier names still work internally: -```python -tier_mapping = { - "concise": "basic", - "moderate": "enhanced", - "detailed": "advanced", - "exhaustive": "cinematic" -} -``` - -**Removed "auto" option** - Users should choose their detail level explicitly. - ---- - -### ❌ Problem 3: Image-to-Video Mode Without Image Input - -**Before:** -- Had a "mode" dropdown with "text-to-video" and "image-to-video" options -- BUT: No way to actually provide an image! -- "image-to-video" mode was completely non-functional -- The Qwen3-VL backend exists but wasn't being used - -**Now: ✅ Optional Image Input with Qwen3-VL** - -**Added to INPUT_TYPES:** -```python -"optional": { - # Optional image/video reference for image-to-video workflows - "reference_image": ("IMAGE", { - "tooltip": "Optional: Provide an image to analyze and incorporate into the prompt using Qwen3-VL" - }), -} -``` - -**How it works:** - -1. **If no image is provided:** - - Works exactly as before - - mode = "text-to-video" - - Normal text expansion - -2. **If image IS provided:** - - Image is analyzed using Qwen3-VL vision model - - Detailed caption is generated describing: - - Main subject and appearance - - Actions and movements - - Environment and setting - - Lighting and atmosphere - - Colors and visual style - - Notable objects/elements - - mode automatically switches to "image-to-video" - - Caption is appended to the working prompt as context - - LLM incorporates image analysis into the expanded prompt - -**Image Processing:** -```python -def _process_reference_image(self, image_tensor): - """Process ComfyUI image tensor using Qwen3-VL for captioning""" - # Convert ComfyUI format (B,H,W,C) to PIL Image - # Call Qwen3-VL with detailed video-focused prompt - # Return caption or None if error -``` - -**Status Display:** -The status now shows: -- `Mode: text-to-video` - if no image -- `Mode: image-to-video (with image)` - if image provided - ---- - -## Migration Guide - -### For Existing Workflows - -**Old Node Configuration:** -``` -expansion_tier: "advanced" -mode: "text-to-video" -basic_prompt: "your prompt here" -``` - -**New Equivalent:** -``` -detail_level: "detailed" -operation_mode: "expand_from_idea" -basic_prompt: "your prompt here" -reference_image: (empty/optional) -``` - -### Mapping Old to New - -| Old `expansion_tier` | New `detail_level` | Word Count | -|---------------------|-------------------|------------| -| basic | concise | 150-200 | -| enhanced | moderate | 250-350 | -| advanced | detailed | 400-500 | -| cinematic | exhaustive | 600-1000 | -| auto | (removed) | user chooses | - -**The old "mode" dropdown has been removed** - it's now automatically determined by whether an image is provided. - ---- - -## New Workflows Enabled - -### Workflow 1: Refine an Existing Long Prompt -``` -Input: [Your 300-word existing prompt] -operation_mode: refine_existing -detail_level: detailed -Result: Polished version with better flow and clarity -``` - -### Workflow 2: Change Style of Existing Prompt -``` -Input: [Your existing prompt about a detective scene] -operation_mode: modify_style -preset: noir (changed from cinematic) -detail_level: detailed -Result: Same detective scene, but now in noir style -``` - -### Workflow 3: Image-to-Video with Context -``` -Input: "Make the subject move towards the camera dramatically" -operation_mode: expand_from_idea -reference_image: [Your reference image] -detail_level: detailed -Result: Detailed video prompt incorporating image analysis + your direction -``` - -### Workflow 4: Add More Detail to Good Prompt -``` -Input: [Your working prompt that's a bit sparse] -operation_mode: add_details -detail_level: exhaustive -Result: Same prompt but with atmospheric details, textures, emotions added -``` - ---- - -## Technical Changes - -### Files Modified - -1. **prompt_expander_node_advanced.py** - - Added `operation_mode` parameter - - Renamed `expansion_tier` → `detail_level` - - Removed `mode` parameter (auto-detected) - - Added optional `reference_image` input - - Added `_apply_operation_mode()` helper method - - Added `_process_reference_image()` for Qwen3-VL integration - - Updated status display to show operation mode and image usage - - Updated metadata for saved files - -2. **expansion_engine.py** - - Added tier name mapping for backward compatibility - - Supports both old and new tier names - - Cleaner logic for tier detection - -### New Dependencies - -The node now imports from qwen3_vl_backend.py when an image is provided: -```python -from .qwen3_vl_backend import caption_with_qwen3_vl -``` - -This is only imported if needed, so the node still works without Qwen3-VL installed (just can't use image input). - ---- - -## Testing Checklist - -### Test 1: Operation Modes -- [ ] expand_from_idea: "cat playing piano" expands fully -- [ ] refine_existing: Long prompt gets polished, not expanded -- [ ] modify_style: Subject stays same, style changes with preset -- [ ] add_details: Original content preserved, details added - -### Test 2: Detail Levels -- [ ] concise: Output ~150-200 words -- [ ] moderate: Output ~250-350 words -- [ ] detailed: Output ~400-500 words -- [ ] exhaustive: Output ~600-1000 words - -### Test 3: Image Input -- [ ] No image: Works normally, mode=text-to-video -- [ ] With image: Qwen3-VL analyzes it, mode=image-to-video -- [ ] Image analysis appears in breakdown -- [ ] Status shows "(with image)" - -### Test 4: Backward Compatibility -- [ ] Old workflows with "advanced" tier still work -- [ ] Old tier names map to new detail levels correctly - -### Test 5: Combined Features -- [ ] modify_style + with_image: Changes style based on image -- [ ] refine_existing + exhaustive: Makes existing prompt much more detailed -- [ ] add_details + moderate: Balanced detail addition - ---- - -## Benefits - -✅ **More Intuitive** -- Clear operation modes match user intent -- Detail levels have obvious names and tooltips - -✅ **More Powerful** -- Can now modify existing prompts 4 different ways -- Can incorporate image analysis for image-to-video workflows - -✅ **Better UX** -- Tooltips explain every option -- Status messages are more informative -- No more confusing "auto" mode - -✅ **Backward Compatible** -- Old tier names still work internally -- Existing workflows won't break -- Expansion engine supports both naming systems - -✅ **Leverages Existing Tech** -- Finally uses the Qwen3-VL backend that was already there -- ComfyUI image tensors integrate seamlessly - ---- - -## Future Enhancements - -Possible future additions: -- Support for video input (Qwen3-VL can handle it) -- Multiple reference images -- Image directive modes (like text_to_image_node has) -- Comparison of before/after for modify/refine modes -- Batch processing with different operation modes - ---- - -## Status - -**Version:** 1.8.0 -**Date:** October 23, 2025 -**Status:** ✅ Complete - Ready for Testing -**Tested:** No syntax errors, imports validated -**Next:** Test in ComfyUI with actual LLM and images - ---- - -## Questions & Answers - -**Q: Do I need Qwen3-VL to use this node?** -A: No! It's optional. The node works fine without it - you just can't use the image input feature. - -**Q: Will my old workflows break?** -A: No. The expansion_engine still understands old tier names internally, so saved workflows with "advanced" will still work. - -**Q: What if I'm happy with the old simple behavior?** -A: Just use `operation_mode: expand_from_idea` and ignore the image input. It works exactly as before. - -**Q: Can I use multiple images?** -A: Not yet, but the architecture supports it. Currently limited to one reference image. - -**Q: What's the best detail level?** -A: Start with "detailed" (the default). Use "exhaustive" for professional work, "moderate" for quick tests, "concise" for API token savings. - -**Q: When should I use modify_style vs add_details?** -A: -- **modify_style**: You want the same scene but different visual treatment -- **add_details**: You want to keep the style but make it richer - diff --git a/docs/BUGFIX_ADVANCED_NODE.md b/docs/BUGFIX_ADVANCED_NODE.md deleted file mode 100644 index 6a36bf1..0000000 --- a/docs/BUGFIX_ADVANCED_NODE.md +++ /dev/null @@ -1,237 +0,0 @@ -# Bug Fixes for Advanced Prompt Expander Node - October 2025 - -## Issues Fixed - -The `prompt_expander_node_advanced.py` (and `prompt_expander_node.py`) were missing critical bugfixes that had already been applied to `text_to_image_node.py` in version 1.6.1. - -### 1. ✅ FIXED: Emphasis Syntax Being Broken - -**Problem:** -User input like `(dark skin:1.5)` was being converted to `dark skin (1.5)`, losing the emphasis weight that's critical for Stable Diffusion and other image generation models. - -**Solution:** -- Added `_preserve_emphasis_syntax()` function that protects emphasis patterns before LLM processing -- Emphasis patterns like `(keyword:1.5)` are temporarily replaced with placeholders `__EMPHASIS_0__` -- After LLM processing, `_restore_emphasis_syntax()` puts them back exactly as they were -- Supports any format: `(text:number)` where number can be decimal - -**Supported Emphasis:** -``` -(dark skin:1.5) - Increases weight to 1.5x -(background:0.5) - Decreases weight to 0.5x -(red hair:2.0) - Doubles the weight -``` - -**Implementation:** -```python -# Before LLM processing -basic_prompt = self._preserve_emphasis_syntax(basic_prompt) - -# After LLM response parsing -enhanced_prompt = self._restore_emphasis_syntax(enhanced_prompt) -``` - ---- - -### 2. ✅ FIXED: Missing Alternation Syntax Support - -**Problem:** -No way to have random selection from options in the prompt for video generation. - -**Solution:** -- Added `_process_alternations()` function -- Supports `{option1|option2|option3}` syntax -- Randomly picks one option each time -- Processes BEFORE LLM to ensure clean input - -**Supported Alternations:** -``` -{apple|banana|orange} - Picks one randomly -{red|blue|green} dress - Color chosen randomly -a {cat|dog|bird} in the garden - Animal chosen randomly -``` - -**Nested/Combined:** -``` -{red|blue|green} (dress:1.2) - Random color with emphasis -{tall|short} woman with {blonde|brunette|red} hair - Multiple alternations -A cat playing {piano|guitar|drums} in a {cozy|modern|vintage} room -``` - -**Implementation:** -```python -# Very first step - before LLM processing -basic_prompt = self._process_alternations(basic_prompt) -``` - ---- - -## Technical Details - -### Functions Added to Both Nodes - -1. **`_process_alternations(text: str) -> str`** - - Uses regex to find `{option1|option2|option3}` patterns - - Splits by `|` and randomly chooses one - - Handles nested alternations (up to 10 levels) - - Runs BEFORE LLM processing and emphasis preservation - -2. **`_preserve_emphasis_syntax(text: str) -> str`** - - Uses regex pattern `r'\(([^():]+):(\d+\.?\d*)\)'` to find emphasis - - Replaces each with unique placeholder `__EMPHASIS_N__` - - Stores originals in `self._emphasis_store` list - - Returns text with placeholders - -3. **`_restore_emphasis_syntax(text: str) -> str`** - - Replaces all placeholders with original emphasis syntax - - Clears the `_emphasis_store` after restoration - - Safe to call even if no emphasis was preserved - -### Processing Order - -The correct order is critical: - -```python -# 1. Process alternations FIRST (choose random options) -basic_prompt = self._process_alternations(basic_prompt) - -# 2. Preserve emphasis syntax (protect from LLM) -basic_prompt = self._preserve_emphasis_syntax(basic_prompt) - -# 3. Parse keywords and other processing -pos_kw_list = parse_keywords(positive_keywords) -# ... rest of processing ... - -# 4. Call LLM with protected prompt -response = llm.send_prompt(system_prompt, user_prompt) - -# 5. Parse LLM response -enhanced_prompt = parsed["prompt"] - -# 6. IMMEDIATELY restore emphasis syntax -enhanced_prompt = self._restore_emphasis_syntax(enhanced_prompt) - -# 7. Continue with keyword validation, etc. -``` - ---- - -## Files Modified - -### 1. `prompt_expander_node_advanced.py` -- ✅ Added imports: `re`, `random` -- ✅ Added `_emphasis_store = []` to `__init__` -- ✅ Added processing in `expand_prompt()` method -- ✅ Added three new methods at end of class -- Lines changed: ~30 additions, ~5 modifications - -### 2. `prompt_expander_node.py` -- ✅ Added imports: `re`, `random` -- ✅ Added `_emphasis_store = []` to `__init__` -- ✅ Added processing in `expand_prompt()` method -- ✅ Added three new methods at end of class -- Lines changed: ~30 additions, ~5 modifications - ---- - -## Testing the Fixes - -### Test 1: Emphasis Syntax Preservation -``` -Input: "A beautiful woman with (dark skin:1.5) wearing a (red dress:1.3)" -Expected Output: Emphasis weights preserved exactly as-is -``` - -### Test 2: Alternation Syntax -``` -Input: "A {cat|dog|bird} playing {piano|guitar|drums}" -Expected: One random combination each time (e.g., "A bird playing piano") -``` - -### Test 3: Combined Usage -``` -Input: "A {tall|short} woman with (dark hair:1.4) in a {modern|vintage} setting" -Expected: -- One random option chosen from each {...} -- (dark hair:1.4) preserved exactly -``` - -### Test 4: Advanced Node with Controls -``` -Input: "A {cyberpunk|steampunk} cityscape with (neon lights:1.8)" -Camera Movement: camera pushes in -Lighting: volumetric lighting -Expected: -- Random genre chosen -- Emphasis preserved -- Camera and lighting integrated naturally -``` - ---- - -## Backward Compatibility - -✅ **100% Backward Compatible** -- Existing prompts without emphasis or alternations work exactly as before -- New syntax is completely optional -- No breaking changes to existing functionality - ---- - -## Why This Matters - -### For Video Generation: -1. **Emphasis syntax** allows fine control over element importance in generated videos -2. **Alternation syntax** enables variety in batch generation without manual prompt changes -3. Both features are standard in Stable Diffusion and other gen models - -### For User Experience: -- Users can now use familiar syntax from SD workflows -- No more broken emphasis weights -- Easy random variations without re-running or editing - ---- - -## Status - -**Fixed:** October 23, 2025 -**Version:** 1.7.0 (unofficial - pending release) -**Tested:** No syntax errors, imports validated -**Next Step:** Test in ComfyUI environment with actual LLM calls - ---- - -## Example Workflow - -**Before Fix:** -``` -Input: "A detective with (weathered face:1.5) in film noir style" -Output: "A detective with weathered face (1.5) in film noir style" ❌ Broken! -``` - -**After Fix:** -``` -Input: "A detective with (weathered face:1.5) in film noir style" -Output: "A grizzled detective with (weathered face:1.5), standing in the shadows - of a rain-soaked alley, illuminated only by the dim glow of a distant - street lamp, film noir style with high contrast lighting" ✅ Perfect! -``` - -**With Alternations:** -``` -Input: "A {cat|dog|rabbit} with (fluffy fur:1.3) in a {cozy|modern|vintage} room" -Run 1: "A rabbit with (fluffy fur:1.3) in a vintage room..." -Run 2: "A dog with (fluffy fur:1.3) in a cozy room..." -Run 3: "A cat with (fluffy fur:1.3) in a modern room..." -``` - ---- - -## Notes - -- The functions were directly ported from `text_to_image_node.py` which had these fixes applied in v1.6.1 -- No modifications to the logic were needed - just integration into the expand_prompt flow -- Both the basic and advanced prompt expander nodes now have feature parity with the text-to-image node - -**Status:** Bug Fixes Complete ✅ -**Restart Required:** Yes - Restart ComfyUI to load the updated nodes diff --git a/docs/BUGFIX_SUMMARY.md b/docs/BUGFIX_SUMMARY.md deleted file mode 100644 index 7c55298..0000000 --- a/docs/BUGFIX_SUMMARY.md +++ /dev/null @@ -1,121 +0,0 @@ -# Bug Fixes Summary - Advanced Prompt Expander Node - -## Date: October 23, 2025 - ---- - -## Issues Addressed - -### 1. ✅ No Way to Modify Existing Prompts - -**Added:** `operation_mode` dropdown with 4 options: -- `expand_from_idea` - Original behavior (expand short concepts) -- `refine_existing` - Polish existing prompts without major changes -- `modify_style` - Change aesthetic while keeping subject -- `add_details` - Add richer descriptions to existing content - -### 2. ✅ Confusing Tier System - -**Changed:** Renamed `expansion_tier` → `detail_level` with clear names: -- `concise` (~150-200 words) - replaces "basic" -- `moderate` (~250-350 words) - replaces "enhanced" -- `detailed` (~400-500 words) - replaces "advanced" (DEFAULT) -- `exhaustive` (~600-1000 words) - replaces "cinematic" - -**Removed:** "auto" option - users now explicitly choose detail level - -**Added:** Tooltips explaining each option - -### 3. ✅ Image-to-Video Mode Without Image Input - -**Added:** Optional `reference_image` input (IMAGE type) - -**Functionality:** -- If no image: Works as text-to-video (normal operation) -- If image provided: Uses Qwen3-VL to analyze image and incorporates description into prompt -- Mode automatically switches to "image-to-video" when image is provided -- Status shows "(with image)" indicator - -**Removed:** Manual "mode" dropdown - now auto-detected based on image presence - ---- - -## Backward Compatibility - -✅ Old tier names still work internally via mapping: -```python -"concise" → "basic" -"moderate" → "enhanced" -"detailed" → "advanced" -"exhaustive" → "cinematic" -``` - -✅ Existing workflows won't break - ---- - -## Files Modified - -1. **prompt_expander_node_advanced.py** (~100 lines changed) - - Updated INPUT_TYPES with new parameters - - Added optional image input - - Added `_apply_operation_mode()` method - - Added `_process_reference_image()` method with Qwen3-VL integration - - Updated function signature - - Updated status and metadata - -2. **expansion_engine.py** (~30 lines changed) - - Added tier name mapping for backward compatibility - - Updated docstring - - Improved tier detection logic - ---- - -## Testing Status - -✅ No syntax errors -✅ No import errors -✅ Backward compatibility maintained -⏳ Needs real-world testing in ComfyUI with LLM and images - ---- - -## Usage Examples - -### Refine existing prompt: -``` -operation_mode: refine_existing -detail_level: detailed -``` - -### Change style of existing scene: -``` -operation_mode: modify_style -preset: noir -detail_level: detailed -``` - -### Image-to-video with direction: -``` -operation_mode: expand_from_idea -basic_prompt: "Camera slowly zooms in on the subject" -reference_image: [your image] -detail_level: detailed -``` - -### Add more detail to sparse prompt: -``` -operation_mode: add_details -detail_level: exhaustive -``` - ---- - -## Documentation - -- Full redesign documentation: `docs/ADVANCED_NODE_REDESIGN.md` -- Previous bugfixes: `docs/BUGFIX_ADVANCED_NODE.md` - ---- - -**Status:** ✅ Complete - Ready for Testing diff --git a/docs/BUGFIX_V161.md b/docs/BUGFIX_V161.md deleted file mode 100644 index fac831f..0000000 --- a/docs/BUGFIX_V161.md +++ /dev/null @@ -1,236 +0,0 @@ -# Text-to-Image Node Bug Fixes - v1.6.1 - -## Issues Fixed - -### 1. Settings Appearing in Prompt Output ✅ FIXED - -**Problem:** -The node was appending settings information to the prompt: -``` -...golden hour sunlight | Settings: camera angle: extreme close-up; lighting: volumetric... -``` - -**Solution:** -- Updated system prompt to explicitly instruct LLM not to include settings -- Changed user prompt to say "Required settings to incorporate" instead of just "Settings" -- Added regex cleanup to strip any "| Settings:" or trailing settings that slip through -- Settings are now incorporated naturally into the description, not appended - -**Result:** -Prompts now look like: -``` -masterpiece, best quality, detailed portrait shot from extreme close-up angle -with volumetric golden hour sunlight... -``` - ---- - -### 2. Emphasis Syntax Being Broken ✅ FIXED - -**Problem:** -User input like `(dark skin:1.5)` was being converted to `dark skin (1.5)`, losing the emphasis weight. - -**Solution:** -- Added `_preserve_emphasis_syntax()` function that protects emphasis patterns before LLM processing -- Emphasis patterns like `(keyword:1.5)` are temporarily replaced with placeholders `__EMPHASIS_0__` -- After LLM processing, `_restore_emphasis_syntax()` puts them back -- Supports any format: `(text:number)` where number can be decimal - -**Supported Emphasis:** -``` -(dark skin:1.5) - Increases weight to 1.5x -(background:0.5) - Decreases weight to 0.5x -(red hair:2.0) - Doubles the weight -``` - ---- - -### 3. Alternation Syntax Added ✅ NEW FEATURE - -**Problem:** -No way to have random selection from options in the prompt. - -**Solution:** -- Added `_process_alternations()` function -- Supports `{option1|option2|option3}` syntax -- Randomly picks one option each time -- Processes before LLM to ensure clean input - -**Supported Alternations:** -``` -{apple|banana|orange} - Picks one randomly -{red|blue|green} dress - Color chosen randomly -a {cat|dog|bird} in the garden - Animal chosen randomly -``` - -**Nested/Combined:** -``` -{red|blue|green} (dress:1.2) - Random color with emphasis -{tall|short} woman with {blonde|brunette|red} hair - Multiple alternations -``` - ---- - -### 4. Tooltip Updated ✅ ADDED - -**New Tooltip for text_prompt field:** -``` -Describe the image you want to generate - -Supports: -- Emphasis: (keyword:1.5) to increase weight -- De-emphasis: (keyword:0.5) to decrease weight -- Alternation: {apple|banana|orange} picks one randomly -- Nested: {red|blue|green} (dress:1.2) works too -``` - -Users now see usage instructions directly in the GUI! - ---- - -## Technical Details - -### Functions Added - -1. **`_process_alternations(text: str) -> str`** - - Uses regex to find `{option1|option2|option3}` patterns - - Splits by `|` and randomly chooses one - - Handles nested alternations (up to 10 levels) - - Runs BEFORE LLM processing - -2. **`_preserve_emphasis_syntax(text: str) -> str`** - - Finds patterns like `(keyword:1.5)` - - Replaces with `__EMPHASIS_0__`, `__EMPHASIS_1__`, etc. - - Stores originals in `self._emphasis_store` - - Protects from LLM modification - -3. **`_restore_emphasis_syntax(text: str) -> str`** - - Replaces `__EMPHASIS_N__` placeholders back to original - - Runs AFTER LLM processing - - Clears the emphasis store - -### System Prompt Updates - -Added explicit instructions: -``` -CRITICAL OUTPUT REQUIREMENTS: -- Output ONLY the final image prompt text -- DO NOT include any settings information in your output -- DO NOT append "Settings:" or list the camera/lighting/etc values -- Incorporate settings naturally INTO the description -``` - -With examples of correct vs wrong output. - -### Response Cleanup - -Added regex patterns to strip: -```python -# Remove "| Settings: ..." at end -cleaned = re.sub(r'\s*\|\s*[Ss]ettings:.*$', '', cleaned) -# Remove standalone "Settings: ..." at end -cleaned = re.sub(r'\s*[Ss]ettings:.*$', '', cleaned) -# Clean up trailing pipes -cleaned = cleaned.rstrip('|').strip() -``` - ---- - -## Usage Examples - -### Example 1: Emphasis -``` -Input: "a woman with (dark skin:1.5) and (blue eyes:1.3)" -Platform: flux - -Output: "masterpiece, best quality, detailed portrait of a woman -with (dark skin:1.5) and (blue eyes:1.3), photorealistic..." -``` -✅ Emphasis preserved! - -### Example 2: Alternation -``` -Input: "a {cat|dog|rabbit} playing in the garden" -Platform: flux - -Run 1: "...a cat playing in the garden..." -Run 2: "...a dog playing in the garden..." -Run 3: "...a rabbit playing in the garden..." -``` -✅ Random selection works! - -### Example 3: Combined -``` -Input: "{red|blue|green} (dress:1.2) on a {tall|short} woman" -Platform: pony - -Output: "score_9, score_8_up, score_7_up, 1girl, blue (dress:1.2), -short, detailed_face..." -``` -✅ Both features work together! - -### Example 4: No Settings Leak -``` -Input: "woman in garden" -Settings: camera_angle=low angle, lighting=golden hour - -OLD OUTPUT (WRONG): -"...woman in garden with golden hour lighting | Settings: camera angle: low angle..." - -NEW OUTPUT (CORRECT): -"masterpiece, best quality, woman in garden shot from low angle, -golden hour lighting, professional photography..." -``` -✅ Settings incorporated naturally, not appended! - ---- - -## Testing Checklist - -- [x] Emphasis syntax `(keyword:1.5)` preserved -- [x] Alternation syntax `{a|b|c}` works -- [x] No "| Settings:" in output -- [x] Settings incorporated naturally -- [x] Tooltip shows usage instructions -- [x] Code compiles without errors -- [x] Multiple emphasis in one prompt works -- [x] Multiple alternations in one prompt works -- [x] Nested alternations work -- [x] Combined emphasis + alternation works - ---- - -## Files Modified - -**text_to_image_node.py:** -- Updated `text_prompt` INPUT_TYPES with new tooltip -- Added `_process_alternations()` function -- Added `_preserve_emphasis_syntax()` function -- Added `_restore_emphasis_syntax()` function -- Updated `enhance_prompt()` to call alternation and emphasis functions -- Updated `_build_system_prompt()` with explicit anti-settings instructions -- Updated `_build_user_prompt()` to clarify settings are to be incorporated -- Updated `_parse_llm_response()` to strip any stray settings info -- Added regex cleanup for "| Settings:" patterns - -**Lines Changed:** ~100 lines modified/added - ---- - -## Version - -**Version:** 1.6.1 (Bug Fix Update) -**Date:** October 15, 2025 -**Status:** ✅ Ready to use - ---- - -## Next Steps - -1. Restart ComfyUI (if running) -2. Test emphasis syntax: `(keyword:1.5)` -3. Test alternations: `{option1|option2}` -4. Verify no settings appear in output -5. Check tooltip displays correctly - -**All bugs fixed and features added!** 🎉 diff --git a/docs/TESTING_GUIDE_V161.md b/docs/TESTING_GUIDE_V161.md deleted file mode 100644 index 0d693a2..0000000 --- a/docs/TESTING_GUIDE_V161.md +++ /dev/null @@ -1,276 +0,0 @@ -# Testing Guide for v1.6.1 Bug Fixes - -## Overview -Version 1.6.1 fixes three critical bugs in the Text-to-Image Prompt Enhancer node: -1. ✅ **Settings Leakage**: Fixed settings appearing in output with `| Settings:` separator -2. ✅ **Emphasis Syntax**: Fixed `(keyword:weight)` being broken by LLM processing -3. ✅ **Alternation Syntax**: Added support for `{option1|option2|option3}` random selection - -## Testing Status -- ✅ All unit tests passed -- ✅ Code compilation verified -- ⏳ **User testing in ComfyUI required** - ---- - -## Installation Steps - -1. **Restart ComfyUI** - - Close ComfyUI completely - - Restart to load the updated node code - -2. **Verify Node Appears** - - Look for "Eric Prompt Enhancers" category - - Should see "Text-to-Image Prompt Enhancer" - ---- - -## Test Cases - -### Test 1: Emphasis Syntax (Weight Preservation) -**What to test**: The node should preserve `(keyword:weight)` syntax exactly as entered - -**Example prompts**: -``` -a woman with (dark skin:1.5) and (detailed face:1.3) -``` -``` -(masterpiece:1.4), (best quality:1.2), portrait of a cat -``` -``` -forest landscape with (dramatic lighting:1.8) and (fog:0.6) -``` - -**Expected behavior**: -- ✅ Input: `a woman with (dark skin:1.5)` -- ✅ Output should contain: `(dark skin:1.5)` ← Weight syntax preserved -- ❌ **OLD BUG**: Would output `dark skin (1.5)` ← Weight broken - -**How to verify**: -1. Enter a prompt with `(keyword:number)` emphasis -2. Run the node -3. Check the enhanced output -4. Verify the `(keyword:number)` format is **exactly preserved** - ---- - -### Test 2: Alternation Syntax (Random Selection) -**What to test**: The node should randomly select one option from `{a|b|c}` expressions - -**Example prompts**: -``` -a {cat|dog|rabbit} in the garden -``` -``` -{red|blue|green|yellow} dress on a {tall|short} woman -``` -``` -portrait of a person with {blonde|brunette|red|black} hair and {blue|green|brown} eyes -``` - -**Expected behavior**: -- ✅ Input: `a {cat|dog|rabbit} in the garden` -- ✅ Output might be: `a cat in the garden` OR `a dog in the garden` OR `a rabbit in the garden` -- Each run should potentially give different random selections - -**How to verify**: -1. Enter a prompt with `{option1|option2|option3}` syntax -2. Run the node multiple times -3. Observe different random selections each time -4. The `{}` brackets should be removed in output - ---- - -### Test 3: Settings Cleanup (No Leakage) -**What to test**: The node should NOT include settings information in the prompt output - -**Settings to test with**: -- Try different camera angles (low angle, high angle, eye level) -- Try different lighting options (golden hour, soft, dramatic) -- Try different shot types (close-up, full body, portrait) - -**Example configuration**: -``` -Prompt: a woman in a garden -Camera Angle: low angle -Lighting: golden hour -Shot Type: close-up -``` - -**Expected behavior**: -- ✅ Output: Enhanced prompt describing woman, garden, mood, details -- ❌ Output should **NOT contain**: `| Settings: camera angle: low angle` or similar - -**OLD BUG example**: -``` -beautiful woman in lush garden with detailed flowers and soft atmosphere | Settings: camera angle: low angle; lighting: golden hour; shot type: close-up -``` -☝️ This should NO LONGER happen! - -**How to verify**: -1. Enter any prompt -2. Change camera angle, lighting, and shot type settings -3. Run the node -4. Check the enhanced output -5. Verify NO settings information appears in the prompt - ---- - -### Test 4: Combined Features -**What to test**: All three features should work together correctly - -**Example prompts**: -``` -{red|blue|purple} (dress:1.3) on a {tall|short} woman with (detailed face:1.5) -``` -``` -a {cat|dog} with (fluffy fur:1.4) in a {garden|park|field} -``` - -**Expected behavior**: -1. Alternations `{}` are processed first (random selection) -2. Emphasis `()` is preserved through LLM enhancement -3. Settings do NOT appear in output - -**Example flow**: -- **Input**: `{red|blue} (dress:1.3) on a woman` -- **After alternation**: `blue (dress:1.3) on a woman` (red randomly chosen) -- **Emphasis protected during LLM**: `(dress:1.3)` wrapped safely -- **After LLM**: Enhanced description with `(dress:1.3)` intact -- **Final output**: `elegant blue (dress:1.3) on a confident woman, detailed fashion photography` ← No settings info! - ---- - -## Platform-Specific Testing - -Test with different platforms to ensure compatibility: - -### Flux (Natural Language) -``` -Prompt: a {cat|dog} with (detailed fur:1.4) -Platform: flux -``` - -### Pony Diffusion (Booru Tags) -``` -Prompt: 1girl, {red hair|blonde hair|black hair}, (detailed face:1.3) -Platform: pony -``` - -### SDXL (Detailed Descriptions) -``` -Prompt: portrait of a {young|elderly} person with (dramatic lighting:1.5) -Platform: sdxl -``` - ---- - -## What to Report - -If you find any issues, please note: - -1. **Which bug occurred**: - - Settings appearing in output? - - Emphasis syntax broken? - - Alternation not working? - -2. **Your test prompt**: Exact text you entered - -3. **Settings used**: Platform, camera angle, lighting, etc. - -4. **Expected output**: What should have happened - -5. **Actual output**: What actually happened - -6. **Screenshot**: If possible, capture the node and output - ---- - -## Known Behaviors (Not Bugs) - -### Alternation is Random -- Each run with `{a|b|c}` will randomly pick one option -- This is intentional for variety in prompt generation -- If you want consistent results, don't use alternation syntax - -### LLM May Rephrase -- The LLM will enhance and rephrase your prompt -- This is normal and expected behavior -- The emphasis weights `(keyword:1.5)` will be preserved even if surrounding text changes - -### Settings Are Incorporated -- Settings (camera angle, lighting, shot type) ARE used by the LLM -- They influence the enhancement style and content -- They just shouldn't appear as literal text in the output - ---- - -## Testing Checklist - -Use this checklist when testing: - -- [ ] Restart ComfyUI -- [ ] Node appears in "Eric Prompt Enhancers" category -- [ ] Test emphasis syntax: `(keyword:1.5)` preserved -- [ ] Test alternation syntax: `{a|b|c}` randomly selected -- [ ] Test settings cleanup: No `| Settings:` in output -- [ ] Test combined features: All work together -- [ ] Test with different platforms (Flux, Pony, SDXL) -- [ ] Test with complex prompts -- [ ] Multiple runs show variety (alternation randomness) - ---- - -## Success Criteria - -v1.6.1 is working correctly if: - -1. ✅ **Emphasis weights are preserved exactly**: `(dark skin:1.5)` stays as `(dark skin:1.5)` -2. ✅ **Alternations are processed**: `{cat|dog}` becomes either `cat` or `dog` -3. ✅ **No settings leakage**: Output never contains `| Settings:` or `Settings:` -4. ✅ **All features work together**: Can use both emphasis and alternation in same prompt - ---- - -## Quick Test Script - -Copy-paste this into the node to test all features at once: - -``` -a {beautiful|stunning|elegant} woman with (detailed face:1.5) and {red|blonde|dark} (hair:1.3) in a {garden|forest|meadow} -``` - -**Platform**: flux -**Camera Angle**: low angle -**Lighting**: golden hour - -**Expected**: -- One color chosen from each `{}` -- Both `(detailed face:1.5)` and `(hair:1.3)` preserved -- No settings text in output -- Enhanced natural language description - ---- - -## Files Modified - -- `text_to_image_node.py` - Main bug fixes -- `BUGFIX_V161.md` - Technical documentation -- `test_txt2img_bugfixes.py` - Unit tests (all passed ✅) - ---- - -## Support - -If issues persist after testing: -1. Check `BUGFIX_V161.md` for technical details -2. Verify ComfyUI was restarted -3. Check console for any error messages -4. Report findings with details listed above - ---- - -**Version**: 1.6.1 -**Date**: 2025 -**Status**: Ready for User Testing -**Previous Issues**: All resolved in unit tests ✅ diff --git a/docs/archive/BUGFIX_AUTO_MODE.md b/docs/archive/BUGFIX_AUTO_MODE.md deleted file mode 100644 index 7242f76..0000000 --- a/docs/archive/BUGFIX_AUTO_MODE.md +++ /dev/null @@ -1,160 +0,0 @@ -# Bug Fix: Auto Mode Empty Output - RESOLVED - -## The Problem - -When `expansion_tier` was set to "auto", the node would: -- ✅ Call the LLM successfully -- ✅ LLM would generate a response -- ❌ But output would be empty in ComfyUI - -**Root Cause:** Aggressive response parsing was removing too much content, leaving empty output. - -## The Fix (Version 1.2.1) - -### 1. ✅ Fixed expansion_engine.py - `parse_llm_response()` method - -**Added safety fallback:** -```python -# CRITICAL FIX: If cleaning left us with nothing or very little, use the original -if not cleaned or len(cleaned) < 50: - print(f"WARNING: Aggressive parsing removed too much content. Using original response.") - cleaned = original_response.strip() - - # At least try to remove obvious prefix markers - for marker in ["expanded prompt:", "enhanced prompt:", "output:"]: - if cleaned.lower().startswith(marker): - cleaned = cleaned[len(marker):].strip() -``` - -**Now:** If aggressive cleaning removes everything, we use the original response instead of returning empty. - -### 2. ✅ Updated prompt_expander_node.py - Show detected tier - -**Status now displays:** -- Before: `Tier: auto` -- After: `Tier: auto→enhanced` (shows what auto selected) - -**Breakdown now shows:** -``` -Tier Setting: auto (detected: enhanced) -``` - -### 3. ✅ Added validation check - -**Added check for empty output:** -```python -if not enhanced_prompt or len(enhanced_prompt) < 20: - return (..., "ERROR: LLM returned empty or very short response", ...) -``` - -Now you'll see exactly what went wrong if output is still empty. - -## How Auto Mode Works - -**Auto mode analyzes your input and picks the best tier:** - -| Input Complexity | Auto Selects | -|-----------------|--------------| -| Simple, < 10 words, no technical terms | **basic** (150-250 words) | -| Moderate, < 25 words | **enhanced** (250-400 words) | -| Complex, < 50 words or has technical terms | **advanced** (400-600 words) | -| Very complex, > 50 words | **cinematic** (600-1000 words) | - -**Examples:** -- `"cat playing piano"` → auto selects **basic** -- `"weathered detective in dimly lit office"` → auto selects **enhanced** -- `"The camera slowly dollies in on the protagonist"` → auto selects **advanced** (has technical terms) -- `"A complex multi-paragraph description..."` → auto selects **cinematic** - -## Testing the Fix - -### Test 1: Auto Mode -``` -Input: "cat playing piano" -expansion_tier: auto -Expected: - - Status shows "Tier: auto→basic" or "auto→enhanced" - - Breakdown shows detected tier - - Output is NOT empty -``` - -### Test 2: Manual Tiers -``` -Input: "cat playing piano" -expansion_tier: advanced -Expected: - - Status shows "Tier: advanced" - - Output is detailed (400-600 words) -``` - -### Test 3: Check Breakdown -``` -Look at the breakdown output: -- Should show "Tier Setting: auto (detected: X)" if auto used -- Or "Detected Tier: X" if manual tier selected -``` - -## What Changed - -**Files Modified:** -1. ✅ `expansion_engine.py` - Safer parsing with fallback -2. ✅ `prompt_expander_node.py` - Show detected tier in status -3. ✅ `prompt_expander_node_advanced.py` - Same fixes - -**Backwards Compatible:** ✅ Yes, no breaking changes - -## If Auto Mode Still Has Issues - -If you still get empty output with auto mode: - -### 1. Check the Breakdown Output -It will show what tier was detected. Try using that tier manually to see if it works. - -### 2. Check Console/Terminal -The fix now prints warnings when content is removed: -``` -WARNING: Aggressive parsing removed too much content. Using original response. -``` - -### 3. Try Different Temperature -Lower temperature (0.4-0.6) = better instruction following - -### 4. Try Different Model -Some models follow instructions better than others: -- ✅ Llama 3.1, Qwen, Command-R -- ⚠️ Smaller 7B models may struggle - -### 5. Use Manual Tier -If auto detection picks wrong tier: -- See what it detected in breakdown -- Use manual tier selection instead -- Report which tier auto chose vs what works - -## Restart Required - -**YES** - Restart ComfyUI to load the fixes: -1. Close ComfyUI -2. Restart -3. Test auto mode again -4. Check status output for "auto→X" display - -## Summary - -**Problem:** Auto mode produced empty output due to over-aggressive parsing - -**Solution:** -- Added safety fallback in parsing -- Show detected tier to user -- Added validation checks -- Better error messages - -**Result:** Auto mode now works reliably and shows what it selected! - ---- - -**Version:** 1.2.1 -**Status:** Bug Fixed ✅ -**Files:** 3 files updated -**Restart:** Required - -Try it now - auto mode should work! diff --git a/docs/archive/FILE_CHANGES.md b/docs/archive/FILE_CHANGES.md deleted file mode 100644 index d4d470d..0000000 --- a/docs/archive/FILE_CHANGES.md +++ /dev/null @@ -1,294 +0,0 @@ -# File Changes Summary - Eric's Prompt Enhancers v1.6 - -## Files Modified - -### 1. __init__.py -**Changes:** -- Updated node registration names (added "Eric" prefix) -- Changed display names to remove redundant prefixes -- Added import for new text_to_image_node -- Updated all categories to "Eric Prompt Enhancers" - -**Status:** ✅ Compiles successfully - ---- - -### 2. platforms.py -**Changes:** -- Added 4 new platform configurations: - - pony (Pony Diffusion with score system) - - illustrious (Illustrious XL anime model) - - chroma (Meissonic/MeissonFlow complex scenes) - - wan_image (Wan Image technical cinematography) -- Updated negative prompt function with new platforms -- Added platform-specific requirements (required_positive tokens) - -**Status:** ✅ Compiles successfully - ---- - -### 3. prompt_expander_node.py -**Changes:** -- Changed CATEGORY from "video/prompting" to "Eric Prompt Enhancers" - -**Status:** ✅ Already working, now categorized correctly - ---- - -### 4. prompt_expander_node_advanced.py -**Changes:** -- Changed CATEGORY from "video/prompting" to "Eric Prompt Enhancers" - -**Status:** ✅ Already working, now categorized correctly - ---- - -### 5. image_to_video_node.py -**Changes:** -- Changed CATEGORY from "video/prompting" to "Eric Prompt Enhancers" - -**Status:** ✅ Already working, now categorized correctly - ---- - -### 6. image_to_image_node.py -**Changes:** -- Changed CATEGORY from "image/prompting" to "Eric Prompt Enhancers" - -**Status:** ✅ FIXED - Now appears in ComfyUI - ---- - -### 7. README.md -**Changes:** -- Updated title to "Eric's Prompt Enhancers" -- Added overview of all 5 nodes -- Added new platform information -- Updated installation instructions -- Added Text-to-Image features - -**Status:** ✅ Updated - ---- - -## Files Created - -### 1. text_to_image_node.py ⭐ NEW -**Description:** Advanced text-to-image prompt enhancer with multi-platform support - -**Features:** -- 8 platform support (Flux, SDXL, Pony, Illustrious, Chroma, Qwen, Wan) -- Advanced aesthetic controls (camera, lighting, weather, time, etc.) -- Wildcard random options -- Optional reference images (1-2 inputs) -- Platform-specific formatting and token optimization -- Custom keywords support -- File saving with metadata - -**Lines of Code:** 864 lines -**Status:** ✅ Compiles successfully, ready to use - ---- - -### 2. TXT2IMG_GUIDE.md ⭐ NEW -**Description:** Complete guide for Text-to-Image Prompt Enhancer - -**Contents:** -- Overview and platform descriptions -- Platform-specific examples (Flux, SDXL, Pony, Illustrious, etc.) -- Quick start workflows -- All control options explained -- Wildcard usage -- Troubleshooting -- Best practices per platform -- FAQ section - -**Pages:** ~20 pages of documentation -**Status:** ✅ Complete - ---- - -### 3. UPDATE_V16_ERIC.md ⭐ NEW -**Description:** Version 1.6 update notes - -**Contents:** -- What's new summary -- Platform-specific details -- File structure changes -- All nodes overview -- Quick start guide -- Example workflows -- Platform selection guide -- Troubleshooting - -**Status:** ✅ Complete - ---- - -### 4. QUICK_REFERENCE.md ⭐ NEW -**Description:** Quick reference guide for all nodes - -**Contents:** -- How to find nodes -- Platform selection tables -- Quick workflows for each node -- Control options -- Common settings -- Platform examples -- Troubleshooting -- Tips for best results - -**Status:** ✅ Complete - ---- - -### 5. SETUP_COMPLETE.md ⭐ NEW -**Description:** Setup completion summary and next steps - -**Contents:** -- What's been done checklist -- Next steps to use nodes -- Platform-specific critical notes -- Platform selection guide -- Troubleshooting -- Quick examples -- Advanced features overview - -**Status:** ✅ Complete - ---- - -## Summary Statistics - -### Code Files: -- **Modified:** 6 files -- **Created:** 1 file (text_to_image_node.py) -- **Total new code:** ~864 lines -- **Compile status:** ✅ All files compile without errors - -### Documentation Files: -- **Modified:** 1 file (README.md) -- **Created:** 4 files (guides and references) -- **Total documentation:** ~50+ pages - -### Platforms Supported: -- **Video:** Wan 2.2 video model -- **Image (existing):** Flux, SDXL, Wan 2.2, Hunyuan Image, Qwen Image, Qwen Edit -- **Image (new):** Pony Diffusion, Illustrious XL, Chroma/Meissonic, Wan Image -- **Total platforms:** 8 unique image platforms + video - -### Features Added: -- ✅ Multi-platform text-to-image enhancement -- ✅ Advanced aesthetic controls (camera, lighting, weather, time) -- ✅ Wildcard random options -- ✅ Optional reference image inputs -- ✅ Platform-specific token optimization -- ✅ Pony Diffusion support (booru tags + score system) -- ✅ Illustrious XL support (anime tags) -- ✅ Chroma/Meissonic support (complex scenes) -- ✅ All nodes rebranded and organized - ---- - -## Testing Checklist - -### Before Using: -- [ ] Restart ComfyUI completely -- [ ] Verify LM Studio or Ollama is running -- [ ] Load appropriate model in LLM backend -- [ ] Check console for any errors - -### First Test: -- [ ] Find "Eric Prompt Enhancers" category -- [ ] All 5 nodes appear -- [ ] Text-to-Image node loads without errors -- [ ] Simple prompt test works - -### Platform Tests: -- [ ] Flux: Natural language output -- [ ] SDXL: Token-optimized, front-loaded -- [ ] Pony: score_9, score_8_up tags present -- [ ] Illustrious: masterpiece, best quality tags -- [ ] Chroma: Long detailed descriptions -- [ ] Qwen: Balanced natural language -- [ ] Wan Image: Technical cinematography terms - ---- - -## Known Issues / Notes - -### None Currently -All files compile and are ready to use. Image-to-Image node issue was resolved by updating the category. - -### Platform-Specific Requirements - -**Pony Diffusion - CRITICAL:** -- MUST start with: score_9, score_8_up, score_7_up -- MUST use underscores: long_hair NOT "long hair" -- Negative MUST include: score_6, score_5, score_4 - -**Illustrious XL - IMPORTANT:** -- MUST start with: masterpiece, best quality -- Use underscores in multi-word tags -- Character count tags: 1girl, 1boy, etc. - -**All handled automatically by the node when platform is selected correctly.** - ---- - -## Next Development Steps (Future) - -### Potential Enhancements: -1. Vision model support for reference images (text-to-image node) -2. Additional platforms as they emerge -3. Preset saving/loading system -4. Batch processing features -5. Style transfer reference capabilities - -### Platform Examples to Document: -- More Pony examples with different subjects -- Illustrious character design examples -- Chroma complex scene examples -- Platform comparison outputs - ---- - -## File Locations - -All files located in: -``` -ComfyUI/custom_nodes/video_prompter/ -``` - -**Code:** -- text_to_image_node.py (NEW) -- platforms.py (UPDATED) -- __init__.py (UPDATED) -- [other node files] (UPDATED categories) - -**Documentation:** -- TXT2IMG_GUIDE.md (NEW) -- UPDATE_V16_ERIC.md (NEW) -- QUICK_REFERENCE.md (NEW) -- SETUP_COMPLETE.md (NEW) -- README.md (UPDATED) -- [existing guides remain] - ---- - -## Verification Commands - -```powershell -# Verify all Python files compile -python -m py_compile text_to_image_node.py -python -m py_compile platforms.py -python -m py_compile __init__.py - -# All should complete without errors ✅ -``` - ---- - -**Setup Status: ✅ COMPLETE AND READY TO USE** - -Restart ComfyUI and find all nodes under "Eric Prompt Enhancers"! diff --git a/docs/archive/GITHUB_PUBLICATION_COMPLETE.md b/docs/archive/GITHUB_PUBLICATION_COMPLETE.md deleted file mode 100644 index 0dd24ea..0000000 --- a/docs/archive/GITHUB_PUBLICATION_COMPLETE.md +++ /dev/null @@ -1,376 +0,0 @@ -# GitHub Publication Checklist - Complete! ✅ - -## Date: October 16, 2025 - ---- - -## ✅ All Tasks Completed - -### 1. ✅ License Headers Added -- **__init__.py**: Full dual-license header with dependencies and credits -- All dependency licenses documented: - - Python (PSF License) - - PyTorch (BSD-style) - - NumPy (BSD) - - Pillow (HPND) - - requests (Apache 2.0) - - ComfyUI (GPL-3.0) - - LM Studio (Proprietary) - - Ollama (MIT) -- Platform credits included: - - Flux, SDXL, Pony, Illustrious, Chroma, Qwen, Wan - -### 2. ✅ README.md Created -- **Comprehensive README** with: - - Clear feature descriptions - - Installation instructions (git clone + manual) - - LLM setup guide (LM Studio + Ollama) - - Quick start examples - - Platform comparison table - - Use case examples - - Troubleshooting section - - Version history summary - - Credits and acknowledgments - - Support information -- **Badges**: License, Version, ComfyUI Compatible -- **Professional formatting**: Clear sections, tables, code blocks -- **Length**: ~800 lines, comprehensive yet readable - -### 3. ✅ LICENSE File Created -- **Dual License Agreement**: - - Creative Commons Attribution-NonCommercial 4.0 (NC) - - Commercial license available on request -- **Clear definitions**: Non-commercial vs commercial use -- **Disclaimer of warranty**: Standard liability protection -- **Third-party dependencies**: All licenses listed -- **Attribution requirements**: Clear guidelines -- **Contact information**: Email and GitHub - -### 4. ✅ CHANGELOG.md Updated -- **Complete version history**: v1.0.0 through v1.7.0 -- **Detailed entries** for each version: - - v1.7.0: Enhanced controls, reference image fixes - - v1.6.1: Critical bug fixes - - v1.6.0: Text-to-image node - - v1.5.0: Image-to-image node - - v1.3.0: Image-to-video node - - v1.2.0: Advanced node - - v1.0.0: Initial release -- **Version summary table** -- **Planned features list** -- **Migration notes** between versions -- **Technical requirements** -- **Credits section** - -### 5. ✅ requirements.txt Updated -- **Core dependency**: requests>=2.25.0 -- **Optional dependencies noted**: PyTorch, NumPy, Pillow (usually with ComfyUI) -- **LLM backends noted**: LM Studio, Ollama (install separately) -- **Clear comments**: Explains what's needed vs already installed - -### 6. ✅ Documentation Organized -- **Created docs/ folder** -- **Moved all guides**: - - BUGFIX_AUTO_MODE.md - - BUGFIX_V161.md - - CONFIGURATION.md - - IMG2IMG_GUIDE.md - - LM_STUDIO_SETUP.md - - NODE_COMPARISON.md - - QUICKSTART.md - - QUICK_REFERENCE.md - - QUICK_REF_V17.md - - TESTING_GUIDE_V161.md - - TXT2IMG_GUIDE.md - - UPDATE_NOTES.md - - UPDATE_V13.md, V15.md, V16_ERIC.md, V17_ENHANCED_CONTROLS.md - - WAN_GUIDE_REFERENCE.md - - WILDCARD_GUIDE.md - - FILE_CHANGES.md, SETUP_COMPLETE.md - - README_OLD.md (backup) - -### 7. ✅ Test Files Removed -- **Deleted**: test_setup.py -- **Deleted**: test_txt2img_bugfixes.py -- **Kept in repo**: __pycache__ (can be gitignored) - ---- - -## 📁 Final Repository Structure - -``` -video_prompter/ -├── README.md ← Main repository intro -├── LICENSE ← Dual license terms -├── CHANGELOG.md ← Version history -├── requirements.txt ← Python dependencies -├── __init__.py ← Node registration (licensed) -│ -├── docs/ ← All documentation -│ ├── README_OLD.md ← Old README backup -│ ├── QUICKSTART.md ← Fast start guide -│ ├── LM_STUDIO_SETUP.md ← LLM backend setup -│ ├── CONFIGURATION.md ← Node configuration -│ ├── TXT2IMG_GUIDE.md ← Text-to-image (20+ pages) -│ ├── IMG2IMG_GUIDE.md ← Image-to-image guide -│ ├── WAN_GUIDE_REFERENCE.md ← Wan platform guide -│ ├── WILDCARD_GUIDE.md ← Random wildcards -│ ├── QUICK_REFERENCE.md ← Fast lookup -│ ├── QUICK_REF_V17.md ← v1.7 features -│ ├── NODE_COMPARISON.md ← Which node to use -│ ├── TESTING_GUIDE_V161.md ← v1.6.1 testing -│ ├── BUGFIX_V161.md ← v1.6.1 fixes -│ ├── BUGFIX_AUTO_MODE.md ← Auto mode fixes -│ ├── UPDATE_V17_ENHANCED_CONTROLS.md ← v1.7 update notes -│ ├── UPDATE_V16_ERIC.md ← v1.6 rebranding -│ ├── UPDATE_V15.md, V13.md ← Earlier updates -│ ├── UPDATE_NOTES.md, UPDATE_NOTES_V12.md -│ ├── FILE_CHANGES.md -│ └── SETUP_COMPLETE.md -│ -├── Core Node Files (All Python) -│ ├── prompt_expander_node.py ← Video prompt expander -│ ├── prompt_expander_node_advanced.py ← Advanced video node -│ ├── image_to_video_node.py ← Image-to-video node -│ ├── image_to_image_node.py ← Image-to-image node -│ └── text_to_image_node.py ← Text-to-image node (v1.7) -│ -├── Supporting Modules -│ ├── expansion_engine.py ← Video prompt expansion logic -│ ├── img2img_expansion_engine.py ← Img2img expansion logic -│ ├── llm_backend.py ← LLM API interface -│ ├── platforms.py ← Platform configurations -│ ├── presets.py ← Style presets -│ └── utils.py ← Helper functions -│ -└── .gitignore ← Git ignore rules - .history/ ← History folder - __pycache__/ ← Python cache (should be gitignored) -``` - ---- - -## 🎯 Repository Ready For - -### ✅ GitHub Publication -- [x] Professional README with badges -- [x] Clear installation instructions -- [x] License file with dual licensing -- [x] Complete changelog -- [x] Requirements file -- [x] Organized documentation -- [x] Clean root directory -- [x] All files licensed - -### ✅ User Friendly -- [x] Quick start guide -- [x] Comprehensive documentation -- [x] Troubleshooting section -- [x] Examples and use cases -- [x] Platform comparison -- [x] Clear versioning - -### ✅ Developer Friendly -- [x] Modular code structure -- [x] Clear dependencies -- [x] Version history -- [x] Migration notes -- [x] Credits and licenses - -### ✅ Legal Protection -- [x] Dual license (NC + Commercial) -- [x] Copyright notices -- [x] Warranty disclaimers -- [x] Attribution requirements -- [x] Contact information - ---- - -## 🚀 Next Steps for Publication - -### 1. Create GitHub Repository -```bash -# On GitHub: Create new repository "video_prompter" -# Or use your preferred name: "comfyui-prompt-enhancers" -``` - -### 2. Initialize Git (if not already) -```bash -cd A:\Comfy25\ComfyUI_windows_portable\ComfyUI\custom_nodes\video_prompter -git init -``` - -### 3. Create .gitignore (if needed) -``` -__pycache__/ -*.pyc -*.pyo -.DS_Store -.history/ -output/ -*.log -``` - -### 4. Initial Commit -```bash -git add . -git commit -m "Initial release v1.7.0 - Eric's Prompt Enhancers for ComfyUI" -``` - -### 5. Push to GitHub -```bash -git remote add origin https://github.com/EricRollei/video_prompter.git -git branch -M main -git push -u origin main -``` - -### 6. Create Release (on GitHub) -- **Tag**: v1.7.0 -- **Title**: Eric's Prompt Enhancers v1.7.0 - Enhanced Controls -- **Description**: Copy from CHANGELOG.md v1.7.0 section -- **Attach**: ZIP of repository (optional) - -### 7. Update Repository Settings (on GitHub) -- **Description**: "AI-powered prompt enhancement nodes for ComfyUI using local LLMs" -- **Topics**: `comfyui`, `ai`, `llm`, `prompt-engineering`, `image-generation`, `video-generation` -- **Website**: Your website/portfolio (optional) -- **License**: Other (Dual License) - ---- - -## 📋 Pre-Publication Checklist - -- [x] All Python files have license headers -- [x] README is comprehensive and professional -- [x] LICENSE file is clear and complete -- [x] CHANGELOG is detailed and up-to-date -- [x] requirements.txt is accurate -- [x] Documentation is organized in docs/ -- [x] Test files removed -- [x] Root directory is clean -- [x] All dependencies credited -- [x] Contact information provided -- [x] Version number consistent (1.7.0) -- [x] Code compiles without errors -- [x] No sensitive information (API keys, etc.) - ---- - -## 🎉 What's Included - -### 5 Nodes -1. **Video Prompt Expander** - Simple presets -2. **Video Prompt Expander (Advanced)** - 50+ controls -3. **Image-to-Video Prompt Expander** - Vision analysis -4. **Image-to-Image Prompt Expander** - 5 platforms -5. **Text-to-Image Prompt Enhancer** - 8 platforms (v1.7) - -### 8 Image Platforms -- Flux, SDXL, Pony Diffusion, Illustrious XL -- Chroma/Meissonic, Qwen Image, Qwen Edit, Wan Image - -### Features -- Local LLM support (LM Studio, Ollama) -- Reference image analysis -- Genre/style control (22 options) -- Prompt length control (6 sizes) -- Subject framing (14 types) -- Subject pose (17 options) -- Emphasis syntax: `(keyword:1.5)` -- Alternation syntax: `{a|b|c}` -- Platform-specific optimization -- Keyword integration -- File export with metadata - -### Documentation -- 20+ markdown guides -- Quick start guide -- Platform comparisons -- Use case examples -- Troubleshooting -- Version notes - ---- - -## 📊 Statistics - -- **Total Nodes**: 5 -- **Total Platforms**: 13 (8 image, 5 video/img2img) -- **Python Files**: 11 core + 1 init -- **Documentation Files**: 20+ guides -- **Lines of README**: ~800 -- **Version**: 1.7.0 -- **License**: Dual (NC + Commercial) - ---- - -## ✉️ Repository Information - -### Suggested Repository Name -- **Primary**: `video_prompter` (current folder name) -- **Alternative**: `comfyui-prompt-enhancers` -- **Alternative**: `eric-prompt-enhancers` - -### Suggested GitHub URL -- `https://github.com/EricRollei/video_prompter` - -### Suggested Topics/Tags -- comfyui -- ai -- llm -- prompt-engineering -- image-generation -- video-generation -- stable-diffusion -- flux -- local-llm -- lm-studio -- ollama - -### Suggested Description -"AI-powered prompt enhancement nodes for ComfyUI using local LLMs. Transform simple prompts into detailed, platform-optimized descriptions for video and image generation. Supports 8 image platforms including Flux, SDXL, Pony, and more." - ---- - -## 🎯 Marketing Points - -### For Users -- **Privacy**: Everything runs locally -- **Control**: 100+ combined settings -- **Quality**: Platform-optimized outputs -- **Flexibility**: Works with multiple LLMs -- **Free**: Non-commercial use - -### For Developers -- **Clean Code**: Modular, well-documented -- **Extensible**: Easy to add platforms -- **Type-Safe**: Type hints throughout -- **Well-Tested**: Bug fixes in v1.6.1 - -### For Commercial -- **Available**: Commercial license on request -- **Support**: Direct contact with author -- **Stable**: v1.7.0 production-ready -- **Maintained**: Regular updates - ---- - -## ✅ Publication Ready! - -**Everything is prepared for GitHub publication!** - -The repository is: -- ✅ Professionally structured -- ✅ Legally compliant -- ✅ Well documented -- ✅ User friendly -- ✅ Ready to publish - -**You can now publish to GitHub whenever you're ready!** - ---- - -**Prepared by**: AI Assistant -**Date**: October 16, 2025 -**Version**: 1.7.0 -**Status**: ✅ READY FOR PUBLICATION diff --git a/docs/archive/README_OLD.md b/docs/archive/README_OLD.md deleted file mode 100644 index 242d43c..0000000 --- a/docs/archive/README_OLD.md +++ /dev/null @@ -1,303 +0,0 @@ -# Eric's Prompt Enhancers for ComfyUI - -A comprehensive suite of AI-powered prompt enhancement nodes for ComfyUI using local LLMs (LM Studio or Ollama). Transform simple prompts into detailed, platform-optimized descriptions for video and image generation. - -## 🎯 All Nodes (Under "Eric Prompt Enhancers" Category) - -### 1. Video Prompt Expander -Simple video prompt expansion with presets and expansion tiers. - -### 2. Video Prompt Expander (Advanced) -Granular control over video aesthetics with detailed settings. - -### 3. Image-to-Video Prompt Expander -Vision model analyzes images and adds motion descriptions. - -### 4. Image-to-Image Prompt Expander -Platform-aware image-to-image prompt generation (Flux, SDXL, Hunyuan, Qwen, Wan). - -### 5. Text-to-Image Prompt Enhancer ⭐ NEW -Advanced multi-platform image prompt enhancement with extensive controls. - -**Supports:** Flux, SDXL, Pony Diffusion, Illustrious XL, Chroma, Qwen Image, Qwen Edit, Wan Image - -## ✨ Key Features - -### Video Nodes -- 🎬 **5 Expansion Tiers**: Auto, Basic, Enhanced, Advanced, Cinematic -- 🎨 **6 Style Presets**: Cinematic, Surreal, Action, Stylized, Noir, Random -- 🎯 **Auto-Detection**: Analyzes input complexity -- 🔄 **Multiple Variations**: Generate up to 3 variations -- � **Vision Support**: Analyze images for video generation - -### Image Nodes (NEW!) -- 🖼️ **8 Platform Support**: Flux, SDXL, Pony, Illustrious, Chroma, Qwen, Wan -- 🎨 **Advanced Controls**: Camera, lighting, weather, time of day -- � **Wildcard Random**: Auto-variety in batch generation -- 📸 **Reference Images**: Optional 1-2 image inputs -- 🏷️ **Platform-Specific**: Automatic token optimization per platform - -### Universal -- 🤖 **Local LLM Support**: LM Studio and Ollama -- 📝 **Keyword Integration**: Add LoRA triggers and custom terms -- � **File Export**: Save prompts with metadata -- ➖ **Smart Negatives**: Platform-optimized negative prompts - -## Installation - -1. Navigate to your ComfyUI custom nodes directory: -```bash -cd ComfyUI/custom_nodes/ -``` - -2. The node is already installed in: `video_prompter/` - -3. Restart ComfyUI - -4. All nodes will appear under: **Add Node → Eric Prompt Enhancers** - -## Requirements - -### Python Dependencies -```bash -pip install requests -``` - -### LLM Backend Setup - -**Option 1: LM Studio** -1. Download from: https://lmstudio.ai/ -2. Load a model (recommended: Llama 3 or similar) -3. Start the server (default: http://localhost:1234) - -**Option 2: Ollama** -1. Install from: https://ollama.ai/ -2. Pull a model: `ollama pull llama3` -3. Server runs automatically (default: http://localhost:11434) - -## Node Inputs - -### Core Inputs -- **basic_prompt**: Your simple video idea -- **preset**: Style preset (custom/cinematic/surreal/action/stylized/noir/random) -- **expansion_tier**: Detail level (auto/basic/enhanced/advanced/cinematic) -- **mode**: text-to-video or image-to-video - -### LLM Configuration -- **llm_backend**: lm_studio or ollama -- **model_name**: Model identifier (e.g., "llama3") -- **api_endpoint**: API URL (default LM Studio: http://localhost:1234/v1) -- **temperature**: 0.1-2.0 (lower = focused, higher = creative) - -### Keywords -- **positive_keywords**: Comma-separated must-include terms (LoRA triggers, etc.) -- **negative_keywords**: Comma-separated terms to avoid - -### Output Options -- **num_variations**: Generate 1-3 variations -- **save_to_file**: Save prompts to disk -- **filename_base**: Base name for saved files - -## Node Outputs - -1. **positive_prompt_1**: First enhanced prompt -2. **positive_prompt_2**: Second variation (if requested) -3. **positive_prompt_3**: Third variation (if requested) -4. **negative_prompt**: Auto-generated negative prompt -5. **breakdown**: Detailed analysis of expansion -6. **status**: Success/error messages and file save location - -## Expansion Tiers - -### Basic -**Formula**: Subject + Scene + Motion -- Simple expansion with essential details -- Clear subject, setting, and action -- ~50-100 words - -### Enhanced -**Formula**: Subject + Scene + Motion + Basic Aesthetics -- Detailed descriptions with characteristics -- Basic shot size and lighting -- ~100-200 words - -### Advanced -**Formula**: Full Details + Complete Aesthetics + Camera Work -- Professional cinematography terms -- Specific lighting, composition, lens choices -- Camera angles and movements -- ~200-350 words - -### Cinematic -**Formula**: Masterful Description + All Professional Elements -- Director-level shot description -- Complete lighting setup with technical details -- Precise camera movements and choreography -- Color grading and atmospheric elements -- ~350-500+ words - -## Presets Explained - -### Cinematic -Professional film quality with emphasis on lighting, composition, and camera movement. -- Edge lighting, soft lighting, warm colors -- Smooth camera movements -- Professional framing - -### Surreal -Dreamlike, otherworldly aesthetics with unusual elements. -- Unnatural lighting and mixed sources -- Floating, ethereal movements -- Saturated or desaturated colors - -### Action -High-energy, dynamic sequences with rapid motion. -- Fast camera movement, tracking shots -- High contrast, dramatic lighting -- Explosive, kinetic action - -### Stylized -Artistic visual style over realism. -- Strong visual identity -- Consistent color palette -- Graphic, illustrative elements - -### Noir -Dark, moody, high-contrast aesthetic. -- High contrast, hard lighting -- Deep shadows and chiaroscuro -- Desaturated or black and white -- Low angles and dutch angles - -### Random -Randomly selects complementary elements from the Wan 2.2 guide for creative exploration. - -## Usage Examples - -### Example 1: Basic Text-to-Video -``` -Input: "A cat playing piano" -Preset: Cinematic -Tier: Auto (detects "Enhanced") - -Output: "A fluffy orange tabby cat sits at a polished black grand piano in a warmly lit living room. The cat's paws press down on the ivory keys with surprising dexterity. Soft afternoon light streams through a nearby window, creating edge lighting on the cat's fur. Medium close-up shot, eye-level angle. The camera slowly pushes in as the cat continues to play. Warm color palette, soft lighting, clean single shot." -``` - -### Example 2: Image-to-Video with Keywords -``` -Input: "The woman turns and walks toward the camera" -Mode: Image-to-Video -Preset: Noir -Positive Keywords: myLoRA_trigger, detailed_face -Tier: Advanced - -Output: "The woman slowly turns her head, edge lighting creating dramatic shadows across her face, myLoRA_trigger, detailed_face. She begins walking directly toward the camera with deliberate, purposeful steps. Her silhouette is backlit by a single streetlight, creating a strong rim light effect. The camera remains static as she approaches, her features gradually emerging from shadow. High contrast lighting, desaturated colors, low angle shot. The scene has a tense, mysterious atmosphere." -``` - -### Example 3: Multiple Variations for Action -``` -Input: "Superhero landing from the sky" -Preset: Action -Variations: 3 -Tier: Cinematic - -Results in 3 different takes: -- Variation 1: Emphasizes impact crater and dust -- Variation 2: Focuses on dynamic camera arc around landing -- Variation 3: Features slow-motion with particle effects -``` - -## Workflow Integration - -### Basic Workflow -``` -[AI Video Prompt Expander] - ↓ (positive_prompt_1) -[Video Generation Node] - ↓ -[Output] -``` - -### Advanced Workflow with Variations -``` -[AI Video Prompt Expander] (num_variations: 3) - ↓ (positive_prompt_1) → [Video Gen 1] - ↓ (positive_prompt_2) → [Video Gen 2] - ↓ (positive_prompt_3) → [Video Gen 3] - ↓ (negative_prompt) → [All Video Gens] -``` - -## File Output - -When **save_to_file** is enabled, prompts are saved to: -``` -ComfyUI/output/video_prompts/[filename_base]_[timestamp].txt -``` - -File includes: -- Enhanced positive prompt -- Negative prompt -- Detailed breakdown -- Metadata (preset, tier, model, temperature) -- Original input - -## Troubleshooting - -### "Cannot connect to LM Studio/Ollama" -- Ensure LM Studio or Ollama is running -- Check the API endpoint URL -- Verify the model is loaded - -### "Request timed out" -- LLM might be slow on complex prompts -- Try lowering the tier -- Reduce temperature -- Use a smaller/faster model - -### "Missing keywords in output" -- Keywords are automatically appended if missing -- Check the positive_keywords field spelling -- Verify keywords are comma-separated - -### Empty outputs -- Check LLM backend connection -- Review status output for error messages -- Try with a simpler input prompt first - -## Tips for Best Results - -1. **Start Simple**: Begin with basic concepts and let the node expand them -2. **Use Auto Tier**: Let the node detect appropriate complexity -3. **Experiment with Presets**: Different presets dramatically change the output -4. **Adjust Temperature**: Lower (0.3-0.5) for consistency, higher (0.8-1.2) for creativity -5. **Combine Keywords**: Use positive_keywords for LoRA triggers and style terms -6. **Save Good Prompts**: Enable save_to_file to build a library -7. **Generate Variations**: Use multiple variations to explore different interpretations - -## Wan 2.2 Guide Reference - -This node implements the comprehensive Wan 2.2 prompting framework including: - -- **Aesthetic Control**: Lighting sources/types, time of day, shot sizes, composition, lenses, camera angles -- **Dynamic Control**: Motion types, character emotions, camera movements -- **Stylization**: Visual styles (3D, 2D, watercolor, etc.), visual effects - -For more details, see the original guide: https://wan.video/ - -## Credits - -- Based on the Wan 2.2 Video Generation Prompting Guide -- Developed for ComfyUI integration -- Supports LM Studio and Ollama backends - -## Version - -**v1.0** - Initial release with full Wan 2.2 framework integration - -## License - -MIT License - Free to use and modify - ---- - -**Questions or Issues?** Check the status output for detailed error messages, or review the saved prompt files for debugging information. diff --git a/docs/archive/SETUP_COMPLETE.md b/docs/archive/SETUP_COMPLETE.md deleted file mode 100644 index c7340f5..0000000 --- a/docs/archive/SETUP_COMPLETE.md +++ /dev/null @@ -1,268 +0,0 @@ -# SETUP COMPLETE - Eric's Prompt Enhancers - -## ✅ What's Been Done - -### 1. Nodes Rebranded -All nodes now appear under **"Eric Prompt Enhancers"** category in ComfyUI: -- Video Prompt Expander -- Video Prompt Expander (Advanced) -- Image-to-Video Prompt Expander -- Image-to-Image Prompt Expander ✅ FIXED -- Text-to-Image Prompt Enhancer ⭐ NEW - -### 2. New Text-to-Image Node Created -Comprehensive multi-platform image prompt enhancement with: -- ✅ 8 platform support (Flux, SDXL, Pony, Illustrious, Chroma, Qwen, Wan) -- ✅ Advanced controls (camera, lighting, weather, time of day) -- ✅ Wildcard random options -- ✅ Optional reference image inputs (1-2 images) -- ✅ Platform-specific formatting and token optimization - -### 3. Platforms Added -New platforms configured: -- ✅ Pony Diffusion (booru tags, score system) -- ✅ Illustrious XL (anime, detailed tags) -- ✅ Chroma/Meissonic (complex scenes) -- ✅ Wan Image (technical cinematography) - -### 4. Documentation Created -- ✅ TXT2IMG_GUIDE.md - Complete guide with examples -- ✅ UPDATE_V16_ERIC.md - Version update notes -- ✅ QUICK_REFERENCE.md - Quick reference for all nodes -- ✅ README.md - Updated with new features - -### 5. Code Verified -- ✅ All Python files compile without errors -- ✅ Proper imports and dependencies -- ✅ ComfyUI node registration correct - ---- - -## 🚀 Next Steps - -### 1. Restart ComfyUI -```powershell -# Close ComfyUI completely -# Restart ComfyUI -``` - -### 2. Find Your Nodes -In ComfyUI: -``` -Right-click → Add Node → Eric Prompt Enhancers -``` - -You'll see all 5 nodes! - -### 3. Test the New Text-to-Image Node - -**Simple Test:** -``` -1. Add "Text-to-Image Prompt Enhancer" -2. Set text_prompt: "a cat in a garden" -3. Set target_platform: "flux" (or match your image model) -4. Leave other settings as "auto" -5. Connect positive_prompt to your CLIP Text Encode -6. Connect negative_prompt to your CLIP Text Encode -7. Generate! -``` - -**Verify LLM Connection:** -- Make sure LM Studio or Ollama is running -- Default endpoint: http://localhost:1234/v1 (LM Studio) -- Model should be loaded and ready - ---- - -## 📝 Platform-Specific Notes - -### Critical: Pony Diffusion Users -If using Pony, the output MUST include: -``` -Positive starts with: score_9, score_8_up, score_7_up -Negative includes: score_6, score_5, score_4 -Uses underscores: long_hair NOT "long hair" -``` -The node handles this automatically when platform = "pony" - -### Critical: Illustrious XL Users -If using Illustrious, the output MUST include: -``` -Positive starts with: masterpiece, best quality -Uses underscores in tags -``` -The node handles this automatically when platform = "illustrious" - -### Other Platforms -- Flux, SDXL, Chroma, Qwen, Wan: Natural language works -- Node optimizes token count per platform -- Negative prompts auto-generated per platform - ---- - -## 🎯 Platform Selection Guide - -| Your Image Model | Select This Platform | -|------------------|---------------------| -| FLUX.1-dev | flux | -| FLUX.1-schnell | flux | -| Stable Diffusion XL | sd_xl | -| Pony Diffusion v6 | pony | -| Illustrious XL | illustrious | -| Meissonic | chroma | -| MeissonFlow | chroma | -| Qwen Image | qwen_image | -| Qwen Image Edit | qwen_image_edit | -| Wan Image | wan_image | - -**Important:** Selecting the wrong platform will produce prompts in the wrong format! - ---- - -## 🔧 Troubleshooting - -### Nodes Don't Appear -1. **Did you restart ComfyUI?** Must fully restart -2. **Check console:** Look for Python errors -3. **Check category:** Look under "Eric Prompt Enhancers" not "video" or "image" - -### Image-to-Image Node Issues -The image-to-image node was **fixed** by updating the category. It should now appear with the other nodes under "Eric Prompt Enhancers". - -### LLM Errors -1. **Is LM Studio/Ollama running?** -2. **Is a model loaded?** -3. **Check endpoint URL:** Default is http://localhost:1234/v1 -4. **Test connection:** Console will show detailed errors - -### Wrong Output Format -1. **Check platform setting:** Must match your image model -2. **Pony/Illustrious:** Verify you selected correct platform -3. **Token count:** Each platform has optimal range - ---- - -## 📚 Documentation Files - -**Read These:** - -### For Text-to-Image: -- **QUICK_REFERENCE.md** - Quick guide for all nodes -- **TXT2IMG_GUIDE.md** - Complete text-to-image guide with examples -- **UPDATE_V16_ERIC.md** - What's new in v1.6 - -### For Image-to-Image: -- **IMG2IMG_GUIDE.md** - Image-to-image complete guide - -### For Video: -- **README.md** - Overview of all nodes -- **CONFIGURATION.md** - LLM setup details -- **LM_STUDIO_SETUP.md** - LM Studio setup - ---- - -## 🎨 Quick Examples - -### Example 1: Flux Portrait -``` -Text-to-Image Enhancer: - text_prompt: "woman with red hair" - target_platform: flux - art_style: photorealistic - lighting_source: golden hour sun - camera_angle: eye level - -Output: "masterpiece, best quality, highly detailed professional -photograph of a woman with flowing red hair, golden hour sunlight, -shot at eye level, photorealistic, 8k uhd..." -``` - -### Example 2: Pony Anime -``` -Text-to-Image Enhancer: - text_prompt: "magical girl" - target_platform: pony - art_style: anime - time_of_day: night - -Output: "score_9, score_8_up, score_7_up, 1girl, magical_girl, -detailed_face, night, anime_style, best_quality..." - -Negative: "score_6, score_5, score_4, worst quality, low quality..." -``` - -### Example 3: SDXL Quick -``` -Text-to-Image Enhancer: - text_prompt: "cyberpunk street" - target_platform: sd_xl - lighting_source: neon lights - -Output: "masterpiece, best quality, highly detailed, cyberpunk -street at night, neon lights, professional, sharp focus..." -``` - ---- - -## ✨ Advanced Features - -### Wildcard Random -Set any control to "random" for variety: -``` -camera_angle: random -lighting_source: random -weather: random -color_mood: random -``` -Perfect for batch generation! - -### Reference Images -Connect 1-2 reference images (optional): -``` -reference_image_1: [Load Image] -reference_image_2: [Load Image] -``` -Images will be noted in the enhancement context. - -### Custom Keywords -``` -positive_keywords: "LoRA_trigger, cinematic_lighting" -negative_keywords: "watermark, blurry, distorted" -``` - -### File Saving -``` -save_to_file: true -filename_base: "my_prompt" -``` -Saves to: `output/txt2img_prompts/my_prompt_TIMESTAMP.txt` - ---- - -## 🎉 You're All Set! - -**Summary:** -1. ✅ 5 nodes rebranded and organized -2. ✅ Image-to-Image node fixed -3. ✅ New Text-to-Image node with 8 platforms -4. ✅ Comprehensive documentation -5. ✅ All code tested and working - -**Next:** -1. Restart ComfyUI -2. Find nodes under "Eric Prompt Enhancers" -3. Test with simple prompts -4. Read guides for platform-specific tips -5. Experiment and create! - ---- - -## 📞 Need Help? - -1. **Check QUICK_REFERENCE.md** for fast answers -2. **Read TXT2IMG_GUIDE.md** for detailed examples -3. **Check console** for error details -4. **Verify platform selection** matches your model -5. **Start simple** and add complexity gradually - -**Happy creating with Eric's Prompt Enhancers!** 🎨✨ diff --git a/docs/archive/UPDATE_NOTES.md b/docs/archive/UPDATE_NOTES.md deleted file mode 100644 index 635a3d0..0000000 --- a/docs/archive/UPDATE_NOTES.md +++ /dev/null @@ -1,202 +0,0 @@ -# Version 1.1 Updates - Enhanced Prompt Expansion - -## Changes Made - -### 1. Added Wan 2.2 Reference Document -**File:** `WAN_GUIDE_REFERENCE.md` - -Complete distillation of the Wan 2.2 prompting guide including: -- All aesthetic control elements (lighting, composition, camera, etc.) -- Example transformations showing before/after -- Best practices and common combinations -- Available for your reference anytime - -### 2. Dramatically Enhanced System Prompts -**File:** `expansion_engine.py` (completely rewritten) - -#### Critical Output Rules Added: -``` -1. Output ONLY the enhanced prompt - nothing else -2. Do NOT repeat or reference the user's input -3. Do NOT include phrases like "Here is the expanded prompt:" -4. Do NOT use labels, explanations, or meta-commentary -5. Write as a single flowing paragraph -``` - -#### Multiple Examples Per Tier: -- **Basic Tier:** 3 examples showing simple expansions -- **Enhanced Tier:** 3 examples with details and aesthetics -- **Advanced Tier:** 2 examples with full cinematography -- **Cinematic Tier:** 2+ examples with complete director-level descriptions - -#### Preset-Specific Examples: -- Cinematic preset: Astronaut in space, boxer before fight -- Noir preset: Detective in alley with full noir aesthetics -- Action preset: Car chase with kinetic energy -- Each example shows the full tier + preset combination - -### 3. Improved Response Parsing -**File:** `expansion_engine.py` - `parse_llm_response()` method - -Now aggressively removes: -- Common LLM artifact phrases ("Here is...", "Expanded prompt:", etc.) -- Echoed user input (detects and strips first line if it's the input) -- Meta-commentary and labels -- Multiple cleaning passes for stubborn LLMs - -### 4. Cleaner User Prompts -**File:** `expansion_engine.py` - `_build_user_prompt()` method - -Changed from: -``` -"Expand this text-to-video prompt:\n\n[prompt]\n\nExpand to [tier] tier level..." -``` - -To: -``` -"[prompt] | Required terms: [keywords if any]" -``` - -Simpler format = less chance LLM echoes it back. - -## Testing the Updates - -### Quick Test: -1. Restart ComfyUI (to load the updated code) -2. Try a simple prompt: "cat playing piano" -3. **Before:** Might have included "Expand this text-to-video prompt: A cat playing piano..." -4. **After:** Should start directly with "A fluffy orange tabby cat sits..." - -### What to Expect: - -**Input:** "robot walking through city" - -**Old Style Output (what we're fixing):** -``` -Expand this text-to-video prompt: robot walking through city - -Here is the enhanced prompt: - -A sleek humanoid robot walks through a futuristic city at night... -``` - -**New Style Output:** -``` -A sleek humanoid robot with polished chrome plating walks through a neon-lit futuristic city at night. The robot has glowing blue circuit patterns across its body and moves with precise mechanical grace. Towering skyscrapers with holographic advertisements surround it... -``` - -Clean, direct, ready to use! - -## Example Improvements by Tier - -### Basic Tier Example -**Input:** "woman in rain" - -**Output Now Includes:** -- Subject details: "young woman with long dark hair" -- Scene: "wet city street during heavy rainstorm" -- Action: "walks slowly... holding black umbrella" -- Basic lighting: "soft glow from streetlights" -- Shot info: "Medium shot, eye-level angle" - -### Enhanced Tier Example -**Input:** "chef cooking" - -**Output Now Includes:** -- Detailed subject: "professional chef in pristine white uniform" -- Rich scene: "gleaming stainless steel counter in busy restaurant kitchen" -- Motion quality: "expertly flips vegetables... flames leaping dramatically" -- Aesthetics: "Medium close-up shot, practical lighting from overhead fixtures, warm colors" - -### Advanced Tier Example -**Input:** "samurai in bamboo forest" - -**Output Now Includes:** -- Full professional cinematography terms -- Specific lighting: "side lighting creates edge lighting on silhouette" -- Camera work: "camera slowly pushes in from medium shot to medium close-up" -- Composition: "Centered composition with bamboo creating natural leading lines" -- Color grading: "warm colors transitioning to cool shadows, desaturated tones" -- Lens: "Medium lens" -- Angle: "Low angle shot emphasizing imposing presence" - -### Cinematic Tier Example -**Input:** "astronaut floating in space" - -**Output Now Includes:** -- Complete subject description (suit details, wear, instruments) -- Fully realized scene (Earth below, void of space, tether movement) -- Choreographed motion (hand reaching, ice crystals, weightless drift) -- Complete camera movement: "slow 180-degree arc shot, starting behind then rotating..." -- Lighting setup: "Backlighting from sun creates rim light... Earth side lit by soft reflected light" -- Technical reasoning for all choices -- Emotional and atmospheric elements -- Professional color grading specifics - -## What Each Preset Now Emphasizes - -### Cinematic -Examples focus on: Professional lighting setups, motivated camera movements, emotional beats - -### Noir -Examples focus on: High contrast, dramatic shadows, venetian blinds, practical lighting, desaturated colors - -### Action -Examples focus on: Kinetic energy, dynamic camera, motion blur, explosive moments - -### Surreal -Examples focus on: Dreamlike qualities, unusual elements, ethereal movement - -### Stylized -Examples focus on: Artistic interpretation, graphic elements, consistent visual identity - -### Random -Picks random elements from the guide for creative exploration - -## Files Modified - -1. ✅ **expansion_engine.py** - Complete rewrite with examples (23KB → was 14KB) -2. ✅ **WAN_GUIDE_REFERENCE.md** - New comprehensive reference (4.3KB) - -## Files Unchanged - -- All other files remain the same -- Node interface is identical -- No breaking changes to workflows - -## How to Use - -Just restart ComfyUI and use the node as before. The improvements are automatic: - -1. **Better Instructions:** LLM gets detailed examples for each tier -2. **Cleaner Output:** Aggressive parsing removes echoed content -3. **Reference Available:** Check WAN_GUIDE_REFERENCE.md anytime - -## Verification - -To verify it's working: -1. Look at the positive_prompt_1 output -2. It should NOT contain "Expand this..." or "Here is..." -3. It should start directly with the enhanced description -4. Compare to your original input - should be dramatically expanded - -## Next Potential Improvements - -Future enhancements could include: -- Even more examples (currently 10+ examples across tiers) -- Style-specific vocabulary emphasis -- Better handling of technical keywords -- Prompt analysis and suggestions -- A/B comparison tools - -## Questions? - -If outputs still include echoed content: -1. Check which LLM model you're using (some follow instructions better) -2. Try temperature 0.3-0.6 for more instruction-following -3. Check the status output for any errors -4. Look at WAN_GUIDE_REFERENCE.md to see what's being taught - ---- - -**Version 1.1** - Enhanced system prompts with examples and improved parsing diff --git a/docs/archive/UPDATE_NOTES_V12.md b/docs/archive/UPDATE_NOTES_V12.md deleted file mode 100644 index 90f0778..0000000 --- a/docs/archive/UPDATE_NOTES_V12.md +++ /dev/null @@ -1,295 +0,0 @@ -# Version 1.2 - Major Update: Detail Enhancement + Advanced Node - -## Summary of Changes - -This update addresses the issue of insufficient detail in prompts and adds granular control for power users. - -##Changes Made - -### 1. ✅ Enhanced Existing Node -**File:** `prompt_expander_node.py` - -- Increased `max_tokens` from 2000 → **3000** -- Allows LLM to generate longer, more detailed responses - -### 2. ✅ Enhanced Expansion Engine -**File:** `expansion_engine.py` - -**Added explicit word count requirements:** -- **Basic tier:** 150-250 words minimum -- **Enhanced tier:** 250-400 words minimum -- **Advanced tier:** 400-600 words minimum -- **Cinematic tier:** 600-1000 words minimum - -**Added stronger detail instructions:** -``` -DETAIL REQUIREMENTS: -- Be EXHAUSTIVELY detailed - describe every visual element -- Do NOT summarize or abbreviate - expand fully -- Include specific details about: textures, materials, lighting quality, - color nuances, motion characteristics, spatial relationships, emotional beats -- Every element should be richly described with multiple adjectives and specific details -``` - -**Better output format control:** -``` -CRITICAL REQUIREMENTS: -1. Output ONLY the enhanced prompt - no labels, no explanations -2. Do NOT repeat or echo the user's input -3. Do NOT include meta-commentary -4. Write as ONE flowing paragraph -``` - -### 3. ✅ NEW: Advanced Node with Granular Controls -**File:** `prompt_expander_node_advanced.py` - -Complete dropdown control over ALL Wan 2.2 elements: - -#### Lighting Controls (3 dropdowns): -- **Light Source:** sunny, artificial, moonlighting, practical, firelighting, fluorescent, overcast, mixed -- **Lighting Type:** soft, hard, top, side, edge, rim, underlighting, silhouette, backlighting, low/high contrast -- **Time of Day:** sunrise, dawn, daylight, dusk, sunset, night - -#### Camera/Shot Controls (5 dropdowns): -- **Shot Size:** extreme close-up, close-up, medium close-up, medium, medium wide, wide, extreme wide, establishing -- **Composition:** center, balanced, left/right-weighted, symmetrical, short-side, rule of thirds -- **Lens:** wide-angle, medium, long-focus, telephoto, fisheye -- **Camera Angle:** eye-level, high angle, low angle, dutch angle, aerial, bird's eye, over-the-shoulder, top-down -- **Camera Movement:** static, pushes in, pulls back, pans, tilts, tracking, arc, crane, handheld, steadicam, compound move, whip pan - -#### Color/Style Controls (3 dropdowns): -- **Color Tone:** warm, cool, saturated, desaturated, monochromatic, black and white -- **Visual Style:** photorealistic, cinematic, 3D cartoon, 2D anime, pixel art, claymation, puppet, felt, watercolor, oil painting, pencil sketch, comic book, line drawing -- **Visual Effect:** tilt-shift, time-lapse, slow motion, motion blur, depth of field, bokeh, lens flare, film grain, vignette - -#### Motion/Emotion Controls (1 dropdown): -- **Character Emotion:** angry, fearful, happy, sad, surprised, confused, determined, thoughtful, pensive, excited, calm, anxious - -**Each dropdown has "auto" and "none" options:** -- **"auto"** = LLM decides (like standard node) -- **"none"** = Don't specify this element -- **Specific selection** = MUST include in output - -### 4. ✅ Updated Node Registration -**File:** `__init__.py` - -Now registers BOTH nodes: -- `AIVideoPromptExpander` - Standard node (simple, preset-based) -- `AIVideoPromptExpanderAdvanced` - Advanced node (granular controls) - -## How To Use - -### Standard Node (For Most Users) -**Path:** Add Node → video → prompting → **AI Video Prompt Expander** - -Use when: -- You want quick, preset-based expansion -- Fewer UI options = faster workflow -- Presets (cinematic, noir, action, etc.) are sufficient - -### Advanced Node (For Power Users) -**Path:** Add Node → video → prompting → **AI Video Prompt Expander (Advanced)** - -Use when: -- You need specific cinematography elements -- Want to enforce certain shot types, lighting, lenses -- Need precise control over aesthetic choices -- Working with specific style requirements - -## Examples of Advanced Node Usage - -### Example 1: Enforce Specific Cinematography -``` -Input: "woman walking in rain" -Shot Size: medium close-up shot -Lighting Type: edge lighting -Camera Angle: low angle shot -Lens: wide-angle lens -Color Tone: desaturated colors -All others: auto - -Result: LLM MUST include these specific elements while building the rest -``` - -### Example 2: Lock Down Complete Look -``` -Input: "detective in office" -Light Source: practical lighting -Lighting Type: hard lighting -Time of Day: night time -Shot Size: medium shot -Composition: short-side composition -Lens: medium lens -Camera Angle: low angle shot -Camera Movement: static shot -Color Tone: desaturated colors -Visual Style: cinematic -Character Emotion: thoughtful - -Result: Noir-style shot with every aesthetic element controlled -``` - -### Example 3: Partial Control -``` -Input: "superhero landing" -Shot Size: wide shot -Camera Movement: camera pushes in -Everything else: auto - -Result: LLM handles most elements but MUST do wide shot → dolly in -``` - -## Testing the Enhancements - -### Test 1: Word Count -1. Use Standard Node -2. Input: "cat playing piano" -3. Tier: **enhanced** -4. Expected: ~250-400 words output - -### Test 2: Advanced Controls -1. Use Advanced Node -2. Input: "robot walking" -3. Set Shot Size: "medium shot" -4. Set Lighting Type: "edge lighting" -5. Set Lens: "wide-angle lens" -6. Expected: Output MUST mention "medium shot", "edge lighting", and "wide-angle lens" - -### Test 3: Detail Increase -1. Use either node -2. Input: "woman in rain" -3. Tier: **advanced** -4. Expected: 400-600 words with exhaustive detail - -## Word Count Targets - -The LLM now receives explicit targets: - -| Tier | Word Count | Description | -|------|------------|-------------| -| Basic | 150-250 | Essential elements only | -| Enhanced | 250-400 | Rich details + basic aesthetics | -| Advanced | 400-600 | Professional cinematography | -| Cinematic | 600-1000 | Complete director vision | - -## What If Output Is Still Too Short? - -If your LLM model still produces short outputs: - -### 1. Try Different Models -Some models follow instructions better: -- **Better:** Llama 3.1, Qwen, Command-R -- **Good:** Llama 3, Mistral -- **Variable:** Smaller 7B models - -### 2. Adjust Temperature -- Lower (0.3-0.5) = More instruction-following -- Test with 0.5 first - -### 3. Use Advanced Node -- Specify MANY aesthetic controls -- More requirements = longer output forced - -### 4. Add Detail Keywords -In positive_keywords, add: -``` -highly detailed, exhaustive description, complete scene -``` - -### 5. Use Cinematic Tier -- Always produces longest output -- 600-1000 word target - -## Files Modified - -1. ✅ `__init__.py` - Register both nodes -2. ✅ `expansion_engine.py` - Word counts + stronger instructions -3. ✅ `prompt_expander_node.py` - Increased max_tokens to 3000 -4. ✅ `prompt_expander_node_advanced.py` - NEW advanced node (20KB) - -## Files Created - -1. ✅ `UPDATE_NOTES_V12.md` - This file -2. ✅ `WAN_GUIDE_REFERENCE.md` - Complete Wan 2.2 reference (from v1.1) - -## Restart Required - -**YES - You must restart ComfyUI to see:** -- The new Advanced node -- Updated word count requirements -- Stronger detail instructions - -## Node Comparison - -| Feature | Standard Node | Advanced Node | -|---------|--------------|---------------| -| Complexity | Simple | Complex | -| UI Options | 13 | 25+ | -| Presets | Yes | Yes | -| Aesthetic Dropdowns | No | 12 dropdowns | -| Best For | Quick workflow | Precise control | -| Setup Time | Fast | Slower | -| Output Control | Preset-based | Element-specific | - -## Backwards Compatibility - -✅ **Fully compatible** -- Existing workflows with standard node work unchanged -- No breaking changes -- Advanced node is additional, not replacement - -## Next Steps After Restart - -1. **Test Standard Node:** - - Try "advanced" or "cinematic" tier - - Look for longer, more detailed output - - Check word count - -2. **Test Advanced Node:** - - Add it to your workflow - - Pick specific aesthetic controls - - Verify they appear in output - -3. **Compare:** - - Same prompt in both nodes - - Standard with "cinematic" preset - - Advanced with manual aesthetic choices - - See which workflow you prefer - -## Troubleshooting - -### "Output still too short" -- Check your LLM model capabilities -- Try temperature 0.4-0.6 -- Use cinematic tier -- Add detail-focused keywords - -### "Advanced node not appearing" -- Restart ComfyUI completely -- Check console for errors -- Verify file exists: `prompt_expander_node_advanced.py` - -### "Aesthetic controls not working" -- They show in breakdown output -- LLM must incorporate them -- Some models ignore instructions better than others -- Try more explicit model (Llama 3.1) - -### "Which node should I use?" -- **Standard:** Most users, quick workflows -- **Advanced:** Specific requirements, matching references, precise control - -## Summary - -**Version 1.2 Changes:** -- ✅ Much stronger detail requirements (word counts) -- ✅ Increased max_tokens (2000 → 3000) -- ✅ NEW Advanced Node with 12 aesthetic dropdown controls -- ✅ Better LLM instructions about not echoing input -- ✅ Both nodes work together - choose based on need - -**Result:** More detailed prompts + granular control option for power users! - ---- - -**Questions?** Check the status output for applied settings and the breakdown for what was requested vs generated. diff --git a/docs/archive/UPDATE_V13.md b/docs/archive/UPDATE_V13.md deleted file mode 100644 index 0272ebb..0000000 --- a/docs/archive/UPDATE_V13.md +++ /dev/null @@ -1,278 +0,0 @@ -# Version 1.3 Update - Fixed Random + NEW Wildcards! - -## What's New - -### 1. ✅ FIXED: Random Preset Now Uses Your Input -**Before:** Random preset generated completely unrelated content -**After:** Random takes YOUR concept and applies random aesthetics to it - -**Example:** -``` -Input: "cat playing piano" -Preset: random - -Before (WRONG): Generated something totally unrelated -After (CORRECT): "A fluffy orange tabby cat sits at a polished grand piano..." - + random lighting, camera angles, color tones applied -``` - -### 2. ✅ FIXED: Advanced Node Random Respects Dropdowns -**Before:** Random ignored all your dropdown selections -**After:** Random respects your selections, only randomizes "auto" ones - -**Example:** -``` -Input: "detective in office" -Preset: random -Shot Size: medium shot (YOU specified) -Lighting: auto (will randomize) -Camera Angle: low angle shot (YOU specified) - -Result: -- MUST use medium shot ✅ -- MUST use low angle shot ✅ -- Lighting randomized (maybe "edge lighting") -- Other auto elements randomized -- Core concept: detective in office preserved! -``` - -### 3. 🆕 NEW: Wildcard Support! - -Create dynamic prompts with random variations! - -**Syntax:** -``` -{category:option1|option2|option3} -``` - -**Example:** -``` -A {animal:cat|dog|bird} playing {instrument:piano|guitar|drums} -``` - -**Generates random combinations:** -- "A cat playing piano" -- "A dog playing guitar" -- "A bird playing drums" -- Etc. - -## Wildcard Examples - -### Basic Usage -``` -Input: A {profession:detective|chef|scientist} in their {location:office|kitchen|lab} -Result: Random profession + random location -``` - -### With Presets -``` -Input: A {animal} {action:running|flying|swimming} -Preset: cinematic -Result: Random animal doing random action, with cinematic aesthetics -``` - -### With Advanced Node -``` -Input: A {vehicle:car|motorcycle|truck} in motion -Shot Size: wide shot -Camera Movement: tracking shot -Preset: action -Result: Random vehicle, but YOUR specified cinematography -``` - -### Predefined Categories -``` -Input: A {person} using a {tool} to fix a {object} -``` - -**Built-in categories:** -- {animal}, {person}, {profession}, {instrument} -- {location}, {weather}, {time}, {emotion} -- {action}, {color}, {vehicle}, {tool}, {object} - -See `WILDCARD_GUIDE.md` for complete list! - -## How Random Preset Works Now - -**Old Way (BROKEN):** -``` -Input: "robot in city" -Preset: random -Result: Something completely unrelated ❌ -``` - -**New Way (FIXED):** -``` -Input: "robot in city" -Preset: random -Result: "A sleek metallic robot with glowing blue circuits walks through a neon-lit city..." - + random shot size (maybe "medium shot") - + random lighting (maybe "mixed lighting") - + random camera angle (maybe "low angle shot") - + random color tone (maybe "saturated colors") - ✅ Robot and city preserved! -``` - -## Random + Advanced Node - -**Standard Node + Random:** -- Takes your input -- Applies fully random aesthetics - -**Advanced Node + Random:** -- Takes your input -- Respects your dropdown selections -- Only randomizes the "auto" ones - -**Example:** -``` -Standard Node: -Input: "spaceship flying" -Preset: random -→ Everything randomized - -Advanced Node: -Input: "spaceship flying" -Preset: random -Shot Size: wide shot (locked) -Lighting: auto (will randomize) -Lens: telephoto lens (locked) -Camera Movement: auto (will randomize) -→ Only "auto" elements randomized -``` - -## Breakdown Output Shows Everything - -The breakdown now displays: - -**For Random Preset:** -``` -Applied Preset: random - -Random Elements Applied: -- Lighting Quality: edge lighting -- Time of Day: dusk time -- Shot Sizes: medium close-up shot -- Camera Movement: tracking shot - -User-Specified Controls (Advanced Node): -- Lens: telephoto lens -- Shot Size: wide shot -``` - -**For Wildcards:** -``` -Original Input: -A {animal:cat|dog|bird} playing {instrument} - -Wildcard Replacements: -- animal: cat (from: cat|dog|bird) -- instrument: piano (predefined) - -Processed Prompt: -A cat playing piano -``` - -## Testing the Fixes - -### Test 1: Random with Input -``` -Input: "wizard casting spell" -Preset: random -Tier: enhanced - -Expected: -- Output mentions wizard ✅ -- Output mentions casting spell ✅ -- Random cinematography applied ✅ -- NOT something unrelated ✅ -``` - -### Test 2: Advanced Node Random -``` -Input: "car chase" -Preset: random -Shot Size: wide shot -Camera Movement: tracking shot -Everything else: auto - -Expected: -- "wide shot" in output ✅ -- "tracking shot" or "tracking" in output ✅ -- Random lighting/color/time ✅ -``` - -### Test 3: Wildcards -``` -Input: "A {animal:cat|dog} playing {instrument:piano|guitar}" -Variations: 3 - -Expected: -- Variation 1: Maybe "cat" + "piano" -- Variation 2: Maybe "dog" + "guitar" -- Variation 3: Maybe "cat" + "guitar" -- Each different! ✅ -``` - -## Files Modified - -1. ✅ `expansion_engine.py` - Fixed random logic + added wildcards -2. ✅ `WILDCARD_GUIDE.md` - Complete wildcard documentation -3. ✅ `UPDATE_V13.md` - This file - -## Restart Required - -**YES - Restart ComfyUI** to load: -- Fixed random preset behavior -- Wildcard support -- Updated breakdown display - -## Quick Start - -### Try Random Fix: -``` -Input: "robot in futuristic city" -Preset: random -Tier: advanced -``` - -Should get: Robot + city + random cinematography (NOT unrelated content) - -### Try Wildcards: -``` -Input: "A {animal:cat|dog|fox} in a {location:forest|city|desert}" -Preset: cinematic -Tier: enhanced -Variations: 3 -``` - -Should get: 3 different animal/location combos with cinematic style - -### Try Both: -``` -Input: "A {profession} using a {tool}" -Preset: random -Tier: advanced -``` - -Should get: Random profession/tool + random cinematography! - -## Summary - -**Version 1.3 delivers:** -- ✅ Fixed random preset (uses your input!) -- ✅ Fixed advanced node random (respects dropdowns!) -- 🆕 Wildcard support for dynamic prompts! -- ✅ Better breakdown showing what was selected -- ✅ All previous fixes intact - -**Key improvement:** "Random" now means "random AESTHETICS applied to YOUR concept", not "random unrelated prompt"! - ---- - -**Ready to test!** -1. Restart ComfyUI -2. Try random preset with your own concept -3. Try wildcards: `{animal:cat|dog|bird}` -4. Try advanced node random with some dropdowns set -5. Check `WILDCARD_GUIDE.md` for more examples! diff --git a/docs/archive/UPDATE_V15.md b/docs/archive/UPDATE_V15.md deleted file mode 100644 index f1cfc21..0000000 --- a/docs/archive/UPDATE_V15.md +++ /dev/null @@ -1,193 +0,0 @@ -# Version 1.5 Update - Image-to-Image Node with Platform Support - -## What's New - -### 🆕 Image-to-Image Prompt Expander Node - -A platform-aware node that generates optimized prompts for different image generation models! - -**Supported Platforms:** -1. **Flux** (FLUX.1-dev/schnell) - Natural, artistic, detailed -2. **Stable Diffusion XL** - Token-optimized, front-loaded -3. **Wan 2.2** (adapted) - Technical, cinematic terms -4. **Hunyuan Image** - Clear, realistic, simple English -5. **Qwen Image** - Balanced, versatile, natural -6. **Qwen Image Edit** - Concise, edit-focused - -## Key Features - -### 1. Platform-Specific Formatting - -Each platform gets prompts formatted THE WAY IT WORKS BEST: - -**Flux Example:** -``` -Input: "make it look like oil painting" -Output: "masterpiece, best quality, [image], rendered as - oil painting with rich textures, in style of..." -(Natural, 75-150 tokens, artistic) -``` - -**Qwen Edit Example:** -``` -Input: "change background to forest" -Output: "replace background with forest, keep subject, - seamless, natural" -(Very concise, 20-50 tokens, edit-focused) -``` - -### 2. Vision Model Integration - -- Llama 3.2 Vision, LLaVA support -- AI describes your image -- You just say what to change - -### 3. Advanced Aesthetic Controls - -- **Art Style**: photorealistic, digital art, painting, anime, etc. -- **Lighting**: natural, studio, dramatic, golden hour, etc. -- **Composition**: rule of thirds, centered, symmetrical, etc. -- **Color Palette**: vibrant, muted, warm, cool, etc. -- **Mood**: serene, dramatic, mysterious, etc. -- **Detail Level**: standard, highly detailed, minimalist, etc. - -### 4. Smart Adaptation - -Controls adapt to each platform: -- Flux: Adds "in the style of..." -- SDXL: Front-loads quality tokens -- Qwen Edit: Focuses on changes only -- Hunyuan: Simplifies language - -## Quick Setup - -### 1. Files Created - -- ✅ `platforms.py` - Platform configurations -- ✅ `img2img_expansion_engine.py` - Platform-aware expansion -- ✅ `image_to_image_node.py` - Main node -- ✅ `__init__.py` - Updated registration -- ✅ `IMG2IMG_GUIDE.md` - Complete documentation - -### 2. Workflow - -``` -[Load Image] - ↓ -[Image-to-Image Prompt Expander] - - Select platform (flux, sd_xl, etc.) - - Describe changes - - Set aesthetic controls - ↓ -[Your Image Gen Model] -``` - -### 3. Example Use Cases - -**Style Transfer:** -``` -Platform: flux -Change: "convert to impressionist painting" -Art Style: oil painting -→ Artistic, detailed Flux prompt -``` - -**Lighting Change:** -``` -Platform: sd_xl -Change: "add golden hour sunset" -Lighting: golden hour -→ Token-optimized SDXL prompt -``` - -**Quick Edit:** -``` -Platform: qwen_image_edit -Change: "change shirt to red" -→ Concise edit instruction -``` - -## Platform Comparison - -| Platform | Best For | Token Count | Style | -|----------|----------|-------------|-------| -| Flux | Artistic, creative | 75-150 | Natural, detailed | -| SDXL | Standard workflows | 40-75 | Token-optimized | -| Wan 2.2 | Cinematic quality | 50-100 | Technical, structured | -| Hunyuan | Photorealistic | 40-80 | Clear, simple | -| Qwen Image | Versatile | 50-100 | Balanced, natural | -| Qwen Edit | Specific edits | 20-50 | Concise, focused | - -## Node Outputs - -1. **positive_prompt** - Platform-optimized prompt -2. **negative_prompt** - Platform-specific negatives -3. **image_description** - Vision analysis -4. **status** - Processing info - -## Integration with Existing Nodes - -**You now have 4 nodes:** - -1. **AI Video Prompt Expander** - Text-to-video, simple -2. **AI Video Prompt Expander (Advanced)** - Text-to-video, detailed controls -3. **Image-to-Video Prompt Expander** - Animate images -4. **Image-to-Image Prompt Expander** - Transform images (NEW!) - -**All in:** `Add Node → video/prompting` or `image/prompting` - -## Restart Required - -**YES** - Restart ComfyUI to see the new node - -## Quick Test - -### Test Platform Optimization - -**Try this with Flux:** -``` -Load an image -Platform: flux -Change: "make it look like anime art" -Art Style: anime -Generate -→ Should get natural, artistic Flux prompt -``` - -**Try same image with Qwen Edit:** -``` -Same image -Platform: qwen_image_edit -Change: "make it look like anime art" -Generate -→ Should get very concise edit instruction -``` - -**See the difference!** Same request, different formatting per platform. - -## Version History - -- **v1.5** - Image-to-Image node with 6 platforms -- **v1.4** - Image-to-Video node with vision -- **v1.3** - Fixed random, added wildcards -- **v1.2** - Fixed auto mode -- **v1.1** - Advanced node -- **v1.0** - Initial release - -## Summary - -**v1.5 brings:** -- 🆕 Image-to-Image node -- 🆕 6 platform configurations (Flux, SDXL, Wan, Hunyuan, Qwen, Qwen Edit) -- 🆕 Platform-specific prompt formatting -- 🆕 Advanced aesthetic controls for images -- 🆕 Vision model integration for img2img -- ✅ All previous features intact - -**Key innovation:** Same change request → Different prompt format per platform → Optimal results! - ---- - -**Restart ComfyUI and transform images with platform-optimized prompts!** - -See `IMG2IMG_GUIDE.md` for complete documentation. diff --git a/docs/archive/UPDATE_V16_ERIC.md b/docs/archive/UPDATE_V16_ERIC.md deleted file mode 100644 index 08ea059..0000000 --- a/docs/archive/UPDATE_V16_ERIC.md +++ /dev/null @@ -1,344 +0,0 @@ -# Version 1.6 Update - Eric's Prompt Enhancers - -## What's New - -### 🎯 Rebranded as "Eric's Prompt Enhancers" - -All nodes now appear under **"Eric Prompt Enhancers"** category in ComfyUI for easy access! - -### 🆕 Text-to-Image Prompt Enhancer Node - -A powerful new node for advanced text-to-image prompt enhancement with multi-platform support! - -**Supported Platforms:** -1. **Flux** - Natural, artistic, detailed (75-150 tokens) -2. **Stable Diffusion XL** - Token-optimized, front-loaded (40-75 tokens) -3. **Pony Diffusion** - Booru tags, score system (40-80 tokens) ⭐ NEW -4. **Illustrious XL** - Anime booru tags, detailed (50-100 tokens) ⭐ NEW -5. **Chroma (Meissonic)** - Complex scenes, natural (100-200 tokens) ⭐ NEW -6. **Qwen Image** - Balanced, versatile (50-100 tokens) -7. **Qwen Image Edit** - Concise, edit-focused (20-50 tokens) -8. **Wan Image** - Technical, cinematic (60-120 tokens) ⭐ NEW - -## Key Features - -### Advanced Aesthetic Controls - -**Camera & Composition:** -- Camera angles (eye level, low angle, bird's eye, etc.) -- Composition styles (rule of thirds, golden ratio, etc.) - -**Lighting:** -- Lighting sources (natural, studio, golden hour, moonlight, etc.) -- Lighting quality (soft diffused, dramatic, volumetric, etc.) - -**Time & Weather:** -- Time of day (dawn, noon, golden hour, night, etc.) -- Weather conditions (clear, foggy, rainy, snowy, etc.) - -**Style & Mood:** -- Art styles (photorealistic, anime, oil painting, etc.) -- Color moods (vibrant, muted, warm, cool, etc.) -- Detail levels (standard, highly detailed, minimalist, etc.) - -### Wildcard Random Options - -Set any control to "random" for automatic variety: -- Random camera angles -- Random lighting combinations -- Random weather conditions -- Random color moods - -Perfect for batch generation with variety! - -### Optional Reference Images - -- Supports 1-2 reference images -- Images noted for context -- Can guide enhancement direction - -### Platform-Specific Optimization - -Each platform gets prompts formatted exactly as it works best: - -**Flux Example:** -``` -"masterpiece, best quality, highly detailed photograph of a woman -in a garden, golden hour lighting, in the style of Annie Leibovitz" -``` - -**Pony Example:** -``` -"score_9, score_8_up, score_7_up, 1girl, long_hair, detailed_face, -garden, golden_hour, photorealistic, best_quality" -``` - -**SDXL Example:** -``` -"masterpiece, best quality, highly detailed, woman in garden, -golden hour, professional photography, sharp focus" -``` - -## Platform-Specific Details - -### Pony Diffusion ⭐ NEW - -**Critical Requirements:** -- ✅ MUST start with: `score_9, score_8_up, score_7_up` -- ✅ Use underscores (not spaces): `long_hair` not "long hair" -- ✅ Danbooru tag format -- ✅ Character count: `1girl`, `2boys`, etc. - -**Negative MUST include:** -- `score_6, score_5, score_4, worst quality, low quality` - -### Illustrious XL ⭐ NEW - -**Requirements:** -- ✅ Start with: `masterpiece, best quality` -- ✅ Use underscores in tags -- ✅ Detailed character descriptions -- Good for anime, detailed characters - -### Chroma (Meissonic) ⭐ NEW - -**Strengths:** -- Handles complex scenes with multiple subjects -- Natural language, detailed (100-200 tokens) -- Excellent for compositional complexity -- Spatial relationships well understood - -### Wan Image ⭐ NEW - -**Style:** -- Technical cinematography terms -- Structured: subject, setting, lighting, composition -- Professional photography language -- Specific lighting types - -## File Structure - -### New Files Created: -- ✅ `text_to_image_node.py` - Main text-to-image enhancer node -- ✅ `TXT2IMG_GUIDE.md` - Complete documentation -- ✅ `UPDATE_V16_ERIC.md` - This file - -### Updated Files: -- ✅ `__init__.py` - Added new node, rebranded all nodes -- ✅ `platforms.py` - Added 4 new platforms (Pony, Illustrious, Chroma, Wan Image) -- ✅ `prompt_expander_node.py` - Updated category -- ✅ `prompt_expander_node_advanced.py` - Updated category -- ✅ `image_to_video_node.py` - Updated category -- ✅ `image_to_image_node.py` - Updated category - -## All Nodes Now Available - -Under **"Eric Prompt Enhancers"** category: - -1. **Video Prompt Expander** - Simple video prompt expansion -2. **Video Prompt Expander (Advanced)** - Granular video controls -3. **Image-to-Video Prompt Expander** - Vision + motion expansion -4. **Image-to-Image Prompt Expander** - Platform-aware img2img -5. **Text-to-Image Prompt Enhancer** ⭐ NEW - Advanced multi-platform txt2img - -## Quick Start - -### Text-to-Image Enhancer - -1. Add node: `Eric Prompt Enhancers → Text-to-Image Prompt Enhancer` - -2. Enter basic prompt: - ``` - "a woman in a garden" - ``` - -3. Select platform: - - flux, sd_xl, pony, illustrious, chroma, etc. - -4. Set controls (optional): - - Camera angle - - Lighting - - Time of day - - Art style - - etc. - -5. Connect outputs: - ``` - positive_prompt → CLIP Text Encode → KSampler - negative_prompt → CLIP Text Encode → KSampler - ``` - -### Platform Selection Guide - -| Your Image Model | Select Platform | -|------------------|-----------------| -| FLUX.1-dev/schnell | flux | -| Stable Diffusion XL | sd_xl | -| Pony Diffusion | pony | -| Illustrious XL | illustrious | -| Meissonic/MeissonFlow | chroma | -| Qwen Image | qwen_image | -| Wan models | wan_image | - -## Example Workflows - -### Example 1: Flux Photorealistic - -``` -Text-to-Image Enhancer: - - text_prompt: "portrait of a woman" - - target_platform: flux - - art_style: photorealistic - - lighting_source: golden hour sun - - camera_angle: eye level - - composition: rule of thirds - -→ positive_prompt: "masterpiece, best quality, highly detailed - professional photograph of a woman, golden hour sunlight, - shot at eye level, rule of thirds composition..." -``` - -### Example 2: Pony Anime Character - -``` -Text-to-Image Enhancer: - - text_prompt: "magical girl with blue hair" - - target_platform: pony - - art_style: anime - - time_of_day: night - - positive_keywords: "magical_staff, sparkles" - -→ positive_prompt: "score_9, score_8_up, score_7_up, 1girl, - magical_girl, long_blue_hair, magical_staff, sparkles, - night, detailed_face, anime_style, best_quality..." - -→ negative_prompt: "score_6, score_5, score_4, worst quality, - low quality, bad anatomy, sketch, jpeg artifacts..." -``` - -### Example 3: Chroma Complex Scene - -``` -Text-to-Image Enhancer: - - text_prompt: "busy coffee shop" - - target_platform: chroma - - time_of_day: morning - - lighting_source: window light - - composition: dynamic - -→ positive_prompt: "high quality, intricate, masterpiece: - A bustling coffee shop interior on a sunny morning, - with warm natural window light streaming through large - windows, baristas working, customers at tables, plants - hanging from ceiling, dynamic composition with multiple - focal points..." -``` - -## Platform Token Optimization - -The node automatically optimizes token usage per platform: - -| Platform | Target Length | Auto-Handled | -|----------|---------------|--------------| -| Flux | 75-150 tokens | ✅ | -| SDXL | 40-75 tokens | ✅ | -| Pony | 40-80 tokens | ✅ | -| Illustrious | 50-100 tokens | ✅ | -| Chroma | 100-200 tokens | ✅ | -| Qwen Image | 50-100 tokens | ✅ | -| Qwen Edit | 20-50 tokens | ✅ | -| Wan Image | 60-120 tokens | ✅ | - -## Tips & Best Practices - -### General Tips - -1. **Match Your Model**: Always select the correct platform -2. **Start Simple**: Let the node enhance basic prompts -3. **Use Auto**: "auto" settings let LLM decide -4. **Quality Emphasis**: Keep ON for best results -5. **Negative Prompts**: Always connect negative output - -### Platform-Specific Tips - -**Pony & Illustrious:** -- ✅ MUST use correct format (scores, tags, underscores) -- Include character count (1girl, 1boy, etc.) -- Use danbooru tag style - -**Flux & Chroma:** -- Natural language works best -- More verbose = better -- Artistic references encouraged - -**SDXL:** -- Keep concise (under 75 tokens) -- Front-load important concepts -- Quality tokens at start - -**Wan Image:** -- Technical terminology -- Think cinematography -- Structured descriptions - -### Wildcard Random Usage - -Great for variety in batch generation: - -``` -camera_angle: random -lighting_source: random -weather: random -color_mood: random -``` - -Each generation gets different combinations! - -## Troubleshooting - -### Node Not Appearing -- ✅ Restart ComfyUI completely -- ✅ Check console for Python errors -- ✅ Look under "Eric Prompt Enhancers" category - -### LLM Connection Issues -- ✅ Verify LM Studio/Ollama is running -- ✅ Check API endpoint (default: `http://localhost:1234/v1`) -- ✅ Test with simple prompt first - -### Poor Results -- ✅ Verify correct platform selected -- ✅ Check if your image model matches platform setting -- ✅ Try adjusting temperature (0.6-0.8 recommended) -- ✅ Add positive/negative keywords -- ✅ Set specific controls (don't leave all on "auto") - -### Pony/Illustrious Not Working -- ✅ Check output includes score tags -- ✅ Verify underscores in tags -- ✅ Make sure negative has required score_6, score_5, score_4 - -## Documentation - -**Complete guides available:** - -- 📘 `README.md` - Overview and installation -- 📘 `TXT2IMG_GUIDE.md` - Complete text-to-image guide with examples -- 📘 `IMG2IMG_GUIDE.md` - Image-to-image guide -- 📘 `CONFIGURATION.md` - LLM setup and configuration -- 📘 `LM_STUDIO_SETUP.md` - LM Studio setup guide - -## Next Steps - -1. **Restart ComfyUI** to load new nodes -2. **Find nodes** under "Eric Prompt Enhancers" -3. **Try each platform** to see differences -4. **Experiment with controls** to understand effects -5. **Use wildcards** for variety -6. **Read TXT2IMG_GUIDE.md** for detailed examples - ---- - -**Enjoy your new multi-platform prompt enhancement capabilities!** - -All nodes are now conveniently organized under "Eric Prompt Enhancers" for easy access. diff --git a/docs/archive/UPDATE_V17_ENHANCED_CONTROLS.md b/docs/archive/UPDATE_V17_ENHANCED_CONTROLS.md deleted file mode 100644 index c9fd566..0000000 --- a/docs/archive/UPDATE_V17_ENHANCED_CONTROLS.md +++ /dev/null @@ -1,496 +0,0 @@ -# Text-to-Image Node Update v1.7 - Enhanced Controls - -## Date: October 16, 2025 - -## Overview -Updated the Text-to-Image Prompt Enhancer node with enhanced controls for prompt generation, including proper reference image usage and additional creative controls similar to the Advanced Video Prompt Expander node. - ---- - -## Changes Made - -### 1. ✅ Fixed Reference Image Usage - -**Previous Behavior:** -- Reference images were accepted as input but barely used -- Only noted as "[Image provided as reference]" -- LLM didn't receive meaningful information about the images - -**New Behavior:** -- **Enhanced Image Analysis** (`_get_simple_image_description`): - - Analyzes image dimensions and aspect ratio (landscape/portrait/square) - - Determines brightness level (bright/balanced/dark) - - Analyzes color dominance and saturation (warm tones/cool tones/monochromatic) - - Provides descriptive characteristics: e.g., "Reference 1: landscape 1024x768, bright lighting, warm tones, reddish hues" - -- **Improved LLM Integration** (`_build_user_prompt`): - - Reference image characteristics are now prominently included in the prompt - - LLM receives explicit instruction to incorporate visual characteristics - - Format: Multi-line description with clear emphasis on what to use from references - -**Example Output:** -``` -Reference images provided - Use these characteristics to inform the enhanced prompt: - - Reference 1: landscape 1920x1080, bright lighting, cool tones, bluish hues - - Reference 2: portrait 768x1024, balanced lighting, warm tones, reddish hues -Incorporate the visual characteristics (composition, lighting, color tones, mood) from these reference images into your enhancement. -``` - ---- - -### 2. ✅ Added Prompt Length Control - -**New Input:** `prompt_length` - -**Options:** -- `auto` - Let LLM decide based on platform optimal length (default) -- `very_short` - 20-40 tokens (minimal, concise) -- `short` - 40-80 tokens (brief but descriptive) -- `medium` - 80-150 tokens (balanced detail) -- `long` - 150-250 tokens (detailed descriptions) -- `very_long` - 250-400 tokens (maximum detail, complex scenes) - -**How It Works:** -- Target length is passed to LLM in system prompt -- LLM adjusts output complexity accordingly -- Useful for platforms with different token budgets -- Helps control generation costs and prompt complexity - -**Use Cases:** -- **Very Short**: Quick concepts, simple subjects -- **Short**: Standard SDXL prompts -- **Medium**: Flux, balanced descriptions -- **Long**: Complex scenes, Chroma/Meissonic -- **Very Long**: Highly detailed narratives, multiple subjects - ---- - -### 3. ✅ Added Genre/Style Control - -**New Input:** `genre_style` - -**Options:** -- `auto` - LLM decides based on content (default) -- `random` - Randomly selects a style -- `none` - No specific genre guidance -- **Creative Genres:** surreal, cinematic, dramatic, action, humorous, indie, artistic, documentary, minimalist, maximalist, fantasy, noir, cyberpunk -- **Content Rating:** x-rated, pg, romantic -- **Era:** vintage, modern -- **Technical:** scifi, horror - -**Each Genre Includes Guidance:** -- **surreal**: "dreamlike, unexpected juxtapositions, reality-bending elements" -- **cinematic**: "film-like quality, dramatic lighting, professional composition" -- **dramatic**: "high contrast, emotional intensity, dynamic tension" -- **action**: "dynamic motion, energy, movement, intensity" -- **horror**: "dark atmosphere, ominous mood, eerie elements, tension" -- **noir**: "dark, moody, high contrast shadows, mystery" -- **cyberpunk**: "neon, futuristic dystopia, tech, gritty urban" -- **pg**: "family-friendly, clean, wholesome, appropriate for all ages" -- *(and more...)* - -**How It Works:** -- Selected genre/style is passed to LLM with descriptive guidance -- LLM infuses the prompt with appropriate mood, atmosphere, and aesthetic -- Works across all platforms with platform-specific adaptations - -**Example:** -- Input: "a woman in a city" -- Genre: `noir` -- Output: "dark moody portrait, film noir aesthetic, woman silhouetted against neon-lit rain-soaked streets, high contrast shadows, mysterious atmosphere..." - ---- - -### 4. ✅ Added Subject Framing Controls - -**New Input:** `subject_framing` - -**Options:** -- `auto` - LLM decides (default) -- `random` - Random selection -- `none` - No specific framing -- **Shot Types:** - - `extreme close-up` - Very tight, facial details - - `close-up` - Face and shoulders - - `medium close-up` - Chest up - - `medium shot` - Waist up - - `medium wide` - Knees up - - `wide shot` - Full body with surroundings - - `full body` - Complete subject, minimal background - - `cowboy shot` - Mid-thigh up (classic western) - - `bust shot` - Chest and head - - `head and shoulders` - Portrait framing - - `three-quarter` - 3/4 view of body - -**New Input:** `subject_pose` - -**Options:** -- `auto` - LLM decides (default) -- `random` - Random selection -- `none` - No specific pose -- **Static Poses:** standing, sitting, lying down, kneeling, crouching, relaxed -- **Dynamic Poses:** action pose, walking, running, jumping, dancing -- **Portrait Poses:** portrait pose, contrapposto, asymmetric -- **Energy:** dynamic, static, tense - -**How It Works:** -- Selected framing and pose are incorporated into the LLM instructions -- LLM structures the prompt to emphasize these elements -- Particularly useful for character/portrait generation -- Works with all platforms, adapted to platform prompting style - -**Example:** -- Framing: `close-up` -- Pose: `contrapposto` -- Result: Enhanced prompt emphasizes facial detail with classic contrapposto stance - ---- - -## Technical Implementation - -### Modified Functions - -1. **`_get_simple_image_description()`** - Lines ~398-450 - - Added numpy-based image analysis - - Calculates aspect ratio, brightness, color dominance - - Returns descriptive string with visual characteristics - -2. **`_build_user_prompt()`** - Lines ~752-777 - - Restructured to emphasize reference images - - Multi-line format for better LLM comprehension - - Explicit instructions to use reference characteristics - -3. **`_resolve_settings()`** - Lines ~596-717 - - Added resolution logic for `genre_style`, `prompt_length`, `subject_framing`, `subject_pose` - - Handles `random` selections from appropriate wildcard lists - - Passes resolved values to system prompt - -4. **`_build_system_prompt()`** - Lines ~719-890 - - Added prompt length guidance section - - Added genre/style description with mood guidance - - Incorporated all new settings into LLM instructions - -5. **`enhance_prompt()`** - Lines ~286-380 - - Updated function signature with new parameters - - Passes new parameters through the processing pipeline - -### New Wildcard Lists - -Added to `__init__()`: -```python -self.genre_styles = [...] # 18 genre options -self.subject_framings = [...] # 11 framing options -self.subject_poses = [...] # 12 pose options -``` - ---- - -## INPUT_TYPES Updates - -### New Inputs Added - -```python -"genre_style": dropdown with 22 options -"prompt_length": dropdown with 6 options -"subject_framing": dropdown with 14 options -"subject_pose": dropdown with 17 options -``` - -All new inputs support: -- `auto` - Intelligent defaults -- `random` - Random selection for variety -- `none` - Disable the control -- Specific values for precise control - ---- - -## Testing Instructions - -### 1. Test Reference Images -**Steps:** -1. Connect an image to `reference_image_1` -2. Enter basic prompt: "a portrait" -3. Run the node -4. Verify the enhanced prompt reflects the image's characteristics (lighting, colors, composition) - -**Expected:** -- If reference is bright landscape with blue tones, prompt should include similar lighting/color descriptions -- Settings display should show reference image analysis - -### 2. Test Prompt Length -**Test Cases:** -``` -very_short: Should generate ~20-40 tokens -short: Should generate ~40-80 tokens -medium: Should generate ~80-150 tokens -long: Should generate ~150-250 tokens -very_long: Should generate 250+ tokens -``` - -**Steps:** -1. Use same basic prompt for all tests -2. Change only `prompt_length` setting -3. Count tokens in output (roughly: words * 1.3) -4. Verify output matches target range - -### 3. Test Genre/Style -**Test Prompts:** -``` -Prompt: "a woman in a city" - -Genre: noir -Expected: Dark, moody, shadows, mystery, high contrast - -Genre: cyberpunk -Expected: Neon, futuristic, tech, gritty, urban dystopia - -Genre: pg -Expected: Family-friendly, wholesome, clean, appropriate - -Genre: horror -Expected: Dark, ominous, eerie, tension, atmospheric -``` - -**Verify:** -- Output tone matches selected genre -- Vocabulary and descriptors align with genre guidance -- Works with all platforms (Flux, SDXL, Pony, etc.) - -### 4. Test Subject Controls -**Test Combinations:** -``` -Framing: close-up -Pose: portrait pose -Expected: Emphasis on facial features, formal pose - -Framing: wide shot -Pose: action pose -Expected: Full body visible, dynamic movement - -Framing: cowboy shot -Pose: contrapposto -Expected: Mid-thigh up, classic artistic stance - -Framing: extreme close-up -Pose: none -Expected: Very tight framing on features, natural expression -``` - -### 5. Test Random Selection -**Steps:** -1. Set multiple controls to `random` -2. Run node 5 times with same prompt -3. Verify different results each time -4. Check that random selections are sensible - -### 6. Test Combined Features -**Complex Test:** -``` -Prompt: "{elegant|casual} woman with (detailed face:1.4)" -Platform: pony -Genre Style: cinematic -Prompt Length: long -Subject Framing: medium close-up -Subject Pose: asymmetric -Reference Image: [attach a moody portrait] -``` - -**Expected:** -- Alternation processed (elegant OR casual chosen) -- Emphasis preserved: (detailed face:1.4) -- Genre infused: cinematic mood -- Length: 150-250 tokens -- Framing mentioned: waist/chest up -- Pose described: asymmetric stance -- Reference colors/lighting incorporated -- Pony format: score_9, score_8_up, tags... - ---- - -## Platform Compatibility - -All new features work across all 8 platforms: - -| Platform | Genre Style | Prompt Length | Subject Controls | Reference Images | -|----------|-------------|---------------|------------------|------------------| -| Flux | ✅ Natural | ✅ 75-150 | ✅ Descriptive | ✅ Color/mood | -| SDXL | ✅ Adapted | ✅ 40-75 | ✅ Concise | ✅ Composition | -| Pony | ✅ Tags | ✅ Tag count | ✅ Tag format | ✅ Tag style | -| Illustrious | ✅ Tags | ✅ Tag count | ✅ Detailed | ✅ Booru style | -| Chroma | ✅ Natural | ✅ 100-200 | ✅ Spatial | ✅ Complex | -| Qwen Image | ✅ Technical | ✅ Medium | ✅ Clear | ✅ Structured | -| Qwen Edit | ✅ Technical | ✅ Medium | ✅ Edit focus | ✅ Before/after | -| Wan Image | ✅ Cinema | ✅ 60-120 | ✅ Pro terms | ✅ Lighting | - ---- - -## Use Case Examples - -### Example 1: Portrait Photography -``` -Prompt: "professional headshot" -Platform: flux -Genre Style: documentary -Prompt Length: medium -Subject Framing: close-up -Subject Pose: portrait pose -Reference Image: [professional portrait with soft lighting] - -Result: Realistic, authentic portrait with natural lighting, -professional headshot framing, formal pose, similar to reference -``` - -### Example 2: Action Scene -``` -Prompt: "superhero landing" -Platform: sd_xl -Genre Style: action -Prompt Length: short -Subject Framing: wide shot -Subject Pose: dynamic -Reference Image: none - -Result: Dynamic superhero mid-landing, full body visible, -explosive energy, action-oriented composition -``` - -### Example 3: Artistic Illustration -``` -Prompt: "fantasy character" -Platform: illustrious -Genre Style: fantasy -Prompt Length: long -Subject Framing: three-quarter -Subject Pose: contrapposto -Reference Image: [colorful fantasy art] - -Result: Detailed danbooru tags for fantasy character, -magical elements, artistic pose, vibrant colors matching reference -``` - -### Example 4: Horror Scene -``` -Prompt: "abandoned building" -Platform: chroma -Genre Style: horror -Prompt Length: very_long -Subject Framing: none -Subject Pose: none -Reference Image: [dark, moody reference] - -Result: Extensive atmospheric description, ominous mood, -dark tones, eerie elements, incorporating reference darkness -``` - ---- - -## Migration Notes - -### From v1.6.1 to v1.7 - -**Backward Compatibility:** -- ✅ All existing inputs remain unchanged -- ✅ New inputs have sensible defaults (`auto`) -- ✅ Existing workflows will continue to work -- ✅ No breaking changes to output format - -**New Requirements:** -- None - purely additive - -**Recommended Updates:** -1. Restart ComfyUI to load updated node -2. Open existing workflows - new inputs will appear with default values -3. Optionally customize new controls for enhanced results - ---- - -## Known Behaviors - -### Reference Image Analysis -- Analysis is basic (dimensions, brightness, colors) -- Does NOT use vision AI models (future enhancement possibility) -- Best results with clear, well-lit reference images -- Works with any image format ComfyUI supports - -### Prompt Length -- Token counts are approximate targets, not guarantees -- LLM may vary slightly from target -- Some platforms have hard limits that override settings -- Very long prompts may be truncated by some platforms - -### Genre Style -- Style guidance is descriptive, not prescriptive -- LLM interprets guidance based on its training -- Some genres work better with certain platforms -- "x-rated" follows platform-specific mature content handling - -### Subject Controls -- Most effective when subjects are present in the prompt -- Less impact on landscape/abstract scenes -- Works best with character/portrait generation -- Can be combined for precise control - ---- - -## Files Modified - -- `text_to_image_node.py` - Main implementation - - Lines ~30-100: Added wildcard lists - - Lines ~190-240: Updated INPUT_TYPES with new controls - - Lines ~286-380: Updated enhance_prompt signature - - Lines ~398-450: Enhanced _get_simple_image_description - - Lines ~596-717: Updated _resolve_settings - - Lines ~719-890: Enhanced _build_system_prompt - - Lines ~752-777: Improved _build_user_prompt - ---- - -## Performance Impact - -- **Minimal** - New controls don't add significant processing time -- Reference image analysis: ~10-50ms per image -- Random selection: negligible -- LLM call time unchanged (same API) - ---- - -## Future Enhancements (Possible) - -1. **Vision AI Integration**: Use vision models (CLIP, BLIP, etc.) for deep image understanding -2. **Multi-Image Blending**: Combine characteristics from multiple reference images with weights -3. **Style Transfer**: Explicit style transfer from reference to prompt -4. **Preset Combinations**: Save commonly used control combinations -5. **Advanced Pose Library**: Predefined complex poses (yoga, martial arts, dance) -6. **Genre Mixing**: Combine multiple genres (noir + cyberpunk, etc.) - ---- - -## Version History - -- **v1.7** (Oct 16, 2025) - Enhanced controls (this update) -- **v1.6.1** (Oct 16, 2025) - Bug fixes (settings, emphasis, alternation) -- **v1.6** (Oct 2025) - Text-to-image node creation - ---- - -## Support - -**Issues to Report:** -1. Reference images not being incorporated into prompts -2. Prompt length significantly off target -3. Genre style not reflected in output -4. Subject controls not working with specific platforms -5. Random selection always returning same value - -**Testing Feedback:** -- Which combinations work best? -- Which platforms respond best to new controls? -- Are there missing genre styles you'd like? -- Is the reference image analysis sufficient? - ---- - -**Status:** ✅ Ready for Testing -**Compilation:** ✅ No errors -**Backward Compatibility:** ✅ Maintained -**Next Step:** Restart ComfyUI and test in workflows! diff --git a/v1.9.0_IMPLEMENTATION_COMPLETE.md b/v1.9.0_IMPLEMENTATION_COMPLETE.md deleted file mode 100644 index 9e3670b..0000000 --- a/v1.9.0_IMPLEMENTATION_COMPLETE.md +++ /dev/null @@ -1,304 +0,0 @@ -# v1.9.0 Implementation - COMPLETE ✅ - -## Date: October 24, 2025 - -## Status: Phase 1 Implementation FINISHED - -All critical Wan 2.2 alignment changes have been successfully implemented! - ---- - -## ✅ Completed Changes - -### 1. Restructured LLM System Prompt (expansion_engine.py) - -**Changed:** Core system prompt now uses **shot-based structure** instead of single paragraph - -**New Format:** -``` -[GLOBAL SETUP - 2-4 sentences] - -Shot 1: [Framing + Camera Move] -[Action, parallax, atmosphere] - -Shot 2: [New Angle + Camera Move] -[Escalation, depth cues] - -Shot 3: [Final Reveal + Camera Move] -[Ending with "Final shot" termination] - -[STYLE/TECH FOOTER + Negatives] -``` - -**Key Requirements Added:** -- ✅ Shot-based structure mandatory (not optional) -- ✅ Explicit ending cue ("Final shot" or "Final wide reveal") -- ✅ Character identity repetition across shots -- ✅ Camera framing AND movement in every shot - ---- - -### 2. Added Atmospheric Motion & Parallax Requirements - -**Added to ALL tier instructions:** - -**Atmospheric Motion Section:** -- Foreground: rain streaks, particles, steam, fabric rippling -- Background: mist rising, clouds moving, reflections, shadows -- Environmental: leaves falling, water flowing, smoke drifting - -**Example Phrases Provided:** -- "rain streaks diagonally past the lens, catching neon light" -- "low mist rises from the lake and drifts across the frame" -- "her long sleeves leave glowing trails as they sweep through air" - -**Impact:** Prevents flat, static-looking videos - ---- - -### 3. Enhanced Camera Movement Options (Advanced Node) - -**Added 7 new camera movements:** -- `camera orbits around subject` -- `smooth glide` -- `locked-off shot` -- `crash zoom in` -- `camera cranes up` -- `camera cranes down` - -**Added 2 new shot angles:** -- `first-person POV` -- `profile close-up` - -**Total camera_movement options:** 24 (was 17, +41% increase) - ---- - -### 4. Added Reference Image Mode (Image-to-Video Node) - -**New Parameter:** `reference_mode` dropdown with 4 options - -**Modes:** -1. **recreate_exact** (default) - - "Use the provided image as the exact character and costume reference. Keep the same face, hair, outfit, and lighting. Animate this character without changing identity." - -2. **style_transfer** - - "Match the lighting, color palette, and cinematic mood of the provided image, but create a new pose and new scene." - -3. **character_remix** - - "Loosely base the main character on the provided image, but change the outfit and relocate them to a new setting." - -4. **face_only** - - "Preserve ONLY the subject's face and body identity from the provided image. Ignore the original background and lighting. Place this character in the new described scene." - -**New Method:** `_build_combined_prompt_with_mode()` includes explicit mode instruction in LLM prompt - ---- - -### 5. Enhanced Negative Prompts (Wan 2.2 Style) - -**Updated:** `generate_negative_prompt()` now accepts `visual_style` parameter - -**For photorealistic/cinematic:** -``` -no subtitles, no on-screen text, no watermarks, no logos, -no extra limbs, no deformed hands, no distortion, not low quality -``` - -**For anime/stylized:** -``` -no photoreal skin texture, no live-action lighting, no watermarks, -no subtitles, keep clean cel shading, no flicker, no jitter -``` - -**Auto-applied** based on visual_style in Advanced Node - ---- - -## 📊 Files Modified - -### 1. expansion_engine.py -**Changes:** -- ✅ Restructured `_build_system_prompt()` with shot-based format -- ✅ Completely rewrote tier instructions (basic, enhanced, advanced, cinematic) -- ✅ Added atmospheric motion requirements section to all tiers -- ✅ Enhanced `generate_negative_prompt()` with visual_style parameter -- ✅ Added Wan 2.2 vocabulary requirements - -**Lines Changed:** ~200+ lines - -### 2. prompt_expander_node_advanced.py -**Changes:** -- ✅ Added 7 new camera_movement options -- ✅ Added 2 new camera_angle options -- ✅ Updated `generate_negative_prompt()` call to pass visual_style -- ✅ Added tooltip for camera_movement - -**Lines Changed:** ~30 lines - -### 3. image_to_video_node.py -**Changes:** -- ✅ Added `reference_mode` parameter to INPUT_TYPES -- ✅ Added tooltip explaining 4 modes -- ✅ Created `_build_combined_prompt_with_mode()` method -- ✅ Updated `expand_img2vid_prompt()` signature to accept reference_mode -- ✅ Integrated mode instructions into LLM prompt - -**Lines Changed:** ~70 lines - -### 4. CHANGELOG.md -**Changes:** -- ✅ Added comprehensive v1.9.0 entry at top -- ✅ Documented all changes with examples -- ✅ Included migration notes -- ✅ Explained version jump (1.8.1 → 1.9.0) - -**Lines Added:** ~150 lines - ---- - -## ✅ Quality Checks Passed - -1. **Syntax Validation:** - - ✅ expansion_engine.py - No errors - - ✅ prompt_expander_node_advanced.py - No errors - - ✅ image_to_video_node.py - No errors - -2. **Backward Compatibility:** - - ✅ All existing parameters retained - - ✅ Old workflows will work automatically - - ✅ No breaking changes to API - -3. **Alignment with Wan 2.2 Guide:** - - ✅ Shot-based structure matches Director System Prompt - - ✅ Atmospheric motion requirements included - - ✅ Camera vocabulary aligned with recommendations - - ✅ Reference mode instructions per Wan 2.2 spec - - ✅ Negative prompts match Wan 2.2 style blocks - ---- - -## 📈 Expected Improvements - -Users should see: -- ✅ **Better temporal progression** - Clear shot 1 → 2 → 3 structure -- ✅ **More dynamic camera work** - Compound moves, orbits, cranes -- ✅ **Improved depth perception** - Atmospheric motion creates parallax -- ✅ **Cleaner endings** - Explicit "Final shot" prevents awkward loops -- ✅ **Better identity consistency** - Reference mode prevents drift -- ✅ **Professional cinematography** - Wan 2.2-optimized language - ---- - -## 🎯 Before/After Example - -### BEFORE (v1.8.1 - Single Paragraph): -``` -A graceful woman in flowing white Hanfu dances at the edge of a moonlit lake at night, -her long sleeves catching soft blue rim light as tiny birds of glowing spirit energy -blossom from her fingertips and circle her in synchronized motion, leaving shimmering -trails through the air while the dark water reflects their luminous glow and faint mist -drifts across the scene, creating an ethereal wuxia fantasy atmosphere with cinematic -realism and smooth motion at 24fps... [continues for 400 words] -``` - -### AFTER (v1.9.0 - Shot Structure): -``` -A graceful woman in flowing white Hanfu dances at the edge of a moonlit lake at night. -Soft blue rim light outlines her sleeves, and faint mist drifts across the water. Glowing -spirit-bird particles gather around her hands. Cinematic realism, ethereal wuxia mood. - -Shot 1: Close-up, Slow Dolly In -The camera starts in a close-up on her hands. She turns her wrists with elegant precision, -and tiny birds of light blossom from her fingertips. Their wings glow softly and leave -shimmering trails in the air. Slow dolly in toward her glowing fingertips. - -Shot 2: Medium Shot, Orbital Arc -The camera eases back to a medium shot and begins a smooth orbital arc around her to the -left. Her long sleeves sweep through the air, leaving ribbons of light. The spirit birds -circle her in synchronized motion. Mist drifts between camera and subject. - -Shot 3: Overhead Crane Reveal (Final Shot) -The camera cranes upward and tilts down to an overhead view. The glowing birds form a -radiant halo around her on the lakeshore, their reflections flickering on the black water. -Final wide reveal, majestic and otherworldly. - -24fps, 1280×720, cinematic realism, smooth motion. -Negative: no subtitles, no on-screen text, no watermarks, no extra limbs, no deformed hands. -``` - -**Improvements:** -- ✅ Clear 3-shot progression -- ✅ Specific camera moves per shot -- ✅ Atmospheric motion in every shot ("mist drifts") -- ✅ Explicit ending ("Final wide reveal") -- ✅ Negative prompt included -- ✅ Easier to read and parse - ---- - -## 🚀 Next Steps - -### To Test Implementation: - -1. **Restart ComfyUI** to load updated nodes -2. **Create test workflow:** - - Add Advanced Prompt Expander node - - Try short prompt: "A robot exploring an ancient temple" - - Set detail_level to "enhanced" or "advanced" - - Check output format (should be shot-based) - -3. **Test Image-to-Video:** - - Add Image-to-Video node - - Load reference image - - Try different reference_mode options - - Verify mode instruction appears in output - -4. **Compare outputs:** - - Same prompt in v1.8.1 vs v1.9.0 - - Should see structured shots instead of paragraph - -### To Commit (When Ready): - -```bash -git add expansion_engine.py -git add prompt_expander_node_advanced.py -git add image_to_video_node.py -git add CHANGELOG.md -git add WAN22_ALIGNMENT_ANALYSIS.md - -git commit -m "v1.9.0: Wan 2.2 Alignment - Shot-based structure, atmospheric motion, reference modes - -Major restructure to align with Wan 2.2 best practices: -- Restructured LLM prompts to shot-based format (Shot 1/2/3) -- Added mandatory atmospheric motion & parallax requirements -- Added reference_mode parameter to image-to-video (4 modes) -- Enhanced camera movements (+7 options, total 24) -- Wan 2.2-style negative prompts based on visual_style - -Following official Wan 2.2 Prompt Design Guide and Director System Prompt. -Backward compatible - all existing workflows auto-upgrade to new format." - -git push origin main -``` - ---- - -## 📚 Documentation Available - -1. **WAN22_ALIGNMENT_ANALYSIS.md** - Detailed gap analysis and recommendations -2. **CHANGELOG.md** - v1.9.0 entry with all changes -3. **docs/Wan2.2_Prompt_Design_Guide.md** - Official Wan 2.2 reference -4. **docs/Wan2.2_Director_System_Prompt.md** - Official Director prompt - ---- - -## ✅ Implementation Complete! - -**Status:** READY TO TEST AND COMMIT -**Version:** v1.9.0 -**Alignment:** Wan 2.2 ✅ -**Breaking Changes:** None -**Backward Compatible:** Yes - -All Phase 1 critical fixes have been successfully implemented. The nodes are now fully aligned with Wan 2.2 best practices and should produce significantly better video prompts! diff --git a/v1.9.1_ENHANCEMENTS.md b/v1.9.1_ENHANCEMENTS.md deleted file mode 100644 index 8f22d54..0000000 --- a/v1.9.1_ENHANCEMENTS.md +++ /dev/null @@ -1,363 +0,0 @@ -# v1.9.1 Enhancement Summary - -**Date:** October 26, 2025 -**Status:** ✅ COMPLETE - Ready for Testing - ---- - -## Overview - -Added two powerful new control parameters to the **Advanced Video Prompt Expander** node based on user request for more granular control over reference image handling and output structure. - ---- - -## New Features - -### 1. Reference Image Mode Control - -**Parameter:** `reference_mode` -**Location:** Advanced Video Prompt Expander node -**Default:** `recreate_exact` - -#### Available Modes - -| Mode | Description | Use Case | -|------|-------------|----------| -| **recreate_exact** | Use image as exact character/costume/setting reference | Animate existing artwork, maintain consistency | -| **subject_only** | Keep character identity, ignore background/lighting | Place character in new environment | -| **style_only** | Match aesthetic and mood, create new subject | Apply artistic style to new content | -| **color_palette_only** | Extract and apply color scheme only | Match color mood, different subject | -| **action_only** | Use pose/gesture, change everything else | Recreate motion with different character | -| **character_remix** | Keep character, place in new scenario | Same character, different story | - -#### How It Works - -Each mode generates a specific instruction to the LLM that tells it exactly how to interpret the reference image: - -**Example - recreate_exact:** -``` -[REFERENCE MODE: RECREATE EXACT] -Use the provided image as the exact character and costume reference. -Keep the same face, hair, outfit, lighting, and overall aesthetic. -Animate this character/scene without changing identity or appearance. -``` - -**Example - subject_only:** -``` -[REFERENCE MODE: SUBJECT ONLY] -Preserve ONLY the subject's face, body identity, and core appearance. -Ignore the original background, lighting, and environment. -Place this character in the new scene with new lighting and atmosphere. -``` - -This prevents common issues like: -- ❌ Identity drift (character changes appearance) -- ❌ Unwanted background copying -- ❌ Style conflicts -- ❌ Lighting inconsistencies - ---- - -### 2. Shot Structure Control - -**Parameter:** `shot_structure` -**Location:** Advanced Video Prompt Expander node -**Default:** `3_shot_structure` (Wan 2.2 recommended) - -#### Available Structures - -| Structure | Shots | Description | Best For | -|-----------|-------|-------------|----------| -| **continuous_paragraph** | N/A | Single flowing narrative, no shot breaks | Smooth single-camera moves, simple scenes | -| **2_shot_structure** | 2 | Opening + Final Reveal | Quick before/after, simple narratives | -| **3_shot_structure** | 3 | Setup + Development + Finale | Balanced storytelling (recommended) | -| **4_shot_structure** | 4 | Intro + Build + Climax + Resolution | Complex narrative arcs, dramatic scenes | - -#### Structure Templates - -**Continuous Paragraph:** -``` -[Global Setup] -The camera starts... [opening action] -Then... [middle development] -Finally... [ending with "Final wide reveal"] -``` - -**2-Shot:** -``` -[Global Setup] -Shot 1: [Opening - longer 3-4 sentences] -Shot 2: [Final Reveal - longer 3-4 sentences with "Final shot"] -``` - -**3-Shot (Default):** -``` -[Global Setup] -Shot 1: [Setup - 2-3 sentences] -Shot 2: [Development - 2-3 sentences] -Shot 3: [Finale - 2-3 sentences with "Final shot"] -``` - -**4-Shot:** -``` -[Global Setup] -Shot 1: [Introduction - 2 sentences] -Shot 2: [Build - 2 sentences] -Shot 3: [Climax - 2 sentences] -Shot 4: [Resolution - 2 sentences with "Final shot"] -``` - ---- - -## Technical Implementation - -### Modified Files - -**1. `prompt_expander_node_advanced.py`** - -Added parameters: -```python -"reference_mode": ([ - "recreate_exact", - "subject_only", - "style_only", - "color_palette_only", - "action_only", - "character_remix" -], {"default": "recreate_exact"}) - -"shot_structure": ([ - "continuous_paragraph", - "2_shot_structure", - "3_shot_structure", - "4_shot_structure" -], {"default": "3_shot_structure"}) -``` - -New method: -```python -def _build_reference_mode_instruction(reference_mode: str) -> str: - """ - Build explicit instruction for how to use reference image - Returns mode-specific LLM instruction text - """ -``` - -Updated signature: -```python -def expand_prompt(..., reference_mode, shot_structure, ...): - # Now accepts and processes both new parameters -``` - -**2. `expansion_engine.py`** - -Added parameter to methods: -```python -def expand_prompt(..., shot_structure="3_shot_structure"): - """Now accepts shot structure preference""" - -def _build_system_prompt(..., shot_structure="3_shot_structure"): - """Dynamically selects structure template""" -``` - -New helper methods: -```python -def _get_3_shot_structure_instructions() -> str: -def _get_2_shot_structure_instructions() -> str: -def _get_4_shot_structure_instructions() -> str: -def _get_continuous_structure_instructions() -> str: -``` - -Each method returns the complete LLM instruction template for that structure. - ---- - -## User Benefits - -### For Reference Image Workflows - -**Before v1.9.1:** -- ❌ No control over how image is used -- ❌ Generic "use this image" instruction -- ❌ Unpredictable results (identity drift, wrong elements copied) - -**After v1.9.1:** -- ✅ 6 explicit modes for different use cases -- ✅ Clear LLM instructions prevent confusion -- ✅ Predictable, controlled results -- ✅ Optimized for Wan 2.2 image-to-video - -### For Output Structure - -**Before v1.9.1:** -- ❌ Always 3-shot structure (locked) -- ❌ No option for continuous paragraphs -- ❌ Can't match different video lengths - -**After v1.9.1:** -- ✅ 4 structure options to choose from -- ✅ Continuous paragraph for smooth single-camera -- ✅ 2-shot for quick scenes -- ✅ 3-shot for balanced (still recommended) -- ✅ 4-shot for complex narratives - ---- - -## Backward Compatibility - -**100% Compatible** ✅ - -- Default `reference_mode = "recreate_exact"` maintains v1.9.0 behavior -- Default `shot_structure = "3_shot_structure"` maintains v1.9.0 output format -- All existing parameters unchanged -- Existing workflows continue to work without modification - ---- - -## Testing Recommendations - -### Test 1: Reference Mode Parameter -1. Load Advanced Video Prompt Expander node -2. Attach a reference image -3. Check `reference_mode` dropdown shows 6 options -4. Set to "subject_only" -5. Execute and verify output includes mode instruction - -**Expected:** Output should contain `[REFERENCE MODE: SUBJECT ONLY]` instruction - -### Test 2: Shot Structure Parameter -1. Load Advanced Video Prompt Expander node -2. Check `shot_structure` dropdown shows 4 options -3. Set to "2_shot_structure" -4. Execute with simple prompt -5. Verify output has 2 shots instead of 3 - -**Expected:** Output format matches 2-shot template (Opening + Final) - -### Test 3: Continuous Paragraph -1. Set `shot_structure` to "continuous_paragraph" -2. Execute -3. Verify output is single flowing paragraph with no "Shot 1/2/3" labels - -**Expected:** Continuous narrative with temporal cues ("At first...", "Then...", "Finally...") - -### Test 4: 4-Shot Structure -1. Set `shot_structure` to "4_shot_structure" -2. Execute -3. Verify output has 4 distinct shots - -**Expected:** Intro, Build, Climax, Resolution with proper labels - ---- - -## Usage Examples - -### Example 1: Character Remix -``` -reference_image: [image of a warrior] -reference_mode: "character_remix" -prompt: "in a cyberpunk city at night" -shot_structure: "3_shot_structure" - -→ Keeps warrior's face/identity, places in neon cityscape -``` - -### Example 2: Style Transfer -``` -reference_image: [moody film noir image] -reference_mode: "style_only" -prompt: "a detective investigating a crime scene" -shot_structure: "2_shot_structure" - -→ Creates new detective, applies noir lighting/mood -``` - -### Example 3: Continuous Camera Move -``` -reference_mode: "recreate_exact" -prompt: "the camera dollies through a mystical forest" -shot_structure: "continuous_paragraph" - -→ Single flowing description, smooth camera movement -``` - -### Example 4: Complex Narrative -``` -prompt: "a wizard's duel in an ancient temple" -shot_structure: "4_shot_structure" - -→ Intro, Build, Climax, Resolution - full story arc -``` - ---- - -## Code Quality - -### Syntax Validation -✅ No errors in `prompt_expander_node_advanced.py` -✅ No errors in `expansion_engine.py` - -### Parameter Validation -✅ All new parameters have defaults -✅ Tooltips explain each option -✅ Dropdown prevents invalid inputs - -### Error Handling -✅ Falls back to defaults if invalid mode -✅ Graceful degradation if structure not found - ---- - -## Files Modified - -1. `prompt_expander_node_advanced.py` - Added parameters and logic -2. `expansion_engine.py` - Added structure templates -3. `CHANGELOG.md` - Documented v1.9.1 - -## Documentation Created - -1. `v1.9.1_ENHANCEMENTS.md` - This file - ---- - -## Next Steps - -1. **Clear cache:** - ```powershell - Remove-Item -Recurse -Force a:\Comfy25\ComfyUI_windows_portable\ComfyUI\custom_nodes\video_prompter\__pycache__ - ``` - -2. **Restart ComfyUI** - -3. **Test both parameters:** - - Reference mode dropdown visible and functional - - Shot structure dropdown visible and functional - - Each mode produces expected output - -4. **If tests pass, commit:** - ```bash - git add prompt_expander_node_advanced.py expansion_engine.py CHANGELOG.md v1.9.1_ENHANCEMENTS.md - git commit -m "v1.9.1: Add reference_mode and shot_structure controls to Advanced node" - git push origin main - ``` - ---- - -## Summary - -**v1.9.1 adds two highly requested features:** - -1. **Reference Mode** - 6 options for controlling image-to-video interpretation -2. **Shot Structure** - 4 options for controlling output format - -Both features: -- ✅ Provide granular user control -- ✅ Follow Wan 2.2 best practices -- ✅ Maintain backward compatibility -- ✅ Have clear, helpful tooltips -- ✅ Are fully tested and error-free - -**Total new options:** 10 (6 reference modes + 4 shot structures) -**Complexity added to user:** Minimal (good defaults, clear tooltips) -**Power gained:** Significant (precise control over two critical aspects) -