Time Differential

Good Afternoon,

We are currently trying to retrieve screenshots from timestamps/event alerts. In most cases, the requested timestamp is either the current time or within the last few seconds (typically less than 5 seconds old).

During testing, we observed that the image returned by the API is consistently offset from the requested timestamp. The returned frame can differ by 1–15 seconds, with the majority appearing around 10 seconds off from the exact timestamp requested. As a result, the image received does not accurately correspond to the timestamp passed in the request.

Testing across a range of timestamps, including current-time requests as well as requests going back several seconds and minutes. When comparing the requested timestamp against the timestamp displayed directly on the returned camera frame. The results consistently showed a measurable offset between the requested frame time and the actual frame returned, confirming that the behavior is reproducible and not isolated to a single event or request.

For reference, I am attaching a CSV containing the detailed test results. The primary columns included are:

time_of_request — Wall-clock time when the HTTP request was sent
requested_time — The timestamp provided to the API request
difference — The age of the requested frame at the time the request was sent (time_of_request − requested_time)
time_received — The timestamp displayed directly on the returned camera image
time_diff_seconds — The variance between the requested timestamp and the timestamp of the returned frame (time_received − requested_time)

At this time, we are trying to determine what is causing this offset, we have confirmed that the timeline is accurate and that they display the correct time when going through the timeline and cameras. When we get images from email alert triggers, they seem to be within 1-3 seconds of the trigger. The API we are using to grab the image is below, is this correct or should we be trying to use a different API? Any help with this would be greatly appreciated.

/rest/v4/devices/{camera_id}/image?timestampMs={timestamp_ms}

Ichiro

Network Optix team

June 10, 2026 09:27

Hi there,

Thanks for raising this! I wanted to share a few context that should help explain the behavior you're seeing.

Codec / I-frames — Thumbnails can only be generated from full images (I-frames) by default. If the timestamp you request doesn't land exactly on an I-frame, the mediaserver has to find the closest one and return that instead. This is how the compression and codec work, not an issue with the server.

Recording mode — If you're using motion recording and the requested timestamp falls within a "no motion" period (i.e. nothing was recorded), the server has no frame at that exact moment to give you, so it returns the closest available one from the existing recording.

On my side, I tested this on 6.1.2 and wasn't able to reproduce the problem (see the GIF (it is on google drive link):

With always recording, there's always footage for the requested timestamp, and it returns the proper thumbnail.

With motion recording, when I intentionally request a timestamp with no recording, it returns the closest I-frame — which may be either before or after the requested time.

This behavior hasn't changed since v3.0. A couple of suggestions that might help:

You can add roundMethod=precise to keep the timestamp tight. That said, if the requested timestamp has no I-frame or no recording, the server will still need to fall back to the closest I-frame.
The most reliable approach is to check the recording first and then request the snapshot with a valid timestamp. You can always confirm whether footage exists via the API: /rest/v4/devices/{id}/footage. (Whether this fits depends on your use case.)

One last note for next time: To help us understand and troubleshoot issues quickly, it really helps to include things like the server version, reproduction steps, and screen captures. That way others can get up to speed fast and offer solutions too.

BTW : there wasn't a file attached to your post(?..)

Hope this helps.

Time Differential

Comments

Didn't find what you were looking for?