Update changelog and api_versions file

API_VERSIONS.md

@@ -5,6 +5,40 @@ All backward-incompatible FreeFeed API changes will be documented in this file.
 See the [About API versions](#about-api-versions) section in the end of this
 file for the general versioning information.
 
+## [4] - 2025-02-01
+### Changed
+- The attachment serialization is changed. The new format contains the following
+  fields:
+  - _id_ (string) - the UUID of the attachment
+  - _mediaType_ (string) - the media type of the attachment, one of 'image',
+    'video', 'audio', 'general'
+  - _fileName_ (string) - the original filename of the attachment
+  - _fileSize_ (number) - the size of the attachment's original file in bytes
+  - _previewTypes_ (array of string) - the array of available preview types of
+    the attachment, can be empty or contains the following values: 'image',
+    'video', 'audio'
+  - _meta_ (object) - optional field with temporary or not essential media
+    metadata (all fields are optional):
+    - _dc:title_: the audio/video title
+    - _dc:creator_: the audio/video author name
+    - _animatedImage_: true if the video was created from an animated image
+    - _silent_: true if the video has no audio track
+    - _inProgress_: true if the media file is currently being processed
+  - _width_ and _height_ (number) - the size of the original image/video file in
+    pixels, presents only for 'image' and 'video' attachments, and when the
+    processing is done
+  - _duration_ (number) - the duration of the audio/video file in seconds,
+    present only for 'audio' and 'video' attachments, and when the processing is
+    done
+  - _previewWidth_ and _previewHeight_ (number) - the size of the maximum
+    available image/video preview in pixels, presents only when different from
+    the _width_ and _height_
+  - _postId_ (string|null) - the UUID of the post to which the attachment is
+    attached
+  - _createdBy_ (string) - the UUID of the user who uploaded the attachment
+  - _createdAt_ (string) - the ISO 8601 datetime when the attachment was created
+  - _updatedAt_ (string) - the ISO 8601 datetime when the attachment was updated
+
 ## [3] - 2024-06-21
 
 ### Changed

CHANGELOG.md

@@ -6,7 +6,49 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
 ## [2.23.0] - Not released
-### Added
+### Changed
+- The media files (attachments) handling algorithm has been changed. There are
+  four media types now: 'image', 'video', 'audio' and 'general'. Images are
+  accepted in JPEG, PNG, WebP, GIF, HEIC/HEIF and AVIF formats. Also now we
+  accept and process arbitrary formats of video and audio files (detected with
+  ffmpeg).
+
+  For the visual files (images and videos), the multiple preview sizes are
+  created, in addition to the legacy 'thumbnail' and 'thumbnail2'.
+
+  The animated GIF images are now treated as video files and the video previews
+  are created for them.
+
+  We don't keep the originals for the truly (not from animated images) video
+  files. After the preview creation, the largest preview is kept as the
+  'original'.
+
+  Some media files (the truly video ones for now) are processed asynchronously.
+  Right after they are uploaded to the server, the asynchronous job is
+  scheduled, and after the job finishes, the 'attachment:update' realtime event
+  is sent to the 'user:{ownerId}', 'attachment:{attachmentId}' and
+  'post:{postId}' (if the file is attached to a post) channels.
+
+  The `attachments` table now has a few new columns:
+  - `width` and `height`: size of the original image or video file in pixels
+    (null for non-visual files)
+  - `duration`: duration of the video or audio in seconds (null for non-playable
+    files)
+  - `previews`: JSON object with preview types and sizes, see the
+    _MediaPreviews_ type in the
+    [app/support/media-files/types.ts](app/support/media-files/types.ts) file.
+  - `meta`: JSON object with temporary or not essential media metadata. It can
+    contain the audio/video title and author name (in 'dc:title' and
+    'dc:creator' fields, respectively) and some special flags:
+    - `animatedImage`: true if the video was created from an animated image
+    - `silent`: true if the video has no audio track
+    - `inProgress`: true if the media file is currently being processed
+### Added
+- The new V4 API version is introduced, to support the new attachment features.
+  See the new serialized attachment type `SerializedAttachmentV4` in the
+  [app/serializers/v2/attachment.ts](app/serializers/v2/attachment.ts) file.
+- The new `GET /vN/attachments/:attId` API endpoint returns the attachment by
+  its ID.
 - Allow to limit the number of simultaneous executions for some job types.
 
   The JobManager now has a `limitedJobs` parameter of type `Record<string,

app/serializers/v2/attachment.ts

@@ -26,10 +26,16 @@ type SerializedAttachmentV4 = {
   fileName: string;
   fileSize: number;
   previewTypes: (keyof MediaPreviews)[];
+  // File metadata, don't send if empty
   meta?: MediaMetaData;
+  // Original size, only send for visual types (image, video), and when the
+  // processing is done
   width?: number;
   height?: number;
+  // Duration in seconds, only for playable files (video, audio), and when the
+  // processing is done
   duration?: number;
+  // Maximum possible preview size, only when different from the (width, height)
   previewWidth?: number;
   previewHeight?: number;