openpilot v0.11.1 release

date: 2026-06-04T09:49:56
master commit: c0ab3550eca2e9daf197c46b7e4b24aa9637cf2e

tools/replay/.gitignore

@@ -0,0 +1,2 @@
+replay
+tests/test_replay

tools/replay/README.md

@@ -0,0 +1,142 @@
+# Replay
+
+`replay` allows you to simulate a driving session by replaying all messages logged during the use of openpilot. This provides a way to analyze and visualize system behavior as if it were live.
+
+## Setup
+
+Before starting a replay, you need to authenticate with your comma account using `auth.py`. This will allow you to access your routes from the server.
+
+```bash
+# Authenticate to access routes from your comma account:
+python3 tools/lib/auth.py
+```
+
+## Replay a Remote Route
+You can replay a route from your comma account by specifying the route name.
+
+```bash
+# Start a replay with a specific route:
+tools/replay/replay <route-name>
+
+# Example:
+tools/replay/replay '5beb9b58bd12b691/0000010a--a51155e496'
+
+# Replay the default demo route:
+tools/replay/replay --demo
+```
+
+## Replay a Local Route
+To replay a route stored locally on your machine, specify the route name and provide the path to the directory where the route files are stored.
+
+```bash
+# Replay a local route
+tools/replay/replay <route-name> --data_dir="/path_to/route"
+
+# Example:
+# If you have a local route stored at /path_to_routes with segments like:
+# 5beb9b58bd12b691/0000010a--a51155e496--0
+# 5beb9b58bd12b691/0000010a--a51155e496--1
+# You can replay it like this:
+tools/replay/replay "5beb9b58bd12b691/0000010a--a51155e496" --data_dir="/path_to_routes"
+```
+
+## Send Messages via ZMQ
+By default, replay sends messages via MSGQ. To switch to ZMQ, set the ZMQ environment variable.
+
+```bash
+# Start replay and send messages via ZMQ:
+ZMQ=1 tools/replay/replay <route-name>
+```
+
+## Usage
+For more information on available options and arguments, use the help command:
+
+``` bash
+$ tools/replay/replay -h
+Usage: tools/replay/replay [options] route
+Mock openpilot components by publishing logged messages.
+
+Options:
+  -h, --help             Displays this help.
+  -a, --allow <allow>    whitelist of services to send (comma-separated)
+  -b, --block <block>    blacklist of services to send (comma-separated)
+  -c, --cache <n>        cache <n> segments in memory. default is 5
+  -s, --start <seconds>  start from <seconds>
+  -x <speed>             playback <speed>. between 0.2 - 3
+  --demo                 use a demo route instead of providing your own
+  --auto                 Auto load the route from the best available source (no video):
+                         internal, openpilotci, comma_api, car_segments, testing_closet
+  --data_dir <data_dir>  local directory with routes
+  --prefix <prefix>      set OPENPILOT_PREFIX
+  --dcam                 load driver camera
+  --ecam                 load wide road camera
+  --no-loop              stop at the end of the route
+  --no-cache             turn off local cache
+  --qcam                 load qcamera
+  --no-hw-decoder        disable HW video decoding
+  --no-vipc              do not output video
+  --all                  do output all messages including uiDebug, userBookmark.
+                         this may causes issues when used along with UI
+
+Arguments:
+  route                  the drive to replay. find your drives at
+                         connect.comma.ai
+```
+
+## Visualize the Replay in the openpilot UI
+To visualize the replay within the openpilot UI, run the following commands:
+
+```bash
+tools/replay/replay <route-name>
+cd selfdrive/ui && ./ui.py
+```
+
+## Work with plotjuggler
+If you want to use replay with plotjuggler, you can stream messages by running:
+
+```bash
+tools/replay/replay <route-name>
+tools/plotjuggler/juggle.py --stream
+```
+
+## watch3
+
+watch all three cameras simultaneously from your comma three routes with watch3
+
+simply replay a route using the `--dcam` and `--ecam` flags:
+
+```bash
+# start a replay
+cd tools/replay && ./replay --demo --dcam --ecam
+
+# then start watch3
+cd selfdrive/ui && ./watch3.py
+```
+
+![](https://i.imgur.com/IeaOdAb.png)
+
+## Stream CAN messages to your device
+
+Replay CAN messages as they were recorded using a [panda jungle](https://comma.ai/shop/products/panda-jungle). The jungle has 6x OBD-C ports for connecting all your comma devices. Check out the [jungle repo](https://github.com/commaai/panda_jungle) for more info.
+
+In order to run your device as if it was in a car:
+* connect a panda jungle to your PC
+* connect a comma device or panda to the jungle via OBD-C
+* run `can_replay.py`
+
+``` bash
+batman:replay$ ./can_replay.py -h
+usage: can_replay.py [-h] [route_or_segment_name]
+
+Replay CAN messages from a route to all connected pandas and jungles
+in a loop.
+
+positional arguments:
+  route_or_segment_name
+                        The route or segment name to replay. If not
+                        specified, a default public route will be
+                        used. (default: None)
+
+optional arguments:
+  -h, --help            show this help message and exit
+```

tools/replay/SConscript

@@ -0,0 +1,21 @@
+Import('env', 'arch', 'common', 'messaging', 'visionipc', 'cereal')
+
+replay_env = env.Clone()
+replay_env['CCFLAGS'] += ['-Wno-deprecated-declarations']
+
+base_frameworks = ['VideoToolbox', 'CoreMedia', 'CoreFoundation', 'CoreVideo'] if arch == "Darwin" else []
+base_libs = [common, messaging, cereal, visionipc, 'm', 'pthread']
+
+replay_lib_src = ["replay.cc", "consoleui.cc", "camera.cc", "filereader.cc", "logreader.cc", "framereader.cc",
+                  "route.cc", "util.cc", "seg_mgr.cc", "timeline.cc", "py_downloader.cc"]
+if arch != "Darwin":
+  replay_lib_src.append("qcom_decoder.cc")
+replay_lib = replay_env.Library("replay", replay_lib_src, LIBS=base_libs, FRAMEWORKS=base_frameworks)
+Export('replay_lib')
+replay_libs = [replay_lib, 'avformat', 'avcodec', 'swresample', 'avutil', 'x264', 'z', 'bz2', 'zstd', 'yuv', 'ncurses'] + base_libs
+if arch != "Darwin":
+  replay_libs += ['va', 'va-drm', 'drm']
+replay_env.Program("replay", ["main.cc"], LIBS=replay_libs, FRAMEWORKS=base_frameworks)
+
+if GetOption('extras'):
+  replay_env.Program('tests/test_replay', ['tests/test_replay.cc'], LIBS=replay_libs)

tools/replay/camera.cc

@@ -0,0 +1,116 @@
+#include "tools/replay/camera.h"
+
+#include <algorithm>
+
+#include <capnp/dynamic.h>
+
+#include "system/camerad/cameras/nv12_info.h"
+#include "tools/replay/util.h"
+
+const int BUFFER_COUNT = 40;
+
+CameraServer::CameraServer(std::pair<int, int> camera_size[MAX_CAMERAS]) {
+  for (int i = 0; i < MAX_CAMERAS; ++i) {
+    std::tie(cameras_[i].width, cameras_[i].height) = camera_size[i];
+  }
+  startVipcServer();
+}
+
+CameraServer::~CameraServer() {
+  for (auto &cam : cameras_) {
+    if (cam.thread.joinable()) {
+      // Clear the queue
+      std::pair<FrameReader*, const Event *> item;
+      while (cam.queue.try_pop(item)) {
+        --publishing_;
+      }
+
+      // Signal termination and join the thread
+      cam.queue.push({});
+      cam.thread.join();
+    }
+  }
+  vipc_server_.reset(nullptr);
+}
+
+void CameraServer::startVipcServer() {
+  vipc_server_.reset(new VisionIpcServer("camerad"));
+  for (auto &cam : cameras_) {
+    cam.cached_buf.clear();
+
+    if (cam.width > 0 && cam.height > 0) {
+      rInfo("camera[%d] frame size %dx%d", cam.type, cam.width, cam.height);
+      auto [stride, y_height, uv_height_, buffer_size] = get_nv12_info(cam.width, cam.height);
+      (void)uv_height_;  // unused in replay
+      vipc_server_->create_buffers_with_sizes(cam.stream_type, BUFFER_COUNT, cam.width, cam.height,
+                                              buffer_size, stride, stride * y_height);
+      if (!cam.thread.joinable()) {
+        cam.thread = std::thread(&CameraServer::cameraThread, this, std::ref(cam));
+      }
+    }
+  }
+  vipc_server_->start_listener();
+}
+
+void CameraServer::cameraThread(Camera &cam) {
+  while (true) {
+    const auto [fr, event] = cam.queue.pop();
+    if (!fr) break;
+
+    capnp::FlatArrayMessageReader reader(event->data);
+    auto evt = reader.getRoot<cereal::Event>();
+    auto eidx = capnp::AnyStruct::Reader(evt).getPointerSection()[0].getAs<cereal::EncodeIndex>();
+
+    int segment_id = eidx.getSegmentId();
+    uint32_t frame_id = eidx.getFrameId();
+    if (auto yuv = getFrame(cam, fr, segment_id, frame_id)) {
+      VisionIpcBufExtra extra = {
+          .frame_id = frame_id,
+          .timestamp_sof = eidx.getTimestampSof(),
+          .timestamp_eof = eidx.getTimestampEof(),
+      };
+      vipc_server_->send(yuv, &extra);
+    } else {
+      rError("camera[%d] failed to get frame: %lu", cam.type, segment_id);
+    }
+
+    // Prefetch the next frame
+    getFrame(cam, fr, segment_id + 1, frame_id + 1);
+
+    --publishing_;
+  }
+}
+
+VisionBuf *CameraServer::getFrame(Camera &cam, FrameReader *fr, int32_t segment_id, uint32_t frame_id) {
+  // Check if the frame is cached
+  auto buf_it = std::find_if(cam.cached_buf.begin(), cam.cached_buf.end(),
+                             [frame_id](VisionBuf *buf) { return buf->get_frame_id() == frame_id; });
+  if (buf_it != cam.cached_buf.end()) return *buf_it;
+
+  VisionBuf *yuv_buf = vipc_server_->get_buffer(cam.stream_type);
+  if (fr->get(segment_id, yuv_buf)) {
+    yuv_buf->set_frame_id(frame_id);
+    cam.cached_buf.insert(yuv_buf);
+    return yuv_buf;
+  }
+  return nullptr;
+}
+
+void CameraServer::pushFrame(CameraType type, FrameReader *fr, const Event *event) {
+  auto &cam = cameras_[type];
+  if (cam.width != fr->width || cam.height != fr->height) {
+    cam.width = fr->width;
+    cam.height = fr->height;
+    waitForSent();
+    startVipcServer();
+  }
+
+  ++publishing_;
+  cam.queue.push({fr, event});
+}
+
+void CameraServer::waitForSent() {
+  while (publishing_ > 0) {
+    std::this_thread::yield();
+  }
+}

tools/replay/camera.h

@@ -0,0 +1,41 @@
+#pragma once
+
+#include <memory>
+#include <set>
+#include <tuple>
+#include <utility>
+
+#include "msgq/visionipc/visionipc_server.h"
+#include "common/queue.h"
+#include "tools/replay/framereader.h"
+#include "tools/replay/logreader.h"
+
+class CameraServer {
+public:
+  CameraServer(std::pair<int, int> camera_size[MAX_CAMERAS] = nullptr);
+  ~CameraServer();
+  void pushFrame(CameraType type, FrameReader* fr, const Event *event);
+  void waitForSent();
+
+protected:
+  struct Camera {
+    CameraType type;
+    VisionStreamType stream_type;
+    int width;
+    int height;
+    std::thread thread;
+    SafeQueue<std::pair<FrameReader*, const Event *>> queue;
+    std::set<VisionBuf *> cached_buf;
+  };
+  void startVipcServer();
+  void cameraThread(Camera &cam);
+  VisionBuf *getFrame(Camera &cam, FrameReader *fr, int32_t segment_id, uint32_t frame_id);
+
+  Camera cameras_[MAX_CAMERAS] = {
+      {.type = RoadCam, .stream_type = VISION_STREAM_ROAD},
+      {.type = DriverCam, .stream_type = VISION_STREAM_DRIVER},
+      {.type = WideRoadCam, .stream_type = VISION_STREAM_WIDE_ROAD},
+  };
+  std::atomic<int> publishing_ = 0;
+  std::unique_ptr<VisionIpcServer> vipc_server_;
+};

tools/replay/can_replay.py

@@ -0,0 +1,107 @@
+#!/usr/bin/env python3
+import argparse
+import os
+import time
+import usb1
+import threading
+
+from openpilot.common.realtime import config_realtime_process, Ratekeeper, DT_CTRL
+from openpilot.selfdrive.pandad import can_capnp_to_list
+from openpilot.tools.lib.logreader import LogReader
+from panda import PandaJungle
+
+# set both to cycle power or ignition
+PWR_ON = int(os.getenv("PWR_ON", "0"))
+PWR_OFF = int(os.getenv("PWR_OFF", "0"))
+IGN_ON = int(os.getenv("ON", "0"))
+IGN_OFF = int(os.getenv("OFF", "0"))
+ENABLE_IGN = IGN_ON > 0 and IGN_OFF > 0
+ENABLE_PWR = PWR_ON > 0 and PWR_OFF > 0
+
+
+def send_thread(j: PandaJungle, flock):
+  if "FLASH" in os.environ:
+    with flock:
+      j.flash()
+
+  j.reset()
+  for i in [0, 1, 2, 3, 0xFFFF]:
+    j.can_clear(i)
+    j.set_can_speed_kbps(i, 500)
+  j.set_ignition(True)
+  j.set_panda_power(True)
+  j.set_can_loopback(False)
+
+  rk = Ratekeeper(1 / DT_CTRL, print_delay_threshold=None)
+  while True:
+    # handle cycling
+    if ENABLE_PWR:
+      i = (rk.frame*DT_CTRL) % (PWR_ON + PWR_OFF) < PWR_ON
+      j.set_panda_power(i)
+    if ENABLE_IGN:
+      i = (rk.frame*DT_CTRL) % (IGN_ON + IGN_OFF) < IGN_ON
+      j.set_ignition(i)
+
+    send = CAN_MSGS[rk.frame % len(CAN_MSGS)]
+    send = list(filter(lambda x: x[-1] <= 2, send))
+    try:
+      j.can_send_many(send)
+    except usb1.USBErrorTimeout:
+      # timeout is fine, just means the CAN TX buffer is full
+      pass
+
+    # Drain panda message buffer
+    j.can_recv()
+    rk.keep_time()
+
+
+def connect():
+  config_realtime_process(3, 55)
+
+  serials = {}
+  flashing_lock = threading.Lock()
+  while True:
+    # look for new devices
+    for s in PandaJungle.list():
+      if s not in serials:
+        print("starting send thread for", s)
+        serials[s] = threading.Thread(target=send_thread, args=(PandaJungle(s), flashing_lock))
+        serials[s].start()
+
+    # try to join all send threads
+    cur_serials = serials.copy()
+    for s, t in cur_serials.items():
+      if t is  not None:
+        t.join(0.01)
+        if not t.is_alive():
+          del serials[s]
+
+    time.sleep(1)
+
+
+def load_route(route_or_segment_name):
+  print("Loading log...")
+  lr = LogReader(route_or_segment_name)
+  CP = lr.first("carParams")
+  print(f"carFingerprint: '{CP.carFingerprint}'")
+  mbytes = [m.as_builder().to_bytes() for m in lr if m.which() == 'can']
+  return [m[1] for m in can_capnp_to_list(mbytes)]
+
+
+if __name__ == "__main__":
+  parser = argparse.ArgumentParser(description="Replay CAN messages from a route to all connected pandas and jungles in a loop.",
+                                   formatter_class=argparse.ArgumentDefaultsHelpFormatter)
+  parser.add_argument("route_or_segment_name", nargs='?', help="The route or segment name to replay. If not specified, a default public route will be used.")
+  args = parser.parse_args()
+
+  if args.route_or_segment_name is None:
+    args.route_or_segment_name = "77611a1fac303767/2020-03-24--09-50-38/2:4"
+
+  CAN_MSGS = load_route(args.route_or_segment_name)
+
+  if ENABLE_PWR:
+    print(f"Cycling power: on for {PWR_ON}s, off for {PWR_OFF}s")
+  if ENABLE_IGN:
+    print(f"Cycling ignition: on for {IGN_ON}s, off for {IGN_OFF}s")
+
+  connect()

tools/replay/consoleui.cc

@@ -0,0 +1,388 @@
+#include "tools/replay/consoleui.h"
+
+#include <time.h>
+#include <initializer_list>
+#include <string>
+#include <tuple>
+#include <utility>
+
+#include "common/ratekeeper.h"
+#include "common/util.h"
+#include "common/version.h"
+#include "tools/replay/py_downloader.h"
+
+namespace {
+
+const int BORDER_SIZE = 3;
+
+const std::initializer_list<std::pair<std::string, std::string>> keyboard_shortcuts[] = {
+  {
+    {"s", "+10s"},
+    {"shift+s", "-10s"},
+    {"m", "+60s"},
+    {"shift+m", "-60s"},
+    {"space", "Pause/Resume"},
+    {"e", "Next Engagement"},
+    {"d", "Next Disengagement"},
+    {"t", "Next User Tag"},
+    {"i", "Next Info"},
+    {"w", "Next Warning"},
+    {"c", "Next Critical"},
+  },
+  {
+    {"enter", "Enter seek request"},
+    {"+/-", "Playback speed"},
+    {"q", "Exit"},
+  },
+};
+
+enum Color {
+  Default,
+  Debug,
+  Yellow,
+  Green,
+  Red,
+  Cyan,
+  BrightWhite,
+  Engaged,
+  Disengaged,
+};
+
+void add_str(WINDOW *w, const char *str, Color color = Color::Default, bool bold = false) {
+  if (color != Color::Default) wattron(w, COLOR_PAIR(color));
+  if (bold) wattron(w, A_BOLD);
+  waddstr(w, str);
+  if (bold) wattroff(w, A_BOLD);
+  if (color != Color::Default) wattroff(w, COLOR_PAIR(color));
+}
+
+ExitHandler do_exit;
+
+}  // namespace
+
+ConsoleUI::ConsoleUI(Replay *replay) : replay(replay), sm({"carState", "liveParameters"}) {
+  // Initialize curses
+  initscr();
+  clear();
+  curs_set(false);
+  cbreak();  // Line buffering disabled. pass on everything
+  noecho();
+  keypad(stdscr, true);
+  nodelay(stdscr, true);  // non-blocking getchar()
+
+  // Initialize all the colors. https://www.ditig.com/256-colors-cheat-sheet
+  start_color();
+  init_pair(Color::Debug, 246, COLOR_BLACK);  // #949494
+  init_pair(Color::Yellow, 184, COLOR_BLACK);
+  init_pair(Color::Red, COLOR_RED, COLOR_BLACK);
+  init_pair(Color::Cyan, COLOR_CYAN, COLOR_BLACK);
+  init_pair(Color::BrightWhite, 15, COLOR_BLACK);
+  init_pair(Color::Disengaged, COLOR_BLUE, COLOR_BLUE);
+  init_pair(Color::Engaged, 28, 28);
+  init_pair(Color::Green, 34, COLOR_BLACK);
+
+  initWindows();
+
+  installMessageHandler([this](ReplyMsgType type, const std::string msg) {
+    std::scoped_lock lock(mutex);
+    logs.emplace_back(type, msg);
+  });
+  installDownloadProgressHandler([this](uint64_t cur, uint64_t total, bool success) {
+    std::scoped_lock lock(mutex);
+    progress_cur = cur;
+    progress_total = total;
+    download_success = success;
+  });
+}
+
+ConsoleUI::~ConsoleUI() {
+  installDownloadProgressHandler(nullptr);
+  installMessageHandler(nullptr);
+  endwin();
+}
+
+void ConsoleUI::initWindows() {
+  getmaxyx(stdscr, max_height, max_width);
+  w.fill(nullptr);
+  w[Win::Title] = newwin(1, max_width, 0, 0);
+  w[Win::Stats] = newwin(2, max_width - 2 * BORDER_SIZE, 2, BORDER_SIZE);
+  w[Win::Timeline] = newwin(4, max_width - 2 * BORDER_SIZE, 5, BORDER_SIZE);
+  w[Win::TimelineDesc] = newwin(1, 100, 10, BORDER_SIZE);
+  w[Win::CarState] = newwin(3, 100, 12, BORDER_SIZE);
+  w[Win::DownloadBar] = newwin(1, 100, 16, BORDER_SIZE);
+  if (int log_height = max_height - 27; log_height > 4) {
+    w[Win::LogBorder] = newwin(log_height, max_width - 2 * (BORDER_SIZE - 1), 17, BORDER_SIZE - 1);
+    box(w[Win::LogBorder], 0, 0);
+    w[Win::Log] = newwin(log_height - 2, max_width - 2 * BORDER_SIZE, 18, BORDER_SIZE);
+    scrollok(w[Win::Log], true);
+  }
+  if (max_height >= 23) {
+    w[Win::Help] = newwin(5, max_width - (2 * BORDER_SIZE), max_height - 6, BORDER_SIZE);
+  } else if (max_height >= 17) {
+    w[Win::Help] = newwin(1, max_width - (2 * BORDER_SIZE), max_height - 1, BORDER_SIZE);
+    mvwprintw(w[Win::Help], 0, 0, "Expand screen vertically to list available commands");
+  }
+
+  // set the title bar
+  wbkgd(w[Win::Title], A_REVERSE);
+  mvwprintw(w[Win::Title], 0, 3, "openpilot replay %s", COMMA_VERSION);
+
+  // show windows on the real screen
+  refresh();
+  displayTimelineDesc();
+  if (max_height >= 23) displayHelp();
+  updateSummary();
+  updateTimeline();
+  for (auto win : w) {
+    if (win) wrefresh(win);
+  }
+}
+
+void ConsoleUI::updateSize() {
+  if (is_term_resized(max_height, max_width)) {
+    for (auto win : w) {
+      if (win) delwin(win);
+    }
+    endwin();
+    clear();
+    refresh();
+    initWindows();
+    rWarning("resize term %dx%d", max_height, max_width);
+  }
+}
+
+void ConsoleUI::updateStatus() {
+  auto write_item = [this](int y, int x, const char *key, const std::string &value, const std::string &unit,
+                           bool bold = false, Color color = Color::BrightWhite) {
+    auto win = w[Win::CarState];
+    wmove(win, y, x);
+    add_str(win, key);
+    add_str(win, value.c_str(), color, bold);
+    add_str(win, unit.c_str());
+  };
+  static const std::pair<const char *, Color> status_text[] = {
+      {"playing", Color::Green},
+      {"paused...", Color::Yellow},
+  };
+
+  sm.update(0);
+
+  auto [status_str, status_color] = status_text[status];
+  write_item(0, 0, "STATUS:    ", status_str, "      ", false, status_color);
+  auto cur_ts = replay->routeDateTime() + (int)replay->currentSeconds();
+  char *time_string = ctime(&cur_ts);
+  std::string current_segment = " - " + std::to_string((int)(replay->currentSeconds() / 60));
+  write_item(0, 25, "TIME:  ", time_string, current_segment, true);
+
+  auto p = sm["liveParameters"].getLiveParameters();
+  write_item(1, 0, "STIFFNESS: ", util::string_format("%.2f %%", p.getStiffnessFactor() * 100), "  ");
+  write_item(1, 25, "SPEED: ", util::string_format("%.2f", sm["carState"].getCarState().getVEgo()), " m/s");
+  write_item(2, 0, "STEER RATIO: ", util::string_format("%.2f", p.getSteerRatio()), "");
+  auto angle_offsets = util::string_format("%.2f|%.2f", p.getAngleOffsetAverageDeg(), p.getAngleOffsetDeg());
+  write_item(2, 25, "ANGLE OFFSET(AVG|INSTANT): ", angle_offsets, " deg");
+
+  wrefresh(w[Win::CarState]);
+}
+
+void ConsoleUI::displayHelp() {
+  for (int i = 0; i < std::size(keyboard_shortcuts); ++i) {
+    wmove(w[Win::Help], i * 2, 0);
+    for (auto &[key, desc] : keyboard_shortcuts[i]) {
+      wattron(w[Win::Help], A_REVERSE);
+      waddstr(w[Win::Help], (' ' + key + ' ').c_str());
+      wattroff(w[Win::Help], A_REVERSE);
+      waddstr(w[Win::Help], (' ' + desc + ' ').c_str());
+    }
+  }
+  wrefresh(w[Win::Help]);
+}
+
+void ConsoleUI::displayTimelineDesc() {
+  std::tuple<Color, const char *, bool> indicators[]{
+      {Color::Engaged, " Engaged ", false},
+      {Color::Disengaged, " Disengaged ", false},
+      {Color::Green, " Info ", true},
+      {Color::Yellow, " Warning ", true},
+      {Color::Red, " Critical ", true},
+      {Color::Cyan, " User Tag ", true},
+  };
+  for (auto [color, name, bold] : indicators) {
+    add_str(w[Win::TimelineDesc], "__", color, bold);
+    add_str(w[Win::TimelineDesc], name);
+  }
+}
+
+void ConsoleUI::logMessage(ReplyMsgType type, const std::string &msg) {
+  if (auto win = w[Win::Log]) {
+    Color color = Color::Default;
+    if (type == ReplyMsgType::Debug) {
+      color = Color::Debug;
+    } else if (type == ReplyMsgType::Warning) {
+      color = Color::Yellow;
+    } else if (type == ReplyMsgType::Critical) {
+      color = Color::Red;
+    }
+    add_str(win, (msg + "\n").c_str(), color);
+    wrefresh(win);
+  }
+}
+
+void ConsoleUI::updateProgressBar() {
+  werase(w[Win::DownloadBar]);
+  if (download_success && progress_cur < progress_total) {
+    const int width = 35;
+    const float progress = progress_cur / (double)progress_total;
+    const int pos = width * progress;
+    wprintw(w[Win::DownloadBar], "Downloading [%s>%s]  %d%% %s", std::string(pos, '=').c_str(),
+            std::string(width - pos, ' ').c_str(), int(progress * 100.0), formattedDataSize(progress_total).c_str());
+  }
+  wrefresh(w[Win::DownloadBar]);
+}
+
+void ConsoleUI::updateSummary() {
+  const auto &route = replay->route();
+  mvwprintw(w[Win::Stats], 0, 0, "Route: %s, %lu segments", route.name().c_str(), route.segments().size());
+  mvwprintw(w[Win::Stats], 1, 0, "Car Fingerprint: %s", replay->carFingerprint().c_str());
+  wrefresh(w[Win::Stats]);
+}
+
+void ConsoleUI::updateTimeline() {
+  auto win = w[Win::Timeline];
+  int width = getmaxx(win);
+  werase(win);
+
+  wattron(win, COLOR_PAIR(Color::Disengaged));
+  mvwhline(win, 1, 0, ' ', width);
+  mvwhline(win, 2, 0, ' ', width);
+  wattroff(win, COLOR_PAIR(Color::Disengaged));
+
+  const int total_sec = replay->maxSeconds() - replay->minSeconds();
+  for (const auto &entry : *replay->getTimeline()) {
+    int start_pos = ((entry.start_time - replay->minSeconds()) / total_sec) * width;
+    int end_pos = ((entry.end_time - replay->minSeconds()) / total_sec) * width;
+    if (entry.type == TimelineType::Engaged) {
+      mvwchgat(win, 1, start_pos, end_pos - start_pos + 1, A_COLOR, Color::Engaged, NULL);
+      mvwchgat(win, 2, start_pos, end_pos - start_pos + 1, A_COLOR, Color::Engaged, NULL);
+    } else if (entry.type == TimelineType::UserBookmark) {
+      mvwchgat(win, 3, start_pos, end_pos - start_pos + 1, ACS_S3, Color::Cyan, NULL);
+    } else {
+      auto color_id = Color::Green;
+      if (entry.type != TimelineType::AlertInfo) {
+        color_id = entry.type == TimelineType::AlertWarning ? Color::Yellow : Color::Red;
+      }
+      mvwchgat(win, 3, start_pos, end_pos - start_pos + 1, ACS_S3, color_id, NULL);
+    }
+  }
+
+  int cur_pos = ((replay->currentSeconds() - replay->minSeconds()) / total_sec) * width;
+  wattron(win, COLOR_PAIR(Color::BrightWhite));
+  mvwaddch(win, 0, cur_pos, ACS_VLINE);
+  mvwaddch(win, 3, cur_pos, ACS_VLINE);
+  wattroff(win, COLOR_PAIR(Color::BrightWhite));
+  wrefresh(win);
+}
+
+void ConsoleUI::pauseReplay(bool pause) {
+  replay->pause(pause);
+  status = pause ? Status::Paused : Status::Playing;
+}
+
+void ConsoleUI::handleKey(char c) {
+  if (c == '\n') {
+    // pause the replay and blocking getchar()
+    pauseReplay(true);
+    updateStatus();
+    curs_set(true);
+    nodelay(stdscr, false);
+
+    // Wait for user input
+    rWarning("Waiting for input...");
+    int y = getmaxy(stdscr) - 9;
+    move(y, BORDER_SIZE);
+    add_str(stdscr, "Enter seek request: ", Color::BrightWhite, true);
+    refresh();
+
+    // Seek to choice
+    echo();
+    int choice = 0;
+    scanw((char *)"%d", &choice);
+    noecho();
+    pauseReplay(false);
+    replay->seekTo(choice, false);
+
+    // Clean up and turn off the blocking mode
+    move(y, 0);
+    clrtoeol();
+    nodelay(stdscr, true);
+    curs_set(false);
+    refresh();
+
+  } else if (c == '+' || c == '=') {
+    auto it = std::upper_bound(speed_array.begin(), speed_array.end(), replay->getSpeed());
+    if (it != speed_array.end()) {
+      rWarning("playback speed: %.1fx", *it);
+      replay->setSpeed(*it);
+    }
+  } else if (c == '_' || c == '-') {
+    auto it = std::lower_bound(speed_array.begin(), speed_array.end(), replay->getSpeed());
+    if (it != speed_array.begin()) {
+      auto prev = std::prev(it);
+      rWarning("playback speed: %.1fx", *prev);
+      replay->setSpeed(*prev);
+    }
+  } else if (c == 'e') {
+    replay->seekToFlag(FindFlag::nextEngagement);
+  } else if (c == 'd') {
+    replay->seekToFlag(FindFlag::nextDisEngagement);
+  } else if (c == 't') {
+    replay->seekToFlag(FindFlag::nextUserBookmark);
+  } else if (c == 'i') {
+    replay->seekToFlag(FindFlag::nextInfo);
+  } else if (c == 'w') {
+    replay->seekToFlag(FindFlag::nextWarning);
+  } else if (c == 'c') {
+    replay->seekToFlag(FindFlag::nextCritical);
+  } else if (c == 'm') {
+    replay->seekTo(+60, true);
+  } else if (c == 'M') {
+    replay->seekTo(-60, true);
+  } else if (c == 's') {
+    replay->seekTo(+10, true);
+  } else if (c == 'S') {
+    replay->seekTo(-10, true);
+  } else if (c == ' ') {
+    pauseReplay(!replay->isPaused());
+  }
+}
+
+int ConsoleUI::exec() {
+  RateKeeper rk("Replay", 20);
+
+  while (!do_exit) {
+    int c = getch();
+    if (c == 'q' || c == 'Q') {
+      break;
+    }
+    handleKey(c);
+
+    if (rk.frame() % 25) {
+      updateSize();
+      updateSummary();
+    }
+
+    updateTimeline();
+    updateStatus();
+
+    {
+      std::scoped_lock lock(mutex);
+      updateProgressBar();
+      for (auto &[type, msg] : logs) {
+        logMessage(type, msg);
+      }
+      logs.clear();
+    }
+
+    rk.keepTime();
+  }
+  return 0;
+}

tools/replay/consoleui.h

@@ -0,0 +1,43 @@
+#pragma once
+
+#include <array>
+#include <mutex>
+#include <vector>
+
+#include "tools/replay/replay.h"
+#include <ncurses.h>
+
+class ConsoleUI {
+public:
+  ConsoleUI(Replay *replay);
+  ~ConsoleUI();
+  int exec();
+  inline static const std::array speed_array = {0.2f, 0.5f, 1.0f, 2.0f, 4.0f, 8.0f};
+
+private:
+  void initWindows();
+  void handleKey(char c);
+  void displayHelp();
+  void displayTimelineDesc();
+  void updateTimeline();
+  void updateSummary();
+  void updateStatus();
+  void pauseReplay(bool pause);
+  void updateSize();
+  void updateProgressBar();
+  void logMessage(ReplyMsgType type, const std::string &msg);
+
+  enum Status { Playing, Paused };
+  enum Win { Title, Stats, Log, LogBorder, DownloadBar, Timeline, TimelineDesc, Help, CarState, Max};
+  std::array<WINDOW*, Win::Max> w{};
+  SubMaster sm;
+  Replay *replay;
+  int max_width, max_height;
+  Status status = Status::Playing;
+
+  std::mutex mutex;
+  std::vector<std::pair<ReplyMsgType, std::string>> logs;
+  uint64_t progress_cur = 0;
+  uint64_t progress_total = 0;
+  bool download_success = false;
+};

tools/replay/filereader.cc

@@ -0,0 +1,14 @@
+#include "tools/replay/filereader.h"
+
+#include "common/util.h"
+#include "tools/replay/py_downloader.h"
+
+std::string FileReader::read(const std::string &file, std::atomic<bool> *abort) {
+  const bool is_remote = (file.find("https://") == 0) || (file.find("http://") == 0);
+  if (is_remote) {
+    std::string local_path = PyDownloader::download(file, cache_to_local_, abort);
+    if (local_path.empty()) return {};
+    return util::read_file(local_path);
+  }
+  return util::read_file(file);
+}

tools/replay/filereader.h

@@ -0,0 +1,14 @@
+#pragma once
+
+#include <atomic>
+#include <string>
+
+class FileReader {
+public:
+  FileReader(bool cache_to_local) : cache_to_local_(cache_to_local) {}
+  virtual ~FileReader() {}
+  std::string read(const std::string &file, std::atomic<bool> *abort = nullptr);
+
+private:
+  bool cache_to_local_;
+};

tools/replay/framereader.cc

@@ -0,0 +1,313 @@
+#include "tools/replay/framereader.h"
+
+#include <map>
+#include <memory>
+#include <tuple>
+#include <utility>
+
+#include "common/util.h"
+#include "libyuv.h"
+#include "tools/replay/py_downloader.h"
+#include "tools/replay/util.h"
+#include "system/hardware/hw.h"
+
+#ifdef __APPLE__
+#define HW_DEVICE_TYPE AV_HWDEVICE_TYPE_VIDEOTOOLBOX
+#define HW_PIX_FMT AV_PIX_FMT_VIDEOTOOLBOX
+#else
+#define HW_DEVICE_TYPE AV_HWDEVICE_TYPE_CUDA
+#define HW_PIX_FMT AV_PIX_FMT_CUDA
+#endif
+
+namespace {
+
+enum AVPixelFormat get_hw_format(AVCodecContext *ctx, const enum AVPixelFormat *pix_fmts) {
+  enum AVPixelFormat *hw_pix_fmt = reinterpret_cast<enum AVPixelFormat *>(ctx->opaque);
+  for (const enum AVPixelFormat *p = pix_fmts; *p != -1; p++) {
+    if (*p == *hw_pix_fmt) return *p;
+  }
+  rWarning("Please run replay with the --no-hw-decoder flag!");
+  *hw_pix_fmt = AV_PIX_FMT_NONE;
+  return AV_PIX_FMT_YUV420P;
+}
+
+struct DecoderManager {
+  VideoDecoder *acquire(CameraType type, AVCodecParameters *codecpar, bool hw_decoder) {
+    auto key = std::tuple(type, codecpar->width, codecpar->height);
+    std::unique_lock lock(mutex_);
+    if (auto it = decoders_.find(key); it != decoders_.end()) {
+      return it->second.get();
+    }
+
+    std::unique_ptr<VideoDecoder> decoder;
+    #ifndef __APPLE__
+    if (!Hardware::PC() && hw_decoder) {
+      decoder = std::make_unique<QcomVideoDecoder>();
+    } else
+    #endif
+    {
+      decoder = std::make_unique<FFmpegVideoDecoder>();
+    }
+
+    if (!decoder->open(codecpar, hw_decoder)) {
+      decoder.reset(nullptr);
+    }
+    decoders_[key] = std::move(decoder);
+    return decoders_[key].get();
+  }
+
+  std::mutex mutex_;
+  std::map<std::tuple<CameraType, int, int>, std::unique_ptr<VideoDecoder>> decoders_;
+};
+
+DecoderManager decoder_manager;
+
+}  // namespace
+
+FrameReader::FrameReader() {
+  av_log_set_level(AV_LOG_QUIET);
+}
+
+FrameReader::~FrameReader() {
+  if (input_ctx) avformat_close_input(&input_ctx);
+}
+
+bool FrameReader::load(CameraType type, const std::string &url, bool no_hw_decoder, std::atomic<bool> *abort, bool local_cache) {
+  std::string local_file_path;
+  if (url.find("https://") == 0 || url.find("http://") == 0) {
+    local_file_path = PyDownloader::download(url, local_cache, abort);
+    if (local_file_path.empty()) return false;
+  } else {
+    local_file_path = url;
+  }
+  return loadFromFile(type, local_file_path, no_hw_decoder, abort);
+}
+
+bool FrameReader::loadFromFile(CameraType type, const std::string &file, bool no_hw_decoder, std::atomic<bool> *abort) {
+  if (avformat_open_input(&input_ctx, file.c_str(), nullptr, nullptr) != 0 ||
+      avformat_find_stream_info(input_ctx, nullptr) < 0) {
+    rError("Failed to open input file or find video stream");
+    return false;
+  }
+  input_ctx->probesize = 10 * 1024 * 1024;  // 10MB
+
+  video_stream_idx_ = av_find_best_stream(input_ctx, AVMEDIA_TYPE_VIDEO, -1, -1, NULL, 0);
+  if (video_stream_idx_ < 0) {
+    rError("No video stream found in file");
+    return false;
+  }
+
+  decoder_ = decoder_manager.acquire(type, input_ctx->streams[video_stream_idx_]->codecpar, !no_hw_decoder);
+  if (!decoder_) {
+    return false;
+  }
+  width = decoder_->width;
+  height = decoder_->height;
+
+  AVPacket pkt;
+  packets_info.reserve(60 * 20);  // 20fps, one minute
+  while (!(abort && *abort) && av_read_frame(input_ctx, &pkt) == 0) {
+    if (pkt.stream_index == video_stream_idx_) {
+      packets_info.emplace_back(PacketInfo{.flags = pkt.flags, .pos = pkt.pos});
+    }
+    av_packet_unref(&pkt);
+  }
+  avio_seek(input_ctx->pb, 0, SEEK_SET);
+  return !packets_info.empty();
+}
+
+bool FrameReader::get(int idx, VisionBuf *buf) {
+  if (!buf || idx < 0 || idx >= packets_info.size()) {
+    return false;
+  }
+  return decoder_->decode(this, idx, buf);
+}
+
+// class VideoDecoder
+
+FFmpegVideoDecoder::FFmpegVideoDecoder() {
+  av_frame_ = av_frame_alloc();
+  hw_frame_ = av_frame_alloc();
+}
+
+FFmpegVideoDecoder::~FFmpegVideoDecoder() {
+  if (hw_device_ctx) av_buffer_unref(&hw_device_ctx);
+  if (decoder_ctx) avcodec_free_context(&decoder_ctx);
+  av_frame_free(&av_frame_);
+  av_frame_free(&hw_frame_);
+}
+
+bool FFmpegVideoDecoder::open(AVCodecParameters *codecpar, bool hw_decoder) {
+  const AVCodec *decoder = avcodec_find_decoder(codecpar->codec_id);
+  if (!decoder) return false;
+
+  decoder_ctx = avcodec_alloc_context3(decoder);
+  if (!decoder_ctx || avcodec_parameters_to_context(decoder_ctx, codecpar) != 0) {
+    rError("Failed to allocate or initialize codec context");
+    return false;
+  }
+  width = (decoder_ctx->width + 3) & ~3;
+  height = decoder_ctx->height;
+
+  if (hw_decoder && !initHardwareDecoder(HW_DEVICE_TYPE)) {
+    rWarning("No device with hardware decoder found. fallback to CPU decoding.");
+  }
+
+  if (avcodec_open2(decoder_ctx, decoder, nullptr) < 0) {
+    rError("Failed to open codec");
+    return false;
+  }
+  return true;
+}
+
+bool FFmpegVideoDecoder::initHardwareDecoder(AVHWDeviceType hw_device_type) {
+  const AVCodecHWConfig *config = nullptr;
+  for (int i = 0; (config = avcodec_get_hw_config(decoder_ctx->codec, i)) != nullptr; i++) {
+    if (config->methods & AV_CODEC_HW_CONFIG_METHOD_HW_DEVICE_CTX && config->device_type == hw_device_type) {
+      hw_pix_fmt = config->pix_fmt;
+      break;
+    }
+  }
+  if (!config) {
+    rWarning("Hardware configuration not found");
+    return false;
+  }
+
+  int ret = av_hwdevice_ctx_create(&hw_device_ctx, hw_device_type, nullptr, nullptr, 0);
+  if (ret < 0) {
+    hw_pix_fmt = AV_PIX_FMT_NONE;
+    rWarning("Failed to create specified HW device %d.", ret);
+    return false;
+  }
+
+  decoder_ctx->hw_device_ctx = av_buffer_ref(hw_device_ctx);
+  decoder_ctx->opaque = &hw_pix_fmt;
+  decoder_ctx->get_format = get_hw_format;
+  return true;
+}
+
+bool FFmpegVideoDecoder::decode(FrameReader *reader, int idx, VisionBuf *buf) {
+  int current_idx = idx;
+  if (idx != reader->prev_idx + 1) {
+    // seeking to the nearest key frame
+    for (int i = idx; i >= 0; --i) {
+      if (reader->packets_info[i].flags & AV_PKT_FLAG_KEY) {
+        current_idx = i;
+        break;
+      }
+    }
+
+    auto pos = reader->packets_info[current_idx].pos;
+    int ret = avformat_seek_file(reader->input_ctx, 0, pos, pos, pos, AVSEEK_FLAG_BYTE);
+    if (ret < 0) {
+      rError("Failed to seek to byte position %lld: %d", pos, AVERROR(ret));
+      return false;
+    }
+    avcodec_flush_buffers(decoder_ctx);
+  }
+  reader->prev_idx = idx;
+
+  AVPacket pkt;
+  while (av_read_frame(reader->input_ctx, &pkt) >= 0) {
+    // Skip non-video packets
+    if (pkt.stream_index != reader->video_stream_idx_) {
+      av_packet_unref(&pkt);
+      continue;
+    }
+
+    AVFrame *frame = decodeFrame(&pkt);
+    av_packet_unref(&pkt);
+    if (!frame) {
+      rError("Failed to decode frame at index %d", current_idx);
+      return false;
+    }
+
+    if (current_idx++ == idx) {
+      return copyBuffer(frame, buf);
+    }
+  }
+  rError("Failed to find frame at index %d", idx);
+  return false;
+}
+
+AVFrame *FFmpegVideoDecoder::decodeFrame(AVPacket *pkt) {
+  int ret = avcodec_send_packet(decoder_ctx, pkt);
+  if (ret < 0) {
+    rError("Error sending a packet for decoding: %d", ret);
+    return nullptr;
+  }
+
+  ret = avcodec_receive_frame(decoder_ctx, av_frame_);
+  if (ret != 0) {
+    rError("avcodec_receive_frame error: %d", ret);
+    return nullptr;
+  }
+
+  if (av_frame_->format == hw_pix_fmt && av_hwframe_transfer_data(hw_frame_, av_frame_, 0) < 0) {
+    rError("error transferring frame data from GPU to CPU");
+    return nullptr;
+  }
+  return (av_frame_->format == hw_pix_fmt) ? hw_frame_ : av_frame_;
+}
+
+bool FFmpegVideoDecoder::copyBuffer(AVFrame *f, VisionBuf *buf) {
+  if (hw_pix_fmt == HW_PIX_FMT) {
+    for (int i = 0; i < height/2; i++) {
+      memcpy(buf->y + (i*2 + 0)*buf->stride, f->data[0] + (i*2 + 0)*f->linesize[0], width);
+      memcpy(buf->y + (i*2 + 1)*buf->stride, f->data[0] + (i*2 + 1)*f->linesize[0], width);
+      memcpy(buf->uv + i*buf->stride, f->data[1] + i*f->linesize[1], width);
+    }
+  } else {
+    libyuv::I420ToNV12(f->data[0], f->linesize[0],
+                       f->data[1], f->linesize[1],
+                       f->data[2], f->linesize[2],
+                       buf->y, buf->stride,
+                       buf->uv, buf->stride,
+                       width, height);
+  }
+  return true;
+}
+
+#ifndef __APPLE__
+bool QcomVideoDecoder::open(AVCodecParameters *codecpar, bool hw_decoder) {
+  if (codecpar->codec_id != AV_CODEC_ID_HEVC) {
+    rError("Hardware decoder only supports HEVC codec");
+    return false;
+  }
+  width = codecpar->width;
+  height = codecpar->height;
+  msm_vidc.init(VIDEO_DEVICE, width, height, V4L2_PIX_FMT_HEVC);
+  return true;
+}
+
+bool QcomVideoDecoder::decode(FrameReader *reader, int idx, VisionBuf *buf) {
+  int from_idx = idx;
+  if (idx != reader->prev_idx + 1) {
+    // seeking to the nearest key frame
+    for (int i = idx; i >= 0; --i) {
+      if (reader->packets_info[i].flags & AV_PKT_FLAG_KEY) {
+        from_idx = i;
+        break;
+      }
+    }
+
+    auto pos = reader->packets_info[from_idx].pos;
+    int ret = avformat_seek_file(reader->input_ctx, 0, pos, pos, pos, AVSEEK_FLAG_BYTE);
+    if (ret < 0) {
+      rError("Failed to seek to byte position %lld: %d", pos, AVERROR(ret));
+      return false;
+    }
+  }
+  reader->prev_idx = idx;
+  bool result = false;
+  AVPacket pkt;
+  msm_vidc.avctx = reader->input_ctx;
+  for (int i = from_idx; i <= idx; ++i) {
+    if (av_read_frame(reader->input_ctx, &pkt) == 0) {
+      result = msm_vidc.decodeFrame(&pkt, buf) && (i == idx);
+      av_packet_unref(&pkt);
+    }
+  }
+  return result;
+}
+#endif

tools/replay/framereader.h

@@ -0,0 +1,80 @@
+#pragma once
+
+#include <string>
+#include <vector>
+
+#include "msgq/visionipc/visionbuf.h"
+#include "tools/replay/util.h"
+
+#ifndef __APPLE__
+#include "tools/replay/qcom_decoder.h"
+#endif
+
+extern "C" {
+#include <libavcodec/avcodec.h>
+#include <libavformat/avformat.h>
+}
+
+class VideoDecoder;
+
+class FrameReader {
+public:
+  FrameReader();
+  ~FrameReader();
+  bool load(CameraType type, const std::string &url, bool no_hw_decoder = false, std::atomic<bool> *abort = nullptr, bool local_cache = false);
+  bool loadFromFile(CameraType type, const std::string &file, bool no_hw_decoder = false, std::atomic<bool> *abort = nullptr);
+  bool get(int idx, VisionBuf *buf);
+  size_t getFrameCount() const { return packets_info.size(); }
+
+  int width = 0, height = 0;
+
+  VideoDecoder *decoder_ = nullptr;
+  AVFormatContext *input_ctx = nullptr;
+  int video_stream_idx_ = -1;
+  int prev_idx = -1;
+  struct PacketInfo {
+    int flags;
+    int64_t pos;
+  };
+  std::vector<PacketInfo> packets_info;
+};
+
+
+class VideoDecoder {
+public:
+  virtual ~VideoDecoder() = default;
+  virtual bool open(AVCodecParameters *codecpar, bool hw_decoder) = 0;
+  virtual bool decode(FrameReader *reader, int idx, VisionBuf *buf) = 0;
+  int width = 0, height = 0;
+};
+
+class FFmpegVideoDecoder : public VideoDecoder {
+public:
+  FFmpegVideoDecoder();
+  ~FFmpegVideoDecoder() override;
+  bool open(AVCodecParameters *codecpar, bool hw_decoder) override;
+  bool decode(FrameReader *reader, int idx, VisionBuf *buf) override;
+
+private:
+  bool initHardwareDecoder(AVHWDeviceType hw_device_type);
+  AVFrame *decodeFrame(AVPacket *pkt);
+  bool copyBuffer(AVFrame *f, VisionBuf *buf);
+
+  AVFrame *av_frame_, *hw_frame_;
+  AVCodecContext *decoder_ctx = nullptr;
+  AVPixelFormat hw_pix_fmt = AV_PIX_FMT_NONE;
+  AVBufferRef *hw_device_ctx = nullptr;
+};
+
+#ifndef __APPLE__
+class QcomVideoDecoder : public VideoDecoder {
+public:
+  QcomVideoDecoder() {};
+  ~QcomVideoDecoder() override {};
+  bool open(AVCodecParameters *codecpar, bool hw_decoder) override;
+  bool decode(FrameReader *reader, int idx, VisionBuf *buf) override;
+
+private:
+  MsmVidc msm_vidc = MsmVidc();
+};
+#endif

tools/replay/lib/ui_helpers.py

@@ -0,0 +1,220 @@
+import itertools
+
+import matplotlib.pyplot as plt
+import numpy as np
+import pyray as rl
+
+from matplotlib.backends.backend_agg import FigureCanvasAgg
+from matplotlib.offsetbox import AnchoredOffsetbox, HPacker, TextArea
+
+from openpilot.common.transformations.camera import get_view_frame_from_calib_frame
+from openpilot.selfdrive.controls.radard import RADAR_TO_CAMERA
+
+
+RED = (255, 0, 0)
+GREEN = (0, 255, 0)
+BLUE = (0, 0, 255)
+YELLOW = (255, 255, 0)
+BLACK = (0, 0, 0)
+WHITE = (255, 255, 255)
+
+
+class UIParams:
+  lidar_x, lidar_y, lidar_zoom = 384, 960, 6
+  lidar_car_x, lidar_car_y = lidar_x / 2.0, lidar_y / 1.1
+  car_hwidth = 1.7272 / 2 * lidar_zoom
+  car_front = 2.6924 * lidar_zoom
+  car_back = 1.8796 * lidar_zoom
+  car_color = 110
+
+
+UP = UIParams
+
+METER_WIDTH = 20
+
+
+class Calibration:
+  def __init__(self, num_px, rpy, intrinsic, calib_scale):
+    self.intrinsic = intrinsic
+    self.extrinsics_matrix = get_view_frame_from_calib_frame(rpy[0], rpy[1], rpy[2], 0.0)[:, :3]
+    self.zoom = calib_scale
+
+  def car_space_to_ff(self, x, y, z):
+    car_space_projective = np.column_stack((x, y, z)).T
+
+    ep = self.extrinsics_matrix.dot(car_space_projective)
+    kep = self.intrinsic.dot(ep)
+    return (kep[:-1, :] / kep[-1, :]).T
+
+  def car_space_to_bb(self, x, y, z):
+    pts = self.car_space_to_ff(x, y, z)
+    return pts / self.zoom
+
+
+_COLOR_CACHE: dict[tuple[int, int, int], int] = {
+  (255, 0, 0): 1,  # RED
+  (0, 255, 0): 2,  # GREEN
+  (0, 0, 255): 3,  # BLUE
+  (255, 255, 0): 4,  # YELLOW
+  (0, 0, 0): 0,  # BLACK
+  (255, 255, 255): 255,  # WHITE
+}
+
+
+def find_color(lidar_surface, color):
+  return _COLOR_CACHE.get(color, 255)
+
+
+def to_topdown_pt(y, x):
+  px, py = x * UP.lidar_zoom + UP.lidar_car_x, -y * UP.lidar_zoom + UP.lidar_car_y
+  if px > 0 and py > 0 and px < UP.lidar_x and py < UP.lidar_y:
+    return int(px), int(py)
+  return -1, -1
+
+
+def draw_path(path, color, img, calibration, top_down, lid_color=None, z_off=0):
+  x, y, z = np.asarray(path.x), np.asarray(path.y), np.asarray(path.z) + z_off
+  pts = calibration.car_space_to_bb(x, y, z)
+  pts = np.round(pts).astype(int)
+
+  # draw lidar path point on lidar
+  # find color in 8 bit
+  if lid_color is not None and top_down is not None:
+    tcolor = find_color(top_down[0], lid_color)
+    for i in range(len(x)):
+      px, py = to_topdown_pt(x[i], y[i])
+      if px != -1:
+        top_down[1][px, py] = tcolor
+
+  height, width = img.shape[:2]
+  for x, y in pts:
+    if 1 < x < width - 1 and 1 < y < height - 1:
+      for a, b in itertools.permutations([-1, 0, -1], 2):
+        img[y + a, x + b] = color
+
+
+def init_plots(arr, name_to_arr_idx, plot_xlims, plot_ylims, plot_names, plot_colors, plot_styles):
+  color_palette = {"r": (1, 0, 0), "g": (0, 1, 0), "b": (0, 0, 1), "k": (0, 0, 0), "y": (1, 1, 0), "p": (0, 1, 1), "m": (1, 0, 1)}
+  label_palette = {**color_palette, "b": (43/255, 114/255, 1.0)}
+
+  dpi = 90
+  fig = plt.figure(figsize=(575 / dpi, 600 / dpi), dpi=dpi)
+  canvas = FigureCanvasAgg(fig)
+
+  fig.set_facecolor((0.2, 0.2, 0.2))
+
+  axs = []
+  for pn in range(len(plot_ylims)):
+    ax = fig.add_subplot(len(plot_ylims), 1, len(axs) + 1)
+    ax.set_xlim(plot_xlims[pn][0], plot_xlims[pn][1])
+    ax.set_ylim(plot_ylims[pn][0], plot_ylims[pn][1])
+    ax.patch.set_facecolor((0.4, 0.4, 0.4))
+    axs.append(ax)
+
+  plots, idxs, plot_select = [], [], []
+  for i, pl_list in enumerate(plot_names):
+    for j, item in enumerate(pl_list):
+      (plot,) = axs[i].plot(arr[:, name_to_arr_idx[item]], label=item, color=color_palette[plot_colors[i][j]], linestyle=plot_styles[i][j])
+      plots.append(plot)
+      idxs.append(name_to_arr_idx[item])
+      plot_select.append(i)
+    # Build colored title: each label colored to match its plot line
+    title_texts = []
+    for j2, (nm, cl) in enumerate(zip(pl_list, plot_colors[i], strict=False)):
+      if j2 > 0:
+        title_texts.append(TextArea(", ", textprops=dict(color="white", fontsize=10)))
+      title_texts.append(TextArea(nm, textprops=dict(color=label_palette[cl], fontsize=10)))
+    packed = HPacker(children=title_texts, pad=0, sep=0)
+    ab = AnchoredOffsetbox(loc='lower center', child=packed, bbox_to_anchor=(0.5, 1.0),
+                           bbox_transform=axs[i].transAxes, frameon=False, pad=0)
+    axs[i].add_artist(ab)
+    axs[i].tick_params(axis="x", colors="white")
+    axs[i].tick_params(axis="y", colors="white")
+
+    if i < len(plot_ylims) - 1:
+      axs[i].set_xticks([])
+
+  canvas.draw()
+
+  # Pre-create texture for plots (reuse each frame to avoid log spam)
+  w, h = canvas.get_width_height()
+  plot_image = rl.gen_image_color(w, h, rl.BLACK)
+  plot_texture = rl.load_texture_from_image(plot_image)
+  rl.unload_image(plot_image)
+
+  def draw_plots(arr):
+    for ax in axs:
+      ax.draw_artist(ax.patch)
+    for i in range(len(plots)):
+      plots[i].set_ydata(arr[:, idxs[i]])
+      axs[plot_select[i]].draw_artist(plots[i])
+
+    raw_data = np.ascontiguousarray(canvas.buffer_rgba(), dtype=np.uint8)
+    rl.update_texture(plot_texture, rl.ffi.cast("void *", raw_data.ctypes.data))
+    return plot_texture
+
+  return draw_plots
+
+
+def plot_model(m, img, calibration, top_down):
+  if calibration is None or top_down is None:
+    return
+
+  for lead in m.leadsV3:
+    if lead.prob < 0.5:
+      continue
+
+    x, y = lead.x[0], lead.y[0]
+    x_std = lead.xStd[0]
+    x -= RADAR_TO_CAMERA
+
+    _, py_top = to_topdown_pt(x + x_std, y)
+    px, py_bottom = to_topdown_pt(x - x_std, y)
+    top_down[1][int(round(px - 4)) : int(round(px + 4)), py_top:py_bottom] = find_color(top_down[0], YELLOW)
+
+  for path, prob, _ in zip(m.laneLines, m.laneLineProbs, m.laneLineStds, strict=True):
+    color = (0, int(255 * prob), 0)
+    draw_path(path, color, img, calibration, top_down, YELLOW)
+
+  for edge, std in zip(m.roadEdges, m.roadEdgeStds, strict=True):
+    prob = max(1 - std, 0)
+    color = (int(255 * prob), 0, 0)
+    draw_path(edge, color, img, calibration, top_down, RED)
+
+  color = (255, 0, 0)
+  draw_path(m.position, color, img, calibration, top_down, RED, 1.22)
+
+
+def plot_lead(rs, top_down):
+  for lead in [rs.leadOne, rs.leadTwo]:
+    if not lead.status:
+      continue
+
+    x = lead.dRel
+    px_left, py = to_topdown_pt(x, -10)
+    px_right, _ = to_topdown_pt(x, 10)
+    top_down[1][px_left:px_right, py] = find_color(top_down[0], RED)
+
+
+def maybe_update_radar_points(lt, lid_overlay):
+  ar_pts = []
+  if lt is not None:
+    ar_pts = {}
+    for track in lt:
+      ar_pts[track.trackId] = [track.dRel, track.yRel, track.vRel, track.aRel]
+  for pt in ar_pts.values():
+    # negative here since radar is left positive
+    px, py = to_topdown_pt(pt[0], -pt[1])
+    if px != -1:
+      lid_overlay[px - 4 : px + 4, py - 4 : py + 4] = 0
+      lid_overlay[px - 2 : px + 2, py - 2 : py + 2] = 255
+
+
+def get_blank_lid_overlay(UP):
+  lid_overlay = np.zeros((UP.lidar_x, UP.lidar_y), 'uint8')
+  # Draw the car.
+  lid_overlay[int(round(UP.lidar_car_x - UP.car_hwidth)) : int(round(UP.lidar_car_x + UP.car_hwidth)), int(round(UP.lidar_car_y - UP.car_front))] = UP.car_color
+  lid_overlay[int(round(UP.lidar_car_x - UP.car_hwidth)) : int(round(UP.lidar_car_x + UP.car_hwidth)), int(round(UP.lidar_car_y + UP.car_back))] = UP.car_color
+  lid_overlay[int(round(UP.lidar_car_x - UP.car_hwidth)), int(round(UP.lidar_car_y - UP.car_front)) : int(round(UP.lidar_car_y + UP.car_back))] = UP.car_color
+  lid_overlay[int(round(UP.lidar_car_x + UP.car_hwidth)), int(round(UP.lidar_car_y - UP.car_front)) : int(round(UP.lidar_car_y + UP.car_back))] = UP.car_color
+  return lid_overlay

tools/replay/logreader.cc

@@ -0,0 +1,169 @@
+#include "tools/replay/logreader.h"
+
+#include <algorithm>
+#include <chrono>
+#include <utility>
+#include "tools/replay/filereader.h"
+#include "tools/replay/py_downloader.h"
+#include "tools/replay/util.h"
+#include "common/util.h"
+
+bool LogReader::load(const std::string &url, std::atomic<bool> *abort, bool local_cache,
+                     const ProgressCallback &progress) {
+  using Clock = std::chrono::steady_clock;
+  compressed_size_ = 0;
+  decompressed_size_ = 0;
+  download_seconds_ = 0.0;
+  decompress_seconds_ = 0.0;
+  parse_seconds_ = 0.0;
+
+  if (progress) {
+    installDownloadProgressHandler([progress](uint64_t cur, uint64_t total, bool success) {
+      if (success) {
+        progress(ProgressStage::Downloading, cur, total);
+      }
+    });
+  }
+  const auto download_start = Clock::now();
+  std::string data = FileReader(local_cache).read(url, abort);
+  const auto download_end = Clock::now();
+  if (progress) {
+    installDownloadProgressHandler(nullptr);
+  }
+  compressed_size_ = data.size();
+  download_seconds_ = std::chrono::duration<double>(download_end - download_start).count();
+  if (!data.empty()) {
+    const auto decompress_start = Clock::now();
+    if (url.find(".bz2") != std::string::npos || util::starts_with(data, "BZh9")) {
+      data = decompressBZ2(data, abort);
+    } else if (url.find(".zst") != std::string::npos || util::starts_with(data, "\x28\xB5\x2F\xFD")) {
+      data = decompressZST(data, abort);
+    }
+    const auto decompress_end = Clock::now();
+    decompress_seconds_ = std::chrono::duration<double>(decompress_end - decompress_start).count();
+  }
+  decompressed_size_ = data.size();
+
+  bool success = !data.empty() && load(data.data(), data.size(), abort, progress);
+  if (filters_.empty())
+    raw_ = std::move(data);
+  return success;
+}
+
+bool LogReader::load(const char *data, size_t size, std::atomic<bool> *abort,
+                     const ProgressCallback &progress) {
+  using Clock = std::chrono::steady_clock;
+  const auto parse_start = Clock::now();
+  try {
+    events.reserve(65000);
+    kj::ArrayPtr<const capnp::word> words((const capnp::word *)data, size / sizeof(capnp::word));
+    const uint64_t total_bytes = size;
+    const uint64_t report_step = std::max<uint64_t>(1, total_bytes / 200);
+    uint64_t last_reported = 0;
+    if (progress) {
+      progress(ProgressStage::Parsing, 0, total_bytes);
+    }
+    while (words.size() > 0 && !(abort && *abort)) {
+      capnp::FlatArrayMessageReader reader(words);
+      auto event = reader.getRoot<cereal::Event>();
+      auto which = event.which();
+      auto event_data = kj::arrayPtr(words.begin(), reader.getEnd());
+      words = kj::arrayPtr(reader.getEnd(), words.end());
+      if (which == cereal::Event::Which::SELFDRIVE_STATE) {
+        requires_migration = false;
+      }
+
+      if (!filters_.empty()) {
+        if (which >= filters_.size() || !filters_[which])
+          continue;
+        auto buf = buffer_.allocate(event_data.size() * sizeof(capnp::word));
+        memcpy(buf, event_data.begin(), event_data.size() * sizeof(capnp::word));
+        event_data = kj::arrayPtr((const capnp::word *)buf, event_data.size());
+      }
+
+      uint64_t mono_time = event.getLogMonoTime();
+      const Event &evt = events.emplace_back(which, mono_time, event_data);
+      // Add encodeIdx packet again as a frame packet for the video stream
+      if (evt.which == cereal::Event::ROAD_ENCODE_IDX ||
+          evt.which == cereal::Event::DRIVER_ENCODE_IDX ||
+          evt.which == cereal::Event::WIDE_ROAD_ENCODE_IDX) {
+        auto idx = capnp::AnyStruct::Reader(event).getPointerSection()[0].getAs<cereal::EncodeIndex>();
+        if (idx.getType() == cereal::EncodeIndex::Type::FULL_H_E_V_C) {
+          uint64_t sof = idx.getTimestampSof();
+          events.emplace_back(which, sof ? sof : mono_time, event_data, idx.getSegmentNum());
+        }
+      }
+
+      if (progress) {
+        const uint64_t current_bytes =
+          total_bytes - static_cast<uint64_t>(words.size() * sizeof(capnp::word));
+        if (current_bytes >= total_bytes || current_bytes - last_reported >= report_step) {
+          progress(ProgressStage::Parsing, current_bytes, total_bytes);
+          last_reported = current_bytes;
+        }
+      }
+    }
+  } catch (const kj::Exception &e) {
+    rWarning("Failed to parse log : %s.\nRetrieved %zu events from corrupt log", e.getDescription().cStr(), events.size());
+  }
+
+  if (progress) {
+    progress(ProgressStage::Parsing, size, size);
+  }
+
+  if (requires_migration) {
+    migrateOldEvents();
+  }
+
+  parse_seconds_ = std::chrono::duration<double>(Clock::now() - parse_start).count();
+
+  if (!events.empty() && !(abort && *abort)) {
+    events.shrink_to_fit();
+    std::sort(events.begin(), events.end());
+    return true;
+  }
+  return false;
+}
+
+void LogReader::migrateOldEvents() {
+  size_t events_size = events.size();
+  for (int i = 0; i < events_size; ++i) {
+    // Check if the event is of the old CONTROLS_STATE type
+    auto &event = events[i];
+    if (event.which == cereal::Event::CONTROLS_STATE) {
+      // Read the old event data
+      capnp::FlatArrayMessageReader reader(event.data);
+      auto old_evt = reader.getRoot<cereal::Event>();
+      auto old_state = old_evt.getControlsState();
+
+      // Migrate relevant fields from old CONTROLS_STATE to new SelfdriveState
+      MessageBuilder msg;
+      auto new_evt = msg.initEvent(old_evt.getValid());
+      new_evt.setLogMonoTime(old_evt.getLogMonoTime());
+      auto new_state = new_evt.initSelfdriveState();
+
+      auto old_dep = old_state.getDeprecated();
+      new_state.setActive(old_dep.getActive());
+      new_state.setAlertSize(old_dep.getAlertSize());
+      new_state.setAlertSound(old_dep.getAlertSound2());
+      new_state.setAlertStatus(old_dep.getAlertStatus());
+      new_state.setAlertText1(old_dep.getAlertText1());
+      new_state.setAlertText2(old_dep.getAlertText2());
+      new_state.setAlertType(old_dep.getAlertType());
+      new_state.setEnabled(old_dep.getEnabled());
+      new_state.setEngageable(old_dep.getEngageable());
+      new_state.setExperimentalMode(old_dep.getExperimentalMode());
+      new_state.setPersonality(old_dep.getPersonality());
+      new_state.setState(old_dep.getState());
+
+      // Serialize the new event to the buffer
+      auto buf_size = msg.getSerializedSize();
+      auto buf = buffer_.allocate(buf_size);
+      msg.serializeToBuffer(reinterpret_cast<unsigned char *>(buf), buf_size);
+
+      // Store the migrated event in the events list
+      auto event_data = kj::arrayPtr(reinterpret_cast<const capnp::word *>(buf), buf_size);
+      events.emplace_back(new_evt.which(), new_evt.getLogMonoTime(), event_data);
+    }
+  }
+}

tools/replay/logreader.h

@@ -0,0 +1,63 @@
+#pragma once
+
+#include <cstdint>
+#include <functional>
+#include <string>
+#include <vector>
+
+#include "cereal/gen/cpp/log.capnp.h"
+#include "tools/replay/util.h"
+
+const CameraType ALL_CAMERAS[] = {RoadCam, DriverCam, WideRoadCam};
+const int MAX_CAMERAS = std::size(ALL_CAMERAS);
+
+class Event {
+public:
+  Event(cereal::Event::Which which, uint64_t mono_time, const kj::ArrayPtr<const capnp::word> &data, int eidx_segnum = -1)
+    : which(which), mono_time(mono_time), data(data), eidx_segnum(eidx_segnum) {}
+
+  bool operator<(const Event &other) const {
+    return mono_time < other.mono_time || (mono_time == other.mono_time && which < other.which);
+  }
+
+  uint64_t mono_time;
+  cereal::Event::Which which;
+  kj::ArrayPtr<const capnp::word> data;
+  int32_t eidx_segnum;
+};
+
+class LogReader {
+public:
+  enum class ProgressStage {
+    Downloading,
+    Parsing,
+  };
+
+  using ProgressCallback = std::function<void(ProgressStage stage, uint64_t current, uint64_t total)>;
+
+  LogReader(const std::vector<bool> &filters = {}) { filters_ = filters; }
+  bool load(const std::string &url, std::atomic<bool> *abort = nullptr,
+            bool local_cache = false, const ProgressCallback &progress = {});
+  bool load(const char *data, size_t size, std::atomic<bool> *abort = nullptr,
+            const ProgressCallback &progress = {});
+  std::vector<Event> events;
+
+  uint64_t compressed_size() const { return compressed_size_; }
+  uint64_t decompressed_size() const { return decompressed_size_; }
+  double download_seconds() const { return download_seconds_; }
+  double decompress_seconds() const { return decompress_seconds_; }
+  double parse_seconds() const { return parse_seconds_; }
+
+private:
+  void migrateOldEvents();
+
+  std::string raw_;
+  bool requires_migration = true;
+  std::vector<bool> filters_;
+  MonotonicBuffer buffer_{1024 * 1024};
+  uint64_t compressed_size_ = 0;
+  uint64_t decompressed_size_ = 0;
+  double download_seconds_ = 0.0;
+  double decompress_seconds_ = 0.0;
+  double parse_seconds_ = 0.0;
+};

tools/replay/main.cc

@@ -0,0 +1,187 @@
+#include <getopt.h>
+
+#include <cstdlib>
+#include <iomanip>
+#include <iostream>
+#include <map>
+#include <string>
+#include <vector>
+
+#include "common/prefix.h"
+#include "common/timing.h"
+#include "tools/replay/consoleui.h"
+#include "tools/replay/replay.h"
+#include "tools/replay/util.h"
+
+const std::string helpText =
+R"(Usage: replay [options] [route]
+Options:
+  -a, --allow        Whitelist of services to send (comma-separated)
+  -b, --block        Blacklist of services to send (comma-separated)
+  -c, --cache        Cache <n> segments in memory. Default is 5
+  -s, --start        Start from <seconds>
+  -x, --playback     Playback <speed>
+      --demo         Use a demo route instead of providing your own
+      --auto         Auto load the route from the best available source (no video):
+                     internal, openpilotci, comma_api, car_segments, testing_closet
+  -d, --data_dir     Local directory with routes
+  -p, --prefix       Set OPENPILOT_PREFIX
+      --dcam         Load driver camera
+      --ecam         Load wide road camera
+      --no-loop      Stop at the end of the route
+      --no-cache     Turn off local cache
+      --qcam         Load qcamera
+      --no-hw-decoder Disable HW video decoding
+      --no-vipc      Do not output video
+      --all          Output all messages including bookmarkButton, uiDebug, userBookmark
+      --benchmark    Run in benchmark mode (process all events then exit with stats)
+  -h, --help         Show this help message
+)";
+
+struct ReplayConfig {
+  std::string route;
+  std::vector<std::string> allow;
+  std::vector<std::string> block;
+  std::string data_dir;
+  std::string prefix;
+  uint32_t flags = REPLAY_FLAG_NONE;
+  bool auto_source = false;
+  int start_seconds = 0;
+  int cache_segments = -1;
+  float playback_speed = -1;
+};
+
+bool parseArgs(int argc, char *argv[], ReplayConfig &config) {
+  const struct option cli_options[] = {
+      {"allow", required_argument, nullptr, 'a'},
+      {"block", required_argument, nullptr, 'b'},
+      {"cache", required_argument, nullptr, 'c'},
+      {"start", required_argument, nullptr, 's'},
+      {"playback", required_argument, nullptr, 'x'},
+      {"demo", no_argument, nullptr, 0},
+      {"auto", no_argument, nullptr, 0},
+      {"data_dir", required_argument, nullptr, 'd'},
+      {"prefix", required_argument, nullptr, 'p'},
+      {"dcam", no_argument, nullptr, 0},
+      {"ecam", no_argument, nullptr, 0},
+      {"no-loop", no_argument, nullptr, 0},
+      {"no-cache", no_argument, nullptr, 0},
+      {"qcam", no_argument, nullptr, 0},
+      {"no-hw-decoder", no_argument, nullptr, 0},
+      {"no-vipc", no_argument, nullptr, 0},
+      {"all", no_argument, nullptr, 0},
+      {"benchmark", no_argument, nullptr, 0},
+      {"help", no_argument, nullptr, 'h'},
+      {nullptr, 0, nullptr, 0},  // Terminating entry
+  };
+
+  const std::map<std::string, REPLAY_FLAGS> flag_map = {
+      {"dcam", REPLAY_FLAG_DCAM},
+      {"ecam", REPLAY_FLAG_ECAM},
+      {"no-loop", REPLAY_FLAG_NO_LOOP},
+      {"no-cache", REPLAY_FLAG_NO_FILE_CACHE},
+      {"qcam", REPLAY_FLAG_QCAMERA},
+      {"no-hw-decoder", REPLAY_FLAG_NO_HW_DECODER},
+      {"no-vipc", REPLAY_FLAG_NO_VIPC},
+      {"all", REPLAY_FLAG_ALL_SERVICES},
+      {"benchmark", REPLAY_FLAG_BENCHMARK},
+  };
+
+  if (argc == 1) {
+    std::cout << helpText;
+    return false;
+  }
+
+  int opt, option_index = 0;
+  while ((opt = getopt_long(argc, argv, "a:b:c:s:x:d:p:h", cli_options, &option_index)) != -1) {
+    switch (opt) {
+      case 'a': config.allow = split(optarg, ','); break;
+      case 'b': config.block = split(optarg, ','); break;
+      case 'c': config.cache_segments = std::atoi(optarg); break;
+      case 's': config.start_seconds = std::atoi(optarg); break;
+      case 'x': config.playback_speed = std::atof(optarg); break;
+      case 'd': config.data_dir = optarg; break;
+      case 'p': config.prefix = optarg; break;
+      case 0: {
+        std::string name = cli_options[option_index].name;
+        if (name == "demo") config.route = DEMO_ROUTE;
+        else if (name == "auto") config.auto_source = true;
+        else config.flags |= flag_map.at(name);
+        break;
+      }
+      case 'h': std::cout << helpText; return false;
+      default: return false;
+    }
+  }
+
+  // Check for a route name (first positional argument)
+  if (config.route.empty() && optind < argc) {
+    config.route = argv[optind];
+  }
+
+  if (config.route.empty()) {
+    std::cerr << "No route provided. Use --help for usage information.\n";
+    return false;
+  }
+
+  return true;
+}
+
+int main(int argc, char *argv[]) {
+#ifdef __APPLE__
+  // With all sockets opened, we might hit the default limit of 256 on macOS
+  util::set_file_descriptor_limit(1024);
+#endif
+
+  // The vendored ncurses static library has a wrong compiled-in terminfo path.
+  // Point it at the system terminfo database if not already set.
+  setenv("TERMINFO_DIRS", "/usr/share/terminfo:/lib/terminfo:/usr/lib/terminfo", 0);
+
+  ReplayConfig config;
+
+  if (!parseArgs(argc, argv, config)) {
+    return 1;
+  }
+
+  std::unique_ptr<OpenpilotPrefix> op_prefix;
+  if (!config.prefix.empty()) {
+    op_prefix = std::make_unique<OpenpilotPrefix>(config.prefix);
+  }
+
+  Replay replay(config.route, config.allow, config.block, nullptr, config.flags, config.data_dir, config.auto_source);
+  if (config.cache_segments > 0) {
+    replay.setSegmentCacheLimit(config.cache_segments);
+  }
+  if (config.playback_speed > 0) {
+    replay.setSpeed(std::clamp(config.playback_speed, ConsoleUI::speed_array.front(), ConsoleUI::speed_array.back()));
+  }
+  if (!replay.load()) {
+    return 1;
+  }
+
+  if (config.flags & REPLAY_FLAG_BENCHMARK) {
+    replay.start(config.start_seconds);
+    replay.waitForFinished();
+
+    const auto &stats = replay.getBenchmarkStats();
+    uint64_t process_start = stats.process_start_ts;
+
+    std::cout << "\n===== REPLAY BENCHMARK RESULTS =====\n";
+    std::cout << "Route: " << replay.route().name() << "\n\n";
+
+    std::cout << "TIMELINE:\n";
+    std::cout << "  t=0 ms        process start\n";
+    for (const auto &[ts, event] : stats.timeline) {
+      double ms = (ts - process_start) / 1e6;
+      std::cout << "  t=" << std::fixed << std::setprecision(0) << ms << " ms"
+                << std::string(std::max(1, 8 - static_cast<int>(std::to_string(static_cast<int>(ms)).length())), ' ')
+                << event << "\n";
+    }
+
+    return 0;
+  }
+
+  ConsoleUI console_ui(&replay);
+  replay.start(config.start_seconds);
+  return console_ui.exec();
+}

tools/replay/py_downloader.cc

@@ -0,0 +1,180 @@
+#include "tools/replay/py_downloader.h"
+
+#include <csignal>
+#include <fcntl.h>
+#include <mutex>
+#include <sys/wait.h>
+#include <unistd.h>
+#include <vector>
+
+#include "tools/replay/util.h"
+
+namespace {
+
+static std::mutex handler_mutex;
+static DownloadProgressHandler progress_handler = nullptr;
+
+// Run a Python command and capture stdout. Stderr is left attached to the parent.
+// Returns stdout content. If abort is signaled, kills the child process.
+std::string runPython(const std::vector<std::string> &args, std::atomic<bool> *abort = nullptr) {
+  // Build argv for execvp
+  std::vector<const char *> argv;
+  argv.push_back("python3");
+  argv.push_back("-m");
+  argv.push_back("openpilot.tools.lib.file_downloader");
+  for (const auto &a : args) {
+    argv.push_back(a.c_str());
+  }
+  argv.push_back(nullptr);
+
+  int stdout_pipe[2];
+  if (pipe(stdout_pipe) != 0) {
+    rWarning("py_downloader: pipe() failed");
+    return {};
+  }
+
+  pid_t pid = fork();
+  if (pid < 0) {
+    rWarning("py_downloader: fork() failed");
+    close(stdout_pipe[0]); close(stdout_pipe[1]);
+    return {};
+  }
+
+  if (pid == 0) {
+    // Child process — detach from controlling terminal so Python
+    // cannot corrupt terminal settings needed by ncurses in the parent.
+    setsid();
+    int devnull = open("/dev/null", O_RDONLY);
+    if (devnull >= 0) {
+      dup2(devnull, STDIN_FILENO);
+      if (devnull > STDERR_FILENO) close(devnull);
+    }
+
+    // Clear OPENPILOT_PREFIX so the Python process uses default paths
+    // (e.g. ~/.comma/auth.json). The prefix is only for IPC in the parent.
+    unsetenv("OPENPILOT_PREFIX");
+
+    close(stdout_pipe[0]);
+    dup2(stdout_pipe[1], STDOUT_FILENO);
+    close(stdout_pipe[1]);
+
+    execvp("python3", const_cast<char *const *>(argv.data()));
+    _exit(127);
+  }
+
+  // Parent process
+  close(stdout_pipe[1]);
+
+  std::string stdout_data;
+  char buf[4096];
+
+  // Use select() so abort can interrupt while waiting for Python output.
+  fd_set rfds;
+  bool stdout_open = true;
+
+  while (stdout_open) {
+    if (abort && *abort) {
+      kill(pid, SIGTERM);
+      break;
+    }
+
+    FD_ZERO(&rfds);
+    FD_SET(stdout_pipe[0], &rfds);
+
+    struct timeval tv = {0, 100000};  // 100ms timeout
+    int ret = select(stdout_pipe[0] + 1, &rfds, nullptr, nullptr, &tv);
+    if (ret < 0) break;
+
+    if (FD_ISSET(stdout_pipe[0], &rfds)) {
+      ssize_t n = read(stdout_pipe[0], buf, sizeof(buf));
+      if (n <= 0) {
+        stdout_open = false;
+      } else {
+        stdout_data.append(buf, n);
+      }
+    }
+  }
+
+  // Drain remaining pipe data to prevent child from blocking on write
+  while (true) {
+    ssize_t n = read(stdout_pipe[0], buf, sizeof(buf));
+    if (n <= 0) break;
+    stdout_data.append(buf, n);
+  }
+  close(stdout_pipe[0]);
+
+  int status;
+  waitpid(pid, &status, 0);
+
+  const bool aborted = abort && *abort;
+  const bool expected_sigterm = aborted && WIFSIGNALED(status) && WTERMSIG(status) == SIGTERM;
+  bool failed = aborted ||
+                (WIFEXITED(status) && WEXITSTATUS(status) != 0) ||
+                WIFSIGNALED(status);
+  if (failed) {
+    if (expected_sigterm) {
+      // Route/camera teardown cancels outstanding downloader subprocesses.
+      // Keep that expected shutdown path quiet.
+    } else if (WIFEXITED(status) && WEXITSTATUS(status) != 0) {
+      rWarning("py_downloader: process exited with code %d", WEXITSTATUS(status));
+    } else if (WIFSIGNALED(status)) {
+      rWarning("py_downloader: process killed by signal %d", WTERMSIG(status));
+    }
+    std::lock_guard<std::mutex> lk(handler_mutex);
+    if (progress_handler) {
+      progress_handler(0, 0, false);
+    }
+    return {};
+  }
+
+  // Trim trailing newline
+  while (!stdout_data.empty() && (stdout_data.back() == '\n' || stdout_data.back() == '\r')) {
+    stdout_data.pop_back();
+  }
+
+  return stdout_data;
+}
+
+}  // namespace
+
+void installDownloadProgressHandler(DownloadProgressHandler handler) {
+  std::lock_guard<std::mutex> lk(handler_mutex);
+  progress_handler = handler;
+}
+
+namespace PyDownloader {
+
+std::string download(const std::string &url, bool use_cache, std::atomic<bool> *abort) {
+  std::vector<std::string> args = {"download", url};
+  if (!use_cache) {
+    args.push_back("--no-cache");
+  }
+  return runPython(args, abort);
+}
+
+std::string getRouteFiles(const std::string &route) {
+  return runPython({"route-files", route});
+}
+
+std::string getDevices() {
+  return runPython({"devices"});
+}
+
+std::string getDeviceRoutes(const std::string &dongle_id, int64_t start_ms, int64_t end_ms, bool preserved) {
+  std::vector<std::string> args = {"device-routes", dongle_id};
+  if (preserved) {
+    args.push_back("--preserved");
+  } else {
+    if (start_ms > 0) {
+      args.push_back("--start");
+      args.push_back(std::to_string(start_ms));
+    }
+    if (end_ms > 0) {
+      args.push_back("--end");
+      args.push_back(std::to_string(end_ms));
+    }
+  }
+  return runPython(args);
+}
+
+}  // namespace PyDownloader

tools/replay/py_downloader.h

@@ -0,0 +1,24 @@
+#pragma once
+
+#include <atomic>
+#include <functional>
+#include <string>
+
+typedef std::function<void(uint64_t cur, uint64_t total, bool success)> DownloadProgressHandler;
+void installDownloadProgressHandler(DownloadProgressHandler handler);
+
+namespace PyDownloader {
+
+// Downloads url to local cache, returns local file path. Reports progress via installDownloadProgressHandler.
+std::string download(const std::string &url, bool use_cache = true, std::atomic<bool> *abort = nullptr);
+
+// Returns JSON string of route files (same format as /v1/route/.../files API)
+std::string getRouteFiles(const std::string &route);
+
+// Returns JSON string of user's devices
+std::string getDevices();
+
+// Returns JSON string of device routes
+std::string getDeviceRoutes(const std::string &dongle_id, int64_t start_ms = 0, int64_t end_ms = 0, bool preserved = false);
+
+}  // namespace PyDownloader

tools/replay/qcom_decoder.cc

@@ -0,0 +1,346 @@
+#include "qcom_decoder.h"
+
+#include <assert.h>
+#include <linux/v4l2-controls.h>
+#include <linux/videodev2.h>
+
+
+#include "common/swaglog.h"
+#include "common/util.h"
+
+// echo "0xFFFF" > /sys/kernel/debug/msm_vidc/debug_level
+
+static void copyBuffer(VisionBuf *src_buf, VisionBuf *dst_buf) {
+  // Copy Y plane
+  memcpy(dst_buf->y, src_buf->y, src_buf->height * src_buf->stride);
+  // Copy UV plane
+  memcpy(dst_buf->uv, src_buf->uv, src_buf->height / 2 * src_buf->stride);
+}
+
+static void request_buffers(int fd, v4l2_buf_type buf_type, unsigned int count) {
+  struct v4l2_requestbuffers reqbuf = {
+    .count = count,
+    .type = buf_type,
+    .memory = V4L2_MEMORY_USERPTR
+  };
+  util::safe_ioctl(fd, VIDIOC_REQBUFS, &reqbuf, "VIDIOC_REQBUFS failed");
+}
+
+MsmVidc::~MsmVidc() {
+  if (fd > 0) {
+    close(fd);
+  }
+}
+
+bool MsmVidc::init(const char* dev, size_t width, size_t height, uint64_t codec) {
+  LOG("Initializing msm_vidc device %s", dev);
+  this->w = width;
+  this->h = height;
+  this->fd = open(dev, O_RDWR, 0);
+  if (fd < 0) {
+    LOGE("failed to open video device %s", dev);
+    return false;
+  }
+  subscribeEvents();
+  v4l2_buf_type out_type = V4L2_BUF_TYPE_VIDEO_OUTPUT_MPLANE;
+  setPlaneFormat(out_type, V4L2_PIX_FMT_HEVC); // Also allocates the output buffer
+  setFPS(FPS);
+  request_buffers(fd, out_type, OUTPUT_BUFFER_COUNT);
+  util::safe_ioctl(fd, VIDIOC_STREAMON, &out_type, "VIDIOC_STREAMON OUTPUT failed");
+  restartCapture();
+  setupPolling();
+
+  this->initialized = true;
+  return true;
+}
+
+VisionBuf* MsmVidc::decodeFrame(AVPacket *pkt, VisionBuf *buf) {
+  assert(initialized && (pkt != nullptr) && (buf != nullptr));
+
+  this->frame_ready = false;
+  this->current_output_buf = buf;
+  bool sent_packet = false;
+
+  while (!this->frame_ready) {
+    if (!sent_packet) {
+      int buf_index = getBufferUnlocked();
+      if (buf_index >= 0) {
+        assert(buf_index < out_buf_cnt);
+        sendPacket(buf_index, pkt);
+        sent_packet = true;
+      }
+    }
+
+    if (poll(pfd, nfds, -1) < 0) {
+      LOGE("poll() error: %d", errno);
+      return nullptr;
+    }
+
+    if (VisionBuf* result = processEvents()) {
+      return result;
+    }
+  }
+
+  return buf;
+}
+
+VisionBuf* MsmVidc::processEvents() {
+  for (int idx = 0; idx < nfds; idx++) {
+    short revents = pfd[idx].revents;
+    if (!revents) continue;
+
+    if (idx == ev[EV_VIDEO]) {
+      if (revents & (POLLIN | POLLRDNORM)) {
+        VisionBuf *result = handleCapture();
+        if (result == this->current_output_buf) {
+          this->frame_ready = true;
+        }
+      }
+      if (revents & (POLLOUT | POLLWRNORM)) {
+        handleOutput();
+      }
+      if (revents & POLLPRI) {
+        handleEvent();
+      }
+    } else {
+      LOGE("Unexpected event on fd %d", pfd[idx].fd);
+    }
+  }
+  return nullptr;
+}
+
+VisionBuf* MsmVidc::handleCapture() {
+  struct v4l2_buffer buf = {0};
+  struct v4l2_plane planes[1] = {0};
+  buf.type          = V4L2_BUF_TYPE_VIDEO_CAPTURE_MPLANE;
+  buf.memory        = V4L2_MEMORY_USERPTR;
+  buf.m.planes      = planes;
+  buf.length        = 1;
+  util::safe_ioctl(this->fd, VIDIOC_DQBUF, &buf, "VIDIOC_DQBUF CAPTURE failed");
+
+  if (this->reconfigure_pending || buf.m.planes[0].bytesused == 0) {
+    return nullptr;
+  }
+
+  copyBuffer(&cap_bufs[buf.index], this->current_output_buf);
+  queueCaptureBuffer(buf.index);
+  return this->current_output_buf;
+}
+
+bool MsmVidc::subscribeEvents() {
+  for (uint32_t event : subscriptions) {
+    struct v4l2_event_subscription sub = { .type = event};
+    util::safe_ioctl(fd, VIDIOC_SUBSCRIBE_EVENT, &sub, "VIDIOC_SUBSCRIBE_EVENT failed");
+  }
+  return true;
+}
+
+bool MsmVidc::setPlaneFormat(enum v4l2_buf_type type, uint32_t fourcc) {
+  struct v4l2_format fmt = {.type = type};
+  struct v4l2_pix_format_mplane *pix = &fmt.fmt.pix_mp;
+  *pix = {
+    .width = (__u32)this->w,
+    .height = (__u32)this->h,
+    .pixelformat = fourcc
+  };
+  util::safe_ioctl(fd, VIDIOC_S_FMT, &fmt, "VIDIOC_S_FMT failed");
+  if (type == V4L2_BUF_TYPE_VIDEO_OUTPUT_MPLANE) {
+    this->out_buf_size = pix->plane_fmt[0].sizeimage;
+    int ion_size = this->out_buf_size * OUTPUT_BUFFER_COUNT; // Output (input) buffers are ION buffer.
+    this->out_buf.allocate(ion_size); // mmap rw
+    for (int i = 0; i < OUTPUT_BUFFER_COUNT; i++) {
+      this->out_buf_off[i] = i * this->out_buf_size;
+      this->out_buf_addr[i] = (char *)this->out_buf.addr + this->out_buf_off[i];
+      this->out_buf_flag[i] = false;
+    }
+    LOGD("Set output buffer size to %d, count %d, addr %p", this->out_buf_size, OUTPUT_BUFFER_COUNT, this->out_buf.addr);
+  } else if (type == V4L2_BUF_TYPE_VIDEO_CAPTURE_MPLANE) {
+    request_buffers(this->fd, type, CAPTURE_BUFFER_COUNT);
+    util::safe_ioctl(fd, VIDIOC_G_FMT, &fmt, "VIDIOC_G_FMT failed");
+    const __u32 y_size    = pix->plane_fmt[0].sizeimage;
+    const __u32 y_stride  = pix->plane_fmt[0].bytesperline;
+    for (int i = 0; i < CAPTURE_BUFFER_COUNT; i++) {
+      size_t uv_offset = (size_t)y_stride * pix->height;
+      size_t required = uv_offset + (y_stride * pix->height / 2); // enough for Y + UV. For linear NV12, UV plane starts at y_stride * height.
+      size_t alloc_size = std::max<size_t>(y_size, required);
+      this->cap_bufs[i].allocate(alloc_size);
+      this->cap_bufs[i].init_yuv(pix->width, pix->height, y_stride, uv_offset);
+    }
+    LOGD("Set capture buffer size to %d, count %d, addr %p, extradata size %d",
+      pix->plane_fmt[0].sizeimage, CAPTURE_BUFFER_COUNT, this->cap_bufs[0].addr, pix->plane_fmt[1].sizeimage);
+  }
+  return true;
+}
+
+bool MsmVidc::setFPS(uint32_t fps) {
+  struct v4l2_streamparm streamparam = {
+    .type = V4L2_BUF_TYPE_VIDEO_OUTPUT_MPLANE,
+  };
+  streamparam.parm.output.timeperframe = {1, fps};
+  util::safe_ioctl(fd, VIDIOC_S_PARM, &streamparam, "VIDIOC_S_PARM failed");
+  return true;
+}
+
+bool MsmVidc::restartCapture() {
+  // stop if already initialized
+  enum v4l2_buf_type type = V4L2_BUF_TYPE_VIDEO_CAPTURE_MPLANE;
+  if (this->initialized) {
+    LOGD("Restarting capture, flushing buffers...");
+    util::safe_ioctl(this->fd, VIDIOC_STREAMOFF, &type, "VIDIOC_STREAMOFF CAPTURE failed");
+    struct v4l2_requestbuffers reqbuf = {.type = type, .memory = V4L2_MEMORY_USERPTR};
+    util::safe_ioctl(this->fd, VIDIOC_REQBUFS, &reqbuf, "VIDIOC_REQBUFS failed");
+    for (size_t i = 0; i < CAPTURE_BUFFER_COUNT; ++i) {
+      this->cap_bufs[i].free();
+      this->cap_buf_flag[i] = false; // mark as not queued
+      cap_bufs[i].~VisionBuf();
+      new (&cap_bufs[i]) VisionBuf();
+    }
+  }
+  // setup, start and queue capture buffers
+  setDBP();
+  setPlaneFormat(type, V4L2_PIX_FMT_NV12);
+  util::safe_ioctl(this->fd, VIDIOC_STREAMON, &type, "VIDIOC_STREAMON CAPTURE failed");
+  for (size_t i = 0; i < CAPTURE_BUFFER_COUNT; ++i) {
+    queueCaptureBuffer(i);
+  }
+
+  return true;
+}
+
+bool MsmVidc::queueCaptureBuffer(int i) {
+  struct v4l2_buffer buf = {0};
+  struct v4l2_plane planes[1] = {0};
+
+  buf.type = V4L2_BUF_TYPE_VIDEO_CAPTURE_MPLANE;
+  buf.memory = V4L2_MEMORY_USERPTR;
+  buf.index = i;
+  buf.m.planes = planes;
+  buf.length = 1;
+  // decoded frame plane
+  planes[0].m.userptr     = (unsigned long)this->cap_bufs[i].addr; // no security
+  planes[0].length        = this->cap_bufs[i].len;
+  planes[0].reserved[0]   = this->cap_bufs[i].fd; // ION fd
+  planes[0].reserved[1]   = 0;
+  planes[0].bytesused     = this->cap_bufs[i].len;
+  planes[0].data_offset   = 0;
+  util::safe_ioctl(this->fd, VIDIOC_QBUF, &buf, "VIDIOC_QBUF failed");
+  this->cap_buf_flag[i] = true; // mark as queued
+  return true;
+}
+
+bool MsmVidc::queueOutputBuffer(int i, size_t size) {
+  struct v4l2_buffer buf = {0};
+  struct v4l2_plane planes[1] = {0};
+
+  buf.type                = V4L2_BUF_TYPE_VIDEO_OUTPUT_MPLANE;
+  buf.memory              = V4L2_MEMORY_USERPTR;
+  buf.index               = i;
+  buf.m.planes            = planes;
+  buf.length              = 1;
+  // decoded frame plane
+  planes[0].m.userptr     = (unsigned long)this->out_buf_off[i]; // check this
+  planes[0].length        = this->out_buf_size;
+  planes[0].reserved[0]   = this->out_buf.fd; // ION fd
+  planes[0].reserved[1]   = 0;
+  planes[0].bytesused     = size;
+  planes[0].data_offset   = 0;
+  assert((this->out_buf_off[i] & 0xfff) == 0);          // must be 4 KiB aligned
+  assert(this->out_buf_size % 4096 == 0);               // ditto for size
+
+  util::safe_ioctl(this->fd, VIDIOC_QBUF, &buf, "VIDIOC_QBUF failed");
+  this->out_buf_flag[i] = true; // mark as queued
+  return true;
+}
+
+bool MsmVidc::setDBP() {
+  struct v4l2_ext_control control[2] = {0};
+  struct v4l2_ext_controls controls = {0};
+  control[0].id           = V4L2_CID_MPEG_VIDC_VIDEO_STREAM_OUTPUT_MODE;
+  control[0].value        = 1; // V4L2_CID_MPEG_VIDC_VIDEO_STREAM_OUTPUT_SECONDARY
+  control[1].id           = V4L2_CID_MPEG_VIDC_VIDEO_DPB_COLOR_FORMAT;
+  control[1].value        = 0; // V4L2_MPEG_VIDC_VIDEO_DPB_COLOR_FMT_NONE
+  controls.count          = 2;
+  controls.ctrl_class     = V4L2_CTRL_CLASS_MPEG;
+  controls.controls       = control;
+  util::safe_ioctl(fd, VIDIOC_S_EXT_CTRLS, &controls, "VIDIOC_S_EXT_CTRLS failed");
+  return true;
+}
+
+bool MsmVidc::setupPolling() {
+  // Initialize poll array
+  pfd[EV_VIDEO] = {fd, POLLIN | POLLOUT | POLLWRNORM | POLLRDNORM | POLLPRI, 0};
+  ev[EV_VIDEO] = EV_VIDEO;
+  nfds = 1;
+  return true;
+}
+
+bool MsmVidc::sendPacket(int buf_index, AVPacket *pkt) {
+  assert(buf_index >= 0 && buf_index < out_buf_cnt);
+  assert(pkt != nullptr && pkt->data != nullptr && pkt->size > 0);
+  // Prepare output buffer
+  memset(this->out_buf_addr[buf_index], 0, this->out_buf_size);
+  uint8_t * data = (uint8_t *)this->out_buf_addr[buf_index];
+  memcpy(data, pkt->data, pkt->size);
+  queueOutputBuffer(buf_index, pkt->size);
+  return true;
+}
+
+int MsmVidc::getBufferUnlocked() {
+  for (int i = 0; i < this->out_buf_cnt; i++) {
+    if (!out_buf_flag[i]) {
+      return i;
+    }
+  }
+  return -1;
+}
+
+
+bool MsmVidc::handleOutput() {
+  struct v4l2_buffer buf = {0};
+  struct v4l2_plane planes[1];
+  buf.type      = V4L2_BUF_TYPE_VIDEO_OUTPUT_MPLANE;
+  buf.memory    = V4L2_MEMORY_USERPTR;
+  buf.m.planes  = planes;
+  buf.length    = 1;
+  util::safe_ioctl(this->fd, VIDIOC_DQBUF, &buf, "VIDIOC_DQBUF OUTPUT failed");
+  this->out_buf_flag[buf.index] = false; // mark as not queued
+  return true;
+}
+
+bool MsmVidc::handleEvent() {
+  // dequeue event
+  struct v4l2_event event = {0};
+  util::safe_ioctl(this->fd, VIDIOC_DQEVENT, &event, "VIDIOC_DQEVENT failed");
+  switch (event.type) {
+    case V4L2_EVENT_MSM_VIDC_PORT_SETTINGS_CHANGED_INSUFFICIENT: {
+      unsigned int *ptr     = (unsigned int *)event.u.data;
+      unsigned int height   = ptr[0];
+      unsigned int width    = ptr[1];
+      this->w               = width;
+      this->h               = height;
+      LOGD("Port Reconfig received insufficient, new size %ux%u, flushing capture bufs...", width, height); // This is normal
+      struct v4l2_decoder_cmd dec;
+      dec.flags = V4L2_QCOM_CMD_FLUSH_CAPTURE;
+      dec.cmd = V4L2_QCOM_CMD_FLUSH;
+      util::safe_ioctl(this->fd, VIDIOC_DECODER_CMD, &dec, "VIDIOC_DECODER_CMD FLUSH_CAPTURE failed");
+      this->reconfigure_pending = true;
+      LOGD("Waiting for flush done event to reconfigure capture queue");
+      break;
+    }
+
+    case V4L2_EVENT_MSM_VIDC_FLUSH_DONE: {
+      unsigned int *ptr   = (unsigned int *)event.u.data;
+      unsigned int flags  = ptr[0];
+      if (flags & V4L2_QCOM_CMD_FLUSH_CAPTURE) {
+        if (this->reconfigure_pending) {
+          this->restartCapture();
+          this->reconfigure_pending = false;
+        }
+      }
+      break;
+    }
+    default:
+      break;
+  }
+  return true;
+}

tools/replay/qcom_decoder.h

@@ -0,0 +1,88 @@
+#pragma once
+
+#include <linux/videodev2.h>
+#include <poll.h>
+
+#include "msgq/visionipc/visionbuf.h"
+
+extern "C" {
+  #include <libavcodec/avcodec.h>
+  #include <libavformat/avformat.h>
+}
+
+#define V4L2_EVENT_MSM_VIDC_START (V4L2_EVENT_PRIVATE_START + 0x00001000)
+#define V4L2_EVENT_MSM_VIDC_FLUSH_DONE (V4L2_EVENT_MSM_VIDC_START + 1)
+#define V4L2_EVENT_MSM_VIDC_PORT_SETTINGS_CHANGED_INSUFFICIENT (V4L2_EVENT_MSM_VIDC_START + 3)
+#define V4L2_CID_MPEG_MSM_VIDC_BASE 0x00992000
+#define V4L2_CID_MPEG_VIDC_VIDEO_DPB_COLOR_FORMAT (V4L2_CID_MPEG_MSM_VIDC_BASE + 44)
+#define V4L2_CID_MPEG_VIDC_VIDEO_STREAM_OUTPUT_MODE (V4L2_CID_MPEG_MSM_VIDC_BASE + 22)
+#define V4L2_QCOM_CMD_FLUSH_CAPTURE (1 << 1)
+#define V4L2_QCOM_CMD_FLUSH (4)
+
+#define VIDEO_DEVICE "/dev/video32"
+#define OUTPUT_BUFFER_COUNT 	8
+#define CAPTURE_BUFFER_COUNT 	8
+#define FPS 									20
+
+
+class MsmVidc {
+public:
+  MsmVidc() = default;
+  ~MsmVidc();
+
+  bool init(const char* dev, size_t width, size_t height, uint64_t codec);
+  VisionBuf* decodeFrame(AVPacket* pkt, VisionBuf* buf);
+
+  AVFormatContext* avctx = nullptr;
+  int fd = 0;
+
+private:
+  bool initialized = false;
+  bool reconfigure_pending = false;
+  bool frame_ready = false;
+
+  VisionBuf* current_output_buf = nullptr;
+  VisionBuf out_buf;                          // Single input buffer
+  VisionBuf cap_bufs[CAPTURE_BUFFER_COUNT];   // Capture (output) buffers
+
+  size_t w = 1928, h = 1208;
+  size_t cap_height = 0, cap_width = 0;
+
+  int cap_buf_size = 0;
+  int out_buf_size = 0;
+
+  size_t cap_plane_off[CAPTURE_BUFFER_COUNT] = {0};
+  size_t cap_plane_stride[CAPTURE_BUFFER_COUNT] = {0};
+  bool cap_buf_flag[CAPTURE_BUFFER_COUNT] = {false};
+
+  size_t out_buf_off[OUTPUT_BUFFER_COUNT] = {0};
+  void* out_buf_addr[OUTPUT_BUFFER_COUNT] = {0};
+  bool out_buf_flag[OUTPUT_BUFFER_COUNT] = {false};
+  const int out_buf_cnt = OUTPUT_BUFFER_COUNT;
+
+  const int subscriptions[2] = {
+    V4L2_EVENT_MSM_VIDC_FLUSH_DONE,
+    V4L2_EVENT_MSM_VIDC_PORT_SETTINGS_CHANGED_INSUFFICIENT
+  };
+
+  enum { EV_VIDEO, EV_COUNT };
+  struct pollfd pfd[EV_COUNT] = {0};
+  int ev[EV_COUNT] = {-1};
+  int nfds = 0;
+
+  VisionBuf* processEvents();
+  bool setupOutput();
+  bool subscribeEvents();
+  bool setPlaneFormat(v4l2_buf_type type, uint32_t fourcc);
+  bool setFPS(uint32_t fps);
+  bool restartCapture();
+  bool queueCaptureBuffer(int i);
+  bool queueOutputBuffer(int i, size_t size);
+  bool setDBP();
+  bool setupPolling();
+  bool sendPacket(int buf_index, AVPacket* pkt);
+  int getBufferUnlocked();
+  VisionBuf* handleCapture();
+  bool handleOutput();
+  bool handleEvent();
+};

tools/replay/replay.cc

@@ -0,0 +1,408 @@
+#include "tools/replay/replay.h"
+
+#include <capnp/dynamic.h>
+#include <csignal>
+#include <iomanip>
+#include <sstream>
+#include "cereal/services.h"
+#include "common/params.h"
+#include "tools/replay/util.h"
+
+static void interrupt_sleep_handler(int signal) {}
+
+// Helper function to notify events with safety checks
+template <typename Callback, typename... Args>
+void notifyEvent(Callback &callback, Args &&...args) {
+  if (callback) callback(std::forward<Args>(args)...);
+}
+
+Replay::Replay(const std::string &route, std::vector<std::string> allow, std::vector<std::string> block,
+               SubMaster *sm, uint32_t flags, const std::string &data_dir, bool auto_source)
+    : sm_(sm), flags_(flags), seg_mgr_(std::make_unique<SegmentManager>(route, flags, data_dir, auto_source)) {
+  std::signal(SIGUSR1, interrupt_sleep_handler);
+
+  if (flags_ & REPLAY_FLAG_BENCHMARK) {
+    benchmark_stats_.process_start_ts = nanos_since_boot();
+    seg_mgr_->setBenchmarkCallback([this](int seg_num, const std::string& event) {
+      benchmark_stats_.timeline.emplace_back(nanos_since_boot(),
+          "segment " + std::to_string(seg_num) + " " + event);
+    });
+  }
+
+  if (!(flags_ & REPLAY_FLAG_ALL_SERVICES)) {
+    block.insert(block.end(), {"bookmarkButton", "uiDebug", "userBookmark"});
+  }
+  setupServices(allow, block);
+  setupSegmentManager(!allow.empty() || !block.empty());
+}
+
+void Replay::setupServices(const std::vector<std::string> &allow, const std::vector<std::string> &block) {
+  auto event_schema = capnp::Schema::from<cereal::Event>().asStruct();
+  sockets_.resize(event_schema.getUnionFields().size(), nullptr);
+
+  std::vector<const char *> active_services;
+  active_services.reserve(services.size());
+
+  for (const auto &[name, _] : services) {
+    bool is_blocked = std::find(block.begin(), block.end(), name) != block.end();
+    bool is_allowed = allow.empty() || std::find(allow.begin(), allow.end(), name) != allow.end();
+    if (is_allowed && !is_blocked) {
+      uint16_t which = event_schema.getFieldByName(name).getProto().getDiscriminantValue();
+      sockets_[which] = name.c_str();
+      active_services.push_back(name.c_str());
+    }
+  }
+
+  std::string services_str = join(active_services, ", ");
+  rInfo("active services: %s", services_str.c_str());
+  if (!sm_) {
+    pm_ = std::make_unique<PubMaster>(active_services);
+  }
+}
+
+void Replay::setupSegmentManager(bool has_filters) {
+  seg_mgr_->setCallback([this]() { handleSegmentMerge(); });
+
+  if (has_filters) {
+    std::vector<bool> filters(sockets_.size(), false);
+    for (size_t i = 0; i < sockets_.size(); ++i) {
+      filters[i] = (i == cereal::Event::Which::INIT_DATA || i == cereal::Event::Which::CAR_PARAMS || sockets_[i]);
+    }
+    seg_mgr_->setFilters(filters);
+  }
+}
+
+Replay::~Replay() {
+  if (stream_thread_.joinable()) {
+    rInfo("shutdown: in progress...");
+    interruptStream([this]() {
+      exit_ = true;
+      return false;
+    });
+    stream_thread_.join();
+    rInfo("shutdown: done");
+  }
+  camera_server_.reset();
+  seg_mgr_.reset();
+}
+
+bool Replay::load() {
+  rInfo("loading route %s", seg_mgr_->route_.name().c_str());
+
+  if (!seg_mgr_->load()) return false;
+
+  if (hasFlag(REPLAY_FLAG_BENCHMARK)) {
+    benchmark_stats_.timeline.emplace_back(nanos_since_boot(), "route metadata loaded");
+  }
+
+  min_seconds_ = seg_mgr_->route_.segments().begin()->first * 60;
+  max_seconds_ = (seg_mgr_->route_.segments().rbegin()->first + 1) * 60;
+  return true;
+}
+
+void Replay::interruptStream(const std::function<bool()> &update_fn) {
+  if (stream_thread_.joinable() && stream_thread_id) {
+    pthread_kill(stream_thread_id, SIGUSR1);  // Interrupt sleep in stream thread
+  }
+  {
+    interrupt_requested_ = true;
+    std::unique_lock lock(stream_lock_);
+    events_ready_ = update_fn();
+    interrupt_requested_ = user_paused_;
+  }
+  stream_cv_.notify_one();
+}
+
+void Replay::seekTo(double seconds, bool relative) {
+  double target_time = relative ? seconds + currentSeconds() : seconds;
+  target_time = std::max(0.0, target_time);
+  int target_segment = target_time / 60;
+  if (!seg_mgr_->hasSegment(target_segment)) {
+    rWarning("Invalid seek to %.2f s (segment %d)", target_time, target_segment);
+    return;
+  }
+
+  rInfo("Seeking to %d s, segment %d", (int)target_time, target_segment);
+  notifyEvent(onSeeking, target_time);
+
+  interruptStream([&]() {
+    current_segment_.store(target_segment);
+    cur_mono_time_ = route_start_ts_ + target_time * 1e9;
+    cur_which_ = cereal::Event::Which::INIT_DATA;
+    seeking_to_.store(target_time, std::memory_order_relaxed);
+    return false;
+  });
+
+  seg_mgr_->setCurrentSegment(target_segment);
+  checkSeekProgress();
+}
+
+void Replay::checkSeekProgress() {
+  if (!seg_mgr_->getEventData()->isSegmentLoaded(current_segment_.load())) return;
+
+  double seek_to = seeking_to_.exchange(-1.0, std::memory_order_acquire);
+  if (seek_to >= 0 && onSeekedTo) {
+    onSeekedTo(seek_to);
+  }
+
+  // Resume the interrupted stream
+  interruptStream([]() { return true; });
+}
+
+void Replay::seekToFlag(FindFlag flag) {
+  if (auto next = timeline_.find(currentSeconds(), flag)) {
+    seekTo(*next - 2, false);  // seek to 2 seconds before next
+  }
+}
+
+void Replay::pause(bool pause) {
+  if (user_paused_ != pause) {
+    interruptStream([=]() {
+      rWarning("%s at %.2f s", pause ? "paused..." : "resuming", currentSeconds());
+      user_paused_ = pause;
+      return !pause;
+    });
+  }
+}
+
+void Replay::handleSegmentMerge() {
+  if (exit_) return;
+
+  auto event_data = seg_mgr_->getEventData();
+  if (!stream_thread_.joinable() && !event_data->segments.empty()) {
+    startStream(event_data->segments.begin()->second);
+  }
+  notifyEvent(onSegmentsMerged);
+
+  // Interrupt the stream to handle segment merge
+  interruptStream([]() { return false; });
+  checkSeekProgress();
+}
+
+void Replay::startStream(const std::shared_ptr<Segment> segment) {
+  const auto &events = segment->log->events;
+  route_start_ts_ = events.front().mono_time;
+  cur_mono_time_ += route_start_ts_ - 1;
+
+  // get datetime from INIT_DATA, fallback to datetime in the route name
+  route_date_time_ = route().datetime();
+  auto it = std::find_if(events.cbegin(), events.cend(),
+                         [](const Event &e) { return e.which == cereal::Event::Which::INIT_DATA; });
+  if (it != events.cend()) {
+    capnp::FlatArrayMessageReader reader(it->data);
+    auto event = reader.getRoot<cereal::Event>();
+    uint64_t wall_time = event.getInitData().getWallTimeNanos();
+    if (wall_time > 0) {
+      route_date_time_ = wall_time / 1e6;
+    }
+  }
+
+  // write CarParams
+  it = std::find_if(events.begin(), events.end(), [](const Event &e) { return e.which == cereal::Event::Which::CAR_PARAMS; });
+  if (it != events.end()) {
+    capnp::FlatArrayMessageReader reader(it->data);
+    auto event = reader.getRoot<cereal::Event>();
+    car_fingerprint_ = event.getCarParams().getCarFingerprint();
+
+    capnp::MallocMessageBuilder builder;
+    builder.setRoot(event.getCarParams());
+    auto words = capnp::messageToFlatArray(builder);
+    auto bytes = words.asBytes();
+    Params().put("CarParams", (const char *)bytes.begin(), bytes.size());
+    Params().put("CarParamsPersistent", (const char *)bytes.begin(), bytes.size());
+  } else {
+    rWarning("failed to read CarParams from current segment");
+  }
+
+  // start camera server
+  if (!hasFlag(REPLAY_FLAG_NO_VIPC)) {
+    std::pair<int, int> camera_size[MAX_CAMERAS] = {};
+    for (auto type : ALL_CAMERAS) {
+      if (auto &fr = segment->frames[type]) {
+        camera_size[type] = {fr->width, fr->height};
+      }
+    }
+    camera_server_ = std::make_unique<CameraServer>(camera_size);
+  }
+
+  timeline_.initialize(seg_mgr_->route_, route_start_ts_, !(flags_ & REPLAY_FLAG_NO_FILE_CACHE),
+                       [this](std::shared_ptr<LogReader> log) { notifyEvent(onQLogLoaded, log); });
+
+  stream_thread_ = std::thread(&Replay::streamThread, this);
+}
+
+void Replay::publishMessage(const Event *e) {
+  if (event_filter_ && event_filter_(e)) return;
+
+  if (!sm_) {
+    auto bytes = e->data.asBytes();
+    int ret = pm_->send(sockets_[e->which], (capnp::byte *)bytes.begin(), bytes.size());
+    if (ret == -1) {
+      rWarning("stop publishing %s due to multiple publishers error", sockets_[e->which]);
+      sockets_[e->which] = nullptr;
+    }
+  } else {
+    capnp::FlatArrayMessageReader reader(e->data);
+    auto event = reader.getRoot<cereal::Event>();
+    sm_->update_msgs(nanos_since_boot(), {{sockets_[e->which], event}});
+  }
+}
+
+void Replay::publishFrame(const Event *e) {
+  CameraType cam;
+  switch (e->which) {
+    case cereal::Event::ROAD_ENCODE_IDX: cam = RoadCam; break;
+    case cereal::Event::DRIVER_ENCODE_IDX: cam = DriverCam; break;
+    case cereal::Event::WIDE_ROAD_ENCODE_IDX: cam = WideRoadCam; break;
+    default: return;  // Invalid event type
+  }
+
+  if ((cam == DriverCam && !hasFlag(REPLAY_FLAG_DCAM)) || (cam == WideRoadCam && !hasFlag(REPLAY_FLAG_ECAM)))
+    return;  // Camera isdisabled
+
+  auto seg_it = event_data_->segments.find(e->eidx_segnum);
+  if (seg_it != event_data_->segments.end()) {
+    if (auto &frame = seg_it->second->frames[cam]; frame) {
+      camera_server_->pushFrame(cam, frame.get(), e);
+    }
+  }
+}
+
+void Replay::streamThread() {
+  stream_thread_id = pthread_self();
+  std::unique_lock lk(stream_lock_);
+
+  int last_processed_segment = -1;
+  uint64_t segment_start_time = 0;
+  bool streaming_started = false;
+
+  while (true) {
+    stream_cv_.wait(lk, [this]() { return exit_ || (events_ready_ && !interrupt_requested_); });
+
+    if (exit_) break;
+
+    event_data_ = seg_mgr_->getEventData();
+    const auto &events = event_data_->events;
+    auto first = std::upper_bound(events.cbegin(), events.cend(), Event(cur_which_, cur_mono_time_, {}));
+    if (first == events.cend()) {
+      rInfo("waiting for events...");
+      events_ready_ = false;
+      continue;
+    }
+
+    if (!streaming_started && hasFlag(REPLAY_FLAG_BENCHMARK)) {
+      benchmark_stats_.timeline.emplace_back(nanos_since_boot(), "streaming started");
+      streaming_started = true;
+    }
+
+    auto it = publishEvents(first, events.cend(), last_processed_segment, segment_start_time);
+
+    // Ensure frames are sent before unlocking to prevent race conditions
+    if (camera_server_) {
+      camera_server_->waitForSent();
+    }
+
+    if (it == events.cend() && !hasFlag(REPLAY_FLAG_NO_LOOP) && !hasFlag(REPLAY_FLAG_BENCHMARK)) {
+      int last_segment = seg_mgr_->route_.segments().rbegin()->first;
+      if (event_data_->isSegmentLoaded(last_segment)) {
+        rInfo("reaches the end of route, restart from beginning");
+        stream_lock_.unlock();
+        seekTo(minSeconds(), false);
+        stream_lock_.lock();
+      }
+    } else if (it == events.cend() && hasFlag(REPLAY_FLAG_BENCHMARK)) {
+      // Exit benchmark mode after first segment completes
+      exit_ = true;
+      break;
+    }
+  }
+
+  if (hasFlag(REPLAY_FLAG_BENCHMARK)) {
+    benchmark_stats_.timeline.emplace_back(nanos_since_boot(), "benchmark done");
+
+    {
+      std::unique_lock lock(benchmark_lock_);
+      benchmark_done_ = true;
+    }
+    benchmark_cv_.notify_one();
+  }
+}
+
+std::vector<Event>::const_iterator Replay::publishEvents(std::vector<Event>::const_iterator first,
+                                                         std::vector<Event>::const_iterator last,
+                                                         int &last_processed_segment,
+                                                         uint64_t &segment_start_time) {
+  uint64_t evt_start_ts = cur_mono_time_;
+  uint64_t loop_start_ts = nanos_since_boot();
+  double prev_replay_speed = speed_;
+
+  for (; !interrupt_requested_ && first != last; ++first) {
+    const Event &evt = *first;
+
+    int segment = toSeconds(evt.mono_time) / 60;
+    if (current_segment_.load(std::memory_order_relaxed) != segment) {
+      current_segment_.store(segment, std::memory_order_relaxed);
+      seg_mgr_->setCurrentSegment(segment);
+    }
+
+    // Track segment completion for benchmark timeline
+    if (hasFlag(REPLAY_FLAG_BENCHMARK) && segment != last_processed_segment) {
+      if (last_processed_segment >= 0 && segment_start_time > 0) {
+        uint64_t processing_time_ns = nanos_since_boot() - segment_start_time;
+        double processing_time_ms = processing_time_ns / 1e6;
+        double realtime_factor = 60.0 / (processing_time_ns / 1e9);  // 60s per segment
+
+        std::ostringstream oss;
+        oss << "segment " << last_processed_segment << " done publishing ("
+            << std::fixed << std::setprecision(0) << processing_time_ms << " ms, "
+            << std::fixed << std::setprecision(0) << realtime_factor << "x realtime)";
+        benchmark_stats_.timeline.emplace_back(nanos_since_boot(), oss.str());
+      }
+      segment_start_time = nanos_since_boot();
+      last_processed_segment = segment;
+    }
+
+    cur_mono_time_ = evt.mono_time;
+    cur_which_ = evt.which;
+
+    // Skip events if socket is not present
+    if (!sockets_[evt.which]) continue;
+
+    const uint64_t current_nanos = nanos_since_boot();
+    const int64_t time_diff = (evt.mono_time - evt_start_ts) / speed_ - (current_nanos - loop_start_ts);
+
+    // Reset timestamps for potential synchronization issues:
+    // - A negative time_diff may indicate slow execution or system wake-up,
+    // - A time_diff exceeding 1 second suggests a skipped segment.
+    if ((time_diff < -1e9 || time_diff >= 1e9) || speed_ != prev_replay_speed) {
+      evt_start_ts = evt.mono_time;
+      loop_start_ts = current_nanos;
+      prev_replay_speed = speed_;
+    } else if (time_diff > 0 && !hasFlag(REPLAY_FLAG_BENCHMARK)) {
+      // Skip sleep in benchmark mode for maximum throughput
+      precise_nano_sleep(time_diff, interrupt_requested_);
+    }
+
+    if (interrupt_requested_) break;
+
+    if (evt.eidx_segnum == -1) {
+      publishMessage(&evt);
+    } else if (camera_server_) {
+      if (speed_ > 1.0) {
+        camera_server_->waitForSent();
+      }
+      publishFrame(&evt);
+    }
+  }
+
+  return first;
+}
+
+void Replay::waitForFinished() {
+  if (!hasFlag(REPLAY_FLAG_BENCHMARK)) {
+    return;
+  }
+
+  std::unique_lock lock(benchmark_lock_);
+  benchmark_cv_.wait(lock, [this]() { return benchmark_done_; });
+}

tools/replay/replay.h

@@ -0,0 +1,125 @@
+#pragma once
+
+#include <algorithm>
+#include <functional>
+#include <memory>
+#include <mutex>
+#include <optional>
+#include <string>
+#include <vector>
+
+#include "tools/replay/camera.h"
+#include "tools/replay/seg_mgr.h"
+#include "tools/replay/timeline.h"
+
+#define DEMO_ROUTE "5beb9b58bd12b691/0000010a--a51155e496"
+
+enum REPLAY_FLAGS {
+  REPLAY_FLAG_NONE = 0x0000,
+  REPLAY_FLAG_DCAM = 0x0002,
+  REPLAY_FLAG_ECAM = 0x0004,
+  REPLAY_FLAG_NO_LOOP = 0x0010,
+  REPLAY_FLAG_NO_FILE_CACHE = 0x0020,
+  REPLAY_FLAG_QCAMERA = 0x0040,
+  REPLAY_FLAG_NO_HW_DECODER = 0x0100,
+  REPLAY_FLAG_NO_VIPC = 0x0400,
+  REPLAY_FLAG_ALL_SERVICES = 0x0800,
+  REPLAY_FLAG_BENCHMARK = 0x1000,
+};
+
+struct BenchmarkStats {
+  uint64_t process_start_ts = 0;
+  std::vector<std::pair<uint64_t, std::string>> timeline;
+};
+
+class Replay {
+public:
+  Replay(const std::string &route, std::vector<std::string> allow, std::vector<std::string> block, SubMaster *sm = nullptr,
+         uint32_t flags = REPLAY_FLAG_NONE, const std::string &data_dir = "", bool auto_source = false);
+  ~Replay();
+  bool load();
+  RouteLoadError lastRouteError() const { return route().lastError(); }
+  void start(int seconds = 0) { seekTo(min_seconds_ + seconds, false); }
+  void pause(bool pause);
+  void seekToFlag(FindFlag flag);
+  void seekTo(double seconds, bool relative);
+  inline bool isPaused() const { return user_paused_; }
+  inline int segmentCacheLimit() const { return seg_mgr_->segment_cache_limit_; }
+  inline void setSegmentCacheLimit(int n) { seg_mgr_->segment_cache_limit_ = std::max(MIN_SEGMENTS_CACHE, n); }
+  inline bool hasFlag(REPLAY_FLAGS flag) const { return flags_ & flag; }
+  void setLoop(bool loop) { loop ? flags_ &= ~REPLAY_FLAG_NO_LOOP : flags_ |= REPLAY_FLAG_NO_LOOP; }
+  bool loop() const { return !(flags_ & REPLAY_FLAG_NO_LOOP); }
+  const Route &route() const { return seg_mgr_->route_; }
+  inline double currentSeconds() const { return double(cur_mono_time_ - route_start_ts_) / 1e9; }
+  inline std::time_t routeDateTime() const { return route_date_time_; }
+  inline uint64_t routeStartNanos() const { return route_start_ts_; }
+  inline double toSeconds(uint64_t mono_time) const { return (mono_time - route_start_ts_) / 1e9; }
+  inline double minSeconds() const { return min_seconds_; }
+  inline double maxSeconds() const { return max_seconds_; }
+  inline void setSpeed(float speed) { speed_ = speed; }
+  inline float getSpeed() const { return speed_; }
+  inline const std::string &carFingerprint() const { return car_fingerprint_; }
+  inline const std::shared_ptr<std::vector<Timeline::Entry>> getTimeline() const { return timeline_.getEntries(); }
+  inline const std::optional<Timeline::Entry> findAlertAtTime(double sec) const { return timeline_.findAlertAtTime(sec); }
+  const std::shared_ptr<SegmentManager::EventData> getEventData() const { return seg_mgr_->getEventData(); }
+  void installEventFilter(std::function<bool(const Event *)> filter) { event_filter_ = filter; }
+  void waitForFinished();
+  const BenchmarkStats &getBenchmarkStats() const { return benchmark_stats_; }
+
+  // Event callback functions
+  std::function<void()> onSegmentsMerged = nullptr;
+  std::function<void(double)> onSeeking = nullptr;
+  std::function<void(double)> onSeekedTo = nullptr;
+  std::function<void(std::shared_ptr<LogReader>)> onQLogLoaded = nullptr;
+
+private:
+  void setupServices(const std::vector<std::string> &allow, const std::vector<std::string> &block);
+  void setupSegmentManager(bool has_filters);
+  void startStream(const std::shared_ptr<Segment> segment);
+  void streamThread();
+  void handleSegmentMerge();
+  void interruptStream(const std::function<bool()>& update_fn);
+  std::vector<Event>::const_iterator publishEvents(std::vector<Event>::const_iterator first,
+                                                   std::vector<Event>::const_iterator last,
+                                                   int &last_processed_segment,
+                                                   uint64_t &segment_start_time);
+  void publishMessage(const Event *e);
+  void publishFrame(const Event *e);
+  void checkSeekProgress();
+
+  std::unique_ptr<SegmentManager> seg_mgr_;
+  Timeline timeline_;
+
+  pthread_t stream_thread_id = 0;
+  std::thread stream_thread_;
+  std::mutex stream_lock_;
+  bool user_paused_ = false;
+  std::condition_variable stream_cv_;
+  std::atomic<int> current_segment_ = 0;
+  std::atomic<double> seeking_to_ = -1.0;
+  std::atomic<bool> exit_ = false;
+  std::atomic<bool> interrupt_requested_ = false;
+  bool events_ready_ = false;
+  std::time_t route_date_time_;
+  uint64_t route_start_ts_ = 0;
+  std::atomic<uint64_t> cur_mono_time_ = 0;
+  cereal::Event::Which cur_which_ = cereal::Event::Which::INIT_DATA;
+  double min_seconds_ = 0;
+  double max_seconds_ = 0;
+  SubMaster *sm_ = nullptr;
+  std::unique_ptr<PubMaster> pm_;
+  std::vector<const char*> sockets_;
+  std::unique_ptr<CameraServer> camera_server_;
+  std::atomic<uint32_t> flags_ = REPLAY_FLAG_NONE;
+
+  std::string car_fingerprint_;
+  std::atomic<float> speed_ = 1.0;
+  std::function<bool(const Event *)> event_filter_ = nullptr;
+
+  std::shared_ptr<SegmentManager::EventData> event_data_ = std::make_shared<SegmentManager::EventData>();
+
+  BenchmarkStats benchmark_stats_;
+  std::condition_variable benchmark_cv_;
+  std::mutex benchmark_lock_;
+  bool benchmark_done_ = false;
+};

tools/replay/route.cc

@@ -0,0 +1,252 @@
+#include "tools/replay/route.h"
+
+#include <array>
+#include <filesystem>
+#include <regex>
+
+#include "json11/json11.hpp"
+#include "system/hardware/hw.h"
+#include "tools/replay/py_downloader.h"
+#include "tools/replay/replay.h"
+#include "tools/replay/util.h"
+
+Route::Route(const std::string &route, const std::string &data_dir, bool auto_source)
+    : route_string_(route), data_dir_(data_dir), auto_source_(auto_source) {}
+
+RouteIdentifier Route::parseRoute(const std::string &str) {
+  RouteIdentifier identifier = {};
+  static const std::regex pattern(R"(^(([a-z0-9]{16})[|_/])?(.{20})((--|/)((-?\d+(:(-?\d+)?)?)|(:-?\d+)))?$)");
+  std::smatch match;
+
+  if (std::regex_match(str, match, pattern)) {
+    identifier.dongle_id = match[2].str();
+    identifier.timestamp = match[3].str();
+    identifier.str = identifier.dongle_id + "|" + identifier.timestamp;
+
+    const auto separator = match[5].str();
+    const auto range_str = match[6].str();
+    if (!range_str.empty()) {
+      if (separator == "/") {
+        int pos = range_str.find(':');
+        int begin_seg = std::stoi(range_str.substr(0, pos));
+        identifier.begin_segment = identifier.end_segment = begin_seg;
+        if (pos != std::string::npos) {
+          auto end_seg_str = range_str.substr(pos + 1);
+          identifier.end_segment = end_seg_str.empty() ? -1 : std::stoi(end_seg_str);
+        }
+      } else if (separator == "--") {
+        identifier.begin_segment = std::atoi(range_str.c_str());
+      }
+    }
+  }
+  return identifier;
+}
+
+bool Route::load() {
+  route_ = parseRoute(route_string_);
+  if (route_.str.empty() || (data_dir_.empty() && route_.dongle_id.empty())) {
+    rInfo("invalid route format");
+    return false;
+  }
+
+  // Parse the timestamp from the route identifier (only applicable for old route formats).
+  struct tm tm_time = {0};
+  if (strptime(route_.timestamp.c_str(), "%Y-%m-%d--%H-%M-%S", &tm_time)) {
+    date_time_ = mktime(&tm_time);
+  }
+
+  if (!loadSegments()) {
+    rInfo("Failed to load segments");
+    return false;
+  }
+
+  return true;
+}
+
+bool Route::loadSegments() {
+  if (!auto_source_) {
+    bool ret = data_dir_.empty() ? loadFromServer() : loadFromLocal();
+    if (ret) {
+      // Trim segments
+      if (route_.begin_segment > 0) {
+        segments_.erase(segments_.begin(), segments_.lower_bound(route_.begin_segment));
+      }
+      if (route_.end_segment >= 0) {
+        segments_.erase(segments_.upper_bound(route_.end_segment), segments_.end());
+      }
+    }
+    return !segments_.empty();
+  }
+  return loadFromAutoSource();
+}
+
+bool Route::loadFromAutoSource() {
+  auto origin_prefix = getenv("OPENPILOT_PREFIX");
+  if (origin_prefix) {
+    setenv("OPENPILOT_PREFIX", "", 1);
+  }
+  auto cmd = util::string_format("../auto_source.py \"%s\"", route_string_.c_str());
+  auto log_files = split(util::check_output(cmd), '\n');
+  if (origin_prefix) {
+    setenv("OPENPILOT_PREFIX", origin_prefix, 1);
+  }
+
+  const static std::regex rx(R"(\/(\d+)\/)");
+  for (int i = 0; i < log_files.size(); ++i) {
+    int seg_num = i;
+    std::smatch match;
+    if (std::regex_search(log_files[i], match, rx)) {
+      seg_num = std::stoi(match[1]);
+    }
+    addFileToSegment(seg_num, log_files[i]);
+  }
+  return !segments_.empty();
+}
+
+bool Route::loadFromServer() {
+  std::string result = PyDownloader::getRouteFiles(route_.str);
+  if (result.empty()) {
+    err_ = RouteLoadError::NetworkError;
+    rWarning("Failed to fetch route files from server");
+    return false;
+  }
+
+  // Check for error field in JSON response
+  std::string parse_err;
+  auto json = json11::Json::parse(result, parse_err);
+  if (!parse_err.empty()) {
+    err_ = RouteLoadError::NetworkError;
+    rWarning("Failed to parse route files response");
+    return false;
+  }
+
+  if (json.is_object() && json["error"].is_string()) {
+    const std::string &error = json["error"].string_value();
+    if (error == "unauthorized") {
+      rWarning(">> Unauthorized. Authenticate with tools/lib/auth.py <<");
+      err_ = RouteLoadError::Unauthorized;
+    } else if (error == "not_found") {
+      rWarning("The specified route could not be found on the server.");
+      err_ = RouteLoadError::FileNotFound;
+    } else {
+      rWarning("API error: %s", error.c_str());
+      err_ = RouteLoadError::NetworkError;
+    }
+    return false;
+  }
+
+  return loadFromJson(json);
+}
+
+bool Route::loadFromJson(const json11::Json &json) {
+  const static std::regex rx(R"(\/(\d+)\/)");
+  for (const auto &value : json.object_items()) {
+    const auto &urlArray = value.second.array_items();
+    for (const auto &url : urlArray) {
+      std::string url_str = url.string_value();
+      std::smatch match;
+      if (std::regex_search(url_str, match, rx)) {
+        addFileToSegment(std::stoi(match[1]), url_str);
+      }
+    }
+  }
+  return !segments_.empty();
+}
+
+bool Route::loadFromLocal() {
+  std::string pattern = route_.timestamp + "--";
+  for (const auto &entry : std::filesystem::directory_iterator(data_dir_)) {
+    if (entry.is_directory() && entry.path().filename().string().find(pattern) != std::string::npos) {
+      std::string segment = entry.path().string();
+      int seg_num = std::atoi(segment.substr(segment.rfind("--") + 2).c_str());
+
+      for (const auto &file : std::filesystem::directory_iterator(segment)) {
+        if (file.is_regular_file()) {
+          addFileToSegment(seg_num, file.path().string());
+        }
+      }
+    }
+  }
+  return !segments_.empty();
+}
+
+void Route::addFileToSegment(int n, const std::string &file) {
+  std::string name = extractFileName(file);
+  auto pos = name.find_last_of("--");
+  name = pos != std::string::npos ? name.substr(pos + 2) : name;
+
+  if (name == "rlog.bz2" || name == "rlog.zst" || name == "rlog") {
+    segments_[n].rlog = file;
+  } else if (name == "qlog.bz2" || name == "qlog.zst" || name == "qlog") {
+    segments_[n].qlog = file;
+  } else if (name == "fcamera.hevc") {
+    segments_[n].road_cam = file;
+  } else if (name == "dcamera.hevc") {
+    segments_[n].driver_cam = file;
+  } else if (name == "ecamera.hevc") {
+    segments_[n].wide_road_cam = file;
+  } else if (name == "qcamera.ts") {
+    segments_[n].qcamera = file;
+  }
+}
+
+// class Segment
+
+Segment::Segment(int n, const SegmentFile &files, uint32_t flags, const std::vector<bool> &filters,
+                 std::function<void(int, bool)> callback)
+    : seg_num(n), flags(flags), filters_(filters), on_load_finished_(callback) {
+  // [RoadCam, DriverCam, WideRoadCam, log]. fallback to qcamera/qlog
+  const std::array file_list = {
+      (flags & REPLAY_FLAG_QCAMERA) || files.road_cam.empty() ? files.qcamera : files.road_cam,
+      flags & REPLAY_FLAG_DCAM ? files.driver_cam : "",
+      flags & REPLAY_FLAG_ECAM ? files.wide_road_cam : "",
+      files.rlog.empty() ? files.qlog : files.rlog,
+  };
+  for (int i = 0; i < file_list.size(); ++i) {
+    if (!file_list[i].empty() && (!(flags & REPLAY_FLAG_NO_VIPC) || i >= MAX_CAMERAS)) {
+      ++loading_;
+      threads_.emplace_back(&Segment::loadFile, this, i, file_list[i]);
+    }
+  }
+}
+
+Segment::~Segment() {
+  {
+    std::lock_guard lock(mutex_);
+    on_load_finished_ = nullptr;  // Prevent callback after destruction
+  }
+  abort_ = true;
+  for (auto &thread : threads_) {
+    if (thread.joinable()) thread.join();
+  }
+}
+
+void Segment::loadFile(int id, const std::string file) {
+  const bool local_cache = !(flags & REPLAY_FLAG_NO_FILE_CACHE);
+  bool success = false;
+  if (id < MAX_CAMERAS) {
+    frames[id] = std::make_unique<FrameReader>();
+    success = frames[id]->load((CameraType)id, file, flags & REPLAY_FLAG_NO_HW_DECODER, &abort_, local_cache);
+  } else {
+    log = std::make_unique<LogReader>(filters_);
+    success = log->load(file, &abort_, local_cache);
+  }
+
+  if (!success) {
+    // abort all loading jobs.
+    abort_ = true;
+  }
+
+  if (--loading_ == 0) {
+    std::lock_guard lock(mutex_);
+    load_state_ = !abort_ ? LoadState::Loaded : LoadState::Failed;
+    if (on_load_finished_) {
+      on_load_finished_(seg_num, !abort_);
+    }
+  }
+}
+
+Segment::LoadState Segment::getState() {
+  std::scoped_lock lock(mutex_);
+  return load_state_;
+}

tools/replay/route.h

@@ -0,0 +1,95 @@
+#pragma once
+
+#include <ctime>
+#include <map>
+#include <memory>
+#include <mutex>
+#include <string>
+#include <thread>
+#include <vector>
+
+#include "json11/json11.hpp"
+#include "tools/replay/framereader.h"
+#include "tools/replay/logreader.h"
+#include "tools/replay/util.h"
+
+enum class RouteLoadError {
+  None,
+  Unauthorized,
+  AccessDenied,
+  NetworkError,
+  FileNotFound,
+  UnknownError
+};
+
+struct RouteIdentifier {
+  std::string dongle_id;
+  std::string timestamp;
+  int begin_segment = 0;
+  int end_segment = -1;
+  std::string str;
+};
+
+struct SegmentFile {
+  std::string rlog;
+  std::string qlog;
+  std::string road_cam;
+  std::string driver_cam;
+  std::string wide_road_cam;
+  std::string qcamera;
+};
+
+class Route {
+public:
+  Route(const std::string &route, const std::string &data_dir = {}, bool auto_source = false);
+  bool load();
+  RouteLoadError lastError() const { return err_; }
+  inline const std::string &name() const { return route_.str; }
+  inline const std::time_t datetime() const { return date_time_; }
+  inline const std::string &dir() const { return data_dir_; }
+  inline const RouteIdentifier &identifier() const { return route_; }
+  inline const std::map<int, SegmentFile> &segments() const { return segments_; }
+  inline const SegmentFile &at(int n) { return segments_.at(n); }
+  static RouteIdentifier parseRoute(const std::string &str);
+
+protected:
+  bool loadSegments();
+  bool loadFromAutoSource();
+  bool loadFromLocal();
+  bool loadFromServer();
+  bool loadFromJson(const json11::Json &json);
+  void addFileToSegment(int seg_num, const std::string &file);
+  RouteIdentifier route_ = {};
+  std::string data_dir_;
+  std::map<int, SegmentFile> segments_;
+  std::time_t date_time_ = 0;
+  RouteLoadError err_ = RouteLoadError::None;
+  bool auto_source_ = false;
+  std::string route_string_;
+};
+
+class Segment {
+public:
+  enum class LoadState {Loading, Loaded, Failed};
+
+  Segment(int n, const SegmentFile &files, uint32_t flags, const std::vector<bool> &filters,
+          std::function<void(int, bool)> callback);
+  ~Segment();
+  LoadState getState();
+
+  const int seg_num = 0;
+  std::unique_ptr<LogReader> log;
+  std::unique_ptr<FrameReader> frames[MAX_CAMERAS] = {};
+
+protected:
+  void loadFile(int id, const std::string file);
+
+  std::atomic<bool> abort_ = false;
+  std::atomic<int> loading_ = 0;
+  std::mutex mutex_;
+  std::vector<std::thread> threads_;
+  std::function<void(int, bool)> on_load_finished_ = nullptr;
+  uint32_t flags;
+  std::vector<bool> filters_;
+  LoadState load_state_  = LoadState::Loading;
+};

tools/replay/seg_mgr.cc

@@ -0,0 +1,147 @@
+#include "tools/replay/seg_mgr.h"
+
+#include <algorithm>
+
+SegmentManager::~SegmentManager() {
+  {
+    std::unique_lock lock(mutex_);
+    exit_ = true;
+  }
+  cv_.notify_one();
+  if (thread_.joinable()) thread_.join();
+}
+
+bool SegmentManager::load() {
+  if (!route_.load()) {
+    rError("failed to load route: %s", route_.name().c_str());
+    return false;
+  }
+
+  for (const auto &[n, file] : route_.segments()) {
+    if (!file.rlog.empty() || !file.qlog.empty()) {
+      segments_.insert({n, nullptr});
+    }
+  }
+
+  if (segments_.empty()) {
+    rInfo("no valid segments in route: %s", route_.name().c_str());
+    return false;
+  }
+
+  rInfo("loaded route %s with %zu valid segments", route_.name().c_str(), segments_.size());
+  thread_ = std::thread(&SegmentManager::manageSegmentCache, this);
+  return true;
+}
+
+void SegmentManager::setCurrentSegment(int seg_num) {
+  {
+    std::unique_lock lock(mutex_);
+    if (cur_seg_num_ == seg_num) return;
+
+    cur_seg_num_ = seg_num;
+    needs_update_ = true;
+  }
+  cv_.notify_one();
+}
+
+void SegmentManager::manageSegmentCache() {
+  while (true) {
+    std::unique_lock lock(mutex_);
+    cv_.wait(lock, [this]() { return exit_ || needs_update_; });
+    if (exit_) break;
+
+    needs_update_ = false;
+    auto cur = segments_.lower_bound(cur_seg_num_);
+    if (cur == segments_.end()) continue;
+
+    // Calculate the range of segments to load
+    auto begin = std::prev(cur, std::min<int>(segment_cache_limit_ / 2, std::distance(segments_.begin(), cur)));
+    auto end = std::next(begin, std::min<int>(segment_cache_limit_, std::distance(begin, segments_.end())));
+    begin = std::prev(end, std::min<int>(segment_cache_limit_, std::distance(segments_.begin(), end)));
+
+    lock.unlock();
+
+    loadSegmentsInRange(begin, cur, end);
+    bool merged = mergeSegments(begin, end);
+
+    // Free segments outside the current range
+    std::for_each(segments_.begin(), begin, [](auto &segment) { segment.second.reset(); });
+    std::for_each(end, segments_.end(), [](auto &segment) { segment.second.reset(); });
+
+    if (merged && onSegmentMergedCallback_) {
+      onSegmentMergedCallback_();  // Notify listener that segments have been merged
+    }
+  }
+}
+
+bool SegmentManager::mergeSegments(const SegmentMap::iterator &begin, const SegmentMap::iterator &end) {
+  std::set<int> segments_to_merge;
+  size_t total_event_count = 0;
+  for (auto it = begin; it != end; ++it) {
+    const auto &segment = it->second;
+    if (segment && segment->getState() == Segment::LoadState::Loaded) {
+      segments_to_merge.insert(segment->seg_num);
+      total_event_count += segment->log->events.size();
+    }
+  }
+
+  if (segments_to_merge == merged_segments_) return false;
+
+  auto merged_event_data = std::make_shared<EventData>();
+  auto &merged_events = merged_event_data->events;
+  merged_events.reserve(total_event_count);
+
+  std::string segments_str = join(segments_to_merge, ", ");
+  rDebug("merging segments: %s", segments_str.c_str());
+  for (int n : segments_to_merge) {
+    const auto &events = segments_.at(n)->log->events;
+    if (events.empty()) continue;
+
+    // Skip INIT_DATA if present
+    auto events_begin = (events.front().which == cereal::Event::Which::INIT_DATA) ? std::next(events.begin()) : events.begin();
+
+    size_t previous_size = merged_events.size();
+    merged_events.insert(merged_events.end(), events_begin, events.end());
+    std::inplace_merge(merged_events.begin(), merged_events.begin() + previous_size, merged_events.end());
+
+    merged_event_data->segments[n] = segments_.at(n);
+  }
+
+  std::atomic_store(&event_data_, std::move(merged_event_data));
+  merged_segments_ = segments_to_merge;
+
+  return true;
+}
+
+void SegmentManager::loadSegmentsInRange(SegmentMap::iterator begin, SegmentMap::iterator cur, SegmentMap::iterator end) {
+  auto tryLoadSegment = [this](auto first, auto last) {
+    for (auto it = first; it != last; ++it) {
+      auto &segment_ptr = it->second;
+      if (!segment_ptr) {
+        if (onBenchmarkEvent_) {
+          onBenchmarkEvent_(it->first, "loading");
+        }
+        segment_ptr = std::make_shared<Segment>(
+            it->first, route_.at(it->first), flags_, filters_,
+            [this](int seg_num, bool success) {
+              if (onBenchmarkEvent_) {
+                onBenchmarkEvent_(seg_num, success ? "loaded" : "load failed");
+              }
+              std::unique_lock lock(mutex_);
+              needs_update_ = true;
+              cv_.notify_one();
+            });
+      }
+
+      if (segment_ptr->getState() == Segment::LoadState::Loading) {
+        return true;  // Segment is still loading
+      }
+    }
+    return false;  // No segments need loading
+  };
+
+  // Try forward loading, then reverse if necessary
+  if (!tryLoadSegment(cur, end)) {
+    tryLoadSegment(std::make_reverse_iterator(cur), std::make_reverse_iterator(begin));
+  }
+}

tools/replay/seg_mgr.h

@@ -0,0 +1,58 @@
+#pragma once
+
+#include <condition_variable>
+#include <map>
+#include <mutex>
+#include <set>
+#include <vector>
+
+#include "tools/replay/route.h"
+
+constexpr int MIN_SEGMENTS_CACHE = 5;
+
+using SegmentMap = std::map<int, std::shared_ptr<Segment>>;
+
+class SegmentManager {
+public:
+  struct EventData {
+    std::vector<Event> events;  //  Events extracted from the segments
+    SegmentMap segments;        // Associated segments that contributed to these events
+    bool isSegmentLoaded(int n) const { return segments.find(n) != segments.end(); }
+  };
+
+  SegmentManager(const std::string &route_name, uint32_t flags, const std::string &data_dir = "", bool auto_source = false)
+      : flags_(flags), route_(route_name, data_dir, auto_source), event_data_(std::make_shared<EventData>()) {}
+  ~SegmentManager();
+
+  bool load();
+  void setCurrentSegment(int seg_num);
+  void setCallback(const std::function<void()> &callback) { onSegmentMergedCallback_ = callback; }
+  void setBenchmarkCallback(const std::function<void(int, const std::string&)> &callback) { onBenchmarkEvent_ = callback; }
+  void setFilters(const std::vector<bool> &filters) { filters_ = filters; }
+  const std::shared_ptr<EventData> getEventData() const { return std::atomic_load(&event_data_); }
+  bool hasSegment(int n) const { return segments_.find(n) != segments_.end(); }
+
+  Route route_;
+  int segment_cache_limit_ = MIN_SEGMENTS_CACHE;
+
+private:
+  void manageSegmentCache();
+  void loadSegmentsInRange(SegmentMap::iterator begin, SegmentMap::iterator cur, SegmentMap::iterator end);
+  bool mergeSegments(const SegmentMap::iterator &begin, const SegmentMap::iterator &end);
+
+  std::vector<bool> filters_;
+  uint32_t flags_;
+
+  std::mutex mutex_;
+  std::condition_variable cv_;
+  std::thread thread_;
+  int cur_seg_num_ = -1;
+  bool needs_update_ = false;
+  bool exit_ = false;
+
+  SegmentMap segments_;
+  std::shared_ptr<EventData> event_data_;
+  std::function<void()> onSegmentMergedCallback_ = nullptr;
+  std::function<void(int, const std::string&)> onBenchmarkEvent_ = nullptr;
+  std::set<int> merged_segments_;
+};

tools/replay/tests/test_replay.cc

@@ -0,0 +1,18 @@
+#define CATCH_CONFIG_MAIN
+#include "catch2/catch.hpp"
+#include "tools/replay/filereader.h"
+#include "tools/replay/replay.h"
+
+const std::string TEST_RLOG_URL = "https://commadataci.blob.core.windows.net/openpilotci/0c94aa1e1296d7c6/2021-05-05--19-48-37/0/rlog.bz2";
+
+TEST_CASE("LogReader") {
+  SECTION("corrupt log") {
+    FileReader reader(true);
+    std::string corrupt_content = reader.read(TEST_RLOG_URL);
+    corrupt_content.resize(corrupt_content.length() / 2);
+    corrupt_content = decompressBZ2(corrupt_content);
+    LogReader log;
+    REQUIRE(log.load(corrupt_content.data(), corrupt_content.size()));
+    REQUIRE(log.events.size() > 0);
+  }
+}

tools/replay/timeline.cc

@@ -0,0 +1,111 @@
+#include "tools/replay/timeline.h"
+
+#include <algorithm>
+#include <array>
+
+#include "cereal/gen/cpp/log.capnp.h"
+
+Timeline::~Timeline() {
+  should_exit_.store(true);
+  if (thread_.joinable()) {
+    thread_.join();
+  }
+}
+
+void Timeline::initialize(const Route &route, uint64_t route_start_ts, bool local_cache,
+                          std::function<void(std::shared_ptr<LogReader>)> callback) {
+  thread_ = std::thread(&Timeline::buildTimeline, this, route, route_start_ts, local_cache, callback);
+}
+
+std::optional<uint64_t> Timeline::find(double cur_ts, FindFlag flag) const {
+  for (const auto &entry : *getEntries()) {
+    if (entry.type == TimelineType::Engaged) {
+      if (flag == FindFlag::nextEngagement && entry.start_time > cur_ts) {
+        return entry.start_time;
+      } else if (flag == FindFlag::nextDisEngagement && entry.end_time > cur_ts) {
+        return entry.end_time;
+      }
+    } else if (entry.start_time > cur_ts) {
+      if ((flag == FindFlag::nextUserBookmark && entry.type == TimelineType::UserBookmark) ||
+          (flag == FindFlag::nextInfo && entry.type == TimelineType::AlertInfo) ||
+          (flag == FindFlag::nextWarning && entry.type == TimelineType::AlertWarning) ||
+          (flag == FindFlag::nextCritical && entry.type == TimelineType::AlertCritical)) {
+        return entry.start_time;
+      }
+    }
+  }
+  return std::nullopt;
+}
+
+std::optional<Timeline::Entry> Timeline::findAlertAtTime(double target_time) const {
+  for (const auto &entry : *getEntries()) {
+    if (entry.start_time > target_time) break;
+    if (entry.end_time >= target_time && entry.type >= TimelineType::AlertInfo) {
+      return entry;
+    }
+  }
+  return std::nullopt;
+}
+
+void Timeline::buildTimeline(const Route &route, uint64_t route_start_ts, bool local_cache,
+                             std::function<void(std::shared_ptr<LogReader>)> callback) {
+  std::optional<size_t> current_engaged_idx, current_alert_idx;
+
+  for (const auto &segment : route.segments()) {
+    if (should_exit_) break;
+
+    auto log = std::make_shared<LogReader>();
+    if (!log->load(segment.second.qlog, &should_exit_, local_cache) || log->events.empty()) {
+      continue;  // Skip if log loading fails or no events
+    }
+
+    for (const Event &e : log->events) {
+      double seconds = (e.mono_time - route_start_ts) / 1e9;
+      if (e.which == cereal::Event::Which::SELFDRIVE_STATE) {
+        capnp::FlatArrayMessageReader reader(e.data);
+        auto cs = reader.getRoot<cereal::Event>().getSelfdriveState();
+        updateEngagementStatus(cs, current_engaged_idx, seconds);
+        updateAlertStatus(cs, current_alert_idx, seconds);
+      } else if (e.which == cereal::Event::Which::USER_BOOKMARK) {
+        staging_entries_.emplace_back(Entry{seconds, seconds, TimelineType::UserBookmark});
+      }
+    }
+
+    // Sort and finalize the timeline entries
+    auto entries = std::make_shared<std::vector<Entry>>(staging_entries_);
+    std::sort(entries->begin(), entries->end(), [](auto &a, auto &b) { return a.start_time < b.start_time; });
+    std::atomic_store(&timeline_entries_, std::move(entries));
+
+    callback(log);  // Notify the callback once the log is processed
+  }
+}
+
+void Timeline::updateEngagementStatus(const cereal::SelfdriveState::Reader &cs, std::optional<size_t> &idx, double seconds) {
+  if (idx) staging_entries_[*idx].end_time = seconds;
+  if (cs.getEnabled()) {
+    if (!idx) {
+      idx = staging_entries_.size();
+      staging_entries_.emplace_back(Entry{seconds, seconds, TimelineType::Engaged});
+    }
+  } else {
+    idx.reset();
+  }
+}
+
+void Timeline::updateAlertStatus(const cereal::SelfdriveState::Reader &cs, std::optional<size_t> &idx, double seconds) {
+  static auto alert_types = std::array{TimelineType::AlertInfo, TimelineType::AlertWarning, TimelineType::AlertCritical};
+
+  Entry *entry = idx ? &staging_entries_[*idx] : nullptr;
+  if (entry) entry->end_time = seconds;
+  if (cs.getAlertSize() != cereal::SelfdriveState::AlertSize::NONE) {
+    auto type = alert_types[(int)cs.getAlertStatus()];
+    std::string text1 = cs.getAlertText1().cStr();
+    std::string text2 = cs.getAlertText2().cStr();
+    if (!entry || entry->type != type || entry->text1 != text1 || entry->text2 != text2) {
+      idx = staging_entries_.size();
+      staging_entries_.emplace_back(Entry{seconds, seconds, type, text1, text2});  // Start a new entry
+    }
+  } else {
+    idx.reset();
+  }
+}

tools/replay/timeline.h

@@ -0,0 +1,46 @@
+#pragma once
+
+#include <atomic>
+#include <optional>
+#include <thread>
+#include <vector>
+
+#include "tools/replay/route.h"
+
+enum class TimelineType { None, Engaged, AlertInfo, AlertWarning, AlertCritical, UserBookmark };
+enum class FindFlag { nextEngagement, nextDisEngagement, nextUserBookmark, nextInfo, nextWarning, nextCritical };
+
+class Timeline {
+public:
+  struct Entry {
+    double start_time;
+    double end_time;
+    TimelineType type;
+    std::string text1;
+    std::string text2;
+  };
+
+  Timeline() : timeline_entries_(std::make_shared<std::vector<Entry>>()) {}
+  ~Timeline();
+
+  void initialize(const Route &route, uint64_t route_start_ts, bool local_cache,
+                  std::function<void(std::shared_ptr<LogReader>)> callback);
+  std::optional<uint64_t> find(double cur_ts, FindFlag flag) const;
+  std::optional<Entry> findAlertAtTime(double target_time) const;
+  const std::shared_ptr<std::vector<Entry>> getEntries() const { return std::atomic_load(&timeline_entries_); }
+
+private:
+  void buildTimeline(const Route &route, uint64_t route_start_ts, bool local_cache,
+                     std::function<void(std::shared_ptr<LogReader>)> callback);
+  void updateEngagementStatus(const cereal::SelfdriveState::Reader &cs, std::optional<size_t> &idx, double seconds);
+  void updateAlertStatus(const cereal::SelfdriveState::Reader &cs, std::optional<size_t> &idx, double seconds);
+
+  std::thread thread_;
+  std::atomic<bool> should_exit_ = false;
+
+  // Temporarily holds entries before they are sorted and finalized
+  std::vector<Entry> staging_entries_;
+
+  // Final sorted timeline entries
+  std::shared_ptr<std::vector<Entry>> timeline_entries_;
+};

tools/replay/ui.py

@@ -0,0 +1,271 @@
+#!/usr/bin/env python3
+import argparse
+import os
+import sys
+
+import numpy as np
+import pyray as rl
+
+import cereal.messaging as messaging
+from openpilot.common.basedir import BASEDIR
+from openpilot.common.transformations.camera import DEVICE_CAMERAS
+from openpilot.tools.replay.lib.ui_helpers import (
+  UP,
+  BLACK,
+  GREEN,
+  YELLOW,
+  Calibration,
+  get_blank_lid_overlay,
+  init_plots,
+  maybe_update_radar_points,
+  plot_lead,
+  plot_model,
+)
+from msgq.visionipc import VisionStreamType
+from openpilot.selfdrive.ui.mici.onroad.cameraview import CameraView
+
+os.environ['BASEDIR'] = BASEDIR
+
+ANGLE_SCALE = 5.0
+
+
+def ui_thread(addr):
+  # Get monitor info before creating window
+  rl.set_config_flags(rl.ConfigFlags.FLAG_MSAA_4X_HINT)
+  rl.init_window(1, 1, "")
+  max_height = rl.get_monitor_height(0)
+  rl.close_window()
+
+  hor_mode = os.getenv("HORIZONTAL") is not None
+  hor_mode = True if max_height < 960 + 300 else hor_mode
+
+  if hor_mode:
+    size = (640 + 384 + 640, 960)
+    write_x = 5
+    write_y = 680
+  else:
+    size = (640 + 384, 960 + 300)
+    write_x = 645
+    write_y = 970
+
+  rl.set_trace_log_level(rl.TraceLogLevel.LOG_ERROR)
+  rl.set_config_flags(rl.ConfigFlags.FLAG_MSAA_4X_HINT)
+  rl.init_window(size[0], size[1], "openpilot debug UI")
+  rl.set_target_fps(60)
+
+  # Load font
+  font_path = os.path.join(BASEDIR, "selfdrive/assets/fonts/JetBrainsMono-Medium.ttf")
+  font = rl.load_font_ex(font_path, 32, None, 0)
+
+  camera_view = CameraView("camerad", VisionStreamType.VISION_STREAM_ROAD)
+
+  # Overlay texture for model/lane line drawing
+  overlay_img = np.zeros((480, 640, 4), dtype='uint8')
+  overlay_image = rl.gen_image_color(640, 480, rl.BLANK)
+  overlay_texture = rl.load_texture_from_image(overlay_image)
+  rl.unload_image(overlay_image)
+
+  # lid_overlay array is (lidar_x, lidar_y) = (384, 960)
+  top_down_image = rl.gen_image_color(UP.lidar_x, UP.lidar_y, rl.BLACK)
+  top_down_texture = rl.load_texture_from_image(top_down_image)
+  rl.unload_image(top_down_image)
+
+  sm = messaging.SubMaster(
+    [
+      'carState',
+      'longitudinalPlan',
+      'carControl',
+      'radarState',
+      'liveCalibration',
+      'controlsState',
+      'selfdriveState',
+      'liveTracks',
+      'modelV2',
+      'liveParameters',
+      'roadCameraState',
+    ],
+    addr=addr,
+  )
+
+  img = np.zeros((480, 640, 3), dtype='uint8')
+  num_px = 0
+  calibration = None
+
+  lid_overlay_blank = get_blank_lid_overlay(UP)
+
+  # plots
+  name_to_arr_idx = {
+    "gas": 0,
+    "computer_gas": 1,
+    "user_brake": 2,
+    "computer_brake": 3,
+    "v_ego": 4,
+    "v_pid": 5,
+    "angle_steers_des": 6,
+    "angle_steers": 7,
+    "angle_steers_k": 8,
+    "steer_torque": 9,
+    "v_override": 10,
+    "v_cruise": 11,
+    "a_ego": 12,
+    "a_target": 13,
+  }
+
+  plot_arr = np.zeros((100, len(name_to_arr_idx.values())))
+
+  plot_xlims = [(0, plot_arr.shape[0]), (0, plot_arr.shape[0]), (0, plot_arr.shape[0]), (0, plot_arr.shape[0])]
+  plot_ylims = [(-0.1, 1.1), (-ANGLE_SCALE, ANGLE_SCALE), (0.0, 75.0), (-3.5, 2.0)]
+  plot_names = [
+    ["gas", "computer_gas", "user_brake", "computer_brake"],
+    ["angle_steers", "angle_steers_des", "angle_steers_k", "steer_torque"],
+    ["v_ego", "v_override", "v_pid", "v_cruise"],
+    ["a_ego", "a_target"],
+  ]
+  plot_colors = [["b", "b", "g", "r", "y"], ["b", "g", "y", "r"], ["b", "g", "r", "y"], ["b", "r"]]
+  plot_styles = [["-", "-", "-", "-", "-"], ["-", "-", "-", "-"], ["-", "-", "-", "-"], ["-", "-"]]
+
+  draw_plots = init_plots(plot_arr, name_to_arr_idx, plot_xlims, plot_ylims, plot_names, plot_colors, plot_styles)
+
+  # Palette for converting lid_overlay grayscale indices to RGBA colors
+  palette = np.zeros((256, 4), dtype=np.uint8)
+  palette[:, 3] = 255  # alpha
+  palette[1] = [255, 0, 0, 255]  # RED
+  palette[2] = [0, 255, 0, 255]  # GREEN
+  palette[3] = [0, 0, 255, 255]  # BLUE
+  palette[4] = [255, 255, 0, 255]  # YELLOW
+  palette[110] = [110, 110, 110, 255]  # car_color (gray)
+  palette[255] = [255, 255, 255, 255]  # WHITE
+
+  while not rl.window_should_close():
+    rl.begin_drawing()
+    rl.clear_background(rl.Color(64, 64, 64, 255))
+
+    # Render camera (NV12->RGB on GPU via shader)
+    if camera_view.frame:
+      cam_h = 640.0 * camera_view.frame.height / camera_view.frame.width
+    else:
+      cam_h = 480.0
+    camera_view.render(rl.Rectangle(0, 0, 640, cam_h))
+
+    lid_overlay = lid_overlay_blank.copy()
+    top_down = top_down_texture, lid_overlay
+
+    sm.update(0)
+
+    camera = DEVICE_CAMERAS[("tici", str(sm['roadCameraState'].sensor))]
+    calib_scale = camera.fcam.width / 640.0
+
+    if camera_view.frame:
+      num_px = camera_view.frame.width * camera_view.frame.height
+
+    intrinsic_matrix = camera.fcam.intrinsics
+
+    w = sm['controlsState'].lateralControlState.which()
+    if w == 'lqrStateDEPRECATED':
+      angle_steers_k = sm['controlsState'].lateralControlState.lqrStateDEPRECATED.steeringAngleDeg
+    elif w == 'indiState':
+      angle_steers_k = sm['controlsState'].lateralControlState.indiState.steeringAngleDeg
+    else:
+      angle_steers_k = np.inf
+
+    if sm.updated['carState']:
+      plot_arr[:-1] = plot_arr[1:]
+    plot_arr[-1, name_to_arr_idx['angle_steers']] = sm['carState'].steeringAngleDeg
+    plot_arr[-1, name_to_arr_idx['angle_steers_des']] = sm['carControl'].actuators.steeringAngleDeg
+    plot_arr[-1, name_to_arr_idx['angle_steers_k']] = angle_steers_k
+    plot_arr[-1, name_to_arr_idx['gas']] = sm['carState'].gasDEPRECATED
+    # TODO gas is deprecated
+    plot_arr[-1, name_to_arr_idx['computer_gas']] = np.clip(sm['carControl'].actuators.accel / 4.0, 0.0, 1.0)
+    plot_arr[-1, name_to_arr_idx['user_brake']] = sm['carState'].brake
+    plot_arr[-1, name_to_arr_idx['steer_torque']] = sm['carControl'].actuators.torque * ANGLE_SCALE
+    # TODO brake is deprecated
+    plot_arr[-1, name_to_arr_idx['computer_brake']] = np.clip(-sm['carControl'].actuators.accel / 4.0, 0.0, 1.0)
+    plot_arr[-1, name_to_arr_idx['v_ego']] = sm['carState'].vEgo
+    plot_arr[-1, name_to_arr_idx['v_cruise']] = sm['carState'].cruiseState.speed
+    plot_arr[-1, name_to_arr_idx['a_ego']] = sm['carState'].aEgo
+
+    plot_arr[-1, name_to_arr_idx['a_target']] = sm['longitudinalPlan'].aTarget
+
+    # Draw model overlays onto img, then blit as transparent overlay
+    img[:] = 0
+    if sm.recv_frame['modelV2']:
+      plot_model(sm['modelV2'], img, calibration, top_down)
+
+    if sm.recv_frame['radarState']:
+      plot_lead(sm['radarState'], top_down)
+
+    # draw all radar points
+    maybe_update_radar_points(sm['liveTracks'].points, top_down[1])
+
+    if sm.updated['liveCalibration'] and num_px:
+      rpyCalib = np.asarray(sm['liveCalibration'].rpyCalib)
+      calibration = Calibration(num_px, rpyCalib, intrinsic_matrix, calib_scale)
+
+    # Update overlay texture (RGB img -> RGBA with non-black pixels visible)
+    mask = np.any(img > 0, axis=2)
+    overlay_img[:, :, :3] = img
+    overlay_img[:, :, 3] = mask * 255
+    rl.update_texture(overlay_texture, rl.ffi.cast("void *", overlay_img.ctypes.data))
+    rl.draw_texture(overlay_texture, 0, 0, rl.WHITE)  # noqa: TID251
+
+    # display alerts
+    rl.draw_text_ex(font, sm['selfdriveState'].alertText1, rl.Vector2(180, 150), 30, 0, rl.RED)
+    rl.draw_text_ex(font, sm['selfdriveState'].alertText2, rl.Vector2(180, 190), 20, 0, rl.RED)
+
+    # draw plots (texture is reused internally)
+    plot_texture = draw_plots(plot_arr)
+    if hor_mode:
+      rl.draw_texture(plot_texture, 640 + 384, 0, rl.WHITE)  # noqa: TID251
+    else:
+      rl.draw_texture(plot_texture, 0, 600, rl.WHITE)  # noqa: TID251
+
+    # Convert lid_overlay to RGBA and update top_down texture
+    # lid_overlay is (384, 960), need to transpose to (960, 384) for row-major RGBA buffer
+    lid_rgba = palette[lid_overlay.T]
+    rl.update_texture(top_down_texture, rl.ffi.cast("void *", np.ascontiguousarray(lid_rgba).ctypes.data))
+    rl.draw_texture(top_down_texture, 640, 0, rl.WHITE)  # noqa: TID251
+
+    SPACING = 25
+    lines = [
+      ("ENABLED", GREEN if sm['selfdriveState'].enabled else BLACK),
+      ("SPEED: " + str(round(sm['carState'].vEgo, 1)) + " m/s", YELLOW),
+      ("LONG CONTROL STATE: " + str(sm['controlsState'].longControlState), YELLOW),
+      ("LONG MPC SOURCE: " + str(sm['longitudinalPlan'].longitudinalPlanSource), YELLOW),
+      None,
+      ("ANGLE OFFSET (AVG): " + str(round(sm['liveParameters'].angleOffsetAverageDeg, 2)) + " deg", YELLOW),
+      ("ANGLE OFFSET (INSTANT): " + str(round(sm['liveParameters'].angleOffsetDeg, 2)) + " deg", YELLOW),
+      ("STIFFNESS: " + str(round(sm['liveParameters'].stiffnessFactor * 100.0, 2)) + " %", YELLOW),
+      ("STEER RATIO: " + str(round(sm['liveParameters'].steerRatio, 2)), YELLOW),
+    ]
+
+    for i, line in enumerate(lines):
+      if line is not None:
+        color = rl.Color(line[1][0], line[1][1], line[1][2], 255)
+        rl.draw_text_ex(font, line[0], rl.Vector2(write_x, write_y + i * SPACING), 20, 0, color)
+
+    rl.end_drawing()
+
+  rl.unload_texture(overlay_texture)
+  rl.unload_texture(top_down_texture)
+  rl.unload_font(font)
+  camera_view.close()
+  rl.close_window()
+
+
+def get_arg_parser():
+  parser = argparse.ArgumentParser(description="Show replay data in a UI.", formatter_class=argparse.ArgumentDefaultsHelpFormatter)
+
+  parser.add_argument("ip_address", nargs="?", default="127.0.0.1", help="The ip address on which to receive zmq messages.")
+
+  parser.add_argument("--frame-address", default=None, help="The frame address (fully qualified ZMQ endpoint for frames) on which to receive zmq messages.")
+  return parser
+
+
+if __name__ == "__main__":
+  args = get_arg_parser().parse_args(sys.argv[1:])
+
+  if args.ip_address != "127.0.0.1":
+    os.environ["ZMQ"] = "1"
+    messaging.reset_context()
+
+  ui_thread(args.ip_address)

tools/replay/util.cc

@@ -0,0 +1,205 @@
+#include "tools/replay/util.h"
+
+#include <bzlib.h>
+
+#include <cassert>
+#include <cstdarg>
+#include <cstring>
+#include <iostream>
+#include <mutex>
+#include <zstd.h>
+
+#include "common/timing.h"
+#include "common/util.h"
+
+ReplayMessageHandler message_handler = nullptr;
+void installMessageHandler(ReplayMessageHandler handler) { message_handler = handler; }
+
+void logMessage(ReplyMsgType type, const char *fmt, ...) {
+  static std::mutex lock;
+  std::lock_guard lk(lock);
+
+  char *msg_buf = nullptr;
+  va_list args;
+  va_start(args, fmt);
+  int ret = vasprintf(&msg_buf, fmt, args);
+  va_end(args);
+  if (ret <= 0 || !msg_buf) return;
+
+  if (message_handler) {
+    message_handler(type, msg_buf);
+  } else {
+    if (type == ReplyMsgType::Debug) {
+      std::cout << "\033[38;5;248m" << msg_buf << "\033[00m" << std::endl;
+    } else if (type == ReplyMsgType::Warning) {
+      std::cout << "\033[38;5;227m" << msg_buf << "\033[00m" << std::endl;
+    } else if (type == ReplyMsgType::Critical) {
+      std::cout << "\033[38;5;196m" << msg_buf << "\033[00m" << std::endl;
+    } else {
+      std::cout << msg_buf << std::endl;
+    }
+  }
+
+  free(msg_buf);
+}
+
+std::string formattedDataSize(size_t size) {
+  if (size < 1024) {
+    return std::to_string(size) + " B";
+  } else if (size < 1024 * 1024) {
+    return util::string_format("%.2f KB", (float)size / 1024);
+  } else {
+    return util::string_format("%.2f MB", (float)size / (1024 * 1024));
+  }
+}
+
+std::string getUrlWithoutQuery(const std::string &url) {
+  size_t idx = url.find("?");
+  return (idx == std::string::npos ? url : url.substr(0, idx));
+}
+
+std::string decompressBZ2(const std::string &in, std::atomic<bool> *abort) {
+  return decompressBZ2((std::byte *)in.data(), in.size(), abort);
+}
+
+std::string decompressBZ2(const std::byte *in, size_t in_size, std::atomic<bool> *abort) {
+  if (in_size == 0) return {};
+
+  bz_stream strm = {};
+  int bzerror = BZ2_bzDecompressInit(&strm, 0, 0);
+  assert(bzerror == BZ_OK);
+
+  strm.next_in = (char *)in;
+  strm.avail_in = in_size;
+  std::string out(in_size * 5, '\0');
+  do {
+    strm.next_out = (char *)(&out[strm.total_out_lo32]);
+    strm.avail_out = out.size() - strm.total_out_lo32;
+
+    const char *prev_write_pos = strm.next_out;
+    bzerror = BZ2_bzDecompress(&strm);
+    if (bzerror == BZ_OK && prev_write_pos == strm.next_out) {
+      // content is corrupt
+      bzerror = BZ_STREAM_END;
+      rWarning("decompressBZ2 error: content is corrupt");
+      break;
+    }
+
+    if (bzerror == BZ_OK && strm.avail_in > 0 && strm.avail_out == 0) {
+      out.resize(out.size() * 2);
+    }
+  } while (bzerror == BZ_OK && !(abort && *abort));
+
+  BZ2_bzDecompressEnd(&strm);
+  if (bzerror == BZ_STREAM_END && !(abort && *abort)) {
+    out.resize(strm.total_out_lo32);
+    out.shrink_to_fit();
+    return out;
+  }
+  return {};
+}
+
+std::string decompressZST(const std::string &in, std::atomic<bool> *abort) {
+  return decompressZST((std::byte *)in.data(), in.size(), abort);
+}
+
+std::string decompressZST(const std::byte *in, size_t in_size, std::atomic<bool> *abort) {
+  ZSTD_DCtx *dctx = ZSTD_createDCtx();
+  assert(dctx != nullptr);
+
+  // Initialize input and output buffers
+  ZSTD_inBuffer input = {in, in_size, 0};
+
+  // Estimate and reserve memory for decompressed data
+  size_t estimatedDecompressedSize = ZSTD_getFrameContentSize(in, in_size);
+  if (estimatedDecompressedSize == ZSTD_CONTENTSIZE_ERROR || estimatedDecompressedSize == ZSTD_CONTENTSIZE_UNKNOWN) {
+    estimatedDecompressedSize = in_size * 2;  // Use a fallback size
+  }
+
+  std::string decompressedData;
+  decompressedData.reserve(estimatedDecompressedSize);
+
+  const size_t bufferSize = ZSTD_DStreamOutSize();  // Recommended output buffer size
+  std::string outputBuffer(bufferSize, '\0');
+
+  while (input.pos < input.size && !(abort && *abort)) {
+    ZSTD_outBuffer output = {outputBuffer.data(), bufferSize, 0};
+
+    size_t result = ZSTD_decompressStream(dctx, &output, &input);
+    if (ZSTD_isError(result)) {
+      rWarning("decompressZST error: content is corrupt");
+      break;
+    }
+
+    decompressedData.append(outputBuffer.data(), output.pos);
+  }
+
+  ZSTD_freeDCtx(dctx);
+  if (!(abort && *abort)) {
+    decompressedData.shrink_to_fit();
+    return decompressedData;
+  }
+  return {};
+}
+
+void precise_nano_sleep(int64_t nanoseconds, std::atomic<bool> &interrupt_requested) {
+  struct timespec req, rem;
+  req.tv_sec = nanoseconds / 1000000000;
+  req.tv_nsec = nanoseconds % 1000000000;
+  while (!interrupt_requested) {
+#ifdef __APPLE__
+    int ret = nanosleep(&req, &rem);
+    if (ret == 0 || errno != EINTR)
+      break;
+#else
+    int ret = clock_nanosleep(CLOCK_MONOTONIC, 0, &req, &rem);
+    if (ret == 0 || ret != EINTR)
+      break;
+#endif
+    // Retry sleep if interrupted by a signal
+    req = rem;
+  }
+}
+
+std::vector<std::string> split(std::string_view source, char delimiter) {
+  std::vector<std::string> fields;
+  size_t last = 0;
+  for (size_t i = 0; i < source.length(); ++i) {
+    if (source[i] == delimiter) {
+      fields.emplace_back(source.substr(last, i - last));
+      last = i + 1;
+    }
+  }
+  fields.emplace_back(source.substr(last));
+  return fields;
+}
+
+std::string extractFileName(const std::string &file) {
+  size_t queryPos = file.find_first_of("?");
+  std::string path = (queryPos != std::string::npos) ? file.substr(0, queryPos) : file;
+  size_t lastSlash = path.find_last_of("/\\");
+  return (lastSlash != std::string::npos) ? path.substr(lastSlash + 1) : path;
+}
+
+// MonotonicBuffer
+
+void *MonotonicBuffer::allocate(size_t bytes, size_t alignment) {
+  assert(bytes > 0);
+  void *p = std::align(alignment, bytes, current_buf, available);
+  if (p == nullptr) {
+    available = next_buffer_size = std::max(next_buffer_size, bytes);
+    current_buf = buffers.emplace_back(std::aligned_alloc(alignment, next_buffer_size));
+    next_buffer_size *= growth_factor;
+    p = current_buf;
+  }
+
+  current_buf = (char *)current_buf + bytes;
+  available -= bytes;
+  return p;
+}
+
+MonotonicBuffer::~MonotonicBuffer() {
+  for (auto buf : buffers) {
+    free(buf);
+  }
+}

tools/replay/util.h

@@ -0,0 +1,67 @@
+#pragma once
+
+#include <atomic>
+#include <deque>
+#include <functional>
+#include <sstream>
+#include <string>
+#include <string_view>
+#include <vector>
+#include "cereal/messaging/messaging.h"
+
+enum CameraType {
+  RoadCam = 0,
+  DriverCam,
+  WideRoadCam
+};
+
+enum class ReplyMsgType {
+  Info,
+  Debug,
+  Warning,
+  Critical
+};
+
+typedef std::function<void(ReplyMsgType type, const std::string msg)> ReplayMessageHandler;
+void installMessageHandler(ReplayMessageHandler);
+void logMessage(ReplyMsgType type, const char* fmt, ...);
+
+#define rInfo(fmt, ...) ::logMessage(ReplyMsgType::Info, fmt,  ## __VA_ARGS__)
+#define rDebug(fmt, ...) ::logMessage(ReplyMsgType::Debug, fmt,  ## __VA_ARGS__)
+#define rWarning(fmt, ...) ::logMessage(ReplyMsgType::Warning, fmt,  ## __VA_ARGS__)
+#define rError(fmt, ...) ::logMessage(ReplyMsgType::Critical , fmt,  ## __VA_ARGS__)
+
+class MonotonicBuffer {
+public:
+  MonotonicBuffer(size_t initial_size) : next_buffer_size(initial_size) {}
+  ~MonotonicBuffer();
+  void *allocate(size_t bytes, size_t alignment = 16ul);
+  void deallocate(void *p) {}
+
+private:
+  void *current_buf = nullptr;
+  size_t next_buffer_size = 0;
+  size_t available = 0;
+  std::deque<void *> buffers;
+  static constexpr float growth_factor = 1.5;
+};
+
+void precise_nano_sleep(int64_t nanoseconds, std::atomic<bool> &interrupt_requested);
+std::string decompressBZ2(const std::string &in, std::atomic<bool> *abort = nullptr);
+std::string decompressBZ2(const std::byte *in, size_t in_size, std::atomic<bool> *abort = nullptr);
+std::string decompressZST(const std::string &in, std::atomic<bool> *abort = nullptr);
+std::string decompressZST(const std::byte *in, size_t in_size, std::atomic<bool> *abort = nullptr);
+std::string getUrlWithoutQuery(const std::string &url);
+std::string formattedDataSize(size_t size);
+std::string extractFileName(const std::string& file);
+std::vector<std::string> split(std::string_view source, char delimiter);
+
+template <typename Iterable>
+std::string join(const Iterable& elements, const std::string& separator) {
+  std::ostringstream oss;
+  for (auto it = elements.begin(); it != elements.end(); ++it) {
+    if (it != elements.begin()) oss << separator;
+    oss << *it;
+  }
+  return oss.str();
+}