Ask your AI agent in plain English for "lobby camera footage from 8 to 9 PM yesterday" and get back an MP4.
See it in action
The short version
This is for the moment when somebody asks for camera footage and you do not want to open the Hikvision web UI, guess the channel number, fight with ISAPI XML, copy an RTSP playback URL into ffmpeg, and then verify whether the exported clip actually covers the requested time.
You register each NVR once with a short alias. After that, your AI agent can handle requests like:
Pull the front-door camera from 2:15 PM to 2:35 PM yesterday and save it as an MP4.
The skill searches the recorder, chooses the best download strategy, clips the recording to the requested time window, verifies the output, and reports progress in a format another agent can summarize while the download runs.
What it actually does
- Speaks Hikvision natively. ISAPI search/download, RTSP playback fallback, and a working understanding of the protocol's quirks (Content-Type variants, lying narrow-search results, NVR account lockouts, NI-vs-HQHI schema differences).
- Intelligent strategy ladder. Tries ISAPI first (fast network speed), backs off and retries on throttling, can optionally reboot the recorder only if you explicitly allow it (off by default), and falls through to RTSP playback if all else fails. Every transition is announced as a structured progress event.
- Wide-search + clip. Works around a documented Hikvision behavior where narrow ISAPI searches return falsified segment boundaries. Searches a padded window, finds the true segment, downloads it, and ffmpeg-clips to within a second or two of the requested time.
- Built for AI agents. Emits NDJSON progress events so your agent can dispatch a download as a background task, stream summarized status, and stay responsive.
SKILL.mddocuments the exact dispatch pattern. - Secure credential storage. Onboarding picks between your OS keyring (Windows Credential Manager / macOS Keychain / Linux Secret Service) and a local
.envfile for headless use. NVRs are registered by short aliases; credentials never appear in command lines or logs. - Guided setup. Onboarding opens a real terminal for credential entry and can install ffmpeg for you (with your confirmation, via winget, Homebrew, or apt), so you are not left hunting for prerequisites.
- Verification built in. Each downloaded MP4 is checked with ffprobe for codec, resolution, duration, and frame rate, and—when Pillow and tesseract are available—its on-screen-display timestamp.
- Flexible file organization. Flat, per-day, per-camera, or per-day-per-camera layouts, set once during onboarding.
Who it's for
Anyone with a Hikvision (or compatible OEM) DVR/NVR fleet who would rather say "pull the front-door camera at 2:30 yesterday" than wrestle with ISAPI XML and ffmpeg flags. Security teams pulling evidence clips, integrators automating routine exports, anyone who wants their AI to handle the protocol layer.
Good fits include:
- Security teams that export evidence clips often enough for the manual process to hurt.
- Integrators who support several Hikvision or OEM recorder models.
- Businesses that need a non-technical person to request footage without learning camera-channel maps.
- Developers building an agent workflow around recorded camera footage.
What sets it apart
Most Hikvision download tools (HikLoad, hikvision-download-assistant) generate curl commands or run a one-shot CLI. This skill is designed for an AI agent to drive it: clean JSON contracts, typed error classifications (AuthError, NoRecordingsError, ThrottledError, LockedOutError), explicit instructions on when to fall back to RTSP, when to retry, when to bail. Validated across four recorder models spanning firmware V3.1.10 through V4.50.000.
Common problems it handles
| Problem | Why it matters | How the skill handles it |
|---|---|---|
| Wrong clip boundaries | Some recorders report misleading segment start and end times for narrow searches. | Searches a wider padded window, finds the true recording segment, then clips locally. |
| Confusing channel IDs | Main stream and substream IDs vary by channel and model family. | Keeps camera aliases and recorder mapping out of the user's prompt. |
| Slow RTSP playback | RTSP can work when direct download fails, but it often exports in real time. | Uses ISAPI download first when possible and falls back to RTSP only when needed. |
| Throttling and lockouts | Repeated auth/download attempts can slow or lock a recorder. | Classifies auth, throttling, and lockout states so the agent can stop or retry appropriately. |
| Verifying the result | A downloaded MP4 is not useful if it is corrupt or from the wrong time. | Checks codec, resolution, duration, and optional on-screen-display timestamp. |
Tested on
- DS-9016HWI-ST, DS-7316HQHI-SH, DS-7716NI-I4/16P, DS-9632NI-ST
- Firmware spread from V3.1.10 through V4.50.000
- Other Hikvision and OEM-rebrand recorders that speak ISAPI should work too.
Compatibility notes
The skill is built around Hikvision DVRs/NVRs and compatible OEM recorders that expose ISAPI and RTSP. It has been validated across older DVR firmware, newer NI-family NVRs, and mixed fleets where model families do not return the exact same XML shape.
It uses the open Agent Skills (SKILL.md) standard, so it works natively in Claude (Code, Desktop, and web) and OpenAI Codex, plus Gemini CLI, Cursor, GitHub Copilot, OpenClaw, Hermes, and any other SKILL.md-compatible AI assistant.
Recommended environment:
- Windows, macOS, or Linux with Python 3.10+.
ffmpegandffprobeavailable on PATH.- Network access from the agent machine to the recorder.
- A recorder account with permission to search and play back recorded footage.
- RTSP enabled for fallback playback.
If you are not sure whether your recorder is a fit, send the model number and firmware version through the contact form and I can sanity-check it before you buy.
Run a different brand of recorder?
If your cameras run on Dahua or a Dahua-protocol OEM (IC Realtime, newer Lorex, Amcrest, Honeywell Performance, EZVIZ business line), use the Dahua / IC Realtime NVR skill instead.
Related technical guide
Want the manual version first? Read Download Hikvision NVR footage by time range with ISAPI, RTSP, and ffmpeg. It explains the workflow this skill automates.
FAQ
Does this replace Hikvision's web UI?
No. It automates a specific pain point: finding and exporting recorded footage by time range. The web UI still exists for administration, live view, and normal recorder management.
Which AI agents does it work with?
It uses the open Agent Skills (SKILL.md) standard, so it works natively in Claude (Code, Desktop, and web) and OpenAI Codex, plus Gemini CLI, Cursor, GitHub Copilot, OpenClaw, Hermes, and any other SKILL.md-compatible assistant.
Does it work without internet access?
Yes, the recorder workflow is local-network friendly. You still need whatever your AI agent environment requires, but credentials and camera traffic do not need to be exposed publicly.
Where are NVR passwords stored?
In your OS keyring when possible (Windows Credential Manager / macOS Keychain / Linux Secret Service), or in a local .env file for headless setups. On macOS and Linux that file is restricted to your user account (permissions 0600). The skill uses short aliases in prompts and logs, and credentials never appear on command lines.
Why not just use ffmpeg with an RTSP URL?
You can, and sometimes that is enough. The hard parts are finding the right recording segment, mapping channels correctly, handling firmware quirks, falling back when ISAPI fails, and verifying the exported MP4. That is what the skill packages for an agent.
Can it pull footage from more than one NVR?
Yes. Recorders are registered by alias, so a prompt can refer to a known site, recorder, or camera name instead of an IP address.
What happens if there is no recording for the requested time?
The skill returns a typed NoRecordingsError so the parent agent can tell the user clearly instead of pretending a download failed for some unrelated reason.