Add JPEG XL docs

imgproxy · Dec 8, 2024 · cb18a7c · cb18a7c
1 parent 78ba19d
commit cb18a7c
Show file tree

Hide file tree

Showing 5 changed files with 29 additions and 10 deletions.
diff --git a/docs/configuration/options.mdx b/docs/configuration/options.mdx
@@ -166,7 +166,7 @@ When cookie forwarding is activated, by default, imgproxy assumes the scope of t
 ## Compression
 
 * [`IMGPROXY_QUALITY`]: the default quality of the resultant image, percentage. Default: `80`
-* [`IMGPROXY_FORMAT_QUALITY`]: default quality of the resulting image per format, separated by commas. Example: `jpeg=70,avif=40,webp=60`. When a value for the resulting format is not set, the `IMGPROXY_QUALITY` value is used. Default: `avif=65`
+* [`IMGPROXY_FORMAT_QUALITY`]: default quality of the resulting image per format, separated by commas. Example: `jpeg=70,avif=40,webp=60`. When a value for the resulting format is not set, the `IMGPROXY_QUALITY` value is used. Default: `avif=65,jxl=77`
 
 ### Advanced JPEG compression
 
@@ -201,6 +201,10 @@ When cookie forwarding is activated, by default, imgproxy assumes the scope of t
 
 * [`IMGPROXY_AVIF_SPEED`]: controls the CPU effort spent improving compression. The lowest speed is at 0 and the fastest is at 9. Default: `9`
 
+### Advanced JPEG XL compression
+
+* [`IMGPROXY_JXL_EFFORT`]: controls the CPU effort spent improving compression. The larger the value, the slower the encoding process but the better the compression. The value should be between 1 and 9. Default: `4`
+
 ### Autoquality
 
 imgproxy can calculate the quality of the resulting image based on selected metric. Read more in the [Autoquality](../features/autoquality.mdx) guide.
@@ -220,30 +224,37 @@ Autoquality requires the image to be saved several times. Use it only when you p
 * [`IMGPROXY_AUTOQUALITY_JPEG_NET`]: ((pro)) the path to the neural network for JPEG.
 * [`IMGPROXY_AUTOQUALITY_WEBP_NET`]: ((pro)) the path to the neural network for WebP.
 * [`IMGPROXY_AUTOQUALITY_AVIF_NET`]: ((pro)) the path to the neural network for AVIF.
+* [`IMGPROXY_AUTOQUALITY_JXL_NET`]: ((pro)) the path to the neural network for JPEG XL.
 
 ## SVG processing
 * [`IMGPROXY_SVG_FIX_UNSUPPORTED`]: when `true`, imgproxy will try to replace SVG features unsupported by librsvg to minimize SVG rendering error. This config only takes effect on SVG rasterization. Default: `false`
 * [`IMGPROXY_ALWAYS_RASTERIZE_SVG`]: when `true`, imgproxy will always rasterize SVG images unless SVG processing is not [skipped](#skip-processing). Default: `false`
 
-## AVIF/WebP support detection
+## AVIF/WebP/JPEG XL support detection
 
-imgproxy can use the `Accept` HTTP header to detect if the browser supports AVIF or WebP and use it as the default format. This feature is disabled by default and can be enabled by the following options:
+imgproxy can use the `Accept` HTTP header to detect if the browser supports AVIF, WebP, or JPEG XL and use it as the default format. This feature is disabled by default and can be enabled by the following options:
 
 * [`IMGPROXY_AUTO_WEBP`]: _(deprecated alias: [`IMGPROXY_ENABLE_WEBP_DETECTION`])_ enables WebP support detection. When the file extension is omitted in the imgproxy URL and browser supports WebP, imgproxy will use it as the resulting format.
 * [`IMGPROXY_ENFORCE_WEBP`]: enables WebP support detection and enforces WebP usage. If the browser supports WebP, it will be used as resulting format even if another extension is specified in the imgproxy URL.
 * [`IMGPROXY_AUTO_AVIF`]: _(deprecated alias: [`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.
+* [`IMGPROXY_AUTO_JXL`]: enables JPEG XL support detection. When the file extension is omitted in the imgproxy URL and browser supports JPEG XL, imgproxy will use it as the resulting format.
+* [`IMGPROXY_ENFORCE_JXL`]: enables JPEG XL support detection and enforces JPEG XL usage. If the browser supports JPEG XL, it will be used as the resulting format even if another extension is specified in the imgproxy URL.
 
 :::info
-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.
+If multiple format detection/enforcement options are enabled, and the browser supports multiple of them, imgproxy will use the format with the highest priority. The priority is as follows (from the highest to the lowest): JPEG XL, AVIF, WebP
 :::
 
 :::info
 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.
 :::
 
+:::info
+If both the source and the requested image formats support animation and JPEG XL detection/enforcement is enabled, JPEG XL won't be used as animated JPEG XL is not widely supported by browsers yet.
+:::
+
 :::tip
-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.
+When AVIF/WebP/JPEG XL 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
@@ -265,7 +276,7 @@ imgproxy is guided by the following rules when choosing the resulting format:
 5. If none of the preferred formats meet the requirements, the first preferred format is used
 
 :::info
-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.
+When AVIF/WebP/JPEG XL support detection is enabled and the browser supports AVIF/WebP/JPEG XL, it may be used as the resultant format even if the preferred formats list doesn't contain it.
 :::
 
 ## Skip processing

diff --git a/docs/features/autoquality.mdx b/docs/features/autoquality.mdx
@@ -111,10 +111,11 @@ IMGPROXY_AUTOQUALITY_MAX=80
 # Quality 50 for AVIF is pretty the same as 80 for JPEG
 IMGPROXY_AUTOQUALITY_FORMAT_MIN="avif=40"
 IMGPROXY_AUTOQUALITY_FORMAT_MAX="avif=50"
-# Neural networks paths for JPEG, WebP, and AVIF
+# Neural networks paths for JPEG, WebP, AVIF, and JPEG XL
 IMGPROXY_AUTOQUALITY_JPEG_NET="/networks/autoquality-jpeg.pb"
 IMGPROXY_AUTOQUALITY_WEBP_NET="/networks/autoquality-webp.pb"
 IMGPROXY_AUTOQUALITY_AVIF_NET="/networks/autoquality-avif.pb"
+IMGPROXY_AUTOQUALITY_JXL_NET="/networks/autoquality-jxl.pb"
 ```
 
 :::info

diff --git a/docs/features/best_format.mdx b/docs/features/best_format.mdx
@@ -10,11 +10,11 @@ You can use the `best` value for the [format](../usage/processing.mdx#format) op
 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.
 
 :::info
-imgproxy uses only the formats listed as [preferred](../configuration/options.mdx#preferred-formats) when choosing the best format. It may also use AVIF or WebP if [AVIF/WebP support detection](../configuration/options.mdx#avifwebp-support-detection) is enabled.
+imgproxy uses only the formats listed as [preferred](../configuration/options.mdx#preferred-formats) when choosing the best format. It may also use AVIF, WebP, or JPEG XL if [AVIF/WebP/JPEG XL support detection](../configuration/options.mdx#avifwebpjpeg-xl-support-detection) is enabled.
 :::
 
 :::info
-imgproxy will use AVIF or WebP _only_ if [AVIF/WebP support detection](../configuration/options.mdx#avifwebp-support-detection) is enabled.
+imgproxy will use AVIF, WebP, or JPEG XL _only_ if [AVIF/WebP/JPEG XL support detection](../configuration/options.mdx#avifwebpjpeg-xl-support-detection) is enabled.
 :::
 
 :::info

diff --git a/docs/image_formats_support.mdx b/docs/image_formats_support.mdx
@@ -10,6 +10,7 @@ At the moment, imgproxy supports only the most popular image formats:
 | ----------------------------|-----------|--------------------------------|---------------------------|
 | PNG                         | `png`     | :white_check_mark:             | :white_check_mark:        |
 | JPEG                        | `jpg`     | :white_check_mark:             | :white_check_mark:        |
+| JPEG XL                     | `jxl`     | :white_check_mark:             | [See notes](#jxl-support) |
 | WebP                        | `webp`    | :white_check_mark:             | :white_check_mark:        |
 | AVIF                        | `avif`    | :white_check_mark:             | :white_check_mark:        |
 | GIF                         | `gif`     | :white_check_mark:             | :white_check_mark:        |
@@ -22,6 +23,12 @@ At the moment, imgproxy supports only the most popular image formats:
 | MP4 (h264) ((pro))          | `mp4`     | [See notes](#video-thumbnails) | :white_check_mark:        |
 | Other video formats ((pro)) |           | [See notes](#video-thumbnails) | :x:                       |
 
+## JPEG XL support {#jxl-support}
+
+imgproxy supports JPEG XL as a source format without limitations.
+
+When JPEG XL is used as a result format, animations are not supported because animated JPEG XL is not yet supported by browsers.
+
 ## SVG support
 
 imgproxy supports SVG sources without limitations, but SVG results are not supported when the source image is not SVG.

diff --git a/docs/usage/processing.mdx b/docs/usage/processing.mdx
@@ -1168,7 +1168,7 @@ When using an encrypted source URL, you can specify the [extension](#extension)
 
 Extension specifies the format of the resulting image. Read more about image formats support [here](../image_formats_support.mdx).
 
-The extension can be omitted. In this case, imgproxy will use the source image format as resulting one. If the source image format is not supported as the resulting image, imgproxy will use `jpg`. You also can [enable AVIF or WebP support detection](../configuration/options.mdx#avifwebp-support-detection) to use it as the default resulting format when possible.
+The extension can be omitted. In this case, imgproxy will use the source image format as resulting one. If the source image format is not supported as the resulting image, imgproxy will use `jpg`. You also can [enable AVIF, WebP, or JPEG XL support detection](../configuration/options.mdx#avifwebpjpeg-xl-support-detection) to use it as the default resulting format when possible.
 
 ### Best format ((pro))