1
0
Fork 0
mirror of https://github.com/rails/rails.git synced 2022-11-09 12:12:34 -05:00

Add 'requirements' subsection to active storage guide

This commit is contained in:
Breno Gazzola 2021-07-12 16:25:28 -03:00
parent 04121a5f30
commit f17a9aece6

View file

@ -32,6 +32,25 @@ Using Active Storage, an application can transform image uploads or generate ima
representations of non-image uploads like PDFs and videos, and extract metadata from
arbitrary files.
### Requirements
Various features of Active Storage depend on third-party software which Rails
will not install, and must be installed separately:
* [ImageMagick](https://imagemagick.org/index.php) or [libvips](https://github.com/libvips/libvips) v8.6+ for image analysis and transformations
* [ffmpeg](http://ffmpeg.org/) v3.4+ for video/audio analysis and video previews
* [poppler](https://poppler.freedesktop.org/) or [muPDF](https://mupdf.com/) for PDF previews
Image analysis and transformations also require the `image_processing` gem. Uncomment it in your `Gemfile`, or add it if necessary:
```ruby
gem "image_processing", ">= 1.2"
```
TIP: Compared to libvips, ImageMagick is better known and more widely available. However, libvips can be [up to 10x faster and consume 1/10 the memory](https://github.com/libvips/libvips/wiki/Speed-and-memory-use). For JPEG files, this can be further improved by replacing `libjpeg-dev` with `libjpeg-turbo-dev`, which is [2-7x faster](https://libjpeg-turbo.org/About/Performance).
WARNING: Before you install and use third-party software, make sure you understand the licensing implications of doing so. MuPDF, in particular, is licensed under AGPL and requires a commercial license for some use.
## Setup
Active Storage uses three tables in your applications database named
@ -722,10 +741,6 @@ Active Storage analyzes files once they've been uploaded by queuing a job in Act
Image analysis provides `width` and `height` attributes. Video analysis provides these, as well as `duration`, `angle`, `display_aspect_ratio`, and `video` and `audio` booleans to indicate the presence of those channels. Audio analysis provides `duration` and `bit_rate` attributes.
Image analysis requires either the `mini_magick` gem and the ImageMagick library, or the `ruby-vips` gem and the libvips library. Note that the libraries are not included in the gems, and must be installed separately.
Audio/Video analysis requires [FFmpeg](https://www.ffmpeg.org/), which must also be installed separately.
[`analyzed?`]: https://api.rubyonrails.org/classes/ActiveStorage/Blob/Analyzable.html#method-i-analyzed-3F
Displaying Images, Videos, and PDFs
@ -806,12 +821,6 @@ end
### Transforming Images
Transforming images allows you to display the image at your choice of dimensions.
To enable variants, add the `image_processing` gem to your `Gemfile`:
```ruby
gem 'image_processing'
```
To create a variation of an image, call [`variant`][] on the attachment. You
can pass any transformation supported by the variant processor to the method.
When the browser hits the variant URL, Active Storage will lazily transform
@ -858,12 +867,6 @@ a link to a lazily-generated preview, use the attachment's [`preview`][] method:
To add support for another format, add your own previewer. See the
[`ActiveStorage::Preview`][] documentation for more information.
WARNING: Extracting previews requires third-party applications: FFmpeg v3.4+ for
video and muPDF for PDFs, and on macOS also XQuartz and Poppler.
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.
[`preview`]: https://api.rubyonrails.org/classes/ActiveStorage/Blob/Representable.html#method-i-preview
[`ActiveStorage::Preview`]: https://api.rubyonrails.org/classes/ActiveStorage/Preview.html