{"record":{"id":"1dc57b2523a0a2ee","repo":"heygen-com/hyperframes","slug":"engine-config-hdr-must-be-false-or-an-hlg-pq-trans","errorCode":null,"errorMessage":"Engine config hdr must be false or an hlg/pq transfer object","messagePattern":"Engine config hdr must be false or an hlg/pq transfer object","errorType":"validation","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"packages/engine/src/config.ts","lineNumber":481,"sourceCode":"    if (typeof config[field] !== \"boolean\")\n      throw new Error(`Engine config ${field} must be a boolean`);\n  }\n  for (const field of POSITIVE_NUMBER_ENGINE_CONFIG_FIELDS) {\n    assertEngineConfigNumber(config, field, 1, field === \"frameDataUriCacheLimit\");\n  }\n  assertEngineConfigNumber(config, \"streamingEncodeMaxDurationSeconds\", 0);\n  assertEngineConfigNumber(config, \"audioGain\", 0);\n}\n\nfunction validateEngineConfigHdr(config: Record<string, unknown>): void {\n  const { hdr } = config;\n  if (\n    hdr !== false &&\n    (!isPlainObject(hdr) ||\n      Object.keys(hdr).length !== 1 ||\n      (hdr.transfer !== \"hlg\" && hdr.transfer !== \"pq\"))\n  ) {\n    throw new Error(\"Engine config hdr must be false or an hlg/pq transfer object\");\n  }\n}\n\nfunction validateOptionalEngineConfigFields(config: Record<string, unknown>): void {\n  for (const field of [\"chromePath\", \"runtimeManifestPath\", \"extractCacheDir\"] as const) {\n    if (\n      config[field] !== undefined &&\n      (typeof config[field] !== \"string\" || config[field].length === 0)\n    ) {\n      throw new Error(`Engine config ${field} must be a non-empty string`);\n    }\n  }\n  if (config.expectedChromiumMajor !== undefined) {\n    assertEngineConfigNumber(config, \"expectedChromiumMajor\", 1, true);\n  }\n  for (const field of [\n    \"pageSideCompositingAutoDisabled\",\n    \"forceScreenshotExplicitlyOptedOut\",","sourceCodeStart":463,"sourceCodeEnd":499,"githubUrl":"https://github.com/heygen-com/hyperframes/blob/c2996c8626135db5253519359d8a063d3bafad8d/packages/engine/src/config.ts#L463-L499","documentation":"validateEngineConfigHdr() requires `hdr` to be either the literal `false` or a single-key object `{ transfer: \"hlg\" | \"pq\" }` — the two HDR transfer functions the encode pipeline supports. Any other shape (true, a string, an object with extra keys, an object whose transfer is neither hlg nor pq) is rejected.","triggerScenarios":"validateEngineConfigSnapshot() receives hdr: true (use {transfer:\"hlg\"} instead), hdr: \"hlg\" (must be an object), hdr: {transfer:\"hlg\", other:1} (must be exactly one key), or hdr: {transfer:\"dolby\"} (unsupported transfer).","commonSituations":"Treating hdr as a boolean toggle; an older schema where hdr was a different shape; passing extra metadata keys alongside transfer; authoring a transfer function the pipeline does not encode.","solutions":["For SDR, set hdr: false (the default).","For HLG HDR, set hdr: { transfer: \"hlg\" }; for PQ, set hdr: { transfer: \"pq\" } — and no other keys.","If you only need to detect HDR from source, that is `hdrAutoDetect` (a boolean), not `hdr`."],"exampleFix":"// before\nconst snap = { ...DEFAULT_CONFIG, hdr: true };\n\n// after\nconst snap = { ...DEFAULT_CONFIG, hdr: { transfer: \"pq\" } };","handlingStrategy":"type-guard","validationCode":"function assertHdr(value: unknown): asserts value is false | { transfer: \"hlg\" | \"pq\" } {\n  if (value === false) return;\n  if (\n    typeof value !== \"object\" || value === null ||\n    Object.keys(value).length !== 1 ||\n    ((value as any).transfer !== \"hlg\" && (value as any).transfer !== \"pq\")\n  ) {\n    throw new Error('hdr must be false or { transfer: \"hlg\" | \"pq\" }');\n  }\n}","typeGuard":"function isValidHdr(value: unknown): value is false | { transfer: \"hlg\" | \"pq\" } {\n  if (value === false) return true;\n  if (typeof value !== \"object\" || value === null) return false;\n  const keys = Object.keys(value);\n  return keys.length === 1 && (value.transfer === \"hlg\" || value.transfer === \"pq\");\n}","tryCatchPattern":"try { validateEngineConfigSnapshot(snapshot); }\ncatch (e) {\n  if (/hdr must be/.test(String(e))) {\n    snapshot.hdr = false; // SDR fallback\n    validateEngineConfigSnapshot(snapshot);\n  } else throw e;\n}","preventionTips":["Use hdr: false for SDR; hdr: { transfer: \"hlg\" } or { transfer: \"pq\" } for HDR.","Use hdrAutoDetect (boolean) for source-based detection — not hdr.","Do not attach extra keys to the hdr object."],"tags":["engine-config","validation","hdr","transfer-function"],"backgroundTag":null,"analyzedSha":"c2996c8626135db5253519359d8a063d3bafad8d","analyzedAt":"2026-08-12T22:18:56.877Z","schemaVersion":2},"datasetVersion":"2026-08-13T04:17:16.726Z"}