moq-video 0.1.1

//! Surface capture. [`Config`] is shared; the implementation is per-platform and
//! per-source:
//! - macOS camera -> AVFoundation, screen -> ScreenCaptureKit, both yielding
//!   zero-copy `CVPixelBuffer` surfaces straight to VideoToolbox.
//! - Linux camera -> native V4L2 (YUYV / MJPEG -> CPU I420), or a PipeWire
//!   camera node (`pipewire` feature), X11 display and window -> X11, Wayland
//!   display -> xdg-desktop-portal + PipeWire (`pipewire` feature).
//! - Windows camera -> native Media Foundation (`IMFSourceReader`), screen ->
//!   DXGI Desktop Duplication, window -> GDI (BGRA -> CPU I420).
//!
//! [`encode::publish_capture`](crate::encode::publish_capture) consumes [`Config`].

use std::sync::Arc;

use crate::{Error, Frame, Rate};

mod channel;
use channel::FrameChannel;

/// Type-erased keep-alive for a capture backend, dropped to release the device.
///
/// `Send` off macOS (the backend is a pump-thread guard: an `Arc` stop flag plus
/// a `JoinHandle`), which keeps [`publish_capture`](crate::encode::publish_capture)
/// `Send` so a server can `tokio::spawn` it. On macOS the backend is the objc
/// `AVCaptureSession` (plus its delegate), which is `!Send`, so that platform's
/// capture future is `!Send` too.
#[cfg(not(target_os = "macos"))]
type Keepalive = Box<dyn std::any::Any + Send>;
#[cfg(target_os = "macos")]
type Keepalive = Box<dyn std::any::Any>;

#[cfg(target_os = "macos")]
mod avfoundation;
#[cfg(target_os = "macos")]
mod screencapture;
#[cfg(target_os = "macos")]
mod surface;

// Native V4L2 camera capture on Linux.
#[cfg(target_os = "linux")]
mod v4l2;
// The mode choice V4L2 and PipeWire cameras share.
#[cfg(target_os = "linux")]
mod mode;
// Native X11 display and window capture, including the portal fallback.
#[cfg(target_os = "linux")]
mod x11;

// Portal + PipeWire screen capture and PipeWire camera capture on Linux.
#[cfg(all(target_os = "linux", feature = "pipewire"))]
mod pipewire;

// Native Media Foundation camera capture on Windows.
#[cfg(target_os = "windows")]
mod mediafoundation;

// DXGI Desktop Duplication screen capture on Windows.
#[cfg(target_os = "windows")]
mod desktopduplication;
// Native GDI window enumeration and capture on Windows.
#[cfg(target_os = "windows")]
mod window;

// Blocking-device -> async-channel bridge used by V4L2 / Media Foundation.
#[cfg(any(target_os = "linux", target_os = "windows"))]
mod pump;

// Geometry debounce shared by the X11 and Windows window backends. The state
// machine is platform independent, so it is also built under `cfg(test)` to
// keep its tests running on every host.
#[cfg(any(target_os = "linux", target_os = "windows", test))]
mod settle;

/// What to capture. Each variant carries the identifier that selects it, so a
/// window can't be captured without saying which one, and a camera id can't
/// reach the display backend.
///
/// The identifiers come from [`cameras`], [`displays`], [`windows`], and
/// [`apps`]; each listed item's `source()` builds the matching variant.
#[derive(Clone, Debug, PartialEq, Eq)]
#[non_exhaustive]
pub enum Source {
	/// A camera / webcam. `None` opens the default camera.
	///
	/// The identifiers from [`cameras`] are an AVFoundation `uniqueID` on macOS,
	/// a `/dev/videoN` path on Linux, and a Media Foundation symbolic link on
	/// Windows. Bare numeric indices remain accepted on Linux and Windows.
	///
	/// With the `pipewire` feature, Linux also lists PipeWire camera nodes as
	/// `pipewire:<node name>`, and `pipewire` alone opens the camera with the
	/// highest session priority, which the session manager treats as default.
	/// The id picks the backend: a `/dev/videoN` path always opens V4L2, and a
	/// `pipewire` id always opens PipeWire. `None` opens `/dev/video0`, except
	/// inside a sandbox (Flatpak or Snap), where it opens PipeWire's default
	/// camera through the camera portal.
	Camera(Option<String>),

	/// A whole display. `None` opens the main display.
	///
	/// The id is the opaque value [`displays`] reports. On Wayland the
	/// xdg-desktop-portal picker owns selection and no stable id is available.
	Display(Option<String>),

	/// A single window, by the id [`windows`] reports. Supported on macOS,
	/// Windows, and X11.
	Window(String),

	/// Every window belonging to one application, by the id [`apps`] reports
	/// (a bundle identifier). Windows that open later are included. macOS only.
	App(String),
}

/// The default camera, matching the historical `Config::default()`.
impl Default for Source {
	fn default() -> Self {
		Self::Camera(None)
	}
}

impl Source {
	/// A short human-readable name for the source, used in logs and as the
	/// captured device label.
	///
	/// macOS-only: one ScreenCaptureKit backend serves display, window, and app,
	/// so it names the source from the config. The other backends label a stream
	/// with the device they resolved (`/dev/video0`, a Media Foundation friendly
	/// name), which the config doesn't know.
	#[cfg(target_os = "macos")]
	pub(crate) fn label(&self) -> String {
		match self {
			Self::Camera(None) => "camera".to_string(),
			Self::Camera(Some(id)) => format!("camera:{id}"),
			Self::Display(None) => "display".to_string(),
			Self::Display(Some(id)) => format!("display:{id}"),
			Self::Window(id) => format!("window:{id}"),
			Self::App(id) => format!("app:{id}"),
		}
	}
}

/// A camera reported by [`cameras`].
#[derive(Clone, Debug)]
pub struct Camera {
	/// Opaque identifier: pass to [`Source::Camera`].
	pub id: String,
	/// Human-readable name, e.g. "FaceTime HD Camera".
	pub name: String,
}

impl Camera {
	/// The [`Source`] that captures this camera.
	pub fn source(&self) -> Source {
		Source::Camera(Some(self.id.clone()))
	}
}

/// A capture mode a source reports: one frame size and its exact frame rates.
#[derive(Clone, Debug, PartialEq, Eq)]
pub struct Mode {
	/// Frame width in pixels.
	pub width: u32,
	/// Frame height in pixels.
	pub height: u32,
	/// The exact frame rates offered at this size, highest first.
	///
	/// Empty when the driver describes a continuous range instead of listing
	/// rates, or cannot enumerate intervals for this size.
	pub framerates: Vec<Rate>,
}

impl Mode {
	/// The highest rate this mode offers, or `None` when the driver listed none.
	pub fn max_framerate(&self) -> Option<Rate> {
		self.framerates.first().copied()
	}
}

/// A display reported by [`displays`].
#[derive(Clone, Debug)]
pub struct Display {
	/// Opaque identifier: pass to [`Source::Display`].
	pub id: String,
	/// Human-readable name, e.g. "Display 1".
	pub name: String,
	/// Width in the platform's desktop coordinate space: points on macOS and
	/// desktop pixels on Windows and X11.
	pub width: u32,
	/// Height in the platform's desktop coordinate space: points on macOS and
	/// desktop pixels on Windows and X11.
	pub height: u32,
}

impl Display {
	/// The [`Source`] that captures this display.
	pub fn source(&self) -> Source {
		Source::Display(Some(self.id.clone()))
	}
}

/// A window reported by [`windows`].
#[derive(Clone, Debug)]
pub struct Window {
	/// Opaque identifier: pass to [`Source::Window`].
	pub id: String,
	/// The window title, empty if it has none.
	pub title: String,
	/// The name of the application owning the window.
	pub app: String,
	/// Width in platform window coordinates: points on macOS and pixels on
	/// Windows and X11.
	pub width: u32,
	/// Height in platform window coordinates: points on macOS and pixels on
	/// Windows and X11.
	pub height: u32,
}

impl Window {
	/// The [`Source`] that captures this window.
	pub fn source(&self) -> Source {
		Source::Window(self.id.clone())
	}
}

/// An application reported by [`apps`].
#[derive(Clone, Debug)]
pub struct App {
	/// Bundle identifier: pass to [`Source::App`].
	pub id: String,
	/// Human-readable name, e.g. "Safari".
	pub name: String,
}

impl App {
	/// The [`Source`] that captures every window of this application.
	pub fn source(&self) -> Source {
		Source::App(self.id.clone())
	}
}

/// Capture configuration. All fields are hints; the backend picks the closest
/// supported mode.
///
/// `#[non_exhaustive]`: construct via [`Config::default`] and set fields, so
/// new options can be added without breaking callers.
#[derive(Clone, Debug)]
#[non_exhaustive]
pub struct Config {
	/// What to capture.
	pub source: Source,
	/// Preferred output width in pixels.
	pub width: Option<u32>,
	/// Preferred output height in pixels.
	pub height: Option<u32>,
	/// Preferred exact frame rate.
	pub framerate: Option<Rate>,
	/// Draw the mouse cursor into captured frames. Screen/window/app sources
	/// only; ignored by cameras. Defaults to `true`.
	pub cursor: bool,
}

impl Default for Config {
	fn default() -> Self {
		Self {
			source: Source::default(),
			width: None,
			height: None,
			framerate: None,
			cursor: true,
		}
	}
}

/// A live, async frame source opened via [`open`].
///
/// Every backend delivers frames through the same latest-frame channel, so the
/// consumer just `read().await`s regardless of platform. Dropping the stream
/// releases the device (stops the macOS `AVCaptureSession`, joins the V4L2 /
/// Media Foundation pump thread). That is the whole point: because `read` is a
/// real await, cancelling the capture future drops this and the camera turns off
/// promptly, with no blocking task left pinned to the runtime.
pub struct Stream {
	chan: Arc<FrameChannel>,
	width: u32,
	height: u32,
	framerate: Option<Rate>,
	color: Option<crate::Color>,
	label: String,
	/// First frame captured during [`open`] (some backends learn their geometry
	/// only from a frame); returned by the first [`read`](Self::read).
	pending: Option<Frame>,
	/// Keeps the backend alive and releases it on drop. Type-erased because it
	/// differs per platform (objc session + delegate, or pump-thread guard).
	_backend: Keepalive,
}

impl Stream {
	/// Build a stream from a backend's channel, geometry, and keep-alive guard.
	fn new(
		chan: Arc<FrameChannel>,
		width: u32,
		height: u32,
		framerate: Option<Rate>,
		label: String,
		pending: Option<Frame>,
		backend: Keepalive,
	) -> Self {
		let color = pending.as_ref().and_then(|frame| frame.surface.color());
		Self {
			chan,
			width,
			height,
			framerate,
			color,
			label,
			pending,
			_backend: backend,
		}
	}

	/// Await the next frame, or `None` once the source ends.
	///
	/// `None` is recoverable: the source stopped for a benign reason (it
	/// resized, the compositor renegotiated the format, the device went idle)
	/// and reopening is expected to work. An `Err` is terminal for this
	/// selection: the source is gone or was refused.
	///
	/// Dropping this future cancels only the pending read. Dropping the stream
	/// releases the capture source.
	pub async fn read(&mut self) -> Result<Option<Frame>, Error> {
		if let Some(frame) = self.pending.take() {
			return Ok(Some(frame));
		}
		self.chan.recv().await
	}

	/// Width of the captured frames in pixels.
	pub fn width(&self) -> u32 {
		self.width
	}

	/// Height of the captured frames in pixels.
	pub fn height(&self) -> u32 {
		self.height
	}

	/// The negotiated frame rate, or `None` if the source doesn't report one.
	pub fn framerate(&self) -> Option<Rate> {
		self.framerate
	}

	/// The first frame's declared color space, when its capture backend knows it.
	pub fn color(&self) -> Option<crate::Color> {
		self.color
	}

	/// Human-readable label for the selected capture source.
	pub fn label(&self) -> &str {
		&self.label
	}

	/// Current time in this stream's private capture timeline.
	pub(crate) fn now(&self) -> moq_net::Timestamp {
		self.chan.now()
	}
}

/// Open the capture source described by `config`.
pub async fn open(config: &Config) -> Result<Stream, Error> {
	match &config.source {
		Source::Camera(device) => {
			let _ = device;
			#[cfg(target_os = "macos")]
			{
				avfoundation::open(config, device.as_deref()).await
			}
			#[cfg(target_os = "linux")]
			{
				match LinuxCamera::select(device.as_deref(), sandboxed()) {
					LinuxCamera::V4l2(device) => v4l2::open(config, device).await,
					#[cfg(feature = "pipewire")]
					LinuxCamera::PipeWire(node) => pipewire::camera::open(config, node).await,
					#[cfg(not(feature = "pipewire"))]
					LinuxCamera::PipeWire(_) => Err(Error::Unsupported(
						"PipeWire camera capture without the `pipewire` feature".to_string(),
					)),
				}
			}
			#[cfg(target_os = "windows")]
			{
				mediafoundation::open(config, device.as_deref()).await
			}
			#[cfg(not(any(target_os = "macos", target_os = "linux", target_os = "windows")))]
			{
				Err(Error::Unsupported("camera capture".to_string()))
			}
		}
		Source::Display(device) => {
			let _ = device;
			#[cfg(target_os = "macos")]
			{
				screencapture::open_display(config, device.as_deref()).await
			}
			#[cfg(target_os = "windows")]
			{
				desktopduplication::open(config, device.as_deref()).await
			}
			#[cfg(all(target_os = "linux", feature = "pipewire"))]
			{
				if x11::selected(device.as_deref()) {
					x11::open_display(config, device.as_deref()).await
				} else {
					pipewire::open(config, device.as_deref()).await
				}
			}
			#[cfg(all(target_os = "linux", not(feature = "pipewire")))]
			{
				x11::open_display(config, device.as_deref()).await
			}
			#[cfg(not(any(target_os = "macos", target_os = "windows", target_os = "linux")))]
			{
				Err(Error::Unsupported("screen capture".to_string()))
			}
		}
		Source::Window(id) => {
			let _ = id;
			#[cfg(target_os = "macos")]
			{
				screencapture::open_window(config, id).await
			}
			#[cfg(target_os = "linux")]
			{
				x11::open_window(config, id).await
			}
			#[cfg(target_os = "windows")]
			{
				window::open(config, id).await
			}
			#[cfg(not(any(target_os = "macos", target_os = "linux", target_os = "windows")))]
			{
				Err(Error::Unsupported("window capture".to_string()))
			}
		}
		Source::App(id) => {
			let _ = id;
			#[cfg(target_os = "macos")]
			{
				screencapture::open_app(config, id).await
			}
			#[cfg(not(target_os = "macos"))]
			{
				Err(Error::Unsupported("application capture".to_string()))
			}
		}
	}
}

/// List the available cameras and the identifiers [`Source::Camera`] accepts.
///
/// On Linux with the `pipewire` feature, V4L2 devices come first and PipeWire
/// camera nodes follow, so a webcam that PipeWire also serves appears once per
/// backend. A session without PipeWire lists V4L2 alone. Inside a sandbox the
/// PipeWire nodes come through the camera portal, which may ask the user for
/// camera access.
pub async fn cameras() -> Result<Vec<Camera>, Error> {
	#[cfg(target_os = "macos")]
	{
		avfoundation::cameras()
	}
	#[cfg(target_os = "linux")]
	{
		let cameras = blocking(v4l2::cameras).await?;
		#[cfg(feature = "pipewire")]
		let cameras = [cameras, pipewire::camera::cameras().await?].concat();
		Ok(cameras)
	}
	#[cfg(target_os = "windows")]
	{
		blocking(mediafoundation::cameras).await
	}
	#[cfg(not(any(target_os = "macos", target_os = "linux", target_os = "windows")))]
	{
		Err(Error::Unsupported("listing cameras".to_string()))
	}
}

/// List the modes a camera reports, largest size first.
///
/// `camera` selects the device exactly as [`Source::Camera`] does. Only the
/// formats this crate can convert are enumerated, so the modes that come back
/// are ones [`open`] could negotiate rather than everything the driver
/// advertises.
///
/// Linux only (V4L2, and PipeWire cameras with the `pipewire` feature); other
/// platforms return [`Error::Unsupported`].
/// Rates are exact device reports and [`Config::framerate`] accepts the same type.
/// Both Linux backends prefer the closest geometry, then the accepted rate
/// nearest that request, then the cheaper conversion format.
///
/// An empty list is not a failure: it means the driver enumerated nothing this
/// crate can convert.
pub async fn camera_modes(camera: Option<&str>) -> Result<Vec<Mode>, Error> {
	let _ = camera;
	#[cfg(target_os = "linux")]
	{
		match LinuxCamera::select(camera, sandboxed()) {
			LinuxCamera::V4l2(camera) => {
				let camera = camera.map(str::to_string);
				blocking(move || v4l2::modes(camera.as_deref())).await
			}
			#[cfg(feature = "pipewire")]
			LinuxCamera::PipeWire(node) => pipewire::camera::modes(node).await,
			#[cfg(not(feature = "pipewire"))]
			LinuxCamera::PipeWire(_) => Err(Error::Unsupported(
				"PipeWire camera modes without the `pipewire` feature".to_string(),
			)),
		}
	}
	#[cfg(not(target_os = "linux"))]
	{
		Err(Error::Unsupported("listing camera modes".to_string()))
	}
}

/// List the available displays and the identifiers [`Source::Display`] accepts.
///
/// On Wayland the xdg-desktop-portal picker owns display selection, so there is
/// no portal list or stable identifier to expose. When XWayland is available,
/// its native displays are listed with stable X11 ids.
pub async fn displays() -> Result<Vec<Display>, Error> {
	#[cfg(target_os = "macos")]
	{
		screencapture::displays().await
	}
	#[cfg(target_os = "windows")]
	{
		blocking(desktopduplication::displays).await
	}
	#[cfg(target_os = "linux")]
	{
		blocking(x11::displays).await
	}
	#[cfg(not(any(target_os = "macos", target_os = "windows", target_os = "linux")))]
	{
		Err(Error::Unsupported("listing displays".to_string()))
	}
}

/// List the on-screen windows.
pub async fn windows() -> Result<Vec<Window>, Error> {
	#[cfg(target_os = "macos")]
	{
		screencapture::windows().await
	}
	#[cfg(target_os = "linux")]
	{
		blocking(x11::windows).await
	}
	#[cfg(target_os = "windows")]
	{
		blocking(window::windows).await
	}
	#[cfg(not(any(target_os = "macos", target_os = "linux", target_os = "windows")))]
	{
		Err(Error::Unsupported("listing windows".to_string()))
	}
}

/// List the applications with at least one on-screen window. macOS only.
pub async fn apps() -> Result<Vec<App>, Error> {
	#[cfg(target_os = "macos")]
	{
		screencapture::apps().await
	}
	#[cfg(not(target_os = "macos"))]
	{
		Err(Error::Unsupported("listing applications".to_string()))
	}
}

/// The id prefix of a PipeWire camera, and on its own the default one.
#[cfg(any(target_os = "linux", test))]
const PIPEWIRE: &str = "pipewire";

/// The Linux backend a [`Source::Camera`] selector names.
#[cfg(any(target_os = "linux", test))]
#[derive(Debug, PartialEq, Eq)]
enum LinuxCamera<'a> {
	/// A V4L2 device, by path or index. `None` opens `/dev/video0`.
	V4l2(Option<&'a str>),
	/// A PipeWire camera, by `node.name`. `None` picks the camera with the
	/// highest session priority, the one the session manager links by default.
	PipeWire(Option<&'a str>),
}

#[cfg(any(target_os = "linux", test))]
impl<'a> LinuxCamera<'a> {
	/// Parse a camera selector. A sandbox has no V4L2 devices to open by
	/// default, so its default camera is PipeWire's, reached through the portal.
	fn select(selector: Option<&'a str>, sandboxed: bool) -> Self {
		match selector {
			None if sandboxed => Self::PipeWire(None),
			None => Self::V4l2(None),
			Some(PIPEWIRE) => Self::PipeWire(None),
			Some(selector) => match selector.strip_prefix(PIPEWIRE).and_then(|rest| rest.strip_prefix(':')) {
				Some(name) => Self::PipeWire(Some(name)),
				None => Self::V4l2(Some(selector)),
			},
		}
	}
}

/// Whether this process runs in a Flatpak or Snap sandbox. Without the
/// `pipewire` feature there is no portal to use, so it never matters.
#[cfg(target_os = "linux")]
fn sandboxed() -> bool {
	#[cfg(feature = "pipewire")]
	{
		ashpd::is_sandboxed()
	}
	#[cfg(not(feature = "pipewire"))]
	{
		false
	}
}

/// Run synchronous platform enumeration off the async runtime's worker threads.
#[cfg(any(target_os = "linux", target_os = "windows"))]
async fn blocking<T, F>(f: F) -> Result<T, Error>
where
	F: FnOnce() -> Result<T, Error> + Send + 'static,
	T: Send + 'static,
{
	tokio::task::spawn_blocking(f)
		.await
		.map_err(|err| Error::Codec(anyhow::anyhow!("capture enumeration thread failed: {err}")))?
}

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

	#[test]
	fn camera_selectors_name_their_backend() {
		assert_eq!(LinuxCamera::select(None, false), LinuxCamera::V4l2(None));
		assert_eq!(LinuxCamera::select(None, true), LinuxCamera::PipeWire(None));
		for sandboxed in [false, true] {
			assert_eq!(
				LinuxCamera::select(Some("/dev/video2"), sandboxed),
				LinuxCamera::V4l2(Some("/dev/video2"))
			);
			assert_eq!(LinuxCamera::select(Some("1"), sandboxed), LinuxCamera::V4l2(Some("1")));
			assert_eq!(
				LinuxCamera::select(Some("pipewire"), sandboxed),
				LinuxCamera::PipeWire(None)
			);
			assert_eq!(
				LinuxCamera::select(Some("pipewire:v4l2_input.pci-0000_00_14.0-usb-0_4_1.0"), sandboxed),
				LinuxCamera::PipeWire(Some("v4l2_input.pci-0000_00_14.0-usb-0_4_1.0"))
			);
		}
		// Only the whole prefix selects PipeWire; anything else is a device path.
		assert_eq!(
			LinuxCamera::select(Some("pipewired"), false),
			LinuxCamera::V4l2(Some("pipewired"))
		);
	}
}