#HDR

Transcodely supports High Dynamic Range (HDR) video processing at the variant level. Each video variant can independently control how HDR content is handled — you can preserve HDR on high-resolution variants while tone mapping to SDR for lower resolutions in the same ABR ladder.

HDR is configured via the hdr object on a VideoVariant.

HDR pricing depends on the mode and format. passthrough and force add no HDR surcharge (1.0x); tonemap adds a 1.5x feature multiplier; and any Dolby Vision format (dolby_vision_5, dolby_vision_8) adds a 2.0x multiplier in any mode. The Dolby Vision multiplier supersedes the tone-mapping one rather than stacking with it. See Pricing for details.

#The HDRConfig object

{
  "hdr": {
    "format": "hdr10",
    "mode": "passthrough"
  }
}

#HDR formats

#Processing modes

Each HDR configuration requires a mode that determines how Transcodely handles HDR content.

#Tone mapping

When converting HDR to SDR (mode: "tonemap"), choose a tone mapping algorithm:

target_peak_nits sets the target brightness for tone mapping. When omitted, the applied default is format-dependent (1000 nits for HDR10, 4000 for Dolby Vision). Increase or lower it to match the displays you target.

#Static metadata

With passthrough or force mode you can inject static mastering display metadata (most commonly for HDR10). This metadata is forbidden in tonemap mode, which discards HDR.

master_display — SMPTE ST 2086 mastering display color volume. Format:

G(x,y)B(x,y)R(x,y)WP(x,y)L(max,min)

Where x,y are chromaticity coordinates (0—50000 range, representing 0.0—1.0 scaled by 50000) and L(max,min) is peak and minimum luminance in units of 0.0001 cd/m² — the HEVC mastering-display-colour-volume SEI / x265 --master-display convention, not raw cd/m². So a 1000 cd/m² (1000-nit) peak is encoded as L(10000000,...), since 10000000 × 0.0001 = 1000.

Example for a DCI-P3 D65 mastering display with 1000 nit peak:

G(13250,34500)B(7500,3000)R(34000,16000)WP(15635,16450)L(10000000,50)

content_light_level — Maximum content light level. Format:

MaxCLL,MaxFALL

Where MaxCLL is maximum content light level and MaxFALL is maximum frame-average light level, both in cd/m².

Example: "1000,400" means peak brightness of 1000 nits, average of 400 nits.

#Dolby Vision

Dolby Vision uses dynamic metadata stored in an RPU (Reference Processing Unit) file to optimize the picture on a scene-by-scene or frame-by-frame basis.

Profile 5 (dolby_vision_5): Standalone profile with no backwards compatibility. Only plays on Dolby Vision capable devices.

Profile 8 (dolby_vision_8): HDR10-compatible profile. Includes a base layer that falls back to HDR10 on non-Dolby devices. Recommended for maximum compatibility.

To use Dolby Vision, provide the RPU file via rpu_url:

{
  "hdr": {
    "format": "dolby_vision_8",
    "mode": "force",
    "rpu_url": "gs://my-bucket/rpu/movie_dv_rpu.bin"
  }
}

#Codec compatibility

Not all codecs support HDR encoding:

If you request an HDR format on a codec that doesn’t support it — such as any hdr config on an H.264 or VP9 variant, or a non-HLG format on AV1 — the API returns a validation error.

#Examples

#HDR10 passthrough

Preserve the original HDR10 metadata on a 4K H.265 variant.

{
  "codec": "h265",
  "resolution": "2160p",
  "quality": "premium",
  "h265": {
    "profile": "main10"
  },
  "hdr": {
    "format": "hdr10",
    "mode": "passthrough"
  }
}

#HDR to SDR tone mapping

Convert HDR content to SDR using the BT.2390 algorithm for a 1080p variant.

{
  "codec": "h265",
  "resolution": "1080p",
  "quality": "standard",
  "hdr": {
    "mode": "tonemap",
    "tone_mapping": "bt2390",
    "target_peak_nits": 100
  }
}

#Force HDR10 with metadata

Inject HDR10 static metadata onto a 10-bit encode, specifying both mastering display and content light level.

{
  "codec": "h265",
  "resolution": "2160p",
  "quality": "premium",
  "h265": {
    "profile": "main10"
  },
  "hdr": {
    "format": "hdr10",
    "mode": "force",
    "master_display": "G(13250,34500)B(7500,3000)R(34000,16000)WP(15635,16450)L(10000000,50)",
    "content_light_level": "1000,400"
  }
}

#Dolby Vision Profile 8 with RPU

Apply Dolby Vision Profile 8 dynamic metadata using an external RPU file. Falls back to HDR10 on non-Dolby devices.

{
  "codec": "h265",
  "resolution": "2160p",
  "quality": "premium",
  "h265": {
    "profile": "main10"
  },
  "hdr": {
    "format": "dolby_vision_8",
    "mode": "force",
    "rpu_url": "gs://my-bucket/rpu/movie_dv_rpu.bin"
  }
}

#ABR ladder with mixed HDR/SDR

Create an adaptive bitrate ladder where the 4K variant preserves HDR and lower resolutions are tone mapped to SDR.

[
  {
    "codec": "h265",
    "resolution": "2160p",
    "quality": "premium",
    "h265": { "profile": "main10" },
    "hdr": { "format": "hdr10", "mode": "passthrough" }
  },
  {
    "codec": "h265",
    "resolution": "1080p",
    "quality": "standard",
    "hdr": { "mode": "tonemap", "tone_mapping": "bt2390" }
  },
  {
    "codec": "h265",
    "resolution": "720p",
    "quality": "economy",
    "hdr": { "mode": "tonemap", "tone_mapping": "bt2390" }
  }
]