Previews and renditions

After an upload, processing makes renditions of the files it can read: smaller images for lists and feeds, the first page of a PDF, a poster and playable MP4 files for a video. Your app shows those instead of the original, and the preview call picks the right one for you. This page is for developers who show files; the sizes and formats are on Renditions and formats.

What each kind gets

Source	Renditions
Images (JPEG, PNG, WebP, GIF, TIFF, AVIF, HEIC, HEIF)	`thumbnail` (256), `preview` (1280) and `large` (2048), WebP, orientation applied, never upscaled, without camera metadata
PDF	`thumbnail` (256) and `preview` (1280): the first page, WebP
Video	`poster` (a JPEG frame near the start) and `thumbnail` from it; `mp4_720p` and `mp4_1080p` for playback
Office documents (Word, Excel, PowerPoint, OpenDocument, RTF)	None: there is no Office preview. Their text is still extracted for content search
Everything else	None

Renditions are made in the background: file.ready says which ones are ready. They do not count against the quota. The application can switch them off (renditions_enabled).

Playable video

Phones and cameras record in many formats that not every browser plays. Each video gets H.264 MP4 renditions that every browser and mobile player plays, with AAC stereo sound, the index at the front so playback starts before the download finishes, and no metadata (a phone’s location in the original is not copied):

Rendition	Size	Made when
`mp4_720p`	The short side 720 pixels, or the source’s own size when it is smaller	Always, within the limits below
`mp4_1080p`	The short side 1080 pixels, never upscaled	The source is larger than 720p

The short side follows the picture as it is displayed: a portrait 1080 × 1920 phone video gets a 720 × 1280 and a 1080 × 1920 rendition. Each ready MP4 rendition carries width, height and duration_ms.

A rendition that is not made is skipped, with error saying why:

`error`	Why	The video plays from
`source_smaller`	`mp4_1080p` only: the source is not larger than 720p	`mp4_720p`
`duration_exceeds_limit`	The video is longer than 10 minutes	The original
`size_exceeds_limit`	The file is larger than 2 GiB	The original
`duration_unknown`	The video’s length could not be read	The original

"renditions": {
  "poster": { "status": "ready", "mime_type": "image/jpeg", "size": 81233, "width": 1080, "height": 1920, "duration_ms": null },
  "mp4_720p": { "status": "ready", "mime_type": "video/mp4", "size": 4810233, "width": 720, "height": 1280, "duration_ms": 14520 },
  "mp4_1080p": { "status": "skipped", "mime_type": null, "size": null, "width": null, "height": null, "duration_ms": null, "error": "source_smaller" }
}

Record or pick H.264 MP4 when you can: the original then plays everywhere even before its renditions exist.

The preview call

GET P/files/:file_id/preview answers one signed URL to show, its kind, and every rendition with a URL when it is ready:

`kind`	`url` points at
`image`	The `preview` rendition when it is ready; the original meanwhile, for the formats browsers display
`video`	`mp4_720p` when it is ready, then `mp4_1080p`, then the original
`audio`	The original
`pdf`	The original, for the browser’s own viewer; the `thumbnail` and `preview` renditions are in `renditions`
`text`	The original as UTF-8 text, cut after 1 MiB
`none`	Nothing can be shown: Office documents, archives, other types, or a quarantined file. Offer a download

A player that adapts to the screen can choose itself: the web client’s playbackSources(preview) lists the ready mp4_1080p, then mp4_720p, then the original, as the <source> list of a <video>.

Rendition URLs

Every rendition is minted like the original: GET P/files/:file_id/download with ?rendition=mp4_720p, or a whole page with POST P/files/urls and rendition. Viewing a rendition needs view, not download. A rendition that is not ready answers 404 rendition_not_available (in a batch, that entry’s error): fall back to the original or to the preview call. Under the application’s scan policy, every URL of a file not scanned yet answers 409 scan_pending (Malware scanning).

Making them again

POST P/files/:file_id/renditions makes renditions again, all or the names you pass (for example ["mp4_720p", "mp4_1080p"]), and answers 202 with a job; GET P/files/:file_id/renditions lists them with their status and error. Use it after switching renditions back on.