Preface
The Raspberry Pi OS provides a set of small example programs called rpicam-apps. These command‑line (CLI) applications, built on the libcamera library, can be used to capture images and video from a camera. The main programs include:
- rpicam-hello: A "hello world" example for the camera, launching a camera preview stream and displaying it on the screen.
- rpicam-jpeg: Runs a preview window and then captures a high‑resolution still image.
- rpicam-still: Emulates most of the features of the original
raspistilltool. - rpicam-vid: Records video.
- rpicam-raw: Captures raw (unprocessed Bayer) frame data directly from the image sensor.
- rpicam-detect: Not compiled by default; users can compile it themselves if TensorFlow Lite is installed on the Raspberry Pi. When a specified object is detected, it automatically captures a JPEG photo.
When a supported MIPI camera module is connected, users can configure it via the config.txt file and then use commands to preview and use the camera.
rpicam-hello
You should see a camera preview window for about five seconds.
Note: If running on a Raspberry Pi 3 or earlier device with Bullseye, you need to re‑enable Glamor for the X Windows hardware‑accelerated preview window to work correctly.
In a terminal, type sudo raspi-config, then select Advanced Options, Glamor, and Yes. Exit and restart your Raspberry Pi board.
By default, Raspberry Pi 3 and earlier devices running Bullseye may not be using the correct display driver. Check the /boot/firmware/config.txt file and ensure that either dtoverlay=vc4-fkms-v3d or dtoverlay=vc4-kms-v3d is currently enabled. If you need to change this setting, reboot after doing so.
rpicam-hello is the "hello world" of the camera: it starts a camera preview stream and displays it on the screen. You can stop the preview by clicking the window's close button or by pressing Ctrl^C in the terminal.
rpicam-hello -t 0
Tuning Files
The libcamera for Raspberry Pi has tuning files for each type of camera module. The parameters in these files are passed to algorithms and hardware to produce the best quality image. libcamera can automatically determine which image sensor is being used, but it cannot automatically determine the entire module (even though the module affects tuning). Therefore, it is sometimes necessary to override the default tuning file for a particular sensor.
For example, NoIR versions of sensors need different AWB (auto white balance) settings than the standard version. So an IMX219 NoIR used with a Pi 4 or earlier should be run with:
rpicam-hello --tuning-file /usr/share/libcamera/ipa/rpi/vc4/imx219_noir.json
On Raspberry Pi 5, different tuning files are used in a different folder, so here you would use:
rpicam-hello --tuning-file /usr/share/libcamera/ipa/rpi/pisp/imx219_noir.json
This also means that users can copy an existing tuning file and modify it to their liking, as long as the --tuning-file parameter points to the new version.
The --tuning-file parameter works with all rpicam-apps, just like other command‑line options.
rpicam-jpeg
rpicam-jpeg is a simple still image capture application.
To capture a full‑resolution JPEG image, use the following command. It will display a preview for about five seconds and then save a full‑resolution JPEG image to the file test.jpg.
rpicam-jpeg -o test.jpg
The -t option can change the length of the preview display, and the --width and --height options change the resolution of the captured still image. For example:
rpicam-jpeg -o test.jpg -t 2000 --width 640 --height 480
Exposure Control
All rpicam-apps allow the user to run the camera with fixed shutter speed and gain. To capture an image with an exposure time of 20 ms and a gain of 1.5× (which will be used as analogue gain inside the sensor until the maximum analogue gain allowed by the kernel sensor driver is reached, after which the remainder will be used as digital gain):
rpicam-jpeg -o test.jpg -t 2000 --shutter 20000 --gain 1.5
The Raspberry Pi's AEC/AGC algorithm allows applications to specify exposure compensation: it can darken or brighten an image with a given number of stops.
rpicam-jpeg --ev -0.5 -o darker.jpg
rpicam-jpeg --ev 0 -o normal.jpg
rpicam-jpeg --ev 0.5 -o brighter.jpg
Digital Gain
The digital gain is applied by the ISP, not by the sensor. The digital gain will always be very close to 1.0 unless:
The total gain requested (via the option --gain or via the exposure profile in the camera adjustment) exceeds the gain that can be used as an analog gain within the sensor. Only the extra gain required will be used as digital gain.
One of the color gains is less than 1 (note that color gains are also applied as digital gain). In this case, the reported digital gain will settle to 1 / min(red gain, blue gain). This means that one color channel (rather than the green channel) gets a unit digital gain.
The AEC/AGC is changing. When the AEC/AGC moves, digital gain may vary somewhat to try to smooth out any fluctuations, but it quickly returns to a normal value.
rpicam-still
It emulates many features of the original raspistill application.
rpicam-still -o test.jpg
Encoders
rpicam-still allows images to be saved in several different formats. It supports PNG and BMP encoding. It also allows images to be saved as binary dumps of RGB or YUV pixels, with no encoding or file format. In the latter case, the application reading the file must understand the pixel layout itself.
rpicam-still -e png -o test.png
rpicam-still -e bmp -o test.bmp
rpicam-still -e rgb -o test.data
rpicam-still -e yuv420 -o test.data
Note that the format of the saved image is determined by the -e (or --encoding) option, and is not automatically selected based on the output filename.
Raw Image Capture
A raw image is produced directly by the image sensor before any processing by the ISP (Image Signal Processor) or CPU cores. For color image sensors, these are usually Bayer format images. Note that raw images are quite different from the processed but unencoded RGB or YUV images we saw earlier.
To capture a raw image:
rpicam-still --raw --output test.jpg
Here the -r (or --raw) option indicates that a raw image should be captured along with a JPEG. In fact, the raw image is the raw image from which the JPEG was generated. The raw image is saved in DNG (Adobe Digital Negative) format, which is compatible with many standard applications (such as draw or RawTherapee). The raw image is saved to a file with the same name but the extension .dng, so in this case test.dng.
These DNG files contain metadata about the image capture, including black levels, white balance information, and the colour matrix that the ISP used to generate the JPEG. This makes these DNG files more convenient for later "manual" raw conversion using some of the tools mentioned above. You can use exiftool to display all the metadata encoded in a DNG file:
File Name : test.dng
Directory : .
File Size : 24 MB
File Modification Date/Time : 2021:08:17 16:36:18+01:00
File Access Date/Time : 2021:08:17 16:36:18+01:00
File Inode Change Date/Time : 2021:08:17 16:36:18+01:00
File Permissions : rw-r--r--
File Type : DNG
File Type Extension : dng
MIME Type : image/x-adobe-dng
Exif Byte Order : Little-endian (Intel, II)
Make : Raspberry Pi
Camera Model Name : /base/soc/i2c0mux/i2c@1/imx477@1a
Orientation : Horizontal (normal)
Software : rpicam-still
Subfile Type : Full-resolution Image
Image Width : 4056
Image Height : 3040
Bits Per Sample : 16
Compression : Uncompressed
Photometric Interpretation : Color Filter Array
Samples Per Pixel : 1
Planar Configuration : Chunky
CFA Repeat Pattern Dim : 2 2
CFA Pattern 2 : 2 1 1 0
Black Level Repeat Dim : 2 2
Black Level : 256 256 256 256
White Level : 4095
DNG Version : 1.1.0.0
DNG Backward Version : 1.0.0.0
Unique Camera Model : /base/soc/i2c0mux/i2c@1/imx477@1a
Color Matrix 1 : 0.8545269369 -0.2382823821 -0.09044229197 -0.1890484985 1.063961506 0.1062747385 -0.01334283455 0.1440163847 0.2593136724
As Shot Neutral : 0.4754476844 1 0.413686484
Calibration Illuminant 1 : D65
Strip Offsets : 0
Strip Byte Counts : 0
Exposure Time : 1/20
ISO : 400
CFA Pattern : [Blue,Green][Green,Red]
Image Size : 4056x3040
Megapixels : 12.3
Shutter Speed : 1/20
Notice that there is only one calibration illuminant (the one determined by the AWB algorithm – though it is always labelled as "D65"), and dividing the ISO number by 100 gives the analogue gain that was used.
Very Long Exposures
To capture a long‑exposure image, disable AEC/AGC and AWB, because these algorithms would cause the camera to wait many frames for convergence.
Disable them by providing explicit values. Also, use the --immediate option to skip the preview phase entirely.
Thus, to perform a 100‑second exposure capture:
rpicam-still -o long_exposure.jpg --shutter 100000000 --gain 1 --awbgains 1,1 --immediate
For reference, the maximum exposure times for the three official Raspberry Pi camera modules can be found in the table below.
rpicam-vid
rpicam-vid helps you capture video on a Raspberry Pi device. rpicam-vid displays a preview window and writes the encoded bitstream to the specified output. This produces an un‑packaged video bitstream, not wrapped in any container format (such as an MP4 file).
By default, rpicam-vid uses H.264 encoding.
For example, the following command writes a 10‑second video to a file named test.h264:
rpicam-vid -t 10s -o test.h264
You can play the resulting file with VLC or other video players:
VLC test.h264
On Raspberry Pi 5, you can output directly to MP4 container format by specifying the MP4 file extension for the output file:
rpicam-vid -t 10s -o test.mp4
Encoders
rpicam-vid also supports Motion JPEG and uncompressed, unformatted YUV420:
rpicam-vid -t 10000 --codec mjpeg -o test.mjpeg
rpicam-vid -t 10000 --codec yuv420 -o test.data
The codec option determines the output format, not the output file extension.
The segment option splits the output file into chunks of a given size (in milliseconds). By specifying a very short segment (1 ms), you can break a Motion JPEG stream into individual JPEG files. For example, the following command combines 1 ms segments with a counter in the output filename, generating a new filename for each segment:
rpicam-vid -t 10000 --codec mjpeg --segment 1 -o test%05d.jpeg
Capturing High‑Frame‑Rate Video
To minimise frame drops for high‑frame‑rate (> 60 fps) video, try the following configuration tweaks:
Set the H.264 target level to 4.2 using --level 4.2.
Disable software colour denoising by setting the denoise option to cdn_off.
Disable the preview window with nopreview to free up some additional CPU cycles.
Set force_turbo=1 in /boot/firmware/config.txt to ensure the CPU clock does not throttle during video capture. For more information, see the force_turbo documentation.
Adjust the ISP output resolution parameters to --width 1280 --height 720 or lower to achieve the frame‑rate target.
On Raspberry Pi 4, you can overclock the GPU by adding gpu_freq=550 or higher to /boot/firmware/config.txt to improve performance. For more details, see the overclocking documentation.
The following command demonstrates how to capture 1280×720 video at 120 fps:
rpicam-vid --level 4.2 --framerate 120 --width 1280 --height 720 --save-pts timestamp.pts -o video.264 -t 10000 --denoise cdn_off -n
Integration with Libav
rpicam-vid can use the ffmpeg/libav codec backend to encode audio and video streams. You can save these streams to a file, or stream them over the network.
To enable the libav backend, pass libav to the codec option:
rpicam-vid --codec libav --libav-format avi --libav-audio --output example.avi
UDP
To stream video over UDP using the Raspberry Pi as a server, use the following command, replacing the <ip-addr> placeholder with the IP address of the client (or a multicast address) and the <port> placeholder with the port you want to use for streaming:
rpicam-vid -t 0 --inline -o udp://<ip-addr>:<port>
To view the video stream via UDP using a Raspberry Pi as the client, use the following command, replacing the <port> placeholder with the port you want to use for streaming:
vlc udp://@:<port> :demux=h264
Alternatively, use the following command on the client to stream using ffplay:
ffplay udp://<ip-addr-of-server>:<port> -fflags nobuffer -flags low_delay -framedrop
TCP
You can also transmit video over TCP. Use a Raspberry Pi as the server:
rpicam-vid -t 0 --inline --listen -o tcp://0.0.0.0:<port>
Use the Raspberry Pi as the client to view the video stream over TCP, use the following command:
vlc tcp/h264://<ip-addr-of-server>:<port>
Alternatively, on the client side, use the following command to stream with ffplay at 30 frames per second:
ffplay tcp://<ip-addr-of-server>:<port> -vf "setpts=N/30" -fflags nobuffer -flags low_delay -framedrop
RTSP
To stream video over RTSP with VLC, using the Raspberry Pi as the server, use the following command:
rpicam-vid -t 0 --inline -o - | cvlc stream:///dev/stdin --sout '#rtp{sdp=rtsp://:8554/stream1}' :demux=h264
To view the video stream on the RTSP using the Raspberry Pi as a client, use the following command:
ffplay rtsp://<ip-addr-of-server>:8554/stream1 -vf "setpts=N/30" -fflags nobuffer -flags low_delay -framedrop
Or use the following command to stream with VLC on the client:
vlc rtsp://<ip-addr-of-server>:8554/stream1
If you want to close the preview window on the server, use the nopreview command.
The inline flag forces stream header information into every intra‑frame, which helps clients understand the stream even if they missed the beginning.
rpicam-raw
rpicam-raw records video directly from the sensor as raw Bayer frames. It doesn't show the preview window. To record a 2-second raw clip to a file named test.raw, run the following command:
rpicam-raw -t 2000 -o test.raw
rpicam-raw outputs raw frames with no formatting information. The application prints the pixel format and image dimensions to the terminal window to help users parse the pixel data.
By default, rpicam-raw outputs all raw frames into a single, possibly very large, file. Use the segment option to direct each raw frame to a separate file, using the %05d directive to make each frame filename unique:
rpicam-raw -t 2000 --segment 1 -o test%05d.raw
With fast storage devices, rpicam-raw can write 18 MB HQ camera frames (12 megapixels) to disk at 10 fps. rpicam-raw cannot format the output frames as DNG files; for that, use rpicam-still with a frame‑rate lower than 10 to avoid dropped frames:
rpicam-raw -t 5000 --width 4056 --height 3040 -o test.raw --framerate 8
For more information on raw formats, see the mode documentation.
rpicam-detect
Note: The Raspberry Pi OS does not include rpicam-detect. If you have installed TensorFlow Lite, you can build rpicam-detect. For more information, see the rpicam-apps build instructions. Don't forget to pass -DENABLE_TFLITE=1 when running cmake.
rpicam-detect displays a preview window and monitors the content using the Google MobileNet v1 SSD (Single Shot Detector) neural network, which has been trained to recognize about 80 classes of objects using the Coco dataset. rpicam-detect can recognize people, cars, cats, and many other objects.
Whenever rpicam-detect detects the target object, it captures a full‑resolution JPEG Then return to monitoring preview mode.
For general information on using models, refer to the TensorFlow Lite Object Detector section. For example, to monitor your cat while you are away:
rpicam-detect -t 0 -o cat%04d.jpg --lores-width 400 --lores-height 300 --post-process-file object_detect_tf.json --object cat
rpicam Command Options
--help -h prints all options along with a brief description of each.
rpicam-hello -h
--version outputs the version strings of libcamera and rpicam-apps.
rpicam-hello --version
Example output:
rpicam-apps build: ca559f46a97a 27-09-2021 (14:10:24)
libcamera build: v0.0.0+3058-c29143f7
--list-cameras lists the cameras connected to the Raspberry Pi and their available sensor modes.
rpicam-hello --list-cameras
Sensor mode identifiers have the following form:
S<Bayer order><Bit-depth>*<Optional packing> : <Resolution list>
Crops are specified in native sensor pixels (even in pixel‑binning modes) as (<x>, <y>) / <Width> × <Height>. (x, y) defines where in the sensor array the crop window of size width × height is located.
For example, the following output shows information for an IMX219 sensor (index 0) and an IMX477 sensor (index 1):
Available cameras
---
0 : imx219 [3280x2464] (/base/soc/i2c0mux/i2c@1/imx219@10)
Modes: 'SRGGB10_CSI2P' : 640x480 [206.65 fps - (1000, 752)/1280x960 crop]
1640x1232 [41.85 fps - (0, 0)/3280x2464 crop]
1920x1080 [47.57 fps - (680, 692)/1920x1080 crop]
3280x2464 [21.19 fps - (0, 0)/3280x2464 crop]
'SRGGB8' : 640x480 [206.65 fps - (1000, 752)/1280x960 crop]
1640x1232 [41.85 fps - (0, 0)/3280x2464 crop]
1920x1080 [47.57 fps - (680, 692)/1920x1080 crop]
3280x2464 [21.19 fps - (0, 0)/3280x2464 crop]
1 : imx477 [4056x3040] (/base/soc/i2c0mux/i2c@1/imx477@1a)
Modes: 'SRGGB10_CSI2P' : 1332x990 [120.05 fps - (696, 528)/2664x1980 crop]
'SRGGB12_CSI2P' : 2028x1080 [50.03 fps - (0, 440)/4056x2160 crop]
2028x1520 [40.01 fps - (0, 0)/4056x3040 crop]
4056x3040 [10.00 fps - (0, 0)/4056x3040 crop]
--camera selects the camera to use. Specify an index from the list of available cameras.
rpicam-hello --list-cameras 0
rpicam-hello --list-cameras 1
--config -c specifies a file containing command‑line options and values. Typically, it is a file named example_configuration.txt where options and values are specified as key-value pairs, one option per line.
timeout=99000
verbose=
Note: Omit the prefix -- normally used in command‑line options. For flags that take no value, such as verbose in the example above, the trailing = must be included.
Then you can run the following command to specify a timeout of 99,000 milliseconds and detailed output:
rpicam-hello --config example_configuration.txt
--time -t defaults to a delay of 5000 milliseconds..
rpicam-hello -t
Specifies how long the application should run before exiting. This applies to both the video recording and preview windows. When capturing a still image, the application displays a preview window for the specified number of milliseconds before capturing the output image.
rpicam-hello -t 0
--preview sets the position (x,y coordinates) and size (w,h dimensions) of the desktop or DRM preview window. This does not affect the resolution or aspect ratio of the image requested from the camera.
Pass the preview window dimensions as a comma‑separated list: x,y,w,h.
rpicam-hello --preview 100,100,500,500
--fullscreen -f forces the preview window to use the entire screen, with no borders or title bars. The image is scaled to fit the whole screen. Takes no value.
rpicam-hello -f
--qt-preview uses the Qt preview window, which consumes more resources than other options, but supports X window forwarding. Not compatible with the fullscreen flag. Takes no value.
rpicam-hello --qt-preview
--nopreview prevents the application from displaying a preview window. Takes no value.
rpicam-hello --nopreview
--info-text
Default: "#%frame (%fps fps) exp %exp ag %ag dg %dg"
When running in a desktop environment, set the provided string as the title of the preview window. The following image metadata substitutions are supported: | Directive | Description |
| %frame | Frame sequence number |
| %fps | Instantaneous frame rate |
| %exp | Shutter speed used to capture the image, in ms |
| %ag | Image analog gain controlled by the sensor chip |
| %dg | Image digital gain controlled by the ISP |
| %rg | Gain of the red component of each pixel point
| %bg | Gain of the blue component of each pixel point
| %focus | The corner point measure of the image, the larger the value, the clearer the image
|%lp | Diopter of the current lens (distance in 1/meter)
|%afstate | Autofocus status (idle, scanning, focused, failed)
rpicam-hello --info-test "Focus measure: %focus"
--width
--height
Each accepts a single number defining the dimensions (in pixels) of the captured image.
For rpicam-still, rpicam-jpeg, and rpicam-vid, specify the output resolution.
For rpicam-raw, specify the original frame resolution. For a camera with a 2×2 bin readout mode, specify a resolution that is equal to or less than the bin mode to capture 2×2 bin original frames.
For rpicam-hello, there is no effect.
Record a 1080p video
rpicam-vid -o test.h264 --width 1920 --height 1080
To capture a 2028×1520 resolution JPEG. If used with an HQ camera, the 2×2 bin mode is used, so the original file (test. ng) contains 2028×1520 original Bayer images.
rpicam-still -r -o test.jpg --width 2028 --height 1520
--viewfinder-width
--viewfinder-height
Each parameter accepts a number that defines the size of the image displayed in the preview window in pixels. The size of the preview window is not affected, as the image is resized to fit. Captured still images or videos are not affected.
rpicam-still --viewfinder-width 1920 --viewfinder-height 1080
--mode allows specifying a camera mode in the following colon‑separated format: <width>:<height>:<bit-depth>:<packing>. If the provided values do not match exactly, the system will select the closest available option for the sensor. Packing can be packed (P) or unpacked (U), which affects the format of stored video and still images but does not affect the format of frames delivered to the preview window.
Bit-depth and packing are optional. The default bit‑depth is 12, and the default packing is P (packed).
For information on the bit depth, resolution, and packing options available for the sensors, please refer to list-cameras.
Examples:
4056:3040:12:P - 4056×3040 resolution, 12 bits/pixel, packed.
1632:1224:10 - 1632×1224 resolution, 10 bits/pixel.
2592:1944:10:U - 2592×1944 resolution, 10 bits/pixel, unpacked.
3264:2448 - 3264×2448 resolution.
--viewfinder-mode is the same as the mode option, but applies to the data delivered to the preview window. For more information, see the mode documentation.
--lores-width and --lores-height
provide a second, low‑resolution image stream from the camera, scaled down to the specified dimensions. Each accepts a number defining the dimensions (in pixels) of the low‑resolution stream. Can be used in preview and video modes. Not available for still captures. For rpicam‑vid, disables additional color denoising processing. Useful for image analysis in combination with image post‑processing.
rpicam-hello --lores-width 224 --lores-height 224
--hflip flips the image horizontally. Takes no value.
rpicam-hello --hflip -t 0
--vflip flips the image vertically. Takes no value.
rpicam-hello --vflip -t 0
--rotation rotates the image extracted from the sensor. Only accepts the value 0 or 180.
rpicam-hello --rotation 0
--roi crops the image extracted from the whole sensor area. Accepts four decimal values in the range 0 to 1, in the following format: <x>, <y>, <w>, <h>. Each of these values represents the percentage of available width and height as a decimal between 0 and 1.
These values define the following ratios:
<x>: Amount of X coordinate to skip before extracting the image
<y>: Amount of Y coordinate to skip before extracting the image
<w>: Width of the image to extract
<h>: Height of the image to extract
The default is 0,0,1,1 (starting with the first X coordinate and the first Y coordinate, using 100% of the image width and 100% of the image height).
Example:
rpicam-hello --roi 0.25,0.25,0.5,0.5 selects half of the total pixels cropped from the center of the image (skip the first 25% of X coordinates, skip the first 25% of Y coordinates, use 50% of the total image width, use 50% of the total image height).
rpicam-hello --roi 0,0,0.25,0.25 selects a quarter of the total pixels cropped from the top‑left corner of the image (skip 0% of X coordinates, skip 0% of Y coordinates, use 25% of the image width, use 25% of the image height).
--hdr default: off. Run the camera in HDR mode. If no value is passed, auto is assumed. Accepts one of the following values:
off - disables HDR.
auto - enables HDR on supported devices. Use the sensor's built‑in HDR mode if available. If the sensor does not have a built-in HDR mode, use the onboard HDR mode (if available).
single-exp enables HDR on supported devices. Use the sensor's built‑in HDR mode if available. If the sensor does not have a built-in HDR mode, use the onboard HDR mode (if available).
rpicam-hello --hdr
Use the onboard HDR mode, if available, even if the sensor has a built-in HDR mode. If the onboard HDR mode is not available, HDR is disabled.
Raspberry Pi 5 and higher versions of devices have the onboard HDR mode.
To check the HDR mode built into the sensor, add this option to the list of cameras.
Camera Control Options
The following options control the image processing and algorithms that affect the image quality of the camera.
sharpness
sets the image sharpness. Accepts a numeric value within the following range:
0.0 applies no sharpening.
Values greater than 0.0 but less than 1.0 apply less sharpening than the default.
1.0 applies the default amount of sharpening.
Values greater than 1.0 apply extra sharpening.
rpicam-hello --sharpness 0.0
contrast
specifies the image contrast. Accepts a numeric value within the following range:
0.0 applies minimum contrast.
Values greater than 0.0 but less than 1.0 apply less contrast than the default.
1.0 applies the default contrast.
Values greater than 1.0 apply extra contrast.
rpicam-hello --contrast 0.0
brightness
Specifies the image brightness, which is added as an offset of all pixels in the output image. Accepts a numeric value within the following range:
-1.0 applies minimum brightness (black).
0.0 applies standard brightness.
1.0 applies maximum brightness (white).
For more usage, ev is recommended.
rpicam-hello --brightness 1.0
saturation
Specifies the image color saturation. Accepts a numeric value within the following range:
0.0 applies minimum saturation (grayscale).
Values greater than 0.0 but less than 1.0 apply less saturation than the default.
1.0 applies the default saturation.
Values greater than 1.0 apply extra saturation.
rpicam-hello --saturation 0.6
ev
Specify the exposure value (EV) compensation for the image. Accepts a numeric value that controls the target value passed to the auto‑exposure/gain control (AEC/AGC) processing algorithm along the following spectrum:
-10.0 applies the minimum target value.
0.0 applies standard target value.
10.0 applies the maximum target value.
rpicam-hello --ev 10.0
shutter
Specifies the exposure time using the shutter, measured in microseconds. When you use this option, the gain can still be varied. If the frame rate at which the camera is running is too fast to allow the specified exposure time (e.g., frame rate of 1 fps, exposure time of 10000 µs), the sensor will use the maximum exposure time allowed by the frame rate.
For a list of minimum and maximum shutter times for the official Raspberry Pi cameras, refer to the camera hardware documentation. Values higher than the maximum will result in undefined behavior.
rpicam-hello --shutter 10000
gain
analoggain has the same effect as gain.
Sets the combined analog and digital gain. When the sensor drive can provide the required gain, only analog gain is used. When the analog gain reaches its maximum, the ISP applies the digital gain.
Accepts a numeric value.
For a list of analog gain limits for the official cameras, refer to the camera hardware documentation.
Sometimes, digital gain can exceed 1.0 even when the analogue gain limit is not exceeded. This can happen in the following cases:
Any of the color gains is below 1.0, which will cause the digital gain to settle at 1.0 / min(red gain, blue gain). This applies total digital gain to any color channel above 1.0 to avoid color artifacts.
Slight variations when the auto‑exposure/gain control (AEC/AGC) changes.
rpicam-hello --gain 0.8
metering default: centre.
Sets the metering mode of the Automatic Exposure/Gain Control (AEC/AGC) algorithm. Accepts the following values:
centre - center-weighted metering
spot - spot metering
average - average or full-frame metering
custom - custom metering mode defined in the camera tuning file
For more information on defining custom metering modes and adjusting region weights in existing metering modes, refer to the Raspberry Pi Camera and libcamera Tuning Guide.
rpicam-hello --metering centre
exposure
Sets the exposure profile. Changing the exposure profile should not affect the image exposure. Instead, different modes adjust gain settings to achieve the same net result. Accepts the following values:
sport: short exposure time, high gain
normal: normal exposure, normal gain
long: long exposure time, low gain
You can edit exposure profiles using tuning files. For more information, refer to the Raspberry Pi Camera and libcamera Tuning Guide.
rpicam-hello --exposure sport
awb
Sets the exposure profile. Changing the exposure profile should not affect the image exposure. Instead, different modes adjust gain settings to achieve the same final result. Accepts the following values. Available white balance modes:
Mode Color Temperature
auto 2500K ~ 8000K
incadescent 2500K ~ 3000K
tungsten 3000K ~3500K
fluorescent 4000K ~ 4700K
indoor 3000K ~ 5000K
daylight 5500K ~ 6500 K
cloudy 7000K ~ 8500K
custom: The custom range defined in the tuning file.
These values are approximate: values may vary depending on the camera tuning.
No mode completely disables AWB. Instead, you can fix colour gains with awbgains.
For more information about AWB modes, including how to define custom modes, refer to the Raspberry Pi Camera and libcamera Tuning Guide.
rpicam-hello --awb auto
awbgains
Sets a fixed red and blue gain value to be used instead of an Auto White Balance (AWB) algorithm. Setting non‑zero values disables AWB. Accepts a comma‑separated numeric input in the format: <red_gain>, <blue_gain>.
rpicam-jpeg -o test.jpg --awbgains 1.5,2.0
denoise
Default: auto
Sets the denoising mode. Accepts the following values:
auto: Enables standard spatial denoising. Uses extra-fast colour denoise for video, and high-quality colour denoise for images. Enables no extra colour denoise in the preview window.
off: Disables spatial and colour denoising.
cdn_off: Disables color noise reduction.
cdn_fast: Uses fast color denoising.
cdn_hq: Uses high‑quality color denoising. Not appropriate for video/viewfinder due to reduced throughput.
Even fast colour denoise can lower framerates. High quality colour denoise significantly lowers framerates.
rpicam-hello --denoise off
tuning-file
Specifies the camera tuning file. The tuning file allows you to control many aspects of image processing, including the Automatic Exposure/Gain Control (AEC/AGC), Auto White Balance (AWB), colour shading correction, colour processing, denoising and more. Accepts a tuning file path as input. For details on tuning files, see the Tuning Files section.
autofocus-mode
Default: default specifies the autofocus mode. Accepts the following values:
default: Puts the camera in continuous autofocus mode, unless the lens position or autofocus capture overrides to manual mode.
manual: Does not move the lens unless the lens position is configured manually.
auto: Moves the lens for an autofocus scan only on camera startup or before capture, if autofocus capture is also used.
continuous: Adjusts the lens position automatically as the scene changes.
This option is only supported for certain camera modules.
rpicam-hello --autofocus-mode auto
autofocus-range
Default: normal
Specifies the autofocus range. Accepts the following values:
normal: Focus range fairly close to infinity.
macro: Focus only on nearby objects, including the closest focal distance supported by the camera.
full: Focus over the entire range, from the closest object to infinity.
This option is only supported for certain camera modules.
rpicam-hello autofocus-range normal
autofocus-speed
Default: normal
Specifies the autofocus speed. Accepts the following values:
normal: Changes the lens position at normal speed.
fast: Changes the lens position quickly.
This option is only supported for certain camera modules.
rpicam-hello --autofocus-speed normal
autofocus-window
Specifies the autofocus window within the full field of the sensor. Accepts four decimal values in the range 0 to 1, in the following format: <x>, <y>, <w>, <h>. Each of these values represents the percentage of available width and height as a decimal between 0 and 1.
These values define the following ratios:
<x>: Amount of X coordinate to skip before applying autofocus.
<y>: Amount of Y coordinate to skip before applying autofocus.
<w>: Width of the autofocus area.
<h>: Height of the autofocus area.
The default uses the middle third of the output image in both dimensions (1/9 of the total image area).
Example:
rpicam-hello—autofocus-window 0.25,0.25,0.5,0.5
selects half of the total pixels cropped from the center of the image (skip the first 25% of X coordinates, skip the first 25% of Y coordinates, use 50% of the total image width, use 50% of the total image height).
rpicam-hello—autofocus-window 0,0,0.25,0.25
selects a quarter of the total pixels cropped from the top‑left corner of the image (skip 0% of X coordinates, skip 0% of Y coordinates, use 25% of the image width, use 25% of the image height).
This option is only supported for certain camera modules.
lens-position
Default: default moves the lens to a fixed focal distance, usually expressed in diopters (units of 1/meter distance). Accepts the following range of values:
0.0: Moves the lens to the "infinity" position.
Any other number: Moves the lens to the 1 / number position. For example, the value 2.0 would focus at approximately 0.5m
normal: Moves the lens to a default position corresponding to the lens hyperfocal distance.
Lens calibration is imperfect, so different camera modules of the same model may vary.
verbose
Alias: -v
Default: 1 sets the verbosity level. Accepts the following values:
0: No output
1: Normal output
2: Verbose output
rpicam-hello --verbose 1
For more detailed information, refer to the Raspberry Pi official documentation.