Variant generation system for images and videos.
This module handles the creation of different variants (thumbnails, resizes, quality adjustments) for uploaded files based on dimension configurations.
Supported Operations
Images
- Resize to specific dimensions
- Generate thumbnails (square crops)
- Quality adjustments
- Format conversion (JPEG, PNG, WebP)
Videos
- Quality variants (360p, 720p, 1080p)
- Thumbnail extraction
- Format conversion (MP4)
Dependencies
Requires external tools to be installed:
- Images: ImageMagick (
convertandidentifycommands) - Videos: FFmpeg
Summary
Functions
The variants file should have by its library's variant set (V205), as
{dimension, variant_name, format}: every enabled size for its type and
each of its alternative formats. [] for a file no sizes are made of
(system-managed, not an image, video or PDF) or whose set makes none.
Generates a specific variant for a file.
Generates variant_name of file from dimension in format: the
size's own format, or one of its alternative formats ("medium_webp"
from medium in "webp"). What the reconciler uses to make one missing
or stale variant (expected_variants/1 lists them).
Generates variants for a file based on enabled dimensions.
Stores an already-rendered variant file as variant_name on file.
Whether sizes are made of file at all (by its type, not its set).
System-managed media (Tessera DZI tiles + manifests) never get quality
variants — a tile is already 256×256, generating a smaller tile-of-a-tile
would waste CPU and disk for no user-facing value.
Functions
The variants file should have by its library's variant set (V205), as
{dimension, variant_name, format}: every enabled size for its type and
each of its alternative formats. [] for a file no sizes are made of
(system-managed, not an image, video or PDF) or whose set makes none.
Generates a specific variant for a file.
Parameters
file- The file structdimension- The dimension configuration
Returns
{:ok, file_instance}- Generated variant{:error, reason}- Error if generation fails
Generates variant_name of file from dimension in format: the
size's own format, or one of its alternative formats ("medium_webp"
from medium in "webp"). What the reconciler uses to make one missing
or stale variant (expected_variants/1 lists them).
Generates variants for a file based on enabled dimensions.
Parameters
file- The file struct to generate variants foropts- Options for variant generation
Options
:dimensions- List of specific dimensions to generate (default: all enabled)
Variant generation is always synchronous from the caller's perspective.
Internally process_variants/2 parallelizes the per-dimension work via
Task.await_many/2 with a 10-minute cap. Callers that need fire-and-forget
semantics should enqueue the work via Oban (see process_file_job.ex).
Returns
{:ok, variants}- List of generated file instances{:error, reason}- Error if generation fails
Stores an already-rendered variant file as variant_name on file.
Use this when the variant bytes are produced outside the normal resize
pipeline (e.g. the baked annotated thumbnail). Handles stats, bucket storage,
the FileInstance row, and file-location records — then removes prepared_path.
Pass source_key: — the file_name of the original instance the bytes
were made from (Storage.retrieve_original/1) — and the variant is only
recorded while that is still the file's original.
Returns {:ok, instance} or {:error, reason}.
Whether sizes are made of file at all (by its type, not its set).
System-managed media (Tessera DZI tiles + manifests) never get quality
variants — a tile is already 256×256, generating a smaller tile-of-a-tile
would waste CPU and disk for no user-facing value.