Note

This is the documentation for the latest development branch and may refer to features that are not available in released versions. If you are looking for the documentation for a specific release, use the drop-down menu on the left and select the desired version.

MJPEGEncoder Module API Manual

Overview

MJPEGEncoder uses the K230 VENC hardware encoder to encode a frame of image.Image, py_video_frame, or py_video_frame_info into JPEG byte data. This interface is suitable for snapshot saving, HTTP MJPEG video streaming, and applications that require per-frame JPEG data.

The recommended way to import is:

from media.mjpeg import MJPEGEncoder

The encoder allocates VENC channels and VB buffers on the first call to encode(), and automatically reconfigures when the input size or pixel format changes. Call close() after use to release hardware resources.

Quick Start

The following example directly encodes video frames output by the Sensor, avoiding extra image copying:

from media.mjpeg import MJPEGEncoder
from media.sensor import Sensor

sensor = Sensor()
encoder = None

try:
    sensor.reset()
    sensor.set_framesize(width=1920, height=1080, alignment=12)
    sensor.set_pixformat(Sensor.YUV420SP)
    sensor.run()

    encoder = MJPEGEncoder(quality=50)
    frame = sensor.snapshot(dump_frame=True)
    jpeg = encoder.encode(frame, timeout_ms=1000)

    with open("/sdcard/snapshot.jpg", "wb") as file:
        file.write(jpeg)
finally:
    if encoder is not None:
        encoder.close()
    sensor.stop()

alignment=12 means the Sensor aligns each image plane to \(2^{12}=4096\) bytes. The physical address of the VENC input plane must satisfy this requirement, especially at resolutions such as 1920×1080 where the image plane size is not a multiple of 4096.

API Reference

MJPEGEncoder()

Creates an MJPEG encoder object. The VENC channel is not occupied during construction; hardware resources are created on demand during the first encoding.

encoder = MJPEGEncoder(quality=90)

Parameter	Type	Default	Description
quality	int	90	JPEG encoding quality, ranging from 1 to 99; larger values typically produce higher image quality and larger output data size

A ValueError is raised when quality is outside the valid range.

MJPEGEncoder.encode()

Encodes a frame of image into complete JPEG file data.

jpeg = encoder.encode(input, timeout_ms=1000)

Parameter	Type	Default	Description
input	image.Image, py_video_frame, or py_video_frame_info	None	The image or video frame to be encoded
timeout_ms	int	1000	Timeout for VENC sending frame and retrieving encoded stream, in milliseconds; -1 means blocking wait

Return Value

Returns a bytes object containing a single complete JPEG image, which can be directly written to a .jpg file, sent via socket, or embedded into an HTTP MJPEG multipart data stream.

Supported image.Image Formats

Image Format	Pre-encoding Processing
BINARY, GRAYSCALE, RGB565	Convert to RGB888 planar format
RGB888, BGR888, RGBP888, BGRP888	Convert or arrange to RGB888 planar format
ARGB8888, ABGR8888, RGBA8888, BGRA8888	Arrange in the 32-bit pixel order supported by VENC
YUV422, YVU422	Arrange to YUYV 4:2:2 packed format
YUV420, YVU420	Arrange to 4:2:0 semi-planar format

The image.Image input is copied to the encoder’s internal page-aligned VB buffer. This approach is universal, but introduces additional memory bandwidth overhead during continuous encoding at high resolutions.

The following example encodes an image.Image:

import image

from media.mjpeg import MJPEGEncoder

img = image.Image("/sdcard/input.bmp")
encoder = MJPEGEncoder(quality=85)

try:
    jpeg = encoder.encode(img)
    with open("/sdcard/output.jpg", "wb") as file:
        file.write(jpeg)
finally:
    encoder.close()

Supported Video Frame Formats

Video frame input supports the following k_pixel_format:

• PIXEL_FORMAT_ARGB_8888

• PIXEL_FORMAT_ABGR_8888

• PIXEL_FORMAT_BGRA_8888

• PIXEL_FORMAT_BGR_888_PLANAR

• PIXEL_FORMAT_RGB_888_PLANAR

• PIXEL_FORMAT_YUV_SEMIPLANAR_420

• PIXEL_FORMAT_YVU_PLANAR_420

• PIXEL_FORMAT_YVU_SEMIPLANAR_420

• PIXEL_FORMAT_UYVY_PACKAGE_422

• PIXEL_FORMAT_YUYV_PACKAGE_422

Video frames must come from the VB buffer pool, and the physical address of each valid plane must be aligned to 4096 bytes. For Sensor output, use:

sensor.set_framesize(width=width, height=height, alignment=12)
frame = sensor.snapshot(dump_frame=True)

Encoding must complete before the frame is recycled by the Sensor. Typically, encoder.encode(frame) should be called immediately before obtaining the next frame.

MJPEGEncoder.close()

Stops and destroys the VENC channel, and releases the VB buffer pool created by the encoder.

encoder.close()

This method can be called repeatedly. After being closed, the object cannot be used again to perform encoding.

MJPEGEncoder.is_closed()

Returns whether the encoder has been closed.

closed = encoder.is_closed()

The return type is bool.

Read-only Properties

Property	Type	Description
quality	int	JPEG quality set when the encoder was constructed
width	int	Image width of the current VENC channel; 0 before the first encoding
height	int	Image height of the current VENC channel; 0 before the first encoding
chn	int	Automatically allocated VENC channel number; -1 when not initialized or after closing

Performance Recommendations

• For continuous Sensor capture, high-resolution, or high-frame-rate scenarios, prefer using the video frame returned by snapshot(dump_frame=True) to avoid full-frame copying from image.Image input.

• For multi-plane formats like 1920×1080, configure alignment=12; otherwise the encoder will reject physical addresses that are not aligned to 4096 bytes.

• quality affects JPEG size and network bandwidth. For web video streaming, start adjusting from quality=50.

• timeout_ms only controls VENC operations, not subsequent file writing or network sending time.

• A MJPEGEncoder object should only encode one frame at a time. The object serializes concurrent calls internally.

Exceptions

Exception	Common Cause
ValueError	Invalid quality or timeout parameters, unsupported input format, invalid image dimensions, video frame is not a VB buffer, or unaligned plane address
MemoryError	Unable to allocate memory for JPEG return data
RuntimeError	VENC channel, VB buffer pool, sending frame, or obtaining stream failure

After a VENC runtime error occurs, the encoder will clean up the current hardware resources. The next call to encode() will re-allocate hardware resources; the application can also call close() to end the task.