Download Hikvision NVR footage by time range with ISAPI, RTSP, and ffmpeg

The simple request is usually something like: "pull the front-door camera from 2:15 to 2:35 yesterday." The implementation is less simple. Hikvision recorders can expose recorded video through ISAPI search/download endpoints and RTSP playback URLs, but firmware differences, channel mapping, auth behavior, and timestamp handling make this easy to get almost right.

Manual workflow

Confirm the recorder exposes ISAPI and RTSP. Hikvision recorders usually need ISAPI and RTSP enabled before automation works. Confirm the agent machine can reach the recorder over the network and that the account has playback/search permission.
Map camera names to channel and stream IDs. Manual exports usually break when a human has to remember whether a camera is channel 1 main stream, channel 1 substream, channel 3 main stream, or a model-specific track ID. Write down the camera name, channel, and expected track IDs before building commands.
Search a wider time window than the requested clip. Some Hikvision firmware returns misleading recording boundaries for narrow searches. A safer workflow searches a padded window, identifies the segment that actually contains the requested time, then clips the output locally.
Prefer direct ISAPI download when available. Direct download is usually faster than RTSP playback. Use it first when the recorder returns a usable download URI and the response content type is actually video.
Fall back to RTSP playback when direct download fails. RTSP playback is slower because it often exports in real time, but it can be the most reliable fallback across older firmware, incompatible response formats, or direct-download quirks.
Verify the resulting MP4. Check codec, resolution, duration, and, when possible, the on-screen-display timestamp. A file that exists is not necessarily the clip the user asked for.

RTSP playback URL shape

A common recorded-playback URL uses the ISAPI streaming path with a track ID plus start and end timestamps. Exact track IDs vary by model and channel layout, so treat this as a shape to validate, not a universal command:

rtsp://USER:PASSWORD@NVR_HOST:554/ISAPI/Streaming/tracks/101?starttime=YYYYMMDDTHHMMSSZ&endtime=YYYYMMDDTHHMMSSZ

In many installations, channel 1 main stream is represented as 101, channel 1 substream as 102, channel 2 main stream as 201, and so on. Mixed DVR/NVR fleets can disagree, so verify against the actual recorder.

Example ffmpeg export

ffmpeg -rtsp_transport tcp \
  -i "rtsp://USER:PASSWORD@192.168.1.50:554/ISAPI/Streaming/tracks/101?starttime=20260626T181500Z&endtime=20260626T183500Z" \
  -map 0:v -c copy -t 1200 front-door-2026-06-26-1815.mp4

This can be enough for a one-off clip. The tradeoff is that RTSP playback often runs at playback speed, while direct ISAPI downloads can be much faster when the recorder returns a valid download URI.

Why narrow searches can betray you

The frustrating failure mode is a search that returns a recording segment near the requested time but not the real segment boundaries. The safer pattern is to search a wider padded range, identify the segment that actually covers the requested window, download that broader recording, then use ffmpeg to clip it precisely.

Failure modes to plan for

The recorder reports a segment that does not actually cover the requested time.
The channel number is right, but the stream or track ID is wrong.
The direct download endpoint returns XML, HTML, or an error payload instead of video.
RTSP works in VLC but fails in ffmpeg because the timestamp format, transport, or credentials differ.
Repeated failed attempts trigger throttling or account lockout.
The MP4 downloads successfully but has the wrong duration or missing frames.

When automation is worth it

If you export a clip once a year, a saved command and a little testing may be fine. If staff, security teams, or integrators need to pull footage repeatedly, the manual workflow becomes a reliability problem: every request depends on somebody remembering channel maps, timestamp formats, fallback behavior, and verification steps.

That is why I built the Hikvision NVR Claude skill. It wraps the search, download, fallback, clipping, credential storage, and verification process so an AI agent can handle requests in plain English and return a checked MP4.