H264Decoder< Alloc > Class Template Reference

Template class for decoding H.264 streams to raw video frames. More...

#include <H264Decoder.h>

Classes
struct	Config
	Configuration structure for H.264 decoder and output settings. More...

Public Member Functions
Config	defaultConfig ()
	Create a default configuration with reasonable defaults.
	H264Decoder (Stream &input_stream)
	Constructor with input stream.
	H264Decoder ()
	Default constructor (no input stream)
	~H264Decoder ()
	Destructor.
void	setInputStream (Stream *input_stream)
	Set input stream for H.264 data.
bool	begin (Config cfg)
	Initialize H.264 decoder and allocate buffers.
bool	processStream ()
	Process H.264 data from configured input stream.
bool	decode (const uint8_t *h264_data, size_t h264_len)
	Decode H.264 data from buffer.
bool	hasFrame () const
	Check if a decoded frame is available.
bool	getFrame (uint8_t *dst, size_t dst_len, uint32_t &width, uint32_t &height)
	Retrieve decoded frame data.
uint32_t	getFrameCount () const
	Get total number of successfully decoded frames.
uint32_t	getDecodeErrors () const
	Get total number of decode errors.
bool	getFrameDimensions (uint32_t &width, uint32_t &height) const
	Get current frame dimensions.
void	end ()
	Cleanup and release decoder resources.

Static Public Attributes
static constexpr const char *	TAG = "H264Decoder"
	Logging tag for ESP32 log system.

Detailed Description

template<typename Alloc = H264_DEFAULT_ALLOCATOR>
class esp_h264::H264Decoder< Alloc >

Template class for decoding H.264 streams to raw video frames.

H264Decoder is a lightweight, header-only class that wraps H.264 decoder initialization, stream processing, and output format conversions (I420 → RGB565/other formats).

The class is templated on an allocator type to allow customization of memory allocation strategy (e.g., PSRAM vs regular heap).

Template Parameters

Alloc

Memory allocator type for internal buffers (defaults to PSRAMAllocatorH264)

Note

This class intentionally keeps implementation in the header for easy integration into Arduino sketches without separate .cpp files

The decoder supports constrained baseline H.264 profile

Requires ESP32 with sufficient memory for frame buffers

Example usage:

#include "H264Decoder.h"
#include <WiFiUdp.h>
 
WiFiUDP udp;
H264DecoderPSRAM decoder(&udp);  // Uses PSRAM allocation (simpler than H264Decoder<>)
 
void setup() {
  auto cfg = decoder.defaultConfig();
  cfg.output_format = ESP_H264_RAW_FMT_RGB565_LE;
  cfg.frame_callback = [](const uint8_t* frame, uint32_t w, uint32_t h, esp_h264_raw_format_t fmt) {
    // Process decoded frame (e.g., display on TFT)
    tft.drawFrame(frame, w, h);
  };
  
  udp.begin(5000);
  if (!decoder.begin(cfg)) {
    Serial.println("Failed to start decoder");
  }
}
 
void loop() {
  decoder.processStream();  // Reads from UDP and decodes
}

Constructor & Destructor Documentation

H264Decoder() [1/2]

H264Decoder ( Stream &  input_stream )

inlineexplicit

Constructor with input stream.

Creates a H264Decoder that reads H.264 data from the specified stream. The stream can be UDP, TCP, Serial, or any other Stream implementation.

Parameters

input_stream

Pointer to Stream object for H.264 input data

Note

The stream must remain valid for the lifetime of the decoder

Call begin() to initialize decoder resources

H264Decoder() [2/2]

H264Decoder ( )

inline

Default constructor (no input stream)

Creates a H264Decoder without an input stream. Use decode() method to process H.264 data directly from buffers.

Note

Call begin() to initialize decoder resources

Use setInputStream() to assign a stream later if needed

~H264Decoder()

~H264Decoder ( )

inline

Destructor.

Automatically releases decoder and buffer resources by calling end().

Note

Safe to destroy without calling end() explicitly

Member Function Documentation

begin()

bool begin ( Config  cfg )

inline

Initialize H.264 decoder and allocate buffers.

Configures and initializes the H.264 software decoder with specified output format and allocates internal buffers using the configured allocator.

Parameters

cfg	Configuration structure (passed by value to allow temporary objects)

Returns

true if initialization succeeded, false on any failure

Note

Decoder is configured for constrained baseline H.264 profile

Buffers are allocated using the template allocator (Alloc)

On failure, any partially initialized resources are cleaned up

decode()

bool decode ( const uint8_t *  h264_data, size_t  h264_len  )

inline

Decode H.264 data from buffer.

Processes H.264 encoded data directly from a memory buffer. Handles NAL unit parsing, decoding, and output frame generation.

Parameters

h264_data	Pointer to H.264 encoded data buffer
h264_len	Size of H.264 data in bytes

Returns

true if decoding succeeded, false on error

Note

Input data should contain complete NAL units when possible

Decoder handles partial NAL units and reassembly internally

Decoded frames trigger frame_callback if configured

This method can be used without an input stream

defaultConfig()

Config defaultConfig ( )

inline

Create a default configuration with reasonable defaults.

Returns a Config structure populated with default values suitable for typical H.264 decoding scenarios. Output format defaults to I420.

Returns

Config Default configuration structure

Note

Input and output buffer sizes are set for VGA resolution

Frame callback is nullptr - set manually for real-time processing

end()

void end ( )

inline

Cleanup and release decoder resources.

Deinitializes the H.264 decoder and releases all allocated resources. Should be called when decoding is complete or when switching decoder configurations.

Note

Safe to call multiple times

Required before calling begin() with different Config

Automatically called by destructor

getDecodeErrors()

uint32_t getDecodeErrors ( ) const

inline

Get total number of decode errors.

Returns

Number of decode errors since begin() was called

Note

Counter is reset when begin() is called

Useful for monitoring stream quality and decoder health

getFrame()

bool getFrame ( uint8_t *  dst, size_t  dst_len, uint32_t &  width, uint32_t &  height  )

inline

Retrieve decoded frame data.

Copies the most recently decoded frame to the provided buffer. Frame dimensions and format are returned via reference parameters.

Parameters

dst	Destination buffer for frame data
dst_len	Size of destination buffer in bytes
width	Reference to store frame width in pixels
height	Reference to store frame height in pixels

Returns

true if frame copied successfully, false on error or no frame

Note

Buffer must be large enough for the frame data

Frame availability is reset after successful retrieval

Frame format matches Config::output_format setting

getFrameCount()

uint32_t getFrameCount ( ) const

inline

Get total number of successfully decoded frames.

Returns

Number of frames decoded since begin() was called

Note

Counter is reset when begin() is called

Useful for monitoring decoder performance

getFrameDimensions()

bool getFrameDimensions ( uint32_t &  width, uint32_t &  height  ) const

inline

Get current frame dimensions.

Parameters

width	Reference to store frame width in pixels
height	Reference to store frame height in pixels

Returns

true if valid dimensions available, false if no frame decoded yet

Note

Dimensions are available after the first successful frame decode

Dimensions may change if stream resolution changes

hasFrame()

bool hasFrame ( ) const

inline

Check if a decoded frame is available.

Returns

true if a decoded frame is ready for retrieval, false otherwise

Note

Frame availability is reset after calling getFrame()

This method is useful for polling-based frame processing

processStream()

bool processStream ( )

inline

Process H.264 data from configured input stream.

Reads available H.264 data from the input stream (if configured) and processes it through the decoder. Automatically handles NAL unit parsing and frame assembly.

Returns

true if stream processing succeeded, false on error or no stream

Note

Returns false if no input stream is configured

Amount of data read per call is limited by Config::max_read_bytes

Decoded frames trigger frame_callback if configured

Use this method in loop() for continuous stream processing

setInputStream()

void setInputStream ( Stream *  input_stream )

inline

Set input stream for H.264 data.

Assigns or changes the input stream used by processStream() method.

Parameters

input_stream

Pointer to Stream object for H.264 input data

Note

The stream must remain valid for the lifetime of the decoder

Can be called at any time to change input source

Member Data Documentation

TAG

constexpr const char* TAG = "H264Decoder"

staticconstexpr

Logging tag for ESP32 log system.

---

The documentation for this class was generated from the following file:

• src/H264Decoder.h