Media

Upload, optimize, and pick media — with WebP + multi-size out of the box.

The media manager

The media-manager extension owns the media library. It runs at /admin/media with both grid (thumbnails) and list (filename, size, mime, dimensions, uploaded date) views. Search by filename, filter by mime type, sort by date or size.

What you can upload

Anything: images (jpeg, png, webp, avif, gif, svg), videos (mp4, webm), audio (mp3, m4a, ogg), documents (pdf, docx, xlsx). Per-format size limits configurable in /admin/settings/media.

Uploading

Drag & drop a single file or many onto the library page
Click upload for a file picker
Paste from clipboard — ctrl/cmd+V on the library page lifts an image from the OS clipboard
Import from URL — paste a public URL; the server downloads and stores it (core.media.import_url)

Per-file metadata

Click any file to open the editor sheet. You can edit:

Alt text — per-language; falls back to default-language alt if not set
Caption
Description
Slug — the public URL slug at /media/<slug>

Image optimization

Multi-size variants

Every image upload generates a configurable set of size variants. Defaults: thumbnail (300px), medium (768px), large (1536px), plus the original. Add your own at /admin/settings/media — each entry is { slug, width, height?, fit }. Theme/extension code can request a specific size by slug.

WebP conversion

Originals are kept as-is and a WebP variant is generated for each size. The public URL emitter chooses WebP for clients that send Accept: image/webp, and falls back to the original format otherwise.

Reoptimize on demand

Changed your size list, quality settings, or want to switch to AVIF later? Reoptimize regenerates all variants from the original. Bulk action available from the library list view.

Quality controls

Per-format quality (1–100), JPEG progressive on/off, PNG compression level, WebP effort — all configurable.

TIP

Originals are backed up, never replaced. You can lower quality, change formats, or delete variants — the original byte-stream is preserved so reoptimize is always lossless on input.

The media picker

The picker is a modal embedded everywhere a node, term, or block needs media — featured image, image custom fields, gallery fields, file fields. From the modal you can:

Browse the library with grid/list/search/filter
Upload a new file inline (drag-drop into the modal)
Multi-select for gallery fields
Edit alt-text and caption inline before confirming

Confirmed selections are stored as full media objects: { id, slug, url, alt, width, height, sizes: { thumbnail: {...}, medium: {...} } }. Theme templates resolve the right variant by reading .sizes.<slug>.url.

Public URL routing

Every media file resolves at /media/<slug> (or /media/<slug>@<size>.<format> for size variants). The route is owned by the media-manager extension and adds Cache-Control, ETag, and the right MIME type. Direct /storage/... paths are not exposed publicly — they're an implementation detail.