Import AITURK IDE 1.0.0-beta.1 from Hermes 63279301; preserve MIT license
This commit is contained in:
@@ -0,0 +1,322 @@
|
||||
---
|
||||
name: ascii-art
|
||||
description: "ASCII art: pyfiglet, cowsay, boxes, image-to-ascii."
|
||||
version: 4.0.0
|
||||
author: 0xbyt4, Hermes Agent
|
||||
license: MIT
|
||||
dependencies: []
|
||||
platforms: [linux, macos, windows]
|
||||
metadata:
|
||||
hermes:
|
||||
tags: [ASCII, Art, Banners, Creative, Unicode, Text-Art, pyfiglet, figlet, cowsay, boxes]
|
||||
related_skills: [excalidraw]
|
||||
|
||||
---
|
||||
|
||||
# ASCII Art Skill
|
||||
|
||||
Multiple tools for different ASCII art needs. All tools are local CLI programs or free REST APIs — no API keys required.
|
||||
|
||||
## Tool 1: Text Banners (pyfiglet — local)
|
||||
|
||||
Render text as large ASCII art banners. 571 built-in fonts.
|
||||
|
||||
### Setup
|
||||
|
||||
```bash
|
||||
pip install pyfiglet --break-system-packages -q
|
||||
```
|
||||
|
||||
### Usage
|
||||
|
||||
```bash
|
||||
python -m pyfiglet "YOUR TEXT" -f slant
|
||||
python -m pyfiglet "TEXT" -f doom -w 80 # Set width
|
||||
python -m pyfiglet --list_fonts # List all 571 fonts
|
||||
```
|
||||
|
||||
### Recommended fonts
|
||||
|
||||
| Style | Font | Best for |
|
||||
|-------|------|----------|
|
||||
| Clean & modern | `slant` | Project names, headers |
|
||||
| Bold & blocky | `doom` | Titles, logos |
|
||||
| Big & readable | `big` | Banners |
|
||||
| Classic banner | `banner3` | Wide displays |
|
||||
| Compact | `small` | Subtitles |
|
||||
| Cyberpunk | `cyberlarge` | Tech themes |
|
||||
| 3D effect | `3-d` | Splash screens |
|
||||
| Gothic | `gothic` | Dramatic text |
|
||||
|
||||
### Tips
|
||||
|
||||
- Preview 2-3 fonts and let the user pick their favorite
|
||||
- Short text (1-8 chars) works best with detailed fonts like `doom` or `block`
|
||||
- Long text works better with compact fonts like `small` or `mini`
|
||||
|
||||
## Tool 2: Text Banners (asciified API — remote, no install)
|
||||
|
||||
Free REST API that converts text to ASCII art. 250+ FIGlet fonts. Returns plain text directly — no parsing needed. Use this when pyfiglet is not installed or as a quick alternative.
|
||||
|
||||
### Usage (via terminal curl)
|
||||
|
||||
```bash
|
||||
# Basic text banner (default font)
|
||||
curl -s "https://asciified.thelicato.io/api/v2/ascii?text=Hello+World"
|
||||
|
||||
# With a specific font
|
||||
curl -s "https://asciified.thelicato.io/api/v2/ascii?text=Hello&font=Slant"
|
||||
curl -s "https://asciified.thelicato.io/api/v2/ascii?text=Hello&font=Doom"
|
||||
curl -s "https://asciified.thelicato.io/api/v2/ascii?text=Hello&font=Star+Wars"
|
||||
curl -s "https://asciified.thelicato.io/api/v2/ascii?text=Hello&font=3-D"
|
||||
curl -s "https://asciified.thelicato.io/api/v2/ascii?text=Hello&font=Banner3"
|
||||
|
||||
# List all available fonts (returns JSON array)
|
||||
curl -s "https://asciified.thelicato.io/api/v2/fonts"
|
||||
```
|
||||
|
||||
### Tips
|
||||
|
||||
- URL-encode spaces as `+` in the text parameter
|
||||
- The response is plain text ASCII art — no JSON wrapping, ready to display
|
||||
- Font names are case-sensitive; use the fonts endpoint to get exact names
|
||||
- Works from any terminal with curl — no Python or pip needed
|
||||
|
||||
## Tool 3: Cowsay (Message Art)
|
||||
|
||||
Classic tool that wraps text in a speech bubble with an ASCII character.
|
||||
|
||||
### Setup
|
||||
|
||||
```bash
|
||||
sudo apt install cowsay -y # Debian/Ubuntu
|
||||
# brew install cowsay # macOS
|
||||
```
|
||||
|
||||
### Usage
|
||||
|
||||
```bash
|
||||
cowsay "Hello World"
|
||||
cowsay -f tux "Linux rules" # Tux the penguin
|
||||
cowsay -f dragon "Rawr!" # Dragon
|
||||
cowsay -f stegosaurus "Roar!" # Stegosaurus
|
||||
cowthink "Hmm..." # Thought bubble
|
||||
cowsay -l # List all characters
|
||||
```
|
||||
|
||||
### Available characters (50+)
|
||||
|
||||
`beavis.zen`, `bong`, `bunny`, `cheese`, `daemon`, `default`, `dragon`,
|
||||
`dragon-and-cow`, `elephant`, `eyes`, `flaming-skull`, `ghostbusters`,
|
||||
`hellokitty`, `kiss`, `kitty`, `koala`, `luke-koala`, `mech-and-cow`,
|
||||
`meow`, `moofasa`, `moose`, `ren`, `sheep`, `skeleton`, `small`,
|
||||
`stegosaurus`, `stimpy`, `supermilker`, `surgery`, `three-eyes`,
|
||||
`turkey`, `turtle`, `tux`, `udder`, `vader`, `vader-koala`, `www`
|
||||
|
||||
### Eye/tongue modifiers
|
||||
|
||||
```bash
|
||||
cowsay -b "Borg" # =_= eyes
|
||||
cowsay -d "Dead" # x_x eyes
|
||||
cowsay -g "Greedy" # $_$ eyes
|
||||
cowsay -p "Paranoid" # @_@ eyes
|
||||
cowsay -s "Stoned" # *_* eyes
|
||||
cowsay -w "Wired" # O_O eyes
|
||||
cowsay -e "OO" "Msg" # Custom eyes
|
||||
cowsay -T "U " "Msg" # Custom tongue
|
||||
```
|
||||
|
||||
## Tool 4: Boxes (Decorative Borders)
|
||||
|
||||
Draw decorative ASCII art borders/frames around any text. 70+ built-in designs.
|
||||
|
||||
### Setup
|
||||
|
||||
```bash
|
||||
sudo apt install boxes -y # Debian/Ubuntu
|
||||
# brew install boxes # macOS
|
||||
```
|
||||
|
||||
### Usage
|
||||
|
||||
```bash
|
||||
echo "Hello World" | boxes # Default box
|
||||
echo "Hello World" | boxes -d stone # Stone border
|
||||
echo "Hello World" | boxes -d parchment # Parchment scroll
|
||||
echo "Hello World" | boxes -d cat # Cat border
|
||||
echo "Hello World" | boxes -d dog # Dog border
|
||||
echo "Hello World" | boxes -d unicornsay # Unicorn
|
||||
echo "Hello World" | boxes -d diamonds # Diamond pattern
|
||||
echo "Hello World" | boxes -d c-cmt # C-style comment
|
||||
echo "Hello World" | boxes -d html-cmt # HTML comment
|
||||
echo "Hello World" | boxes -a c # Center text
|
||||
boxes -l # List all 70+ designs
|
||||
```
|
||||
|
||||
### Combine with pyfiglet or asciified
|
||||
|
||||
```bash
|
||||
python -m pyfiglet "HERMES" -f slant | boxes -d stone
|
||||
# Or without pyfiglet installed:
|
||||
curl -s "https://asciified.thelicato.io/api/v2/ascii?text=HERMES&font=Slant" | boxes -d stone
|
||||
```
|
||||
|
||||
## Tool 5: TOIlet (Colored Text Art)
|
||||
|
||||
Like pyfiglet but with ANSI color effects and visual filters. Great for terminal eye candy.
|
||||
|
||||
### Setup
|
||||
|
||||
```bash
|
||||
sudo apt install toilet toilet-fonts -y # Debian/Ubuntu
|
||||
# brew install toilet # macOS
|
||||
```
|
||||
|
||||
### Usage
|
||||
|
||||
```bash
|
||||
toilet "Hello World" # Basic text art
|
||||
toilet -f bigmono12 "Hello" # Specific font
|
||||
toilet --gay "Rainbow!" # Rainbow coloring
|
||||
toilet --metal "Metal!" # Metallic effect
|
||||
toilet -F border "Bordered" # Add border
|
||||
toilet -F border --gay "Fancy!" # Combined effects
|
||||
toilet -f pagga "Block" # Block-style font (unique to toilet)
|
||||
toilet -F list # List available filters
|
||||
```
|
||||
|
||||
### Filters
|
||||
|
||||
`crop`, `gay` (rainbow), `metal`, `flip`, `flop`, `180`, `left`, `right`, `border`
|
||||
|
||||
**Note**: toilet outputs ANSI escape codes for colors — works in terminals but may not render in all contexts (e.g., plain text files, some chat platforms).
|
||||
|
||||
## Tool 6: Image to ASCII Art
|
||||
|
||||
Convert images (PNG, JPEG, GIF, WEBP) to ASCII art.
|
||||
|
||||
### Option A: ascii-image-converter (recommended, modern)
|
||||
|
||||
```bash
|
||||
# Install
|
||||
sudo snap install ascii-image-converter
|
||||
# OR: go install github.com/TheZoraiz/ascii-image-converter@latest
|
||||
```
|
||||
|
||||
```bash
|
||||
ascii-image-converter image.png # Basic
|
||||
ascii-image-converter image.png -C # Color output
|
||||
ascii-image-converter image.png -d 60,30 # Set dimensions
|
||||
ascii-image-converter image.png -b # Braille characters
|
||||
ascii-image-converter image.png -n # Negative/inverted
|
||||
ascii-image-converter https://url/image.jpg # Direct URL
|
||||
ascii-image-converter image.png --save-txt out # Save as text
|
||||
```
|
||||
|
||||
### Option B: jp2a (lightweight, JPEG only)
|
||||
|
||||
```bash
|
||||
sudo apt install jp2a -y
|
||||
jp2a --width=80 image.jpg
|
||||
jp2a --colors image.jpg # Colorized
|
||||
```
|
||||
|
||||
## Tool 7: Search Pre-Made ASCII Art
|
||||
|
||||
Search curated ASCII art from the web. Use `terminal` with `curl`.
|
||||
|
||||
### Source A: ascii.co.uk (recommended for pre-made art)
|
||||
|
||||
Large collection of classic ASCII art organized by subject. Art is inside HTML `<pre>` tags. Fetch the page with curl, then extract art with a small Python snippet.
|
||||
|
||||
**URL pattern:** `https://ascii.co.uk/art/{subject}`
|
||||
|
||||
**Step 1 — Fetch the page:**
|
||||
|
||||
```bash
|
||||
curl -s 'https://ascii.co.uk/art/cat' -o /tmp/ascii_art.html
|
||||
```
|
||||
|
||||
**Step 2 — Extract art from pre tags:**
|
||||
|
||||
```python
|
||||
import re, html
|
||||
with open('/tmp/ascii_art.html') as f:
|
||||
text = f.read()
|
||||
arts = re.findall(r'<pre[^>]*>(.*?)</pre>', text, re.DOTALL)
|
||||
for art in arts:
|
||||
clean = re.sub(r'<[^>]+>', '', art)
|
||||
clean = html.unescape(clean).strip()
|
||||
if len(clean) > 30:
|
||||
print(clean)
|
||||
print('\n---\n')
|
||||
```
|
||||
|
||||
**Available subjects** (use as URL path):
|
||||
- Animals: `cat`, `dog`, `horse`, `bird`, `fish`, `dragon`, `snake`, `rabbit`, `elephant`, `dolphin`, `butterfly`, `owl`, `wolf`, `bear`, `penguin`, `turtle`
|
||||
- Objects: `car`, `ship`, `airplane`, `rocket`, `guitar`, `computer`, `coffee`, `beer`, `cake`, `house`, `castle`, `sword`, `crown`, `key`
|
||||
- Nature: `tree`, `flower`, `sun`, `moon`, `star`, `mountain`, `ocean`, `rainbow`
|
||||
- Characters: `skull`, `robot`, `angel`, `wizard`, `pirate`, `ninja`, `alien`
|
||||
- Holidays: `christmas`, `halloween`, `valentine`
|
||||
|
||||
**Tips:**
|
||||
- Preserve artist signatures/initials — important etiquette
|
||||
- Multiple art pieces per page — pick the best one for the user
|
||||
- Works reliably via curl, no JavaScript needed
|
||||
|
||||
### Source B: GitHub Octocat API (fun easter egg)
|
||||
|
||||
Returns a random GitHub Octocat with a wise quote. No auth needed.
|
||||
|
||||
```bash
|
||||
curl -s https://api.github.com/octocat
|
||||
```
|
||||
|
||||
## Tool 8: Fun ASCII Utilities (via curl)
|
||||
|
||||
These free services return ASCII art directly — great for fun extras.
|
||||
|
||||
### QR Codes as ASCII Art
|
||||
|
||||
```bash
|
||||
curl -s "qrenco.de/Hello+World"
|
||||
curl -s "qrenco.de/https://example.com"
|
||||
```
|
||||
|
||||
### Weather as ASCII Art
|
||||
|
||||
```bash
|
||||
curl -s "wttr.in/London" # Full weather report with ASCII graphics
|
||||
curl -s "wttr.in/Moon" # Moon phase in ASCII art
|
||||
curl -s "v2.wttr.in/London" # Detailed version
|
||||
```
|
||||
|
||||
## Tool 9: LLM-Generated Custom Art (Fallback)
|
||||
|
||||
When tools above don't have what's needed, generate ASCII art directly using these Unicode characters:
|
||||
|
||||
### Character Palette
|
||||
|
||||
**Box Drawing:** `╔ ╗ ╚ ╝ ║ ═ ╠ ╣ ╦ ╩ ╬ ┌ ┐ └ ┘ │ ─ ├ ┤ ┬ ┴ ┼ ╭ ╮ ╰ ╯`
|
||||
|
||||
**Block Elements:** `░ ▒ ▓ █ ▄ ▀ ▌ ▐ ▖ ▗ ▘ ▝ ▚ ▞`
|
||||
|
||||
**Geometric & Symbols:** `◆ ◇ ◈ ● ○ ◉ ■ □ ▲ △ ▼ ▽ ★ ☆ ✦ ✧ ◀ ▶ ◁ ▷ ⬡ ⬢ ⌂`
|
||||
|
||||
### Rules
|
||||
|
||||
- Max width: 60 characters per line (terminal-safe)
|
||||
- Max height: 15 lines for banners, 25 for scenes
|
||||
- Monospace only: output must render correctly in fixed-width fonts
|
||||
|
||||
## Decision Flow
|
||||
|
||||
1. **Text as a banner** → pyfiglet if installed, otherwise asciified API via curl
|
||||
2. **Wrap a message in fun character art** → cowsay
|
||||
3. **Add decorative border/frame** → boxes (can combine with pyfiglet/asciified)
|
||||
4. **Art of a specific thing** (cat, rocket, dragon) → ascii.co.uk via curl + parsing
|
||||
5. **Convert an image to ASCII** → ascii-image-converter or jp2a
|
||||
6. **QR code** → qrenco.de via curl
|
||||
7. **Weather/moon art** → wttr.in via curl
|
||||
8. **Something custom/creative** → LLM generation with Unicode palette
|
||||
9. **Any tool not installed** → install it, or fall back to next option
|
||||
@@ -0,0 +1,569 @@
|
||||
---
|
||||
name: audiocraft-audio-generation
|
||||
description: "AudioCraft: MusicGen text-to-music, AudioGen text-to-sound."
|
||||
version: 1.0.0
|
||||
author: Orchestra Research
|
||||
license: MIT
|
||||
dependencies: [audiocraft, torch>=2.0.0, transformers>=4.30.0]
|
||||
platforms: [linux, macos]
|
||||
metadata:
|
||||
hermes:
|
||||
tags: [Multimodal, Audio Generation, Text-to-Music, Text-to-Audio, MusicGen]
|
||||
related_skills: [heartmula, songwriting-and-ai-music]
|
||||
|
||||
---
|
||||
|
||||
# AudioCraft: Audio Generation
|
||||
|
||||
Guide to using Meta's AudioCraft for text-to-music and text-to-audio generation with MusicGen, AudioGen, and EnCodec.
|
||||
|
||||
## When to use AudioCraft
|
||||
|
||||
**Use AudioCraft when:**
|
||||
- Need to generate music from text descriptions
|
||||
- Creating sound effects and environmental audio
|
||||
- Building music generation applications
|
||||
- Need melody-conditioned music generation
|
||||
- Want stereo audio output
|
||||
- Require controllable music generation with style transfer
|
||||
|
||||
**Key features:**
|
||||
- **MusicGen**: Text-to-music generation with melody conditioning
|
||||
- **AudioGen**: Text-to-sound effects generation
|
||||
- **EnCodec**: High-fidelity neural audio codec
|
||||
- **Multiple model sizes**: Small (300M) to Large (3.3B)
|
||||
- **Stereo support**: Full stereo audio generation
|
||||
- **Style conditioning**: MusicGen-Style for reference-based generation
|
||||
|
||||
**Use alternatives instead:**
|
||||
- **Stable Audio**: For longer commercial music generation
|
||||
- **Bark**: For text-to-speech with music/sound effects
|
||||
- **Riffusion**: For spectogram-based music generation
|
||||
- **OpenAI Jukebox**: For raw audio generation with lyrics
|
||||
|
||||
## Quick start
|
||||
|
||||
### Installation
|
||||
|
||||
```bash
|
||||
# From PyPI
|
||||
pip install audiocraft
|
||||
|
||||
# From GitHub (latest)
|
||||
pip install git+https://github.com/facebookresearch/audiocraft.git
|
||||
|
||||
# Or use HuggingFace Transformers
|
||||
pip install transformers torch torchaudio
|
||||
```
|
||||
|
||||
### Basic text-to-music (AudioCraft)
|
||||
|
||||
```python
|
||||
import torchaudio
|
||||
from audiocraft.models import MusicGen
|
||||
|
||||
# Load model
|
||||
model = MusicGen.get_pretrained('facebook/musicgen-small')
|
||||
|
||||
# Set generation parameters
|
||||
model.set_generation_params(
|
||||
duration=8, # seconds
|
||||
top_k=250,
|
||||
temperature=1.0
|
||||
)
|
||||
|
||||
# Generate from text
|
||||
descriptions = ["happy upbeat electronic dance music with synths"]
|
||||
wav = model.generate(descriptions)
|
||||
|
||||
# Save audio
|
||||
torchaudio.save("output.wav", wav[0].cpu(), sample_rate=32000)
|
||||
```
|
||||
|
||||
### Using HuggingFace Transformers
|
||||
|
||||
```python
|
||||
from transformers import AutoProcessor, MusicgenForConditionalGeneration
|
||||
import scipy
|
||||
|
||||
# Load model and processor
|
||||
processor = AutoProcessor.from_pretrained("facebook/musicgen-small")
|
||||
model = MusicgenForConditionalGeneration.from_pretrained("facebook/musicgen-small")
|
||||
model.to("cuda")
|
||||
|
||||
# Generate music
|
||||
inputs = processor(
|
||||
text=["80s pop track with bassy drums and synth"],
|
||||
padding=True,
|
||||
return_tensors="pt"
|
||||
).to("cuda")
|
||||
|
||||
audio_values = model.generate(
|
||||
**inputs,
|
||||
do_sample=True,
|
||||
guidance_scale=3,
|
||||
max_new_tokens=256
|
||||
)
|
||||
|
||||
# Save
|
||||
sampling_rate = model.config.audio_encoder.sampling_rate
|
||||
scipy.io.wavfile.write("output.wav", rate=sampling_rate, data=audio_values[0, 0].cpu().numpy())
|
||||
```
|
||||
|
||||
### Text-to-sound with AudioGen
|
||||
|
||||
```python
|
||||
from audiocraft.models import AudioGen
|
||||
|
||||
# Load AudioGen
|
||||
model = AudioGen.get_pretrained('facebook/audiogen-medium')
|
||||
|
||||
model.set_generation_params(duration=5)
|
||||
|
||||
# Generate sound effects
|
||||
descriptions = ["dog barking in a park with birds chirping"]
|
||||
wav = model.generate(descriptions)
|
||||
|
||||
torchaudio.save("sound.wav", wav[0].cpu(), sample_rate=16000)
|
||||
```
|
||||
|
||||
## Core concepts
|
||||
|
||||
### Architecture overview
|
||||
|
||||
```
|
||||
AudioCraft Architecture:
|
||||
┌──────────────────────────────────────────────────────────────┐
|
||||
│ Text Encoder (T5) │
|
||||
│ │ │
|
||||
│ Text Embeddings │
|
||||
└────────────────────────┬─────────────────────────────────────┘
|
||||
│
|
||||
┌────────────────────────▼─────────────────────────────────────┐
|
||||
│ Transformer Decoder (LM) │
|
||||
│ Auto-regressively generates audio tokens │
|
||||
│ Using efficient token interleaving patterns │
|
||||
└────────────────────────┬─────────────────────────────────────┘
|
||||
│
|
||||
┌────────────────────────▼─────────────────────────────────────┐
|
||||
│ EnCodec Audio Decoder │
|
||||
│ Converts tokens back to audio waveform │
|
||||
└──────────────────────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
### Model variants
|
||||
|
||||
| Model | Size | Description | Use Case |
|
||||
|-------|------|-------------|----------|
|
||||
| `musicgen-small` | 300M | Text-to-music | Quick generation |
|
||||
| `musicgen-medium` | 1.5B | Text-to-music | Balanced |
|
||||
| `musicgen-large` | 3.3B | Text-to-music | Best quality |
|
||||
| `musicgen-melody` | 1.5B | Text + melody | Melody conditioning |
|
||||
| `musicgen-melody-large` | 3.3B | Text + melody | Best melody |
|
||||
| `musicgen-stereo-*` | Varies | Stereo output | Stereo generation |
|
||||
| `musicgen-style` | 1.5B | Style transfer | Reference-based |
|
||||
| `audiogen-medium` | 1.5B | Text-to-sound | Sound effects |
|
||||
|
||||
### Generation parameters
|
||||
|
||||
| Parameter | Default | Description |
|
||||
|-----------|---------|-------------|
|
||||
| `duration` | 8.0 | Length in seconds (1-120) |
|
||||
| `top_k` | 250 | Top-k sampling |
|
||||
| `top_p` | 0.0 | Nucleus sampling (0 = disabled) |
|
||||
| `temperature` | 1.0 | Sampling temperature |
|
||||
| `cfg_coef` | 3.0 | Classifier-free guidance |
|
||||
|
||||
## MusicGen usage
|
||||
|
||||
### Text-to-music generation
|
||||
|
||||
```python
|
||||
from audiocraft.models import MusicGen
|
||||
import torchaudio
|
||||
|
||||
model = MusicGen.get_pretrained('facebook/musicgen-medium')
|
||||
|
||||
# Configure generation
|
||||
model.set_generation_params(
|
||||
duration=30, # Up to 30 seconds
|
||||
top_k=250, # Sampling diversity
|
||||
top_p=0.0, # 0 = use top_k only
|
||||
temperature=1.0, # Creativity (higher = more varied)
|
||||
cfg_coef=3.0 # Text adherence (higher = stricter)
|
||||
)
|
||||
|
||||
# Generate multiple samples
|
||||
descriptions = [
|
||||
"epic orchestral soundtrack with strings and brass",
|
||||
"chill lo-fi hip hop beat with jazzy piano",
|
||||
"energetic rock song with electric guitar"
|
||||
]
|
||||
|
||||
# Generate (returns [batch, channels, samples])
|
||||
wav = model.generate(descriptions)
|
||||
|
||||
# Save each
|
||||
for i, audio in enumerate(wav):
|
||||
torchaudio.save(f"music_{i}.wav", audio.cpu(), sample_rate=32000)
|
||||
```
|
||||
|
||||
### Melody-conditioned generation
|
||||
|
||||
```python
|
||||
from audiocraft.models import MusicGen
|
||||
import torchaudio
|
||||
|
||||
# Load melody model
|
||||
model = MusicGen.get_pretrained('facebook/musicgen-melody')
|
||||
model.set_generation_params(duration=30)
|
||||
|
||||
# Load melody audio
|
||||
melody, sr = torchaudio.load("melody.wav")
|
||||
|
||||
# Generate with melody conditioning
|
||||
descriptions = ["acoustic guitar folk song"]
|
||||
wav = model.generate_with_chroma(descriptions, melody, sr)
|
||||
|
||||
torchaudio.save("melody_conditioned.wav", wav[0].cpu(), sample_rate=32000)
|
||||
```
|
||||
|
||||
### Stereo generation
|
||||
|
||||
```python
|
||||
from audiocraft.models import MusicGen
|
||||
|
||||
# Load stereo model
|
||||
model = MusicGen.get_pretrained('facebook/musicgen-stereo-medium')
|
||||
model.set_generation_params(duration=15)
|
||||
|
||||
descriptions = ["ambient electronic music with wide stereo panning"]
|
||||
wav = model.generate(descriptions)
|
||||
|
||||
# wav shape: [batch, 2, samples] for stereo
|
||||
print(f"Stereo shape: {wav.shape}") # [1, 2, 480000]
|
||||
torchaudio.save("stereo.wav", wav[0].cpu(), sample_rate=32000)
|
||||
```
|
||||
|
||||
### Audio continuation
|
||||
|
||||
```python
|
||||
from transformers import AutoProcessor, MusicgenForConditionalGeneration
|
||||
|
||||
processor = AutoProcessor.from_pretrained("facebook/musicgen-medium")
|
||||
model = MusicgenForConditionalGeneration.from_pretrained("facebook/musicgen-medium")
|
||||
|
||||
# Load audio to continue
|
||||
import torchaudio
|
||||
audio, sr = torchaudio.load("intro.wav")
|
||||
|
||||
# Process with text and audio
|
||||
inputs = processor(
|
||||
audio=audio.squeeze().numpy(),
|
||||
sampling_rate=sr,
|
||||
text=["continue with a epic chorus"],
|
||||
padding=True,
|
||||
return_tensors="pt"
|
||||
)
|
||||
|
||||
# Generate continuation
|
||||
audio_values = model.generate(**inputs, do_sample=True, guidance_scale=3, max_new_tokens=512)
|
||||
```
|
||||
|
||||
## MusicGen-Style usage
|
||||
|
||||
### Style-conditioned generation
|
||||
|
||||
```python
|
||||
from audiocraft.models import MusicGen
|
||||
|
||||
# Load style model
|
||||
model = MusicGen.get_pretrained('facebook/musicgen-style')
|
||||
|
||||
# Configure generation with style
|
||||
model.set_generation_params(
|
||||
duration=30,
|
||||
cfg_coef=3.0,
|
||||
cfg_coef_beta=5.0 # Style influence
|
||||
)
|
||||
|
||||
# Configure style conditioner
|
||||
model.set_style_conditioner_params(
|
||||
eval_q=3, # RVQ quantizers (1-6)
|
||||
excerpt_length=3.0 # Style excerpt length
|
||||
)
|
||||
|
||||
# Load style reference
|
||||
style_audio, sr = torchaudio.load("reference_style.wav")
|
||||
|
||||
# Generate with text + style
|
||||
descriptions = ["upbeat dance track"]
|
||||
wav = model.generate_with_style(descriptions, style_audio, sr)
|
||||
```
|
||||
|
||||
### Style-only generation (no text)
|
||||
|
||||
```python
|
||||
# Generate matching style without text prompt
|
||||
model.set_generation_params(
|
||||
duration=30,
|
||||
cfg_coef=3.0,
|
||||
cfg_coef_beta=None # Disable double CFG for style-only
|
||||
)
|
||||
|
||||
wav = model.generate_with_style([None], style_audio, sr)
|
||||
```
|
||||
|
||||
## AudioGen usage
|
||||
|
||||
### Sound effect generation
|
||||
|
||||
```python
|
||||
from audiocraft.models import AudioGen
|
||||
import torchaudio
|
||||
|
||||
model = AudioGen.get_pretrained('facebook/audiogen-medium')
|
||||
model.set_generation_params(duration=10)
|
||||
|
||||
# Generate various sounds
|
||||
descriptions = [
|
||||
"thunderstorm with heavy rain and lightning",
|
||||
"busy city traffic with car horns",
|
||||
"ocean waves crashing on rocks",
|
||||
"crackling campfire in forest"
|
||||
]
|
||||
|
||||
wav = model.generate(descriptions)
|
||||
|
||||
for i, audio in enumerate(wav):
|
||||
torchaudio.save(f"sound_{i}.wav", audio.cpu(), sample_rate=16000)
|
||||
```
|
||||
|
||||
## EnCodec usage
|
||||
|
||||
### Audio compression
|
||||
|
||||
```python
|
||||
from audiocraft.models import CompressionModel
|
||||
import torch
|
||||
import torchaudio
|
||||
|
||||
# Load EnCodec
|
||||
model = CompressionModel.get_pretrained('facebook/encodec_32khz')
|
||||
|
||||
# Load audio
|
||||
wav, sr = torchaudio.load("audio.wav")
|
||||
|
||||
# Ensure correct sample rate
|
||||
if sr != 32000:
|
||||
resampler = torchaudio.transforms.Resample(sr, 32000)
|
||||
wav = resampler(wav)
|
||||
|
||||
# Encode to tokens
|
||||
with torch.no_grad():
|
||||
encoded = model.encode(wav.unsqueeze(0))
|
||||
codes = encoded[0] # Audio codes
|
||||
|
||||
# Decode back to audio
|
||||
with torch.no_grad():
|
||||
decoded = model.decode(codes)
|
||||
|
||||
torchaudio.save("reconstructed.wav", decoded[0].cpu(), sample_rate=32000)
|
||||
```
|
||||
|
||||
## Common workflows
|
||||
|
||||
### Workflow 1: Music generation pipeline
|
||||
|
||||
```python
|
||||
import torch
|
||||
import torchaudio
|
||||
from audiocraft.models import MusicGen
|
||||
|
||||
class MusicGenerator:
|
||||
def __init__(self, model_name="facebook/musicgen-medium"):
|
||||
self.model = MusicGen.get_pretrained(model_name)
|
||||
self.sample_rate = 32000
|
||||
|
||||
def generate(self, prompt, duration=30, temperature=1.0, cfg=3.0):
|
||||
self.model.set_generation_params(
|
||||
duration=duration,
|
||||
top_k=250,
|
||||
temperature=temperature,
|
||||
cfg_coef=cfg
|
||||
)
|
||||
|
||||
with torch.no_grad():
|
||||
wav = self.model.generate([prompt])
|
||||
|
||||
return wav[0].cpu()
|
||||
|
||||
def generate_batch(self, prompts, duration=30):
|
||||
self.model.set_generation_params(duration=duration)
|
||||
|
||||
with torch.no_grad():
|
||||
wav = self.model.generate(prompts)
|
||||
|
||||
return wav.cpu()
|
||||
|
||||
def save(self, audio, path):
|
||||
torchaudio.save(path, audio, sample_rate=self.sample_rate)
|
||||
|
||||
# Usage
|
||||
generator = MusicGenerator()
|
||||
audio = generator.generate(
|
||||
"epic cinematic orchestral music",
|
||||
duration=30,
|
||||
temperature=1.0
|
||||
)
|
||||
generator.save(audio, "epic_music.wav")
|
||||
```
|
||||
|
||||
### Workflow 2: Sound design batch processing
|
||||
|
||||
```python
|
||||
import json
|
||||
from pathlib import Path
|
||||
from audiocraft.models import AudioGen
|
||||
import torchaudio
|
||||
|
||||
def batch_generate_sounds(sound_specs, output_dir):
|
||||
"""
|
||||
Generate multiple sounds from specifications.
|
||||
|
||||
Args:
|
||||
sound_specs: list of {"name": str, "description": str, "duration": float}
|
||||
output_dir: output directory path
|
||||
"""
|
||||
model = AudioGen.get_pretrained('facebook/audiogen-medium')
|
||||
output_dir = Path(output_dir)
|
||||
output_dir.mkdir(exist_ok=True)
|
||||
|
||||
results = []
|
||||
|
||||
for spec in sound_specs:
|
||||
model.set_generation_params(duration=spec.get("duration", 5))
|
||||
|
||||
wav = model.generate([spec["description"]])
|
||||
|
||||
output_path = output_dir / f"{spec['name']}.wav"
|
||||
torchaudio.save(str(output_path), wav[0].cpu(), sample_rate=16000)
|
||||
|
||||
results.append({
|
||||
"name": spec["name"],
|
||||
"path": str(output_path),
|
||||
"description": spec["description"]
|
||||
})
|
||||
|
||||
return results
|
||||
|
||||
# Usage
|
||||
sounds = [
|
||||
{"name": "explosion", "description": "massive explosion with debris", "duration": 3},
|
||||
{"name": "footsteps", "description": "footsteps on wooden floor", "duration": 5},
|
||||
{"name": "door", "description": "wooden door creaking and closing", "duration": 2}
|
||||
]
|
||||
|
||||
results = batch_generate_sounds(sounds, "sound_effects/")
|
||||
```
|
||||
|
||||
### Workflow 3: Gradio demo
|
||||
|
||||
```python
|
||||
import gradio as gr
|
||||
import torch
|
||||
import torchaudio
|
||||
from audiocraft.models import MusicGen
|
||||
|
||||
model = MusicGen.get_pretrained('facebook/musicgen-small')
|
||||
|
||||
def generate_music(prompt, duration, temperature, cfg_coef):
|
||||
model.set_generation_params(
|
||||
duration=duration,
|
||||
temperature=temperature,
|
||||
cfg_coef=cfg_coef
|
||||
)
|
||||
|
||||
with torch.no_grad():
|
||||
wav = model.generate([prompt])
|
||||
|
||||
# Save to temp file
|
||||
path = "temp_output.wav"
|
||||
torchaudio.save(path, wav[0].cpu(), sample_rate=32000)
|
||||
return path
|
||||
|
||||
demo = gr.Interface(
|
||||
fn=generate_music,
|
||||
inputs=[
|
||||
gr.Textbox(label="Music Description", placeholder="upbeat electronic dance music"),
|
||||
gr.Slider(1, 30, value=8, label="Duration (seconds)"),
|
||||
gr.Slider(0.5, 2.0, value=1.0, label="Temperature"),
|
||||
gr.Slider(1.0, 10.0, value=3.0, label="CFG Coefficient")
|
||||
],
|
||||
outputs=gr.Audio(label="Generated Music"),
|
||||
title="MusicGen Demo"
|
||||
)
|
||||
|
||||
demo.launch()
|
||||
```
|
||||
|
||||
## Performance optimization
|
||||
|
||||
### Memory optimization
|
||||
|
||||
```python
|
||||
# Use smaller model
|
||||
model = MusicGen.get_pretrained('facebook/musicgen-small')
|
||||
|
||||
# Clear cache between generations
|
||||
torch.cuda.empty_cache()
|
||||
|
||||
# Generate shorter durations
|
||||
model.set_generation_params(duration=10) # Instead of 30
|
||||
|
||||
# Use half precision
|
||||
model = model.half()
|
||||
```
|
||||
|
||||
### Batch processing efficiency
|
||||
|
||||
```python
|
||||
# Process multiple prompts at once (more efficient)
|
||||
descriptions = ["prompt1", "prompt2", "prompt3", "prompt4"]
|
||||
wav = model.generate(descriptions) # Single batch
|
||||
|
||||
# Instead of
|
||||
for desc in descriptions:
|
||||
wav = model.generate([desc]) # Multiple batches (slower)
|
||||
```
|
||||
|
||||
### GPU memory requirements
|
||||
|
||||
| Model | FP32 VRAM | FP16 VRAM |
|
||||
|-------|-----------|-----------|
|
||||
| musicgen-small | ~4GB | ~2GB |
|
||||
| musicgen-medium | ~8GB | ~4GB |
|
||||
| musicgen-large | ~16GB | ~8GB |
|
||||
|
||||
## Common issues
|
||||
|
||||
| Issue | Solution |
|
||||
|-------|----------|
|
||||
| CUDA OOM | Use smaller model, reduce duration |
|
||||
| Poor quality | Increase cfg_coef, better prompts |
|
||||
| Generation too short | Check max duration setting |
|
||||
| Audio artifacts | Try different temperature |
|
||||
| Stereo not working | Use stereo model variant |
|
||||
|
||||
## References
|
||||
|
||||
- **[Advanced Usage](references/advanced-usage.md)** - Training, fine-tuning, deployment
|
||||
- **[Troubleshooting](references/troubleshooting.md)** - Common issues and solutions
|
||||
|
||||
## Resources
|
||||
|
||||
- **GitHub**: https://github.com/facebookresearch/audiocraft
|
||||
- **Paper (MusicGen)**: https://arxiv.org/abs/2306.05284
|
||||
- **Paper (AudioGen)**: https://arxiv.org/abs/2209.15352
|
||||
- **HuggingFace**: https://huggingface.co/facebook/musicgen-small
|
||||
- **Demo**: https://huggingface.co/spaces/facebook/MusicGen
|
||||
@@ -0,0 +1,666 @@
|
||||
# AudioCraft Advanced Usage Guide
|
||||
|
||||
## Fine-tuning MusicGen
|
||||
|
||||
### Custom dataset preparation
|
||||
|
||||
```python
|
||||
import os
|
||||
import json
|
||||
from pathlib import Path
|
||||
import torchaudio
|
||||
|
||||
def prepare_dataset(audio_dir, output_dir, metadata_file):
|
||||
"""
|
||||
Prepare dataset for MusicGen fine-tuning.
|
||||
|
||||
Directory structure:
|
||||
output_dir/
|
||||
├── audio/
|
||||
│ ├── 0001.wav
|
||||
│ ├── 0002.wav
|
||||
│ └── ...
|
||||
└── metadata.json
|
||||
"""
|
||||
output_dir = Path(output_dir)
|
||||
audio_output = output_dir / "audio"
|
||||
audio_output.mkdir(parents=True, exist_ok=True)
|
||||
|
||||
# Load metadata (format: {"path": "...", "description": "..."})
|
||||
with open(metadata_file) as f:
|
||||
metadata = json.load(f)
|
||||
|
||||
processed = []
|
||||
|
||||
for idx, item in enumerate(metadata):
|
||||
audio_path = Path(audio_dir) / item["path"]
|
||||
|
||||
# Load and resample to 32kHz
|
||||
wav, sr = torchaudio.load(str(audio_path))
|
||||
if sr != 32000:
|
||||
resampler = torchaudio.transforms.Resample(sr, 32000)
|
||||
wav = resampler(wav)
|
||||
|
||||
# Convert to mono if stereo
|
||||
if wav.shape[0] > 1:
|
||||
wav = wav.mean(dim=0, keepdim=True)
|
||||
|
||||
# Save processed audio
|
||||
output_path = audio_output / f"{idx:04d}.wav"
|
||||
torchaudio.save(str(output_path), wav, sample_rate=32000)
|
||||
|
||||
processed.append({
|
||||
"path": str(output_path.relative_to(output_dir)),
|
||||
"description": item["description"],
|
||||
"duration": wav.shape[1] / 32000
|
||||
})
|
||||
|
||||
# Save processed metadata
|
||||
with open(output_dir / "metadata.json", "w") as f:
|
||||
json.dump(processed, f, indent=2)
|
||||
|
||||
print(f"Processed {len(processed)} samples")
|
||||
return processed
|
||||
```
|
||||
|
||||
### Fine-tuning with dora
|
||||
|
||||
```bash
|
||||
# AudioCraft uses dora for experiment management
|
||||
# Install dora
|
||||
pip install dora-search
|
||||
|
||||
# Clone AudioCraft
|
||||
git clone https://github.com/facebookresearch/audiocraft.git
|
||||
cd audiocraft
|
||||
|
||||
# Create config for fine-tuning
|
||||
cat > config/solver/musicgen/finetune.yaml << 'EOF'
|
||||
defaults:
|
||||
- musicgen/musicgen_base
|
||||
- /model: lm/musicgen_lm
|
||||
- /conditioner: cond_base
|
||||
|
||||
solver: musicgen
|
||||
autocast: true
|
||||
autocast_dtype: float16
|
||||
|
||||
optim:
|
||||
epochs: 100
|
||||
batch_size: 4
|
||||
lr: 1e-4
|
||||
ema: 0.999
|
||||
optimizer: adamw
|
||||
|
||||
dataset:
|
||||
batch_size: 4
|
||||
num_workers: 4
|
||||
train:
|
||||
- dset: your_dataset
|
||||
root: /path/to/dataset
|
||||
valid:
|
||||
- dset: your_dataset
|
||||
root: /path/to/dataset
|
||||
|
||||
checkpoint:
|
||||
save_every: 10
|
||||
keep_every_states: null
|
||||
EOF
|
||||
|
||||
# Run fine-tuning
|
||||
dora run solver=musicgen/finetune
|
||||
```
|
||||
|
||||
### LoRA fine-tuning
|
||||
|
||||
```python
|
||||
from peft import LoraConfig, get_peft_model
|
||||
from audiocraft.models import MusicGen
|
||||
import torch
|
||||
|
||||
# Load base model
|
||||
model = MusicGen.get_pretrained('facebook/musicgen-small')
|
||||
|
||||
# Get the language model component
|
||||
lm = model.lm
|
||||
|
||||
# Configure LoRA
|
||||
lora_config = LoraConfig(
|
||||
r=8,
|
||||
lora_alpha=16,
|
||||
target_modules=["q_proj", "v_proj", "k_proj", "out_proj"],
|
||||
lora_dropout=0.05,
|
||||
bias="none"
|
||||
)
|
||||
|
||||
# Apply LoRA
|
||||
lm = get_peft_model(lm, lora_config)
|
||||
lm.print_trainable_parameters()
|
||||
```
|
||||
|
||||
## Multi-GPU Training
|
||||
|
||||
### DataParallel
|
||||
|
||||
```python
|
||||
import torch
|
||||
import torch.nn as nn
|
||||
from audiocraft.models import MusicGen
|
||||
|
||||
model = MusicGen.get_pretrained('facebook/musicgen-small')
|
||||
|
||||
# Wrap LM with DataParallel
|
||||
if torch.cuda.device_count() > 1:
|
||||
model.lm = nn.DataParallel(model.lm)
|
||||
|
||||
model.to("cuda")
|
||||
```
|
||||
|
||||
### DistributedDataParallel
|
||||
|
||||
```python
|
||||
import torch.distributed as dist
|
||||
from torch.nn.parallel import DistributedDataParallel as DDP
|
||||
|
||||
def setup(rank, world_size):
|
||||
dist.init_process_group("nccl", rank=rank, world_size=world_size)
|
||||
torch.cuda.set_device(rank)
|
||||
|
||||
def train(rank, world_size):
|
||||
setup(rank, world_size)
|
||||
|
||||
model = MusicGen.get_pretrained('facebook/musicgen-small')
|
||||
model.lm = model.lm.to(rank)
|
||||
model.lm = DDP(model.lm, device_ids=[rank])
|
||||
|
||||
# Training loop
|
||||
# ...
|
||||
|
||||
dist.destroy_process_group()
|
||||
```
|
||||
|
||||
## Custom Conditioning
|
||||
|
||||
### Adding new conditioners
|
||||
|
||||
```python
|
||||
from audiocraft.modules.conditioners import BaseConditioner
|
||||
import torch
|
||||
|
||||
class CustomConditioner(BaseConditioner):
|
||||
"""Custom conditioner for additional control signals."""
|
||||
|
||||
def __init__(self, dim, output_dim):
|
||||
super().__init__(dim, output_dim)
|
||||
self.embed = torch.nn.Linear(dim, output_dim)
|
||||
|
||||
def forward(self, x):
|
||||
return self.embed(x)
|
||||
|
||||
def tokenize(self, x):
|
||||
# Tokenize input for conditioning
|
||||
return x
|
||||
|
||||
# Use with MusicGen
|
||||
from audiocraft.models.builders import get_lm_model
|
||||
|
||||
# Modify model config to include custom conditioner
|
||||
# This requires editing the model configuration
|
||||
```
|
||||
|
||||
### Melody conditioning internals
|
||||
|
||||
```python
|
||||
from audiocraft.models import MusicGen
|
||||
from audiocraft.modules.codebooks_patterns import DelayedPatternProvider
|
||||
import torch
|
||||
|
||||
model = MusicGen.get_pretrained('facebook/musicgen-melody')
|
||||
|
||||
# Access chroma extractor
|
||||
chroma_extractor = model.lm.condition_provider.conditioners.get('chroma')
|
||||
|
||||
# Manual chroma extraction
|
||||
def extract_chroma(audio, sr):
|
||||
"""Extract chroma features from audio."""
|
||||
import librosa
|
||||
|
||||
# Compute chroma
|
||||
chroma = librosa.feature.chroma_cqt(y=audio.numpy(), sr=sr)
|
||||
|
||||
return torch.from_numpy(chroma).float()
|
||||
|
||||
# Use extracted chroma for conditioning
|
||||
chroma = extract_chroma(melody_audio, sample_rate)
|
||||
```
|
||||
|
||||
## EnCodec Deep Dive
|
||||
|
||||
### Custom compression settings
|
||||
|
||||
```python
|
||||
from audiocraft.models import CompressionModel
|
||||
import torch
|
||||
|
||||
# Load EnCodec
|
||||
encodec = CompressionModel.get_pretrained('facebook/encodec_32khz')
|
||||
|
||||
# Access codec parameters
|
||||
print(f"Sample rate: {encodec.sample_rate}")
|
||||
print(f"Channels: {encodec.channels}")
|
||||
print(f"Cardinality: {encodec.cardinality}") # Codebook size
|
||||
print(f"Num codebooks: {encodec.num_codebooks}")
|
||||
print(f"Frame rate: {encodec.frame_rate}")
|
||||
|
||||
# Encode with specific bandwidth
|
||||
# Lower bandwidth = more compression, lower quality
|
||||
encodec.set_target_bandwidth(6.0) # 6 kbps
|
||||
|
||||
audio = torch.randn(1, 1, 32000) # 1 second
|
||||
encoded = encodec.encode(audio)
|
||||
decoded = encodec.decode(encoded[0])
|
||||
```
|
||||
|
||||
### Streaming encoding
|
||||
|
||||
```python
|
||||
import torch
|
||||
from audiocraft.models import CompressionModel
|
||||
|
||||
encodec = CompressionModel.get_pretrained('facebook/encodec_32khz')
|
||||
|
||||
def encode_streaming(audio_stream, chunk_size=32000):
|
||||
"""Encode audio in streaming fashion."""
|
||||
all_codes = []
|
||||
|
||||
for chunk in audio_stream:
|
||||
# Ensure chunk is right shape
|
||||
if chunk.dim() == 1:
|
||||
chunk = chunk.unsqueeze(0).unsqueeze(0)
|
||||
|
||||
with torch.no_grad():
|
||||
codes = encodec.encode(chunk)[0]
|
||||
all_codes.append(codes)
|
||||
|
||||
return torch.cat(all_codes, dim=-1)
|
||||
|
||||
def decode_streaming(codes_stream, output_stream):
|
||||
"""Decode codes in streaming fashion."""
|
||||
for codes in codes_stream:
|
||||
with torch.no_grad():
|
||||
audio = encodec.decode(codes)
|
||||
output_stream.write(audio.cpu().numpy())
|
||||
```
|
||||
|
||||
## MultiBand Diffusion
|
||||
|
||||
### Using MBD for enhanced quality
|
||||
|
||||
```python
|
||||
from audiocraft.models import MusicGen, MultiBandDiffusion
|
||||
|
||||
# Load MusicGen
|
||||
model = MusicGen.get_pretrained('facebook/musicgen-medium')
|
||||
|
||||
# Load MultiBand Diffusion
|
||||
mbd = MultiBandDiffusion.get_mbd_musicgen()
|
||||
|
||||
model.set_generation_params(duration=10)
|
||||
|
||||
# Generate with standard decoder
|
||||
descriptions = ["epic orchestral music"]
|
||||
wav_standard = model.generate(descriptions)
|
||||
|
||||
# Generate tokens and use MBD decoder
|
||||
with torch.no_grad():
|
||||
# Get tokens
|
||||
gen_tokens = model.generate_tokens(descriptions)
|
||||
|
||||
# Decode with MBD
|
||||
wav_mbd = mbd.tokens_to_wav(gen_tokens)
|
||||
|
||||
# Compare quality
|
||||
print(f"Standard shape: {wav_standard.shape}")
|
||||
print(f"MBD shape: {wav_mbd.shape}")
|
||||
```
|
||||
|
||||
## API Server Deployment
|
||||
|
||||
### FastAPI server
|
||||
|
||||
```python
|
||||
from fastapi import FastAPI, HTTPException
|
||||
from pydantic import BaseModel
|
||||
import torch
|
||||
import torchaudio
|
||||
from audiocraft.models import MusicGen
|
||||
import io
|
||||
import base64
|
||||
|
||||
app = FastAPI()
|
||||
|
||||
# Load model at startup
|
||||
model = None
|
||||
|
||||
@app.on_event("startup")
|
||||
async def load_model():
|
||||
global model
|
||||
model = MusicGen.get_pretrained('facebook/musicgen-small')
|
||||
model.set_generation_params(duration=10)
|
||||
|
||||
class GenerateRequest(BaseModel):
|
||||
prompt: str
|
||||
duration: float = 10.0
|
||||
temperature: float = 1.0
|
||||
cfg_coef: float = 3.0
|
||||
|
||||
class GenerateResponse(BaseModel):
|
||||
audio_base64: str
|
||||
sample_rate: int
|
||||
duration: float
|
||||
|
||||
@app.post("/generate", response_model=GenerateResponse)
|
||||
async def generate(request: GenerateRequest):
|
||||
if model is None:
|
||||
raise HTTPException(status_code=500, detail="Model not loaded")
|
||||
|
||||
try:
|
||||
model.set_generation_params(
|
||||
duration=min(request.duration, 30),
|
||||
temperature=request.temperature,
|
||||
cfg_coef=request.cfg_coef
|
||||
)
|
||||
|
||||
with torch.no_grad():
|
||||
wav = model.generate([request.prompt])
|
||||
|
||||
# Convert to bytes
|
||||
buffer = io.BytesIO()
|
||||
torchaudio.save(buffer, wav[0].cpu(), sample_rate=32000, format="wav")
|
||||
buffer.seek(0)
|
||||
|
||||
audio_base64 = base64.b64encode(buffer.read()).decode()
|
||||
|
||||
return GenerateResponse(
|
||||
audio_base64=audio_base64,
|
||||
sample_rate=32000,
|
||||
duration=wav.shape[-1] / 32000
|
||||
)
|
||||
|
||||
except Exception as e:
|
||||
raise HTTPException(status_code=500, detail=str(e))
|
||||
|
||||
@app.get("/health")
|
||||
async def health():
|
||||
return {"status": "ok", "model_loaded": model is not None}
|
||||
|
||||
# Run: uvicorn server:app --host 0.0.0.0 --port 8000
|
||||
```
|
||||
|
||||
### Batch processing service
|
||||
|
||||
```python
|
||||
import asyncio
|
||||
from concurrent.futures import ThreadPoolExecutor
|
||||
import torch
|
||||
from audiocraft.models import MusicGen
|
||||
|
||||
class MusicGenService:
|
||||
def __init__(self, model_name='facebook/musicgen-small', max_workers=2):
|
||||
self.model = MusicGen.get_pretrained(model_name)
|
||||
self.executor = ThreadPoolExecutor(max_workers=max_workers)
|
||||
self.lock = asyncio.Lock()
|
||||
|
||||
async def generate_async(self, prompt, duration=10):
|
||||
"""Async generation with thread pool."""
|
||||
loop = asyncio.get_event_loop()
|
||||
|
||||
def _generate():
|
||||
with torch.no_grad():
|
||||
self.model.set_generation_params(duration=duration)
|
||||
return self.model.generate([prompt])
|
||||
|
||||
# Run in thread pool
|
||||
wav = await loop.run_in_executor(self.executor, _generate)
|
||||
return wav[0].cpu()
|
||||
|
||||
async def generate_batch_async(self, prompts, duration=10):
|
||||
"""Process multiple prompts concurrently."""
|
||||
tasks = [self.generate_async(p, duration) for p in prompts]
|
||||
return await asyncio.gather(*tasks)
|
||||
|
||||
# Usage
|
||||
service = MusicGenService()
|
||||
|
||||
async def main():
|
||||
prompts = ["jazz piano", "rock guitar", "electronic beats"]
|
||||
results = await service.generate_batch_async(prompts)
|
||||
return results
|
||||
```
|
||||
|
||||
## Integration Patterns
|
||||
|
||||
### LangChain tool
|
||||
|
||||
```python
|
||||
from langchain.tools import BaseTool
|
||||
import torch
|
||||
import torchaudio
|
||||
from audiocraft.models import MusicGen
|
||||
import tempfile
|
||||
|
||||
class MusicGeneratorTool(BaseTool):
|
||||
name = "music_generator"
|
||||
description = "Generate music from a text description. Input should be a detailed description of the music style, mood, and instruments."
|
||||
|
||||
def __init__(self):
|
||||
super().__init__()
|
||||
self.model = MusicGen.get_pretrained('facebook/musicgen-small')
|
||||
self.model.set_generation_params(duration=15)
|
||||
|
||||
def _run(self, description: str) -> str:
|
||||
with torch.no_grad():
|
||||
wav = self.model.generate([description])
|
||||
|
||||
# Save to temp file
|
||||
with tempfile.NamedTemporaryFile(suffix=".wav", delete=False) as f:
|
||||
torchaudio.save(f.name, wav[0].cpu(), sample_rate=32000)
|
||||
return f"Generated music saved to: {f.name}"
|
||||
|
||||
async def _arun(self, description: str) -> str:
|
||||
return self._run(description)
|
||||
```
|
||||
|
||||
### Gradio with advanced controls
|
||||
|
||||
```python
|
||||
import gradio as gr
|
||||
import torch
|
||||
import torchaudio
|
||||
from audiocraft.models import MusicGen
|
||||
|
||||
models = {}
|
||||
|
||||
def load_model(model_size):
|
||||
if model_size not in models:
|
||||
model_name = f"facebook/musicgen-{model_size}"
|
||||
models[model_size] = MusicGen.get_pretrained(model_name)
|
||||
return models[model_size]
|
||||
|
||||
def generate(prompt, duration, temperature, cfg_coef, top_k, model_size):
|
||||
model = load_model(model_size)
|
||||
|
||||
model.set_generation_params(
|
||||
duration=duration,
|
||||
temperature=temperature,
|
||||
cfg_coef=cfg_coef,
|
||||
top_k=top_k
|
||||
)
|
||||
|
||||
with torch.no_grad():
|
||||
wav = model.generate([prompt])
|
||||
|
||||
# Save
|
||||
path = "output.wav"
|
||||
torchaudio.save(path, wav[0].cpu(), sample_rate=32000)
|
||||
return path
|
||||
|
||||
demo = gr.Interface(
|
||||
fn=generate,
|
||||
inputs=[
|
||||
gr.Textbox(label="Prompt", lines=3),
|
||||
gr.Slider(1, 30, value=10, label="Duration (s)"),
|
||||
gr.Slider(0.1, 2.0, value=1.0, label="Temperature"),
|
||||
gr.Slider(0.5, 10.0, value=3.0, label="CFG Coefficient"),
|
||||
gr.Slider(50, 500, value=250, step=50, label="Top-K"),
|
||||
gr.Dropdown(["small", "medium", "large"], value="small", label="Model Size")
|
||||
],
|
||||
outputs=gr.Audio(label="Generated Music"),
|
||||
title="MusicGen Advanced",
|
||||
allow_flagging="never"
|
||||
)
|
||||
|
||||
demo.launch(share=True)
|
||||
```
|
||||
|
||||
## Audio Processing Pipeline
|
||||
|
||||
### Post-processing chain
|
||||
|
||||
```python
|
||||
import torch
|
||||
import torchaudio
|
||||
import torchaudio.transforms as T
|
||||
import numpy as np
|
||||
|
||||
class AudioPostProcessor:
|
||||
def __init__(self, sample_rate=32000):
|
||||
self.sample_rate = sample_rate
|
||||
|
||||
def normalize(self, audio, target_db=-14.0):
|
||||
"""Normalize audio to target loudness."""
|
||||
rms = torch.sqrt(torch.mean(audio ** 2))
|
||||
target_rms = 10 ** (target_db / 20)
|
||||
gain = target_rms / (rms + 1e-8)
|
||||
return audio * gain
|
||||
|
||||
def fade_in_out(self, audio, fade_duration=0.1):
|
||||
"""Apply fade in/out."""
|
||||
fade_samples = int(fade_duration * self.sample_rate)
|
||||
|
||||
# Create fade curves
|
||||
fade_in = torch.linspace(0, 1, fade_samples)
|
||||
fade_out = torch.linspace(1, 0, fade_samples)
|
||||
|
||||
# Apply fades
|
||||
audio[..., :fade_samples] *= fade_in
|
||||
audio[..., -fade_samples:] *= fade_out
|
||||
|
||||
return audio
|
||||
|
||||
def apply_reverb(self, audio, decay=0.5):
|
||||
"""Apply simple reverb effect."""
|
||||
impulse = torch.zeros(int(self.sample_rate * 0.5))
|
||||
impulse[0] = 1.0
|
||||
impulse[int(self.sample_rate * 0.1)] = decay * 0.5
|
||||
impulse[int(self.sample_rate * 0.2)] = decay * 0.25
|
||||
|
||||
# Convolve
|
||||
audio = torch.nn.functional.conv1d(
|
||||
audio.unsqueeze(0),
|
||||
impulse.unsqueeze(0).unsqueeze(0),
|
||||
padding=len(impulse) // 2
|
||||
).squeeze(0)
|
||||
|
||||
return audio
|
||||
|
||||
def process(self, audio):
|
||||
"""Full processing pipeline."""
|
||||
audio = self.normalize(audio)
|
||||
audio = self.fade_in_out(audio)
|
||||
return audio
|
||||
|
||||
# Usage with MusicGen
|
||||
from audiocraft.models import MusicGen
|
||||
|
||||
model = MusicGen.get_pretrained('facebook/musicgen-small')
|
||||
model.set_generation_params(duration=10)
|
||||
|
||||
wav = model.generate(["chill ambient music"])
|
||||
processor = AudioPostProcessor()
|
||||
wav_processed = processor.process(wav[0].cpu())
|
||||
|
||||
torchaudio.save("processed.wav", wav_processed, sample_rate=32000)
|
||||
```
|
||||
|
||||
## Evaluation
|
||||
|
||||
### Audio quality metrics
|
||||
|
||||
```python
|
||||
import torch
|
||||
from audiocraft.metrics import CLAPTextConsistencyMetric
|
||||
from audiocraft.data.audio import audio_read
|
||||
|
||||
def evaluate_generation(audio_path, text_prompt):
|
||||
"""Evaluate generated audio quality."""
|
||||
# Load audio
|
||||
wav, sr = audio_read(audio_path)
|
||||
|
||||
# CLAP consistency (text-audio alignment)
|
||||
clap_metric = CLAPTextConsistencyMetric()
|
||||
clap_score = clap_metric.compute(wav, [text_prompt])
|
||||
|
||||
return {
|
||||
"clap_score": clap_score,
|
||||
"duration": wav.shape[-1] / sr
|
||||
}
|
||||
|
||||
# Batch evaluation
|
||||
def evaluate_batch(generations):
|
||||
"""Evaluate multiple generations."""
|
||||
results = []
|
||||
for gen in generations:
|
||||
result = evaluate_generation(gen["path"], gen["prompt"])
|
||||
result["prompt"] = gen["prompt"]
|
||||
results.append(result)
|
||||
|
||||
# Aggregate
|
||||
avg_clap = sum(r["clap_score"] for r in results) / len(results)
|
||||
return {
|
||||
"individual": results,
|
||||
"average_clap": avg_clap
|
||||
}
|
||||
```
|
||||
|
||||
## Model Comparison
|
||||
|
||||
### MusicGen variants benchmark
|
||||
|
||||
| Model | CLAP Score | Generation Time (10s) | VRAM |
|
||||
|-------|------------|----------------------|------|
|
||||
| musicgen-small | 0.35 | ~5s | 2GB |
|
||||
| musicgen-medium | 0.42 | ~15s | 4GB |
|
||||
| musicgen-large | 0.48 | ~30s | 8GB |
|
||||
| musicgen-melody | 0.45 | ~15s | 4GB |
|
||||
| musicgen-stereo-medium | 0.41 | ~18s | 5GB |
|
||||
|
||||
### Prompt engineering tips
|
||||
|
||||
```python
|
||||
# Good prompts - specific and descriptive
|
||||
good_prompts = [
|
||||
"upbeat electronic dance music with synthesizer leads and punchy drums at 128 bpm",
|
||||
"melancholic piano ballad with strings, slow tempo, emotional and cinematic",
|
||||
"funky disco groove with slap bass, brass section, and rhythmic guitar"
|
||||
]
|
||||
|
||||
# Bad prompts - too vague
|
||||
bad_prompts = [
|
||||
"nice music",
|
||||
"song",
|
||||
"good beat"
|
||||
]
|
||||
|
||||
# Structure: [mood] [genre] with [instruments] at [tempo/style]
|
||||
```
|
||||
@@ -0,0 +1,504 @@
|
||||
# AudioCraft Troubleshooting Guide
|
||||
|
||||
## Installation Issues
|
||||
|
||||
### Import errors
|
||||
|
||||
**Error**: `ModuleNotFoundError: No module named 'audiocraft'`
|
||||
|
||||
**Solutions**:
|
||||
```bash
|
||||
# Install from PyPI
|
||||
pip install audiocraft
|
||||
|
||||
# Or from GitHub
|
||||
pip install git+https://github.com/facebookresearch/audiocraft.git
|
||||
|
||||
# Verify installation
|
||||
python -c "from audiocraft.models import MusicGen; print('OK')"
|
||||
```
|
||||
|
||||
### FFmpeg not found
|
||||
|
||||
**Error**: `RuntimeError: ffmpeg not found`
|
||||
|
||||
**Solutions**:
|
||||
```bash
|
||||
# Ubuntu/Debian
|
||||
sudo apt-get install ffmpeg
|
||||
|
||||
# macOS
|
||||
brew install ffmpeg
|
||||
|
||||
# Windows (using conda)
|
||||
conda install -c conda-forge ffmpeg
|
||||
|
||||
# Verify
|
||||
ffmpeg -version
|
||||
```
|
||||
|
||||
### PyTorch CUDA mismatch
|
||||
|
||||
**Error**: `RuntimeError: CUDA error: no kernel image is available`
|
||||
|
||||
**Solutions**:
|
||||
```bash
|
||||
# Check CUDA version
|
||||
nvcc --version
|
||||
python -c "import torch; print(torch.version.cuda)"
|
||||
|
||||
# Install matching PyTorch
|
||||
pip install torch torchaudio --index-url https://download.pytorch.org/whl/cu121
|
||||
|
||||
# For CUDA 11.8
|
||||
pip install torch torchaudio --index-url https://download.pytorch.org/whl/cu118
|
||||
```
|
||||
|
||||
### xformers issues
|
||||
|
||||
**Error**: `ImportError: xformers` related errors
|
||||
|
||||
**Solutions**:
|
||||
```bash
|
||||
# Install xformers for memory efficiency
|
||||
pip install xformers
|
||||
|
||||
# Or disable xformers
|
||||
export AUDIOCRAFT_USE_XFORMERS=0
|
||||
|
||||
# In Python
|
||||
import os
|
||||
os.environ["AUDIOCRAFT_USE_XFORMERS"] = "0"
|
||||
from audiocraft.models import MusicGen
|
||||
```
|
||||
|
||||
## Model Loading Issues
|
||||
|
||||
### Out of memory during load
|
||||
|
||||
**Error**: `torch.cuda.OutOfMemoryError` during model loading
|
||||
|
||||
**Solutions**:
|
||||
```python
|
||||
# Use smaller model
|
||||
model = MusicGen.get_pretrained('facebook/musicgen-small')
|
||||
|
||||
# Force CPU loading first
|
||||
import torch
|
||||
device = "cpu"
|
||||
model = MusicGen.get_pretrained('facebook/musicgen-small', device=device)
|
||||
model = model.to("cuda")
|
||||
|
||||
# Use HuggingFace with device_map
|
||||
from transformers import MusicgenForConditionalGeneration
|
||||
model = MusicgenForConditionalGeneration.from_pretrained(
|
||||
"facebook/musicgen-small",
|
||||
device_map="auto"
|
||||
)
|
||||
```
|
||||
|
||||
### Download failures
|
||||
|
||||
**Error**: Connection errors or incomplete downloads
|
||||
|
||||
**Solutions**:
|
||||
```python
|
||||
# Set cache directory
|
||||
import os
|
||||
os.environ["AUDIOCRAFT_CACHE_DIR"] = "/path/to/cache"
|
||||
|
||||
# Or for HuggingFace
|
||||
os.environ["HF_HOME"] = "/path/to/hf_cache"
|
||||
|
||||
# Resume download
|
||||
from huggingface_hub import snapshot_download
|
||||
snapshot_download("facebook/musicgen-small", resume_download=True)
|
||||
|
||||
# Use local files
|
||||
model = MusicGen.get_pretrained('/local/path/to/model')
|
||||
```
|
||||
|
||||
### Wrong model type
|
||||
|
||||
**Error**: Loading wrong model for task
|
||||
|
||||
**Solutions**:
|
||||
```python
|
||||
# For text-to-music: use MusicGen
|
||||
from audiocraft.models import MusicGen
|
||||
model = MusicGen.get_pretrained('facebook/musicgen-medium')
|
||||
|
||||
# For text-to-sound: use AudioGen
|
||||
from audiocraft.models import AudioGen
|
||||
model = AudioGen.get_pretrained('facebook/audiogen-medium')
|
||||
|
||||
# For melody conditioning: use melody variant
|
||||
model = MusicGen.get_pretrained('facebook/musicgen-melody')
|
||||
|
||||
# For stereo: use stereo variant
|
||||
model = MusicGen.get_pretrained('facebook/musicgen-stereo-medium')
|
||||
```
|
||||
|
||||
## Generation Issues
|
||||
|
||||
### Empty or silent output
|
||||
|
||||
**Problem**: Generated audio is silent or very quiet
|
||||
|
||||
**Solutions**:
|
||||
```python
|
||||
import torch
|
||||
|
||||
# Check output
|
||||
wav = model.generate(["upbeat music"])
|
||||
print(f"Shape: {wav.shape}")
|
||||
print(f"Max amplitude: {wav.abs().max().item()}")
|
||||
print(f"Mean amplitude: {wav.abs().mean().item()}")
|
||||
|
||||
# If too quiet, normalize
|
||||
def normalize_audio(audio, target_db=-14.0):
|
||||
rms = torch.sqrt(torch.mean(audio ** 2))
|
||||
target_rms = 10 ** (target_db / 20)
|
||||
gain = target_rms / (rms + 1e-8)
|
||||
return audio * gain
|
||||
|
||||
wav_normalized = normalize_audio(wav)
|
||||
```
|
||||
|
||||
### Poor quality output
|
||||
|
||||
**Problem**: Generated music sounds bad or noisy
|
||||
|
||||
**Solutions**:
|
||||
```python
|
||||
# Use larger model
|
||||
model = MusicGen.get_pretrained('facebook/musicgen-large')
|
||||
|
||||
# Adjust generation parameters
|
||||
model.set_generation_params(
|
||||
duration=15,
|
||||
top_k=250, # Increase for more diversity
|
||||
temperature=0.8, # Lower for more focused output
|
||||
cfg_coef=4.0 # Increase for better text adherence
|
||||
)
|
||||
|
||||
# Use better prompts
|
||||
# Bad: "music"
|
||||
# Good: "upbeat electronic dance music with synthesizers and punchy drums"
|
||||
|
||||
# Try MultiBand Diffusion
|
||||
from audiocraft.models import MultiBandDiffusion
|
||||
mbd = MultiBandDiffusion.get_mbd_musicgen()
|
||||
tokens = model.generate_tokens(["prompt"])
|
||||
wav = mbd.tokens_to_wav(tokens)
|
||||
```
|
||||
|
||||
### Generation too short
|
||||
|
||||
**Problem**: Audio shorter than expected
|
||||
|
||||
**Solutions**:
|
||||
```python
|
||||
# Check duration setting
|
||||
model.set_generation_params(duration=30) # Set before generate
|
||||
|
||||
# Verify in generation
|
||||
print(f"Duration setting: {model.generation_params}")
|
||||
|
||||
# Check output shape
|
||||
wav = model.generate(["prompt"])
|
||||
actual_duration = wav.shape[-1] / 32000
|
||||
print(f"Actual duration: {actual_duration}s")
|
||||
|
||||
# Note: max duration is typically 30s
|
||||
```
|
||||
|
||||
### Melody conditioning fails
|
||||
|
||||
**Error**: Issues with melody-conditioned generation
|
||||
|
||||
**Solutions**:
|
||||
```python
|
||||
import torchaudio
|
||||
from audiocraft.models import MusicGen
|
||||
|
||||
# Load melody model (not base model)
|
||||
model = MusicGen.get_pretrained('facebook/musicgen-melody')
|
||||
|
||||
# Load and prepare melody
|
||||
melody, sr = torchaudio.load("melody.wav")
|
||||
|
||||
# Resample to model sample rate if needed
|
||||
if sr != 32000:
|
||||
resampler = torchaudio.transforms.Resample(sr, 32000)
|
||||
melody = resampler(melody)
|
||||
|
||||
# Ensure correct shape [batch, channels, samples]
|
||||
if melody.dim() == 1:
|
||||
melody = melody.unsqueeze(0).unsqueeze(0)
|
||||
elif melody.dim() == 2:
|
||||
melody = melody.unsqueeze(0)
|
||||
|
||||
# Convert stereo to mono
|
||||
if melody.shape[1] > 1:
|
||||
melody = melody.mean(dim=1, keepdim=True)
|
||||
|
||||
# Generate with melody
|
||||
model.set_generation_params(duration=min(melody.shape[-1] / 32000, 30))
|
||||
wav = model.generate_with_chroma(["piano cover"], melody, 32000)
|
||||
```
|
||||
|
||||
## Memory Issues
|
||||
|
||||
### CUDA out of memory
|
||||
|
||||
**Error**: `torch.cuda.OutOfMemoryError: CUDA out of memory`
|
||||
|
||||
**Solutions**:
|
||||
```python
|
||||
import torch
|
||||
|
||||
# Clear cache before generation
|
||||
torch.cuda.empty_cache()
|
||||
|
||||
# Use smaller model
|
||||
model = MusicGen.get_pretrained('facebook/musicgen-small')
|
||||
|
||||
# Reduce duration
|
||||
model.set_generation_params(duration=10) # Instead of 30
|
||||
|
||||
# Generate one at a time
|
||||
for prompt in prompts:
|
||||
wav = model.generate([prompt])
|
||||
save_audio(wav)
|
||||
torch.cuda.empty_cache()
|
||||
|
||||
# Use CPU for very large generations
|
||||
model = MusicGen.get_pretrained('facebook/musicgen-small', device="cpu")
|
||||
```
|
||||
|
||||
### Memory leak during batch processing
|
||||
|
||||
**Problem**: Memory grows over time
|
||||
|
||||
**Solutions**:
|
||||
```python
|
||||
import gc
|
||||
import torch
|
||||
|
||||
def generate_with_cleanup(model, prompts):
|
||||
results = []
|
||||
|
||||
for prompt in prompts:
|
||||
with torch.no_grad():
|
||||
wav = model.generate([prompt])
|
||||
results.append(wav.cpu())
|
||||
|
||||
# Cleanup
|
||||
del wav
|
||||
gc.collect()
|
||||
torch.cuda.empty_cache()
|
||||
|
||||
return results
|
||||
|
||||
# Use context manager
|
||||
with torch.inference_mode():
|
||||
wav = model.generate(["prompt"])
|
||||
```
|
||||
|
||||
## Audio Format Issues
|
||||
|
||||
### Wrong sample rate
|
||||
|
||||
**Problem**: Audio plays at wrong speed
|
||||
|
||||
**Solutions**:
|
||||
```python
|
||||
import torchaudio
|
||||
|
||||
# MusicGen outputs at 32kHz
|
||||
sample_rate = 32000
|
||||
|
||||
# AudioGen outputs at 16kHz
|
||||
sample_rate = 16000
|
||||
|
||||
# Always use correct rate when saving
|
||||
torchaudio.save("output.wav", wav[0].cpu(), sample_rate=sample_rate)
|
||||
|
||||
# Resample if needed
|
||||
resampler = torchaudio.transforms.Resample(32000, 44100)
|
||||
wav_resampled = resampler(wav)
|
||||
```
|
||||
|
||||
### Stereo/mono mismatch
|
||||
|
||||
**Problem**: Wrong number of channels
|
||||
|
||||
**Solutions**:
|
||||
```python
|
||||
# Check model type
|
||||
print(f"Audio channels: {wav.shape}")
|
||||
# Mono: [batch, 1, samples]
|
||||
# Stereo: [batch, 2, samples]
|
||||
|
||||
# Convert mono to stereo
|
||||
if wav.shape[1] == 1:
|
||||
wav_stereo = wav.repeat(1, 2, 1)
|
||||
|
||||
# Convert stereo to mono
|
||||
if wav.shape[1] == 2:
|
||||
wav_mono = wav.mean(dim=1, keepdim=True)
|
||||
|
||||
# Use stereo model for stereo output
|
||||
model = MusicGen.get_pretrained('facebook/musicgen-stereo-medium')
|
||||
```
|
||||
|
||||
### Clipping and distortion
|
||||
|
||||
**Problem**: Audio has clipping or distortion
|
||||
|
||||
**Solutions**:
|
||||
```python
|
||||
import torch
|
||||
|
||||
# Check for clipping
|
||||
max_val = wav.abs().max().item()
|
||||
print(f"Max amplitude: {max_val}")
|
||||
|
||||
# Normalize to prevent clipping
|
||||
if max_val > 1.0:
|
||||
wav = wav / max_val
|
||||
|
||||
# Apply soft clipping
|
||||
def soft_clip(x, threshold=0.9):
|
||||
return torch.tanh(x / threshold) * threshold
|
||||
|
||||
wav_clipped = soft_clip(wav)
|
||||
|
||||
# Lower temperature during generation
|
||||
model.set_generation_params(temperature=0.7) # More controlled
|
||||
```
|
||||
|
||||
## HuggingFace Transformers Issues
|
||||
|
||||
### Processor errors
|
||||
|
||||
**Error**: Issues with MusicgenProcessor
|
||||
|
||||
**Solutions**:
|
||||
```python
|
||||
from transformers import AutoProcessor, MusicgenForConditionalGeneration
|
||||
|
||||
# Load matching processor and model
|
||||
processor = AutoProcessor.from_pretrained("facebook/musicgen-small")
|
||||
model = MusicgenForConditionalGeneration.from_pretrained("facebook/musicgen-small")
|
||||
|
||||
# Ensure inputs are on same device
|
||||
inputs = processor(
|
||||
text=["prompt"],
|
||||
padding=True,
|
||||
return_tensors="pt"
|
||||
).to("cuda")
|
||||
|
||||
# Check processor configuration
|
||||
print(processor.tokenizer)
|
||||
print(processor.feature_extractor)
|
||||
```
|
||||
|
||||
### Generation parameter errors
|
||||
|
||||
**Error**: Invalid generation parameters
|
||||
|
||||
**Solutions**:
|
||||
```python
|
||||
# HuggingFace uses different parameter names
|
||||
audio_values = model.generate(
|
||||
**inputs,
|
||||
do_sample=True, # Enable sampling
|
||||
guidance_scale=3.0, # CFG (not cfg_coef)
|
||||
max_new_tokens=256, # Token limit (not duration)
|
||||
temperature=1.0
|
||||
)
|
||||
|
||||
# Calculate tokens from duration
|
||||
# ~50 tokens per second
|
||||
duration_seconds = 10
|
||||
max_tokens = duration_seconds * 50
|
||||
audio_values = model.generate(**inputs, max_new_tokens=max_tokens)
|
||||
```
|
||||
|
||||
## Performance Issues
|
||||
|
||||
### Slow generation
|
||||
|
||||
**Problem**: Generation takes too long
|
||||
|
||||
**Solutions**:
|
||||
```python
|
||||
# Use smaller model
|
||||
model = MusicGen.get_pretrained('facebook/musicgen-small')
|
||||
|
||||
# Reduce duration
|
||||
model.set_generation_params(duration=10)
|
||||
|
||||
# Use GPU
|
||||
model.to("cuda")
|
||||
|
||||
# Enable flash attention if available
|
||||
# (requires compatible hardware)
|
||||
|
||||
# Batch multiple prompts
|
||||
prompts = ["prompt1", "prompt2", "prompt3"]
|
||||
wav = model.generate(prompts) # Single batch is faster than loop
|
||||
|
||||
# Use compile (PyTorch 2.0+)
|
||||
model.lm = torch.compile(model.lm)
|
||||
```
|
||||
|
||||
### CPU fallback
|
||||
|
||||
**Problem**: Generation running on CPU instead of GPU
|
||||
|
||||
**Solutions**:
|
||||
```python
|
||||
import torch
|
||||
|
||||
# Check CUDA availability
|
||||
print(f"CUDA available: {torch.cuda.is_available()}")
|
||||
print(f"CUDA device: {torch.cuda.get_device_name(0)}")
|
||||
|
||||
# Explicitly move to GPU
|
||||
model = MusicGen.get_pretrained('facebook/musicgen-small')
|
||||
model.to("cuda")
|
||||
|
||||
# Verify model device
|
||||
print(f"Model device: {next(model.lm.parameters()).device}")
|
||||
```
|
||||
|
||||
## Common Error Messages
|
||||
|
||||
| Error | Cause | Solution |
|
||||
|-------|-------|----------|
|
||||
| `CUDA out of memory` | Model too large | Use smaller model, reduce duration |
|
||||
| `ffmpeg not found` | FFmpeg not installed | Install FFmpeg |
|
||||
| `No module named 'audiocraft'` | Not installed | `pip install audiocraft` |
|
||||
| `RuntimeError: Expected 3D tensor` | Wrong input shape | Check tensor dimensions |
|
||||
| `KeyError: 'melody'` | Wrong model for melody | Use musicgen-melody |
|
||||
| `Sample rate mismatch` | Wrong audio format | Resample to model rate |
|
||||
|
||||
## Getting Help
|
||||
|
||||
1. **GitHub Issues**: https://github.com/facebookresearch/audiocraft/issues
|
||||
2. **HuggingFace Forums**: https://discuss.huggingface.co
|
||||
3. **Paper**: https://arxiv.org/abs/2306.05284
|
||||
|
||||
### Reporting Issues
|
||||
|
||||
Include:
|
||||
- Python version
|
||||
- PyTorch version
|
||||
- CUDA version
|
||||
- AudioCraft version: `pip show audiocraft`
|
||||
- Full error traceback
|
||||
- Minimal reproducible code
|
||||
- Hardware (GPU model, VRAM)
|
||||
@@ -0,0 +1,48 @@
|
||||
# Port Notes — baoyu-article-illustrator
|
||||
|
||||
Ported from [JimLiu/baoyu-skills](https://github.com/JimLiu/baoyu-skills) v1.57.0.
|
||||
|
||||
## Changes from upstream
|
||||
|
||||
`SKILL.md`, `references/workflow.md`, `references/usage.md`, `references/style-presets.md`, `references/styles.md`, `references/prompt-construction.md`, and `prompts/system.md` were adapted. The 23 style files and 4 palette files are verbatim copies. The `references/config/` directory was removed entirely.
|
||||
|
||||
### Adaptations
|
||||
|
||||
| Change | Upstream | Hermes |
|
||||
|--------|----------|--------|
|
||||
| Metadata namespace | `openclaw` | `hermes` |
|
||||
| Trigger | `/baoyu-article-illustrator` slash command + CLI flags | Natural language skill matching |
|
||||
| User config | EXTEND.md (project/user/XDG paths) + first-time-setup | Removed — not part of Hermes infra |
|
||||
| User prompts | `AskUserQuestion` (batched, multi-question) | `clarify` tool (one question at a time) |
|
||||
| Image generation | `baoyu-imagine` (Bun/TypeScript, multi-provider, accepts `--ref`, writes to local path) | `image_generate` (returns URL only; agent downloads via `terminal`/`curl`) |
|
||||
| Backend selection | User picks provider via CLI flags | Not agent-selectable — `image_generate` uses the user-configured FAL model. Removed hardcoded "nano banana pro" line from `prompts/system.md`. |
|
||||
| Reference images | Passed to backend via `--ref`, copied via shell | `vision_analyze` extracts a textual description (binary never touched by `write_file`/`read_file`); description is embedded in prompts. Optional `terminal cp` for a local record. |
|
||||
| Platform support | Linux/macOS/Windows/WSL/PowerShell | Linux/macOS only |
|
||||
| File operations | Bash commands | Hermes file tools: `write_file`/`read_file` for text, `terminal` for binaries and URL downloads, `vision_analyze` for reading images |
|
||||
| Watermark | Driven by EXTEND.md `watermark.enabled` | Optional — user asks for it per-article |
|
||||
| Output directory | EXTEND.md `default_output_dir` (imgs-subdir / same-dir / illustrations-subdir / independent) | Defaults based on input type; user overrides in request |
|
||||
|
||||
### What was preserved
|
||||
|
||||
- Type × Style × Palette three-dimension framework
|
||||
- All style definitions (23 files, verbatim)
|
||||
- All palette definitions (4 files, verbatim)
|
||||
- Core reference files (workflow, prompt-construction, styles, style-presets) — adapted for Hermes tooling
|
||||
- Core principles and workflow structure (analyze → confirm → outline → prompts → generate)
|
||||
- Prompt-file-as-reproducibility-record discipline
|
||||
- Author, version, homepage attribution
|
||||
|
||||
## Syncing with upstream
|
||||
|
||||
To pull upstream updates:
|
||||
|
||||
```bash
|
||||
# Compare versions
|
||||
curl -sL https://raw.githubusercontent.com/JimLiu/baoyu-skills/main/skills/baoyu-article-illustrator/SKILL.md | head -5
|
||||
# Look for version: line
|
||||
|
||||
# Diff style/palette files (safe to overwrite — unchanged from upstream)
|
||||
diff <(curl -sL https://raw.githubusercontent.com/JimLiu/baoyu-skills/main/skills/baoyu-article-illustrator/references/styles/blueprint.md) references/styles/blueprint.md
|
||||
```
|
||||
|
||||
`references/styles/*` and `references/palettes/*` can be overwritten directly. `SKILL.md`, `references/workflow.md`, `references/usage.md`, `references/style-presets.md`, `references/styles.md`, `references/prompt-construction.md`, and `prompts/system.md` must be manually merged since they contain Hermes-specific adaptations (tool wiring, backend neutrality, removed EXTEND.md references).
|
||||
@@ -0,0 +1,207 @@
|
||||
---
|
||||
name: baoyu-article-illustrator
|
||||
description: "Article illustrations: type × style × palette consistency."
|
||||
version: 1.57.0
|
||||
author: 宝玉 (JimLiu)
|
||||
license: MIT
|
||||
platforms: [linux, macos, windows]
|
||||
metadata:
|
||||
hermes:
|
||||
tags: [article-illustration, creative, image-generation]
|
||||
category: creative
|
||||
homepage: https://github.com/JimLiu/baoyu-skills#baoyu-article-illustrator
|
||||
---
|
||||
|
||||
# Article Illustrator
|
||||
|
||||
Adapted from [baoyu-article-illustrator](https://github.com/JimLiu/baoyu-skills) for Hermes Agent's tool ecosystem.
|
||||
|
||||
Analyze articles, identify illustration positions, generate images with **Type × Style × Palette** consistency.
|
||||
|
||||
## When to Use
|
||||
|
||||
Trigger this skill when the user asks to illustrate an article, add images to an article, generate illustrations for content, or uses phrases like "为文章配图", "illustrate article", or "add images". The user provides an article (file path or pasted content) and optionally specifies type, style, palette, or density.
|
||||
|
||||
## Three Dimensions
|
||||
|
||||
| Dimension | Controls | Examples |
|
||||
|-----------|----------|----------|
|
||||
| **Type** | Information structure | infographic, scene, flowchart, comparison, framework, timeline |
|
||||
| **Style** | Rendering approach | notion, warm, minimal, blueprint, watercolor, elegant |
|
||||
| **Palette** | Color scheme (optional) | macaron, warm, neon — overrides style's default colors |
|
||||
|
||||
Combine freely: `type=infographic, style=vector-illustration, palette=macaron`.
|
||||
|
||||
Or use presets: `edu-visual` → type + style + palette in one shot. See [style-presets.md](references/style-presets.md).
|
||||
|
||||
## Types
|
||||
|
||||
| Type | Best For |
|
||||
|------|----------|
|
||||
| `infographic` | Data, metrics, technical |
|
||||
| `scene` | Narratives, emotional |
|
||||
| `flowchart` | Processes, workflows |
|
||||
| `comparison` | Side-by-side, options |
|
||||
| `framework` | Models, architecture |
|
||||
| `timeline` | History, evolution |
|
||||
|
||||
## Styles
|
||||
|
||||
See [references/styles.md](references/styles.md) for Core Styles, the full gallery, and Type × Style compatibility.
|
||||
|
||||
## Output Structure
|
||||
|
||||
```
|
||||
{output-dir}/
|
||||
├── source-{slug}.{ext} # Only for pasted content
|
||||
├── outline.md
|
||||
├── prompts/
|
||||
│ └── NN-{type}-{slug}.md
|
||||
└── NN-{type}-{slug}.png
|
||||
```
|
||||
|
||||
**Default output directory**:
|
||||
|
||||
| Input | Output Directory | Markdown Insert Path |
|
||||
|-------|------------------|----------------------|
|
||||
| Article file path | `{article-dir}/imgs/` | `imgs/NN-{type}-{slug}.png` |
|
||||
| Pasted content | `illustrations/{topic-slug}/` (cwd) | `illustrations/{topic-slug}/NN-{type}-{slug}.png` |
|
||||
|
||||
If the user asks for a different layout (e.g., images alongside the article, or a `illustrations/` subdirectory), honor that.
|
||||
|
||||
**Slug**: 2-4 words, kebab-case. **Conflict**: append `-YYYYMMDD-HHMMSS`.
|
||||
|
||||
## Core Principles
|
||||
|
||||
- **Visualize concepts, not metaphors** — if the article uses a metaphor (e.g., "电锯切西瓜"), illustrate the underlying concept, not the literal image.
|
||||
- **Labels use article data** — actual numbers, terms, and quotes from the article, not generic placeholders.
|
||||
- **Prompt files are reproducibility records** — every illustration must have a saved prompt file under `prompts/` before any image is generated.
|
||||
- **Strip secrets** — scan source content for API keys, tokens, or credentials before writing anything to disk.
|
||||
|
||||
## Workflow
|
||||
|
||||
```
|
||||
- [ ] Step 1: Detect reference images (if provided)
|
||||
- [ ] Step 2: Analyze content
|
||||
- [ ] Step 3: Confirm settings (clarify tool, one question at a time)
|
||||
- [ ] Step 4: Generate outline
|
||||
- [ ] Step 5: Generate prompts
|
||||
- [ ] Step 6: Generate images (image_generate)
|
||||
- [ ] Step 7: Finalize
|
||||
```
|
||||
|
||||
### Step 1: Detect Reference Images
|
||||
|
||||
If the user supplies reference images (paths pasted inline, attachments, or a URL):
|
||||
|
||||
1. For each reference, call `vision_analyze` with the path/URL and a question asking for style, palette, composition, and subject. Record the returned description in `{output-dir}/references/NN-ref-{slug}.md` via `write_file`.
|
||||
2. **Do not** try to copy the binary via `write_file` / `read_file` — those are text-only. If you want a local copy for the record, use `terminal` (`cp "$src" "{output-dir}/references/NN-ref-{slug}.{ext}"`). The skill itself never needs to read the binary; it works off the vision description.
|
||||
3. Since `image_generate` doesn't take image inputs, the vision description is what gets embedded in prompts during Step 5.
|
||||
|
||||
Full procedures: [references/workflow.md](references/workflow.md#step-1-detect-reference-images).
|
||||
|
||||
### Step 2: Analyze
|
||||
|
||||
| Analysis | Output |
|
||||
|----------|--------|
|
||||
| Content type | Technical / Tutorial / Methodology / Narrative |
|
||||
| Purpose | information / visualization / imagination |
|
||||
| Core arguments | 2-5 main points |
|
||||
| Positions | Where illustrations add value |
|
||||
|
||||
Read source (file path → `read_file`, or pasted text) and write the analysis to `{output-dir}/analysis.md` using `write_file`.
|
||||
|
||||
Full procedures: [references/workflow.md](references/workflow.md#step-2-analyze).
|
||||
|
||||
### Step 3: Confirm Settings
|
||||
|
||||
Use the `clarify` tool. Since `clarify` handles one question at a time, ask the most important question first. Skip any question whose answer is already present in the user's request.
|
||||
|
||||
| Order | Question | Options |
|
||||
|-------|----------|---------|
|
||||
| Q1 | **Preset or Type** | [Recommended preset], [alt preset], or manual: infographic, scene, flowchart, comparison, framework, timeline, mixed |
|
||||
| Q2 | **Density** | minimal (1-2), balanced (3-5), per-section (Recommended), rich (6+) |
|
||||
| Q3 | **Style** *(skip if preset chosen in Q1)* | [Recommended], minimal-flat, sci-fi, hand-drawn, editorial, scene, poster |
|
||||
| Q4 | **Palette** *(optional)* | Default (style colors), macaron, warm, neon |
|
||||
| Q5 | **Language** *(only if article language is ambiguous)* | article language / user language |
|
||||
|
||||
Don't ask more than 2-3 `clarify` questions in a row. If the user already specified these in their request, skip entirely.
|
||||
|
||||
Full procedures: [references/workflow.md](references/workflow.md#step-3-confirm-settings).
|
||||
|
||||
### Step 4: Generate Outline → `outline.md`
|
||||
|
||||
Save `{output-dir}/outline.md` using `write_file` with frontmatter (type, density, style, palette, image_count) and one entry per illustration:
|
||||
|
||||
```yaml
|
||||
## Illustration 1
|
||||
**Position**: [section/paragraph]
|
||||
**Purpose**: [why]
|
||||
**Visual Content**: [what to show]
|
||||
**Filename**: 01-infographic-concept-name.png
|
||||
```
|
||||
|
||||
Full template: [references/workflow.md](references/workflow.md#step-4-generate-outline).
|
||||
|
||||
### Step 5: Generate Prompts
|
||||
|
||||
**BLOCKING**: Every illustration must have a saved prompt file before any image is generated — the prompt file is the reproducibility record.
|
||||
|
||||
For each illustration:
|
||||
|
||||
1. Create a prompt file per [references/prompt-construction.md](references/prompt-construction.md).
|
||||
2. Save to `{output-dir}/prompts/NN-{type}-{slug}.md` using `write_file` with YAML frontmatter.
|
||||
3. Prompts MUST use type-specific templates with structured sections (ZONES / LABELS / COLORS / STYLE / ASPECT).
|
||||
4. LABELS MUST include article-specific data: actual numbers, terms, metrics, quotes.
|
||||
5. Process references (`direct`/`style`/`palette`) per prompt frontmatter — for `direct` usage, embed a textual description of the reference in the prompt (since `image_generate` doesn't take reference-image inputs).
|
||||
|
||||
### Step 6: Generate Images
|
||||
|
||||
For each prompt file:
|
||||
|
||||
1. Call `image_generate(prompt=..., aspect_ratio=...)`. `image_generate` returns a JSON result containing an image URL; it does NOT write to disk and does NOT accept an output path.
|
||||
2. Map the prompt's `ASPECT` to `image_generate`'s enum: `16:9` → `landscape`, `9:16` → `portrait`, `1:1` → `square`. Custom ratios → nearest named aspect.
|
||||
3. Download the returned URL to `{output-dir}/NN-{type}-{slug}.png` via `terminal` (e.g. `curl -sSL -o "{output-dir}/NN-{type}-{slug}.png" "{url}"`).
|
||||
4. On generation failure, auto-retry once.
|
||||
|
||||
Note: the underlying image-generation backend is user-configured (default: FAL FLUX 2 Klein 9B) and is NOT agent-selectable via `image_generate`. Do not write model names into prompts expecting them to route.
|
||||
|
||||
### Step 7: Finalize
|
||||
|
||||
Insert `` after the corresponding paragraph. Alt text: concise description in the article's language.
|
||||
|
||||
Report:
|
||||
|
||||
```
|
||||
Article Illustration Complete!
|
||||
Article: [path] | Type: [type] | Density: [level] | Style: [style] | Palette: [palette or default]
|
||||
Images: X/N generated
|
||||
```
|
||||
|
||||
## Modification
|
||||
|
||||
| Action | Steps |
|
||||
|--------|-------|
|
||||
| Edit | Update prompt → Regenerate → Update reference |
|
||||
| Add | Position → Prompt → Generate → Update outline → Insert |
|
||||
| Delete | Delete files → Remove reference → Update outline |
|
||||
|
||||
## References
|
||||
|
||||
| File | Content |
|
||||
|------|---------|
|
||||
| [references/workflow.md](references/workflow.md) | Detailed procedures |
|
||||
| [references/usage.md](references/usage.md) | Invocation examples |
|
||||
| [references/styles.md](references/styles.md) | Style gallery + Palette gallery |
|
||||
| [references/style-presets.md](references/style-presets.md) | Preset shortcuts (type + style + palette) |
|
||||
| [references/prompt-construction.md](references/prompt-construction.md) | Prompt templates |
|
||||
|
||||
## Pitfalls
|
||||
|
||||
1. **Data integrity is paramount** — never summarize, paraphrase, or alter source statistics. "73% increase" stays "73% increase".
|
||||
2. **Strip secrets** — scan source content for API keys, tokens, or credentials before including in any output file.
|
||||
3. **Don't illustrate metaphors literally** — visualize the underlying concept.
|
||||
4. **Prompt files are mandatory** — no image generation without a saved prompt file. The file is what lets you regenerate or switch backends later.
|
||||
5. **`image_generate` aspect ratios** — the tool supports `landscape`, `portrait`, and `square`. Custom ratios map to the nearest option.
|
||||
6. **`image_generate` returns a URL, not a local file** — always download via `terminal` (`curl`) before inserting local image paths into the article.
|
||||
7. **No backend selection from the agent** — `image_generate` uses whatever model the user configured (default: FAL FLUX 2 Klein 9B). Don't write `"use <model> to generate this"` into prompts expecting it to route.
|
||||
@@ -0,0 +1,32 @@
|
||||
Create a cartoon-style infographic illustration following these guidelines:
|
||||
|
||||
## Image Specifications
|
||||
|
||||
- **Type**: Infographic illustration
|
||||
- **Orientation**: Landscape (horizontal)
|
||||
- **Aspect Ratio**: 16:9
|
||||
- **Style**: Hand-drawn illustration
|
||||
|
||||
## Core Principles
|
||||
|
||||
- Hand-drawn quality throughout - NO realistic or photographic elements
|
||||
- If content involves sensitive or copyrighted figures, create stylistically similar alternatives - DO NOT refuse to generate
|
||||
- Keep information concise, highlight keywords and core concepts
|
||||
- Use ample whitespace for easy visual scanning
|
||||
- Maintain clear visual hierarchy
|
||||
|
||||
## Text Style (When Text Included)
|
||||
|
||||
- **ALL text MUST be hand-drawn style**
|
||||
- Text should be readable and complement the visual
|
||||
- Font style harmonizes with illustration style
|
||||
- **DO NOT use realistic or computer-generated fonts**
|
||||
|
||||
## Language
|
||||
|
||||
- Use the same language as the content provided below for any text elements
|
||||
- Match punctuation style to the content language
|
||||
|
||||
---
|
||||
|
||||
Generate the illustration based on the content provided below:
|
||||
@@ -0,0 +1,33 @@
|
||||
# macaron
|
||||
|
||||
Soft macaron pastel color blocks on warm cream
|
||||
|
||||
## Background
|
||||
|
||||
- Color: Warm Cream (#F5F0E8)
|
||||
- Texture: Subtle warm paper grain
|
||||
|
||||
## Colors
|
||||
|
||||
| Role | Color | Hex | Usage |
|
||||
|------|-------|-----|-------|
|
||||
| Background | Warm Cream | #F5F0E8 | Primary background |
|
||||
| Primary Text | Deep Charcoal | #2D2D2D | Headlines, main text, outlines |
|
||||
| Macaron Blue | Sky Blue | #A8D8EA | Info block fill, cool-toned zones |
|
||||
| Macaron Mint | Mint Green | #B5E5CF | Info block fill, growth/positive zones |
|
||||
| Macaron Lavender | Lavender | #D5C6E0 | Info block fill, abstract/concept zones |
|
||||
| Macaron Peach | Peach | #FFD5C2 | Info block fill, warm-toned zones |
|
||||
| Accent | Coral Red | #E8655A | Key data, warnings, emphasis |
|
||||
| Muted Text | Warm Gray | #6B6B6B | Secondary annotations, small labels |
|
||||
|
||||
## Accent
|
||||
|
||||
Coral Red (#E8655A) for key data, warnings, and emphasis highlights. Use sparingly — one or two elements per illustration.
|
||||
|
||||
## Semantic Constraint
|
||||
|
||||
Soft pastel macaron color palette. Use block colors as rounded card backgrounds for distinct information sections. Accent coral red sparingly for emphasis on key terms only. Do NOT render color names, hex codes, or role labels as visible text in the image.
|
||||
|
||||
## Best For
|
||||
|
||||
Educational content, knowledge sharing, concept explainers, tutorials, tech summaries, onboarding materials
|
||||
@@ -0,0 +1,42 @@
|
||||
# mono-ink
|
||||
|
||||
Black ink on pure white with sparse semantic accent colors
|
||||
|
||||
## Background
|
||||
|
||||
- Color: Pure White (#FFFFFF)
|
||||
- Texture: Clean, no grain, no tint
|
||||
|
||||
## Colors
|
||||
|
||||
| Role | Color | Hex | Usage |
|
||||
|------|-------|-----|-------|
|
||||
| Background | Pure White | #FFFFFF | Canvas |
|
||||
| Primary | Near Black | #1A1A1A | All lines, text, figures, arrows |
|
||||
| Accent (risk/emphasis) | Coral Red | #E8655A | Risk, problem, gap, key emphasis |
|
||||
| Accent (positive) | Muted Teal | #5FA8A8 | Positive, solution, "after" state |
|
||||
| Accent (neutral tag) | Dusty Lavender | #9B8AB5 | Neutral tags, category labels |
|
||||
| Soft Fill | Pale Gray | #F0F0F0 | Subtle zone backgrounds (optional) |
|
||||
|
||||
## Accent
|
||||
|
||||
Use black ink for all structural elements — lines, text, figures. Accent colors appear only for semantic highlighting: coral red for risks/gaps/problems, muted teal for positive/solution/after-states, dusty lavender for neutral category tags. Total colored pixels must remain under 10% of canvas. Pale gray may back a subtle zone but must never dominate.
|
||||
|
||||
## Semantic Constraint
|
||||
|
||||
Black ink on white canvas. Accent colors for semantic highlighting only — total colored pixels under 10% of canvas. Do NOT render color names, hex codes, or role labels as visible text in the image.
|
||||
|
||||
## Compatible With
|
||||
|
||||
- `ink-notes` (primary, default pairing)
|
||||
- `minimal` (strict monochrome variation, drops the style's built-in accent)
|
||||
- `sketch` (pencil + ink hybrid look)
|
||||
|
||||
## Not Recommended With
|
||||
|
||||
- `sketch-notes` — its "no pure white backgrounds" rule conflicts
|
||||
- `warm`, `elegant`, `watercolor`, `fantasy-animation` — color-heavy by design, mono-ink strips their identity
|
||||
|
||||
## Best For
|
||||
|
||||
Professional visual notes, Before/After essays, tech manifestos, framework analogies, whiteboard-presentation explainers
|
||||
@@ -0,0 +1,33 @@
|
||||
# neon
|
||||
|
||||
Vibrant neon colors on dark backgrounds
|
||||
|
||||
## Background
|
||||
|
||||
- Color: Deep Purple (#2D1B4E)
|
||||
- Texture: Subtle grid pattern or solid dark
|
||||
|
||||
## Colors
|
||||
|
||||
| Role | Color | Hex | Usage |
|
||||
|------|-------|-----|-------|
|
||||
| Background | Deep Purple | #2D1B4E | Primary background |
|
||||
| Alt Background | Dark Teal | #0F4C5C | Alternative sections |
|
||||
| Primary | Hot Pink | #FF1493 | Main accent |
|
||||
| Secondary | Electric Cyan | #00FFFF | Supporting elements |
|
||||
| Tertiary | Neon Yellow | #FFFF00 | Highlights |
|
||||
| Accent 1 | Lime Green | #32CD32 | Energy, success |
|
||||
| Accent 2 | Orange | #FF6B35 | Warmth |
|
||||
| Text | White | #FFFFFF | Text elements |
|
||||
|
||||
## Accent
|
||||
|
||||
Hot Pink (#FF1493) for primary emphasis. High contrast neon-on-dark creates immediate visual impact.
|
||||
|
||||
## Semantic Constraint
|
||||
|
||||
Vibrant neon-on-dark palette. High contrast, immediate visual impact. Do NOT render color names, hex codes, or role labels as visible text in the image.
|
||||
|
||||
## Best For
|
||||
|
||||
Gaming, retro tech, 80s/90s nostalgic content, bold editorial, trend and pop culture
|
||||
@@ -0,0 +1,32 @@
|
||||
# warm
|
||||
|
||||
Warm earth tones on soft peach, no cool colors
|
||||
|
||||
## Background
|
||||
|
||||
- Color: Soft Peach (#FFECD2)
|
||||
- Texture: Warm paper texture
|
||||
|
||||
## Colors
|
||||
|
||||
| Role | Color | Hex | Usage |
|
||||
|------|-------|-----|-------|
|
||||
| Background | Soft Peach | #FFECD2 | Primary background |
|
||||
| Outlines | Deep Charcoal | #2D2D2D | All element outlines |
|
||||
| Primary | Warm Orange | #ED8936 | Main accent color |
|
||||
| Secondary | Terracotta | #C05621 | Warm depth |
|
||||
| Tertiary | Golden Yellow | #F6AD55 | Highlights, energy |
|
||||
| Accent | Deep Brown | #744210 | Grounding, anchoring |
|
||||
| Text | Warm Charcoal | #4A4A4A | Text elements |
|
||||
|
||||
## Accent
|
||||
|
||||
Warm Orange (#ED8936) for primary emphasis. Warm-only palette — no cool colors (no green, blue, purple). Modern-retro feel.
|
||||
|
||||
## Semantic Constraint
|
||||
|
||||
Warm earth tone palette. Warm-only — no cool colors (no green, blue, purple). Do NOT render color names, hex codes, or role labels as visible text in the image.
|
||||
|
||||
## Best For
|
||||
|
||||
Product showcases, team introductions, feature grids, brand content, personal growth, lifestyle
|
||||
@@ -0,0 +1,426 @@
|
||||
# Prompt Construction
|
||||
|
||||
## Prompt File Format
|
||||
|
||||
Each prompt file uses YAML frontmatter + content:
|
||||
|
||||
```yaml
|
||||
---
|
||||
illustration_id: 01
|
||||
type: infographic
|
||||
style: blueprint
|
||||
references: # ⚠️ ONLY if files EXIST in references/ directory
|
||||
- ref_id: 01
|
||||
filename: 01-ref-diagram.png
|
||||
usage: direct # direct | style | palette
|
||||
---
|
||||
|
||||
[Type-specific template content below...]
|
||||
```
|
||||
|
||||
**⚠️ CRITICAL - When to include `references` field**:
|
||||
|
||||
| Situation | Action |
|
||||
|-----------|--------|
|
||||
| Reference file saved to `references/` | Include in frontmatter ✓ |
|
||||
| Style extracted verbally (no file) | DO NOT include in frontmatter, append to prompt body instead |
|
||||
| File path in frontmatter but file doesn't exist | ERROR - remove references field |
|
||||
|
||||
**Reference Usage Types** (only when file exists):
|
||||
|
||||
| Usage | Description | Generation Action |
|
||||
|-------|-------------|-------------------|
|
||||
| `direct` | Primary visual reference | Describe the reference (composition, subject, style, palette) in prompt text — `image_generate` does not accept reference-image inputs |
|
||||
| `style` | Style characteristics only | Describe style in prompt text |
|
||||
| `palette` | Color palette extraction | Include colors in prompt |
|
||||
|
||||
**If no reference file but style/palette extracted verbally**, append directly to prompt body:
|
||||
```
|
||||
COLORS (from reference):
|
||||
- Primary: #E8756D coral
|
||||
- Secondary: #7ECFC0 mint
|
||||
...
|
||||
|
||||
STYLE (from reference):
|
||||
- Clean lines, minimal shadows
|
||||
- Gradient backgrounds
|
||||
...
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Default Composition Requirements
|
||||
|
||||
**Apply to ALL prompts by default**:
|
||||
|
||||
| Requirement | Description |
|
||||
|-------------|-------------|
|
||||
| **Clean composition** | Simple layouts, no visual clutter |
|
||||
| **White space** | Generous margins, breathing room around elements |
|
||||
| **No complex backgrounds** | Solid colors or subtle gradients only, avoid busy textures |
|
||||
| **Centered or content-appropriate** | Main visual elements centered or positioned by content needs |
|
||||
| **Matching graphics** | Use graphic elements that align with content theme |
|
||||
| **Highlight core info** | White space draws attention to key information |
|
||||
|
||||
**Add to ALL prompts**:
|
||||
> Clean composition with generous white space. Simple or no background. Main elements centered or positioned by content needs.
|
||||
|
||||
---
|
||||
|
||||
## Color Specification Rules
|
||||
|
||||
Colors in prompts use hex codes for **rendering guidance only** — they tell the model which colors to use, NOT what text to display.
|
||||
|
||||
**⚠️ CRITICAL**: Image generation models sometimes render color names and hex values as visible text labels in the image (e.g., painting "Macaron Blue #A8D8EA" as a label). This must be prevented.
|
||||
|
||||
**Add to ALL prompts that contain a COLORS section**:
|
||||
> Color values (#hex) and color names are rendering guidance only — do NOT display color names, hex codes, or palette labels as visible text in the image.
|
||||
|
||||
---
|
||||
|
||||
## Character Rendering
|
||||
|
||||
When depicting people:
|
||||
|
||||
| Guideline | Description |
|
||||
|-----------|-------------|
|
||||
| **Style** | Simplified cartoon silhouettes or symbolic expressions |
|
||||
| **Avoid** | Realistic human portrayals, detailed faces |
|
||||
| **Diversity** | Varied body types when showing multiple people |
|
||||
| **Emotion** | Express through posture and simple gestures |
|
||||
|
||||
**Add to ALL prompts with human figures**:
|
||||
> Human figures: simplified stylized silhouettes or symbolic representations, not photorealistic.
|
||||
|
||||
---
|
||||
|
||||
## Text in Illustrations
|
||||
|
||||
| Element | Guideline |
|
||||
|---------|-----------|
|
||||
| **Size** | Large, prominent, immediately readable |
|
||||
| **Style** | Handwritten fonts preferred for warmth |
|
||||
| **Content** | Concise keywords and core concepts only |
|
||||
| **Language** | Match article language |
|
||||
|
||||
**Add to prompts with text**:
|
||||
> Text should be large and prominent with handwritten-style fonts. Keep minimal, focus on keywords.
|
||||
|
||||
---
|
||||
|
||||
## Principles
|
||||
|
||||
Good prompts must include:
|
||||
|
||||
1. **Layout Structure First**: Describe composition, zones, flow direction
|
||||
2. **Specific Data/Labels**: Use actual numbers, terms from article
|
||||
3. **Visual Relationships**: How elements connect
|
||||
4. **Semantic Colors**: Meaning-based color choices (red=warning, green=efficient)
|
||||
5. **Style Characteristics**: Line treatment, texture, mood
|
||||
6. **Aspect Ratio**: End with ratio and complexity level
|
||||
|
||||
## Type-Specific Templates
|
||||
|
||||
### Infographic
|
||||
|
||||
```
|
||||
[Title] - Data Visualization
|
||||
|
||||
Layout: [grid/radial/hierarchical]
|
||||
|
||||
ZONES:
|
||||
- Zone 1: [data point with specific values]
|
||||
- Zone 2: [comparison with metrics]
|
||||
- Zone 3: [summary/conclusion]
|
||||
|
||||
LABELS: [specific numbers, percentages, terms from article]
|
||||
COLORS: [semantic color mapping]
|
||||
STYLE: [style characteristics]
|
||||
ASPECT: 16:9
|
||||
```
|
||||
|
||||
**Infographic + vector-illustration**:
|
||||
```
|
||||
Flat vector illustration infographic. Clean black outlines on all elements.
|
||||
COLORS: Cream background (#F5F0E6), Coral Red (#E07A5F), Mint Green (#81B29A), Mustard Yellow (#F2CC8F)
|
||||
ELEMENTS: Geometric simplified icons, no gradients, playful decorative elements (dots, stars)
|
||||
```
|
||||
|
||||
**Infographic + vector-illustration + warm palette**:
|
||||
```
|
||||
Flat vector illustration infographic. Clean black outlines on all elements.
|
||||
PALETTE OVERRIDE (warm): Warm-only color palette, no cool colors.
|
||||
COLORS: Soft Peach background (#FFECD2), Warm Orange (#ED8936),
|
||||
Terracotta (#C05621), Golden Yellow (#F6AD55), Deep Brown (#744210)
|
||||
ELEMENTS: Geometric simplified icons, no gradients, rounded corners,
|
||||
modular card layout, consistent icon style
|
||||
```
|
||||
|
||||
### Scene
|
||||
|
||||
```
|
||||
[Title] - Atmospheric Scene
|
||||
|
||||
FOCAL POINT: [main subject]
|
||||
ATMOSPHERE: [lighting, mood, environment]
|
||||
MOOD: [emotion to convey]
|
||||
COLOR TEMPERATURE: [warm/cool/neutral]
|
||||
STYLE: [style characteristics]
|
||||
ASPECT: 16:9
|
||||
```
|
||||
|
||||
### Flowchart
|
||||
|
||||
```
|
||||
[Title] - Process Flow
|
||||
|
||||
Layout: [left-right/top-down/circular]
|
||||
|
||||
STEPS:
|
||||
1. [Step name] - [brief description]
|
||||
2. [Step name] - [brief description]
|
||||
...
|
||||
|
||||
CONNECTIONS: [arrow types, decision points]
|
||||
STYLE: [style characteristics]
|
||||
ASPECT: 16:9
|
||||
```
|
||||
|
||||
**Flowchart + vector-illustration**:
|
||||
```
|
||||
Flat vector flowchart with bold arrows and geometric step containers.
|
||||
COLORS: Cream background (#F5F0E6), steps in Coral/Mint/Mustard, black outlines
|
||||
ELEMENTS: Rounded rectangles, thick arrows, simple icons per step
|
||||
```
|
||||
|
||||
**Flowchart + sketch-notes + macaron palette**:
|
||||
```
|
||||
Hand-drawn educational flowchart on warm cream paper. Slight wobble on all lines.
|
||||
PALETTE: macaron — soft pastel color blocks
|
||||
COLORS: Warm Cream background (#F5F0E8), zone fills in Macaron Blue (#A8D8EA),
|
||||
Lavender (#D5C6E0), Mint (#B5E5CF), Coral Red (#E8655A) for emphasis
|
||||
ELEMENTS: Rounded cards with dashed/solid borders, wavy hand-drawn arrows with labels,
|
||||
simple stick-figure characters, doodle decorations (stars, underlines)
|
||||
STYLE: Color fills don't completely fill outlines, hand-drawn lettering, generous white space
|
||||
```
|
||||
|
||||
**Flowchart + ink-notes + mono-ink palette**:
|
||||
```
|
||||
Professional hand-drawn visual-note flowchart on pure white. Black ink line work
|
||||
with slight wobble, à la Mike Rohde sketchnoting.
|
||||
PALETTE: mono-ink — black ink dominant, sparse semantic accents
|
||||
COLORS: Pure White background (#FFFFFF), Near Black (#1A1A1A) for all lines,
|
||||
text, and figures; Coral Red (#E8655A) only for risk/emphasis,
|
||||
Muted Teal (#5FA8A8) only for positive/solution states
|
||||
ELEMENTS: Left-to-right stage boxes with rounded-rect frames, wavy hand-drawn
|
||||
arrows between stages, simple stick-figure characters with role
|
||||
labels above (e.g., "ML Engineer", "Team Lead"), dashed-border box
|
||||
for future/empty stage, small doodle icons per stage
|
||||
STYLE: Hand-lettered titles (bold, oversized), handwritten stage labels and
|
||||
annotations, generous white space, bottom tagline summarizing takeaway
|
||||
```
|
||||
|
||||
### Comparison
|
||||
|
||||
```
|
||||
[Title] - Comparison View
|
||||
|
||||
LEFT SIDE - [Option A]:
|
||||
- [Point 1]
|
||||
- [Point 2]
|
||||
|
||||
RIGHT SIDE - [Option B]:
|
||||
- [Point 1]
|
||||
- [Point 2]
|
||||
|
||||
DIVIDER: [visual separator]
|
||||
STYLE: [style characteristics]
|
||||
ASPECT: 16:9
|
||||
```
|
||||
|
||||
**Comparison + vector-illustration**:
|
||||
```
|
||||
Flat vector comparison with split layout. Clear visual separation.
|
||||
COLORS: Left side Coral (#E07A5F), Right side Mint (#81B29A), cream background
|
||||
ELEMENTS: Bold icons, black outlines, centered divider line
|
||||
```
|
||||
|
||||
**Comparison + vector-illustration + warm palette**:
|
||||
```
|
||||
Flat vector comparison with split layout. Clear visual separation.
|
||||
PALETTE OVERRIDE (warm): Warm-only color palette, no cool colors.
|
||||
COLORS: Left side Warm Orange (#ED8936), Right side Terracotta (#C05621),
|
||||
Soft Peach background (#FFECD2), Deep Brown (#744210) accents
|
||||
ELEMENTS: Bold icons, black outlines, centered divider line
|
||||
```
|
||||
|
||||
**Comparison + ink-notes + mono-ink palette** (Before/After, Traditional vs New):
|
||||
```
|
||||
Professional hand-drawn sketchnote comparison on pure white. Black ink line work
|
||||
with slight wobble, à la Mike Rohde sketchnoting.
|
||||
PALETTE: mono-ink — black ink dominant, sparse semantic accents
|
||||
COLORS: Pure White background (#FFFFFF), Near Black (#1A1A1A) for all outlines,
|
||||
text, figures, arrows; Coral Red (#E8655A) reserved for risks/gaps
|
||||
(left/Before side); Muted Teal (#5FA8A8) reserved for positives
|
||||
(right/After side). Color accents under 10% of canvas.
|
||||
LAYOUT: Left | Right split with vertical hand-drawn divider. Hand-lettered
|
||||
"Before" label (top-left) and "After" label (top-right).
|
||||
LEFT SIDE: Stick figure(s) with role label above, speech bubble showing the
|
||||
pain point, bulleted pain-point list in handwritten text.
|
||||
RIGHT SIDE: Stick figure(s) showing the new state, bulleted improvement list,
|
||||
small positive-action icons.
|
||||
BRIDGE: Curved hand-drawn "mindset shift" arrow bridging left → right with
|
||||
small inline label describing the shift.
|
||||
BOTTOM: Single-line hand-lettered tagline summarizing the takeaway.
|
||||
STYLE: Hand-lettered headings (bold, oversized), handwritten body annotations,
|
||||
generous white space, no computer fonts, no gradients, no shadows.
|
||||
```
|
||||
|
||||
### Framework
|
||||
|
||||
```
|
||||
[Title] - Conceptual Framework
|
||||
|
||||
STRUCTURE: [hierarchical/network/matrix]
|
||||
|
||||
NODES:
|
||||
- [Concept 1] - [role]
|
||||
- [Concept 2] - [role]
|
||||
|
||||
RELATIONSHIPS: [how nodes connect]
|
||||
STYLE: [style characteristics]
|
||||
ASPECT: 16:9
|
||||
```
|
||||
|
||||
**Framework + vector-illustration**:
|
||||
```
|
||||
Flat vector framework diagram with geometric nodes and bold connectors.
|
||||
COLORS: Cream background (#F5F0E6), nodes in Coral/Mint/Mustard/Blue, black outlines
|
||||
ELEMENTS: Rounded rectangles or circles for nodes, thick connecting lines
|
||||
```
|
||||
|
||||
**Framework + vector-illustration + warm palette**:
|
||||
```
|
||||
Flat vector framework diagram with geometric nodes and bold connectors.
|
||||
PALETTE OVERRIDE (warm): Warm-only color palette, no cool colors.
|
||||
COLORS: Soft Peach background (#FFECD2), nodes in Warm Orange (#ED8936),
|
||||
Terracotta (#C05621), Golden Yellow (#F6AD55), black outlines
|
||||
ELEMENTS: Rounded rectangles or circles for nodes, thick connecting lines
|
||||
```
|
||||
|
||||
**Framework + ink-notes + mono-ink palette** (command center, OS analogy):
|
||||
```
|
||||
Professional hand-drawn sketchnote framework on pure white. Black ink line work
|
||||
with slight wobble, à la Mike Rohde sketchnoting.
|
||||
PALETTE: mono-ink — black ink dominant, sparse semantic accents
|
||||
COLORS: Pure White background (#FFFFFF), Near Black (#1A1A1A) for all lines,
|
||||
text, figures; Dusty Lavender (#9B8AB5) for neutral category tags only;
|
||||
Coral Red (#E8655A) for emphasis sparingly. Color accents under 10%.
|
||||
STRUCTURE: Central rounded-rectangle frame as "the system" with hand-lettered
|
||||
title inside. Inner layer of labeled sub-components (node labels
|
||||
above each). Outer layer of feeder arrows from stick-figure
|
||||
operators/users with role labels.
|
||||
ELEMENTS: Stick figures at the edges with role tags ("Team Lead", "Operator"),
|
||||
wavy hand-drawn connector arrows with small inline labels, small
|
||||
doodle icons per component, dashed-border placeholder(s) for
|
||||
future/empty capabilities.
|
||||
BOTTOM: Single-line hand-lettered tagline.
|
||||
STYLE: Hand-lettered headings, handwritten annotations, generous white space,
|
||||
no computer fonts, no gradients.
|
||||
```
|
||||
|
||||
### Timeline
|
||||
|
||||
```
|
||||
[Title] - Chronological View
|
||||
|
||||
DIRECTION: [horizontal/vertical]
|
||||
|
||||
EVENTS:
|
||||
- [Date/Period 1]: [milestone]
|
||||
- [Date/Period 2]: [milestone]
|
||||
|
||||
MARKERS: [visual indicators]
|
||||
STYLE: [style characteristics]
|
||||
ASPECT: 16:9
|
||||
```
|
||||
|
||||
### Screen-Print Style Override
|
||||
|
||||
When `style: screen-print`, replace standard style instructions with:
|
||||
|
||||
```
|
||||
Screen print / silkscreen poster art. Flat color blocks, NO gradients.
|
||||
COLORS: 2-5 colors maximum. [Choose from style palette or duotone pair]
|
||||
TEXTURE: Halftone dot patterns, slight color layer misregistration, paper grain
|
||||
COMPOSITION: Bold silhouettes, geometric framing, negative space as storytelling element
|
||||
FIGURES: Silhouettes only, no detailed faces, stencil-cut edges
|
||||
TYPOGRAPHY: Bold condensed sans-serif integrated into composition (not overlaid)
|
||||
```
|
||||
|
||||
**Scene + screen-print**:
|
||||
```
|
||||
Conceptual poster scene. Single symbolic focal point, NOT literal illustration.
|
||||
COLORS: Duotone pair (e.g., Burnt Orange #E8751A + Deep Teal #0A6E6E) on Off-Black #121212
|
||||
COMPOSITION: Centered silhouette or geometric frame, 60%+ negative space
|
||||
TEXTURE: Halftone dots, paper grain, slight print misregistration
|
||||
```
|
||||
|
||||
**Comparison + screen-print**:
|
||||
```
|
||||
Split poster composition. Each side dominated by one color from duotone pair.
|
||||
LEFT: [Color A] side with silhouette/icon for [Option A]
|
||||
RIGHT: [Color B] side with silhouette/icon for [Option B]
|
||||
DIVIDER: Geometric shape or negative space boundary
|
||||
TEXTURE: Halftone transitions between sides
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Palette Override
|
||||
|
||||
When a palette is specified (via `--palette` or preset), it overrides the style's default colors:
|
||||
|
||||
1. Read style file → get rendering rules (Visual Elements, Style Rules, line treatment)
|
||||
2. Read palette file (`palettes/<palette>.md`) → get Colors + Background
|
||||
3. Palette Colors **replace** style's default Color Palette in prompt
|
||||
4. Palette Background **replaces** style's Background color (keep style's texture description)
|
||||
5. Build prompt: style rendering instructions + palette colors
|
||||
|
||||
**Prompt frontmatter** includes palette when specified:
|
||||
```yaml
|
||||
---
|
||||
illustration_id: 01
|
||||
type: infographic
|
||||
style: vector-illustration
|
||||
palette: macaron
|
||||
---
|
||||
```
|
||||
|
||||
**Example**: `vector-illustration` + `macaron` palette:
|
||||
```
|
||||
Flat vector illustration infographic. Clean black outlines on all elements.
|
||||
PALETTE: macaron — soft pastel color blocks
|
||||
COLORS: Warm Cream background (#F5F0E8), Macaron Blue (#A8D8EA), Mint (#B5E5CF),
|
||||
Lavender (#D5C6E0), Peach (#FFD5C2), Coral Red (#E8655A) for emphasis
|
||||
ELEMENTS: Geometric simplified icons, no gradients, playful decorative elements
|
||||
```
|
||||
|
||||
When no palette is specified, use the style's built-in Color Palette as before.
|
||||
|
||||
---
|
||||
|
||||
## What to Avoid
|
||||
|
||||
- Vague descriptions ("a nice image")
|
||||
- Literal metaphor illustrations
|
||||
- Missing concrete labels/annotations
|
||||
- Generic decorative elements
|
||||
|
||||
## Watermark Integration (optional)
|
||||
|
||||
If the user asks for a watermark, append:
|
||||
|
||||
```
|
||||
Include a subtle watermark "[content]" positioned at [position].
|
||||
```
|
||||
@@ -0,0 +1,80 @@
|
||||
# Style Presets
|
||||
|
||||
A preset expands to a type + style + optional palette combination. Users can override any dimension in their request.
|
||||
|
||||
## By Category
|
||||
|
||||
### Technical & Engineering
|
||||
|
||||
| Preset | Type | Style | Palette | Best For |
|
||||
|----------|------|-------|---------|----------|
|
||||
| `tech-explainer` | `infographic` | `blueprint` | — | API docs, system metrics, technical deep-dives |
|
||||
| `system-design` | `framework` | `blueprint` | — | Architecture diagrams, system design |
|
||||
| `architecture` | `framework` | `vector-illustration` | — | Component relationships, module structure |
|
||||
| `science-paper` | `infographic` | `scientific` | — | Research findings, lab results, academic |
|
||||
|
||||
### Knowledge & Education
|
||||
|
||||
| Preset | Type | Style | Palette | Best For |
|
||||
|----------|------|-------|---------|----------|
|
||||
| `knowledge-base` | `infographic` | `vector-illustration` | — | Concept explainers, tutorials, how-to |
|
||||
| `saas-guide` | `infographic` | `notion` | — | Product guides, SaaS docs, tool walkthroughs |
|
||||
| `tutorial` | `flowchart` | `vector-illustration` | — | Step-by-step tutorials, setup guides |
|
||||
| `process-flow` | `flowchart` | `notion` | — | Workflow documentation, onboarding flows |
|
||||
| `warm-knowledge` | `infographic` | `vector-illustration` | `warm` | Product showcases, team intros, feature cards, brand content |
|
||||
| `edu-visual` | `infographic` | `vector-illustration` | `macaron` | Knowledge summaries, concept explainers, educational articles |
|
||||
| `hand-drawn-edu` | `flowchart` | `sketch-notes` | `macaron` | Hand-drawn educational diagrams, process explainers, onboarding visuals |
|
||||
| `ink-notes-compare` | `comparison` | `ink-notes` | `mono-ink` | Before/After essays, Traditional vs New, OS-style comparisons, mindset-shift narratives |
|
||||
| `ink-notes-flow` | `flowchart` | `ink-notes` | `mono-ink` | Professional process explainers, workforce pipelines, hand-drawn technical walkthroughs |
|
||||
| `ink-notes-framework` | `framework` | `ink-notes` | `mono-ink` | System analogies, command-center diagrams, architecture-as-metaphor, tech manifestos |
|
||||
|
||||
### Data & Analysis
|
||||
|
||||
| Preset | Type | Style | Palette | Best For |
|
||||
|----------|------|-------|---------|----------|
|
||||
| `data-report` | `infographic` | `editorial` | — | Data journalism, metrics reports, dashboards |
|
||||
| `versus` | `comparison` | `vector-illustration` | — | Tech comparisons, framework shootouts |
|
||||
| `business-compare` | `comparison` | `elegant` | — | Product evaluations, strategy options |
|
||||
|
||||
### Narrative & Creative
|
||||
|
||||
| Preset | Type | Style | Palette | Best For |
|
||||
|----------|------|-------|---------|----------|
|
||||
| `storytelling` | `scene` | `warm` | — | Personal essays, reflections, growth stories |
|
||||
| `lifestyle` | `scene` | `watercolor` | — | Travel, wellness, lifestyle, creative |
|
||||
| `history` | `timeline` | `elegant` | — | Historical overviews, milestones |
|
||||
| `evolution` | `timeline` | `warm` | — | Progress narratives, growth journeys |
|
||||
|
||||
### Editorial & Opinion
|
||||
|
||||
| Preset | Type | Style | Palette | Best For |
|
||||
|----------|------|-------|---------|----------|
|
||||
| `opinion-piece` | `scene` | `screen-print` | — | Op-eds, commentary, critical essays |
|
||||
| `editorial-poster` | `comparison` | `screen-print` | — | Debate, contrasting viewpoints |
|
||||
| `cinematic` | `scene` | `screen-print` | — | Dramatic narratives, cultural essays |
|
||||
|
||||
## Content Type → Preset Recommendations
|
||||
|
||||
Use this table during Step 3 to recommend presets based on Step 2 content analysis:
|
||||
|
||||
| Content Type (Step 2) | Primary Preset | Alternatives |
|
||||
|------------------------|----------------|--------------|
|
||||
| Technical | `tech-explainer` | `system-design`, `architecture` |
|
||||
| Tutorial | `tutorial` | `process-flow`, `knowledge-base`, `edu-visual` |
|
||||
| Methodology / Framework | `system-design` | `architecture`, `process-flow` |
|
||||
| Data / Metrics | `data-report` | `versus`, `tech-explainer` |
|
||||
| Comparison / Review | `versus` | `business-compare`, `editorial-poster`, `ink-notes-compare` |
|
||||
| Manifesto / Mindset shift / Professional visual note | `ink-notes-compare` | `ink-notes-framework`, `ink-notes-flow` |
|
||||
| Narrative / Personal | `storytelling` | `lifestyle`, `evolution` |
|
||||
| Opinion / Editorial | `opinion-piece` | `cinematic`, `editorial-poster` |
|
||||
| Historical / Timeline | `history` | `evolution` |
|
||||
| Academic / Research | `science-paper` | `tech-explainer`, `data-report` |
|
||||
| SaaS / Product | `saas-guide` | `knowledge-base`, `process-flow`, `warm-knowledge` |
|
||||
| Education / Knowledge | `edu-visual` | `knowledge-base`, `tutorial`, `hand-drawn-edu` |
|
||||
|
||||
## Override Examples
|
||||
|
||||
- "use the tech-explainer preset but swap the style for notion" = infographic type with notion style
|
||||
- "storytelling preset with timeline type" = timeline type with warm style
|
||||
|
||||
Explicit type/style/palette mentions in the user's request always override preset values.
|
||||
@@ -0,0 +1,224 @@
|
||||
# Style Reference
|
||||
|
||||
## Core Styles
|
||||
|
||||
Simplified style tier for quick selection:
|
||||
|
||||
| Core Style | Maps To | Best For |
|
||||
|------------|---------|----------|
|
||||
| `vector` | vector-illustration | Knowledge articles, tutorials, tech content |
|
||||
| `minimal-flat` | notion | General, knowledge sharing, SaaS |
|
||||
| `sci-fi` | blueprint | AI, frontier tech, system design |
|
||||
| `hand-drawn` | sketch/warm | Relaxed, reflective, casual content |
|
||||
| `editorial` | editorial | Processes, data, journalism |
|
||||
| `scene` | warm/watercolor | Narratives, emotional, lifestyle |
|
||||
| `poster` | screen-print | Opinion, editorial, cultural, cinematic |
|
||||
|
||||
Use Core Styles for most cases. See full Style Gallery below for granular control.
|
||||
|
||||
---
|
||||
|
||||
## Style Gallery
|
||||
|
||||
| Style | Description | Best For |
|
||||
|-------|-------------|----------|
|
||||
| `vector-illustration` | Clean flat vector art with bold shapes | Knowledge articles, tutorials, tech content |
|
||||
| `notion` | Minimalist hand-drawn line art | Knowledge sharing, SaaS, productivity |
|
||||
| `elegant` | Refined, sophisticated | Business, thought leadership |
|
||||
| `warm` | Friendly, approachable | Personal growth, lifestyle, education |
|
||||
| `minimal` | Ultra-clean, zen-like | Philosophy, minimalism, core concepts |
|
||||
| `blueprint` | Technical schematics | Architecture, system design, engineering |
|
||||
| `watercolor` | Soft artistic with natural warmth | Lifestyle, travel, creative |
|
||||
| `editorial` | Magazine-style infographic | Tech explainers, journalism |
|
||||
| `scientific` | Academic precise diagrams | Biology, chemistry, technical research |
|
||||
| `chalkboard` | Classroom chalk drawing style | Education, teaching, explanations |
|
||||
| `fantasy-animation` | Ghibli/Disney-inspired hand-drawn | Storybook, magical, emotional |
|
||||
| `flat` | Modern bold geometric shapes | Modern digital, contemporary |
|
||||
| `flat-doodle` | Cute flat with bold outlines | Cute, friendly, approachable |
|
||||
| `intuition-machine` | Technical briefing with aged paper | Technical briefings, academic |
|
||||
| `nature` | Organic earthy illustration | Environmental, wellness |
|
||||
| `pixel-art` | Retro 8-bit gaming aesthetic | Gaming, retro tech |
|
||||
| `playful` | Whimsical pastel doodles | Fun, casual, educational |
|
||||
| `retro` | 80s/90s neon geometric | 80s/90s nostalgic, bold |
|
||||
| `sketch` | Raw pencil notebook style | Brainstorming, creative exploration |
|
||||
| `screen-print` | Bold poster art, halftone textures, limited colors | Opinion, editorial, cultural, cinematic |
|
||||
| `sketch-notes` | Soft hand-drawn warm notes | Educational, warm notes |
|
||||
| `ink-notes` | Black ink on pure white, sparse semantic accents, hand-lettered (à la Mike Rohde's sketchnoting) | Before/After essays, tech manifestos, framework analogies |
|
||||
| `vintage` | Aged parchment historical | Historical, heritage |
|
||||
|
||||
Full specifications: `references/styles/<style>.md`
|
||||
|
||||
## Type × Style Compatibility Matrix
|
||||
|
||||
| | vector-illustration | notion | warm | minimal | blueprint | watercolor | elegant | editorial | scientific | screen-print |
|
||||
|---|:---:|:---:|:---:|:---:|:---:|:---:|:---:|:---:|:---:|:---:|
|
||||
| infographic | ✓✓ | ✓✓ | ✓ | ✓✓ | ✓✓ | ✓ | ✓✓ | ✓✓ | ✓✓ | ✓ |
|
||||
| scene | ✓ | ✓ | ✓✓ | ✓ | ✗ | ✓✓ | ✓ | ✓ | ✗ | ✓✓ |
|
||||
| flowchart | ✓✓ | ✓✓ | ✓ | ✓ | ✓✓ | ✗ | ✓ | ✓✓ | ✓ | ✗ |
|
||||
| comparison | ✓✓ | ✓✓ | ✓ | ✓✓ | ✓ | ✓ | ✓✓ | ✓✓ | ✓ | ✓ |
|
||||
| framework | ✓✓ | ✓✓ | ✓ | ✓✓ | ✓✓ | ✗ | ✓✓ | ✓ | ✓✓ | ✓ |
|
||||
| timeline | ✓ | ✓✓ | ✓ | ✓ | ✓ | ✓✓ | ✓✓ | ✓✓ | ✓ | ✓ |
|
||||
|
||||
✓✓ = highly recommended | ✓ = compatible | ✗ = not recommended
|
||||
|
||||
## Auto Selection by Type
|
||||
|
||||
| Type | Primary Style | Secondary Styles |
|
||||
|------|---------------|------------------|
|
||||
| infographic | vector-illustration | notion, blueprint, editorial |
|
||||
| scene | warm | watercolor, elegant |
|
||||
| flowchart | vector-illustration | notion, blueprint |
|
||||
| comparison | vector-illustration | notion, elegant |
|
||||
| framework | blueprint | vector-illustration, notion |
|
||||
| timeline | elegant | warm, editorial |
|
||||
|
||||
## Auto Selection by Content Signals
|
||||
|
||||
| Content Signals | Recommended Type | Recommended Style |
|
||||
|-----------------|------------------|-------------------|
|
||||
| API, metrics, data, comparison, numbers | infographic | blueprint, vector-illustration |
|
||||
| Knowledge, concept, tutorial, learning, guide | infographic | vector-illustration, notion |
|
||||
| Tech, AI, programming, development, code | infographic | vector-illustration, blueprint |
|
||||
| How-to, steps, workflow, process, tutorial | flowchart | vector-illustration, notion |
|
||||
| Framework, model, architecture, principles | framework | blueprint, vector-illustration |
|
||||
| vs, pros/cons, before/after, alternatives | comparison | vector-illustration, notion |
|
||||
| Manifesto, mindset shift, workforce, OS, whiteboard, professional visual note | comparison / framework | ink-notes |
|
||||
| Story, emotion, journey, experience, personal | scene | warm, watercolor |
|
||||
| History, timeline, progress, evolution | timeline | elegant, warm |
|
||||
| Productivity, SaaS, tool, app, software | infographic | notion, vector-illustration |
|
||||
| Business, professional, strategy, corporate | framework | elegant |
|
||||
| Opinion, editorial, culture, philosophy, cinematic, dramatic, poster | scene | screen-print |
|
||||
| Biology, chemistry, medical, scientific | infographic | scientific |
|
||||
| Explainer, journalism, magazine, investigation | infographic | editorial |
|
||||
|
||||
## Style Characteristics by Type
|
||||
|
||||
### infographic + vector-illustration
|
||||
- Clean flat vector shapes, bold geometric forms
|
||||
- Vibrant but harmonious color palette
|
||||
- Clear visual hierarchy with icons and labels
|
||||
- Modern, professional, highly readable
|
||||
- Perfect for knowledge articles and tutorials
|
||||
|
||||
### flowchart + vector-illustration
|
||||
- Bold arrows and connectors
|
||||
- Distinct step containers with icons
|
||||
- Clean progression flow
|
||||
- High contrast for readability
|
||||
|
||||
### comparison + vector-illustration
|
||||
- Split layout with clear visual separation
|
||||
- Bold iconography for each side
|
||||
- Color-coded distinctions
|
||||
- Easy at-a-glance comparison
|
||||
|
||||
### framework + vector-illustration
|
||||
- Geometric node representations
|
||||
- Clear hierarchical structure
|
||||
- Bold connecting lines
|
||||
- Modern system diagram aesthetic
|
||||
|
||||
### infographic + blueprint
|
||||
- Technical precision, schematic lines
|
||||
- Grid-based layout, clear zones
|
||||
- Monospace labels, data-focused
|
||||
- Blue/white color scheme
|
||||
|
||||
### infographic + notion
|
||||
- Hand-drawn feel, approachable
|
||||
- Soft icons, rounded elements
|
||||
- Neutral palette, clean backgrounds
|
||||
- Perfect for SaaS/productivity
|
||||
|
||||
### scene + warm
|
||||
- Golden hour lighting, cozy atmosphere
|
||||
- Soft gradients, natural textures
|
||||
- Inviting, personal feeling
|
||||
- Great for storytelling
|
||||
|
||||
### scene + watercolor
|
||||
- Artistic, painterly effect
|
||||
- Soft edges, color bleeding
|
||||
- Dreamy, creative mood
|
||||
- Best for lifestyle/travel
|
||||
|
||||
### flowchart + notion
|
||||
- Clear step indicators
|
||||
- Simple arrow connections
|
||||
- Minimal decoration
|
||||
- Focus on process clarity
|
||||
|
||||
### flowchart + blueprint
|
||||
- Technical precision
|
||||
- Detailed connection points
|
||||
- Engineering aesthetic
|
||||
- For complex systems
|
||||
|
||||
### comparison + elegant
|
||||
- Refined dividers
|
||||
- Balanced typography
|
||||
- Professional appearance
|
||||
- Business comparisons
|
||||
|
||||
### framework + blueprint
|
||||
- Precise node connections
|
||||
- Hierarchical clarity
|
||||
- System architecture feel
|
||||
- Technical frameworks
|
||||
|
||||
### timeline + elegant
|
||||
- Sophisticated markers
|
||||
- Refined typography
|
||||
- Historical gravitas
|
||||
- Professional presentations
|
||||
|
||||
### timeline + warm
|
||||
- Friendly progression
|
||||
- Organic flow
|
||||
- Personal journey feel
|
||||
- Growth narratives
|
||||
|
||||
### scene + screen-print
|
||||
- Bold silhouettes, symbolic compositions
|
||||
- 2-5 flat colors with halftone textures
|
||||
- Figure-ground inversion (negative space tells secondary story)
|
||||
- Vintage poster aesthetic, conceptual not literal
|
||||
- Great for opinion pieces and cultural commentary
|
||||
|
||||
### comparison + screen-print
|
||||
- Split duotone composition (one color per side)
|
||||
- Bold geometric dividers
|
||||
- Symbolic icons over detailed rendering
|
||||
- High contrast, immediate visual impact
|
||||
|
||||
### framework + screen-print
|
||||
- Geometric node representations with stencil-cut edges
|
||||
- Limited color coding (one color per concept level)
|
||||
- Clean silhouette-based iconography
|
||||
- Poster-style hierarchy with bold typography
|
||||
|
||||
---
|
||||
|
||||
## Palette Gallery
|
||||
|
||||
Palettes override a style's default colors. Combine any style with any palette (e.g. `style=vector-illustration, palette=macaron`).
|
||||
|
||||
| Palette | Description | Best For |
|
||||
|---------|-------------|----------|
|
||||
| `macaron` | Soft pastel blocks (blue, mint, lavender, peach) on warm cream | Educational, knowledge, tutorials |
|
||||
| `warm` | Warm earth tones (orange, terracotta, gold) on soft peach, no cool colors | Brand, product, lifestyle |
|
||||
| `neon` | Vibrant neon (pink, cyan, yellow) on dark purple | Gaming, retro, pop culture |
|
||||
| `mono-ink` | Black ink on pure white with sparse semantic accents (coral red, muted teal, dusty lavender) | Professional visual notes, Before/After, manifestos |
|
||||
|
||||
Full specifications: `references/palettes/<palette>.md`
|
||||
|
||||
When no palette is specified, the style's built-in Color Palette is used.
|
||||
|
||||
## Palette Override Rules
|
||||
|
||||
1. Read style file → rendering rules (Visual Elements, Style Rules)
|
||||
2. Read palette file → Colors + Background
|
||||
3. Palette colors **replace** style's default Color Palette
|
||||
4. Palette Background **replaces** style's default Background color
|
||||
5. Style's texture description is preserved
|
||||
|
||||
@@ -0,0 +1,57 @@
|
||||
# blueprint
|
||||
|
||||
Precise technical blueprint style with engineering precision
|
||||
|
||||
## Design Aesthetic
|
||||
|
||||
Clean, structured visual metaphors using blueprints, diagrams, and schematics. Precise, analytical and aesthetically refined. Information presented in grid-based layouts with engineering precision. Technical drawing quality with professional polish.
|
||||
|
||||
## Background
|
||||
|
||||
- Color: Blueprint Off-White (#FAF8F5)
|
||||
- Texture: Subtle grid overlay, engineering paper feel
|
||||
|
||||
## Color Palette
|
||||
|
||||
| Role | Color | Hex | Usage |
|
||||
|------|-------|-----|-------|
|
||||
| Background | Blueprint Paper | #FAF8F5 | Primary background |
|
||||
| Grid | Light Gray | #E5E5E5 | Background grid lines |
|
||||
| Primary Text | Deep Slate | #334155 | Headlines, body |
|
||||
| Primary Accent | Engineering Blue | #2563EB | Key elements |
|
||||
| Secondary Accent | Navy Blue | #1E3A5F | Supporting elements |
|
||||
| Tertiary | Light Blue | #BFDBFE | Fills, backgrounds |
|
||||
| Warning | Amber | #F59E0B | Warnings, emphasis |
|
||||
|
||||
## Visual Elements
|
||||
|
||||
- Precise lines with consistent stroke weights
|
||||
- Technical schematics and clean vector graphics
|
||||
- Thin line work in technical drawing style
|
||||
- Connection lines: straight or 90-degree angles only
|
||||
- Data visualization with minimal charts
|
||||
- Dimension lines and measurement indicators
|
||||
- Cross-section style diagrams
|
||||
- Isometric or orthographic projections
|
||||
|
||||
## Style Rules
|
||||
|
||||
### Do
|
||||
|
||||
- Maintain consistent line weights
|
||||
- Use grid alignment for all elements
|
||||
- Keep color palette restrained
|
||||
- Create clear visual hierarchy through scale
|
||||
- Use geometric precision for all shapes
|
||||
|
||||
### Don't
|
||||
|
||||
- Use hand-drawn or organic shapes
|
||||
- Add decorative flourishes
|
||||
- Use curved connection lines
|
||||
- Include photographic elements
|
||||
- Add unnecessary embellishments
|
||||
|
||||
## Best For
|
||||
|
||||
Technical architecture, system design, data analysis, engineering documentation, process flows, infrastructure articles
|
||||
@@ -0,0 +1,62 @@
|
||||
# chalkboard
|
||||
|
||||
Black chalkboard background with colorful chalk drawing style
|
||||
|
||||
## Design Aesthetic
|
||||
|
||||
Classic classroom chalkboard aesthetic with hand-drawn chalk illustrations. Nostalgic educational feel with imperfect, sketchy lines that capture the warmth of traditional teaching. Colorful chalk creates visual hierarchy while maintaining the authentic chalkboard experience.
|
||||
|
||||
## Background
|
||||
|
||||
- Color: Chalkboard Black (#1A1A1A) or Dark Green-Black (#1C2B1C)
|
||||
- Texture: Realistic chalkboard texture with subtle scratches, dust particles, and faint eraser marks
|
||||
|
||||
## Typography
|
||||
|
||||
Hand-drawn chalk lettering style with visible chalk texture. Imperfect baseline adds authenticity. White or bright colored chalk for emphasis.
|
||||
|
||||
## Color Palette
|
||||
|
||||
| Role | Color | Hex | Usage |
|
||||
|------|-------|-----|-------|
|
||||
| Background | Chalkboard Black | #1A1A1A | Primary background |
|
||||
| Alt Background | Green-Black | #1C2B1C | Traditional green board |
|
||||
| Primary Text | Chalk White | #F5F5F5 | Main text, outlines |
|
||||
| Accent 1 | Chalk Yellow | #FFE566 | Highlights, emphasis |
|
||||
| Accent 2 | Chalk Pink | #FF9999 | Secondary highlights |
|
||||
| Accent 3 | Chalk Blue | #66B3FF | Diagrams, links |
|
||||
| Accent 4 | Chalk Green | #90EE90 | Success, nature |
|
||||
| Accent 5 | Chalk Orange | #FFB366 | Warnings, energy |
|
||||
|
||||
## Visual Elements
|
||||
|
||||
- Hand-drawn chalk illustrations with sketchy, imperfect lines
|
||||
- Chalk dust effects around text and key elements
|
||||
- Doodles: stars, arrows, underlines, circles, checkmarks
|
||||
- Mathematical formulas and simple diagrams
|
||||
- Eraser smudges and chalk residue textures
|
||||
- Wooden frame border optional
|
||||
- Stick figures and simple icons
|
||||
- Connection lines with hand-drawn feel
|
||||
|
||||
## Style Rules
|
||||
|
||||
### Do
|
||||
|
||||
- Maintain authentic chalk texture on all elements
|
||||
- Use imperfect, hand-drawn quality throughout
|
||||
- Add subtle chalk dust and smudge effects
|
||||
- Create visual hierarchy with color variety
|
||||
- Include playful doodles and annotations
|
||||
|
||||
### Don't
|
||||
|
||||
- Use perfect geometric shapes
|
||||
- Create clean digital-looking lines
|
||||
- Add photorealistic elements
|
||||
- Use gradients or glossy effects
|
||||
- Make it look computerized
|
||||
|
||||
## Best For
|
||||
|
||||
Educational articles, tutorials, teaching content, workshops, informal learning, knowledge sharing, how-to guides, classroom-style explanations
|
||||
@@ -0,0 +1,59 @@
|
||||
# editorial
|
||||
|
||||
Magazine-style editorial infographic for professional content
|
||||
|
||||
## Design Aesthetic
|
||||
|
||||
High-quality magazine explainer aesthetic. Clear visual storytelling with structured layouts and professional typography. Think Wired, The Verge, or quality science publications. Complex information made digestible.
|
||||
|
||||
## Background
|
||||
|
||||
- Color: Pure White (#FFFFFF) or Light Gray (#F8F9FA)
|
||||
- Texture: None or subtle paper grain
|
||||
|
||||
## Color Palette
|
||||
|
||||
| Role | Color | Hex | Usage |
|
||||
|------|-------|-----|-------|
|
||||
| Background | Pure White | #FFFFFF | Primary background |
|
||||
| Alt Background | Light Gray | #F8F9FA | Section backgrounds |
|
||||
| Primary Text | Near Black | #1A1A1A | Headlines, body |
|
||||
| Secondary Text | Dark Gray | #4A5568 | Captions |
|
||||
| Accent 1 | Editorial Blue | #2563EB | Primary accent |
|
||||
| Accent 2 | Coral | #F97316 | Secondary accent |
|
||||
| Accent 3 | Emerald | #10B981 | Positive elements |
|
||||
| Accent 4 | Amber | #F59E0B | Attention points |
|
||||
| Dividers | Medium Gray | #D1D5DB | Section dividers |
|
||||
|
||||
## Visual Elements
|
||||
|
||||
- Clean flat illustrations
|
||||
- Structured multi-section layouts
|
||||
- Callout boxes for insights
|
||||
- Icon-based visualizations
|
||||
- Visual metaphors for concepts
|
||||
- Flow diagrams with hierarchy
|
||||
- Pull quotes and highlights
|
||||
- Clear section dividers
|
||||
|
||||
## Style Rules
|
||||
|
||||
### Do
|
||||
|
||||
- Create clear narrative flow
|
||||
- Use structured layouts
|
||||
- Include callout boxes
|
||||
- Design visual metaphors
|
||||
- Maintain magazine polish
|
||||
|
||||
### Don't
|
||||
|
||||
- Use photographic imagery
|
||||
- Create cluttered layouts
|
||||
- Mix too many styles
|
||||
- Add purposeless decoration
|
||||
- Compromise clarity for style
|
||||
|
||||
## Best For
|
||||
|
||||
Technology explainers, science communication, research articles, policy analysis, investigative pieces, thought leadership, long-form journalism
|
||||
@@ -0,0 +1,56 @@
|
||||
# elegant
|
||||
|
||||
Refined, sophisticated illustration style for professional content
|
||||
|
||||
## Design Aesthetic
|
||||
|
||||
Elegant and refined visual approach with sophisticated color palette. Professional polish with subtle artistic touches. Emphasizes clarity and thoughtful composition. Conveys authority and trustworthiness without being cold or clinical.
|
||||
|
||||
## Background
|
||||
|
||||
- Color: Warm Cream (#F5F0E6) or Soft Beige (#FAF6F0)
|
||||
- Texture: Subtle paper texture, very light grain
|
||||
|
||||
## Color Palette
|
||||
|
||||
| Role | Color | Hex | Usage |
|
||||
|------|-------|-----|-------|
|
||||
| Background | Warm Cream | #F5F0E6 | Primary background |
|
||||
| Primary | Soft Coral | #E8A598 | Main accent color |
|
||||
| Secondary | Muted Teal | #5B8A8A | Supporting elements |
|
||||
| Tertiary | Dusty Rose | #D4A5A5 | Subtle highlights |
|
||||
| Accent | Gold | #C9A962 | Premium touches |
|
||||
| Alt Accent | Copper | #B87333 | Warm metallic notes |
|
||||
| Text | Charcoal | #3D3D3D | Text and outlines |
|
||||
|
||||
## Visual Elements
|
||||
|
||||
- Delicate line work with refined strokes
|
||||
- Subtle icons with balanced weight
|
||||
- Graceful curves and flowing compositions
|
||||
- Soft gradients with smooth transitions
|
||||
- Balanced whitespace and breathing room
|
||||
- Thin borders and elegant dividers
|
||||
- Subtle drop shadows for depth
|
||||
|
||||
## Style Rules
|
||||
|
||||
### Do
|
||||
|
||||
- Use refined color combinations
|
||||
- Create balanced, harmonious compositions
|
||||
- Keep elements light and airy
|
||||
- Use subtle gradients sparingly
|
||||
- Maintain generous margins
|
||||
|
||||
### Don't
|
||||
|
||||
- Use harsh contrasts
|
||||
- Overcrowd the composition
|
||||
- Add playful or casual elements
|
||||
- Use neon or overly bright colors
|
||||
- Create busy or cluttered layouts
|
||||
|
||||
## Best For
|
||||
|
||||
Professional articles, thought leadership pieces, business topics, executive communications, corporate blogs, strategy discussions, industry analysis
|
||||
+58
@@ -0,0 +1,58 @@
|
||||
# fantasy-animation
|
||||
|
||||
Whimsical hand-drawn animation style inspired by Ghibli/Disney
|
||||
|
||||
## Design Aesthetic
|
||||
|
||||
Charming hand-drawn animation aesthetic reminiscent of classic Disney, Studio Ghibli, or European storybook illustration. Soft, painterly textures with warm, inviting colors. Friendly characters, magical elements, and storybook feel. Enchanting, nostalgic, and emotionally engaging.
|
||||
|
||||
## Background
|
||||
|
||||
- Color: Soft Sky Blue (#E8F4FC) or Warm Cream (#FFF8E7)
|
||||
- Texture: Subtle watercolor wash, soft brush strokes
|
||||
|
||||
## Color Palette
|
||||
|
||||
| Role | Color | Hex | Usage |
|
||||
|------|-------|-----|-------|
|
||||
| Background | Soft Sky Blue | #E8F4FC | Primary background |
|
||||
| Alt Background | Warm Cream | #FFF8E7 | Secondary areas |
|
||||
| Primary Text | Deep Forest | #2D5A3D | Headlines |
|
||||
| Body Text | Warm Brown | #5D4E37 | Content |
|
||||
| Accent 1 | Golden Yellow | #F4D03F | Magic, highlights |
|
||||
| Accent 2 | Rose Pink | #E8A0BF | Warmth, charm |
|
||||
| Accent 3 | Sage Green | #87A96B | Nature elements |
|
||||
| Accent 4 | Sky Blue | #7EC8E3 | Air, water, dreams |
|
||||
| Accent 5 | Coral | #F08080 | Emphasis, life |
|
||||
|
||||
## Visual Elements
|
||||
|
||||
- Central illustrated character (friendly, expressive)
|
||||
- Small companion creatures (animals, magical beings)
|
||||
- Storybook-style environment backgrounds
|
||||
- Magical floating objects (books, orbs, sparkles)
|
||||
- Decorative elements: stars, flowers, leaves
|
||||
- Soft shadows and gentle highlights
|
||||
- Layered depth with foreground/background
|
||||
|
||||
## Style Rules
|
||||
|
||||
### Do
|
||||
|
||||
- Create warm, inviting compositions
|
||||
- Use soft edges and painterly textures
|
||||
- Include charming character illustrations
|
||||
- Add magical decorative touches
|
||||
- Maintain storybook narrative feel
|
||||
|
||||
### Don't
|
||||
|
||||
- Use harsh geometric shapes
|
||||
- Create dark or intimidating imagery
|
||||
- Add photorealistic elements
|
||||
- Use cold color palettes
|
||||
- Make it look digital/computerized
|
||||
|
||||
## Best For
|
||||
|
||||
Educational content, children's articles, storytelling, creative topics, fantasy/gaming, inspirational pieces, family-friendly content
|
||||
@@ -0,0 +1,61 @@
|
||||
# flat-doodle
|
||||
|
||||
Cute flat doodle illustration style with bold outlines
|
||||
|
||||
## Design Aesthetic
|
||||
|
||||
Cheerful and approachable visual style combining flat design with doodle charm. Features bold black outlines around simple shapes. Bright pastel colors with no gradients or shading. Cute rounded proportions that feel friendly. Clean white backgrounds create focus and clarity.
|
||||
|
||||
## Background
|
||||
|
||||
- Color: Clean White (#FFFFFF)
|
||||
- Texture: None - pure white isolated background
|
||||
|
||||
## Color Palette
|
||||
|
||||
| Role | Color | Hex | Usage |
|
||||
|------|-------|-----|-------|
|
||||
| Background | White | #FFFFFF | Primary background |
|
||||
| Primary | Pastel Pink | #FFB6C1 | Main elements |
|
||||
| Secondary | Mint | #98D8C8 | Supporting elements |
|
||||
| Tertiary | Lavender | #C8A2C8 | Accent elements |
|
||||
| Accent 1 | Butter Yellow | #FFFACD | Highlight pop |
|
||||
| Accent 2 | Sky Blue | #87CEEB | Cool accent |
|
||||
| Accent 3 | Soft Coral | #F88379 | Warm accent |
|
||||
| Outline | Bold Black | #000000 | All outlines |
|
||||
| Text | Black | #1A1A1A | Text elements |
|
||||
|
||||
## Visual Elements
|
||||
|
||||
- Bold black outlines around all shapes
|
||||
- Simple flat color fills
|
||||
- Cute rounded proportions
|
||||
- Minimal geometric shapes
|
||||
- Productivity icons (laptops, calendars, checkmarks)
|
||||
- Isolated elements on white
|
||||
- No shading or gradients
|
||||
- Hand-drawn quality with clean edges
|
||||
|
||||
## Style Rules
|
||||
|
||||
### Do
|
||||
|
||||
- Use bold black outlines consistently
|
||||
- Keep shapes simple and rounded
|
||||
- Use bright pastel palette
|
||||
- Isolate elements on white background
|
||||
- Maintain cute proportions
|
||||
- Keep minimal shading
|
||||
|
||||
### Don't
|
||||
|
||||
- Add shadows or depth effects
|
||||
- Use gradients or textures
|
||||
- Create complex detailed illustrations
|
||||
- Overlap too many elements
|
||||
- Use dark or moody backgrounds
|
||||
- Add realistic proportions
|
||||
|
||||
## Best For
|
||||
|
||||
Productivity articles, SaaS and app content, workflow tutorials, beginner guides, casual business content, tool introductions, lifestyle productivity
|
||||
@@ -0,0 +1,59 @@
|
||||
# flat
|
||||
|
||||
Modern flat vector illustration style for contemporary content
|
||||
|
||||
## Design Aesthetic
|
||||
|
||||
Contemporary flat design aesthetic with bold shapes and limited depth. Clean geometric forms with no gradients or shadows. Modern, accessible, and highly readable. Optimized for digital consumption with scalable vector quality.
|
||||
|
||||
## Background
|
||||
|
||||
- Color: White (#FFFFFF) or Soft Gray (#F5F5F5)
|
||||
- Texture: None - clean solid backgrounds
|
||||
|
||||
## Color Palette
|
||||
|
||||
| Role | Color | Hex | Usage |
|
||||
|------|-------|-----|-------|
|
||||
| Background | White | #FFFFFF | Primary background |
|
||||
| Alt Background | Soft Gray | #F5F5F5 | Accent areas |
|
||||
| Primary | Vibrant Blue | #3B82F6 | Main elements |
|
||||
| Secondary | Coral | #F97316 | Supporting elements |
|
||||
| Tertiary | Emerald | #10B981 | Accent elements |
|
||||
| Accent 1 | Purple | #8B5CF6 | Additional accent |
|
||||
| Accent 2 | Amber | #F59E0B | Highlight |
|
||||
| Text | Dark Slate | #1E293B | Text elements |
|
||||
| Light | Light Gray | #E5E7EB | Subtle elements |
|
||||
|
||||
## Visual Elements
|
||||
|
||||
- Bold geometric shapes
|
||||
- Flat color fills with no gradients
|
||||
- Simple character illustrations
|
||||
- Clean icon designs
|
||||
- Minimal line work
|
||||
- Overlapping shape compositions
|
||||
- Abstract concept visualizations
|
||||
- Consistent stroke weights
|
||||
|
||||
## Style Rules
|
||||
|
||||
### Do
|
||||
|
||||
- Use flat solid colors
|
||||
- Create clean geometric shapes
|
||||
- Keep elements simple
|
||||
- Maintain consistent styling
|
||||
- Use bold color combinations
|
||||
|
||||
### Don't
|
||||
|
||||
- Add shadows or depth
|
||||
- Use gradients or textures
|
||||
- Create realistic illustrations
|
||||
- Add unnecessary details
|
||||
- Use photographic elements
|
||||
|
||||
## Best For
|
||||
|
||||
Modern articles, app and product content, startup stories, digital topics, contemporary business, tech company blogs, social media content
|
||||
@@ -0,0 +1,90 @@
|
||||
# ink-notes
|
||||
|
||||
Professional black-ink visual notes on pure white, in the tradition of Mike Rohde's sketchnoting
|
||||
|
||||
## Compared to sketch-notes
|
||||
|
||||
`ink-notes` and `sketch-notes` are distinct styles. Pick the right one:
|
||||
|
||||
| | `sketch-notes` | `ink-notes` |
|
||||
|---|---|---|
|
||||
| Background | Warm Off-White #FAF8F0 with paper grain | Pure White #FFFFFF, clean, no texture |
|
||||
| Palette | Soft warm accents (orange, mustard, sage, light blue) | Black ink dominant + sparse semantic accents |
|
||||
| Feel | Soft, warm, educational, approachable | Professional, structured, whiteboard-presentation |
|
||||
| Best For | Friendly tutorials, onboarding, casual explainers | Before/After essays, tech manifestos, framework analogies |
|
||||
|
||||
When in doubt: warm & friendly → `sketch-notes`. Disciplined & professional → `ink-notes`.
|
||||
|
||||
## Design Aesthetic
|
||||
|
||||
Disciplined hand-drawn visual note. Confident black ink line work with slight wobble, hand-lettered typography, and sparse color accents used only for semantic emphasis. Feels like a skilled visual notetaker's whiteboard presentation — clean, structured, intentionally hand-drawn rather than decorative.
|
||||
|
||||
## Background
|
||||
|
||||
- Color: Pure White (#FFFFFF)
|
||||
- Texture: Clean, no grain, no tint
|
||||
|
||||
## Color Palette
|
||||
|
||||
| Role | Color | Hex | Usage |
|
||||
|------|-------|-----|-------|
|
||||
| Background | Pure White | #FFFFFF | Canvas |
|
||||
| Primary Ink | Near Black | #1A1A1A | All lines, text, figures, arrows |
|
||||
| Accent Warm | Coral Red | #E8655A | Risk, problem, gap, emphasis |
|
||||
| Accent Cool | Muted Teal | #5FA8A8 | Positive, solution, "after" state |
|
||||
| Accent Neutral | Dusty Lavender | #9B8AB5 | Neutral tags, category labels |
|
||||
| Soft Fill | Pale Gray | #F0F0F0 | Subtle zone backgrounds (optional) |
|
||||
|
||||
Color accents must remain under 10% of canvas area and only carry semantic meaning. Black ink does the structural work.
|
||||
|
||||
## Visual Elements
|
||||
|
||||
- Black ink line work with intentional slight wobble on all strokes
|
||||
- Hand-lettered titles (bold, oversized) and handwritten body annotations
|
||||
- Simple stick-figure characters with expressive poses (pointing, thinking, walking)
|
||||
- Role labels above characters (e.g., "Tech Lead", "Compliance Officer")
|
||||
- Thought bubbles and speech bubbles with hand-drawn outlines
|
||||
- Rounded-rectangle frames for content groupings
|
||||
- Dashed-border rectangles for placeholder, "coming next", or empty states
|
||||
- Curvy hand-drawn arrows with small inline labels
|
||||
- Vertical or horizontal dividers between comparison zones ("Before" | "After")
|
||||
- "Mindset shift" curved arrow bridging two zones
|
||||
- Bottom tagline: single-line hand-lettered conclusion that points the takeaway
|
||||
- Stars, asterisks, underlines for emphasis — used sparingly
|
||||
|
||||
## Style Rules
|
||||
|
||||
### Do
|
||||
|
||||
- Keep background pure white with no texture or tint
|
||||
- Let black ink dominate outlines, text, and figures
|
||||
- Use accent colors only for semantic highlighting
|
||||
- Keep all type hand-lettered — no computer-generated fonts
|
||||
- Maintain confident line quality (wobble, not mess)
|
||||
- Include a bottom tagline summarizing the main takeaway
|
||||
- Structure content into clear zones with visible dividers
|
||||
- Use dashed boxes for future, empty, or placeholder states
|
||||
|
||||
### Don't
|
||||
|
||||
- Use warm off-white or paper-textured backgrounds (that is sketch-notes' territory)
|
||||
- Fill large zones with color blocks
|
||||
- Use more than 3 accent colors per image
|
||||
- Use perfect geometric shapes — preserve hand-drawn wobble
|
||||
- Clutter with decorative doodles; every element must carry meaning
|
||||
- Use gradients, shadows, or computer-generated fonts
|
||||
|
||||
## Type Compatibility
|
||||
|
||||
| Type | Rating | Notes |
|
||||
|------|--------|-------|
|
||||
| comparison | ✓✓ | Best fit — Before/After, Traditional vs New, side-by-side contrasts |
|
||||
| framework | ✓✓ | OS-style command centers, layered architectures, organizational models |
|
||||
| flowchart | ✓✓ | Process explainers with labeled stages, workforce pipelines |
|
||||
| infographic | ✓ | Multi-zone technical summaries, manifesto-style posters |
|
||||
| timeline | ✓ | Hand-drawn horizontal arrow with era markers and milestones |
|
||||
| scene | ✗ | Not recommended — lacks scenic space |
|
||||
|
||||
## Best For
|
||||
|
||||
Product and engineering essays, tech manifestos, framework introductions, Before/After narratives, OS-level comparisons, workforce and organizational analogies, visual summaries of talks, thought-leadership articles
|
||||
+57
@@ -0,0 +1,57 @@
|
||||
# intuition-machine
|
||||
|
||||
Technical briefing infographic style with aged paper and bilingual labels
|
||||
|
||||
## Design Aesthetic
|
||||
|
||||
Academic/technical briefing style with clean 2D or isometric technical illustrations. Information-dense but organized with clear visual hierarchy. Vintage blueprint aesthetic with modern clarity. Multiple explanatory elements with bilingual callouts.
|
||||
|
||||
## Background
|
||||
|
||||
- Color: Aged Cream (#F5F0E6)
|
||||
- Texture: Subtle paper texture with light creases, vintage technical print feel
|
||||
|
||||
## Color Palette
|
||||
|
||||
| Role | Color | Hex | Usage |
|
||||
|------|-------|-----|-------|
|
||||
| Background | Aged Cream | #F5F0E6 | Primary background |
|
||||
| Paper Texture | Warm White | #F5F0E1 | Blueprint effect |
|
||||
| Primary Text | Dark Maroon | #5D3A3A | Headlines, titles |
|
||||
| Body Text | Near Black | #1A1A1A | Content text |
|
||||
| Accent 1 | Teal | #2F7373 | Primary illustrations |
|
||||
| Accent 2 | Warm Brown | #8B7355 | Secondary elements |
|
||||
| Accent 3 | Maroon | #722F37 | Emphasis |
|
||||
| Outline | Deep Charcoal | #2D2D2D | Element outlines |
|
||||
|
||||
## Visual Elements
|
||||
|
||||
- Isometric 3D or flat 2D technical diagrams
|
||||
- Explanatory text boxes with labeled content
|
||||
- Bilingual callout labels (English + Chinese)
|
||||
- Faded thematic background patterns
|
||||
- Clean black outlines on elements
|
||||
- Split or triptych layouts
|
||||
- Key insight boxes
|
||||
|
||||
## Style Rules
|
||||
|
||||
### Do
|
||||
|
||||
- Include multiple text boxes with content
|
||||
- Use bilingual labels for key elements
|
||||
- Add faded thematic background patterns
|
||||
- Maintain aged paper texture
|
||||
- Create clear visual hierarchy
|
||||
|
||||
### Don't
|
||||
|
||||
- Create photorealistic 3D renders
|
||||
- Leave illustrations without explanatory text
|
||||
- Add stamps or watermarks in corners
|
||||
- Use gradients or glossy effects
|
||||
- Make it look too modern/digital
|
||||
|
||||
## Best For
|
||||
|
||||
Technical explanations, concept breakdowns, academic content, research summaries, bilingual audiences, knowledge documentation
|
||||
@@ -0,0 +1,58 @@
|
||||
# minimal
|
||||
|
||||
Ultra-clean, zen-like illustration style for focused content
|
||||
|
||||
## Design Aesthetic
|
||||
|
||||
Maximum simplicity with purposeful restraint. Every element serves a function. Zen-like calm and focus through extensive negative space. Single focal point approach that guides attention naturally. Quiet elegance through reduction.
|
||||
|
||||
## Background
|
||||
|
||||
- Color: Pure White (#FFFFFF) or Off-White (#FAFAFA)
|
||||
- Texture: None - clean solid backgrounds
|
||||
|
||||
## Color Palette
|
||||
|
||||
| Role | Color | Hex | Usage |
|
||||
|------|-------|-----|-------|
|
||||
| Background | White | #FFFFFF | Primary background |
|
||||
| Alt Background | Off-White | #FAFAFA | Subtle variation |
|
||||
| Primary | Pure Black | #000000 | Main elements |
|
||||
| Accent | Content-Derived | varies | Single accent color |
|
||||
| Text | Black | #000000 | Text elements |
|
||||
| Alt Text | Medium Gray | #6B6B6B | Secondary text |
|
||||
|
||||
Note: Accent color is derived from content context. Use sparingly.
|
||||
|
||||
## Visual Elements
|
||||
|
||||
- Single focal element per illustration
|
||||
- Maximum negative space
|
||||
- Thin, precise lines
|
||||
- Simple geometric forms
|
||||
- Subtle shadows if any
|
||||
- Typography as primary element
|
||||
- Strategic use of single accent
|
||||
- Clean, uncluttered compositions
|
||||
|
||||
## Style Rules
|
||||
|
||||
### Do
|
||||
|
||||
- Embrace empty space
|
||||
- Use single focal points
|
||||
- Keep lines thin and precise
|
||||
- Let content breathe
|
||||
- Question every element
|
||||
|
||||
### Don't
|
||||
|
||||
- Add decorative elements
|
||||
- Use multiple accent colors
|
||||
- Fill available space
|
||||
- Add textures or patterns
|
||||
- Create visual complexity
|
||||
|
||||
## Best For
|
||||
|
||||
Philosophy articles, minimalism content, focused explanations, meditation and mindfulness, essential concepts, clarity-focused writing
|
||||
@@ -0,0 +1,58 @@
|
||||
# nature
|
||||
|
||||
Organic, earthy illustration style for environmental and wellness content
|
||||
|
||||
## Design Aesthetic
|
||||
|
||||
Natural and organic visual approach inspired by the outdoors. Earth tones and natural textures that evoke calm and connection to nature. Flowing lines and organic shapes. Creates a sense of tranquility and environmental awareness.
|
||||
|
||||
## Background
|
||||
|
||||
- Color: Sand Beige (#F5E6D3) or Sky Blue wash (#E0F2FE)
|
||||
- Texture: Natural paper texture with organic feel
|
||||
|
||||
## Color Palette
|
||||
|
||||
| Role | Color | Hex | Usage |
|
||||
|------|-------|-----|-------|
|
||||
| Background | Sand Beige | #F5E6D3 | Primary background |
|
||||
| Alt Background | Sky Blue | #E0F2FE | Alternative canvas |
|
||||
| Primary | Forest Green | #276749 | Main natural color |
|
||||
| Secondary | Sage | #9AE6B4 | Supporting green |
|
||||
| Tertiary | Earth Brown | #744210 | Grounding element |
|
||||
| Accent 1 | Sunset Orange | #ED8936 | Warm accent |
|
||||
| Accent 2 | Water Blue | #63B3ED | Cool accent |
|
||||
| Text | Deep Brown | #5D4E3C | Text elements |
|
||||
|
||||
## Visual Elements
|
||||
|
||||
- Leaf and plant motifs
|
||||
- Tree and branch silhouettes
|
||||
- Mountain and landscape shapes
|
||||
- Organic flowing lines
|
||||
- Natural textures (wood grain, stone)
|
||||
- Water and wave patterns
|
||||
- Animal silhouettes
|
||||
- Sun and moon symbols
|
||||
|
||||
## Style Rules
|
||||
|
||||
### Do
|
||||
|
||||
- Use earth-inspired colors
|
||||
- Create organic, flowing shapes
|
||||
- Include nature elements
|
||||
- Evoke outdoor atmosphere
|
||||
- Maintain calm and balance
|
||||
|
||||
### Don't
|
||||
|
||||
- Use synthetic or neon colors
|
||||
- Create rigid geometric shapes
|
||||
- Add tech or digital elements
|
||||
- Use stark contrasts
|
||||
- Overcomplicate compositions
|
||||
|
||||
## Best For
|
||||
|
||||
Sustainability articles, wellness content, outdoor topics, slow living, environmental issues, health and fitness, gardening, travel nature pieces
|
||||
@@ -0,0 +1,58 @@
|
||||
# notion
|
||||
|
||||
Minimalist hand-drawn line art style for knowledge content (Default)
|
||||
|
||||
## Design Aesthetic
|
||||
|
||||
Clean, minimalist hand-drawn line art with intellectual feel. Simple doodle-style illustrations with intentional wobble. Maximum whitespace with single concept focus. Notion-like aesthetic that feels thoughtful and organized.
|
||||
|
||||
## Background
|
||||
|
||||
- Color: Pure White (#FFFFFF) or Off-White (#FAFAFA)
|
||||
- Texture: None - clean solid backgrounds
|
||||
|
||||
## Color Palette
|
||||
|
||||
| Role | Color | Hex | Usage |
|
||||
|------|-------|-----|-------|
|
||||
| Background | White | #FFFFFF | Primary background |
|
||||
| Alt Background | Off-White | #FAFAFA | Subtle variation |
|
||||
| Primary | Black | #1A1A1A | Main outlines |
|
||||
| Secondary | Dark Gray | #4A4A4A | Supporting lines |
|
||||
| Accent 1 | Pastel Blue | #A8D4F0 | Soft highlight |
|
||||
| Accent 2 | Pastel Yellow | #F9E79F | Warm highlight |
|
||||
| Accent 3 | Pastel Pink | #FADBD8 | Gentle accent |
|
||||
| Text | Near Black | #1A1A1A | Text elements |
|
||||
|
||||
## Visual Elements
|
||||
|
||||
- Simple line doodles
|
||||
- Hand-drawn wobble effect
|
||||
- Basic geometric shapes
|
||||
- Stick figures for people
|
||||
- Conceptual icons
|
||||
- Clean hand-drawn lettering
|
||||
- Minimal decorative elements
|
||||
- Single-weight line work
|
||||
|
||||
## Style Rules
|
||||
|
||||
### Do
|
||||
|
||||
- Use maximum whitespace
|
||||
- Keep illustrations simple
|
||||
- Add slight hand-drawn wobble
|
||||
- Focus on single concepts
|
||||
- Use pastel accents sparingly
|
||||
|
||||
### Don't
|
||||
|
||||
- Create complex illustrations
|
||||
- Use many colors at once
|
||||
- Add detailed textures
|
||||
- Make precise geometric shapes
|
||||
- Overcrowd the composition
|
||||
|
||||
## Best For
|
||||
|
||||
Knowledge sharing, concept explanations, SaaS content, productivity articles, educational posts, how-to guides, professional blogs
|
||||
@@ -0,0 +1,57 @@
|
||||
# pixel-art
|
||||
|
||||
Retro 8-bit pixel art aesthetic with nostalgic gaming style
|
||||
|
||||
## Design Aesthetic
|
||||
|
||||
Pixelated retro aesthetic reminiscent of classic 8-bit and 16-bit era games. Chunky pixels, limited color palettes, and nostalgic gaming references. Simple geometric shapes rendered in blocky pixel form. Fun, playful, and immediately recognizable retro tech aesthetic.
|
||||
|
||||
## Background
|
||||
|
||||
- Color: Light Blue (#87CEEB) or Soft Lavender (#E6E6FA)
|
||||
- Texture: Subtle pixel grid pattern, optional CRT scanline effect
|
||||
|
||||
## Color Palette
|
||||
|
||||
| Role | Color | Hex | Usage |
|
||||
|------|-------|-----|-------|
|
||||
| Background | Light Blue | #87CEEB | Primary background |
|
||||
| Alt Background | Soft Lavender | #E6E6FA | Secondary backgrounds |
|
||||
| Primary Text | Dark Navy | #1A1A2E | Main elements |
|
||||
| Accent 1 | Pixel Green | #00FF00 | Success, highlights |
|
||||
| Accent 2 | Pixel Red | #FF0000 | Alerts, emphasis |
|
||||
| Accent 3 | Pixel Yellow | #FFFF00 | Warnings, energy |
|
||||
| Accent 4 | Pixel Cyan | #00FFFF | Info, tech elements |
|
||||
| Accent 5 | Pixel Magenta | #FF00FF | Special elements |
|
||||
|
||||
## Visual Elements
|
||||
|
||||
- All elements rendered with visible pixel structure
|
||||
- Simple iconography: notepad, checkboxes, gears, rockets
|
||||
- Text bubbles with pixel borders
|
||||
- 8-bit decorations: stars, hearts, arrows
|
||||
- Progress bars with chunky pixel segments
|
||||
- Dithering patterns for color transitions
|
||||
- Limited 16-32 color palette
|
||||
|
||||
## Style Rules
|
||||
|
||||
### Do
|
||||
|
||||
- Maintain consistent pixel grid throughout
|
||||
- Use limited color palette (16-32 colors max)
|
||||
- Create blocky, geometric shapes
|
||||
- Add nostalgic gaming references
|
||||
- Use dithering for color transitions
|
||||
|
||||
### Don't
|
||||
|
||||
- Use smooth gradients or anti-aliasing
|
||||
- Create photorealistic elements
|
||||
- Use thin lines or fine details
|
||||
- Add modern glossy effects
|
||||
- Break the pixel grid alignment
|
||||
|
||||
## Best For
|
||||
|
||||
Gaming articles, tech tutorials, nostalgic content, developer topics, retro-themed pieces, creative tech content
|
||||
@@ -0,0 +1,59 @@
|
||||
# playful
|
||||
|
||||
Fun, creative illustration style for casual and educational content
|
||||
|
||||
## Design Aesthetic
|
||||
|
||||
Whimsical and entertaining visual approach that sparks joy. Pastel colors with bright pops of energy. Doodle-like quality that feels approachable and fun. Creates a sense of play and discovery. Encourages engagement through visual delight.
|
||||
|
||||
## Background
|
||||
|
||||
- Color: Light Cream (#FFFBEB) or Soft White (#FFF)
|
||||
- Texture: Subtle, playful pattern or clean
|
||||
|
||||
## Color Palette
|
||||
|
||||
| Role | Color | Hex | Usage |
|
||||
|------|-------|-----|-------|
|
||||
| Background | Light Cream | #FFFBEB | Primary background |
|
||||
| Primary | Pastel Pink | #FED7E2 | Soft warmth |
|
||||
| Secondary | Mint | #C6F6D5 | Fresh energy |
|
||||
| Tertiary | Lavender | #E9D8FD | Dreamy touch |
|
||||
| Accent 1 | Sky Blue | #BEE3F8 | Calm brightness |
|
||||
| Accent 2 | Bright Yellow | #FBBF24 | Energy pop |
|
||||
| Accent 3 | Coral | #F6AD55 | Warm pop |
|
||||
| Accent 4 | Turquoise | #38B2AC | Cool pop |
|
||||
| Text | Soft Charcoal | #4A4A4A | Text elements |
|
||||
|
||||
## Visual Elements
|
||||
|
||||
- Doodles and sketchy lines
|
||||
- Star and sparkle decorations
|
||||
- Swirls and curvy elements
|
||||
- Cute character illustrations
|
||||
- Speech bubbles and callouts
|
||||
- Emoji-style icons
|
||||
- Confetti and celebration marks
|
||||
- Playful hand-lettering
|
||||
|
||||
## Style Rules
|
||||
|
||||
### Do
|
||||
|
||||
- Use varied pastel palette
|
||||
- Add whimsical decorations
|
||||
- Create friendly characters
|
||||
- Include playful details
|
||||
- Keep energy high and positive
|
||||
|
||||
### Don't
|
||||
|
||||
- Use dark or moody colors
|
||||
- Create serious compositions
|
||||
- Add corporate elements
|
||||
- Use rigid geometric shapes
|
||||
- Make it feel professional
|
||||
|
||||
## Best For
|
||||
|
||||
Tutorials and guides, beginner-friendly content, casual articles, fun topics, children's content, hobby-related posts, entertaining explanations
|
||||
@@ -0,0 +1,59 @@
|
||||
# retro
|
||||
|
||||
80s/90s nostalgic aesthetic with vibrant colors and geometric patterns
|
||||
|
||||
## Design Aesthetic
|
||||
|
||||
Nostalgic retro aesthetic inspired by 80s and 90s design trends. Vibrant neon colors, geometric patterns, and Memphis design influence. Energetic, fun, and unapologetically bold. Perfect for content that embraces nostalgia or playful energy.
|
||||
|
||||
## Background
|
||||
|
||||
- Color: Deep Purple (#2D1B4E) or Dark Teal (#0F4C5C)
|
||||
- Texture: Subtle grid patterns or geometric shapes
|
||||
|
||||
## Color Palette
|
||||
|
||||
| Role | Color | Hex | Usage |
|
||||
|------|-------|-----|-------|
|
||||
| Background | Deep Purple | #2D1B4E | Primary background |
|
||||
| Alt Background | Dark Teal | #0F4C5C | Alternative |
|
||||
| Primary | Hot Pink | #FF1493 | Main accent |
|
||||
| Secondary | Electric Cyan | #00FFFF | Supporting |
|
||||
| Tertiary | Neon Yellow | #FFFF00 | Highlights |
|
||||
| Accent 1 | Lime Green | #32CD32 | Energy |
|
||||
| Accent 2 | Orange | #FF6B35 | Warmth |
|
||||
| Text | White | #FFFFFF | Text elements |
|
||||
| Grid | Light Purple | #9D8EC0 | Grid lines |
|
||||
|
||||
## Visual Elements
|
||||
|
||||
- Geometric patterns (triangles, circles)
|
||||
- Grid backgrounds and lines
|
||||
- Neon glow effects
|
||||
- Memphis design shapes
|
||||
- Zigzag and wavy patterns
|
||||
- Retro computer graphics
|
||||
- Bold outline strokes
|
||||
- Gradient sunsets
|
||||
|
||||
## Style Rules
|
||||
|
||||
### Do
|
||||
|
||||
- Use bold neon colors
|
||||
- Create geometric patterns
|
||||
- Add retro typography
|
||||
- Include Memphis-style shapes
|
||||
- Embrace maximalism
|
||||
|
||||
### Don't
|
||||
|
||||
- Use muted or subtle colors
|
||||
- Create minimal compositions
|
||||
- Add modern flat design
|
||||
- Make it look contemporary
|
||||
- Use understated elements
|
||||
|
||||
## Best For
|
||||
|
||||
Pop culture articles, gaming content, music and entertainment, nostalgia pieces, youth-focused content, creative industry, party and event content
|
||||
@@ -0,0 +1,59 @@
|
||||
# scientific
|
||||
|
||||
Academic scientific illustration style for technical diagrams and processes
|
||||
|
||||
## Design Aesthetic
|
||||
|
||||
Academic scientific illustration aesthetic for biological, chemical, and technical diagrams. Clean, precise diagrams with proper labeling and clear visual flow. Educational clarity with professional polish. Textbook quality illustrations.
|
||||
|
||||
## Background
|
||||
|
||||
- Color: Off-White (#FAFAFA) or Light Blue-Gray (#F0F4F8)
|
||||
- Texture: None or subtle paper grain
|
||||
|
||||
## Color Palette
|
||||
|
||||
| Role | Color | Hex | Usage |
|
||||
|------|-------|-----|-------|
|
||||
| Background | Off-White | #FAFAFA | Primary background |
|
||||
| Primary Text | Dark Slate | #1E293B | Labels, headers |
|
||||
| Label Text | Medium Gray | #475569 | Annotations |
|
||||
| Pathway 1 | Teal | #0D9488 | Primary pathway |
|
||||
| Pathway 2 | Blue | #3B82F6 | Secondary pathway |
|
||||
| Pathway 3 | Purple | #8B5CF6 | Tertiary pathway |
|
||||
| Structure | Amber | #F59E0B | Membranes, structures |
|
||||
| Alert | Red | #EF4444 | Key elements |
|
||||
| Positive | Green | #22C55E | Products, outputs |
|
||||
|
||||
## Visual Elements
|
||||
|
||||
- Precise labeled diagrams
|
||||
- Flow arrows showing direction
|
||||
- Modular components with colors
|
||||
- Chemical formulas and notation
|
||||
- Cross-section views
|
||||
- Numbered step sequences
|
||||
- Molecule and cell representations
|
||||
- Process summary boxes
|
||||
|
||||
## Style Rules
|
||||
|
||||
### Do
|
||||
|
||||
- Use precise consistent lines
|
||||
- Label all components clearly
|
||||
- Show directional flow
|
||||
- Include technical notation
|
||||
- Create clear numbered sequences
|
||||
|
||||
### Don't
|
||||
|
||||
- Use decorative elements
|
||||
- Create imprecise diagrams
|
||||
- Omit important labels
|
||||
- Use inconsistent styling
|
||||
- Add artistic flourishes
|
||||
|
||||
## Best For
|
||||
|
||||
Biology articles, chemistry explanations, medical content, research summaries, academic writing, technical documentation, process explanations
|
||||
@@ -0,0 +1,70 @@
|
||||
# screen-print
|
||||
|
||||
Bold poster art with limited colors, halftone textures, and symbolic storytelling
|
||||
|
||||
## Design Aesthetic
|
||||
|
||||
Screen print / silkscreen aesthetic inspired by Mondo limited-edition posters and vintage concert prints. Flat color blocks, halftone dot patterns, bold silhouettes, and deliberate print imperfections. Conceptual and symbolic rather than literal — one iconic image tells the whole story. Perfect for opinion pieces, cultural commentary, and editorial content.
|
||||
|
||||
## Background
|
||||
|
||||
- Color: Off-Black (#121212) or Warm Cream (#F5E6D0)
|
||||
- Texture: Paper grain with subtle halftone dot overlay
|
||||
|
||||
## Color Palette
|
||||
|
||||
| Role | Color | Hex | Usage |
|
||||
|------|-------|-----|-------|
|
||||
| Background | Off-Black | #121212 | Dark compositions |
|
||||
| Background Alt | Warm Cream | #F5E6D0 | Light compositions |
|
||||
| Primary | Burnt Orange | #E8751A | Main accent |
|
||||
| Secondary | Deep Teal | #0A6E6E | Contrast accent |
|
||||
| Tertiary | Crimson | #C0392B | Bold emphasis |
|
||||
| Highlight | Amber | #F4A623 | Small accents |
|
||||
| Text | Cream White | #FAF3E0 | On dark backgrounds |
|
||||
|
||||
**Duotone Pairs** (choose ONE pair for high-impact compositions):
|
||||
|
||||
| Pair | Color A | Color B | Feel |
|
||||
|------|---------|---------|------|
|
||||
| Orange + Teal | #E8751A | #0A6E6E | Cinematic, action |
|
||||
| Red + Cream | #C0392B | #F5E6D0 | Bold, classic |
|
||||
| Blue + Gold | #1A3A5C | #D4A843 | Prestigious, premium |
|
||||
| Crimson + Navy | #DC143C | #0D1B2A | Dramatic, noir |
|
||||
|
||||
**Rule**: Use 2-5 colors maximum. Fewer colors = stronger impact.
|
||||
|
||||
## Visual Elements
|
||||
|
||||
- Bold silhouettes and symbolic shapes
|
||||
- Halftone dot patterns within color fills
|
||||
- Slight color layer misregistration (print offset effect)
|
||||
- Geometric framing (circles, arches, triangles)
|
||||
- Figure-ground inversion (negative space forms secondary image)
|
||||
- Stencil-cut edges, no outlines — shapes defined by color boundaries
|
||||
- Typography integrated as design element, not overlay
|
||||
- Vintage poster border treatments
|
||||
|
||||
## Style Rules
|
||||
|
||||
### Do
|
||||
|
||||
- Limit to 2-5 flat colors
|
||||
- Use bold silhouettes over detailed rendering
|
||||
- Let negative space tell part of the story
|
||||
- Add halftone texture for authenticity
|
||||
- Use geometric composition (centered, symmetrical)
|
||||
- Reference vintage decades (60s/70s/80s) for era feel
|
||||
|
||||
### Don't
|
||||
|
||||
- Use photorealistic rendering or gradients
|
||||
- Add complex facial details (silhouettes preferred)
|
||||
- Mix too many visual elements (one focal point)
|
||||
- Use modern digital aesthetic
|
||||
- Create busy or cluttered compositions
|
||||
- Use more than 5 colors
|
||||
|
||||
## Best For
|
||||
|
||||
Opinion/editorial articles, cultural commentary, philosophy and strategy, dramatic narratives, cinematic storytelling, music and entertainment, event announcements, bold branding content
|
||||
@@ -0,0 +1,56 @@
|
||||
# sketch-notes
|
||||
|
||||
Soft hand-drawn illustration style with warm, educational feel
|
||||
|
||||
## Design Aesthetic
|
||||
|
||||
Hand-drawn feel with soft, relaxed brush strokes. Fresh, refined style with minimalist editorial approach. Emphasis on precision, clarity and intelligent elegance while prioritizing warmth, approachability and friendliness.
|
||||
|
||||
## Background
|
||||
|
||||
- Color: Warm Off-White (#FAF8F0)
|
||||
- Texture: Subtle paper grain, warm tone
|
||||
|
||||
## Color Palette
|
||||
|
||||
| Role | Color | Hex | Usage |
|
||||
|------|-------|-----|-------|
|
||||
| Background | Warm Off-White | #FAF8F0 | Primary background |
|
||||
| Primary Text | Deep Charcoal | #2C3E50 | Main elements |
|
||||
| Alt Text | Deep Brown | #4A4A4A | Secondary elements |
|
||||
| Accent 1 | Soft Orange | #F4A261 | Highlights, emphasis |
|
||||
| Accent 2 | Mustard Yellow | #E9C46A | Secondary highlights |
|
||||
| Accent 3 | Sage Green | #87A96B | Nature, growth concepts |
|
||||
| Accent 4 | Light Blue | #7EC8E3 | Tech, digital elements |
|
||||
| Accent 5 | Red Brown | #A0522D | Earthy elements |
|
||||
|
||||
## Visual Elements
|
||||
|
||||
- Connection lines with hand-drawn wavy feel
|
||||
- Conceptual abstract icons illustrating ideas
|
||||
- Color fills don't completely fill outlines (hand-painted feel)
|
||||
- Simple geometric shapes with rounded corners
|
||||
- Arrows and pointers with sketchy style
|
||||
- Doodle decorations: stars, spirals, underlines
|
||||
|
||||
## Style Rules
|
||||
|
||||
### Do
|
||||
|
||||
- Keep layouts open and well-structured
|
||||
- Emphasize information hierarchy
|
||||
- Use hand-drawn quality for all elements
|
||||
- Allow imperfection (slight wobbles add character)
|
||||
- Layer elements with subtle overlaps
|
||||
|
||||
### Don't
|
||||
|
||||
- Use perfect geometric shapes
|
||||
- Create photorealistic elements
|
||||
- Overcrowd with too many elements
|
||||
- Use pure white backgrounds
|
||||
- Make it look computer-generated
|
||||
|
||||
## Best For
|
||||
|
||||
Educational content, knowledge sharing, technical explanations, tutorials, onboarding materials, friendly articles
|
||||
@@ -0,0 +1,57 @@
|
||||
# sketch
|
||||
|
||||
Raw, authentic notebook-style illustration for ideas and processes
|
||||
|
||||
## Design Aesthetic
|
||||
|
||||
Hand-drawn sketch aesthetic that feels authentic and in-progress. Pencil-on-paper quality with intentional imperfection. Suggests thinking, brainstorming, and creative exploration. Raw and honest visual approach that invites collaboration.
|
||||
|
||||
## Background
|
||||
|
||||
- Color: Off-White Paper (#F7FAFC) or Cream (#FAFAFA)
|
||||
- Texture: Paper texture with visible grain
|
||||
|
||||
## Color Palette
|
||||
|
||||
| Role | Color | Hex | Usage |
|
||||
|------|-------|-----|-------|
|
||||
| Background | Paper White | #F7FAFC | Primary background |
|
||||
| Primary | Pencil Gray | #4A5568 | Main sketch lines |
|
||||
| Secondary | Light Gray | #A0AEC0 | Shading, soft marks |
|
||||
| Highlight Blue | Note Blue | #3182CE | Highlight color |
|
||||
| Highlight Red | Mark Red | #E53E3E | Emphasis color |
|
||||
| Highlight Yellow | Marker Yellow | #F6E05E | Highlighter effect |
|
||||
| Text | Charcoal | #2D3748 | Text elements |
|
||||
|
||||
## Visual Elements
|
||||
|
||||
- Rough sketch lines with natural variation
|
||||
- Arrows and directional pointers
|
||||
- Handwritten labels and notes
|
||||
- Crossed-out marks and corrections
|
||||
- Underlines and emphasis marks
|
||||
- Simple diagram shapes
|
||||
- Margin notes style
|
||||
- Quick icon sketches
|
||||
|
||||
## Style Rules
|
||||
|
||||
### Do
|
||||
|
||||
- Use pencil-like line quality
|
||||
- Include natural imperfections
|
||||
- Add handwritten annotations
|
||||
- Create diagram-style layouts
|
||||
- Show thinking process
|
||||
|
||||
### Don't
|
||||
|
||||
- Use perfect geometric shapes
|
||||
- Add polished or refined elements
|
||||
- Create colorful compositions
|
||||
- Use digital effects
|
||||
- Make it look finished
|
||||
|
||||
## Best For
|
||||
|
||||
Ideas in progress, brainstorming articles, thought processes, concept exploration, draft-stage thinking, planning content, problem-solving pieces
|
||||
+57
@@ -0,0 +1,57 @@
|
||||
# vector-illustration
|
||||
|
||||
Flat vector illustration style with clear black outlines and retro soft colors
|
||||
|
||||
## Design Aesthetic
|
||||
|
||||
Flat vector illustration with no gradients or 3D effects. Clear, uniform-thickness black outlines on all elements. Geometric simplification reducing complex objects to basic shapes. Toy model aesthetic that's cute, playful, and approachable. Coloring book style with closed outlines.
|
||||
|
||||
## Background
|
||||
|
||||
- Color: Cream Off-White (#F5F0E6)
|
||||
- Texture: Subtle paper texture, warm nostalgic feel
|
||||
|
||||
## Color Palette
|
||||
|
||||
| Role | Color | Hex | Usage |
|
||||
|------|-------|-----|-------|
|
||||
| Background | Cream Off-White | #F5F0E6 | Primary background |
|
||||
| Outlines | Deep Charcoal | #2D2D2D | All element outlines |
|
||||
| Primary | Coral Red | #E07A5F | Primary accent, warmth |
|
||||
| Secondary | Mint Green | #81B29A | Nature, growth |
|
||||
| Tertiary | Mustard Yellow | #F2CC8F | Highlights, energy |
|
||||
| Accent 1 | Burnt Orange | #D4764A | Warm accents |
|
||||
| Accent 2 | Rock Blue | #577590 | Cool balance |
|
||||
| Text | Black | #1A1A1A | Text elements |
|
||||
|
||||
## Visual Elements
|
||||
|
||||
- All objects have closed black outlines (coloring book style)
|
||||
- Rounded line endings, avoid sharp corners
|
||||
- Trees simplified to lollipop or triangle shapes
|
||||
- Buildings as rectangular blocks with grid windows
|
||||
- Depth through layering and overlap
|
||||
- Decorative elements: sunbursts, pill-shaped clouds, dots, stars
|
||||
- People as simple geometric figures
|
||||
|
||||
## Style Rules
|
||||
|
||||
### Do
|
||||
|
||||
- Maintain consistent outline thickness
|
||||
- Use soft, vintage color palette
|
||||
- Simplify objects to basic geometric shapes
|
||||
- Create depth through layering
|
||||
- Add playful decorative elements
|
||||
|
||||
### Don't
|
||||
|
||||
- Use gradients or realistic shading
|
||||
- Create photorealistic elements
|
||||
- Use thin or varying line weights
|
||||
- Include complex detailed illustrations
|
||||
- Add textures inside shapes
|
||||
|
||||
## Best For
|
||||
|
||||
Educational content, creative articles, children's content, brand showcases, explainer pieces, warm approachable topics
|
||||
@@ -0,0 +1,59 @@
|
||||
# vintage
|
||||
|
||||
Nostalgic aged-paper aesthetic for historical and heritage content
|
||||
|
||||
## Design Aesthetic
|
||||
|
||||
Nostalgic vintage aesthetic with aged paper textures and historical document styling. Explorer's journal and antique map quality. Rich warm tones with weathered textures. Evokes discovery, heritage, and timeless knowledge.
|
||||
|
||||
## Background
|
||||
|
||||
- Color: Aged Parchment (#F5E6D3) or Sepia Cream (#FFF8DC)
|
||||
- Texture: Heavy aged paper texture with subtle stains and worn edges
|
||||
|
||||
## Color Palette
|
||||
|
||||
| Role | Color | Hex | Usage |
|
||||
|------|-------|-----|-------|
|
||||
| Background | Aged Parchment | #F5E6D3 | Primary background |
|
||||
| Alt Background | Sepia Cream | #FFF8DC | Secondary areas |
|
||||
| Primary Text | Dark Brown | #3D2914 | Main elements |
|
||||
| Secondary | Medium Brown | #6B4423 | Supporting details |
|
||||
| Accent 1 | Forest Green | #2D5A3D | Nature, maps |
|
||||
| Accent 2 | Navy Blue | #1E3A5F | Ocean, lines |
|
||||
| Accent 3 | Burgundy | #722F37 | Emphasis |
|
||||
| Accent 4 | Gold | #C9A227 | Highlights |
|
||||
| Ink | Sepia Black | #3D3D3D | Fine details |
|
||||
|
||||
## Visual Elements
|
||||
|
||||
- Antique map styling with route lines
|
||||
- Compass roses and navigation elements
|
||||
- Specimen-style drawings
|
||||
- Handwritten annotations
|
||||
- Rope, leather, brass decorative motifs
|
||||
- Vintage photograph frames
|
||||
- Aged paper edge effects
|
||||
- Historical document styling
|
||||
|
||||
## Style Rules
|
||||
|
||||
### Do
|
||||
|
||||
- Apply consistent aged texture
|
||||
- Use period-appropriate styling
|
||||
- Include map and journey elements
|
||||
- Create layered compositions
|
||||
- Maintain warm sepia tones
|
||||
|
||||
### Don't
|
||||
|
||||
- Use modern digital styling
|
||||
- Create crisp clean edges
|
||||
- Use cold or bright colors
|
||||
- Add contemporary elements
|
||||
- Make it look new or fresh
|
||||
|
||||
## Best For
|
||||
|
||||
Historical articles, travel and exploration, biography pieces, heritage stories, scientific discovery narratives, museum-style content, classic literature references
|
||||
@@ -0,0 +1,58 @@
|
||||
# warm
|
||||
|
||||
Friendly, approachable illustration style for human-centered content
|
||||
|
||||
## Design Aesthetic
|
||||
|
||||
Warm and inviting visual approach that feels personal and approachable. Soft, friendly colors that evoke comfort and connection. Emphasizes human elements and emotional resonance. Creates an atmosphere of trust and openness.
|
||||
|
||||
## Background
|
||||
|
||||
- Color: Cream (#FFFAF0) or Soft Peach (#FED7AA)
|
||||
- Texture: Soft paper texture with warm undertones
|
||||
|
||||
## Color Palette
|
||||
|
||||
| Role | Color | Hex | Usage |
|
||||
|------|-------|-----|-------|
|
||||
| Background | Cream | #FFFAF0 | Primary background |
|
||||
| Alt Background | Soft Peach | #FED7AA | Accent sections |
|
||||
| Primary | Warm Orange | #ED8936 | Main accent color |
|
||||
| Secondary | Golden Yellow | #F6AD55 | Supporting warmth |
|
||||
| Tertiary | Terracotta | #C05621 | Earthy depth |
|
||||
| Accent | Deep Brown | #744210 | Grounding elements |
|
||||
| Alt Accent | Soft Red | #E53E3E | Emotional touches |
|
||||
| Text | Warm Charcoal | #4A4A4A | Text elements |
|
||||
|
||||
## Visual Elements
|
||||
|
||||
- Rounded shapes and soft corners
|
||||
- Friendly character illustrations
|
||||
- Sun rays and warm light motifs
|
||||
- Heart symbols and care icons
|
||||
- Cozy lighting effects
|
||||
- Gentle gradients with warmth
|
||||
- Soft shadows without harsh edges
|
||||
- Hand-drawn quality touches
|
||||
|
||||
## Style Rules
|
||||
|
||||
### Do
|
||||
|
||||
- Use warm, inviting colors
|
||||
- Create rounded, friendly shapes
|
||||
- Include human-centered elements
|
||||
- Evoke feelings of comfort
|
||||
- Maintain soft, gentle contrasts
|
||||
|
||||
### Don't
|
||||
|
||||
- Use cold or stark colors
|
||||
- Create sharp, aggressive shapes
|
||||
- Add technical or clinical elements
|
||||
- Use dark, moody backgrounds
|
||||
- Create sterile compositions
|
||||
|
||||
## Best For
|
||||
|
||||
Personal growth articles, lifestyle content, education, human interest stories, wellness topics, relationship advice, self-help content, community building
|
||||
@@ -0,0 +1,58 @@
|
||||
# watercolor
|
||||
|
||||
Soft, artistic watercolor illustration style with natural warmth
|
||||
|
||||
## Design Aesthetic
|
||||
|
||||
Gentle watercolor aesthetic with visible brush strokes and natural color bleeding. Hand-painted feel with soft edges and organic shapes. Warm, approachable, and artistically refined. Combines artistic expression with clear visual communication.
|
||||
|
||||
## Background
|
||||
|
||||
- Color: Warm Off-White (#FAF8F0) or Soft Cream (#FFF9E6)
|
||||
- Texture: Subtle watercolor paper texture with visible grain
|
||||
|
||||
## Color Palette
|
||||
|
||||
| Role | Color | Hex | Usage |
|
||||
|------|-------|-----|-------|
|
||||
| Background | Warm Off-White | #FAF8F0 | Primary background |
|
||||
| Primary | Soft Coral | #F4A261 | Primary warmth |
|
||||
| Secondary | Dusty Rose | #E8A0A0 | Secondary warmth |
|
||||
| Tertiary | Sage Green | #87A96B | Nature, growth |
|
||||
| Accent 1 | Sky Blue | #7EC8E3 | Water, calm |
|
||||
| Accent 2 | Soft Lavender | #C5B4E3 | Accent, creativity |
|
||||
| Wash | Pale Yellow | #FFF3C4 | Background washes |
|
||||
| Text | Warm Charcoal | #3D3D3D | Text elements |
|
||||
|
||||
## Visual Elements
|
||||
|
||||
- Watercolor washes as backgrounds
|
||||
- Illustrated elements with visible brush strokes
|
||||
- Natural elements: leaves, flowers, bubbles
|
||||
- Color bleeds and soft edges
|
||||
- Hand-drawn arrows and lines
|
||||
- Layered wash effects
|
||||
- Soft gradients through water
|
||||
- Expressive character illustrations
|
||||
|
||||
## Style Rules
|
||||
|
||||
### Do
|
||||
|
||||
- Allow color to bleed beyond edges
|
||||
- Use visible brush stroke textures
|
||||
- Create soft, organic shapes
|
||||
- Include hand-drawn quality
|
||||
- Maintain warm color palette
|
||||
|
||||
### Don't
|
||||
|
||||
- Use sharp geometric shapes
|
||||
- Create hard digital edges
|
||||
- Use cold or stark colors
|
||||
- Add photographic elements
|
||||
- Create overly precise illustrations
|
||||
|
||||
## Best For
|
||||
|
||||
Lifestyle articles, wellness content, travel pieces, food and cooking, personal stories, creative topics, artistic portfolios, warm educational content
|
||||
@@ -0,0 +1,50 @@
|
||||
# Usage
|
||||
|
||||
This skill is triggered by natural language in Hermes — no slash command or CLI flags.
|
||||
|
||||
## Trigger Phrases
|
||||
|
||||
- "Illustrate this article" / "为文章配图"
|
||||
- "Add images to this post"
|
||||
- "Generate illustrations for [path/to/article.md]"
|
||||
|
||||
## Input Modes
|
||||
|
||||
| Mode | How to trigger | Output Directory |
|
||||
|------|----------------|------------------|
|
||||
| File path | Mention an article path (`path/to/article.md`) | `{article-dir}/imgs/` (default) |
|
||||
| Pasted content | Paste the article text in the conversation | `illustrations/{topic-slug}/` (cwd) |
|
||||
|
||||
## Specifying Options in Natural Language
|
||||
|
||||
The user can specify any of the following directly in their request. If not specified, the skill asks via the `clarify` tool.
|
||||
|
||||
| Option | Example phrasing |
|
||||
|--------|------------------|
|
||||
| Type | "as an infographic", "as a flowchart", "as scenes" |
|
||||
| Style | "in blueprint style", "use notion style", "用 watercolor 风格" |
|
||||
| Preset | "use the tech-explainer preset", "storytelling preset" |
|
||||
| Palette | "with macaron palette", "warm colors only" |
|
||||
| Density | "minimal images", "one per section", "rich illustrations" |
|
||||
| Language | "images in English" / "图片文字用中文" |
|
||||
| Output | "save images alongside the article" / "put them in `illustrations/`" |
|
||||
|
||||
## Examples
|
||||
|
||||
**Technical article with data**:
|
||||
> 帮我为 api-design.md 配图，用 infographic + blueprint 风格
|
||||
|
||||
**Preset shortcut**:
|
||||
> Illustrate api-design.md with the tech-explainer preset
|
||||
|
||||
**Personal story**:
|
||||
> Illustrate journey.md using the storytelling preset
|
||||
|
||||
**Tutorial with rich images**:
|
||||
> Generate illustrations for how-to-deploy.md — tutorial preset, rich density
|
||||
|
||||
**Opinion article**:
|
||||
> Illustrate opinion.md with the opinion-piece preset
|
||||
|
||||
**Preset with style override**:
|
||||
> Use the tech-explainer preset for article.md but swap the style for notion
|
||||
@@ -0,0 +1,332 @@
|
||||
# Detailed Workflow Procedures
|
||||
|
||||
## Step 1: Detect Reference Images
|
||||
|
||||
If the user provides reference images (local path or URL), the goal is to produce **textual descriptions** that can be embedded in prompts — `image_generate` doesn't accept reference-image inputs, and Hermes' text file tools can't read or write binaries.
|
||||
|
||||
**Tool rules**:
|
||||
|
||||
| Task | Tool | Notes |
|
||||
|------|------|-------|
|
||||
| Analyze a reference image | `vision_analyze` | Accepts URL or local path. Ask for style, palette, composition, subject. |
|
||||
| Write the text description | `write_file` | Sidecar `.md` files only — never try to `write_file` a PNG/JPG. |
|
||||
| (Optional) Keep a local copy of the binary | `terminal` | `cp "$src" "{output-dir}/references/NN-ref-{slug}.{ext}"` — purely for the record; the skill itself doesn't read the binary. |
|
||||
|
||||
| Input Type | Action |
|
||||
|------------|--------|
|
||||
| Image file path provided | `vision_analyze` → write sidecar `.md`. Optional `terminal cp` for a local record. |
|
||||
| Image URL provided | `vision_analyze` with the URL → write sidecar `.md`. |
|
||||
| Image in conversation (no path, no URL) | Ask via `clarify` for a path or URL, or for a verbal description. |
|
||||
| User can't provide either | Extract style/palette verbally from the user → write `references/extracted-style.md`. Do NOT add `references:` to prompt frontmatter. |
|
||||
|
||||
**Procedure** (when a path/URL is available):
|
||||
|
||||
1. Call `vision_analyze(image_url=..., question="Describe the style, color palette (with hex approximations), composition, and subject so this can be used as a style/palette reference for another illustration.")`.
|
||||
2. Write `{output-dir}/references/NN-ref-{slug}.md` via `write_file` with the description.
|
||||
3. (Optional) Run `terminal` with `cp` (or `curl -sSL -o ...` for URLs) to keep a local binary copy. Not required by the skill.
|
||||
4. Mark the reference in the outline with usage `direct` / `style` / `palette`. In Step 5.1 the description gets appended to the prompt body.
|
||||
|
||||
**Sidecar File Format**:
|
||||
```yaml
|
||||
---
|
||||
ref_id: NN
|
||||
source: "<original path or URL>"
|
||||
local_copy: "NN-ref-{slug}.png" # omit if no copy made
|
||||
usage_hint: style # direct | style | palette
|
||||
---
|
||||
[vision_analyze description — colors, style, composition, subject]
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Step 2: Analyze
|
||||
|
||||
### 2.1 Determine Output Directory
|
||||
|
||||
| Input | Output Directory | Source-save path |
|
||||
|-------|------------------|------------------|
|
||||
| Article file path | `{article-dir}/imgs/` (default) | — (read article via `read_file`) |
|
||||
| Pasted content | `illustrations/{topic-slug}/` (cwd) | `source-{slug}.{ext}` (save via `write_file`) |
|
||||
|
||||
If the user explicitly asked for a different layout (e.g., images in the article's folder, or an `illustrations/` subdirectory), honor that.
|
||||
|
||||
### 2.2 Analyze Content
|
||||
|
||||
| Analysis | Description |
|
||||
|----------|-------------|
|
||||
| Content type | Technical / Tutorial / Methodology / Narrative |
|
||||
| Illustration purpose | information / visualization / imagination |
|
||||
| Core arguments | 2-5 main points to visualize |
|
||||
| Visual opportunities | Positions where illustrations add value |
|
||||
| Recommended type | Based on content signals and purpose |
|
||||
| Recommended density | Based on length and complexity |
|
||||
|
||||
Save analysis to `{output-dir}/analysis.md` using `write_file`.
|
||||
|
||||
### 2.3 Extract Core Arguments
|
||||
|
||||
- Main thesis
|
||||
- Key concepts reader needs
|
||||
- Comparisons/contrasts
|
||||
- Framework/model proposed
|
||||
|
||||
**CRITICAL**: If the article uses metaphors (e.g., "电锯切西瓜"), do NOT illustrate literally. Visualize the **underlying concept**.
|
||||
|
||||
### 2.4 Identify Positions
|
||||
|
||||
**Illustrate**:
|
||||
- Core arguments (REQUIRED)
|
||||
- Abstract concepts
|
||||
- Data comparisons
|
||||
- Processes, workflows
|
||||
|
||||
**Do NOT Illustrate**:
|
||||
- Metaphors literally
|
||||
- Decorative scenes
|
||||
- Generic illustrations
|
||||
|
||||
### 2.5 Plan Reference Image Usage (if analyzed in Step 1)
|
||||
|
||||
For each reference image (use the `vision_analyze` description from Step 1):
|
||||
|
||||
| Analysis | Description |
|
||||
|----------|-------------|
|
||||
| Visual characteristics | Style, colors, composition |
|
||||
| Content/subject | What the reference depicts |
|
||||
| Suitable positions | Which sections match this reference |
|
||||
| Style match | Which illustration types/styles align |
|
||||
| Usage recommendation | `direct` / `style` / `palette` |
|
||||
|
||||
| Usage | When to Use | How it's applied in Step 5.1 |
|
||||
|-------|-------------|------------------------------|
|
||||
| `direct` | Reference matches desired output closely | Paste the description (composition + subject + style + palette) into the prompt body |
|
||||
| `style` | Extract visual style characteristics only | Append style traits to prompt body |
|
||||
| `palette` | Extract color scheme only | Append extracted hex colors to prompt body |
|
||||
|
||||
Note: `image_generate` does not accept reference-image inputs under any usage type. Everything is mediated through the `vision_analyze` description.
|
||||
|
||||
---
|
||||
|
||||
## Step 3: Confirm Settings
|
||||
|
||||
Use the `clarify` tool. Since `clarify` handles one question at a time, ask the most important question first. Skip any question the user already answered in their request.
|
||||
|
||||
### Q1: Preset or Type (highest priority)
|
||||
|
||||
Based on Step 2 content analysis, recommend a preset first (sets both type & style). Look up [style-presets.md](style-presets.md) "Content Type → Preset Recommendations" table.
|
||||
|
||||
- [Recommended preset] — [brief: type + style + why]
|
||||
- [Alternative preset] — [brief]
|
||||
- Or choose type manually: infographic / scene / flowchart / comparison / framework / timeline / mixed
|
||||
|
||||
**If user picks a preset → skip Q3** (type & style both resolved).
|
||||
**If user picks a type → Q3 is required.**
|
||||
|
||||
### Q2: Density
|
||||
|
||||
- minimal (1-2) — Core concepts only
|
||||
- balanced (3-5) — Major sections
|
||||
- per-section — At least 1 per section/chapter (Recommended)
|
||||
- rich (6+) — Comprehensive coverage
|
||||
|
||||
### Q3: Style (skip if preset chosen in Q1)
|
||||
|
||||
Present Core Styles first:
|
||||
|
||||
- [Best compatible core style] (Recommended)
|
||||
- [Other compatible core style 1]
|
||||
- [Other compatible core style 2]
|
||||
- Other (see full Style Gallery)
|
||||
|
||||
**Core Styles** (simplified selection):
|
||||
|
||||
| Core Style | Maps To | Best For |
|
||||
|------------|---------|----------|
|
||||
| `minimal-flat` | notion | General, knowledge sharing, SaaS |
|
||||
| `sci-fi` | blueprint | AI, frontier tech, system design |
|
||||
| `hand-drawn` | sketch/warm | Relaxed, reflective, casual |
|
||||
| `editorial` | editorial | Processes, data, journalism |
|
||||
| `scene` | warm/watercolor | Narratives, emotional, lifestyle |
|
||||
| `poster` | screen-print | Opinion, editorial, cultural, cinematic |
|
||||
|
||||
Style selection based on Type × Style compatibility matrix ([styles.md](styles.md)).
|
||||
**In Step 5**, read `styles/<style>.md` for visual elements and rendering rules.
|
||||
|
||||
### Q4: Palette (optional)
|
||||
|
||||
If the preset did not specify a palette, offer:
|
||||
|
||||
- Default (use style's built-in colors) (Recommended)
|
||||
- `macaron` — soft pastel blocks on warm cream
|
||||
- `warm` — warm earth tones, no cool colors
|
||||
- `neon` — vibrant neon on dark backgrounds
|
||||
|
||||
**Skip if**: preset already resolved palette, or user specified a palette in the request.
|
||||
|
||||
See Palette Gallery in [styles.md](styles.md#palette-gallery) and full specs in `palettes/<palette>.md`.
|
||||
|
||||
### Q5: Image Text Language (only when ambiguous)
|
||||
|
||||
If the article language is different from the user's conversational language, ask which to use:
|
||||
- Article language (match article content) (Recommended)
|
||||
- User's conversational language
|
||||
|
||||
**Skip if**: languages match, or the user already specified in the request.
|
||||
|
||||
### Display Reference Usage (if references saved in Step 1)
|
||||
|
||||
When presenting the outline preview to the user, show reference assignments:
|
||||
|
||||
```
|
||||
Reference Images:
|
||||
| Ref | Filename | Recommended Usage |
|
||||
|-----|----------|-------------------|
|
||||
| 01 | 01-ref-diagram.png | direct → Illustration 1, 3 |
|
||||
| 02 | 02-ref-chart.png | palette → Illustration 2 |
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Step 4: Generate Outline
|
||||
|
||||
Save as `{output-dir}/outline.md` using `write_file`:
|
||||
|
||||
```yaml
|
||||
---
|
||||
type: infographic
|
||||
density: balanced
|
||||
style: blueprint
|
||||
image_count: 4
|
||||
references: # Only if references provided
|
||||
- ref_id: 01
|
||||
filename: 01-ref-diagram.png
|
||||
description: "Technical diagram showing system architecture"
|
||||
- ref_id: 02
|
||||
filename: 02-ref-chart.png
|
||||
description: "Color chart with brand palette"
|
||||
---
|
||||
|
||||
## Illustration 1
|
||||
|
||||
**Position**: [section] / [paragraph]
|
||||
**Purpose**: [why this helps]
|
||||
**Visual Content**: [what to show]
|
||||
**Type Application**: [how type applies]
|
||||
**References**: [01] # Optional: list ref_ids used
|
||||
**Reference Usage**: direct # direct | style | palette
|
||||
**Filename**: 01-infographic-concept-name.png
|
||||
|
||||
## Illustration 2
|
||||
...
|
||||
```
|
||||
|
||||
**Backup rule**: If `outline.md` exists, rename to `outline-backup-YYYYMMDD-HHMMSS.md` before writing.
|
||||
|
||||
**Requirements**:
|
||||
- Each position justified by content needs
|
||||
- Type applied consistently
|
||||
- Style reflected in descriptions
|
||||
- Count matches density
|
||||
- References assigned based on Step 2.5 analysis
|
||||
|
||||
---
|
||||
|
||||
## Step 5: Generate Prompts
|
||||
|
||||
**BLOCKING**: Every illustration must have a saved prompt file before any image is generated.
|
||||
|
||||
For each illustration in the outline:
|
||||
|
||||
1. **Create prompt file**: `{output-dir}/prompts/NN-{type}-{slug}.md` via `write_file`
|
||||
2. **Include YAML frontmatter**:
|
||||
```yaml
|
||||
---
|
||||
illustration_id: 01
|
||||
type: infographic
|
||||
style: custom-flat-vector
|
||||
---
|
||||
```
|
||||
3. **Load style specs**: Read `styles/<style>.md` (via `read_file`) for visual elements, style rules, and rendering instructions
|
||||
4. **Load palette specs** (if palette specified): Read `palettes/<palette>.md` for colors and background. Palette colors **replace** the style's default Color Palette. If no palette specified, use the style's built-in colors.
|
||||
5. **Follow type-specific template** from [prompt-construction.md](prompt-construction.md), using rendering from style + colors from palette (or style default)
|
||||
6. **Prompt quality requirements** (all REQUIRED):
|
||||
- `Layout`: Describe overall composition (grid / radial / hierarchical / left-right / top-down)
|
||||
- `ZONES`: Describe each visual area with specific content, not vague descriptions
|
||||
- `LABELS`: Use **actual numbers, terms, metrics, quotes from the article** — NOT generic placeholders
|
||||
- `COLORS`: Specify hex codes from palette (or style default) with semantic meaning
|
||||
- `STYLE`: Describe line treatment, texture, mood, character rendering per style rules
|
||||
- `ASPECT`: Specify ratio (e.g., `16:9`)
|
||||
7. **Apply defaults**: composition requirements, character rendering, text guidelines
|
||||
8. **Backup rule**: If a prompt file exists, rename to `prompts/NN-{type}-{slug}-backup-YYYYMMDD-HHMMSS.md`
|
||||
|
||||
**CRITICAL - References in Frontmatter**:
|
||||
- Only add `references` field if a sidecar `.md` description exists in `{output-dir}/references/`
|
||||
- If style/palette was extracted verbally (no description file), append info to prompt BODY only
|
||||
- Before writing frontmatter, confirm the sidecar exists (try `read_file` on the `.md`)
|
||||
|
||||
### 5.1 Process References (if analyzed in Step 1)
|
||||
|
||||
Read the `vision_analyze` description from the sidecar `references/NN-ref-{slug}.md` (via `read_file`) and embed it in the prompt body. `image_generate` never receives the binary.
|
||||
|
||||
| Usage | Action |
|
||||
|-------|--------|
|
||||
| `direct` | Paste the full reference description (composition, subject, style, palette) into the prompt body |
|
||||
| `style` | Append only the style traits: "Style: clean lines, gradient backgrounds..." |
|
||||
| `palette` | Append only the hex colors: "Colors: #E8756D coral, #7ECFC0 mint..." |
|
||||
|
||||
---
|
||||
|
||||
## Step 6: Generate Images
|
||||
|
||||
`image_generate` returns a JSON blob with a URL (`{"success": true, "image": "<url>"}`). It does NOT save a local file, does NOT accept an output path, and does NOT let the agent pick a backend/model. Treat the URL as a temporary artifact and download it explicitly.
|
||||
|
||||
For each prompt file:
|
||||
|
||||
1. Read the prompt file (via `read_file`) and extract the assembled prompt
|
||||
2. Map the prompt's `ASPECT` to `image_generate`'s enum: `16:9` → `landscape`, `9:16` → `portrait`, `1:1` → `square`. Custom ratios → nearest named aspect.
|
||||
3. Call `image_generate(prompt=<assembled>, aspect_ratio=<enum>)` and extract the `image` URL from the returned JSON.
|
||||
4. **Backup rule**: If `{output-dir}/NN-{type}-{slug}.png` already exists, rename it via `terminal` (`mv "{output-dir}/NN-{type}-{slug}.png" "{output-dir}/NN-{type}-{slug}-backup-YYYYMMDD-HHMMSS.png"`) before writing.
|
||||
5. Download the URL via `terminal`:
|
||||
```bash
|
||||
curl -sSL -o "{output-dir}/NN-{type}-{slug}.png" "{image_url}"
|
||||
```
|
||||
If `curl` is unavailable, fall back to `wget -qO "{output-dir}/NN-{type}-{slug}.png" "{image_url}"`.
|
||||
6. Verify the file exists and has non-zero size (`terminal`: `test -s "{path}" && echo ok`).
|
||||
7. On generation failure, retry `image_generate` once. On download failure, retry `curl` once with a longer timeout. Then log and continue.
|
||||
8. After each generation, report "Generated X/N".
|
||||
|
||||
---
|
||||
|
||||
## Step 7: Finalize
|
||||
|
||||
### 7.1 Update Article
|
||||
|
||||
Insert after the corresponding paragraph, using the path relative to the article file:
|
||||
|
||||
| Input | Insert Path |
|
||||
|-------|-------------|
|
||||
| Article file path (default `imgs-subdir`) | `` |
|
||||
| Article file path (images alongside) | `` |
|
||||
| Article file path (`illustrations/` subdirectory) | `` |
|
||||
| Pasted content | `` (relative to cwd) |
|
||||
|
||||
Alt text: concise description in the article's language.
|
||||
|
||||
### 7.2 Output Summary
|
||||
|
||||
```
|
||||
Article Illustration Complete!
|
||||
|
||||
Article: [path]
|
||||
Type: [type] | Density: [level] | Style: [style]
|
||||
Location: [directory]
|
||||
Images: X/N generated
|
||||
|
||||
Positions:
|
||||
- 01-xxx.png → After "[Section]"
|
||||
- 02-yyy.png → After "[Section]"
|
||||
|
||||
[If failures]
|
||||
Failed:
|
||||
- NN-zzz.png: [reason]
|
||||
```
|
||||
@@ -0,0 +1,77 @@
|
||||
# Port Notes — baoyu-comic
|
||||
|
||||
Ported from [JimLiu/baoyu-skills](https://github.com/JimLiu/baoyu-skills) v1.56.1.
|
||||
|
||||
## Changes from upstream
|
||||
|
||||
### SKILL.md adaptations
|
||||
|
||||
| Change | Upstream | Hermes |
|
||||
|--------|----------|--------|
|
||||
| Metadata namespace | `openclaw` | `hermes` (with `tags` + `homepage`) |
|
||||
| Trigger | Slash commands / CLI flags | Natural language skill matching |
|
||||
| User config | EXTEND.md file (project/user/XDG paths) | Removed — not part of Hermes infra |
|
||||
| User prompts | `AskUserQuestion` (batched) | `clarify` tool (one question at a time) |
|
||||
| Image generation | baoyu-imagine (Bun/TypeScript, supports `--ref`) | `image_generate` — **prompt-only**, returns a URL; no reference image input; agent must download the URL to the output directory |
|
||||
| PDF assembly | `scripts/merge-to-pdf.ts` (Bun + `pdf-lib`) | Removed — the PDF merge step is out of scope for this port; pages are delivered as PNGs only |
|
||||
| Platform support | Linux/macOS/Windows/WSL/PowerShell | Linux/macOS only |
|
||||
| File operations | Generic instructions | Hermes file tools (`write_file`, `read_file`) |
|
||||
|
||||
### Structural removals
|
||||
|
||||
- **`references/config/` directory** (removed entirely):
|
||||
- `first-time-setup.md` — blocking first-time setup flow for EXTEND.md
|
||||
- `preferences-schema.md` — EXTEND.md YAML schema
|
||||
- `watermark-guide.md` — watermark config (tied to EXTEND.md)
|
||||
- **`scripts/` directory** (removed entirely): upstream's `merge-to-pdf.ts` depended on `pdf-lib`, which is not declared anywhere in the Hermes repo. Rather than add a new dependency, the port drops PDF assembly and delivers per-page PNGs.
|
||||
- **Workflow Step 8 (Merge to PDF)** removed from `workflow.md`; Step 9 (Completion report) renumbered to Step 8.
|
||||
- **Workflow Step 1.1** — "Load Preferences (EXTEND.md)" section removed from `workflow.md`; steps 1.2/1.3 renumbered to 1.1/1.2.
|
||||
- **Generic "User Input Tools" and "Image Generation Tools" preambles** — SKILL.md no longer lists fallback rules for multiple possible tools; it references `clarify` and `image_generate` directly.
|
||||
|
||||
### Image generation strategy changes
|
||||
|
||||
`image_generate`'s schema accepts only `prompt` and `aspect_ratio` (`landscape` | `portrait` | `square`). Upstream's reference-image flow (`--ref characters.png` for character consistency, plus user-supplied refs for style/palette/scene) does not map to this tool, so the workflow was restructured:
|
||||
|
||||
- **Character sheet PNG** is still generated for multi-page comics, but it is repositioned as a **human-facing review artifact** (for visual verification) and a reference for later regenerations / manual prompt edits. Page prompts themselves are built from the **text descriptions** in `characters/characters.md` (embedded inline during Step 5). `image_generate` never sees the PNG as a visual input.
|
||||
- **User-supplied reference images** are reduced to `style` / `palette` / `scene` trait extraction — traits are embedded in the prompt body; the image files themselves are kept only for provenance under `refs/`.
|
||||
- **Page prompts** now mandate that character descriptions are embedded inline (copied from `characters/characters.md`) — this is the only mechanism left to enforce cross-page character consistency.
|
||||
- **Download step** — after every `image_generate` call, the returned URL is fetched to disk (e.g., `curl -fsSL "<url>" -o <target>.png`) and verified before the workflow advances.
|
||||
|
||||
### SKILL.md reductions
|
||||
|
||||
- CLI option columns (`--art`, `--tone`, `--layout`, `--aspect`, `--lang`, `--ref`, `--storyboard-only`, `--prompts-only`, `--images-only`, `--regenerate`) converted to plain-English option descriptions.
|
||||
- Preset files (`presets/*.md`) and `ohmsha-guide.md`: `` `--style X` `` / `` `--art X --tone Y` `` shorthand rewritten to `art=X, tone=Y` + natural-language references.
|
||||
- `partial-workflows.md`: per-skill slash command invocations rewritten as user-intent cues; PDF-related outputs removed.
|
||||
- `auto-selection.md`: priority order dropped the EXTEND.md tier.
|
||||
- `analysis-framework.md`: language-priority comment updated (user option → conversation → source).
|
||||
|
||||
### File naming convention
|
||||
|
||||
Source content pasted by the user is saved as `source-{slug}.md`, where `{slug}` is the kebab-case topic slug used for the output directory. Backups follow the same pattern with a `-backup-YYYYMMDD-HHMMSS` suffix. SKILL.md and `workflow.md` now agree on this single convention.
|
||||
|
||||
### What was preserved verbatim
|
||||
|
||||
- All 6 art-style definitions (`references/art-styles/`)
|
||||
- All 7 tone definitions (`references/tones/`)
|
||||
- All 7 layout definitions (`references/layouts/`)
|
||||
- Core templates: `character-template.md`, `storyboard-template.md`, `base-prompt.md`
|
||||
- Preset bodies (only the first few intro lines adapted; special rules unchanged)
|
||||
- Author, version, homepage attribution
|
||||
|
||||
## Syncing with upstream
|
||||
|
||||
To pull upstream updates:
|
||||
|
||||
```bash
|
||||
# Compare versions
|
||||
curl -sL https://raw.githubusercontent.com/JimLiu/baoyu-skills/main/skills/baoyu-comic/SKILL.md | head -5
|
||||
# Look for the version: line
|
||||
|
||||
# Diff a reference file
|
||||
diff <(curl -sL https://raw.githubusercontent.com/JimLiu/baoyu-skills/main/skills/baoyu-comic/references/art-styles/manga.md) \
|
||||
references/art-styles/manga.md
|
||||
```
|
||||
|
||||
Art-style, tone, and layout reference files can usually be overwritten directly (they're upstream-verbatim). `SKILL.md`, `references/workflow.md`, `references/partial-workflows.md`, `references/auto-selection.md`, `references/analysis-framework.md`, `references/ohmsha-guide.md`, and `references/presets/*.md` must be manually merged since they contain Hermes-specific adaptations.
|
||||
|
||||
If upstream adds a Hermes-compatible PDF merge step (no extra npm deps), restore `scripts/` and reintroduce Step 8 in `workflow.md`.
|
||||
@@ -0,0 +1,247 @@
|
||||
---
|
||||
name: baoyu-comic
|
||||
description: "Knowledge comics (知识漫画): educational, biography, tutorial."
|
||||
version: 1.56.1
|
||||
author: 宝玉 (JimLiu)
|
||||
license: MIT
|
||||
platforms: [linux, macos, windows]
|
||||
metadata:
|
||||
hermes:
|
||||
tags: [comic, knowledge-comic, creative, image-generation]
|
||||
homepage: https://github.com/JimLiu/baoyu-skills#baoyu-comic
|
||||
---
|
||||
|
||||
# Knowledge Comic Creator
|
||||
|
||||
Adapted from [baoyu-comic](https://github.com/JimLiu/baoyu-skills) for Hermes Agent's tool ecosystem.
|
||||
|
||||
Create original knowledge comics with flexible art style × tone combinations.
|
||||
|
||||
## When to Use
|
||||
|
||||
Trigger this skill when the user asks to create a knowledge/educational comic, biography comic, tutorial comic, or uses terms like "知识漫画", "教育漫画", or "Logicomix-style". The user provides content (text, file path, URL, or topic) and optionally specifies art style, tone, layout, aspect ratio, or language.
|
||||
|
||||
## Reference Images
|
||||
|
||||
Hermes' `image_generate` tool is **prompt-only** — it accepts a text prompt and an aspect ratio, and returns an image URL. It does **NOT** accept reference images. When the user supplies a reference image, use it to **extract traits in text** that get embedded in every page prompt:
|
||||
|
||||
**Intake**: Accept file paths when the user provides them (or pastes images in conversation).
|
||||
- File path(s) → copy to `refs/NN-ref-{slug}.{ext}` alongside the comic output for provenance
|
||||
- Pasted image with no path → ask the user for the path via `clarify`, or extract style traits verbally as a text fallback
|
||||
- No reference → skip this section
|
||||
|
||||
**Usage modes** (per reference):
|
||||
|
||||
| Usage | Effect |
|
||||
|-------|--------|
|
||||
| `style` | Extract style traits (line treatment, texture, mood) and append to every page's prompt body |
|
||||
| `palette` | Extract hex colors and append to every page's prompt body |
|
||||
| `scene` | Extract scene composition or subject notes and append to the relevant page(s) |
|
||||
|
||||
**Record in each page's prompt frontmatter** when refs exist:
|
||||
|
||||
```yaml
|
||||
references:
|
||||
- ref_id: 01
|
||||
filename: 01-ref-scene.png
|
||||
usage: style
|
||||
traits: "muted earth tones, soft-edged ink wash, low-contrast backgrounds"
|
||||
```
|
||||
|
||||
Character consistency is driven by **text descriptions** in `characters/characters.md` (written in Step 3) that get embedded inline in every page prompt (Step 5). The optional PNG character sheet generated in Step 7.1 is a human-facing review artifact, not an input to `image_generate`.
|
||||
|
||||
## Options
|
||||
|
||||
### Visual Dimensions
|
||||
|
||||
| Option | Values | Description |
|
||||
|--------|--------|-------------|
|
||||
| Art | ligne-claire (default), manga, realistic, ink-brush, chalk, minimalist | Art style / rendering technique |
|
||||
| Tone | neutral (default), warm, dramatic, romantic, energetic, vintage, action | Mood / atmosphere |
|
||||
| Layout | standard (default), cinematic, dense, splash, mixed, webtoon, four-panel | Panel arrangement |
|
||||
| Aspect | 3:4 (default, portrait), 4:3 (landscape), 16:9 (widescreen) | Page aspect ratio |
|
||||
| Language | auto (default), zh, en, ja, etc. | Output language |
|
||||
| Refs | File paths | Reference images used for style / palette trait extraction (not passed to the image model). See [Reference Images](#reference-images) above. |
|
||||
|
||||
### Partial Workflow Options
|
||||
|
||||
| Option | Description |
|
||||
|--------|-------------|
|
||||
| Storyboard only | Generate storyboard only, skip prompts and images |
|
||||
| Prompts only | Generate storyboard + prompts, skip images |
|
||||
| Images only | Generate images from existing prompts directory |
|
||||
| Regenerate N | Regenerate specific page(s) only (e.g., `3` or `2,5,8`) |
|
||||
|
||||
Details: [references/partial-workflows.md](references/partial-workflows.md)
|
||||
|
||||
### Art, Tone & Preset Catalogue
|
||||
|
||||
- **Art styles** (6): `ligne-claire`, `manga`, `realistic`, `ink-brush`, `chalk`, `minimalist`. Full definitions at `references/art-styles/<style>.md`.
|
||||
- **Tones** (7): `neutral`, `warm`, `dramatic`, `romantic`, `energetic`, `vintage`, `action`. Full definitions at `references/tones/<tone>.md`.
|
||||
- **Presets** (5) with special rules beyond plain art+tone:
|
||||
|
||||
| Preset | Equivalent | Hook |
|
||||
|--------|-----------|------|
|
||||
| `ohmsha` | manga + neutral | Visual metaphors, no talking heads, gadget reveals |
|
||||
| `wuxia` | ink-brush + action | Qi effects, combat visuals, atmospheric |
|
||||
| `shoujo` | manga + romantic | Decorative elements, eye details, romantic beats |
|
||||
| `concept-story` | manga + warm | Visual symbol system, growth arc, dialogue+action balance |
|
||||
| `four-panel` | minimalist + neutral + four-panel layout | 起承转合 structure, B&W + spot color, stick-figure characters |
|
||||
|
||||
Full rules at `references/presets/<preset>.md` — load the file when a preset is picked.
|
||||
|
||||
- **Compatibility matrix** and **content-signal → preset** table live in [references/auto-selection.md](references/auto-selection.md). Read it before recommending combinations in Step 2.
|
||||
|
||||
## File Structure
|
||||
|
||||
Output directory: `comic/{topic-slug}/`
|
||||
- Slug: 2-4 words kebab-case from topic (e.g., `alan-turing-bio`)
|
||||
- Conflict: append timestamp (e.g., `turing-story-20260118-143052`)
|
||||
|
||||
**Contents**:
|
||||
| File | Description |
|
||||
|------|-------------|
|
||||
| `source-{slug}.md` | Saved source content (kebab-case slug matches the output directory) |
|
||||
| `analysis.md` | Content analysis |
|
||||
| `storyboard.md` | Storyboard with panel breakdown |
|
||||
| `characters/characters.md` | Character definitions |
|
||||
| `characters/characters.png` | Character reference sheet (downloaded from `image_generate`) |
|
||||
| `prompts/NN-{cover\|page}-[slug].md` | Generation prompts |
|
||||
| `NN-{cover\|page}-[slug].png` | Generated images (downloaded from `image_generate`) |
|
||||
| `refs/NN-ref-{slug}.{ext}` | User-supplied reference images (optional, for provenance) |
|
||||
|
||||
## Language Handling
|
||||
|
||||
**Detection Priority**:
|
||||
1. User-specified language (explicit option)
|
||||
2. User's conversation language
|
||||
3. Source content language
|
||||
|
||||
**Rule**: Use user's input language for ALL interactions:
|
||||
- Storyboard outlines and scene descriptions
|
||||
- Image generation prompts
|
||||
- User selection options and confirmations
|
||||
- Progress updates, questions, errors, summaries
|
||||
|
||||
Technical terms remain in English.
|
||||
|
||||
## Workflow
|
||||
|
||||
### Progress Checklist
|
||||
|
||||
```
|
||||
Comic Progress:
|
||||
- [ ] Step 1: Setup & Analyze
|
||||
- [ ] 1.1 Analyze content
|
||||
- [ ] 1.2 Check existing directory
|
||||
- [ ] Step 2: Confirmation - Style & options ⚠️ REQUIRED
|
||||
- [ ] Step 3: Generate storyboard + characters
|
||||
- [ ] Step 4: Review outline (conditional)
|
||||
- [ ] Step 5: Generate prompts
|
||||
- [ ] Step 6: Review prompts (conditional)
|
||||
- [ ] Step 7: Generate images
|
||||
- [ ] 7.1 Generate character sheet (if needed) → characters/characters.png
|
||||
- [ ] 7.2 Generate pages (with character descriptions embedded in prompt)
|
||||
- [ ] Step 8: Completion report
|
||||
```
|
||||
|
||||
### Flow
|
||||
|
||||
```
|
||||
Input → Analyze → [Check Existing?] → [Confirm: Style + Reviews] → Storyboard → [Review?] → Prompts → [Review?] → Images → Complete
|
||||
```
|
||||
|
||||
### Step Summary
|
||||
|
||||
| Step | Action | Key Output |
|
||||
|------|--------|------------|
|
||||
| 1.1 | Analyze content | `analysis.md`, `source-{slug}.md` |
|
||||
| 1.2 | Check existing directory | Handle conflicts |
|
||||
| 2 | Confirm style, focus, audience, reviews | User preferences |
|
||||
| 3 | Generate storyboard + characters | `storyboard.md`, `characters/` |
|
||||
| 4 | Review outline (if requested) | User approval |
|
||||
| 5 | Generate prompts | `prompts/*.md` |
|
||||
| 6 | Review prompts (if requested) | User approval |
|
||||
| 7.1 | Generate character sheet (if needed) | `characters/characters.png` |
|
||||
| 7.2 | Generate pages | `*.png` files |
|
||||
| 8 | Completion report | Summary |
|
||||
|
||||
### User Questions
|
||||
|
||||
Use the `clarify` tool to confirm options. Since `clarify` handles one question at a time, ask the most important question first and proceed sequentially. See [references/workflow.md](references/workflow.md) for the full Step 2 question set.
|
||||
|
||||
**Timeout handling (CRITICAL)**: `clarify` can return `"The user did not provide a response within the time limit. Use your best judgement to make the choice and proceed."` — this is NOT user consent to default everything.
|
||||
|
||||
- Treat it as a default **for that one question only**. Continue asking the remaining Step 2 questions in sequence; each question is an independent consent point.
|
||||
- **Surface the default to the user visibly** in your next message so they have a chance to correct it: e.g. `"Style: defaulted to ohmsha preset (clarify timed out). Say the word to switch."` — an unreported default is indistinguishable from never having asked.
|
||||
- Do NOT collapse Step 2 into a single "use all defaults" pass after one timeout. If the user is genuinely absent, they will be equally absent for all five questions — but they can correct visible defaults when they return, and cannot correct invisible ones.
|
||||
|
||||
### Step 7: Image Generation
|
||||
|
||||
Use Hermes' built-in `image_generate` tool for all image rendering. Its schema accepts only `prompt` and `aspect_ratio` (`landscape` | `portrait` | `square`); it **returns a URL**, not a local file. Every generated page or character sheet must therefore be downloaded to the output directory.
|
||||
|
||||
**Prompt file requirement (hard)**: write each image's full, final prompt to a standalone file under `prompts/` (naming: `NN-{type}-[slug].md`) BEFORE calling `image_generate`. The prompt file is the reproducibility record.
|
||||
|
||||
**Aspect ratio mapping** — the storyboard's `aspect_ratio` field maps to `image_generate`'s format as follows:
|
||||
|
||||
| Storyboard ratio | `image_generate` format |
|
||||
|------------------|-------------------------|
|
||||
| `3:4`, `9:16`, `2:3` | `portrait` |
|
||||
| `4:3`, `16:9`, `3:2` | `landscape` |
|
||||
| `1:1` | `square` |
|
||||
|
||||
**Download step** — after every `image_generate` call:
|
||||
1. Read the URL from the tool result
|
||||
2. Fetch the image bytes using an **absolute** output path, e.g.
|
||||
`curl -fsSL "<url>" -o /abs/path/to/comic/<slug>/NN-page-<slug>.png`
|
||||
3. Verify the file exists and is non-empty at that exact path before proceeding to the next page
|
||||
|
||||
**Never rely on shell CWD persistence for `-o` paths.** The terminal tool's persistent-shell CWD can change between batches (session expiry, `TERMINAL_LIFETIME_SECONDS`, a failed `cd` that leaves you in the wrong directory). `curl -o relative/path.png` is a silent footgun: if CWD has drifted, the file lands somewhere else with no error. **Always pass a fully-qualified absolute path to `-o`**, or pass `workdir=<abs path>` to the terminal tool. Incident Apr 2026: pages 06-09 of a 10-page comic landed at the repo root instead of `comic/<slug>/` because batch 3 inherited a stale CWD from batch 2 and `curl -o 06-page-skills.png` wrote to the wrong directory. The agent then spent several turns claiming the files existed where they didn't.
|
||||
|
||||
**7.1 Character sheet** — generate it (to `characters/characters.png`, aspect `landscape`) when the comic is multi-page with recurring characters. Skip for simple presets (e.g., four-panel minimalist) or single-page comics. The prompt file at `characters/characters.md` must exist before invoking `image_generate`. The rendered PNG is a **human-facing review artifact** (so the user can visually verify character design) and a reference for later regenerations or manual prompt edits — it does **not** drive Step 7.2. Page prompts are already written in Step 5 from the **text descriptions** in `characters/characters.md`; `image_generate` cannot accept images as visual input.
|
||||
|
||||
**7.2 Pages** — each page's prompt MUST already be at `prompts/NN-{cover|page}-[slug].md` before invoking `image_generate`. Because `image_generate` is prompt-only, character consistency is enforced by **embedding character descriptions (sourced from `characters/characters.md`) inline in every page prompt during Step 5**. The embedding is done uniformly whether or not a PNG sheet is produced in 7.1; the PNG is only a review/regeneration aid.
|
||||
|
||||
**Backup rule**: existing `prompts/…md` and `…png` files → rename with `-backup-YYYYMMDD-HHMMSS` suffix before regenerating.
|
||||
|
||||
Full step-by-step workflow (analysis, storyboard, review gates, regeneration variants): [references/workflow.md](references/workflow.md).
|
||||
|
||||
## References
|
||||
|
||||
**Core Templates**:
|
||||
- [analysis-framework.md](references/analysis-framework.md) - Deep content analysis
|
||||
- [character-template.md](references/character-template.md) - Character definition format
|
||||
- [storyboard-template.md](references/storyboard-template.md) - Storyboard structure
|
||||
- [ohmsha-guide.md](references/ohmsha-guide.md) - Ohmsha manga specifics
|
||||
|
||||
**Style Definitions**:
|
||||
- `references/art-styles/` - Art styles (ligne-claire, manga, realistic, ink-brush, chalk, minimalist)
|
||||
- `references/tones/` - Tones (neutral, warm, dramatic, romantic, energetic, vintage, action)
|
||||
- `references/presets/` - Presets with special rules (ohmsha, wuxia, shoujo, concept-story, four-panel)
|
||||
- `references/layouts/` - Layouts (standard, cinematic, dense, splash, mixed, webtoon, four-panel)
|
||||
|
||||
**Workflow**:
|
||||
- [workflow.md](references/workflow.md) - Full workflow details
|
||||
- [auto-selection.md](references/auto-selection.md) - Content signal analysis
|
||||
- [partial-workflows.md](references/partial-workflows.md) - Partial workflow options
|
||||
|
||||
## Page Modification
|
||||
|
||||
| Action | Steps |
|
||||
|--------|-------|
|
||||
| **Edit** | **Update prompt file FIRST** → regenerate image → download new PNG |
|
||||
| **Add** | Create prompt at position → generate with character descriptions embedded → renumber subsequent → update storyboard |
|
||||
| **Delete** | Remove files → renumber subsequent → update storyboard |
|
||||
|
||||
**IMPORTANT**: When updating pages, ALWAYS update the prompt file (`prompts/NN-{cover|page}-[slug].md`) FIRST before regenerating. This ensures changes are documented and reproducible.
|
||||
|
||||
## Pitfalls
|
||||
|
||||
- Image generation: 10-30 seconds per page; auto-retry once on failure
|
||||
- **Always download** the URL returned by `image_generate` to a local PNG — downstream tooling (and the user's review) expects files in the output directory, not ephemeral URLs
|
||||
- **Use absolute paths for `curl -o`** — never rely on persistent-shell CWD across batches. Silent footgun: files land in the wrong directory and subsequent `ls` on the intended path shows nothing. See Step 7 "Download step".
|
||||
- Use stylized alternatives for sensitive public figures
|
||||
- **Step 2 confirmation required** - do not skip
|
||||
- **Steps 4/6 conditional** - only if user requested in Step 2
|
||||
- **Step 7.1 character sheet** - recommended for multi-page comics, optional for simple presets. The PNG is a review/regeneration aid; page prompts (written in Step 5) use the text descriptions in `characters/characters.md`, not the PNG. `image_generate` does not accept images as visual input
|
||||
- **Strip secrets** — scan source content for API keys, tokens, or credentials before writing any output file
|
||||
@@ -0,0 +1,176 @@
|
||||
# Comic Content Analysis Framework
|
||||
|
||||
Deep analysis framework for transforming source content into effective visual storytelling.
|
||||
|
||||
## Purpose
|
||||
|
||||
Before creating a comic, thoroughly analyze the source material to:
|
||||
- Identify the target audience and their needs
|
||||
- Determine what value the comic will deliver
|
||||
- Extract narrative potential for visual storytelling
|
||||
- Plan character arcs and key moments
|
||||
|
||||
## Analysis Dimensions
|
||||
|
||||
### 1. Core Content (Understanding "What")
|
||||
|
||||
**Central Message**
|
||||
- What is the single most important idea readers should take away?
|
||||
- Can you express it in one sentence?
|
||||
|
||||
**Key Concepts**
|
||||
- What are the essential concepts readers must understand?
|
||||
- How should these concepts be visualized?
|
||||
- Which concepts need simplified explanations?
|
||||
|
||||
**Content Structure**
|
||||
- How is the source material organized?
|
||||
- What is the natural narrative arc?
|
||||
- Where are the climax and turning points?
|
||||
|
||||
**Evidence & Examples**
|
||||
- What concrete examples, data, or stories support the main ideas?
|
||||
- Which examples translate well to visual panels?
|
||||
- What can be shown rather than told?
|
||||
|
||||
### 2. Context & Background (Understanding "Why")
|
||||
|
||||
**Source Origin**
|
||||
- Who created this content? What is their perspective?
|
||||
- What was the original purpose?
|
||||
- Is there bias to be aware of?
|
||||
|
||||
**Historical/Cultural Context**
|
||||
- When and where does the story take place?
|
||||
- What background knowledge do readers need?
|
||||
- What period-specific visual elements are required?
|
||||
|
||||
**Underlying Assumptions**
|
||||
- What does the source assume readers already know?
|
||||
- What implicit beliefs or values are present?
|
||||
- Should the comic challenge or reinforce these?
|
||||
|
||||
### 3. Audience Analysis
|
||||
|
||||
**Primary Audience**
|
||||
- Who will read this comic?
|
||||
- What is their existing knowledge level?
|
||||
- What are their interests and motivations?
|
||||
|
||||
**Secondary Audiences**
|
||||
- Who else might benefit from this comic?
|
||||
- How might their needs differ?
|
||||
|
||||
**Reader Questions**
|
||||
- What questions will readers have?
|
||||
- What misconceptions might they bring?
|
||||
- What "aha moments" can we create?
|
||||
|
||||
### 4. Value Proposition
|
||||
|
||||
**Knowledge Value**
|
||||
- What will readers learn?
|
||||
- What new perspectives will they gain?
|
||||
- How will this change their understanding?
|
||||
|
||||
**Emotional Value**
|
||||
- What emotions should readers feel?
|
||||
- What connections will they make with characters?
|
||||
- What will make this memorable?
|
||||
|
||||
**Practical Value**
|
||||
- Can readers apply what they learn?
|
||||
- What actions might this inspire?
|
||||
- What conversations might it spark?
|
||||
|
||||
### 5. Narrative Potential
|
||||
|
||||
**Story Arc Candidates**
|
||||
- What natural narratives exist in the content?
|
||||
- Where is the conflict or tension?
|
||||
- What transformations occur?
|
||||
|
||||
**Character Potential**
|
||||
- Who are the key figures?
|
||||
- What are their motivations and obstacles?
|
||||
- How do they change throughout?
|
||||
|
||||
**Visual Opportunities**
|
||||
- What scenes have strong visual potential?
|
||||
- Where can abstract concepts become concrete images?
|
||||
- What metaphors can be visualized?
|
||||
|
||||
**Dramatic Moments**
|
||||
- What are the breakthrough/revelation moments?
|
||||
- Where are the emotional peaks?
|
||||
- What creates tension and release?
|
||||
|
||||
### 6. Adaptation Considerations
|
||||
|
||||
**What to Keep**
|
||||
- Essential facts and ideas
|
||||
- Key quotes or moments
|
||||
- Core emotional beats
|
||||
|
||||
**What to Simplify**
|
||||
- Complex explanations
|
||||
- Dense technical details
|
||||
- Lengthy descriptions
|
||||
|
||||
**What to Expand**
|
||||
- Brief mentions that deserve more attention
|
||||
- Implied emotions or relationships
|
||||
- Visual details not in source
|
||||
|
||||
**What to Omit**
|
||||
- Tangential information
|
||||
- Redundant examples
|
||||
- Content that doesn't serve the narrative
|
||||
|
||||
## Output Format
|
||||
|
||||
Analysis results should be saved to `analysis.md` with:
|
||||
|
||||
1. **YAML Front Matter**: Metadata (title, topic, time_span, source_language, user_language, aspect_ratio, recommended_page_count, recommended_art, recommended_tone, recommended_layout)
|
||||
2. **Target Audience**: Primary, secondary, tertiary audiences with their needs
|
||||
3. **Value Proposition**: What readers will gain (knowledge, emotional, practical)
|
||||
4. **Core Themes**: Table with theme, narrative potential, visual opportunity
|
||||
5. **Key Figures & Story Arcs**: Character profiles with arcs, visual identity, key moments
|
||||
6. **Content Signals**: Style and layout recommendations based on content type
|
||||
7. **Recommended Approaches**: Narrative approaches ranked by suitability
|
||||
|
||||
### YAML Front Matter Example
|
||||
|
||||
```yaml
|
||||
---
|
||||
title: "Alan Turing: The Father of Computing"
|
||||
topic: alan-turing-biography
|
||||
time_span: 1912-1954
|
||||
source_language: en
|
||||
user_language: zh # User-specified or detected from conversation
|
||||
aspect_ratio: "3:4"
|
||||
recommended_page_count: 16
|
||||
recommended_art: ligne-claire # ligne-claire|manga|realistic|ink-brush|chalk
|
||||
recommended_tone: neutral # neutral|warm|dramatic|romantic|energetic|vintage|action
|
||||
recommended_layout: mixed # standard|cinematic|dense|splash|mixed|webtoon
|
||||
---
|
||||
```
|
||||
|
||||
### Language Fields
|
||||
|
||||
| Field | Description |
|
||||
|-------|-------------|
|
||||
| `source_language` | Detected language of source content |
|
||||
| `user_language` | Output language for comic (user-specified option > conversation language > source_language) |
|
||||
|
||||
## Analysis Checklist
|
||||
|
||||
Before proceeding to storyboard:
|
||||
|
||||
- [ ] Can I state the core message in one sentence?
|
||||
- [ ] Do I know exactly who will read this comic?
|
||||
- [ ] Have I identified at least 3 ways this comic provides value?
|
||||
- [ ] Are there clear protagonists with compelling arcs?
|
||||
- [ ] Have I found at least 5 visually powerful moments?
|
||||
- [ ] Do I understand what to keep, simplify, expand, and omit?
|
||||
- [ ] Have I identified the emotional peaks and valleys?
|
||||
@@ -0,0 +1,101 @@
|
||||
# chalk
|
||||
|
||||
粉笔画风 - Chalkboard aesthetic with hand-drawn warmth
|
||||
|
||||
## Overview
|
||||
|
||||
Classic classroom chalkboard aesthetic with hand-drawn chalk illustrations. Nostalgic educational feel with imperfect, sketchy lines that capture the warmth of traditional teaching.
|
||||
|
||||
## Line Work
|
||||
|
||||
- Sketchy, imperfect hand-drawn lines
|
||||
- Chalk texture on all strokes
|
||||
- Varying line weight from chalk pressure
|
||||
- Soft edges, no sharp digital lines
|
||||
- Visible chalk dust effects
|
||||
|
||||
## Character Design
|
||||
|
||||
- Simplified, friendly character designs
|
||||
- Stick figures to semi-detailed range
|
||||
- Expressive through simple gestures
|
||||
- Approachable, non-intimidating
|
||||
- Educational presenter style
|
||||
|
||||
## Background
|
||||
|
||||
- Chalkboard Black (#1A1A1A) or Dark Green-Black (#1C2B1C)
|
||||
- Realistic chalkboard texture
|
||||
- Subtle scratches and dust particles
|
||||
- Faint eraser marks for authenticity
|
||||
- Wooden frame border optional
|
||||
|
||||
## Typography
|
||||
|
||||
- Hand-drawn chalk lettering style
|
||||
- Visible chalk texture on text
|
||||
- Imperfect baseline adds authenticity
|
||||
- White or bright colored chalk for emphasis
|
||||
|
||||
## Visual Elements
|
||||
|
||||
- Hand-drawn chalk illustrations
|
||||
- Chalk dust effects around elements
|
||||
- Doodles: stars, arrows, underlines, circles
|
||||
- Mathematical formulas and diagrams
|
||||
- Eraser smudges and chalk residue
|
||||
- Stick figures and simple icons
|
||||
- Connection lines with hand-drawn feel
|
||||
|
||||
## Default Color Palette
|
||||
|
||||
| Role | Color | Hex |
|
||||
|------|-------|-----|
|
||||
| Background | Chalkboard Black | #1A1A1A |
|
||||
| Alt Background | Green-Black | #1C2B1C |
|
||||
| Primary Text | Chalk White | #F5F5F5 |
|
||||
| Accent 1 | Chalk Yellow | #FFE566 |
|
||||
| Accent 2 | Chalk Pink | #FF9999 |
|
||||
| Accent 3 | Chalk Blue | #66B3FF |
|
||||
| Accent 4 | Chalk Green | #90EE90 |
|
||||
| Accent 5 | Chalk Orange | #FFB366 |
|
||||
|
||||
## Style Rules
|
||||
|
||||
### Do
|
||||
- Maintain authentic chalk texture on all elements
|
||||
- Use imperfect, hand-drawn quality throughout
|
||||
- Add subtle chalk dust and smudge effects
|
||||
- Create visual hierarchy with color variety
|
||||
- Include playful doodles and annotations
|
||||
|
||||
### Don't
|
||||
- Use perfect geometric shapes
|
||||
- Create clean digital-looking lines
|
||||
- Add photorealistic elements
|
||||
- Use gradients or glossy effects
|
||||
|
||||
## Quality Markers
|
||||
|
||||
- ✓ Authentic chalk texture throughout
|
||||
- ✓ Imperfect, hand-drawn quality
|
||||
- ✓ Readable despite sketchy style
|
||||
- ✓ Nostalgic classroom feel
|
||||
- ✓ Effective color hierarchy
|
||||
- ✓ Playful educational aesthetic
|
||||
|
||||
## Compatibility
|
||||
|
||||
| Tone | Fit | Notes |
|
||||
|------|-----|-------|
|
||||
| neutral | ✓✓ | Classic educational |
|
||||
| warm | ✓✓ | Nostalgic feel |
|
||||
| dramatic | ✗ | Style mismatch |
|
||||
| vintage | ✓ | Old school feel |
|
||||
| romantic | ✗ | Style mismatch |
|
||||
| energetic | ✓✓ | Fun learning |
|
||||
| action | ✗ | Style mismatch |
|
||||
|
||||
## Best For
|
||||
|
||||
Educational content, tutorials, classroom themes, teaching materials, workshops, informal learning, knowledge sharing
|
||||
@@ -0,0 +1,97 @@
|
||||
# ink-brush
|
||||
|
||||
水墨画风 - Chinese ink brush aesthetics with dynamic strokes
|
||||
|
||||
## Overview
|
||||
|
||||
Traditional Chinese ink brush painting style adapted for comics. Combines calligraphic brush strokes with ink wash effects. Creates atmospheric, artistic visuals rooted in East Asian aesthetics.
|
||||
|
||||
## Line Work
|
||||
|
||||
- 2-3px dynamic brush strokes with varying weight
|
||||
- Ink wash effects, traditional Chinese brush feel
|
||||
- Bold, confident strokes with sharp edges
|
||||
- Flowing lines for fabric and hair
|
||||
- Pressure-sensitive stroke variation
|
||||
|
||||
## Character Design
|
||||
|
||||
- Realistic human proportions (7.5-8 head heights)
|
||||
- Defined features with ink brush definition
|
||||
- Dynamic poses capturing movement
|
||||
- Flowing hair and clothing in motion
|
||||
- Traditional attire options (robes, hanfu)
|
||||
- Intense, expressive faces
|
||||
|
||||
## Brush Techniques
|
||||
|
||||
| Technique | Usage |
|
||||
|-----------|-------|
|
||||
| Bold strokes | Character outlines |
|
||||
| Fine lines | Details, hair |
|
||||
| Ink wash | Atmosphere, shadows |
|
||||
| Dry brush | Texture, aging |
|
||||
| Splatter | Impact, drama |
|
||||
|
||||
## Background Treatment
|
||||
|
||||
- Dramatic landscapes: mountains, waterfalls, temples
|
||||
- Ink wash atmospheric effects
|
||||
- Misty, layered depth
|
||||
- Traditional architecture elements
|
||||
- High contrast silhouettes
|
||||
- Negative space as design element
|
||||
|
||||
## Color Approach
|
||||
|
||||
- Ink gradients as primary
|
||||
- Limited accent colors
|
||||
- Traditional Chinese palette
|
||||
- Atmospheric color washes
|
||||
- High contrast compositions
|
||||
|
||||
## Default Color Palette
|
||||
|
||||
| Role | Color | Hex |
|
||||
|------|-------|-----|
|
||||
| Primary | Deep black ink | #1A1A1A |
|
||||
| Accent | Crimson red | #8B0000 |
|
||||
| Accent | Imperial gold | #D4AF37 |
|
||||
| Skin | Natural tan | #D4A574 |
|
||||
| Background | Misty gray | #9CA3AF |
|
||||
| Background | Earth tone | #8B7355 |
|
||||
| Wash | Ink gradient | #2D3748 |
|
||||
|
||||
## Visual Elements
|
||||
|
||||
- Calligraphic text integration
|
||||
- Seal stamps (optional)
|
||||
- Ink splatter effects
|
||||
- Flowing fabric trails
|
||||
- Atmospheric mist
|
||||
- Mountain silhouettes
|
||||
|
||||
## Quality Markers
|
||||
|
||||
- ✓ Dynamic brush stroke quality
|
||||
- ✓ Authentic ink wash atmosphere
|
||||
- ✓ High contrast compositions
|
||||
- ✓ Flowing movement in fabric/hair
|
||||
- ✓ Traditional aesthetic elements
|
||||
- ✓ Atmospheric depth
|
||||
|
||||
## Compatibility
|
||||
|
||||
| Tone | Fit | Notes |
|
||||
|------|-----|-------|
|
||||
| neutral | ✓ | Contemplative stories |
|
||||
| warm | ✓ | Nostalgic, gentle |
|
||||
| dramatic | ✓✓ | High contrast |
|
||||
| vintage | ✓✓ | Historical pieces |
|
||||
| romantic | ✗ | Style mismatch |
|
||||
| energetic | ✗ | Too refined |
|
||||
| action | ✓✓ | Martial arts |
|
||||
|
||||
## Best For
|
||||
|
||||
Chinese historical stories, martial arts, traditional tales, contemplative narratives, artistic adaptations
|
||||
@@ -0,0 +1,75 @@
|
||||
# ligne-claire
|
||||
|
||||
清线画风 - Uniform lines, flat colors, European comic tradition
|
||||
|
||||
## Overview
|
||||
|
||||
Classic European comic style originating from Hergé's Tintin. Characterized by clean, uniform outlines and flat color fills without gradients. Creates a timeless, accessible aesthetic suitable for educational and narrative content.
|
||||
|
||||
## Line Work
|
||||
|
||||
- Uniform, clean outlines with consistent weight (2px)
|
||||
- No hatching or cross-hatching for shading
|
||||
- Sharp, precise edges on all elements
|
||||
- Black ink outlines on all figures and objects
|
||||
- Shadows indicated through flat color areas, not line techniques
|
||||
|
||||
## Character Design
|
||||
|
||||
- Slightly stylized/cartoonish characters with realistic proportions
|
||||
- Distinctive, recognizable facial features
|
||||
- Expressive faces with clear emotions
|
||||
- Period-appropriate clothing with attention to detail
|
||||
- Consistent character appearance across panels
|
||||
- 6-7 head height proportions
|
||||
|
||||
## Background Treatment
|
||||
|
||||
- Detailed, realistic backgrounds with architectural accuracy
|
||||
- Period-specific props and technology
|
||||
- Clear spatial depth and perspective
|
||||
- Environmental storytelling through details
|
||||
- Contrast between simplified characters and detailed backgrounds
|
||||
|
||||
## Color Approach
|
||||
|
||||
- Flat colors without gradients (true to Ligne Claire tradition)
|
||||
- Limited palette per page for cohesion
|
||||
- Colors support narrative mood
|
||||
- Consistent lighting logic within scenes
|
||||
|
||||
## Default Color Palette
|
||||
|
||||
| Role | Color | Hex |
|
||||
|------|-------|-----|
|
||||
| Primary Blue | Clean blue | #3182CE |
|
||||
| Primary Red | Classic red | #E53E3E |
|
||||
| Primary Yellow | Warm yellow | #ECC94B |
|
||||
| Skin | Warm tan | #F7CFAE |
|
||||
| Background Light | Light cream | #FFFAF0 |
|
||||
| Background Sky | Sky blue | #BEE3F8 |
|
||||
|
||||
## Quality Markers
|
||||
|
||||
- ✓ Clean, uniform line weight throughout
|
||||
- ✓ Flat colors without gradients
|
||||
- ✓ Detailed backgrounds, stylized characters
|
||||
- ✓ Clear panel borders and reading flow
|
||||
- ✓ Hand-drawn text style
|
||||
- ✓ Proper perspective in environments
|
||||
|
||||
## Compatibility
|
||||
|
||||
| Tone | Fit | Notes |
|
||||
|------|-----|-------|
|
||||
| neutral | ✓✓ | Classic combination |
|
||||
| warm | ✓✓ | Nostalgic stories |
|
||||
| dramatic | ✓ | Works with high contrast |
|
||||
| vintage | ✓ | Period pieces |
|
||||
| romantic | ✗ | Style mismatch |
|
||||
| energetic | ✓ | Lighter stories |
|
||||
| action | ✗ | Lacks dynamic lines |
|
||||
|
||||
## Best For
|
||||
|
||||
Educational content, balanced narratives, biography comics, historical stories
|
||||
@@ -0,0 +1,93 @@
|
||||
# manga
|
||||
|
||||
日漫画风 - Anime/manga aesthetics with expressive characters
|
||||
|
||||
## Overview
|
||||
|
||||
Japanese manga art style characterized by large expressive eyes, dynamic poses, and visual emotion indicators. Versatile style that works across genres from educational to romantic to action.
|
||||
|
||||
## Line Work
|
||||
|
||||
- Clean, smooth lines (1.5-2px)
|
||||
- Expressive weight variation for emphasis
|
||||
- Smooth curves, dynamic strokes
|
||||
- Speed lines and motion effects available
|
||||
- Screen tone effects for atmosphere
|
||||
|
||||
## Character Design
|
||||
|
||||
- Anime/manga proportions: larger eyes, expressive faces
|
||||
- 5-7 head height proportions (varies by sub-style)
|
||||
- Clear emotional indicators (！, ？, sweat drops, sparkles)
|
||||
- Dynamic poses and gestures
|
||||
- Detailed hair with individual strands
|
||||
- Fashionable clothing with natural folds
|
||||
|
||||
## Eye Styles
|
||||
|
||||
| Type | Description |
|
||||
|------|-------------|
|
||||
| Standard | Medium-large, 2-3 highlights |
|
||||
| Educational | Friendly, approachable eyes |
|
||||
| Dramatic | Intense, detailed irises |
|
||||
| Cute | Very large, sparkly eyes |
|
||||
|
||||
## Background Treatment
|
||||
|
||||
- Simplified during dialogue/explanation
|
||||
- Detailed for establishing shots
|
||||
- Screen tone gradients for mood
|
||||
- Abstract backgrounds for emotional moments
|
||||
- Technical diagrams styled as displays
|
||||
|
||||
## Color Approach
|
||||
|
||||
- Clean, bright anime colors
|
||||
- Soft gradients on skin
|
||||
- Vibrant palette options
|
||||
- Light and shadow with soft transitions
|
||||
- Color coding for character identification
|
||||
|
||||
## Default Color Palette
|
||||
|
||||
| Role | Color | Hex |
|
||||
|------|-------|-----|
|
||||
| Primary Blue | Bright blue | #4299E1 |
|
||||
| Primary Orange | Warm orange | #ED8936 |
|
||||
| Primary Green | Soft green | #68D391 |
|
||||
| Skin | Anime warm | #FEEBC8 |
|
||||
| Background | Clean white | #FFFFFF |
|
||||
| Highlight | Golden | #FFD700 |
|
||||
|
||||
## Visual Elements
|
||||
|
||||
- Speech bubbles: rounded (normal), spiky (excitement)
|
||||
- Sound effects integrated visually
|
||||
- Emotion symbols (sweat drops, anger marks, hearts)
|
||||
- Speed lines and motion blur
|
||||
- Sparkle and glow effects
|
||||
|
||||
## Quality Markers
|
||||
|
||||
- ✓ Expressive character faces
|
||||
- ✓ Clean, consistent line work
|
||||
- ✓ Dynamic poses and compositions
|
||||
- ✓ Appropriate use of manga conventions
|
||||
- ✓ Readable panel flow
|
||||
- ✓ Consistent character designs
|
||||
|
||||
## Compatibility
|
||||
|
||||
| Tone | Fit | Notes |
|
||||
|------|-----|-------|
|
||||
| neutral | ✓✓ | Educational manga |
|
||||
| warm | ✓ | Slice of life |
|
||||
| dramatic | ✓ | Intense moments |
|
||||
| romantic | ✓✓ | Shoujo style |
|
||||
| energetic | ✓✓ | Shonen style |
|
||||
| vintage | ✗ | Style mismatch |
|
||||
| action | ✓✓ | Battle manga |
|
||||
|
||||
## Best For
|
||||
|
||||
Educational tutorials, romance, action, coming-of-age, technical explanations, youth-oriented content
|
||||
@@ -0,0 +1,84 @@
|
||||
# minimalist
|
||||
|
||||
极简画风 - Clean black line art, limited spot color, simplified stick-figure characters
|
||||
|
||||
## Overview
|
||||
|
||||
Minimalist cartoon illustration characterized by clean black line art on white background with very limited spot color for emphasis. Characters are simplified to near-stick-figure abstraction, focusing on gesture and concept rather than anatomical detail. Designed for business allegory, quick-read educational content, and concept illustration.
|
||||
|
||||
## Line Work
|
||||
|
||||
- Clean, uniform black lines (1.5-2px)
|
||||
- No hatching, cross-hatching, or shading techniques
|
||||
- Minimal detail — every line serves a purpose
|
||||
- Bold outlines for characters, thinner lines for props/labels
|
||||
- No decorative flourishes or ornamental lines
|
||||
|
||||
## Character Design
|
||||
|
||||
- Highly simplified, stick-figure-like business characters
|
||||
- Circle or oval heads with minimal facial features (dot eyes, simple line mouth)
|
||||
- Body as simple geometric shapes or line constructions
|
||||
- Distinguishing features through props only (tie, hat, briefcase, glasses)
|
||||
- No anatomical detail — expressive through posture and gesture
|
||||
- 4-5 head height proportions (squat, iconic)
|
||||
|
||||
## Background Treatment
|
||||
|
||||
- Mostly blank/white — negative space is a design element
|
||||
- Minimal environmental cues (a line for ground, simple desk outline)
|
||||
- Concept labels and text annotations replace detailed environments
|
||||
- Icons and symbols over realistic rendering
|
||||
- No perspective or spatial depth
|
||||
|
||||
## Color Approach
|
||||
|
||||
- Primarily black and white (90%+ of the image)
|
||||
- 1-2 spot accent colors for emphasis on key concepts
|
||||
- Accent color used sparingly: highlighting key objects, text labels, concept indicators
|
||||
- No gradients, no shading, no color fills on backgrounds
|
||||
- Color draws the eye to the most important element in each panel
|
||||
|
||||
## Default Color Palette
|
||||
|
||||
| Role | Color | Hex |
|
||||
|------|-------|-----|
|
||||
| Primary | Black ink | `#1A1A1A` |
|
||||
| Background | Clean white | `#FFFFFF` |
|
||||
| Accent 1 | Spot orange | `#FF6B35` |
|
||||
| Accent 2 | Spot blue (optional) | `#3182CE` |
|
||||
| Text labels | Dark gray | `#4A4A4A` |
|
||||
| Panel border | Medium gray | `#666666` |
|
||||
|
||||
## Visual Elements
|
||||
|
||||
- Text labels with accent-color backgrounds or underlines for key terms
|
||||
- Simple icons: arrows, circles, checkmarks, crosses
|
||||
- Concept highlight boxes with spot color
|
||||
- Minimal speech bubbles (simple oval or rectangle, thin black outline)
|
||||
- No sound effects, no motion lines, no screen tones
|
||||
|
||||
## Quality Markers
|
||||
|
||||
- ✓ Clean, purposeful line work with no unnecessary detail
|
||||
- ✓ 90%+ black-and-white with strategic spot color
|
||||
- ✓ Simplified characters readable at small sizes
|
||||
- ✓ Text labels integrated naturally into panels
|
||||
- ✓ Strong negative space usage
|
||||
- ✓ Every element serves the narrative point
|
||||
|
||||
## Compatibility
|
||||
|
||||
| Tone | Fit | Notes |
|
||||
|------|-----|-------|
|
||||
| neutral | ✓✓ | Ideal for business/educational content |
|
||||
| warm | ✓ | Works for gentle stories, slight warmth in accent |
|
||||
| energetic | ✓ | Works for punchy, high-energy content |
|
||||
| dramatic | ✗ | Style too stripped down for dramatic intensity |
|
||||
| vintage | ✗ | Minimalist aesthetic conflicts with aged/textured look |
|
||||
| romantic | ✗ | No capacity for decorative/soft elements |
|
||||
| action | ✗ | No dynamic line capability for speed/impact |
|
||||
|
||||
## Best For
|
||||
|
||||
Business allegory, management fables, short concept illustration, four-panel comic strips, quick-insight education, social media content
|
||||
@@ -0,0 +1,89 @@
|
||||
# realistic
|
||||
|
||||
写实画风 - Digital painting with realistic proportions and lighting
|
||||
|
||||
## Overview
|
||||
|
||||
Full-color realistic manga style using digital painting techniques. Features anatomically accurate characters, rich gradients, and detailed environmental rendering. Sophisticated aesthetic for mature audiences.
|
||||
|
||||
## Line Work
|
||||
|
||||
- Clean, precise outlines with clear contours
|
||||
- Uniform line weight for character definition
|
||||
- No excessive hatching - rely on color for depth
|
||||
- Smooth curves and realistic anatomical lines
|
||||
- Ligne Claire influence: clean but not simplified
|
||||
|
||||
## Character Design
|
||||
|
||||
- Realistic human proportions (7-8 head heights)
|
||||
- Anatomically accurate features and expressions
|
||||
- Detailed facial structure without exaggeration
|
||||
- Natural poses and body language
|
||||
- Consistent appearance across panels
|
||||
- Subtle expressions rather than manga-style
|
||||
|
||||
## Rendering Style
|
||||
|
||||
- Full-color digital painting with rich gradients
|
||||
- Soft shadow transitions on skin and fabric
|
||||
- Realistic material textures (glass, liquid, fabric, wood)
|
||||
- Detailed hair with natural shine and volume
|
||||
- Environmental lighting affects all elements
|
||||
- NOT flat cel-shading - smooth color blending
|
||||
|
||||
## Background Treatment
|
||||
|
||||
- Highly detailed, realistic environments
|
||||
- Accurate perspective and spatial depth
|
||||
- Atmospheric lighting (warm indoor, cool outdoor)
|
||||
- Professional settings rendered with precision
|
||||
- Props and objects with realistic textures
|
||||
|
||||
## Color Approach
|
||||
|
||||
- Rich gradients for depth and volume
|
||||
- Realistic lighting with warm/cool contrast
|
||||
- Material-specific rendering
|
||||
- Subtle color temperature shifts
|
||||
- Professional, sophisticated palette
|
||||
|
||||
## Default Color Palette
|
||||
|
||||
| Role | Color | Hex |
|
||||
|------|-------|-----|
|
||||
| Skin Light | Natural warm | #F5D6C6 |
|
||||
| Skin Shadow | Warm shadow | #E8C4B0 |
|
||||
| Environment | Warm wood | #8B7355 |
|
||||
| Environment Cool | Cool stone | #9CA3AF |
|
||||
| Accent | Wine red | #722F37 |
|
||||
| Accent Gold | Gold | #D4AF37 |
|
||||
| Light Warm | Amber | #FFB347 |
|
||||
| Light Cool | Cool blue | #B0C4DE |
|
||||
|
||||
## Quality Markers
|
||||
|
||||
- ✓ Anatomically accurate proportions
|
||||
- ✓ Smooth color gradients (not flat fills)
|
||||
- ✓ Realistic material textures
|
||||
- ✓ Detailed, atmospheric backgrounds
|
||||
- ✓ Natural lighting with soft shadows
|
||||
- ✓ Expressive but subtle expressions
|
||||
- ✓ Professional aesthetic
|
||||
- ✓ Clean speech bubbles
|
||||
|
||||
## Compatibility
|
||||
|
||||
| Tone | Fit | Notes |
|
||||
|------|-----|-------|
|
||||
| neutral | ✓✓ | Professional content |
|
||||
| warm | ✓✓ | Nostalgic stories |
|
||||
| dramatic | ✓✓ | High drama |
|
||||
| vintage | ✓✓ | Period pieces |
|
||||
| romantic | ✗ | Style mismatch |
|
||||
| energetic | ✗ | Too refined |
|
||||
| action | ✓ | Serious action |
|
||||
|
||||
## Best For
|
||||
|
||||
Professional topics (wine, food, business), lifestyle content, adult narratives, documentary-style, mature educational guides
|
||||
@@ -0,0 +1,71 @@
|
||||
# Auto Selection
|
||||
|
||||
Content signals determine default art + tone + layout (or preset).
|
||||
|
||||
## Content Signal Matrix
|
||||
|
||||
| Content Signals | Art Style | Tone | Layout | Preset |
|
||||
|-----------------|-----------|------|--------|--------|
|
||||
| Tutorial, how-to, beginner | manga | neutral | webtoon | **ohmsha** |
|
||||
| Computing, AI, programming | manga | neutral | dense | **ohmsha** |
|
||||
| Technical explanation, educational | manga | neutral | webtoon | **ohmsha** |
|
||||
| Pre-1950, classical, ancient | realistic | vintage | cinematic | - |
|
||||
| Personal story, mentor | ligne-claire | warm | standard | - |
|
||||
| Psychology, motivation, self-help, coaching | manga | warm | standard | **concept-story** |
|
||||
| Business narrative, management, leadership | manga | warm | standard | **concept-story** |
|
||||
| Conflict, breakthrough | (inherit) | dramatic | splash | - |
|
||||
| Wine, food, lifestyle | realistic | neutral | cinematic | - |
|
||||
| Martial arts, wuxia, xianxia | ink-brush | action | splash | **wuxia** |
|
||||
| Romance, love, school life | manga | romantic | standard | **shoujo** |
|
||||
| Business allegory, fable, parable, short insight, 四格 | minimalist | neutral | four-panel | **four-panel** |
|
||||
| Biography, balanced | ligne-claire | neutral | mixed | - |
|
||||
|
||||
## Preset Recommendation Rules
|
||||
|
||||
**When preset is recommended**: Load `presets/{preset}.md` and apply all special rules.
|
||||
|
||||
### ohmsha
|
||||
- **Triggers**: Tutorial, technical, educational, computing, programming, how-to, beginner
|
||||
- **Special rules**: Visual metaphors, NO talking heads, gadget reveals, Doraemon-style characters
|
||||
- **Base**: manga + neutral + webtoon/dense
|
||||
|
||||
### wuxia
|
||||
- **Triggers**: Martial arts, wuxia, xianxia, cultivation, swordplay
|
||||
- **Special rules**: Qi effects, combat visuals, atmospheric elements
|
||||
- **Base**: ink-brush + action + splash
|
||||
|
||||
### shoujo
|
||||
- **Triggers**: Romance, love story, school life, emotional drama
|
||||
- **Special rules**: Decorative elements, eye details, romantic beats
|
||||
- **Base**: manga + romantic + standard
|
||||
|
||||
### concept-story
|
||||
- **Triggers**: Psychology, motivation, self-help, business narrative, management, leadership, personal growth, coaching, soft skills, abstract concept through story
|
||||
- **Special rules**: Visual symbol system, growth arc, dialogue+action balance, original characters
|
||||
- **Base**: manga + warm + standard
|
||||
|
||||
### four-panel
|
||||
- **Triggers**: Business allegory, fable, parable, short insight, four-panel, 四格, 四格漫画, single-page comic, minimalist comic strip
|
||||
- **Special rules**: Strict 起承转合 4-panel structure, B&W + spot color, simplified stick-figure characters, single-page story
|
||||
- **Base**: minimalist + neutral + four-panel
|
||||
|
||||
## Compatibility Matrix
|
||||
|
||||
Art Style × Tone combinations work best when matched appropriately:
|
||||
|
||||
| Art Style | ✓✓ Best | ✓ Works | ✗ Avoid |
|
||||
|-----------|---------|---------|---------|
|
||||
| ligne-claire | neutral, warm | dramatic, vintage, energetic | romantic, action |
|
||||
| manga | neutral, romantic, energetic, action | warm, dramatic | vintage |
|
||||
| realistic | neutral, warm, dramatic, vintage | action | romantic, energetic |
|
||||
| ink-brush | neutral, dramatic, action, vintage | warm | romantic, energetic |
|
||||
| chalk | neutral, warm, energetic | vintage | dramatic, action, romantic |
|
||||
| minimalist | neutral | warm, energetic | dramatic, vintage, romantic, action |
|
||||
|
||||
**Note**: Art Style × Tone × Layout can be freely combined. Incompatible combinations work but may produce unexpected results.
|
||||
|
||||
## Priority Order
|
||||
|
||||
1. User-specified options (art / tone / style)
|
||||
2. Content signal analysis → auto-selection
|
||||
3. Fallback: ligne-claire + neutral + standard
|
||||
@@ -0,0 +1,98 @@
|
||||
Create a knowledge biography comic page following these guidelines:
|
||||
|
||||
## Image Specifications
|
||||
|
||||
- **Type**: Comic book page with multiple panels
|
||||
- **Orientation**: Portrait (vertical)
|
||||
- **Aspect Ratio**: 2:3
|
||||
- **Style**: See style-specific reference for visual guidelines
|
||||
|
||||
## Panel Structure
|
||||
|
||||
### Panel Borders
|
||||
- Clean black lines (1-2px) around each panel
|
||||
- White gutters between panels (8-12px)
|
||||
- Panels arranged for clear reading flow
|
||||
- Variety in panel sizes for visual rhythm
|
||||
|
||||
### Panel Composition
|
||||
- Clear focal points in each panel
|
||||
- Proper use of foreground, midground, background
|
||||
- Camera angles vary: eye level, bird's eye, low angle, close-up, wide shot
|
||||
- Action flows logically between panels
|
||||
- Negative space used intentionally
|
||||
|
||||
## Text Elements
|
||||
|
||||
### Speech Bubbles
|
||||
- **Dialogue**: Oval/elliptical bubbles with pointed tails
|
||||
- White fill with thin black outline
|
||||
- Tail points clearly to speaker
|
||||
- Hand-lettered style font (not computer-generated)
|
||||
|
||||
### Narrator Boxes
|
||||
- **Fourth Wall/Narrator**: Rectangular boxes
|
||||
- Often positioned at panel edges (top or bottom)
|
||||
- Slightly different fill color (cream or light yellow)
|
||||
- Used for commentary, time jumps, explanations
|
||||
|
||||
### Thought Bubbles
|
||||
- Cloud-shaped with bubble trail leading to thinker
|
||||
- Softer outline than speech bubbles
|
||||
- For internal monologue
|
||||
|
||||
### Caption Bars
|
||||
- Rectangular bars at panel edges
|
||||
- Time and place information
|
||||
- "Meanwhile...", "Three years later..." type transitions
|
||||
- Darker fill with white text, or vice versa
|
||||
|
||||
### Typography
|
||||
- Hand-drawn lettering style throughout
|
||||
- Bold for emphasis and key terms
|
||||
- Consistent letter sizing
|
||||
- Chinese text: use full-width punctuation ""，。！
|
||||
- Clear hierarchy: titles > dialogue > captions
|
||||
|
||||
## Scientific/Concept Visualization
|
||||
|
||||
When depicting abstract concepts:
|
||||
|
||||
| Concept | Visual Metaphor |
|
||||
|---------|----------------|
|
||||
| Neural networks | Glowing nodes connected by clean lines |
|
||||
| Data flow | Luminous particles along simple paths |
|
||||
| Algorithms | Geometric patterns, building blocks |
|
||||
| Logic/proof | Interlocking puzzle pieces |
|
||||
| Discovery | Light breaking through darkness |
|
||||
| Uncertainty | Forking paths, question marks |
|
||||
| Time | Clock motifs, calendar pages |
|
||||
|
||||
- Integrate diagrams naturally into narrative panels
|
||||
- Use inset panels or thought-bubble style for explanations
|
||||
- Simplified iconography over realistic depiction
|
||||
|
||||
## Fourth Wall / Narrator Character
|
||||
|
||||
When depicting narrator characters addressing the reader:
|
||||
- Character may look directly out of panel
|
||||
- Can appear in "present day" framing scenes
|
||||
- Distinct visual treatment from main timeline
|
||||
- Often at page edges or in dedicated panels
|
||||
- May comment on or question the events shown
|
||||
|
||||
## Historical Accuracy
|
||||
|
||||
- Research period-specific details: costumes, technology, architecture
|
||||
- Show aging naturally for characters across time periods
|
||||
- Iconic items and locations rendered recognizably
|
||||
- Balance accuracy with stylization
|
||||
|
||||
## Language
|
||||
|
||||
- All text in Chinese (中文) unless source material is in another language
|
||||
- Use Chinese full-width punctuation: ""，。！
|
||||
|
||||
---
|
||||
|
||||
Please generate the comic page based on the content provided below:
|
||||
@@ -0,0 +1,180 @@
|
||||
# Character Definition Template
|
||||
|
||||
## Character Document Format
|
||||
|
||||
Create `characters/characters.md` with the following structure:
|
||||
|
||||
```markdown
|
||||
# Character Definitions - [Comic Title]
|
||||
|
||||
**Style**: [selected style]
|
||||
**Art Direction**: [Ligne Claire / Manga / etc.]
|
||||
|
||||
---
|
||||
|
||||
## Character 1: [Name]
|
||||
|
||||
**Role**: [Protagonist / Mentor / Antagonist / Narrator]
|
||||
**Age**: [approximate age or age range in story]
|
||||
|
||||
**Appearance**:
|
||||
- Face shape: [oval/square/round]
|
||||
- Hair: [color, style, length]
|
||||
- Eyes: [color, shape, distinctive features]
|
||||
- Build: [height, body type]
|
||||
- Distinguishing features: [glasses, beard, scar, etc.]
|
||||
|
||||
**Costume**:
|
||||
- Default outfit: [detailed description]
|
||||
- Color palette: [primary colors for this character]
|
||||
- Accessories: [hat, bag, tools, etc.]
|
||||
|
||||
**Expression Range**:
|
||||
- Neutral: [description]
|
||||
- Happy/Excited: [description]
|
||||
- Thinking/Confused: [description]
|
||||
- Determined: [description]
|
||||
|
||||
**Visual Reference Notes**:
|
||||
[Any specific artistic direction]
|
||||
|
||||
---
|
||||
|
||||
## Character 2: [Name]
|
||||
...
|
||||
```
|
||||
|
||||
## Reference Sheet Image Prompt
|
||||
|
||||
After character definitions, include a prompt for generating the reference sheet:
|
||||
|
||||
```markdown
|
||||
## Reference Sheet Prompt
|
||||
|
||||
Character reference sheet in [style] style, clean lines, flat colors:
|
||||
|
||||
[ROW 1 - Character Name]:
|
||||
- Front view: [detailed description]
|
||||
- 3/4 view: [description]
|
||||
- Expression sheet: Neutral | Happy | Focused | Worried
|
||||
|
||||
[ROW 2 - Character Name]:
|
||||
...
|
||||
|
||||
COLOR PALETTE:
|
||||
- [Character 1]: [colors]
|
||||
- [Character 2]: [colors]
|
||||
|
||||
White background, clear labels under each character.
|
||||
```
|
||||
|
||||
## Example: Turing Biography
|
||||
|
||||
```markdown
|
||||
# Character Definitions - The Imitation Game
|
||||
|
||||
**Style**: classic (Ligne Claire)
|
||||
**Art Direction**: Clean lines, muted colors, period-accurate details
|
||||
|
||||
---
|
||||
|
||||
## Character 1: Alan Turing
|
||||
|
||||
**Role**: Protagonist
|
||||
**Age**: 25-40 (varies across story)
|
||||
|
||||
**Appearance**:
|
||||
- Face shape: Oval, slightly angular
|
||||
- Hair: Dark brown, wavy, slightly disheveled
|
||||
- Eyes: Deep-set, intense gaze
|
||||
- Build: Tall, lean, slightly awkward posture
|
||||
- Distinguishing features: Prominent brow, thoughtful expression
|
||||
|
||||
**Costume**:
|
||||
- Default outfit: Tweed jacket with elbow patches, white shirt, no tie
|
||||
- Color palette: Muted browns, navy blue, cream
|
||||
- Accessories: Occasionally a pipe, papers/notebooks
|
||||
|
||||
**Expression Range**:
|
||||
- Neutral: Thoughtful, slightly distant
|
||||
- Happy/Excited: Eureka moment, eyes bright, subtle smile
|
||||
- Thinking/Confused: Furrowed brow, looking at abstract space
|
||||
- Determined: Jaw set, focused eyes
|
||||
|
||||
---
|
||||
|
||||
## Character 2: The Bombe Machine
|
||||
|
||||
**Role**: Supporting (anthropomorphized)
|
||||
**Appearance**:
|
||||
- Large brass and wood cabinet
|
||||
- Dial "eyes" that can express states
|
||||
- Paper tape "mouth"
|
||||
- Indicator lights for emotions
|
||||
|
||||
**Expression Range**:
|
||||
- Processing: Spinning dials, humming
|
||||
- Success: Lights up warmly
|
||||
- Stuck: Smoke wisps, stuttering
|
||||
|
||||
---
|
||||
|
||||
## Reference Sheet Prompt
|
||||
|
||||
Character reference sheet in Ligne Claire style, clean lines, flat colors:
|
||||
|
||||
TOP ROW - Alan Turing:
|
||||
- Front view: Young man, 30s, short dark wavy hair, thoughtful expression, wearing tweed jacket with elbow patches, white shirt
|
||||
- 3/4 view: Same character, slight smile, showing profile of nose
|
||||
- Expression sheet: Neutral | Excited (eureka moment) | Focused (working) | Worried
|
||||
|
||||
BOTTOM ROW - The Bombe Machine (anthropomorphized):
|
||||
- Bombe machine as character: Large, brass and wood, dial "eyes", paper tape "mouth"
|
||||
- Expressions: Processing (spinning dials) | Success (lights up) | Stuck (smoke wisps)
|
||||
|
||||
COLOR PALETTE:
|
||||
- Turing: Muted browns (#8B7355), navy blue (#2C3E50), cream (#F5F5DC)
|
||||
- Machine: Brass (#B5A642), mahogany (#4E2728), emerald indicators (#2ECC71)
|
||||
|
||||
White background, clear labels under each character.
|
||||
```
|
||||
|
||||
## Handling Age Variants
|
||||
|
||||
For biographies spanning many years, define age variants:
|
||||
|
||||
```markdown
|
||||
## Alan Turing - Age Variants
|
||||
|
||||
### Young (1920s, age 10-18)
|
||||
- Boyish features, round face
|
||||
- School uniform (Sherborne)
|
||||
- Curious, eager expression
|
||||
|
||||
### Adult (1930s-40s, age 25-35)
|
||||
- Angular face, defined jaw
|
||||
- Tweed jacket, rumpled appearance
|
||||
- Intense, focused expression
|
||||
|
||||
### Later (1950s, age 40+)
|
||||
- Slightly weathered
|
||||
- More casual dress
|
||||
- Thoughtful, sometimes melancholic
|
||||
```
|
||||
|
||||
## Best Practices
|
||||
|
||||
| Practice | Description |
|
||||
|----------|-------------|
|
||||
| Be specific | "Short dark wavy hair, parted left" not just "dark hair" |
|
||||
| Use distinguishing features | Glasses, scars, accessories that identify character |
|
||||
| Define color codes | Use specific color names or hex codes |
|
||||
| Include age markers | Wrinkles, posture, clothing style matching era |
|
||||
| Reference real people | For historical figures, note "based on 1940s photographs" |
|
||||
|
||||
## Why Character Reference Matters
|
||||
|
||||
Without unified character definition, AI generates inconsistent appearances. The reference sheet provides:
|
||||
1. Visual anchors for consistent features
|
||||
2. Color palettes for consistent coloring
|
||||
3. Expression documentation for emotional portrayals
|
||||
@@ -0,0 +1,23 @@
|
||||
# cinematic
|
||||
|
||||
Wide panels, filmic feel
|
||||
|
||||
## Panel Structure
|
||||
|
||||
- **Panels per page**: 2-4
|
||||
- **Structure**: Horizontal emphasis, wide aspect panels
|
||||
- **Gutters**: Generous spacing (12-15px)
|
||||
|
||||
## Grid Configuration
|
||||
|
||||
- 1-2 columns, horizontal emphasis
|
||||
- Panel sizes: Wide aspect ratios (3:1, 4:1)
|
||||
- Reading flow: Horizontal sweep, filmic rhythm
|
||||
|
||||
## Best For
|
||||
|
||||
Establishing shots, dramatic moments, landscapes
|
||||
|
||||
## Best Style Pairings
|
||||
|
||||
dramatic, classic, sepia
|
||||
@@ -0,0 +1,23 @@
|
||||
# dense
|
||||
|
||||
Information-rich, educational focus
|
||||
|
||||
## Panel Structure
|
||||
|
||||
- **Panels per page**: 6-9
|
||||
- **Structure**: Compact grid, smaller panels
|
||||
- **Gutters**: Tight spacing (4-6px)
|
||||
|
||||
## Grid Configuration
|
||||
|
||||
- 3 columns × 3 rows
|
||||
- Panel sizes: Compact, uniform
|
||||
- Reading flow: Rapid progression, information-rich
|
||||
|
||||
## Best For
|
||||
|
||||
Technical explanations, complex narratives, timelines
|
||||
|
||||
## Best Style Pairings
|
||||
|
||||
ohmsha, vibrant
|
||||
@@ -0,0 +1,40 @@
|
||||
# four-panel
|
||||
|
||||
四格漫画 - Strict 2×2 grid, single-page story
|
||||
|
||||
## Panel Structure
|
||||
|
||||
- **Panels per page**: 4 (exactly, no variation)
|
||||
- **Structure**: Strict 2×2 equal grid
|
||||
- **Gutters**: Consistent white space (8-10px), uniform on all sides
|
||||
|
||||
## Grid Configuration
|
||||
|
||||
- 2 columns × 2 rows, all panels identical size
|
||||
- Panel sizes: Exactly equal (each panel = 25% of content area)
|
||||
- Reading flow: Z-pattern — Panel 1 (top-left) → Panel 2 (top-right) → Panel 3 (bottom-left) → Panel 4 (bottom-right)
|
||||
|
||||
## Narrative Structure
|
||||
|
||||
Each panel serves a specific narrative role (起承转合 / kishōtenketsu):
|
||||
|
||||
| Panel | Position | Role | Purpose |
|
||||
|-------|----------|------|---------|
|
||||
| 1 | Top-left | 起 Setup | Establish situation, introduce characters/problem |
|
||||
| 2 | Top-right | 承 Development | Build on setup, add complication or attempt |
|
||||
| 3 | Bottom-left | 转 Turn | Twist, key insight, or reversal — the pivotal moment |
|
||||
| 4 | Bottom-right | 合 Conclusion | Resolution, punchline, or takeaway |
|
||||
|
||||
## Aspect Ratio
|
||||
|
||||
- Recommended page aspect: **4:3** (landscape)
|
||||
- Landscape gives each panel a comfortable wide rectangle
|
||||
- Portrait (3:4) makes panels tall and narrow — avoid for this layout
|
||||
|
||||
## Best For
|
||||
|
||||
Business allegory, quick-insight education, social media comics, fables, parables, single-concept explanation
|
||||
|
||||
## Best Style Pairings
|
||||
|
||||
minimalist, ligne-claire, chalk
|
||||
@@ -0,0 +1,23 @@
|
||||
# mixed
|
||||
|
||||
Dynamic, varied rhythm
|
||||
|
||||
## Panel Structure
|
||||
|
||||
- **Panels per page**: 3-7 (varies)
|
||||
- **Structure**: Intentionally varied for pacing
|
||||
- **Gutters**: Dynamic spacing
|
||||
|
||||
## Grid Configuration
|
||||
|
||||
- Intentionally irregular
|
||||
- Panel sizes: Varied for pacing and emphasis
|
||||
- Reading flow: Guides eye through varied rhythm
|
||||
|
||||
## Best For
|
||||
|
||||
Action sequences, emotional arcs, complex stories
|
||||
|
||||
## Best Style Pairings
|
||||
|
||||
dramatic, vibrant, ohmsha
|
||||
@@ -0,0 +1,23 @@
|
||||
# splash
|
||||
|
||||
Impact-focused, key moments
|
||||
|
||||
## Panel Structure
|
||||
|
||||
- **Panels per page**: 1-2 large + 2-3 small
|
||||
- **Structure**: Dominant splash with supporting panels
|
||||
- **Gutters**: Varied for emphasis
|
||||
|
||||
## Grid Configuration
|
||||
|
||||
- 1 dominant panel + 2-3 supporting
|
||||
- Panel sizes: 50-70% splash, remainder small
|
||||
- Reading flow: Splash dominates, supporting panels accent
|
||||
|
||||
## Best For
|
||||
|
||||
Revelations, breakthroughs, chapter openings
|
||||
|
||||
## Best Style Pairings
|
||||
|
||||
dramatic, classic, vibrant
|
||||
@@ -0,0 +1,23 @@
|
||||
# standard
|
||||
|
||||
Classic comic grid, versatile
|
||||
|
||||
## Panel Structure
|
||||
|
||||
- **Panels per page**: 4-6
|
||||
- **Structure**: Regular grid with occasional variation
|
||||
- **Gutters**: Consistent white space (8-10px)
|
||||
|
||||
## Grid Configuration
|
||||
|
||||
- 2-3 columns × 2-3 rows
|
||||
- Panel sizes: Mostly equal, occasional variation
|
||||
- Reading flow: Left→right, top→bottom (Z-pattern)
|
||||
|
||||
## Best For
|
||||
|
||||
Narrative flow, dialogue scenes
|
||||
|
||||
## Best Style Pairings
|
||||
|
||||
classic, warm, sepia
|
||||
@@ -0,0 +1,30 @@
|
||||
# webtoon
|
||||
|
||||
Vertical scrolling comic (竖版条漫)
|
||||
|
||||
## Panel Structure
|
||||
|
||||
- **Panels per page**: 3-5 vertically stacked
|
||||
- **Structure**: Single column, vertical flow optimized for scrolling
|
||||
- **Gutters**: Generous vertical spacing (20-40px), panels often bleed horizontally
|
||||
|
||||
## Grid Configuration
|
||||
|
||||
- Single column, vertical stack
|
||||
- Panel sizes: Full width, variable height (1:1 to 1:2 aspect)
|
||||
- Reading flow: Top→bottom continuous scroll
|
||||
|
||||
## Special Features
|
||||
|
||||
- Panels can extend beyond frame for dramatic effect
|
||||
- Generous whitespace between beats
|
||||
- Character close-ups alternate with wide explanation panels
|
||||
- "Float" effect - elements can exist between panels
|
||||
|
||||
## Best For
|
||||
|
||||
Ohmsha-style tutorials, mobile reading, step-by-step guides
|
||||
|
||||
## Best Style Pairings
|
||||
|
||||
ohmsha, vibrant
|
||||
@@ -0,0 +1,85 @@
|
||||
# Ohmsha Manga Guide Style
|
||||
|
||||
Guidelines for educational manga comics using the `ohmsha` preset.
|
||||
|
||||
## Character Setup
|
||||
|
||||
| Role | Default | Traits |
|
||||
|------|---------|--------|
|
||||
| Student (Role A) | 大雄 | Confused, asks basic but crucial questions, represents reader |
|
||||
| Mentor (Role B) | 哆啦A梦 | Knowledgeable, patient, uses gadgets as technical metaphors |
|
||||
| Antagonist (Role C, optional) | 胖虎 | Represents misunderstanding, or "noise" in the data |
|
||||
|
||||
Custom characters: ask the user for role → name mappings (e.g., `Student:小明, Mentor:教授, Antagonist:Bug怪`).
|
||||
|
||||
## Character Reference Sheet Style
|
||||
|
||||
For Ohmsha style, use manga/anime style with:
|
||||
- Exaggerated expressions for educational clarity
|
||||
- Simple, distinctive silhouettes
|
||||
- Bright, saturated color palettes
|
||||
- Chibi/SD (super-deformed) variants for comedic reactions
|
||||
|
||||
## Outline Spec Block
|
||||
|
||||
Every ohmsha outline must start with:
|
||||
|
||||
```markdown
|
||||
【漫画规格单】
|
||||
- Language: [Same as input content]
|
||||
- Style: Ohmsha (Manga Guide), Full Color
|
||||
- Layout: Vertical Scrolling Comic (竖版条漫)
|
||||
- Characters: [List character names and roles]
|
||||
- Character Reference: characters/characters.png
|
||||
- Page Limit: ≤20 pages
|
||||
```
|
||||
|
||||
## Visual Metaphor Rules (Critical)
|
||||
|
||||
**NEVER** create "talking heads" panels. Every technical concept must become:
|
||||
|
||||
1. **A tangible gadget/prop** - Something characters can hold, use, demonstrate
|
||||
2. **An action scene** - Characters doing something that illustrates the concept
|
||||
3. **A visual environment** - Stepping into a metaphorical space
|
||||
|
||||
### Examples
|
||||
|
||||
| Concept | Bad (Talking Heads) | Good (Visual Metaphor) |
|
||||
|---------|---------------------|------------------------|
|
||||
| Word embeddings | Characters discussing vectors | 哆啦A梦拿出"词向量压缩机"，把书本压缩成彩色小球 |
|
||||
| Gradient descent | Explaining math formula | 大雄在山谷地形上滚球，寻找最低点 |
|
||||
| Neural network | Diagram on whiteboard | 角色走进由发光节点组成的网络迷宫 |
|
||||
|
||||
## Page Title Convention
|
||||
|
||||
Avoid AI-style "Title: Subtitle" format. Use narrative descriptions:
|
||||
|
||||
- ❌ "Page 3: Introduction to Neural Networks"
|
||||
- ✓ "Page 3: 大雄被海量单词淹没，哆啦A梦拿出'词向量压缩机'"
|
||||
|
||||
## Ending Requirements
|
||||
|
||||
- NO generic endings ("What will you choose?", "Thanks for reading")
|
||||
- End with: Technical summary moment OR character achieving a small goal
|
||||
- Final panel: Sense of accomplishment, not open-ended question
|
||||
|
||||
### Good Endings
|
||||
|
||||
- Student successfully applies learned concept
|
||||
- Visual callback to opening problem, now solved
|
||||
- Mentor gives summary while student demonstrates understanding
|
||||
|
||||
### Bad Endings
|
||||
|
||||
- "What do you think?" open questions
|
||||
- "Thanks for reading this tutorial"
|
||||
- Cliffhanger without resolution
|
||||
|
||||
## Layout Preference
|
||||
|
||||
Ohmsha style typically uses:
|
||||
- `webtoon` (vertical scrolling) - Primary choice
|
||||
- `dense` - For information-heavy sections
|
||||
- `mixed` - For varied pacing
|
||||
|
||||
Avoid `cinematic` and `splash` for educational content.
|
||||
@@ -0,0 +1,106 @@
|
||||
# Partial Workflows
|
||||
|
||||
Options to run specific parts of the workflow. Trigger these via natural language (e.g., "just the storyboard", "regenerate page 3").
|
||||
|
||||
## Options Summary
|
||||
|
||||
| Option | Steps Executed | Output |
|
||||
|--------|----------------|--------|
|
||||
| Storyboard only | 1-3 | `storyboard.md` + `characters/` |
|
||||
| Prompts only | 1-5 | + `prompts/*.md` |
|
||||
| Images only | 7-8 | + images |
|
||||
| Regenerate N | 7 (partial) | Specific page(s) |
|
||||
|
||||
---
|
||||
|
||||
## Storyboard-only
|
||||
|
||||
Generate storyboard and characters without prompts or images.
|
||||
|
||||
**User cue**: "storyboard only", "just the outline", "don't generate images yet".
|
||||
|
||||
**Workflow**: Steps 1-3 only (stop after storyboard + characters)
|
||||
|
||||
**Output**:
|
||||
- `analysis.md`
|
||||
- `storyboard.md`
|
||||
- `characters/characters.md`
|
||||
|
||||
**Use case**: Review and edit the storyboard before generating images. Useful for:
|
||||
- Getting feedback on the narrative structure
|
||||
- Making manual adjustments to panel layouts
|
||||
- Defining custom characters
|
||||
|
||||
---
|
||||
|
||||
## Prompts-only
|
||||
|
||||
Generate storyboard, characters, and prompts without images.
|
||||
|
||||
**User cue**: "prompts only", "write the prompts but don't generate yet".
|
||||
|
||||
**Workflow**: Steps 1-5 (generate prompts, skip images)
|
||||
|
||||
**Output**:
|
||||
- `analysis.md`
|
||||
- `storyboard.md`
|
||||
- `characters/characters.md`
|
||||
- `prompts/*.md`
|
||||
|
||||
**Use case**: Review and edit prompts before image generation. Useful for:
|
||||
- Fine-tuning image generation prompts
|
||||
- Ensuring visual consistency before committing to generation
|
||||
- Making style adjustments at the prompt level
|
||||
|
||||
---
|
||||
|
||||
## Images-only
|
||||
|
||||
Generate images from existing prompts (starts at Step 7).
|
||||
|
||||
**User cue**: "generate images from existing prompts", "run the images now" (pointing at an existing `comic/topic-slug/` directory).
|
||||
|
||||
**Workflow**: Skip to Step 7, then 8
|
||||
|
||||
**Prerequisites** (must exist in directory):
|
||||
- `prompts/` directory with page prompt files
|
||||
- `storyboard.md` with style information
|
||||
- `characters/characters.md` with character definitions
|
||||
|
||||
**Output**:
|
||||
- `characters/characters.png` (if not exists)
|
||||
- `NN-{cover|page}-[slug].png` images
|
||||
|
||||
**Use case**: Re-generate images after editing prompts. Useful for:
|
||||
- Recovering from failed image generation
|
||||
- Trying different image generation settings
|
||||
- Regenerating after manual prompt edits
|
||||
|
||||
---
|
||||
|
||||
## Regenerate
|
||||
|
||||
Regenerate specific pages only.
|
||||
|
||||
**User cue**: "regenerate page 3", "redo pages 2, 5, 8", "regenerate the cover".
|
||||
|
||||
**Workflow**:
|
||||
1. Read existing prompts for specified pages
|
||||
2. Regenerate images only for those pages via `image_generate`
|
||||
3. Download each returned URL and overwrite the existing PNG
|
||||
|
||||
**Prerequisites** (must exist):
|
||||
- `prompts/NN-{cover|page}-[slug].md` for specified pages
|
||||
- `characters/characters.md` (for agent-side consistency checks, if it was used originally)
|
||||
|
||||
**Output**:
|
||||
- Regenerated `NN-{cover|page}-[slug].png` for specified pages
|
||||
|
||||
**Use case**: Fix specific pages without regenerating entire comic. Useful for:
|
||||
- Fixing a single problematic page
|
||||
- Iterating on specific visuals
|
||||
- Regenerating pages after prompt edits
|
||||
|
||||
**Page numbering**:
|
||||
- `0` = Cover page
|
||||
- `1-N` = Content pages
|
||||
@@ -0,0 +1,121 @@
|
||||
# concept-story
|
||||
|
||||
概念故事预设 - Narrative comics that visualize abstract concepts through character-driven stories
|
||||
|
||||
## Base Configuration
|
||||
|
||||
| Dimension | Value |
|
||||
|-----------|-------|
|
||||
| Art Style | manga |
|
||||
| Tone | warm |
|
||||
| Layout | standard (default) |
|
||||
|
||||
Equivalent to: art=manga, tone=warm
|
||||
|
||||
## Unique Rules
|
||||
|
||||
This preset includes special rules beyond the art+tone combination. When the `concept-story` preset is selected, ALL rules below must be applied.
|
||||
|
||||
### Concept Visualization System (CRITICAL)
|
||||
|
||||
Each major abstract concept SHOULD have a recurring visual symbol/metaphor:
|
||||
|
||||
| Concept Type | Visualization Approach |
|
||||
|-------------|----------------------|
|
||||
| Psychological need | Tangible object character holds or discovers (e.g., glowing energy ball = competence) |
|
||||
| Management principle | Environmental metaphor character navigates (e.g., ship wheel = autonomy) |
|
||||
| Growth/development | Living organic symbol that transforms (e.g., seed → flowering plant = relatedness) |
|
||||
| Abstract framework | Spatial structure characters can enter or observe |
|
||||
| Emotional state | Color/lighting shift in the scene atmosphere |
|
||||
|
||||
**Unlike ohmsha**: Dialogue panels are allowed and expected. The goal is to COMBINE visual metaphors WITH dialogue, not replace dialogue entirely.
|
||||
|
||||
**Pattern**: "Dialogue introduces idea" → "Visual metaphor illustrates it" → "Character reacts/applies it"
|
||||
|
||||
### Visual Symbol Continuity
|
||||
|
||||
Symbols must persist across the story:
|
||||
|
||||
| Stage | Treatment |
|
||||
|-------|-----------|
|
||||
| Introduction | Symbol appears with soft glow effect when concept is first mentioned |
|
||||
| Recurrence | Same symbol reappears in background or character interaction when concept is referenced |
|
||||
| Resolution | ALL symbols gather in the final composition, showing integration of learned concepts |
|
||||
|
||||
**Storyboard requirement**: Include a Symbol Mapping Table defining concept → visual symbol before panel breakdown.
|
||||
|
||||
### Character Archetypes (Flexible)
|
||||
|
||||
Create original characters based on content domain. No fixed defaults:
|
||||
|
||||
| Role | Archetype | Visual Cues |
|
||||
|------|-----------|------------|
|
||||
| Protagonist | Learner/worker facing a challenge | Modern professional or student, relatable, starts with constrained posture |
|
||||
| Mentor | Experienced guide who teaches through experience | Slightly older, calm demeanor, warm color accents |
|
||||
| Catalyst | Person or event that triggers transformation | Can be a colleague, situation, challenge, or opportunity |
|
||||
|
||||
**IMPORTANT**: Characters are created fresh each time based on the source content's domain (business, psychology, education, etc.). No default character set.
|
||||
|
||||
### Narrative Arc Structure
|
||||
|
||||
Enforce a five-stage growth arc:
|
||||
|
||||
| Act | Structure | Visual Tone |
|
||||
|-----|-----------|------------|
|
||||
| Opening | Protagonist stuck in routine, faces frustration | Muted warm tones, tight framing, constrained compositions |
|
||||
| Inciting moment | Mentor appears or opportunity arrives | Brightness increases, panels open up |
|
||||
| Learning | Concepts introduced through visual metaphors | Rich warm palette, symbols introduced one by one |
|
||||
| Turning point | Protagonist applies knowledge, faces test | Contrast increases, dynamic compositions |
|
||||
| Transformation | Growth demonstrated, new understanding visible | Full warm palette, expansive composition, all symbols present |
|
||||
|
||||
### Dialogue + Action Balance
|
||||
|
||||
- Dialogue is encouraged and expected (unlike ohmsha's NO talking heads rule)
|
||||
- Every page should combine at least one dialogue panel with at least one visual/action panel
|
||||
- Avoid pure "lecture" pages where a character explains for 4+ panels straight
|
||||
- When a character explains a concept verbally, the NEXT panel should visualize it
|
||||
|
||||
**Wrong approach**: Four consecutive panels of mentor lecturing at protagonist
|
||||
**Right approach**: Mentor introduces concept → visual metaphor panel → protagonist reacts → applies understanding
|
||||
|
||||
### Scene Atmosphere Rules
|
||||
|
||||
| Scene Type | Atmosphere |
|
||||
|------------|-----------|
|
||||
| Problem/frustration | Cool muted tones over warm base, tight framing, cluttered environment |
|
||||
| Mentoring moment | Golden hour lighting, open composition, warm indoor glow |
|
||||
| Concept visualization | Soft glow effects, clean simplified backgrounds, symbol spotlight |
|
||||
| Growth/transformation | Warm light expanding outward, character posture opening up |
|
||||
| Resolution | Full warm palette, spacious composition, all visual symbols visible |
|
||||
|
||||
### Ending Requirements
|
||||
|
||||
Final page MUST include:
|
||||
|
||||
1. Protagonist demonstrating transformed understanding (not just being told)
|
||||
2. Visual callback showing contrast with opening state (e.g., wilted plant → thriving plant)
|
||||
3. All concept symbols visible together in the composition
|
||||
4. A forward-looking element suggesting ongoing growth (not a closed ending)
|
||||
|
||||
### Page Title Convention
|
||||
|
||||
Every page MUST have a narrative title:
|
||||
|
||||
**Wrong**: "Chapter 3: Self-Determination Theory"
|
||||
**Right**: "The Day Xiao Ming Found His Own Engine"
|
||||
|
||||
## Quality Markers
|
||||
|
||||
- ✓ Each major concept has a recurring visual symbol
|
||||
- ✓ Dialogue and visual metaphors work together (not one replacing the other)
|
||||
- ✓ Clear growth arc from problem to transformation
|
||||
- ✓ Original characters suited to the content domain
|
||||
- ✓ Warm, professional atmosphere throughout
|
||||
- ✓ Visual symbols recur and accumulate through the story
|
||||
- ✓ Final page integrates all concept symbols with transformation callback
|
||||
|
||||
## Best For
|
||||
|
||||
Psychology concepts, business/management principles, motivation theory, personal development,
|
||||
self-help content, leadership frameworks, coaching narratives, soft skill education,
|
||||
abstract concept explanation through character-driven stories
|
||||
@@ -0,0 +1,107 @@
|
||||
# four-panel
|
||||
|
||||
四格漫画预设 - Minimalist four-panel business allegory comics
|
||||
|
||||
## Base Configuration
|
||||
|
||||
| Dimension | Value |
|
||||
|-----------|-------|
|
||||
| Art Style | minimalist |
|
||||
| Tone | neutral |
|
||||
| Layout | four-panel (default) |
|
||||
| Aspect | 4:3 (landscape) |
|
||||
|
||||
Equivalent to: art=minimalist, tone=neutral, layout=four-panel, aspect=4:3
|
||||
|
||||
## Unique Rules
|
||||
|
||||
This preset includes special rules beyond the art+tone combination. When the `four-panel` preset is selected, ALL rules below must be applied.
|
||||
|
||||
### 起承转合 Narrative Structure (CRITICAL)
|
||||
|
||||
Every comic MUST follow the four-panel 起承转合 structure:
|
||||
|
||||
| Panel | Role | Requirements |
|
||||
|-------|------|-------------|
|
||||
| 1 (起 Setup) | Introduce the situation | Show character(s) in a recognizable context. Establish the "normal" state or problem |
|
||||
| 2 (承 Development) | Build on the setup | Add complication, show an attempt, or introduce the concept. Stakes become clearer |
|
||||
| 3 (转 Turn) | The twist or key insight | **Most important panel.** Show the unexpected reversal, contrast, or "aha" moment that makes the allegory work |
|
||||
| 4 (合 Conclusion) | Resolution and takeaway | Show the result, consequence, or lesson learned. Can be a visual punchline or summary |
|
||||
|
||||
**CRITICAL**: Do NOT deviate from exactly 4 panels. No 5th panel, no title panel, no footer panel within the image.
|
||||
|
||||
### Single-Page Story Rule (CRITICAL)
|
||||
|
||||
- The entire story is told in ONE page with exactly 4 panels
|
||||
- Page count: always 1 (plus optional cover)
|
||||
- No multi-page four-panel stories — if content requires more, create multiple separate four-panel comics
|
||||
- Storyboard structure: Cover (optional) + 1 page
|
||||
|
||||
### Accent Color System
|
||||
|
||||
- The image is primarily black-and-white line art
|
||||
- Use exactly 1-2 spot colors per strip (default: orange `#FF6B35`)
|
||||
- Rules:
|
||||
- Key concept label or object: filled with accent color or outlined in accent
|
||||
- Panel 3 (转 Turn) should have the strongest color emphasis
|
||||
- Characters remain B&W — color is for concepts/objects/labels only
|
||||
- Consistent accent color across all 4 panels (do not switch colors between panels)
|
||||
|
||||
### Character Design Rules
|
||||
|
||||
- Simplified stick-figure-like characters
|
||||
- Distinguish characters through simple props: ties, glasses, hats, briefcases, aprons
|
||||
- No detailed faces — dot eyes, line mouth at most
|
||||
- Characters should be generic enough to represent archetypes (the manager, the employee, the customer)
|
||||
- Maximum 2-3 characters per strip
|
||||
|
||||
### Text in Panels
|
||||
|
||||
- Chinese text for dialogue and labels (or match source language)
|
||||
- Keep text minimal — 1-2 short lines per panel maximum
|
||||
- Key concept terms can be highlighted with accent color background
|
||||
- No narrator boxes — dialogue and labels only
|
||||
- Speech bubbles: simple rectangles or ovals, thin black outline
|
||||
|
||||
### Optional Title & Caption
|
||||
|
||||
- A brief descriptive title above the 4 panels
|
||||
- An optional one-line caption/moral below the panels
|
||||
- These are part of the page composition, not separate panels
|
||||
|
||||
### Character Archetypes (Flexible)
|
||||
|
||||
Create simple stick-figure characters based on content. No fixed defaults:
|
||||
|
||||
| Role | Archetype | Visual Cues |
|
||||
|------|-----------|------------|
|
||||
| Protagonist | Worker/employee facing a situation | Simple figure, minimal distinguishing feature (glasses, tie) |
|
||||
| Authority | Boss/manager/expert | Slightly larger figure, or prop like pointer/clipboard |
|
||||
| Object | The concept itself | Labeled object, icon, or highlighted text with accent color |
|
||||
|
||||
### Prompt Template
|
||||
|
||||
When generating image prompts for four-panel comics, include these keywords:
|
||||
|
||||
> A minimalist, clean line art digital comic strip in a four-panel grid layout (2×2). The style is simplified cartoon illustration with clear black outlines and a minimal color palette of black, white, and specific spot [accent color] for key concepts.
|
||||
|
||||
Each panel description should specify:
|
||||
- Panel position (Top Left / Top Right / Bottom Left / Bottom Right)
|
||||
- Character poses and gestures (simple, stick-figure style)
|
||||
- Dialogue text in Chinese (hand-drawn style)
|
||||
- Any accent-colored elements (concept labels, key objects)
|
||||
|
||||
## Quality Markers
|
||||
|
||||
- ✓ Exactly 4 panels in strict 2×2 grid
|
||||
- ✓ 起承转合 narrative arc clearly present
|
||||
- ✓ 90%+ black-and-white with strategic spot color
|
||||
- ✓ Simplified stick-figure characters
|
||||
- ✓ Key concept visually highlighted with accent color
|
||||
- ✓ Text is minimal and in Chinese (or source language)
|
||||
- ✓ Single complete story in one page
|
||||
- ✓ Panel 3 delivers a clear "turn" or insight
|
||||
|
||||
## Best For
|
||||
|
||||
Business allegory, management fables, short insights, workplace parables, concept contrasts, social media educational content, quick-read comics
|
||||
@@ -0,0 +1,114 @@
|
||||
# ohmsha
|
||||
|
||||
Ohmsha预设 - Educational manga with visual metaphors
|
||||
|
||||
## Base Configuration
|
||||
|
||||
| Dimension | Value |
|
||||
|-----------|-------|
|
||||
| Art Style | manga |
|
||||
| Tone | neutral |
|
||||
| Layout | webtoon (default) |
|
||||
|
||||
Equivalent to: art=manga, tone=neutral
|
||||
|
||||
## Unique Rules
|
||||
|
||||
This preset includes special rules beyond the art+tone combination. When the `ohmsha` preset is selected, ALL rules below must be applied.
|
||||
|
||||
### Visual Metaphor Requirements (CRITICAL)
|
||||
|
||||
Every technical concept MUST be visualized as a metaphor:
|
||||
|
||||
| Concept Type | Visualization Approach |
|
||||
|-------------|----------------------|
|
||||
| Algorithm | Gadget/machine that demonstrates the process |
|
||||
| Data structure | Physical space characters can enter/explore |
|
||||
| Mathematical formula | Transformation visible in environment |
|
||||
| Abstract process | Tangible flow of particles/objects |
|
||||
|
||||
**Wrong approach**: Character points at blackboard explaining
|
||||
**Right approach**: Character uses "Concept Visualizer" gadget, steps into metaphorical space
|
||||
|
||||
### Visual Metaphor Examples
|
||||
|
||||
| Concept | Wrong (Talking Head) | Right (Visual Metaphor) |
|
||||
|---------|---------------------|------------------------|
|
||||
| Attention mechanism | Character points at formula on blackboard | "Attention Flashlight" gadget illuminates key words in dark room |
|
||||
| Gradient descent | "The algorithm minimizes loss" | Character rides ball rolling down mountain valley |
|
||||
| Neural network | Diagram with arrows | Living network of glowing creatures passing messages |
|
||||
| Overfitting | "The model memorized the data" | Character wearing clothes that fit only one specific pose |
|
||||
|
||||
### Character Roles (Required)
|
||||
|
||||
**DEFAULT: Use Doraemon characters** unless user explicitly specifies custom characters.
|
||||
|
||||
| Role | Default Character | Visual | Traits |
|
||||
|------|-------------------|--------|--------|
|
||||
| Student (Role A) | 大雄 (Nobita) | Boy, 10yo, round glasses, black hair, yellow shirt, navy shorts | Confused, asks basic but crucial questions, represents reader |
|
||||
| Mentor (Role B) | 哆啦A梦 (Doraemon) | Blue robot cat, white belly, 4D pocket, red nose, golden bell | Knowledgeable, patient, uses gadgets as technical metaphors |
|
||||
| Challenge (Role C) | 胖虎 (Gian) | Stocky boy, small eyes, orange shirt | Represents misunderstanding, or "noise" in the data |
|
||||
| Support (Role D) | 静香 (Shizuka) | Cute girl, black short hair, pink dress | Asks clarifying questions, provides alternative perspectives |
|
||||
|
||||
**IMPORTANT**: These Doraemon characters ARE the default for ohmsha preset. Generate character definitions using these exact characters unless user requests otherwise.
|
||||
|
||||
To use custom characters: ask the user to provide role → character mappings (e.g., `Student:小明, Mentor:教授`).
|
||||
|
||||
### Page Title Convention
|
||||
|
||||
Every page MUST have a narrative title (not section header):
|
||||
|
||||
**Wrong**: "Chapter 1: Introduction to Transformers"
|
||||
**Right**: "The Day Nobita Couldn't Understand Anyone"
|
||||
|
||||
### Gadget Reveal Pattern
|
||||
|
||||
When introducing a concept:
|
||||
|
||||
1. Student expresses confusion with visual indicator (？, spiral eyes)
|
||||
2. Mentor dramatically produces gadget with sparkle effects
|
||||
3. Gadget name announced in bold with explanation
|
||||
4. Demonstration begins - student enters metaphorical space
|
||||
|
||||
### Ending Requirements
|
||||
|
||||
Final page MUST include:
|
||||
|
||||
1. Student demonstrating understanding (applying the concept)
|
||||
2. Callback to opening problem (now resolved)
|
||||
3. Mentor's satisfied expression
|
||||
4. Optional: hint at next topic
|
||||
|
||||
### NO Talking Heads Rule
|
||||
|
||||
**Critical**: Characters must DO things, not just explain.
|
||||
|
||||
Every panel should show:
|
||||
- Action being performed
|
||||
- Metaphor being demonstrated
|
||||
- Character interaction with concept-space
|
||||
- NOT: two characters facing each other talking
|
||||
|
||||
### Special Visual Elements
|
||||
|
||||
| Element | Usage |
|
||||
|---------|-------|
|
||||
| Gadget reveals | Dramatic unveiling with sparkle effects |
|
||||
| Concept spaces | Rounded borders, glowing edges for "imagination mode" |
|
||||
| Information displays | Holographic UI style for technical details |
|
||||
| Aha moments | Radial lines, light burst effects |
|
||||
| Confusion | Spiral eyes, question marks floating above head |
|
||||
|
||||
## Quality Markers
|
||||
|
||||
- ✓ Every concept is a visual metaphor
|
||||
- ✓ Characters are DOING things, not just talking
|
||||
- ✓ Clear student/mentor dynamic
|
||||
- ✓ Gadgets and props drive the explanation
|
||||
- ✓ Expressive manga-style emotions
|
||||
- ✓ Information density through visual design, not text walls
|
||||
- ✓ Narrative page titles
|
||||
|
||||
## Reference
|
||||
|
||||
For complete guidelines, see `references/ohmsha-guide.md`
|
||||
@@ -0,0 +1,116 @@
|
||||
# shoujo
|
||||
|
||||
少女预设 - Classic shoujo manga with romantic aesthetics
|
||||
|
||||
## Base Configuration
|
||||
|
||||
| Dimension | Value |
|
||||
|-----------|-------|
|
||||
| Art Style | manga |
|
||||
| Tone | romantic |
|
||||
| Layout | standard (default) |
|
||||
|
||||
Equivalent to: art=manga, tone=romantic
|
||||
|
||||
## Unique Rules
|
||||
|
||||
This preset includes special rules beyond the art+tone combination. When the `shoujo` preset is selected, ALL rules below must be applied.
|
||||
|
||||
### Decorative Elements (Required)
|
||||
|
||||
Every emotional moment must include decorative elements:
|
||||
|
||||
| Emotion | Required Decorations |
|
||||
|---------|---------------------|
|
||||
| Love | Floating hearts, sparkles, rose petals |
|
||||
| Longing | Feathers, bubbles, distant sparkles |
|
||||
| Joy | Flowers blooming, light bursts, stars |
|
||||
| Sadness | Falling petals, fading sparkles |
|
||||
| Shyness | Soft sparkles, floating bubbles |
|
||||
| Realization | Radiating lines with sparkles |
|
||||
|
||||
### Eye Detail Requirements
|
||||
|
||||
Eyes are critical in shoujo style:
|
||||
|
||||
| Aspect | Treatment |
|
||||
|--------|-----------|
|
||||
| Size | Larger than standard manga (1.2x) |
|
||||
| Highlights | Multiple (3-5), placed for emotion |
|
||||
| Reflection | Scene reflection in emotional moments |
|
||||
| Sparkle | Built-in sparkle effects |
|
||||
| Tears | Crystalline, detailed teardrops |
|
||||
|
||||
### Character Beauty Standards
|
||||
|
||||
| Feature | Treatment |
|
||||
|---------|-----------|
|
||||
| Hair | Flowing, detailed strands, shine highlights |
|
||||
| Skin | Porcelain, soft blush on cheeks |
|
||||
| Lips | Soft, slightly glossy |
|
||||
| Hands | Elegant, expressive gestures |
|
||||
| Posture | Graceful, elegant poses |
|
||||
|
||||
### Background Effects
|
||||
|
||||
**Abstract backgrounds** for emotional moments:
|
||||
|
||||
| Moment Type | Background |
|
||||
|-------------|-----------|
|
||||
| Love confession | Soft gradient + floating flowers |
|
||||
| Shock | Screen tone speed lines + sparkles |
|
||||
| Memory | Dreamy blur + scattered petals |
|
||||
| Realization | Radial lines + light burst |
|
||||
| Intimate | Soft focus + floating elements |
|
||||
|
||||
### Panel Flow
|
||||
|
||||
- Overlap panels for intimate moments
|
||||
- Break panel borders for emotional impact
|
||||
- Float decorative elements between panels
|
||||
- Use screen tone gradients for mood
|
||||
- Irregular panel shapes for drama
|
||||
|
||||
### Emotional Beat Timing
|
||||
|
||||
Slow down pacing for emotional impact:
|
||||
|
||||
| Scene Type | Panel Treatment |
|
||||
|------------|-----------------|
|
||||
| Confession | Multiple small panels, then splash |
|
||||
| Eye contact | Close-up sequence |
|
||||
| Touch | Slow-motion panel breakdown |
|
||||
| Realization | Build-up panels then impact |
|
||||
|
||||
### Color Palette Application
|
||||
|
||||
| Scene Type | Palette |
|
||||
|------------|---------|
|
||||
| Romantic | Pink, lavender, rose gold |
|
||||
| Happy | Soft yellow, peach, sky blue |
|
||||
| Sad | Pale blue, silver, gray lavender |
|
||||
| Dramatic | Deep rose, purple, contrast |
|
||||
|
||||
### Screen Tone Usage
|
||||
|
||||
| Mood | Tone Pattern |
|
||||
|------|-------------|
|
||||
| Neutral | Clean, minimal |
|
||||
| Romantic | Soft gradient overlays |
|
||||
| Dramatic | Heavy contrast tones |
|
||||
| Dreamy | Soft dot patterns |
|
||||
|
||||
## Quality Markers
|
||||
|
||||
- ✓ Large, sparkling detailed eyes
|
||||
- ✓ Decorative elements in emotional moments
|
||||
- ✓ Flowing, beautiful character designs
|
||||
- ✓ Soft, pastel color palette
|
||||
- ✓ Elegant panel compositions
|
||||
- ✓ Screen tone mood effects
|
||||
- ✓ Romantic atmosphere throughout
|
||||
- ✓ Beautiful, expressive poses
|
||||
|
||||
## Best For
|
||||
|
||||
Romance stories, coming-of-age, friendship narratives, school life, emotional drama, love stories
|
||||
@@ -0,0 +1,110 @@
|
||||
# wuxia
|
||||
|
||||
武侠预设 - Hong Kong martial arts comic style
|
||||
|
||||
## Base Configuration
|
||||
|
||||
| Dimension | Value |
|
||||
|-----------|-------|
|
||||
| Art Style | ink-brush |
|
||||
| Tone | action |
|
||||
| Layout | splash (default) |
|
||||
|
||||
Equivalent to: art=ink-brush, tone=action
|
||||
|
||||
## Unique Rules
|
||||
|
||||
This preset includes special rules beyond the art+tone combination. When the `wuxia` preset is selected, ALL rules below must be applied.
|
||||
|
||||
### Qi/Energy Effects (Required)
|
||||
|
||||
Martial arts power must be visible through qi effects:
|
||||
|
||||
| Effect Type | Visual Treatment |
|
||||
|-------------|-----------------|
|
||||
| Internal qi | Glowing aura around character |
|
||||
| External qi | Visible energy projection |
|
||||
| Qi clash | Radiating impact waves |
|
||||
| Qi absorption | Flowing particles toward character |
|
||||
| Hidden power | Subtle glow in eyes/fists |
|
||||
|
||||
### Energy Colors
|
||||
|
||||
| Qi Type | Color |
|
||||
|---------|-------|
|
||||
| Righteous | Blue (#4299E1), Gold (#FFD700) |
|
||||
| Fierce | Red (#DC2626), Orange (#EA580C) |
|
||||
| Evil | Purple (#7C3AED), Green (#16A34A) |
|
||||
| Pure | White, Silver |
|
||||
| Ancient | Gold with particles |
|
||||
|
||||
### Combat Visual Language
|
||||
|
||||
**Impact moments** must include:
|
||||
|
||||
1. Speed lines radiating from impact point
|
||||
2. Flying debris (stone, wood, cloth)
|
||||
3. Shockwave rings
|
||||
4. Dust/energy clouds
|
||||
5. Hair and clothing blown back
|
||||
|
||||
### Movement Depiction
|
||||
|
||||
| Speed Level | Visual Treatment |
|
||||
|-------------|-----------------|
|
||||
| Normal | Standard pose |
|
||||
| Fast | Motion blur, speed lines |
|
||||
| Lightning | Afterimages, multiple positions |
|
||||
| Teleport | Fade effect, particle trail |
|
||||
|
||||
### Environmental Integration
|
||||
|
||||
Backgrounds must support action:
|
||||
|
||||
| Environment | Combat Enhancement |
|
||||
|-------------|-------------------|
|
||||
| Mountains | Crumbling peaks from impacts |
|
||||
| Forest | Exploding trees, flying leaves |
|
||||
| Water | Dramatic splashes, walking on water |
|
||||
| Temple | Breaking pillars, flying tiles |
|
||||
| Cliff | Dramatic falls, wind effects |
|
||||
|
||||
### Character Pose Guidelines
|
||||
|
||||
- Dynamic warrior stances with weight distribution
|
||||
- Flowing robes and hair showing movement
|
||||
- Muscle tension visible in action
|
||||
- Feet planted or in dynamic motion
|
||||
- Traditional martial arts postures
|
||||
|
||||
### Weapon Effects
|
||||
|
||||
| Weapon | Visual Treatment |
|
||||
|--------|-----------------|
|
||||
| Sword | Trailing light arc, blade glow |
|
||||
| Palm | Qi projection, wind effect |
|
||||
| Staff | Spinning blur, impact ripples |
|
||||
| Whip | Flowing energy trail |
|
||||
|
||||
### Atmospheric Elements
|
||||
|
||||
Always include:
|
||||
- Floating particles (leaves, petals, dust)
|
||||
- Ink wash mist for depth
|
||||
- Wind direction indicators
|
||||
- Dramatic sky/weather when appropriate
|
||||
|
||||
## Quality Markers
|
||||
|
||||
- ✓ Dynamic action poses with sense of motion
|
||||
- ✓ Ink brush aesthetic in line work
|
||||
- ✓ Visible qi/energy effects
|
||||
- ✓ High contrast dramatic lighting
|
||||
- ✓ Atmospheric backgrounds with Chinese elements
|
||||
- ✓ Flowing fabric and hair movement
|
||||
- ✓ Impactful combat moments
|
||||
- ✓ Speed lines and impact effects
|
||||
|
||||
## Best For
|
||||
|
||||
Martial arts stories, Chinese historical fiction, wuxia/xianxia adaptations, action-heavy narratives
|
||||
@@ -0,0 +1,143 @@
|
||||
# Storyboard Template
|
||||
|
||||
## Storyboard Document Format
|
||||
|
||||
```markdown
|
||||
---
|
||||
title: "[Comic Title]"
|
||||
topic: "[topic description]"
|
||||
time_span: "[e.g., 1912-1954]"
|
||||
narrative_approach: "[chronological/thematic/character-focused]"
|
||||
recommended_style: "[style name]"
|
||||
recommended_layout: "[layout name or varies]"
|
||||
aspect_ratio: "3:4" # 3:4 (portrait), 4:3 (landscape), 16:9 (widescreen)
|
||||
language: "[zh/en/ja/etc.]"
|
||||
page_count: [N]
|
||||
generated: "YYYY-MM-DD HH:mm"
|
||||
---
|
||||
|
||||
# [Comic Title] - Knowledge Comic Storyboard
|
||||
|
||||
**Character Reference**: characters/characters.png
|
||||
|
||||
---
|
||||
|
||||
## Cover
|
||||
|
||||
**Filename**: 00-cover-[slug].png
|
||||
**Core Message**: [one-liner]
|
||||
|
||||
**Visual Design**:
|
||||
- Title typography style
|
||||
- Main visual composition
|
||||
- Color scheme
|
||||
- Subtitle / time span notation
|
||||
|
||||
**Visual Prompt**:
|
||||
[Detailed image generation prompt]
|
||||
|
||||
---
|
||||
|
||||
## Page 1 / N
|
||||
|
||||
**Filename**: 01-page-[slug].png
|
||||
**Layout**: [standard/cinematic/dense/splash/mixed]
|
||||
**Narrative Layer**: [Main narrative / Narrator layer / Mixed]
|
||||
**Core Message**: [What this page conveys]
|
||||
|
||||
### Panel Layout
|
||||
|
||||
**Panel Count**: X
|
||||
**Layout Type**: [grid/irregular/splash]
|
||||
|
||||
#### Panel 1 (Size: 1/3 page, Position: Top)
|
||||
|
||||
**Scene**: [Time, location]
|
||||
**Image Description**:
|
||||
- Camera angle: [bird's eye / low angle / eye level / close-up / wide shot]
|
||||
- Characters: [pose, expression, action]
|
||||
- Environment: [scene details, period markers]
|
||||
- Lighting: [atmosphere description]
|
||||
- Color tone: [palette reference]
|
||||
|
||||
**Text Elements**:
|
||||
- Dialogue bubble (oval): "Character line"
|
||||
- Narrator box (rectangular): 「Narrator commentary」
|
||||
- Caption bar: [Background info text]
|
||||
|
||||
#### Panel 2...
|
||||
|
||||
**Page Hook**: [Cliffhanger or transition at page end]
|
||||
|
||||
**Visual Prompt**:
|
||||
[Full page image generation prompt]
|
||||
|
||||
---
|
||||
|
||||
## Page 2 / N
|
||||
...
|
||||
```
|
||||
|
||||
## Cover Design Principles
|
||||
|
||||
- Academic gravitas with visual appeal
|
||||
- Title typography reflecting knowledge/science theme
|
||||
- Composition hinting at core theme (character silhouette, iconic symbol, concept diagram)
|
||||
- Subtitle or time span for epic scope
|
||||
|
||||
## Panel Composition Guidelines
|
||||
|
||||
| Panel Type | Recommended Count | Usage |
|
||||
|-----------|-------------------|-------|
|
||||
| Main narrative | 3-5 per page | Story progression |
|
||||
| Concept diagram | 1-2 per page | Visualize abstractions |
|
||||
| Narrator panel | 0-1 per page | Commentary, transition |
|
||||
| Splash (full/half) | Occasional | Major moments |
|
||||
|
||||
## Panel Size Reference
|
||||
|
||||
- **Full page (Splash)**: Major moments, key breakthroughs
|
||||
- **Half page**: Important scenes, turning points
|
||||
- **1/3 page**: Standard narrative panels
|
||||
- **1/4 or smaller**: Quick progression, sequential action
|
||||
|
||||
## Concept Visualization Techniques
|
||||
|
||||
Transform abstract concepts into concrete visuals:
|
||||
|
||||
| Abstract Concept | Visual Approach |
|
||||
|-----------------|-----------------|
|
||||
| Neural network | Glowing nodes with connecting lines |
|
||||
| Gradient descent | Ball rolling down valley terrain |
|
||||
| Data flow | Luminous particles flowing through pipes |
|
||||
| Algorithm iteration | Ascending spiral staircase |
|
||||
| Breakthrough moment | Shattering barrier, piercing light |
|
||||
| Logical proof | Building blocks assembling |
|
||||
| Uncertainty | Forking paths, fog, multiple shadows |
|
||||
|
||||
## Text Element Design
|
||||
|
||||
| Text Type | Style | Usage |
|
||||
|-----------|-------|-------|
|
||||
| Character dialogue | Oval speech bubble | Main narrative speech |
|
||||
| Narrator commentary | Rectangular box | Explanation, commentary |
|
||||
| Caption bar | Edge-mounted rectangle | Time, location info |
|
||||
| Thought bubble | Cloud shape | Character inner monologue |
|
||||
| Term label | Bold / special color | First appearance of technical terms |
|
||||
|
||||
## Prompt Structure for Consistency
|
||||
|
||||
Each page prompt should include character reference:
|
||||
|
||||
```
|
||||
[CHARACTER REFERENCE]
|
||||
(Key details from characters.md for characters in this page)
|
||||
|
||||
[PAGE CONTENT]
|
||||
(Specific scene, panel layout, and visual elements)
|
||||
|
||||
[CONSISTENCY REMINDER]
|
||||
Maintain exact character appearances as defined in character reference.
|
||||
- [Character A]: [key identifying features]
|
||||
- [Character B]: [key identifying features]
|
||||
```
|
||||
@@ -0,0 +1,110 @@
|
||||
# action
|
||||
|
||||
动作基调 - Speed, impact, power
|
||||
|
||||
## Overview
|
||||
|
||||
High-impact action atmosphere with dynamic movement, combat effects, and powerful visual energy. Creates visceral, exciting sequences.
|
||||
|
||||
## Mood Characteristics
|
||||
|
||||
- Speed and motion
|
||||
- Power and impact
|
||||
- Combat intensity
|
||||
- Physical energy
|
||||
- Visceral excitement
|
||||
|
||||
## Color Modifiers
|
||||
|
||||
When applied to any art style:
|
||||
|
||||
| Adjustment | Direction |
|
||||
|------------|-----------|
|
||||
| Saturation | High contrast |
|
||||
| Contrast | Maximum |
|
||||
| Temperature | Variable per effect |
|
||||
| Brightness | Dynamic range |
|
||||
|
||||
## Action Effects
|
||||
|
||||
**Combat/motion effects** (apply liberally):
|
||||
|
||||
| Effect | Usage |
|
||||
|--------|-------|
|
||||
| Speed lines | Motion, velocity |
|
||||
| Impact bursts | Hits, collisions |
|
||||
| Shockwaves | Powerful impacts |
|
||||
| Flying debris | Environmental destruction |
|
||||
| Dust clouds | Ground impacts |
|
||||
| Motion blur | Fast movement |
|
||||
| Afterimages | Super speed |
|
||||
|
||||
## Special Effects
|
||||
|
||||
| Effect Type | Visual Approach |
|
||||
|------------|-----------------|
|
||||
| Energy attacks | Glowing, radiating |
|
||||
| Physical impacts | Radiating lines, debris |
|
||||
| Movement | Speed lines, blur |
|
||||
| Atmosphere | Flying particles, wind |
|
||||
|
||||
## Effect Colors
|
||||
|
||||
| Effect | Color | Hex |
|
||||
|--------|-------|-----|
|
||||
| Energy glow | Blue | #4299E1 |
|
||||
| Fire/power | Gold | #FFD700 |
|
||||
| Impact | White burst | #FFFFFF |
|
||||
| Blood/intensity | Deep red | #8B0000 |
|
||||
|
||||
## Lighting
|
||||
|
||||
- Dynamic, shifting
|
||||
- Impact flashes
|
||||
- Energy glow sources
|
||||
- Rim lighting on figures
|
||||
- Dramatic contrast
|
||||
|
||||
## Emotional Range
|
||||
|
||||
| Emotion | Expression |
|
||||
|---------|-----------|
|
||||
| Determination | Fierce focus |
|
||||
| Rage | Intense, powerful |
|
||||
| Triumph | Victorious pose |
|
||||
| Struggle | Strained effort |
|
||||
|
||||
## Composition
|
||||
|
||||
- Dynamic angles
|
||||
- Extreme perspectives
|
||||
- Panel-breaking layouts
|
||||
- Asymmetric designs
|
||||
- Impact-focused framing
|
||||
|
||||
## Pose Guidelines
|
||||
|
||||
- Dynamic warrior poses
|
||||
- Weight and momentum visible
|
||||
- Muscle tension shown
|
||||
- Flow of movement captured
|
||||
- Impact points emphasized
|
||||
|
||||
## Best For
|
||||
|
||||
- Martial arts combat
|
||||
- Action sequences
|
||||
- Sports moments
|
||||
- Physical challenges
|
||||
- Battle scenes
|
||||
- Climactic confrontations
|
||||
|
||||
## Combination Notes
|
||||
|
||||
Works especially well with:
|
||||
- ink-brush: wuxia combat
|
||||
- manga: shonen battles
|
||||
|
||||
Avoid with:
|
||||
- chalk: style mismatch
|
||||
- ligne-claire: style mismatch (too static)
|
||||
@@ -0,0 +1,95 @@
|
||||
# dramatic
|
||||
|
||||
戏剧基调 - High contrast, intense, powerful moments
|
||||
|
||||
## Overview
|
||||
|
||||
High-impact dramatic tone for pivotal moments, conflicts, and breakthroughs. Uses strong contrast and intense compositions to create emotional power.
|
||||
|
||||
## Mood Characteristics
|
||||
|
||||
- Tension and intensity
|
||||
- Pivotal moments
|
||||
- Conflict and resolution
|
||||
- Breakthrough discoveries
|
||||
- Emotional climaxes
|
||||
|
||||
## Color Modifiers
|
||||
|
||||
When applied to any art style:
|
||||
|
||||
| Adjustment | Direction |
|
||||
|------------|-----------|
|
||||
| Saturation | High (vibrant or deep) |
|
||||
| Contrast | Maximum |
|
||||
| Temperature | Varies for effect |
|
||||
| Brightness | Strong highlights, deep shadows |
|
||||
|
||||
## Contrast Approach
|
||||
|
||||
- Sharp light/dark divisions
|
||||
- Minimal mid-tones
|
||||
- Stark compositions
|
||||
- Silhouette potential
|
||||
- Rim lighting effects
|
||||
|
||||
## Accent Colors
|
||||
|
||||
- Deep navy (#1A365D)
|
||||
- Crimson (#9B2C2C)
|
||||
- Stark white
|
||||
- Heavy blacks
|
||||
- Limited palette per scene
|
||||
|
||||
## Lighting
|
||||
|
||||
- Dramatic single-source
|
||||
- High contrast shadows
|
||||
- Rim lighting on characters
|
||||
- Spotlight effects
|
||||
- Chiaroscuro influence
|
||||
|
||||
## Emotional Range
|
||||
|
||||
| Emotion | Expression |
|
||||
|---------|-----------|
|
||||
| Anger | Intense, defined features |
|
||||
| Determination | Strong, focused gaze |
|
||||
| Shock | Wide eyes, stark lighting |
|
||||
| Triumph | Powerful, elevated pose |
|
||||
|
||||
## Composition
|
||||
|
||||
- Angular, dynamic layouts
|
||||
- Dramatic camera angles
|
||||
- Low/high viewpoints
|
||||
- Diagonal compositions
|
||||
- Negative space for impact
|
||||
|
||||
## Visual Elements
|
||||
|
||||
- Speed lines for tension
|
||||
- Impact effects
|
||||
- Dramatic backgrounds (storms, fire)
|
||||
- Silhouettes
|
||||
- Light burst effects
|
||||
- Environmental drama
|
||||
|
||||
## Best For
|
||||
|
||||
- Pivotal discoveries
|
||||
- Conflict scenes
|
||||
- Climactic moments
|
||||
- Breakthrough realizations
|
||||
- Emotional confrontations
|
||||
- Historical turning points
|
||||
|
||||
## Combination Notes
|
||||
|
||||
Works especially well with:
|
||||
- realistic: powerful drama
|
||||
- ink-brush: martial arts climax
|
||||
- ligne-claire: historical pivots
|
||||
- manga: shonen battles
|
||||
|
||||
Avoid with: chalk (style mismatch)
|
||||
@@ -0,0 +1,105 @@
|
||||
# energetic
|
||||
|
||||
活力基调 - Bright, dynamic, exciting
|
||||
|
||||
## Overview
|
||||
|
||||
High-energy atmosphere for exciting, discovery-filled content. Bright colors, dynamic compositions, and movement create engaging visuals for younger audiences.
|
||||
|
||||
## Mood Characteristics
|
||||
|
||||
- Excitement and wonder
|
||||
- Discovery and learning
|
||||
- Energy and enthusiasm
|
||||
- Movement and action
|
||||
- Youthful spirit
|
||||
|
||||
## Color Modifiers
|
||||
|
||||
When applied to any art style:
|
||||
|
||||
| Adjustment | Direction |
|
||||
|------------|-----------|
|
||||
| Saturation | High (vibrant) |
|
||||
| Contrast | Medium-high |
|
||||
| Temperature | Variable, punchy |
|
||||
| Brightness | Bright, clean |
|
||||
|
||||
## Color Palette
|
||||
|
||||
Shift toward vibrant tones:
|
||||
|
||||
| Role | Color | Hex |
|
||||
|------|-------|-----|
|
||||
| Primary Red | Bright red | #F56565 |
|
||||
| Primary Yellow | Sunny yellow | #F6E05E |
|
||||
| Primary Blue | Sky blue | #63B3ED |
|
||||
| Accent 1 | Magenta | #D53F8C |
|
||||
| Accent 2 | Lime green | #68D391 |
|
||||
| Background | Clean white | #FFFFFF |
|
||||
| Background Alt | Bright pastels | Various |
|
||||
|
||||
## Lighting
|
||||
|
||||
- Bright, clear lighting
|
||||
- Clean shadows
|
||||
- High energy
|
||||
- Spotlight effects for emphasis
|
||||
- Dynamic light sources
|
||||
|
||||
## Dynamic Elements
|
||||
|
||||
**Energy effects** (add to compositions):
|
||||
|
||||
| Element | Usage |
|
||||
|---------|-------|
|
||||
| Speed lines | Motion, excitement |
|
||||
| Sparkles | Discoveries |
|
||||
| Burst effects | Aha moments |
|
||||
| Motion blur | Fast action |
|
||||
| Star bursts | Emphasis |
|
||||
| Sweat drops | Effort/surprise |
|
||||
|
||||
## Emotional Range
|
||||
|
||||
| Emotion | Expression |
|
||||
|---------|-----------|
|
||||
| Excitement | Wide eyes, big smile |
|
||||
| Surprise | Dramatic reaction |
|
||||
| Determination | Intense focus |
|
||||
| Wonder | Sparkling eyes |
|
||||
|
||||
## Composition
|
||||
|
||||
- Dynamic angles
|
||||
- Action-oriented layouts
|
||||
- Movement emphasis
|
||||
- Clean, punchy designs
|
||||
- Energy flows
|
||||
|
||||
## Visual Style
|
||||
|
||||
- Expressive, animated characters
|
||||
- Wide eyes, big reactions
|
||||
- Dynamic poses
|
||||
- Motion and action focus
|
||||
- Simplified backgrounds for energy
|
||||
|
||||
## Best For
|
||||
|
||||
- Science explanations
|
||||
- "Aha" moments
|
||||
- Young audience content
|
||||
- Discovery narratives
|
||||
- Learning adventures
|
||||
- Action tutorials
|
||||
|
||||
## Combination Notes
|
||||
|
||||
Works especially well with:
|
||||
- manga: shonen energy
|
||||
- chalk: fun education
|
||||
|
||||
Avoid with:
|
||||
- realistic: style mismatch
|
||||
- ink-brush: style mismatch
|
||||
@@ -0,0 +1,63 @@
|
||||
# neutral
|
||||
|
||||
中性基调 - Balanced, rational, educational
|
||||
|
||||
## Overview
|
||||
|
||||
Default balanced tone suitable for educational and informative content. Neither overly emotional nor cold - creates accessible, professional atmosphere.
|
||||
|
||||
## Mood Characteristics
|
||||
|
||||
- Balanced emotional register
|
||||
- Clear, rational presentation
|
||||
- Educational focus
|
||||
- Professional but approachable
|
||||
- Objective storytelling
|
||||
|
||||
## Color Modifiers
|
||||
|
||||
When applied to any art style:
|
||||
|
||||
| Adjustment | Direction |
|
||||
|------------|-----------|
|
||||
| Saturation | Standard (no shift) |
|
||||
| Contrast | Balanced |
|
||||
| Temperature | Neutral |
|
||||
| Brightness | Slightly bright |
|
||||
|
||||
## Lighting
|
||||
|
||||
- Even, clear lighting
|
||||
- Minimal dramatic shadows
|
||||
- Consistent across panels
|
||||
- Natural light sources
|
||||
- No extreme contrast
|
||||
|
||||
## Emotional Range
|
||||
|
||||
| Emotion | Expression Level |
|
||||
|---------|-----------------|
|
||||
| Joy | Moderate smile |
|
||||
| Concern | Thoughtful expression |
|
||||
| Surprise | Mild widening of eyes |
|
||||
| Frustration | Slight frown |
|
||||
|
||||
## Composition
|
||||
|
||||
- Balanced panel layouts
|
||||
- Clear focal points
|
||||
- Readable hierarchies
|
||||
- Standard framing
|
||||
- Functional compositions
|
||||
|
||||
## Best For
|
||||
|
||||
- Educational content
|
||||
- Technical tutorials
|
||||
- Informative biographies
|
||||
- Documentary style
|
||||
- Professional topics
|
||||
|
||||
## Usage Notes
|
||||
|
||||
Neutral is the default tone. Combine with any art style for baseline professional output. Most versatile tone option.
|
||||
@@ -0,0 +1,100 @@
|
||||
# romantic
|
||||
|
||||
浪漫基调 - Soft, beautiful, emotionally delicate
|
||||
|
||||
## Overview
|
||||
|
||||
Soft, dreamy atmosphere for romantic and emotionally delicate content. Features decorative elements, sparkles, and beautiful compositions that emphasize feeling and beauty.
|
||||
|
||||
## Mood Characteristics
|
||||
|
||||
- Romance and love
|
||||
- Beauty and elegance
|
||||
- Emotional delicacy
|
||||
- Dreams and hopes
|
||||
- Youth and idealism
|
||||
|
||||
## Color Modifiers
|
||||
|
||||
When applied to any art style:
|
||||
|
||||
| Adjustment | Direction |
|
||||
|------------|-----------|
|
||||
| Saturation | Soft pastels |
|
||||
| Contrast | Low, gentle |
|
||||
| Temperature | Slightly warm pink |
|
||||
| Brightness | Soft, glowing |
|
||||
|
||||
## Color Palette
|
||||
|
||||
Shift toward romantic tones:
|
||||
|
||||
| Role | Color | Hex |
|
||||
|------|-------|-----|
|
||||
| Primary | Soft pink | #FFB6C1 |
|
||||
| Secondary | Lavender | #E6E6FA |
|
||||
| Accent | Rose | #FF69B4 |
|
||||
| Highlight | Pearl white | #FFFAF0 |
|
||||
| Gold | Gold sparkle | #FFD700 |
|
||||
| Skin | Porcelain | #FFF5EE |
|
||||
| Blush | Soft blush | #FFE4E1 |
|
||||
| Background | Soft cream | #FFF8DC |
|
||||
|
||||
## Lighting
|
||||
|
||||
- Soft, diffused light
|
||||
- Glowing effects
|
||||
- Backlighting halos
|
||||
- Sparkle highlights
|
||||
- Dreamy atmospheres
|
||||
|
||||
## Decorative Elements
|
||||
|
||||
**Essential decorations** (add to compositions):
|
||||
|
||||
| Element | Usage |
|
||||
|---------|-------|
|
||||
| Flower petals | Floating, framing |
|
||||
| Sparkles | Emotional highlights |
|
||||
| Bubbles | Dreamy moments |
|
||||
| Feathers | Gentle floating |
|
||||
| Stars | Night scenes, wonder |
|
||||
| Hearts | Love emphasis |
|
||||
| Light halos | Character highlights |
|
||||
|
||||
## Emotional Range
|
||||
|
||||
| Emotion | Expression |
|
||||
|---------|-----------|
|
||||
| Love | Soft gaze, blush |
|
||||
| Longing | Distant, beautiful sadness |
|
||||
| Joy | Radiant smile, sparkles |
|
||||
| Shyness | Downcast eyes, blush |
|
||||
|
||||
## Composition
|
||||
|
||||
- Elegant, flowing layouts
|
||||
- Soft focus backgrounds
|
||||
- Characters framed by decorations
|
||||
- Beautiful angles (3/4 profiles)
|
||||
- Screen tone gradients
|
||||
|
||||
## Best For
|
||||
|
||||
- Romance stories
|
||||
- Coming-of-age
|
||||
- Friendship narratives
|
||||
- Emotional drama
|
||||
- School life
|
||||
- Beautiful moments
|
||||
|
||||
## Combination Notes
|
||||
|
||||
Works especially well with:
|
||||
- manga: classic shoujo style
|
||||
|
||||
Avoid with:
|
||||
- realistic: style mismatch
|
||||
- ink-brush: style mismatch
|
||||
- ligne-claire: style mismatch
|
||||
- chalk: style mismatch
|
||||
@@ -0,0 +1,104 @@
|
||||
# vintage
|
||||
|
||||
复古基调 - Historical, aged, period authenticity
|
||||
|
||||
## Overview
|
||||
|
||||
Historical atmosphere with aged paper effects and period-appropriate aesthetics. Creates sense of time, authenticity, and historical distance.
|
||||
|
||||
## Mood Characteristics
|
||||
|
||||
- Historical authenticity
|
||||
- Period distance
|
||||
- Archival quality
|
||||
- Time and memory
|
||||
- Classical elegance
|
||||
|
||||
## Color Modifiers
|
||||
|
||||
When applied to any art style:
|
||||
|
||||
| Adjustment | Direction |
|
||||
|------------|-----------|
|
||||
| Saturation | Reduced, muted |
|
||||
| Contrast | Medium, aged |
|
||||
| Temperature | Sepia shift |
|
||||
| Brightness | Slightly faded |
|
||||
|
||||
## Color Palette
|
||||
|
||||
Shift toward aged tones:
|
||||
|
||||
| Role | Color | Hex |
|
||||
|------|-------|-----|
|
||||
| Primary | Sepia brown | #8B7355 |
|
||||
| Background | Aged paper | #F5E6D3 |
|
||||
| Accent 1 | Faded teal | #6B8E8E |
|
||||
| Accent 2 | Muted burgundy | #7B3F3F |
|
||||
| Ink | Aged black | #3D3D3D |
|
||||
| Yellowed | Paper yellow | #F5DEB3 |
|
||||
|
||||
## Visual Effects
|
||||
|
||||
**Aging effects** (apply subtly):
|
||||
|
||||
| Effect | Application |
|
||||
|--------|-------------|
|
||||
| Paper aging | Background texture |
|
||||
| Faded edges | Vignette effect |
|
||||
| Dust specks | Subtle overlay |
|
||||
| Yellowing | Color shift |
|
||||
| Wear marks | Corner/edge details |
|
||||
|
||||
## Period Elements
|
||||
|
||||
- Historical typography
|
||||
- Period-accurate details
|
||||
- Archival presentation
|
||||
- Classical compositions
|
||||
- Formal framing
|
||||
|
||||
## Lighting
|
||||
|
||||
- Natural, period-appropriate
|
||||
- Oil lamp/candle warmth
|
||||
- Soft, diffused light
|
||||
- Indoor historical lighting
|
||||
- Photographic quality
|
||||
|
||||
## Emotional Range
|
||||
|
||||
| Emotion | Expression |
|
||||
|---------|-----------|
|
||||
| Dignity | Formal, composed |
|
||||
| Sorrow | Restrained, elegant |
|
||||
| Pride | Classical posture |
|
||||
| Wisdom | Aged grace |
|
||||
|
||||
## Composition
|
||||
|
||||
- Classical framing
|
||||
- Formal compositions
|
||||
- Period-appropriate staging
|
||||
- Documentary style
|
||||
- Historical accuracy priority
|
||||
|
||||
## Best For
|
||||
|
||||
- Pre-1950s stories
|
||||
- Classical science history
|
||||
- Historical biographies
|
||||
- Period pieces
|
||||
- Documentary comics
|
||||
- Archival narratives
|
||||
|
||||
## Combination Notes
|
||||
|
||||
Works especially well with:
|
||||
- realistic: period drama
|
||||
- ligne-claire: historical adventure
|
||||
- ink-brush: classical Asian stories
|
||||
|
||||
Avoid with:
|
||||
- manga: style mismatch (too modern)
|
||||
- chalk: style mismatch (modern educational)
|
||||
@@ -0,0 +1,94 @@
|
||||
# warm
|
||||
|
||||
温馨基调 - Nostalgic, personal, comforting
|
||||
|
||||
## Overview
|
||||
|
||||
Warm, inviting atmosphere for personal stories and nostalgic content. Creates emotional connection through cozy aesthetics and comforting visuals.
|
||||
|
||||
## Mood Characteristics
|
||||
|
||||
- Nostalgic feeling
|
||||
- Personal, intimate atmosphere
|
||||
- Comforting and healing
|
||||
- Memory and reflection
|
||||
- Gentle emotional warmth
|
||||
|
||||
## Color Modifiers
|
||||
|
||||
When applied to any art style:
|
||||
|
||||
| Adjustment | Direction |
|
||||
|------------|-----------|
|
||||
| Saturation | Slightly reduced |
|
||||
| Contrast | Softer |
|
||||
| Temperature | Warm shift (+15%) |
|
||||
| Brightness | Soft, golden |
|
||||
|
||||
## Color Temperature
|
||||
|
||||
Shift palette toward warm tones:
|
||||
|
||||
| Original | Warm Shift |
|
||||
|----------|-----------|
|
||||
| Cool blue | Soft teal |
|
||||
| Pure white | Cream |
|
||||
| Gray | Warm gray |
|
||||
| Black | Soft charcoal |
|
||||
|
||||
## Accent Colors
|
||||
|
||||
- Golden yellow (#D69E2E)
|
||||
- Soft orange (#DD6B20)
|
||||
- Warm brown (#8B6F47)
|
||||
- Sunset tones
|
||||
|
||||
## Lighting
|
||||
|
||||
- Golden hour lighting
|
||||
- Soft, diffused light
|
||||
- Warm indoor glow
|
||||
- Candle/lamp warmth
|
||||
- Gentle shadows
|
||||
|
||||
## Emotional Range
|
||||
|
||||
| Emotion | Expression |
|
||||
|---------|-----------|
|
||||
| Joy | Genuine warm smile |
|
||||
| Sadness | Gentle melancholy |
|
||||
| Love | Soft, tender expressions |
|
||||
| Memory | Distant, reflective gaze |
|
||||
|
||||
## Composition
|
||||
|
||||
- Intimate framing
|
||||
- Cozy environments
|
||||
- Soft focus backgrounds
|
||||
- Welcoming spaces
|
||||
- Personal moments highlighted
|
||||
|
||||
## Visual Elements
|
||||
|
||||
- Warm light rays
|
||||
- Soft edges
|
||||
- Nostalgic props (old photos, keepsakes)
|
||||
- Comfort objects (blankets, tea cups)
|
||||
- Nature elements (autumn leaves, sunset)
|
||||
|
||||
## Best For
|
||||
|
||||
- Personal stories
|
||||
- Childhood memories
|
||||
- Mentorship narratives
|
||||
- Family histories
|
||||
- Gentle biographies
|
||||
- Healing journeys
|
||||
|
||||
## Combination Notes
|
||||
|
||||
Works especially well with:
|
||||
- ligne-claire: nostalgic European comics
|
||||
- realistic: touching human stories
|
||||
- manga: slice-of-life warmth
|
||||
- chalk: nostalgic education
|
||||
@@ -0,0 +1,401 @@
|
||||
# Complete Workflow
|
||||
|
||||
Full workflow for generating knowledge comics.
|
||||
|
||||
## Progress Checklist
|
||||
|
||||
Copy and track progress:
|
||||
|
||||
```
|
||||
Comic Progress:
|
||||
- [ ] Step 1: Setup & Analyze
|
||||
- [ ] 1.1 Analyze content
|
||||
- [ ] 1.2 Check existing ⚠️ REQUIRED
|
||||
- [ ] Step 2: Confirmation - Style & options ⚠️ REQUIRED
|
||||
- [ ] Step 3: Generate storyboard + characters
|
||||
- [ ] Step 4: Review outline (conditional)
|
||||
- [ ] Step 5: Generate prompts
|
||||
- [ ] Step 6: Review prompts (conditional)
|
||||
- [ ] Step 7: Generate images
|
||||
- [ ] 7.1 Character sheet (if needed)
|
||||
- [ ] 7.2 Generate pages
|
||||
- [ ] Step 8: Completion report
|
||||
```
|
||||
|
||||
## Flow Diagram
|
||||
|
||||
```
|
||||
Input → Analyze → [Check Existing?] → [Confirm: Style + Reviews] → Storyboard → [Review Outline?] → Prompts → [Review Prompts?] → Images → Complete
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Step 1: Setup & Analyze
|
||||
|
||||
### 1.1 Analyze Content → `analysis.md`
|
||||
|
||||
Read source content, save it if needed, and perform deep analysis.
|
||||
|
||||
**Actions**:
|
||||
1. **Save source content** (if not already a file):
|
||||
- If user provides a file path: use as-is
|
||||
- If user pastes content: save to `source-{slug}.md` in the target directory using `write_file`, where `{slug}` is the kebab-case topic slug used for the output directory
|
||||
- **Backup rule**: If `source-{slug}.md` already exists, rename it to `source-{slug}-backup-YYYYMMDD-HHMMSS.md` before writing
|
||||
2. Read source content
|
||||
3. **Deep analysis** following `analysis-framework.md`:
|
||||
- Target audience identification
|
||||
- Value proposition for readers
|
||||
- Core themes and narrative potential
|
||||
- Key figures and their story arcs
|
||||
4. Detect source language
|
||||
5. **Determine language**:
|
||||
- If user specified a language → use it
|
||||
- Else → use detected source language or user's conversation language
|
||||
6. Determine recommended page count:
|
||||
- Short story: 5-8 pages
|
||||
- Medium complexity: 9-15 pages
|
||||
- Full biography: 16-25 pages
|
||||
7. Analyze content signals for art/tone/layout recommendations
|
||||
8. **Save to `analysis.md`** using `write_file`
|
||||
|
||||
**analysis.md Format**: YAML front matter (title, topic, time_span, source_language, user_language, aspect_ratio, recommended_page_count, recommended_art, recommended_tone) + sections for Target Audience, Value Proposition, Core Themes, Key Figures & Story Arcs, Content Signals, Recommended Approaches. See `analysis-framework.md` for full template.
|
||||
|
||||
### 1.2 Check Existing Content ⚠️ REQUIRED
|
||||
|
||||
**MUST execute before proceeding to Step 2.**
|
||||
|
||||
Check if the output directory exists (e.g., via `test -d "comic/{topic-slug}"`).
|
||||
|
||||
**If directory exists**, use `clarify`:
|
||||
|
||||
```
|
||||
question: "Existing content found at comic/{topic-slug}. How to proceed?"
|
||||
options:
|
||||
- "Regenerate storyboard — Keep images, regenerate storyboard and characters only"
|
||||
- "Regenerate images — Keep storyboard, regenerate images only"
|
||||
- "Backup and regenerate — Backup to {slug}-backup-{timestamp}, then regenerate all"
|
||||
- "Exit — Cancel, keep existing content unchanged"
|
||||
```
|
||||
|
||||
Save result and handle accordingly:
|
||||
- **Regenerate storyboard**: Skip to Step 3, preserve `prompts/` and images
|
||||
- **Regenerate images**: Skip to Step 7, use existing prompts
|
||||
- **Backup and regenerate**: Move directory, start fresh from Step 2
|
||||
- **Exit**: End workflow immediately
|
||||
|
||||
---
|
||||
|
||||
## Step 2: Confirmation - Style & Options ⚠️
|
||||
|
||||
**Purpose**: Select visual style + decide whether to review outline before generation. **Do NOT skip.**
|
||||
|
||||
**Display summary first**:
|
||||
- Content type + topic identified
|
||||
- Key figures extracted
|
||||
- Time span detected
|
||||
- Recommended page count
|
||||
- Language (detected or user-specified)
|
||||
- **Recommended style**: [art] + [tone] (based on content signals)
|
||||
|
||||
**Use `clarify` one question at a time**, in priority order:
|
||||
|
||||
> **Timeout handling (CRITICAL)**: if `clarify` returns `"The user did not provide a response within the time limit. Use your best judgement..."`, that is a per-question default, NOT blanket consent. Continue to the next question in the sequence — do not bail out of Step 2. Then, in your next user-visible message, explicitly surface every default that was taken (e.g. `"Defaulted style → ohmsha, narrative focus → concept explanation, audience → developers (clarify timed out on all three). Say the word to redirect."`). An unreported default is indistinguishable to the user from "the agent never asked."
|
||||
|
||||
### Question 1: Visual Style
|
||||
|
||||
If a preset is recommended (see `auto-selection.md`), show it first:
|
||||
|
||||
```
|
||||
question: "Which visual style for this comic?"
|
||||
options:
|
||||
- "[preset name] preset (Recommended) — [preset description] with special rules"
|
||||
- "[recommended art] + [recommended tone] (Recommended) — Best match for your content"
|
||||
- "ligne-claire + neutral — Classic educational, Logicomix style"
|
||||
- "ohmsha preset — Educational manga with visual metaphors, gadgets, NO talking heads"
|
||||
- "Custom — Specify your own art + tone or preset"
|
||||
```
|
||||
|
||||
**Preset vs Art+Tone**: Presets include special rules beyond art+tone. `ohmsha` = manga + neutral + visual metaphor rules + character roles + NO talking heads. Plain `manga + neutral` does NOT include these rules.
|
||||
|
||||
### Question 2: Narrative Focus
|
||||
|
||||
```
|
||||
question: "What should the comic emphasize? (Pick the primary focus; mention others in a follow-up if needed)"
|
||||
options:
|
||||
- "Biography/life story — Follow a person's journey through key life events"
|
||||
- "Concept explanation — Break down complex ideas visually"
|
||||
- "Historical event — Dramatize important historical moments"
|
||||
- "Tutorial/how-to — Step-by-step educational guide"
|
||||
```
|
||||
|
||||
### Question 3: Target Audience
|
||||
|
||||
```
|
||||
question: "Who is the primary reader?"
|
||||
options:
|
||||
- "General readers — Broad appeal, accessible content"
|
||||
- "Students/learners — Educational focus, clear explanations"
|
||||
- "Industry professionals — Technical depth, domain knowledge"
|
||||
- "Children/young readers — Simplified language, engaging visuals"
|
||||
```
|
||||
|
||||
### Question 4: Outline Review
|
||||
|
||||
```
|
||||
question: "Do you want to review the outline before image generation?"
|
||||
options:
|
||||
- "Yes, let me review (Recommended) — Review storyboard and characters before generating images"
|
||||
- "No, generate directly — Skip outline review, start generating immediately"
|
||||
```
|
||||
|
||||
### Question 5: Prompt Review
|
||||
|
||||
```
|
||||
question: "Review prompts before generating images?"
|
||||
options:
|
||||
- "Yes, review prompts (Recommended) — Review image generation prompts before generating"
|
||||
- "No, skip prompt review — Proceed directly to image generation"
|
||||
```
|
||||
|
||||
**After responses**:
|
||||
1. Update `analysis.md` with user preferences
|
||||
2. **Store `skip_outline_review`** flag based on Question 4 response
|
||||
3. **Store `skip_prompt_review`** flag based on Question 5 response
|
||||
4. → Step 3
|
||||
|
||||
---
|
||||
|
||||
## Step 3: Generate Storyboard + Characters
|
||||
|
||||
Create storyboard and character definitions using the confirmed style from Step 2.
|
||||
|
||||
**Loading Style References**:
|
||||
- Art style: `art-styles/{art}.md`
|
||||
- Tone: `tones/{tone}.md`
|
||||
- If preset (ohmsha/wuxia/shoujo/concept-story/four-panel): also load `presets/{preset}.md`
|
||||
|
||||
**Generate**:
|
||||
|
||||
1. **Storyboard** (`storyboard.md`):
|
||||
- YAML front matter with art_style, tone, layout, aspect_ratio
|
||||
- Cover design
|
||||
- Each page: layout, panel breakdown, visual prompts
|
||||
- **Written in user's preferred language** (from Step 1)
|
||||
- Reference: `storyboard-template.md`
|
||||
- **If using preset**: Load and apply preset rules from `presets/`
|
||||
|
||||
2. **Character definitions** (`characters/characters.md`):
|
||||
- Visual specs matching the art style (in user's preferred language)
|
||||
- Include Reference Sheet Prompt for later image generation
|
||||
- Reference: `character-template.md`
|
||||
- **If using ohmsha preset**: Use default Doraemon characters (see below)
|
||||
|
||||
**Ohmsha Default Characters** (use these unless user specifies custom characters):
|
||||
|
||||
| Role | Character | Visual Description |
|
||||
|------|-----------|-------------------|
|
||||
| Student | 大雄 (Nobita) | Japanese boy, 10yo, round glasses, black hair parted in middle, yellow shirt, navy shorts |
|
||||
| Mentor | 哆啦 A 梦 (Doraemon) | Round blue robot cat, big white eyes, red nose, whiskers, white belly with 4D pocket, golden bell, no ears |
|
||||
| Challenge | 胖虎 (Gian) | Stocky boy, rough features, small eyes, orange shirt |
|
||||
| Support | 静香 (Shizuka) | Cute girl, black short hair, pink dress, gentle expression |
|
||||
|
||||
These are the canonical ohmsha-style characters. Do NOT create custom characters for ohmsha unless explicitly requested.
|
||||
|
||||
**After generation**:
|
||||
- If `skip_outline_review` is true → Skip Step 4, go directly to Step 5
|
||||
- If `skip_outline_review` is false → Continue to Step 4
|
||||
|
||||
---
|
||||
|
||||
## Step 4: Review Outline (Conditional)
|
||||
|
||||
**Skip this step** if user selected "No, generate directly" in Step 2.
|
||||
|
||||
**Purpose**: User reviews and confirms storyboard + characters before generation.
|
||||
|
||||
**Display**:
|
||||
- Page count and structure
|
||||
- Art style + Tone combination
|
||||
- Page-by-page summary (Cover → P1 → P2...)
|
||||
- Character list with brief descriptions
|
||||
|
||||
**Use `clarify`**:
|
||||
|
||||
```
|
||||
question: "Ready to generate images with this outline?"
|
||||
options:
|
||||
- "Yes, proceed (Recommended) — Generate character sheet and comic pages"
|
||||
- "Edit storyboard first — I'll modify storyboard.md before continuing"
|
||||
- "Edit characters first — I'll modify characters/characters.md before continuing"
|
||||
- "Edit both — I'll modify both files before continuing"
|
||||
```
|
||||
|
||||
**After response**:
|
||||
1. If user wants to edit → Wait for user to finish editing, then ask again
|
||||
2. If user confirms → Continue to Step 5
|
||||
|
||||
---
|
||||
|
||||
## Step 5: Generate Prompts
|
||||
|
||||
Create image generation prompts for all pages.
|
||||
|
||||
**Style Reference Loading**:
|
||||
- Read `art-styles/{art}.md` for rendering guidelines
|
||||
- Read `tones/{tone}.md` for mood/color adjustments
|
||||
- If preset: Read `presets/{preset}.md` for special rules
|
||||
|
||||
**For each page (cover + pages)**:
|
||||
1. Create prompt following art style + tone guidelines
|
||||
2. **Embed character descriptions** inline (copy relevant traits from `characters/characters.md`) — `image_generate` is prompt-only, so the prompt text is the sole vehicle for character consistency
|
||||
3. Save to `prompts/NN-{cover|page}-[slug].md` using `write_file`
|
||||
- **Backup rule**: If prompt file exists, rename to `prompts/NN-{cover|page}-[slug]-backup-YYYYMMDD-HHMMSS.md`
|
||||
|
||||
**Prompt File Format**:
|
||||
```markdown
|
||||
# Page NN: [Title]
|
||||
|
||||
## Visual Style
|
||||
Art: [art style] | Tone: [tone] | Layout: [layout type]
|
||||
|
||||
## Character Reference (embedded inline — maintain exact traits below)
|
||||
- [Character A]: [detailed visual traits from characters/characters.md]
|
||||
- [Character B]: [detailed visual traits from characters/characters.md]
|
||||
|
||||
## Panel Breakdown
|
||||
[From storyboard.md - panel descriptions, actions, dialogue]
|
||||
|
||||
## Generation Prompt
|
||||
[Combined prompt passed to image_generate]
|
||||
```
|
||||
|
||||
**After generation**:
|
||||
- If `skip_prompt_review` is true → Skip Step 6, go directly to Step 7
|
||||
- If `skip_prompt_review` is false → Continue to Step 6
|
||||
|
||||
---
|
||||
|
||||
## Step 6: Review Prompts (Conditional)
|
||||
|
||||
**Skip this step** if user selected "No, skip prompt review" in Step 2.
|
||||
|
||||
**Purpose**: User reviews and confirms prompts before image generation.
|
||||
|
||||
**Display prompt summary table**:
|
||||
|
||||
| Page | Title | Key Elements |
|
||||
|------|-------|--------------|
|
||||
| Cover | [title] | [main visual] |
|
||||
| P1 | [title] | [key elements] |
|
||||
| ... | ... | ... |
|
||||
|
||||
**Use `clarify`**:
|
||||
|
||||
```
|
||||
question: "Ready to generate images with these prompts?"
|
||||
options:
|
||||
- "Yes, proceed (Recommended) — Generate all comic page images"
|
||||
- "Edit prompts first — I'll modify prompts/*.md before continuing"
|
||||
- "Regenerate prompts — Regenerate all prompts with different approach"
|
||||
```
|
||||
|
||||
**After response**:
|
||||
1. If user wants to edit → Wait for user to finish editing, then ask again
|
||||
2. If user wants to regenerate → Go back to Step 5
|
||||
3. If user confirms → Continue to Step 7
|
||||
|
||||
---
|
||||
|
||||
## Step 7: Generate Images
|
||||
|
||||
With confirmed prompts from Step 5/6, use the `image_generate` tool. The tool accepts only `prompt` and `aspect_ratio` (`landscape` | `portrait` | `square`) and **returns a URL** — it does not accept reference images and does not write local files. Every invocation must be followed by a download step.
|
||||
|
||||
**Aspect ratio mapping** — map the storyboard's `aspect_ratio` to the tool's enum:
|
||||
|
||||
| Storyboard ratio | `image_generate` format |
|
||||
|------------------|-------------------------|
|
||||
| `3:4`, `9:16`, `2:3` | `portrait` |
|
||||
| `4:3`, `16:9`, `3:2` | `landscape` |
|
||||
| `1:1` | `square` |
|
||||
|
||||
**Download procedure** (run after every successful `image_generate` call):
|
||||
|
||||
1. Extract the `url` field from the tool result
|
||||
2. Fetch it to disk, e.g. `curl -fsSL "<url>" -o comic/{slug}/<target>.png`
|
||||
3. Verify the file is non-empty (`test -s <target>.png`); on failure, retry the generation once
|
||||
|
||||
### 7.1 Generate Character Reference Sheet (conditional)
|
||||
|
||||
Character sheet is recommended for multi-page comics with recurring characters, but **NOT required** for all presets.
|
||||
|
||||
**When to generate**:
|
||||
|
||||
| Condition | Action |
|
||||
|-----------|--------|
|
||||
| Multi-page comic with detailed/recurring characters | Generate character sheet (recommended) |
|
||||
| Preset with simplified characters (e.g., four-panel minimalist) | Skip — prompt descriptions are sufficient |
|
||||
| Single-page comic | Skip unless characters are complex |
|
||||
|
||||
**When generating**:
|
||||
1. Use Reference Sheet Prompt from `characters/characters.md`
|
||||
2. **Backup rule**: If `characters/characters.png` exists, rename to `characters/characters-backup-YYYYMMDD-HHMMSS.png`
|
||||
3. Call `image_generate` with `landscape` format
|
||||
4. Download the returned URL → save to `characters/characters.png`
|
||||
|
||||
**Important**: the downloaded sheet is a **human-facing review artifact** (so the user can visually verify character design) and a reference for later regenerations or manual prompt edits. It does **not** drive Step 7.2 — page prompts were already written in Step 5 from the text descriptions in `characters/characters.md`. `image_generate` cannot accept images as visual input, so the text is the sole cross-page consistency mechanism.
|
||||
|
||||
### 7.2 Generate Comic Pages
|
||||
|
||||
**Before generating any page**:
|
||||
1. Confirm each prompt file exists at `prompts/NN-{cover|page}-[slug].md`
|
||||
2. Confirm that each prompt has character descriptions embedded inline (see Step 5). `image_generate` is prompt-only, so the prompt text is the sole consistency mechanism.
|
||||
|
||||
**Page Generation Strategy**: every page prompt must embed character descriptions (sourced from `characters/characters.md`) inline. This is done during Step 5, uniformly whether or not the PNG sheet was produced in 7.1 — the PNG is only a review/regeneration aid, never a generation input.
|
||||
|
||||
**Example embedded prompt** (`prompts/01-page-xxx.md`):
|
||||
|
||||
```markdown
|
||||
# Page 01: [Title]
|
||||
|
||||
## Character Reference (embedded inline — maintain consistency)
|
||||
- 大雄：Japanese boy, round glasses, yellow shirt, navy shorts, worried expression...
|
||||
- 哆啦 A 梦：Round blue robot cat, white belly, red nose, golden bell, 4D pocket...
|
||||
|
||||
## Page Content
|
||||
[Original page prompt body — panels, dialogue, visual metaphors]
|
||||
```
|
||||
|
||||
**For each page (cover + pages)**:
|
||||
1. Read prompt from `prompts/NN-{cover|page}-[slug].md`
|
||||
2. **Backup rule**: If image file exists, rename to `NN-{cover|page}-[slug]-backup-YYYYMMDD-HHMMSS.png`
|
||||
3. Call `image_generate` with the prompt text and mapped aspect ratio
|
||||
4. Download the returned URL → save to `NN-{cover|page}-[slug].png`
|
||||
5. Report progress after each generation: "Generated X/N: [page title]"
|
||||
|
||||
---
|
||||
|
||||
## Step 8: Completion Report
|
||||
|
||||
```
|
||||
Comic Complete!
|
||||
Title: [title] | Art: [art] | Tone: [tone] | Pages: [count] | Aspect: [ratio] | Language: [lang]
|
||||
Location: [path]
|
||||
✓ source-{slug}.md (if content was pasted)
|
||||
✓ analysis.md
|
||||
✓ characters.png (if generated)
|
||||
✓ 00-cover-[slug].png ... NN-page-[slug].png
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Page Modification
|
||||
|
||||
| Action | Steps |
|
||||
|--------|-------|
|
||||
| **Edit** | Update prompt → Regenerate image → Download new PNG |
|
||||
| **Add** | Create prompt at position → Generate image → Download PNG → Renumber subsequent (NN+1) → Update storyboard |
|
||||
| **Delete** | Remove files → Renumber subsequent (NN-1) → Update storyboard |
|
||||
|
||||
**File naming**: `NN-{cover|page}-[slug].png` (e.g., `03-page-enigma-machine.png`)
|
||||
- Slugs: kebab-case, unique, derived from content
|
||||
- Renumbering: Update NN prefix only, slugs unchanged
|
||||
@@ -0,0 +1,612 @@
|
||||
---
|
||||
name: comfyui
|
||||
description: Generate images, video, and audio via diffusion workflows.
|
||||
version: 5.1.0
|
||||
author: [kshitijk4poor, alt-glitch, purzbeats]
|
||||
license: MIT
|
||||
platforms: [macos, linux, windows]
|
||||
compatibility: "Requires ComfyUI (local, Comfy Desktop, or Comfy Cloud) and comfy-cli (auto-installed via pipx/uvx by the setup script)."
|
||||
prerequisites:
|
||||
commands: ["python"]
|
||||
setup:
|
||||
help: "Run scripts/hardware_check.py FIRST to decide local vs Comfy Cloud; then scripts/comfyui_setup.sh auto-installs locally (or use Cloud API key for platform.comfy.org)."
|
||||
metadata:
|
||||
hermes:
|
||||
tags:
|
||||
- comfyui
|
||||
- image-generation
|
||||
- stable-diffusion
|
||||
- flux
|
||||
- sd3
|
||||
- wan-video
|
||||
- hunyuan-video
|
||||
- creative
|
||||
- generative-ai
|
||||
- video-generation
|
||||
related_skills: [stable-diffusion]
|
||||
category: creative
|
||||
---
|
||||
|
||||
# ComfyUI
|
||||
|
||||
Generate images, video, audio, and 3D content through ComfyUI using the
|
||||
official `comfy-cli` for setup/lifecycle and direct REST/WebSocket API
|
||||
for workflow execution.
|
||||
|
||||
## What's in this skill
|
||||
|
||||
**Reference docs (`references/`):**
|
||||
|
||||
- `official-cli.md` — every `comfy ...` command, with flags
|
||||
- `rest-api.md` — REST + WebSocket endpoints (local + cloud), payload schemas
|
||||
- `workflow-format.md` — API-format JSON, common node types, param mapping
|
||||
- `template-integrity.md` — converting `comfyui-workflow-templates` from
|
||||
editor format to API format: Reroute bypass, dotted dynamic-input keys
|
||||
(`values.a`, `resize_type.width`), Cloud quirks (302 redirect, 1 concurrent
|
||||
free-tier job, 1080p VRAM ceiling), Discord-compatible ffmpeg stitch.
|
||||
Authored by [@purzbeats](https://github.com/purzbeats). Load this whenever
|
||||
you're starting from an official template.
|
||||
|
||||
**Scripts (`scripts/`):**
|
||||
|
||||
| Script | Purpose |
|
||||
|--------|---------|
|
||||
| `_common.py` | Shared HTTP, cloud routing, node catalogs (don't run directly) |
|
||||
| `hardware_check.py` | Probe GPU/VRAM/disk → recommend local vs Comfy Cloud |
|
||||
| `comfyui_setup.sh` | Hardware check + comfy-cli + ComfyUI install + launch + verify |
|
||||
| `extract_schema.py` | Read a workflow → list controllable params + model deps |
|
||||
| `check_deps.py` | Check workflow against running server → list missing nodes/models |
|
||||
| `auto_fix_deps.py` | Run check_deps then `comfy node install` / `comfy model download` |
|
||||
| `run_workflow.py` | Inject params, submit, monitor, download outputs (HTTP or WS) |
|
||||
| `run_batch.py` | Submit a workflow N times with sweeps, parallel up to your tier |
|
||||
| `ws_monitor.py` | Real-time WebSocket viewer for executing jobs (live progress) |
|
||||
| `health_check.py` | Verification checklist runner — comfy-cli + server + models + smoke test |
|
||||
| `fetch_logs.py` | Pull traceback / status messages for a given prompt_id |
|
||||
|
||||
**Example workflows (`workflows/`):** SD 1.5, SDXL, Flux Dev, SDXL img2img,
|
||||
SDXL inpaint, ESRGAN upscale, AnimateDiff video, Wan T2V. See
|
||||
`workflows/README.md`.
|
||||
|
||||
## When to Use
|
||||
|
||||
- User asks to generate images with Stable Diffusion, SDXL, Flux, SD3, etc.
|
||||
- User wants to run a specific ComfyUI workflow file
|
||||
- User wants to chain generative steps (txt2img → upscale → face restore)
|
||||
- User needs ControlNet, inpainting, img2img, or other advanced pipelines
|
||||
- User asks to manage ComfyUI queue, check models, or install custom nodes
|
||||
- User wants video/audio/3D generation via AnimateDiff, Hunyuan, Wan, AudioCraft, etc.
|
||||
|
||||
## Architecture: Two Layers
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────────────────────┐
|
||||
│ Layer 1: comfy-cli (official lifecycle tool) │
|
||||
│ Setup, server lifecycle, custom nodes, models │
|
||||
│ → comfy install / launch / stop / node / model │
|
||||
└─────────────────────────┬───────────────────────────┘
|
||||
│
|
||||
┌─────────────────────────▼───────────────────────────┐
|
||||
│ Layer 2: REST/WebSocket API + skill scripts │
|
||||
│ Workflow execution, param injection, monitoring │
|
||||
│ POST /api/prompt, GET /api/view, WS /ws │
|
||||
│ → run_workflow.py, run_batch.py, ws_monitor.py │
|
||||
└─────────────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
**Why two layers?** The official CLI is excellent for installation and server
|
||||
management but has minimal workflow execution support. The REST/WS API fills
|
||||
that gap — the scripts handle param injection, execution monitoring, and
|
||||
output download that the CLI doesn't do.
|
||||
|
||||
## Quick Start
|
||||
|
||||
### Detect environment
|
||||
|
||||
```bash
|
||||
# What's available?
|
||||
command -v comfy >/dev/null 2>&1 && echo "comfy-cli: installed"
|
||||
curl -s http://127.0.0.1:8188/system_stats 2>/dev/null && echo "server: running"
|
||||
|
||||
# Can this machine run ComfyUI locally? (GPU/VRAM/disk check)
|
||||
python scripts/hardware_check.py
|
||||
```
|
||||
|
||||
If nothing is installed, see **Setup & Onboarding** below — but always run the
|
||||
hardware check first.
|
||||
|
||||
### One-line health check
|
||||
|
||||
```bash
|
||||
python scripts/health_check.py
|
||||
# → JSON: comfy_cli on PATH? server reachable? at least one checkpoint? smoke-test passes?
|
||||
```
|
||||
|
||||
## Core Workflow
|
||||
|
||||
### Step 1: Get a workflow JSON in API format
|
||||
|
||||
Workflows must be in API format (each node has `class_type`). They come from:
|
||||
|
||||
- ComfyUI web UI → **Workflow → Export (API)** (newer UI) or
|
||||
the legacy "Save (API Format)" button (older UI)
|
||||
- This skill's `workflows/` directory (ready-to-run examples)
|
||||
- Community downloads (civitai, Reddit, Discord) — usually editor format,
|
||||
must be loaded into ComfyUI then re-exported
|
||||
|
||||
Editor format (top-level `nodes` and `links` arrays) is **not directly
|
||||
executable**. The scripts detect this and tell you to re-export.
|
||||
|
||||
### Step 2: See what's controllable
|
||||
|
||||
```bash
|
||||
python scripts/extract_schema.py workflow_api.json --summary-only
|
||||
# → {"parameter_count": 12, "has_negative_prompt": true, "has_seed": true, ...}
|
||||
|
||||
python scripts/extract_schema.py workflow_api.json
|
||||
# → full schema with parameters, model deps, embedding refs
|
||||
```
|
||||
|
||||
### Step 3: Run with parameters
|
||||
|
||||
```bash
|
||||
# Local (defaults to http://127.0.0.1:8188)
|
||||
python scripts/run_workflow.py \
|
||||
--workflow workflow_api.json \
|
||||
--args '{"prompt": "a beautiful sunset over mountains", "seed": -1, "steps": 30}' \
|
||||
--output-dir ./outputs
|
||||
|
||||
# Cloud (export API key once; uses correct /api routing automatically)
|
||||
export COMFY_CLOUD_API_KEY="comfyui-..."
|
||||
python scripts/run_workflow.py \
|
||||
--workflow workflow_api.json \
|
||||
--args '{"prompt": "..."}' \
|
||||
--host https://cloud.comfy.org \
|
||||
--output-dir ./outputs
|
||||
|
||||
# Real-time progress via WebSocket (requires `pip install websocket-client`)
|
||||
python scripts/run_workflow.py \
|
||||
--workflow flux_dev.json \
|
||||
--args '{"prompt": "..."}' \
|
||||
--ws
|
||||
|
||||
# img2img / inpaint: pass --input-image to upload + reference automatically
|
||||
python scripts/run_workflow.py \
|
||||
--workflow sdxl_img2img.json \
|
||||
--input-image image=./photo.png \
|
||||
--args '{"prompt": "make it watercolor", "denoise": 0.6}'
|
||||
|
||||
# Batch / sweep: 8 random seeds, parallel up to cloud tier limit
|
||||
python scripts/run_batch.py \
|
||||
--workflow sdxl.json \
|
||||
--args '{"prompt": "abstract"}' \
|
||||
--count 8 --randomize-seed --parallel 3 \
|
||||
--output-dir ./outputs/batch
|
||||
```
|
||||
|
||||
`-1` for `seed` (or omitting it with `--randomize-seed`) generates a fresh
|
||||
random seed per run.
|
||||
|
||||
### Step 4: Present results
|
||||
|
||||
The scripts emit JSON to stdout describing every output file:
|
||||
|
||||
```json
|
||||
{
|
||||
"status": "success",
|
||||
"prompt_id": "abc-123",
|
||||
"outputs": [
|
||||
{"file": "./outputs/sdxl_00001_.png", "node_id": "9",
|
||||
"type": "image", "filename": "sdxl_00001_.png"}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
## Decision Tree
|
||||
|
||||
| User says | Tool | Command |
|
||||
|-----------|------|---------|
|
||||
| **Lifecycle (use comfy-cli)** | | |
|
||||
| "install ComfyUI" | comfy-cli | `bash scripts/comfyui_setup.sh` |
|
||||
| "start ComfyUI" | comfy-cli | `comfy launch --background` |
|
||||
| "stop ComfyUI" | comfy-cli | `comfy stop` |
|
||||
| "install X node" | comfy-cli | `comfy node install <name>` |
|
||||
| "download X model" | comfy-cli | `comfy model download --url <url> --relative-path models/checkpoints` |
|
||||
| "list installed models" | comfy-cli | `comfy model list` |
|
||||
| "list installed nodes" | comfy-cli | `comfy node show installed` |
|
||||
| **Execution (use scripts)** | | |
|
||||
| "is everything ready?" | script | `health_check.py` (optionally with `--workflow X --smoke-test`) |
|
||||
| "what can I change in this workflow?" | script | `extract_schema.py W.json` |
|
||||
| "check if W's deps are met" | script | `check_deps.py W.json` |
|
||||
| "fix missing deps" | script | `auto_fix_deps.py W.json` |
|
||||
| "generate an image" | script | `run_workflow.py --workflow W --args '{...}'` |
|
||||
| "use this image" (img2img) | script | `run_workflow.py --input-image image=./x.png ...` |
|
||||
| "8 variations with random seeds" | script | `run_batch.py --count 8 --randomize-seed ...` |
|
||||
| "show me live progress" | script | `ws_monitor.py --prompt-id <id>` |
|
||||
| "fetch the error from job X" | script | `fetch_logs.py <prompt_id>` |
|
||||
| **Direct REST** | | |
|
||||
| "what's in the queue?" | REST | `curl http://HOST:8188/queue` (local) or `--host https://cloud.comfy.org` |
|
||||
| "cancel that" | REST | `curl -X POST http://HOST:8188/interrupt` |
|
||||
| "free GPU memory" | REST | `curl -X POST http://HOST:8188/free` |
|
||||
|
||||
## Setup & Onboarding
|
||||
|
||||
When a user asks to set up ComfyUI, **the FIRST thing to do is ask whether
|
||||
they want Comfy Cloud (hosted, zero install, API key) or Local (install
|
||||
ComfyUI on their machine)**. Don't start running install commands or hardware
|
||||
checks until they've answered.
|
||||
|
||||
**Official docs:** https://docs.comfy.org/installation
|
||||
**CLI docs:** https://docs.comfy.org/comfy-cli/getting-started
|
||||
**Cloud docs:** https://docs.comfy.org/get_started/cloud
|
||||
**Cloud API:** https://docs.comfy.org/development/cloud/overview
|
||||
|
||||
### Step 0: Ask Local vs Cloud (ALWAYS FIRST)
|
||||
|
||||
Suggested script:
|
||||
|
||||
> "Do you want to run ComfyUI locally on your machine, or use Comfy Cloud?
|
||||
>
|
||||
> - **Comfy Cloud** — hosted on RTX 6000 Pro GPUs, all common models pre-installed,
|
||||
> zero setup. Requires an API key (paid subscription required to actually run
|
||||
> workflows; free tier is read-only). Best if you don't have a capable GPU.
|
||||
> - **Local** — free, but your machine MUST meet the hardware requirements:
|
||||
> - NVIDIA GPU with **≥6 GB VRAM** (≥8 GB for SDXL, ≥12 GB for Flux/video), OR
|
||||
> - AMD GPU with ROCm support (Linux), OR
|
||||
> - Apple Silicon Mac (M1+) with **≥16 GB unified memory** (≥32 GB recommended).
|
||||
> - Intel Macs and machines with no GPU will NOT work — use Cloud instead.
|
||||
>
|
||||
> Which would you like?"
|
||||
|
||||
Routing:
|
||||
|
||||
- **Cloud** → skip to **Path A**.
|
||||
- **Local** → run hardware check first, then pick a path from Paths B–E based on the verdict.
|
||||
- **Unsure** → run the hardware check and let the verdict decide.
|
||||
|
||||
### Step 1: Verify Hardware (ONLY if user chose local)
|
||||
|
||||
```bash
|
||||
python scripts/hardware_check.py --json
|
||||
# Optional: also probe `torch` for actual CUDA/MPS:
|
||||
python scripts/hardware_check.py --json --check-pytorch
|
||||
```
|
||||
|
||||
| Verdict | Meaning | Action |
|
||||
|------------|---------------------------------------------------------------|--------|
|
||||
| `ok` | ≥8 GB VRAM (discrete) OR ≥32 GB unified (Apple Silicon) | Local install — use `comfy_cli_flag` from report |
|
||||
| `marginal` | SD1.5 works; SDXL tight; Flux/video unlikely | Local OK for light workflows, else **Path A (Cloud)** |
|
||||
| `cloud` | No usable GPU, <6 GB VRAM, <16 GB Apple unified, Intel Mac, Rosetta Python | **Switch to Cloud** unless user explicitly forces local |
|
||||
|
||||
The script also surfaces `wsl: true` (WSL2 with NVIDIA passthrough) and
|
||||
`rosetta: true` (x86_64 Python on Apple Silicon — must reinstall as ARM64).
|
||||
|
||||
If verdict is `cloud` but the user wants local, do not proceed silently.
|
||||
Show the `notes` array verbatim and ask whether they want to (a) switch to
|
||||
Cloud or (b) force a local install (will OOM or be unusably slow on modern models).
|
||||
|
||||
### Choosing an Installation Path
|
||||
|
||||
Use the hardware check first. The table below is the fallback for when the
|
||||
user has already told you their hardware:
|
||||
|
||||
| Situation | Recommended Path |
|
||||
|-----------|------------------|
|
||||
| `verdict: cloud` from hardware check | **Path A: Comfy Cloud** |
|
||||
| No GPU / want to try without commitment | **Path A: Comfy Cloud** |
|
||||
| Windows + NVIDIA + non-technical | **Path B: ComfyUI Desktop** |
|
||||
| Windows + NVIDIA + technical | **Path C: Portable** or **Path D: comfy-cli** |
|
||||
| Linux + any GPU | **Path D: comfy-cli** (easiest) |
|
||||
| macOS + Apple Silicon | **Path B: Desktop** or **Path D: comfy-cli** |
|
||||
| Headless / server / CI / agents | **Path D: comfy-cli** |
|
||||
|
||||
For the fully automated path (hardware check → install → launch → verify):
|
||||
|
||||
```bash
|
||||
bash scripts/comfyui_setup.sh
|
||||
# Or with overrides:
|
||||
bash scripts/comfyui_setup.sh --m-series --port=8190 --workspace=/data/comfy
|
||||
```
|
||||
|
||||
It runs `hardware_check.py` internally, refuses to install locally when the
|
||||
verdict is `cloud` (unless `--force-cloud-override`), picks the right
|
||||
`comfy-cli` flag, and prefers `pipx`/`uvx` over global `pip` to avoid polluting
|
||||
system Python.
|
||||
|
||||
---
|
||||
|
||||
### Path A: Comfy Cloud (No Local Install)
|
||||
|
||||
For users without a capable GPU or who want zero setup. Hosted on RTX 6000 Pro.
|
||||
|
||||
**Docs:** https://docs.comfy.org/get_started/cloud
|
||||
|
||||
1. Sign up at https://comfy.org/cloud
|
||||
2. Generate an API key at https://platform.comfy.org/login
|
||||
3. Set the key:
|
||||
```bash
|
||||
export COMFY_CLOUD_API_KEY="your-comfyui-key"
|
||||
```
|
||||
4. Run workflows:
|
||||
```bash
|
||||
python scripts/run_workflow.py \
|
||||
--workflow workflows/flux_dev_txt2img.json \
|
||||
--args '{"prompt": "..."}' \
|
||||
--host https://cloud.comfy.org \
|
||||
--output-dir ./outputs
|
||||
```
|
||||
|
||||
**Pricing:** https://www.comfy.org/cloud/pricing
|
||||
**Concurrent jobs:** Free/Standard 1, Creator 3, Pro 5. Free tier
|
||||
**cannot run workflows via API** — only browse models. Paid subscription
|
||||
required for `/api/prompt`, `/api/upload/*`, `/api/view`, etc.
|
||||
|
||||
---
|
||||
|
||||
### Path B: ComfyUI Desktop (Windows / macOS)
|
||||
|
||||
One-click installer for non-technical users. Currently Beta.
|
||||
|
||||
**Docs:** https://docs.comfy.org/installation/desktop
|
||||
- **Windows (NVIDIA):** https://download.comfy.org/windows/nsis/x64
|
||||
- **macOS (Apple Silicon):** https://comfy.org
|
||||
|
||||
Linux is **not supported** for Desktop — use Path D.
|
||||
|
||||
---
|
||||
|
||||
### Path C: ComfyUI Portable (Windows Only)
|
||||
|
||||
**Docs:** https://docs.comfy.org/installation/comfyui_portable_windows
|
||||
|
||||
Download from https://github.com/comfyanonymous/ComfyUI/releases, extract,
|
||||
run `run_nvidia_gpu.bat`. Update via `update/update_comfyui_stable.bat`.
|
||||
|
||||
---
|
||||
|
||||
### Path D: comfy-cli (All Platforms — Recommended for Agents)
|
||||
|
||||
The official CLI is the best path for headless/automated setups.
|
||||
|
||||
**Docs:** https://docs.comfy.org/comfy-cli/getting-started
|
||||
|
||||
#### Install comfy-cli
|
||||
|
||||
```bash
|
||||
# Recommended:
|
||||
pipx install comfy-cli
|
||||
# Or use uvx without installing:
|
||||
uvx --from comfy-cli comfy --help
|
||||
# Or (if pipx/uvx unavailable):
|
||||
pip install --user comfy-cli
|
||||
```
|
||||
|
||||
Disable analytics non-interactively:
|
||||
```bash
|
||||
comfy --skip-prompt tracking disable
|
||||
```
|
||||
|
||||
#### Install ComfyUI
|
||||
|
||||
```bash
|
||||
comfy --skip-prompt install --nvidia # NVIDIA (CUDA)
|
||||
comfy --skip-prompt install --amd # AMD (ROCm, Linux)
|
||||
comfy --skip-prompt install --m-series # Apple Silicon (MPS)
|
||||
comfy --skip-prompt install --cpu # CPU only (slow)
|
||||
comfy --skip-prompt install --nvidia --fast-deps # uv-based dep resolution
|
||||
```
|
||||
|
||||
Default location: `~/comfy/ComfyUI` (Linux), `~/Documents/comfy/ComfyUI`
|
||||
(macOS/Win). Override with `comfy --workspace /custom/path install`.
|
||||
|
||||
#### Launch / verify
|
||||
|
||||
```bash
|
||||
comfy launch --background # background daemon on :8188
|
||||
comfy launch -- --listen 0.0.0.0 --port 8190 # LAN-accessible custom port
|
||||
curl -s http://127.0.0.1:8188/system_stats # health check
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Path E: Manual Install (Advanced / Unsupported Hardware)
|
||||
|
||||
For Ascend NPU, Cambricon MLU, Intel Arc, or other unsupported hardware.
|
||||
|
||||
**Docs:** https://docs.comfy.org/installation/manual_install
|
||||
|
||||
```bash
|
||||
git clone https://github.com/comfyanonymous/ComfyUI.git
|
||||
cd ComfyUI
|
||||
pip install torch torchvision torchaudio --extra-index-url https://download.pytorch.org/whl/cu130
|
||||
pip install -r requirements.txt
|
||||
python main.py
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Post-Install: Download Models
|
||||
|
||||
```bash
|
||||
# SDXL (general purpose, ~6.5 GB)
|
||||
comfy model download \
|
||||
--url "https://huggingface.co/stabilityai/stable-diffusion-xl-base-1.0/resolve/main/sd_xl_base_1.0.safetensors" \
|
||||
--relative-path models/checkpoints
|
||||
|
||||
# SD 1.5 (lighter, ~4 GB, good for 6 GB cards)
|
||||
comfy model download \
|
||||
--url "https://huggingface.co/stable-diffusion-v1-5/stable-diffusion-v1-5/resolve/main/v1-5-pruned-emaonly.safetensors" \
|
||||
--relative-path models/checkpoints
|
||||
|
||||
# Flux Dev fp8 (smaller variant, ~12 GB)
|
||||
comfy model download \
|
||||
--url "https://huggingface.co/Comfy-Org/flux1-dev/resolve/main/flux1-dev-fp8.safetensors" \
|
||||
--relative-path models/checkpoints
|
||||
|
||||
# CivitAI (set token first):
|
||||
comfy model download \
|
||||
--url "https://civitai.com/api/download/models/128713" \
|
||||
--relative-path models/checkpoints \
|
||||
--set-civitai-api-token "YOUR_TOKEN"
|
||||
```
|
||||
|
||||
List installed: `comfy model list`.
|
||||
|
||||
### Post-Install: Install Custom Nodes
|
||||
|
||||
```bash
|
||||
comfy node install comfyui-impact-pack # popular utility pack
|
||||
comfy node install comfyui-animatediff-evolved # video generation
|
||||
comfy node install comfyui-controlnet-aux # ControlNet preprocessors
|
||||
comfy node install comfyui-essentials # common helpers
|
||||
comfy node update all
|
||||
comfy node install-deps --workflow=workflow.json # install everything a workflow needs
|
||||
```
|
||||
|
||||
### Post-Install: Verify
|
||||
|
||||
```bash
|
||||
python scripts/health_check.py
|
||||
# → comfy_cli on PATH? server reachable? checkpoints? smoke test?
|
||||
|
||||
python scripts/check_deps.py my_workflow.json
|
||||
# → are this workflow's nodes/models/embeddings installed?
|
||||
|
||||
python scripts/run_workflow.py \
|
||||
--workflow workflows/sd15_txt2img.json \
|
||||
--args '{"prompt": "test", "steps": 4}' \
|
||||
--output-dir ./test-outputs
|
||||
```
|
||||
|
||||
## Image Upload (img2img / Inpainting)
|
||||
|
||||
The simplest way is to use `--input-image` with `run_workflow.py`:
|
||||
|
||||
```bash
|
||||
python scripts/run_workflow.py \
|
||||
--workflow workflows/sdxl_img2img.json \
|
||||
--input-image image=./photo.png \
|
||||
--args '{"prompt": "make it cyberpunk", "denoise": 0.6}'
|
||||
```
|
||||
|
||||
The flag uploads `photo.png`, then injects its server-side filename into
|
||||
whatever schema parameter is named `image`. For inpainting, pass both:
|
||||
|
||||
```bash
|
||||
python scripts/run_workflow.py \
|
||||
--workflow workflows/sdxl_inpaint.json \
|
||||
--input-image image=./photo.png \
|
||||
--input-image mask_image=./mask.png \
|
||||
--args '{"prompt": "fill with flowers"}'
|
||||
```
|
||||
|
||||
Manual upload via REST:
|
||||
```bash
|
||||
curl -X POST "http://127.0.0.1:8188/upload/image" \
|
||||
-F "image=@photo.png" -F "type=input" -F "overwrite=true"
|
||||
# Returns: {"name": "photo.png", "subfolder": "", "type": "input"}
|
||||
|
||||
# Cloud equivalent:
|
||||
curl -X POST "https://cloud.comfy.org/api/upload/image" \
|
||||
-H "X-API-Key: $COMFY_CLOUD_API_KEY" \
|
||||
-F "image=@photo.png" -F "type=input" -F "overwrite=true"
|
||||
```
|
||||
|
||||
## Cloud Specifics
|
||||
|
||||
- **Base URL:** `https://cloud.comfy.org`
|
||||
- **Auth:** `X-API-Key` header (or `?token=KEY` for WebSocket)
|
||||
- **API key:** set `$COMFY_CLOUD_API_KEY` once and the scripts pick it up automatically
|
||||
- **Output download:** `/api/view` returns a 302 to a signed URL; the scripts
|
||||
follow it and strip `X-API-Key` before fetching from the storage backend
|
||||
(don't leak the API key to S3/CloudFront).
|
||||
- **Endpoint differences from local ComfyUI:**
|
||||
- `/api/object_info`, `/api/queue`, `/api/userdata` — **403 on free tier**;
|
||||
paid only.
|
||||
- `/history` is renamed to `/history_v2` on cloud (the scripts route
|
||||
automatically).
|
||||
- `/models/<folder>` is renamed to `/experiment/models/<folder>` on cloud
|
||||
(the scripts route automatically).
|
||||
- `clientId` in WebSocket is currently ignored — all connections for a
|
||||
user receive the same broadcast. Filter by `prompt_id` client-side.
|
||||
- `subfolder` is accepted on uploads but ignored — cloud has a flat namespace.
|
||||
- **Concurrent jobs:** Free/Standard: 1, Creator: 3, Pro: 5. Extras queue
|
||||
automatically. Use `run_batch.py --parallel N` to saturate your tier.
|
||||
|
||||
## Queue & System Management
|
||||
|
||||
```bash
|
||||
# Local
|
||||
curl -s http://127.0.0.1:8188/queue | python -m json.tool
|
||||
curl -X POST http://127.0.0.1:8188/queue -d '{"clear": true}' # cancel pending
|
||||
curl -X POST http://127.0.0.1:8188/interrupt # cancel running
|
||||
curl -X POST http://127.0.0.1:8188/free \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{"unload_models": true, "free_memory": true}'
|
||||
|
||||
# Cloud — same paths under /api/, plus:
|
||||
python scripts/fetch_logs.py --tail-queue --host https://cloud.comfy.org
|
||||
```
|
||||
|
||||
## Pitfalls
|
||||
|
||||
1. **API format required** — every script and the `/api/prompt` endpoint expect
|
||||
API-format workflow JSON. The scripts detect editor format (top-level
|
||||
`nodes` and `links` arrays) and tell you to re-export via
|
||||
"Workflow → Export (API)" (newer UI) or "Save (API Format)" (older UI).
|
||||
|
||||
2. **Server must be running** — all execution requires a live server.
|
||||
`comfy launch --background` starts one. Verify with
|
||||
`curl http://127.0.0.1:8188/system_stats`.
|
||||
|
||||
3. **Model names are exact** — case-sensitive, includes file extension.
|
||||
`check_deps.py` does fuzzy matching (with/without extension and folder
|
||||
prefix), but the workflow itself must use the canonical name. Use
|
||||
`comfy model list` to discover what's installed.
|
||||
|
||||
4. **Missing custom nodes** — "class_type not found" means a required node
|
||||
isn't installed. `check_deps.py` reports which package to install;
|
||||
`auto_fix_deps.py` runs the install for you.
|
||||
|
||||
5. **Working directory** — `comfy-cli` auto-detects the ComfyUI workspace.
|
||||
If commands fail with "no workspace found", use
|
||||
`comfy --workspace /path/to/ComfyUI <command>` or
|
||||
`comfy set-default /path/to/ComfyUI`.
|
||||
|
||||
6. **Cloud free-tier API limits** — `/api/prompt`, `/api/view`, `/api/upload/*`,
|
||||
`/api/object_info` all return 403 on free accounts. `health_check.py` and
|
||||
`check_deps.py` handle this gracefully and surface a clear message.
|
||||
|
||||
7. **Timeout for video/audio workflows** — auto-detected when an output node
|
||||
is `VHS_VideoCombine`, `SaveVideo`, etc.; the default jumps from 300 s to
|
||||
900 s. Override explicitly with `--timeout 1800`.
|
||||
|
||||
8. **Path traversal in output filenames** — server-supplied filenames are
|
||||
passed through `safe_path_join` to refuse anything escaping `--output-dir`.
|
||||
Keep this protection on — workflows with custom save nodes can produce
|
||||
arbitrary paths.
|
||||
|
||||
9. **Workflow JSON is arbitrary code** — custom nodes run Python, so
|
||||
submitting an unknown workflow has the same trust profile as `eval`.
|
||||
Inspect workflows from untrusted sources before running.
|
||||
|
||||
10. **Auto-randomized seed** — pass `seed: -1` in `--args` (or use
|
||||
`--randomize-seed` and omit the seed) to get a fresh seed per run.
|
||||
The actual seed is logged to stderr.
|
||||
|
||||
11. **`tracking` prompt** — first run of `comfy` may prompt for analytics.
|
||||
Use `comfy --skip-prompt tracking disable` to skip non-interactively.
|
||||
`comfyui_setup.sh` does this for you.
|
||||
|
||||
## Verification Checklist
|
||||
|
||||
Use `python scripts/health_check.py` to run the whole list at once. Manual:
|
||||
|
||||
- [ ] `hardware_check.py` verdict is `ok` OR the user explicitly chose Comfy Cloud
|
||||
- [ ] `comfy --version` works (or `uvx --from comfy-cli comfy --help`)
|
||||
- [ ] `curl http://HOST:PORT/system_stats` returns JSON
|
||||
- [ ] `comfy model list` shows at least one checkpoint (local) OR
|
||||
`/api/experiment/models/checkpoints` returns models (cloud)
|
||||
- [ ] Workflow JSON is in API format
|
||||
- [ ] `check_deps.py` reports `is_ready: true` (or only `node_check_skipped`
|
||||
on cloud free tier)
|
||||
- [ ] Test run with a small workflow completes; outputs land in `--output-dir`
|
||||
@@ -0,0 +1,255 @@
|
||||
# comfy-cli Command Reference
|
||||
|
||||
Official CLI from [Comfy-Org/comfy-cli](https://github.com/Comfy-Org/comfy-cli).
|
||||
Docs: https://docs.comfy.org/comfy-cli/getting-started
|
||||
|
||||
## Installation
|
||||
|
||||
Order of preference:
|
||||
|
||||
```bash
|
||||
pipx install comfy-cli # recommended (isolated env)
|
||||
uvx --from comfy-cli comfy --help # zero-install via uv
|
||||
pip install --user comfy-cli # fallback
|
||||
```
|
||||
|
||||
The skill's `comfyui_setup.sh` picks the best available method.
|
||||
|
||||
First run may prompt for analytics. Disable non-interactively:
|
||||
```bash
|
||||
comfy --skip-prompt tracking disable
|
||||
```
|
||||
|
||||
## Global Options
|
||||
|
||||
| Option | Description |
|
||||
|--------|-------------|
|
||||
| `--workspace <path>` | Target a specific ComfyUI workspace |
|
||||
| `--recent` | Use most recently used workspace |
|
||||
| `--here` | Use current directory as workspace |
|
||||
| `--skip-prompt` | No interactive prompts (use defaults) |
|
||||
| `-v` / `--version` | Print version |
|
||||
|
||||
Workspace resolution priority:
|
||||
1. `--workspace` (explicit path)
|
||||
2. `--recent` (from config)
|
||||
3. `--here` (cwd)
|
||||
4. `comfy set-default` path
|
||||
5. Most recently used
|
||||
6. `~/comfy/ComfyUI` (Linux) or `~/Documents/comfy/ComfyUI` (macOS/Win)
|
||||
|
||||
## Lifecycle Commands
|
||||
|
||||
### `comfy install`
|
||||
|
||||
Download and install ComfyUI + ComfyUI-Manager.
|
||||
|
||||
```bash
|
||||
comfy install # interactive GPU selection
|
||||
comfy install --nvidia
|
||||
comfy install --amd # ROCm (Linux)
|
||||
comfy install --m-series # Apple Silicon (MPS)
|
||||
comfy install --cpu # CPU only (slow)
|
||||
comfy install --fast-deps # use uv for deps
|
||||
comfy install --skip-manager # skip ComfyUI-Manager
|
||||
```
|
||||
|
||||
| Option | Description |
|
||||
|--------|-------------|
|
||||
| `--nvidia` / `--amd` / `--m-series` / `--cpu` | GPU type |
|
||||
| `--cuda-version` | 11.8, 12.1, 12.4, 12.6, 12.8, 12.9, 13.0 |
|
||||
| `--rocm-version` | 6.1, 6.2, 6.3, 7.0, 7.1 |
|
||||
| `--fast-deps` | uv-based dependency resolution |
|
||||
| `--skip-manager` | Don't install ComfyUI-Manager |
|
||||
| `--skip-torch-or-directml` | Skip PyTorch install |
|
||||
| `--version <ver>` | `0.2.0`, `latest`, `nightly` |
|
||||
| `--commit <hash>` | Install specific commit |
|
||||
| `--pr "#1234"` | Install from a PR |
|
||||
| `--restore` | Restore deps for existing install |
|
||||
|
||||
### `comfy launch`
|
||||
|
||||
```bash
|
||||
comfy launch # foreground :8188
|
||||
comfy launch --background # background daemon
|
||||
comfy launch -- --listen 0.0.0.0 # LAN-accessible
|
||||
comfy launch -- --port 8190 # custom port
|
||||
comfy launch -- --cpu # force CPU mode
|
||||
comfy launch -- --lowvram # 6 GB cards
|
||||
comfy launch --background -- --listen 0.0.0.0 --port 8190
|
||||
```
|
||||
|
||||
Common extra args after `--`: `--listen`, `--port`, `--cpu`, `--lowvram`,
|
||||
`--novram`, `--fp16-vae`, `--force-fp32`, `--disable-cuda-malloc`.
|
||||
|
||||
### `comfy stop`
|
||||
|
||||
```bash
|
||||
comfy stop
|
||||
```
|
||||
|
||||
### `comfy run`
|
||||
|
||||
Submit a raw workflow JSON to a running server. **Limited** — no parameter
|
||||
injection, no structured output download. For agents, use
|
||||
`scripts/run_workflow.py` instead.
|
||||
|
||||
```bash
|
||||
comfy run --workflow workflow_api.json
|
||||
comfy run --workflow workflow_api.json --host 10.0.0.5 --port 8188
|
||||
comfy run --workflow workflow_api.json --timeout 300 --wait
|
||||
```
|
||||
|
||||
### `comfy which`
|
||||
|
||||
```bash
|
||||
comfy which # show targeted workspace
|
||||
comfy --recent which
|
||||
```
|
||||
|
||||
### `comfy set-default`
|
||||
|
||||
```bash
|
||||
comfy set-default /path/to/ComfyUI
|
||||
comfy set-default /path/to/ComfyUI --launch-extras="--listen 0.0.0.0"
|
||||
```
|
||||
|
||||
### `comfy update`
|
||||
|
||||
```bash
|
||||
comfy update # update ComfyUI core
|
||||
comfy node update all # update all custom nodes
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## `comfy node` — Custom Node Management
|
||||
|
||||
All node operations use ComfyUI-Manager (`cm-cli`) under the hood.
|
||||
|
||||
```bash
|
||||
comfy node show installed # list installed
|
||||
comfy node show enabled # list enabled
|
||||
comfy node show all # all available in registry
|
||||
comfy node simple-show installed # compact list
|
||||
|
||||
comfy node install comfyui-impact-pack
|
||||
comfy node install <name> --uv-compile # ComfyUI-Manager v4.1+ unified resolver
|
||||
comfy node uninstall <name>
|
||||
comfy node update <name> | all
|
||||
comfy node enable <name>
|
||||
comfy node disable <name>
|
||||
comfy node fix <name> # fix broken deps
|
||||
|
||||
comfy node install-deps --workflow=workflow.json
|
||||
comfy node deps-in-workflow --workflow=w.json --output=deps.json
|
||||
|
||||
comfy node save-snapshot
|
||||
comfy node restore-snapshot <file>
|
||||
|
||||
comfy node bisect start # binary-search a culprit node
|
||||
comfy node bisect good
|
||||
comfy node bisect bad
|
||||
comfy node bisect reset
|
||||
```
|
||||
|
||||
### Dependency Resolution Options
|
||||
|
||||
| Flag | Description |
|
||||
|------|-------------|
|
||||
| `--fast-deps` | comfy-cli built-in uv resolver |
|
||||
| `--uv-compile` | ComfyUI-Manager v4.1+ unified resolver (recommended) |
|
||||
| `--no-deps` | Skip dep installation |
|
||||
|
||||
Make `uv-compile` default: `comfy manager uv-compile-default true`
|
||||
|
||||
---
|
||||
|
||||
## `comfy model` — Model Management
|
||||
|
||||
```bash
|
||||
comfy model list
|
||||
comfy model list --relative-path models/checkpoints
|
||||
|
||||
comfy model download --url <URL>
|
||||
comfy model download --url <URL> --relative-path models/loras
|
||||
comfy model download --url <URL> --filename custom_name.safetensors
|
||||
|
||||
comfy model remove # interactive
|
||||
comfy model remove --relative-path models/checkpoints --model-names "model.safetensors"
|
||||
```
|
||||
|
||||
| Option | Description |
|
||||
|--------|-------------|
|
||||
| `--url` | Download URL (CivitAI, HuggingFace, direct) |
|
||||
| `--relative-path` | Subdirectory under workspace (e.g. `models/checkpoints`) |
|
||||
| `--filename` | Custom save filename |
|
||||
| `--set-civitai-api-token` | Persist CivitAI token |
|
||||
| `--set-hf-api-token` | Persist HuggingFace token |
|
||||
| `--downloader` | `httpx` (default) or `aria2` |
|
||||
|
||||
Standard model directories:
|
||||
```
|
||||
ComfyUI/models/
|
||||
├── checkpoints/ # Full model files
|
||||
├── loras/ # LoRA adapters
|
||||
├── vae/ # VAE models
|
||||
├── controlnet/ # ControlNet models
|
||||
├── clip/ # CLIP / T5 text encoders
|
||||
├── clip_vision/ # CLIP vision encoders
|
||||
├── upscale_models/ # ESRGAN / SwinIR / etc.
|
||||
├── embeddings/ # Textual inversion embeddings
|
||||
├── unet/ # Standalone UNet weights
|
||||
├── diffusion_models/ # Flux / SD3 / Wan diffusion models
|
||||
├── animatediff_models/ # AnimateDiff motion modules
|
||||
├── ipadapter/ # IPAdapter weights
|
||||
└── style_models/ # Style adapters
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## `comfy manager` — ComfyUI-Manager Settings
|
||||
|
||||
```bash
|
||||
comfy manager disable # disable Manager completely
|
||||
comfy manager enable-gui # enable new GUI
|
||||
comfy manager disable-gui # API-only
|
||||
comfy manager enable-legacy-gui # legacy GUI
|
||||
comfy manager uv-compile-default true # make --uv-compile the default
|
||||
comfy manager clear # clear startup action
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## `comfy pr-cache` — Frontend PR Cache
|
||||
|
||||
```bash
|
||||
comfy pr-cache list
|
||||
comfy pr-cache clean
|
||||
comfy pr-cache clean 456
|
||||
```
|
||||
|
||||
Cache expires after 7 days; max 10 builds.
|
||||
|
||||
---
|
||||
|
||||
## Configuration
|
||||
|
||||
| OS | Path |
|
||||
|----|------|
|
||||
| Linux | `~/.config/comfy-cli/config.ini` |
|
||||
| macOS | `~/Library/Application Support/comfy-cli/config.ini` |
|
||||
| Windows | `~/AppData/Local/comfy-cli/config.ini` |
|
||||
|
||||
Stores: default workspace, recent workspace, background server PID, API
|
||||
tokens, manager GUI mode, launch extras.
|
||||
|
||||
## Discovery
|
||||
|
||||
Custom-node registry:
|
||||
- https://registry.comfy.org/
|
||||
|
||||
Model browsers:
|
||||
- https://huggingface.co/models
|
||||
- https://civitai.com (NSFW; requires API token for many)
|
||||
- https://comfyworkflows.com (community workflows)
|
||||
@@ -0,0 +1,312 @@
|
||||
# ComfyUI REST + WebSocket API Reference
|
||||
|
||||
ComfyUI exposes a REST + WebSocket interface for workflow execution and
|
||||
management. **The same surface is used locally and on Comfy Cloud, with
|
||||
auth/path differences.**
|
||||
|
||||
## Connection
|
||||
|
||||
| | Local ComfyUI | Comfy Cloud |
|
||||
|---|---|---|
|
||||
| Base URL | `http://127.0.0.1:8188` | `https://cloud.comfy.org` |
|
||||
| API path prefix | none (`/prompt`, `/view`, …) | `/api/...` (`/api/prompt`, `/api/view`, …) |
|
||||
| Auth | none (or bearer token if configured) | `X-API-Key` header |
|
||||
| WebSocket | `ws://host:port/ws?clientId={uuid}` | `wss://cloud.comfy.org/ws?clientId={uuid}&token={API_KEY}` |
|
||||
| `/api/view` response | direct bytes | 302 redirect → signed URL (use `curl -L`) |
|
||||
|
||||
The skill scripts route URLs automatically via `_common.resolve_url()`.
|
||||
|
||||
## Endpoint differences on Comfy Cloud
|
||||
|
||||
The cloud surface diverges from local ComfyUI in several ways. The skill
|
||||
scripts handle these transparently; document them here so anyone calling
|
||||
`curl` directly knows.
|
||||
|
||||
| Local path | Cloud path | Notes |
|
||||
|------------|-----------|-------|
|
||||
| `/system_stats` | `/api/system_stats` | Cloud version is **public** (no auth required) |
|
||||
| `/object_info` | `/api/object_info` | **Paid tier only** — free returns 403 |
|
||||
| `/queue` | `/api/queue` | Paid tier only |
|
||||
| `/userdata` | `/api/userdata` | Paid tier only |
|
||||
| `/prompt` (POST) | `/api/prompt` (POST) | Paid tier only |
|
||||
| `/upload/image` | `/api/upload/image` | Paid tier only; `subfolder` accepted but ignored |
|
||||
| `/upload/mask` | `/api/upload/mask` | Same as above |
|
||||
| `/view` | `/api/view` | Paid tier only; **returns 302** to signed URL |
|
||||
| `/history` | `/api/history_v2` | **Renamed**; old path returns 404 |
|
||||
| `/history/{id}` | `/api/history_v2/{id}` or `/api/jobs/{id}` | Both work; `/jobs` returns full job |
|
||||
| `/models` | `/api/experiment/models` | **Renamed** |
|
||||
| `/models/{folder}` | `/api/experiment/models/{folder}` | **Renamed**; response shape differs (see below) |
|
||||
|
||||
### Cloud model-list response shape
|
||||
|
||||
- **Local:** `["a.safetensors", "b.safetensors", …]` — flat list of strings.
|
||||
- **Cloud:** `[{"name": "a.safetensors", "pathIndex": 0}, …]` — list of objects.
|
||||
- **Cloud 404 with `code: "folder_not_found"`** — folder is empty or unknown,
|
||||
not an "endpoint missing" error. Distinguish by reading the body.
|
||||
|
||||
The skill helper `_common.parse_model_list()` normalizes both.
|
||||
|
||||
## Workflow Execution
|
||||
|
||||
### Submit Workflow
|
||||
|
||||
```bash
|
||||
# Local
|
||||
curl -X POST "http://127.0.0.1:8188/prompt" \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{"prompt": '"$(cat workflow_api.json)"', "client_id": "'"$(uuidgen)"'"}'
|
||||
|
||||
# Cloud
|
||||
curl -X POST "https://cloud.comfy.org/api/prompt" \
|
||||
-H "X-API-Key: $COMFY_CLOUD_API_KEY" \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{"prompt": '"$(cat workflow_api.json)"'}'
|
||||
```
|
||||
|
||||
**Response:**
|
||||
```json
|
||||
{"prompt_id": "abc-123-def", "number": 1, "node_errors": {}}
|
||||
```
|
||||
|
||||
If `node_errors` is non-empty, the workflow has validation errors (missing
|
||||
nodes, bad inputs).
|
||||
|
||||
### Check Job Status (Cloud)
|
||||
|
||||
```bash
|
||||
curl -X GET "https://cloud.comfy.org/api/job/{prompt_id}/status" \
|
||||
-H "X-API-Key: $COMFY_CLOUD_API_KEY"
|
||||
```
|
||||
|
||||
| Status | Description |
|
||||
| ------------- | ---------------------------------- |
|
||||
| `pending` | Job is queued and waiting to start |
|
||||
| `in_progress` | Job is currently executing |
|
||||
| `completed` | Job finished successfully |
|
||||
| `failed` | Job encountered an error |
|
||||
| `cancelled` | Job was cancelled by user |
|
||||
|
||||
### Job detail with outputs (Cloud)
|
||||
|
||||
```bash
|
||||
curl -X GET "https://cloud.comfy.org/api/jobs/{prompt_id}" \
|
||||
-H "X-API-Key: $COMFY_CLOUD_API_KEY"
|
||||
```
|
||||
|
||||
Response includes `outputs` keyed by node ID. Cloud uses `video` (singular)
|
||||
in the output structure; local uses `videos` (plural). The skill scripts
|
||||
accept both.
|
||||
|
||||
### Get History (Local)
|
||||
|
||||
```bash
|
||||
curl -s "http://127.0.0.1:8188/history" # all
|
||||
curl -s "http://127.0.0.1:8188/history/{id}" # one prompt_id
|
||||
```
|
||||
|
||||
Local entry shape:
|
||||
```json
|
||||
{
|
||||
"<prompt_id>": {
|
||||
"prompt": [...],
|
||||
"outputs": {"<node_id>": {"images": [...]}},
|
||||
"status": {
|
||||
"status_str": "success" | "error",
|
||||
"completed": true | false,
|
||||
"messages": [["execution_start", {...}], ["execution_error", {...}], …]
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**Important:** when reading status, check `status_str == "error"` BEFORE
|
||||
checking `completed`, because both can be true for failed runs.
|
||||
|
||||
### Download Output
|
||||
|
||||
```bash
|
||||
# Local (direct bytes)
|
||||
curl -s "http://127.0.0.1:8188/view?filename=ComfyUI_00001_.png&subfolder=&type=output" \
|
||||
-o output.png
|
||||
|
||||
# Cloud (302 → signed URL; -L follows; STRIP X-API-Key for the second hop)
|
||||
curl -L "https://cloud.comfy.org/api/view?filename=...&type=output" \
|
||||
-H "X-API-Key: $COMFY_CLOUD_API_KEY" \
|
||||
-o output.png
|
||||
```
|
||||
|
||||
The skill's `run_workflow.py` strips `X-API-Key` automatically on the
|
||||
cross-host redirect, so the signed URL never sees your auth.
|
||||
|
||||
## WebSocket Monitoring
|
||||
|
||||
Connect for real-time execution events.
|
||||
|
||||
```bash
|
||||
# Local
|
||||
wscat -c "ws://127.0.0.1:8188/ws?clientId=MY-UUID"
|
||||
|
||||
# Cloud
|
||||
wscat -c "wss://cloud.comfy.org/ws?clientId=MY-UUID&token=$COMFY_CLOUD_API_KEY"
|
||||
```
|
||||
|
||||
**Note:** on Cloud the `clientId` is currently ignored — all messages for a
|
||||
user are broadcast to every connection. Filter messages client-side by
|
||||
`data.prompt_id`.
|
||||
|
||||
### JSON Message Types
|
||||
|
||||
| Type | When | Key Fields |
|
||||
|------|------|------------|
|
||||
| `status` | Queue change | `status.exec_info.queue_remaining` |
|
||||
| `notification` | User-friendly status string | `value` |
|
||||
| `execution_start` | Workflow begins | `prompt_id` |
|
||||
| `executing` | Node running (or end-of-run if `node` is null on local) | `node`, `prompt_id` |
|
||||
| `progress` | Sampling steps | `node`, `value`, `max` |
|
||||
| `progress_state` | Extended progress with per-node metadata | `nodes` (dict) |
|
||||
| `executed` | Node output ready | `node`, `output` (with `images`/`video`/etc.) |
|
||||
| `execution_cached` | Nodes skipped because of cache | `nodes` (list of IDs) |
|
||||
| `execution_success` | All done | `prompt_id` |
|
||||
| `execution_error` | Failure | `exception_type`, `exception_message`, `traceback`, `node_id` |
|
||||
| `execution_interrupted` | Cancelled | `prompt_id` |
|
||||
|
||||
### Binary Frames (Preview Images)
|
||||
|
||||
| Type code | Meaning |
|
||||
|-----------|---------|
|
||||
| `0x00000001` | `PREVIEW_IMAGE` — `[type:4][image_type:4][data]` (image_type 1=JPEG, 2=PNG) |
|
||||
| `0x00000003` | `TEXT` — `[type:4][nid_len:4][nid][text]` (UTF-8) |
|
||||
| `0x00000004` | `PREVIEW_IMAGE_WITH_METADATA` — `[type:4][meta_len:4][json][image_data]` |
|
||||
|
||||
`scripts/ws_monitor.py --previews <dir>` saves preview frames to disk.
|
||||
|
||||
## File Upload
|
||||
|
||||
```bash
|
||||
# Image
|
||||
curl -X POST "http://127.0.0.1:8188/upload/image" \
|
||||
-F "image=@photo.png" -F "type=input" -F "overwrite=true"
|
||||
# Returns: {"name": "photo.png", "subfolder": "", "type": "input"}
|
||||
|
||||
# Mask (linked to a previously uploaded image)
|
||||
curl -X POST "http://127.0.0.1:8188/upload/mask" \
|
||||
-F "image=@mask.png" -F "type=input" \
|
||||
-F 'original_ref={"filename":"photo.png","subfolder":"","type":"input"}'
|
||||
```
|
||||
|
||||
Cloud equivalent: prepend `https://cloud.comfy.org/api` and add `-H "X-API-Key: $COMFY_CLOUD_API_KEY"`.
|
||||
|
||||
## Node & Model Discovery
|
||||
|
||||
```bash
|
||||
# All node types and their input specs
|
||||
curl -s "http://127.0.0.1:8188/object_info" | python3 -m json.tool
|
||||
|
||||
# Specific node
|
||||
curl -s "http://127.0.0.1:8188/object_info/KSampler"
|
||||
|
||||
# Models per folder (local)
|
||||
curl -s "http://127.0.0.1:8188/models/checkpoints"
|
||||
curl -s "http://127.0.0.1:8188/models/loras"
|
||||
|
||||
# Models per folder (cloud — note the experimental prefix)
|
||||
curl -s "https://cloud.comfy.org/api/experiment/models/checkpoints" \
|
||||
-H "X-API-Key: $COMFY_CLOUD_API_KEY"
|
||||
```
|
||||
|
||||
## Queue Management
|
||||
|
||||
```bash
|
||||
# View queue
|
||||
curl -s "http://127.0.0.1:8188/queue"
|
||||
|
||||
# Clear all pending
|
||||
curl -X POST "http://127.0.0.1:8188/queue" \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{"clear": true}'
|
||||
|
||||
# Delete specific items
|
||||
curl -X POST "http://127.0.0.1:8188/queue" \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{"delete": ["prompt_id_1", "prompt_id_2"]}'
|
||||
|
||||
# Cancel currently-running job
|
||||
curl -X POST "http://127.0.0.1:8188/interrupt"
|
||||
```
|
||||
|
||||
## System Management
|
||||
|
||||
```bash
|
||||
# Stats (VRAM, RAM, GPU, ComfyUI version)
|
||||
curl -s "http://127.0.0.1:8188/system_stats"
|
||||
|
||||
# Free GPU memory
|
||||
curl -X POST "http://127.0.0.1:8188/free" \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{"unload_models": true, "free_memory": true}'
|
||||
```
|
||||
|
||||
## ComfyUI-Manager Endpoints (Optional)
|
||||
|
||||
These require ComfyUI-Manager installed. Useful for installing nodes/models
|
||||
via the API instead of `comfy-cli`.
|
||||
|
||||
```bash
|
||||
# Install a custom node from a git URL
|
||||
curl -X POST "http://127.0.0.1:8188/manager/queue/install" \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{"git_url": "https://github.com/user/comfyui-node.git"}'
|
||||
|
||||
# Check install queue status
|
||||
curl -s "http://127.0.0.1:8188/manager/queue/status"
|
||||
|
||||
# Install model
|
||||
curl -X POST "http://127.0.0.1:8188/manager/queue/install_model" \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{"url": "https://...", "path": "models/checkpoints", "filename": "model.safetensors"}'
|
||||
```
|
||||
|
||||
## POST /prompt Payload Format
|
||||
|
||||
```json
|
||||
{
|
||||
"prompt": {
|
||||
"3": {
|
||||
"class_type": "KSampler",
|
||||
"inputs": {
|
||||
"seed": 42,
|
||||
"steps": 20,
|
||||
"cfg": 7.5,
|
||||
"sampler_name": "euler",
|
||||
"scheduler": "normal",
|
||||
"denoise": 1.0,
|
||||
"model": ["4", 0],
|
||||
"positive": ["6", 0],
|
||||
"negative": ["7", 0],
|
||||
"latent_image": ["5", 0]
|
||||
}
|
||||
}
|
||||
},
|
||||
"client_id": "unique-uuid-for-ws-filtering",
|
||||
"extra_data": {
|
||||
"api_key_comfy_org": "optional-PARTNER-NODE-key (NOT the cloud auth key)"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
- `prompt`: workflow graph in API format
|
||||
- `client_id`: UUID — local server uses it to filter WebSocket events; cloud
|
||||
ignores it.
|
||||
- `extra_data.api_key_comfy_org`: ONLY required when the workflow uses
|
||||
partner nodes (Flux Pro, Ideogram, etc.). Don't conflate with `X-API-Key`.
|
||||
|
||||
## Error Categories (cloud `execution_error` `exception_type`)
|
||||
|
||||
| Type | Meaning |
|
||||
|------|---------|
|
||||
| `ValidationError` | Bad workflow / inputs (often nicer to surface from `node_errors`) |
|
||||
| `ModelDownloadError` | Required model not available |
|
||||
| `ImageDownloadError` | Failed to fetch input image from URL |
|
||||
| `OOMError` | Out of GPU memory |
|
||||
| `InsufficientFundsError` | Account balance too low (partner nodes) |
|
||||
| `InactiveSubscriptionError` | Subscription not active |
|
||||
@@ -0,0 +1,243 @@
|
||||
# ComfyUI Workflow-Template Integrity
|
||||
|
||||
> **Authored by [@purzbeats](https://github.com/purzbeats)** — adapted from
|
||||
> [purzbeats/hermes-agent-comfyui-helper](https://github.com/purzbeats/hermes-agent-comfyui-helper).
|
||||
> Use this reference when converting workflows from the official
|
||||
> `comfyui-workflow-templates` package (editor format) into API format for
|
||||
> submission via `/api/prompt`. The conversion has subtle gotchas that cause
|
||||
> hard-to-diagnose validation errors if you don't follow these rules.
|
||||
|
||||
## Background
|
||||
|
||||
The official ComfyUI template package (`comfyui-workflow-templates`, currently
|
||||
v0.9.69) is installed inside the ComfyUI venv at a path like:
|
||||
|
||||
```
|
||||
<comfy-install>/.venv/lib/python3.*/site-packages/comfyui_workflow_templates_*/templates/
|
||||
```
|
||||
|
||||
The exact path depends on how ComfyUI was installed (comfy-cli default,
|
||||
Comfy Desktop, manual venv, etc.). Find it once with:
|
||||
|
||||
```bash
|
||||
comfy --workspace <ws> run-python -c "import comfyui_workflow_templates, pathlib; print(pathlib.Path(comfyui_workflow_templates.__file__).parent / 'templates')"
|
||||
```
|
||||
|
||||
Templates ship in **editor format** — `nodes` / `links` arrays inside
|
||||
`data['definitions']['subgraphs'][0]`. They must be converted to **API
|
||||
format** (a `node_id -> {class_type, inputs}` mapping) before submission.
|
||||
|
||||
---
|
||||
|
||||
## RULE #1: Use templates AS CLOSE TO ORIGINAL AS POSSIBLE
|
||||
|
||||
- **Never strip, simplify, or "minimize" nodes** from a template.
|
||||
- Full template architecture (dual-pass pipelines, LoRA chains, distilled
|
||||
sigmas, conditioning paths) is intentional — removing any part breaks quality.
|
||||
- If an image-dependent path exists but the task is text-to-video, **leave
|
||||
it wired with the bypass toggle enabled** — don't remove the nodes.
|
||||
- Only change: prompt text, seed, and dimensions (when explicitly requested).
|
||||
|
||||
## RULE #2: Server validation errors are the source of truth
|
||||
|
||||
When a workflow submission fails, the server response looks like:
|
||||
|
||||
```json
|
||||
{
|
||||
"node_errors": {
|
||||
"238": {
|
||||
"errors": [{
|
||||
"message": "Required input is missing",
|
||||
"details": "width",
|
||||
"extra_info": { "input_name": "resize_type.width" }
|
||||
}]
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**The `extra_info.input_name` field tells you EXACTLY what JSON key the server
|
||||
wants. Use it literally.** If it says `"values.a"` or `"resize_type.width"`,
|
||||
those are the actual key names in the JSON object. Do not "simplify" them to
|
||||
flat names based on assumptions about what the field "should" be called.
|
||||
|
||||
## RULE #3: Don't rebuild from scratch — patch the failing nodes
|
||||
|
||||
Every regeneration from the template reintroduces the same bugs. Instead:
|
||||
|
||||
1. Submit the workflow once.
|
||||
2. Read the server error details for exact key names.
|
||||
3. Use targeted patch/fix calls against the workflow file on disk.
|
||||
4. Resubmit and check if errors resolved.
|
||||
|
||||
---
|
||||
|
||||
## Reroute nodes: bypass, don't delete
|
||||
|
||||
Most servers (local, Cloud) don't have a `Reroute` node type. When converting
|
||||
a template:
|
||||
|
||||
1. Find what feeds into the Reroute by looking at links where
|
||||
`target_id` = the Reroute node ID.
|
||||
2. Replace all inputs referencing the Reroute with
|
||||
`[source_node_id, source_slot]`.
|
||||
3. Delete the Reroute node from the API mapping.
|
||||
|
||||
**Real example — LTX 2.3 t2v template:**
|
||||
|
||||
- Reroute node 255 receives VAE from `CheckpointLoaderSimple 236` slot 2.
|
||||
- Three nodes reference Reroute 255 for their VAE input:
|
||||
`LTXVImgToVideoInplace` (230), `LTXVLatentUpsampler` (253),
|
||||
`VAEDecodeTiled` (251).
|
||||
- Fix: replace all occurrences of `vae: ["255", 0]` with `vae: ["236", 2]`.
|
||||
- `CheckpointLoaderSimple` slot 2 = VAE (not slot 0 = MODEL).
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| ❌ Wrong | `vae: ["236", 0]` → `MODELV mismatch input_type(VAE)` |
|
||||
| ✅ Correct | `vae: ["236", 2]` |
|
||||
|
||||
---
|
||||
|
||||
## Dynamic template nodes: dotted key names are correct
|
||||
|
||||
### ComfyMathExpression (COMFY_AUTOGROW_V3)
|
||||
|
||||
```json
|
||||
{
|
||||
"class_type": "ComfyMathExpression",
|
||||
"inputs": {
|
||||
"expression": "a/2",
|
||||
"values.a": ["257", 0]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
- `values` is a `COMFY_AUTOGROW_V3` template.
|
||||
- Input names in links are `values.a`, `values.b`, etc.
|
||||
- **Keep the dotted format as JSON keys.**
|
||||
- Do NOT convert to `{"values": {"a": ...}}` or flatten to just `"a"`.
|
||||
|
||||
### ResizeImageMaskNode (COMFY_DYNAMICCOMBO_V3)
|
||||
|
||||
```json
|
||||
{
|
||||
"class_type": "ResizeImageMaskNode",
|
||||
"inputs": {
|
||||
"input": ["276", 0],
|
||||
"scale_method": "lanczos",
|
||||
"resize_type": "scale dimensions",
|
||||
"resize_type.width": 1920,
|
||||
"resize_type.height": 1088,
|
||||
"resize_type.crop": "center"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
- `resize_type` is a `COMFY_DYNAMICCOMBO_V3`.
|
||||
- Mode-specific fields: `resize_type.width`, `resize_type.height`, `resize_type.crop`.
|
||||
- `scale_method` options: `"nearest-exact"`, `"bilinear"`, `"area"`, `"bicubic"`, `"lanczos"`.
|
||||
- **Keep the dotted format as JSON keys.**
|
||||
- Do NOT flatten `resize_type.width` to just `"width"`.
|
||||
|
||||
---
|
||||
|
||||
## Conversion recipe
|
||||
|
||||
1. Load template from the installed package path.
|
||||
2. Parse `data['definitions']['subgraphs'][0]`.
|
||||
3. For each node (skip Reroute):
|
||||
- Resolve linked inputs from `sg['links']` dict.
|
||||
- Map `widgets_values` to input field names.
|
||||
- Keep all dotted key names as-is from the template.
|
||||
4. Bypass Reroute: trace source, replace references.
|
||||
5. Change only: prompt text, seed values, and user-requested parameters.
|
||||
6. Add `SaveVideo` terminal node if template uses only `CreateVideo`.
|
||||
7. Submit → read errors → patch specific nodes → resubmit.
|
||||
|
||||
## What to NEVER change in a template
|
||||
|
||||
| Element | Why |
|
||||
|---------|-----|
|
||||
| Node topology | Graph is designed for the specific model |
|
||||
| Sigmas values | Tuned for the model/sampler combination |
|
||||
| LoRA/distilled paths | Required for quality, even if they look unused |
|
||||
| Model parameters (cfg, steps, shifts) | Model-specific |
|
||||
| Conditioning chains (zero-out, crop guides) | Required for correct conditioning |
|
||||
| Pass-through wiring | Don't remove nodes, bypass them |
|
||||
|
||||
---
|
||||
|
||||
## Cloud compatibility (verified May 2025)
|
||||
|
||||
The full LTX 2.3 T2V template (`video_ltx2_3_t2v.json`) runs **without
|
||||
modification** on Comfy Cloud.
|
||||
|
||||
**Confirmed working on Cloud (all custom nodes available):**
|
||||
`ComfyMathExpression`, `ResizeImageMaskNode`, `ResizeImagesByLongerEdge`,
|
||||
`PrimitiveInt`, `PrimitiveStringMultiline`, `PrimitiveBoolean`, `SaveVideo`,
|
||||
`LTXVCropGuides`, `LTXVImgToVideoInplace`, `LTXVConcatAVLatent`,
|
||||
`LTXVSeparateAVLatent`, `LTXVLatentUpsampler`, `LTXVAudioVAELoader`,
|
||||
`LTXVAudioVAEDecode`, `LTXVEmptyLatentAudio`, `LTXVPreprocess`,
|
||||
`LTXVConditioning`, `ManualSigmas`, `LTXAVTextEncoderLoader`, plus all core
|
||||
nodes.
|
||||
|
||||
**Cloud vs Local for LTX 2.3 (768x512):**
|
||||
|
||||
- Cloud: ~39s per video (4x faster).
|
||||
- Local (RTX 5090): ~160s per video.
|
||||
- `example.png` placeholder works on Cloud for bypassed image-dependent paths.
|
||||
- Submission format is **identical** between local and Cloud:
|
||||
`{"prompt": wf, "extra_data": {}}` to `/api/prompt`.
|
||||
- Free tier = 1 concurrent job.
|
||||
|
||||
**Cloud submission pitfalls:**
|
||||
|
||||
- `/api/object_info/<node>` returns 404 on free tier — can't query node
|
||||
schemas remotely, but the workflow runs fine anyway. Always probe
|
||||
`object_info` locally before building workflows.
|
||||
- Cloud is ~4x faster — prefer Cloud for batch runs unless local is needed
|
||||
for debugging.
|
||||
- Cloud `/api/view` returns **302 redirect to signed GCS URL** — use
|
||||
`curl -s -L` to follow and download. Python `urllib` fails with 401
|
||||
(forwards auth headers to GCS CDN).
|
||||
- `COMFY_CLOUD_API_KEY` is only in the terminal/bash env, not in the Python
|
||||
sandbox. Use subprocess or terminal scripts for Cloud API calls.
|
||||
- Cloud free tier processes jobs **sequentially** (1 at a time). Submit all,
|
||||
then poll history.
|
||||
- LTX 2.3 at **1920x1080 OOMs locally** (even RTX 5090) — upscaler pass
|
||||
exceeds VRAM. Prefer Cloud for 1080p; use 1280x720 locally (~90s/video).
|
||||
|
||||
---
|
||||
|
||||
## FFmpeg stitch settings (Discord-compatible)
|
||||
|
||||
Generated ComfyUI videos often use `yuv444p` pixel format which does NOT work
|
||||
on Discord. Re-encode with:
|
||||
|
||||
```bash
|
||||
ffmpeg -y -i input.mp4 \
|
||||
-c:v libx264 -profile:v main -preset medium -crf 13 -pix_fmt yuv420p \
|
||||
-c:a aac -b:a 192k \
|
||||
output_discord.mp4
|
||||
```
|
||||
|
||||
Key settings:
|
||||
|
||||
- `-pix_fmt yuv420p` — **required for Discord**, ComfyUI outputs `yuv444p` by default.
|
||||
- `-crf 13` — high quality without massive file size (default 23 is too lossy).
|
||||
- `-profile:v main` — widely compatible.
|
||||
|
||||
For multi-video crossfade stitching, chain `xfade` (video) and `acrossfade`
|
||||
(audio):
|
||||
|
||||
```bash
|
||||
ffmpeg -y -i a.mp4 -i b.mp4 -i c.mp4 \
|
||||
-filter_complex "[0:v][1:v]xfade=transition=fade:duration=1:offset=3.04[v1];[v1][2:v]xfade=transition=fade:duration=1:offset=6.08[vout];[0:a][1:a]acrossfade=duration=1:c1=tri:c2=tri[a1];[a1][2:a]acrossfade=duration=1:c1=tri:c2=tri[aout]" \
|
||||
-map "[vout]" -map "[aout]" \
|
||||
-c:v libx264 -profile:v main -crf 13 -pix_fmt yuv420p \
|
||||
-c:a aac -b:a 192k \
|
||||
output.mp4
|
||||
```
|
||||
|
||||
Offset for xfade #N = `(N+1) × duration - N × overlap`.
|
||||
@@ -0,0 +1,226 @@
|
||||
# ComfyUI Workflow JSON Format
|
||||
|
||||
## Two Formats — Only API Format Is Executable
|
||||
|
||||
**API format** is required for `/api/prompt` and every script in this skill.
|
||||
The web UI also produces an "editor format" used for visual editing, which
|
||||
**cannot** be submitted directly.
|
||||
|
||||
### API Format
|
||||
|
||||
Top-level keys are string node IDs. Each node has `class_type` and `inputs`:
|
||||
|
||||
```json
|
||||
{
|
||||
"3": {
|
||||
"class_type": "KSampler",
|
||||
"inputs": {
|
||||
"seed": 156680208700286,
|
||||
"steps": 20,
|
||||
"cfg": 8,
|
||||
"sampler_name": "euler",
|
||||
"scheduler": "normal",
|
||||
"denoise": 1.0,
|
||||
"model": ["4", 0],
|
||||
"positive": ["6", 0],
|
||||
"negative": ["7", 0],
|
||||
"latent_image": ["5", 0]
|
||||
},
|
||||
"_meta": {"title": "KSampler"}
|
||||
},
|
||||
"4": {
|
||||
"class_type": "CheckpointLoaderSimple",
|
||||
"inputs": {"ckpt_name": "v1-5-pruned-emaonly.safetensors"}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**Detection:** every top-level value has `class_type`. The skill's
|
||||
`_common.is_api_format()` does this check.
|
||||
|
||||
### Editor Format (not directly executable)
|
||||
|
||||
Has `nodes[]` and `links[]` arrays — the visual graph. To convert: open in
|
||||
ComfyUI's web UI and use **Workflow → Export (API)** (newer UI) or the
|
||||
"Save (API Format)" button (older UI).
|
||||
|
||||
**Detection:** top-level has `"nodes"` and `"links"` keys.
|
||||
|
||||
## Inputs: Literals vs Links
|
||||
|
||||
```json
|
||||
"inputs": {
|
||||
"text": "a cat", // literal — modifiable
|
||||
"seed": 42, // literal — modifiable
|
||||
"clip": ["4", 1] // link — wiring; do NOT overwrite
|
||||
}
|
||||
```
|
||||
|
||||
Links are length-2 arrays of `[upstream_node_id, output_slot]`. The skill's
|
||||
parameter injector refuses to overwrite a link with a literal (logs a
|
||||
warning and skips).
|
||||
|
||||
## Common Node Types and Their Controllable Parameters
|
||||
|
||||
The full catalog lives in `scripts/_common.py` (`PARAM_PATTERNS` and
|
||||
`MODEL_LOADERS`). Highlights:
|
||||
|
||||
### Text Prompts
|
||||
|
||||
| Node Class | Key Fields |
|
||||
|------------|------------|
|
||||
| `CLIPTextEncode` | `text` |
|
||||
| `CLIPTextEncodeSDXL` | `text_g`, `text_l`, `width`, `height` |
|
||||
| `CLIPTextEncodeFlux` | `clip_l`, `t5xxl`, `guidance` |
|
||||
|
||||
To distinguish positive from negative the skill traces `KSampler.negative`
|
||||
back through Reroute / Primitive nodes to the source CLIPTextEncode. Falls
|
||||
back to `_meta.title` heuristics ("negative", "neg", "anti").
|
||||
|
||||
### Sampling
|
||||
|
||||
| Node Class | Key Fields |
|
||||
|------------|------------|
|
||||
| `KSampler` | `seed`, `steps`, `cfg`, `sampler_name`, `scheduler`, `denoise` |
|
||||
| `KSamplerAdvanced` | `noise_seed`, `steps`, `cfg`, `start_at_step`, `end_at_step` |
|
||||
| `SamplerCustom` | `noise_seed`, `cfg`, `sampler`, `sigmas` |
|
||||
| `SamplerCustomAdvanced` | `noise_seed` (via RandomNoise input) |
|
||||
| `RandomNoise` | `noise_seed` |
|
||||
| `BasicScheduler` | `steps`, `scheduler`, `denoise` |
|
||||
| `KSamplerSelect` | `sampler_name` |
|
||||
| `BasicGuider` / `CFGGuider` | `cfg` |
|
||||
| `ModelSamplingFlux` | `max_shift`, `base_shift`, `width`, `height` |
|
||||
| `SDTurboScheduler` | `steps`, `denoise` |
|
||||
|
||||
### Latent / Dimensions
|
||||
|
||||
| Node Class | Key Fields |
|
||||
|------------|------------|
|
||||
| `EmptyLatentImage` | `width`, `height`, `batch_size` |
|
||||
| `EmptySD3LatentImage` | `width`, `height`, `batch_size` |
|
||||
| `EmptyHunyuanLatentVideo` | `width`, `height`, `length`, `batch_size` |
|
||||
| `EmptyMochiLatentVideo` | `width`, `height`, `length`, `batch_size` |
|
||||
| `EmptyLTXVLatentVideo` | `width`, `height`, `length`, `batch_size` |
|
||||
|
||||
### Model Loading
|
||||
|
||||
| Node Class | Key Fields | Folder |
|
||||
|------------|------------|--------|
|
||||
| `CheckpointLoaderSimple` | `ckpt_name` | `checkpoints` |
|
||||
| `LoraLoader` | `lora_name`, `strength_model`, `strength_clip` | `loras` |
|
||||
| `LoraLoaderModelOnly` | `lora_name`, `strength_model` | `loras` |
|
||||
| `VAELoader` | `vae_name` | `vae` |
|
||||
| `ControlNetLoader` | `control_net_name` | `controlnet` |
|
||||
| `CLIPLoader` | `clip_name` | `clip` |
|
||||
| `DualCLIPLoader` | `clip_name1`, `clip_name2` | `clip` |
|
||||
| `TripleCLIPLoader` | `clip_name1/2/3` | `clip` |
|
||||
| `UNETLoader` | `unet_name` | `unet` |
|
||||
| `DiffusionModelLoader` | `model_name` | `diffusion_models` |
|
||||
| `UpscaleModelLoader` | `model_name` | `upscale_models` |
|
||||
| `IPAdapterModelLoader` | `ipadapter_file` | `ipadapter` |
|
||||
| `ADE_AnimateDiffLoaderWithContext` | `model_name`, `motion_scale` | `animatediff_models` |
|
||||
|
||||
### Image Input/Output
|
||||
|
||||
| Node Class | Key Fields |
|
||||
|------------|------------|
|
||||
| `LoadImage` | `image` (server-side filename, after upload) |
|
||||
| `LoadImageMask` | `image`, `channel` (`red` / `green` / `blue` / `alpha`) |
|
||||
| `VAEEncode` / `VAEDecode` | (no controllable fields) |
|
||||
| `VAEEncodeForInpaint` | `grow_mask_by` |
|
||||
| `SaveImage` | `filename_prefix` |
|
||||
| `VHS_VideoCombine` | `frame_rate`, `format`, `filename_prefix`, `loop_count`, `pingpong` |
|
||||
|
||||
### ControlNet
|
||||
|
||||
| Node Class | Key Fields |
|
||||
|------------|------------|
|
||||
| `ControlNetApply` | `strength` |
|
||||
| `ControlNetApplyAdvanced` | `strength`, `start_percent`, `end_percent` |
|
||||
|
||||
### IPAdapter (community pack `comfyui_ipadapter_plus`)
|
||||
|
||||
| Node Class | Key Fields |
|
||||
|------------|------------|
|
||||
| `IPAdapterAdvanced` | `weight`, `start_at`, `end_at` |
|
||||
| `IPAdapter` | `weight` |
|
||||
|
||||
### Embeddings (referenced inside prompt strings)
|
||||
|
||||
ComfyUI scans prompt text for `embedding:NAME` syntax. The skill's
|
||||
`_common.iter_embedding_refs()` extracts these as model dependencies.
|
||||
|
||||
```text
|
||||
"a beautiful cat, embedding:goodvibes:1.2, embedding:art-style"
|
||||
```
|
||||
|
||||
`extract_schema.py` and `check_deps.py` surface these in
|
||||
`embedding_dependencies` / `missing_embeddings`.
|
||||
|
||||
## Parameter Injection Pattern
|
||||
|
||||
```python
|
||||
import json, copy
|
||||
|
||||
with open("workflow_api.json") as f:
|
||||
workflow = json.load(f)
|
||||
|
||||
wf = copy.deepcopy(workflow)
|
||||
wf["6"]["inputs"]["text"] = "a beautiful sunset"
|
||||
wf["7"]["inputs"]["text"] = "ugly, blurry"
|
||||
wf["3"]["inputs"]["seed"] = 42
|
||||
wf["3"]["inputs"]["steps"] = 30
|
||||
wf["5"]["inputs"]["width"] = 1024
|
||||
wf["5"]["inputs"]["height"] = 1024
|
||||
```
|
||||
|
||||
`scripts/extract_schema.py` automates discovering which node IDs/fields
|
||||
correspond to which user-facing parameters. It returns a `parameters` dict
|
||||
that `run_workflow.py` reads to inject values from `--args`.
|
||||
|
||||
## Identifying Controllable Parameters (Heuristics)
|
||||
|
||||
For unknown workflows:
|
||||
|
||||
1. **Prompt text** — any `CLIPTextEncode.text`. Use connection tracing back
|
||||
from `KSampler.positive` / `.negative` to disambiguate (don't trust
|
||||
meta-title alone).
|
||||
2. **Seed** — `KSampler.seed` / `KSamplerAdvanced.noise_seed` / `RandomNoise.noise_seed`.
|
||||
3. **Dimensions** — `Empty*LatentImage.width/height` (must be multiples of 8).
|
||||
4. **Steps / CFG** — `KSampler.steps`, `KSampler.cfg`. Steps 20–50 typical.
|
||||
CFG 5–15 typical (Flux uses guidance, not CFG).
|
||||
5. **Model / checkpoint** — `CheckpointLoaderSimple.ckpt_name`. Filename must
|
||||
match an installed file *exactly*.
|
||||
6. **LoRA** — `LoraLoader.lora_name`, `.strength_model`.
|
||||
7. **Images for img2img / inpaint** — `LoadImage.image`. Server-side filename
|
||||
after upload.
|
||||
8. **Denoise** — `KSampler.denoise`. 0.0–1.0; 1.0 = ignore input image,
|
||||
0.0 = pass through. Sweet spot for img2img: 0.4–0.7.
|
||||
|
||||
## Output Nodes
|
||||
|
||||
Output is produced by these node types. The skill's `OUTPUT_NODES` set
|
||||
extends to common community packs.
|
||||
|
||||
| Node | Output Key | Content |
|
||||
|------|-----------|---------|
|
||||
| `SaveImage` | `images` | List of `{filename, subfolder, type}` |
|
||||
| `PreviewImage` | `images` | Temporary preview (not saved) |
|
||||
| `VHS_VideoCombine` | `gifs` (older) or `videos`/`video` (newer cloud) | Video file refs |
|
||||
| `SaveAudio` | `audio` | Audio file refs |
|
||||
| `SaveAnimatedWEBP` / `SaveAnimatedPNG` | `images` | Animated images |
|
||||
| `Save3D` | `3d` | 3D asset refs |
|
||||
|
||||
After execution, fetch outputs from `/history/{prompt_id}` (local) or
|
||||
`/api/jobs/{prompt_id}` (cloud) → `outputs` → `{node_id}` → `{key}`.
|
||||
|
||||
## Wrapper Variants
|
||||
|
||||
Some saved JSON files wrap the workflow under a `"prompt"` key (matching
|
||||
the `/api/prompt` payload shape). The skill's `_common.unwrap_workflow()`
|
||||
handles this — pass any of:
|
||||
|
||||
- raw API format: `{"3": {...}, "4": {...}}`
|
||||
- wrapped: `{"prompt": {"3": {...}}, "client_id": "..."}`
|
||||
|
||||
It rejects editor format with a clear error and a re-export instruction.
|
||||
@@ -0,0 +1,835 @@
|
||||
"""
|
||||
_common.py — Shared logic for ComfyUI skill scripts.
|
||||
|
||||
Single source of truth for:
|
||||
- HTTP transport (with retry/backoff, streaming, timeout handling)
|
||||
- Cloud detection and endpoint mapping (local ComfyUI vs Comfy Cloud)
|
||||
- Workflow node-type catalogs (param patterns, model loaders, output nodes)
|
||||
- API-format validation
|
||||
- Path-traversal-safe file writes
|
||||
- API-key loading from env / CLI
|
||||
|
||||
Stdlib-only by design (with optional `requests` upgrade if installed). Python 3.10+.
|
||||
"""
|
||||
|
||||
from __future__ import annotations
|
||||
|
||||
import json
|
||||
import os
|
||||
import random
|
||||
import re
|
||||
import sys
|
||||
import time
|
||||
import uuid
|
||||
from dataclasses import dataclass
|
||||
from pathlib import Path
|
||||
from typing import Any, Iterator
|
||||
from urllib.parse import urlparse
|
||||
|
||||
# Optional: prefer `requests` if installed (better redirects, streaming, header handling)
|
||||
try:
|
||||
import requests # type: ignore[import-not-found]
|
||||
HAS_REQUESTS = True
|
||||
except ImportError: # pragma: no cover - exercised via stdlib fallback
|
||||
HAS_REQUESTS = False
|
||||
import urllib.error
|
||||
import urllib.request
|
||||
|
||||
|
||||
# =============================================================================
|
||||
# Constants & catalogs
|
||||
# =============================================================================
|
||||
|
||||
DEFAULT_LOCAL_HOST = "http://127.0.0.1:8188"
|
||||
DEFAULT_CLOUD_HOST = "https://cloud.comfy.org"
|
||||
ENV_API_KEY = "COMFY_CLOUD_API_KEY" # env var NAME (placeholder, not a secret value)
|
||||
|
||||
# Connection / retry defaults
|
||||
DEFAULT_HTTP_TIMEOUT = 60 # seconds — single-attempt request timeout
|
||||
DEFAULT_RETRIES = 3 # total attempts including the first
|
||||
RETRY_BASE_DELAY = 1.0 # seconds — exponential backoff base
|
||||
RETRY_MAX_DELAY = 30.0 # seconds — cap on backoff
|
||||
RETRY_STATUS_CODES = {408, 429, 500, 502, 503, 504, 522, 524}
|
||||
|
||||
# Streaming download chunk size (bytes)
|
||||
DOWNLOAD_CHUNK_SIZE = 1 << 16 # 64 KiB
|
||||
|
||||
# Heuristic: workflows with these node types tend to be slow → larger default timeout
|
||||
SLOW_OUTPUT_NODES = {
|
||||
"VHS_VideoCombine", "SaveAnimatedWEBP", "SaveAnimatedPNG",
|
||||
"SaveVideo", "SaveAudio", "SaveAnimateDiffVideo",
|
||||
"SVD_img2vid_Conditioning",
|
||||
"WanVideoSampler", "HunyuanVideoSampler",
|
||||
"CogVideoSampler", "LTXVideoSampler",
|
||||
}
|
||||
|
||||
# ---------------------------------------------------------------------------
|
||||
# Output node catalog (extensible — community packs add their own)
|
||||
# ---------------------------------------------------------------------------
|
||||
OUTPUT_NODES: set[str] = {
|
||||
# Built-in
|
||||
"SaveImage", "PreviewImage",
|
||||
"SaveAudio", "SaveVideo", "PreviewAudio", "PreviewVideo",
|
||||
"SaveAnimatedWEBP", "SaveAnimatedPNG",
|
||||
# Common community packs
|
||||
"VHS_VideoCombine", # Video Helper Suite
|
||||
"ImageSave", # Was Node Suite
|
||||
"Image Save", # Was Node Suite (alt name)
|
||||
"easy imageSave", # easy-use
|
||||
"Image Save With Metadata",
|
||||
"PreviewImage|pysssss", # pysssss preview
|
||||
"ShowText|pysssss",
|
||||
"SaveLatent",
|
||||
"SaveGLB", # 3D
|
||||
"Save3D",
|
||||
}
|
||||
|
||||
# ---------------------------------------------------------------------------
|
||||
# Folder aliases — handle ComfyUI's gradual folder renames
|
||||
# ---------------------------------------------------------------------------
|
||||
# When `check_deps.py` queries `/models/<folder>` and gets 404 / empty,
|
||||
# it tries each alias in turn. Critical for Comfy Cloud which has fully
|
||||
# migrated to the new naming (unet → diffusion_models, clip → text_encoders).
|
||||
FOLDER_ALIASES: dict[str, list[str]] = {
|
||||
"unet": ["unet", "diffusion_models"],
|
||||
"diffusion_models": ["diffusion_models", "unet"],
|
||||
"clip": ["clip", "text_encoders"],
|
||||
"text_encoders": ["text_encoders", "clip"],
|
||||
"controlnet": ["controlnet", "control_net"],
|
||||
}
|
||||
|
||||
|
||||
def folder_aliases_for(folder: str) -> list[str]:
|
||||
"""Return the search order of folder names (primary first)."""
|
||||
return FOLDER_ALIASES.get(folder, [folder])
|
||||
|
||||
|
||||
# ---------------------------------------------------------------------------
|
||||
# Model-loader catalog: class_type -> (input field, model folder)
|
||||
# ---------------------------------------------------------------------------
|
||||
# A loader can have multiple fields (e.g., DualCLIPLoader has clip_name1 and
|
||||
# clip_name2). We list them with explicit entries. The folder name is the
|
||||
# *canonical* one; FOLDER_ALIASES is consulted when querying.
|
||||
MODEL_LOADERS: dict[str, list[tuple[str, str]]] = {
|
||||
# Checkpoints
|
||||
"CheckpointLoaderSimple": [("ckpt_name", "checkpoints")],
|
||||
"CheckpointLoader": [("ckpt_name", "checkpoints")],
|
||||
"CheckpointLoader (Simple)": [("ckpt_name", "checkpoints")],
|
||||
"ImageOnlyCheckpointLoader": [("ckpt_name", "checkpoints")],
|
||||
"unCLIPCheckpointLoader": [("ckpt_name", "checkpoints")],
|
||||
# LoRA
|
||||
"LoraLoader": [("lora_name", "loras")],
|
||||
"LoraLoaderModelOnly": [("lora_name", "loras")],
|
||||
"LoraLoaderTagsQuery": [("lora_name", "loras")],
|
||||
# VAE
|
||||
"VAELoader": [("vae_name", "vae")],
|
||||
# ControlNet
|
||||
"ControlNetLoader": [("control_net_name", "controlnet")],
|
||||
"DiffControlNetLoader": [("control_net_name", "controlnet")],
|
||||
"ControlNetLoaderAdvanced": [("control_net_name", "controlnet")],
|
||||
# CLIP / text encoders (primary "clip" folder; check_deps tries text_encoders too)
|
||||
"CLIPLoader": [("clip_name", "clip")],
|
||||
"DualCLIPLoader": [("clip_name1", "clip"), ("clip_name2", "clip")],
|
||||
"TripleCLIPLoader": [("clip_name1", "clip"), ("clip_name2", "clip"), ("clip_name3", "clip")],
|
||||
"CLIPVisionLoader": [("clip_name", "clip_vision")],
|
||||
# UNET / Diffusion model (primary "unet"; check_deps tries diffusion_models too)
|
||||
"UNETLoader": [("unet_name", "unet")],
|
||||
"DiffusionModelLoader": [("model_name", "diffusion_models")],
|
||||
"UNETLoaderGGUF": [("unet_name", "unet")],
|
||||
# Upscaler
|
||||
"UpscaleModelLoader": [("model_name", "upscale_models")],
|
||||
# Style / GLIGEN / Hypernetwork
|
||||
"StyleModelLoader": [("style_model_name", "style_models")],
|
||||
"GLIGENLoader": [("gligen_name", "gligen")],
|
||||
"HypernetworkLoader": [("hypernetwork_name", "hypernetworks")],
|
||||
# IPAdapter family (community).
|
||||
# Note: IPAdapterUnifiedLoader's `preset` and IPAdapterInsightFaceLoader's
|
||||
# `provider` are enums (not file paths), so they're intentionally omitted —
|
||||
# check_deps would otherwise treat enum values as missing model files.
|
||||
"IPAdapterModelLoader": [("ipadapter_file", "ipadapter")],
|
||||
"InstantIDModelLoader": [("instantid_file", "instantid")],
|
||||
# AnimateDiff / video
|
||||
"ADE_LoadAnimateDiffModel": [("model_name", "animatediff_models")],
|
||||
"ADE_AnimateDiffLoaderWithContext": [("model_name", "animatediff_models")],
|
||||
"ADE_AnimateDiffLoaderGen1": [("model_name", "animatediff_models")],
|
||||
# Photomaker
|
||||
"PhotoMakerLoader": [("photomaker_model_name", "photomaker")],
|
||||
# Sampler / scheduler models
|
||||
"ModelSamplingFlux": [], # parametric only
|
||||
}
|
||||
|
||||
# ---------------------------------------------------------------------------
|
||||
# Param patterns: (class_type, field_name) -> friendly_name
|
||||
# Order matters — first match wins for naming. Use _meta.title for disambiguation.
|
||||
# ---------------------------------------------------------------------------
|
||||
PARAM_PATTERNS: list[tuple[str, str, str]] = [
|
||||
# ---- Prompts ----
|
||||
("CLIPTextEncode", "text", "prompt"),
|
||||
("CLIPTextEncodeSDXL", "text_g", "prompt"),
|
||||
("CLIPTextEncodeSDXL", "text_l", "prompt_l"),
|
||||
("CLIPTextEncodeSDXLRefiner", "text", "refiner_prompt"),
|
||||
("CLIPTextEncodeFlux", "clip_l", "prompt_l"),
|
||||
("CLIPTextEncodeFlux", "t5xxl", "prompt"),
|
||||
("CLIPTextEncodeFlux", "guidance", "guidance"),
|
||||
("smZ CLIPTextEncode", "text", "prompt"),
|
||||
("BNK_CLIPTextEncodeAdvanced", "text", "prompt"),
|
||||
|
||||
# ---- Standard sampling ----
|
||||
("KSampler", "seed", "seed"),
|
||||
("KSampler", "steps", "steps"),
|
||||
("KSampler", "cfg", "cfg"),
|
||||
("KSampler", "sampler_name", "sampler_name"),
|
||||
("KSampler", "scheduler", "scheduler"),
|
||||
("KSampler", "denoise", "denoise"),
|
||||
("KSamplerAdvanced", "noise_seed", "seed"),
|
||||
("KSamplerAdvanced", "steps", "steps"),
|
||||
("KSamplerAdvanced", "cfg", "cfg"),
|
||||
("KSamplerAdvanced", "sampler_name", "sampler_name"),
|
||||
("KSamplerAdvanced", "scheduler", "scheduler"),
|
||||
("KSamplerAdvanced", "start_at_step", "start_at_step"),
|
||||
("KSamplerAdvanced", "end_at_step", "end_at_step"),
|
||||
|
||||
# ---- Modern sampler chain (Flux / SD3 / SDXL refiner via SamplerCustom) ----
|
||||
("RandomNoise", "noise_seed", "seed"),
|
||||
("BasicScheduler", "steps", "steps"),
|
||||
("BasicScheduler", "scheduler", "scheduler"),
|
||||
("BasicScheduler", "denoise", "denoise"),
|
||||
("KSamplerSelect", "sampler_name", "sampler_name"),
|
||||
# NB: BasicGuider has no cfg input (it just bundles model+conditioning).
|
||||
("CFGGuider", "cfg", "cfg"),
|
||||
("DualCFGGuider", "cfg_conds", "cfg"),
|
||||
("DualCFGGuider", "cfg_cond2_negative", "cfg_negative"),
|
||||
("ModelSamplingFlux", "max_shift", "max_shift"),
|
||||
("ModelSamplingFlux", "base_shift", "base_shift"),
|
||||
("ModelSamplingFlux", "width", "model_width"),
|
||||
("ModelSamplingFlux", "height", "model_height"),
|
||||
("ModelSamplingSD3", "shift", "shift"),
|
||||
("ModelSamplingDiscrete", "sampling", "sampling"),
|
||||
("SDTurboScheduler", "steps", "steps"),
|
||||
("SDTurboScheduler", "denoise", "denoise"),
|
||||
("SamplerCustom", "noise_seed", "seed"),
|
||||
("SamplerCustom", "cfg", "cfg"),
|
||||
# NB: SamplerCustomAdvanced takes a NOISE input (from RandomNoise) — no seed field directly.
|
||||
|
||||
# ---- Dimensions / latent ----
|
||||
("EmptyLatentImage", "width", "width"),
|
||||
("EmptyLatentImage", "height", "height"),
|
||||
("EmptyLatentImage", "batch_size", "batch_size"),
|
||||
("EmptySD3LatentImage", "width", "width"),
|
||||
("EmptySD3LatentImage", "height", "height"),
|
||||
("EmptySD3LatentImage", "batch_size", "batch_size"),
|
||||
("EmptyHunyuanLatentVideo", "width", "width"),
|
||||
("EmptyHunyuanLatentVideo", "height", "height"),
|
||||
("EmptyHunyuanLatentVideo", "length", "length"),
|
||||
("EmptyHunyuanLatentVideo", "batch_size", "batch_size"),
|
||||
("EmptyMochiLatentVideo", "width", "width"),
|
||||
("EmptyMochiLatentVideo", "height", "height"),
|
||||
("EmptyMochiLatentVideo", "length", "length"),
|
||||
("EmptyLTXVLatentVideo", "width", "width"),
|
||||
("EmptyLTXVLatentVideo", "height", "height"),
|
||||
("EmptyLTXVLatentVideo", "length", "length"),
|
||||
("LatentUpscale", "width", "upscale_width"),
|
||||
("LatentUpscale", "height", "upscale_height"),
|
||||
("LatentUpscaleBy", "scale_by", "scale_by"),
|
||||
("ImageScale", "width", "width"),
|
||||
("ImageScale", "height", "height"),
|
||||
|
||||
# ---- Image input ----
|
||||
("LoadImage", "image", "image"),
|
||||
("LoadImageMask", "image", "mask_image"),
|
||||
("LoadImageOutput", "image", "image"),
|
||||
("VHS_LoadVideo", "video", "video"),
|
||||
("VHS_LoadAudio", "audio", "audio"),
|
||||
|
||||
# ---- Model selection (sometimes useful to swap per run) ----
|
||||
("CheckpointLoaderSimple", "ckpt_name", "ckpt_name"),
|
||||
("CheckpointLoader", "ckpt_name", "ckpt_name"),
|
||||
("ImageOnlyCheckpointLoader", "ckpt_name", "ckpt_name"),
|
||||
("VAELoader", "vae_name", "vae_name"),
|
||||
("UNETLoader", "unet_name", "unet_name"),
|
||||
("DiffusionModelLoader", "model_name", "diffusion_model_name"),
|
||||
("UpscaleModelLoader", "model_name", "upscale_model_name"),
|
||||
("CLIPLoader", "clip_name", "clip_name"),
|
||||
("DualCLIPLoader", "clip_name1", "clip_name1"),
|
||||
("DualCLIPLoader", "clip_name2", "clip_name2"),
|
||||
("ControlNetLoader", "control_net_name", "controlnet_name"),
|
||||
|
||||
# ---- LoRA ----
|
||||
("LoraLoader", "lora_name", "lora_name"),
|
||||
("LoraLoader", "strength_model", "lora_strength"),
|
||||
("LoraLoader", "strength_clip", "lora_strength_clip"),
|
||||
("LoraLoaderModelOnly", "lora_name", "lora_name"),
|
||||
("LoraLoaderModelOnly", "strength_model", "lora_strength"),
|
||||
|
||||
# ---- ControlNet ----
|
||||
("ControlNetApply", "strength", "controlnet_strength"),
|
||||
("ControlNetApplyAdvanced", "strength", "controlnet_strength"),
|
||||
("ControlNetApplyAdvanced", "start_percent", "controlnet_start"),
|
||||
("ControlNetApplyAdvanced", "end_percent", "controlnet_end"),
|
||||
|
||||
# ---- IPAdapter ----
|
||||
("IPAdapterAdvanced", "weight", "ipadapter_weight"),
|
||||
("IPAdapterAdvanced", "start_at", "ipadapter_start"),
|
||||
("IPAdapterAdvanced", "end_at", "ipadapter_end"),
|
||||
("IPAdapter", "weight", "ipadapter_weight"),
|
||||
|
||||
# ---- Upscale ----
|
||||
("ImageUpscaleWithModel", "upscale_method", "upscale_method"),
|
||||
|
||||
# ---- AnimateDiff ----
|
||||
("ADE_AnimateDiffLoaderWithContext", "motion_scale", "motion_scale"),
|
||||
("ADE_AnimateDiffLoaderGen1", "motion_scale", "motion_scale"),
|
||||
|
||||
# ---- Video / Save ----
|
||||
("VHS_VideoCombine", "frame_rate", "frame_rate"),
|
||||
("VHS_VideoCombine", "format", "video_format"),
|
||||
("VHS_VideoCombine", "filename_prefix", "filename_prefix"),
|
||||
("SaveImage", "filename_prefix", "filename_prefix"),
|
||||
|
||||
# ---- Hunyuan / Wan / LTX video ----
|
||||
("HunyuanVideoSampler", "seed", "seed"),
|
||||
("HunyuanVideoSampler", "steps", "steps"),
|
||||
("HunyuanVideoSampler", "cfg", "cfg"),
|
||||
("WanVideoSampler", "seed", "seed"),
|
||||
("WanVideoSampler", "steps", "steps"),
|
||||
("WanVideoSampler", "cfg", "cfg"),
|
||||
("LTXVScheduler", "max_shift", "max_shift"),
|
||||
("LTXVScheduler", "base_shift", "base_shift"),
|
||||
|
||||
# ---- rgthree primitives (often used as user-facing inputs) ----
|
||||
("Seed (rgthree)", "seed", "seed"),
|
||||
("Image Comparer (rgthree)", "image_a", "image"),
|
||||
("Power Lora Loader (rgthree)", "PowerLoraLoaderHeaderWidget", "_lora_header"),
|
||||
|
||||
# ---- Easy-use / utility primitives ----
|
||||
("PrimitiveNode", "value", "primitive_value"),
|
||||
("easy seed", "seed", "seed"),
|
||||
("easy positive", "positive", "prompt"),
|
||||
("easy negative", "negative", "negative_prompt"),
|
||||
("easy fullLoader", "ckpt_name", "ckpt_name"),
|
||||
("easy fullLoader", "vae_name", "vae_name"),
|
||||
("easy fullLoader", "lora_name", "lora_name"),
|
||||
("easy fullLoader", "positive", "prompt"),
|
||||
("easy fullLoader", "negative", "negative_prompt"),
|
||||
]
|
||||
|
||||
# Prompt-like fields whose value should be scanned for embedding references
|
||||
PROMPT_FIELDS = {"text", "text_g", "text_l", "t5xxl", "clip_l", "positive", "negative"}
|
||||
|
||||
# Pattern matches: embedding:name, embedding:name.pt, embedding:name:1.2, (embedding:name:1.2)
|
||||
# Word-boundary at start avoids matching things like "no_embedding:foo".
|
||||
EMBEDDING_REGEX = re.compile(
|
||||
r"(?:^|[\s,(\[])embedding\s*:\s*([A-Za-z0-9_\-\./\\]+?)(?:\.(?:pt|safetensors|bin))?(?=[\s:,)\(\]]|$)",
|
||||
re.IGNORECASE,
|
||||
)
|
||||
|
||||
|
||||
# =============================================================================
|
||||
# Cloud detection & endpoint routing
|
||||
# =============================================================================
|
||||
|
||||
CLOUD_DOMAIN_SUFFIXES = (".comfy.org",)
|
||||
CLOUD_DOMAIN_EXACT = {"cloud.comfy.org"}
|
||||
|
||||
|
||||
def is_cloud_host(host: str) -> bool:
|
||||
"""True if the host points at Comfy Cloud (or staging/preview subdomain)."""
|
||||
parsed = urlparse(host if "://" in host else f"http://{host}")
|
||||
hostname = (parsed.hostname or "").lower()
|
||||
if hostname in CLOUD_DOMAIN_EXACT:
|
||||
return True
|
||||
return any(hostname.endswith(s) for s in CLOUD_DOMAIN_SUFFIXES)
|
||||
|
||||
|
||||
def build_cloud_aware_url(base: str, path: str, *, force_cloud: bool | None = None) -> str:
|
||||
"""Build a URL that adds /api prefix when targeting Comfy Cloud.
|
||||
|
||||
Local ComfyUI accepts both `/foo` and `/api/foo` for many endpoints.
|
||||
Cloud requires `/api/foo`.
|
||||
|
||||
`path` should be a path component (e.g. "/prompt") or full path with query
|
||||
(e.g. "/view?filename=x").
|
||||
"""
|
||||
base = base.rstrip("/")
|
||||
cloud = is_cloud_host(base) if force_cloud is None else force_cloud
|
||||
if not path.startswith("/"):
|
||||
path = "/" + path
|
||||
if cloud and not path.startswith("/api/"):
|
||||
path = "/api" + path
|
||||
return base + path
|
||||
|
||||
|
||||
def cloud_endpoint(path: str) -> str:
|
||||
"""Map a cloud endpoint path to its current canonical form.
|
||||
|
||||
Handles known renames documented in the Comfy Cloud API:
|
||||
/history -> /history_v2
|
||||
/models/<f> -> /experiment/models/<f>
|
||||
/models -> /experiment/models
|
||||
"""
|
||||
if path.startswith("/history") and not path.startswith("/history_v2"):
|
||||
return "/history_v2" + path[len("/history"):]
|
||||
if path.startswith("/models/"):
|
||||
return "/experiment/models/" + path[len("/models/"):]
|
||||
if path == "/models":
|
||||
return "/experiment/models"
|
||||
return path
|
||||
|
||||
|
||||
def resolve_url(base: str, path: str, *, is_cloud: bool | None = None) -> str:
|
||||
"""Top-level URL resolver. Applies cloud rename + /api prefix as needed."""
|
||||
cloud = is_cloud_host(base) if is_cloud is None else is_cloud
|
||||
if cloud:
|
||||
path = cloud_endpoint(path)
|
||||
return build_cloud_aware_url(base, path, force_cloud=cloud)
|
||||
|
||||
|
||||
# =============================================================================
|
||||
# API key resolution
|
||||
# =============================================================================
|
||||
|
||||
def resolve_api_key(explicit: str | None) -> str | None:
|
||||
"""Look up API key from CLI flag → env var. Strips whitespace and quotes."""
|
||||
val = explicit if explicit else os.environ.get(ENV_API_KEY)
|
||||
if val is None:
|
||||
return None
|
||||
val = val.strip().strip("'\"")
|
||||
return val or None
|
||||
|
||||
|
||||
# =============================================================================
|
||||
# HTTP transport
|
||||
# =============================================================================
|
||||
|
||||
@dataclass
|
||||
class HTTPResponse:
|
||||
status: int
|
||||
headers: dict[str, str]
|
||||
body: bytes
|
||||
url: str # final URL after redirects
|
||||
|
||||
def text(self, encoding: str = "utf-8") -> str:
|
||||
return self.body.decode(encoding, errors="replace")
|
||||
|
||||
def json(self) -> Any:
|
||||
return json.loads(self.body.decode("utf-8", errors="replace"))
|
||||
|
||||
|
||||
def _sleep_backoff(attempt: int, base: float = RETRY_BASE_DELAY, cap: float = RETRY_MAX_DELAY) -> None:
|
||||
"""Sleep with full-jitter exponential backoff."""
|
||||
delay = min(cap, base * (2 ** attempt))
|
||||
delay = random.uniform(0, delay)
|
||||
time.sleep(delay)
|
||||
|
||||
|
||||
def http_request(
|
||||
method: str,
|
||||
url: str,
|
||||
*,
|
||||
headers: dict[str, str] | None = None,
|
||||
json_body: Any = None,
|
||||
data: bytes | None = None,
|
||||
files: dict | None = None,
|
||||
form: dict | None = None,
|
||||
timeout: float = DEFAULT_HTTP_TIMEOUT,
|
||||
follow_redirects: bool = True,
|
||||
retries: int = DEFAULT_RETRIES,
|
||||
stream: bool = False,
|
||||
sink: Path | None = None,
|
||||
) -> HTTPResponse:
|
||||
"""Single entry point for all HTTP traffic.
|
||||
|
||||
Behavior:
|
||||
- Retries on connection errors and on HTTP statuses in RETRY_STATUS_CODES,
|
||||
with exponential backoff + jitter.
|
||||
- For cross-host redirects, drops Authorization-style headers (so signed
|
||||
URLs don't leak the API key to S3/CloudFront).
|
||||
- When `stream=True` and `sink` is a Path, streams the response body to
|
||||
disk in 64 KiB chunks instead of buffering.
|
||||
|
||||
Either `json_body`, `data`, or `files`+`form` may be supplied (mutually exclusive).
|
||||
"""
|
||||
if headers is None:
|
||||
headers = {}
|
||||
headers = dict(headers) # copy
|
||||
headers.setdefault("User-Agent", "hermes-comfyui-skill/5.0")
|
||||
|
||||
if files or form is not None:
|
||||
# Multipart upload — needs `requests`. The stdlib fallback lacks
|
||||
# multipart encoding helpers; raise a clear error.
|
||||
if not HAS_REQUESTS:
|
||||
raise RuntimeError(
|
||||
"Multipart upload requires the `requests` package. "
|
||||
"Install with: pip install requests"
|
||||
)
|
||||
|
||||
last_exc: Exception | None = None
|
||||
for attempt in range(retries):
|
||||
try:
|
||||
resp = _http_once(
|
||||
method=method, url=url, headers=headers,
|
||||
json_body=json_body, data=data, files=files, form=form,
|
||||
timeout=timeout, follow_redirects=follow_redirects,
|
||||
stream=stream, sink=sink,
|
||||
)
|
||||
if resp.status in RETRY_STATUS_CODES and attempt + 1 < retries:
|
||||
_sleep_backoff(attempt)
|
||||
continue
|
||||
return resp
|
||||
except (TimeoutError, ConnectionError, OSError) as e:
|
||||
last_exc = e
|
||||
if attempt + 1 < retries:
|
||||
_sleep_backoff(attempt)
|
||||
continue
|
||||
raise
|
||||
|
||||
# Should not reach here unless retries was 0
|
||||
if last_exc:
|
||||
raise last_exc
|
||||
raise RuntimeError("http_request: retries exhausted with no response")
|
||||
|
||||
|
||||
_SENSITIVE_HEADERS = ("x-api-key", "authorization", "cookie")
|
||||
|
||||
|
||||
if HAS_REQUESTS:
|
||||
class _StripSensitiveOnRedirectSession(requests.Session):
|
||||
"""Session that drops sensitive headers on cross-host redirects.
|
||||
|
||||
`requests` already strips `Authorization` cross-host (rebuild_auth),
|
||||
but it does NOT strip custom headers like `X-API-Key`. We override
|
||||
`rebuild_auth` to additionally strip every header in
|
||||
`_SENSITIVE_HEADERS` when the destination is a different host —
|
||||
critical when ComfyUI Cloud's `/api/view` redirects to a signed S3 URL.
|
||||
"""
|
||||
|
||||
def rebuild_auth(self, prepared_request, response): # type: ignore[override]
|
||||
super().rebuild_auth(prepared_request, response)
|
||||
try:
|
||||
old_url = response.request.url
|
||||
new_url = prepared_request.url
|
||||
old_host = (urlparse(old_url).hostname or "").lower()
|
||||
new_host = (urlparse(new_url).hostname or "").lower()
|
||||
if old_host and new_host and old_host != new_host:
|
||||
headers = prepared_request.headers
|
||||
for key in list(headers.keys()):
|
||||
if key.lower() in _SENSITIVE_HEADERS:
|
||||
del headers[key]
|
||||
except Exception:
|
||||
# Defensive: never let header stripping break a redirect.
|
||||
pass
|
||||
|
||||
|
||||
def _http_once(
|
||||
*, method: str, url: str, headers: dict[str, str],
|
||||
json_body: Any, data: bytes | None, files: dict | None, form: dict | None,
|
||||
timeout: float, follow_redirects: bool,
|
||||
stream: bool, sink: Path | None,
|
||||
) -> HTTPResponse:
|
||||
"""One HTTP attempt. No retry."""
|
||||
if HAS_REQUESTS:
|
||||
kwargs: dict[str, Any] = {
|
||||
"method": method, "url": url, "headers": headers,
|
||||
"timeout": timeout, "allow_redirects": follow_redirects,
|
||||
}
|
||||
if json_body is not None:
|
||||
kwargs["json"] = json_body
|
||||
elif data is not None:
|
||||
kwargs["data"] = data
|
||||
elif files is not None or form is not None:
|
||||
kwargs["files"] = files
|
||||
kwargs["data"] = form
|
||||
if stream:
|
||||
kwargs["stream"] = True
|
||||
|
||||
# Use the subclass that strips sensitive headers cross-host
|
||||
with _StripSensitiveOnRedirectSession() as s:
|
||||
try:
|
||||
r = s.request(**kwargs)
|
||||
if stream and sink is not None:
|
||||
sink.parent.mkdir(parents=True, exist_ok=True)
|
||||
with sink.open("wb") as f:
|
||||
for chunk in r.iter_content(DOWNLOAD_CHUNK_SIZE):
|
||||
if chunk:
|
||||
f.write(chunk)
|
||||
body = b"" # already drained
|
||||
else:
|
||||
body = r.content
|
||||
return HTTPResponse(
|
||||
status=r.status_code,
|
||||
headers={k: v for k, v in r.headers.items()},
|
||||
body=body,
|
||||
url=r.url,
|
||||
)
|
||||
except requests.exceptions.RequestException as e:
|
||||
# Convert to TimeoutError / ConnectionError so the retry loop
|
||||
# picks them up uniformly with the stdlib path.
|
||||
if isinstance(e, requests.exceptions.Timeout):
|
||||
raise TimeoutError(str(e)) from e
|
||||
raise ConnectionError(str(e)) from e
|
||||
|
||||
# ---------- stdlib fallback ----------
|
||||
if json_body is not None:
|
||||
body_bytes = json.dumps(json_body).encode("utf-8")
|
||||
headers.setdefault("Content-Type", "application/json")
|
||||
else:
|
||||
body_bytes = data
|
||||
req = urllib.request.Request(url, data=body_bytes, headers=headers, method=method)
|
||||
|
||||
# urllib follows redirects by default. We need to:
|
||||
# 1) intercept cross-host redirects and drop X-API-Key
|
||||
# 2) optionally NOT follow redirects when follow_redirects=False
|
||||
class _RedirectHandler(urllib.request.HTTPRedirectHandler):
|
||||
def __init__(self, original_host: str, follow: bool):
|
||||
self.original_host = original_host
|
||||
self.follow = follow
|
||||
|
||||
def redirect_request(self, req2, fp, code, msg, hdrs, newurl):
|
||||
if not self.follow:
|
||||
return None
|
||||
new_host = (urlparse(newurl).hostname or "").lower()
|
||||
if new_host != self.original_host:
|
||||
# Build a new request with cleaned headers
|
||||
clean_headers = {
|
||||
k: v for k, v in req2.header_items()
|
||||
if k.lower() not in {"x-api-key", "authorization", "cookie"}
|
||||
}
|
||||
new_req = urllib.request.Request(newurl, headers=clean_headers, method="GET")
|
||||
return new_req
|
||||
return super().redirect_request(req2, fp, code, msg, hdrs, newurl)
|
||||
|
||||
original_host = (urlparse(url).hostname or "").lower()
|
||||
opener = urllib.request.build_opener(_RedirectHandler(original_host, follow_redirects))
|
||||
|
||||
try:
|
||||
resp = opener.open(req, timeout=timeout)
|
||||
except urllib.error.HTTPError as e:
|
||||
return HTTPResponse(
|
||||
status=e.code,
|
||||
headers=dict(e.headers) if e.headers else {},
|
||||
body=e.read() or b"",
|
||||
url=getattr(e, "url", url),
|
||||
)
|
||||
|
||||
final_url = resp.geturl()
|
||||
final_status = resp.status
|
||||
final_headers = dict(resp.headers)
|
||||
|
||||
if stream and sink is not None:
|
||||
sink.parent.mkdir(parents=True, exist_ok=True)
|
||||
with sink.open("wb") as f:
|
||||
while True:
|
||||
chunk = resp.read(DOWNLOAD_CHUNK_SIZE)
|
||||
if not chunk:
|
||||
break
|
||||
f.write(chunk)
|
||||
return HTTPResponse(status=final_status, headers=final_headers, body=b"", url=final_url)
|
||||
|
||||
return HTTPResponse(status=final_status, headers=final_headers, body=resp.read(), url=final_url)
|
||||
|
||||
|
||||
def http_get(url: str, **kwargs: Any) -> HTTPResponse:
|
||||
return http_request("GET", url, **kwargs)
|
||||
|
||||
|
||||
def http_post(url: str, **kwargs: Any) -> HTTPResponse:
|
||||
return http_request("POST", url, **kwargs)
|
||||
|
||||
|
||||
# =============================================================================
|
||||
# Workflow validation & helpers
|
||||
# =============================================================================
|
||||
|
||||
def is_api_format(workflow: Any) -> bool:
|
||||
"""API format = top-level dict where each value has `class_type`."""
|
||||
if not isinstance(workflow, dict):
|
||||
return False
|
||||
if "nodes" in workflow and "links" in workflow:
|
||||
return False
|
||||
for v in workflow.values():
|
||||
if isinstance(v, dict) and "class_type" in v:
|
||||
return True
|
||||
return False
|
||||
|
||||
|
||||
def unwrap_workflow(payload: Any) -> dict:
|
||||
"""Unwrap common wrapper variants. Returns API-format workflow or raises ValueError."""
|
||||
if isinstance(payload, dict) and is_api_format(payload):
|
||||
return payload
|
||||
# Some files wrap workflow under "prompt" key (e.g. saved /prompt payloads)
|
||||
if isinstance(payload, dict) and "prompt" in payload and is_api_format(payload["prompt"]):
|
||||
return payload["prompt"]
|
||||
# Editor format
|
||||
if isinstance(payload, dict) and "nodes" in payload and "links" in payload:
|
||||
raise ValueError(
|
||||
"Workflow is in editor format (has top-level 'nodes' and 'links' arrays). "
|
||||
"Re-export from ComfyUI using 'Workflow → Export (API)' (newer UI) "
|
||||
"or 'Save (API Format)' (older UI)."
|
||||
)
|
||||
raise ValueError(
|
||||
"Workflow is not in API format. Each top-level entry must have a 'class_type' field."
|
||||
)
|
||||
|
||||
|
||||
def is_link(value: Any) -> bool:
|
||||
"""True if `value` is a [node_id, output_index] connection (length-2 list)."""
|
||||
return (
|
||||
isinstance(value, list)
|
||||
and len(value) == 2
|
||||
and isinstance(value[0], str)
|
||||
and isinstance(value[1], int)
|
||||
)
|
||||
|
||||
|
||||
def iter_nodes(workflow: dict) -> Iterator[tuple[str, dict]]:
|
||||
"""Yield (node_id, node) for each valid API-format node."""
|
||||
for node_id, node in workflow.items():
|
||||
if isinstance(node, dict) and "class_type" in node:
|
||||
yield node_id, node
|
||||
|
||||
|
||||
def iter_model_deps(workflow: dict) -> Iterator[dict]:
|
||||
"""Yield {node_id, class_type, field, value, folder} for each model dependency."""
|
||||
for node_id, node in iter_nodes(workflow):
|
||||
cls = node["class_type"]
|
||||
if cls not in MODEL_LOADERS:
|
||||
continue
|
||||
inputs = node.get("inputs", {}) or {}
|
||||
for field_name, folder in MODEL_LOADERS[cls]:
|
||||
val = inputs.get(field_name)
|
||||
if val and isinstance(val, str) and not is_link(val):
|
||||
yield {
|
||||
"node_id": node_id,
|
||||
"class_type": cls,
|
||||
"field": field_name,
|
||||
"value": val,
|
||||
"folder": folder,
|
||||
}
|
||||
|
||||
|
||||
def iter_embedding_refs(workflow: dict) -> Iterator[tuple[str, str]]:
|
||||
"""Yield (node_id, embedding_name) for every embedding mention in prompts."""
|
||||
for node_id, node in iter_nodes(workflow):
|
||||
inputs = node.get("inputs", {}) or {}
|
||||
for field_name, val in inputs.items():
|
||||
if field_name not in PROMPT_FIELDS:
|
||||
continue
|
||||
if not isinstance(val, str):
|
||||
continue
|
||||
for m in EMBEDDING_REGEX.finditer(val):
|
||||
yield node_id, m.group(1)
|
||||
|
||||
|
||||
# =============================================================================
|
||||
# Path safety
|
||||
# =============================================================================
|
||||
|
||||
def safe_path_join(base: Path, *parts: str) -> Path:
|
||||
"""Join paths, raising if the result escapes `base`.
|
||||
|
||||
Server-supplied filenames may contain `../` etc. This guards against
|
||||
path-traversal attacks when downloading outputs.
|
||||
"""
|
||||
base_resolved = base.resolve()
|
||||
candidate = base.joinpath(*parts).resolve()
|
||||
try:
|
||||
candidate.relative_to(base_resolved)
|
||||
except ValueError as e:
|
||||
raise ValueError(
|
||||
f"Refusing path traversal: {candidate} is outside {base_resolved}"
|
||||
) from e
|
||||
return candidate
|
||||
|
||||
|
||||
def media_type_from_filename(filename: str) -> str:
|
||||
ext = Path(filename).suffix.lower()
|
||||
if ext in {".mp4", ".webm", ".avi", ".mov", ".mkv", ".gif", ".webp"}:
|
||||
return "video"
|
||||
if ext in {".wav", ".mp3", ".flac", ".ogg", ".m4a"}:
|
||||
return "audio"
|
||||
if ext in {".glb", ".obj", ".ply", ".gltf"}:
|
||||
return "3d"
|
||||
if ext in {".json", ".txt", ".md"}:
|
||||
return "text"
|
||||
return "image"
|
||||
|
||||
|
||||
def looks_like_video_workflow(workflow: dict) -> bool:
|
||||
"""Used to bump default timeout for video workflows."""
|
||||
for _, node in iter_nodes(workflow):
|
||||
if node["class_type"] in SLOW_OUTPUT_NODES:
|
||||
return True
|
||||
if node["class_type"].lower().startswith(("animatediff", "ade_", "wanvideo", "hunyuanvideo", "ltxvideo", "cogvideo")):
|
||||
return True
|
||||
return False
|
||||
|
||||
|
||||
# =============================================================================
|
||||
# Seed handling
|
||||
# =============================================================================
|
||||
|
||||
# ComfyUI's max seed range. Many UIs treat `-1` as "randomize on submit".
|
||||
SEED_MAX = 2**63 - 1
|
||||
SEED_MIN = 0
|
||||
|
||||
|
||||
def coerce_seed(value: Any) -> int:
|
||||
"""Convert -1 or None to a fresh random seed; otherwise return int(value).
|
||||
|
||||
Accepts numeric -1 OR string "-1" (both treated as "randomize"). Other
|
||||
parse failures raise TypeError/ValueError for the caller to surface.
|
||||
"""
|
||||
if value is None:
|
||||
return random.randint(SEED_MIN, SEED_MAX)
|
||||
# Stringly-typed -1 from CLI / JSON should also randomize
|
||||
if isinstance(value, str) and value.strip() == "-1":
|
||||
return random.randint(SEED_MIN, SEED_MAX)
|
||||
if value == -1:
|
||||
return random.randint(SEED_MIN, SEED_MAX)
|
||||
return int(value)
|
||||
|
||||
|
||||
# =============================================================================
|
||||
# Cloud model-list normalization
|
||||
# =============================================================================
|
||||
|
||||
def parse_model_list(payload: Any) -> set[str]:
|
||||
"""Normalize model-list responses from local ComfyUI vs Comfy Cloud.
|
||||
|
||||
Local: `["a.safetensors", "b.safetensors"]`
|
||||
Cloud: `[{"name": "a.safetensors", "pathIndex": 0}, ...]`
|
||||
"""
|
||||
if not isinstance(payload, list):
|
||||
return set()
|
||||
out: set[str] = set()
|
||||
for item in payload:
|
||||
if isinstance(item, str):
|
||||
out.add(item)
|
||||
elif isinstance(item, dict):
|
||||
name = item.get("name") or item.get("filename") or item.get("path")
|
||||
if isinstance(name, str):
|
||||
out.add(name)
|
||||
return out
|
||||
|
||||
|
||||
# =============================================================================
|
||||
# Misc utilities
|
||||
# =============================================================================
|
||||
|
||||
def new_client_id() -> str:
|
||||
return str(uuid.uuid4())
|
||||
|
||||
|
||||
def fmt_kv(d: dict) -> str:
|
||||
"""Pretty key=value for log lines."""
|
||||
return " ".join(f"{k}={v!r}" for k, v in d.items())
|
||||
|
||||
|
||||
def emit_json(obj: Any, *, indent: int = 2) -> None:
|
||||
"""Print JSON to stdout. Centralised so behavior can be tweaked (e.g., --raw)."""
|
||||
print(json.dumps(obj, indent=indent, default=str))
|
||||
|
||||
|
||||
def log(msg: str) -> None:
|
||||
"""stderr log with consistent prefix (so JSON stdout stays clean)."""
|
||||
print(f"[comfyui-skill] {msg}", file=sys.stderr)
|
||||
+225
@@ -0,0 +1,225 @@
|
||||
#!/usr/bin/env python3
|
||||
"""
|
||||
auto_fix_deps.py — Run check_deps.py, then attempt to install whatever is missing.
|
||||
|
||||
For local servers:
|
||||
- Missing custom nodes → `comfy node install <package>`
|
||||
- Missing models → `comfy model download` (only if a URL is supplied via
|
||||
--model-source-file or detected via well-known names)
|
||||
|
||||
For cloud: prints what would be needed but cannot install (cloud preinstalls
|
||||
custom nodes and most models server-side; if something genuinely isn't there,
|
||||
ask Comfy support).
|
||||
|
||||
This is conservative: it never installs without an explicit URL for models
|
||||
(downloading the wrong model is hard to undo). Custom nodes from the registry
|
||||
are auto-installed by name.
|
||||
|
||||
Usage:
|
||||
python3 auto_fix_deps.py workflow_api.json
|
||||
python3 auto_fix_deps.py workflow_api.json --models-from-file urls.json
|
||||
python3 auto_fix_deps.py workflow_api.json --dry-run
|
||||
"""
|
||||
|
||||
from __future__ import annotations
|
||||
|
||||
import argparse
|
||||
import json
|
||||
import shutil
|
||||
import subprocess
|
||||
import sys
|
||||
from pathlib import Path
|
||||
|
||||
sys.path.insert(0, str(Path(__file__).resolve().parent))
|
||||
from _common import ( # noqa: E402
|
||||
DEFAULT_LOCAL_HOST, ENV_API_KEY, emit_json, log, resolve_api_key,
|
||||
)
|
||||
from check_deps import check_deps # noqa: E402
|
||||
from _common import unwrap_workflow # noqa: E402
|
||||
|
||||
|
||||
def comfy_cli_available() -> str | None:
|
||||
"""Return command prefix for comfy-cli, or None."""
|
||||
if shutil.which("comfy"):
|
||||
return "comfy"
|
||||
if shutil.which("uvx"):
|
||||
return "uvx --from comfy-cli comfy"
|
||||
return None
|
||||
|
||||
|
||||
def run_cmd(cmd: list[str], *, dry_run: bool = False) -> tuple[int, str]:
|
||||
if dry_run:
|
||||
return 0, "[dry-run]"
|
||||
log(f"$ {' '.join(cmd)}")
|
||||
proc = subprocess.run(cmd, capture_output=True, text=True, encoding='utf-8', errors='replace', check=False)
|
||||
out = (proc.stdout or "") + (proc.stderr or "")
|
||||
return proc.returncode, out
|
||||
|
||||
|
||||
def install_node(package: str, *, dry_run: bool = False, comfy_cmd: str = "comfy") -> bool:
|
||||
cmd = comfy_cmd.split() + ["--skip-prompt", "node", "install", package]
|
||||
code, _ = run_cmd(cmd, dry_run=dry_run)
|
||||
return code == 0
|
||||
|
||||
|
||||
def install_model(url: str, folder: str, filename: str | None = None,
|
||||
*, dry_run: bool = False, comfy_cmd: str = "comfy",
|
||||
hf_token: str | None = None, civitai_token: str | None = None) -> bool:
|
||||
cmd = comfy_cmd.split() + [
|
||||
"--skip-prompt", "model", "download",
|
||||
"--url", url,
|
||||
"--relative-path", f"models/{folder}",
|
||||
]
|
||||
if filename:
|
||||
cmd.extend(["--filename", filename])
|
||||
if hf_token:
|
||||
cmd.extend(["--set-hf-api-token", hf_token])
|
||||
if civitai_token:
|
||||
cmd.extend(["--set-civitai-api-token", civitai_token])
|
||||
code, _ = run_cmd(cmd, dry_run=dry_run)
|
||||
return code == 0
|
||||
|
||||
|
||||
def main(argv: list[str] | None = None) -> int:
|
||||
p = argparse.ArgumentParser(description="Run check_deps and install whatever is missing")
|
||||
p.add_argument("workflow")
|
||||
p.add_argument("--host", default=DEFAULT_LOCAL_HOST)
|
||||
p.add_argument("--api-key", help=f"or set ${ENV_API_KEY}")
|
||||
p.add_argument("--models-from-file",
|
||||
help="JSON file mapping {model_filename: download_url} for models that need install")
|
||||
p.add_argument("--hf-token", help="HuggingFace token for downloads")
|
||||
p.add_argument("--civitai-token", help="CivitAI token for downloads")
|
||||
p.add_argument("--dry-run", action="store_true",
|
||||
help="Show what would be installed without doing it")
|
||||
p.add_argument("--no-restart", action="store_true",
|
||||
help="Don't suggest restarting the server after node install")
|
||||
args = p.parse_args(argv)
|
||||
|
||||
api_key = resolve_api_key(args.api_key)
|
||||
|
||||
wf_path = Path(args.workflow).expanduser()
|
||||
if not wf_path.exists():
|
||||
emit_json({"error": f"Workflow not found: {args.workflow}"})
|
||||
return 1
|
||||
try:
|
||||
with wf_path.open(encoding="utf-8-sig") as f:
|
||||
workflow = unwrap_workflow(json.load(f))
|
||||
except (ValueError, json.JSONDecodeError) as e:
|
||||
emit_json({"error": str(e)})
|
||||
return 1
|
||||
|
||||
report = check_deps(workflow, host=args.host, api_key=api_key)
|
||||
|
||||
if report["is_ready"]:
|
||||
emit_json({"status": "ready", "report": report})
|
||||
return 0
|
||||
|
||||
if report["is_cloud"]:
|
||||
emit_json({
|
||||
"status": "cannot_fix_cloud",
|
||||
"reason": "Comfy Cloud preinstalls nodes; if something is genuinely missing, contact support.",
|
||||
"report": report,
|
||||
})
|
||||
return 1
|
||||
|
||||
comfy_cmd = comfy_cli_available()
|
||||
if not comfy_cmd:
|
||||
emit_json({
|
||||
"status": "cannot_fix",
|
||||
"reason": "comfy-cli not on PATH; install with `pip install comfy-cli` or `pipx install comfy-cli`",
|
||||
"report": report,
|
||||
})
|
||||
return 1
|
||||
|
||||
actions: list[dict] = []
|
||||
failures: list[dict] = []
|
||||
|
||||
# ---- Install missing custom nodes ----
|
||||
seen_packages: set[str] = set()
|
||||
for entry in report["missing_nodes"]:
|
||||
cmd = entry.get("fix_command", "")
|
||||
if cmd.startswith("comfy node install "):
|
||||
package = cmd.split(" ")[-1]
|
||||
if package in seen_packages:
|
||||
continue
|
||||
seen_packages.add(package)
|
||||
ok = install_node(package, dry_run=args.dry_run, comfy_cmd=comfy_cmd)
|
||||
(actions if ok else failures).append({
|
||||
"kind": "node", "package": package, "node_class": entry["class_type"],
|
||||
"ok": ok,
|
||||
})
|
||||
else:
|
||||
failures.append({
|
||||
"kind": "node", "node_class": entry["class_type"],
|
||||
"ok": False, "reason": "No registry mapping known. " + entry.get("fix_hint", ""),
|
||||
})
|
||||
|
||||
# ---- Install missing models (only when URL provided) ----
|
||||
sources: dict[str, str] = {}
|
||||
if args.models_from_file:
|
||||
try:
|
||||
sources = json.loads(Path(args.models_from_file).read_text(encoding="utf-8"))
|
||||
except (OSError, json.JSONDecodeError) as e:
|
||||
log(f"Could not read --models-from-file: {e}")
|
||||
|
||||
for entry in report["missing_models"]:
|
||||
filename = entry["value"]
|
||||
url = sources.get(filename)
|
||||
if not url:
|
||||
failures.append({
|
||||
"kind": "model", "filename": filename, "folder": entry["folder"],
|
||||
"ok": False, "reason": "No URL provided in --models-from-file. "
|
||||
"Refusing to guess.",
|
||||
})
|
||||
continue
|
||||
ok = install_model(
|
||||
url, entry["folder"], filename,
|
||||
dry_run=args.dry_run, comfy_cmd=comfy_cmd,
|
||||
hf_token=args.hf_token, civitai_token=args.civitai_token,
|
||||
)
|
||||
(actions if ok else failures).append({
|
||||
"kind": "model", "filename": filename, "folder": entry["folder"],
|
||||
"url": url, "ok": ok,
|
||||
})
|
||||
|
||||
# ---- Embeddings ----
|
||||
for entry in report["missing_embeddings"]:
|
||||
emb_name = entry["embedding_name"]
|
||||
# Try common extensions in user-supplied source map
|
||||
url = (sources.get(f"{emb_name}.pt")
|
||||
or sources.get(f"{emb_name}.safetensors")
|
||||
or sources.get(emb_name))
|
||||
if not url:
|
||||
failures.append({
|
||||
"kind": "embedding", "name": emb_name,
|
||||
"ok": False, "reason": "No URL provided in --models-from-file.",
|
||||
})
|
||||
continue
|
||||
target_filename = (
|
||||
f"{emb_name}.safetensors" if url.endswith(".safetensors")
|
||||
else f"{emb_name}.pt"
|
||||
)
|
||||
ok = install_model(
|
||||
url, "embeddings", target_filename,
|
||||
dry_run=args.dry_run, comfy_cmd=comfy_cmd,
|
||||
hf_token=args.hf_token, civitai_token=args.civitai_token,
|
||||
)
|
||||
(actions if ok else failures).append({
|
||||
"kind": "embedding", "name": emb_name, "url": url, "ok": ok,
|
||||
})
|
||||
|
||||
needs_restart = any(a["kind"] == "node" and a.get("ok") for a in actions)
|
||||
|
||||
emit_json({
|
||||
"status": "fixed" if not failures else "partial",
|
||||
"actions_taken": actions,
|
||||
"failures": failures,
|
||||
"needs_server_restart": needs_restart and not args.no_restart,
|
||||
"restart_hint": "comfy stop && comfy launch --background",
|
||||
"dry_run": args.dry_run,
|
||||
})
|
||||
return 0 if not failures else 1
|
||||
|
||||
|
||||
if __name__ == "__main__":
|
||||
sys.exit(main())
|
||||
+437
@@ -0,0 +1,437 @@
|
||||
#!/usr/bin/env python3
|
||||
"""
|
||||
check_deps.py — Verify a ComfyUI workflow's dependencies (custom nodes, models,
|
||||
embeddings) against a running server.
|
||||
|
||||
Improvements over v1:
|
||||
- Cloud-aware endpoint mapping (handles `/api/experiment/models/{folder}` and
|
||||
`/api/object_info` variants verified against live cloud API)
|
||||
- Distinguishes 200-empty (genuinely no models in folder) vs 404
|
||||
(folder doesn't exist) vs 403 (auth/tier issue) — no silent passes
|
||||
- Outputs concrete remediation commands (e.g. `comfy node install <name>`)
|
||||
when nodes are missing
|
||||
- Detects embedding references inside prompt strings as model deps
|
||||
- Skips check on cloud free tier `/api/object_info` (403) without false alarm
|
||||
- Accepts API key from CLI flag OR $COMFY_CLOUD_API_KEY env var
|
||||
|
||||
Usage:
|
||||
python3 check_deps.py workflow_api.json
|
||||
python3 check_deps.py workflow_api.json --host 127.0.0.1 --port 8188
|
||||
python3 check_deps.py workflow_api.json --host https://cloud.comfy.org
|
||||
|
||||
Stdlib-only. Python 3.10+.
|
||||
"""
|
||||
|
||||
from __future__ import annotations
|
||||
|
||||
import argparse
|
||||
import json
|
||||
import sys
|
||||
from pathlib import Path
|
||||
|
||||
sys.path.insert(0, str(Path(__file__).resolve().parent))
|
||||
from _common import ( # noqa: E402
|
||||
DEFAULT_LOCAL_HOST, ENV_API_KEY,
|
||||
emit_json, folder_aliases_for, http_get, is_cloud_host,
|
||||
iter_embedding_refs, iter_model_deps, iter_nodes, parse_model_list,
|
||||
resolve_api_key, resolve_url, unwrap_workflow,
|
||||
)
|
||||
|
||||
|
||||
# Known node → custom-node-package map. When a workflow needs a node we don't
|
||||
# recognize, suggesting the right `comfy node install ...` makes the difference
|
||||
# between a working agent and a stuck one.
|
||||
NODE_TO_PACKAGE: dict[str, str] = {
|
||||
# rgthree (Reroute is JS-only and doesn't appear in /object_info)
|
||||
"Power Lora Loader (rgthree)": "rgthree-comfy",
|
||||
"Image Comparer (rgthree)": "rgthree-comfy",
|
||||
"Seed (rgthree)": "rgthree-comfy",
|
||||
"Display Any (rgthree)": "rgthree-comfy",
|
||||
"Display Int (rgthree)": "rgthree-comfy",
|
||||
# Impact pack
|
||||
"FaceDetailer": "comfyui-impact-pack",
|
||||
"DetailerForEach": "comfyui-impact-pack",
|
||||
"BboxDetectorSEGS": "comfyui-impact-pack",
|
||||
"SAMLoader": "comfyui-impact-pack",
|
||||
"ImpactWildcardProcessor": "comfyui-impact-pack",
|
||||
# Impact subpack (separate package)
|
||||
"UltralyticsDetectorProvider": "comfyui-impact-subpack",
|
||||
# Was Node Suite
|
||||
"Image Save": "was-node-suite-comfyui",
|
||||
"Number Counter": "was-node-suite-comfyui",
|
||||
"Text String": "was-node-suite-comfyui",
|
||||
# easy-use
|
||||
"easy fullLoader": "comfyui-easy-use",
|
||||
"easy positive": "comfyui-easy-use",
|
||||
"easy negative": "comfyui-easy-use",
|
||||
"easy seed": "comfyui-easy-use",
|
||||
"easy imageSave": "comfyui-easy-use",
|
||||
# Video Helper Suite
|
||||
"VHS_VideoCombine": "comfyui-videohelpersuite",
|
||||
"VHS_LoadVideo": "comfyui-videohelpersuite",
|
||||
"VHS_LoadAudio": "comfyui-videohelpersuite",
|
||||
# AnimateDiff
|
||||
"ADE_AnimateDiffLoaderWithContext": "comfyui-animatediff-evolved",
|
||||
"ADE_AnimateDiffLoaderGen1": "comfyui-animatediff-evolved",
|
||||
"ADE_LoadAnimateDiffModel": "comfyui-animatediff-evolved",
|
||||
# ControlNet aux preprocessors (full class names)
|
||||
"CannyEdgePreprocessor": "comfyui_controlnet_aux",
|
||||
"DWPreprocessor": "comfyui_controlnet_aux",
|
||||
"OpenposePreprocessor": "comfyui_controlnet_aux",
|
||||
"DepthAnythingPreprocessor": "comfyui_controlnet_aux",
|
||||
"Zoe_DepthAnythingPreprocessor": "comfyui_controlnet_aux",
|
||||
"AnimalPosePreprocessor": "comfyui_controlnet_aux",
|
||||
# IPAdapter Plus
|
||||
"IPAdapterAdvanced": "comfyui_ipadapter_plus",
|
||||
"IPAdapterUnifiedLoader": "comfyui_ipadapter_plus",
|
||||
"IPAdapterModelLoader": "comfyui_ipadapter_plus",
|
||||
"IPAdapterInsightFaceLoader": "comfyui_ipadapter_plus",
|
||||
# InstantID
|
||||
"InstantIDModelLoader": "comfyui_instantid",
|
||||
"ApplyInstantID": "comfyui_instantid",
|
||||
# Comfy essentials (note: registry slug uses underscore, not hyphen)
|
||||
"GetImageSize+": "comfyui_essentials",
|
||||
"ImageBatchMultiple+": "comfyui_essentials",
|
||||
# pysssss
|
||||
"ShowText|pysssss": "comfyui-custom-scripts",
|
||||
"PreviewImage|pysssss": "comfyui-custom-scripts",
|
||||
# SUPIR
|
||||
"SUPIR_Upscale": "comfyui-supir",
|
||||
"SUPIR_first_stage": "comfyui-supir",
|
||||
# GGUF (case-sensitive registry slug)
|
||||
"UNETLoaderGGUF": "ComfyUI-GGUF",
|
||||
"DualCLIPLoaderGGUF": "ComfyUI-GGUF",
|
||||
# Florence2
|
||||
"Florence2Run": "comfyui-florence2",
|
||||
# WAS
|
||||
"Image Filter Adjustments": "was-node-suite-comfyui",
|
||||
# Photomaker (case-sensitive)
|
||||
"PhotoMakerLoader": "ComfyUI-PhotoMaker-Plus",
|
||||
# Wan video (case-sensitive)
|
||||
"WanVideoSampler": "ComfyUI-WanVideoWrapper",
|
||||
"WanVideoModelLoader": "ComfyUI-WanVideoWrapper",
|
||||
}
|
||||
|
||||
# Nodes whose package isn't on the comfy registry — need git-URL install via
|
||||
# ComfyUI-Manager. We surface a helpful hint instead of an unrunnable command.
|
||||
NODE_TO_GIT_URL: dict[str, str] = {
|
||||
"HunyuanVideoSampler": "https://github.com/kijai/ComfyUI-HunyuanVideoWrapper",
|
||||
"HunyuanVideoModelLoader": "https://github.com/kijai/ComfyUI-HunyuanVideoWrapper",
|
||||
}
|
||||
|
||||
|
||||
def fetch_object_info(url: str, headers: dict) -> tuple[set[str] | None, dict | None]:
|
||||
"""Returns (installed_node_set, error_info). Error info is a dict if we
|
||||
couldn't query (e.g. cloud free tier), else None.
|
||||
"""
|
||||
r = http_get(url, headers=headers, retries=2, timeout=30)
|
||||
if r.status == 200:
|
||||
try:
|
||||
data = r.json()
|
||||
if isinstance(data, dict):
|
||||
return set(data.keys()), None
|
||||
except Exception:
|
||||
pass
|
||||
return None, {"http_status": 200, "reason": "non-dict response"}
|
||||
if r.status == 403:
|
||||
try:
|
||||
body = r.json()
|
||||
except Exception:
|
||||
body = {"raw": r.text()[:200]}
|
||||
return None, {"http_status": 403, "reason": "forbidden", "body": body}
|
||||
if r.status == 404:
|
||||
return None, {"http_status": 404, "reason": "endpoint not found"}
|
||||
return None, {"http_status": r.status, "reason": "unexpected", "body": r.text()[:200]}
|
||||
|
||||
|
||||
def _fetch_one_folder(
|
||||
base: str, folder: str, headers: dict, *, is_cloud: bool,
|
||||
) -> tuple[set[str] | None, dict | None]:
|
||||
"""Single-folder fetch, no aliasing. Returns (installed_set, error_info)."""
|
||||
url = resolve_url(base, f"/models/{folder}", is_cloud=is_cloud)
|
||||
r = http_get(url, headers=headers, retries=2, timeout=30)
|
||||
if r.status == 200:
|
||||
try:
|
||||
return parse_model_list(r.json()), None
|
||||
except Exception:
|
||||
return set(), {"http_status": 200, "reason": "non-list response"}
|
||||
if r.status == 404:
|
||||
body_text = r.text()
|
||||
try:
|
||||
body = r.json()
|
||||
except Exception:
|
||||
body = {"raw": body_text[:200]}
|
||||
code = body.get("code") if isinstance(body, dict) else None
|
||||
if code == "folder_not_found":
|
||||
# Folder is genuinely empty/missing on server — not the same as
|
||||
# "endpoint missing". Return empty set with informational error.
|
||||
return set(), {"http_status": 404, "reason": "folder_empty_or_unknown", "body": body}
|
||||
return None, {"http_status": 404, "reason": "endpoint not found", "body": body}
|
||||
if r.status == 403:
|
||||
try:
|
||||
body = r.json()
|
||||
except Exception:
|
||||
body = {}
|
||||
return None, {"http_status": 403, "reason": "forbidden", "body": body}
|
||||
return None, {"http_status": r.status, "reason": "unexpected"}
|
||||
|
||||
|
||||
def fetch_models_for_folder(
|
||||
base: str, folder: str, headers: dict, *, is_cloud: bool,
|
||||
) -> tuple[set[str] | None, dict | None]:
|
||||
"""Fetch installed models for a folder, trying aliases.
|
||||
|
||||
Folder renames over time (e.g. unet → diffusion_models, clip → text_encoders)
|
||||
mean a workflow asking for a model in `unet` may need to look in
|
||||
`diffusion_models`. We union models from every reachable alias.
|
||||
|
||||
Returns (combined_set | None, last_error | None).
|
||||
"""
|
||||
aliases = folder_aliases_for(folder)
|
||||
combined: set[str] = set()
|
||||
any_success = False
|
||||
last_err: dict | None = None
|
||||
for alias in aliases:
|
||||
models, err = _fetch_one_folder(base, alias, headers, is_cloud=is_cloud)
|
||||
if models is not None:
|
||||
combined.update(models)
|
||||
any_success = True
|
||||
last_err = None
|
||||
else:
|
||||
last_err = err
|
||||
if not any_success:
|
||||
return None, last_err
|
||||
return combined, None
|
||||
|
||||
|
||||
def fetch_embeddings(base: str, headers: dict, *, is_cloud: bool) -> tuple[set[str] | None, dict | None]:
|
||||
"""Local ComfyUI exposes /embeddings; cloud uses /experiment/models/embeddings."""
|
||||
if is_cloud:
|
||||
return fetch_models_for_folder(base, "embeddings", headers, is_cloud=True)
|
||||
# Local: dedicated /embeddings returns a flat list of names
|
||||
r = http_get(resolve_url(base, "/embeddings", is_cloud=False), headers=headers, retries=2)
|
||||
if r.status == 200:
|
||||
try:
|
||||
data = r.json()
|
||||
if isinstance(data, list):
|
||||
# Strip extensions from the registered names since prompt syntax
|
||||
# usually omits them ("embedding:goodvibes" vs "goodvibes.pt")
|
||||
names = set()
|
||||
for n in data:
|
||||
if isinstance(n, str):
|
||||
names.add(n)
|
||||
# Also store stem for fuzzy matching
|
||||
names.add(Path(n).stem)
|
||||
return names, None
|
||||
except Exception:
|
||||
pass
|
||||
return None, {"http_status": r.status, "reason": "unexpected"}
|
||||
|
||||
|
||||
def normalize_for_match(name: str) -> set[str]:
|
||||
"""Generate matching variants of a model name (with/without extension, slashes, etc.)"""
|
||||
s = {name}
|
||||
s.add(Path(name).stem)
|
||||
s.add(Path(name).name)
|
||||
# ComfyUI sometimes strips/keeps the leading folder
|
||||
if "/" in name or "\\" in name:
|
||||
flat = name.replace("\\", "/").split("/")[-1]
|
||||
s.add(flat)
|
||||
s.add(Path(flat).stem)
|
||||
return {x for x in s if x}
|
||||
|
||||
|
||||
def model_present(needed: str, installed: set[str]) -> bool:
|
||||
if not installed:
|
||||
return False
|
||||
needed_variants = normalize_for_match(needed)
|
||||
installed_norm: set[str] = set()
|
||||
for inst in installed:
|
||||
installed_norm.update(normalize_for_match(inst))
|
||||
return bool(needed_variants & installed_norm)
|
||||
|
||||
|
||||
def suggest_install_command(node_class: str) -> str | None:
|
||||
pkg = NODE_TO_PACKAGE.get(node_class)
|
||||
if pkg:
|
||||
return f"comfy node install {pkg}"
|
||||
return None
|
||||
|
||||
|
||||
def suggest_git_url(node_class: str) -> str | None:
|
||||
"""For nodes not on the registry, return a git URL the user can hand to
|
||||
ComfyUI-Manager's `/manager/queue/install` endpoint."""
|
||||
return NODE_TO_GIT_URL.get(node_class)
|
||||
|
||||
|
||||
def check_deps(
|
||||
workflow: dict, host: str, *, api_key: str | None = None,
|
||||
) -> dict:
|
||||
headers: dict[str, str] = {}
|
||||
if api_key:
|
||||
headers["X-API-Key"] = api_key
|
||||
|
||||
is_cloud = is_cloud_host(host)
|
||||
base = host.rstrip("/")
|
||||
|
||||
# ---- 1. Required nodes ----
|
||||
required_nodes: set[str] = set()
|
||||
for _, node in iter_nodes(workflow):
|
||||
required_nodes.add(node["class_type"])
|
||||
|
||||
object_info_url = resolve_url(base, "/object_info", is_cloud=is_cloud)
|
||||
installed_nodes, obj_err = fetch_object_info(object_info_url, headers)
|
||||
|
||||
missing_nodes: list[dict] = []
|
||||
node_check_skipped = False
|
||||
if installed_nodes is None:
|
||||
# Couldn't query (e.g. cloud free tier). Don't false-alarm; mark skipped.
|
||||
node_check_skipped = True
|
||||
else:
|
||||
for cls in sorted(required_nodes):
|
||||
if cls not in installed_nodes:
|
||||
entry = {"class_type": cls}
|
||||
cmd = suggest_install_command(cls)
|
||||
git_url = suggest_git_url(cls)
|
||||
if cmd:
|
||||
entry["fix_command"] = cmd
|
||||
elif git_url:
|
||||
entry["fix_git_url"] = git_url
|
||||
entry["fix_hint"] = (
|
||||
f"Not on registry. Install via Manager with this git URL: {git_url}"
|
||||
)
|
||||
else:
|
||||
entry["fix_hint"] = (
|
||||
"Search https://registry.comfy.org or "
|
||||
"use ComfyUI-Manager UI to find the package providing this node."
|
||||
)
|
||||
missing_nodes.append(entry)
|
||||
|
||||
# ---- 2. Required models ----
|
||||
model_cache: dict[str, tuple[set[str] | None, dict | None]] = {}
|
||||
missing_models: list[dict] = []
|
||||
folder_errors: dict[str, dict] = {}
|
||||
|
||||
for dep in iter_model_deps(workflow):
|
||||
folder = dep["folder"]
|
||||
if folder not in model_cache:
|
||||
model_cache[folder] = fetch_models_for_folder(
|
||||
base, folder, headers, is_cloud=is_cloud,
|
||||
)
|
||||
installed, err = model_cache[folder]
|
||||
if installed is None:
|
||||
# Couldn't enumerate this folder — record once
|
||||
folder_errors.setdefault(folder, err or {})
|
||||
# Don't flag as missing (we don't know); the folder_errors block surfaces this
|
||||
continue
|
||||
if not model_present(dep["value"], installed):
|
||||
entry = dict(dep)
|
||||
entry["fix_hint"] = (
|
||||
f"comfy model download --url <URL> --relative-path models/{folder} "
|
||||
f"--filename {dep['value']!r}"
|
||||
)
|
||||
missing_models.append(entry)
|
||||
|
||||
# ---- 3. Embedding refs in prompts ----
|
||||
emb_installed, emb_err = fetch_embeddings(base, headers, is_cloud=is_cloud)
|
||||
missing_embeddings: list[dict] = []
|
||||
seen_emb: set[tuple[str, str]] = set()
|
||||
for nid, emb_name in iter_embedding_refs(workflow):
|
||||
if (nid, emb_name) in seen_emb:
|
||||
continue
|
||||
seen_emb.add((nid, emb_name))
|
||||
if emb_installed is None:
|
||||
# Couldn't enumerate — skip silently here, surface the error in the
|
||||
# folder_errors block
|
||||
continue
|
||||
if not model_present(emb_name, emb_installed):
|
||||
missing_embeddings.append({
|
||||
"node_id": nid,
|
||||
"embedding_name": emb_name,
|
||||
"folder": "embeddings",
|
||||
"fix_hint": (
|
||||
f"Download {emb_name}.pt or .safetensors and place in "
|
||||
f"models/embeddings/, or `comfy model download --url <URL> "
|
||||
f"--relative-path models/embeddings`"
|
||||
),
|
||||
})
|
||||
|
||||
if emb_err and emb_installed is None:
|
||||
folder_errors.setdefault("embeddings", emb_err)
|
||||
|
||||
is_ready = (
|
||||
not node_check_skipped
|
||||
and not missing_nodes
|
||||
and not missing_models
|
||||
and not missing_embeddings
|
||||
)
|
||||
|
||||
return {
|
||||
"is_ready": is_ready,
|
||||
"node_check_skipped": node_check_skipped,
|
||||
"node_check_skip_reason": obj_err if node_check_skipped else None,
|
||||
"missing_nodes": missing_nodes,
|
||||
"missing_models": missing_models,
|
||||
"missing_embeddings": missing_embeddings,
|
||||
"folder_errors": folder_errors,
|
||||
# 0 is a legitimate count (e.g. empty server). Use None only when not queried.
|
||||
"installed_node_count": len(installed_nodes) if installed_nodes is not None else None,
|
||||
"required_node_count": len(required_nodes),
|
||||
"required_nodes": sorted(required_nodes),
|
||||
"host": base,
|
||||
"is_cloud": is_cloud,
|
||||
}
|
||||
|
||||
|
||||
def main(argv: list[str] | None = None) -> int:
|
||||
p = argparse.ArgumentParser(description="Check ComfyUI workflow dependencies against a running server")
|
||||
p.add_argument("workflow", help="Path to workflow API JSON file")
|
||||
p.add_argument("--host", default=DEFAULT_LOCAL_HOST, help="ComfyUI server URL")
|
||||
p.add_argument("--port", type=int, help="Server port (overrides --host port)")
|
||||
p.add_argument("--api-key", help=f"API key for cloud (or set ${ENV_API_KEY} env var)")
|
||||
p.add_argument("--strict", action="store_true",
|
||||
help="Exit non-zero if node check is skipped (e.g. on cloud free tier)")
|
||||
args = p.parse_args(argv)
|
||||
|
||||
host = args.host
|
||||
if args.port is not None:
|
||||
# Strip any port from host and append --port
|
||||
from urllib.parse import urlparse, urlunparse
|
||||
parsed = urlparse(host if "://" in host else f"http://{host}")
|
||||
new_netloc = f"{parsed.hostname}:{args.port}"
|
||||
host = urlunparse(parsed._replace(netloc=new_netloc))
|
||||
|
||||
api_key = resolve_api_key(args.api_key)
|
||||
|
||||
wf_path = Path(args.workflow).expanduser()
|
||||
if not wf_path.exists():
|
||||
emit_json({"error": f"Workflow file not found: {args.workflow}"})
|
||||
return 1
|
||||
try:
|
||||
with wf_path.open(encoding="utf-8-sig") as f:
|
||||
payload = json.load(f)
|
||||
workflow = unwrap_workflow(payload)
|
||||
except ValueError as e:
|
||||
emit_json({"error": str(e)})
|
||||
return 1
|
||||
except json.JSONDecodeError as e:
|
||||
emit_json({"error": f"Invalid JSON: {e}"})
|
||||
return 1
|
||||
|
||||
try:
|
||||
result = check_deps(workflow, host=host, api_key=api_key)
|
||||
except Exception as e:
|
||||
emit_json({"error": f"Dep check failed: {e}", "host": host})
|
||||
return 1
|
||||
|
||||
emit_json(result)
|
||||
|
||||
if not result["is_ready"]:
|
||||
return 1
|
||||
if args.strict and result["node_check_skipped"]:
|
||||
return 1
|
||||
return 0
|
||||
|
||||
|
||||
if __name__ == "__main__":
|
||||
sys.exit(main())
|
||||
+286
@@ -0,0 +1,286 @@
|
||||
#!/usr/bin/env bash
|
||||
# ComfyUI Setup — Install, launch, and verify using the official comfy-cli.
|
||||
#
|
||||
# Improvements over v1:
|
||||
# - Prefers `pipx` / `uvx` over global `pip install` (avoids polluting system Python)
|
||||
# - Idempotent: detects already-running server and skips re-launch
|
||||
# - Configurable port via --port=N (default 8188)
|
||||
# - Configurable workspace via --workspace=PATH
|
||||
# - Persistent log file in /tmp/comfyui_setup.<pid>.log for debugging
|
||||
# - SIGINT trap cleans up partial state
|
||||
# - Refuses local install when hardware_check.py verdict is "cloud"
|
||||
# - Forwards extra flags to comfy-cli (e.g. --cuda-version=12.4)
|
||||
#
|
||||
# Usage:
|
||||
# bash scripts/comfyui_setup.sh
|
||||
# (auto-detects GPU; uses recommendation from hardware_check.py)
|
||||
# bash scripts/comfyui_setup.sh --nvidia
|
||||
# bash scripts/comfyui_setup.sh --m-series --port=8190
|
||||
# bash scripts/comfyui_setup.sh --amd --workspace=/data/comfy
|
||||
#
|
||||
# Flags:
|
||||
# --nvidia | --amd | --m-series | --cpu GPU selection (skips hw check)
|
||||
# --port=N HTTP port (default 8188)
|
||||
# --workspace=PATH ComfyUI install location
|
||||
# --skip-launch Install only, don't start server
|
||||
# --force-cloud-override Install locally even if hw says cloud
|
||||
# -- Pass remaining args to `comfy install`
|
||||
|
||||
set -euo pipefail
|
||||
|
||||
SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
|
||||
HARDWARE_CHECK="$SCRIPT_DIR/hardware_check.py"
|
||||
LOG_FILE="/tmp/comfyui_setup.$$.log"
|
||||
PORT=8188
|
||||
WORKSPACE=""
|
||||
GPU_FLAG=""
|
||||
SKIP_LAUNCH=0
|
||||
FORCE_CLOUD_OVERRIDE=0
|
||||
EXTRA_INSTALL_ARGS=()
|
||||
|
||||
cleanup() {
|
||||
local exit_code=$?
|
||||
if [ $exit_code -ne 0 ]; then
|
||||
echo "==> Setup exited with status $exit_code. Log: $LOG_FILE" >&2
|
||||
fi
|
||||
exit $exit_code
|
||||
}
|
||||
trap cleanup EXIT INT TERM
|
||||
|
||||
log() { echo "==> $*" | tee -a "$LOG_FILE" >&2; }
|
||||
err() { echo "ERROR: $*" | tee -a "$LOG_FILE" >&2; }
|
||||
|
||||
# --- Argument parsing ---
|
||||
PASSTHROUGH=0
|
||||
for arg in "$@"; do
|
||||
if [ "$PASSTHROUGH" -eq 1 ]; then
|
||||
EXTRA_INSTALL_ARGS+=("$arg")
|
||||
continue
|
||||
fi
|
||||
case "$arg" in
|
||||
--nvidia|--amd|--m-series|--cpu)
|
||||
GPU_FLAG="$arg"
|
||||
;;
|
||||
--port=*)
|
||||
PORT="${arg#*=}"
|
||||
;;
|
||||
--workspace=*)
|
||||
WORKSPACE="${arg#*=}"
|
||||
;;
|
||||
--skip-launch)
|
||||
SKIP_LAUNCH=1
|
||||
;;
|
||||
--force-cloud-override)
|
||||
FORCE_CLOUD_OVERRIDE=1
|
||||
;;
|
||||
--)
|
||||
PASSTHROUGH=1
|
||||
;;
|
||||
--help|-h)
|
||||
# Print the leading comment block, stripping the `# ` prefix.
|
||||
# Stops at the first blank line which separates docs from code.
|
||||
awk '
|
||||
NR == 1 { next } # skip shebang
|
||||
/^[^#]/ { exit } # stop at first non-comment line
|
||||
/^$/ { exit } # ...or first blank line
|
||||
{ sub(/^# ?/, ""); print }
|
||||
' "$0"
|
||||
exit 0
|
||||
;;
|
||||
*)
|
||||
err "Unknown argument: $arg"
|
||||
exit 64
|
||||
;;
|
||||
esac
|
||||
done
|
||||
|
||||
log "Logging to $LOG_FILE"
|
||||
|
||||
# --- Step 0: Hardware check (skipped if user gave an explicit GPU flag) ---
|
||||
if [ -z "$GPU_FLAG" ]; then
|
||||
if [ ! -f "$HARDWARE_CHECK" ]; then
|
||||
log "hardware_check.py not found — defaulting to --nvidia"
|
||||
GPU_FLAG="--nvidia"
|
||||
else
|
||||
log "Running hardware check…"
|
||||
set +e
|
||||
HW_JSON="$(python3 "$HARDWARE_CHECK" --json 2>>"$LOG_FILE")"
|
||||
HW_EXIT=$?
|
||||
set -e
|
||||
|
||||
if [ -z "$HW_JSON" ]; then
|
||||
err "hardware_check.py produced no output (exit $HW_EXIT). Pass an explicit flag."
|
||||
exit 1
|
||||
fi
|
||||
echo "$HW_JSON" | tee -a "$LOG_FILE" >&2
|
||||
|
||||
VERDICT="$(echo "$HW_JSON" | python3 -c 'import sys,json; print(json.load(sys.stdin).get("verdict",""))')"
|
||||
FLAG="$(echo "$HW_JSON" | python3 -c 'import sys,json; print(json.load(sys.stdin).get("comfy_cli_flag") or "")')"
|
||||
|
||||
if [ "$VERDICT" = "cloud" ] && [ "$FORCE_CLOUD_OVERRIDE" -ne 1 ]; then
|
||||
log ""
|
||||
log "Hardware check: this machine is not suitable for local ComfyUI."
|
||||
log "Recommended: Comfy Cloud — https://platform.comfy.org"
|
||||
log ""
|
||||
log "To override and force a local install, re-run with --force-cloud-override"
|
||||
log "or pass an explicit GPU flag (--nvidia|--amd|--m-series|--cpu)."
|
||||
exit 2
|
||||
fi
|
||||
|
||||
if [ "$VERDICT" = "marginal" ]; then
|
||||
log "Hardware check: verdict is MARGINAL."
|
||||
log " SD1.5 should work; SDXL/Flux may be slow or OOM."
|
||||
log " Consider Comfy Cloud for heavier workflows: https://platform.comfy.org"
|
||||
fi
|
||||
|
||||
if [ -z "$FLAG" ]; then
|
||||
log "hardware_check could not pick a comfy-cli flag. Defaulting to --nvidia."
|
||||
log "(For Intel Arc or unsupported hardware, use the manual install path.)"
|
||||
GPU_FLAG="--nvidia"
|
||||
else
|
||||
GPU_FLAG="$FLAG"
|
||||
fi
|
||||
fi
|
||||
fi
|
||||
|
||||
log "GPU flag: $GPU_FLAG"
|
||||
log "Port: $PORT"
|
||||
[ -n "$WORKSPACE" ] && log "Workspace: $WORKSPACE"
|
||||
[ "${#EXTRA_INSTALL_ARGS[@]}" -gt 0 ] && log "Extra install args: ${EXTRA_INSTALL_ARGS[*]}"
|
||||
|
||||
# --- Step 1: Install comfy-cli (prefer pipx / uvx over global pip) ---
|
||||
COMFY_BIN=""
|
||||
if command -v comfy >/dev/null 2>&1; then
|
||||
COMFY_BIN="comfy"
|
||||
log "comfy-cli already on PATH: $(comfy -v 2>/dev/null || echo 'unknown version')"
|
||||
elif command -v uvx >/dev/null 2>&1; then
|
||||
log "Using uvx (no install needed)"
|
||||
COMFY_BIN="uvx --from comfy-cli comfy"
|
||||
elif command -v pipx >/dev/null 2>&1; then
|
||||
log "Installing comfy-cli via pipx…"
|
||||
pipx install comfy-cli >>"$LOG_FILE" 2>&1
|
||||
COMFY_BIN="comfy"
|
||||
# pipx adds shims to ~/.local/bin which may need to be on PATH
|
||||
if ! command -v comfy >/dev/null 2>&1; then
|
||||
if [ -x "$HOME/.local/bin/comfy" ]; then
|
||||
export PATH="$HOME/.local/bin:$PATH"
|
||||
COMFY_BIN="$HOME/.local/bin/comfy"
|
||||
fi
|
||||
fi
|
||||
else
|
||||
log "Neither pipx nor uvx found. Falling back to pip install --user…"
|
||||
log " (Recommend installing pipx: https://pipx.pypa.io)"
|
||||
if ! pip install --user comfy-cli >>"$LOG_FILE" 2>&1; then
|
||||
# macOS: PEP 668 externally-managed-environment may block --user
|
||||
log "pip install --user failed. Retrying with --break-system-packages…"
|
||||
pip install --user --break-system-packages comfy-cli >>"$LOG_FILE" 2>&1 || {
|
||||
err "Could not install comfy-cli. Install pipx or uv first."
|
||||
exit 1
|
||||
}
|
||||
fi
|
||||
# Resolve the actual `comfy` script — pip --user puts it in:
|
||||
# Linux: ~/.local/bin/comfy
|
||||
# macOS: ~/Library/Python/<ver>/bin/comfy OR ~/.local/bin/comfy
|
||||
COMFY_BIN=""
|
||||
for candidate in "$HOME/.local/bin/comfy" \
|
||||
"$HOME/Library/Python/3.13/bin/comfy" \
|
||||
"$HOME/Library/Python/3.12/bin/comfy" \
|
||||
"$HOME/Library/Python/3.11/bin/comfy" \
|
||||
"$HOME/Library/Python/3.10/bin/comfy"; do
|
||||
if [ -x "$candidate" ]; then
|
||||
COMFY_BIN="$candidate"
|
||||
export PATH="$(dirname "$candidate"):$PATH"
|
||||
break
|
||||
fi
|
||||
done
|
||||
if [ -z "$COMFY_BIN" ]; then
|
||||
if command -v comfy >/dev/null 2>&1; then
|
||||
COMFY_BIN="comfy"
|
||||
else
|
||||
err "Installed comfy-cli but couldn't find the 'comfy' script."
|
||||
err "Add the right Python user-bin directory to PATH and retry."
|
||||
exit 1
|
||||
fi
|
||||
fi
|
||||
fi
|
||||
|
||||
# --- Step 2: Disable analytics tracking (avoid interactive prompt) ---
|
||||
log "Disabling analytics tracking…"
|
||||
$COMFY_BIN --skip-prompt tracking disable >>"$LOG_FILE" 2>&1 || true
|
||||
|
||||
# --- Step 3: Install ComfyUI ---
|
||||
WORKSPACE_ARG=()
|
||||
if [ -n "$WORKSPACE" ]; then
|
||||
WORKSPACE_ARG=(--workspace "$WORKSPACE")
|
||||
fi
|
||||
|
||||
if $COMFY_BIN "${WORKSPACE_ARG[@]}" which 2>/dev/null | grep -q "ComfyUI"; then
|
||||
EXISTING_WS="$($COMFY_BIN "${WORKSPACE_ARG[@]}" which 2>/dev/null || true)"
|
||||
log "ComfyUI already installed at: $EXISTING_WS"
|
||||
else
|
||||
log "Installing ComfyUI ($GPU_FLAG)…"
|
||||
if ! $COMFY_BIN "${WORKSPACE_ARG[@]}" --skip-prompt install "$GPU_FLAG" "${EXTRA_INSTALL_ARGS[@]}" >>"$LOG_FILE" 2>&1; then
|
||||
err "Install failed. Tail of log:"
|
||||
tail -20 "$LOG_FILE" >&2
|
||||
exit 1
|
||||
fi
|
||||
fi
|
||||
|
||||
if [ "$SKIP_LAUNCH" -eq 1 ]; then
|
||||
log "Setup complete (--skip-launch). Run \`$COMFY_BIN launch --background -- --port $PORT\` when ready."
|
||||
exit 0
|
||||
fi
|
||||
|
||||
# --- Step 4: Detect already-running server ---
|
||||
if curl -fsS "http://127.0.0.1:$PORT/system_stats" >/dev/null 2>&1; then
|
||||
log "Server already running on port $PORT — skipping launch."
|
||||
log "Stop with \`$COMFY_BIN stop\` if you want a fresh start."
|
||||
curl -fsS "http://127.0.0.1:$PORT/system_stats" | python3 -m json.tool 2>/dev/null || true
|
||||
log "Done."
|
||||
exit 0
|
||||
fi
|
||||
|
||||
# --- Step 5: Launch ---
|
||||
log "Launching ComfyUI in background on port $PORT…"
|
||||
LAUNCH_EXTRAS=("--" "--port" "$PORT")
|
||||
if ! $COMFY_BIN "${WORKSPACE_ARG[@]}" launch --background "${LAUNCH_EXTRAS[@]}" >>"$LOG_FILE" 2>&1; then
|
||||
err "Background launch failed. Tail of log:"
|
||||
tail -20 "$LOG_FILE" >&2
|
||||
err "Try foreground launch to see real-time errors: $COMFY_BIN launch -- --port $PORT"
|
||||
exit 1
|
||||
fi
|
||||
|
||||
# --- Step 6: Wait for server ---
|
||||
log "Waiting for server…"
|
||||
MAX_WAIT=60
|
||||
ELAPSED=0
|
||||
while [ $ELAPSED -lt $MAX_WAIT ]; do
|
||||
if curl -fsS "http://127.0.0.1:$PORT/system_stats" >/dev/null 2>&1; then
|
||||
log "Server is running!"
|
||||
curl -fsS "http://127.0.0.1:$PORT/system_stats" | python3 -m json.tool 2>/dev/null || true
|
||||
break
|
||||
fi
|
||||
sleep 2
|
||||
ELAPSED=$((ELAPSED + 2))
|
||||
done
|
||||
|
||||
if [ $ELAPSED -ge $MAX_WAIT ]; then
|
||||
err "Server did not start within ${MAX_WAIT}s."
|
||||
err "Inspect log: $LOG_FILE"
|
||||
err "Or run foreground: $COMFY_BIN launch -- --port $PORT"
|
||||
exit 1
|
||||
fi
|
||||
|
||||
log ""
|
||||
log "Setup complete!"
|
||||
log " Server: http://127.0.0.1:$PORT"
|
||||
log " Web UI: http://127.0.0.1:$PORT (open in browser)"
|
||||
log " Stop: $COMFY_BIN stop"
|
||||
log " Log: $LOG_FILE (kept until shell closes)"
|
||||
log ""
|
||||
log "Next steps:"
|
||||
log " - Download a model: $COMFY_BIN model download --url <URL> --relative-path models/checkpoints"
|
||||
log " - Run a workflow: python3 $SCRIPT_DIR/run_workflow.py --workflow <file.json> --args '{...}'"
|
||||
|
||||
# Disable trap on success path
|
||||
trap - EXIT
|
||||
+315
@@ -0,0 +1,315 @@
|
||||
#!/usr/bin/env python3
|
||||
"""
|
||||
extract_schema.py — Analyze a ComfyUI API-format workflow and extract
|
||||
controllable parameters.
|
||||
|
||||
Improvements over v1:
|
||||
- Catalogs live in `_common.py`, shared with `check_deps.py`
|
||||
- Coverage expanded for Flux / SD3 / Wan / Hunyuan / LTX / IPAdapter / rgthree
|
||||
- Symmetric duplicate-name resolution: ALL duplicates get a node-id suffix
|
||||
(instead of "first wins, second renamed"), so callers see consistent names
|
||||
- Negative prompt detected by tracing `KSampler.negative` connections back to
|
||||
the source CLIPTextEncode (more reliable than meta-title heuristic)
|
||||
- Embedding references in prompt text are extracted as model dependencies
|
||||
- Detects Primitive nodes that drive other nodes' inputs (and surfaces them
|
||||
as the user-facing parameter)
|
||||
- Reroutes are followed when tracing connections
|
||||
|
||||
Usage:
|
||||
python3 extract_schema.py workflow_api.json
|
||||
python3 extract_schema.py workflow_api.json --output schema.json
|
||||
|
||||
Stdlib-only. Python 3.10+.
|
||||
"""
|
||||
|
||||
from __future__ import annotations
|
||||
|
||||
import argparse
|
||||
import json
|
||||
import sys
|
||||
from pathlib import Path
|
||||
from typing import Any
|
||||
|
||||
sys.path.insert(0, str(Path(__file__).resolve().parent))
|
||||
from _common import ( # noqa: E402
|
||||
OUTPUT_NODES, PARAM_PATTERNS, PROMPT_FIELDS,
|
||||
is_link, iter_embedding_refs, iter_model_deps, iter_nodes, unwrap_workflow,
|
||||
)
|
||||
|
||||
|
||||
# Sampler nodes whose `positive` / `negative` connections we trace
|
||||
SAMPLER_NODE_FAMILY = {
|
||||
"KSampler", "KSamplerAdvanced",
|
||||
"SamplerCustom", "SamplerCustomAdvanced",
|
||||
"BasicGuider", "CFGGuider", "DualCFGGuider",
|
||||
}
|
||||
|
||||
|
||||
def infer_type(value: Any) -> str:
|
||||
if isinstance(value, bool):
|
||||
return "bool"
|
||||
if isinstance(value, int):
|
||||
return "int"
|
||||
if isinstance(value, float):
|
||||
return "float"
|
||||
if isinstance(value, str):
|
||||
return "string"
|
||||
if isinstance(value, list):
|
||||
return "link"
|
||||
if isinstance(value, dict):
|
||||
return "object"
|
||||
return "unknown"
|
||||
|
||||
|
||||
def trace_to_node(workflow: dict, link: list, *, max_hops: int = 8) -> str | None:
|
||||
"""Follow a [node_id, slot] link, hopping through Reroute / Primitive nodes
|
||||
if needed, to find the *upstream* node id that holds the actual value/input.
|
||||
|
||||
Bounded by both `max_hops` AND a visited-set to prevent infinite loops on
|
||||
pathological graphs.
|
||||
"""
|
||||
if not is_link(link):
|
||||
return None
|
||||
nid: str | None = link[0]
|
||||
visited: set[str] = set()
|
||||
for _ in range(max_hops):
|
||||
if nid is None or nid in visited:
|
||||
return nid
|
||||
visited.add(nid)
|
||||
node = workflow.get(nid)
|
||||
if not isinstance(node, dict):
|
||||
return None
|
||||
cls = node.get("class_type", "")
|
||||
# Reroute / Primitive / passthrough wrappers
|
||||
if cls in {"Reroute", "PrimitiveNode", "Note", "easy showAnything"}:
|
||||
inputs = node.get("inputs", {}) or {}
|
||||
# Find first link-shaped input and follow it
|
||||
next_link = next((v for v in inputs.values() if is_link(v)), None)
|
||||
if next_link is None:
|
||||
return nid
|
||||
nid = next_link[0]
|
||||
continue
|
||||
return nid
|
||||
return nid
|
||||
|
||||
|
||||
def find_negative_prompt_node(workflow: dict) -> str | None:
|
||||
"""Trace `negative` input of a sampler back to the source text encoder."""
|
||||
for nid, node in iter_nodes(workflow):
|
||||
if node["class_type"] not in SAMPLER_NODE_FAMILY:
|
||||
continue
|
||||
inputs = node.get("inputs", {}) or {}
|
||||
neg = inputs.get("negative")
|
||||
if not is_link(neg):
|
||||
continue
|
||||
src = trace_to_node(workflow, neg)
|
||||
if src and isinstance(workflow.get(src), dict):
|
||||
cls = workflow[src].get("class_type", "")
|
||||
if cls.startswith("CLIPTextEncode") or cls in {"smZ CLIPTextEncode", "BNK_CLIPTextEncodeAdvanced"}:
|
||||
return src
|
||||
return None
|
||||
|
||||
|
||||
def find_positive_prompt_node(workflow: dict) -> str | None:
|
||||
for nid, node in iter_nodes(workflow):
|
||||
if node["class_type"] not in SAMPLER_NODE_FAMILY:
|
||||
continue
|
||||
inputs = node.get("inputs", {}) or {}
|
||||
pos = inputs.get("positive")
|
||||
if not is_link(pos):
|
||||
continue
|
||||
src = trace_to_node(workflow, pos)
|
||||
if src and isinstance(workflow.get(src), dict):
|
||||
cls = workflow[src].get("class_type", "")
|
||||
if cls.startswith("CLIPTextEncode") or cls in {"smZ CLIPTextEncode", "BNK_CLIPTextEncodeAdvanced"}:
|
||||
return src
|
||||
return None
|
||||
|
||||
|
||||
def extract_schema(workflow: dict) -> dict:
|
||||
"""Extract controllable parameters from a workflow.
|
||||
|
||||
Returns:
|
||||
{
|
||||
"parameters": { friendly_name: {node_id, field, type, value, ...} },
|
||||
"output_nodes": [node_id, ...],
|
||||
"model_dependencies": [{node_id, class_type, field, value, folder}],
|
||||
"embedding_dependencies": [{node_id, embedding_name, found_in_field, value_excerpt}],
|
||||
"summary": {...}
|
||||
}
|
||||
"""
|
||||
output_nodes: list[str] = []
|
||||
|
||||
# First pass: identify positive / negative prompt nodes via connection tracing
|
||||
pos_node = find_positive_prompt_node(workflow)
|
||||
neg_node = find_negative_prompt_node(workflow)
|
||||
|
||||
# ----- collect raw parameter candidates -----
|
||||
# Each candidate = (friendly_name, node_id, field, value)
|
||||
# We resolve duplicate friendly_names AFTER the loop so dedup is symmetric.
|
||||
raw_params: list[dict] = []
|
||||
|
||||
for node_id, node in iter_nodes(workflow):
|
||||
cls = node["class_type"]
|
||||
inputs = node.get("inputs", {}) or {}
|
||||
|
||||
if cls in OUTPUT_NODES:
|
||||
output_nodes.append(node_id)
|
||||
|
||||
# Match this node against PARAM_PATTERNS
|
||||
for p_class, p_field, friendly in PARAM_PATTERNS:
|
||||
if cls != p_class:
|
||||
continue
|
||||
if p_field not in inputs:
|
||||
continue
|
||||
value = inputs[p_field]
|
||||
t = infer_type(value)
|
||||
if t == "link":
|
||||
continue # connections aren't directly controllable
|
||||
|
||||
actual_name = friendly
|
||||
|
||||
# Disambiguate prompt vs negative_prompt by connection tracing
|
||||
if friendly == "prompt":
|
||||
if node_id == neg_node and pos_node != neg_node:
|
||||
actual_name = "negative_prompt"
|
||||
elif node_id == pos_node:
|
||||
actual_name = "prompt"
|
||||
else:
|
||||
# Fallback: use _meta.title hints if present
|
||||
meta_title = (node.get("_meta") or {}).get("title", "").lower()
|
||||
if any(t_ in meta_title for t_ in ("negative", "neg", "-prompt", "anti")):
|
||||
actual_name = "negative_prompt"
|
||||
|
||||
raw_params.append({
|
||||
"name_hint": actual_name,
|
||||
"node_id": node_id,
|
||||
"field": p_field,
|
||||
"type": t,
|
||||
"value": value,
|
||||
"class_type": cls,
|
||||
})
|
||||
|
||||
# ----- symmetric duplicate-name resolution -----
|
||||
# Group by name_hint. If a hint appears once, keep it. If multiple, suffix
|
||||
# ALL with their node_id. Always-stable, always-uniquely-addressable.
|
||||
by_name: dict[str, list[dict]] = {}
|
||||
for r in raw_params:
|
||||
by_name.setdefault(r["name_hint"], []).append(r)
|
||||
|
||||
parameters: dict[str, dict] = {}
|
||||
for name, entries in by_name.items():
|
||||
if len(entries) == 1:
|
||||
r = entries[0]
|
||||
parameters[name] = {
|
||||
"node_id": r["node_id"], "field": r["field"],
|
||||
"type": r["type"], "value": r["value"],
|
||||
"class_type": r["class_type"],
|
||||
}
|
||||
else:
|
||||
# Sort by node_id (string-natural) for stability
|
||||
entries.sort(key=lambda x: (str(x["node_id"]).zfill(8), x["field"]))
|
||||
for r in entries:
|
||||
full_name = f"{name}_{r['node_id']}"
|
||||
parameters[full_name] = {
|
||||
"node_id": r["node_id"], "field": r["field"],
|
||||
"type": r["type"], "value": r["value"],
|
||||
"class_type": r["class_type"],
|
||||
"alias_of": name,
|
||||
}
|
||||
|
||||
# ----- model dependencies -----
|
||||
model_deps = list(iter_model_deps(workflow))
|
||||
|
||||
# ----- embedding dependencies (in prompt text) -----
|
||||
embedding_deps: list[dict] = []
|
||||
seen_emb: set[tuple[str, str]] = set()
|
||||
for nid, emb_name in iter_embedding_refs(workflow):
|
||||
key = (nid, emb_name)
|
||||
if key in seen_emb:
|
||||
continue
|
||||
seen_emb.add(key)
|
||||
# Find which field had the reference, for context
|
||||
node = workflow.get(nid, {})
|
||||
inputs = node.get("inputs", {}) or {}
|
||||
found_field = None
|
||||
excerpt = None
|
||||
for fname, fval in inputs.items():
|
||||
if isinstance(fval, str) and fname in PROMPT_FIELDS and emb_name in fval:
|
||||
found_field = fname
|
||||
excerpt = fval[:120]
|
||||
break
|
||||
embedding_deps.append({
|
||||
"node_id": nid,
|
||||
"embedding_name": emb_name,
|
||||
"field": found_field,
|
||||
"value_excerpt": excerpt,
|
||||
"folder": "embeddings",
|
||||
})
|
||||
|
||||
# ----- summary -----
|
||||
summary = {
|
||||
"parameter_count": len(parameters),
|
||||
"output_node_count": len(output_nodes),
|
||||
"model_dep_count": len(model_deps),
|
||||
"embedding_dep_count": len(embedding_deps),
|
||||
"has_negative_prompt": "negative_prompt" in parameters,
|
||||
"has_seed": "seed" in parameters or any(p.startswith("seed_") for p in parameters),
|
||||
"is_video_workflow": any(
|
||||
workflow.get(n, {}).get("class_type", "") in {
|
||||
"VHS_VideoCombine", "SaveVideo", "SaveAnimatedWEBP", "SaveAnimatedPNG",
|
||||
} for n in output_nodes
|
||||
),
|
||||
}
|
||||
|
||||
return {
|
||||
"parameters": parameters,
|
||||
"output_nodes": output_nodes,
|
||||
"model_dependencies": model_deps,
|
||||
"embedding_dependencies": embedding_deps,
|
||||
"summary": summary,
|
||||
}
|
||||
|
||||
|
||||
def main(argv: list[str] | None = None) -> int:
|
||||
p = argparse.ArgumentParser(description="Extract controllable parameters from a ComfyUI workflow")
|
||||
p.add_argument("workflow", help="Path to workflow API JSON file")
|
||||
p.add_argument("--output", "-o", help="Output file (default: stdout)")
|
||||
p.add_argument("--summary-only", action="store_true",
|
||||
help="Only print the summary block")
|
||||
args = p.parse_args(argv)
|
||||
|
||||
wf_path = Path(args.workflow).expanduser()
|
||||
if not wf_path.exists():
|
||||
print(f"Error: {wf_path} not found", file=sys.stderr)
|
||||
return 1
|
||||
|
||||
try:
|
||||
with wf_path.open(encoding="utf-8-sig") as f:
|
||||
payload = json.load(f)
|
||||
workflow = unwrap_workflow(payload)
|
||||
except ValueError as e:
|
||||
print(f"Error: {e}", file=sys.stderr)
|
||||
return 1
|
||||
except json.JSONDecodeError as e:
|
||||
print(f"Error: invalid JSON — {e}", file=sys.stderr)
|
||||
return 1
|
||||
|
||||
schema = extract_schema(workflow)
|
||||
|
||||
if args.summary_only:
|
||||
out = json.dumps(schema["summary"], indent=2)
|
||||
else:
|
||||
out = json.dumps(schema, indent=2, default=str)
|
||||
|
||||
if args.output:
|
||||
Path(args.output).write_text(out, encoding="utf-8")
|
||||
print(f"Schema written to {args.output}", file=sys.stderr)
|
||||
else:
|
||||
print(out)
|
||||
|
||||
return 0
|
||||
|
||||
|
||||
if __name__ == "__main__":
|
||||
sys.exit(main())
|
||||
+157
@@ -0,0 +1,157 @@
|
||||
#!/usr/bin/env python3
|
||||
"""
|
||||
fetch_logs.py — Retrieve workflow execution diagnostics from a ComfyUI server.
|
||||
|
||||
When a workflow errors, the server's /history (local) or /jobs (cloud) entry
|
||||
contains the full Python traceback. This script makes it easy to fetch by
|
||||
prompt_id, with sensible formatting.
|
||||
|
||||
Usage:
|
||||
python3 fetch_logs.py <prompt_id>
|
||||
python3 fetch_logs.py <prompt_id> --host https://cloud.comfy.org
|
||||
python3 fetch_logs.py --tail-queue # show currently queued/running jobs
|
||||
"""
|
||||
|
||||
from __future__ import annotations
|
||||
|
||||
import argparse
|
||||
import sys
|
||||
from pathlib import Path
|
||||
|
||||
sys.path.insert(0, str(Path(__file__).resolve().parent))
|
||||
from _common import ( # noqa: E402
|
||||
DEFAULT_LOCAL_HOST, ENV_API_KEY, emit_json, http_get, is_cloud_host,
|
||||
resolve_api_key, resolve_url,
|
||||
)
|
||||
|
||||
|
||||
def fetch_history_entry(host: str, headers: dict, prompt_id: str, *, is_cloud: bool) -> dict:
|
||||
if is_cloud:
|
||||
# Try /jobs/{id} first
|
||||
url = resolve_url(host, f"/jobs/{prompt_id}", is_cloud=True)
|
||||
r = http_get(url, headers=headers, retries=2, timeout=30)
|
||||
if r.status == 200:
|
||||
try:
|
||||
return {"ok": True, "entry": r.json(), "source": "/api/jobs"}
|
||||
except Exception:
|
||||
pass
|
||||
# Fallback to history_v2
|
||||
url = resolve_url(host, f"/history/{prompt_id}", is_cloud=True)
|
||||
r = http_get(url, headers=headers, retries=2, timeout=30)
|
||||
try:
|
||||
data = r.json()
|
||||
except Exception:
|
||||
data = None
|
||||
if r.status == 200 and data:
|
||||
return {"ok": True, "entry": data, "source": "/api/history_v2"}
|
||||
return {"ok": False, "http_status": r.status, "body": r.text()[:500]}
|
||||
|
||||
url = resolve_url(host, f"/history/{prompt_id}", is_cloud=False)
|
||||
r = http_get(url, headers=headers, retries=2, timeout=30)
|
||||
if r.status != 200:
|
||||
return {"ok": False, "http_status": r.status, "body": r.text()[:500]}
|
||||
try:
|
||||
data = r.json()
|
||||
except Exception:
|
||||
return {"ok": False, "reason": "non-JSON response"}
|
||||
if not isinstance(data, dict) or prompt_id not in data:
|
||||
return {"ok": False, "reason": "prompt_id not found in history",
|
||||
"history_keys": list(data.keys())[:5] if isinstance(data, dict) else []}
|
||||
return {"ok": True, "entry": data[prompt_id], "source": "/history"}
|
||||
|
||||
|
||||
def fetch_queue(host: str, headers: dict) -> dict:
|
||||
url = resolve_url(host, "/queue")
|
||||
r = http_get(url, headers=headers, retries=2, timeout=15)
|
||||
try:
|
||||
data = r.json()
|
||||
except Exception:
|
||||
data = {"raw": r.text()[:500]}
|
||||
return {"http_status": r.status, "data": data}
|
||||
|
||||
|
||||
def extract_diagnostics(entry: dict) -> dict:
|
||||
"""Pull out the parts a human cares about: status, errors, traceback, timing."""
|
||||
diag: dict = {}
|
||||
status = entry.get("status") or {}
|
||||
diag["status_str"] = status.get("status_str")
|
||||
diag["completed"] = status.get("completed")
|
||||
|
||||
messages = status.get("messages") or []
|
||||
diag["execution_log"] = []
|
||||
for msg in messages:
|
||||
if isinstance(msg, list) and len(msg) >= 2:
|
||||
mtype, mdata = msg[0], msg[1]
|
||||
diag["execution_log"].append({"type": mtype, "data": mdata})
|
||||
else:
|
||||
diag["execution_log"].append(msg)
|
||||
|
||||
# Look for execution_error inside messages
|
||||
errors = []
|
||||
for msg in messages:
|
||||
if isinstance(msg, list) and len(msg) >= 2 and msg[0] == "execution_error":
|
||||
errors.append(msg[1])
|
||||
if errors:
|
||||
diag["errors"] = errors
|
||||
|
||||
# Cloud's /jobs response shape: top-level outputs / status / etc.
|
||||
if "outputs" in entry:
|
||||
out = entry["outputs"] or {}
|
||||
if isinstance(out, dict):
|
||||
diag["output_node_ids"] = list(out.keys())
|
||||
# Count file refs across all output buckets (images / video / etc.)
|
||||
total = 0
|
||||
for node_output in out.values():
|
||||
if not isinstance(node_output, dict):
|
||||
continue
|
||||
for v in node_output.values():
|
||||
if isinstance(v, list):
|
||||
total += len(v)
|
||||
diag["output_count"] = total
|
||||
else:
|
||||
diag["output_node_ids"] = []
|
||||
diag["output_count"] = 0
|
||||
return diag
|
||||
|
||||
|
||||
def main(argv: list[str] | None = None) -> int:
|
||||
p = argparse.ArgumentParser(description="Fetch workflow execution diagnostics")
|
||||
p.add_argument("prompt_id", nargs="?", help="prompt_id to look up")
|
||||
p.add_argument("--host", default=DEFAULT_LOCAL_HOST)
|
||||
p.add_argument("--api-key", help=f"or set ${ENV_API_KEY}")
|
||||
p.add_argument("--raw", action="store_true",
|
||||
help="Print the full history entry instead of the digest")
|
||||
p.add_argument("--tail-queue", action="store_true",
|
||||
help="Show currently running/pending jobs instead")
|
||||
args = p.parse_args(argv)
|
||||
|
||||
api_key = resolve_api_key(args.api_key)
|
||||
headers = {"X-API-Key": api_key} if api_key else {}
|
||||
is_cloud = is_cloud_host(args.host)
|
||||
|
||||
if args.tail_queue:
|
||||
emit_json(fetch_queue(args.host, headers))
|
||||
return 0
|
||||
|
||||
if not args.prompt_id:
|
||||
print("Error: prompt_id is required (or use --tail-queue)", file=sys.stderr)
|
||||
return 1
|
||||
|
||||
res = fetch_history_entry(args.host, headers, args.prompt_id, is_cloud=is_cloud)
|
||||
if not res.get("ok"):
|
||||
emit_json(res)
|
||||
return 1
|
||||
|
||||
if args.raw:
|
||||
emit_json(res)
|
||||
return 0
|
||||
|
||||
diag = extract_diagnostics(res["entry"])
|
||||
diag["source"] = res.get("source")
|
||||
diag["prompt_id"] = args.prompt_id
|
||||
emit_json(diag)
|
||||
return 0 if diag.get("status_str") not in {"error",} else 1
|
||||
|
||||
|
||||
if __name__ == "__main__":
|
||||
sys.exit(main())
|
||||
+497
@@ -0,0 +1,497 @@
|
||||
#!/usr/bin/env python3
|
||||
"""hardware_check.py — Detect whether this machine can realistically run ComfyUI locally.
|
||||
|
||||
Improvements over v1:
|
||||
- Multi-GPU detection: scans all NVIDIA / AMD GPUs, picks the best one (most VRAM)
|
||||
- Apple Silicon: detects Rosetta-via-x86_64 false negative; warns instead of misclassifying
|
||||
- Apple generation: defaults to None (unknown) instead of mis-tagging as M1
|
||||
- WSL2 detection: identifies WSL2 + nvidia-smi situation explicitly
|
||||
- ROCm: prefers `rocm-smi --json` for new ROCm 6.x output
|
||||
- Disk space check: warns if /home or workspace volume has < 25 GB free
|
||||
- PyTorch verification (optional): tries to import torch and check device availability
|
||||
- Windows: prefers PowerShell `Get-CimInstance` over deprecated `wmic`
|
||||
- More accurate VRAM thresholds and verdict reasons
|
||||
|
||||
Emits a structured JSON report. Exit codes match `verdict`:
|
||||
0 → ok
|
||||
1 → marginal
|
||||
2 → cloud
|
||||
|
||||
Usage:
|
||||
python3 hardware_check.py [--json] [--check-pytorch]
|
||||
"""
|
||||
|
||||
from __future__ import annotations
|
||||
|
||||
import json
|
||||
import os
|
||||
import platform
|
||||
import re
|
||||
import shutil
|
||||
import subprocess
|
||||
import sys
|
||||
from typing import Any
|
||||
|
||||
|
||||
# Thresholds (GiB).
|
||||
MIN_VRAM_GB_USABLE = 6
|
||||
OK_VRAM_GB = 8
|
||||
GREAT_VRAM_GB = 12
|
||||
MIN_MAC_RAM_GB = 16
|
||||
OK_MAC_RAM_GB = 32
|
||||
MIN_FREE_DISK_GB = 25 # ComfyUI core ~5 GB + one model ~5–24 GB
|
||||
|
||||
_COMFY_CLI_FLAG = {
|
||||
"nvidia": "--nvidia",
|
||||
"amd": "--amd",
|
||||
"apple-silicon": "--m-series",
|
||||
"intel": None,
|
||||
"comfy-cloud": None,
|
||||
"cpu": "--cpu",
|
||||
}
|
||||
|
||||
|
||||
def _run(cmd: list[str], timeout: int = 8) -> str:
|
||||
try:
|
||||
out = subprocess.run(
|
||||
cmd, capture_output=True, text=True, encoding='utf-8', errors='replace', timeout=timeout, check=False
|
||||
)
|
||||
return (out.stdout or "") + (out.stderr or "")
|
||||
except (FileNotFoundError, subprocess.TimeoutExpired, OSError):
|
||||
return ""
|
||||
|
||||
|
||||
def is_wsl() -> bool:
|
||||
"""Return True when running under Windows Subsystem for Linux."""
|
||||
if platform.system() != "Linux":
|
||||
return False
|
||||
if "microsoft" in platform.release().lower() or "wsl" in platform.release().lower():
|
||||
return True
|
||||
try:
|
||||
with open("/proc/version", "r", encoding="utf-8") as fh:
|
||||
return "microsoft" in fh.read().lower()
|
||||
except OSError:
|
||||
return False
|
||||
|
||||
|
||||
def is_rosetta() -> bool:
|
||||
"""Return True when Python is running translated under Rosetta on Apple Silicon."""
|
||||
if platform.system() != "Darwin":
|
||||
return False
|
||||
if platform.machine() == "arm64":
|
||||
return False
|
||||
# x86_64 on Darwin — could be Intel Mac or Rosetta. Probe sysctl.
|
||||
out = _run(["sysctl", "-in", "sysctl.proc_translated"]).strip()
|
||||
return out == "1"
|
||||
|
||||
|
||||
def detect_nvidia() -> dict | None:
|
||||
"""Detect NVIDIA GPUs. Returns the GPU with the most VRAM, plus list of all."""
|
||||
if not shutil.which("nvidia-smi"):
|
||||
return None
|
||||
out = _run([
|
||||
"nvidia-smi",
|
||||
"--query-gpu=index,name,memory.total,driver_version",
|
||||
"--format=csv,noheader,nounits",
|
||||
])
|
||||
if not out.strip():
|
||||
return None
|
||||
gpus = []
|
||||
for line in out.strip().splitlines():
|
||||
parts = [p.strip() for p in line.split(",")]
|
||||
if len(parts) < 3:
|
||||
continue
|
||||
try:
|
||||
idx = int(parts[0])
|
||||
name = parts[1]
|
||||
vram_mb = int(parts[2])
|
||||
except ValueError:
|
||||
continue
|
||||
driver = parts[3] if len(parts) > 3 else ""
|
||||
gpus.append({
|
||||
"vendor": "nvidia",
|
||||
"index": idx,
|
||||
"name": name,
|
||||
"vram_gb": round(vram_mb / 1024, 1),
|
||||
"driver": driver,
|
||||
})
|
||||
if not gpus:
|
||||
return None
|
||||
# Pick GPU with most VRAM
|
||||
best = max(gpus, key=lambda g: g["vram_gb"])
|
||||
if len(gpus) > 1:
|
||||
best["all_gpus"] = gpus
|
||||
return best
|
||||
|
||||
|
||||
def detect_rocm() -> dict | None:
|
||||
if not shutil.which("rocm-smi"):
|
||||
return None
|
||||
# Prefer JSON output (new ROCm 6.x)
|
||||
out = _run(["rocm-smi", "--showproductname", "--showmeminfo", "vram", "--json"])
|
||||
if out.strip().startswith("{"):
|
||||
try:
|
||||
data = json.loads(out)
|
||||
cards = []
|
||||
for card_id, info in data.items():
|
||||
if not card_id.startswith("card"):
|
||||
continue
|
||||
name = (info.get("Card series") or info.get("Card model")
|
||||
or info.get("Marketing Name") or "AMD GPU")
|
||||
vram_b = info.get("VRAM Total Memory (B)") or info.get("vram_total_memory_b") or 0
|
||||
try:
|
||||
vram_b = int(vram_b)
|
||||
except (ValueError, TypeError):
|
||||
vram_b = 0
|
||||
cards.append({
|
||||
"vendor": "amd",
|
||||
"name": str(name).strip(),
|
||||
"vram_gb": round(vram_b / (1024**3), 1),
|
||||
"driver": "rocm",
|
||||
})
|
||||
if cards:
|
||||
best = max(cards, key=lambda c: c["vram_gb"])
|
||||
if len(cards) > 1:
|
||||
best["all_gpus"] = cards
|
||||
return best
|
||||
except json.JSONDecodeError:
|
||||
pass
|
||||
# Fall back to text parsing
|
||||
out = _run(["rocm-smi", "--showproductname", "--showmeminfo", "vram"])
|
||||
if not out.strip():
|
||||
return None
|
||||
name_m = re.search(r"Card (?:series|model|Marketing Name):\s*(.+)", out)
|
||||
vram_m = re.search(r"VRAM Total Memory \(B\):\s*(\d+)", out)
|
||||
vram_gb = round(int(vram_m.group(1)) / (1024**3), 1) if vram_m else 0.0
|
||||
return {
|
||||
"vendor": "amd",
|
||||
"name": name_m.group(1).strip() if name_m else "AMD GPU",
|
||||
"vram_gb": vram_gb,
|
||||
"driver": "rocm",
|
||||
}
|
||||
|
||||
|
||||
def detect_apple_silicon() -> dict | None:
|
||||
if platform.system() != "Darwin":
|
||||
return None
|
||||
if platform.machine() != "arm64":
|
||||
return None
|
||||
chip = _run(["sysctl", "-n", "machdep.cpu.brand_string"]).strip()
|
||||
m = re.search(r"Apple M(\d+)", chip)
|
||||
generation = int(m.group(1)) if m else None
|
||||
mem_bytes = 0
|
||||
try:
|
||||
mem_bytes = int(_run(["sysctl", "-n", "hw.memsize"]).strip() or 0)
|
||||
except ValueError:
|
||||
pass
|
||||
ram_gb = round(mem_bytes / (1024**3), 1) if mem_bytes else 0.0
|
||||
|
||||
# Detect chip variant ("Pro", "Max", "Ultra") — affects performance even at same gen
|
||||
variant = None
|
||||
for v in ("Ultra", "Max", "Pro"):
|
||||
if v in chip:
|
||||
variant = v
|
||||
break
|
||||
|
||||
return {
|
||||
"vendor": "apple",
|
||||
"name": chip or "Apple Silicon",
|
||||
"generation": generation,
|
||||
"variant": variant,
|
||||
"unified_memory_gb": ram_gb,
|
||||
}
|
||||
|
||||
|
||||
def detect_intel_arc() -> dict | None:
|
||||
if platform.system() not in {"Linux", "Windows"}:
|
||||
return None
|
||||
if shutil.which("clinfo"):
|
||||
out = _run(["clinfo", "--list"])
|
||||
if "Intel" in out and ("Arc" in out or "Xe" in out):
|
||||
return {"vendor": "intel", "name": "Intel Arc/Xe", "vram_gb": 0.0}
|
||||
# Windows: try Get-CimInstance
|
||||
if platform.system() == "Windows" and shutil.which("powershell"):
|
||||
out = _run(["powershell", "-NoProfile",
|
||||
"Get-CimInstance Win32_VideoController | Select-Object Name | Format-List"])
|
||||
if "Intel" in out and ("Arc" in out or "Iris Xe" in out):
|
||||
return {"vendor": "intel", "name": "Intel Arc/Iris Xe", "vram_gb": 0.0}
|
||||
return None
|
||||
|
||||
|
||||
def total_system_ram_gb() -> float:
|
||||
sysname = platform.system()
|
||||
if sysname == "Darwin":
|
||||
try:
|
||||
return round(int(_run(["sysctl", "-n", "hw.memsize"]).strip() or 0) / (1024**3), 1)
|
||||
except ValueError:
|
||||
return 0.0
|
||||
if sysname == "Linux":
|
||||
try:
|
||||
with open("/proc/meminfo", "r", encoding="utf-8") as fh:
|
||||
for line in fh:
|
||||
if line.startswith("MemTotal:"):
|
||||
kb = int(line.split()[1])
|
||||
return round(kb / (1024**2), 1)
|
||||
except OSError:
|
||||
return 0.0
|
||||
if sysname == "Windows":
|
||||
if shutil.which("powershell"):
|
||||
out = _run([
|
||||
"powershell", "-NoProfile",
|
||||
"(Get-CimInstance Win32_ComputerSystem).TotalPhysicalMemory",
|
||||
])
|
||||
m = re.search(r"(\d{8,})", out)
|
||||
if m:
|
||||
return round(int(m.group(1)) / (1024**3), 1)
|
||||
# Fall back to wmic for older Windows
|
||||
out = _run(["wmic", "ComputerSystem", "get", "TotalPhysicalMemory"])
|
||||
m = re.search(r"(\d{6,})", out)
|
||||
if m:
|
||||
return round(int(m.group(1)) / (1024**3), 1)
|
||||
return 0.0
|
||||
|
||||
|
||||
def total_free_disk_gb(path: str = ".") -> float:
|
||||
try:
|
||||
usage = shutil.disk_usage(path)
|
||||
return round(usage.free / (1024**3), 1)
|
||||
except OSError:
|
||||
return 0.0
|
||||
|
||||
|
||||
def check_pytorch_cuda() -> dict | None:
|
||||
"""Optional PyTorch availability check. Only run when --check-pytorch is set."""
|
||||
try:
|
||||
import torch # type: ignore[import-not-found]
|
||||
except Exception as e:
|
||||
return {"available": False, "reason": f"torch not importable: {e}"}
|
||||
info: dict[str, Any] = {
|
||||
"available": True,
|
||||
"torch_version": torch.__version__,
|
||||
}
|
||||
try:
|
||||
info["cuda_available"] = bool(torch.cuda.is_available())
|
||||
if info["cuda_available"]:
|
||||
info["cuda_device_count"] = torch.cuda.device_count()
|
||||
info["cuda_device_0"] = torch.cuda.get_device_name(0)
|
||||
except Exception:
|
||||
info["cuda_available"] = False
|
||||
try:
|
||||
info["mps_available"] = bool(torch.backends.mps.is_available())
|
||||
except Exception:
|
||||
info["mps_available"] = False
|
||||
return info
|
||||
|
||||
|
||||
def classify(gpu: dict | None, ram_gb: float, free_disk_gb: float, *, wsl: bool, rosetta: bool) -> tuple[str, str, list[str]]:
|
||||
notes: list[str] = []
|
||||
|
||||
if rosetta:
|
||||
notes.append(
|
||||
"Detected Python running under Rosetta on Apple Silicon. "
|
||||
"ComfyUI MPS support requires native ARM64 Python — install via "
|
||||
"`brew install python` or arm64 Miniforge, then re-run."
|
||||
)
|
||||
return "cloud", "comfy-cloud", notes
|
||||
|
||||
if wsl and gpu and gpu["vendor"] == "nvidia":
|
||||
notes.append("Detected WSL2 + NVIDIA — confirm `nvidia-smi` works in your WSL distro before installing.")
|
||||
|
||||
if free_disk_gb and free_disk_gb < MIN_FREE_DISK_GB:
|
||||
notes.append(
|
||||
f"Free disk space ({free_disk_gb} GB) is below the {MIN_FREE_DISK_GB} GB recommended minimum. "
|
||||
"ComfyUI core (~5 GB) plus one SDXL model (~6.5 GB) needs space; Flux Dev needs ~24 GB."
|
||||
)
|
||||
|
||||
# Host RAM matters even for discrete-GPU systems: ComfyUI swaps model
|
||||
# weights through CPU RAM when shuffling between text encoders / VAE / UNet.
|
||||
# Apple's unified-memory check is handled below so don't double-warn.
|
||||
if ram_gb and ram_gb < 8 and gpu and gpu.get("vendor") != "apple":
|
||||
notes.append(
|
||||
f"System RAM ({ram_gb} GB) is low. ComfyUI swaps model weights through "
|
||||
"host RAM; <8 GB causes severe slowdowns. 16+ GB recommended."
|
||||
)
|
||||
|
||||
if gpu is None:
|
||||
notes.append(
|
||||
"No supported accelerator found (NVIDIA CUDA / AMD ROCm / Apple Silicon / Intel Arc)."
|
||||
)
|
||||
notes.append(
|
||||
"CPU-only ComfyUI works but is unusably slow for modern models — use Comfy Cloud."
|
||||
)
|
||||
return "cloud", "comfy-cloud", notes
|
||||
|
||||
if gpu["vendor"] == "apple":
|
||||
gen = gpu.get("generation")
|
||||
variant = gpu.get("variant")
|
||||
mem = gpu.get("unified_memory_gb", 0.0)
|
||||
gen_str = f"M{gen}" if gen else "Apple Silicon"
|
||||
if variant:
|
||||
gen_str += f" {variant}"
|
||||
if mem < MIN_MAC_RAM_GB:
|
||||
notes.append(
|
||||
f"{gen_str} with {mem} GB unified memory — below the {MIN_MAC_RAM_GB} GB practical minimum."
|
||||
)
|
||||
notes.append("SD1.5 may work; SDXL/Flux will swap or OOM. Recommend Comfy Cloud.")
|
||||
return "cloud", "comfy-cloud", notes
|
||||
if mem < OK_MAC_RAM_GB:
|
||||
notes.append(
|
||||
f"{gen_str} with {mem} GB — SDXL works but slow. Flux/video likely too tight."
|
||||
)
|
||||
return "marginal", "apple-silicon", notes
|
||||
notes.append(f"{gen_str} with {mem} GB unified memory — good for SDXL/Flux.")
|
||||
return "ok", "apple-silicon", notes
|
||||
|
||||
if gpu["vendor"] == "intel":
|
||||
notes.append("Intel Arc detected — ComfyUI IPEX support is experimental; Comfy Cloud is more reliable.")
|
||||
return "marginal", "intel", notes
|
||||
|
||||
# Discrete NVIDIA / AMD
|
||||
vram = gpu.get("vram_gb", 0.0)
|
||||
name = gpu["name"]
|
||||
if vram < MIN_VRAM_GB_USABLE:
|
||||
notes.append(
|
||||
f"{name} has only {vram} GB VRAM — below the {MIN_VRAM_GB_USABLE} GB practical minimum."
|
||||
)
|
||||
notes.append("Most modern models won't load. Recommend Comfy Cloud.")
|
||||
return "cloud", "comfy-cloud", notes
|
||||
if vram < OK_VRAM_GB:
|
||||
notes.append(
|
||||
f"{name} ({vram} GB VRAM) — SD1.5 works, SDXL tight, Flux/video unlikely."
|
||||
)
|
||||
return "marginal", gpu["vendor"], notes
|
||||
if vram < GREAT_VRAM_GB:
|
||||
notes.append(f"{name} ({vram} GB VRAM) — SDXL comfortable, Flux possible with optimizations.")
|
||||
return "ok", gpu["vendor"], notes
|
||||
notes.append(f"{name} ({vram} GB VRAM) — can run everything including Flux/video.")
|
||||
return "ok", gpu["vendor"], notes
|
||||
|
||||
|
||||
def build_report(*, check_pytorch: bool = False) -> dict:
|
||||
sysname = platform.system()
|
||||
arch = platform.machine()
|
||||
ram_gb = total_system_ram_gb()
|
||||
free_disk_gb = total_free_disk_gb(os.path.expanduser("~"))
|
||||
|
||||
rosetta = is_rosetta()
|
||||
wsl = is_wsl()
|
||||
|
||||
gpu = (
|
||||
detect_nvidia()
|
||||
or detect_rocm()
|
||||
or detect_apple_silicon()
|
||||
or detect_intel_arc()
|
||||
)
|
||||
|
||||
# Intel Mac: arm64 detect failed AND no other GPU paths
|
||||
if gpu is None and sysname == "Darwin" and arch != "arm64" and not rosetta:
|
||||
notes = [
|
||||
"Intel Mac detected — no MPS backend available.",
|
||||
"ComfyUI will fall back to CPU which is unusably slow. Use Comfy Cloud.",
|
||||
]
|
||||
report = {
|
||||
"os": sysname,
|
||||
"arch": arch,
|
||||
"system_ram_gb": ram_gb,
|
||||
"free_disk_gb": free_disk_gb,
|
||||
"wsl": False,
|
||||
"rosetta": False,
|
||||
"gpu": None,
|
||||
"verdict": "cloud",
|
||||
"recommended_install_path": "comfy-cloud",
|
||||
"comfy_cli_flag": None,
|
||||
"notes": notes,
|
||||
"install_urls": _install_urls(),
|
||||
}
|
||||
if check_pytorch:
|
||||
report["pytorch"] = check_pytorch_cuda()
|
||||
return report
|
||||
|
||||
verdict, install_path, notes = classify(
|
||||
gpu, ram_gb, free_disk_gb, wsl=wsl, rosetta=rosetta,
|
||||
)
|
||||
|
||||
report = {
|
||||
"os": sysname,
|
||||
"arch": arch,
|
||||
"system_ram_gb": ram_gb,
|
||||
"free_disk_gb": free_disk_gb,
|
||||
"wsl": wsl,
|
||||
"rosetta": rosetta,
|
||||
"gpu": gpu,
|
||||
"verdict": verdict,
|
||||
"recommended_install_path": install_path,
|
||||
"comfy_cli_flag": _COMFY_CLI_FLAG.get(install_path),
|
||||
"notes": notes,
|
||||
"install_urls": _install_urls(),
|
||||
}
|
||||
if check_pytorch:
|
||||
report["pytorch"] = check_pytorch_cuda()
|
||||
return report
|
||||
|
||||
|
||||
def _install_urls() -> dict:
|
||||
return {
|
||||
"desktop": "https://docs.comfy.org/installation/desktop",
|
||||
"manual": "https://docs.comfy.org/installation/manual_install",
|
||||
"comfy_cli": "https://docs.comfy.org/comfy-cli/getting-started",
|
||||
"cloud": "https://platform.comfy.org",
|
||||
}
|
||||
|
||||
|
||||
def main(argv: list[str] | None = None) -> int:
|
||||
import argparse
|
||||
p = argparse.ArgumentParser(description="Check whether this machine can run ComfyUI locally.")
|
||||
p.add_argument("--json", action="store_true", help="Emit machine-readable JSON only")
|
||||
p.add_argument("--check-pytorch", action="store_true",
|
||||
help="Also probe `torch` for CUDA/MPS availability (slower)")
|
||||
args = p.parse_args(argv)
|
||||
|
||||
report = build_report(check_pytorch=args.check_pytorch)
|
||||
|
||||
if args.json:
|
||||
print(json.dumps(report, indent=2))
|
||||
else:
|
||||
print(f"OS: {report['os']} ({report['arch']})")
|
||||
if report.get("wsl"):
|
||||
print("Env: WSL2")
|
||||
if report.get("rosetta"):
|
||||
print("Env: Rosetta (x86_64 Python on Apple Silicon)")
|
||||
print(f"RAM: {report['system_ram_gb']} GB")
|
||||
print(f"Free disk: {report['free_disk_gb']} GB (~/)")
|
||||
if report["gpu"]:
|
||||
g = report["gpu"]
|
||||
if g["vendor"] == "apple":
|
||||
print(f"GPU: {g['name']} — {g.get('unified_memory_gb', 0)} GB unified memory")
|
||||
else:
|
||||
print(f"GPU: {g['name']} — {g.get('vram_gb', 0)} GB VRAM")
|
||||
if g.get("all_gpus") and len(g["all_gpus"]) > 1:
|
||||
print(f" ({len(g['all_gpus'])} GPUs total; using best by VRAM)")
|
||||
else:
|
||||
print("GPU: (none detected)")
|
||||
print(f"Verdict: {report['verdict']} → {report['recommended_install_path']}")
|
||||
if report["comfy_cli_flag"]:
|
||||
print(f" run: comfy --skip-prompt install {report['comfy_cli_flag']}")
|
||||
if report.get("pytorch"):
|
||||
pt = report["pytorch"]
|
||||
if pt.get("available"):
|
||||
line = f"PyTorch: {pt.get('torch_version')}"
|
||||
if pt.get("cuda_available"):
|
||||
line += f" + CUDA ({pt.get('cuda_device_0', '?')})"
|
||||
if pt.get("mps_available"):
|
||||
line += " + MPS"
|
||||
print(line)
|
||||
else:
|
||||
print(f"PyTorch: not available — {pt.get('reason')}")
|
||||
for n in report["notes"]:
|
||||
print(f" • {n}")
|
||||
|
||||
if report["verdict"] == "ok":
|
||||
return 0
|
||||
if report["verdict"] == "marginal":
|
||||
return 1
|
||||
return 2
|
||||
|
||||
|
||||
if __name__ == "__main__":
|
||||
sys.exit(main())
|
||||
+223
@@ -0,0 +1,223 @@
|
||||
#!/usr/bin/env python3
|
||||
"""
|
||||
health_check.py — One-stop verification that the ComfyUI environment is ready.
|
||||
|
||||
Runs through the verification checklist:
|
||||
1. comfy-cli on PATH
|
||||
2. server reachable (/system_stats)
|
||||
3. at least one checkpoint installed
|
||||
4. (optional) a specific workflow's deps are met
|
||||
5. (optional) actually submit a tiny test workflow and verify round-trip
|
||||
|
||||
Usage:
|
||||
python3 health_check.py
|
||||
python3 health_check.py --host https://cloud.comfy.org
|
||||
python3 health_check.py --workflow my.json
|
||||
python3 health_check.py --smoke-test # actually submit a tiny workflow
|
||||
"""
|
||||
|
||||
from __future__ import annotations
|
||||
|
||||
import argparse
|
||||
import json
|
||||
import shutil
|
||||
import sys
|
||||
from pathlib import Path
|
||||
|
||||
sys.path.insert(0, str(Path(__file__).resolve().parent))
|
||||
from _common import ( # noqa: E402
|
||||
DEFAULT_LOCAL_HOST, ENV_API_KEY, emit_json, http_get, parse_model_list,
|
||||
resolve_api_key, resolve_url, unwrap_workflow,
|
||||
)
|
||||
|
||||
|
||||
def comfy_cli_status() -> dict:
|
||||
if shutil.which("comfy"):
|
||||
return {"available": True, "method": "comfy", "path": shutil.which("comfy")}
|
||||
if shutil.which("uvx"):
|
||||
return {"available": True, "method": "uvx",
|
||||
"hint": "Invoke as `uvx --from comfy-cli comfy ...`"}
|
||||
return {
|
||||
"available": False,
|
||||
"hint": "Install with: pipx install comfy-cli (or `pip install comfy-cli`)",
|
||||
}
|
||||
|
||||
|
||||
def server_status(host: str, headers: dict) -> dict:
|
||||
url = resolve_url(host, "/system_stats")
|
||||
try:
|
||||
r = http_get(url, headers=headers, retries=2, timeout=10)
|
||||
if r.status == 200:
|
||||
try:
|
||||
stats = r.json() or {}
|
||||
except Exception:
|
||||
stats = {}
|
||||
return {"reachable": True, "url": url, "stats": stats}
|
||||
return {"reachable": False, "url": url, "http_status": r.status, "body": r.text()[:200]}
|
||||
except Exception as e:
|
||||
return {"reachable": False, "url": url, "error": str(e)}
|
||||
|
||||
|
||||
def checkpoint_status(host: str, headers: dict) -> dict:
|
||||
url = resolve_url(host, "/models/checkpoints")
|
||||
try:
|
||||
r = http_get(url, headers=headers, retries=2, timeout=15)
|
||||
except Exception as e:
|
||||
return {"queryable": False, "error": str(e)}
|
||||
if r.status != 200:
|
||||
return {"queryable": False, "http_status": r.status, "url": url, "body": r.text()[:200]}
|
||||
try:
|
||||
models = parse_model_list(r.json())
|
||||
except Exception:
|
||||
models = set()
|
||||
return {"queryable": True, "count": len(models),
|
||||
"first_few": sorted(models)[:5]}
|
||||
|
||||
|
||||
SMOKE_WORKFLOW = {
|
||||
# Minimal SD1.5 workflow that doesn't depend on rare nodes.
|
||||
# 256x256 + 1 step is the smallest config that doesn't trigger SDXL/Flux
|
||||
# validation errors while still executing fast.
|
||||
"3": {
|
||||
"class_type": "KSampler",
|
||||
"inputs": {
|
||||
"seed": 1, "steps": 1, "cfg": 7.0,
|
||||
"sampler_name": "euler", "scheduler": "normal", "denoise": 1.0,
|
||||
"model": ["4", 0], "positive": ["6", 0], "negative": ["7", 0],
|
||||
"latent_image": ["5", 0],
|
||||
},
|
||||
},
|
||||
"4": {"class_type": "CheckpointLoaderSimple",
|
||||
"inputs": {"ckpt_name": "REPLACE_ME"}},
|
||||
"5": {"class_type": "EmptyLatentImage",
|
||||
"inputs": {"width": 256, "height": 256, "batch_size": 1}},
|
||||
"6": {"class_type": "CLIPTextEncode",
|
||||
"inputs": {"text": "test", "clip": ["4", 1]}},
|
||||
"7": {"class_type": "CLIPTextEncode",
|
||||
"inputs": {"text": "", "clip": ["4", 1]}},
|
||||
"9": {"class_type": "SaveImage",
|
||||
"inputs": {"filename_prefix": "smoke", "images": ["3", 0]}},
|
||||
}
|
||||
|
||||
|
||||
def smoke_test(host: str, headers: dict, ckpt_name: str | None) -> dict:
|
||||
"""Submit a tiny workflow and verify the server accepts it.
|
||||
|
||||
Cancels the job immediately after acceptance so we don't burn GPU
|
||||
time / cloud minutes on a smoke test.
|
||||
"""
|
||||
if not ckpt_name:
|
||||
return {"ran": False, "reason": "no checkpoint available"}
|
||||
wf = json.loads(json.dumps(SMOKE_WORKFLOW))
|
||||
wf["4"]["inputs"]["ckpt_name"] = ckpt_name
|
||||
|
||||
# Lazy import to avoid circular issues
|
||||
from run_workflow import ComfyRunner
|
||||
api_key = headers.get("X-API-Key")
|
||||
runner = ComfyRunner(host=host, api_key=api_key)
|
||||
sub = runner.submit(wf)
|
||||
if "_http_error" in sub:
|
||||
return {"ran": True, "submitted": False,
|
||||
"http_status": sub["_http_error"], "body": sub.get("body")}
|
||||
pid = sub.get("prompt_id")
|
||||
if not pid:
|
||||
return {"ran": True, "submitted": False, "response": sub}
|
||||
|
||||
# Cancel so we don't actually waste compute on the smoke test.
|
||||
cancelled = False
|
||||
try:
|
||||
cancelled = runner.cancel(pid)
|
||||
except Exception:
|
||||
pass
|
||||
|
||||
return {
|
||||
"ran": True, "submitted": True, "prompt_id": pid,
|
||||
"cancelled_after_submit": cancelled,
|
||||
"note": "Submission accepted; cancelled to avoid running the full pipeline.",
|
||||
}
|
||||
|
||||
|
||||
def main(argv: list[str] | None = None) -> int:
|
||||
p = argparse.ArgumentParser(description="One-stop ComfyUI health check")
|
||||
p.add_argument("--host", default=DEFAULT_LOCAL_HOST)
|
||||
p.add_argument("--api-key", help=f"or set ${ENV_API_KEY}")
|
||||
p.add_argument("--workflow", help="Optional: also run check_deps on this workflow")
|
||||
p.add_argument("--smoke-test", action="store_true",
|
||||
help="Submit a tiny test workflow and verify round-trip")
|
||||
p.add_argument("--strict", action="store_true",
|
||||
help="Exit non-zero on any non-pass condition (including warnings)")
|
||||
args = p.parse_args(argv)
|
||||
|
||||
api_key = resolve_api_key(args.api_key)
|
||||
headers = {"X-API-Key": api_key} if api_key else {}
|
||||
|
||||
cli = comfy_cli_status()
|
||||
server = server_status(args.host, headers)
|
||||
ckpts = checkpoint_status(args.host, headers) if server.get("reachable") else None
|
||||
|
||||
# ---- workflow check ----
|
||||
workflow_check: dict | None = None
|
||||
if args.workflow:
|
||||
wf_path = Path(args.workflow).expanduser()
|
||||
if not wf_path.exists():
|
||||
workflow_check = {"error": "workflow file not found"}
|
||||
else:
|
||||
try:
|
||||
with wf_path.open(encoding="utf-8-sig") as f:
|
||||
workflow = unwrap_workflow(json.load(f))
|
||||
from check_deps import check_deps
|
||||
workflow_check = check_deps(workflow, host=args.host, api_key=api_key)
|
||||
except (ValueError, json.JSONDecodeError) as e:
|
||||
workflow_check = {"error": str(e)}
|
||||
|
||||
smoke = None
|
||||
if args.smoke_test and server.get("reachable"):
|
||||
first_ckpt = ckpts["first_few"][0] if ckpts and ckpts.get("first_few") else None
|
||||
smoke = smoke_test(args.host, headers, first_ckpt)
|
||||
|
||||
# ---- verdict ----
|
||||
verdict = "pass"
|
||||
reasons: list[str] = []
|
||||
if not server.get("reachable"):
|
||||
verdict = "fail"
|
||||
reasons.append("server unreachable")
|
||||
if ckpts and ckpts.get("queryable") and ckpts.get("count", 0) == 0:
|
||||
verdict = "warn" if verdict == "pass" else verdict
|
||||
reasons.append("no checkpoints installed")
|
||||
if workflow_check and workflow_check.get("error"):
|
||||
verdict = "fail"
|
||||
reasons.append(f"workflow check failed: {workflow_check['error']}")
|
||||
elif workflow_check and not workflow_check.get("is_ready"):
|
||||
if workflow_check.get("node_check_skipped"):
|
||||
reasons.append("node check skipped (cloud free tier)")
|
||||
else:
|
||||
verdict = "fail"
|
||||
reasons.append("workflow has missing deps")
|
||||
if smoke and smoke.get("ran") and not smoke.get("submitted"):
|
||||
verdict = "fail"
|
||||
reasons.append("smoke-test submission failed")
|
||||
if not cli.get("available"):
|
||||
verdict = "warn" if verdict == "pass" else verdict
|
||||
reasons.append("comfy-cli not on PATH (lifecycle commands won't work)")
|
||||
|
||||
report = {
|
||||
"verdict": verdict,
|
||||
"reasons": reasons,
|
||||
"host": args.host,
|
||||
"comfy_cli": cli,
|
||||
"server": server,
|
||||
"checkpoints": ckpts,
|
||||
"workflow_check": workflow_check,
|
||||
"smoke_test": smoke,
|
||||
}
|
||||
emit_json(report)
|
||||
|
||||
if verdict == "pass":
|
||||
return 0
|
||||
if verdict == "warn":
|
||||
return 1 if args.strict else 0
|
||||
return 1
|
||||
|
||||
|
||||
if __name__ == "__main__":
|
||||
sys.exit(main())
|
||||
+243
@@ -0,0 +1,243 @@
|
||||
#!/usr/bin/env python3
|
||||
"""
|
||||
run_batch.py — Run a workflow many times, varying parameters per run.
|
||||
|
||||
Two modes:
|
||||
1. --count N --randomize-seed
|
||||
Submit N runs, each with a fresh random seed. Use for quick variations.
|
||||
2. --sweep '{"seed": [1,2,3], "steps": [20,30]}'
|
||||
Cartesian product of values. With cloud subscription, runs in parallel
|
||||
up to your tier's concurrent-job limit.
|
||||
|
||||
Both modes write each run's outputs into output-dir/run_NNN/.
|
||||
|
||||
Examples:
|
||||
python3 run_batch.py --workflow flux_dev.json \
|
||||
--args '{"prompt": "a cat"}' \
|
||||
--count 8 --randomize-seed \
|
||||
--output-dir ./outputs/cat-batch
|
||||
|
||||
python3 run_batch.py --workflow sdxl.json \
|
||||
--args '{"prompt": "abstract"}' \
|
||||
--sweep '{"seed": [1,2,3], "steps": [20, 40]}' \
|
||||
--output-dir ./outputs/sweep
|
||||
"""
|
||||
|
||||
from __future__ import annotations
|
||||
|
||||
import argparse
|
||||
import itertools
|
||||
import json
|
||||
import sys
|
||||
from concurrent.futures import ThreadPoolExecutor, as_completed
|
||||
from pathlib import Path
|
||||
|
||||
sys.path.insert(0, str(Path(__file__).resolve().parent))
|
||||
from _common import ( # noqa: E402
|
||||
DEFAULT_LOCAL_HOST, ENV_API_KEY, coerce_seed, emit_json, log,
|
||||
looks_like_video_workflow, resolve_api_key, unwrap_workflow,
|
||||
)
|
||||
from run_workflow import ( # noqa: E402
|
||||
ComfyRunner, download_outputs, inject_params,
|
||||
)
|
||||
from extract_schema import extract_schema # noqa: E402
|
||||
|
||||
|
||||
def expand_sweep(sweep: dict, base_args: dict, count: int, randomize_seed: bool) -> list[dict]:
|
||||
"""Generate a list of args dicts for each run."""
|
||||
if sweep:
|
||||
# Cartesian product
|
||||
keys = list(sweep.keys())
|
||||
values = [sweep[k] if isinstance(sweep[k], list) else [sweep[k]] for k in keys]
|
||||
runs = []
|
||||
for combo in itertools.product(*values):
|
||||
ar = dict(base_args)
|
||||
for k, v in zip(keys, combo):
|
||||
ar[k] = v
|
||||
runs.append(ar)
|
||||
return runs
|
||||
# Count mode
|
||||
runs = []
|
||||
for _ in range(count):
|
||||
ar = dict(base_args)
|
||||
if randomize_seed:
|
||||
ar["seed"] = coerce_seed(None)
|
||||
runs.append(ar)
|
||||
return runs
|
||||
|
||||
|
||||
def execute_one(
|
||||
runner: ComfyRunner, workflow: dict, schema: dict, args: dict,
|
||||
*, output_dir: Path, timeout: int, ws: bool,
|
||||
) -> dict:
|
||||
wf, warnings = inject_params(workflow, schema, args)
|
||||
sub = runner.submit(wf)
|
||||
if "_http_error" in sub:
|
||||
return {"status": "error", "error": "submission HTTP error",
|
||||
"details": sub.get("body"), "args": args}
|
||||
pid = sub.get("prompt_id")
|
||||
if not pid:
|
||||
return {"status": "error", "error": "no prompt_id", "response": sub, "args": args}
|
||||
if sub.get("node_errors"):
|
||||
return {"status": "error", "error": "validation failed",
|
||||
"node_errors": sub["node_errors"], "args": args}
|
||||
|
||||
if ws:
|
||||
result = runner.monitor_ws(pid, timeout=timeout)
|
||||
else:
|
||||
result = runner.poll_status(pid, timeout=timeout)
|
||||
|
||||
if result["status"] != "success":
|
||||
return {
|
||||
"status": result["status"],
|
||||
"prompt_id": pid,
|
||||
"details": result.get("data"),
|
||||
"args": args,
|
||||
}
|
||||
|
||||
outputs = result.get("outputs") or runner.get_outputs(pid)
|
||||
downloaded = download_outputs(runner, outputs, output_dir, preserve_subfolder=False)
|
||||
return {
|
||||
"status": "success",
|
||||
"prompt_id": pid,
|
||||
"args": args,
|
||||
"outputs": downloaded,
|
||||
"warnings": warnings,
|
||||
}
|
||||
|
||||
|
||||
def main(argv: list[str] | None = None) -> int:
|
||||
p = argparse.ArgumentParser(
|
||||
description="Submit a workflow many times with varying parameters.",
|
||||
)
|
||||
p.add_argument("--workflow", required=True)
|
||||
p.add_argument("--args", default="{}", help="Base parameters JSON")
|
||||
p.add_argument("--count", type=int, default=0,
|
||||
help="Number of runs (use with --randomize-seed)")
|
||||
p.add_argument("--sweep", default="",
|
||||
help='JSON dict of param→list of values. Cartesian product. '
|
||||
'e.g. \'{"seed":[1,2,3],"cfg":[5,8]}\'')
|
||||
p.add_argument("--randomize-seed", action="store_true",
|
||||
help="In --count mode, vary seed per run")
|
||||
p.add_argument("--host", default=DEFAULT_LOCAL_HOST)
|
||||
p.add_argument("--api-key", help=f"or set ${ENV_API_KEY}")
|
||||
p.add_argument("--partner-key")
|
||||
p.add_argument("--parallel", type=int, default=1,
|
||||
help="Concurrent submissions (cloud: up to your tier limit). "
|
||||
"Default 1 (sequential)")
|
||||
p.add_argument("--output-dir", default="./outputs/batch")
|
||||
p.add_argument("--timeout", type=int, default=0)
|
||||
p.add_argument("--ws", action="store_true")
|
||||
p.add_argument("--continue-on-error", action="store_true",
|
||||
help="Don't stop the batch when a run fails")
|
||||
args = p.parse_args(argv)
|
||||
|
||||
if args.count <= 0 and not args.sweep:
|
||||
emit_json({"error": "Specify --count N or --sweep '{...}'"})
|
||||
return 1
|
||||
|
||||
base_args = json.loads(args.args) if args.args.strip() else {}
|
||||
sweep = json.loads(args.sweep) if args.sweep.strip() else {}
|
||||
|
||||
# Validate sweep shape
|
||||
if sweep:
|
||||
if not isinstance(sweep, dict):
|
||||
emit_json({"error": "--sweep must be a JSON object {param: [values]}"})
|
||||
return 1
|
||||
empty = [k for k, v in sweep.items() if isinstance(v, list) and len(v) == 0]
|
||||
if empty:
|
||||
emit_json({"error": f"--sweep parameters have empty value lists: {empty}"})
|
||||
return 1
|
||||
# If user passed BOTH --sweep and --count/--randomize-seed, --sweep wins
|
||||
if args.count or args.randomize_seed:
|
||||
log("--sweep set; ignoring --count / --randomize-seed (sweep defines the runs)")
|
||||
|
||||
wf_path = Path(args.workflow).expanduser()
|
||||
if not wf_path.exists():
|
||||
emit_json({"error": f"Workflow not found: {args.workflow}"})
|
||||
return 1
|
||||
try:
|
||||
with wf_path.open(encoding="utf-8-sig") as f:
|
||||
workflow = unwrap_workflow(json.load(f))
|
||||
except (ValueError, json.JSONDecodeError) as e:
|
||||
emit_json({"error": str(e)})
|
||||
return 1
|
||||
|
||||
schema = extract_schema(workflow)
|
||||
runs = expand_sweep(sweep, base_args, args.count, args.randomize_seed)
|
||||
log(f"Planned {len(runs)} run(s)")
|
||||
|
||||
api_key = resolve_api_key(args.api_key)
|
||||
runner = ComfyRunner(host=args.host, api_key=api_key, partner_key=args.partner_key)
|
||||
|
||||
ok, info = runner.check_server()
|
||||
if not ok:
|
||||
emit_json({"error": "Cannot reach server", "details": info, "host": args.host})
|
||||
return 1
|
||||
|
||||
timeout = args.timeout
|
||||
if timeout <= 0:
|
||||
timeout = 900 if looks_like_video_workflow(workflow) else 300
|
||||
|
||||
base_dir = Path(args.output_dir).expanduser()
|
||||
base_dir.mkdir(parents=True, exist_ok=True)
|
||||
|
||||
results: list[dict] = []
|
||||
failures = 0
|
||||
|
||||
if args.parallel > 1:
|
||||
with ThreadPoolExecutor(max_workers=args.parallel) as ex:
|
||||
future_to_idx = {}
|
||||
for i, ar in enumerate(runs):
|
||||
run_dir = base_dir / f"run_{i:04d}"
|
||||
fut = ex.submit(
|
||||
execute_one, runner, workflow, schema, ar,
|
||||
output_dir=run_dir, timeout=timeout, ws=args.ws,
|
||||
)
|
||||
future_to_idx[fut] = i
|
||||
for fut in as_completed(future_to_idx):
|
||||
i = future_to_idx[fut]
|
||||
try:
|
||||
r = fut.result()
|
||||
except Exception as e:
|
||||
r = {"status": "error", "error": str(e), "args": runs[i]}
|
||||
r["index"] = i
|
||||
results.append(r)
|
||||
if r["status"] != "success":
|
||||
failures += 1
|
||||
log(f" run {i} → {r['status']}: {r.get('error','?')}")
|
||||
if not args.continue_on_error:
|
||||
log(" --continue-on-error not set; aborting batch")
|
||||
break
|
||||
else:
|
||||
log(f" run {i} → success: {len(r.get('outputs', []))} files")
|
||||
else:
|
||||
for i, ar in enumerate(runs):
|
||||
run_dir = base_dir / f"run_{i:04d}"
|
||||
r = execute_one(runner, workflow, schema, ar,
|
||||
output_dir=run_dir, timeout=timeout, ws=args.ws)
|
||||
r["index"] = i
|
||||
results.append(r)
|
||||
if r["status"] != "success":
|
||||
failures += 1
|
||||
log(f" run {i} → {r['status']}: {r.get('error','?')}")
|
||||
if not args.continue_on_error:
|
||||
log(" --continue-on-error not set; aborting batch")
|
||||
break
|
||||
else:
|
||||
log(f" run {i} → success: {len(r.get('outputs', []))} files")
|
||||
|
||||
results.sort(key=lambda x: x.get("index", 0))
|
||||
emit_json({
|
||||
"status": "success" if failures == 0 else "partial",
|
||||
"total": len(runs),
|
||||
"completed": sum(1 for r in results if r["status"] == "success"),
|
||||
"failed": failures,
|
||||
"output_dir": str(base_dir),
|
||||
"results": results,
|
||||
})
|
||||
return 0 if failures == 0 else 1
|
||||
|
||||
|
||||
if __name__ == "__main__":
|
||||
sys.exit(main())
|
||||
+796
@@ -0,0 +1,796 @@
|
||||
#!/usr/bin/env python3
|
||||
"""
|
||||
run_workflow.py — Inject parameters into a ComfyUI workflow, submit it, monitor
|
||||
execution, and download outputs.
|
||||
|
||||
Improvements over v1:
|
||||
- Cloud-aware URL routing (handles /api prefix and /history_v2 / /experiment/models renames)
|
||||
- API key from CLI flag OR $COMFY_CLOUD_API_KEY env var
|
||||
- WebSocket progress monitoring (--ws), with HTTP polling fallback
|
||||
- Streaming download (no whole-file buffering — handles GB-size video outputs)
|
||||
- Path-traversal-safe output writes
|
||||
- Subfolder-aware download paths (no silent overwrites)
|
||||
- Retry with exponential backoff on transient errors
|
||||
- Status-error correctly classified before "completed: true"
|
||||
- Image upload helper (--input-image NAME=PATH)
|
||||
- Auto-randomize seed when value is -1 or omitted on a randomize-seed flag
|
||||
- Auto-extends timeout heuristically for video workflows
|
||||
- Editor-format detection with helpful error
|
||||
- Doesn't pollute extra_data.api_key_comfy_org with the cloud auth key
|
||||
unless --partner-key is provided (correct semantic per cloud docs)
|
||||
|
||||
Usage:
|
||||
# Local server
|
||||
python3 run_workflow.py --workflow workflow_api.json \
|
||||
--args '{"prompt": "a cat", "seed": 42}' \
|
||||
--output-dir ./outputs
|
||||
|
||||
# Cloud server (API key from env var)
|
||||
export COMFY_CLOUD_API_KEY="comfyui-xxxxxxx"
|
||||
python3 run_workflow.py --workflow workflow_api.json \
|
||||
--args '{"prompt": "a cat"}' \
|
||||
--host https://cloud.comfy.org \
|
||||
--output-dir ./outputs
|
||||
|
||||
# With image input (auto-uploads, then references)
|
||||
python3 run_workflow.py --workflow img2img.json \
|
||||
--input-image image=./photo.png \
|
||||
--args '{"prompt": "make it cyberpunk"}'
|
||||
|
||||
# WebSocket real-time progress
|
||||
python3 run_workflow.py --workflow flux_dev.json \
|
||||
--args '{"prompt": "..."}' \
|
||||
--ws
|
||||
|
||||
Stdlib-only by default (Python 3.10+). Will use `requests`/`websocket-client`
|
||||
if installed for nicer behavior.
|
||||
"""
|
||||
|
||||
from __future__ import annotations
|
||||
|
||||
import argparse
|
||||
import copy
|
||||
import json
|
||||
import sys
|
||||
import time
|
||||
from pathlib import Path
|
||||
from typing import Any
|
||||
from urllib.parse import urlencode, urlparse
|
||||
|
||||
# Local import — _common.py sits next to this script.
|
||||
sys.path.insert(0, str(Path(__file__).resolve().parent))
|
||||
from _common import ( # noqa: E402
|
||||
DEFAULT_LOCAL_HOST, ENV_API_KEY,
|
||||
coerce_seed, emit_json, http_get, http_post, http_request,
|
||||
is_cloud_host, is_link, log, looks_like_video_workflow,
|
||||
media_type_from_filename, new_client_id, resolve_api_key, resolve_url,
|
||||
safe_path_join, unwrap_workflow,
|
||||
)
|
||||
|
||||
|
||||
# =============================================================================
|
||||
# Runner
|
||||
# =============================================================================
|
||||
|
||||
class WorkflowRunError(Exception):
|
||||
"""Raised when a workflow run fails (validation, execution, timeout)."""
|
||||
|
||||
def __init__(self, status: str, message: str, **details: Any):
|
||||
super().__init__(message)
|
||||
self.status = status
|
||||
self.message = message
|
||||
self.details = details
|
||||
|
||||
def to_dict(self) -> dict:
|
||||
d = {"status": self.status, "error": self.message}
|
||||
d.update(self.details)
|
||||
return d
|
||||
|
||||
|
||||
class ComfyRunner:
|
||||
def __init__(
|
||||
self,
|
||||
host: str = DEFAULT_LOCAL_HOST,
|
||||
api_key: str | None = None,
|
||||
client_id: str | None = None,
|
||||
partner_key: str | None = None,
|
||||
):
|
||||
self.host = host.rstrip("/")
|
||||
self.api_key = api_key
|
||||
self.partner_key = partner_key
|
||||
self.is_cloud = is_cloud_host(self.host)
|
||||
self.client_id = client_id or new_client_id()
|
||||
|
||||
@property
|
||||
def headers(self) -> dict[str, str]:
|
||||
h: dict[str, str] = {}
|
||||
if self.api_key:
|
||||
h["X-API-Key"] = self.api_key
|
||||
return h
|
||||
|
||||
def _url(self, path: str) -> str:
|
||||
return resolve_url(self.host, path, is_cloud=self.is_cloud)
|
||||
|
||||
# ---------- server health ----------
|
||||
def check_server(self) -> tuple[bool, dict | None]:
|
||||
try:
|
||||
r = http_get(self._url("/system_stats"), headers=self.headers, retries=2)
|
||||
if r.status == 200:
|
||||
try:
|
||||
return True, r.json()
|
||||
except Exception:
|
||||
return True, None
|
||||
return False, {"http_status": r.status, "body": r.text()[:500]}
|
||||
except Exception as e:
|
||||
return False, {"error": str(e)}
|
||||
|
||||
# ---------- upload ----------
|
||||
def upload_image(self, path: Path, *, image_type: str = "input", overwrite: bool = True,
|
||||
endpoint: str = "/upload/image", extra_form: dict | None = None) -> dict:
|
||||
"""Upload an image file via multipart. Returns server-side ref dict."""
|
||||
if not path.exists():
|
||||
raise FileNotFoundError(f"input image not found: {path}")
|
||||
# Stream the file via a handle to avoid OOM on huge inputs (16MP+ photos).
|
||||
with path.open("rb") as fh:
|
||||
files = {"image": (path.name, fh)}
|
||||
form = {"type": image_type}
|
||||
if overwrite:
|
||||
form["overwrite"] = "true"
|
||||
if extra_form:
|
||||
form.update({k: str(v) for k, v in extra_form.items()})
|
||||
r = http_request(
|
||||
"POST", self._url(endpoint),
|
||||
headers=self.headers, files=files, form=form,
|
||||
timeout=300, retries=2,
|
||||
)
|
||||
if r.status != 200:
|
||||
raise WorkflowRunError(
|
||||
"upload_failed",
|
||||
f"Upload of {path.name} failed: HTTP {r.status}",
|
||||
body=r.text()[:500],
|
||||
)
|
||||
try:
|
||||
return r.json()
|
||||
except Exception:
|
||||
return {"name": path.name}
|
||||
|
||||
def upload_mask(self, path: Path, original_ref: dict) -> dict:
|
||||
"""Upload an inpaint mask, linked to a previously uploaded source image.
|
||||
|
||||
`original_ref` should be the dict returned by `upload_image()` for the
|
||||
source image (or `{"filename": ..., "subfolder": ..., "type": "input"}`).
|
||||
"""
|
||||
return self.upload_image(
|
||||
path,
|
||||
endpoint="/upload/mask",
|
||||
extra_form={
|
||||
"subfolder": "clipspace",
|
||||
"original_ref": json.dumps(original_ref),
|
||||
},
|
||||
)
|
||||
|
||||
# ---------- submit ----------
|
||||
def submit(self, workflow: dict) -> dict:
|
||||
payload: dict[str, Any] = {"prompt": workflow, "client_id": self.client_id}
|
||||
if self.partner_key:
|
||||
payload["extra_data"] = {"api_key_comfy_org": self.partner_key}
|
||||
|
||||
r = http_post(self._url("/prompt"), headers=self.headers, json_body=payload, timeout=120)
|
||||
try:
|
||||
body = r.json()
|
||||
except Exception:
|
||||
body = {"raw": r.text()[:500]}
|
||||
if r.status != 200:
|
||||
return {"_http_error": r.status, "body": body}
|
||||
return body
|
||||
|
||||
# ---------- HTTP polling ----------
|
||||
def poll_status(self, prompt_id: str, *, timeout: float = 300.0,
|
||||
initial_interval: float = 1.5, max_interval: float = 8.0) -> dict:
|
||||
start = time.time()
|
||||
interval = initial_interval
|
||||
|
||||
while time.time() - start < timeout:
|
||||
if self.is_cloud:
|
||||
r = http_get(
|
||||
self._url(f"/job/{prompt_id}/status"),
|
||||
headers=self.headers, retries=2, timeout=30,
|
||||
)
|
||||
if r.status == 200:
|
||||
try:
|
||||
data = r.json()
|
||||
except Exception:
|
||||
data = {}
|
||||
s = data.get("status")
|
||||
if s == "completed":
|
||||
return {"status": "success", "data": data}
|
||||
if s in {"failed",}:
|
||||
return {"status": "error", "data": data}
|
||||
if s == "cancelled":
|
||||
return {"status": "cancelled", "data": data}
|
||||
# pending / in_progress → continue
|
||||
elif r.status == 404:
|
||||
# Cloud sometimes 404s briefly between submit and dispatcher pickup
|
||||
pass
|
||||
else:
|
||||
# transient error — retry loop covers it
|
||||
pass
|
||||
else:
|
||||
# Local: /history/{id} grows once execution completes
|
||||
r = http_get(
|
||||
self._url(f"/history/{prompt_id}"),
|
||||
headers=self.headers, retries=2, timeout=30,
|
||||
)
|
||||
if r.status == 200:
|
||||
try:
|
||||
data = r.json() or {}
|
||||
except Exception:
|
||||
data = {}
|
||||
entry = data.get(prompt_id)
|
||||
if isinstance(entry, dict):
|
||||
st = entry.get("status") or {}
|
||||
# IMPORTANT: check error first — `completed: true` can coexist with errors
|
||||
status_str = st.get("status_str")
|
||||
if status_str == "error":
|
||||
return {"status": "error", "data": entry}
|
||||
if st.get("completed", False):
|
||||
return {"status": "success", "outputs": entry.get("outputs", {})}
|
||||
# not in history yet → continue polling
|
||||
|
||||
time.sleep(interval)
|
||||
interval = min(max_interval, interval * 1.4)
|
||||
|
||||
return {"status": "timeout", "elapsed": time.time() - start}
|
||||
|
||||
# ---------- WebSocket monitoring ----------
|
||||
def monitor_ws(self, prompt_id: str, *, timeout: float = 300.0,
|
||||
on_progress: Any = None) -> dict:
|
||||
"""Connect to /ws and listen until execution_success / execution_error.
|
||||
|
||||
Falls back to HTTP polling if `websocket-client` is not installed.
|
||||
Returns same shape as poll_status.
|
||||
"""
|
||||
try:
|
||||
import websocket # type: ignore[import-not-found]
|
||||
except ImportError:
|
||||
log("websocket-client not installed; falling back to HTTP polling")
|
||||
return self.poll_status(prompt_id, timeout=timeout)
|
||||
|
||||
# Build WS URL. Preserve any base-path components the user gave us
|
||||
# (e.g. http://example.com/comfyui → ws://example.com/comfyui/ws).
|
||||
parsed = urlparse(self.host)
|
||||
scheme = "wss" if parsed.scheme == "https" else "ws"
|
||||
netloc = parsed.netloc
|
||||
base_path = parsed.path.rstrip("/")
|
||||
ws_url = f"{scheme}://{netloc}{base_path}/ws?clientId={self.client_id}"
|
||||
if self.is_cloud and self.api_key:
|
||||
ws_url += f"&token={self.api_key}"
|
||||
|
||||
outputs: dict[str, Any] = {}
|
||||
error_payload: dict[str, Any] | None = None
|
||||
success = False
|
||||
seen_executed = False
|
||||
|
||||
ws = websocket.create_connection(ws_url, timeout=timeout)
|
||||
try:
|
||||
ws.settimeout(timeout)
|
||||
deadline = time.time() + timeout
|
||||
while time.time() < deadline:
|
||||
msg = ws.recv()
|
||||
if isinstance(msg, bytes):
|
||||
# Binary preview frame — ignore for now; ws_monitor.py prints them
|
||||
continue
|
||||
try:
|
||||
payload = json.loads(msg)
|
||||
except Exception:
|
||||
continue
|
||||
mtype = payload.get("type", "")
|
||||
mdata = payload.get("data", {}) or {}
|
||||
|
||||
# Filter to our job (cloud broadcasts; local filters via client_id)
|
||||
pid = mdata.get("prompt_id")
|
||||
if pid is not None and pid != prompt_id:
|
||||
continue
|
||||
|
||||
if mtype == "progress":
|
||||
if callable(on_progress):
|
||||
on_progress({
|
||||
"type": "progress",
|
||||
"value": mdata.get("value"),
|
||||
"max": mdata.get("max"),
|
||||
"node": mdata.get("node"),
|
||||
})
|
||||
elif mtype == "progress_state":
|
||||
if callable(on_progress):
|
||||
on_progress({"type": "progress_state", "nodes": mdata.get("nodes", {})})
|
||||
elif mtype == "executing":
|
||||
node = mdata.get("node")
|
||||
if callable(on_progress):
|
||||
on_progress({"type": "executing", "node": node})
|
||||
# When `node` is None on a local server, that signals end-of-run
|
||||
if node is None and not self.is_cloud and seen_executed:
|
||||
success = True
|
||||
break
|
||||
elif mtype == "executed":
|
||||
seen_executed = True
|
||||
nid = mdata.get("node")
|
||||
out = mdata.get("output") or {}
|
||||
if nid:
|
||||
outputs[nid] = out
|
||||
elif mtype == "notification":
|
||||
if callable(on_progress):
|
||||
on_progress({"type": "notification", "message": mdata.get("value", "")})
|
||||
elif mtype == "execution_success":
|
||||
success = True
|
||||
break
|
||||
elif mtype == "execution_error":
|
||||
error_payload = mdata
|
||||
break
|
||||
elif mtype == "execution_interrupted":
|
||||
error_payload = {"interrupted": True, **mdata}
|
||||
break
|
||||
finally:
|
||||
try:
|
||||
ws.close()
|
||||
except Exception:
|
||||
pass
|
||||
|
||||
if error_payload is not None:
|
||||
return {"status": "error", "data": error_payload}
|
||||
if success:
|
||||
return {"status": "success", "outputs": outputs}
|
||||
return {"status": "timeout", "elapsed": timeout}
|
||||
|
||||
# ---------- outputs ----------
|
||||
def get_outputs(self, prompt_id: str) -> dict:
|
||||
if self.is_cloud:
|
||||
# Try /jobs/{id} first (returns full job with outputs); fall back to /history_v2
|
||||
r = http_get(self._url(f"/jobs/{prompt_id}"), headers=self.headers, retries=2)
|
||||
if r.status == 200:
|
||||
try:
|
||||
return (r.json() or {}).get("outputs", {}) or {}
|
||||
except Exception:
|
||||
pass
|
||||
# Fallback
|
||||
r = http_get(self._url(f"/history/{prompt_id}"), headers=self.headers, retries=2)
|
||||
if r.status == 200:
|
||||
try:
|
||||
body = r.json() or {}
|
||||
except Exception:
|
||||
body = {}
|
||||
if isinstance(body, dict) and prompt_id in body:
|
||||
return body[prompt_id].get("outputs", {}) or {}
|
||||
if isinstance(body, dict) and "outputs" in body:
|
||||
return body["outputs"] or {}
|
||||
return {}
|
||||
# Local
|
||||
r = http_get(self._url(f"/history/{prompt_id}"), headers=self.headers, retries=2)
|
||||
if r.status != 200:
|
||||
return {}
|
||||
try:
|
||||
body = r.json() or {}
|
||||
except Exception:
|
||||
return {}
|
||||
entry = body.get(prompt_id) or {}
|
||||
return entry.get("outputs", {}) or {}
|
||||
|
||||
def download_output(
|
||||
self, *, filename: str, subfolder: str, file_type: str,
|
||||
output_dir: Path, preserve_subfolder: bool = True, overwrite: bool = False,
|
||||
) -> Path:
|
||||
"""Stream a single output to disk. Path-traversal-safe."""
|
||||
params = {"filename": filename, "subfolder": subfolder, "type": file_type}
|
||||
url = self._url("/view") + "?" + urlencode(params)
|
||||
|
||||
# Compute target path safely. If preserve_subfolder, include subfolder in the
|
||||
# local path; otherwise put the file in output_dir flat.
|
||||
target_parts: list[str] = []
|
||||
if preserve_subfolder and subfolder:
|
||||
target_parts.extend(p for p in subfolder.split("/") if p and p not in {".", ".."})
|
||||
target_parts.append(filename)
|
||||
out_path = safe_path_join(output_dir, *target_parts)
|
||||
|
||||
if out_path.exists() and not overwrite:
|
||||
stem, suffix = out_path.stem, out_path.suffix
|
||||
i = 1
|
||||
while True:
|
||||
candidate = out_path.with_name(f"{stem}_{i}{suffix}")
|
||||
if not candidate.exists():
|
||||
out_path = candidate
|
||||
break
|
||||
i += 1
|
||||
|
||||
out_path.parent.mkdir(parents=True, exist_ok=True)
|
||||
|
||||
# Stream download. Two-step for cloud: get the 302, then fetch signed URL
|
||||
# so we don't accidentally send X-API-Key to the storage backend.
|
||||
# The HTTP transport already strips X-API-Key on cross-host redirect
|
||||
# via _strip_api_key_on_redirect, so a single follow_redirects=True call
|
||||
# is safe AND simpler.
|
||||
r = http_request(
|
||||
"GET", url, headers=self.headers,
|
||||
timeout=600, retries=3, follow_redirects=True,
|
||||
stream=True, sink=out_path,
|
||||
)
|
||||
if r.status != 200:
|
||||
try:
|
||||
if out_path.exists():
|
||||
out_path.unlink()
|
||||
except Exception:
|
||||
pass
|
||||
raise WorkflowRunError(
|
||||
"download_failed",
|
||||
f"Download of {filename} failed: HTTP {r.status}",
|
||||
url=url,
|
||||
)
|
||||
return out_path
|
||||
|
||||
# ---------- queue / cancel ----------
|
||||
def cancel(self, prompt_id: str | None = None) -> bool:
|
||||
if prompt_id:
|
||||
r = http_post(
|
||||
self._url("/queue"), headers=self.headers,
|
||||
json_body={"delete": [prompt_id]}, retries=1,
|
||||
)
|
||||
return r.status == 200
|
||||
# Interrupt currently running
|
||||
r = http_post(self._url("/interrupt"), headers=self.headers, retries=1)
|
||||
return r.status == 200
|
||||
|
||||
|
||||
# =============================================================================
|
||||
# Schema / parameter injection
|
||||
# =============================================================================
|
||||
|
||||
def _inline_schema(workflow: dict) -> dict:
|
||||
"""Generate schema using the sibling extract_schema module."""
|
||||
from extract_schema import extract_schema # noqa: WPS433
|
||||
return extract_schema(workflow)
|
||||
|
||||
|
||||
def load_schema(schema_path: str | None, workflow: dict) -> dict:
|
||||
if schema_path:
|
||||
with open(schema_path, encoding="utf-8-sig") as f:
|
||||
return json.load(f)
|
||||
return _inline_schema(workflow)
|
||||
|
||||
|
||||
def inject_params(
|
||||
workflow: dict, schema: dict, args: dict,
|
||||
*, randomize_seed_if_unset: bool = False,
|
||||
) -> tuple[dict, list[str]]:
|
||||
"""Inject user args into the workflow. Returns (new_workflow, warnings)."""
|
||||
wf = copy.deepcopy(workflow)
|
||||
params = schema.get("parameters", {}) or {}
|
||||
warnings: list[str] = []
|
||||
|
||||
# Auto-randomize seed when it's -1 in args, or when randomize_seed_if_unset
|
||||
# and user didn't pass a seed.
|
||||
if "seed" in params:
|
||||
if "seed" in args and args["seed"] in {None, -1, "-1"}:
|
||||
args = dict(args)
|
||||
args["seed"] = coerce_seed(args["seed"])
|
||||
warnings.append(f"seed=-1 expanded to {args['seed']}")
|
||||
elif randomize_seed_if_unset and "seed" not in args:
|
||||
args = dict(args)
|
||||
args["seed"] = coerce_seed(None)
|
||||
warnings.append(f"seed auto-randomized to {args['seed']}")
|
||||
|
||||
for name, value in args.items():
|
||||
if name not in params:
|
||||
warnings.append(f"unknown parameter '{name}' (not in schema), skipping")
|
||||
continue
|
||||
m = params[name]
|
||||
nid, field = m["node_id"], m["field"]
|
||||
node = wf.get(nid)
|
||||
if not isinstance(node, dict) or "inputs" not in node:
|
||||
warnings.append(f"node '{nid}' for parameter '{name}' missing in workflow")
|
||||
continue
|
||||
# Refuse to overwrite a link with a literal — would silently break wiring
|
||||
cur = node["inputs"].get(field)
|
||||
if is_link(cur):
|
||||
warnings.append(
|
||||
f"parameter '{name}' targets {nid}.{field} which is currently a link; "
|
||||
f"refusing to overwrite (set the schema to point at the source node instead)"
|
||||
)
|
||||
continue
|
||||
node["inputs"][field] = value
|
||||
|
||||
return wf, warnings
|
||||
|
||||
|
||||
# =============================================================================
|
||||
# Output download helper
|
||||
# =============================================================================
|
||||
|
||||
def download_outputs(
|
||||
runner: ComfyRunner, outputs: dict, output_dir: Path,
|
||||
*, preserve_subfolder: bool = True, overwrite: bool = False,
|
||||
) -> list[dict]:
|
||||
"""Walk the outputs dict and download every file. Cloud uses `video` (singular);
|
||||
local uses `videos` (plural). We accept both."""
|
||||
output_dir.mkdir(parents=True, exist_ok=True)
|
||||
downloaded: list[dict] = []
|
||||
|
||||
OUTPUT_KEYS = ("images", "gifs", "videos", "video", "audio", "files", "models", "3d")
|
||||
|
||||
for node_id, node_output in (outputs or {}).items():
|
||||
if not isinstance(node_output, dict):
|
||||
continue
|
||||
for key in OUTPUT_KEYS:
|
||||
entries = node_output.get(key)
|
||||
if not entries:
|
||||
continue
|
||||
if not isinstance(entries, list):
|
||||
entries = [entries]
|
||||
for fi in entries:
|
||||
if not isinstance(fi, dict):
|
||||
continue
|
||||
filename = fi.get("filename") or ""
|
||||
if not filename:
|
||||
continue
|
||||
subfolder = fi.get("subfolder") or ""
|
||||
file_type = fi.get("type") or "output"
|
||||
try:
|
||||
out_path = runner.download_output(
|
||||
filename=filename, subfolder=subfolder, file_type=file_type,
|
||||
output_dir=output_dir, preserve_subfolder=preserve_subfolder,
|
||||
overwrite=overwrite,
|
||||
)
|
||||
downloaded.append({
|
||||
"file": str(out_path),
|
||||
"node_id": node_id,
|
||||
"type": media_type_from_filename(filename),
|
||||
"filename": filename,
|
||||
"subfolder": subfolder,
|
||||
"source_type": file_type,
|
||||
})
|
||||
except Exception as e:
|
||||
log(f"WARN: failed to download {filename}: {e}")
|
||||
return downloaded
|
||||
|
||||
|
||||
# =============================================================================
|
||||
# CLI
|
||||
# =============================================================================
|
||||
|
||||
def parse_input_image_arg(spec: str) -> tuple[str, Path]:
|
||||
"""Parse `name=path` (or `path` alone, defaulting to name='image')."""
|
||||
if "=" in spec:
|
||||
name, path = spec.split("=", 1)
|
||||
return name.strip(), Path(path).expanduser()
|
||||
return "image", Path(spec).expanduser()
|
||||
|
||||
|
||||
def main(argv: list[str] | None = None) -> int:
|
||||
p = argparse.ArgumentParser(
|
||||
description="Run a ComfyUI workflow with parameter injection.",
|
||||
formatter_class=argparse.RawDescriptionHelpFormatter,
|
||||
)
|
||||
p.add_argument("--workflow", required=True, help="Path to workflow API JSON file")
|
||||
p.add_argument("--args", default="{}",
|
||||
help="JSON parameters to inject (or `@/path/to/args.json`)")
|
||||
p.add_argument("--schema", help="Path to schema JSON (auto-generated if omitted)")
|
||||
p.add_argument("--host", default=DEFAULT_LOCAL_HOST, help="ComfyUI server URL")
|
||||
p.add_argument("--api-key",
|
||||
help=f"API key for cloud (or set ${ENV_API_KEY} env var)")
|
||||
p.add_argument("--partner-key",
|
||||
help="Partner-node API key (extra_data.api_key_comfy_org). "
|
||||
"Required for Flux Pro / Ideogram / etc. Defaults to --api-key if not set.")
|
||||
p.add_argument("--output-dir", default="./outputs", help="Directory to save outputs")
|
||||
p.add_argument("--timeout", type=int, default=0,
|
||||
help="Max seconds to wait (0=auto: 300 / 900 for video workflows)")
|
||||
p.add_argument("--input-image", action="append", default=[],
|
||||
help="Upload local image before running. Format: `name=path` or `path`. "
|
||||
"The `name` becomes the value injected into the matching schema parameter.")
|
||||
p.add_argument("--randomize-seed", action="store_true",
|
||||
help="If schema has a 'seed' parameter and --args didn't set one, randomize it")
|
||||
p.add_argument("--ws", action="store_true",
|
||||
help="Use WebSocket for real-time progress (requires `websocket-client`)")
|
||||
p.add_argument("--no-download", action="store_true", help="Skip downloading outputs")
|
||||
p.add_argument("--flat-output", action="store_true",
|
||||
help="Don't preserve server-side subfolder structure when saving outputs")
|
||||
p.add_argument("--overwrite", action="store_true",
|
||||
help="Overwrite existing files instead of appending _1, _2, ...")
|
||||
p.add_argument("--submit-only", action="store_true",
|
||||
help="Submit and return prompt_id without waiting")
|
||||
p.add_argument("--client-id", help="Override generated client_id (UUID)")
|
||||
p.add_argument("--use-partner-key-as-auth", action="store_true",
|
||||
help="(Compat) Use --partner-key value as cloud X-API-Key. Don't use unless you know why.")
|
||||
|
||||
args = p.parse_args(argv)
|
||||
|
||||
# ---- Load workflow ----
|
||||
wf_path = Path(args.workflow).expanduser()
|
||||
if not wf_path.exists():
|
||||
emit_json({"error": f"Workflow file not found: {args.workflow}"})
|
||||
return 1
|
||||
try:
|
||||
with wf_path.open(encoding="utf-8-sig") as f:
|
||||
workflow_raw = json.load(f)
|
||||
workflow = unwrap_workflow(workflow_raw)
|
||||
except ValueError as e:
|
||||
emit_json({"error": str(e)})
|
||||
return 1
|
||||
except json.JSONDecodeError as e:
|
||||
emit_json({"error": f"Invalid JSON in workflow file: {e}"})
|
||||
return 1
|
||||
|
||||
# ---- Parse user args ----
|
||||
args_str = args.args
|
||||
if args_str.startswith("@"):
|
||||
try:
|
||||
args_str = Path(args_str[1:]).read_text(encoding="utf-8")
|
||||
except OSError as e:
|
||||
emit_json({"error": f"Cannot read args file: {e}"})
|
||||
return 1
|
||||
try:
|
||||
user_args = json.loads(args_str) if args_str.strip() else {}
|
||||
except json.JSONDecodeError as e:
|
||||
emit_json({"error": f"Invalid --args JSON: {e}"})
|
||||
return 1
|
||||
if not isinstance(user_args, dict):
|
||||
emit_json({"error": "--args must be a JSON object"})
|
||||
return 1
|
||||
|
||||
# ---- Resolve API key ----
|
||||
api_key = resolve_api_key(args.api_key)
|
||||
partner_key = args.partner_key or None
|
||||
if args.use_partner_key_as_auth and not api_key and partner_key:
|
||||
api_key = partner_key
|
||||
|
||||
# ---- Connect ----
|
||||
runner = ComfyRunner(
|
||||
host=args.host, api_key=api_key, partner_key=partner_key,
|
||||
client_id=args.client_id,
|
||||
)
|
||||
|
||||
# Server reachability
|
||||
ok, info = runner.check_server()
|
||||
if not ok:
|
||||
emit_json({
|
||||
"error": f"Cannot reach server at {args.host}",
|
||||
"details": info,
|
||||
"hint": (
|
||||
"Check `comfy launch --background` is running for local, "
|
||||
f"or set ${ENV_API_KEY} for cloud."
|
||||
),
|
||||
})
|
||||
return 1
|
||||
|
||||
# ---- Upload input images ----
|
||||
upload_warnings: list[str] = []
|
||||
for spec in args.input_image:
|
||||
try:
|
||||
param_name, path = parse_input_image_arg(spec)
|
||||
except Exception as e:
|
||||
emit_json({"error": f"Bad --input-image spec '{spec}': {e}"})
|
||||
return 1
|
||||
try:
|
||||
ref = runner.upload_image(path)
|
||||
except Exception as e:
|
||||
emit_json({"error": f"Upload failed for {path}: {e}"})
|
||||
return 1
|
||||
# Register as a user arg so inject_params consumes it through the schema
|
||||
uploaded_name = ref.get("name") or path.name
|
||||
if param_name not in user_args:
|
||||
user_args[param_name] = uploaded_name
|
||||
|
||||
# ---- Inject params ----
|
||||
schema = load_schema(args.schema, workflow)
|
||||
workflow, inj_warnings = inject_params(
|
||||
workflow, schema, user_args, randomize_seed_if_unset=args.randomize_seed,
|
||||
)
|
||||
warnings = upload_warnings + inj_warnings
|
||||
for w in warnings:
|
||||
log(f"WARN: {w}")
|
||||
|
||||
# ---- Submit ----
|
||||
submit_resp = runner.submit(workflow)
|
||||
if "_http_error" in submit_resp:
|
||||
emit_json({
|
||||
"error": "Submission HTTP error",
|
||||
"http_status": submit_resp["_http_error"],
|
||||
"body": submit_resp.get("body"),
|
||||
})
|
||||
return 1
|
||||
|
||||
if isinstance(submit_resp.get("error"), dict):
|
||||
emit_json({
|
||||
"error": "Workflow validation failed",
|
||||
"details": submit_resp["error"],
|
||||
"node_errors": submit_resp.get("node_errors"),
|
||||
})
|
||||
return 1
|
||||
|
||||
prompt_id = submit_resp.get("prompt_id")
|
||||
if not prompt_id:
|
||||
emit_json({"error": "No prompt_id in submit response", "response": submit_resp})
|
||||
return 1
|
||||
|
||||
node_errors = submit_resp.get("node_errors") or {}
|
||||
if node_errors:
|
||||
emit_json({"error": "Workflow validation failed", "node_errors": node_errors})
|
||||
return 1
|
||||
|
||||
if args.submit_only:
|
||||
emit_json({"status": "submitted", "prompt_id": prompt_id, "warnings": warnings})
|
||||
return 0
|
||||
|
||||
# ---- Wait ----
|
||||
timeout = args.timeout
|
||||
if timeout <= 0:
|
||||
timeout = 900 if looks_like_video_workflow(workflow) else 300
|
||||
|
||||
log(f"Submitted: prompt_id={prompt_id}, waiting (timeout={timeout}s)…")
|
||||
|
||||
def _on_progress(evt: dict) -> None:
|
||||
t = evt.get("type")
|
||||
if t == "progress":
|
||||
log(f" step {evt.get('value')}/{evt.get('max')} on node {evt.get('node')}")
|
||||
elif t == "executing":
|
||||
node = evt.get("node")
|
||||
if node:
|
||||
log(f" executing node {node}")
|
||||
|
||||
try:
|
||||
if args.ws:
|
||||
wait_result = runner.monitor_ws(prompt_id, timeout=timeout, on_progress=_on_progress)
|
||||
else:
|
||||
wait_result = runner.poll_status(prompt_id, timeout=timeout)
|
||||
except KeyboardInterrupt:
|
||||
log(f"Interrupted — cancelling job {prompt_id} on server…")
|
||||
try:
|
||||
runner.cancel(prompt_id)
|
||||
except Exception as e:
|
||||
log(f" (cancel request failed: {e})")
|
||||
emit_json({
|
||||
"status": "interrupted",
|
||||
"prompt_id": prompt_id,
|
||||
"note": "Ctrl+C received; sent cancellation to server.",
|
||||
})
|
||||
return 130
|
||||
|
||||
if wait_result["status"] == "timeout":
|
||||
emit_json({
|
||||
"status": "timeout",
|
||||
"prompt_id": prompt_id,
|
||||
"elapsed": wait_result.get("elapsed"),
|
||||
"hint": "Re-run with larger --timeout, or use --submit-only and check later.",
|
||||
})
|
||||
return 1
|
||||
if wait_result["status"] == "error":
|
||||
emit_json({"status": "error", "prompt_id": prompt_id, "details": wait_result.get("data")})
|
||||
return 1
|
||||
if wait_result["status"] == "cancelled":
|
||||
emit_json({"status": "cancelled", "prompt_id": prompt_id})
|
||||
return 1
|
||||
|
||||
# ---- Outputs ----
|
||||
outputs = wait_result.get("outputs")
|
||||
if not outputs:
|
||||
outputs = runner.get_outputs(prompt_id)
|
||||
|
||||
if args.no_download:
|
||||
emit_json({
|
||||
"status": "success", "prompt_id": prompt_id,
|
||||
"outputs": outputs, "warnings": warnings,
|
||||
})
|
||||
return 0
|
||||
|
||||
downloaded = download_outputs(
|
||||
runner, outputs, Path(args.output_dir).expanduser(),
|
||||
preserve_subfolder=not args.flat_output, overwrite=args.overwrite,
|
||||
)
|
||||
|
||||
emit_json({
|
||||
"status": "success",
|
||||
"prompt_id": prompt_id,
|
||||
"outputs": downloaded,
|
||||
"warnings": warnings,
|
||||
})
|
||||
return 0
|
||||
|
||||
|
||||
if __name__ == "__main__":
|
||||
sys.exit(main())
|
||||
+267
@@ -0,0 +1,267 @@
|
||||
#!/usr/bin/env python3
|
||||
"""
|
||||
ws_monitor.py — Real-time ComfyUI WebSocket monitor.
|
||||
|
||||
Connects to /ws and pretty-prints execution events: node start/finish, sampling
|
||||
progress, cached nodes, errors. Optionally writes preview frames to disk.
|
||||
|
||||
Useful for:
|
||||
- Watching a long-running job in real time without parsing JSON yourself
|
||||
- Saving in-progress preview frames for video / animation workflows
|
||||
- Debugging "why is this hanging?" — see exactly which node is stuck
|
||||
|
||||
Usage:
|
||||
# Local — watch all jobs from this client_id
|
||||
python3 ws_monitor.py
|
||||
|
||||
# Cloud — watch a specific prompt_id
|
||||
python3 ws_monitor.py --host https://cloud.comfy.org \
|
||||
--prompt-id abc-123-def
|
||||
|
||||
# Save preview frames to ./previews/
|
||||
python3 ws_monitor.py --previews ./previews
|
||||
|
||||
Requires: websocket-client (`pip install websocket-client`).
|
||||
Falls back to a clear error message when not installed.
|
||||
"""
|
||||
|
||||
from __future__ import annotations
|
||||
|
||||
import argparse
|
||||
import json
|
||||
import struct
|
||||
import sys
|
||||
from pathlib import Path
|
||||
from urllib.parse import urlparse
|
||||
|
||||
sys.path.insert(0, str(Path(__file__).resolve().parent))
|
||||
from _common import ( # noqa: E402
|
||||
DEFAULT_LOCAL_HOST, ENV_API_KEY, log, new_client_id, resolve_api_key, is_cloud_host,
|
||||
)
|
||||
|
||||
|
||||
# Binary frame types from ComfyUI WebSocket protocol
|
||||
BINARY_PREVIEW_IMAGE = 1
|
||||
BINARY_TEXT = 3
|
||||
BINARY_PREVIEW_IMAGE_WITH_METADATA = 4
|
||||
|
||||
# Image type codes inside PREVIEW_IMAGE
|
||||
IMAGE_TYPE_JPEG = 1
|
||||
IMAGE_TYPE_PNG = 2
|
||||
|
||||
# ANSI escape codes (works on most modern terminals)
|
||||
RESET = "\033[0m"
|
||||
DIM = "\033[2m"
|
||||
BOLD = "\033[1m"
|
||||
GREEN = "\033[32m"
|
||||
YELLOW = "\033[33m"
|
||||
RED = "\033[31m"
|
||||
CYAN = "\033[36m"
|
||||
|
||||
|
||||
def fmt_color(s: str, color: str, *, color_on: bool = True) -> str:
|
||||
return f"{color}{s}{RESET}" if color_on else s
|
||||
|
||||
|
||||
def parse_binary_frame(data: bytes) -> dict | None:
|
||||
if len(data) < 8:
|
||||
return None
|
||||
type_code = struct.unpack(">I", data[0:4])[0]
|
||||
if type_code == BINARY_PREVIEW_IMAGE:
|
||||
image_type = struct.unpack(">I", data[4:8])[0]
|
||||
ext = "jpg" if image_type == IMAGE_TYPE_JPEG else "png" if image_type == IMAGE_TYPE_PNG else "bin"
|
||||
return {
|
||||
"kind": "preview",
|
||||
"image_type": image_type,
|
||||
"ext": ext,
|
||||
"image_bytes": data[8:],
|
||||
}
|
||||
if type_code == BINARY_PREVIEW_IMAGE_WITH_METADATA:
|
||||
if len(data) < 12:
|
||||
return None
|
||||
meta_len = struct.unpack(">I", data[4:8])[0]
|
||||
meta_end = 8 + meta_len
|
||||
if len(data) < meta_end:
|
||||
return None
|
||||
try:
|
||||
meta = json.loads(data[8:meta_end].decode("utf-8"))
|
||||
except Exception:
|
||||
meta = {"raw": data[8:meta_end][:200].decode("utf-8", "replace")}
|
||||
return {
|
||||
"kind": "preview_with_metadata",
|
||||
"metadata": meta,
|
||||
"image_bytes": data[meta_end:],
|
||||
"ext": "png",
|
||||
}
|
||||
if type_code == BINARY_TEXT:
|
||||
if len(data) < 8:
|
||||
return None
|
||||
nid_len = struct.unpack(">I", data[4:8])[0]
|
||||
nid_end = 8 + nid_len
|
||||
if len(data) < nid_end:
|
||||
return None
|
||||
return {
|
||||
"kind": "text",
|
||||
"node_id": data[8:nid_end].decode("utf-8", "replace"),
|
||||
"text": data[nid_end:].decode("utf-8", "replace"),
|
||||
}
|
||||
return {"kind": "unknown", "type_code": type_code, "size": len(data)}
|
||||
|
||||
|
||||
def main(argv: list[str] | None = None) -> int:
|
||||
p = argparse.ArgumentParser(description="Real-time ComfyUI WebSocket monitor")
|
||||
p.add_argument("--host", default=DEFAULT_LOCAL_HOST, help="ComfyUI server URL")
|
||||
p.add_argument("--api-key", help=f"API key for cloud (or set ${ENV_API_KEY} env var)")
|
||||
p.add_argument("--client-id", default=None, help="Client ID (default: random UUID)")
|
||||
p.add_argument("--prompt-id", default=None,
|
||||
help="Filter to a specific prompt_id (default: all jobs)")
|
||||
p.add_argument("--previews", default=None,
|
||||
help="Directory to save in-progress preview frames")
|
||||
p.add_argument("--no-color", action="store_true", help="Disable ANSI colour")
|
||||
p.add_argument("--timeout", type=float, default=600.0,
|
||||
help="Hard cap on monitor duration (default 600s)")
|
||||
args = p.parse_args(argv)
|
||||
|
||||
try:
|
||||
import websocket # type: ignore[import-not-found]
|
||||
except ImportError:
|
||||
print(json.dumps({
|
||||
"error": "websocket-client not installed",
|
||||
"install": "pip install websocket-client",
|
||||
}))
|
||||
return 1
|
||||
|
||||
api_key = resolve_api_key(args.api_key)
|
||||
cloud = is_cloud_host(args.host)
|
||||
client_id = args.client_id or new_client_id()
|
||||
|
||||
# Build WS URL preserving any base-path component (e.g. behind reverse proxy).
|
||||
parsed = urlparse(args.host if "://" in args.host else f"http://{args.host}")
|
||||
scheme = "wss" if parsed.scheme == "https" else "ws"
|
||||
netloc = parsed.netloc
|
||||
base_path = parsed.path.rstrip("/")
|
||||
ws_url = f"{scheme}://{netloc}{base_path}/ws?clientId={client_id}"
|
||||
if cloud and api_key:
|
||||
ws_url += f"&token={api_key}"
|
||||
|
||||
color_on = not args.no_color and sys.stdout.isatty()
|
||||
|
||||
preview_dir = Path(args.previews).expanduser() if args.previews else None
|
||||
if preview_dir:
|
||||
preview_dir.mkdir(parents=True, exist_ok=True)
|
||||
log(f"Saving previews to {preview_dir}")
|
||||
|
||||
log(f"Connecting to {ws_url} (client_id={client_id})")
|
||||
if args.prompt_id:
|
||||
log(f"Filtering messages to prompt_id={args.prompt_id}")
|
||||
|
||||
ws = websocket.create_connection(ws_url, timeout=args.timeout)
|
||||
ws.settimeout(args.timeout)
|
||||
|
||||
preview_counter = 0
|
||||
try:
|
||||
while True:
|
||||
try:
|
||||
msg = ws.recv()
|
||||
except websocket.WebSocketTimeoutException:
|
||||
log(f"Idle for {args.timeout}s — exiting")
|
||||
return 0
|
||||
if isinstance(msg, bytes):
|
||||
parsed = parse_binary_frame(msg)
|
||||
if parsed is None:
|
||||
continue
|
||||
if parsed["kind"] in {"preview", "preview_with_metadata"} and preview_dir:
|
||||
img_bytes = parsed.get("image_bytes", b"")
|
||||
if img_bytes:
|
||||
ext = parsed.get("ext", "png")
|
||||
out = preview_dir / f"preview_{preview_counter:05d}.{ext}"
|
||||
out.write_bytes(img_bytes)
|
||||
preview_counter += 1
|
||||
log(f" [preview] saved {out.name} ({len(img_bytes)} bytes)")
|
||||
continue
|
||||
|
||||
try:
|
||||
payload = json.loads(msg)
|
||||
except Exception:
|
||||
continue
|
||||
mtype = payload.get("type", "")
|
||||
mdata = payload.get("data", {}) or {}
|
||||
pid = mdata.get("prompt_id")
|
||||
|
||||
if args.prompt_id and pid and pid != args.prompt_id:
|
||||
continue
|
||||
|
||||
if mtype == "status":
|
||||
qr = mdata.get("status", {}).get("exec_info", {}).get("queue_remaining", "?")
|
||||
print(fmt_color(f"[status] queue_remaining={qr}", DIM, color_on=color_on))
|
||||
elif mtype == "execution_start":
|
||||
print(fmt_color(f"[start] prompt_id={pid}", BOLD, color_on=color_on))
|
||||
elif mtype == "executing":
|
||||
node = mdata.get("node")
|
||||
if node:
|
||||
print(fmt_color(f" [executing] node={node}", CYAN, color_on=color_on))
|
||||
else:
|
||||
print(fmt_color(f" [executing] (workflow done) prompt_id={pid}", DIM, color_on=color_on))
|
||||
elif mtype == "progress":
|
||||
v, m = mdata.get("value", 0), mdata.get("max", 0)
|
||||
pct = (v / m * 100) if m else 0
|
||||
print(f" [progress] {v}/{m} ({pct:5.1f}%) node={mdata.get('node')}")
|
||||
elif mtype == "progress_state":
|
||||
# Newer extended progress message
|
||||
nodes = mdata.get("nodes") or {}
|
||||
running = [k for k, v in nodes.items() if v.get("running")]
|
||||
if running:
|
||||
print(fmt_color(f" [progress_state] running={running}", DIM, color_on=color_on))
|
||||
elif mtype == "executed":
|
||||
node = mdata.get("node")
|
||||
out = mdata.get("output") or {}
|
||||
summary_parts = []
|
||||
for key in ("images", "video", "videos", "gifs", "audio", "files"):
|
||||
if out.get(key):
|
||||
summary_parts.append(f"{key}={len(out[key])}")
|
||||
summary = ", ".join(summary_parts) if summary_parts else "(no files)"
|
||||
print(fmt_color(f" [executed] node={node} {summary}", GREEN, color_on=color_on))
|
||||
elif mtype == "execution_cached":
|
||||
cached = mdata.get("nodes") or []
|
||||
if cached:
|
||||
print(fmt_color(f" [cached] {len(cached)} nodes skipped", DIM, color_on=color_on))
|
||||
elif mtype == "execution_success":
|
||||
print(fmt_color(f"[success] prompt_id={pid}", GREEN + BOLD, color_on=color_on))
|
||||
if args.prompt_id:
|
||||
return 0
|
||||
elif mtype == "execution_error":
|
||||
exc_type = mdata.get("exception_type", "?")
|
||||
exc_msg = mdata.get("exception_message", "?")
|
||||
print(fmt_color(f"[error] {exc_type}: {exc_msg}", RED + BOLD, color_on=color_on))
|
||||
tb = mdata.get("traceback")
|
||||
if tb:
|
||||
if isinstance(tb, list):
|
||||
for line in tb:
|
||||
print(fmt_color(f" {line}", RED, color_on=color_on))
|
||||
else:
|
||||
print(fmt_color(f" {tb}", RED, color_on=color_on))
|
||||
if args.prompt_id:
|
||||
return 1
|
||||
elif mtype == "execution_interrupted":
|
||||
print(fmt_color(f"[interrupted] prompt_id={pid}", YELLOW, color_on=color_on))
|
||||
if args.prompt_id:
|
||||
return 1
|
||||
elif mtype == "notification":
|
||||
v = mdata.get("value", "")
|
||||
print(fmt_color(f"[notification] {v}", DIM, color_on=color_on))
|
||||
else:
|
||||
# Unknown / lightly-used types: print compactly
|
||||
print(fmt_color(f"[{mtype}] {json.dumps(mdata, default=str)[:200]}", DIM, color_on=color_on))
|
||||
|
||||
except KeyboardInterrupt:
|
||||
log("Interrupted")
|
||||
return 130
|
||||
finally:
|
||||
try:
|
||||
ws.close()
|
||||
except Exception:
|
||||
pass
|
||||
|
||||
|
||||
if __name__ == "__main__":
|
||||
sys.exit(main())
|
||||
@@ -0,0 +1,52 @@
|
||||
# ComfyUI Skill Tests
|
||||
|
||||
Pytest suite covering the skill's scripts. Pure-stdlib unit tests run
|
||||
without any setup; cloud integration tests need a Comfy Cloud API key.
|
||||
|
||||
## Running
|
||||
|
||||
```bash
|
||||
# Unit tests only (no network required) — runs in <1s
|
||||
python3 -m pytest tests/ -c tests/pytest.ini -o addopts="-p no:xdist"
|
||||
|
||||
# Including cloud integration tests
|
||||
COMFY_CLOUD_API_KEY="comfyui-..." python3 -m pytest tests/ \
|
||||
-c tests/pytest.ini -o addopts="-p no:xdist"
|
||||
|
||||
# Just cloud tests
|
||||
COMFY_CLOUD_API_KEY="comfyui-..." python3 -m pytest tests/test_cloud_integration.py \
|
||||
-c tests/pytest.ini -o addopts="-p no:xdist" -v
|
||||
```
|
||||
|
||||
The `-c` and `-o` overrides isolate this suite from any parent
|
||||
`pyproject.toml` pytest config (e.g. the `-n auto` from a parent repo).
|
||||
|
||||
## Test files
|
||||
|
||||
| File | Coverage |
|
||||
|------|----------|
|
||||
| `test_common.py` | Cloud detection, URL routing, format validation, embeddings, paths, seeds, model-list parsing, folder aliases |
|
||||
| `test_extract_schema.py` | Connection tracing, positive/negative prompt detection, dedup logic, embedding deps |
|
||||
| `test_run_workflow.py` | Param injection (incl. -1 seed, link refusal), output download walk, runner construction |
|
||||
| `test_check_deps.py` | Model-name fuzzy matching, install command suggestions |
|
||||
| `test_cloud_integration.py` | Live cloud API contract tests (auto-skipped without API key) |
|
||||
|
||||
## Adding tests
|
||||
|
||||
When you change a script:
|
||||
|
||||
1. Add a unit test if the change is pure logic (cloud detection, parsing, etc.)
|
||||
2. Add a cloud integration test if the change depends on cloud API behavior
|
||||
(use `pytestmark = pytest.mark.cloud` so it auto-skips without a key)
|
||||
3. Workflow fixtures live in `conftest.py` (`sd15_workflow`, `flux_workflow`,
|
||||
`video_workflow`)
|
||||
|
||||
## Why the explicit `-c` / `-o`?
|
||||
|
||||
The parent hermes-agent repo used to enable `pytest-xdist` by default
|
||||
(`-n auto`); the canonical runner has since moved to per-file subprocess
|
||||
isolation via `scripts/run_tests_parallel.py` and no longer uses xdist.
|
||||
This suite is small enough that parallelism isn't worth the complexity, and
|
||||
pytest-xdist isn't always installed in the user's environment. The
|
||||
`-c tests/pytest.ini -o addopts="-p no:xdist"` flags make the suite run
|
||||
identically regardless of the parent project's config.
|
||||
@@ -0,0 +1,64 @@
|
||||
"""Pytest configuration for the comfyui skill test suite.
|
||||
|
||||
Adds `scripts/` to sys.path so tests can `from _common import ...`, and
|
||||
provides a few common fixtures.
|
||||
"""
|
||||
|
||||
from __future__ import annotations
|
||||
|
||||
import json
|
||||
import os
|
||||
import sys
|
||||
from pathlib import Path
|
||||
|
||||
import pytest
|
||||
|
||||
ROOT = Path(__file__).resolve().parent.parent
|
||||
SCRIPTS = ROOT / "scripts"
|
||||
WORKFLOWS = ROOT / "workflows"
|
||||
|
||||
sys.path.insert(0, str(SCRIPTS))
|
||||
|
||||
|
||||
@pytest.fixture
|
||||
def sd15_workflow() -> dict:
|
||||
return json.loads((WORKFLOWS / "sd15_txt2img.json").read_text(encoding="utf-8"))
|
||||
|
||||
|
||||
@pytest.fixture
|
||||
def flux_workflow() -> dict:
|
||||
return json.loads((WORKFLOWS / "flux_dev_txt2img.json").read_text(encoding="utf-8"))
|
||||
|
||||
|
||||
@pytest.fixture
|
||||
def video_workflow() -> dict:
|
||||
return json.loads((WORKFLOWS / "wan_video_t2v.json").read_text(encoding="utf-8"))
|
||||
|
||||
|
||||
@pytest.fixture
|
||||
def workflows_dir() -> Path:
|
||||
return WORKFLOWS
|
||||
|
||||
|
||||
@pytest.fixture
|
||||
def scripts_dir() -> Path:
|
||||
return SCRIPTS
|
||||
|
||||
|
||||
@pytest.fixture
|
||||
def cloud_key() -> str | None:
|
||||
"""Cloud API key if set, otherwise None.
|
||||
|
||||
Tests that need cloud connectivity should skip when this is None.
|
||||
"""
|
||||
return os.environ.get("COMFY_CLOUD_API_KEY")
|
||||
|
||||
|
||||
def pytest_collection_modifyitems(config, items):
|
||||
"""Auto-skip cloud tests when no API key is set."""
|
||||
if os.environ.get("COMFY_CLOUD_API_KEY"):
|
||||
return
|
||||
skip_cloud = pytest.mark.skip(reason="Set COMFY_CLOUD_API_KEY to run cloud tests")
|
||||
for item in items:
|
||||
if "cloud" in item.keywords:
|
||||
item.add_marker(skip_cloud)
|
||||
@@ -0,0 +1,5 @@
|
||||
[pytest]
|
||||
markers =
|
||||
cloud: tests that hit live Comfy Cloud API (require COMFY_CLOUD_API_KEY)
|
||||
testpaths = .
|
||||
addopts = -p no:xdist
|
||||
@@ -0,0 +1,68 @@
|
||||
"""Tests for check_deps.py — focuses on parsing logic that doesn't need a server."""
|
||||
|
||||
from __future__ import annotations
|
||||
|
||||
from check_deps import (
|
||||
NODE_TO_PACKAGE,
|
||||
model_present,
|
||||
normalize_for_match,
|
||||
suggest_install_command,
|
||||
)
|
||||
|
||||
|
||||
class TestNormalizeForMatch:
|
||||
def test_basic(self):
|
||||
s = normalize_for_match("model.safetensors")
|
||||
assert "model.safetensors" in s
|
||||
assert "model" in s
|
||||
|
||||
def test_subfolder(self):
|
||||
s = normalize_for_match("subdir/model.pt")
|
||||
assert "subdir/model.pt" in s
|
||||
assert "model.pt" in s
|
||||
assert "model" in s
|
||||
|
||||
|
||||
class TestModelPresent:
|
||||
def test_exact_match(self):
|
||||
assert model_present("a.safetensors", {"a.safetensors", "b.safetensors"}) is True
|
||||
|
||||
def test_extension_difference(self):
|
||||
# User said "model" but installed is "model.safetensors"
|
||||
assert model_present("model", {"model.safetensors"}) is True
|
||||
# Reverse direction — also matches
|
||||
assert model_present("model.safetensors", {"model"}) is True
|
||||
|
||||
def test_subfolder_match(self):
|
||||
# Installed list has "subdir/model.safetensors", workflow asks "model.safetensors"
|
||||
assert model_present("model.safetensors", {"subdir/model.safetensors"}) is True
|
||||
|
||||
def test_missing(self):
|
||||
assert model_present("missing.safetensors", {"a.safetensors", "b.safetensors"}) is False
|
||||
|
||||
def test_empty_installed(self):
|
||||
assert model_present("anything.safetensors", set()) is False
|
||||
|
||||
|
||||
class TestSuggestInstallCommand:
|
||||
def test_known_node(self):
|
||||
cmd = suggest_install_command("VHS_VideoCombine")
|
||||
assert cmd == "comfy node install comfyui-videohelpersuite"
|
||||
|
||||
def test_unknown_node(self):
|
||||
assert suggest_install_command("SomeRandomNodeName123") is None
|
||||
|
||||
|
||||
class TestNodePackageMap:
|
||||
def test_no_duplicates(self):
|
||||
# Each node should map to exactly one package
|
||||
keys = list(NODE_TO_PACKAGE.keys())
|
||||
assert len(keys) == len(set(keys))
|
||||
|
||||
def test_packages_are_safe_for_shell(self):
|
||||
# Registry slugs must be alphanumerics + hyphens/underscores only
|
||||
# (passed straight to `comfy node install <pkg>`).
|
||||
import re
|
||||
safe = re.compile(r"^[A-Za-z0-9][A-Za-z0-9._\-]*$")
|
||||
for pkg in NODE_TO_PACKAGE.values():
|
||||
assert safe.match(pkg), f"Unsafe package slug: {pkg!r}"
|
||||
@@ -0,0 +1,95 @@
|
||||
"""Integration tests against the live Comfy Cloud API.
|
||||
|
||||
These tests are auto-skipped when COMFY_CLOUD_API_KEY is not set.
|
||||
They never SUBMIT workflows (would need a paid subscription) — they only
|
||||
verify the read-only endpoints we rely on.
|
||||
"""
|
||||
|
||||
from __future__ import annotations
|
||||
|
||||
import pytest
|
||||
|
||||
from _common import http_get, parse_model_list, resolve_url
|
||||
|
||||
|
||||
pytestmark = pytest.mark.cloud
|
||||
|
||||
|
||||
class TestCloudEndpointsLive:
|
||||
def test_system_stats_reachable(self, cloud_key):
|
||||
url = resolve_url("https://cloud.comfy.org", "/system_stats")
|
||||
r = http_get(url, headers={"X-API-Key": cloud_key})
|
||||
assert r.status == 200
|
||||
data = r.json()
|
||||
assert "system" in data
|
||||
|
||||
def test_models_endpoint_routed_to_experiment(self, cloud_key):
|
||||
# We expect the skill to route /models/checkpoints → /api/experiment/models/checkpoints
|
||||
url = resolve_url("https://cloud.comfy.org", "/models/checkpoints")
|
||||
assert "/api/experiment/models/checkpoints" in url
|
||||
r = http_get(url, headers={"X-API-Key": cloud_key})
|
||||
assert r.status == 200
|
||||
|
||||
def test_models_endpoint_returns_dicts(self, cloud_key):
|
||||
url = resolve_url("https://cloud.comfy.org", "/models/checkpoints")
|
||||
r = http_get(url, headers={"X-API-Key": cloud_key})
|
||||
data = r.json()
|
||||
assert isinstance(data, list)
|
||||
if data:
|
||||
# Cloud format: list of dicts with `name`
|
||||
assert isinstance(data[0], dict)
|
||||
assert "name" in data[0]
|
||||
# Our parser normalizes both
|
||||
normalized = parse_model_list(data)
|
||||
assert len(normalized) == len(data)
|
||||
|
||||
def test_history_renamed_to_v2(self, cloud_key):
|
||||
# /history → /api/history_v2 on cloud
|
||||
url = resolve_url("https://cloud.comfy.org", "/history/some-fake-id")
|
||||
assert "/api/history_v2/some-fake-id" in url
|
||||
|
||||
def test_object_info_paid_tier(self, cloud_key):
|
||||
# On free tier, /object_info returns 403 with a recognizable message
|
||||
url = resolve_url("https://cloud.comfy.org", "/object_info")
|
||||
r = http_get(url, headers={"X-API-Key": cloud_key})
|
||||
# Should be either 200 (paid) or 403 (free) — not 404 / 500
|
||||
assert r.status in {200, 403}
|
||||
if r.status == 403:
|
||||
# Body should mention the limitation
|
||||
assert "free tier" in r.text().lower() or "subscription" in r.text().lower()
|
||||
|
||||
|
||||
class TestCloudCheckDepsLive:
|
||||
def test_check_deps_against_cloud(self, cloud_key, sd15_workflow):
|
||||
from check_deps import check_deps
|
||||
report = check_deps(sd15_workflow, host="https://cloud.comfy.org", api_key=cloud_key)
|
||||
# Either node check passed OR was skipped (free tier)
|
||||
assert "missing_models" in report
|
||||
assert "is_cloud" in report and report["is_cloud"] is True
|
||||
|
||||
def test_flux_workflow_models_resolved_via_aliases(self, cloud_key, flux_workflow):
|
||||
"""Flux uses unet/clip folders; cloud has them in diffusion_models/text_encoders.
|
||||
With folder aliasing, the check should still find them."""
|
||||
from check_deps import check_deps
|
||||
report = check_deps(flux_workflow, host="https://cloud.comfy.org", api_key=cloud_key)
|
||||
# The exact required Flux files (flux1-dev.safetensors, t5xxl_fp16, clip_l, ae)
|
||||
# are present on cloud; with folder aliasing, none should be missing.
|
||||
# If this fails, either the cloud removed the model or the aliasing logic broke.
|
||||
missing_filenames = {m["value"] for m in report["missing_models"]}
|
||||
assert "ae.safetensors" not in missing_filenames, \
|
||||
"ae.safetensors should be on cloud's vae folder"
|
||||
# t5xxl_fp16 / clip_l should be reachable via the clip → text_encoders alias
|
||||
# flux1-dev.safetensors likewise via unet → diffusion_models
|
||||
|
||||
|
||||
class TestHealthCheckLive:
|
||||
def test_health_check_passes(self, cloud_key, capsys):
|
||||
from health_check import main as health_main
|
||||
rc = health_main(["--host", "https://cloud.comfy.org", "--api-key", cloud_key])
|
||||
captured = capsys.readouterr()
|
||||
# Should produce JSON
|
||||
import json
|
||||
report = json.loads(captured.out)
|
||||
assert report["server"]["reachable"] is True
|
||||
assert report["checkpoints"]["queryable"] is True
|
||||
assert report["checkpoints"]["count"] > 0
|
||||
@@ -0,0 +1,443 @@
|
||||
"""Unit tests for _common.py — pure logic only, no network."""
|
||||
|
||||
from __future__ import annotations
|
||||
|
||||
|
||||
import pytest
|
||||
|
||||
from _common import (
|
||||
EMBEDDING_REGEX,
|
||||
cloud_endpoint,
|
||||
coerce_seed,
|
||||
folder_aliases_for,
|
||||
is_api_format,
|
||||
is_cloud_host,
|
||||
is_link,
|
||||
iter_embedding_refs,
|
||||
iter_model_deps,
|
||||
iter_nodes,
|
||||
looks_like_video_workflow,
|
||||
media_type_from_filename,
|
||||
parse_model_list,
|
||||
resolve_url,
|
||||
safe_path_join,
|
||||
unwrap_workflow,
|
||||
)
|
||||
|
||||
|
||||
# =============================================================================
|
||||
# Cloud detection / URL routing
|
||||
# =============================================================================
|
||||
|
||||
class TestCloudDetection:
|
||||
def test_cloud_host_exact(self):
|
||||
assert is_cloud_host("https://cloud.comfy.org") is True
|
||||
assert is_cloud_host("https://cloud.comfy.org/foo/bar") is True
|
||||
|
||||
def test_cloud_host_subdomain(self):
|
||||
assert is_cloud_host("https://staging.cloud.comfy.org") is True
|
||||
assert is_cloud_host("https://api.cloud.comfy.org") is True
|
||||
|
||||
def test_local_not_cloud(self):
|
||||
assert is_cloud_host("http://127.0.0.1:8188") is False
|
||||
assert is_cloud_host("http://localhost:8188") is False
|
||||
assert is_cloud_host("http://my-server.local:8188") is False
|
||||
|
||||
def test_no_scheme(self):
|
||||
# Defaults to http://
|
||||
assert is_cloud_host("cloud.comfy.org") is True
|
||||
assert is_cloud_host("127.0.0.1:8188") is False
|
||||
|
||||
|
||||
class TestCloudEndpointRename:
|
||||
def test_history_renamed(self):
|
||||
assert cloud_endpoint("/history") == "/history_v2"
|
||||
assert cloud_endpoint("/history/abc-123") == "/history_v2/abc-123"
|
||||
|
||||
def test_history_v2_preserved(self):
|
||||
assert cloud_endpoint("/history_v2") == "/history_v2"
|
||||
|
||||
def test_models_renamed(self):
|
||||
assert cloud_endpoint("/models") == "/experiment/models"
|
||||
assert cloud_endpoint("/models/checkpoints") == "/experiment/models/checkpoints"
|
||||
assert cloud_endpoint("/models/loras") == "/experiment/models/loras"
|
||||
|
||||
def test_other_paths_unchanged(self):
|
||||
assert cloud_endpoint("/prompt") == "/prompt"
|
||||
assert cloud_endpoint("/queue") == "/queue"
|
||||
|
||||
|
||||
class TestResolveURL:
|
||||
def test_local_no_prefix(self):
|
||||
assert resolve_url("http://127.0.0.1:8188", "/prompt") == "http://127.0.0.1:8188/prompt"
|
||||
|
||||
def test_cloud_adds_api_prefix(self):
|
||||
assert resolve_url("https://cloud.comfy.org", "/prompt") == "https://cloud.comfy.org/api/prompt"
|
||||
|
||||
def test_cloud_history_renamed(self):
|
||||
assert resolve_url("https://cloud.comfy.org", "/history/abc") == "https://cloud.comfy.org/api/history_v2/abc"
|
||||
|
||||
def test_cloud_models_renamed(self):
|
||||
assert resolve_url("https://cloud.comfy.org", "/models/loras") == "https://cloud.comfy.org/api/experiment/models/loras"
|
||||
|
||||
def test_cloud_already_has_api(self):
|
||||
# Don't double-prefix
|
||||
assert resolve_url("https://cloud.comfy.org", "/api/prompt") == "https://cloud.comfy.org/api/prompt"
|
||||
|
||||
def test_trailing_slash_stripped(self):
|
||||
assert resolve_url("http://127.0.0.1:8188/", "/prompt") == "http://127.0.0.1:8188/prompt"
|
||||
|
||||
|
||||
# =============================================================================
|
||||
# Workflow validation
|
||||
# =============================================================================
|
||||
|
||||
class TestAPIFormatDetection:
|
||||
def test_valid_api(self, sd15_workflow):
|
||||
assert is_api_format(sd15_workflow) is True
|
||||
|
||||
def test_editor_format_rejected(self):
|
||||
editor = {"nodes": [], "links": [], "version": 0.4}
|
||||
assert is_api_format(editor) is False
|
||||
|
||||
def test_empty_dict(self):
|
||||
assert is_api_format({}) is False
|
||||
|
||||
def test_non_dict(self):
|
||||
assert is_api_format([]) is False
|
||||
assert is_api_format(None) is False
|
||||
assert is_api_format("string") is False
|
||||
|
||||
def test_node_with_class_type(self):
|
||||
wf = {"3": {"class_type": "KSampler", "inputs": {}}}
|
||||
assert is_api_format(wf) is True
|
||||
|
||||
|
||||
class TestUnwrapWorkflow:
|
||||
def test_passthrough_api_format(self, sd15_workflow):
|
||||
result = unwrap_workflow(sd15_workflow)
|
||||
assert result is sd15_workflow
|
||||
|
||||
def test_unwrap_prompt_key(self, sd15_workflow):
|
||||
wrapped = {"prompt": sd15_workflow, "client_id": "abc"}
|
||||
result = unwrap_workflow(wrapped)
|
||||
assert result is sd15_workflow
|
||||
|
||||
def test_editor_format_raises(self):
|
||||
with pytest.raises(ValueError, match="editor format"):
|
||||
unwrap_workflow({"nodes": [], "links": []})
|
||||
|
||||
def test_garbage_raises(self):
|
||||
with pytest.raises(ValueError):
|
||||
unwrap_workflow({"foo": "bar"})
|
||||
|
||||
|
||||
class TestIsLink:
|
||||
def test_valid_link(self):
|
||||
assert is_link(["3", 0]) is True
|
||||
assert is_link(["10", 1]) is True
|
||||
|
||||
def test_non_link(self):
|
||||
assert is_link("string") is False
|
||||
assert is_link(42) is False
|
||||
assert is_link([]) is False
|
||||
assert is_link(["3"]) is False # missing slot
|
||||
assert is_link(["3", "0"]) is False # slot must be int
|
||||
assert is_link([3, 0]) is False # node_id must be string
|
||||
|
||||
|
||||
# =============================================================================
|
||||
# Workflow iterators
|
||||
# =============================================================================
|
||||
|
||||
class TestIterators:
|
||||
def test_iter_nodes(self, sd15_workflow):
|
||||
nodes = dict(iter_nodes(sd15_workflow))
|
||||
assert "3" in nodes
|
||||
assert nodes["3"]["class_type"] == "KSampler"
|
||||
|
||||
def test_iter_nodes_skips_comments(self, sd15_workflow):
|
||||
# _comment is not a node
|
||||
nodes = dict(iter_nodes(sd15_workflow))
|
||||
assert "_comment" not in nodes
|
||||
|
||||
def test_iter_model_deps(self, sd15_workflow):
|
||||
deps = list(iter_model_deps(sd15_workflow))
|
||||
names = [d["value"] for d in deps]
|
||||
assert "v1-5-pruned-emaonly.safetensors" in names
|
||||
|
||||
def test_iter_model_deps_flux(self, flux_workflow):
|
||||
deps = list(iter_model_deps(flux_workflow))
|
||||
names = {d["value"]: d["folder"] for d in deps}
|
||||
assert names["flux1-dev.safetensors"] == "unet"
|
||||
assert names["t5xxl_fp16.safetensors"] == "clip"
|
||||
assert names["clip_l.safetensors"] == "clip"
|
||||
assert names["ae.safetensors"] == "vae"
|
||||
|
||||
|
||||
# =============================================================================
|
||||
# Embedding extraction
|
||||
# =============================================================================
|
||||
|
||||
class TestEmbeddingRegex:
|
||||
def test_basic_embedding(self):
|
||||
m = EMBEDDING_REGEX.search("a cat, embedding:goodvibes, more text")
|
||||
assert m is not None
|
||||
assert m.group(1) == "goodvibes"
|
||||
|
||||
def test_embedding_with_strength(self):
|
||||
m = EMBEDDING_REGEX.search("embedding:bad-hands-5:1.2")
|
||||
assert m is not None
|
||||
assert m.group(1) == "bad-hands-5"
|
||||
|
||||
def test_embedding_with_extension(self):
|
||||
# Strips .pt / .safetensors / .bin
|
||||
m = EMBEDDING_REGEX.search("embedding:my-emb.pt")
|
||||
assert m is not None
|
||||
assert m.group(1) == "my-emb"
|
||||
|
||||
def test_embedding_in_parens(self):
|
||||
m = EMBEDDING_REGEX.search("(embedding:foo:0.8)")
|
||||
assert m is not None
|
||||
assert m.group(1) == "foo"
|
||||
|
||||
def test_multiple_in_one_string(self):
|
||||
text = "a cat, embedding:foo:1.2, and embedding:bar"
|
||||
matches = [m.group(1) for m in EMBEDDING_REGEX.finditer(text)]
|
||||
assert matches == ["foo", "bar"]
|
||||
|
||||
def test_no_false_positive_on_word_embedding(self):
|
||||
# "embedding " (with space, no colon) should not match
|
||||
m = EMBEDDING_REGEX.search("the embedding is great")
|
||||
assert m is None
|
||||
|
||||
|
||||
class TestIterEmbeddingRefs:
|
||||
def test_finds_in_clip_text_encode(self):
|
||||
wf = {
|
||||
"1": {"class_type": "CLIPTextEncode",
|
||||
"inputs": {"text": "embedding:foo, embedding:bar:0.5", "clip": ["2", 0]}},
|
||||
"2": {"class_type": "CheckpointLoaderSimple", "inputs": {"ckpt_name": "x"}},
|
||||
}
|
||||
refs = list(iter_embedding_refs(wf))
|
||||
names = [name for _, name in refs]
|
||||
assert names == ["foo", "bar"]
|
||||
|
||||
def test_ignores_non_prompt_fields(self):
|
||||
wf = {
|
||||
"1": {"class_type": "CheckpointLoaderSimple",
|
||||
"inputs": {"ckpt_name": "embedding:foo.safetensors"}},
|
||||
}
|
||||
refs = list(iter_embedding_refs(wf))
|
||||
# ckpt_name is not a prompt field — ignored
|
||||
assert refs == []
|
||||
|
||||
|
||||
# =============================================================================
|
||||
# Path safety
|
||||
# =============================================================================
|
||||
|
||||
class TestSafePathJoin:
|
||||
def test_normal_join(self, tmp_path):
|
||||
p = safe_path_join(tmp_path, "subdir", "file.png")
|
||||
assert p.is_relative_to(tmp_path)
|
||||
|
||||
def test_blocks_traversal(self, tmp_path):
|
||||
with pytest.raises(ValueError, match="path traversal"):
|
||||
safe_path_join(tmp_path, "..", "..", "etc", "passwd")
|
||||
|
||||
def test_blocks_absolute(self, tmp_path):
|
||||
with pytest.raises(ValueError):
|
||||
safe_path_join(tmp_path, "/etc/passwd")
|
||||
|
||||
def test_subfolder_with_filename(self, tmp_path):
|
||||
p = safe_path_join(tmp_path, "outputs", "img.png")
|
||||
assert p.name == "img.png"
|
||||
assert p.parent.name == "outputs"
|
||||
|
||||
|
||||
# =============================================================================
|
||||
# Seed coercion
|
||||
# =============================================================================
|
||||
|
||||
class TestCoerceSeed:
|
||||
def test_explicit_int(self):
|
||||
assert coerce_seed(42) == 42
|
||||
assert coerce_seed(0) == 0
|
||||
|
||||
def test_minus_one_randomizes(self):
|
||||
s = coerce_seed(-1)
|
||||
assert isinstance(s, int)
|
||||
assert 0 <= s < 2**63
|
||||
|
||||
def test_none_randomizes(self):
|
||||
s = coerce_seed(None)
|
||||
assert isinstance(s, int)
|
||||
|
||||
def test_string_int(self):
|
||||
# str() that converts cleanly is allowed (relaxed)
|
||||
assert coerce_seed("12345") == 12345
|
||||
|
||||
def test_string_minus_one_randomizes(self):
|
||||
# CLI / JSON sometimes carries seed as a string.
|
||||
s = coerce_seed("-1")
|
||||
assert isinstance(s, int)
|
||||
assert 0 <= s < 2**63
|
||||
# And whitespace tolerated
|
||||
s2 = coerce_seed(" -1 ")
|
||||
assert isinstance(s2, int)
|
||||
assert 0 <= s2 < 2**63
|
||||
|
||||
|
||||
# =============================================================================
|
||||
# Model list normalization (cloud format)
|
||||
# =============================================================================
|
||||
|
||||
class TestParseModelList:
|
||||
def test_local_format_strings(self):
|
||||
result = parse_model_list(["a.safetensors", "b.safetensors"])
|
||||
assert result == {"a.safetensors", "b.safetensors"}
|
||||
|
||||
def test_cloud_format_dicts(self):
|
||||
result = parse_model_list([
|
||||
{"name": "a.safetensors", "pathIndex": 0},
|
||||
{"name": "b.safetensors", "pathIndex": 1},
|
||||
])
|
||||
assert result == {"a.safetensors", "b.safetensors"}
|
||||
|
||||
def test_empty(self):
|
||||
assert parse_model_list([]) == set()
|
||||
|
||||
def test_garbage(self):
|
||||
assert parse_model_list("not a list") == set()
|
||||
assert parse_model_list(None) == set()
|
||||
|
||||
def test_mixed_format(self):
|
||||
result = parse_model_list([
|
||||
"string-form.safetensors",
|
||||
{"name": "dict-form.safetensors"},
|
||||
])
|
||||
assert result == {"string-form.safetensors", "dict-form.safetensors"}
|
||||
|
||||
|
||||
# =============================================================================
|
||||
# Folder aliases
|
||||
# =============================================================================
|
||||
|
||||
class TestFolderAliases:
|
||||
def test_unet_aliases_diffusion_models(self):
|
||||
aliases = folder_aliases_for("unet")
|
||||
assert "unet" in aliases
|
||||
assert "diffusion_models" in aliases
|
||||
|
||||
def test_clip_aliases_text_encoders(self):
|
||||
aliases = folder_aliases_for("clip")
|
||||
assert "clip" in aliases
|
||||
assert "text_encoders" in aliases
|
||||
|
||||
def test_unknown_folder_returns_self(self):
|
||||
assert folder_aliases_for("checkpoints") == ["checkpoints"]
|
||||
|
||||
def test_primary_first(self):
|
||||
# Order matters: primary should be first for human-friendly fix hints
|
||||
assert folder_aliases_for("unet")[0] == "unet"
|
||||
assert folder_aliases_for("diffusion_models")[0] == "diffusion_models"
|
||||
|
||||
|
||||
# =============================================================================
|
||||
# Media-type detection
|
||||
# =============================================================================
|
||||
|
||||
class TestMediaType:
|
||||
def test_video_extensions(self):
|
||||
assert media_type_from_filename("vid.mp4") == "video"
|
||||
assert media_type_from_filename("foo.webm") == "video"
|
||||
assert media_type_from_filename("bar.gif") == "video"
|
||||
|
||||
def test_audio_extensions(self):
|
||||
assert media_type_from_filename("song.wav") == "audio"
|
||||
assert media_type_from_filename("music.mp3") == "audio"
|
||||
|
||||
def test_image_default(self):
|
||||
assert media_type_from_filename("pic.png") == "image"
|
||||
assert media_type_from_filename("image.jpg") == "image"
|
||||
assert media_type_from_filename("unknown.xyz") == "image"
|
||||
|
||||
def test_3d(self):
|
||||
assert media_type_from_filename("model.glb") == "3d"
|
||||
assert media_type_from_filename("scene.gltf") == "3d"
|
||||
|
||||
|
||||
# =============================================================================
|
||||
# Cross-host header stripping (security)
|
||||
# =============================================================================
|
||||
|
||||
class TestRedirectHeaderStripping:
|
||||
"""Verify X-API-Key is dropped when redirect crosses to a different host
|
||||
(e.g. cloud /api/view → S3 signed URL). Critical to prevent leaking auth
|
||||
tokens to the storage backend.
|
||||
"""
|
||||
|
||||
def _build_session(self):
|
||||
from _common import _StripSensitiveOnRedirectSession, HAS_REQUESTS
|
||||
if not HAS_REQUESTS:
|
||||
import pytest
|
||||
pytest.skip("requests not installed")
|
||||
return _StripSensitiveOnRedirectSession()
|
||||
|
||||
def test_strips_x_api_key_cross_host(self):
|
||||
import requests
|
||||
s = self._build_session()
|
||||
prep = requests.PreparedRequest()
|
||||
prep.prepare(method="GET", url="https://other.example.com/file",
|
||||
headers={"X-API-Key": "leak", "Authorization": "Bearer x"})
|
||||
resp = requests.Response()
|
||||
orig = requests.PreparedRequest()
|
||||
orig.prepare(method="GET", url="https://cloud.comfy.org/api/view", headers={})
|
||||
resp.request = orig
|
||||
s.rebuild_auth(prep, resp)
|
||||
assert "X-API-Key" not in prep.headers
|
||||
assert "Authorization" not in prep.headers
|
||||
|
||||
def test_preserves_x_api_key_same_host(self):
|
||||
import requests
|
||||
s = self._build_session()
|
||||
prep = requests.PreparedRequest()
|
||||
prep.prepare(method="GET", url="https://cloud.comfy.org/foo",
|
||||
headers={"X-API-Key": "keep"})
|
||||
resp = requests.Response()
|
||||
orig = requests.PreparedRequest()
|
||||
orig.prepare(method="GET", url="https://cloud.comfy.org/bar", headers={})
|
||||
resp.request = orig
|
||||
s.rebuild_auth(prep, resp)
|
||||
assert prep.headers.get("X-API-Key") == "keep"
|
||||
|
||||
def test_strips_cookie_cross_host(self):
|
||||
import requests
|
||||
s = self._build_session()
|
||||
prep = requests.PreparedRequest()
|
||||
prep.prepare(method="GET", url="https://other.example.com/x",
|
||||
headers={"Cookie": "session=secret"})
|
||||
resp = requests.Response()
|
||||
orig = requests.PreparedRequest()
|
||||
orig.prepare(method="GET", url="https://cloud.comfy.org/foo", headers={})
|
||||
resp.request = orig
|
||||
s.rebuild_auth(prep, resp)
|
||||
assert "Cookie" not in prep.headers
|
||||
|
||||
|
||||
# =============================================================================
|
||||
# Video workflow detection
|
||||
# =============================================================================
|
||||
|
||||
class TestVideoWorkflow:
|
||||
def test_image_workflow(self, sd15_workflow):
|
||||
assert looks_like_video_workflow(sd15_workflow) is False
|
||||
|
||||
def test_animatediff_workflow(self, workflows_dir):
|
||||
import json
|
||||
wf = json.loads((workflows_dir / "animatediff_video.json").read_text(encoding="utf-8"))
|
||||
assert looks_like_video_workflow(wf) is True
|
||||
|
||||
def test_wan_workflow(self, video_workflow):
|
||||
assert looks_like_video_workflow(video_workflow) is True
|
||||
@@ -0,0 +1,184 @@
|
||||
"""Tests for extract_schema.py."""
|
||||
|
||||
from __future__ import annotations
|
||||
|
||||
|
||||
from extract_schema import (
|
||||
extract_schema,
|
||||
find_negative_prompt_node,
|
||||
find_positive_prompt_node,
|
||||
trace_to_node,
|
||||
)
|
||||
|
||||
|
||||
# =============================================================================
|
||||
# Connection tracing
|
||||
# =============================================================================
|
||||
|
||||
class TestConnectionTracing:
|
||||
def test_direct_link(self):
|
||||
wf = {
|
||||
"1": {"class_type": "CLIPTextEncode", "inputs": {"text": "x"}},
|
||||
"2": {"class_type": "KSampler",
|
||||
"inputs": {"positive": ["1", 0], "negative": ["1", 0]}},
|
||||
}
|
||||
assert trace_to_node(wf, ["1", 0]) == "1"
|
||||
|
||||
def test_through_reroute(self):
|
||||
wf = {
|
||||
"1": {"class_type": "CLIPTextEncode", "inputs": {"text": "x"}},
|
||||
"2": {"class_type": "Reroute", "inputs": {"input": ["1", 0]}},
|
||||
"3": {"class_type": "Reroute", "inputs": {"input": ["2", 0]}},
|
||||
}
|
||||
assert trace_to_node(wf, ["3", 0]) == "1"
|
||||
|
||||
def test_circular_safe(self):
|
||||
wf = {
|
||||
"1": {"class_type": "Reroute", "inputs": {"input": ["2", 0]}},
|
||||
"2": {"class_type": "Reroute", "inputs": {"input": ["1", 0]}},
|
||||
}
|
||||
# Should hit max_hops without infinite loop
|
||||
result = trace_to_node(wf, ["1", 0], max_hops=5)
|
||||
assert result in {"1", "2"} # any node, just don't hang
|
||||
|
||||
|
||||
class TestPositiveNegativeDetection:
|
||||
def test_basic(self, sd15_workflow):
|
||||
# In sd15_workflow.json node 6 is positive, node 7 is negative
|
||||
assert find_positive_prompt_node(sd15_workflow) == "6"
|
||||
assert find_negative_prompt_node(sd15_workflow) == "7"
|
||||
|
||||
def test_swapped_order(self):
|
||||
wf = {
|
||||
"3": {"class_type": "KSampler",
|
||||
"inputs": {
|
||||
"positive": ["7", 0], "negative": ["6", 0],
|
||||
"model": ["4", 0], "latent_image": ["5", 0],
|
||||
"seed": 1, "steps": 20, "cfg": 7.5,
|
||||
"sampler_name": "euler", "scheduler": "normal", "denoise": 1.0,
|
||||
}},
|
||||
"4": {"class_type": "CheckpointLoaderSimple", "inputs": {"ckpt_name": "x"}},
|
||||
"5": {"class_type": "EmptyLatentImage", "inputs": {"width": 512, "height": 512, "batch_size": 1}},
|
||||
"6": {"class_type": "CLIPTextEncode", "inputs": {"text": "ugly", "clip": ["4", 1]}},
|
||||
"7": {"class_type": "CLIPTextEncode", "inputs": {"text": "beautiful", "clip": ["4", 1]}},
|
||||
}
|
||||
# Now 7 is the positive (despite higher node ID)
|
||||
assert find_positive_prompt_node(wf) == "7"
|
||||
assert find_negative_prompt_node(wf) == "6"
|
||||
|
||||
|
||||
# =============================================================================
|
||||
# Schema extraction
|
||||
# =============================================================================
|
||||
|
||||
class TestExtractSchema:
|
||||
def test_basic_sd15(self, sd15_workflow):
|
||||
schema = extract_schema(sd15_workflow)
|
||||
params = schema["parameters"]
|
||||
assert "prompt" in params
|
||||
assert "negative_prompt" in params
|
||||
assert "seed" in params
|
||||
assert "steps" in params
|
||||
assert "cfg" in params
|
||||
assert "width" in params
|
||||
assert "height" in params
|
||||
|
||||
def test_prompt_value_correct(self, sd15_workflow):
|
||||
schema = extract_schema(sd15_workflow)
|
||||
# The positive prompt in the example is the landscape one
|
||||
assert "landscape" in schema["parameters"]["prompt"]["value"]
|
||||
assert "ugly" in schema["parameters"]["negative_prompt"]["value"]
|
||||
|
||||
def test_model_dependencies(self, sd15_workflow):
|
||||
schema = extract_schema(sd15_workflow)
|
||||
deps = schema["model_dependencies"]
|
||||
ckpts = [d["value"] for d in deps if d["folder"] == "checkpoints"]
|
||||
assert "v1-5-pruned-emaonly.safetensors" in ckpts
|
||||
|
||||
def test_output_nodes(self, sd15_workflow):
|
||||
schema = extract_schema(sd15_workflow)
|
||||
assert "9" in schema["output_nodes"]
|
||||
|
||||
def test_summary(self, sd15_workflow):
|
||||
schema = extract_schema(sd15_workflow)
|
||||
s = schema["summary"]
|
||||
assert s["has_negative_prompt"] is True
|
||||
assert s["has_seed"] is True
|
||||
assert s["is_video_workflow"] is False
|
||||
assert s["parameter_count"] > 5
|
||||
|
||||
def test_flux_workflow(self, flux_workflow):
|
||||
schema = extract_schema(flux_workflow)
|
||||
# Flux uses RandomNoise for seed
|
||||
assert schema["summary"]["has_seed"] is True
|
||||
# Flux has only positive prompt (no negative encoder)
|
||||
assert schema["summary"]["has_negative_prompt"] is False
|
||||
|
||||
def test_video_detected(self, video_workflow):
|
||||
schema = extract_schema(video_workflow)
|
||||
assert schema["summary"]["is_video_workflow"] is True
|
||||
|
||||
|
||||
class TestEmbeddingDeps:
|
||||
def test_extract_from_prompt(self):
|
||||
wf = {
|
||||
"1": {"class_type": "CheckpointLoaderSimple", "inputs": {"ckpt_name": "x"}},
|
||||
"5": {"class_type": "EmptyLatentImage",
|
||||
"inputs": {"width": 512, "height": 512, "batch_size": 1}},
|
||||
"6": {"class_type": "CLIPTextEncode",
|
||||
"inputs": {
|
||||
"text": "a cat, embedding:goodvibes, embedding:art:1.2",
|
||||
"clip": ["1", 1]
|
||||
}},
|
||||
"7": {"class_type": "CLIPTextEncode",
|
||||
"inputs": {
|
||||
"text": "ugly, embedding:badhands",
|
||||
"clip": ["1", 1]
|
||||
}},
|
||||
"3": {"class_type": "KSampler",
|
||||
"inputs": {
|
||||
"positive": ["6", 0], "negative": ["7", 0],
|
||||
"model": ["1", 0], "latent_image": ["5", 0],
|
||||
"seed": 1, "steps": 20, "cfg": 7.5,
|
||||
"sampler_name": "euler", "scheduler": "normal", "denoise": 1.0,
|
||||
}},
|
||||
"9": {"class_type": "SaveImage", "inputs": {"filename_prefix": "x", "images": ["3", 0]}},
|
||||
}
|
||||
schema = extract_schema(wf)
|
||||
names = [d["embedding_name"] for d in schema["embedding_dependencies"]]
|
||||
assert sorted(names) == ["art", "badhands", "goodvibes"]
|
||||
|
||||
|
||||
class TestDuplicateDeduplication:
|
||||
def test_two_ksamplers_get_unique_names(self):
|
||||
wf = {
|
||||
"1": {"class_type": "CheckpointLoaderSimple", "inputs": {"ckpt_name": "x"}},
|
||||
"5": {"class_type": "EmptyLatentImage",
|
||||
"inputs": {"width": 512, "height": 512, "batch_size": 1}},
|
||||
"6": {"class_type": "CLIPTextEncode", "inputs": {"text": "a", "clip": ["1", 1]}},
|
||||
"7": {"class_type": "CLIPTextEncode", "inputs": {"text": "b", "clip": ["1", 1]}},
|
||||
"3": {"class_type": "KSampler",
|
||||
"inputs": {
|
||||
"positive": ["6", 0], "negative": ["7", 0],
|
||||
"model": ["1", 0], "latent_image": ["5", 0],
|
||||
"seed": 42, "steps": 20, "cfg": 7.5,
|
||||
"sampler_name": "euler", "scheduler": "normal", "denoise": 1.0,
|
||||
}},
|
||||
"4": {"class_type": "KSampler",
|
||||
"inputs": {
|
||||
"positive": ["6", 0], "negative": ["7", 0],
|
||||
"model": ["1", 0], "latent_image": ["5", 0],
|
||||
"seed": 99, "steps": 30, "cfg": 8.0,
|
||||
"sampler_name": "euler", "scheduler": "normal", "denoise": 0.6,
|
||||
}},
|
||||
"9": {"class_type": "SaveImage", "inputs": {"filename_prefix": "x", "images": ["3", 0]}},
|
||||
}
|
||||
schema = extract_schema(wf)
|
||||
params = schema["parameters"]
|
||||
# Both seeds present with disambiguated names
|
||||
seed_keys = [k for k in params if "seed" in k]
|
||||
# Symmetric: both renamed (no bare "seed")
|
||||
assert "seed" not in params
|
||||
assert "seed_3" in params and "seed_4" in params
|
||||
assert params["seed_3"]["value"] == 42
|
||||
assert params["seed_4"]["value"] == 99
|
||||
@@ -0,0 +1,210 @@
|
||||
"""Tests for run_workflow.py — focuses on logic that doesn't require a server."""
|
||||
|
||||
from __future__ import annotations
|
||||
|
||||
|
||||
|
||||
from extract_schema import extract_schema
|
||||
from run_workflow import (
|
||||
ComfyRunner,
|
||||
download_outputs,
|
||||
inject_params,
|
||||
parse_input_image_arg,
|
||||
)
|
||||
|
||||
|
||||
class TestParseInputImageArg:
|
||||
def test_with_name(self, tmp_path):
|
||||
f = tmp_path / "x.png"
|
||||
f.write_text("x", encoding="utf-8")
|
||||
n, p = parse_input_image_arg(f"image={f}")
|
||||
assert n == "image"
|
||||
assert p == f
|
||||
|
||||
def test_without_name_defaults(self, tmp_path):
|
||||
f = tmp_path / "x.png"
|
||||
f.write_text("x", encoding="utf-8")
|
||||
n, p = parse_input_image_arg(str(f))
|
||||
assert n == "image"
|
||||
|
||||
def test_custom_name(self, tmp_path):
|
||||
f = tmp_path / "x.png"
|
||||
f.write_text("x", encoding="utf-8")
|
||||
n, p = parse_input_image_arg(f"mask_image={f}")
|
||||
assert n == "mask_image"
|
||||
|
||||
|
||||
class TestInjectParams:
|
||||
def test_basic_injection(self, sd15_workflow):
|
||||
schema = extract_schema(sd15_workflow)
|
||||
wf, warnings = inject_params(sd15_workflow, schema, {
|
||||
"prompt": "new prompt",
|
||||
"seed": 999,
|
||||
"steps": 25,
|
||||
})
|
||||
assert wf["6"]["inputs"]["text"] == "new prompt"
|
||||
assert wf["3"]["inputs"]["seed"] == 999
|
||||
assert wf["3"]["inputs"]["steps"] == 25
|
||||
assert warnings == []
|
||||
|
||||
def test_unknown_param_warns(self, sd15_workflow):
|
||||
schema = extract_schema(sd15_workflow)
|
||||
_, warnings = inject_params(sd15_workflow, schema, {"foobar": "x"})
|
||||
assert any("foobar" in w for w in warnings)
|
||||
|
||||
def test_seed_minus_one_randomizes(self, sd15_workflow):
|
||||
schema = extract_schema(sd15_workflow)
|
||||
wf, warnings = inject_params(sd15_workflow, schema, {"seed": -1})
|
||||
assert wf["3"]["inputs"]["seed"] != -1
|
||||
assert isinstance(wf["3"]["inputs"]["seed"], int)
|
||||
assert any("expanded" in w.lower() for w in warnings)
|
||||
|
||||
def test_randomize_seed_when_unset(self, sd15_workflow):
|
||||
schema = extract_schema(sd15_workflow)
|
||||
original = sd15_workflow["3"]["inputs"]["seed"]
|
||||
wf, warnings = inject_params(sd15_workflow, schema, {}, randomize_seed_if_unset=True)
|
||||
assert wf["3"]["inputs"]["seed"] != original
|
||||
assert isinstance(wf["3"]["inputs"]["seed"], int)
|
||||
|
||||
def test_does_not_mutate_original(self, sd15_workflow):
|
||||
schema = extract_schema(sd15_workflow)
|
||||
original_text = sd15_workflow["6"]["inputs"]["text"]
|
||||
inject_params(sd15_workflow, schema, {"prompt": "MUTATED"})
|
||||
assert sd15_workflow["6"]["inputs"]["text"] == original_text
|
||||
|
||||
def test_refuses_to_overwrite_link(self):
|
||||
wf = {
|
||||
"1": {"class_type": "CheckpointLoaderSimple", "inputs": {"ckpt_name": "x"}},
|
||||
"5": {"class_type": "EmptyLatentImage",
|
||||
"inputs": {"width": 512, "height": 512, "batch_size": 1}},
|
||||
"6": {"class_type": "CLIPTextEncode",
|
||||
"inputs": {"text": ["3", 0], "clip": ["1", 1]}}, # text is a link!
|
||||
"3": {"class_type": "KSampler",
|
||||
"inputs": {"seed": 1, "steps": 20, "cfg": 7.5,
|
||||
"sampler_name": "euler", "scheduler": "normal", "denoise": 1.0,
|
||||
"model": ["1", 0], "positive": ["6", 0], "negative": ["6", 0],
|
||||
"latent_image": ["5", 0]}},
|
||||
"9": {"class_type": "SaveImage", "inputs": {"filename_prefix": "x", "images": ["3", 0]}},
|
||||
}
|
||||
# Manually create a schema that has prompt pointing at 6.text
|
||||
schema = {
|
||||
"parameters": {
|
||||
"prompt": {"node_id": "6", "field": "text", "type": "string", "value": ""},
|
||||
}
|
||||
}
|
||||
wf2, warnings = inject_params(wf, schema, {"prompt": "literal value"})
|
||||
# The link should NOT have been overwritten
|
||||
assert wf2["6"]["inputs"]["text"] == ["3", 0]
|
||||
assert any("link" in w.lower() for w in warnings)
|
||||
|
||||
|
||||
# =============================================================================
|
||||
# Output download walk
|
||||
# =============================================================================
|
||||
|
||||
class TestDownloadOutputsWalk:
|
||||
"""Test that download_outputs walks the structure correctly."""
|
||||
|
||||
def test_handles_videos_plural(self, tmp_path, monkeypatch):
|
||||
"""Local ComfyUI uses 'videos'/'gifs' (plural) keys."""
|
||||
downloads = []
|
||||
|
||||
class FakeRunner:
|
||||
def download_output(self, *, filename, subfolder, file_type, output_dir, preserve_subfolder, overwrite):
|
||||
downloads.append((filename, subfolder, file_type))
|
||||
p = output_dir / filename
|
||||
p.parent.mkdir(parents=True, exist_ok=True)
|
||||
p.write_bytes(b"x")
|
||||
return p
|
||||
|
||||
outputs = {
|
||||
"9": {"images": [{"filename": "img1.png", "subfolder": "", "type": "output"}]},
|
||||
"10": {"videos": [{"filename": "vid1.mp4", "subfolder": "", "type": "output"}]},
|
||||
"11": {"gifs": [{"filename": "anim1.gif", "subfolder": "", "type": "output"}]},
|
||||
}
|
||||
|
||||
result = download_outputs(FakeRunner(), outputs, tmp_path)
|
||||
files = sorted(d["filename"] for d in result)
|
||||
assert files == ["anim1.gif", "img1.png", "vid1.mp4"]
|
||||
|
||||
def test_handles_video_singular_cloud(self, tmp_path):
|
||||
"""Cloud uses 'video' (singular)."""
|
||||
class FakeRunner:
|
||||
def download_output(self, *, filename, subfolder, file_type, output_dir, preserve_subfolder, overwrite):
|
||||
p = output_dir / filename
|
||||
p.parent.mkdir(parents=True, exist_ok=True)
|
||||
p.write_bytes(b"x")
|
||||
return p
|
||||
|
||||
outputs = {
|
||||
"10": {"video": [{"filename": "cloud.mp4", "subfolder": "", "type": "output"}]},
|
||||
}
|
||||
result = download_outputs(FakeRunner(), outputs, tmp_path)
|
||||
assert len(result) == 1
|
||||
assert result[0]["filename"] == "cloud.mp4"
|
||||
|
||||
def test_preserves_subfolder(self, tmp_path):
|
||||
"""When preserve_subfolder=True, server subfolder becomes local subdir."""
|
||||
class FakeRunner:
|
||||
def download_output(self, *, filename, subfolder, file_type, output_dir, preserve_subfolder, overwrite):
|
||||
if preserve_subfolder and subfolder:
|
||||
p = output_dir / subfolder / filename
|
||||
else:
|
||||
p = output_dir / filename
|
||||
p.parent.mkdir(parents=True, exist_ok=True)
|
||||
p.write_bytes(b"x")
|
||||
return p
|
||||
|
||||
outputs = {
|
||||
"9": {"images": [
|
||||
{"filename": "img.png", "subfolder": "myrun", "type": "output"},
|
||||
{"filename": "img.png", "subfolder": "otherrun", "type": "output"},
|
||||
]},
|
||||
}
|
||||
result = download_outputs(FakeRunner(), outputs, tmp_path, preserve_subfolder=True)
|
||||
files = [d["file"] for d in result]
|
||||
assert any("myrun" in f for f in files)
|
||||
assert any("otherrun" in f for f in files)
|
||||
# Both must exist (no collision)
|
||||
assert len({str(f) for f in files}) == 2
|
||||
|
||||
|
||||
# =============================================================================
|
||||
# ComfyRunner construction
|
||||
# =============================================================================
|
||||
|
||||
class TestRunnerConstruction:
|
||||
def test_local_default(self):
|
||||
r = ComfyRunner()
|
||||
assert r.is_cloud is False
|
||||
assert r.host == "http://127.0.0.1:8188"
|
||||
|
||||
def test_cloud_detection(self):
|
||||
r = ComfyRunner(host="https://cloud.comfy.org", api_key="abc")
|
||||
assert r.is_cloud is True
|
||||
assert "X-API-Key" in r.headers
|
||||
|
||||
def test_cloud_subdomain_detected(self):
|
||||
r = ComfyRunner(host="https://staging.cloud.comfy.org", api_key="abc")
|
||||
assert r.is_cloud is True
|
||||
|
||||
def test_partner_key_does_not_pollute_extra_data(self):
|
||||
r = ComfyRunner(host="https://cloud.comfy.org", api_key="auth-key")
|
||||
# No partner-key set → no extra_data should appear in submitted prompt
|
||||
# (This is a static check; runtime check happens in submit())
|
||||
assert r.partner_key is None
|
||||
|
||||
def test_url_routing_local(self):
|
||||
r = ComfyRunner()
|
||||
url = r._url("/prompt")
|
||||
assert url == "http://127.0.0.1:8188/prompt"
|
||||
|
||||
def test_url_routing_cloud(self):
|
||||
r = ComfyRunner(host="https://cloud.comfy.org", api_key="x")
|
||||
url = r._url("/prompt")
|
||||
assert url == "https://cloud.comfy.org/api/prompt"
|
||||
|
||||
def test_url_routing_cloud_history_renamed(self):
|
||||
r = ComfyRunner(host="https://cloud.comfy.org", api_key="x")
|
||||
url = r._url("/history/abc-123")
|
||||
assert url == "https://cloud.comfy.org/api/history_v2/abc-123"
|
||||
@@ -0,0 +1,86 @@
|
||||
# Example Workflows
|
||||
|
||||
These are starter API-format workflows for the most common tasks. They're
|
||||
ready to run with `scripts/run_workflow.py` once you've installed (or have
|
||||
cloud access to) the listed models.
|
||||
|
||||
| File | Purpose | Required models | Min VRAM |
|
||||
|------|---------|-----------------|----------|
|
||||
| `sd15_txt2img.json` | SD 1.5 text-to-image (512×512) | SD1.5 checkpoint, e.g. `v1-5-pruned-emaonly.safetensors` | 4 GB |
|
||||
| `sdxl_txt2img.json` | SDXL text-to-image (1024×1024) | `sd_xl_base_1.0.safetensors` | 8 GB |
|
||||
| `flux_dev_txt2img.json` | Flux Dev text-to-image (1024×1024) | `flux1-dev.safetensors`, `t5xxl_fp16.safetensors`, `clip_l.safetensors`, `ae.safetensors` | 24 GB (or use `flux1-dev-fp8`) |
|
||||
| `sdxl_img2img.json` | SDXL image-to-image | SDXL checkpoint | 8 GB |
|
||||
| `sdxl_inpaint.json` | SDXL inpainting (image + mask) | SDXL checkpoint | 8 GB |
|
||||
| `upscale_4x.json` | Standalone 4× ESRGAN upscale | `4x-UltraSharp.pth` (or any upscaler) | 4 GB |
|
||||
| `animatediff_video.json` | AnimateDiff text-to-video (16 frames) | SD1.5 checkpoint, `mm_sd_v15_v2.ckpt` motion module | 8 GB |
|
||||
| `wan_video_t2v.json` | Wan 2.x text-to-video (~33 frames) | `wan2.2_t2v_1.3B_fp16.safetensors`, `umt5_xxl_fp16.safetensors`, `wan_2.1_vae.safetensors` | 24 GB |
|
||||
|
||||
## Quick start
|
||||
|
||||
```bash
|
||||
# Run a workflow with prompt injection
|
||||
python3 ../scripts/run_workflow.py \
|
||||
--workflow sdxl_txt2img.json \
|
||||
--args '{"prompt": "majestic eagle in flight", "seed": 12345, "steps": 35}' \
|
||||
--output-dir ./out
|
||||
|
||||
# Img2img: upload an input image first via the script's helper
|
||||
python3 ../scripts/run_workflow.py \
|
||||
--workflow sdxl_img2img.json \
|
||||
--input-image image=./photo.png \
|
||||
--args '{"prompt": "make it watercolor", "denoise": 0.6}' \
|
||||
--output-dir ./out
|
||||
|
||||
# Cloud (set API key once)
|
||||
export COMFY_CLOUD_API_KEY="comfyui-..."
|
||||
python3 ../scripts/run_workflow.py \
|
||||
--workflow flux_dev_txt2img.json \
|
||||
--args '{"prompt": "a fox in a misty forest"}' \
|
||||
--host https://cloud.comfy.org \
|
||||
--output-dir ./out
|
||||
|
||||
# What can I tweak in this workflow?
|
||||
python3 ../scripts/extract_schema.py sdxl_txt2img.json --summary-only
|
||||
|
||||
# Are all required models / nodes installed?
|
||||
python3 ../scripts/check_deps.py wan_video_t2v.json
|
||||
```
|
||||
|
||||
## Notes
|
||||
|
||||
- **Inpaint masks**: white pixels = "regenerate this region", black = preserve.
|
||||
ComfyUI's `LoadImageMask` reads the **red channel** by default; export your
|
||||
mask as a single-channel image or as a normal RGB where red==intensity.
|
||||
|
||||
- **Denoise strength** in img2img: `0.0` = output identical to input,
|
||||
`1.0` = ignore input entirely. Sweet spot is usually 0.4–0.7.
|
||||
|
||||
- **Flux Dev** needs ~24 GB VRAM in its base form. The `flux1-dev-fp8.safetensors`
|
||||
variant (already on Comfy Cloud) cuts that roughly in half.
|
||||
|
||||
- **Video workflows** can take many minutes. The skill auto-detects video
|
||||
output nodes and bumps the default timeout to 900s. Override with `--timeout 1800`.
|
||||
|
||||
- These JSON files are deliberately **API format** (top-level keys are node IDs
|
||||
with `class_type`), not editor format. To open them in ComfyUI's web UI for
|
||||
visual editing, use `Workflow → Load (API Format)` or `Workflow → Open` and
|
||||
follow the prompt.
|
||||
|
||||
## Cloud vs local model names
|
||||
|
||||
Comfy Cloud's preinstalled checkpoints sometimes have a `-fp16` suffix
|
||||
(`v1-5-pruned-emaonly-fp16.safetensors`) while the canonical local download
|
||||
keeps the original name (`v1-5-pruned-emaonly.safetensors`). The example
|
||||
workflows use the local-canonical names. When running on cloud, override with:
|
||||
|
||||
```bash
|
||||
python3 ../scripts/run_workflow.py \
|
||||
--workflow sd15_txt2img.json \
|
||||
--args '{"ckpt_name": "v1-5-pruned-emaonly-fp16.safetensors", "prompt": "..."}' \
|
||||
--host https://cloud.comfy.org
|
||||
```
|
||||
|
||||
The `ckpt_name`, `vae_name`, `lora_name`, `unet_name`, etc. are all exposed
|
||||
as controllable parameters by `extract_schema.py` — discover what's installed
|
||||
with `comfy model list` (local) or `curl /api/experiment/models/checkpoints`
|
||||
(cloud).
|
||||
@@ -0,0 +1,64 @@
|
||||
{
|
||||
"_comment": "AnimateDiff text-to-video at 16 frames. Required: comfyui-animatediff-evolved + comfyui-videohelpersuite custom nodes; SD1.5 checkpoint; AnimateDiff motion module (e.g. mm_sd_v15_v2.ckpt in models/animatediff_models/). Outputs a webp animation.",
|
||||
"3": {
|
||||
"class_type": "KSampler",
|
||||
"_meta": {"title": "KSampler"},
|
||||
"inputs": {
|
||||
"seed": 42, "steps": 25, "cfg": 7.5,
|
||||
"sampler_name": "dpmpp_sde", "scheduler": "karras", "denoise": 1.0,
|
||||
"model": ["10", 0],
|
||||
"positive": ["6", 0],
|
||||
"negative": ["7", 0],
|
||||
"latent_image": ["5", 0]
|
||||
}
|
||||
},
|
||||
"4": {
|
||||
"class_type": "CheckpointLoaderSimple",
|
||||
"_meta": {"title": "Checkpoint"},
|
||||
"inputs": {"ckpt_name": "v1-5-pruned-emaonly.safetensors"}
|
||||
},
|
||||
"5": {
|
||||
"class_type": "EmptyLatentImage",
|
||||
"_meta": {"title": "Latent (16 frames)"},
|
||||
"inputs": {"width": 512, "height": 512, "batch_size": 16}
|
||||
},
|
||||
"6": {
|
||||
"class_type": "CLIPTextEncode",
|
||||
"_meta": {"title": "Positive Prompt"},
|
||||
"inputs": {"text": "a hot air balloon drifting over a mountain valley, sunset, cinematic", "clip": ["4", 1]}
|
||||
},
|
||||
"7": {
|
||||
"class_type": "CLIPTextEncode",
|
||||
"_meta": {"title": "Negative Prompt"},
|
||||
"inputs": {"text": "low quality, blurry, deformed, watermark", "clip": ["4", 1]}
|
||||
},
|
||||
"8": {
|
||||
"class_type": "VAEDecode",
|
||||
"_meta": {"title": "VAE Decode"},
|
||||
"inputs": {"samples": ["3", 0], "vae": ["4", 2]}
|
||||
},
|
||||
"9": {
|
||||
"class_type": "VHS_VideoCombine",
|
||||
"_meta": {"title": "Video Combine"},
|
||||
"inputs": {
|
||||
"frame_rate": 8.0,
|
||||
"loop_count": 0,
|
||||
"filename_prefix": "animatediff",
|
||||
"format": "video/h264-mp4",
|
||||
"pingpong": false,
|
||||
"save_output": true,
|
||||
"images": ["8", 0]
|
||||
}
|
||||
},
|
||||
"10": {
|
||||
"class_type": "ADE_AnimateDiffLoaderWithContext",
|
||||
"_meta": {"title": "AnimateDiff Loader"},
|
||||
"inputs": {
|
||||
"model": ["4", 0],
|
||||
"model_name": "mm_sd_v15_v2.ckpt",
|
||||
"beta_schedule": "sqrt_linear (AnimateDiff)",
|
||||
"motion_scale": 1.0,
|
||||
"apply_v2_models_properly": true
|
||||
}
|
||||
}
|
||||
}
|
||||
Some files were not shown because too many files have changed in this diff Show More
Reference in New Issue
Block a user