Hikvision Telegram Camera Bot

Telegram Bot which sends snapshots from your Hikvision cameras.

Version: 1.8. Release details.

Features

1. Send full/resized pictures on request (NVR is supported).
2. Auto-send pictures on Motion, Line Crossing and Intrusion (Field) Detection.
3. Send so-called Telegram video-gifs on request and alert events from the previous paragraph.
4. YouTube, Telegram, and Icecast direct or re-encoded livestreams.
5. DVR to local storage with upload to Telegram group.
6. SRS re-stream server.
7. Theoretically, Hikvision doorbells also should be supported, but I don't have one.

Support my work

• Buy me a coffee
• PayPal
• Bitcoin wallet 14kMRS8SvfD2ydMSMEyAmefHV3Yynf9kAd

Development supported by JetBrains and Syntevo by providing free licenses

Installation

To install Hikvision Telegram Camera Bot, simply clone the repo.

git clone https://github.com/tropicoo/hikvision-camera-bot.git
cd hikvision-camera-bot

Configuration

Configuration files are stored in JSON format and can be found in the configs directory.

Quick Setup

1. Create and start Telegram Bot and get its API token

2. Get your Telegram API key (api_id and api_hash)

3. Copy 3 default configuration files with predefined templates in the configs directory:

   cd configs
   cp config-template.json config.json
   cp encoding_templates-template.json encoding_templates.json
   cp livestream_templates-template.json livestream_templates.json
   

4. Edit config.json:

   1. Put the obtained api_id and api_hash strings to the same keys

   2. Put the obtained bot API token string to the token key

   3. Find your Telegram user id and put it to chat_users, alert_users and startup_message_users lists as integer value. Multiple ids can be used, just separate them with a comma.

   4. Hikvision camera settings are placed inside the camera_list section. The template comes with two cameras

      Camera names should start with the cam_ prefix and end with digit suffix: cam_1, cam_2, cam_<digit> with any description.

   5. Write authentication credentials in user and password keys for every camera

   6. Choose authentication type from basic, digest or digest_cached. Default is digest_cached. Check your camera security settings before choosing/changing one.

   7. Write host, which should include protocol e.g., http://192.168.1.1

   8. In the alert section you can enable sending pictures on alert (Motion, Line Crossing and Intrusion (Field) Detection). Configure the delay setting in seconds between pushing alert pictures. To send resized picture change fullpic to false

Example config.json with dummy values

{
  "telegram": {
    "api_id": 11111111,
    "api_hash": "1a1a1a1a1a1a1a1a",
    "lang_code": "en",
    "token": "1b1b1b1b1b1b1b1b",
    "chat_users": [
      1010101010,
      2020202020
    ],
    "alert_users": [
      1010101010,
      2020202020
    ],
    "startup_message_users": [
      1010101010,
      2020202020
    ]
  },
  "log_level": "INFO",
  "camera_list": {
    "cam_1": {
      "hidden": false,
      "description": "Kitchen",
      "hashtag": "kitchen",
      "group": "Default group",
      "api": {
        "host": "http://192.168.1.1",
        "port": 80,
        "auth": {
          "user": "dummy-user",
          "password": "dummy-password",
          "type": "digest_cached"
        },
        "stream_timeout": 10
      },
      "rtsp_port": 554,
      "nvr": {
        "is_behind": false,
        "channel_name": ""
      },
      "picture": {
        "on_demand": {
          "channel": 101
        },
        "on_alert": {
          "channel": 101
        }
      },
      "video_gif": {
        "on_demand": {
          "channel": 101,
          "record_time": 10,
          "rewind_time": 10,
          "tmp_storage": "/tmp",
          "loglevel": "error",
          "rtsp_transport_type": "tcp"
        },
        "on_alert": {
          "channel": 101,
          "record_time": 10,
          "rewind_time": 10,
          "rewind": true,
          "tmp_storage": "/tmp",
          "loglevel": "error",
          "rtsp_transport_type": "tcp"
        }
      },
      "alert": {
        "delay": 15,
        "motion_detection": {
          "enabled": false,
          "sendpic": true,
          "fullpic": false,
          "send_videogif": true,
          "send_text": true
        },
        "line_crossing_detection": {
          "enabled": false,
          "sendpic": true,
          "fullpic": false,
          "send_videogif": true,
          "send_text": true
        },
        "intrusion_detection": {
          "enabled": false,
          "sendpic": true,
          "fullpic": false,
          "send_videogif": true,
          "send_text": true
        }
      },
      "livestream": {
        "youtube": {
          "enabled": false,
          "livestream_template": "tpl_kitchen",
          "encoding_template": "direct.kitchen_youtube"
        },
        "telegram": {
          "enabled": false,
          "livestream_template": "tpl_kitchen",
          "encoding_template": "direct.kitchen_telegram"
        },
        "srs": {
          "enabled": false,
          "livestream_template": "tpl_kitchen",
          "encoding_template": "direct.kitchen_srs"
        },
        "dvr": {
          "enabled": false,
          "local_storage_path": "/data/dvr",
          "livestream_template": "tpl_kitchen",
          "encoding_template": "direct.kitchen_dvr",
          "upload": {
            "delete_after_upload": true,
            "storage": {
              "telegram": {
                "enabled": false,
                "group_id": -10000000
              }
            }
          }
        },
        "icecast": {
          "enabled": false,
          "livestream_template": "tpl_kitchen",
          "encoding_template": "vp9.kitchen"
        }
      },
      "command_sections_visibility": {
        "general": true,
        "infrared": true,
        "motion_detection": true,
        "line_detection": true,
        "intrusion_detection": true,
        "alert_service": true,
        "stream_youtube": true,
        "stream_telegram": true,
        "stream_icecast": true
      }
    }
  }
}

Usage

Launch by using Docker and Docker Compose

1. Set your timezone by editing the .env file (TZ=Europe/Kyiv). Currently, there is a Ukrainian timezone because I live there. Look for your timezone here http://www.timezoneconverter.com/cgi-bin/zoneinfo. If you want to use the default UTC time format, set Greenwich Mean Time timezone TZ=GMT

2. Build an image and run a container in a detached mode

   # Build containers and start
   sudo docker-compose build && sudo docker-compose up -d
   
   # Tail logs per container or from all at once
   sudo docker-compose logs -f --tail 500 hikvision-camera-bot
   sudo docker-compose logs -f --tail 500 hik-hikvision-srs-server
   sudo docker-compose logs -f --tail 500
   
   # Stop running containers while you're in the bot directory
   sudo docker-compose stop
   
   # Check whether any containers are running
   sudo docker ps
   

Commands

* - camera digit id e.g., cam_1.

Advanced Configuration

SRS

SRS (Simple Realtime Server) is a re-stream server that takes a stream from your camera and re-streams it to any destination without touching the native camera stream multiple times. The SRS release version used in the bot is 4.0.

SRS decreases CPU time and network load on the camera when you enable something like DVR, YouTube Livestream or try to get Video GIF at the same time. Pictures are taken directly from the camera stream, not from the SRS.

How it works - if you have two cameras with enabled SRS for both, there will be two running 24/7 bot tasks taking streams from the cameras to the SRS server. Eventually, when you request Video Gif, or it's triggered by some alert, the video will be taken from the SRS server.

You can also connect to the SRS server with any video player like VLC and watch the stream without any interruptions. URL looks like this: rtmp://192.168.1.100/live/livestream_101_cam_2, where:

1. 192.168.1.100 is an IP address or a host of your server.
2. 101 is the camera's configured stream channel.
3. cam_2 is the ID of your second configured camera.

SRS runs in a separate docker container. SRS config and Dockerfile are placed in the srs_prod directory. The service name is hikvision-srs-server in docker-compose.yml.

If docker-compose.yml is a list of forwarded and open SRS ports to the world:

# If you don't plan to use anything from this, just comment out the whole section.
ports:
  - "1935:1935"   # SRS RTMP port, if you comment this out, you won't be able to connect with the video player
  - "1985:1985"   # SRS API port, can be commented out since not used
  - "8080:8080"   # SRS WebUI port

DVR

You can record your videos from the camera to local storage mounted as a volume in volumes section of hikvision-camera-bot service in docker-compose.yml.

DVR configuration is per camera in config.json with livestream template name from livestream_templates.json.

It's very simple:

1. Use the enabled key to turn on/off this feature.

2. local_storage_path is a path inside the container to which videos will be recorded. Don't change this default value (/data/dvr) since it's written in the volumes mapping section. If you need to change it for some reason - you must change it both here and in the volumes mapping.

3. livestream_template has a template name located inside the livestream_templates.json file with DVR stream settings:

   "dvr": {
     "tpl_kitchen": {
       "channel": 101,
       "sub_channel": 102,
       "restart_period": -1,
       "restart_pause": 0,
       "segment_time": 1800,
     }
   }
   

   a) segment_time is the time in seconds when the DVR record file will be split into a new one.

   b) 1800 seconds mean every file will have 30 minutes of video recording.

   c) File is named cam_1_101_1800_2022-04-15_21-19-32.mp4 with cam ID, channel name, segment time, and record start datetime.

4. Configuration part from the config.json:

   "dvr": {
     "enabled": true,
     "local_storage_path": "/data/dvr",
     "livestream_template": "tpl_kitchen",
     "encoding_template": "direct.kitchen_dvr",
     "upload": {
       "delete_after_upload": true,
       "storage": {
         "telegram": {
           "enabled": true,
           "group_id": -1001631507769
         }
       }
     }
   }
   

   Recorded files can be uploaded to the Telegram group. Right now, the upload will work only if delete_after_upload is set to true meaning the uploaded file will be deleted from the local storage. You need to make sure your file size will be up to 2GB since Telegram rejects larger ones. Just experiment with segment time.

5. Local storage (the real one, not in the container) by default is /data/dvr in volumes mapping (the first path string, not the last). Change it to any location you need e.g., - "D:\Videos:/data/dvr" if you're on Windows.

   volumes:
     - "/data/dvr:/data/dvr"
   

6. Watch logs for any errors.

YouTube Livestream

To enable YouTube Live Stream enable it in the youtube key.

Livestream templates

To start a particular livestream, a user needs to set both livestream and encoding templates with stream settings and encoding type/arguments.

Encoding templates

direct means that the video stream will not be re-encoded (transcoded) and will be sent to YouTube/Icecast servers "as is", only audio can be disabled.

x264 or vp9 means that the video stream will be re-encoded on your machine/server where the bot is running using respective encoding codecs.

User can create their templates in a file named livestream_templates.json and encoding_templates.json.

The default dummy template file is named livestream_templates_template.json (not a very funny name but anyway) which should be copied or renamed to livestream_templates.json.

Same for encoding_templates-template.json -> encoding_templates.json

{
  "youtube": {
    "tpl_kitchen": {
      "channel": 101,
      "restart_period": 39600,
      "restart_pause": 10,
      "url": "rtmp://a.rtmp.youtube.com/live2",
      "key": "xxxx-xxxx-xxxx-xxxx"
    },
    "tpl_basement": {
      "channel": 101,
      "restart_period": 39600,
      "restart_pause": 10,
      "url": "rtmp://a.rtmp.youtube.com/live2",
      "key": "xxxx-xxxx-xxxx-xxxx"
    }
  },
  "icecast": {
    "tpl_kitchen": {
      "channel": 101,
      "restart_period": 39600,
      "restart_pause": 10,
      "ice_stream": {
        "ice_genre": "333Default",
        "ice_name": "222Default",
        "ice_description": "111Default",
        "ice_public": 0,
        "url": "icecast://[email protected]:8000/video.webm",
        "password": "hackme",
        "content_type": "video/webm"
      }
    },
    "tpl_basement": {
      "channel": 101,
      "restart_period": 39600,
      "restart_pause": 10,
      "ice_stream": {
        "ice_genre": "333Default",
        "ice_name": "222Default",
        "ice_description": "111Default",
        "ice_public": 0,
        "url": "icecast://[email protected]:8000/video.webm",
        "password": "hackme",
        "content_type": "video/webm"
      }
    }
  }
}

Where:

{
  "x264": {
    "kitchen": {
      "null_audio": false,
      "loglevel": "error",
      "vcodec": "libx264",
      "acodec": "aac",
      "format": "flv",
      "rtsp_transport_type": "tcp",
      "pix_fmt": "yuv420p",
      "pass_mode": 1,
      "framerate": 25,
      "preset": "superfast",
      "average_bitrate": "1000K",
      "maxrate": "3000k",
      "bufsize": "6000k",
      "tune": "zerolatency",
      "scale": {
        "enabled": true,
        "width": 640,
        "height": -1,
        "format": "yuv420p"
      }
    },
    "basement": {
      "null_audio": false,
      "loglevel": "error",
      "vcodec": "libx264",
      "acodec": "aac",
      "format": "flv",
      "rtsp_transport_type": "tcp",
      "pix_fmt": "yuv420p",
      "pass_mode": 1,
      "framerate": 25,
      "preset": "superfast",
      "average_bitrate": "1000K",
      "maxrate": "3000k",
      "bufsize": "6000k",
      "tune": "zerolatency",
      "scale": {
        "enabled": true,
        "width": 640,
        "height": -1,
        "format": "yuv420p"
      }
    }
  },
  "vp9": {
    "kitchen": {
      "null_audio": false,
      "loglevel": "info",
      "vcodec": "libvpx-vp9",
      "acodec": "libopus",
      "format": "webm",
      "rtsp_transport_type": "tcp",
      "pix_fmt": "yuv420p",
      "pass_mode": 1,
      "framerate": 10,
      "average_bitrate": "1000K",
      "maxrate": "2000k",
      "bufsize": "4000k",
      "deadline": "realtime",
      "speed": 5,
      "scale": {
        "enabled": true,
        "width": 640,
        "height": -1,
        "format": "yuv420p"
      }
    },
    "basement": {
      "null_audio": false,
      "loglevel": "info",
      "vcodec": "libvpx-vp9",
      "acodec": "libopus",
      "format": "webm",
      "rtsp_transport_type": "tcp",
      "pix_fmt": "yuv420p",
      "pass_mode": 1,
      "framerate": 10,
      "average_bitrate": "1000K",
      "maxrate": "2000k",
      "bufsize": "4000k",
      "deadline": "realtime",
      "speed": 5,
      "scale": {
        "enabled": true,
        "width": 640,
        "height": -1,
        "format": "yuv420p"
      }
    }
  },
  "direct": {
    "kitchen": {
      "null_audio": false,
      "loglevel": "error",
      "vcodec": "copy",
      "acodec": "aac",
      "format": "flv",
      "rtsp_transport_type": "tcp"
    },
    "basement": {
      "null_audio": false,
      "loglevel": "error",
      "vcodec": "copy",
      "acodec": "aac",
      "format": "flv",
      "rtsp_transport_type": "tcp"
    }
  }
}

Where:

YouTube Live Streams server/key is available at https://www.youtube.com/live_dashboard.