Alt Text and Descriptions

Alt Text and Descriptions

PhotoPress sets each image's alt text and description from the metadata embedded in its file, through templates of words and metadata fields. The settings are the Alt Text and Description cards of the Metadata tab under PhotoPress › Settings.

Requirements

• WordPress 6.6 or later.

Settings

Open PhotoPress › Settings and select the Metadata tab.

The Alt Text card with the default template.

Alt Text

Control	What it does	Default
Alt Text switch ("Set each image's alt text from its metadata when it is uploaded.")	Turns metadata-driven alt text on or off. Saves at once.	On
Use the alt text written in the file, when it has one	Uses the file's Alt Text (Accessibility) field, as Lightroom Classic and Photoshop write it, in place of the template.	Checked
Alt Text Template	Words and fields that make the alt text.	[photoshop:Headline]. [photopress:stringOfKeywords]. (shown as Headline. Keywords.)
Save	Saves the card. Applies to images uploaded from now on.	—
Save and reprocess all images	Saves, then starts the Reprocess alt text job over every image, after a confirmation. Alt text written by hand is replaced.	—
Advanced options › Empty the alt text of images whose files have no metadata for the template	With Save and reprocess, removes the alt text of an image whose file gives no alt text at all. Unchecked, it is kept.	Unchecked

Description

The Description card.

Control	What it does	Default
Description switch ("Set each image's description from its metadata when it is uploaded or its file is replaced.")	Turns metadata-driven descriptions on or off. Saves at once.	Off
Description Template	Words and fields that make the description. Empty: descriptions are left alone.	Empty
Save	Saves the card.	—
Save and reprocess all images	Saves, then starts the Reprocess descriptions job over every image, after a confirmation. Descriptions written by hand are replaced.	—
Advanced options › Empty the description of images whose files have no metadata for the template	With Save and reprocess, empties the description of an image whose file has none of the template's fields. Unchecked, it is kept.	Unchecked

The job's progress shows under its card, with Cancel while it runs.

Editing a template

The template is one line of text. Each field shows as a pill with its name and a × to remove it.

1. Type the words around the fields.
2. Click Insert field and choose a field. It goes in at the caret.
3. Read the line under the field: For example: "…" shows what a photo with every field gets.

A field typed in square brackets, such as [dc:rights], becomes a pill when you leave the field. Pasted text is pasted as plain text. Enter does nothing. The template is saved as text with each field's tag in square brackets (template-editor.js).

Insert field offers these fields:

Group	Field	Tag
The photo	Headline	photoshop:Headline
	Title	dc:title
	Description	dc:description
	Keywords	photopress:stringOfKeywords
	Person Shown	Iptc4xmpExt:PersonInImage
	Organization Shown	Iptc4xmpExt:OrganisationInImageName
	Event	Iptc4xmpExt:Event
Where it was taken	Sublocation	Iptc4xmpCore:Location
	City	photoshop:City
	State/Province	photoshop:State
	Country	photoshop:Country
Who made it	Creator	dc:creator
	Credit Line	photoshop:Credit
	Copyright Notice	dc:rights
Camera	Camera	photopress:camera
	Lens	aux:Lens

Any other XMP property can be typed in brackets. It shows as a pill named by its tag.

How it works

Filling a template

Each [tag] is replaced by the file's value as plain text: markup is removed and a list is joined with commas (metadata.php#L1578). Then:

• A template with no field that has a value gives nothing.
• Separators left by empty fields collapse to one: . , ; : | – — -. [photoshop:Headline]. [dc:title]. with only a title gives Golden Hour., not . Golden Hour..
• Separators at the start are removed, and runs of spaces become one.

Keywords (photopress:stringOfKeywords) is the file's dc:subject keywords, joined with commas, each once. A prefixed keyword gives the part after its first prefix separator: person: Jane gives Jane. The separators are the Prefix separators of Image Taxonomies, or : when that is empty (XmpReader.php#L118).

Camera (photopress:camera) is the cleaned camera name the Cameras taxonomy uses. See Image Taxonomies.

Alt text

PhotoPress takes the first of these that gives text (metadata.php#L1534):

1. The file's Alt Text (Accessibility), Iptc4xmpCore:AltTextAccessibility, when Use the alt text written in the file is checked.
2. The Alt Text Template.
3. The file's description, dc:description.
4. The file's title, dc:title.

When none gives text, the image's alt text is left as it is. The Reprocess alt text job with Empty the alt text… checked removes it instead.

Description

The description is the Description Template filled from the file. There is no fallback. When the switch is off or the template is empty, descriptions are not touched.

When they are set

Event	Alt text	Description
Upload (add_attachment)	Set. Kept as it is when the file gives none.	Set. Emptied when the file has none of the fields.
File replaced through PhotoPress's replace route	Set as on upload when reprocess_metadata is true (the default)	Set from the new file whether or not reprocess_metadata is true
File replaced with Enable Media Replace	Set as on upload	Set as on upload
Reprocess all images (Image Taxonomies card, job metadata.reprocess)	Set as on upload	Set as on upload
A Save and reprocess on an image taxonomy (job metadata.reprocess with taxonomies)	Not touched	Not touched
Reprocess alt text (job metadata.alt_text)	Set. Removed when the file gives none and force is true.	Not touched
Reprocess descriptions (job metadata.description)	Not touched	Set. Emptied when the file has none of the fields and force is true. Otherwise kept.

force is true when Empty the … of images whose files have no metadata for the template was checked. Each job works ten images per batch, rests between batches, and waits while the server is busy. An image whose file is missing is recorded as failed.

Alt text is written only when it differs from the stored value. A description is written only when it differs from the image's current description.

What is left alone

• Images that are not images (PDFs, video, audio) and attachments without a file.
• Alt text, when the Alt Text switch is off. The Reprocess alt text job then changes nothing.
• Descriptions, when the Description switch is off or the template is empty.
• Alt text and descriptions, on a reprocess limited to image taxonomies.
• The title and caption. WordPress sets them on upload from the file's IPTC or EXIF. PhotoPress fills a missing title from dc:title and a missing caption from dc:description, on upload and on a replace (metadata.php#L845).
• Image blocks already in posts keep the alt text they were inserted with. PhotoPress's replace route updates them only with sync_embedded.

WordPress integration

Hook	Type	Code	Purpose
add_attachment	action	metadata.php#L62	Reads a new image's file: terms (while Image Taxonomies is on), then description, then alt text.
photopress_attachment_file_replaced	action (PhotoPress)	metadata.php#L63	The same for a replaced file, unless reprocess_metadata is false.
photopress_attachment_description	filter (PhotoPress)	metadata.php#L54	The description of a replaced file, from the template. When the description is off, the value given is kept.
wp_read_image_metadata	filter	metadata.php#L46	Reads the title and caption from XMP when IPTC and EXIF have none. Adds camera and LightSource to the image's metadata.
init	action	metadata.php#L49	For settings saved before the Description switch existed: sets description_enable on where a template is set.

Core functions relied on: update_post_meta() and delete_post_meta() for _wp_attachment_image_alt, wp_update_post() for post_content, get_attached_file(), wp_attachment_is_image() and wp_strip_all_tags().

Data stored

Name	Kind	Holds
photopress_core_metadata	option	alt_text_enable, alt_text_from_file, alt_text_template, description_enable, description_template. Read and written through /wp/v2/settings.
_wp_attachment_image_alt	post meta	The alt text, WordPress's own field
post_content	post field	The description, WordPress's own field

REST

The jobs start through POST /photopress/v1/jobs with type metadata.alt_text or metadata.description and args.force. The route needs manage_options.

Hooks PhotoPress provides

Hook	Type	Arguments	When	Code
photopress_metadata_tag_name	filter	$name	Runs on every template field lookup. Renames the field asked for.	XmpReader.php#L167
photopress_metadata_tag_value	filter	$value, $name, $all_xmp	Runs on every field lookup of a file with XMP. A non-empty return is used as the field's value. Use it to add fields of your own.	XmpReader.php#L177
photopress_attachment_description	filter	$description (null), $id, $file	When PhotoPress's replace route sets the text of an image given a new file. Return null to leave the description alone.	MediaRest.php#L726
photopress_attachment_file_replaced	action	$id, $replacements, $rewritten, $options	After an image is given a new file	MediaRest.php#L388

Limits, quirks and known issues

• Template fields are read from the file's XMP. A file with no XMP packet fills no field, Camera included.
• The Lens field reads aux:Lens only. The Lenses taxonomy also reads exifEX:LensModel and the EXIF lens model.
• A template of words alone, with no fields, gives nothing. For alt text, PhotoPress then falls back to the file's description or title.
• Keywords drops a prefix from any keyword with a separator after its first character, also when the prefix is not a parent keyword: Star Wars: A New Hope gives A New Hope.
• Keywords reads dc:subject only, not the keyword hierarchy.
• On upload, on a replace and on Reprocess all images, a description whose template fields the file lacks is emptied. Only the Reprocess descriptions job keeps it.
• Reprocess all images replaces alt text and descriptions written by hand with what the files give.

Related

• Image Taxonomies
• Licensing
• Background Jobs