Video Recording (H.264, MP4)

Relevant source files

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

• apps/app_full.py
• picamera2/picamera2.py
• picamera2/encoders/h264_encoder.py
• picamera2/encoders/libav_h264_encoder.py
• picamera2/outputs/ffmpeg_output.py
• picamera2/outputs/pyavoutput.py
• tests/quality_check.py
• CHANGELOG.md

The picamera2 library provides a flexible and powerful framework for video recording. It decouples camera configuration, video encoding, and file output, allowing developers to easily record raw H.264 streams or containerized video files like MP4. This is achieved through a modular system of Encoder and Output classes that work in conjunction with the main Picamera2 object.

The core components involved in video recording are:

• Picamera2: The main camera class that manages configuration and the recording lifecycle.
• Encoder: A class responsible for compressing video frames into a specific format (e.g., H.264). The library provides multiple H.264 encoder implementations.
• Output: A class that handles writing the encoded data to a destination, such as a file or a network stream. Different outputs are used for raw streams (.h264) versus container formats (.mp4).

Core Components and Architecture

The video recording architecture separates concerns, allowing for flexible combinations of encoders and outputs.

This diagram illustrates the relationship between the main classes involved in video recording.

Picamera2 Class Methods

The Picamera2 class provides high-level and low-level methods to control video recording.

• create_video_configuration(): Creates a default camera configuration suitable for video recording. This typically sets a resolution like 1280x720, a format like XBGR8888, and a noise reduction mode optimized for speed.
  Sources: picamera2/picamera2.py:1130-1166
• start_recording(encoder, output, ...): A high-level convenience function that configures the camera (if needed), starts the encoder, and begins the recording process.
  Sources: picamera2/picamera2.py:1620-1635
• stop_recording(): Stops the camera and the encoder, finalizing the output file.
  Sources: picamera2/picamera2.py:1637-1640
• start_encoder(encoder, output, ...): A lower-level method that starts an encoder with a given output. The camera must be started separately. This allows for more complex scenarios, such as running multiple encoders.
  Sources: picamera2/picamera2.py:1568-1603
• stop_encoder(encoders): Stops one or more specified encoders.
  Sources: picamera2/picamera2.py:1605-1618

Encoders

Encoders are responsible for compressing raw video frames. picamera2 offers several options for H.264 encoding.

H264Encoder

This is the primary hardware-accelerated H.264 encoder, inheriting from V4L2Encoder. It leverages the Video4Linux2 (V4L2) interface to access the Raspberry Pi's hardware video encoder.

Parameter	Type	Description
bitrate	int	The target bitrate for the encoded video.
repeat	bool	If True, repeats the SPS/PPS sequence headers for every keyframe. Defaults to True.
iperiod	int	The interval between I-frames (keyframes).
qp	int	Sets a fixed Quantization Parameter (1-51), disabling constant bitrate mode.
profile	str	Sets the H.264 profile (e.g., "baseline", "main", "high").

Sources: picamera2/encoders/h264_encoder.py:22-37

LibavH264Encoder

This encoder uses the libav library (from FFmpeg) for encoding, which typically runs on the CPU. On VC4 platforms (like Raspberry Pi 4), it can be configured to use the V4L2 hardware encoder. This encoder was added on Pi 5.

Parameter	Type	Description
bitrate	int	The target bitrate for the encoded video.
iperiod	int	The interval between I-frames (keyframes). Defaults to 30.
framerate	int	The target framerate. Defaults to 30.
qp	int	Sets a fixed Quantization Parameter.
profile	str	Sets the H.264 profile.
use_hw	bool	If True on a VC4 platform, it will use the V4L2 hardware encoder via libav.

Sources: picamera2/encoders/libav_h264_encoder.py:16-41, CHANGELOG.md:149, CHANGELOG.md:111

Outputs and Containers

Output classes receive encoded frames from an encoder and write them to a destination.

• FileOutput: The simplest output class. It writes the raw encoded byte stream directly to a file. This is suitable for creating .h264 files.
  Sources: apps/app_full.py:161-163
• FfmpegOutput: This output is used to create standard video container formats like MP4, MKV, and AVI. It works by piping the encoded stream to an external ffmpeg process, which handles the muxing (container creation). It also supports muxing an audio stream.
  Sources: apps/app_full.py:157-159, picamera2/picamera2.py:1718-1721
• PyavOutput: An alternative for creating container files. It uses the PyAV library (Python bindings for libav) to perform muxing directly within the Python process, avoiding the need for an external ffmpeg process. This can be more efficient and provides better control over timestamps.
  Sources: picamera2/outputs/pyavoutput.py

Quality Control

The picamera2.encoders.Quality enum provides a simple way to control the trade-off between file size and visual quality.

class Quality(Enum):
    VERY_LOW = 1
    LOW = 2
    MEDIUM = 3
    HIGH = 4
    VERY_HIGH = 5

When a Quality level is passed to start_encoder or start_recording, the encoder's _setup method translates it into a concrete bitrate or qp value. For example, H264Encoder uses a lookup table to determine the bitrate based on resolution and framerate.

H264Encoder Quality to Bitrate Mapping (for 1080p30):

Quality	Bitrate (Mbps)
Quality.VERY_LOW	2
Quality.LOW	4
Quality.MEDIUM	6
Quality.HIGH	9
Quality.VERY_HIGH	15

Sources: picamera2/encoders/h264_encoder.py:87-95, tests/quality_check.py:10

Recording Workflow

The following diagram illustrates the sequence of operations for a typical video recording session that produces an MP4 file.

Practical Examples

Example 1: Recording a Raw H.264 Stream

This example shows how to record a simple .h264 video file for 5 seconds. It uses the hardware-accelerated H264Encoder and the basic FileOutput.

import time
from picamera2 import Picamera2
from picamera2.encoders import H264Encoder
from picamera2.outputs import FileOutput

picam2 = Picamera2()
video_config = picam2.create_video_configuration()
picam2.configure(video_config)

encoder = H264Encoder(bitrate=10000000)
output = FileOutput("test.h264")

picam2.start_recording(encoder, output)
time.sleep(5)
picam2.stop_recording()

Sources: picamera2/picamera2.py:1620-1640, apps/app_full.py:161-163

Example 2: Recording an MP4 File

This example demonstrates how to create an MP4 file. It uses FfmpegOutput to handle the container muxing. The ffmpeg command-line tool must be installed for this to work.

import time
from picamera2 import Picamera2
from picamera2.encoders import H264Encoder
from picamera2.outputs import FfmpegOutput

picam2 = Picamera2()
video_config = picam2.create_video_configuration()
picam2.configure(video_config)

encoder = H264Encoder(bitrate=10000000)
# For MP4, FfmpegOutput is used.
output = FfmpegOutput("test.mp4")

picam2.start_recording(encoder, output)
time.sleep(5)
picam2.stop_recording()

Sources: apps/app_full.py:156-159, picamera2/picamera2.py:1620-1640

Summary

The picamera2 library offers a robust and modular system for video recording. By combining different Encoder and Output classes, developers can easily capture video in various formats, from raw H.264 streams to fully containerized MP4 files. The high-level start_recording API simplifies common use cases, while the lower-level start_encoder API provides the flexibility needed for more advanced applications, such as streaming or multi-file output. The choice between the hardware-accelerated H264Encoder and the software-based LibavH264Encoder allows for optimization based on the specific Raspberry Pi platform and performance requirements.