Skip to main content
Document thumbnails are optional. They create a small image for library cards without replacing the uploaded document or creating a larger preview. PDF thumbnails use the first page only. Existing image and video conversions remain independently configurable.

Enable PDF thumbnails without a queue worker

Install Poppler on the machine that will generate thumbnails and configure the executable path. Enable the feature in config/media-studio.php:
Uploads record pending thumbnails and return without rendering the document. Run a bounded batch manually or through your scheduler:
The time budget stops admission of additional work; an already running conversion has its own timeout and can finish after that budget. No thumbnail appears until a command or worker actually processes it. Library cards retain the file-type icon while waiting.

Choose the PDF backend

Set processing.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:
Install a libvips build with PDF and the desired output codec enabled. The PDF loader can use PDFium or Poppler depending on that build. Check with 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

Configure the connection retry interval above the worker timeout. A 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:
Synchronous execution adds conversion time to the upload response. It is not a background worker replacement for expensive documents.

Disable generation

No new document thumbnail jobs are admitted, and pending document processing stops. Previously created thumbnails and original files are retained. Disabling generation does not delete anything.

Supply your own document generator

The PDF generator is included. Other formats can use a registered generator implementing this contract:
Register it by MIME type:
The raster is encoded using Studio’s WebP/AVIF pipeline and stored through the same Laravel disks as other renditions. Generators must enforce their own process/network/memory constraints. A PHP timeout alone is not an OS sandbox. Run document converters in an isolated, resource-limited worker environment. The included 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:
The backfill command includes images as well as enabled document types. It does not scan your storage bucket. Source ownership, current versions and workspace permissions are checked again during processing. Existing source adapters and external renditions keep their own authority; the native processor does not rewrite externally owned files.

Office documents

Run LibreOffice in an environment with no network access and OS-enforced CPU, memory and temporary-storage limits. The office_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.
Register XLSX, PPTX, ODT, ODS and ODP using their MIME types and the same generator. The archive preflight rejects embedded active content, excessive expansion and external XML references. Each conversion has a private temporary directory and LibreOffice profile. A temporary PDF is removed after first-page rendering; only the thumbnail is published. Large spreadsheets may still be expensive to convert: configure print areas upstream and use a dedicated worker. The initial Office integration test covers DOCX, not every spreadsheet/presentation layout.

Text, Markdown and text-only HTML

Configure a local Unicode TrueType font. No font or external resource is downloaded during rendering.
This renderer uses a bounded first text segment and stops when the card is filled. HTML scripts/styles are discarded; no browser is launched. For visually faithful HTML or Markdown rendering, provide your own isolated ThumbnailGenerator.

Model-specific output

Pass the owner model through the existing upload integration. Studio retains the rendition model on the source version and applies overrides when work is admitted. The master enabled switch always wins. To hide already-created document thumbnails too, set serve_existing to false.

Format overrides and resource bounds

The master enabled 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.