commaai/openpilot · error · VideoFileInvalid

first byte must be 0x00

Error message

first byte must be 0x00

What it means

Raised at the start of hevc_index() when the first byte of the file is not 0x00, the mandatory first byte of the 00 00 00 01 Annex-B start code that raw HEVC route files must begin with. It distinguishes 'not our format at all' from parsing corruption deeper in the file: openpilot's indexer only accepts raw Annex-B streams beginning with a start code.

Source

Thrown at openpilot/tools/lib/vidindex.py:269

  #     1      | P (P slice)
  #     2      | I (I slice)
  # unsigned integer 0-th order Exp-Golomb-coded syntax element with the left bit first
  slice_type, _ = get_ue(dat, rbsp_start, skip_bits)
  if DEBUG:
    print("  slice_type:", slice_type, f"(first slice: {is_first_slice})")
  if slice_type > 2:
    raise VideoFileInvalid("slice_type must be 0, 1, or 2")
  return slice_type, is_first_slice

def hevc_index(hevc_file_name: str, allow_corrupt: bool=False) -> tuple[list, int, bytes]:
  with FileReader(hevc_file_name) as f:
    dat = f.read()

  if len(dat) < NAL_UNIT_START_CODE_SIZE + 1:
    raise VideoFileInvalid("data is too short")

  if dat[0] != 0x00:
    raise VideoFileInvalid("first byte must be 0x00")

  prefix_dat = b""
  frame_types = []

  i = 1 # skip past first byte 0x00
  try:
    while i < len(dat):
      require_nal_unit_start(dat, i)
      nal_unit_len = get_hevc_nal_unit_length(dat, i)
      nal_unit_type = get_hevc_nal_unit_type(dat, i)
      if nal_unit_type in HEVC_PARAMETER_SET_NAL_UNITS:
        prefix_dat += dat[i:i+nal_unit_len]
      elif nal_unit_type in HEVC_CODED_SLICE_SEGMENT_NAL_UNITS:
        slice_type, is_first_slice = get_hevc_slice_type(dat, i, nal_unit_type)
        if is_first_slice:
          frame_types.append((slice_type, i))
      i += nal_unit_len
  except Exception as e:

View on GitHub (pinned to 516ec1e682)

Solutions

1. Verify the path points at the raw HEVC elementary stream from the route (e.g. <route>/<segment>/camera.hevc), not an MP4 or thumbnail.
2. If you have an MP4, extract the raw stream: ffmpeg -i in.mp4 -c:v copy -bsf:v hevc_mp4toannexb out.hevc.
3. Hexdump the first bytes (xxd file | head -1) — valid files start with 00 00 00 01.
4. Add a file-signature check in your batch script to skip non-Annex-B inputs early.

Example fix

# before
idx = hevc_index(clip_path)  # clip_path is actually an .mp4

# after
import subprocess
subprocess.run(['ffmpeg', '-i', clip_path, '-c:v', 'copy', '-bsf:v', 'hevc_mp4toannexb', out_hevc], check=True)
idx = hevc_index(out_hevc)

with open(path, 'rb') as f:
    first = f.read(1)
if first != b'\x00':
    raise SystemExit(f'{path} is not a raw Annex-B HEVC stream')
frames, prefix, prefix_dat = hevc_index(path)

try:
    frames, prefix, prefix_dat = hevc_index(path)
except VideoFileInvalid as e:
    if 'first byte' in str(e):
        raise SystemExit(f'{path} is a container or wrong format; extract the raw .hevc first')
    raise

When it happens

Trigger: hevc_index() on a file whose byte 0 is not 0x00 — e.g. an MP4/MKV container (starts with ftyp box / 0x66), a JPEG/PNG thumbnail, an HEVC stream in length-prefixed (HVCC) format, or a text file passed by mistake.

Common situations: Pointing vidindex at a downloaded container file instead of the extracted raw stream, mixing up thumbnail.jpg and camera.hevc paths in a script, or processing third-party camera dumps that are not Annex-B demuxed.

Related errors

• data is too short
• data must begin with start code
• data to short to contain nal unit header
• slice_type must be 0, 1, or 2
• wrapped firmware is too short

AI-assisted analysis of commaai/openpilot@516ec1e682 (2026-08-15). Data as JSON: /api/errors/b249fe4f7fcd3cfb. Report an issue: GitHub.