{"record":{"id":"b249fe4f7fcd3cfb","repo":"commaai/openpilot","slug":"first-byte-must-be-0x00","errorCode":null,"errorMessage":"first byte must be 0x00","messagePattern":"first byte must be 0x00","errorType":"exception","errorClass":"VideoFileInvalid","httpStatus":null,"severity":"error","filePath":"openpilot/tools/lib/vidindex.py","lineNumber":269,"sourceCode":"  #     1      | P (P slice)\n  #     2      | I (I slice)\n  # unsigned integer 0-th order Exp-Golomb-coded syntax element with the left bit first\n  slice_type, _ = get_ue(dat, rbsp_start, skip_bits)\n  if DEBUG:\n    print(\"  slice_type:\", slice_type, f\"(first slice: {is_first_slice})\")\n  if slice_type > 2:\n    raise VideoFileInvalid(\"slice_type must be 0, 1, or 2\")\n  return slice_type, is_first_slice\n\ndef hevc_index(hevc_file_name: str, allow_corrupt: bool=False) -> tuple[list, int, bytes]:\n  with FileReader(hevc_file_name) as f:\n    dat = f.read()\n\n  if len(dat) < NAL_UNIT_START_CODE_SIZE + 1:\n    raise VideoFileInvalid(\"data is too short\")\n\n  if dat[0] != 0x00:\n    raise VideoFileInvalid(\"first byte must be 0x00\")\n\n  prefix_dat = b\"\"\n  frame_types = []\n\n  i = 1 # skip past first byte 0x00\n  try:\n    while i < len(dat):\n      require_nal_unit_start(dat, i)\n      nal_unit_len = get_hevc_nal_unit_length(dat, i)\n      nal_unit_type = get_hevc_nal_unit_type(dat, i)\n      if nal_unit_type in HEVC_PARAMETER_SET_NAL_UNITS:\n        prefix_dat += dat[i:i+nal_unit_len]\n      elif nal_unit_type in HEVC_CODED_SLICE_SEGMENT_NAL_UNITS:\n        slice_type, is_first_slice = get_hevc_slice_type(dat, i, nal_unit_type)\n        if is_first_slice:\n          frame_types.append((slice_type, i))\n      i += nal_unit_len\n  except Exception as e:","sourceCodeStart":251,"sourceCodeEnd":287,"githubUrl":"https://github.com/commaai/openpilot/blob/516ec1e68203439a73f340f1d0b3b91eabc626ee/openpilot/tools/lib/vidindex.py#L251-L287","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Verify the path points at the raw HEVC elementary stream from the route (e.g. <route>/<segment>/camera.hevc), not an MP4 or thumbnail.","If you have an MP4, extract the raw stream: ffmpeg -i in.mp4 -c:v copy -bsf:v hevc_mp4toannexb out.hevc.","Hexdump the first bytes (xxd file | head -1) — valid files start with 00 00 00 01.","Add a file-signature check in your batch script to skip non-Annex-B inputs early."],"exampleFix":"# before\nidx = hevc_index(clip_path)  # clip_path is actually an .mp4\n\n# after\nimport subprocess\nsubprocess.run(['ffmpeg', '-i', clip_path, '-c:v', 'copy', '-bsf:v', 'hevc_mp4toannexb', out_hevc], check=True)\nidx = hevc_index(out_hevc)","handlingStrategy":"validation","validationCode":"with open(path, 'rb') as f:\n    first = f.read(1)\nif first != b'\\x00':\n    raise SystemExit(f'{path} is not a raw Annex-B HEVC stream')\nframes, prefix, prefix_dat = hevc_index(path)","typeGuard":null,"tryCatchPattern":"try:\n    frames, prefix, prefix_dat = hevc_index(path)\nexcept VideoFileInvalid as e:\n    if 'first byte' in str(e):\n        raise SystemExit(f'{path} is a container or wrong format; extract the raw .hevc first')\n    raise","preventionTips":["Standardize on the route's raw camera.hevc path in scripts.","Add a magic-byte check (00 00 00 01 prefix) at the top of your video pipeline.","Never rename container files to .hevc; extension does not change format."],"tags":["video","hevc","file-format","validation","openpilot"],"backgroundTag":null,"analyzedSha":"516ec1e68203439a73f340f1d0b3b91eabc626ee","analyzedAt":"2026-08-15T00:17:37.461Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}