haoyiyin/mflux-cover

When to Use

Use when the user asks to generate any cover image, thumbnail, banner, poster, or header from a text description. Triggers include: "generate a cover", "create a thumbnail", "make a banner", "设计封面", "生成封面图", or any request involving creating images from prompts with specified dimensions.

This skill uses a two-step pipeline:

1. mflux (FLUX.2 4-bit, Apple MLX) generates the AI background image
2. HTML/CSS + Playwright Chromium renders sharp typography on top

Do NOT use for: general image generation without text overlay, image editing, upscaling, or non-cover use cases.

Requirements

• macOS with Apple Silicon (M1+)
• 16 GB+ RAM recommended (8 GB may work with reduced resolution)
• mflux: brew install uv && uv tool install mflux
• Playwright: pip install playwright && playwright install chromium
• First run downloads FLUX.2 model (~2-4 GB), then fully offline

Procedure

1. Check prerequisites: python3 cover_generator.py --detect — both mflux and Playwright+Chromium should show ✓
2. Determine dimensions: Use presets or exact W×H:
   • youtube-thumbnail (1280×720), twitter-header (1500×500), blog-cover (1200×630)
   • instagram-post (1080×1080), facebook-cover (1640×624), linkedin-banner (1584×396)
   • podcast-cover (3000×3000), github-social (1280×640), story (1080×1920)
3. Choose layout: --layout bottom (default), centered, hero, top
4. Choose gradient: --gradient dark (default), subtle, light, none
5. Generate: python3 cover_generator.py -p "description" --preset blog-cover
6. Optimize prompts: Use English for --prompt (AI background), keep original language for --title (visible text)
7. Verify: Output file should exist with correct dimensions

Pitfalls

• mflux requires Apple Silicon (M1+) — Intel Macs cannot run it
• Playwright installs Chromium separately (~300 MB download)
• First mflux run downloads FLUX.2 model (~2-4 GB); subsequent runs are offline
• Chinese text in AI prompts may produce lower quality backgrounds — translate to English for --prompt, use --title for the visible Chinese text
• Very large dimensions (>3840 px) may be slow. For A4 print (3508 px), expect 3-5 s render time
• Prompt quality heavily impacts the background: be specific about style (e.g., 'minimalist watercolor', 'dark cinematic', 'clean abstract gradient')
• mflux rounds dimensions to multiples of 64 — the background image may be slightly smaller than requested; the final overlay step corrects to exact dimensions

Verification

1. python3 cover_generator.py --detect — mflux ✓, Playwright+Chromium ✓
2. Full pipeline test: python3 cover_generator.py -p 'A serene mountain lake at dawn' -o test.png
3. Verify output dimensions match input
4. Raw mode test: python3 cover_generator.py -p 'test' --preset youtube-thumbnail --no-overlay -o raw.png