justineightyone/joycaption-batch-webui

JoyCaption Batch WebUI

A single-window local Gradio UI for JoyCaption Beta One (8B captioning VLM) and JoyTag (fast ViT Danbooru tagger), built for LoRA / fine-tune dataset prep:

• 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

The UI opens at http://127.0.0.1:7861 (port chosen to never collide with ComfyUI's 8188 or A1111's 7860).

Flags: --nf4 (4-bit), --port N, --listen (LAN access), --cache-dir PATH (where models download; default ./models).

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

Defaults are tuned for Ampere+ GPUs: bf16 weights, SDPA attention, TF32 matmul, whole model on GPU. On an RTX 3090 that's roughly 6–10 s per caption in bf16. JoyTag is near-instant per image.

⚠️ Gradio version

Pinned to gradio==6.12.0. Gradio 6.14.0 has a rendering regression that hides the Caption Type / Caption Length dropdowns and stops the prompt from updating. If the dropdowns ever look broken, you've been auto-upgraded — fix with:

pip install gradio==6.12.0

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.

This repo is licensed Apache-2.0 (see LICENSE).