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:
parent
04121a5f30
commit
f17a9aece6
1 changed files with 20 additions and 17 deletions
|
@ -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 application’s 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
|
||||
|
||||
|
|
Loading…
Reference in a new issue