Skip to content

Use encoding tiers

HeapStream lets you choose an encoding tier per video. The tier determines which quality levels are encoded for the asset, and with them its cost.

Choosing a tier

  • Set the default tier for the project in the Project Settings page.
  • Or pick a tier for one video in the upload page's settings panel.
  • Set the project default with the update project ⧉ endpoint's encoding_tier field.
  • Or set metadata.encoding_tier to full or baseline when uploading ⧉ or fetching ⧉ a video. When omitted (null), the tier resolves through the video's Profile, then the project's default profile.

The project default is full.

Full encoding

The default tier is full. It encodes the complete ladder of quality levels for the source resolution, so adaptive playback has a step for every screen size and connection speed.

Baseline encoding

baseline costs less by encoding fewer quality levels. It always includes the highest and lowest qualities, with fewer steps in between.

Full vs baseline

A 4K upload produces these resolutions per tier:

Quality Full Baseline
4K ✅ ✅
2K ✅ -
1080p ✅ ✅
720p ✅ -
480p ✅ ✅
360p ✅ -
240p ✅ ✅

Sources between quality levels

Quality levels are named by their line count (1080p, 720p, ...) and a video is never upscaled, so a source whose height falls between two levels used to top out at the level below it: a 1920x818 widescreen film (the 2.39:1 "scope" ratio most cinema is shot in) was delivered at 1690x720, a fifth of its pixels gone. Two rules keep the source's own resolution at the top of the ladder:

  • A source within 10% below a level gets that level, encoded at its own lines. A 1920x1072 upload (a common crop) gets its 1080p rendition, at 1072 lines.
  • A source more than 10% past a level gets a top rendition at its own dimensions. The 1920x818 film gets an 818p rendition beside its 720p one, capped at the bitrate the level above would spend on that many pixels. It appears under that name in the player's quality menu, the API and the encoding progress panel.

Both apply to vertical videos on their short edge. Interior levels are unchanged, and nothing is ever upscaled: a source smaller than 240 lines is delivered at its own size rather than stretched to 240.

Watch encoding progress

While a freshly uploaded video is processing, the Video Preview panel on its Video Edit page shows live encoding progress in place of the player. It lists every quality being prepared (one progress bar per rendition, e.g. 1080p, 720p, 480p, plus an overall percentage) and fills in as the encode advances. The panel updates on its own, with no need to refresh.

Encoding runs in two passes: the essential lower qualities are produced first, then the higher ones. So as soon as those essentials are ready the player appears and you can start watching, while a slim strip beneath it keeps showing the higher qualities still being prepared. Each rendition turns green with a check as it finishes, and once the whole video is done the strip disappears.