{"record":{"id":"60f23cdefd37fe99","repo":"heygen-com/hyperframes","slug":"engine-config-vp9cpuused-must-be-an-integer-in-8","errorCode":null,"errorMessage":"Engine config vp9CpuUsed must be an integer in [-8, 8]","messagePattern":"Engine config vp9CpuUsed must be an integer in \\[-8, 8\\]","errorType":"validation","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"packages/engine/src/config.ts","lineNumber":457,"sourceCode":"      !Number.isInteger(config.concurrency) ||\n      config.concurrency < 1)\n  ) {\n    throw new Error(\"Engine config concurrency must be a positive integer or auto\");\n  }\n  assertPositiveEngineConfigNumber(config, \"coresPerWorker\");\n  for (const field of [\"minParallelFrames\", \"largeRenderThreshold\"] as const) {\n    assertEngineConfigNumber(config, field, 0, true);\n  }\n}\n\nfunction validateEngineConfigVp9(config: Record<string, unknown>): void {\n  if (\n    typeof config.vp9CpuUsed !== \"number\" ||\n    !Number.isInteger(config.vp9CpuUsed) ||\n    config.vp9CpuUsed < -8 ||\n    config.vp9CpuUsed > 8\n  ) {\n    throw new Error(\"Engine config vp9CpuUsed must be an integer in [-8, 8]\");\n  }\n}\n\nfunction validateEngineConfigRuntime(config: Record<string, unknown>): void {\n  for (const field of BOOLEAN_ENGINE_CONFIG_FIELDS) {\n    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 (","sourceCodeStart":439,"sourceCodeEnd":475,"githubUrl":"https://github.com/heygen-com/hyperframes/blob/c2996c8626135db5253519359d8a063d3bafad8d/packages/engine/src/config.ts#L439-L475","documentation":"validateEngineConfigVp9() requires vp9CpuUsed to be an integer in the closed range [-8, 8] — the documented libvpx `-cpu-used` quality/speed bracket. Non-integers, values outside that range, or non-numbers are rejected.","triggerScenarios":"validateEngineConfigSnapshot() receives vp9CpuUsed outside [-8,8] (e.g. 9 or -10), a float (4.5), or a non-number. DEFAULT_VP9_CPU_USED is the safe default; resolveConfig() also normalizes via normalizeVp9CpuUsed, so this usually only fires for raw snapshots.","commonSituations":"Confusing vp9CpuUsed with jpegQuality scale; passing a CRF or bitrate value into the wrong field; an older config that used a different range; typo negative bound.","solutions":["Set vp9CpuUsed to an integer in [-8, 8] (higher = faster/lower quality; default is sane for most renders).","If unsure, omit it and let resolveConfig() apply DEFAULT_VP9_CPU_USED.","Use normalizeVp9CpuUsed() (exported from the engine's vp9Options module) to clamp an external value before snapshotting."],"exampleFix":"// before\nconst snap = { ...DEFAULT_CONFIG, vp9CpuUsed: 16 };\n\n// after\nconst snap = { ...DEFAULT_CONFIG, vp9CpuUsed: 4 };","handlingStrategy":"validation","validationCode":"function normalizeVp9CpuUsed(value: unknown): number {\n  const n = typeof value === \"number\" ? value : Number(value);\n  if (!Number.isInteger(n) || n < -8 || n > 8) throw new Error(\"vp9CpuUsed must be an integer in [-8,8]\");\n  return n;\n}\ncfg.vp9CpuUsed = normalizeVp9CpuUsed(cfg.vp9CpuUsed);","typeGuard":"function isValidVp9CpuUsed(value: unknown): boolean {\n  return typeof value === \"number\" && Number.isInteger(value) && value >= -8 && value <= 8;\n}","tryCatchPattern":"try { validateEngineConfigSnapshot(snapshot); }\ncatch (e) {\n  if (/vp9CpuUsed/.test(String(e))) {\n    snapshot.vp9CpuUsed = DEFAULT_CONFIG.vp9CpuUsed;\n    validateEngineConfigSnapshot(snapshot);\n  } else throw e;\n}","preventionTips":["Omit vp9CpuUsed and let resolveConfig() apply DEFAULT_VP9_CPU_USED.","Use normalizeVp9CpuUsed() to clamp external input before snapshotting.","Do not confuse vp9CpuUsed with CRF or bitrate."],"tags":["engine-config","validation","vp9","codec","range"],"backgroundTag":null,"analyzedSha":"c2996c8626135db5253519359d8a063d3bafad8d","analyzedAt":"2026-08-12T22:18:56.877Z","schemaVersion":2},"datasetVersion":"2026-08-12T23:17:12.415Z"}