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.
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
timestampis0.A video file's timestamps are its playback positions, the same a video player shows. The frame at 0:12 has a
timestampof12000000000.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
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_atandended_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
Predictions — every field of a prediction
Tracks and Selected Predictions — times that span many frames
Last updated
