Some non-image blobs can be previewed: that is, they can be presented as images. A video blob can be previewed by extracting its first frame, and a PDF blob can be previewed by extracting its first page.
A previewer extracts a preview image from a blob. Active Storage provides previewers for videos and PDFs. ActiveStorage::Previewer::VideoPreviewer
is used for videos whereas ActiveStorage::Previewer::PopplerPDFPreviewer
and ActiveStorage::Previewer::MuPDFPreviewer
are used for PDFs. Build custom previewers by subclassing ActiveStorage::Previewer
and implementing the requisite methods. Consult the ActiveStorage::Previewer
documentation for more details on what's required of previewers.
To choose the previewer for a blob, Active Storage calls accept?
on each registered previewer in order. It uses the first previewer for which accept?
returns true when given the blob. In a Rails application, add or remove previewers by manipulating Rails.application.config.active_storage.previewers
in an initializer:
Rails.application.config.active_storage.previewers
# => [ ActiveStorage::Previewer::PopplerPDFPreviewer, ActiveStorage::Previewer::MuPDFPreviewer, ActiveStorage::Previewer::VideoPreviewer ]
# Add a custom previewer for Microsoft Office documents:
Rails.application.config.active_storage.previewers << DOCXPreviewer
# => [ ActiveStorage::Previewer::PopplerPDFPreviewer, ActiveStorage::Previewer::MuPDFPreviewer, ActiveStorage::Previewer::VideoPreviewer, DOCXPreviewer ]
Outside of a Rails application, modify ActiveStorage.previewers
instead.
The built-in previewers rely on third-party system libraries. Specifically, the built-in video previewer requires FFmpeg. Two PDF previewers are provided: one requires Poppler, and the other requires muPDF (version 1.8 or newer). To preview PDFs, install either Poppler or muPDF.
These libraries are not provided by Rails. You must install them yourself to use the built-in previewers. Before you install and use third-party software, make sure you understand the licensing implications of doing so.
- MODULE ActiveRecord
- MODULE ActiveStorage
- CLASS ActiveStorage::Preview
- CLASS ActiveStorage::Preview::UnprocessedError