Elixir configuration

An ImagePipe configuration holds the settings that apply to every image you serve or process: sources, caches, limits, output defaults, presets, and URL settings such as signing keys. You build it with ImagePipe.config/1, which lists every option with its default.

config =
  ImagePipe.config(
    base_url: "/images",
    keys: [signing_key],
    sources: [
      media: [
        adapter: ImagePipe.Source.File,
        match: :path,
        options: [root: "/srv/images", root_id: "media"]
      ]
    ],
    presets: %{"card" => "w=400/h=300/fit=cover"},
    max_input_pixels: 40_000_000,
    quality: 82
  )

A mount, an instance, or a call to ImagePipe.run/4 takes this configuration. Invalid options raise ArgumentError when you build it.

Where settings belong

A mount checks request URLs against the configuration's URL settings, or those of the named set it picks with mount:. To build URLs in the same app, get those settings with ImagePipe.url_config/2, adding mount: :signed for a mount that picks the named set :signed. A separate app needs the same keys (see shared URL settings).

Which setting wins

When the same setting is given in more than one place:

• Options passed to an inline mount next to config: replace that configuration's options. A mount of an instance accepts only mount options and mount:, which picks one of the named sets of URL settings in the instance's mounts:.
• Each entry in an instance's mounts: applies its URL settings on top of the instance's. A setting the entry leaves out keeps the instance's value, so a mount that sets only source_encryption_keys still checks the instance's signing keys. For a mount that doesn't check signatures, set keys: [], and source_encryption_keys: [] if the instance has them.
• Options passed to an instance next to config: replace that configuration's options.
• Options passed to ImagePipe.run/4 or ImagePipe.write/5 replace the configuration's options for that call.
• A request's own options win over the configuration's defaults. A URL with q=90 uses quality 90 whatever quality says.
• Presets apply in a fixed order: request_defaults first, then the named presets in the order the URL lists them, then the request's own options. See presets.

Encoder defaults

:jpeg_options, :png_options, :webp_options, and :avif_options set encoder defaults. They take the same keyword lists as the options of the same name in ImagePipe.URL.output/2:

config =
  ImagePipe.config(
    jpeg_options: [interlace: true],
    webp_options: [effort: 5]
  )

builder =
  ImagePipe.URL.new()
  |> ImagePipe.URL.output(format: :jpeg, jpeg_options: [interlace: false])

A request's settings replace the configuration's field by field, so this builder encodes a baseline JPEG and keeps any other JPEG defaults. The fields are listed in encoder options under their URL names. Hyphens become underscores, and progressive and subsample have different builder names, listed in URL option names.

WebP encodes at effort: 4 and AVIF at effort: 3 unless :webp_options or :avif_options set another :effort. AVIF also encodes without chroma subsampling (subsample_mode: :off) unless :avif_options sets another :subsample_mode. See WebP options and AVIF options for the time and size tradeoff.

Limits and cached images

The limits, such as max_input_pixels and max_result_width, set the largest images ImagePipe processes. They don't apply to images already in the cache. After you lower a limit, cached images that exceed it are still served from the cache.