Skip to content

thumbnails-and-transcoding.md

Latest commit

 

History

History
96 lines (64 loc) · 2.54 KB

thumbnails-and-transcoding.md

File metadata and controls

96 lines (64 loc) · 2.54 KB

Thumbnails and Transcoding

OxiCloud optimizes image delivery with two complementary features:

  • WebP thumbnail generation in three sizes
  • On-the-fly image transcoding for browsers that advertise WebP support

Both features use a memory cache plus a persistent disk cache and are designed to stay off the request hot path whenever possible.

Thumbnails

Supported sizes

Size Dimensions Directory
icon 150 x 150 .thumbnails/icon/
preview 400 x 400 .thumbnails/preview/
large 800 x 800 .thumbnails/large/

Supported inputs

image/jpeg, image/jpg, image/png, image/gif, and image/webp

All thumbnail outputs are stored as WebP.

API

Method Path Description
GET /api/files/{id}/thumbnail/{size} Fetch a thumbnail
POST /api/files/upload Upload a file and pre-generate thumbnails for supported images

Thumbnail responses include:

  • Content-Type: image/webp
  • Cache-Control: public, max-age=31536000, immutable
  • ETag: "thumb-{id}-{size}"

Generation flow

  1. Upload succeeds through the file API
  2. If the MIME type is supported, OxiCloud starts thumbnail generation in a background task
  3. If a thumbnail is requested before pre-generation completes, the request can generate it lazily
  4. Future requests are served from memory or disk cache

Image Transcoding

OxiCloud can serve a smaller WebP version of uploaded JPEG, PNG, or GIF files when the client advertises WebP support in the Accept header.

Rules

  • Files over 5 MB skip transcoding
  • Existing WebP files are not transcoded again
  • SVG and BMP are not transcoded
  • If the WebP output is larger than the original, OxiCloud serves the original file instead

Storage layout

<storage_path>/
  .transcoded/
    webp/
      <file_id>.webp

Statistics tracked by the service

  • Cache hits
  • Disk hits
  • Successful transcodes
  • Bytes saved
  • Transcode errors

Caching

Both thumbnail and transcode services use:

  • An in-memory LRU cache for hot assets
  • A disk cache for persistent reuse across restarts
  • Fire-and-forget background writes for cache warmup

For the broader cache model across metadata and listings, see Caching Architecture.

Example

Client: GET /api/files/abc-123/download
Accept: image/webp, image/png, */*

Server: checks cache -> transcodes if needed -> returns the smaller asset

Related Pages