JoyCaption Batch WebUI

• Batch folder captioning — point it at a dataset folder and it writes a .txt next to each image (kohya / diffusion-pipe style), with skip-existing and an optional trigger-word prefix.
• All JoyCaption caption types — Descriptive, Straightforward, Stable Diffusion prompt, Danbooru/e621/Rule34/booru tags, Art Critic, Product Listing, and more, plus length control and the full extra-options list, with a live editable prompt.
• JoyTag tab — near-instant Danbooru tagging (~0.4 GB VRAM), single image with confidence scores or whole folders, threshold slider, underscores→spaces toggle. Loads/unloads independently of the big model.
• VRAM control — Load/Unload buttons free VRAM without closing the app (handy for switching back to ComfyUI), and a 4-bit NF4 mode (~7 GB) lets it run alongside a diffusion UI on one GPU.
• Streaming output, copy-to-clipboard, LAN mode (--listen).

🖥️ This is a local tool, not a hosted demo — batch mode reads dataset folders on your own disk, so clone it and run it on your own GPU. Main repo: https://github.com/justineightyone/joycaption-batch-webui (this HF repo is a mirror).

Requirements

• NVIDIA GPU: ~18 GB VRAM in bf16 (RTX 3090/4090 class) or ~7 GB with --nf4 (RTX 3060 12GB and up work fine)
• Python 3.10+
• ~17 GB disk for the JoyCaption model (auto-downloaded on first caption into ./models)

Install & run (Windows)

git clone https://github.com/justineightyone/joycaption-batch-webui
cd joycaption-batch-webui
install_windows.bat
start_windows.bat          (full quality, ~18 GB VRAM)
start_windows_lowvram.bat  (4-bit NF4, ~7 GB VRAM)

Install & run (Linux)

git clone https://github.com/justineightyone/joycaption-batch-webui
cd joycaption-batch-webui
bash install_linux.sh
./start_linux.sh           # add --nf4 for the ~7 GB mode

Usage notes

• The model loads on the first caption (or the Load button). The Unload button frees VRAM without closing the app.
• Batch Folder writes image_name.txt next to each image. Skip existing is on by default, so you can re-run a folder after adding images.
• The prompt box is editable — the dropdowns build the prompt, but you can hand-tweak it before captioning.
• JoyTag is a different model (a 91M-param ViT classifier, not the VLM) — use it when you want fast, consistent booru tags rather than prose.

Performance

⚠️ Gradio version

Credits & license

• JoyCaption and JoyTag models and original code by fancyfeast (fpgaminer) — Apache-2.0. JoyCaption is free, open, and uncensored; if you find it useful, go star the upstream project.
• UI derived from the HF Spaces fancyfeast/joy-caption-beta-one and MegaTronX/JoyCaptionBetaOne.
• joytag_models.py is from the official fancyfeast/joytag Space.