From f17a9aece6e51be8653d73303e3f7ad2139f5933 Mon Sep 17 00:00:00 2001 From: Breno Gazzola Date: Mon, 12 Jul 2021 16:25:28 -0300 Subject: [PATCH] Add 'requirements' subsection to active storage guide --- guides/source/active_storage_overview.md | 37 +++++++++++++----------- 1 file changed, 20 insertions(+), 17 deletions(-) diff --git a/guides/source/active_storage_overview.md b/guides/source/active_storage_overview.md index 567f906242..2f0f61199d 100644 --- a/guides/source/active_storage_overview.md +++ b/guides/source/active_storage_overview.md @@ -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 @@ -805,13 +820,7 @@ 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' -``` - +Transforming images allows you to display the image at your choice of dimensions. 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