File size: 4,359 Bytes
99e38eb | 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 | ---
license: apache-2.0
pipeline_tag: image-text-to-text
tags:
- captioning
- joycaption
- joytag
- dataset-preparation
- gradio
base_model:
- fancyfeast/llama-joycaption-beta-one-hf-llava
- fancyfeast/joytag
---
# JoyCaption Batch WebUI
A single-window local Gradio UI for **[JoyCaption Beta One](https://huggingface.co/fancyfeast/llama-joycaption-beta-one-hf-llava)** (8B captioning VLM) and **[JoyTag](https://huggingface.co/fancyfeast/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)](https://github.com/fpgaminer/joycaption) — 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](https://huggingface.co/spaces/fancyfeast/joy-caption-beta-one) and [MegaTronX/JoyCaptionBetaOne](https://huggingface.co/spaces/MegaTronX/JoyCaptionBetaOne).
- `joytag_models.py` is from the official [fancyfeast/joytag](https://huggingface.co/spaces/fancyfeast/joytag) Space.
This repo is licensed **Apache-2.0** (see [LICENSE](LICENSE)).
|