Hikvision Multi-NVR Camera Viewer

A desktop application for viewing cameras from multiple Hikvision NVRs in a single window, with a full-screen kiosk mode.

✨ Features

• 🎥 View multiple cameras from different NVRs in one window
• 🔒 Secure storage of credentials (encryption)
• 🎨 Flexible camera grid layouts (auto or manual)
• 🖥️ Kiosk mode (full screen)
• 🔄 Automatic reconnect on connection loss
• 📊 Friendly graphical interface
• ⚡ Command-line launching (CLI)
• 📝 Detailed logging

📋 Requirements

System

• Python 3.7+
• Windows / Linux / macOS
• Network access to the Hikvision NVRs

Python libraries

Install everything with:

pip install -r requirements.txt

Or manually:

pip install opencv-python numpy requests cryptography screeninfo Pillow

📁 Project structure

HikVision-KioskMode-Viewer/
├── main.py                      # Main application entry point
├── config/
│   ├── __init__.py
│   ├── settings.py              # Global settings
│   └── nvr_config.py            # NVR configuration (encrypted data)
├── core/
│   ├── __init__.py
│   ├── security.py              # Encryption and authorization
│   ├── nvr_manager.py           # NVR manager and API communication
│   └── video_stream.py          # RTSP stream handling
├── gui/
│   ├── __init__.py
│   ├── main_window.py           # Main GUI window
│   ├── viewer_window.py         # Camera viewer window
│   └── dialogs.py               # Dialogs (splash, loading, password)
├── utils/
│   ├── __init__.py
│   ├── cli_parser.py            # CLI argument parser
│   └── credential_generator.py  # Encrypted credentials generator
├── assets/
│   └── app_icon.ico             # Application icon
├── test/                        # Local test tooling (fake NVR / RTSP)
├── HikvisionViewer-onefile.spec # PyInstaller spec (single .exe)
├── HikvisionViewer-onedir.spec  # PyInstaller spec (folder build)
├── build_exe.bat                # Build script (onefile + onedir)
├── build_env.bat                # Virtual environment setup script
├── requirements.txt
├── LICENSE
└── README.md

🚀 Quick start

1. Install dependencies

pip install -r requirements.txt

2. Generate encrypted credentials

python main.py --generate-creds

Follow the prompts and add the generated entry to config/nvr_config.py.

3. Run the application

GUI (standard)

python main.py

CLI (specific cameras)

python main.py -c NVR1:1 NVR1:2 NVR2:5

Kiosk mode

python main.py -c NVR1:1 NVR1:2 -k

📖 Usage

GUI

1. Select an NVR – choose an NVR from the list
2. Test the connection – click "🔗 Test" to check access
3. Select a camera – choose a camera from the list
4. Add the camera – click "➕ Add camera"
5. Manage the list – remove cameras or change their order
6. Options – choose kiosk mode and layout (optional)
7. Start – click "▶ Start viewer"

Viewer controls

• Q or ESC – exit the application
• M – return to the menu

Command line

python main.py [OPTIONS]

Options:
  -c, --cameras NVR:CHANNEL [NVR:CHANNEL ...]
                        List of cameras (e.g. NVR1:1 NVR2:3)
  -s, --substream {main,sub,third,1,2,3}
                        Substream: main/1 (highest quality), sub/2 (default 640x360), third/3
  -k, --kiosk           Kiosk mode (full screen)
  -l, --layout ROWSxCOLS
                        Forced layout (e.g. 2x2, 3x3)
  -p, --password PASSWORD
                        Application password (not recommended!)
  --generate-creds      Encrypted credentials generator
  -v, --verbose         Verbose logging
  --version             Application version

Examples

# Show 4 cameras in a 2x2 layout
python main.py -c NVR1:1 NVR1:2 NVR1:3 NVR1:4 -l 2x2

# Kiosk mode with auto layout
python main.py -c NVR1:1 NVR2:2 NVR3:1 -k

# Generate credentials
python main.py --generate-creds

⚙️ Configuration

Application password

Default password: admin123

The password hash lives in config/settings.py:

APP_PASSWORD_HASH = "240be518fabd2724ddb6f04eeb1da5967448d7e831c08c8fa822809f74c720a9"

To change the password:

1. Run python main.py --generate-creds
2. Copy the generated hash
3. Paste it into config/settings.py

Security note: Change both APP_PASSWORD_HASH and ENCRYPTION_SALT in config/settings.py before deploying.

Camera layouts

Default (auto) layouts:

Cameras	Layout
1	1×1
2	1×2
3–4	2×2
5–6	2×3
7–9	3×3
10–12	3×4
13–16	4×4

You can force a custom layout in the GUI or with -l.

Stream settings

In config/settings.py:

VIDEO_SETTINGS = {
    'retry_delay': 2,           # Reconnect delay (s)
    'frame_timeout': 3,         # Frame timeout (s)
    'buffer_size': 1,           # Buffer size
    'initial_load_timeout': 5   # Initial load timeout (s)
}

Adding an NVR

1. Generate the encrypted data:

   python main.py --generate-creds

2. Add it to config/nvr_config.py:

   ENCRYPTED_NVR_DATA = {
       "NVR1": "encrypted_string_1",
       "NVR2": "encrypted_string_2",
   }

📝 Logging

Logs and run history are written under %APPDATA%\HCV\ (Windows):

• Logs: %APPDATA%\HCV\logs\app_YYYY-MM-DD.log
• Rotation: one file per day
• Level: INFO (use -v for DEBUG)

🔒 Security

• Credentials are encrypted with AES (Fernet)
• NVR passwords are never stored in plaintext
• Authorization is required at startup
• The application password is hashed with SHA256

🐛 Troubleshooting

No connection to the NVR

1. Check network access (ping)
2. Use the "🔗 Test" button in the GUI
3. Check the credentials in config/nvr_config.py
4. Review the logs in %APPDATA%\HCV\logs

Black camera screen

• The camera may be disabled on the NVR
• Check the 640×360 substream on the NVR
• Increase initial_load_timeout in the settings

Authorization error

• Make sure you are using the correct password
• The password hash must match the one in config/settings.py
• Use --generate-creds to generate a new hash

🔧 Building an executable (PyInstaller)

Install PyInstaller first:

pip install pyinstaller

Option A: build script (recommended, Windows)

build_exe.bat          # builds both onefile and onedir
build_exe.bat onefile  # single .exe only
build_exe.bat onedir   # folder build only

Option B: spec files

Onefile – a single self-contained .exe:

pyinstaller HikvisionViewer-onefile.spec

Output: dist/HikvisionViewer.exe

Onedir – a folder build that keeps all files next to the .exe (uses contents-directory=".", so there is no _internal subfolder):

pyinstaller HikvisionViewer-onedir.spec

Output: dist/HikvisionViewer/HikvisionViewer.exe

Option C: plain command line

Onefile:

pyinstaller --onefile --windowed --name HikvisionViewer ^
            --add-data "config;config" --add-data "assets;assets" ^
            --hidden-import PIL._tkinter_finder ^
            --icon assets/app_icon.ico main.py

Onedir with contents-directory=".":

pyinstaller --onedir --contents-directory "." --windowed --name HikvisionViewer ^
            --add-data "config;config" --add-data "assets;assets" ^
            --hidden-import PIL._tkinter_finder ^
            --icon assets/app_icon.ico main.py

On Linux/macOS, replace ; with : in the --add-data arguments and ^ line continuations with \.

📄 License

Released under the MIT License – free to use, modify, and distribute.

👨‍💻 Author

Marak123

🙏 Acknowledgments

Built with the help of Claude Code (Opus 4.8).

🤝 Contributing

Pull requests are welcome! For larger changes, please open an issue first to discuss what you would like to change.