remotion-dev/remotion · error · Error

Unsupported HVCC version ${configurationVersion}

Error message

Unsupported HVCC version ${configurationVersion}

What it means

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.

Source

Thrown at packages/media-parser/src/make-hvc1-codec-strings.ts:6

import type {BufferIterator} from './iterator/buffer-iterator';

export const getHvc1CodecString = (data: BufferIterator) => {
	const configurationVersion = data.getUint8();
	if (configurationVersion !== 1) {
		throw new Error(`Unsupported HVCC version ${configurationVersion}`);
	}

	const generalProfileSpaceTierFlagAndIdc = data.getUint8();
	let generalProfileCompatibility = data.getUint32();
	//  unsigned int(2) general_profile_space;
	// 	unsigned int(1) general_tier_flag;
	//	unsigned int(5) general_profile_idc;

	const generalProfileSpace = generalProfileSpaceTierFlagAndIdc >> 6;
	const generalTierFlag = (generalProfileSpaceTierFlagAndIdc & 0x20) >> 5;
	const generalProfileIdc = generalProfileSpaceTierFlagAndIdc & 0x1f;

	// general_constraint_indicator_flags(48)
	const generalConstraintIndicator = data.getSlice(6);
	const generalLevelIdc = data.getUint8();

	let profileId = 0;
	for (let i = 0; i < 32; i++) {

View on GitHub (pinned to 78fe4bb3fd)

Solutions

1. Re-mux/re-encode the HEVC stream with a mainstream tool (FFmpeg: `ffmpeg -i in -c:v libx265 -tag:v hvc1 out.mp4`).
2. If you do not need HEVC, transcode to H.264 (`-c:v libx264`) which the parser fully supports.
3. Verify the file with `ffprobe` — if ffprobe also errors on the hvcC, the file is the problem.
4. Report the file at https://remotion.dev/report if it is a valid v1 record being misread.

Example fix

// before: source has non-v1 hvcC
await parseMedia({src: 'weird-hevc.mp4', fields: {tracks: true}});

// after: transcode to a supported config
// ffmpeg -i weird-hevc.mp4 -c:v libx265 -tag:v hvc1 -c:a aac fixed.mp4
await parseMedia({src: 'fixed.mp4', fields: {tracks: true}});

// Confirm HEVC config is version 1 via ffprobe
import {execFileSync} from 'node:child_process';
function isHevcV1(path: string): boolean {
  try {
    execFileSync('ffprobe', ['-v','error', path], {stdio: 'pipe'});
    return true;
  } catch { return false; }
}

try {
  await parseMedia({src, fields: {tracks: true}});
} catch (e) {
  if (e instanceof Error && e.message.startsWith('Unsupported HVCC version')) {
    // re-encode HEVC with a mainstream encoder
    throw new Error('HEVC config unsupported; re-encode with FFmpeg libx265');
  }
  throw e;
}

When it happens

Trigger: 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.

Common situations: 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.

Related errors

• Could not find number of channels
• Could not find sample rate
• No video sample
• Could not find video codec
• Unsupported AVCC version ${confVersion}

AI-assisted analysis of remotion-dev/remotion@78fe4bb3fd (2026-08-12). Data as JSON: /api/errors/0d6f4b53c8f04914. Report an issue: GitHub.