+Media preview proxy: image previews in configured sizes besides the thumbnail (`image_sizes`), listed on image attachments as `pleroma.image_sizes`, optionally as AVIF (`avif`); the Docker image adds `vips-heif` for it.
"Min content length (in bytes) to perform preview. Media smaller in size will be served without thumbnailing."
+ },
+ %{
+ key: :image_sizes,
+ type: {:list, :integer},
+ description:
+ "Sizes (the longer side, in pixels) of image previews besides the thumbnail, offered to clients so they can show an image fitting the screen instead of the original. Only these sizes are served. An empty list turns them off.",
+ suggestions: [[960, 1600, 2560]]
+ },
+ %{
+ key: :avif,
+ type: :boolean,
+ description:
+ "Serve the image sizes as AVIF to clients that accept it (about 40% smaller than JPEG at the same quality, but several times slower to encode: put a cache in front). Needs a libvips with libheif and an AV1 encoder (the Docker image has them); without one, the sizes stay JPEG/PNG."
+ },
+ %{
+ key: :avif_quality,
+ type: :integer,
+ description: "Quality of AVIF previews, 0 to 100.",
+ suggestions: [55]
+ },
+ %{
+ key: :avif_effort,
+ type: :integer,
+ description:
+ "CPU effort of the AVIF encoder, 0 (fastest) to 9 (smallest files). Each step up costs much more time for a little less size.",
@@ -392,6 +392,10 @@ This section describe PWA manifest instance-specific values. Currently this opti
* `thumbnail_max_height`: Max height of preview thumbnail for images (video preview always has original dimensions).
* `image_quality`: Quality of the output. Ranges from 0 (min quality) to 100 (max quality).
* `min_content_length`: Min content length to perform preview, in bytes. If greater than 0, media smaller in size will be served as is, without thumbnailing.
+* `image_sizes`: Sizes of image previews besides the thumbnail, as the longer side in pixels (default: `[960, 1600, 2560]`). The API lists them on each image attachment (`pleroma.image_sizes`, only the sizes smaller than the image), so that clients can show an image fitting the screen instead of the original. A preview of such a size is `/proxy/preview/…?size=1600`; other sizes redirect to the thumbnail. An empty list turns them off. Every preview is made on request, so put a cache in front of `/proxy` (see the nginx example config) to resize each image only once per size.
+* `avif`: Serve the `image_sizes` as AVIF to clients whose `Accept` header includes `image/avif` (default: `false`). AVIF is about 40% smaller than JPEG at the same quality, but encoding takes several times longer, so a cache in front of `/proxy` matters even more. The responses carry `Vary: Accept`: a cache or CDN in front must honour it, or it would give one format to everyone. Needs a libvips with libheif and an AV1 encoder (on Alpine: `vips-heif`, also when compiling Vix); without one, the sizes stay JPEG or PNG. Thumbnails stay JPEG or PNG.
+* `avif_quality`: Quality of the AVIF previews, 0 to 100 (default: `55`).
+* `avif_effort`: CPU effort of the AVIF encoder, 0 (fastest) to 9 (smallest files) (default: `3`).
@@ -54,6 +54,32 @@ defmodule Pleroma.Web.ApiSpec.Schemas.Attachment do
name: %Schema{
type: :string,
description: "Name of the attachment, typically the filename"
+ },
+ image_sizes: %Schema{
+ type: :array,
+ description:
+ "Previews of an image in the sizes the instance offers, for a client to pick from (as in srcset); only sizes smaller than the image. Absent when there are none (no media preview proxy, not an image, a GIF).",
+ items: %Schema{
+ type: :object,
+ required: [:size, :url],
+ properties: %{
+ size: %Schema{
+ type: :integer,
+ description: "The longer side of the preview's box, in pixels"
+ },
+ width: %Schema{
+ type: :integer,
+ description:
+ "Width of the preview (approximate), when the image's dimensions are known"
+ },
+ height: %Schema{
+ type: :integer,
+ description:
+ "Height of the preview (approximate), when the image's dimensions are known"
+ },
+ url: %Schema{type: :string, format: :uri, description: "The preview's URL"}