Libcamera Usage and Integration Guide
libcamera is a modern Linux camera framework and userspace library designed for platforms that require coordinated camera pipelines, ISP integration, advanced controls, or multiple output streams. Applications can interact with cameras directly through the libcamera API or through integrations built on top of it.
One of the most common integrations is the GStreamer libcamerasrc element, which exposes libcamera-managed cameras as a standard GStreamer source, allowing applications to preview, record, stream, or process video using normal GStreamer pipelines.
In general, libcamerasrc is commonly used for embedded CSI cameras and ISP-backed camera systems where libcamera provides pipeline management, stream configuration, and camera controls.
Introduction
This guide explains how to use libcamera with GStreamer, how libcamerasrc interacts with the underlying camera framework, how to build and configure the plugin. It also provides enough background on libcamera architecture to help developers understand how camera configuration, controls, and stream management work behind the scenes.
When to Use libcamera and libcamerasrc
libcamera is designed for camera systems that require more than simple frame capture. While traditional Linux applications can access cameras directly through V4L2 using elements such as v4l2src, modern camera platforms often include image signal processors (ISPs), multiple video streams, and advanced camera controls that require additional coordination between hardware components.
The GStreamer libcamerasrc element provides access to these capabilities through the libcamera framework while maintaining the flexibility of standard GStreamer pipelines.
Typical use cases for libcamerasrc include:
- Embedded cameras connected through CSI interfaces
- Platforms with integrated ISPs
- Applications that require automatic exposure, white balance, or autofocus
- Multi-stream camera pipelines
- Systems where camera configuration must be validated automatically
For simple USB webcams that already expose standard V4L2 video nodes, v4l2src is often sufficient. In these scenarios, libcamera may provide limited additional functionality because most image processing is already handled internally by the camera device.
In contrast, platforms such as Raspberry Pi, Rockchip, NXP i.MX, and other embedded systems frequently rely on libcamera to manage complex camera pipelines and expose advanced camera controls to applications.
Tool Fundamentals
libcamera Architecture
libcamera acts as a coordination layer between camera hardware and applications. It discovers camera devices, configures the underlying media pipeline, manages camera controls, and provides a unified API that applications can use independently of the underlying hardware implementation.
When using GStreamer, the libcamerasrc element acts as a bridge between libcamera and the GStreamer pipeline.
The following diagram illustrates how libcamera integrates with the system and how data flows from the camera to the application:
The key takeaway from this diagram is that applications do not interact directly with camera hardware. Instead, libcamera coordinates the underlying media pipeline through a platform-specific pipeline handler and exposes a unified camera API that can be consumed by applications or by GStreamer through the libcamerasrc element.
The following table explains how the components participate in a typical libcamera capture pipeline:
| Component | Purpose |
|---|---|
| Camera Sensor | Produces the raw image data captured by the camera. |
| V4L2 / Media Controller | Exposes camera hardware through standard Linux kernel interfaces and media graphs. |
| Pipeline Handler | Configures and manages the hardware-specific capture pipeline. |
| IPA Module | Implements image-processing algorithms such as auto-exposure (AE), auto-white-balance (AWB), and autofocus (AF). |
| libcamera Core | Coordinates camera discovery, configuration, requests, controls, and device management. |
| Requests | Represent capture operations containing buffers and control parameters. |
| Buffer Management | Allocates and manages memory used to store captured frames. |
| GstLibcameraSrc | Connects libcamera with GStreamer through the libcamerasrc element.
|
| GStreamer Pipeline | Processes, converts, encodes, or transports captured video frames. |
| Application Sink | Consumes the final data for display, recording, streaming, or further processing. |
Pipeline Handlers
A pipeline handler is the component responsible for understanding a specific camera hardware topology. It discovers the media devices associated with a camera, configures the required links and formats, manages buffers, and coordinates image-processing components when present. Applications do not normally select a pipeline handler directly, so when a camera is detected, libcamera automatically chooses the appropriate handler based on the hardware available in the system.
In other words, the application usually just asks libcamera for a camera; libcamera handles the detection of the hardware and the selection of the correct pipeline handler behind the scenes.
These are the current supported handlers:
| Handler | Platform | Description |
|---|---|---|
| uvcvideo | Any architecture | USB Video Class (UVC) cameras such as standard USB webcams and other devices exposing conventional V4L2 interfaces. |
| simple | Any architecture | Generic handler for straightforward media-controller/V4L2 pipelines without complex ISP integration. |
| ipu3 | x86 | Intel IPU3 platforms. Manages the CIO2 input path, ImgU processing block, and associated IPA logic. |
| rkisp1 | ARM | Rockchip ISP1 platforms. Supports sensor integration, ISP processing paths, and Rockchip IPA modules. |
| imx8-isi | ARM | NXP i.MX8 ISI capture pipelines based on the Image Sensing Interface (ISI). |
| mali-c55 | ARM | ARM Mali-C55 ISP platforms supporting several hardware topologies and RAW capture paths. |
| rpi/vc4 | ARM | Legacy Raspberry Pi VC4 camera pipeline based on Unicam and the VC4 ISP. |
| rpi/pisp | ARM | New Raspberry Pi PiSP architecture including PiSP front-end and ISP processing blocks. |
| vimc | Test | Virtual Media Controller test pipeline used for development and validation. |
| virtual | Test | Synthetic virtual cameras useful for testing, demonstrations, and controlled image generation. |
Build support is also architecture-dependent:
- simple and uvcvideo can be built on any architecture supported by libcamera. However, actual camera support depends on the underlying hardware topology and available drivers.
- ipu3 is enabled for x86 platforms.
- imx8-isi, mali-c55, rkisp1, rpi/vc4, and rpi/pisp are enabled on ARM platforms.
- vimc and virtual are test-oriented handlers.
Image Processing and Controls
One of the main advantages of libcamera is its ability to expose camera controls and image-processing functionality through a unified interface.
The exact capabilities available depend on the camera hardware, the controls implemented by the sensor driver and the pipeline handler in use. While simple USB cameras typically expose only basic controls, embedded camera systems may provide features such as:
- Auto Exposure (AE)
- Auto White Balance (AWB)
- Autofocus (AF)
- Multiple output streams
- Per-frame metadata
- ISP-assisted image processing
Rather than exposing a fixed set of ISP features, libcamera provides access to the controls and metadata supported by the underlying platform. As a result, the functionality available through libcamerasrc may vary between devices depending on the camera hardware and pipeline handler in use.
It does not expose ISP features such as denoise, sharpening, HDR, or tone mapping as a standard list of capabilities. These features are often implemented internally by the pipeline handler and IPA module, and may not be directly configurable.
To understand what a specific camera supports, you should:
- Inspect available controls (via libcamera or GStreamer)
- Check supported stream formats and resolutions
- Analyze metadata returned per frame
- Refer to the pipeline handler documentation for the platform
The GStreamer libcamera Plugin
The GStreamer libcamera plugin provides the libcamerasrc element, which acts as the integration layer between libcamera and GStreamer.
While libcamera is responsible for camera discovery, configuration, request management, and camera controls, libcamerasrc exposes these capabilities as a standard GStreamer source element. This allows libcamera-managed cameras to be used with the full GStreamer ecosystem, including video conversion, encoding, recording, streaming, and AI processing pipelines.
Unlike traditional source elements such as v4l2src, libcamerasrc can leverage libcamera features such as automatic pipeline configuration, camera controls, stream roles, and multi-stream operation when supported by the underlying hardware.
Element Properties
The libcamerasrc element exposes a large number of properties that map directly to libcamera controls. These properties allow applications to configure camera behavior, image processing parameters, and sensor settings from within a GStreamer pipeline.
The exact properties exposed by libcamerasrc depend on the libcamera version, camera hardware, ISP capabilities, and pipeline handler in use. The table below highlights some of the most commonly used controls.
To inspect the complete list of properties available on your system, run:
gst-inspect-1.0 libcamerasrc
While the exact set of properties varies by platform, the following table summarizes some of the most commonly used controls and their typical purpose:
| Category | Property | Description |
|---|---|---|
| Camera Selection | camera-name | Selects the camera to use when multiple cameras are available. |
| Auto Exposure (AE) | ae-enable | Enables or disables automatic exposure and gain control. |
| ae-metering-mode | Selects the image regions used for exposure calculations. | |
| Exposure Control | exposure-time | Sets the sensor exposure time when operating in manual mode. |
| Gain Control | analogue-gain | Sets the sensor gain manually. |
| Auto White Balance (AWB) | awb-enable | Enables or disables automatic white balance. |
| awb-mode | Selects the white balance operating mode. | |
| Autofocus (AF) | af-mode | Selects autofocus operation mode. |
| lens-position | Sets the lens position manually when supported. | |
| Image Processing | brightness | Adjusts image brightness. |
| contrast | Adjusts image contrast. | |
| saturation | Adjusts color saturation. | |
| sharpness | Controls edge enhancement. | |
| Sensor Configuration | scaler-crop | Defines a cropped sensor region for digital zoom. |
| sensor-config | Selects sensor operating modes and configurations. |
libcamerasrc vs v4l2src
Both libcamerasrc and v4l2src ultimately interact with Linux camera drivers through the V4L2 subsystem. The main difference is that libcamerasrc uses the libcamera framework as an abstraction layer between the application and the hardware.
| Feature | v4l2src | libcamerasrc |
|---|---|---|
| Camera access | Direct V4L2 device access | Through libcamera |
| Configuration | Manual format and resolution selection | Automatic configuration and validation |
| ISP integration | Limited | Supported when available |
| Camera controls | Standard V4L2 controls | Unified libcamera controls |
| Multi-stream support | Limited | Supported when hardware allows |
| Complex camera pipelines | Platform dependent | Primary use case |
| Embedded CSI cameras | Platform dependent | Common use case |
Pros and Cons
The following points summarize the main advantages and limitations of using libcamera and the libcamerasrc GStreamer element compared to direct V4L2-based approaches such as v4l2src.
Advantages
- Simplified pipeline creation through automatic configuration and validation.
- Unified API across different camera platforms and hardware topologies.
- Support for advanced camera pipelines, ISP integration, and camera controls.
- Multi-stream support when supported by the underlying hardware.
- Seamless integration with the GStreamer ecosystem.
Limitations
- Additional abstraction layer introduces slight runtime overhead compared to direct V4L2 access.
- Limited benefits when using simple USB cameras that already expose standard V4L2 interfaces.
- Some features depend on hardware support, pipeline handlers, and camera-specific implementations.
- Debugging may require understanding both libcamera and the underlying V4L2/media-controller infrastructure.
Installation Guide
This section describes how to build and install libcamera from the upstream project sources. The instructions can be used either to install the libcamera library and command-line tools, or to additionally build the GStreamer integration provided by the libcamerasrc element.
These instructions are suitable for general Linux environments and provide a baseline installation that can be used for development, testing, and supported platforms that rely on upstream libcamera.
Some platforms require additional build steps, custom forks, or BSP integration. For platform-specific instructions, refer to the corresponding sections later in this guide, such as the NXP i.MX95 build procedures.
Dependencies
The following packages are required to build libcamera:
- Meson (>= 1.0)
- Ninja build system
- pkg-config
- libyaml-dev
- python3-yaml
- python3-jinja2
- python3-ply
For GStreamer integration:
- libgstreamer1.0-dev
- libgstreamer-plugins-base1.0-dev
Optional dependencies:
- libdrm-dev
- libsdl2-dev
- libjpeg-dev
- libtiff-dev
On Debian-based systems you can run:
sudo apt-get install \ meson ninja-build pkg-config \ libyaml-dev python3-yaml python3-jinja2 python3-ply \ libgstreamer1.0-dev libgstreamer-plugins-base1.0-dev
Building the Project
The examples in this section were tested using the upstream libcamera project on an x86_64 Ubuntu development system.
To start get the libcamera project:
git clone https://git.libcamera.org/libcamera/libcamera.git cd libcamera
This project uses the Meson build system and provides several configuration options that affect the build:
- -Dgstreamer=enabled
- Enables the GStreamer plugin (libcamerasrc)
- -Ddocumentation=disabled
- Disables documentation generation to avoid missing Sphinx dependencies
- -Dtest=false
- Disables unit tests to reduce compilation time
A standard build can be performed as follows:
meson setup build ninja -C build sudo ninja -C build install
If installation fails due to permissions, ensure the install step is executed with elevated privileges.
Using the Development Environment
To run GStreamer plugins directly from the build directory without installing:
meson devenv -C build
This launches a shell with the appropriate environment variables (e.g., GST_PLUGIN_PATH).
Verifying Installation
First, verify that the libcamera tools were installed correctly:
cam --help
The command should display the available options for the cam utility.
To verify that the GStreamer integration was built and installed correctly:
gst-inspect-1.0 libcamerasrc
Expected output should include:
- libcamerasrc: GStreamer source element for libcamera
If both commands succeed, the libcamera library, command-line tools, and GStreamer plugin are available for use.
Building on Jetson Platform
Jetson platforms use NVIDIA-specific camera infrastructure that differs from the camera stacks supported by upstream libcamera.
While libcamera can be compiled on Jetson systems and may work with USB cameras through the uvcvideo pipeline handler, CSI camera support is currently limited because NVIDIA cameras typically rely on the proprietary Argus framework rather than an upstream libcamera pipeline handler.
Building libcamera on NXP i.MX95
NXP maintains a separate libcamera fork repository for i.MX platforms because camera support on i.MX95 is not limited to simple sensor registration. The platform exposes multiple camera processing paths, each requiring a specific pipeline handler along with supporting components.
The examples and validation steps described in this section were tested using the following hardware and software configuration. Different BSP versions, camera sensors, or pipeline handlers may expose different capabilities and behaviors.
| Component | Value |
|---|---|
| Platform | NXP i.MX95 |
| Camera | OV5640 |
| Source | NXP libcamera fork |
| Pipeline Handler | imx8-isi |
For related models, NXP defines the following usage:
- RAW camera paths use the dedicated nxp/neo pipeline handler together with its associated IPA module.
- ISI-based camera paths use the NXP ISI pipeline handler.
- Basic or generic use cases can rely on upstream handlers such as simple and uvcvideo.
NXP-Specific Pipeline Handlers
To use the NXP Neo ISP pipeline, the NXP libcamera fork and BSP packages must be installed. Pipeline handler selection can be controlled through the LIBCAMERA_PIPELINES_MATCH_LIST environment variable, which is discussed later in the verification section.
NXP also defines environment variables used to locate IPA modules and configuration files:
export LIBCAMERA_IPA_MODULE_PATH=/usr/lib/libcamera/ipa export LIBCAMERA_IPA_CONFIG_PATH=/usr/share/libcamera/ipa
The Neo pipeline configuration is typically located at:
share/libcamera/pipeline/nxp/neo/config.yaml
For RAW sensor support, the IPA implementation and calibration files are typically located under:
src/ipa/nxp/neo/ src/ipa/nxp/neo/data/<camera>.yaml
NXP Additions
NXP's implementation extends upstream libcamera by providing all the components required to support the Neo ISP pipeline:
- A dedicated pipeline handler for the Neo ISP path.
- An IPA module implementing camera control algorithms such as AE and AWB.
- Sensor-specific calibration data.
- Pipeline configuration files for additional streams and operating modes.
- Environment variables used to control handler selection and priority.
The pipeline handler manages the platform-specific media graph. In the Neo ISP case, this includes the sensor, CSI interface, ISI block, and ISP. In contrast, the ISI pipeline typically manages only the sensor, CSI, and ISI components.
Building libcamera with Yocto
On i.MX95 platforms, libcamera is typically built from NXP's fork through the Yocto build system rather than being compiled directly on the target device. This approach ensures that the correct pipeline handlers, IPA modules, and GStreamer integration are included in the final image.
Creating the Yocto Override
The recommended approach is to override the existing libcamera recipe using a .bbappend file in a custom Yocto layer rather than modifying the original recipe directly.
For example:
meta-custom/
└── recipes-multimedia/
└── libcamera/
└── libcamera_%.bbappend
The contents shown in the following example should be placed in the libcamera_%.bbappend file. Ensure that the custom layer is included in bblayers.conf so that BitBake applies the override during the build.
SRC_URI = "git://github.com/nxp-imx/libcamera.git;protocol=https;branch=lf-6.12.34_2.1.0"
SRCREV = "0fe7f3f91fb9cc162c4ac4ef854322c3d6c4f5ee"
S = "${WORKDIR}/git"
EXTRA_OEMESON:remove = "-Dpipelines=auto"
EXTRA_OEMESON:append = " -Dpipelines=simple,imx8-isi,uvcvideo -Dgstreamer=enabled"
DEPENDS:append = " glib-2.0 gstreamer1.0 gstreamer1.0-plugins-base"
The override performs the following changes:
- Replaces the upstream source with the NXP libcamera fork.
- Pins the build to a known commit validated on i.MX95.
- Explicitly enables the simple, imx8-isi, and uvcvideo pipeline handlers.
- Enables the GStreamer plugin through -Dgstreamer=enabled.
- Adds the required GLib and GStreamer build dependencies.
After modifying the recipe, build libcamera and generate the target image you are going to deploy:
bitbake libcamera bitbake example-image
Verifying Installation
After flashing the image, it is important to verify that libcamera and the GStreamer plugin were installed correctly before testing the camera pipeline.
As mentioned before, the NXP libcamera fork includes support for multiple pipeline handlers, so before testing the camera, the pipeline matching order must be configured so that libcamera selects the correct handler for the platform.
For i.MX systems using the Neo ISP pipeline, set:
export LIBCAMERA_PIPELINES_MATCH_LIST='nxp/neo,imx8-isi,simple'
This configuration prioritizes the NXP Neo handler, followed by the NXP ISI and Simple handlers.
For debugging, enable verbose logging:
export LIBCAMERA_LOG_LEVELS=SimplePipeline:DEBUG,Camera:DEBUG,V4L2:DEBUG,ISI:DEBUG
Then verify that libcamera is able to detect the available cameras:
cam -l
A successful execution should display one or more cameras registered by a pipeline handler. For example:
[2:03:23.349933847] [12854] INFO Camera camera_manager.cpp:340 libcamera v0.7.1+8-2106c9f9 [2:03:23.476956695] [12858] INFO Camera camera_manager.cpp:223 Adding camera '\_SB_.PC00.XHCI.RHUB.HS06-6:1.0-0c45:6739' for pipeline handler uvcvideo Available cameras: 1: Internal front camera (\_SB_.PC00.XHCI.RHUB.HS06-6:1.0-0c45:6739)
The exact camera name and pipeline handler will depend on the platform and connected camera. The important part is that libcamera reports one or more cameras under the Available cameras section.
Also verify that the GStreamer plugin is installed:
gst-inspect-1.0 libcamerasrc
The output should include information about the libcamerasrc element and its supported properties and capabilities.
Practical Implications
The use of a dedicated NXP repository reflects the SoC- and ISP-specific nature of the i.MX95 camera stack. While upstream libcamera provides the general framework for camera discovery, controls, and pipeline management, NXP extends it with:
- Neo ISP-specific pipeline logic.
- Sensor tuning and calibration data.
- Board-specific camera configuration.
- Additional pipeline handlers and IPA modules.
As a result, camera enablement on i.MX95 often requires platform-specific components beyond what is available in upstream libcamera. Understanding the relationship between pipeline handlers, IPA modules, and the media topology is essential when debugging camera integration issues or enabling support for new camera sensors.
Usage
The following examples demonstrate usage of both the libcamera framework and the GStreamer libcamerasrc element on an NXP i.MX95 platform using an OV5640 camera.
Before running the examples, ensure that the camera is detected by libcamera and that the appropriate pipeline handler is available.
Using libcamera utility
The libcamera project provides several command-line applications that interact directly with the libcamera framework without requiring GStreamer.
The main command is cam, which can be used to verify camera detection, inspect available cameras, and perform basic frame capture operations.
To list the available cameras:
cam -l
Example output:
Available cameras: 1: 'ov5640' (/base/soc/bus@42000000/i2c@426b0000/camera@3c)
Basic Capture Test
To be able to capture frames for this NXP use case, first export the handlers:
export LIBCAMERA_PIPELINES_MATCH_LIST='nxp/neo,imx8-isi,simple'
Then run a simple capture:
cam -c 1 --capture=10
This captures 10 frames and reports capture statistics such as frame rate and frame size.
Using libcamera Through GStreamer
A simple way to verify camera capture through GStreamer is to stream frames into a fakesink:
gst-launch-1.0 libcamerasrc ! fakesink
This pipeline validates camera detection, stream negotiation, and frame delivery without requiring a graphical display.
Example with Explicit Caps
It is recommended to explicitly specify the desired stream configuration:
gst-launch-1.0 libcamerasrc ! \
'video/x-raw,colorimetry=bt709,format=YUY2,width=1280,height=720,framerate=30/1' ! \
fakesink
Note that libcamera validates requested configurations and may automatically adjust them to the closest supported values.
GStreamer Requirements
When building pipelines with libcamerasrc, it is recommended to explicitly define caps including format, framerate, and colorimetry to avoid negotiation issues.
Example:
gst-launch-1.0 libcamerasrc ! \
'video/x-raw,colorimetry=bt709,format=YUY2,width=1920,height=1080,framerate=30/1' ! \
fakesink
Failing to specify these parameters may lead to negotiation errors or unexpected behavior depending on the platform.
Multiple Stream Configuration
libcamerasrc supports configuring multiple streams from a single camera device when the underlying hardware allows it. This enables use cases such as generating a low-resolution preview while simultaneously producing a higher-resolution encoded stream.
Stream Roles
When requesting multiple streams, each source pad can be assigned a stream-role. Stream roles describe the intended use of a stream and allow libcamera to select an appropriate camera configuration for that purpose.
The libcamerasrc element currently supports the following stream roles:
| Stream Role | Description | Typical Use Case |
|---|---|---|
| still-capture | Optimized for high-quality image capture. | Taking photographs or snapshots. |
| video-recording | Optimized for continuous video capture and encoding. | Recording video streams. |
| view-finder | Optimized for low-latency preview output. | Live display and preview windows. |
In a multi-stream configuration, different roles can be assigned to different source pads. For example, a camera may provide a low-latency view-finder stream for display while simultaneously generating a higher-quality video-recording stream for encoding or storage.
The following example illustrates a generic libcamera multi-stream configuration. Support depends on the camera sensor, pipeline handler, and platform implementation.
gst-launch-1.0 libcamerasrc name=cs \
src::stream-role=view-finder \
src_0::stream-role=video-recording \
cs.src ! queue ! video/x-raw,width=640,height=480 ! videoconvert ! autovideosink \
cs.src_0 ! queue ! video/x-raw,width=800,height=600 ! videoconvert ! jpegenc ! fakesink
In this pipeline:
- Two streams are requested from the camera using different roles.
- The view-finder stream is used for low-latency display at a lower resolution.
- The video-recording stream is used for video capture and encoding at a higher resolution.
- Each stream is accessed through a different source pad (cs.src and cs.src_0).
- libcamera selects stream configurations that best match the requirements of each role.
Hardware Considerations
Multi-stream configurations depend on the capabilities of the camera and its pipeline handler.
If the hardware does not support multi-stream configurations, the pipeline may fail with errors such as:
Camera::generateConfiguration() returned nullptr
Understanding Configuration Adjustment
During pipeline execution, libcamera may output messages indicating that the configuration has been modified:
CameraConfiguration::validate() returned CameraConfiguration::Adjusted
This means:
- The requested format or resolution was not fully supported.
- libcamera automatically selected a compatible configuration.
- The pipeline continues using the adjusted parameters.
Camera Selection
When multiple cameras are connected, libcamera automatically detects all available devices:
cam -l
Example output:
Available cameras: 1: 'ov5640' (/base/soc/bus@42000000/i2c@426b0000/camera@3c)
When multiple cameras are available, a specific camera can be selected through the camera-name property:
gst-launch-1.0 libcamerasrc camera-name="ov5640" ! \
fakesink
Internally, these cameras are still mapped to V4L2 devices such as /dev/video0, /dev/video1, etc., but libcamera abstracts this mapping and uses its own naming system.
Debugging
libcamera provides detailed logging that can help diagnose camera detection issues, pipeline handler selection, stream configuration problems, and capture failures. To enable global debug logging:
export LIBCAMERA_LOG_LEVELS=*:DEBUG
To enable specific logging categories:
export LIBCAMERA_LOG_LEVELS='Camera:DEBUG,Pipeline:DEBUG,ISI:DEBUG,SimplePipeline:DEBUG'
For GStreamer-specific debugging:
GST_DEBUG=libcamera*:7 gst-launch-1.0 libcamerasrc ! fakesink
Debug output typically includes information about camera discovery, pipeline handler selection, sensor configuration, stream negotiation, and capture operations.
For example:
[0:26:30.623978017] [848] DEBUG Camera camera_manager.cpp:126 Found listed pipeline handler 'imx8-isi' [0:26:30.627569930] [848] DEBUG Camera camera_manager.cpp:161 Pipeline handler "imx8-isi" matched [0:26:31.106225315] [849] DEBUG ISI imx8-isi.cpp:571 Computed sensor configuration: 1920x1080-UYVY8_1X16 [0:26:31.106498308] [849] INFO Camera camera.cpp:1205 configuring streams: (0) 1920x1080-YUYV/Unset [0:26:31.115613755] [849] DEBUG Camera camera.cpp:1382 Starting capture
These messages indicate that libcamera successfully discovered a compatible pipeline handler, selected a sensor format, configured the requested stream, and started frame capture.
The following log messages are commonly useful when debugging camera pipelines.
Pipeline Handler Selection
Verify which pipeline handlers were discovered and which one matched the hardware:
DEBUG Camera camera_manager.cpp:126 Found listed pipeline handler 'imx8-isi' DEBUG Camera camera_manager.cpp:161 Pipeline handler "imx8-isi" matched
Pipeline handlers are selected automatically by libcamera based on the detected media topology. Applications do not directly choose a handler.
In some cases, the matching order can be influenced through the LIBCAMERA_PIPELINES_MATCH_LIST environment variable. For example:
export LIBCAMERA_PIPELINES_MATCH_LIST='nxp/neo,imx8-isi,simple'
This does not force a handler to be used if it cannot manage the hardware, but it allows compatible handlers to be prioritized during the matching process.
Sensor Driver Warnings
These warnings may indicate missing controls or incomplete sensor driver support:
WARN CameraSensor camera_sensor_legacy.cpp:354 'ov5640 4-003c': Recommended V4L2 control 0x009a0922 not supported WARN CameraSensor camera_sensor_legacy.cpp:616 'ov5640 4-003c': Rotation control not available, default to 0 degrees
Stream Configuration
Applications can request stream parameters such as resolution, pixel format, and frame rate through libcamera or libcamerasrc. However, the final stream configuration is validated by libcamera and may be adjusted to match the capabilities of the camera sensor, ISP, and pipeline handler.
These debug messages show both the requested stream configuration and the sensor format ultimately selected by the pipeline handler.
Here you can verify the requested stream parameters, sensor configuration, and selected format:
DEBUG ISI imx8-isi.cpp:464 Stream 0: 1920x1080-YUYV/Unset DEBUG ISI imx8-isi.cpp:571 Computed sensor configuration: 1920x1080-UYVY8_1X16 DEBUG ISI imx8-isi.cpp:631 Selected sensor format: 1920x1080-UYVY8_1X16
Final Camera Configuration
Confirm the final stream configuration applied by libcamera:
INFO Camera camera.cpp:1205 configuring streams: (0) 1920x1080-YUYV/Unset
This is useful when verifying whether libcamera adjusted the requested configuration.
Frame Statistics
The cam utility reports frame-level statistics that can be used to validate throughput and frame rate:
1591.748128 (30.03 fps) cam0-stream0 seq: 000001 bytesused: 4147200
This output includes the measured frame rate, frame sequence number, and captured frame size.
Performance
To evaluate the overhead introduced by libcamera, CPU utilization and memory consumption were measured on an NXP i.MX95 platform using an OV5640 camera configured for 1920x1080 @ 30 FPS.
The measurements were collected using the Linux time -v utility while running each pipeline continuously for 60 seconds and directing the output to a fakesink.
Test Environment
| Component | Value |
|---|---|
| Platform | NXP i.MX95 |
| Camera | OV5640 |
| Resolution | 1920x1080 |
| Framerate | 30 FPS |
| Format | YUY2 |
| Duration | 60 seconds |
Tested Pipelines
libcamerasrc
gst-launch-1.0 -q \ libcamerasrc ! \ 'video/x-raw,colorimetry=bt709,format=YUY2,width=1920,height=1080,framerate=30/1' ! \ fakesink sync=false
v4l2src
gst-launch-1.0 -q \ v4l2src device=/dev/video6 io-mode=mmap ! \ 'video/x-raw,format=YUY2,width=1920,height=1080,framerate=30/1' ! \ fakesink sync=false
Results
CPU Usage
The following measurements provide a reference for the runtime overhead introduced by libcamera compared to direct V4L2.
All measurements were performed using a single OV5640 camera operating at 1920x1080 @ 30 FPS. No additional cameras were active during the test.
| Pipeline | CPU Usage (%) |
|---|---|
| libcamerasrc | 3 |
| v4l2src | 1 |
Latency
To evaluate the end-to-end latency introduced by libcamera, a glass-to-glass test was performed on the same i.MX95 platform used for the performance measurements. The test measures the delay between a visual event occurring in front of the camera and the corresponding image being displayed on the screen.
The following pipelines were used during the latency test:
v4l2src
gst-launch-1.0 \
v4l2src device=/dev/video6 ! \
video/x-raw,width=1920,height=1080 ! \
autovideosink
libcamerasrc
export LIBCAMERA_PIPELINES_MATCH_LIST='nxp/neo,imx8-isi,simple'
gst-launch-1.0 \
libcamerasrc ! \
videoconvert ! \
autovideosink
The measured glass-to-glass latency values were:
| Pipeline | Latency (ms) |
|---|---|
| libcamerasrc | 159.6 |
| v4l2src | 107.4 |
The results show that libcamerasrc introduces additional latency compared to direct V4L2 capture. This behavior is expected because libcamera performs camera configuration, request management, buffer handling, and control processing before frames are delivered to the GStreamer pipeline.
Known Limitations
- CSI cameras on Jetson typically use NVIDIA's Argus stack and may not work with libcamera's generic pipeline handlers.
- Some optional dependencies such as gnutls or libcrypto may be missing on Jetson setups. In that case IPA modules run in isolated mode, which is acceptable for basic usage but adds runtime overhead.
- Multi-stream support depends on the camera hardware and pipeline handler.
- Not all cameras expose the same controls.
- Some ISP features are implemented internally and may not be configurable.
- USB cameras often expose fewer controls than embedded camera pipelines.
FAQ
- What is libcamerasrc?
- A GStreamer source element that captures video through the libcamera framework.
- How is libcamerasrc different from v4l2src?
- libcamerasrc uses libcamera's higher-level camera management while v4l2src directly accesses V4L2 devices.
- Can I use USB cameras with libcamera?
- Yes. Most USB webcams are supported through the uvcvideo pipeline handler.
- Does libcamera support multiple streams?
- Yes, when the hardware and pipeline handler support it.
- How can I see which cameras libcamera detects?
- Use
cam -lorgst-device-monitor-1.0 Video. - Why does libcamerasrc expose different controls on different cameras?
- Controls depend on the camera hardware, ISP capabilities, and pipeline handler.
- Can I use libcamerasrc with CSI cameras?
- Yes, provided the platform includes a supported libcamera pipeline handler.
- How do I enable debugging?
- Use
LIBCAMERA_LOG_LEVELS=*:DEBUGorGST_DEBUG=libcamera*:7.
References
The information presented in this guide is based on the following primary sources and project documentation:
- libcamera Official Project
- libcamera Source Repository
- GStreamer libcamera Plugin Documentation
- NXP libcamera Fork
- RidgeRun Glass-to-Glass Latency Measurement Methodology
For direct inquiries, please refer to the contact information available on our Contact page. Alternatively, you may complete and submit the form provided at the same link. We will respond to your request at our earliest opportunity.
Links to RidgeRun Resources and RidgeRun Artificial Intelligence Solutions can be found in the footer below.
ARTIFICIAL INTELLIGENCE
