Enable PDF thumbnails without a queue worker
Install Poppler on the machine that will generate thumbnails and configure the executable path. Enable the feature inconfig/media-studio.php:
Choose the PDF backend
Setprocessing.document_thumbnails.pdf_backend to poppler (default)
or vips. The environment variable MEDIA_STUDIO_PDF_BACKEND also selects
the backend when using the package configuration.
For a small installation, use
poppler, command execution and one scheduled
batch at a time. For a VPS, vips can run on the dedicated document queue.
Both backends require permission to start processes and a writable temporary
directory. Neither backend requires PHP FFI.
Example configuration for the libvips backend:
vips -l pdfload and render a trusted PDF before enabling it. Installing
ordinary libvips does not guarantee PDFium support.
Each conversion runs in a separate process with a deadline, bounded encoded output,
disabled libvips operation cache and 1–8 configured threads. The default is one
thread. Thread count limits libvips evaluation; decoder or encoder libraries may
have additional threads. Use OS/container memory and CPU limits for hard resource
isolation. Cache settings alone are not a process memory limit.
The libvips path writes the final encoded thumbnail to a temporary file and
streams it to the existing publication pipeline for validation. It avoids an
intermediate PNG and decoding/re-encoding that PNG in PHP. The source PDF is still
staged locally and validated in full. Existing pending recipes keep their stored
generator when the configured backend changes. Newly admitted recipes use the
selected backend. A missing executable or codec produces a retryable rendition
failure.
Use a queue worker
sync connection is deliberately not dispatched for documents: pending work remains available for the explicit command. Studio does not silently convert it inside the upload request.
Explicit synchronous execution
For small trusted documents where extra upload latency is acceptable:Disable generation
Supply your own document generator
The PDF generator is included. Other formats can use a registered generator implementing this contract:OfficeThumbnailGenerator uses LibreOffice and Poppler. Enable it only on an isolated conversion worker (see below). TextThumbnailGenerator produces a text-only thumbnail for TXT, Markdown and HTML; it does not execute HTML or preserve its visual page layout.
Profiles are recorded with the rendition. Changing configuration does not silently rewrite existing output. Use explicit backfill/refresh for existing assets.
Existing documents
Use the registered principal type and ID of an authorized user:Office documents
Run LibreOffice in an environment with no network access and OS-enforced CPU, memory and temporary-storage limits. Theoffice_isolated_worker setting acknowledges that deployment requirement; it does not create a sandbox by itself. Never enable it on an unrestricted web server for untrusted uploads.
Text, Markdown and text-only HTML
Configure a local Unicode TrueType font. No font or external resource is downloaded during rendering.ThumbnailGenerator.
Model-specific output
enabled switch always wins. To hide already-created document thumbnails too, set serve_existing to false.
Format overrides and resource bounds
The masterenabled switch must be true. Studio combines the MIME-type registration
with the matching owner model_profiles override, then uses global defaults for
unspecified settings. An enabled MIME registration alone does not start processing.
max_raster_bytes is a global document setting, not a per-format override;
it accepts 1–33554432 bytes. Binary paths, text font and Office-worker acknowledgement
are also deployment configuration. Neither a byte budget nor the acknowledgement
switch replaces OS-level process resource isolation.
Diagnose a missing thumbnail
Use the full processing reference for all shipped
defaults, video thumbnails for FFmpeg posters, and
existing thumbnail mappings when another application owns
the derivative files.