Heimdall

Advanced Detection Surveillance System that uses A.I. and ML to utilize facial recognition, customizable to also perform automated response/actions based on human behaviors. Both threat detection, as well as loss prevention.

Features

• RTSP Stream Viewing: Connect to and display RTSP camera streams
• Configurable: Support for both environment variables and YAML configuration
• Recording: Optional video recording capabilities
• Error Handling: Robust error handling with automatic reconnection
• Logging: Comprehensive logging for debugging and monitoring
• Security: No hardcoded credentials - uses configuration files

Installation

Prerequisites

• Python 3.8 or higher
• OpenCV compatible system (for camera/video processing)

Install Dependencies

pip install -r requirements.txt

Configuration

Heimdall supports multiple configuration methods:

1. Environment Variables (.env file)

Copy the example file and edit:

cp .env.example .env
# Edit .env with your camera credentials

2. YAML Configuration

Copy the example file and edit:

cp config.yaml.example config.yaml
# Edit config.yaml with your settings

3. Command Line Arguments

Provide credentials directly via command line:

python rtsp_ip/rtsp_stream.py --ip 192.168.1.100 --username admin --password secret

Usage

Basic Usage

With configuration in .env or config.yaml:

python rtsp_ip/rtsp_stream.py

Using Command Line Arguments

# Specify connection details
python rtsp_ip/rtsp_stream.py --ip 192.168.1.100 --username admin --password pass123 --channel 401

# Use custom config file
python rtsp_ip/rtsp_stream.py --config my_config.yaml

# Set log level
python rtsp_ip/rtsp_stream.py --log-level DEBUG

Keyboard Controls

While viewing the stream:

• Press q to quit
• Press r to toggle recording on/off

Project Structure

Heimdall/
├── rtsp_ip/              # RTSP streaming module
│   ├── rtsp_stream.py    # Main RTSP viewer application
│   └── README.md         # RTSP-specific documentation
├── .env.example          # Example environment configuration
├── config.yaml.example   # Example YAML configuration
├── requirements.txt      # Python dependencies
├── .gitignore           # Git ignore rules
├── LICENSE              # MIT License
└── README.md            # This file

Security

• Never commit credentials: .env and config.yaml are gitignored
• Use strong passwords: Always use strong, unique passwords for camera access
• Network security: Ensure RTSP streams are on a secure network
• Update regularly: Keep dependencies updated for security patches

Development

Code Quality Tools

Install development dependencies:

pip install pytest pytest-cov black flake8 pylint mypy

Linting

flake8 rtsp_ip/
pylint rtsp_ip/

Formatting

black rtsp_ip/

Type Checking

mypy rtsp_ip/

Troubleshooting

Cannot connect to camera

1. Verify camera IP address is correct
2. Check that RTSP port (default 554) is accessible
3. Verify username and password
4. Check network connectivity
5. Review logs for detailed error messages

Video display issues

1. Ensure OpenCV is properly installed: pip install opencv-python
2. Check that your system has a display available
3. Try reducing display resolution in config
4. Check camera stream format compatibility

Recording issues

1. Ensure recording path exists and is writable
2. Check available disk space
3. Verify codec is supported (try ‘mp4v’ or ‘XVID’)
4. Review logs for error messages

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

License

MIT License - see LICENSE file for details.

Author

Ky1e Parisher (cywf)

Acknowledgments

• OpenCV for video processing capabilities
• The open-source community for various tools and libraries

This site is open source. Improve this page.