usage: encoderd --clip OUTPUT START DURATION [--bitrate BPS]

Error message

usage: encoderd --clip OUTPUT START DURATION [--bitrate BPS] [--speedup N] [--metadata JSON] SEGMENT [SEGMENT ...]

What it means

Printed by encoderd's main() on comma hardware when invoked as `encoderd --clip ...` with fewer than 6 argv entries — the --clip subcommand needs at least OUTPUT START DURATION plus one SEGMENT (argv[0..5]). It exits with status 2 (usage error). All other arguments are optional flags (--bitrate, --speedup, --metadata) parsed after position 5.

Source

Thrown at openpilot/system/loggerd/encoderd.cc:184

  if (!streams.empty()) {
    std::vector<std::thread> encoder_threads;
    for (auto stream : streams) {
      auto it = std::find_if(std::begin(cameras), std::end(cameras),
                             [stream](auto &cam) { return cam.stream_type == stream; });
      assert(it != std::end(cameras));
      ++s.max_waiting;
      encoder_threads.push_back(std::thread(encoder_thread, &s, *it));
    }

    for (auto &t : encoder_threads) t.join();
  }
}

int main(int argc, char* argv[]) {
#ifdef __COMMA_HARDWARE__
  if (argc > 1 && std::string(argv[1]) == "--clip") {
    if (argc < 6) {
      fprintf(stderr, "usage: encoderd --clip OUTPUT START DURATION [--bitrate BPS] [--speedup N] "
                      "[--metadata JSON] SEGMENT [SEGMENT ...]\n");
      return 2;
    }
    try {
      int bitrate = 5'000'000;
      int speedup = 1;
      std::string metadata;
      int input_arg = 5;
      while (input_arg < argc && std::string(argv[input_arg]).rfind("--", 0) == 0) {
        const std::string option = argv[input_arg++];
        if (option == "--") break;
        if (input_arg == argc) throw std::invalid_argument("missing clip option value");
        if (option == "--bitrate") bitrate = std::stoi(argv[input_arg++]);
        else if (option == "--speedup") speedup = std::stoi(argv[input_arg++]);
        else if (option == "--metadata") metadata = argv[input_arg++];
        else throw std::invalid_argument("unknown clip option: " + option);
      }
      if (input_arg == argc) throw std::invalid_argument("missing clip input");

View on GitHub (pinned to 516ec1e682)

Solutions

Provide all four positionals: encoderd --clip OUTPUT START DURATION SEGMENT [SEGMENT ...], e.g. encoderd --clip clip.mp4 30 10 5 --speedup 2.
Note START/DURATION are std::stod-parsed seconds — pass numeric strings, not timestamps.
List multiple SEGMENT numbers consecutively (they are joined) instead of separate runs.

Example fix

# before
encoderd --clip clip.mp4 30 10        # argc=5 -> usage error, exit 2

# after
encoderd --clip clip.mp4 30 10 5      # OUTPUT START DURATION SEGMENT

Defensive patterns

Strategy: validation

Validate before calling

#!/bin/sh
# require: encoderd --clip OUTPUT START DURATION SEGMENT...
[ $# -ge 4 ] || { echo 'need OUTPUT START DURATION SEGMENT'; exit 2; }
case "$2" in ''|*[!0-9.]*) echo 'START must be seconds'; exit 2;; esac
case "$3" in ''|*[!0-9.]*) echo 'DURATION must be seconds'; exit 2;; esac
encoderd --clip "$@"

Prevention

Count arguments before calling: argc must be >= 6 including program and --clip.
Pass START/DURATION as numeric seconds and at least one SEGMENT number.

When it happens

Trigger: Running `encoderd --clip out.mp4 0` (missing DURATION and SEGMENT), `encoderd --clip out.mp4 10 5` (missing SEGMENT — argc==5 fails the <6 check), or forgetting OUTPUT entirely. Only reachable in builds with __COMMA_HARDWARE__ defined.

Common situations: Typos in clip-extraction wrapper scripts on a comma device, changing the argument order, or assuming SEGMENT is optional because DURATION already bounds the clip.

Related errors

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