A recording can play perfectly and still be unusable: the first seconds of frames carry timestamps counted from power-on, and every frame after one boundary is counted from the 1970 epoch. This guide is for anyone joining recorded camera streams to robot logs, PLC events or a second camera. You will classify each stamp by scale, find the switch frame, compute the single offset that maps the early stamps onto wall time, and set up the next recording so the mix cannot happen. The frames themselves are never lost — only the stamps need repair.
What a mixed-epoch recording looks like
The tell is scale. A stamp counted since boot is small: 257162167000 ns is 257.162167 s, about four minutes of uptime. A wall-clock stamp in nanoseconds is enormous by comparison: 1762106032377000000 ns is 1762106032.377 s since 1970. In C++ terms these are std::chrono::steady_clock and std::chrono::system_clock values, both printed in nanoseconds.
Play the stamps back as a series and the switch stands out. On a 30 fps stream the expected step between frames is 33333333 ns (1e9 / 30). A jump of 1762105775214833000 ns between two adjacent frames is 5.3 × 10^10 frame periods, which no dropped-frame gap explains. The switch lands on a single frame boundary, and on a multi-camera rig every file crosses at the same instant, because all recorders read the same host clock.
Why it happens, in order of probability
- Recording started before the host clock was set. A freshly booted machine runs with the system clock unset or far off until time sync completes. Capture stacks that stamp frames with the system clock have no valid wall time in that window, so many fall back to the monotonic clock, then switch the moment sync lands. Test: boot with the network unplugged, start a recording, reconnect, and watch the switch appear at reconnection. The stamping clock is rarely a setting you can flip in the capture library; the fix lives at the start of your pipeline.
- Two stamping paths feed one file. A driver writes one scale and your recorder appends its own. Test: check whether the two scales alternate by frame index instead of switching exactly once.
- Your reading code assumes one epoch. The file is consistent and the conversion on readback is what mixes them. Test: pull raw stamps from an early and a late frame with no conversion and compare their magnitude.
Classify every stamp with one threshold
Below 1e17 ns the stamp is monotonic; at or above, it is wall time. The basis: 1e17 ns is 1e8 s, about 3.2 years of unbroken uptime, which a recorder does not reach, while wall time passed 1e17 ns in 1973 and today sits near 1.76e18 ns. The rule holds for any recording made now.
To locate the switch, binary-search the frame index for the first stamp above the threshold: 12 reads for a 4,096-frame file. Frames before the boundary get repaired; frames after it need nothing. Why the two clocks disagree in the first place is its own subject: camera frame timestamp vs system time.
Fix: one offset repairs the early frames
Take the pair that straddles the boundary: the last monotonic stamp, 257162167000 ns, and the first wall stamp one frame later, 1762106032377000000 ns. The frames are 33333333 ns apart at 30 fps, so treating them as simultaneous costs at most that much error — well inside any alignment tolerance.
boot_epoch_ns = 1762106032377000000 - 257162167000 = 1762105775214833000 ns
That value is the boot moment in wall time: 1762105775.214833 s since 1970, which is 17:49:35 UTC on 2025-11-02. Add it to every monotonic stamp. Check on a frame you did not use: 260000000000 ns becomes 1762105775214833000 + 260000000000 = 1762106035214833000 ns, which is 260 s after boot — consistent.
On a multi-camera rig the host clock is shared, so compute the offset once and apply it to every file; the boundary frame index can differ per stream, the offset cannot.
Keep the next recording clean
- Gate the recorder on time sync. Poll the host clock until its offset against a reference settles below 10 ms, then open files. On a machine that reaches the network in seconds, that idle time costs nothing.
- Stamp from one clock yourself. Write monotonic nanoseconds per frame plus one anchor record at file open holding wall and monotonic together. Intervals stay exact no matter what the clock does later.
- Use one stamping path for every camera, so all files share an epoch by construction.
Which timebase to use at playback
Keep native stamps for anything frame-paced: encoder rate control, drop detection, frame counting — the monotonic segment is exact. Map to wall time at export, or when joining against logs that carry wall time, with the offset above; the recorded frames mapped to PC time article covers the general mapping.
The one real hazard is a clock step mid-recording: classic NTP implementations step the clock instead of slewing once the offset exceeds about 128 ms, and a step shifts every later stamp. If your network can step, write a fresh anchor every few minutes. Where processor time fits against wall time in benchmarks, CPU time vs wall-clock time separates the two.
When the stamps break differently
Three failure modes look alike and fix differently. An epoch mix is one huge upward jump with clean intervals on both sides — the case above. A wrapped counter falls to near zero mid-file: see camera timestamp clock rollover and monotonic time mapping. Stamps that freeze or repeat point at the stamping source, not the clock: see the frozen or jumping clock source fix. Two streams that disagree per frame, rather than at one boundary, are a sync problem — align by device timestamp, not queue order, as in syncing RGB and depth frames by device timestamp.
Next step
Recordings are only as good as the cameras feeding them. Compare area scan cameras and 3D sensors in the camera finder, start a rig at the camera step of the configurator, or write to us via the contact page with your frame rates and sync setup. The systems guides collect the rest of the timing material.
Questions
Why do all cameras in a multi-camera rig switch clocks at the same frame?
They read the same host clock. The switch is not a per-camera fault; it is the moment the operating system applied time sync, which every recording process observes simultaneously. Frame indices at the boundary can differ between files because frame rates differ, but the wall-clock second of the switch is identical across the set, so one computed offset repairs every file.
How can I tell monotonic and Unix timestamps apart by eye?
Divide by 1e9. A wall-clock value in seconds is about 1.76 × 10^9 today and grows every year; a monotonic value in seconds equals the machine's uptime, typically seconds to weeks. Any nanosecond stamp under 1e17 is uptime by this rule, since wall time passed that mark in 1973 and uptime needs 3.2 unbroken years to reach it.
Does the clock switch damage the recorded frames?
No. Every pixel and every frame interval survives; only the epoch of the stamps changes at one boundary. After you add the computed offset to the early stamps, the whole file plays back on one timeline at the original frame rate. Nothing needs re-recording unless the file also lost frames, which the interval check in this guide would reveal.
Why not stamp everything with wall clock and skip the offset math?
Wall time moves. NTP corrections step or slew the clock during long recordings, so equal frame intervals stop looking equal, and a correction can even run stamps backward. A monotonic stamp plus one recorded anchor gives exact intervals and a stable map to wall time; you choose which view to use at playback instead of inheriting whatever the clock did mid-file.
How much can NTP move the clock during a recording?
Routine corrections slew by milliseconds, which a mapping built from one anchor absorbs without visible error. Classic NTP implementations step the clock instead once the offset exceeds about 128 ms, for example after a long network outage, and a step shifts every later stamp by that amount. Write a fresh anchor after any known step, or every few minutes.