mirror of
https://github.com/imgproxy/imgproxy.git
synced 2024-11-24 08:12:38 +02:00
Format docs
This commit is contained in:
DarthSim
parent
9416168575
commit
0d23389385
@ -2,7 +2,7 @@
|
||||
|
||||
imgproxy can calculate quality for your resultant images so they best fit the selected metric. The supported methods are [none](#none), [size](#autoquality-by-file-size), [dssim](#autoquality-by-dssim), and [ml](#autoquality-with-ml).
|
||||
|
||||
**⚠️Warning:** Autoquality requires an image to be saved several times. Use it only when you prefer the resultant quality and size over speed.
|
||||
**⚠️ Warning:** Autoquality requires an image to be saved several times. Use it only when you prefer the resultant quality and size over speed.
|
||||
|
||||
You can enable autoquality using [config options](configuration.md#autoquality) (for all images) or with [processing options](generating_the_url.md#autoquality) (for each image individually).
|
||||
|
||||
@ -83,7 +83,7 @@ IMGPROXY_AUTOQUALITY_FORMAT_MAX="avif=50"
|
||||
|
||||
This method is almost the same as autoquality with [DSSIM](#autoquality-by-dssim) but imgproxy will try to predict the initial quality using neural networks. This requires neural networks to be configured (see the config examlpe or the config documentation). If a neural network for the resulting format is not provided, the [DSSIM](#autoquality-by-dssim) method will be used instead.
|
||||
|
||||
**📝Note:** When this method is used, imgproxy will save JPEG images with the most optimal [advanced JPEG compression](configuration.md#advanced-jpeg-compression) settings, ignoring config and processing options.
|
||||
**📝 Note:** When this method is used, imgproxy will save JPEG images with the most optimal [advanced JPEG compression](configuration.md#advanced-jpeg-compression) settings, ignoring config and processing options.
|
||||
|
||||
**Method name:** `ml`
|
||||
|
||||
@ -108,7 +108,7 @@ IMGPROXY_AUTOQUALITY_WEBP_NET="/networks/autoquality-webp.pb"
|
||||
IMGPROXY_AUTOQUALITY_AVIF_NET="/networks/autoquality-avif.pb"
|
||||
```
|
||||
|
||||
**📝Note:** If you trust your neural network's autoquality, you may want to set `IMGPROXY_AUTOQUALITY_ALLOWED_ERROR` to 1 (the maximum possible DSSIM value). In this case, imgproxy will always use the quality predicted by the neural network.
|
||||
**📝 Note:** If you trust your neural network's autoquality, you may want to set `IMGPROXY_AUTOQUALITY_ALLOWED_ERROR` to 1 (the maximum possible DSSIM value). In this case, imgproxy will always use the quality predicted by the neural network.
|
||||
|
||||
#### Processing options example
|
||||
|
||||
|
||||
@ -4,11 +4,11 @@ You can use the `best` value for the [format](generating_the_url#format) option
|
||||
|
||||
imgproxy measures the complexity of the image to choose when it should use a lossless or near-lossless encoding. Then imgproxy tries to save the image in multiple formats to pick one with the smallest resulting size.
|
||||
|
||||
**📝Note:** imgproxy uses only the formats listed as [preferred](configuration#preferred-formats) when choosing the best format. It may also use AVIF or WebP if [AVIF/WebP support detection](configuration#avifwebp-support-detection) is enabled.
|
||||
**📝 Note:** imgproxy uses only the formats listed as [preferred](configuration#preferred-formats) when choosing the best format. It may also use AVIF or WebP if [AVIF/WebP support detection](configuration#avifwebp-support-detection) is enabled.
|
||||
|
||||
**📝Note:** imgproxy will use AVIF or WebP _only_ if [AVIF/WebP support detection](configuration#avifwebp-support-detection) is enabled.
|
||||
**📝 Note:** imgproxy will use AVIF or WebP _only_ if [AVIF/WebP support detection](configuration#avifwebp-support-detection) is enabled.
|
||||
|
||||
**📝Note:** imgproxy may change your quality and autoquality settings if the `best` format is used.
|
||||
**📝 Note:** imgproxy may change your quality and autoquality settings if the `best` format is used.
|
||||
|
||||
## Configuration
|
||||
|
||||
|
||||
@ -61,7 +61,7 @@ imgproxy protects you from so-called image bombs. Here's how you can specify the
|
||||
|
||||
* `IMGPROXY_MAX_SRC_RESOLUTION`: the maximum resolution of the source image, in megapixels. Images with larger actual size will be rejected. Default: `16.8`
|
||||
|
||||
**⚠️Warning:** When the source image is animated, imgproxy summarizes all its frames' resolutions while checking the source image resolution unless `IMGPROXY_MAX_ANIMATION_FRAME_RESOLUTION` is greater than zero.
|
||||
**⚠️ Warning:** When the source image is animated, imgproxy summarizes all its frames' resolutions while checking the source image resolution unless `IMGPROXY_MAX_ANIMATION_FRAME_RESOLUTION` is greater than zero.
|
||||
|
||||
* `IMGPROXY_MAX_SRC_FILE_SIZE`: the maximum size of the source image, in bytes. Images with larger file size will be rejected. When set to `0`, file size check is disabled. Default: `0`
|
||||
|
||||
@ -86,7 +86,7 @@ If you don't want to reveal your source URLs, you can encrypt them with the AES-
|
||||
|
||||
* `IMGPROXY_SOURCE_URL_ENCRYPTION_KEY`: hex-encoded key used for source URL encryption. Default: blank
|
||||
|
||||
**📝Note:** Read more about source URL encryption in the [encrypting the source URL guide](encrypting_the_source_url.md).
|
||||
**📝 Note:** Read more about source URL encryption in the [encrypting the source URL guide](encrypting_the_source_url.md).
|
||||
|
||||
imgproxy does not send CORS headers by default. CORS will need to be allowed by using the following variable:
|
||||
|
||||
@ -96,27 +96,27 @@ You can limit allowed source URLs with the following variable:
|
||||
|
||||
* `IMGPROXY_ALLOWED_SOURCES`: a whitelist of source image URL prefixes divided by comma. Wildcards can be included with `*` to match all characters except `/`. When blank, imgproxy allows all source image URLs. Example: `s3://,https://*.example.com/,local://`. Default: blank
|
||||
|
||||
**⚠️Warning:** Be careful when using this config to limit source URL hosts, and always add a trailing slash after the host.
|
||||
**⚠️ Warning:** Be careful when using this config to limit source URL hosts, and always add a trailing slash after the host.
|
||||
|
||||
❌ Bad: `http://example.com`
|
||||
❌ Bad: `http://example.com`
|
||||
|
||||
✅ Good: `http://example.com/`
|
||||
✅ Good: `http://example.com/`
|
||||
|
||||
If the trailing slash is absent, `http://example.com@baddomain.com` would be a permissable URL, however, the request would be made to `baddomain.com`.
|
||||
|
||||
* `IMGPROXY_SANITIZE_SVG`: when true, imgproxy will remove scripts from SVG images to prevent XSS attacks. Defaut: `true`
|
||||
* `IMGPROXY_SANITIZE_SVG`: when `true`, imgproxy will remove scripts from SVG images to prevent XSS attacks. Defaut: `true`
|
||||
|
||||
When using imgproxy in a development environment, it can be useful to ignore SSL verification:
|
||||
|
||||
* `IMGPROXY_IGNORE_SSL_VERIFICATION`: when true, disables SSL verification, so imgproxy can be used in a development environment with self-signed SSL certificates.
|
||||
* `IMGPROXY_IGNORE_SSL_VERIFICATION`: when `true`, disables SSL verification, so imgproxy can be used in a development environment with self-signed SSL certificates.
|
||||
|
||||
Also you may want imgproxy to respond with the same error message that it writes to the log:
|
||||
|
||||
* `IMGPROXY_DEVELOPMENT_ERRORS_MODE`: when true, imgproxy will respond with detailed error messages. Not recommended for production because some errors may contain stack traces.
|
||||
* `IMGPROXY_DEVELOPMENT_ERRORS_MODE`: when `true`, imgproxy will respond with detailed error messages. Not recommended for production because some errors may contain stack traces.
|
||||
|
||||
* `IMGPROXY_ALLOW_SECURITY_OPTIONS`: when `true`, allows usage of security-related processing options such as `max_src_resolution`, `max_src_file_size`, `max_animation_frames`, and `max_animation_frame_resolution`. Default: `false`.
|
||||
|
||||
**⚠️Warning:** `IMGPROXY_ALLOW_SECURITY_OPTIONS` allows bypassing your security restrictions. Don't set it to `true` unless you are completely sure that an attacker can't change your imgproxy URLs.
|
||||
**⚠️ Warning:** `IMGPROXY_ALLOW_SECURITY_OPTIONS` allows bypassing your security restrictions. Don't set it to `true` unless you are completely sure that an attacker can't change your imgproxy URLs.
|
||||
|
||||
## Cookies
|
||||
|
||||
@ -136,11 +136,11 @@ When cookie forwarding is activated, by default, imgproxy assumes the scope of t
|
||||
|
||||
### Advanced JPEG compression
|
||||
|
||||
* `IMGPROXY_JPEG_PROGRESSIVE`: when true, enables progressive JPEG compression. Default: `false`
|
||||
* `IMGPROXY_JPEG_NO_SUBSAMPLE`:  when true, chrominance subsampling is disabled. This will improve quality at the cost of larger file size. Default: `false`
|
||||
* `IMGPROXY_JPEG_TRELLIS_QUANT`:  when true, enables trellis quantisation for each 8x8 block. Reduces file size but increases compression time. Default: `false`
|
||||
* `IMGPROXY_JPEG_OVERSHOOT_DERINGING`:  when true, enables overshooting of samples with extreme values. Overshooting may reduce ringing artifacts from compression, in particular in areas where black text appears on a white background. Default: `false`
|
||||
* `IMGPROXY_JPEG_OPTIMIZE_SCANS`:  when true, splits the spectrum of DCT coefficients into separate scans. Reduces file size but increases compression time. Requires `IMGPROXY_JPEG_PROGRESSIVE` to be true. Default: `false`
|
||||
* `IMGPROXY_JPEG_PROGRESSIVE`: when `true`, enables progressive JPEG compression. Default: `false`
|
||||
* `IMGPROXY_JPEG_NO_SUBSAMPLE`:  when `true`, chrominance subsampling is disabled. This will improve quality at the cost of larger file size. Default: `false`
|
||||
* `IMGPROXY_JPEG_TRELLIS_QUANT`:  when `true`, enables trellis quantisation for each 8x8 block. Reduces file size but increases compression time. Default: `false`
|
||||
* `IMGPROXY_JPEG_OVERSHOOT_DERINGING`:  when `true`, enables overshooting of samples with extreme values. Overshooting may reduce ringing artifacts from compression, in particular in areas where black text appears on a white background. Default: `false`
|
||||
* `IMGPROXY_JPEG_OPTIMIZE_SCANS`:  when `true`, splits the spectrum of DCT coefficients into separate scans. Reduces file size but increases compression time. Requires `IMGPROXY_JPEG_PROGRESSIVE` to be true. Default: `false`
|
||||
* `IMGPROXY_JPEG_QUANT_TABLE`:  quantization table to use. Supported values are:
|
||||
* `0`: Table from JPEG Annex K (default)
|
||||
* `1`: Flat table
|
||||
@ -154,8 +154,8 @@ When cookie forwarding is activated, by default, imgproxy assumes the scope of t
|
||||
|
||||
### Advanced PNG compression
|
||||
|
||||
* `IMGPROXY_PNG_INTERLACED`: when true, enables interlaced PNG compression. Default: `false`
|
||||
* `IMGPROXY_PNG_QUANTIZE`: when true, enables PNG quantization. libvips should be built with [Quantizr](https://github.com/DarthSim/quantizr) or libimagequant support. Default: `false`
|
||||
* `IMGPROXY_PNG_INTERLACED`: when `true`, enables interlaced PNG compression. Default: `false`
|
||||
* `IMGPROXY_PNG_QUANTIZE`: when `true`, enables PNG quantization. libvips should be built with [Quantizr](https://github.com/DarthSim/quantizr) or libimagequant support. Default: `false`
|
||||
* `IMGPROXY_PNG_QUANTIZATION_COLORS`: maximum number of quantization palette entries. Should be between 2 and 256. Default: 256
|
||||
|
||||
<!-- ### Advanced GIF compression
|
||||
@ -175,7 +175,7 @@ When cookie forwarding is activated, by default, imgproxy assumes the scope of t
|
||||
|
||||
imgproxy can calculate the quality of the resulting image based on selected metric. Read more in the [Autoquality](autoquality.md) guide.
|
||||
|
||||
**⚠️Warning:** Autoquality requires the image to be saved several times. Use it only when you prefer the resulting size and quality over the speed.
|
||||
**⚠️ Warning:** Autoquality requires the image to be saved several times. Use it only when you prefer the resulting size and quality over the speed.
|
||||
|
||||
* `IMGPROXY_AUTOQUALITY_METHOD`:  the method of quality calculation. Default: `none`
|
||||
* `IMGPROXY_AUTOQUALITY_TARGET`:  desired value of the autoquality method metric. Default: 0.02
|
||||
@ -198,13 +198,13 @@ imgproxy can use the `Accept` HTTP header to detect if the browser supports AVIF
|
||||
* `IMGPROXY_ENABLE_AVIF_DETECTION`: enables AVIF support detection. When the file extension is omitted in the imgproxy URL and browser supports AVIF, imgproxy will use it as the resulting format.
|
||||
* `IMGPROXY_ENFORCE_AVIF`: enables AVIF support detection and enforces AVIF usage. If the browser supports AVIF, it will be used as resulting format even if another extension is specified in the imgproxy URL.
|
||||
|
||||
**📝Note:** imgproxy prefers AVIF over WebP. This means that if both AVIF and WebP detection/enforcement are enabled and the browser supports both of them, AVIF will be used.
|
||||
**📝 Note:** imgproxy prefers AVIF over WebP. This means that if both AVIF and WebP detection/enforcement are enabled and the browser supports both of them, AVIF will be used.
|
||||
|
||||
**📝Note:** If both the source and the requested image formats support animation and AVIF detection/enforcement is enabled, AVIF won't be used as AVIF sequence is not supported yet.
|
||||
**📝 Note:** If both the source and the requested image formats support animation and AVIF detection/enforcement is enabled, AVIF won't be used as AVIF sequence is not supported yet.
|
||||
|
||||
**📝Note:** When AVIF/WebP support detection is enabled, please take care to configure your CDN or caching proxy to take the `Accept` HTTP header into account while caching.
|
||||
**📝 Note:** When AVIF/WebP support detection is enabled, please take care to configure your CDN or caching proxy to take the `Accept` HTTP header into account while caching.
|
||||
|
||||
**⚠️Warning:** Headers cannot be signed. This means that an attacker can bypass your CDN cache by changing the `Accept` HTTP headers. Keep this in mind when configuring your production caching setup.
|
||||
**⚠️ Warning:** Headers cannot be signed. This means that an attacker can bypass your CDN cache by changing the `Accept` HTTP headers. Keep this in mind when configuring your production caching setup.
|
||||
|
||||
## Preferred formats
|
||||
|
||||
@ -220,7 +220,7 @@ imgproxy is guided by the following rules when choosing the resulting format:
|
||||
4. imgproxy chooses the first preferred format that meets those requirements
|
||||
5. If none of the preferred formats meet the requirements, the first preferred format is used
|
||||
|
||||
**📝Note:** When AVIF/WebP support detection is enabled and the browser supports AVIF/WebP, it may be used as the resultant format even if the preferred formats list doesn't contain it.
|
||||
**📝 Note:** When AVIF/WebP support detection is enabled and the browser supports AVIF/WebP, it may be used as the resultant format even if the preferred formats list doesn't contain it.
|
||||
|
||||
## Skip processing
|
||||
|
||||
@ -228,9 +228,9 @@ You can configure imgproxy to skip processing of some formats:
|
||||
|
||||
* `IMGPROXY_SKIP_PROCESSING_FORMATS`: a list of formats that imgproxy shouldn't process, comma divided.
|
||||
|
||||
**📝Note:** Processing can only be skipped when the requested format is the same as the source format.
|
||||
**📝 Note:** Processing can only be skipped when the requested format is the same as the source format.
|
||||
|
||||
**📝Note:** Video thumbnail processing can't be skipped.
|
||||
**📝 Note:** Video thumbnail processing can't be skipped.
|
||||
|
||||
## Best format
|
||||
|
||||
@ -249,18 +249,18 @@ imgproxy can use the `Width`, `Viewport-Width` or `DPR` HTTP headers to determin
|
||||
|
||||
* `IMGPROXY_ENABLE_CLIENT_HINTS`: enables Client Hints support to determine default width and DPR options. Read more details [here](https://developers.google.com/web/updates/2015/09/automating-resource-selection-with-client-hints) about Client Hints.
|
||||
|
||||
**⚠️Warning:** Headers cannot be signed. This means that an attacker can bypass your CDN cache by changing the `Width`, `Viewport-Width` or `DPR` HTTP headers. Keep this in mind when configuring your production caching setup.
|
||||
**⚠️ Warning:** Headers cannot be signed. This means that an attacker can bypass your CDN cache by changing the `Width`, `Viewport-Width` or `DPR` HTTP headers. Keep this in mind when configuring your production caching setup.
|
||||
|
||||
## Video thumbnails
|
||||
|
||||
imgproxy Pro can extract specific video frames to create thumbnails. This feature is disabled by default, but can be enabled with `IMGPROXY_ENABLE_VIDEO_THUMBNAILS`.
|
||||
|
||||
* `IMGPROXY_ENABLE_VIDEO_THUMBNAILS`:  when true, enables video thumbnail generation. Default: `false`
|
||||
* `IMGPROXY_ENABLE_VIDEO_THUMBNAILS`:  when `true`, enables video thumbnail generation. Default: `false`
|
||||
* `IMGPROXY_VIDEO_THUMBNAIL_SECOND`:  the timestamp of the frame (in seconds) that will be used for a thumbnail. Default: 1
|
||||
* `IMGPROXY_VIDEO_THUMBNAIL_PROBE_SIZE`:  the maximum amount of bytes used to determine the format. Lower values can decrease memory usage but can produce inaccurate data, or even lead to errors. Default: 5000000
|
||||
* `IMGPROXY_VIDEO_THUMBNAIL_MAX_ANALYZE_DURATION`:  the maximum number of milliseconds used to get the stream info. Lower values can decrease memory usage but can produce inaccurate data, or even lead to errors. When set to 0, the heuristic is used. Default: 0
|
||||
|
||||
**⚠️Warning:** Though using `IMGPROXY_VIDEO_THUMBNAIL_PROBE_SIZE` and `IMGPROXY_VIDEO_THUMBNAIL_MAX_ANALYZE_DURATION` can lower the memory footprint of video thumbnail generation, they should be used in production only when you know what you're doing.
|
||||
**⚠️ Warning:** Though using `IMGPROXY_VIDEO_THUMBNAIL_PROBE_SIZE` and `IMGPROXY_VIDEO_THUMBNAIL_MAX_ANALYZE_DURATION` can lower the memory footprint of video thumbnail generation, they should be used in production only when you know what you're doing.
|
||||
|
||||
## Watermark
|
||||
|
||||
@ -425,9 +425,9 @@ Check out the [Prometheus](prometheus.md) guide to learn more.
|
||||
imgproxy can send its metrics to Datadog:
|
||||
|
||||
* `IMGPROXY_DATADOG_ENABLE`: when `true`, enables sending metrics to Datadog. Default: false
|
||||
* `IMGPROXY_DATADOG_ENABLE_ADDITIONAL_METRICS`: when true, enables sending the additional metrics to Datadog. Default: false
|
||||
* `IMGPROXY_DATADOG_ENABLE_ADDITIONAL_METRICS`: when `true`, enables sending the additional metrics to Datadog. Default: false
|
||||
|
||||
**⚠️Warning:** Since the additional metrics are treated by Datadog as custom, Datadog can additionally bill you for their usage. Please, check out Datadog's [Custom Metrics Billing](https://docs.datadoghq.com/account_management/billing/custom_metrics/) page for additional details.
|
||||
**⚠️ Warning:** Since the additional metrics are treated by Datadog as custom, Datadog can additionally bill you for their usage. Please, check out Datadog's [Custom Metrics Billing](https://docs.datadoghq.com/account_management/billing/custom_metrics/) page for additional details.
|
||||
|
||||
Check out the [Datadog](datadog.md) guide to learn more.
|
||||
|
||||
@ -493,7 +493,7 @@ imgproxy can report occurred errors to Bugsnag, Honeybadger and Sentry:
|
||||
* `pretty`: _(default)_ colored human-readable format
|
||||
* `structured`: machine-readable format
|
||||
* `json`: JSON format
|
||||
* `gcp`: Google Cloud Logging agent compliant
|
||||
* `gcp`: Google Cloud Logging agent compliant format
|
||||
* `IMGPROXY_LOG_LEVEL`: the log level. The following levels are supported `error`, `warn`, `info` and `debug`. Default: `info`
|
||||
|
||||
imgproxy can send logs to syslog, but this feature is disabled by default. To enable it, set `IMGPROXY_SYSLOG_ENABLE` to `true`:
|
||||
@ -504,11 +504,11 @@ imgproxy can send logs to syslog, but this feature is disabled by default. To en
|
||||
* `IMGPROXY_SYSLOG_ADDRESS`: the address of the syslog service. Not used if `IMGPROXY_SYSLOG_NETWORK` is blank. Default: blank
|
||||
* `IMGPROXY_SYSLOG_TAG`: the specific syslog tag. Default: `imgproxy`
|
||||
|
||||
**📝Note:** imgproxy always uses structured log format for syslog.
|
||||
**📝 Note:** imgproxy always uses structured log format for syslog.
|
||||
|
||||
## Memory usage tweaks
|
||||
|
||||
**⚠️Warning:** We highly recommended reading the [Memory usage tweaks](memory_usage_tweaks.md) guide before changing these settings.
|
||||
**⚠️ Warning:** We highly recommended reading the [Memory usage tweaks](memory_usage_tweaks.md) guide before changing these settings.
|
||||
|
||||
* `IMGPROXY_DOWNLOAD_BUFFER_SIZE`: the initial size (in bytes) of a single download buffer. When set to zero, initializes empty download buffers. Default: `0`
|
||||
* `IMGPROXY_FREE_MEMORY_INTERVAL`: the interval (in seconds) at which unused memory will be returned to the OS. Default: `10`
|
||||
|
||||
@ -63,7 +63,7 @@ It's 39-byte long, so we should align it to 16 bytes using the PKCS #7 method:
|
||||
http://example.com/images/curiosity.jpg\09\09\09\09\09\09\09\09\09
|
||||
```
|
||||
|
||||
**📝Note:** From this point on, we'll show unprintable characters in `\NN` format where `NN` is a hex representation of the byte.
|
||||
**📝 Note:** From this point on, we'll show unprintable characters in `\NN` format where `NN` is a hex representation of the byte.
|
||||
|
||||
Next, we need an initialization vector (IV). Let's assume we generated the following IV:
|
||||
|
||||
@ -95,4 +95,4 @@ Now you can put this encrypted URL in the imgproxy URL path, prepending it with
|
||||
/unsafe/rs:fit:300:300/enc/p5VjorNdhs7mRRw8gA9TWoRlGci3l1kuzqN43UQlRaRIQ0qtBKW3qFABIsx-ZRz_cVc8iVTYbhsNsxNBL1BHaQ
|
||||
```
|
||||
|
||||
**📝Note:** The imgproxy URL in this example is not signed but signing URLs is especially important when using encrypted source URLs to prevent a padding oracle attack.
|
||||
**📝 Note:** The imgproxy URL in this example is not signed but signing URLs is especially important when using encrypted source URLs to prevent a padding oracle attack.
|
||||
|
||||
@ -104,7 +104,7 @@ mw:%width
|
||||
|
||||
Defines the minimum width of the resulting image.
|
||||
|
||||
**⚠️Warning:** When both `width` and `min-width` are set, the final image will be cropped according to `width`, so use this combination with care.
|
||||
**⚠️ Warning:** When both `width` and `min-width` are set, the final image will be cropped according to `width`, so use this combination with care.
|
||||
|
||||
Default: `0`
|
||||
|
||||
@ -117,7 +117,7 @@ mh:%height
|
||||
|
||||
Defines the minimum height of the resulting image.
|
||||
|
||||
**⚠️Warning:** When both `height` and `min-height` are set, the final image will be cropped according to `height`, so use this combination with care.
|
||||
**⚠️ Warning:** When both `height` and `min-height` are set, the final image will be cropped according to `height`, so use this combination with care.
|
||||
|
||||
Default: `0`
|
||||
|
||||
@ -135,7 +135,7 @@ When set, imgproxy will multiply the image dimensions according to these factors
|
||||
|
||||
Can be combined with `width` and `height` options. In this case, imgproxy calculates scale factors for the provided size and then multiplies it with the provided zoom factors.
|
||||
|
||||
**📝Note:** Unlike [dpr](#dpr), `zoom` doesn't set the `Content-DPR` header in the response.
|
||||
**📝 Note:** Unlike [dpr](#dpr), `zoom` doesn't set the `Content-DPR` header in the response.
|
||||
|
||||
Default: `1`
|
||||
|
||||
@ -147,7 +147,7 @@ dpr:%dpr
|
||||
|
||||
When set, imgproxy will multiply the image dimensions according to this factor for HiDPI (Retina) devices. The value must be greater than 0.
|
||||
|
||||
**📝Note:** `dpr` also sets the `Content-DPR` header in the response so the browser can correctly render the image.
|
||||
**📝 Note:** `dpr` also sets the `Content-DPR` header in the response so the browser can correctly render the image.
|
||||
|
||||
Default: `1`
|
||||
|
||||
@ -245,13 +245,13 @@ Removes surrounding background.
|
||||
* `equal_hor` - _(optional)_ set to `1`, `t` or `true`, imgproxy will cut only equal parts from left and right sides. That means that if 10px of background can be cut off from the left and 5px from the right, then 5px will be cut off from both sides. For example, this can be useful if objects on your images are centered but have non-symmetrical shadow.
|
||||
* `equal_ver` - _(optional)_ acts like `equal_hor` but for top/bottom sides.
|
||||
|
||||
**⚠️Warning:** Trimming requires an image to be fully loaded into memory. This disables scale-on-load and significantly increases memory usage and processing time. Use it carefully with large images.
|
||||
**⚠️ Warning:** Trimming requires an image to be fully loaded into memory. This disables scale-on-load and significantly increases memory usage and processing time. Use it carefully with large images.
|
||||
|
||||
**📝Note:** If you know background color of your images then setting it explicitly via `color` will also save some resources because imgproxy won't need to automatically detect it.
|
||||
**📝 Note:** If you know background color of your images then setting it explicitly via `color` will also save some resources because imgproxy won't need to automatically detect it.
|
||||
|
||||
**📝Note:** Use a `color` value of `FF00FF` for trimming transparent backgrounds as imgproxy uses magenta as a transparency key.
|
||||
**📝 Note:** Use a `color` value of `FF00FF` for trimming transparent backgrounds as imgproxy uses magenta as a transparency key.
|
||||
|
||||
**📝Note:** The trimming of animated images is not supported.
|
||||
**📝 Note:** The trimming of animated images is not supported.
|
||||
|
||||
### Padding
|
||||
|
||||
@ -267,9 +267,9 @@ Defines padding size using CSS-style syntax. All arguments are optional but at l
|
||||
* `bottom` - bottom padding
|
||||
* `left` - left padding
|
||||
|
||||
**📝Note:** Padding is applied after all image transformations (except watermarking) and enlarges the generated image. This means that if your resize dimensions were 100x200px and you applied the `padding:10` option, then you will end up with an image with dimensions of 120x220px.
|
||||
**📝 Note:** Padding is applied after all image transformations (except watermarking) and enlarges the generated image. This means that if your resize dimensions were 100x200px and you applied the `padding:10` option, then you will end up with an image with dimensions of 120x220px.
|
||||
|
||||
**📝Note:** Padding follows the [dpr](#dpr) option so it will also be scaled if you've set it.
|
||||
**📝 Note:** Padding follows the [dpr](#dpr) option so it will also be scaled if you've set it.
|
||||
|
||||
### Auto rotate
|
||||
|
||||
@ -289,7 +289,7 @@ rot:%angle
|
||||
|
||||
Rotates the image on the specified angle. The orientation from the image metadata is applied before the rotation unless autorotation is disabled.
|
||||
|
||||
**📝Note:** Only 0, 90, 180, 270, etc., degree angles are supported.
|
||||
**📝 Note:** Only 0, 90, 180, 270, etc., degree angles are supported.
|
||||
|
||||
Default: 0
|
||||
|
||||
@ -509,7 +509,7 @@ When `%width` is set to `0`, imgproxy will calculate the width using the defined
|
||||
|
||||
When `%height` is set to `0`, imgproxy will calculate the height using the defined width and watermark's aspect ratio.
|
||||
|
||||
**📝Note:** This processing option takes effect only when the `scale` argument of the `watermark` option is set to zero.
|
||||
**📝 Note:** This processing option takes effect only when the `scale` argument of the `watermark` option is set to zero.
|
||||
|
||||
Default: `0:0`
|
||||
|
||||
@ -599,7 +599,7 @@ aq:%method:%target:%min_quality:%max_quality:%allowed_error
|
||||
|
||||
Redefines autoquality settings. All arguments have the same meaning as [Autoquality](configuration.md#autoquality) configs. All arguments are optional and can be omitted.
|
||||
|
||||
**⚠️Warning:** Autoquality requires the image to be saved several times. Use it only when you prefer the resulting size and quality over the speed.
|
||||
**⚠️ Warning:** Autoquality requires the image to be saved several times. Use it only when you prefer the resulting size and quality over the speed.
|
||||
|
||||
### Max bytes
|
||||
|
||||
@ -610,9 +610,9 @@ mb:%bytes
|
||||
|
||||
When set, imgproxy automatically degrades the quality of the image until the image size is under the specified amount of bytes.
|
||||
|
||||
**📝Note:** Applicable only to `jpg`, `webp`, `heic`, and `tiff`.
|
||||
**📝 Note:** Applicable only to `jpg`, `webp`, `heic`, and `tiff`.
|
||||
|
||||
**⚠️Warning:** When `max_bytes` is set, imgproxy saves image multiple times to achieve the specified image size.
|
||||
**⚠️ Warning:** When `max_bytes` is set, imgproxy saves image multiple times to achieve the specified image size.
|
||||
|
||||
Default: 0
|
||||
|
||||
@ -717,9 +717,9 @@ skp:%extension1:%extension2:...:%extensionN
|
||||
|
||||
When set, imgproxy will skip the processing of the listed formats. Also available as the [IMGPROXY_SKIP_PROCESSING_FORMATS](configuration.md#skip-processing) configuration.
|
||||
|
||||
**📝Note:** Processing can only be skipped when the requested format is the same as the source format.
|
||||
**📝 Note:** Processing can only be skipped when the requested format is the same as the source format.
|
||||
|
||||
**📝Note:** Video thumbnail processing can't be skipped.
|
||||
**📝 Note:** Video thumbnail processing can't be skipped.
|
||||
|
||||
Default: empty
|
||||
|
||||
@ -804,7 +804,7 @@ msr:%resolution
|
||||
|
||||
Allows redefining `IMGPROXY_MAX_SRC_RESOLUTION` config.
|
||||
|
||||
**⚠️Warning:** Since this option allows redefining a security restriction, its usage is not allowed unless the `IMGPROXY_ALLOW_SECURITY_OPTIONS` config is set to `true`.
|
||||
**⚠️ Warning:** Since this option allows redefining a security restriction, its usage is not allowed unless the `IMGPROXY_ALLOW_SECURITY_OPTIONS` config is set to `true`.
|
||||
|
||||
### Max src file size
|
||||
|
||||
@ -815,7 +815,7 @@ msfs:%size
|
||||
|
||||
Allows redefining `IMGPROXY_MAX_SRC_FILE_SIZE` config.
|
||||
|
||||
**⚠️Warning:** Since this option allows redefining a security restriction, its usage is not allowed unless the `IMGPROXY_ALLOW_SECURITY_OPTIONS` config is set to `true`.
|
||||
**⚠️ Warning:** Since this option allows redefining a security restriction, its usage is not allowed unless the `IMGPROXY_ALLOW_SECURITY_OPTIONS` config is set to `true`.
|
||||
|
||||
### Max animation frames
|
||||
|
||||
@ -826,7 +826,7 @@ maf:%size
|
||||
|
||||
Allows redefining `IMGPROXY_MAX_ANIMATION_FRAMES` config.
|
||||
|
||||
**⚠️Warning:** Since this option allows redefining a security restriction, its usage is not allowed unless the `IMGPROXY_ALLOW_SECURITY_OPTIONS` config is set to `true`.
|
||||
**⚠️ Warning:** Since this option allows redefining a security restriction, its usage is not allowed unless the `IMGPROXY_ALLOW_SECURITY_OPTIONS` config is set to `true`.
|
||||
|
||||
### Max animation frame resolution
|
||||
|
||||
@ -837,7 +837,7 @@ mafr:%size
|
||||
|
||||
Allows redefining `IMGPROXY_MAX_ANIMATION_FRAME_RESOLUTION` config.
|
||||
|
||||
**⚠️Warning:** Since this option allows redefining a security restriction, its usage is not allowed unless the `IMGPROXY_ALLOW_SECURITY_OPTIONS` config is set to `true`.
|
||||
**⚠️ Warning:** Since this option allows redefining a security restriction, its usage is not allowed unless the `IMGPROXY_ALLOW_SECURITY_OPTIONS` config is set to `true`.
|
||||
|
||||
## Source URL
|
||||
### Plain
|
||||
@ -848,7 +848,7 @@ The source URL can be provided as is, prepended by the `/plain/` segment:
|
||||
/plain/http://example.com/images/curiosity.jpg
|
||||
```
|
||||
|
||||
**📝Note:** If the source URL contains a query string or `@`, you'll need to escape it.
|
||||
**📝 Note:** If the source URL contains a query string or `@`, you'll need to escape it.
|
||||
|
||||
When using a plain source URL, you can specify the [extension](#extension) after `@`:
|
||||
|
||||
|
||||
@ -26,7 +26,7 @@ The source URL can be provided as is, prepended by `/plain/` part:
|
||||
/plain/http://example.com/images/curiosity.jpg
|
||||
```
|
||||
|
||||
**📝Note:** If the source URL contains a query string or `@`, you'll need to escape it.
|
||||
**📝 Note:** If the source URL contains a query string or `@`, you'll need to escape it.
|
||||
|
||||
#### Base64 encoded
|
||||
|
||||
@ -57,7 +57,7 @@ imgproxy responses with a JSON body and returns the following info:
|
||||
* `xmp`: XMP data
|
||||
* `video_meta`: metadata from the video
|
||||
|
||||
**📝Note:** There are lots of IPTC tags in the spec, but imgproxy supports only a few of them. If you need some tags to be supported, just contact us.
|
||||
**📝 Note:** There are lots of IPTC tags in the spec, but imgproxy supports only a few of them. If you need some tags to be supported, just contact us.
|
||||
|
||||
#### Example (JPEG)
|
||||
|
||||
|
||||
@ -34,7 +34,7 @@ Since the processing of animated images is a pretty heavy process, only one fram
|
||||
|
||||
* `IMGPROXY_MAX_ANIMATION_FRAMES`: the maximum of animated image frames to be processed. Default: `1`.
|
||||
|
||||
**📝Note:** imgproxy summarizes all frames resolutions while the checking source image resolution.
|
||||
**📝 Note:** imgproxy summarizes all frames resolutions while the checking source image resolution.
|
||||
|
||||
## Converting animated images to MP4 :id=converting-animated-images-to-mp4
|
||||
|
||||
|
||||
@ -2,7 +2,7 @@
|
||||
|
||||
There are some imgproxy options that can help you optimize memory usage and decrease memory fragmentation.
|
||||
|
||||
**⚠️Warning:** This is an advanced part. Please make sure that you know what you're doing before changing anything.
|
||||
**⚠️ Warning:** This is an advanced part. Please make sure that you know what you're doing before changing anything.
|
||||
|
||||
### IMGPROXY_DOWNLOAD_BUFFER_SIZE
|
||||
|
||||
|
||||
@ -15,7 +15,7 @@ There are three ways to specify a watermark image using environment variables:
|
||||
|
||||
You can also specify the base opacity of a watermark using `IMGPROXY_WATERMARK_OPACITY`.
|
||||
|
||||
**📝Note:** If you're going to use the `scale` argument of `watermark`, it's highly recommended to use SVG, WebP or JPEG watermarks since these formats support scale-on-load.
|
||||
**📝 Note:** If you're going to use the `scale` argument of `watermark`, it's highly recommended to use SVG, WebP or JPEG watermarks since these formats support scale-on-load.
|
||||
|
||||
## Watermarking an image
|
||||
|
||||
|
||||
Loading…
Reference in New Issue
Block a user