File size: 3,729 Bytes
e2dfa95 5670bcb 458c525 5670bcb 458c525 5670bcb 0e838bb 5670bcb | 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 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 | ---
license: mit
tags:
- image-captioning
- dataset-tools
- lora
- pytorch
pipeline_tag: image-to-text
library_name: transformers
pretty_name: Caption Tool
---
# Caption Tool
A small, friendly tool that writes text descriptions (captions) for every image
in a folder, all on your own computer.
- **No API key. No account. No internet** (after the first-time model download).
- **Private:** your images never leave your machine.
- **Lightweight:** runs on a GPU with as little as **2 GB of VRAM**.
- **Whole folders at once:** point it at a directory and it captions everything.
Made by [oohfixer.com](https://oohfixer.com).
---
## What it does
For every image it finds, Caption Tool writes a matching text file next to it:
```
vacation.jpg → vacation.txt
cat.png → cat.txt
```
That's it. The caption sits in the `.txt` file, ready to use for training
image models, organizing photos, or search.
---
## Install
You need **Python 3.13 or older** (3.14 doesn't work with this tool's
dependencies).
### One command (recommended)
Open a terminal and run:
```bash
curl -fsSL https://oohfixer.com/caption-tool/install.sh | bash
```
This downloads the tool, installs what it needs in its own isolated
environment, and adds a **`captions`** command you can run from anywhere. When it
finishes, open a new terminal (or run `source ~/.bashrc`).
Then just type:
```bash
captions
```
### Manual install
If you'd rather set it up by hand:
1. Download this folder and open a terminal in it.
2. Install the requirements:
```bash
pip install -r requirements.txt
```
3. Run it:
```bash
python caption.py
```
---
## Use it
Just run it:
```bash
python caption.py
```
It will ask you for a folder of images, show the settings, and caption them.
Sit back, a progress bar shows how far it's gotten.
### Want to skip the questions?
If you already know what you want, you can do it in one line:
```bash
python caption.py --path "/path/to/your/images"
```
Useful extras:
| Option | What it does |
| --- | --- |
| `--path "FOLDER"` | Caption this folder right away (no prompt). |
| `--force` | Re-caption images that already have a `.txt` file. |
| `--model florence2-base` | Pick a different model (see below). |
| `--max-new-tokens 512` | Allow longer captions. |
---
## Choosing a model
When you run it, you can pick which AI model writes the captions. Bigger = more
detailed, but uses more VRAM.
| Model | Size | Best for |
| --- | --- | --- |
| **florence2-large** (default) | ~1.5 GB | Slightly less accurate. Needs a normal GPU. |
| **florence2-base** | ~0.45 GB | **2 GB GPUs**, or when you want it fast. |
If your card only has 2 GB of VRAM, choose **florence2-base**.
---
## Prefix and suffix (optional)
If you're captioning images to train your own image model, you may want a
**trigger word** on every caption (for example, your subject's name). Set a
**prefix** and the tool adds it to the front of every caption automatically.
A **suffix** does the same at the end.
Leave them empty if you just want plain descriptions.
---
## Settings
Settings are stored in `caption_config.json` next to the script. You can edit
that file directly, or change things from the tool's menu. The defaults:
- Skip images that already have a caption (so re-running is safe).
- At least ~15 words per caption (it re-captions anything shorter).
- 256 token cap on caption length.
---
## Questions
- **Does it need to be online?** Only the very first time, to download the
model. After that, everything runs offline.
- **Where do my images go?** Nowhere. They're processed locally and the caption
is saved next to each image.
- **What image types?** jpg, png, webp, bmp, tiff.
|