# alt-text-fill: reviewed alt text for the media library

[alt-text-fill](https://github.com/IndianOpinion/alt-text-fill) is a WordPress plugin that finds every image in the media library with no alt text, asks a vision model you choose to describe each one from the image and the post around it, and puts every suggestion on a review list. It is for site operators with a large backlog of undescribed images. Licence MIT. Version v0.1.0, released 19 November 2026.

It was written from scratch from an idea, as one of the utilities described on the [engineering blog](https://indianopinion.org/blog/). It has not run on a live site, and the PRD quotes no measured result.

## The problem

Alt text is what a screen reader says in place of a picture, and what a search engine or an assistant reads when it cannot see one. Most media libraries hold many images with none. Fixing them by hand is slow, so it does not happen. The shortcuts go wrong in predictable ways.

- Copying the post title into the alt field. The title describes the story, not the picture. On a news site the picture is often a file photo or a logo slate, so the title is confidently wrong.

- Copying the file name, which tells a reader nothing.

- Running a model over the whole library and writing whatever comes back. Models refuse, wrap answers in prose, open every line with "An image of", guess who a person is, and repeat the headline. A bulk write with no review and no undo turns a missing field into a wrong one at scale.

- Giving a shared image, such as a placeholder or a logo, a description taken from one post that uses it. Every other post then carries a wrong description.

## What it does

- Scans for images whose alt is missing, empty or only whitespace, including non-breaking and zero-width characters. An optional weak-alt mode also counts file names and filler words as empty.

- Builds a context from the post that uses the image, sends the image and context to an adapter, and validates the answer.

- Puts each suggestion on a review screen, where a person approves, edits, rejects, retries or marks the image decorative.

- Records every write with the exact previous state, so undo works for one entry, a whole run or everything since a time.

- Provides a dry run that shows, per image, whether it would be sent and why not, without any call or write.

## How it works

Scanner reads image attachments by ID range, 500 at a time, with a stored cursor that wraps. It reads post and meta rows only and never opens a file. Context\UsageFinder finds the posts that use an image by parent, featured image, image block ID, wp-image-<id> class and file URL. Context\ContextBuilder picks one post and builds the context: caption, description, post title, two paragraphs either side of the image and the nearest heading, with HTML, shortcodes and URLs removed. An image used by more posts than a threshold, or listed as a placeholder, gets no post context at all.

Image\ImagePreparer chooses the smallest intermediate size of at least 1,024 pixels, scales it in memory with GD or Imagick, reads the real type from the bytes and refuses anything over the byte limit. Runner makes the call through a VisionAdapter. The one bundled adapter speaks an OpenAI-compatible chat completions endpoint with image parts, as the README describes. The prompt carries the context in a delimited block marked as data.

Validator rejects empty or short text, refusals, links, file names, and copies of the post title or file name. Writer is the only code that changes alt text, and Undo restores absent as absent and a string byte for byte.

wp alt-text-fill run --dry-run
wp alt-text-fill run --user=<editor>
wp alt-text-fill undo --since=<datetime>

State lives in three tables for suggestions, entries and runs, plus a few options. Retention is 30 days for pending suggestions, 90 for decided ones and runs, and 365 for entries.

## Guard rails

- No write without approval. There is no auto-approve and no "approve all", on screen or in WP-CLI.

- A new install starts in dry-run-only mode. Real runs are refused until it is turned off and an adapter is set.

- The per-run cap is 20 images and the daily cap is 200 model calls, with failed and rejected calls counted. An optional money cap uses reported tokens and prices you enter, and nothing is shipped.

- The kill switch, a constant named ALT_TEXT_FILL_DISABLED, wins over the setting and is checked before every call, including inside a run already going.

- A 429 ends the run and waits for Retry-After. A 401, 402, 403 or quota error pauses the plugin until an administrator resumes it. Five failures in a row open a circuit breaker.

- Before a write, the current alt is read again. If someone filled it meanwhile, the suggestion is superseded and nothing is written. If the file changed, the suggestion is stale and cannot be approved.

- Drafts, private, pending and password-protected posts are excluded unless you include them. Keys are shown as their last four characters and redacted from logs.

- Uninstall never changes or deletes any alt text, including text the plugin wrote.

## What review changed

An independent review of the build PR fixed these before the merge.

- The run lock had a race. add_option() upserts, so two runs could both win. It now uses INSERT IGNORE plus a compare-and-swap update, tested with two MySQL connections.

- Queue jobs and "Test connection" spent outside the lock, so the daily cap could be passed. They now take the run lock.

- A dry run moved the scan cursor, so the real run after it skipped what the dry run had shown. A dry run no longer writes the cursor.

- A tiny PNG declaring 30,000 by 30,000 pixels went to the image library. Canvases over 25 million pixels are now skipped as too large.

The review also fixed undo of an undo, which left the original entry marked undone, and approval of a "suggest decorative" row, which skipped the re-read and could mark an image decorative over an editor's text.

## Limits and what is next

- The block editor copies alt text into post content when an image is inserted. Changing the attachment's alt does not change posts already written. An opt-in render fill covers only images with no alt attribute at all.

- Only the alt field is written, never captions, titles or descriptions.

- Animated GIF and WebP are skipped, and SVG is never sent.

- One language per call, and one bundled real adapter. The money cap is an estimate, not a bill.

No issues are open on the repo. Test status: 182 PHPUnit tests with 895 assertions pass on PHP 8.3, including seven integration tests against a throwaway MySQL 8.0, with PHPStan level 8 and phpcs clean. The unit suite runs on a WordPress stub layer and model calls are tested against a fake adapter. This is v0.1.0. The CI workflow has not run on GitHub, and there is no production mileage.

## Install

It needs WordPress 6.4 or later and PHP 8.1 or later. GD or Imagick is optional. Without Composer, copy the directory to wp-content/plugins/alt-text-fill/ and activate it. With Composer:

composer require indianopinion/alt-text-fill

The package is not on Packagist yet, so add a Composer vcs repository entry for https://github.com/IndianOpinion/alt-text-fill first.

[All 47 utilities](https://indianopinion.org/blog/open-source/) · [alt-text-fill on GitHub](https://github.com/IndianOpinion/alt-text-fill)

Canonical: https://indianopinion.org/blog/open-source/alt-text-fill/

AI disclosure: Every summary and comment here is written by AI and published automatically, without a person reviewing each article. We do no original reporting. How this works: https://indianopinion.org/ai-use-policy/
