For the complete documentation index, see llms.txt. This page is also available as Markdown.

Temporal Attributes

How a prediction says when — timestamp, duration and captured_at, and which to use for what

A prediction says when as well as where. There are two different clocks behind that: the media's own timeline, which starts at zero and counts through the video, and the real time a camera captured a frame. They answer different questions, and mixing them up is the most common mistake when correlating predictions with anything else.

All times are integers in nanoseconds: 1 second is 1000000000.

A timeline from 0 to 10 seconds. Each live prediction covers one frame, starting at its timestamp and lasting its duration. Above it, the camera clock gives captured_at from 09:30:02 on; before that it is not known yet. A motion runs from begin_timestamp at 1 s to finished_timestamp at 7 s. A track runs from started_at at 2 s to ended_at at 6 s; its start is reported on the prediction at 3 s and its end later, on the prediction at 8 s. A selected prediction carries the timestamp of the live 4 s prediction but arrives after the live 8 s prediction, so the arrival order is 0 to 8 s, then 4 s, then 9 s.
Every time a prediction can carry, on one timeline.

Position in the media: timestamp

timestamp is where the frame sits on the media's timeline, counted from its start. A video recorded at 24 frames per second produces predictions like these:

  • A single image has one moment, so its timestamp is 0.

  • A video file's timestamps are its playback positions, the same a video player shows. The frame at 0:12 has a timestamp of 12000000000.

  • A live stream's timestamps count through the stream as EyePop receives it. They order the frames and measure the time between them, but they say nothing about the time of day.

timestamp is always present. It is the key to order a source's predictions by, and to find the frame a prediction belongs to when you go back to the video.

Convenience: seconds

seconds is the same position as timestamp, in seconds, for display and logging. Compare and store timestamp: seconds is a floating-point copy and can differ from it in the last digits.

Length of the frame: duration

duration is how long the frame stands for on the timeline: the time until the next processed frame. At 24 frames per second that is 41666666 nanoseconds. A single image has no duration.

With fps set lower than the video's own rate, the Pop skips frames, and each frame it processes stands for the frames skipped after it. The same 24 fps video at fps="5/1":

The timestamp values stay on the video's own frames, about 0.2 seconds apart, and duration is the 0.2 seconds each one covers.

Real time of capture: captured_at

captured_at is the moment a camera captured the frame, on the camera's own clock, in nanoseconds since the Unix epoch (1970-01-01 UTC). It appears only on frames from a camera that provides its clock, such as an RTSP camera that sends RTCP sender reports:

This frame is 75 seconds into the stream, and the camera captured it at 2026-10-30 21:13:00.812 UTC.

Unlike timestamp, captured_at can be compared across sources and against anything outside EyePop: another camera, a door sensor, a point-of-sale log. Network and buffering delay between the camera and EyePop vary, and captured_at is unaffected by both.

captured_at is left out, never guessed, when the capture time is not known: on a file, on a camera without a usable clock, and for the first moments of a stream, before the camera's first clock reference arrives. Private Cameras describes when a camera provides it.

Which time to use

To…
Use

Order the predictions of one source

timestamp

Find the frame in a video file, or cut a clip around it

timestamp

Show a position to a person

seconds

Measure how long something lasted in the media

the difference of two timestamp values

Match frames from different cameras, or with sensors and logs

captured_at

Know the time of day a live frame was taken

captured_at

Times inside a prediction

Some results carry times of their own. They are on the same timeline as timestamp:

  • A track event says when a tracked object was first and last seen, as started_at and ended_at.

  • A motion says when motion began, as begin_timestamp.

A selected prediction reports about a frame from the past. Its timestamp, duration and captured_at are that frame's, so it arrives later than predictions with a later timestamp.

Example: print the times of a prediction

JavaScript numbers hold integers exactly only up to 253, about 9 × 1015. A captured_at is about 1.8 × 1018, so in JavaScript it is precise to roughly a quarter of a microsecond, far finer than any frame rate.

Next steps

Last updated