diff options
Diffstat (limited to 'README.rst')
| -rw-r--r-- | README.rst | 181 |
1 files changed, 155 insertions, 26 deletions
@@ -1,4 +1,4 @@ -.. section-begin-libcamera +.. SPDX-License-Identifier: CC-BY-SA-4.0 =========== libcamera @@ -20,7 +20,6 @@ open-source-friendly while still protecting vendor core IP. libcamera was born out of that collaboration and will offer modern camera support to Linux-based systems, including traditional Linux distributions, ChromeOS and Android. -.. section-end-libcamera .. section-begin-getting-started Getting Started @@ -28,11 +27,11 @@ Getting Started To fetch the sources, build and install: -:: +.. code:: - git clone git://linuxtv.org/libcamera.git + git clone https://git.libcamera.org/libcamera/libcamera.git cd libcamera - meson build + meson setup build ninja -C build install Dependencies @@ -42,45 +41,175 @@ The following Debian/Ubuntu packages are required for building libcamera. Other distributions may have differing package names: A C++ toolchain: [required] - Either {g++, clang} + Either {g++, clang} -for libcamera: [required] - meson (>= 0.47) ninja-build python3-yaml +Meson Build system: [required] + meson (>= 0.60) ninja-build pkg-config - If your distribution doesn't provide a recent enough version of meson, - you can install or upgrade it using pip3. +for the libcamera core: [required] + libyaml-dev python3-yaml python3-ply python3-jinja2 - .. code:: +for IPA module signing: [recommended] + Either libgnutls28-dev or libssl-dev, openssl - pip3 install --user meson - pip3 install --user --upgrade meson + Without IPA module signing, all IPA modules will be isolated in a + separate process. This adds an unnecessary extra overhead at runtime. -for device hotplug enumeration: [optional] - pkg-config libudev-dev +for improved debugging: [optional] + libdw-dev libunwind-dev -for qcam: [optional] - qtbase5-dev libqt5core5a libqt5gui5 libqt5widgets5 + libdw and libunwind provide backtraces to help debugging assertion + failures. Their functions overlap, libdw provides the most detailed + information, and libunwind is not needed if both libdw and the glibc + backtrace() function are available. + +for device hotplug enumeration: [optional] + libudev-dev for documentation: [optional] - python3-sphinx doxygen + python3-sphinx doxygen graphviz texlive-latex-extra for gstreamer: [optional] - libgstreamer1.0-dev libgstreamer-plugins-base1.0-dev + libgstreamer1.0-dev libgstreamer-plugins-base1.0-dev + +for Python bindings: [optional] + libpython3-dev pybind11-dev + +for cam: [optional] + libevent-dev is required to support cam, however the following + optional dependencies bring more functionality to the cam test + tool: + + - libdrm-dev: Enables the KMS sink + - libjpeg-dev: Enables MJPEG on the SDL sink + - libsdl2-dev: Enables the SDL sink + +for qcam: [optional] + libtiff-dev qt6-base-dev qt6-tools-dev-tools + +for tracing with lttng: [optional] + liblttng-ust-dev python3-jinja2 lttng-tools + +for android: [optional] + libexif-dev libjpeg-dev + +for Python bindings: [optional] + pybind11-dev + +for lc-compliance: [optional] + libevent-dev libgtest-dev + +for abi-compat.sh: [optional] + abi-compliance-checker + +Basic testing with cam utility +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +The ``cam`` utility can be used for basic testing. You can list the cameras +detected on the system with ``cam -l``, and capture ten frames from the first +camera and save them to disk with ``cam -c 1 --capture=10 --file``. See +``cam -h`` for more information about the ``cam`` tool. + +In case of problems, a detailed debug log can be obtained from libcamera by +setting the ``LIBCAMERA_LOG_LEVELS`` environment variable: + +.. code:: + + :~$ LIBCAMERA_LOG_LEVELS=*:DEBUG cam -l Using GStreamer plugin ~~~~~~~~~~~~~~~~~~~~~~ -To use GStreamer plugin from source tree, set the following environment so that -GStreamer can find it. +To use the GStreamer plugin from the source tree, use the meson ``devenv`` +command. This will create a new shell instance with the ``GST_PLUGIN_PATH`` +environment set accordingly. + +.. code:: + + meson devenv -C build + +The debugging tool ``gst-launch-1.0`` can be used to construct a pipeline and +test it. The following pipeline will stream from the camera named "Camera 1" +onto the OpenGL accelerated display element on your system. + +.. code:: + + gst-launch-1.0 libcamerasrc camera-name="Camera 1" ! queue ! glimagesink + +To show the first camera found you can omit the camera-name property, or you +can list the cameras and their capabilities using: + +.. code:: + + gst-device-monitor-1.0 Video + +This will also show the supported stream sizes which can be manually selected +if desired with a pipeline such as: + +.. code:: + + gst-launch-1.0 libcamerasrc ! 'video/x-raw,width=1280,height=720' ! \ + queue ! glimagesink + +The libcamerasrc element has two log categories, named libcamera-provider (for +the video device provider) and libcamerasrc (for the operation of the camera). +All corresponding debug messages can be enabled by setting the ``GST_DEBUG`` +environment variable to ``libcamera*:7``. + +Presently, to prevent element negotiation failures it is required to specify +the colorimetry and framerate as part of your pipeline construction. For +instance, to capture and encode as a JPEG stream and receive on another device +the following example could be used as a starting point: + +.. code:: - export GST_PLUGIN_PATH=$(pwd)/build/src/gstreamer + gst-launch-1.0 libcamerasrc ! \ + video/x-raw,colorimetry=bt709,format=NV12,width=1280,height=720,framerate=30/1 ! \ + queue ! jpegenc ! multipartmux ! \ + tcpserversink host=0.0.0.0 port=5000 -The debugging tool `gst-launch-1.0` can be used to construct and pipeline and test -it. The following pipeline will stream from the camera named "Camera 1" onto the -default video display element on your system. +Which can be received on another device over the network with: .. code:: - gst-launch-1.0 libcamerasrc camera-name="Camera 1" ! videoconvert ! autovideosink + gst-launch-1.0 tcpclientsrc host=$DEVICE_IP port=5000 ! \ + multipartdemux ! jpegdec ! autovideosink + +The GStreamer element also supports multiple streams. This is achieved by +requesting additional source pads. Downstream caps filters can be used +to choose specific parameters like resolution and pixel format. The pad +property ``stream-role`` can be used to select a role. + +The following example displays a 640x480 view finder while streaming JPEG +encoded 800x600 video. You can use the receiver pipeline above to view the +remote stream from another device. + +.. code:: + + 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 ! multipartmux ! tcpserversink host=0.0.0.0 port=5000 .. section-end-getting-started + +Troubleshooting +~~~~~~~~~~~~~~~ + +Several users have reported issues with meson installation, crux of the issue +is a potential version mismatch between the version that root uses, and the +version that the normal user uses. On calling `ninja -C build`, it can't find +the build.ninja module. This is a snippet of the error message. + +:: + + ninja: Entering directory `build' + ninja: error: loading 'build.ninja': No such file or directory + +This can be solved in two ways: + +1. Don't install meson again if it is already installed system-wide. + +2. If a version of meson which is different from the system-wide version is + already installed, uninstall that meson using pip3, and install again without + the --user argument. |