heldar_kernel/services/
mediamtx.rs

1//! Live-view gateway integration: registers a camera's stream as a MediaMTX path (server-side,
2//! credentials never exposed to the browser) and returns HLS / WebRTC / RTSP playback URLs.
3
4use serde::Serialize;
5use serde_json::json;
6
7use crate::camera_url;
8use crate::config::Config;
9use crate::error::{AppError, AppResult};
10use crate::models::Camera;
11use crate::state::AppState;
12
13/// Software (libx264) encoder args for the live HEVC->H.264 preview transcode (the default path).
14const SOFTWARE_CODEC_ARGS: &str =
15    "-c:v libx264 -preset ultrafast -tune zerolatency -profile:v baseline -pix_fmt yuv420p -g 30";
16
17/// FFmpeg encoder args for the live preview transcode, selected by `HELDAR_LIVE_TRANSCODE_ENGINE`.
18/// `software` uses libx264 (CPU); `vaapi` offloads to an Intel/AMD render node; `nvenc` to an NVIDIA
19/// GPU. An unknown engine warns and falls back to software so a typo never breaks live preview.
20pub fn transcode_codec_args(cfg: &Config) -> String {
21    select_codec_args(&cfg.live_transcode_engine, &cfg.vaapi_device)
22}
23
24fn select_codec_args(engine: &str, vaapi_device: &str) -> String {
25    match engine {
26        "software" => SOFTWARE_CODEC_ARGS.to_string(),
27        // VAAPI: upload the decoded frames to the render node and encode with h264_vaapi.
28        "vaapi" => {
29            format!("-vaapi_device {vaapi_device} -vf format=nv12,hwupload -c:v h264_vaapi -g 30")
30        }
31        // NVENC: low-latency NVIDIA hardware encoder.
32        "nvenc" => "-c:v h264_nvenc -preset p1 -tune ll -profile:v baseline -pix_fmt yuv420p -g 30"
33            .to_string(),
34        other => {
35            tracing::warn!(
36                engine = %other,
37                "unknown HELDAR_LIVE_TRANSCODE_ENGINE; falling back to software (libx264)"
38            );
39            SOFTWARE_CODEC_ARGS.to_string()
40        }
41    }
42}
43
44#[derive(Debug, Serialize)]
45pub struct LiveUrls {
46    pub name: String,
47    pub hls_url: String,
48    pub webrtc_url: String,
49    pub rtsp_url: String,
50}
51
52/// Ensure a MediaMTX path exists for this camera and return its playback URLs.
53pub async fn ensure_live(state: &AppState, camera_id: &str) -> AppResult<LiveUrls> {
54    let cam: Option<Camera> = sqlx::query_as::<_, Camera>("SELECT * FROM cameras WHERE id = ?")
55        .bind(camera_id)
56        .fetch_optional(&state.pool)
57        .await?;
58    let cam = cam.ok_or_else(|| AppError::NotFound(format!("camera {camera_id} not found")))?;
59
60    let source = camera_url::stream_url(&cam, "sub")
61        .or_else(|| camera_url::record_url(&cam))
62        .ok_or_else(|| AppError::BadRequest("camera has no stream URL".into()))?;
63
64    let name = format!("cam_{camera_id}");
65    let api = state.cfg.mediamtx_api_url.trim_end_matches('/');
66
67    let existing = state
68        .http
69        .get(format!("{api}/v3/config/paths/get/{name}"))
70        .send()
71        .await;
72    let already = matches!(existing, Ok(ref r) if r.status().is_success());
73
74    if !already {
75        // Transcode to H.264 on demand: many cameras (e.g. these HikVision units) emit HEVC, which
76        // browsers can't play over HLS/WebRTC. FFmpeg decodes the camera stream and republishes
77        // H.264 to this path, but only while someone is actually watching (runOnDemand). The raw
78        // stream is still recorded untouched by the recorder; this decode is preview-only.
79        // $MTX_PATH / $RTSP_PORT are substituted by MediaMTX; credentials stay server-side. The
80        // video encoder args are selected by HELDAR_LIVE_TRANSCODE_ENGINE (software | vaapi | nvenc).
81        let codec_args = transcode_codec_args(&state.cfg);
82        let run_on_demand = format!(
83            "ffmpeg -nostdin -rtsp_transport tcp -timeout 10000000 -i {source} -an \
84{codec_args} \
85-f rtsp rtsp://localhost:$RTSP_PORT/$MTX_PATH"
86        );
87        let body = json!({
88            "runOnDemand": run_on_demand,
89            "runOnDemandRestart": true,
90            "runOnDemandCloseAfter": "10s",
91        });
92        let resp = state
93            .http
94            .post(format!("{api}/v3/config/paths/add/{name}"))
95            .json(&body)
96            .send()
97            .await
98            .map_err(|e| AppError::Other(anyhow::anyhow!("MediaMTX unreachable at {api}: {e}")))?;
99        let code = resp.status();
100        if !code.is_success() && code.as_u16() != 400 {
101            let txt = resp.text().await.unwrap_or_default();
102            return Err(AppError::Other(anyhow::anyhow!(
103                "MediaMTX add-path failed ({code}): {txt}"
104            )));
105        }
106    }
107
108    let hls = state.cfg.mediamtx_hls_base.trim_end_matches('/');
109    let webrtc = state.cfg.mediamtx_webrtc_base.trim_end_matches('/');
110    let rtsp = state.cfg.mediamtx_rtsp_base.trim_end_matches('/');
111    Ok(LiveUrls {
112        hls_url: format!("{hls}/{name}/index.m3u8"),
113        webrtc_url: format!("{webrtc}/{name}"),
114        rtsp_url: format!("{rtsp}/{name}"),
115        name,
116    })
117}
118
119#[cfg(test)]
120mod tests {
121    use super::*;
122
123    #[test]
124    fn codec_args_select_by_engine() {
125        assert_eq!(
126            select_codec_args("software", "/dev/dri/renderD128"),
127            SOFTWARE_CODEC_ARGS
128        );
129        let vaapi = select_codec_args("vaapi", "/dev/dri/renderD129");
130        assert!(vaapi.contains("h264_vaapi"));
131        assert!(vaapi.contains("/dev/dri/renderD129"));
132        assert!(select_codec_args("nvenc", "/dev/dri/renderD128").contains("h264_nvenc"));
133        // Unknown engine falls back to software (libx264).
134        assert_eq!(
135            select_codec_args("bogus", "/dev/dri/renderD128"),
136            SOFTWARE_CODEC_ARGS
137        );
138    }
139}
heldar_kernel/services/mediamtx.rs

heldar_kernel/services/
mediamtx.rs
