CCTV-Smartphone-AI-Monitoring

Sentinel Real-Time Monitoring System

🇺🇸 English | 🇨🇳 中文

This project has been featured by ruanyf’s weekly, xuanli199’s Tech Review, and Треугольник’s Open Source. We sincerely appreciate their recognition and support.

🚀 Latest Update (ongoing): v1.1.6 — 2026-11-05

Sentinel is a distributed real-time vision system framework for local area networks (LAN).

Figure 1 – Sentinel in operation

♻️ It repurposes unused Android devices as network camera nodes, enabling:

• Distributed image acquisition
• Real-time PC-side video streaming
• AI-driven monitoring and analysis

It adopts a layered architecture of “mobile capture + PC processing + browser control”, supporting real-time image preview, local video recording, and structured event analysis, and can be extended to integrate multimodal AI models.

• The system consists of a PC Dashboard and an Android client CamFlow.

This project can be used both as a lightweight local monitoring system and as an engineering prototype platform for visual data acquisition and intelligent analysis.

Before first use, it is strongly recommended to read the chapters in order. Click to jump:
① Project Overview → ② Project Deployment → ③ Run the Project → ④ Dashboard Guide

---

Table of Contents

• 1. Project Overview

  • 1.1. Core Capabilities
  • 1.2. System Architecture
  • 1.3. Practical Applications

• 2. Implemented Features

  • 2.1. Real-time Video Preview
  • 2.2. System Parameter Customization
  • 2.3. AI Triggered Monitoring & Controllable Cognitive Output
  • 2.4. Mobile Camera Capture App (CamFlow)

• 3. Project Deployment

  • 3.1. Environment Requirements
  • 3.2. Get the Source Code
  • 3.3. PC-side Deployment
  • 3.4. Android-side Deployment

• 4. Run the Project

  • 4.1. Start the PC Side
  • 4.2. Start CamFlow
  • 4.3. Dashboard Guide
  • 4.4. AI Monitoring Features
  • 4.5. Dashboard AI Module Guide
  • 4.6. Third-party Model Integration

• 5. Version Information & Notes

  • 5.1. System Version
  • 5.2. Data Locations
  • 5.3. Roadmap
  • 5.4. Usage & License

---

1. Project Overview ⌃

Sentinel is a real-time monitoring system that runs on a LAN, and it can also serve as a tool for data acquisition and analysis. It consists of the following two parts:

• CamFlow (Android client): captures the phone camera feed and uploads it to the server as single-frame JPEG images.
• PC Dashboard (Flask + Web UI): receives image frames and provides live preview, video recording, screenshot saving, log viewing, and optional AI triggered monitoring.

The system supports running in a local LAN environment without relying on cloud services. However, to run multimodal models, it is recommended to use an online model inference service.

---

1.1. Core Capabilities ⌃

Sentinel is not designed as a single-purpose monitoring tool. Instead, it aims to build an extensible real-time vision system framework of “mobile capture + PC processing + browser control”. Its core capabilities include:

Self-developed Android camera client (CamFlow) A regular smartphone can be used as a real-time camera endpoint, without purchasing dedicated IP cameras or extra hardware. Real-time MJPEG video preview in the browser Based on HTTP streaming output; can be viewed directly in a browser without plugins. Standardized image frame upload interface (HTTP POST) The Android client continuously uploads single-frame JPEG images; the interface is clear and extensible. Segmented local video recording (MP4 / AVI) and real-time screenshots Supports time-based segmentation for writing video/image files, suitable for long-term operation and archival management.

Layered, trigger-based visual processing mechanism A two-stage architecture of “traditional CV algorithms → model inference” to improve real-time performance and reduce compute/inference costs. Structured multimodal visual cognition After trigger conditions are met, a vision model is called for semantic analysis and structured outputs, supporting risk grading and event management. Explicit and verifiable manual connection setup The PC prints the CamFlow address at startup, while the Android client validates it and provides a /ping connection test. Structured logging and configuration management Generates local runtime logs and AI event records to support traceability and data analysis.

---

1.2. System Architecture ⌃

The system consists of three structural layers:

1. Data Acquisition Layer (Android App)
2. Service Processing Layer (PC Server)
3. Presentation & Control Layer (Browser Dashboard)

┌─────────────────────────────────────────────────────────────────────────┐
│                         Android Client (CamFlow)
│
│          Camera Capture → Single JPEG Frame → HTTP POST /upload
└─────────────────────────────────────────────────────────────────────────┘
                                     │
                                     ▼
┌─────────────────────────────────────────────────────────────────────────┐
│                           PC-side Flask Server
│
│   ① FrameBuffer (Latest Frame Cache)
│         ├── Provides MJPEG Stream (/stream)
│         ├── Provides Snapshot
│         └── Provides Recorder Access
│
│   ② Recorder Module
│         └── Writes Segmented Video Files by FPS
│
│   ③ AI Monitor (Optional Module)
│         ├── Motion Trigger (Traditional CV Detection)
│         ├── Vision Model Interface (Pluggable)
│         └── Event Logging / Real-time Feedback (Local / Web Access)
│
│   ④ Config & Log Management
│         ├── config.json
│         └── server.log
└─────────────────────────────────────────────────────────────────────────┘
                                     │
                                     ▼
┌─────────────────────────────────────────────────────────────────────────┐
│                            Browser Dashboard
│
│ Live Preview | Recording Control | Parameter Configuration | Log Viewer
└─────────────────────────────────────────────────────────────────────────┘

• Architecture Design

  • All image data flows only within the local area network (LAN);
  • FrameBuffer serves as the core shared data structure to avoid repeated decoding;
  • Recording and AI analysis both read from FrameBuffer without interfering with each other;
  • The AI module adopts an interface-based design, allowing flexible integration of different vision models;
  • The Dashboard functions purely as the control and presentation layer, and does not participate in image processing.

---

1.3. Practical Applications ⌃

Sentinel is not only a real-time monitoring tool, but also an extensible platform for visual data acquisition and analysis. Its LAN-based localized operation gives it practical value in the following scenarios:

Local Privacy-Oriented Monitoring Solution All data is fully stored on the local LAN PC No reliance on cloud storage or third-party platforms No need for additional storage cards or subscription fees Suitable for private environments such as homes, laboratories, and studios AI Behavior Analysis Experimental Platform Supports integration of multimodal vision models Output structure can be controlled through Prompt engineering Outputs person count, activity, risk level, and confidence Suitable for behavior recognition and risk analysis research

Data Acquisition & Analysis Prototype System Automatically generates structured JSON event records Local video and logs are traceable Convenient for subsequent statistical analysis and model optimization Can serve as a small-scale visual data collection prototype Distributed Vision System Architecture Example Android-side acquisition + PC-side processing State machine–driven trigger-based AI analysis FrameBuffer decoupled architecture design Suitable for teaching and system architecture demonstrations

---

2. Implemented Features ⌃

2.1. Real-time Video Preview ⌃

Sentinel provides browser-based real-time video preview capability. The camera feed captured by the Android device is continuously uploaded to the server as single JPEG frames, and the server pushes real-time images to the browser via an MJPEG stream.

This mechanism has the following characteristics:

Implemented based on MJPEG streaming — the browser can parse and refresh frames in real time without any plugins. No additional client software required — users only need to access the Dashboard address through a browser to view the live video. Low-latency transmission within LAN — under the same Wi-Fi network, end-to-end latency is typically at the millisecond level. Decoupled architectural design — real-time preview reads the latest frame from FrameBuffer and does not interfere with recording or AI analysis modules. Supports dynamic parameter adjustment — stream FPS and JPEG compression quality can be modified via configuration to adapt to different device performance and network conditions. Fully localized storage and data control — unlike traditional monitoring solutions that rely on SD cards or cloud storage, Sentinel saves video data directly on the LAN PC. Local disk storage avoids cloud service fees and third-party data risks, and also facilitates subsequent data analysis, model training, or secondary processing.

Figure 2 - Dashboard Live Preview Interface (Full-screen Mode)

---

2.2. System Parameter Customization ⌃

Sentinel is not a fixed-behavior “black-box monitoring tool”, but a highly configurable real-time vision system. Users can finely control video streaming, recording strategies, and AI behavior through the Dashboard to adapt to different hardware environments and application scenarios.

System parameters are mainly divided into three categories: ① Video Stream Parameters Stream FPS (real-time preview frame rate), JPEG Quality (image compression quality), Upload FPS (upload rate)… Users can balance image quality and network bandwidth, making it suitable for weak network conditions or low-performance device environments. ② Recording Strategy Parameters Record FPS (recording frame rate), Segment Seconds (segment duration), Codec (video encoding format)… Configures segmented writing and video encoding to avoid oversized single files and facilitate long-term operation and archival management. ③ AI Behavior Parameters OBSERVE Interval (detection interval), Motion Threshold (motion trigger threshold), Prompt Template / Scene Profile … These parameters allow adjustments to “AI trigger sensitivity” and “model decision logic” via the Settings page, optimizing token usage and enabling personalized monitoring scenarios.

Figure 3 - Dashboard Parameter Control Interface (Expanded View)

---

2.3. AI Trigger-based Monitoring and Controllable Cognitive Output ⌃

With the support of multimodal vision models, Sentinel is capable not only of “seeing the scene”, but also of performing structured understanding and risk assessment. The system adopts a layered mechanism of “motion trigger + model analysis”:

• Uses “traditional computer vision algorithms + large model inference” for layered processing, reducing token consumption and API costs;
• When trigger conditions are met, the system calls the model and enters the OBSERVE state;
• Invokes the vision model for semantic analysis and outputs structured JSON results;
• Records observation results and displays them in real time on the Dashboard.

AI module capabilities include: ① Structured Semantic Output Under the current configuration, model analysis outputs follow a unified structure: whether a person is present (has_person), risk level (risk_level), confidence (confidence), scene summary (summary)… Structured outputs facilitate subsequent rule engine processing or statistical data analysis. ② Event-level State Management The system records the complete lifecycle of a defined event: SLEEP → OBSERVE state machine, trigger/duration statistics, AI call health monitoring… This allows the system not only to determine whether an event has occurred, but also to manage the evaluation criteria of such decisions. ③ Flexible Model Rule Configuration Users can modify multiple prompt-related parameters: Prompt Template (role definition), Scene Profile (long-term scene context), Session Focus (short-term task focus), Extra Rules (additional constraints) to make model behavior programmable and controllable.

Figure 4 - AI Enabled Status

---

2.4. Mobile Camera Capture Application (CamFlow) ⌃

Sentinel does not rely on dedicated surveillance cameras. Instead, it provides a self-developed Android client CamFlow to handle image acquisition and data upload.

CamFlow transforms an ordinary smartphone into a real-time camera endpoint and:

① Real-time Image Capture and Upload Invokes the device’s native camera Continuously uploads frames in single JPEG format Configure upload rate, JPEG quality and resolution preference in Settings Allows at most two outstanding uploads, with status counters and no queued backlog; concurrent arrivals can be out of order ② Manual Configuration and Connection Displays the CamFlow IP:PORT beside the Dashboard subtitle and in command-line startup output Requests this address on first launch and tests the saved connection on subsequent launches Validates IP, port, and HTTP/HTTPS addresses and provides real-time diagnostics Allows specifying a particular device camera (code-level interface) ③ Runtime Control Supports start/stop capture Allows preview to be disabled for power saving Provides runtime status feedback CamFlow and the PC side together form a complete system architecture of “mobile acquisition + local processing,” enabling the construction of a real-time vision system without additional hardware devices.

Figure 5 - CamFlow Application Interface

📘 For detailed functionality and usage instructions, please refer to CamFlow User Guide.

---

Contributing 🤝

This project is still evolving, and contributions and issues are highly welcome!

If you have ideas, improvements, or bug fixes, feel free to open a PR or submit an issue. Even small contributions are meaningful — feel free to jump in.

---

3. Project Deployment ⌃

Please complete the basic project deployment in the following order:

• Obtain the project source code
• Deploy the PC-side server
• Install the Android client APK

Project Structure 📂

Sentinel/
│
├── server.py                     # Program entry point (starts Flask, initializes runtime environment, launches threads)
├── README.md                     # Project documentation
├── CamFlow_UserGuide.md          # Android user guide
├── requirements.txt              # Dependency installation list
├── version.properties            # Shared version metadata for PC, Android, and documentation
├── Sentinel.cmd                  # Windows desktop entry point
├── sentinel_desktop.py           # Desktop window and service controls
├── .gitignore                    # Git ignore rules
├── LICENSE                       # MIT License
│
├── app/                          # Main application package
│   │
│   ├── __init__.py               # Package initialization
│   │
│   ├── ai/                       # AI-related modules (optional)
│   │   ├── ai_ark.py             # Vision model interface implementation (replaceable)
│   │   ├── ai_monitor_worker.py  # AI monitoring thread (SLEEP/OBSERVE state machine)
│   │   ├── ai_store.py           # AI event writing and persistence
│   │   ├── motion_trigger.py     # Low-cost motion detection module
│   │   └── __init__.py
│   │
│   ├── config/                   # Configuration management module
│   │   ├── config.json           # Automatically generated after saving in Dashboard
│   │   ├── config_store.py       # Configuration validation and read/write logic
│   │   └── __init__.py
│   │
│   ├── core/                     # Core runtime modules
│   │   ├── auth.py               # Administrator sessions and device pairing
│   │   ├── frame_buffer.py       # Latest frame cache (system data sharing center)
│   │   ├── logger.py             # Logging initialization
│   │   ├── runtime.py            # Global runtime state management
│   │   ├── upload_stats.py       # Upload statistics
│   │   └── __init__.py
│   │
│   ├── net/                      # Networking modules
│   │   ├── net_discovery.py      # Retained experimental LAN module (not enabled by the default workflow)
│   │   └── __init__.py
│   │
│   ├── recorder/                 # Video recording module
│   │   ├── storage.py            # Registered recording retention and disk protection
│   │   ├── recorder.py           # Video writing logic
│   │   ├── recorder_worker.py    # Recording thread controller
│   │   └── __init__.py
│   │
│   └── web/                      # Web interface and API layer
│       ├── webapp.py             # Flask routes and APIs
│       ├── upload_diagnostics.py # Upload timing and request correlation
│       ├── __init__.py
│       │
│       ├── static/               # Frontend static assets
│       │   ├── access.js          # Login, access state and camera pairing
│       │   ├── dashboard.js
│       │   └── style.css
│       │
│       └── templates/            # HTML templates
│           └── dashboard.html
│
├── PhoneCamSender/               # Android client source code (Android Studio project)
│   ├── app/                      # Android application module
│   ├── gradle/                   # Gradle configuration
│   ├── build.gradle.kts
│   ├── settings.gradle.kts
│   ├── ...
│   ├── CamFlow-v1.1.2.apk        # Current locally built installation package (debug-signed)
│   ├── CamFlow-v1.1.1.apk        # Retained legacy installation package
│   └── CamFlow-v1.1.0.apk        # Retained legacy installation package
│
├── assets/                       # Images used in README
│   ├── app_main_page.jpg
│   ├── app_setting_page.jpg
│   └── app_failed_hint.jpg
│
├── log/                          # Runtime log directory (empty at first run)
│   ├── server.log                # System runtime log
│   └── ai_events.jsonl           # AI event records
│
└── recordings/                   # Video and snapshot output directory (empty at first run)
    ├── snapshots/
    └── videos/

---

3.1. Environment Requirements ⌃

PC Side	Android Side
Python 3.9 or above	Android 8.0 or above
Windows / macOS / Linux	Allow installation from unknown sources
Git installed (for cloning repository)	Connected to the same local area network as the PC

---

3.2. Obtain the Project Source Code ⌃

Execute in the cmd terminal:

git clone https://github.com/suzuran0y/CCTV-Smartphone-AI-Monitoring.git
cd CCTV-Smartphone-AI-Monitoring

---

3.3. PC-side Deployment ⌃

3.3.1. Create a Virtual Environment (Recommended)

Windows System

python -m venv venv            # Create virtual environment
venv\Scripts\activate          # Activate virtual environment

macOS / Linux System

python3 -m venv venv
source venv/bin/activate

3.3.2. Install Dependencies

pip install -r requirements.txt

The dependency list includes:

flask>=2.2                     # Web service
numpy>=1.23                    # Image data processing
opencv-python>=4.8             # Image decoding and video writing
volcenginesdkarkruntime        # AI module dependency

3.3.3. Windows Desktop

On Windows 10 or 11, double-click Sentinel.cmd in the project root. For the first launch, install Python 3.12 and accept the prompt to create .venv and install the desktop dependencies. If Sentinel prompts for Microsoft Edge WebView2 Evergreen Runtime, install it and open Sentinel again.

If you are using the Windows x64 package, keep the Sentinel folder intact and double-click Sentinel.exe. See the Windows desktop guide for package and data-folder instructions.

---

3.4. Android-side Deployment ⌃

Compatibility: use CamFlow v1.1.2 with this authenticated server; v1.1.0 / v1.1.1 cannot upload anonymously.

The Android application CamFlow is responsible for camera capture and image upload.
The application source code is located in the repository path:

PhoneCamSender/

The precompiled APK file is located at:

PhoneCamSender/CamFlow-v1.1.2.apk

3.4.1. Quick Installation via APK (Recommended)

For general users, installing via the APK file is the most convenient method:

1. Use the APK file included in the cloned repository or download it from the project’s Release page;

2. Open the APK file and install CamFlow on the Android device;

3. If prompted by the system, allow installation from unknown sources, then complete installation and launch the application.

3.4.2. Build and Install via Android Studio (Optional)

For developers who want to debug or modify features, the app can be built from source:

1. Open Android Studio;

2. Open the project directory: Sentinel/PhoneCamSender;

3. Connect an Android device;

4. Wait for Gradle synchronization to complete, then run the project.

📘 For detailed Android-side functionality and usage instructions, please refer to CamFlow User Guide.

---

4. Run the Project ⌃

Start Sentinel on the PC, connect CamFlow over the local network, then enable Ingest in Dashboard to see the camera. Ingest and recording start switched off.

---

4.1. Start the PC Side (Server + Dashboard) ⌃

4.1.1. Windows Desktop

1. Double-click Sentinel.cmd and click Start Sentinel.
2. On first use, click Show token, save the token, and enter it in the access panel at the top of Dashboard. Click I saved the token to dismiss the token panel.
3. Enter the CamFlow address next to the Dashboard subtitle in the phone app. Follow the camera pairing steps, then enable Ingest.
4. Click Stop Sentinel to finish the current recording and stop the service. Minimizing keeps it running. Closing the window while the service is running asks whether to stop and exit.

4.1.2. Command Line and Browser

From the project root, run:

python server.py

Open the Dashboard address printed in the terminal on the PC. The terminal displays the administrator token on first startup. Other devices on the same network can open the LAN Web address in a browser. For the phone app, use the address labeled CamFlow.

---

4.2. Start CamFlow (Android App) ⌃

4.2.1. Prerequisites

• The PC and the mobile device must be connected to the same local area network (same Wi-Fi);
• The PC-side service must already be running, and the Dashboard must be accessible in the browser.

4.2.2. Connection Methods

• CamFlow now uses manual address configuration and does not attempt automatic server discovery.
• On first launch, the app prompts for the Sentinel server address.
• Start Sentinel on the PC and enter the CamFlow address shown beside the Dashboard subtitle or in the terminal:

CamFlow:    192.168.1.10:8000

You can change the address later in Settings. Use Test connection first, then select Save after the connection succeeds.

4.2.3. Start Uploading (Push Frames)

1. Sign into Dashboard and click Add CamFlow to generate a pairing code.
2. In CamFlow Settings, enter the server address, device name and code; tap Pair / Re-pair, then Save.
3. The administrator enables Ingest. CamFlow captures and uploads while the camera is running and its credential remains valid.

A successful Test connection only confirms reachability, not upload permission. See camera pairing and the phone-side pairing procedure.

4.2.4. View the Camera on the PC

• Open Dashboard in the desktop window or in a browser at the address printed in the terminal.

• Since Ingest is OFF by default, the Live View section will initially display Ingest OFF - enable in dashboard instead of the camera feed.

• After administrator login, click Enable Ingest to check whether Live View displays video. If no video appears, expand the Logs section under Live View (collapsed by default) and check for messages such as ingest disabled, then adjust settings accordingly.

• Under normal conditions, once Ingest is switched to ON, the Live View section in the Dashboard will immediately update with the camera feed from the device.

At this point, the CamFlow service and data transmission to the PC have been successfully started.
For detailed usage instructions of CamFlow, please refer to the repository documentation: CamFlow User Guide.

---

4.3. Dashboard Guide ⌃

Dashboard uses dashboard.html, access.js, dashboard.js and style.css; data and access checks come from backend APIs. The controls below require administrator login. Visitors only receive the viewing access described in Viewing modes.

---

4.3.1. Page Structure

The layout of the Dashboard is divided into three sections: top bar + left monitoring panel + right settings panel.

• Top Bar
  • Title: Sentinel System Dashboard and subtitle: Vision Monitoring & Risk Detection System
  • Access panel is collapsed on load and after sign-in. Expand it to sign in, remember this device, log out or manage paired cameras.
  • CamFlow next to the subtitle shows the server address to enter on the phone when LAN access is available.
  • Button: Shutdown (administrator only)
• Left Panel
  • Live View: real-time video preview + quick control buttons
  • Monitor Status: system status summary + Logs: system logs
• Right Panel
  • Settings: all configurable parameter input fields
  • AI Monitoring: AI module switches and configuration
  • Apply / Save / Load: configuration application and persistence

The divider between panels is draggable, allowing adjustment of the display ratio;
Click the Collapse button to hide the right-side Settings panel and enlarge the Live View area.
Click Expand Settings to the left of Shutdown to reopen the panel. In a narrow desktop window, Settings appears below the monitoring area.

---

4.3.2. Live View Section

The latest frame uploaded from the mobile device enters the PC-side FrameBuffer, and the browser continuously refreshes the display in Live View via /stream using MJPEG.

① Display Logic

The video shown in Live View depends on whether CamFlow is uploading frames and whether PC-side Ingest (allowing /upload to write into FrameBuffer) is enabled.

• When Ingest is OFF: displays Ingest OFF - enable in dashboard;
• When Ingest is ON but no frame has been received yet: displays Waiting for frames....

---

② Core Button Area

Below Live View, there are three buttons. All are OFF by default:
Enable Ingest, Start Recording, Snapshot.

1. Enable / Disable Ingest

   • Function: controls whether the server accepts image uploads from CamFlow;
   • Feature: when clicking Disable Ingest, the preview immediately returns to placeholder state, allowing easy observation of data flow;
   • Usage: click to toggle Ingest ON/OFF.

2. Start / Stop Recording

   • Function: controls whether the recording thread writes FrameBuffer data into segmented video files;
   • Feature: recording and preview functions are independent. Recording only requires Ingest to be ON;
   • Output path structure: recordings/videos/YYYYMMDD/<cam_name>_YYYYMMDD_HHMMSS.mp4; XVID/MJPG fallback files use .avi;
   • Usage: click to toggle Recording ON/OFF.

3. Snapshot

   • Function: saves the current frame as an image.
   • Output path structure: recordings/snapshots/YYYYMMDD/snapshot_YYYYMMDD_HHMMSS.jpg, configurable in Settings;
   • Usage: click to trigger screenshot.

---

4.3.3. Monitor Status Section

Monitor Status is an area that aggregates system runtime information and refreshes dynamically according to current system settings.

The table below provides a structured explanation of core fields:

Field	Format	Meaning	Usage & Troubleshooting
Ingest	Boolean (ON / OFF)	Whether camera uploads are being accepted	If OFF, /upload will be rejected. If no video appears, check this first
Recording	Boolean (ON / OFF)	Whether video recording is currently active	If ON but no file is generated → check Output Root, codec, or recording thread
Last frame age	Number (seconds)	Time since the last successfully written frame	Should remain at small fractions of a second. If continuously increasing → upload interrupted or rejected
Upload FPS	Number (frames/sec)	Estimated upload frame rate	Close to 0 → CamFlow not uploading or Ingest is OFF
Stream FPS	Number (frames/sec)	Browser MJPEG refresh rate	Reduce if browser lags; too high increases CPU usage
JPEG Quality	Number (0–100)	Preview image compression quality	Higher quality = clearer image but higher load; high quality + high FPS may cause performance pressure
Frame stale after (sec)	Seconds	Mark the image stale after no new frames	Default 5; range 1–120.
Pause recording after no frames (sec)	Seconds	Close the current recording segment after a gap	Default 5; range 1–300.
Resume recording after camera returns	Automatic / Manual	Open a new segment on recovery, or stop until manually started	Default Automatic.
Record FPS	Number (frames/sec)	Recording frame rate	Too high increases disk pressure; too low results in choppy video
Segment Seconds	Number (seconds)	Video segmentation duration	Reduce if files become too large; too small generates many files
Recording file	String (file path)	Current video file being written	If Recording = ON but empty → recording thread not functioning properly
Rec elapsed	Time string (HH:MM:SS)	Duration of current recording session	If not increasing → recording not actually started
Seg remaining	Number (seconds)	Remaining time for current segment	Abnormal jumps → time configuration or segmentation logic error
Upload counts	Structured counter fields	Upload result statistics	Increases when Ingest is ON; contains multiple subfields

---

Upload counts Field Breakdown:

Subfield	Meaning	Normal Trend	Abnormal Explanation
200_ok	Successful upload and write count	Should continuously increase	If not increasing, no valid uploads
400_missing_image	Request missing image field	Should remain 0	Client field name error
400_decode_failed	Data received but failed to decode	Should remain 0	Data corruption or non-JPEG content
503_ingest_disabled	Rejected uploads due to Ingest OFF	Increases when Ingest = OFF	Ingest not enabled

---

4.3.4. Logs Section

Below Monitor Status, there is a collapsible Logs area used to view real-time server runtime logs.

• Collapsed by default; click the Logs row to expand;
• Logs are read from log/server.log (generated during project runtime);
• When the system encounters issues, open the Logs section to inspect runtime information.

Note: Logs only display the most recent 50 entries.
To review earlier logs, open the log/server.log file directly to view the complete content.

---

4.3.5. Settings Section

The right-side Settings panel contains system parameter input fields and configuration buttons.
When modifying system configuration, parameters must first be adjusted in the Settings area and then applied to the system.

① Settings Fields

The table below explains configuration options available in the Dashboard.

It is recommended to understand the “purpose” and “recommended range rationale” before modifying parameters to avoid performance or stability issues.

Configuration	Format	Purpose	Recommended Range
Viewing mode	Default / Privacy	Controls visitor access	See viewing modes; changing this setting persists configuration even with Autosave off.
Stream FPS	Number (frames/sec)	Controls MJPEG refresh rate in browser	Recommended 8–15. Too high increases CPU and bandwidth usage; below 5 causes noticeable lag.
JPEG Quality	Number	Controls JPEG compression quality	Recommended 60–80. Too low causes blur; too high significantly increases CPU load at high FPS.
Record FPS	Number (frames/sec)	Controls recording frame rate	Recommended 10–15. Too high increases disk pressure and file size; below 8 reduces smoothness.
Segment Secs	Number (seconds)	Controls video segmentation duration	Recommended 60–3600. Too large creates huge files; too small creates many fragments.
Output Root	String (file path)	Video and snapshot output directory	Recommended default recordings; avoid system root directories or unauthorized paths.
Cam Name	String (identifier)	Camera identifier written into filenames	Recommended simple identifiers (e.g., phone1); avoid spaces or special characters.
Codec	String (FourCC)	Video encoding format: mp4v / XVID / MJPG / avc1	mp4v is the recommended Windows default. The recorder falls back to XVID/MJPG if needed. avc1 requires an H.264/OpenH264 library compatible with the installed OpenCV build.
Autosave	Boolean (true / false)	Whether to automatically write to config.json after clicking Apply	Recommended enabled during development; disable during frequent experimentation to avoid overwriting configurations.

---

Note: Parameter modifications do not take effect automatically.
Changes must be applied using the buttons below.
It is recommended to stop current system tasks before applying new parameters to ensure full effect.

② AI Monitoring Section

Under default configuration, the AI module is disabled.
To enable it, click the Enable button on the right side of the AI Monitoring panel.
Once enabled, AI settings and status sections will appear on the Dashboard.

For detailed information, refer to 4.4. AI Monitoring Features.

③ Application Buttons

• Difference between Apply / Save / Load

  • Apply

    • Submits current input parameters to backend /api/config and immediately updates runtime configuration.
    • If parameters are invalid (out of range / wrong type), the backend will reject and return an error message.

  • Save

    • Writes the current configuration to local file (app/config/config.json).

  • Load

    • Loads config.json from disk and refreshes the page form.

• On first system startup, a pre-filled configuration set is used;
• To customize system configuration, modify parameters in the Settings panel and click Apply;
• (If Autosave is not enabled) click Save to persist configuration locally;
• Later, click Load to reload saved configuration into the form without re-entering values.

---

4.3.5.1. Recording Retention and Disk Protection

Setting	Default	Behavior
record_cleanup_enabled	false	Explicit administrator confirmation enables permanent deletion of registered completed recordings
record_retention_days	7	Expired recordings are removed first
record_max_storage_gb	20 GiB	Remove oldest completed recordings when over quota
record_min_free_gb	1 GiB	Stop/reject recording when disk space is low; display the reason in Dashboard

Cleanup only touches completed recordings registered by this version under the current Output Root’s videos directory. It excludes active segments, snapshots, unregistered historical files and manually placed files, and refuses symlinks or Windows junctions. Deletion bypasses the recycle bin. Unregistered files still consume disk space and need separate management. Periodic quota enforcement is not a hard disk quota; an active segment can temporarily exceed it. Changing the output directory leaves previous directories for manual management.

Adjust these fields in Settings and click Apply as an administrator; enabling cleanup requires confirmation of permanent deletion.

---

4.3.6. Shutdown

⚠️ This is the “terminate service” button.
The top Shutdown button triggers the system shutdown procedure: stop recording, disable ingest, stop the Python service, and attempt to close the page.

---

4.3.7. Administrator Access and Token Recovery

Expand the access panel at the top and enter the administrator token shown once by the PC on first startup. The panel starts collapsed on every page load and closes after a successful sign-in.

By default, an administrator session lasts up to 8 hours. On a trusted device, reopen the access panel after signing in and select Remember this device for 30 days to stay signed in when reopening the same browser or desktop app. Select Stop remembering this device to turn this off, or Log out to end the session immediately. Resetting the administrator token ends all administrator sessions.

If you lose the token, stop Sentinel and select Reset administrator token in the desktop window. For a command-line installation, stop the service and run python server.py --reset-admin-token with the same data directory. Save the replacement token. Paired cameras can continue using their existing credentials.

4.3.8. Default and Privacy Viewing Modes

Mode / identity	Permission
Default-mode visitor	Live view and basic status only
Privacy-mode visitor	Login page only; video and status require administrator login
Administrator	Configuration, recording, snapshots, logs, AI events, shutdown and device management
Paired CamFlow	Image upload only, no management permissions

Select Viewing mode and click Apply. Changing the mode saves the current configuration even with Autosave off. Privacy mode stops existing anonymous streams; it cannot recall images already viewed or saved.

Authentication does not encrypt transport. Default HTTP is for trusted LANs, not direct public exposure; configure HTTPS for untrusted networks. Cloud AI sends sampled images to the selected model provider.

4.3.9. Camera Pairing and Revocation

1. Sign in as administrator and click Add CamFlow.
2. Enter the 8-character code in the phone’s Settings together with its server address and device name.
3. Tap Pair / Re-pair, then Save, and enable Ingest in Dashboard.

Codes are single-use and expire after 5 minutes; generating a new code replaces the previous one. Never enter the administrator token on the phone. Follow the CamFlow pairing guide for phone-side operations.

Android Keystore encrypts each device credential, binds it to its server address and excludes it from backups. The server stores only device-token hashes. Click Revoke for an individual camera to invalidate its credential. Changing servers, clearing local credentials or revocation requires pairing again.

Multiple paired phones share one frame buffer; they do not create independent camera feeds. See upload diagnostics for rejected or stalled uploads.

---

4.3.10. Frame Freshness and Recording Recovery

Below Live View, the page identifies live frames, waiting for frames, Ingest off, or stale frames. By default, 5 seconds without a new frame marks the image stale; the stream itself also overlays STALE on the old image. Fresh uploads automatically restore live state. Failed status requests show that the server is unavailable rather than labeling an old image live. Snapshots require a fresh frame.

Configure Frame stale after (sec) and Pause recording after no frames (sec) independently in Settings, then click Apply. By default, recording closes its current segment after a 5-second gap and waits. With Resume recording after camera returns set to Automatic, fresh frames start a new segment; Manual stops recording until Start Recording is pressed. No old image is recorded when Ingest is off or no frame exists. Disk protection and manual Stop do not automatically restart recording.

Within the threshold, the latest frame is still written at Record FPS. The recording does not fill the entire outage with a still image; segments before and after recovery remain separate files.

4.3.11. Multiple Viewers and Shared Encoding

Browsers viewing the same feed reuse the JPEG for the same frame and JPEG Quality. New frames, image-state transitions or quality changes refresh the encoded result. Stream FPS still controls each connection’s send rate, and each viewer still consumes bandwidth. Encoding uses a separate lock and does not hold the upload frame-buffer lock.

4.3.12. Browse and Download Recordings and Snapshots

After administrator login, expand Recordings & Snapshots on the left. Select Recordings or Snapshots, click Refresh, and use Previous / Next for pages of up to 25 items. The list shows filenames, modification times, sizes and Download links, newest modified first. No deletion controls are provided.

Only recordings and snapshots under the current Output Root that follow the system’s filename rules are listed, including matching historical files. The active recording segment is hidden and cannot be downloaded; refresh after it closes. Downloads require administrator login; visitors and paired phones cannot access them. Symbolic links and Windows junctions are rejected.

Changing Output Root switches the browser to that directory; old directories remain on disk. Cleanup may remove a listed file before download, in which case refresh the list. Listing a historical file does not register it for automatic cleanup.

---

4.3.13. Desktop Appearance

Use Appearance in the desktop toolbar to switch between Default · Light, Default · Dark, and Windows XP · Luna Blue. Sentinel remembers the selected theme. The live view and current sign-in stay open while you switch. The light appearance is shown in Figure 1.

Default · Dark

Windows XP · Luna Blue

---

4.4. AI Monitoring Features (Optional Feature) ⌃

The AI module is an optional enhancement module:
Even without configuring any API Key, the system can fully operate basic functions such as video upload / live preview / recording / snapshot / logs.

Sentinel’s AI module adopts an event-driven layered trigger-based visual cognition architecture.
Instead of performing inference on every frame, the system uses lightweight motion detection, a dual-state machine control mechanism, and structured event management to achieve lower-cost long-term intelligent monitoring.

The modular design supports pluggable models, structured output contracts, and system decoupling, ensuring scalability, interpretability, and maintainability.

---

AI Module Main Workflow Framework (From Frame to Dashboard)

┌─────────────────────────────────────────────────────────────────────┐
│                            Data Input Layer                    
│  CamFlow → POST /upload → FrameBuffer (Latest Frame Cache)  
└──────────────────────────────┬──────────────────────────────────────┘
                               │
                               ▼
┌─────────────────────────────────────────────────────────────────────┐
│                Lightweight Motion Trigger Layer (Cost Reduction)    
│  - Compute frame difference ratio                            
│  - If motion_ratio > threshold                                
│  - Trigger frequency controlled by Motion Min Interval        
└──────────────────────────────┬──────────────────────────────────────┘
                               │
                               ▼ If triggered, STATE: SLEEP → OBSERVE
┌─────────────────────────────────────────────────────────────────────┐
│                     AI State Machine Control Layer            
│    STATE ∈ { SLEEP, OBSERVE }                                
│  SLEEP:                                                       
│    - Only runs motion trigger                                 
│    - Does not call model                                      
│  OBSERVE:                                                     
│    - Calls model every AI Interval                            
│    - Manages dwell timing                                     
│    - Calculates event_duration                                
└──────────────────────────────┬──────────────────────────────────────┘
                               │
                               ▼
┌─────────────────────────────────────────────────────────────────────┐
│                      Vision Model Interface Layer              
│  - Construct Prompt (Role + Scene + Session + Extra)         
│  - Compress JPEG (AI JPEG Quality)                            
│  - Call third-party vision model API                          
│  - Receive JSON output                                        
│  - Perform Output Contract validation                         
└──────────────────────────────┬──────────────────────────────────────┘
                               │
                               ▼
┌─────────────────────────────────────────────────────────────────────┐
│                 Event Lifecycle Management Layer              
│  - dwell ≥ threshold → confirmed                              
│  - No target ≥ End Grace → end event                          
│  - Write to ai_events.jsonl                                   
│  - Update AI runtime status                                   
└──────────────────────────────┬──────────────────────────────────────┘
                               │
                               ▼
┌─────────────────────────────────────────────────────────────────────┐
│                      Visualization & Display Layer            
│  - /api/ai_status                                             
│  - Display current AI Result                                  
│  - Display Info: Times, Metrics                               
│  - Display History List                                       
└─────────────────────────────────────────────────────────────────────┘

---

4.5. Dashboard AI Module Guide ⌃

When the Dashboard page is first opened, the AI module is disabled by default.
Click the Enable button on the right side of the AI Monitoring panel to activate the AI module.

The AI module on the Dashboard consists of two parts:

• AI Settings (Configuration Area): determines whether AI is enabled, call frequency, thresholds, etc.;
• AI Status (Information Area): displays state machine status, health status, and AI monitoring history.

---

4.5.1. AI Settings Fields

It is recommended to understand the purpose of each parameter before enabling the AI module, in order to control model call sensitivity and reasonably tune for different scenarios.

Configuration	Format	Purpose	Recommended Value
Provider	Select option	Selects the active visual model platform	Ark, OpenAI, Gemini, DashScope, SiliconFlow, or OpenAI-compatible / Local.
Model ID	String (model ID)	Specifies the generic visual model ID	Use a vision-capable model ID; Ark can be left empty to fall back to Legacy Ark Model.
Provider Hint	Auto hint	Shows the default Base URL, key source, and model guidance for the selected Provider	Updates automatically when the Provider changes to reduce configuration mistakes.
Base URL	String (endpoint URL)	Custom third-party / local model service URL	Can be left empty for built-in Providers; usually required for openai_compatible.
Provider API Key	String (key)	Generic model service credential	Must be obtained from the provider. See 4.6. Third-party Model Integration.
Timeout (sec)	Number (seconds)	Timeout for one model request	Allowed range: 5–120 seconds; default: 30 seconds.
Legacy Ark Model	String (model ID)	Backward-compatible Ark / Volcengine model field	Used when Model ID is empty. Existing configurations may contain a retired model, so enter an available model in Model ID.
Legacy Ark API Key	String (key)	Backward-compatible Ark / Volcengine API Key	Used as an Ark fallback only when the generic Provider API Key is empty.
OBSERVE Interval (sec)	Number (seconds)	Minimum interval between model calls in OBSERVE state	Recommended 2–3 seconds. Too small increases token consumption.
Dwell Threshold (sec)	Number (seconds)	Duration a target must persist before confirming an event	Recommended 3–5 seconds. Increasing reduces occasional false positives.
End Grace (sec)	Number (seconds)	Delay before ending event after target disappears	Recommended 2–3 seconds to avoid interruption due to brief occlusion.
AI JPEG Quality	Number (50–95)	JPEG compression quality sent to model	Recommended 75–90. Too high increases bandwidth and encoding cost.
Motion Threshold (ratio)	Decimal (ratio)	Frame change ratio threshold for motion detection	Recommended 0.1–0.3. Lower values increase sensitivity; raise if AI triggers too frequently.
Motion Min Interval (sec)	Number (seconds)	Minimum time between motion triggers	Recommended 1–3 seconds to prevent excessive triggering.
Prompt Template (Role)	Long text (role definition)	Defines model role and output format specification	Recommend explicitly requiring “JSON-only output”.
Scene Profile (Long-term)	Long text (long-term context)	Provides fixed environmental background description	Describe camera position, scene type, etc.
Session Focus (Short-term)	Long text (temporary focus)	Temporary monitoring objective	Example: “Focus on whether strangers enter the area.”
Extra Prompt / Rules	Long text (additional rules)	Additional output format, language, or risk evaluation rules	Can specify output language or restrict fields.

Parameters usually require tuning according to lighting conditions, camera angle, and target types.
After modification, observe 1–2 complete event cycles before evaluating effectiveness.

---

① Detailed Explanation of Text-type Parameters (Recommended Reading)

The following four fields belong to Prompt engineering parameters and directly affect model output structure and semantic understanding.

• Prompt Template (Role): defines the model’s role and output structure.

Example:

You are a video surveillance assistant. You will receive a monitoring image and background information. Only output a JSON object including whether a person is present, number of people, activity, risk level, and a brief summary.

• Scene Profile (Long-term): provides long-term fixed background context to help the model determine what is considered “abnormal”.

Example:

Home scenario: the camera faces the living room.
Office scenario: the camera faces the workspace area. Multiple people during working hours are normal.

• Session Focus (Short-term): temporary task configuration that can change according to short-term requirements.

Example:

Currently focus on whether children approach the balcony area.

• Extra Prompt / Rules: supplementary output and language constraints.

Example:

Use Chinese for the summary.
If uncertain, keep has_person=false.

---

② Output Contract and Automatic Structure Constraint Mechanism

To ensure stable parsing of model outputs in the Dashboard, the backend implements an Output Contract mechanism.

Regardless of how the task is described in the Prompt Template, the model’s final output must conform to the predefined JSON structure required by the system.

---

4.5.2. AI Status Section

This area visualizes the runtime status of the backend AI state machine in real time.

① Status Header

Located at the top of the AI Status panel, displaying the current state machine runtime status:

┌────────────────────────┬──────────────────┬─────────────────┬──────────────────────┐
| STATE: SLEEP / OBSERVE | Event: evt_xxxxx | Dwell: Yes / No | Health: Fine / Error |
└────────────────────────┴──────────────────┴─────────────────┴──────────────────────┘

Field	Format	Meaning
STATE	SLEEP / OBSERVE	Indicates whether AI is currently active
Event	String (evt_xxxxx)	Current active event ID
Dwell	Yes / No	Whether dwell confirmation threshold has been reached
Health	Fine / Error	Whether the most recent model call succeeded

• Model Info shows the current Provider, client type, model ID, Base URL, whether the API Key is configured, request timeout, and a Ready / Needs ... configuration status.

• State Machine Description

🔹 SLEEP: only runs traditional vision algorithms; does not call the vision model; low resource consumption.

🔹 OBSERVE: periodically calls the vision model, analyzes structured fields, and performs event recording.

---

② Last AI Result

To stabilize output structure, the system enforces an Output Contract mechanism.
The model must output a JSON object containing at least the following fields:

{
  "has_person": bool,
  "person_count": int,
  "activity": str,
  "risk_level": "info|warn|critical",
  "confidence": float,
  "summary": str
}

After structured extraction, the Dashboard presents a human-readable format (example):

Person: No | Count: 0 | Activity: unknown | Risk: info | Conf: 99%
Summary: This indoor CCTV scene contains no people...

Field	JSON Key	Format	Description
Person	has_person	Boolean (Yes / No)	Whether a person is detected
Count	person_count	Number	Number of people
Activity	activity	String	Behavior description
Risk	risk_level	info / warn / critical	Risk level
Conf	confidence	0–100%	Model confidence
Summary	summary	String	Natural language summary

The system includes Output Contract safeguards.
If the model response is incomplete, it will be processed to ensure the Dashboard always receives valid output.

---

③ Time Information (Times)

Calculates runtime timing information for the event monitoring module (example):

Last trigger: 2026-02-24 01:48:37 (2m ago)
Last AI call: 2026-02-24 01:51:05 (6s ago)
Event start:  2026-02-24 01:48:37 (2m ago)

Field	Meaning
Last trigger	Most recent motion trigger time
Last AI call	Most recent model call time
Event start	Start time of current event

---

④ Event Metrics (Metrics) (Example)

Person present (acc): 115.0 s
Event duration: 153.9 s

Metric	Meaning
Person present (acc)	Accumulated time a person was confirmed present during event
Event duration	Total duration of the current event

Note: Only after dwell_confirmed (confirmed persistent presence) does the system begin accumulating effective person presence time.

---

⑤ Raw JSON Output

Below Metrics, there is a collapsible Raw JSON section used to view the latest original JSON output from the model.

• Collapsed by default; click Raw JSON to expand.

Useful for debugging Prompt configuration and checking field completeness.

---

⑥ History List

When the system runs for the first time, this section is empty.
After an event ends, it is written into log/ai_events.jsonl and displayed in chronological order on the page (example):

┌────────────────────────────────────────────────────────────┐
│ 2026-02-24 01:51:03   AI   🔴 critical                    
│ Person: Yes | Count: 1 | Activity: lingering              
│ Risk Level: critical | Confidence: 99%                    
│ Summary: A single person is lying prone...                
└────────────────────────────────────────────────────────────┘
┌────────────────────────────────────────────────────────────┐
│ 2026-02-24 01:50:48   AI   🟢 info                        
│ Person: Yes | Count: 1 | Activity: passing                
│ Risk Level: info | Confidence: 98%                        
│ Summary: One person is walking through the indoor space…  
└────────────────────────────────────────────────────────────┘
                            ...
                            ...
                            ...

Note: The History List only displays the most recent 20 records.
To review earlier entries, open log/ai_events.jsonl directly to view the complete content.

---

4.6. Third-party Model Integration ⌃

Sentinel’s AI module now uses a switchable visual model Provider architecture. You can switch to OpenAI, Gemini, DashScope, SiliconFlow, or other third-party / local visual model services that expose an OpenAI-compatible API through configuration.

Model switching can be completed through the Dashboard configuration panel, app/config/config.json, environment variables, or code defaults. The Dashboard can edit Provider / Model / Base URL / API Key / Timeout and display t</cam_name>

README 内容过长，已截取前 64 KB。完整内容请前往 GitHub 仓库查看。