{"record":{"id":"0d6f4b53c8f04914","repo":"remotion-dev/remotion","slug":"unsupported-hvcc-version-configurationversion","errorCode":null,"errorMessage":"Unsupported HVCC version ${configurationVersion}","messagePattern":"Unsupported HVCC version (.+?)","errorType":"exception","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"packages/media-parser/src/make-hvc1-codec-strings.ts","lineNumber":6,"sourceCode":"import type {BufferIterator} from './iterator/buffer-iterator';\n\nexport const getHvc1CodecString = (data: BufferIterator) => {\n\tconst configurationVersion = data.getUint8();\n\tif (configurationVersion !== 1) {\n\t\tthrow new Error(`Unsupported HVCC version ${configurationVersion}`);\n\t}\n\n\tconst generalProfileSpaceTierFlagAndIdc = data.getUint8();\n\tlet generalProfileCompatibility = data.getUint32();\n\t//  unsigned int(2) general_profile_space;\n\t// \tunsigned int(1) general_tier_flag;\n\t//\tunsigned int(5) general_profile_idc;\n\n\tconst generalProfileSpace = generalProfileSpaceTierFlagAndIdc >> 6;\n\tconst generalTierFlag = (generalProfileSpaceTierFlagAndIdc & 0x20) >> 5;\n\tconst generalProfileIdc = generalProfileSpaceTierFlagAndIdc & 0x1f;\n\n\t// general_constraint_indicator_flags(48)\n\tconst generalConstraintIndicator = data.getSlice(6);\n\tconst generalLevelIdc = data.getUint8();\n\n\tlet profileId = 0;\n\tfor (let i = 0; i < 32; i++) {","sourceCodeStart":1,"sourceCodeEnd":24,"githubUrl":"https://github.com/remotion-dev/remotion/blob/78fe4bb3fdb5a2cd68724393d63cb223db333fa7/packages/media-parser/src/make-hvc1-codec-strings.ts#L1-L24","documentation":"getHvc1CodecString reads the first byte of an HEVC (H.265) decoder configuration record (HEVCDecoderConfigurationRecord) and requires configurationVersion === 1. Any other version is rejected because the layout of the record is version-defined and the library only knows how to parse version 1. The result is a codec string like hvc1.1.6.L120.B01 for the track.","triggerScenarios":"Parsing an MP4 track whose hvcC (HEVC decoder config) box has a configurationVersion other than 1 — produced by experimental HEVC muxers, future spec revisions, or a corrupt/truncated hvcC box whose first byte was misread.","commonSituations":"Files produced by bleeding-edge or non-standard HEVC encoders, AV1-vs-HEVC mislabeling, corrupted downloads, or test fixtures with hand-crafted boxes. Rare in mainstream content.","solutions":["Re-mux/re-encode the HEVC stream with a mainstream tool (FFmpeg: `ffmpeg -i in -c:v libx265 -tag:v hvc1 out.mp4`).","If you do not need HEVC, transcode to H.264 (`-c:v libx264`) which the parser fully supports.","Verify the file with `ffprobe` — if ffprobe also errors on the hvcC, the file is the problem.","Report the file at https://remotion.dev/report if it is a valid v1 record being misread."],"exampleFix":"// before: source has non-v1 hvcC\nawait parseMedia({src: 'weird-hevc.mp4', fields: {tracks: true}});\n\n// after: transcode to a supported config\n// ffmpeg -i weird-hevc.mp4 -c:v libx265 -tag:v hvc1 -c:a aac fixed.mp4\nawait parseMedia({src: 'fixed.mp4', fields: {tracks: true}});","handlingStrategy":"try-catch","validationCode":"// Confirm HEVC config is version 1 via ffprobe\nimport {execFileSync} from 'node:child_process';\nfunction isHevcV1(path: string): boolean {\n  try {\n    execFileSync('ffprobe', ['-v','error', path], {stdio: 'pipe'});\n    return true;\n  } catch { return false; }\n}","typeGuard":null,"tryCatchPattern":"try {\n  await parseMedia({src, fields: {tracks: true}});\n} catch (e) {\n  if (e instanceof Error && e.message.startsWith('Unsupported HVCC version')) {\n    // re-encode HEVC with a mainstream encoder\n    throw new Error('HEVC config unsupported; re-encode with FFmpeg libx265');\n  }\n  throw e;\n}","preventionTips":["Encode HEVC with mainstream FFmpeg libx265 and -tag:v hvc1.","Prefer H.264/AAC for maximum parser compatibility.","Validate unusual HEVC files with ffprobe before parsing.","Report genuinely-valid v1 records misread by the parser."],"tags":["hevc","h265","mp4","codec","media-parser"],"backgroundTag":null,"analyzedSha":"78fe4bb3fdb5a2cd68724393d63cb223db333fa7","analyzedAt":"2026-08-12T17:18:50.444Z","schemaVersion":2},"datasetVersion":"2026-08-12T23:17:12.415Z"}