Preview Covers in MediaHub for ProcessWire

Show preview images for PDFs, audio, and other non-image assets in the library, picker, and inputfield. Auto-generate when your server supports it, or choose a library image as a manual cover.

From MediaHub 1.19.51, PDFs, audio files, and other non-image assets can show a preview image in the library, picker, and inputfield instead of a generic file-type icon. One library item per file: generated previews and curated covers stay on the same asset page.

Images continue to use ProcessWire's normal Pageimage thumbnails. Preview covers apply to non-image assets and to optional custom posters on YouTube and Vimeo embeds.

Why previews are separate from the image field

MediaHub stores previews in dedicated fields, not in pkd_mediahub_image:

Field	Role
`pkd_mediahub_file`	Primary file for non-image assets (PDF, MP3, MP4, etc.)
`pkd_mediahub_image`	Primary file for image assets only
`pkd_mediahub_preview`	Auto-generated preview poster stored on the asset
`pkd_mediahub_preview_ref`	Page ID of a library image or crop used as a curated preview

Keeping previews out of the image field preserves correct isImage() behaviour and prevents crop and focus UI from appearing on poster images.

What editors see

Library, picker, and inputfield

Non-image asset with a preview: tile shows the cover image. Type badge (PDF, MP3, etc.) still appears.
Non-image asset without a preview: file-type icon (unchanged behaviour).
The asset does not appear under the Images filter. MIME type still drives filtering.

Asset detail page

Asset type	Main preview area
Image	Full image (+ transparency grid toggle)
Uploaded video	Native `<video controls>` when the browser can decode the file
Audio	Cover image (if set) above native `<audio controls>`
PDF / document with cover	Cover image + Open / Download links
No cover	File icon + download fallback
YouTube / Vimeo embed	Embedded player with click-to-play consent; optional custom poster

Preview image sidebar (non-image assets)

Under Asset Internal Notes on the asset detail page:

Click the preview thumbnail or + placeholder to choose an image or crop from the library
Clear the current preview with the × on the thumbnail strip
Status shows whether the cover is auto-generated or a library selection

Library selections save immediately. Removal uses the asset detail form save.

Automatic generation

When your server supports it, MediaHub generates a preview on upload or import. Orchestration runs after upload and after asset detail saves for non-image assets that do not have a library-selected preview.

Asset type	Server tools	Result
PDF (`application/pdf`)	Imagick PHP extension, Poppler (`pdftoppm`), or Ghostscript (`gs`)	First page rasterised to a JPEG on the asset
Audio (`audio/*`)	`ffmpeg` (preferred) or embedded MP3 ID3 APIC artwork	Artwork stored on the audio asset

Embedded MP3 artwork stays on the audio asset. It is not imported as a separate library image.

Auto-generation applies to uploaded non-image files only. YouTube and Vimeo embed imports always show a provider thumbnail from the CDN; see YouTube and Vimeo Embeds for custom poster overrides.

Library-selected previews are never overwritten by auto-generation.

Manual override (shared hosting workflow)

When PDF tools are unavailable on your host:

Upload the PDF to MediaHub (stores in pkd_mediahub_file).
Auto-generation fails silently; no preview is populated.
Upload or pick an existing image or crop in the library.
Open the PDF asset detail → Preview image → choose that library item.
The library tile for the PDF now shows your chosen art.

No Imagick, Poppler, or Ghostscript required for this path.

Module settings

Go to Modules → Configure → MediaHub → Preview covers. Capability badges beside each toggle show what your server supports.

Setting	Default	Purpose
Generate PDF preview	On	Rasterise page 1 on upload/import
Generate audio preview	On	Extract embedded artwork on upload/import
Max preview width	1200 px	Maximum width of generated preview images

A short summary of these settings also appears on the Configuration page.

Template API

Methods on PkdMediahubAssetPage:

Method	Returns	Description
`$asset->preview()`	`Pageimage\|null`	Auto-generated or stored preview file
`$asset->hasPreview()`	`bool`	Whether any preview exists
`$asset->thumbSource()`	`Pageimage\|null`	Best source for library-style thumbs: primary image, then preview ref, then auto preview

Thumbnail resolution order used internally:

pkd_mediahub_image (real images)
pkd_mediahub_preview_ref (library image or crop selected as curated preview)
pkd_mediahub_preview (auto-generated preview for non-image assets)

foreach ($page->resources as $asset) {
if ($asset->isImage()) {
echo $asset->imgTag(400, 0);
continue;
}
$thumb = $asset->thumbSource();
if ($thumb) {
echo '<img src="' . $thumb->url . '" alt="' . htmlspecialchars($asset->title) . '">';
}
// file link, etc.
}

See Template API and findRaw for high-volume read paths.

What preview covers are not

Not a duplicate library item. Curated previews reference an existing image or crop, or store a derivative on the same asset page.
Not crop/focus eligible. Previews are posters, not master images.
Not the Images filter. Filtering still uses MIME type.
Not inline PDF embeds in TinyMCE. PDFs in rich text remain download links unless you add separate embed markup in your templates.

Menu

Preview Covers