Media Previews, Image Cropping, and File Conversion

django-var-cms provides three complementary media capabilities out of the box: modal previews for any file field in list and detail views, a built-in image cropper with rotate and flip support, and a file conversion API that can transform images, audio, video, and PDF files — all without leaving the control panel.

No configuration is needed. When a model field is an ImageField, the list view renders a thumbnail and clicking it opens a full-size preview modal. When a field is a FileField, an icon link is rendered; clicking it opens the appropriate modal player based on the file extension. The icon and modal type are determined by the file extension using the following map:

Extension	Icon	Modal behaviour
`mp4`, `webm`	video icon	Inline `<video>` player
`mp3`, `wav`	music icon	Inline `<audio>` player
`pdf`	file-text icon	Embedded PDF viewer
Any other extension	paperclip icon	Opens/downloads in new tab

You can control the thumbnail dimensions shown in the list view with two attributes on your VarCMSModelAdmin:

class MediaAssetAdmin(VarCMSModelAdmin):
    list_display = ["title", "image", "file"]

    # Thumbnail size in list view (pixels); defaults are 38 × 38
    list_image_width  = 80
    list_image_height = 80

Image Cropper

Every ImageField widget in add/edit forms includes a built-in cropper modal powered by Cropper.js on the frontend and Pillow on the backend. Users can:

Draw a custom crop box
Rotate the image by arbitrary degrees
Flip horizontally and/or vertically
Choose an output format (JPEG, PNG, or WebP)

The cropped result is saved to MEDIA_ROOT/crops/ with a 12-character UUID hex filename and its URL is returned to the frontend to update the form field.

Transform Order

When multiple transforms are applied, they are executed in this order:

Flip — scale_x = -1 flips horizontally; scale_y = -1 flips vertically
Rotate — rotation is applied with expand=True so the full image is preserved
Crop — the crop box (x, y, w, h) is applied to the transformed image

Crop API Endpoint

POST /var-cms/api/media/crop/

All parameters are sent as multipart/form-data (standard POST body).

Parameter	Type	Required	Description
`file_path`	string	✅	Relative media path of the source image (e.g. `var_cms/images/2024/06/photo.jpg`)
`x`	float → int	✅	Left edge of the crop box in pixels
`y`	float → int	✅	Top edge of the crop box in pixels
`w`	float → int	✅	Width of the crop box in pixels
`h`	float → int	✅	Height of the crop box in pixels
`rotate`	float	❌	Rotation in degrees (default `0`)
`scale_x`	float	❌	`-1` to flip horizontally, `1` for no flip (default `1`)
`scale_y`	float	❌	`-1` to flip vertically, `1` for no flip (default `1`)
`format`	string	❌	Output format: `jpeg`, `png`, or `webp` (defaults to source format)

Success response (200 OK):

{
  "url": "/media/crops/3a7f9c1b2d4e.jpg",
  "path": "crops/3a7f9c1b2d4e.jpg",
  "format": "JPEG",
  "size": [800, 600]
}

The size array reflects the dimensions of the cropped image ([width, height]). JPEG output automatically converts RGBA images to RGB.

The crop endpoint is protected by login_required. Unauthenticated requests are redirected to the login page. Cropped images are saved under MEDIA_ROOT/crops/ and are given a 12-character UUID hex filename to avoid collisions.

Media Conversion API

The conversion endpoint can transform images between formats, convert audio and video files via ffmpeg, and rasterise PDF pages to PNG images via pdf2image.

POST /var-cms/api/media/convert/

Parameter	Type	Required	Description
`file_path`	string	✅	Relative media path of the source file
`target_fmt`	string	✅	Desired output extension, e.g. `webp`, `mp3`, `mp4`, `png`

Supported Conversions

Images (Pillow)
Audio & Video (ffmpeg)
PDF to Images (pdf2image)

Image-to-image conversion is handled entirely by Pillow — no external binaries required.Supported formats: jpeg / jpg, png, webp, bmp, tiff, gifAny combination of these formats can be converted to any other. Images in RGBA or palette (P) mode are automatically converted to RGB when the target is JPEG. Converted images are saved with quality=90.Success response:

{
  "url": "/media/converted/8c3a1f920b44.webp",
  "path": "converted/8c3a1f920b44.webp",
  "type": "image"
}

Audio and video conversions are delegated to ffmpeg, which must be installed on the server. The ffmpeg process has a timeout of 120 seconds.Audio formats: mp3, wav, ogg, flac, aac, m4aVideo formats: mp4, webm, avi, mov, mkvCross-type conversions (e.g. video → audio) are also supported by ffmpeg.Success response:

{
  "url": "/media/converted/2b9d4e7a3c81.mp3",
  "path": "converted/2b9d4e7a3c81.mp3",
  "type": "audio"
}

If ffmpeg is not found on the system, the endpoint returns a 500 error with an install hint:

{
  "error": "ffmpeg not found. Install with: sudo apt install ffmpeg",
  "install_hint": "sudo apt install ffmpeg"
}

A PDF can be rasterised into one PNG image per page at 150 DPI. This requires pdf2image and the poppler system library.Supported target format: png (PDF pages are always saved as PNG regardless of the target_fmt value)Success response:

{
  "type": "pdf_pages",
  "pages": [
    "/media/converted/a1b2c3d4e5f6.png",
    "/media/converted/9f8e7d6c5b4a.png"
  ],
  "count": 2
}

Page files are saved to MEDIA_ROOT/converted/ with 12-character UUID hex filenames.If pdf2image is not installed, the endpoint returns a 500 error:

{
  "error": "pdf2image not installed. Run: uv add pdf2image",
  "install_hint": "uv add pdf2image"
}

Converted files are saved to MEDIA_ROOT/converted/ with 12-character UUID hex filenames.

Requirements

Capability	Requirement	How to install
Image previews & cropping	Pillow	`pip install pillow` (included in standard install)
Image format conversion	Pillow	Already required
Audio / video conversion	ffmpeg binary	`sudo apt install ffmpeg`
PDF to images	pdf2image + poppler	`pip install pdf2image` + `sudo apt install poppler-utils`

Pillow is a hard requirement for django-var-cms. Install it alongside the package:

pip install django-var-cms pillow

Without Pillow, the crop endpoint returns a 500 error and image thumbnails will not render.

For PDF support you can use the bundled extra:

pip install django-var-cms[pdf]

This installs pdf2image automatically. You still need poppler-utils as a system package (sudo apt install poppler-utils on Debian/Ubuntu).

Get Started

Model Registration

Permissions

Features

Integrations

Media Previews, Image Cropping, and File Conversion

Image Cropper

Transform Order

Crop API Endpoint

Media Conversion API

Supported Conversions

Requirements

Build docs developers (and LLMs) love

Get Started

Model Registration

Permissions

Features

Integrations

Documentation Index

​Modal Previews

​Image Cropper

​Transform Order

​Crop API Endpoint

​Media Conversion API

​Supported Conversions

​Requirements

Build docs developers (and LLMs) love

Modal Previews

Image Cropper

Transform Order

Crop API Endpoint

Media Conversion API

Supported Conversions

Requirements