livekit::capture::CaptureSource Class Reference

A server-side capture source (livekit-capture) that produces video without per-frame FFI traffic. More...

#include <capture_source.h>

Public Member Functions
	CaptureSource (const CaptureSource &)=delete
CaptureSource &	operator= (const CaptureSource &)=delete
	CaptureSource (CaptureSource &&)=delete
CaptureSource &	operator= (CaptureSource &&)=delete
CaptureSourceKind	kind () const noexcept
	Kind of media this source produces.
int	width () const noexcept
	Declared or discovered stream resolution.
int	height () const noexcept
	Declared or discovered stream height.
std::optional< VideoCodec >	codec () const noexcept
	Codec produced by the source; encoded sources only.
std::shared_ptr< VideoSource >	videoSource () const noexcept
	RTC video source fed by this capture source; use it with LocalVideoTrack::createLocalVideoTrack().
TrackPublishOptions	publishOptions (TrackPublishOptions options={}) const
	Returns publish options for this track, applying application options.
Result< void, CaptureError >	start ()
	Start pumping frames into the RTC video source.
Result< void, CaptureError >	stop ()
	Signal a running capture to stop after the frame in flight.
std::future< Result< CaptureResult, CaptureError > >	join ()
	Consume the running pump and wait asynchronously for it to exit.

Static Public Member Functions
static std::future< Result< std::shared_ptr< CaptureSource >, CaptureError > >	create (const GstreamerVideoSourceConfig &config)
	Create a capture source from a GStreamer pipeline configuration.
static std::future< Result< std::shared_ptr< CaptureSource >, CaptureError > >	create (PatternVideoSourceConfig config)
	Create the built-in test pattern capture source.
static std::future< Result< std::shared_ptr< CaptureSource >, CaptureError > >	create (ClockVideoSourceConfig config)
	Create the built-in wall clock capture source.

Friends
class	livekit::FfiClient

Detailed Description

A server-side capture source (livekit-capture) that produces video without per-frame FFI traffic.

The source owns its producer (e.g. a GStreamer pipeline) and the pump that feeds an RTC video source. Publish it like any other source: create a track from CaptureSource::videoSource(), merge application options through CaptureSource::publishOptions(), then call CaptureSource::start().

Structured pump failures are returned as Result values containing CaptureError. Failures without a protobuf error kind throw exceptions. Rust validates source configurations and reports failures as std::runtime_error. Invalid enum values cannot be serialized and throw std::invalid_argument. Initialization, transport, protocol, cancellation, and untyped Rust failures throw std::runtime_error. For create() and join(), these exceptions are delivered when awaiting the future.

Requires a capture-enabled SDK build (LIVEKIT_CAPTURE). Creation fails when the requested source was not compiled into the Rust FFI.

Note

Keep this object alive while the track is published. Destroying it stops a running capture.

Member Function Documentation

codec()

std::optional< VideoCodec > livekit::capture::CaptureSource::codec ( ) const

noexcept

Codec produced by the source; encoded sources only.

Returns

The codec, or no value for a pixel source.

create() [1/3]

static std::future< Result< std::shared_ptr< CaptureSource >, CaptureError > > livekit::capture::CaptureSource::create ( ClockVideoSourceConfig  config )

static

Create the built-in wall clock capture source.

Completes asynchronously after Rust initializes the GPU renderer. Keep the future to overlap setup with other work, or await it immediately. Destroying the future does not wait for creation; an abandoned result is released when creation completes.

Parameters

config

Clock source configuration.

Returns

A future containing a successful Result with the created source.

Exceptions

std::runtime_error	When awaiting the future if Rust rejects the configuration or setup, initialization, transport, protocol validation, or cancellation fails.
std::bad_alloc	If allocation fails, including when awaiting the future.

create() [2/3]

static std::future< Result< std::shared_ptr< CaptureSource >, CaptureError > > livekit::capture::CaptureSource::create ( const GstreamerVideoSourceConfig &  config )

static

Create a capture source from a GStreamer pipeline configuration.

Completes asynchronously: construction starts the pipeline and may wait for its first output to discover stream settings. Configuration, producer setup, transport, protocol, and cancellation failures are delivered as exceptions through the future. Destroying the future does not wait for creation. The source is released when creation completes if the future was discarded.

Parameters

config

GStreamer pipeline configuration.

Returns

A future containing a successful Result with the created source.

Exceptions

std::invalid_argument	When awaiting the future if enum values cannot be serialized.
std::runtime_error	When awaiting the future if Rust rejects the configuration or setup, initialization, transport, protocol validation, or cancellation fails.
std::bad_alloc	If allocation fails, including when awaiting the future.

create() [3/3]

static std::future< Result< std::shared_ptr< CaptureSource >, CaptureError > > livekit::capture::CaptureSource::create ( PatternVideoSourceConfig  config )

static

Create the built-in test pattern capture source.

Completes asynchronously after Rust initializes the GPU renderer. Keep the future to overlap setup with other work, or await it immediately. Destroying the future does not wait for creation; an abandoned result is released when creation completes.

Parameters

config

Pattern source configuration.

Returns

A future containing a successful Result with the created source.

Exceptions

std::invalid_argument	When awaiting the future if enum values cannot be serialized.
std::runtime_error	When awaiting the future if Rust rejects the configuration or setup, initialization, transport, protocol validation, or cancellation fails.
std::bad_alloc	If allocation fails, including when awaiting the future.

height()

int livekit::capture::CaptureSource::height ( ) const

noexcept

Declared or discovered stream height.

Returns

Height in pixels.

join()

std::future< Result< CaptureResult, CaptureError > > livekit::capture::CaptureSource::join

(

)

Consume the running pump and wait asynchronously for it to exit.

This method does not signal the pump to stop. Call stop() first when ending an unbounded source. Join may be called only once after a successful start().

Returns

A future containing statistics on success or a structured pump CaptureError whose kind is supplied by Rust.

Exceptions

std::runtime_error	When awaiting the future if initialization, transport, protocol validation, or cancellation fails.
std::bad_alloc	If allocation fails, including when awaiting the future.

kind()

CaptureSourceKind livekit::capture::CaptureSource::kind ( ) const

noexcept

Kind of media this source produces.

Returns

The source kind.

publishOptions()

TrackPublishOptions livekit::capture::CaptureSource::publishOptions

(

TrackPublishOptions

options = {}

)

const

Returns publish options for this track, applying application options.

Encoded sources override codec with the source codec, select the PreEncoded encoder backend, and disable simulcast. All other fields are taken from options unchanged. Pixel sources preserve every application option; Rust supplies defaults for fields left unset.

Parameters

options

Application publish options.

Returns

Options with source-required fields applied.

start()

Result< void, CaptureError > livekit::capture::CaptureSource::start

(

)

Start pumping frames into the RTC video source.

Returns

A successful Result when Rust acknowledges the request.

Exceptions

std::runtime_error	If the SDK is not initialized, Rust rejects the request, or transport or protocol validation fails.
std::bad_alloc	If memory allocation fails.

stop()

Result< void, CaptureError > livekit::capture::CaptureSource::stop

(

)

Signal a running capture to stop after the frame in flight.

This method does not wait for the pump thread to exit. Call join() to synchronize and retrieve the terminal result. Stopping an already-finished capture is a no-op.

Returns

A successful Result when Rust acknowledges the request.

Exceptions

std::runtime_error	If the SDK is not initialized, Rust rejects the request, or transport or protocol validation fails.
std::bad_alloc	If memory allocation fails.

videoSource()

std::shared_ptr< VideoSource > livekit::capture::CaptureSource::videoSource ( ) const

noexcept

RTC video source fed by this capture source; use it with LocalVideoTrack::createLocalVideoTrack().

Returns

The RTC video source.

width()

int livekit::capture::CaptureSource::width ( ) const

noexcept

Declared or discovered stream resolution.

Returns

Width in pixels.

---

The documentation for this class was generated from the following file:

• include/livekit/capture/capture_source.h