From 19dd8c13a2c164f92a518d141fa542d991872353 Mon Sep 17 00:00:00 2001 From: asonix Date: Fri, 8 Dec 2023 22:58:43 -0600 Subject: [PATCH] Add animation and media documentation --- releases/0.5.0.md | 99 +++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 99 insertions(+) diff --git a/releases/0.5.0.md b/releases/0.5.0.md index 3e3c5b0..0c0c17e 100644 --- a/releases/0.5.0.md +++ b/releases/0.5.0.md @@ -145,9 +145,108 @@ and in the example [pict-rs.toml](https://git.asonix.dog/asonix/pict-rs/src/bran ### Improved Animation Support +pict-rs 0.4 only supported `gif` for animated images. This decision had been made due to the +format's poor support for higher-resolution animations with higher framerates compared to silent +videos for a given file size. In pict-rs 0.5, animated images are now supported to the same extent +as still images. Available formats for animated images include apng, avif, gif, and webp (although +not jxl yet). + +With this support for more animated file types, pict-rs no longer transcodes larger animations into +videos. Instead, animated images will be left in their original format unless an override is +configured, and the default values for maximum animation dimensions, file size, and frame count have +been increased. + +Configuration related to animations has been moved from `[media.gif]` to `[media.animation]` to +better reflect what it applies to. + +For all configuration options regarding animations, see the example +[pict-rs.toml](https://git.asonix.dog/asonix/pict-rs/src/branch/main/pict-rs.toml). + ### Media Configuration +pict-rs 0.5 splits media configuration further, allowing images, animations, and videos to each +specify their own maximum file size, dimensions, frame counts, etc, in addition to a few global +limits. Relevant sections of configuration are `[media]`, `[media.image]`, `[media.animation]`, and +`[media.video]`. + +A list of updated and moved configuration values can be found below. + +##### Image Changes +| Old Environment Variable | New Environment Variable | +| ------------------------------ | ------------------------------------- | +| `PICTRS__MEDIA__FORMAT` | `PICTRS__MEDIA__IMAGE__FORMAT` | +| `PICTRS__MEDIA__MAX_WIDTH` | `PICTRS__MEDIA__IMAGE__MAX_WIDTH` | +| `PICTRS__MEDIA__MAX_HEIGHT` | `PICTRS__MEDIA__IMAGE__MAX_HEIGHT` | +| `PICTRS__MEDIA__MAX_AREA` | `PICTRS__MEDIA__IMAGE__MAX_AREA` | +| | `PICTRS__MEDIA__IMAGE__MAX_FILE_SIZE` | + +| Old TOML Value | New TOML Value | +| ----------------------- | ----------------------------- | +| `[media] format` | `[media.image] format` | +| `[media] max_width` | `[media.image] max_width` | +| `[media] max_height` | `[media.image] max_height` | +| `[media] max_area` | `[media.image] max_area` | +| | `[media.image] max_file_size` | + +##### Animation Changes +| Old Environment Variable | New Environment Variable | +| ------------------------------------- | ------------------------------------------- | +| `PICTRS__MEDIA__GIF__MAX_WIDTH` | `PICTRS__MEDIA__ANIMATION__MAX_WIDTH` | +| `PICTRS__MEDIA__GIF__MAX_HEIGHT` | `PICTRS__MEDIA__ANIMATION__MAX_HEIGHT` | +| `PICTRS__MEDIA__GIF__MAX_AREA` | `PICTRS__MEDIA__ANIMATION__MAX_AREA` | +| `PICTRS__MEDIA__GIF__MAX_FILE_SIZE` | `PICTRS__MEDIA__ANIMATION__MAX_FILE_SIZE` | +| `PICTRS__MEDIA__GIF__MAX_FRAME_COUNT` | `PICTRS__MEDIA__ANIMATION__MAX_FRAME_COUNT` | +| | `PICTRS__MEDIA__ANIMATION__FORMAT` | +| | `PICTRS__MEDIA__ANIMATION__MAX_FILE_SIZE` | + +| Old TOML Value | New TOML Value | +| ----------------------------- | ----------------------------------- | +| `[media.gif] max_width` | `[media.animation] max_width` | +| `[media.gif] max_height` | `[media.animation] max_height` | +| `[media.gif] max_area` | `[media.animation] max_area` | +| `[media.gif] max_file_size` | `[media.animation] max_file_size` | +| `[media.gif] max_frame_count` | `[media.animation] max_frame_count` | +| | `[media.animation] format` | +| | `[media.animation] max_file_size` | + +##### Video Changes +| Old Environment Variable | New Environment Variable | +| ------------------------------------ | --------------------------------------- | +| `PICTRS__MEDIA__ENABLE_SILENT_VIDEO` | `PICTRS__MEDIA__VIDEO__ENABLE` | +| `PICTRS__MEDIA__ENABLE_FULL_VIDEO` | `PICTRS__MEDIA__VIDEO__ALLOW_AUDIO` | +| `PICTRS__MEDIA__VIDEO_CODEC` | `PICTRS__MEDIA__VIDEO__VIDEO_CODEC` | +| `PICTRS__MEDIA__AUDIO_CODEC` | `PICTRS__MEDIA__VIDEO__AUDIO_CODEC` | +| `PICTRS__MEDIA__MAX_FRAME_COUNT` | `PICTRS__MEDIA__VIDEO__MAX_FRAME_COUNT` | +| `PICTRS__MEDIA__ENABLE_FULL_VIDEO` | `PICTRS__MEDIA__VIDEO__ALLOW_AUDIO` | +| | `PICTRS__MEDIA__VIDEO__MAX_WIDTH` | +| | `PICTRS__MEDIA__VIDEO__MAX_HEIGHT` | +| | `PICTRS__MEDIA__VIDEO__MAX_AREA` | +| | `PICTRS__MEDIA__VIDEO__MAX_FILE_SIZE` | + +| Old TOML Value | New TOML Value | +| ----------------------------- | ------------------------------- | +| `[media] enable_silent_video` | `[media.video] enable` | +| `[media] enable_full_video` | `[media.video] allow_audio` | +| `[media] video_codec` | `[media.video] video_codec` | +| `[media] audio_codec` | `[media.video] audio_codec` | +| `[media] max_frame_count` | `[media.video] max_frame_count` | +| `[media] enable_full_video` | `[media.video] allow_audio` | +| | `[media.video] max_width` | +| | `[media.video] max_height` | +| | `[media.video] max_area` | +| | `[media.video] max_file_size` | + +Note that although each media type now includes its own `MAX_FILE_SIZE` configuration, the +`PICTRS__MEDIA__MAX_FILE_SIZE` value still exists as a global limit for any file type. + +In addition to all the configuration options mentioned above, there are now individual quality +settings that can be configured for each image and animation type, as well as for video files. +Please see the [pict-rs.toml](./pict-rs.toml) file for more information. + +For all configuration options regarding media, see the example +[pict-rs.toml](https://git.asonix.dog/asonix/pict-rs/src/branch/main/pict-rs.toml). + ### Improved Collision Resistance