{"record":{"id":"8abe445152c73ab3","repo":"commaai/openpilot","slug":"ffmpeg-failed-result-stderr-decode","errorCode":null,"errorMessage":"ffmpeg failed: {result.stderr.decode()}","messagePattern":"ffmpeg failed: (.+?)","errorType":"exception","errorClass":"RuntimeError","httpStatus":null,"severity":"error","filePath":"openpilot/tools/clip/run.py","lineNumber":160,"sourceCode":"  current_seg: int = -1\n  get_frame: Callable[[int], np.ndarray] | None = None\n\n  for global_idx in range(start_frame, end_frame):\n    seg_idx, local_idx = global_idx // frames_per_seg, global_idx % frames_per_seg\n\n    if seg_idx != current_seg:\n      current_seg = seg_idx\n      path = camera_paths[seg_idx] if seg_idx < len(camera_paths) else None\n      if not path:\n        raise RuntimeError(f\"No camera file for segment {seg_idx}\")\n\n      if use_qcam:\n        w, h = frame_size or get_frame_dimensions(path)\n        with FileReader(path) as f:\n          result = subprocess.run([\"ffmpeg\", \"-v\", \"quiet\", \"-i\", \"-\", \"-f\", \"rawvideo\", \"-pix_fmt\", \"nv12\", \"-\"],\n                                  input=f.read(), capture_output=True)\n        if result.returncode != 0:\n          raise RuntimeError(f\"ffmpeg failed: {result.stderr.decode()}\")\n        seg_frames = np.frombuffer(result.stdout, dtype=np.uint8).reshape(-1, w * h * 3 // 2)\n        get_frame = seg_frames.__getitem__\n      else:\n        get_frame = FrameReader(path, pix_fmt=\"nv12\").get\n\n    assert get_frame is not None\n    yield global_idx, get_frame(local_idx)\n\n\nclass FrameQueue:\n  def __init__(self, camera_paths, start_time, end_time, fps=20, prefetch_count=60, use_qcam=False):\n    # Probe first valid camera file for dimensions\n    first_path = next((p for p in camera_paths if p), None)\n    if not first_path:\n      raise RuntimeError(\"No valid camera paths\")\n    self.frame_w, self.frame_h = get_frame_dimensions(first_path)\n\n    self._queue, self._stop, self._error = queue.Queue(maxsize=prefetch_count), threading.Event(), None","sourceCodeStart":142,"sourceCodeEnd":178,"githubUrl":"https://github.com/commaai/openpilot/blob/516ec1e68203439a73f340f1d0b3b91eabc626ee/openpilot/tools/clip/run.py#L142-L178","documentation":"When decoding a qcamera segment with the ffmpeg subprocess (stdin raw file, stdout rawvideo nv12), a non-zero exit code triggers this RuntimeError carrying ffmpeg's stderr. The qcamera file is an HEVC stream inside a ts container; failures usually mean ffmpeg cannot parse the container, was built without the needed demuxer/decoder, or got truncated input via the pipe.","triggerScenarios":"use_qcam=True path in iter_segment_frames(): subprocess ffmpeg exits non-zero because the .ts is corrupt/truncated; system ffmpeg lacks hevc decoding (--disable-decoders builds, distro 'ffmpeg-free' packages); piping the whole file via stdin when the container needs seekable input.","commonSituations":"Partially downloaded qcamera.ts; Fedora-style ffmpeg builds without libde265/hevc; old ffmpeg versions with poor hevc-in-mpegts demuxing; empty stderr because '-v quiet' suppressed diagnostics so the message looks empty.","solutions":["Run the same command manually to see the real error: ffmpeg -i <qcamera.ts> -f rawvideo -pix_fmt nv12 out.yuv","Install a full ffmpeg build with HEVC support (e.g. ffmpeg from ffmpeg.org, not a codec-stripped distro package)","Re-download the qcamera file if it is truncated/corrupt (verify size against the server listing)","If stderr is empty due to -v quiet, temporarily raise verbosity to '-v error' to capture the cause"],"exampleFix":"# before\nresult = subprocess.run([\"ffmpeg\", \"-v\", \"quiet\", ...])\n\n# after (surface the real cause)\nresult = subprocess.run([\"ffmpeg\", \"-v\", \"error\", ...])\nif result.returncode != 0:\n    raise RuntimeError(f\"ffmpeg failed: {result.stderr.decode(errors='replace') or 'no stderr (check ffmpeg build has hevc)'}\")","handlingStrategy":"try-catch","validationCode":"import shutil, subprocess\nassert shutil.which('ffmpeg'), 'ffmpeg not on PATH'\nprobe = subprocess.run(['ffmpeg', '-decoders'], capture_output=True, text=True)\nassert 'hevc' in probe.stdout.lower(), 'system ffmpeg cannot decode HEVC qcamera streams'","typeGuard":null,"tryCatchPattern":"try:\n    result = subprocess.run(cmd, input=f.read(), capture_output=True)\nexcept RuntimeError as e:\n    msg = str(e)\n    if 'ffmpeg failed' in msg:\n        if 'decode' in msg or not msg.strip('ffmpeg failed: '):\n            raise SystemExit('install a full ffmpeg build with HEVC support')\n        raise SystemExit(f'qcamera decode failed: {msg}')\n    raise","preventionTips":["Use '-v error' instead of '-v quiet' so failures carry actionable stderr","Pin a known-good, full-featured ffmpeg (e.g. via conda/static builds) in environments that run the clip tool"],"tags":["ffmpeg","clip-tool","video-decoding","subprocess","openpilot"],"backgroundTag":null,"analyzedSha":"516ec1e68203439a73f340f1d0b3b91eabc626ee","analyzedAt":"2026-08-15T00:17:37.461Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}