ivckolpak is a high-reliability, low-overhead Network Video Recorder (NVR) designed specifically for RTSP IP cameras operating in true passthrough mode. The application continuously reads RTSP streams and writes video packets directly to MP4 containers without any decoding, re-encoding, or frame processing. Recording is triggered exclusively by external JSON events received via TCP (AlarmServer), making it ideal for integration with camera-native analytics, VMS systems, or custom bots.

sudo apt install build-essential pkg-config cmake \
                 libavformat-dev libavcodec-dev libavutil-dev

git clone https://github.com/sheredom/json.h.git
git clone https://github.com/denzen84/ivckolpak.git

copy json.h into ivckolpak dir

cd ivckolpak
mkdir build && cd build
cmake -DCMAKE_BUILD_TYPE=Release ..
make -j$(nproc)

Binary output: build/bin/ivckolpak

For maximum performance on embedded ARM SoCs, enable aggressive optimization flags:

# Native build (auto-detect host CPU)
cmake -DCMAKE_BUILD_TYPE=Release -DENABLE_AGGRESSIVE_OPT=ON -DTARGET_CPU=native ..

# Cross-compile for specific SoC
cmake -DCMAKE_BUILD_TYPE=Release -DENABLE_AGGRESSIVE_OPT=ON -DTARGET_CPU=rk3566 ..

# Universal ARMv8-A compatible build
cmake -DCMAKE_BUILD_TYPE=Release -DENABLE_AGGRESSIVE_OPT=ON -DTARGET_CPU=armv8_generic ..

Release builds automatically:

• Enable -O3, -ffast-math, -flto (Link-Time Optimization)
• Strip debug symbols (-s) for minimal binary size
• Apply architecture-specific tuning via -mcpu

⚠️ Note: -march=native works only for native compilation. Use specific TARGET_CPU values for cross-compilation.

Examples:

# Run with custom config
./ivckolpak --config /etc/ivckolpak/custom.ini

# Silent mode (no console output)
./ivckolpak --silent

# View full documentation
./ivckolpak --help-full

The application uses a standard INI-style configuration with three sections: [global], [camera], and [alarm_server].

All parameters in [global] act as defaults for every camera. When a parameter is specified inside a [camera] section, it overrides the global value. If a camera parameter is left empty, 0, or 0.0, the system automatically falls back to the [global] setting.

Send TCP packets to localhost:15002 (or configured port) with raw JSON (no binary prefix required):

{
  "Type": "Alarm",
  "Status": "Start",
  "Event": "MotionDetect",
  "Channel": 0,
  "SerialID": "cam_front_door",
  "Address": "192.168.1.100",
  "Descrip": "Motion detected at entrance",
  "StartTime": "2026-05-18 14:30:00"
}

{
  "Type": "Alarm",
  "Status": "Stop",
  "Event": "MotionDetect",
  "Channel": 0,
  "SerialID": "cam_front_door",
  "Address": "192.168.1.100",
  "Descrip": "Motion cleared",
  "StartTime": "2026-05-18 14:30:00"
}

Required fields: Type (must be "Alarm"), Status ("Start"/"Stop"), SerialID (matches camera serialid).

Macros can be used in filename_format and external script commands (on_* hooks).

Filename format:

filename_format=rec_%{cam_name}_%Y%m%d_%T_v%v_%e.mp4
# Output: rec_FrontDoor_20260518_143022_v0_42.mp4

Script command:

on_video_save=/usr/local/bin/upload.sh -f %f -n %{cam_name} -t %{json_event}

┌─────────────────┐     TCP:15002      ┌─────────────────┐
│ Camera / VMS /  │  JSON Alarm Events │   AlarmServer   │
│ Telegram Bot    │ ─────────────────► │ (TCP Listener)  │
└─────────────────┘                    └────────┬────────┘
                                                │
                                                ▼
                                     ┌─────────────────────┐
                                     │   AlarmQueue        │
                                     │ (thread-safe FIFO)  │
                                     └────────┬────────────┘
                                              │
                                              ▼
                                   ┌─────────────────────┐
                                   │  CameraManager      │
                                   │ (orchestrator)      │
                                   └────────┬────────────┘
                                            │
              ┌─────────────────────────────┼─────────────────────────────┐
              ▼                             ▼                             ▼
    ┌─────────────────┐    ┌─────────────────┐    ┌─────────────────┐
    │  CameraNode #1  │    │  CameraNode #2  │    │  CameraNode #N  │
    │ • RTSP reader   │    │ • RTSP reader   │    │ • RTSP reader   │
    │ • Passthrough   │    │ • Passthrough   │    │ • Passthrough   │
    │ • RecordingSession│  │ • RecordingSession│  │ • RecordingSession│
    └────────┬────────┘    └────────┬────────┘    └────────┬────────┘
             │                      │                      │
             ▼                      ▼                      ▼
    ┌─────────────────┐  ┌─────────────────┐  ┌─────────────────┐
    │ MP4 Chunk #1    │  │ MP4 Chunk #1    │  │ MP4 Chunk #1    │
    │ (passthrough)   │  │ (passthrough)   │  │ (passthrough)   │
    └─────────────────┘  └─────────────────┘  └─────────────────┘

Critical design principle: Video packets flow unchanged from RTSP stream to MP4 muxer. No decoding, no pixel buffers, no re-encoding — only PTS rebasing and container muxing.

✅ Zero CPU video processing — ideal for Raspberry Pi, Orange Pi, Rockchip, Amlogic SBCs
✅ Bit-perfect recordings — no quality loss, no generation loss from re-encoding
✅ Camera-native intelligence — leverage built-in PIR, AI detection, not software heuristics
✅ Telegram/VMS ready — simple JSON/TCP interface, scriptable hooks for notifications
✅ I-frame aligned — recordings always start/end on decodable keyframes
✅ Resilient by design — exponential reconnect backoff, timeout protection, clean shutdown
✅ Minimal memory footprint — packet pooling, zero-copy stats, no frame buffers
✅ Production-hardened — deadlock-free threading, audited mutex usage, graceful degradation
✅ Flexible naming — 22 macros across filename and script contexts
✅ Open & auditable — clean modern C++20, no hidden dependencies, MIT-style clarity

For questions, issues, or contributions, please open an issue or submit a pull request on GitHub.