videocall_cli/cli_args.rs
1/*
2 * Copyright 2025 Security Union LLC
3 *
4 * Licensed under either of
5 *
6 * * Apache License, Version 2.0
7 * (http://www.apache.org/licenses/LICENSE-2.0)
8 * * MIT license
9 * (http://opensource.org/licenses/MIT)
10 *
11 * at your option.
12 *
13 * Unless you explicitly state otherwise, any contribution intentionally
14 * submitted for inclusion in the work by you, as defined in the Apache-2.0
15 * license, shall be dual licensed as above, without any additional terms or
16 * conditions.
17 */
18
19use std::str::FromStr;
20
21use clap::{ArgGroup, Args, Parser, Subcommand};
22use thiserror::Error;
23use url::Url;
24use videocall_nokhwa::utils::FrameFormat;
25
26/// Video Call CLI
27///
28/// This cli connects to the videocall.rs and streams audio and video to the specified meeting.
29///
30/// NOTE: the meeting must be created first from a browser at https://videocall.rs.
31/// The CLI can only JOIN an existing call — it cannot create one. A call created
32/// by the CLI will not work.
33///
34/// You can watch the video at https://videocall.rs/meeting/{meeting_id}
35#[derive(Parser, Debug)]
36#[clap(name = "client")]
37pub struct Opt {
38 #[clap(subcommand)]
39 pub mode: Mode,
40}
41
42#[derive(Clone, Debug)]
43pub enum IndexKind {
44 String(String),
45 Index(u32),
46}
47
48#[derive(Error, Debug)]
49pub enum ParseIndexKindError {
50 #[error("Invalid index value: {0}")]
51 InvalidIndex(String),
52}
53
54impl FromStr for IndexKind {
55 type Err = ParseIndexKindError;
56
57 fn from_str(s: &str) -> Result<Self, Self::Err> {
58 if let Ok(index) = s.parse::<u32>() {
59 Ok(IndexKind::Index(index))
60 } else {
61 Ok(IndexKind::String(s.to_string()))
62 }
63 }
64}
65
66#[derive(Subcommand, Debug)]
67pub enum Mode {
68 /// Stream audio and video to an EXISTING meeting.
69 ///
70 /// The meeting must be created first by a user in a browser at
71 /// https://videocall.rs. The CLI can only join a call, not create one.
72 Stream(Stream),
73
74 /// Information mode to list cameras, formats, and resolutions.
75 Info(Info),
76}
77
78#[derive(Args, Debug, Clone)]
79pub struct Stream {
80 /// URL to connect to (default: us-east) but you can use any other region by passing the full URL.
81 /// US: https://webtransport-us-east.webtransport.video
82 /// SG: https://webtransport-singapore.webtransport.video
83 #[clap(
84 long = "url",
85 default_value = "https://webtransport-us-east.webtransport.video"
86 )]
87 pub url: Url,
88
89 #[clap(long = "user-id")]
90 pub user_id: String,
91
92 /// Meeting (call) ID to join.
93 ///
94 /// IMPORTANT: the call must already exist — create it first from a browser
95 /// at https://videocall.rs. The CLI can no longer create a call itself (the
96 /// API changed); if the call's creator is the CLI, it will not work — a
97 /// browser user has to create it.
98 #[clap(long = "meeting-id")]
99 pub meeting_id: String,
100
101 /// Specify which camera to use, either by index number or name.
102 ///
103 /// Examples:
104 /// --video-device-index 0 # Use first camera
105 /// --video-device-index "HD WebCam" # Use camera by name
106 ///
107 /// If not provided, the program will list all available cameras.
108 /// You can also see available cameras by running:
109 /// videocall-cli info --list-cameras
110 ///
111 /// Note for MacOS users: You must use the device UUID instead of the human-readable name.
112 /// The UUID can be found in the "Extras" field when listing cameras.
113 #[clap(long = "video-device-index", short = 'v')]
114 pub video_device_index: Option<IndexKind>,
115
116 /// Microphone to capture, by exact device name. Use `default` for the
117 /// system default input device.
118 ///
119 /// List available names with:
120 /// videocall-cli info --list-audio-devices
121 ///
122 /// If omitted, no audio is captured (video-only).
123 #[clap(long = "audio-device", short = 'a')]
124 pub audio_device: Option<String>,
125
126 /// Resolution in WIDTHxHEIGHT format (e.g., 1920x1080)
127 #[clap(long = "resolution", short = 'r')]
128 #[clap(default_value = "1280x720")]
129 pub resolution: String,
130
131 /// Frame rate for the video stream.
132 #[clap(long = "fps")]
133 #[clap(default_value = "30")]
134 pub fps: u32,
135
136 #[clap(long = "bitrate-kbps")]
137 #[clap(default_value = "500")]
138 pub bitrate_kbps: u32,
139
140 /// Controls the speed vs. quality tradeoff for VP9 encoding.
141 ///
142 /// The value ranges from `0` (slowest, best quality) to `15` (fastest, lowest quality).
143 ///
144 /// The cli does not allow selecting values below 4 because they are useless for realtime streaming.
145 ///
146 /// ## Valid Values:
147 /// - `4` to `8`: **Fast encoding**, lower quality (good for real-time streaming, live video).
148 /// - `9` to `15`: **Very fast encoding**, lowest quality, largest files (for ultra-low-latency applications).
149 ///
150 /// videocall-cli --vp9-cpu-used 5 # Fast encoding, good for live streaming
151 #[arg(long, default_value_t = 5, value_parser = clap::value_parser!(u8).range(4..=15))]
152 pub vp9_cpu_used: u8,
153
154 /// Frame format to use for the video stream.
155 /// Different cameras support different formats.
156 /// Please use the `info` subcommand to list supported formats for a specific camera.
157 #[arg(long, default_value_t = FrameFormat::NV12, value_parser = parse_frame_format)]
158 pub frame_format: FrameFormat,
159
160 /// Perform NSS-compatible TLS key logging to the file specified in `SSLKEYLOGFILE`.
161 #[clap(long = "debug-keylog")]
162 pub keylog: bool,
163
164 /// Send test pattern instead of camera video.
165 #[clap(long = "debug-send-test-pattern")]
166 pub send_test_pattern: bool,
167
168 /// This is for ensuring that we can open the camera and encode video
169 #[clap(long = "debug-offline-streaming-test")]
170 pub local_streaming_test: bool,
171
172 /// Skip TLS certificate verification for QUIC connections.
173 /// Warning: This makes connections insecure and should only be used for testing.
174 #[clap(long = "insecure-skip-verify")]
175 pub insecure_skip_verify: bool,
176}
177
178fn parse_frame_format(s: &str) -> Result<FrameFormat, String> {
179 match s {
180 "NV12" => Ok(FrameFormat::NV12),
181 // TODO: Merge MR with MacOS BGRA support
182 // "BGRA" => Ok(FrameFormat::BGRA),
183 "YUYV" => Ok(FrameFormat::YUYV),
184 _ => Err("Invalid frame format, please use one of [NV12, BGRA, YUYV]".to_string()),
185 }
186}
187
188#[derive(Args, Debug)]
189#[clap(group = ArgGroup::new("info").required(true))]
190pub struct Info {
191 /// List available cameras.
192 #[clap(long = "list-cameras", group = "info")]
193 pub list_cameras: bool,
194
195 /// List available audio input devices (names usable with `stream --audio-device`).
196 #[clap(long = "list-audio-devices", group = "info")]
197 pub list_audio_devices: bool,
198
199 /// List supported formats for a specific camera using the index from `list-cameras`
200 #[clap(long = "list-formats", group = "info")]
201 pub list_formats: Option<IndexKind>, // Camera index
202
203 /// List supported resolutions for a specific camera using the index from `list-cameras`
204 #[clap(long = "list-resolutions", group = "info")]
205 pub list_resolutions: Option<IndexKind>, // Camera index
206}
207
208#[derive(Args, Debug, Clone)]
209pub struct TestCamera {
210 #[clap(long = "video-device-index")]
211 pub video_device_index: IndexKind,
212}