Capturing Stills During Video Recording

Relevant source files

The following files were used as context for generating this wiki page:

• examples/still_during_video.py
• examples/switch_mode_2.py
• picamera2/picamera2.py
• picamera2/request.py
• apps/app_full.py
• CHANGELOG.md

The picamera2 library provides robust functionality for capturing high-resolution still images while a video preview or recording is in progress. This is not a simultaneous hardware operation; instead, it is achieved by intelligently and rapidly switching the camera's operational mode. The camera is momentarily paused from its video or preview state, reconfigured for a high-resolution still capture, the image is taken, and then the camera is switched back to its original video mode.

This process is managed through a series of helper methods that abstract away the complexity of mode switching, making it straightforward to implement. For more advanced use cases, developers can also perform these steps manually. The core of this feature revolves around the Picamera2 class methods that handle camera configuration and capture requests, such as switch_mode, capture_file, and capture_request.

Core Concept: Mode Switching

The fundamental principle behind capturing a still during video is mode switching. A camera sensor cannot typically provide a full-resolution still image and a high-framerate video stream at the same time. Therefore, the picamera2 library must perform a sequence of operations to accomplish this.

The general flow is as follows:

1. The camera is running in a "video" or "preview" configuration.
2. A request to capture a still image is made.
3. The Picamera2 instance stops the camera stream.
4. It reconfigures the camera using a "still" configuration, which typically specifies the full sensor resolution.
5. The camera is started, and a single frame (the still image) is captured.
6. The camera is stopped again.
7. It is reconfigured back to the original "video" or "preview" configuration.
8. The camera stream is restarted, resuming the video or preview.

This entire sequence is often wrapped in a single, convenient helper method.

Sources: picamera2/picamera2.py:1210-1215, picamera2/picamera2.py:1255-1277

The diagram below illustrates the state transitions involved in the mode-switching process.

High-Level API: switch_mode_and_capture_* Methods

The picamera2 library provides a set of high-level "helper" methods that encapsulate the entire mode-switching and capture process. These are the recommended methods for most users as they handle the sequence of operations automatically.

Sources: picamera2/picamera2.py:1255-1358

switch_mode_and_capture_file

This method is the most direct way to capture a still image to a file while a video stream is running. It handles switching to the still configuration, capturing the image, and switching back to the original configuration.

def switch_mode_and_capture_file(self, camera_config, file_output, name="main", format=None,
                                 wait=None, signal_function=None, exif_data=None, delay=0
                                 ) -> Union[dict[str, Any], Job[dict[str, Any]]]:

The delay parameter can be used to introduce a number of dropped frames after the mode switch to allow 3A algorithms to settle before the capture.

Sources: picamera2/picamera2.py:1255-1290

An example of its usage:

# From examples/still_during_video.py
picam2.start_encoder(encoder, "test.h264")
picam2.start()
time.sleep(2)

# It's better to capture the still in this way, as it forces the camera
# to capture a new frame.
still_config = picam2.create_still_configuration()
job = picam2.switch_mode_and_capture_file(still_config, "test.jpg", wait=False)
metadata = picam2.wait(job)

Sources: examples/still_during_video.py:15-22

switch_mode_and_capture_request

This method is similar to switch_mode_and_capture_file, but instead of saving to a file, it returns a CompletedRequest object. This is useful for applications that need to process the image data in memory (e.g., as a NumPy array) rather than saving it directly.

The docstring warns that frequent use of this method may increase CMA heap fragmentation. For applications that need to do this repeatedly, switch_mode_capture_request_and_stop might be a better alternative.

Sources: picamera2/picamera2.py:1292-1329, CHANGELOG.md:195-196

switch_mode_capture_request_and_stop

This variant switches to the capture mode, captures a CompletedRequest, and then stops the camera entirely without switching back. This allows the application to process the request and release it before restarting the camera in the desired mode, which can help manage memory more effectively.

Sources: picamera2/picamera2.py:1406-1438

Manual Mode Switching

For finer control over the capture process, developers can perform the mode switch manually using the switch_mode method. This involves explicitly calling switch_mode with a still configuration, performing the capture, and then calling switch_mode again with the original video configuration.

The following sequence diagram shows the manual process:

Practical Implementation: UI Example

The apps/app_full.py file provides a comprehensive example of how to manage still captures and video recording in a Qt-based GUI application.

The application uses a tabbed interface to switch between "Still Capture" and "Video" modes. When the user is in the video tab and recording, a still capture is not possible. To take a photo, the user must be in the "Still Capture" tab.

The core logic resides in the on_pic_button_clicked and capture_done functions:

1. on_pic_button_clicked: If a preview is running (meaning the camera is in a lower-resolution preview mode), it first calls switch_config("still") to change to the high-resolution still capture configuration. It then calls picam2.capture_request() to trigger the capture.
2. capture_done: This callback function is executed when the capture is complete. After saving the image, it checks if the application was in preview mode before the capture. If so, it calls switch_config("preview") to return the camera to its original state.

This demonstrates a robust, stateful implementation of capturing stills while a preview is active.

Sources: apps/app_full.py:189-198, apps/app_full.py:221-240

The following flowchart visualizes the logic for taking a photo in app_full.py.

Key API Components

The following table summarizes the key methods in the Picamera2 class related to this feature.

Method	Description	Key Parameters	Source
switch_mode	Switches the camera into another mode. This is a low-level building block.	camera_config	picamera2/picamera2.py:1236-1253
switch_mode_and_capture_file	Atomically switches mode, captures a frame to a file, and switches back.	camera_config, file_output, delay	picamera2/picamera2.py:1255-1290
switch_mode_and_capture_request	Atomically switches mode, captures a CompletedRequest object, and switches back.	camera_config, delay	picamera2/picamera2.py:1292-1329
switch_mode_capture_request_and_stop	Switches mode, captures a request, and then stops the camera.	camera_config	picamera2/picamera2.py:1406-1438
capture_file	Captures the next available frame to a file. Used after a manual mode switch.	file_output, name	picamera2/picamera2.py:1186-1208
capture_request	Fetches the next available CompletedRequest. Used after a manual mode switch.	wait, signal_function	picamera2/picamera2.py:1360-1404

Conclusion

Capturing a full-resolution still image while recording or previewing video is a powerful feature of the picamera2 library. It is accomplished through a well-orchestrated "stop-reconfigure-capture-reconfigure-start" sequence. For most applications, the high-level switch_mode_and_capture_file and switch_mode_and_capture_request methods provide a simple and effective solution. For developers needing more granular control over the process, the library exposes the underlying switch_mode and capture_* methods to allow for manual implementation of this workflow.