esp-idf/examples/peripherals/h264/README.md

Supported Targets	ESP32-P4	ESP32-S3

H.264 Encoder-Decoder Example

Overview

This example demonstrates how to use H.264 hardware/software encoder and decoder with visual pattern generation:

• Generate colorful test patterns for video processing
• Encode video frames using H.264 codec (hardware on ESP32-P4, software on ESP32-S3)
• Decode the encoded frames back to original format using software decoder
• Display visual comparison between source and decoded images

The example supports multiple YUV formats and provides side-by-side colorized display in the console. All encoding parameters are configurable through the ESP-IDF menuconfig system.

Configuration

This example provides comprehensive configuration options through idf.py menuconfig:

H.264 Encoder Type Selection

• Hardware Encoder: Available only on ESP32-P4, provides better performance and lower power consumption
• Software Encoder: Available on all targets (ESP32-S3, ESP32-P4), uses more CPU resources

Configurable Parameters

All parameters can be adjusted in "H.264 Example Configuration" menu:

• Video Width: 64-1920 pixels (default: 320)
• Video Height: 64-1080 pixels (default: 240)
• Frame Rate: 1-60 fps (default: 30 for hardware, 15 for software)
• Bitrate: 64K-10M bps (default: 512K for hardware, 256K for software)
• GOP Size: 1-255 frames (default: 30)
• QP Value: 10-51 (default: 26 for hardware, 28 for software)

Target-Specific Defaults

• ESP32-P4: Optimized for hardware encoding with higher performance settings
• ESP32-S3: Optimized for software encoding with conservative settings

How to use example

Prerequisites Required

This example requires:

• ESP32-P4 development board (for hardware encoding) or ESP32-S3 development board (for software encoding)
• USB cable for programming and power supply
• Terminal that supports ANSI color codes for proper visual output

Configure the Example

Before building, configure the example parameters:

idf.py menuconfig

Navigate to: Component config → H.264 Example Configuration

1. Select Encoder Type: Choose between Hardware (ESP32-P4 only) or Software encoder
2. Adjust Parameters: Configure video resolution, frame rate, bitrate, etc.
3. Save and Exit: Press 'S' to save configuration

Build and Flash

For ESP32-P4 (with hardware encoding support):

idf.py set-target esp32p4
idf.py menuconfig  # Configure as needed
idf.py build
idf.py -p PORT flash monitor

For ESP32-S3 (software encoding only):

idf.py set-target esp32s3
idf.py menuconfig  # Software encoder will be automatically selected
idf.py build
idf.py -p PORT flash monitor

(To exit the serial monitor, type Ctrl-].)

See the Getting Started Guide for full steps to configure and use ESP-IDF to build projects.

Example Output

I (1555) H264_ENC_DEC: H264 Example starting: 320x240 @ 30fps
I (1565) H264_ENC_DEC: Encoder: Hardware, Decoder: Software
I (1575) H264_ENC_DEC: Config: GOP=30, Bitrate=512000 bps, QP=26
I (1585) H264_DEC.SW: tinyh264 version: 1c7f584
I (1585) H264_ENC_DEC: H264 encode-decode loop started (320x240 @ 30fps)

Frame 0: source image             |            decoded image
[Colorized bar patterns displayed side by side using ANSI colors]

Frame 1: source image             |            decoded image
[Colorized bar patterns displayed side by side using ANSI colors]

Frame 2: source image             |            decoded image
[Colorized bar patterns displayed side by side using ANSI colors]
...

I (21465) H264_ENC_DEC: H264 process Completed successfully
I (21475) main_task: Returned from app_main()

Note: The exact values shown will depend on your menuconfig settings.

Video Format Support

• ESP_H264_RAW_FMT_I420: Planar YUV 4:2:0 format (decoder output, software encoder input)
• ESP_H264_RAW_FMT_O_UYY_E_VYY: Interlaced YUV format (hardware encoder input on ESP32-P4)

Performance Recommendations

For ESP32-P4 (Hardware Encoding):

• Resolution: Up to 1920x1080 supported
• Frame Rate: 30-60 fps achievable
• Bitrate: 512K-5M bps recommended
• QP: 20-30 for optimal quality/performance balance

For ESP32-S3 (Software Encoding):

• Resolution: 320x240 or smaller recommended
• Frame Rate: 10-15 fps for stable performance
• Bitrate: 256K-1M bps recommended
• QP: 28-35 for better performance

Troubleshooting

Configuration Issues:

• Use idf.py menuconfig to verify H.264 settings before building
• Ensure hardware encoder is only selected for ESP32-P4 target

Memory allocation failures:

• Reduce resolution or frame rate in menuconfig
• Ensure sufficient SPIRAM is available
• Check ESP-IDF memory configuration

Encoding/decoding errors:

• Verify the correct target is selected (ESP32-P4 for hardware)
• Check that H.264 component is properly configured in menuconfig
• Adjust bitrate settings for your resolution/frame rate combination

Performance Issues:

• Lower resolution, frame rate, or bitrate for software encoding
• Use hardware encoder on ESP32-P4 for better performance
• Increase QP value to reduce computational load

Visual output issues:

• Ensure your terminal supports ANSI color codes
• Try different terminal applications if colors don't display properly

(For any technical queries, please open an issue on GitHub. We will get back to you as soon as possible.)