kunlang_video/docs/project-management.md

# Vehicle Video Service Project Management

## Project Summary

This project packages the vehicle video stack as a single deployable service bundle.

Main components:

- `vehicle_video_service`: C++ service for camera capture, RTMP push, MQTT heartbeats, live URL replies, record query, and record playback replies.
- Bundled SRS source: `external/srs-server-5.0-r3`.
- SRS live instance: low-latency live playback through RTMP to WebRTC/WHEP.
- SRS record instance: DVR segment recording and HTTP file serving.
- Built-in web configuration page: `http://<device-ip>:18080`.

Default install path:

```text
/opt/vehicle-video-service
```

Default record path:

```text
/media/record
```

## Current Services

Installed systemd services:

```text
vehicle-video-srs-live.service
vehicle-video-srs-record.service
vehicle-video-service.service
```

Legacy services to remove on old devices:

```text
srs-live.service
srs-record.service
video_manager.service
```

Removal command:

```bash
sudo systemctl disable --now srs-live.service srs-record.service video_manager.service
sudo rm -f /etc/systemd/system/srs-live.service
sudo rm -f /etc/systemd/system/srs-record.service
sudo rm -f /etc/systemd/system/video_manager.service
sudo systemctl daemon-reload
sudo systemctl reset-failed
```

## Build And Package

Build everything:

```bash
./scripts/build_all.sh
```

Build only SRS:

```bash
./scripts/build_srs.sh
```

Build only video service:

```bash
./scripts/build_video.sh
```

Package release:

```bash
./scripts/package_release.sh
```

Release artifact:

```text
dist/vehicle-video-service-aarch64.tar.gz
```

SRS is built out-of-tree into:

```text
build/srs/objs/srs
```

## Install / Upgrade

Recommended clean install from package:

```bash
mkdir -p /tmp/vvs-install
cd /tmp/vvs-install
tar -xzf ~/kunlang_video/dist/vehicle-video-service-aarch64.tar.gz
cd vehicle-video-service-aarch64
sudo ./install.sh
```

If extracting in `dist/`, old extracted files may be owned by root. Remove them with:

```bash
cd ~/kunlang_video/dist
sudo rm -rf vehicle-video-service-aarch64
tar -xzf vehicle-video-service-aarch64.tar.gz
cd vehicle-video-service-aarch64
sudo ./install.sh
```

For first install, `install.sh` enables and starts services. For upgrade installs, restart services after install:

```bash
sudo systemctl restart vehicle-video-srs-live.service vehicle-video-srs-record.service vehicle-video-service.service
```

## Web Configuration

Default URL:

```text
http://<device-ip>:18080
```

Default login:

```text
admin / admin123
```

Current web page capabilities:

- Edit MQTT settings.
- Edit camera channels: enabled, name, device node, bitrate, width, height, fps.
- Enable or disable live stream push.
- Enable or disable record stream push.
- Edit SRS root, record config path, app name, public network interface.
- Edit record path, DVR segment duration, retention days, disk cleanup threshold.
- Edit live and record SRS ports.
- Show runtime status as a channel table:
  - channel
  - device node
  - enabled/disabled
  - device exists/missing
  - running/stopped
  - reason
  - playback URL

Saving config writes:

```text
/opt/vehicle-video-service/bin/config.json
/opt/vehicle-video-service/srs/conf/live.conf
/opt/vehicle-video-service/srs/conf/record.conf
```

Runtime changes require service restart in the current version.

## Important Config Fields

SRS and record:

- `srs.root`: SRS runtime root directory.
- `srs.record_config`: SRS record config read by `RecordManager`.
- `srs.stream_app`: RTMP app name, default `camera`.
- `srs.live_enabled`: whether to push live stream branch.
- `srs.record_enabled`: whether to push record stream branch.
- `srs.record_path`: DVR mp4 root directory.
- `srs.dvr_duration_sec`: DVR file segment duration.
- `srs.retention_days`: record retention days.
- `srs.usage_threshold`: disk cleanup threshold, for example `0.9`.
- `srs.public_interface`: network interface used to generate playback URLs.

Ports:

- `live_rtmp_port`: RTMP ingest port for live SRS.
- `live_http_api_port`: SRS HTTP API / WHEP playback port.
- `live_http_server_port`: SRS static HTTP / HTTP-FLV port.
- `live_rtc_port`: WebRTC UDP media port.
- `record_rtmp_port`: RTMP ingest port for record SRS.
- `record_http_api_port`: HTTP API port for record SRS.
- `record_http_server_port`: HTTP port used for record playback files.

## Verification Commands

Service state:

```bash
systemctl status vehicle-video-srs-live.service
systemctl status vehicle-video-srs-record.service
systemctl status vehicle-video-service.service
```

Ports:

```bash
ss -lntup | grep -E ':(1935|2935|1985|2985|8080|2980|8000|18080)\b'
```

Logs:

```bash
journalctl -u vehicle-video-service.service -f
journalctl -u vehicle-video-srs-live.service -f
journalctl -u vehicle-video-srs-record.service -f
```

Package content:

```bash
tar -tzf dist/vehicle-video-service-aarch64.tar.gz | head
```

## Current Known Notes

- `main` is ahead of `origin/main`; remember to push when ready.
- Web config save does not hot-reload video pipelines yet.
- SRS config changes require service restart.
- `dist/vehicle-video-service-aarch64/` can contain root-owned files if install was run directly from that extracted directory.
- `external/srs-server-5.0-r3/trunk/objs/` is intentionally ignored.

## Backlog

- Add hot restart for a single camera channel.
- Add one-click restart buttons in the web page.
- Add port conflict checks before saving config.
- Add record path permission checks before saving config.
- Add GStreamer plugin check display.
- Add config backup and restore from the web page.
- Add safer credential handling for web login and MQTT password.
- Add live preview/playback links per channel in the web UI.