| --- |
| 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)). |
|
|
