Media library

The media library holds every image, document, audio and video file a site uses. An asset is uploaded once, install-wide, and chosen in documents through an asset field. The library keeps the words about each asset (alt text and caption) per locale with a per-site override, records the licence it is used under, and generates the image sizes your templates ask for.

A minimal setupCopy Anchor Link

A new project already has a working library: originals and derivatives are stored on the local disk under storage.filesystem.root.

# config/engine.yaml
storage:
  driver: filesystem
  filesystem:
    root: ./storage

media:
  max_upload_bytes: 30MB        # default 50MB
  require_alt_text: true        # the default: an image needs alt text unless it is decorative

A content type offers the library through an asset field, and a template renders the image through a named transform from images.yaml:

# config/schema/article.yaml
fields:
  - name: hero
    type: asset
    alt: required          # never empty unless the image is marked decorative
    caption: true          # offer a per-use caption

{% if entry.hero %}{{ entry.hero.figure("hero", priority=true) }}{% endif %}

figure() writes the picture, the caption and the licence credit. How to render images, the transforms in images.yaml and the responsive sizes are covered in Images.

UploadingCopy Anchor Link

Staff upload in the admin’s Media screen, or from an asset field that declares upload: true. Members upload through the portal (DMO bundle), agents through the content MCP, and a migration through engine-dmo media import. Every path goes through the same pipeline:

A refused upload says why: “this file type is not accepted”, “the file is larger than the upload limit”, or “alt text is required for every enabled locale unless the image is decorative”.

The admin’s upload form needs media.upload. Editing an asset afterwards needs media.edit.

Alt text and captionsCopy Anchor Link

Alt text describes the image for someone who cannot see it. A caption is editorial text shown to everyone. The library keeps both:

• Per locale. Each enabled locale has its own alt text and caption.
• Per site. The text written on the asset is the default for every site. A site may override the alt text, the caption, or both, in any locale, so the same photograph can be described differently on two sites. The asset page shows, for each locale, what every site will display.
• Per use. An asset field may carry its own alt text and caption for one document (alt: inherit, the default, lets the editor override; caption: true offers a caption). A per-use value wins over the library’s.
• Decorative. An image marked decorative renders alt="" everywhere and is never overridden per site. The library counts decorative images separately, so marking cannot hide a backlog.

The admin refuses alt text over 200 characters, shows a count against an advised 125, and refuses alt text that opens with “image of”, “photo of” and similar.

How a page finds its alt textCopy Anchor Link

For a page on site S in locale L, alt text and caption are each taken from the first of:

1. the per-use value on the field;
2. S’s override in L;
3. the default in L;
4. for each locale in L’s fallback chain, then the install’s default locale: S’s override, then the default.

Language comes before site: a reader gets text in their own language before a site-specific text in another language. When the text comes from a fallback locale, the image value’s altLang (and captionLang) names that locale, and img(), picture() and figure() write a lang attribute so a screen reader pronounces it correctly.

Missing translations at publishCopy Anchor Link

Each site decides what happens when an image’s alt text exists only in a fallback locale, in site.yaml:

# config/sites/<site>/site.yaml
accessibility:
  alt_fallback: warn            # allow | warn (the default) | block
  alt_fallback_locales:
    cy-GB: block                # Welsh pages must carry Welsh alt text

An image with no alt text in any locale of the chain is always an error at publish (alt_needed for an alt: required field, otherwise alt while media.require_alt_text is on). Saving a draft is never refused for alt text. The policy used is the owning site’s, also for a document shared to other sites.

Working through a backlogCopy Anchor Link

The admin’s Alt text queue lists images missing alt text (or captions) in one locale, for the default or for one site, most used first, with a field per row saved from the keyboard. With an AI provider configured, “Draft these with AI” fills the queue with drafts a person reviews (AI assistance).

engine-dmo media stats reports the library’s size and, per site and locale, how many images have alt text of their own, how many show a fallback, and how many have none:

engine-dmo media stats
engine-dmo media stats --site main --json

Editing the default text needs media.edit with no site restriction; a site’s override needs media.edit on that site; a grant scoped to locales covers those locales only.

Rights and licencesCopy Anchor Link

Every asset can carry a rights record: the licence term, the holder, the uses it covers, the territory, the start and end dates, the credit line, the source, and an evidence file (a model release or licence PDF, itself an asset). The record is edited on the asset’s Rights panel and needs the media.rights permission, which no built-in role except Owner holds; grant it in config/access/roles.yaml. Every change is audited.

Licence termsCopy Anchor Link

media.rights.terms is the vocabulary editors choose from. Applying a term fills the uses and territory when they are empty, and the end date from the start date (today when none is given) plus the term’s duration. A term with credit_required refuses a record without a credit line.

# config/engine.yaml
media:
  rights:
    on_expiry: placeholder
    expiry_warnings: [90d, 30d, 0d]
    terms:
      commissioned:
        label: { en: "Commissioned, perpetual" }
        uses: [website, social, newsletter, print]
        territory: [WORLD]
      stock-web-1y:
        label: { en: "Stock, web only, one year" }
        uses: [website]
        territory: [WORLD]
        duration: 1y
        credit_required: true
      member-supplied:
        label: { en: "Supplied by member" }
        uses: [website, social, newsletter]
        territory: [WORLD]
        credit_required: true

Setting terms replaces the engine’s four defaults: commissioned-perpetual, stock-2yr-web, member-supplied and press-only. Keep a member-supplied term if members upload photos through the portal (DMO bundle): without it, member uploads are unavailable.

ExpiryCopy Anchor Link

• At publish, an image whose licence ended before today refuses the publish (rights_expired) while block_publish_when_expired is true, the default, and is a warning when it is false. An image whose licence ends while the page stays live is a warning (rights_expiring) while warn_publish_when_expiring is true. Saving is never refused for rights.
• Every day, a scheduled sweep finds licences ending within the largest of expiry_warnings and notifies every user holding media.rights, once per threshold crossed.
• Once a licence has ended, on_expiry: warn (the default) changes nothing on the live site. on_expiry: placeholder renders the image as absent on public pages, exactly as a deleted asset, so a template’s {% if entry.hero %} falls through to its own fallback. Nothing is ever deleted automatically.

CreditsCopy Anchor Link

An image’s credit is the credit line its licence requires, and creditRequired is true when there is one. figure() always writes it in the <figcaption>. img() and picture() write no caption, so a template that uses them must print the credit itself:

{{ entry.hero.picture("hero") }}
{% if entry.hero.credit %}<small>{{ entry.hero.credit }}</small>{% endif %}

engine-dmo check warns (image-credit) at every X.img(...) or X.picture(...) in a template that neither prints X.credit nor calls X.figure(...) anywhere in the same file.

Member-supplied photosCopy Anchor Link

A photo whose licence is member-supplied, or that a member uploaded and accepted the upload terms for, is given to a third party only when its rights record names that use: partner for a partner site’s widget or embed and for engine-dmo export embeds, handover for engine-dmo site export. Without it the photo is left out. The site’s own pages, feeds and APIs always show it.

Duplicates, orphans and bulk editingCopy Anchor Link

• Duplicates. Each image gets a 64-bit perceptual hash at upload. Images whose hashes differ by at most media.duplicates.threshold bits (10 by default), and files with the same checksum, are listed on the asset page under “Possible duplicates” and in the library’s “Possible duplicates” filter. It is a suggestion: nothing is merged or refused. “Not a duplicate” dismisses a pair for good.
• Orphans. A scheduled scan, at media.orphans.scan_schedule (03:00 UTC by default), marks every asset as in use, used only in old revisions, or unreferenced. The library’s Usage filter reads it, and “Scan now” runs it on demand. An asset used as rights evidence or in a collection counts as in use.
• Bulk editing. The library’s list view selects assets (up to 2,000 matching a filter) and applies one operation: add or remove a tag, apply a licence term or credit line (media.rights), add to a collection, set or clear decorative, regenerate derivatives, soft delete or restore (media.delete). A preview says what will change before it runs; the run is one audited job. Deleted assets are listed under “Deleted”, where they can be restored.
• Collections are named, install-wide, manual groups of assets, used as a filter.

Not in this version: merging two duplicate assets into one, a hard purge of a deleted asset’s file (a deleted asset stays restorable; media prune removes only derivatives), collections that fill themselves from a rule, and press packs.

DerivativesCopy Anchor Link

Image sizes are generated on demand from the transforms in config/images.yaml (and a site’s own config/sites/<site>/images.yaml). A derivative’s address carries a keyed hash, so nobody can request a size the site never rendered. Derivatives are stored and reused; the pure Go build serves JPEG, and the -vips image also serves WebP and AVIF.

engine-dmo media transforms                  # every transform and its width ladder
engine-dmo media transforms --site main --source-width 1600
engine-dmo media warm --dry-run              # count derivatives the published pages need
engine-dmo media warm --site main            # generate them, JPEG before WebP before AVIF
engine-dmo media prune --dry-run             # what pruning would remove, and the bytes freed

All media commands need the database.

Configuration referenceCopy Anchor Link

Every key is under media: in config/engine.yaml.

The files themselves live where storage: says:

PermissionsCopy Anchor Link

Owner holds every permission. A built-in role is changed by declaring a role with the same key in config/access/roles.yaml.