Add local video publisher & subcriber examples (#830)

* Adding local video publisher & subcriber examples

* improve ctrl-c handling

* update .gitignore

* lock aspect ratio

* fix window resize & display some stats on video

* update readme

* lint

* Update examples/local_video/README.md

Co-authored-by: Copilot <[email protected]>

* Update examples/local_video/src/subscriber.rs

Co-authored-by: Copilot <[email protected]>

* Revert "Update examples/local_video/src/subscriber.rs"

This reverts commit 2a6aae3.

* add simulcast option

* move main app loop into a `run` function

* refactor event handling into separate functions for readability

* add script to list devices

* lint

---------

Co-authored-by: Copilot <[email protected]>

Author: chenosaurus

.gitignore

@@ -3,4 +3,5 @@ target
 soxr-sys/test-input.wav
 soxr-sys/test-output.wav
 .DS_Store
-.env
+.env
+.cursor

Cargo.toml

@@ -20,6 +20,7 @@ members = [
     "examples/basic_text_stream",
     "examples/encrypted_text_stream",
     "examples/local_audio",
+    "examples/local_video",
     "examples/mobile",
     "examples/play_from_disk",
     "examples/rpc",

examples/local_video/Cargo.toml

@@ -0,0 +1,45 @@
+[package]
+name = "local_video"
+version = "0.1.0"
+edition = "2021"
+publish = false
+
+[[bin]]
+name = "publisher"
+path = "src/publisher.rs"
+
+[[bin]]
+name = "subscriber"
+path = "src/subscriber.rs"
+
+[[bin]]
+name = "list_devices"
+path = "src/list_devices.rs"
+
+[dependencies]
+tokio = { version = "1", features = ["full", "parking_lot"] }
+livekit = { workspace = true, features = ["rustls-tls-native-roots"] }
+webrtc-sys = { workspace = true }
+libwebrtc = { workspace = true }
+livekit-api = { workspace = true }
+yuv-sys = { workspace = true }
+futures = "0.3"
+clap = { version = "4.5", features = ["derive"] }
+log = "0.4"
+env_logger = "0.10.0"
+nokhwa = { version = "0.10", default-features = false, features = ["input-avfoundation", "input-v4l", "input-msmf", "output-threaded"] }
+image = "0.24"
+egui = "0.31.1"
+egui-wgpu = "0.31.1"
+eframe = { version = "0.31.1", default-features = false, features = ["default_fonts", "wgpu", "persistence"] }
+wgpu = "25.0"
+winit = { version = "0.30.11", features = ["android-native-activity"] }
+parking_lot = { version = "0.12.1", features = ["deadlock_detection"] }
+anyhow = "1"
+bytemuck = { version = "1.16", features = ["derive"] }
+
+[target.'cfg(target_os = "macos")'.dependencies]
+objc2 = { version = "0.6.0", features = ["relax-sign-encoding"] }
+nokhwa-bindings-macos = "0.2"
+
+

examples/local_video/README.md

@@ -0,0 +1,64 @@
+# local_video
+
+Three examples demonstrating capturing frames from a local camera video and publishing to LiveKit, listing camera capabilities, and subscribing to render video in a window.
+
+- list_devices: enumerate available cameras and their capabilities
+- publisher: capture from a selected camera and publish a video track
+- subscriber: connect to a room, subscribe to video tracks, and display in a window
+
+LiveKit connection can be provided via flags or environment variables:
+- `--url` or `LIVEKIT_URL`
+- `--api-key` or `LIVEKIT_API_KEY`
+- `--api-secret` or `LIVEKIT_API_SECRET`
+
+Publisher usage:
+```
+ cargo run -p local_video --bin publisher -- --list-cameras
+ cargo run -p local_video --bin publisher -- --camera-index 0 --room-name demo --identity cam-1
+ 
+ # with explicit LiveKit connection flags
+ cargo run -p local_video --bin publisher -- \
+   --camera-index 0 \
+   --room-name demo \
+   --identity cam-1 \
+   --simulcast \
+   --h265 \
+   --max-bitrate 1500000 \
+   --url https://your.livekit.server \
+   --api-key YOUR_KEY \
+   --api-secret YOUR_SECRET
+```
+
+List devices usage:
+```
+ cargo run -p local_video --bin list_devices
+```
+
+Publisher flags (in addition to the common connection flags above):
+- `--h265`: Use H.265/HEVC encoding if supported (falls back to H.264 on failure).
+- `--simulcast`: Publish simulcast video (multiple layers when the resolution is large enough).
+- `--max-bitrate <bps>`: Max video bitrate for the main (highest) layer in bits per second (e.g. `1500000`).
+
+Subscriber usage:
+```
+ # relies on env vars LIVEKIT_URL, LIVEKIT_API_KEY, LIVEKIT_API_SECRET
+ cargo run -p local_video --bin subscriber -- --room-name demo --identity viewer-1
+
+ # or pass credentials via flags
+ cargo run -p local_video --bin subscriber -- \
+   --room-name demo \
+   --identity viewer-1 \
+   --url https://your.livekit.server \
+   --api-key YOUR_KEY \
+   --api-secret YOUR_SECRET
+
+  # subscribe to a specific participant's video only
+  cargo run -p local_video --bin subscriber -- \
+    --room-name demo \
+    --identity viewer-1 \
+    --participant alice
+```
+
+Notes:
+- `--participant` limits subscription to video tracks from the specified participant identity.
+- If the active video track is unsubscribed or unpublished, the app clears its state and will automatically attach to the next matching video track when it appears.

examples/local_video/src/list_devices.rs

@@ -0,0 +1,108 @@
+use anyhow::Result;
+use nokhwa::pixel_format::RgbFormat;
+use nokhwa::utils::{
+    ApiBackend, CameraFormat, CameraInfo, FrameFormat, RequestedFormat, RequestedFormatType,
+    Resolution,
+};
+use nokhwa::Camera;
+use std::collections::BTreeMap;
+
+#[cfg(target_os = "macos")]
+use nokhwa_bindings_macos::AVCaptureDevice;
+
+fn main() -> Result<()> {
+    let cameras = nokhwa::query(ApiBackend::Auto)?;
+    if cameras.is_empty() {
+        println!("No cameras detected.");
+        return Ok(());
+    }
+
+    println!("Available cameras and capabilities:");
+    for (idx, info) in cameras.iter().enumerate() {
+        println!();
+        println!("{}. {}", idx, info.human_name());
+        match enumerate_capabilities(info) {
+            Ok(formats) => print_capabilities(&formats),
+            Err(err) => println!("   Capabilities: unavailable ({})", err),
+        }
+    }
+
+    Ok(())
+}
+
+#[cfg(target_os = "macos")]
+fn enumerate_capabilities(
+    info: &CameraInfo,
+) -> Result<BTreeMap<FrameFormat, BTreeMap<Resolution, Vec<u32>>>> {
+    let device = AVCaptureDevice::new(info.index())?;
+    let formats = device.supported_formats()?;
+    Ok(capabilities_from_formats(formats))
+}
+
+#[cfg(not(target_os = "macos"))]
+fn enumerate_capabilities(
+    info: &CameraInfo,
+) -> Result<BTreeMap<FrameFormat, BTreeMap<Resolution, Vec<u32>>>> {
+    let requested = RequestedFormat::new::<RgbFormat>(RequestedFormatType::None);
+    let mut camera = Camera::new(info.index().clone(), requested)?;
+    let mut capabilities = BTreeMap::new();
+    if let Ok(mut fourccs) = camera.compatible_fourcc() {
+        fourccs.sort();
+        for fourcc in fourccs {
+            let mut res_map = camera.compatible_list_by_resolution(fourcc)?;
+            let mut res_sorted = BTreeMap::new();
+            for (res, mut fps_list) in res_map.drain() {
+                fps_list.sort();
+                res_sorted.insert(res, fps_list);
+            }
+            capabilities.insert(fourcc, res_sorted);
+        }
+    } else {
+        let formats = camera.compatible_camera_formats()?;
+        capabilities = capabilities_from_formats(formats);
+    }
+
+    Ok(capabilities)
+}
+
+fn capabilities_from_formats(
+    formats: Vec<CameraFormat>,
+) -> BTreeMap<FrameFormat, BTreeMap<Resolution, Vec<u32>>> {
+    let mut capabilities = BTreeMap::new();
+    for fmt in formats {
+        let res_map = capabilities.entry(fmt.format()).or_insert_with(BTreeMap::new);
+        let fps_list = res_map.entry(fmt.resolution()).or_insert_with(Vec::new);
+        fps_list.push(fmt.frame_rate());
+    }
+    for res_map in capabilities.values_mut() {
+        for fps_list in res_map.values_mut() {
+            fps_list.sort();
+            fps_list.dedup();
+        }
+    }
+    capabilities
+}
+
+fn print_capabilities(capabilities: &BTreeMap<FrameFormat, BTreeMap<Resolution, Vec<u32>>>) {
+    if capabilities.is_empty() {
+        println!("   Capabilities: none reported");
+        return;
+    }
+
+    println!("   Capabilities:");
+    for (format, resolutions) in capabilities {
+        println!("   - Format: {}", format);
+        if resolutions.is_empty() {
+            println!("     (no resolutions reported)");
+            continue;
+        }
+        for (resolution, fps_list) in resolutions {
+            let fps_text = if fps_list.is_empty() {
+                "unknown".to_string()
+            } else {
+                fps_list.iter().map(|fps| fps.to_string()).collect::<Vec<String>>().join(", ")
+            };
+            println!("     {} @ {} fps", resolution, fps_text);
+        }
+    }
+}