tedyst/hikload

Download videos from a HikVision DVR/NVR

HikLoad

A collection of short Python scripts that utilize the ISAPI specification for Hikvision DVR/NVRs/Cameras.

Using the UI

If you want to use the new interface written in Qt, you can use the command hikload-qt after installing using one of the recommended methods (only pip and source).

Using the terminal

To use your own DVR it is usually only needed to change the arguments for the script. The first parameter is the IP, the second one is the username and the third is the password. Here are all of the possible parameters:

usage: main.py [-h] [--server SERVER] [--username USERNAME] [--password PASSWORD] [--starttime STARTTIME] [--endtime ENDTIME] [--folders {onepercamera,oneperday,onepermonth,oneperyear}]
               [--debug | --no-debug] [--videoformat {mkv,mp4,avi}] [--downloads DOWNLOADS] [--frames FRAMES] [--force | --no-force] [--skipseconds SKIPSECONDS] [--seconds SECONDS] [--days DAYS]
               [--skipdownload | --no-skipdownload] [--allrecordings | --no-allrecordings] [--cameras CAMERAS] [--localtimefilenames | --no-localtimefilenames] [--yesterday | --no-yesterday]
               [--ffmpeg | --no-ffmpeg] [--forcetranscoding | --no-forcetranscoding] [--photos | --no-photos] [--mock | --no-mock] [--videoname VIDEONAME] [--concat | --no-concat] [--trim | --no-trim]
               [--ui | --no-ui] [--skipexisting | --no-skipexisting]

Download Recordings from a HikVision server, from a range interval

options:
  -h, --help            show this help message and exit
  --server SERVER       the hikvision server's address
  --username USERNAME   the username
  --password PASSWORD   the password
  --starttime STARTTIME
                        the start time in ISO format (default: today at 00:00:00, local time)
  --endtime ENDTIME     the start time in ISO format (default: today at 23:59:59, local time)
  --folders {onepercamera,oneperday,onepermonth,oneperyear}
                        create a separate folder per camera/duration (default: disabled)
  --debug, --no-debug   enable debug mode (default: false)
  --videoformat {mkv,mp4,avi}
                        specify video format (default: mp4)
  --downloads DOWNLOADS
                        the downloads folder (default: "Downloads")
  --frames FRAMES       save a frame for every X frames in the video (default: false)
  --force, --no-force   force saving of files (default: false)
  --skipseconds SKIPSECONDS
                        skip first X seconds for each video (default: 0)
  --seconds SECONDS     save only X seconds for each video (default: inf)
  --days DAYS           download videos for the last X days (ignores --endtime and --starttime)
  --skipdownload, --no-skipdownload
                        do not download anything
  --allrecordings, --no-allrecordings
                        download all recordings saved
  --cameras CAMERAS     camera IDs to search (example: --cameras=201,301)
  --localtimefilenames, --no-localtimefilenames
                        save filenames using date in local time instead of UTC
  --yesterday, --no-yesterday
                        download yesterday's videos
  --ffmpeg, --no-ffmpeg
                        enable ffmpeg and disable downloading directly from server
  --forcetranscoding, --no-forcetranscoding
                        force transcoding if downloading directly from server
  --photos, --no-photos
                        enable experimental downloading of saved photos
  --mock, --no-mock     enable mock mode WARNING! This will not download anything from the server
  --videoname VIDEONAME
                        name of the downloaded video(s). Does not suppress --localtimefilenames
  --concat, --no-concat
                        enable concatenating downloaded vides into one file (channel-wise)
  --trim, --no-trim     enable triming of the concatenated video. Does work only with --concat enabled
  --ui, --no-ui         enable UI interface WARNING! Requires Qt5 to be installed (default: False)
  --skipexisting, --no-skipexisting
                        Skip dowloading files those already exist in the destination dir. Won't skip files that need preprocessing

The DVR/NVR needs to have ISAPI and RTSP enabled in System/Security and H264+ disabled for every camera.

Installing and running the script

You can install the script from PyPi, run the script directly from the source, or use the Docker image:

docker pull ghcr.io/tedyst/hikload
docker run -v $(pwd)/Downloads:/app/Downloads ghcr.io/tedyst/hikload --server 192.168.10.239 --user admin --password password

If you decide to use the PyPi package, there will be a command called hikload in your PATH, and also a program named hikload-qt for the UI version:

pip install hikload
hikload -h

To run the script from source, you can use this command from the root directory of the project:

python setup.py install
hikload -h

After this command, you will have installed hikload and hikload-qt in your PATH.

If you want to use the default arguments, you can specify only the required arguments:

hikload --server 192.168.10.239 --user username --password password

For more advanced users, you can specify optional arguments like the start and end time for the video search:

hikload --server 192.168.10.239 --user username --password password --starttime 2021-09-19T03:00:00+03:00 --endtime 2021-09-20T04:00:00+00:00

Or just specify the cameras that you want to search(be sure to use the HikVision format - 101 for first camera, 201 for the second one...):

hikload --server 192.168.10.239 --user username --password password --cameras=201,301

Installing Dependencies

Due to common problems found while installing the dependencies needed by this project, it is recommended to use a python virtualenv. Here is how to setup one:

pip install pipenv
pipenv install --dev
pipenv shell

And everytime you restart the terminal and want to use the virtualenv, you need to run these commands:

pipenv shell

hikload's Issues

Downloaded video is incomplete if download is started shortly after recording ends

Describe the bug
I use the ISAPI/hikload to coordinate video recording and downloading for my research. However, when I download a video immediately after I stop a recording using ISAPI, the video is sometimes incomplete. However, the video is correctly formatted if I look on the DVR itself.

To Reproduce
To start a recording:
hikutils.putXML(self.server, 'ContentMgmt/record/control/manual/start/tracks/' + cam)

To stop a recording:
hikutils.putXML(self.server, 'ContentMgmt/record/control/manual/stop/tracks/' + addr)

To download:

resp = self.server.ContentMgmt.search.getAllRecordingsForID(addr)
vids = resp['CMSearchResult']['matchList']['searchMatchItem']
if not isinstance(vids, list):
  vids = [vids]
vid = vids[-1]
dwnld = self.server.ContentMgmt.search.downloadURI(vid['mediaSegmentDescriptor']['playbackURI'])
if not os.path.exists(output_folder):
  os.makedirs(output_folder)
with open(output_folder + str(name) + "_" + addr + ".mp4", 'wb') as file:
  file.write(dwnld.content)

Additional context
Device is an iDS-7216HQHI-M2/S

Script for Hikvision cameras with SD card

It is possible to modify this script for use with cameras, not DVRs?
trying to load from DS-2CD2143G0-I
Traceback (most recent call last):
File "/Users/max/Downloads/HikLoad-master/downloadTodayRecordings.py", line 22, in
for channel in channelList['StreamingChannelList']['StreamingChannel']:
KeyError: 'StreamingChannelList'

how shell?

`>>> hikload h
File "", line 1
hikload h
^
SyntaxError: invalid syntax

hikload -h
Traceback (most recent call last):
File "", line 1, in
NameError: name 'h' is not defined
hikload /h
Traceback (most recent call last):
File "", line 1, in
NameError: name 'h' is not defined

hikload --server 10.0.0.2 --user admin --password XXXX --starttime 2022-09-+downday+T07:00:00+03:00 --endtime 2022-09-+downday+T18:00:00+00:00 --cameras 2201
SyntaxError: invalid syntax
`

Script for Hikvision cameras with SD card - download .jpeg timed captures?

it's possible?

Use TQDM loading bar

Try to use tqdm to improve the user experience while downloading.

module 'argparse' has no attribute 'BooleanOptionalAction'

hikload doesn't run in python==3.8?

Unauthorized user

Hello,

I'm trying to use this code as base for an automatic video download from a hikvision NVR.

I have the problem that even though I use the correct user, pass and camera, I always get an unauthorized user response.

>>> responseXML = requests.post(serverpath, data, headers).text
>>> responseXML
<?xml version="1.0" encoding="UTF-8" ?>
<userCheck>
<statusValue>401</statusValue>
<statusString>Unauthorized</statusString>
</userCheck>

In the DVR the camara names are "Camara 01" "Camera 02" .... but I use as indicated in the config life "101" "201"

Any help will be appreciated.

thanks
E.M.

cant run in windows and docker

Describe the bug
when I run code

python main.py --server ip --user admin --password password --debug

DEBUG:hikload:http://admin:[email protected]:65002/ISAPI/System/deviceInfo
DEBUG:hikload:http://admin:[email protected]:65002/ISAPI/Streaming/channels
DEBUG:hikload:Data sent: <?xml version = "1.0" encoding = "UTF-8" ?><CMSearchDescription version="1.0" xmlns="http://www.hikvision.com/ver20/XMLSchema"><searchID>e9e31579-c5a1-444c-a2c8-2782525597e5</searchID><trackIDList><trackID>101</trackID></trackIDList><timeSpanList><timeSpan><startTime>2023-12-25T00:00:00Z</startTime><endTime>2023-12-25T23:59:59Z</endTime></timeSpan></timeSpanList><maxResults>64</maxResults></CMSearchDescription>
ERROR:root:Could not get recordings for channel 101
ERROR:root:Invalid Operation
INFO:hikload:Downloading recordings...
0it [00:00, ?it/s]

follow the error, I found that I used the IP alone to enter the URL of the corresponding camera, which does not have a hard disk to store. All videos are stored in the same URL, which can see all the camera footage and playback information. In this case, how to do it?

single camera url and its harddisk:

and the aggregated camera URL and its harddisk:

Supported Models of hikvision NVR for API

I am trying to do similar project.
can you please let me know supported models of hikvision on which I can run this.
thank you in advance.

Download recorded files Error

After modifying config.py, I ran main.py, but the following error occurred.
Would you give me a hand?

ERROR:root:Got the response: OrderedDict([('userCheck', OrderedDict([('statusValue', '401'), ('statusString', 'Unauthorized')]))])

speed download video

good afternoon! Can you please tell me, the video from the camera using the iwms 4200 program is downloaded at an average speed of 50 megabits, but using isapi, the speed does not rise above 2.4 kilobytes.

TypeError: search_for_recordings() missing 1 required positional argument: 'args'

Describe the bug
Hello, I'm tried testing your program and encountered this error while running hikload-qt. When I tested the connection I got 101,102 and 103. Upon clicking start download of an hour video with specified date and time this happens. TIA

Additional context
Camera Model DS-2CD2027G1-L

Concatenating videos from one camera

First of all, thank you for the Python Hikvision API. It's a great job.

The API downloads videos from the NVR as they are stored - in 1 GB chunks. Most users (I suppose) would like one video per camera of the required length. Did you consider adding the concatenating feature (option) to the app?

I imagine the download queue would contain information about the camera (which is discarded while creating the queue). Once all recordings of one camera are downloaded, we would concat the videos using FFmpeg. It should be enough to copy the encoding since all videos are in the same format and encoding, so the concatenation would not take so long.
Further (which I suppose could be another pull request and/or issue), we could cut the resulting video to contain only the required time from arguments.

I already do the same in my post-processing script, and the concatenation usually runs between 60 - 150 times faster than the duration of the video.

The proposed solution would only slow the process marginally (without re-encoding, always saving new videos and deleting old ones). It could blow up in terms of memory when downloading longer videos. Still, we can always check for the video length before running this process or prompt the user for confirmation.

Since I need the functionality, I will implement it in my fork. Please let me know if you'd be interested, and I can implement it for the HikLoad.

requests.exceptions.InvalidURL: Failed to parse

Failed to parse
When running the main.py, we are getting an error with a message -
requests.exceptions.InvalidURL: Failed to parse: http://admin:fp#56789@http://192.168.1.24/ISAPI/System/deviceInfo

Download videos for specific periods of time

Hello
I am very impressed by your code.
Would you please let me know if there is a way to download a specific period of video?
Thank you.

Videos not downloading, while being streamed on the Hikconnect app.

When running the hikload code to download video from nvr, we are not getting any video, while the videos are being shown on the Hikconnect app. This is what is showing:

python main.py --server 192.168.31.254 --username admin --password Hikvision --starttime 2023-03-01T13:00:00 --endtime 2023-06-19T14:30:00 --folders onepercamera --skipdownload --debug
DEBUG:hikload:http://admin:[email protected]/ISAPI/System/deviceInfo
DEBUG:hikload:http://admin:[email protected]/ISAPI/Streaming/channels
DEBUG:hikload:Data sent: <?xml version = "1.0" encoding = "UTF-8" ?><CMSearchDescription version="1.0" xmlns="http://www.hikvision.com/ver20/XMLSchema"><searchID>987bf5de-fbfe-4037-a865-449a7957bd3c</searchID><trackIDList><trackID>101</trackID></trackIDList><timeSpanList><timeSpan><startTime>2023-03-01T13:00:00Z</startTime><endTime>2023-06-19T14:30:00Z</endTime></timeSpan></timeSpanList><maxResults>64</maxResults></CMSearchDescription>
INFO:hikload:Downloading recordings...
0it [00:00, ?it/s]

We have checked for the IP address, and the settings. What may be going wrong?

Script error on OS X

Trying to run script on Mac OS Catalina latest

max@MacBook-Pro HikLoad-master %
Traceback (most recent call last):
File "/Users/max/Downloads/HikLoad-master/downloadTodayRecordings.py", line 22, in
for channel in channelList['StreamingChannelList']['StreamingChannel']:
KeyError: 'StreamingChannelList'

What am I doing wrong?

error while installing hikLoad using pip install hikload.

Describe the bug
While installing hikLoad using pip I am getting an error ERROR: Could not build wheels for lxml, pyqt5-sip, which is required to install pyproject.toml-based projects on
windows powershell and also on ubuntu terminal. I have downloaded all the python dependency and still getting the error.

To Reproduce
I have tried installing using dockers on ubuntu, I was not able to install it I keep getting Unable to find image 'monitoring:latest' locally docker: Error response from daemon: pull access denied for monitoring, repository does not exist or may require 'docker login': denied: requested access to the resource is denied. error, so I tried pip install and still unable to I am not how I will able to install it, please help.

Additional context
I have tried researching on how to fix the error but I have found any solution, How can I fix this?

Package is incompatible with older versions of Python (<3.9 at least), and doesn't declare such in its metadata

Describe the bug
The package doesn't run on Python 3.7, throwing a SyntaxError on this line. This syntax was added in Python 3.8.

If the package is intentionally not compatible with older versions of Python, it should declare that so that pip won't install it in an environment where the code won't run.

To Reproduce
Attempt to run hikload or hikload-qt, regardless of arguments, on Python 3.7.

Additional context
Nothing particularly relevant.

TypeError: string indices must be integers

I would like to inquire because the following error occurred when executing the 'getList(response)' function of main().

Traceback (most recent call last):
File "./main.py", line 49, in
main()
File "./main.py", line 40, in main
for stream in getList(response):
File "./hikload/util.py", line 114, in getList
url = i["ns0:mediaSegmentDescriptor"]["ns0:playbackURI"].replace("rtsp://", "rtsp://" + getConfig('user') + ":" + getConfig("password") + "@", 1)

TypeError: string indices must be integers

※ In the 112th line of util.py, insert print(i) as follows, and the result is 'ns0:sourceID'.

Download video skipping frames

Hello @Tedyst

Is there a way to use the Hikvision SDK to download video, but skipping frames?. I want to reduce bandwich comsumption skipping some frame from the DVR/NVR directly. Lets put an example:

If I download a video from 2021-04-13 15:20:00 to 2021-04-13 15:25:00 I will have a 5 minutes video. Let's say the device save the video with a fps od 10. This means this downloaded video have 3000 frames. Now I want to skipp 9 frames per each frame downloaded, so for this example I will only download 300 frames. The downloaded frames will be: frame1, frame11, frame21, frame 31, and so on. (note that 9 frames were skipped between each downloaded frame).

Is there a way to do this?

Thanks in advance for any help.

Error when downloading single file

Hi, Thanks for the awesome package.

I found an error when trying to download a single recording.

I think the error occurs because the received recording data format is different when there are multiple recordings, and only one recording.

When there is only one recording, I needed to fix the existing code to this and remove the for loop.
recording = recordings['CMSearchResult']['matchList']['searchMatchItem']

I hope this issue could be fixed.

I'm sorry I couldn't help much, I'm a noob in Python.

Starttime and endtime not used

Even though providing starttime and endtime why is that the videos which gets downloaded is way longer than required some times its 2.5 hours or 1.5 hours although we are always looking to download 16 minutes of video. Its very random. The command we are using hikload --server servername --user username --password password --starttime 2024-03-05T08:06:00 --endtime 2024-03-05T08:08:00 --cameras=2001 and it is downloading the video from 6:17 am to 9:00 am. Why is that. AM i doing something wrong?

Invalid Operation

I have DVR with 16 cameras.

hikload 192.168.20.100 admin hardpassword123 --cameras=101

Traceback (most recent call last):
File "/usr/local/bin/hikload", line 8, in
sys.exit(main())
File "/usr/local/lib/python3.9/dist-packages/hikload/main.py", line 7, in main
run(args)
File "/usr/local/lib/python3.9/dist-packages/hikload/download.py", line 298, in run
downloadQueue = search_for_recordings(server, args)
File "/usr/local/lib/python3.9/dist-packages/hikload/download.py", line 148, in search_for_recordings
channelList = server.Streaming.getChannels()
File "/usr/local/lib/python3.9/dist-packages/hikload/hikvisionapi/_Streaming.py", line 19, in getChannels
return hikvisionapi.getXML(self.parent, "Streaming/channels")
File "/usr/local/lib/python3.9/dist-packages/hikload/hikvisionapi/utils.py", line 40, in getXML
raise hikvisionapi.HikvisionException(
hikload.hikvisionapi.classes.HikvisionException: Invalid Operation

What am I doing wrong?

Not enough bandwidth

Hello, I've tried getting something similar to work and I keep getting an error from ffmpeg:

[rtsp @ 000001b3b14db040] method DESCRIBE failed: 453 Not Enough Bandwidth

This was also the case with this library. Any chance you've come across this before?