API Reference#

class pyvirtualcam.Camera(width, height, fps, *, fmt=PixelFormat.RGB, device=None, backend=None, print_fps=False, **kw)#

Parameters:

width (int) – Frame width in pixels.
height (int) – Frame height in pixels.
fps (float) – Target frame rate in frames per second.
fmt (PixelFormat) – Input pixel format.
device (Optional[str]) –
The virtual camera device to use. If None, the first available device is used.

Built-in backends:
- v4l2loopback (Linux): /dev/video<n>
- obs (macOS/Windows): OBS Virtual Camera
- unitycapture (Windows): Unity Video Capture, or the name you gave to the device
backend (Optional[str]) –
The virtual camera backend to use. If None, all available backends are tried.

Built-in backends:
- v4l2loopback (Linux)
- obs (macOS/Windows)
- unitycapture (Windows)
print_fps (bool) – Print frame rate every second.
kw – Extra keyword arguments forwarded to the backend. Should only be given if a backend is specified. Note that the built-in backends do not have extra arguments.

close()#

Manually free resources.

This method is automatically called when using with or when this instance goes out of scope.

Return type:: None

send(frame)#

Send a frame to the virtual camera device.

Parameters:: frame (ndarray) – Frame to send. The shape of the array must match the chosen PixelFormat.
Return type:: None

sleep_until_next_frame()#

Adaptively sleep until the next frame is due.

This method continuously adapts the sleep duration in order to reach the target frame rate. As a side effect, it estimates the time spent in computation which is printed as a percentage if print_fps=True is given as argument in the constructor.

Return type:: None

property backend: str#: The virtual camera backend in use.

property current_fps: float#: Current measured frames per second.

property device: str#: The virtual camera device in use.

property fmt: PixelFormat#: The input pixel format as accepted by send().

property fps: float#: Target frame rate in frames per second.

property frames_sent: int#: Number of frames sent.

property height: int#: Frame height in pixels.

property native_fmt: PixelFormat | None#

The native pixel format of the virtual camera, or None if not known or otherwise unavailable.

Note that this is the native format in use in the virtual camera backend and may not necessarily be the native format of the virtual camera device itself. For example, on Windows, a camera device typically supports multiple formats.

property width: int#: Frame width in pixels.

class pyvirtualcam.PixelFormat(value)#

Pixel formats.

The enum values are libyuv FourCC codes. They are only used internally by the virtual camera backends.

BGR = '24BG'#: Shape: (h,w,3)

GRAY = 'J400'#: Shape: (h,w)

I420 = 'I420'#: Shape: any of size w * h * 3/2

NV12 = 'NV12'#: Shape: any of size w * h * 3/2

RGB = 'raw '#: Shape: (h,w,3)

RGBA = 'ABGR'#: Shape: (h,w,4)

UYVY = 'UYVY'#: Shape: any of size w * h * 2

YUYV = 'YUY2'#: Shape: any of size w * h * 2

pyvirtualcam.register_backend(name, clazz)#

If a backend with the same name is already registered, it will be replaced.

Parameters:

name (str) – Name of the backend. Used as backend argument in Camera().
clazz – Class type of the backend conforming to Backend.

class pyvirtualcam.Backend(*, width, height, fps, fourcc, device, **kw)#

Describes the interface of Backend classes.

Note that Backend classes should not inherit from this class, it exists only for documentation and static typing purposes.

All arguments are keyword-only arguments to avoid ambiguities.

Parameters:

width (int) – Image width of the frames passed to send(). If the virtual camera does not support the given width and height combination then an exception must be raised.
height (int) – Image height of the frames passed to send().
fps (float) – Approximate rate at which send() will be called, actual rate may be more or less. The backend should not expect a specific rate but may use this rate as a hint or an upper bound. If the rate is not one of the native frame rates supported by the virtual camera device, then a suitable rate should be chosen. An exception should generally not be raised.
fourcc (int) – Pixel format of frames passed to send(), encoded as libyuv FourCC code. One of the codes in the PixelFormat enum. If the pixel format is unsupported then an exception must be raised.
device (Optional[str]) – If given, name of the virtual camera device to use, otherwise any available device can be used. Depending on the operating system, this is typically a device file name or a camera name as it appears in apps. If a device name is given then the specified device must be used or an exception raised if the device is unavailable. If no device name is given (None) and no device is available then an exception must be raised.
kw – Extra keyword arguments passed through from user code.

abstract close()#

Releases any resources associated with the virtual camera device.

This method is guaranteed to be called exactly once. After this method was called, no further methods are called.

abstract device()#

The name of the virtual camera device in use.

If device was not None in the constructor, then the returned value must match the constructor argument.

Return type:: str

abstract native_fourcc()#

The libyuv FourCC code of the native pixel format used in the backend. Must be one of the codes in the PixelFormat enum, or None if no matching code is defined or the value for some other reason is not available or sensible.

This does not necessarily correspond to all the formats that the device supports when a program captures from it, which is typical on Windows. Rather it is an indication on whether any pixel format conversions have to be done in the backend itself before sending the frame to the camera device.

Return type:: Optional[int]

abstract send(frame)#

Send the given frame to the camera device.

Parameters:: frame (ndarray) – A 1D C-contiguous uint8 numpy array corresponding to the chosen pixel format and frame width and height.