Reference → Media — Reference

Media — Reference

The Media surface is the asset library — every image, video, document, font asset, and downloadable file that a site references in pages, posts, products, or template designs. It owns upload, storage backend, image variants, alt-text and descriptions, bulk operations, and cross-site sync to remote object storage.

This page is a reference for platform engineers and integrators. Customer-facing walkthroughs for uploading and organizing media live in the customer docs set; this page describes the surface, not the workflow.

Overview

Media lives under the Media Library module in SG-Admin. The module renders four primary views — the asset grid, the per-asset edit drawer, the upload tray, and the settings panel — and exposes a write surface for upload, metadata edit, soft delete, bulk operations, and remote-storage sync.

Two storage modes are supported. The default mode stores asset binaries on the platform's primary file system, served through a CDN URL. The optional GCP sync mode replicates the asset library to a Google Cloud Storage bucket and serves binaries from there — used by sites with high traffic or large libraries. The two modes coexist; sync can be enabled on an existing library and a one-time backfill walks every record into the bucket.

Where it lives in SG-Admin:

Sidebar: SG-Admin → Media Library
URL prefix: /sg-admin/media/
View templates: application/views/Admin/Media/

The asset grid is the primary view — a paged, filterable thumbnail wall with selection. The edit drawer opens against the selected asset. The upload tray accepts drag-and-drop and file-picker uploads, optionally toggling on-the-fly format conversion and compression before storage commit.

┌────────────────────────────────────────────────────────────────────┐│ SG-Admin → Media Library [⬆ Upload files] │├────────────────────────────────────────────────────────────────────┤│ Filter: [All ▾] [Type ▾] [Date ▾] [Tag ▾] Search: [____] │├────────────────────────────────────────────────────────────────────┤│ ┌────┐ ┌────┐ ┌────┐ ┌────┐ ┌────┐ ┌────┐ ┌────┐ ┌────┐ ││ │img │ │img │ │ pdf│ │img │ │vid │ │img │ │img │ │img │ ││ └────┘ └────┘ └────┘ └────┘ └────┘ └────┘ └────┘ └────┘ ││ hero bg-1 spec icon demo logo alt promo ││ ││ ┌────┐ ┌────┐ ┌────┐ ┌────┐... 248 of 1,402 [<] [>] ││ │img │ │img │ │img │ │ ttf│ ││ └────┘ └────┘ └────┘ └────┘ ││ ││ Settings · Import / Export · GCP sync · Bulk select │└────────────────────────────────────────────────────────────────────┘

Actions

The Media surface exposes the following operations.

List and filter

Returns the media records, paged thumbnail-first, with filename, type, dimensions, file size, upload date, uploader, and tag columns. Supports column sort, free-text filter by filename or description, and faceted filter by type (image / video / document / font / other), date range, tag, and upload source.

Upload files

Accepts one or many files in a single submission. Each file passes through a recognizer that derives type, dimensions (for images and videos), and duration (for video and audio). The submission may toggle on-the-fly format conversion (for example, converting a PNG to WebP) and compression level before the binary commits to storage.

Per-upload options:

Format. original (default) keeps the source format. webp converts compatible images to WebP. auto picks the most compact suitable format.
Compression. off (default), or a numeric quality target. Lossy compression applies to JPEG, WebP, and AVIF outputs.
Image variants. A set of resized renditions auto-generates on upload (thumbnail, medium, large; sizes configurable in Settings). Each variant is a separate file on disk; the parent record carries the variant map.

Engineering note. The default upload settings store the file at original format with compression off. For libraries that serve thousands of front-end image requests per day, toggle Format=WebP and pick a compression target before bulk uploads.

Edit asset metadata

Opens the edit drawer for the selected asset. Editable: filename (display name only — the on-disk filename is stable), description, alt text, tags, and custom-field values (if any custom fields are defined for media records). Save replaces the stored metadata.

Generate alt text

A dedicated write path that invokes the platform's description generator against the asset binary and writes the result to the alt-text field. Available per-asset and as a bulk operation across a selection.

Save description

Lighter-weight write path for the alt-text and description fields specifically. Used by the inline description editor in the asset grid.

Soft delete

Marks the record as deleted without removing the binary. Soft-deleted assets disappear from the default grid but remain queryable via the deleted filter. References from pages and posts continue to resolve until permanent delete.

Permanent delete

Hard-removes the record and its binary (and all variant binaries). Irreversible. References from pages and posts that pointed to the deleted asset render as broken links — the surface returns a warning in the delete confirmation listing the referencing records.

Bulk operations

Multi-select in the grid enables: bulk tag (apply or remove tags across the selection), bulk delete (soft delete), bulk generate alt text, bulk export (download a bundle). Bulk operations run against the selection in batches and report per-item success or skip.

Import library

Bulk-loads media from an exported bundle (typically from another SGEN site). Import accepts the bundle, validates filename collisions (rename or skip), commits binaries, and writes parent records and variant maps.

Export library

Produces a bundle of media records and binaries. The bundle is suitable for re-import into another SGEN site. Selection-scoped or full-library.

Start GCP sync

One-time bulk replication of the entire library to a Google Cloud Storage bucket. The action validates bucket credentials, enumerates the library, and queues per-record copy tasks. Progress is visible in the sync progress view.

Check sync progress

Returns the current state of an in-flight GCP sync — total record count, copied count, failed count, and current rate.

Cancel sync

Stops an in-flight sync. Already-copied records remain in the bucket; the sync flag returns to off and the library reverts to default storage for new uploads until sync is restarted.

Update settings

Writes the media-wide settings: storage backend (default vs GCP), image variant sizes, default upload format, default compression level, max upload size, allowed file types, alt-text auto-generation toggle, GCP credentials.

Data model

A media record carries the following fields.

Field	Type	Notes
`id`	integer	Primary key.
`filename`	string	Display name. Editable. Distinct from the on-disk filename.
`disk_path`	string	On-disk path. Stable across edits.
`mime_type`	string	Detected on upload.
`type_class`	enum	`image`, `video`, `document`, `font`, `audio`, `other`.
`file_size`	integer	Bytes.
`width`, `height`	integer	Set for images and videos.
`duration_seconds`	integer	Set for video and audio.
`alt_text`	string	Used in the front-end `alt` attribute.
`description`	string	Used in caption and as the social-card alt.
`tags`	array	Many-to-many to the media-tag taxonomy.
`variants`	JSON	Map of variant slug → variant record (path, width, height, file size).
`storage_backend`	enum	`local` or `gcp`. Set per-record at upload time.
`gcp_url`	string	Populated when stored in GCP.
`uploader_id`	integer	Foreign key to Users.
`created_at`	timestamp	Upload time.
`updated_at`	timestamp	Touched on metadata edits.

Variant generation. On upload, the surface generates one variant per configured size. Variants are independent files on disk (or in the GCP bucket) with their own dimensions. The parent record's variants map names them. Theme code requests a specific variant by slug; the front-end resolves the URL from the map.

Reference tracking. Pages, posts, products, theme designs, and Custom Codes references all point at a media id. The Media surface maintains an inverse index so the delete-confirmation step can list every record that would break.

UPLOAD│▼┌──────────────────────────────┐│ Recognizer │ → mime, dims, duration└──────────────┬───────────────┘│▼optional conversion (format=webp, compression=quality)│▼┌──────────────────────────────┐│ Storage backend (per record) ││ ││ LOCAL GCP ││ /uploads/... bucket:// ││ │└──────────────┬───────────────┘│▼variants generated (thumbnail, medium, large)│▼media record persisted│▼variant map written inverse index updated(so delete sees referrers)

Permissions

Access follows the standard admin gate plus per-action capability checks.

Capability	Administrator	Editor	Author	Viewer
List media	✔	✔	✔	✔
Upload	✔	✔	✔	—
Edit any asset metadata	✔	✔	—	—
Edit own uploads' metadata	✔	✔	✔	—
Generate alt text	✔	✔	own only	—
Soft delete	✔	✔	own only	—
Permanent delete	✔	—	—	—
Bulk operations	✔	✔	—	—
Export	✔	—	—	—
Import	✔	—	—	—
Start / cancel GCP sync	✔	—	—	—
Update settings	✔	—	—	—

File-type gate. Settings defines the allowed type list. Uploads of disallowed types fail at the upload stage with a structured rejection naming the type. The gate is in addition to the platform's own image and document handling — for example, executable file types are never allowed regardless of settings.

Audit. Every upload, edit, delete, restore, bulk operation, sync start, sync cancel, and settings update emits an Activity Log entry.

PERMANENT DELETE (asset id = 487, filename = "hero-spring.jpg")│▼┌────────────────────────────────────────────────────────────┐│ Inverse-index lookup — referring records ││ ││ PAGE id=12 "Spring landing" (canvas embed) ││ POST id=88 "Q1 platform recap" (featured img) ││ POST id=104 "Five lessons from..." (inline embed) ││ THEME default-2026 (header bg) ││ │└──────────────────────────┬─────────────────────────────────┘│▼Confirmation prompt lists referrers├─ proceed → delete record + binary + variants└─ cancel → no change

Related references

Settings — Reference. Image variant sizes, allowed file types, max upload size, default upload format / compression, GCP credentials live in Settings.
Pages — Reference. Canvas-embedded image and asset references resolve against Media.
Posts — Reference. Featured image and inline asset references resolve against Media.
Custom Fonts — Reference. Font assets uploaded for the Custom Fonts module store in the Media library with type_class = font.
Users — Reference. Uploader attribution and capability checks resolve against Users.
Migration — Reference. Library export and import bundles are produced and consumed by Migration as well as locally.

For the corresponding customer-facing walkthrough — uploading assets, optimizing image delivery, organizing with tags — see the Media Library section of the customer docs at /docs/media.

On this page

Guides

Reference

Changelog

Roadmap