Skip to content

egocap: drop the capture_unix_us timestamp basis - #1525

Merged
gareth-morgan-nv merged 1 commit into
mainfrom
gmorgan/EgocapDropCaptureUnix
Nov 16, 2026
Merged

gareth-morgan-nv merged 1 commit into
mainfrom
gmorgan/EgocapDropCaptureUnix

Conversation

@gareth-morgan-nv

@gareth-morgan-nv gareth-morgan-nv commented Nov 13, 2026 •

Copy link
Copy Markdown
Contributor

Summary

  • Removes the capture_unix_us timestamp basis from egocap: the streams-file loader, the Orin emulator's --timestamp-basis choices, the LiveKitTimestampBasis enum member (wire value 3 is no longer assigned), the docs and the tests that exercised it.
  • processing_unix_us stays: the Jetson sender still publishes it.

Why

No publisher stamps capture_unix_us any more. The camera bridge now publishes either the frame-ready time or the chrony-qualified capture time, both on the publisher's monotonic clock (see the bridge PR that removes it), and the Jetson sender's choices are monotonic_us, capture_monotonic_us and processing_unix_us. The basis was never recordable, since no Unix-clock mapping is part of the synchronization path; keeping it only let a streams file declare a basis nothing produces.

A streams file that names capture_unix_us is now rejected with the existing "timestamp_basis must be one of ..." error.

Validation

  • 411 Python tests pass under examples/egocap/tests (the LiveKit streams loader, emulator, recording and receiver tests, plus every other test that mentions timestamp_basis).
  • ruff and the repository pre-commit hooks pass on the changed files.
  • Not run: the frontend captureProtocol vitest (no node dependencies installed here). The frontend defines only the monotonic basis constants, so it is not changed.

🤖 Generated with Claude Code

Summary by CodeRabbit

  • Changes
    • Removed support for Unix-time sensor capture timestamps from the emulator and capture configuration. The remaining options are publisher monotonic, publisher processing Unix, and sensor capture monotonic timestamps.
    • Updated documentation and examples to reflect the available timestamp options and recording behavior.

No publisher stamps it any more: the camera bridge publishes the frame-ready time
or the chrony-qualified capture time, and the Jetson sender's choices are
monotonic_us, capture_monotonic_us and processing_unix_us. Streams files and the
emulator no longer accept it, and wire value 3 is no longer assigned.

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
Signed-off-by: Gareth Morgan <gmorgan@nvidia.com>
@coderabbitai

coderabbitai Bot commented Nov 13, 2026 •

Copy link
Copy Markdown
Contributor

Explain Change →

No actionable comments were generated in the recent review.

Walkthrough

The change removes capture_unix_us from accepted LiveKit stream configuration and Orin emulator timestamp options. LiveKitTimestampBasis no longer represents wire value 3. Documentation and tests now cover the remaining timestamp bases.

Estimated code review effort: 2 (Simple) | ~10 minutes

Merge Risk: Minimal · up to e7675

This change removes an unused, unrecordable timestamp basis and updates the docs and tests to match. Streams files that still name capture_unix_us will now be rejected with the existing validation error. The change is low risk to merge.

Security architecture risk: Minimal · up to e7675

The removed basis is rejected explicitly rather than reinterpreted. Remaining wire values and recording restrictions are preserved. The inspected change establishes no introduced or worsened risk to security, failure containment, rollback, or ownership guarantees.

Retained concerns
No architecture-level concerns identified.

Security review details

Trust Boundaries and Controls

  • observed — The existing recording boundary remains restrictive: only the two monotonic bases are recordable. Admission rejects other bases, and the per-stream feed independently rejects them before receiving frames or offering samples to recording ingress. Processing Unix remains outside the recording allowlist.

Resilience and Maintainability Implications

  • observed — Unchanged downstream checks stop the recording feed on publication replacement, missing timestamps, clock discontinuity, unavailable or overly uncertain mappings, or implausible mapped frame times. Sample submission remains after those checks; removing the enum member does not introduce a fallback timestamp path.
Pre-merge checks: Passed 4

Check name Status Explanation
Description Check Passed Check skipped - CodeRabbit’s high-level summary is enabled.
Title check Passed The title names the main change: removing the capture_unix_us timestamp basis. The raw summary and objectives confirm that the enum member, the emulator choices, the streams-file loader, docs, and tes…
Linked Issues check Passed Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check Passed Check skipped because no linked issues were found for this pull request.
Full details: Title check

Explanation

The title names the main change: removing the capture_unix_us timestamp basis. The raw summary and objectives confirm that the enum member, the emulator choices, the streams-file loader, docs, and tests all drop this basis. Nothing in the title is off-topic.

Finishing Touches

Generate unit tests (beta)

  • Commit to this branch
  • Create a new PR
  • Autofix · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts
Recent review info

Run configuration

Commits

Reviewing files that changed from the base of the PR and between 7f6f5f0 and e767543.

Files selected for processing: 9

  • examples/egocap/LIVEKIT_PREVIEW.md
  • examples/egocap/capture_server/README.md
  • examples/egocap/capture_server/capture_server/livekit_streams.py
  • examples/egocap/capture_server/capture_server/protocol.py
  • examples/egocap/tests/backend/test_livekit_recording.py
  • examples/egocap/tests/backend/test_livekit_recording_source.py
  • examples/egocap/tests/capture_server/test_livekit_streams.py
  • examples/egocap/tests/tools/test_livekit_orin_emulator.py
  • examples/egocap/tools/livekit_orin_emulator.py
Files with no reviewable changes: 3

  • examples/egocap/capture_server/capture_server/livekit_streams.py
  • examples/egocap/capture_server/capture_server/protocol.py
  • examples/egocap/tests/backend/test_livekit_recording_source.py

Included review availability: This review used your included allowance. Your plan provides up to 12 included reviews per hour; 11 remain after this review.

@gareth-morgan-nv

Copy link
Copy Markdown
Contributor Author

@NVdejung @NVshawnhwang this removes the capture_unix_us timestamp basis from egocap now that the camera bridge no longer publishes it (the bridge change is in #1519). Recording already refused it, so this only drops the unused option from the streams-file loader, the emulator, the wire enum (value 3 is no longer assigned), the docs and the tests. processing_unix_us is unchanged. Could you review?

@NVdejung NVdejung left a comment

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🤖 Automated first-pass review (Claude, for Dejun) — I'll follow up personally where needed.

Summary — This PR removes the capture_unix_us timestamp basis from egocap: the streams-file loader, LiveKitTimestampBasis value 3, the Orin emulator's --timestamp-basis, the docs and the tests. The removal is complete. Nothing in the repository (Python, frontend, docs, example configs) still names the basis, and recording is unaffected because it already allowlisted only the two monotonic bases (backend/egocap_web/livekit_recording.py:54). I found no blockers. The main follow-up is to reserve value 3 so it is never reused. I read the code but did not run the tests.

Must fix
None found.

Suggestions (paths are under examples/egocap/)

  • Reserve wire value 3 and pin it with a test. capture_server/README.md:576 already lists retired values ("unused StopReason values 2, 3 and 5 are reserved"). Add LiveKitTimestampBasis 3 to that sentence. A one-line "3 was SENSOR_CAPTURE_UNIX_US, do not reuse" comment in the enum at capture_server/capture_server/protocol.py:216 would also help. Also add {"timestamp_basis": 3} next to 0 and 5 in test_livekit_camera_stream_rejects_bad_fields (tests/capture_server/test_livekit_streams.py:127). As changed, the tests would still pass if 3 were given a new meaning. Today, a peer that still sends 3 gets its whole SessionInit rejected (protocol.py:1870), which is safe. If 3 is reassigned later, an older capture server's stream would be misread without any error.
  • Emulator help text that was not updated. In tools/livekit_orin_emulator.py:102, the --clock-offset-ms help still says it "applies to the Unix bases", but only processing_unix_us is left. The matching test was renamed to ..._the_unix_basis_...; the help was not. At :115, --pipeline-delay-ms now only shifts capture_monotonic_us. Naming that basis in the help would stop people setting the flag with the default monotonic_us and seeing no effect.
  • Test leftovers. tests/backend/test_livekit_recording.py:415 and :854 keep a basis = PROCESSING local from the old parametrization; inline it. test_non_monotonic_basis_is_still_refused (:853) now checks the same thing as test_unrecordable_reason_names_a_stream_that_is_not_monotonic (:840) and could be dropped.
  • Check before merging. A streams file that still declares capture_unix_us now stops the whole capture server at startup with exit code 2 (capture_server/capture_server/server.py:2275), not just that stream. The description says nothing publishes this basis any more. Still, confirm that no deployed station's streams file names it, for example one written for the bridge before #1519.

Conflicts

  • With main: the PR is 0 commits behind and there are no 3-way conflicts, so no rebase is needed. GitHub's "blocked" state comes from branch protection, not a conflict.
  • With open PRs: #1520 (same author) shares tests/backend/test_livekit_recording_source.py. It targets another feature branch rather than main, so textual conflicts were not computed. This PR deletes the UNIX_CAPTURE constant and the stream-22 line in test_only_monotonic_streams_with_full_geometry_are_recordable. Whichever of the two lands second should rebase and check that it adds no UNIX_CAPTURE or SENSOR_CAPTURE_UNIX_US use; once the member is gone, either would fail when the test runs.
Change-by-change (9 files)
File / area What changed Makes sense?
capture_server/capture_server/protocol.py Drops SENSOR_CAPTURE_UNIX_US = 3 and its comment; the class docstring (recording accepts 1 and 4) is still accurate ✅ (value 3 should be reserved, see suggestions)
capture_server/capture_server/livekit_streams.py Drops capture_unix_us from _BASES, so the loader's existing "must be one of" error now covers it ✅ intended; such a file now stops the server at startup
capture_server/README.md Enum table, timestamp_basis field row, YAML comment and name-to-value sentence drop 3; now says "2 is preview only" ✅ (the reserved-values sentence at L576 was not updated)
LIVEKIT_PREVIEW.md Emulator --timestamp-basis values updated ✅ nit: the emulator and the Orin sender now take the same three values, so the two sentences could be merged
tools/livekit_orin_emulator.py _CAPTURE_BASES is now capture_monotonic_us only; --timestamp-basis choices and help updated ⚠️ the help for --clock-offset-ms and --pipeline-delay-ms was not updated
tests/capture_server/test_livekit_streams.py Wire-stability, JSON round-trip and loader-accept cases drop 3; capture_unix_us is added to the loader's rejected names ✅ (but the wire value 3 is not in the rejected list)
tests/tools/test_livekit_orin_emulator.py capture_unix_us cases removed; drift test moved to processing_unix_us (same numbers, since that model has no offset or delay); offset test renamed ✅ the delay-at-capture path is still asserted through monotonic_us and capture_monotonic_us
tests/backend/test_livekit_recording.py UNIX_CAPTURE removed; two parametrized tests reduced to PROCESSING ⚠️ leftover locals and one test that is now a duplicate
tests/backend/test_livekit_recording_source.py UNIX_CAPTURE and its stream 22 removed from the recordable-filter test ✅
Unchanged consumers (checked) backend/egocap_web/livekit_recording.py allowlists only 1 and 4. frontend/src/captureProtocol.ts:364 reads the basis as a bounded integer and defines constants only for 1 and 4 ✅ the frontend vitest that was not run is not affected

Reviewed at e767543 · 9 files · 2026-11-13 15:45 PST

@NVshawnhwang

Copy link
Copy Markdown
Collaborator

Automated review

The PR removes the capture_unix_us basis and the SENSOR_CAPTURE_UNIX_US enum member from the streams loader, protocol, emulator, docs and tests. A repo-wide case-insensitive grep finds no leftover references except the test asserting the value is now rejected. The docs, the emulator's _CAPTURE_BASES and the README tables are consistent. I found no correctness problems.

No issues found.

✅ Nothing blocking left from my side — auto-review of this one is now finished.


🤖 Sent by Shawn's Claude — automatic reply. Shawn hasn't reviewed this personally yet; treat it as a first pass.

@gareth-morgan-nv
gareth-morgan-nv merged commit 716acd0 into main Nov 16, 2026
43 checks passed
@gareth-morgan-nv
gareth-morgan-nv deleted the gmorgan/EgocapDropCaptureUnix branch November 16, 2026 23:36

This branch was successfully deployed

1 active deployment
dev — e7675435 Deployed Nov 14, 2026 by gareth-morgan-nv via publish-wheel #6922
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

Projects

None yet

Development

Successfully merging this pull request may close these issues.

4 participants