Skip to content

Your Android phone and your Windows PC, working as one. Local-first, end-to-end encrypted, no account.

15.9 KB
Raw Blame
// SPDX-License-Identifier: GPL-3.0-or-later
//! Linux Virtual Camera (`v4l2loopback`) discovery, registration, and
//! shared-memory-to-V4L2 YUYV frame output for `"NectarLink Webcam"`.

use std::{
    fs::{self, OpenOptions},
    io::Write,
    os::{fd::AsRawFd, unix::fs::OpenOptionsExt},
    path::{Path, PathBuf},
    process::{Command, Stdio},
    sync::{
        Arc, OnceLock,
        atomic::{AtomicBool, Ordering},
    },
    thread,
    time::Duration,
};

use nectarlink_vcam::{DEFAULT_MAPPING_NAME, LOCAL_MAPPING_NAME, SharedFrameMapping};

pub const CLSID_STR: &str = "{8E6C3B74-5D4A-4B9E-9A12-7C8F1E2D3A40}";
pub const FRIENDLY_NAME: &str = "NectarLink Webcam";
pub const REGISTER_ARG: &str = "--register-vcam";
pub const UNREGISTER_ARG: &str = "--unregister-vcam";

const MODULES_LOAD_CONF: &str = "/etc/modules-load.d/nectarlink-vcam.conf";
const MODPROBE_CONF: &str = "/etc/modprobe.d/nectarlink-vcam.conf";

const V4L2_BUF_TYPE_VIDEO_OUTPUT: u32 = 2;
const V4L2_PIX_FMT_YUYV: u32 = 0x5659_5559; // 'Y' 'U' 'Y' 'V'
const V4L2_FIELD_NONE: u32 = 1;
const V4L2_COLORSPACE_SMPTE170M: u32 = 1;
/// `_IOWR('V', 5, struct v4l2_format)` where `sizeof(struct v4l2_format) == 208` (`0xD0`).
const VIDIOC_S_FMT: libc::c_ulong = 0xC0D0_5605;

#[repr(C)]
#[derive(Clone, Copy)]
struct V4l2PixFormat {
    width: u32,
    height: u32,
    pixelformat: u32,
    field: u32,
    bytesperline: u32,
    sizeimage: u32,
    colorspace: u32,
    priv_: u32,
    flags: u32,
    ycbcr_enc: u32,
    quantization: u32,
    xfer_func: u32,
}

#[repr(C)]
struct V4l2Format {
    type_: u32,
    _pad: u32,
    pix: V4l2PixFormat,
    _rest: [u8; 200 - std::mem::size_of::<V4l2PixFormat>()],
}

/// Locates a `v4l2loopback` `/dev/videoN` device node by inspecting `/sys/class/video4linux`.
pub fn find_v4l2loopback_device() -> Option<PathBuf> {
    find_v4l2loopback_in_sysfs(Path::new("/sys"), Path::new("/dev"))
}

/// Testable helper that scans `<sysfs_root>/class/video4linux/video*` and `<dev_root>/video*`.
pub fn find_v4l2loopback_in_sysfs(sysfs_root: &Path, dev_root: &Path) -> Option<PathBuf> {
    let v4l_dir = sysfs_root.join("class/video4linux");
    if let Ok(entries) = fs::read_dir(&v4l_dir) {
        let mut candidates: Vec<(u8, String, PathBuf)> = Vec::new();
        for entry in entries.flatten() {
            let file_name = entry.file_name();
            let dev_name = file_name.to_string_lossy().into_owned();
            if !dev_name.starts_with("video") {
                continue;
            }
            let dev_node = dev_root.join(&dev_name);
            if !dev_node.exists() {
                continue;
            }
            let Ok(card_name) = fs::read_to_string(entry.path().join("name")) else {
                continue;
            };
            let lower = card_name.to_ascii_lowercase();
            if lower.contains("nectarlink") {
                candidates.push((0, dev_name, dev_node));
            } else if lower.contains("dummy video device") || lower.contains("v4l2loopback") {
                candidates.push((1, dev_name, dev_node));
            }
        }
        candidates.sort_by(|a, b| a.0.cmp(&b.0).then_with(|| a.1.cmp(&b.1)));
        if let Some((_, _, node)) = candidates.into_iter().next() {
            return Some(node);
        }
    }

    if sysfs_root.join("module/v4l2loopback").exists() {
        for idx in 0..16 {
            let dev = dev_root.join(format!("video{idx}"));
            if dev.exists() {
                return Some(dev);
            }
        }
    }
    None
}

fn has_v4l2loopback_module_installed() -> bool {
    static INSTALLED: OnceLock<bool> = OnceLock::new();
    *INSTALLED.get_or_init(|| {
        if let Ok(release) = fs::read_to_string("/proc/sys/kernel/osrelease") {
            let rel = release.trim();
            for root in ["/lib/modules", "/usr/lib/modules"] {
                let dep = Path::new(root).join(rel).join("modules.dep");
                if let Ok(contents) = fs::read_to_string(&dep)
                    && contents.contains("v4l2loopback")
                {
                    return true;
                }
            }
        }
        for bin in ["/sbin/modinfo", "/usr/sbin/modinfo", "modinfo"] {
            if let Ok(status) = Command::new(bin)
                .arg("v4l2loopback")
                .stdin(Stdio::null())
                .stdout(Stdio::null())
                .stderr(Stdio::null())
                .status()
                && status.success()
            {
                return true;
            }
        }
        false
    })
}

/// Returns the active `v4l2loopback` device node, module sysfs directory, or `modprobe` binary
/// when `v4l2loopback` is loaded or installed on this Linux host.
pub fn dll_path() -> Option<PathBuf> {
    if let Some(dev) = find_v4l2loopback_device() {
        return Some(dev);
    }
    let sys_mod = PathBuf::from("/sys/module/v4l2loopback");
    if sys_mod.exists() {
        return Some(sys_mod);
    }
    if !has_v4l2loopback_module_installed() {
        return None;
    }
    for candidate in ["/sbin/modprobe", "/usr/sbin/modprobe", "/bin/modprobe", "/usr/bin/modprobe"] {
        let p = PathBuf::from(candidate);
        if p.exists() {
            return Some(p);
        }
    }
    None
}

/// Returns `true` if `v4l2loopback` is currently loaded in the kernel or exposes a loopback node.
pub fn is_registered() -> bool {
    find_v4l2loopback_device().is_some() || PathBuf::from("/sys/module/v4l2loopback").exists()
}

/// Ensures `v4l2loopback` is registered, attempting `register_hklm()` when not already active.
pub fn ensure_registered() -> bool {
    if is_registered() {
        return true;
    }
    register_hklm().is_ok() && is_registered()
}

fn run_modprobe(args: &[&str]) -> Result<(), String> {
    let bins = ["/sbin/modprobe", "/usr/sbin/modprobe", "modprobe"];
    let mut last_err = String::from("modprobe not found");
    for bin in bins {
        match Command::new(bin)
            .args(args)
            .stdin(Stdio::null())
            .stdout(Stdio::null())
            .stderr(Stdio::piped())
            .output()
        {
            Ok(out) if out.status.success() => return Ok(()),
            Ok(out) => {
                let stderr = String::from_utf8_lossy(&out.stderr).trim().to_owned();
                last_err =
                    if stderr.is_empty() { format!("{bin} exited with {}", out.status) } else { stderr };
            }
            Err(e) if e.kind() == std::io::ErrorKind::NotFound => continue,
            Err(e) => last_err = e.to_string(),
        }
    }
    Err(last_err)
}

fn write_config_nofollow(path: &Path, content: &[u8]) {
    if let Some(parent) = path.parent() {
        let _ = fs::create_dir_all(parent);
    }
    if let Ok(mut f) = OpenOptions::new()
        .write(true)
        .create(true)
        .truncate(true)
        .custom_flags(libc::O_NOFOLLOW)
        .mode(0o644)
        .open(path)
    {
        let _ = f.write_all(content);
    }
}

/// Loads `v4l2loopback` with `"NectarLink Webcam"` and writes persistent module config files.
pub fn register_hklm() -> Result<(), String> {
    write_config_nofollow(Path::new(MODULES_LOAD_CONF), b"v4l2loopback\n");
    write_config_nofollow(
        Path::new(MODPROBE_CONF),
        format!("options v4l2loopback exclusive_caps=1 card_label=\"{FRIENDLY_NAME}\"\n").as_bytes(),
    );

    run_modprobe(&["v4l2loopback", "exclusive_caps=1", &format!("card_label={FRIENDLY_NAME}")])
}

/// Removes persistent `v4l2loopback` config files and unloads the kernel module.
pub fn unregister_hklm() -> Result<(), String> {
    let _ = fs::remove_file(MODULES_LOAD_CONF);
    let _ = fs::remove_file(MODPROBE_CONF);
    run_modprobe(&["-r", "v4l2loopback"])
}

/// Launches `nectarlink-desktop <arg>` under `pkexec` and invokes `on_done` when it exits.
pub fn run_elevated(arg: &'static str, on_done: impl FnOnce(bool) + Send + 'static) {
    thread::spawn(move || {
        let Ok(exe) = std::env::current_exe() else {
            on_done(false);
            return;
        };
        let ok = super::elevated::run_elevated(&exe, &[arg]).is_ok_and(|code| code == 0);
        on_done(ok);
    });
}

/// Converts top-down BGRX (`width * height * 4`) to packed YUYV 4:2:2 (`even_width * height * 2`)
/// using BT.601 studio-swing integer math.
pub fn bgrx_to_yuyv(bgrx: &[u8], width: u32, height: u32, yuyv: &mut Vec<u8>) {
    let w = width as usize;
    let h = height as usize;
    if w == 0 || h == 0 || bgrx.len() < w.saturating_mul(h).saturating_mul(4) {
        yuyv.clear();
        return;
    }
    let even_w = (w + 1) & !1;
    let total_bytes = even_w * h * 2;
    yuyv.resize(total_bytes, 0);

    for y in 0..h {
        let src_row = &bgrx[y * w * 4..(y + 1) * w * 4];
        let dst_row = &mut yuyv[y * even_w * 2..(y + 1) * even_w * 2];
        for pair in 0..(even_w / 2) {
            let x0 = pair * 2;
            let x1 = (x0 + 1).min(w - 1);

            let b0 = i32::from(src_row[x0 * 4]);
            let g0 = i32::from(src_row[x0 * 4 + 1]);
            let r0 = i32::from(src_row[x0 * 4 + 2]);

            let b1 = i32::from(src_row[x1 * 4]);
            let g1 = i32::from(src_row[x1 * 4 + 1]);
            let r1 = i32::from(src_row[x1 * 4 + 2]);

            let y0 = (((66 * r0 + 129 * g0 + 25 * b0 + 128) >> 8) + 16).clamp(16, 235) as u8;
            let y1 = (((66 * r1 + 129 * g1 + 25 * b1 + 128) >> 8) + 16).clamp(16, 235) as u8;

            let r_avg = (r0 + r1) >> 1;
            let g_avg = (g0 + g1) >> 1;
            let b_avg = (b0 + b1) >> 1;

            let u = (((-38 * r_avg - 74 * g_avg + 112 * b_avg + 128) >> 8) + 128).clamp(16, 240) as u8;
            let v = (((112 * r_avg - 94 * g_avg - 18 * b_avg + 128) >> 8) + 128).clamp(16, 240) as u8;

            let dst_off = pair * 4;
            dst_row[dst_off] = y0;
            dst_row[dst_off + 1] = u;
            dst_row[dst_off + 2] = y1;
            dst_row[dst_off + 3] = v;
        }
    }
}

/// Active Linux `v4l2loopback` feeder handle.
pub struct VirtualCameraHandle {
    stop: Arc<AtomicBool>,
    worker: Option<thread::JoinHandle<()>>,
}

impl std::fmt::Debug for VirtualCameraHandle {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        f.debug_struct("VirtualCameraHandle").field("running", &!self.stop.load(Ordering::Relaxed)).finish()
    }
}

impl VirtualCameraHandle {
    /// Spawns the `"vcam-v4l2"` background worker that reads BGRX frames from
    /// [`SharedFrameMapping`] and writes YUYV frames into the `v4l2loopback` device node.
    pub fn start() -> Result<Self, String> {
        let stop = Arc::new(AtomicBool::new(false));
        let stop_worker = stop.clone();
        let worker = thread::Builder::new()
            .name("vcam-v4l2".into())
            .spawn(move || v4l2_worker_loop(&stop_worker))
            .map_err(|e| format!("spawn vcam-v4l2 thread: {e}"))?;
        Ok(Self { stop, worker: Some(worker) })
    }
}

impl Drop for VirtualCameraHandle {
    fn drop(&mut self) {
        self.stop.store(true, Ordering::Release);
        if let Some(worker) = self.worker.take() {
            let _ = worker.join();
        }
    }
}

fn configure_v4l2_yuyv(fd: i32, width: u32, height: u32) -> bool {
    let even_w = (width + 1) & !1;
    let stride = even_w * 2;
    let sizeimage = stride * height;
    let mut fmt = V4l2Format {
        type_: V4L2_BUF_TYPE_VIDEO_OUTPUT,
        _pad: 0,
        pix: V4l2PixFormat {
            width: even_w,
            height,
            pixelformat: V4L2_PIX_FMT_YUYV,
            field: V4L2_FIELD_NONE,
            bytesperline: stride,
            sizeimage,
            colorspace: V4L2_COLORSPACE_SMPTE170M,
            priv_: 0,
            flags: 0,
            ycbcr_enc: 0,
            quantization: 0,
            xfer_func: 0,
        },
        _rest: [0u8; 200 - std::mem::size_of::<V4l2PixFormat>()],
    };
    // SAFETY: `VIDIOC_S_FMT` is called on a valid V4L2 device file descriptor with a properly
    // sized `v4l2_format` structure.
    unsafe { libc::ioctl(fd, VIDIOC_S_FMT, &raw mut fmt) == 0 }
}

fn v4l2_worker_loop(stop: &AtomicBool) {
    const OUT_W: u32 = 1280;
    const OUT_H: u32 = 720;

    let mut mapping: Option<SharedFrameMapping> = None;
    let mut v4l2_file: Option<fs::File> = None;
    let mut configured_dims: Option<(u32, u32)> = None;
    let mut bgrx = Vec::new();
    let mut yuyv = Vec::new();
    let mut last_ts: Option<(bool, u64)> = None;

    while !stop.load(Ordering::Acquire) {
        if mapping.is_none() {
            mapping = SharedFrameMapping::open_or_create(DEFAULT_MAPPING_NAME)
                .or_else(|_| SharedFrameMapping::open_or_create(LOCAL_MAPPING_NAME))
                .ok();
        }

        if v4l2_file.is_none()
            && let Some(dev_path) = find_v4l2loopback_device()
            && let Ok(file) = OpenOptions::new().read(true).write(true).open(&dev_path)
        {
            v4l2_file = Some(file);
            configured_dims = None;
            last_ts = None;
        }

        let (Some(map), Some(dev)) = (mapping.as_ref(), v4l2_file.as_mut()) else {
            thread::sleep(Duration::from_millis(50));
            continue;
        };

        if bgrx.len() != (OUT_W * OUT_H * 4) as usize {
            bgrx.resize((OUT_W * OUT_H * 4) as usize, 0);
        }

        let state = map.read_bgrx(OUT_W, OUT_H, &mut bgrx);
        if state.0 && last_ts == Some(state) {
            thread::sleep(Duration::from_millis(8));
            continue;
        }
        last_ts = Some(state);

        if configured_dims != Some((OUT_W, OUT_H)) {
            let _ = configure_v4l2_yuyv(dev.as_raw_fd(), OUT_W, OUT_H);
            configured_dims = Some((OUT_W, OUT_H));
        }

        bgrx_to_yuyv(&bgrx, OUT_W, OUT_H, &mut yuyv);
        if dev.write_all(&yuyv).is_err() {
            v4l2_file = None;
            configured_dims = None;
            thread::sleep(Duration::from_millis(50));
        } else if !state.0 {
            thread::sleep(Duration::from_millis(33));
        }
    }
}

#[cfg(test)]
mod tests {
    use super::*;

    #[test]
    fn v4l2_format_struct_has_kernel_abi_size() {
        assert_eq!(std::mem::size_of::<V4l2Format>(), 208);
    }

    #[test]
    fn bgrx_to_yuyv_converts_colors_and_rounds_odd_widths() {
        // 2x1 pure black and pure white pixels in BGRX.
        let bgrx = [
            0, 0, 0, 255, // black
            255, 255, 255, 255, // white
        ];
        let mut yuyv = Vec::new();
        bgrx_to_yuyv(&bgrx, 2, 1, &mut yuyv);
        assert_eq!(yuyv.len(), 4);
        assert_eq!(yuyv[0], 16, "black Y should be studio-swing 16");
        assert_eq!(yuyv[2], 235, "white Y should be studio-swing 235");
        assert!((126..=130).contains(&yuyv[1]), "neutral U should be ~128, got {}", yuyv[1]);
        assert!((126..=130).contains(&yuyv[3]), "neutral V should be ~128, got {}", yuyv[3]);

        // Odd width (3x2) rounds up to 4x2 -> 16 bytes of YUYV.
        let odd_bgrx = vec![0x80u8; 3 * 2 * 4];
        bgrx_to_yuyv(&odd_bgrx, 3, 2, &mut yuyv);
        assert_eq!(yuyv.len(), 4 * 2 * 2);
    }

    #[test]
    fn find_v4l2loopback_in_sysfs_prefers_nectarlink_and_matches_loopback() {
        let dir = tempfile::tempdir().unwrap();
        let sysfs = dir.path().join("sys");
        let dev = dir.path().join("dev");
        let v0 = sysfs.join("class/video4linux/video0");
        let v1 = sysfs.join("class/video4linux/video1");
        fs::create_dir_all(&v0).unwrap();
        fs::create_dir_all(&v1).unwrap();
        fs::create_dir_all(&dev).unwrap();

        fs::write(v0.join("name"), "Integrated Camera: USB\n").unwrap();
        fs::write(v1.join("name"), "NectarLink Webcam\n").unwrap();
        fs::write(dev.join("video0"), b"").unwrap();
        fs::write(dev.join("video1"), b"").unwrap();

        let found = find_v4l2loopback_in_sysfs(&sysfs, &dev);
        assert_eq!(found, Some(dev.join("video1")));
    }

    #[test]
    fn virtual_camera_handle_starts_and_drops_cleanly() {
        let handle = VirtualCameraHandle::start().expect("should spawn vcam-v4l2 worker");
        drop(handle);
    }
}