Video

The Video widget is designed for video display and playback. It supports various video formats and data sources (Memory, File System, and FTL Storage), and provides a comprehensive set of APIs for playback control.

Usage

Video Formats

The Video widget supports the MJPEG, AVI, and H264 formats. The characteristics of each format are described below:

Comparison of Different Video Formats
Type	Resource	Audio	Transparency	Decoding Cost	Frame Skipping	Encoding	Decoder
MJPEG	Small	❌	❌	Low	✔️	JPEG	HW(RTL8773G)/SW
AVI	Slightly larger than MJPEG	✔️	❌	Low	✔️	JPEG	HW(RTL8773G)/SW
H264	Very Small	❌	❌	High	❌	H264	SW

Video File Resource Size

The file size of a video resource is influenced by multiple factors, including duration, frame rate, resolution, scene complexity, and the presence of audio. Higher scene complexity-characterized by high-frequency content with significant changes or detailed textures-typically results in larger exported file sizes. During video conversion, appropriate quality parameters can be configured to balance the trade-off between storage space and image quality. Exported AVI files can be previewed using standard media players on PC platforms.

Video Resource Conversion

Use the conversion tool to generate video formats compatible with HoneyGUI:

The tool supports importing common video formats as well as image sequences.

Identical quality parameter settings are not equivalent across different export formats.

For detailed instructions on video resource conversion, please refer to the conversion tool documentation.

Access Methods

The Video widget supports various resource access methods:

Direct Mapping: Reads directly from memory addresses (e.g., RAM/PSRAM, NOR Flash XIP).
File System: Reads via file system interfaces (e.g., LittleFS).
Buffered Access: Reads from storage addresses via a buffer (e.g., NAND Flash).

When creating a Video widget, the appropriate creation API must be selected based on the specific resource access method.

Video Creation API
Type	Creation API
Direct Mapping	`gui_video_create_from_mem()`
File System	`gui_video_create_from_fs()`
Buffered Access	`gui_video_create_from_ftl()`

Playback Control

Playback State

Use the function gui_video_set_state() to set the video playback state. Supported states include Playing (GUI_VIDEO_STATE_PLAYING), Paused (GUI_VIDEO_STATE_PAUSE), and Stopped (GUI_VIDEO_STATE_STOP).

If the video is set to Playing (GUI_VIDEO_STATE_PLAYING) while in the Stopped state (GUI_VIDEO_STATE_STOP), playback will restart from the first frame.

Repeat Playback

Use the function gui_video_set_repeat_count() to set the number of times the video repeats. For example, setting the repeat count to 1 results in the video playing twice (initial play + 1 repeat).

Set the count to GUI_VIDEO_REPEAT_INFINITE or a negative value to enable infinite looping.

Frame Rate Settings

The Video widget uses the frame rate defined in the resource file as the initial playback rate. Since MJPEG files do not contain frame rate information, a default of 25 fps is used. AVI and H264 files include frame rate information.

Use the function gui_video_set_frame_rate() to set the playback frame rate, which will override the original frame rate setting.

Use the function gui_video_get_frame_time() to retrieve the actual frame interval time.

Step Settings

For video formats that support frame skipping, use the function gui_video_set_frame_step() to set the playback frame step. This achieves a fast-forward effect. Reverse playback is not supported.

Use the function gui_video_get_frame_step() to retrieve the current playback step of the video widget.

UI Transformations

Scaling

Use the function gui_video_set_scale() to set the scaling parameters for the video display, allowing adjustment of the video aspect ratio.

Example

The following code snippet demonstrates how to create a Video widget, configure the frame rate, control playback, register interaction events, and adjust playback speed.

static void video_click_cb(void *obj)
{
    gui_video_t *this = (gui_video_t *)obj;
    GUI_VIDEO_STATE state = gui_video_get_state(this);
    if (state == GUI_VIDEO_STATE_PLAYING)
    {
        gui_video_set_state(this, GUI_VIDEO_STATE_PAUSE);
    }
    else
    {
        gui_video_set_state(this, GUI_VIDEO_STATE_PLAYING);
    }

}


static void video_pressing_cb(void *obj)
{
    gui_video_t *this = (gui_video_t *)obj;
    static uint32_t cnt = 0;
    uint32_t frame_time = gui_video_get_frame_time(this);

    if (frame_time > 30)
    {
        cnt = 0;
        gui_video_set_frame_rate(this, 50.f);
    }
    else if (frame_time > 15)
    {
        cnt++;
        if (cnt >= 80)
        {
            cnt = 80;
            gui_video_set_frame_step(this, 2);
        }
    }

}

static void video_release_cb(void *obj)
{
    gui_video_t *this = (gui_video_t *)obj;

    gui_video_set_frame_rate(this, 30.f);
    gui_video_set_frame_step(this, 1);
}

static int app_init(void)
{
#ifdef _HONEYGUI_SIMULATOR_
    unsigned char *resource_root = (unsigned char *)_binary_earth_420_410_502_40_lq_mjpg_start;
#else
    unsigned char *resource_root = (unsigned char *)EARTH_420_410_502_40_LQ_MJPG;
#endif
    gui_log("GUI Video Widget Example Start\n");
    gui_video_t *video = gui_video_create_from_mem(gui_obj_get_root(), "earth",
                                                   (void *)resource_root,
                                                   0, 0, 410,
                                                   502);
    /* Set default frame rate to 30 FPS */
    gui_video_set_frame_rate(video, 30.f);
    gui_video_set_state(video, GUI_VIDEO_STATE_PLAYING);      // Set initial state to Playing
    gui_video_set_repeat_count(video, GUI_VIDEO_REPEAT_INFINITE); // Enable infinite loop

    /*
     * Register CLICK event callback.
     * Logic: Toggle between Play and Pause states.
     */
    gui_obj_add_event_cb(video,
                         (gui_event_cb_t)video_click_cb,
                         GUI_EVENT_TOUCH_CLICKED,
                         NULL);

    /*
     * Register PRESSING (Long Press) event callback.
     * Logic: Handle 2-stage Fast Forward:
     *   1. Initial long press: Increase frame rate (FPS) for smooth fast forward.
     *   2. Extended long press: Increase seek step for faster fast forward.
     */
    gui_obj_add_event_cb(video,
                         (gui_event_cb_t)video_pressing_cb,
                         GUI_EVENT_TOUCH_PRESSING,
                         NULL);

    /*
     * Register RELEASE event callback.
     * Logic: Restore initial playback settings (Default FPS and Step) when finger is lifted.
     */
    gui_obj_add_event_cb(video,
                         (gui_event_cb_t)video_release_cb,
                         GUI_EVENT_TOUCH_RELEASED,
                         NULL);

    return 0;
}
GUI_INIT_APP_EXPORT(app_init);

API

Defines

GUI_VIDEO_REPEAT_INFINITE 0xFFFFFFFF

IMG_LIVE_FPS (25)

Enums

enum GUI_VIDEO_EVENT

Values:

enumerator GUI_VIDEO_EVENT_FRAME_UPDATE

enumerator GUI_VIDEO_EVENT_PLAY

enumerator GUI_VIDEO_EVENT_PAUSE

enumerator GUI_VIDEO_EVENT_STOP

enumerator GUI_VIDEO_EVENT_END

enum GUI_VIDEO_STATE

Values:

enumerator GUI_VIDEO_STATE_ERR

enumerator GUI_VIDEO_STATE_INIT

enumerator GUI_VIDEO_STATE_PLAYING

enumerator GUI_VIDEO_STATE_PAUSE

enumerator GUI_VIDEO_STATE_STOP

enum GUI_VIDEO_RES

Values:

enumerator GUI_IMG_LIVE_SUCCESSED

enum VIDEO_MJPEG_SCAN_STATE

Values:

enumerator MJPEG_SCAN_INIT

enumerator MJPEG_SCAN_START

enumerator MJPEG_SCAN_END

enumerator MJPEG_SCAN_EOF

enum GUI_VIDEO_TYPE

Values:

enumerator VIDEO_TYPE_NULL

enumerator VIDEO_TYPE_MJPEG

enumerator VIDEO_TYPE_H264

enumerator VIDEO_TYPE_AVI

enum AVI_CHUNK_TYPE

Values:

enumerator CHUNK_VIDEO

enumerator CHUNK_AUDIO

enumerator CHUNK_UNKNOWN

Functions

int gui_video_get_filesize_from_addr(void *addr, uint8_t storage_type)

Retrieves the video file size from a memory address or FTL storage address.

Note

For file paths, please use the file system (FS) API to get the file size.
Supported video formats: mjpeg, avi, h264.

Parameters:

addr -- [in] The starting address of the video data.
- For IMG_SRC_MEMADDR: Pointer to the data in RAM or Flash.
- For IMG_SRC_FTL: Storage address or offset in Flash.
storage_type -- [in] The storage source type. Supported types: IMG_SRC_MEMADDR, IMG_SRC_FTL.

Returns:

int Returns the file size in bytes. Returns 0 or a negative value on failure.

void gui_video_set_frame_rate(gui_video_t *this, float fps)

uint32_t gui_video_get_frame_time(gui_video_t *this)

void gui_video_set_scale(gui_video_t *this, float scale_x, float scale_y)

void gui_video_set_state(gui_video_t *this, GUI_VIDEO_STATE state)

Set the playback state of a video widget.

Note

When set state Play at state Stop, widget will play from the beginning.

Parameters:

this -- Pointer to the video widget (must be valid).
state -- Target state, as defined by GUI_VIDEO_STATE (e.g., Play, Pause, Stop).

void gui_video_set_repeat_count(gui_video_t *this, int32_t cnt)

Set the repeat (loop) count for video playback.

Parameters:

this -- Pointer to the video widget (must be valid).
cnt -- Number of times to repeat playback after the first run:
- cnt > 0: Play the video cnt additional times (total plays = 1 + cnt).
- cnt = 0: Do not repeat (play once).
- GUI_VIDEO_REPEAT_INFINITE: Repeat indefinitely (infinite loop).

GUI_VIDEO_STATE gui_video_get_state(gui_video_t *this)

void gui_video_set_frame_step(gui_video_t *this, uint32_t step)

uint32_t gui_video_get_frame_step(gui_video_t *this)

void gui_video_refresh_size(gui_video_t *this)

void gui_video_refresh_type(gui_video_t *this)

gui_video_t *gui_video_create_from_ftl(void *parent, const char *name, void *addr, int16_t x, int16_t y, int16_t w, int16_t h)

Create a video widget from an FTL source(cannot be accessed directly) and attach it to a parent container.

Parameters:

parent -- Pointer to the parent GUI object (must be valid).
name -- Widget name/identifier.
addr -- Pointer to the FTL source handle or buffer.
x -- Top-left x position relative to the parent.
y -- Top-left y position relative to the parent.
w -- Width in pixels (will be overwritten by the video file).
h -- Height in pixels (will be overwritten by the video file).

Returns:

Pointer to gui_video_t on success; NULL on failure.

gui_video_t *gui_video_create_from_fs(void *parent, const char *name, void *addr, int16_t x, int16_t y, int16_t w, int16_t h)

Create a video widget from a file system and attach it to a parent container.

Parameters:

parent -- Pointer to the parent GUI object (must be valid).
name -- Widget name/identifier.
addr -- Pointer to the file path string.
x -- Top-left x position relative to the parent.
y -- Top-left y position relative to the parent.
w -- Width in pixels (will be overwritten by video file).
h -- Height in pixels (will be overwritten by video file).

Returns:

Pointer to gui_video_t on success; NULL on failure.

gui_video_t *gui_video_create_from_mem(void *parent, const char *name, void *addr, int16_t x, int16_t y, int16_t w, int16_t h)

Create a video widget from a memory buffer and attach it to a parent container.

Parameters:

parent -- Pointer to the parent GUI object (must be valid).
name -- Widget name/identifier.
addr -- Pointer to the memory buffer containing video data.
x -- Top-left x position relative to the parent.
y -- Top-left y position relative to the parent.
w -- Width in pixels (will be overwritten by video file).
h -- Height in pixels (will be overwritten by video file).

Returns:

Pointer to gui_video_t on success; NULL on failure.

struct gui_h264_header_t

Public Members

char symbol[4]

uint32_t w

uint32_t h

uint32_t frame_num

uint32_t frame_time

uint32_t size

struct gui_riff_header_t

Public Members

char symbol[4]

uint32_t size

char format[4]

struct MainAVIHeader_t

Public Members

uint32_t usec_per_frame

uint32_t max_byte_rate

uint32_t reserved_0

uint32_t flags

uint32_t total_frame

uint32_t initial_frame

uint32_t streams

uint32_t buffer_size

uint32_t width

uint32_t height

struct AVIStreamHeader_t

Public Members

char type[4]

uint32_t handler

uint32_t flags

uint32_t priority

uint32_t initial_frames

uint32_t scale

uint32_t rate

uint32_t start

uint32_t length

uint32_t buffer_size

uint32_t quality

uint32_t sample_size

uint16_t frame[4]

uint32_t stream_format

uint32_t length_format

struct BitMapInfoHeader_t

Public Members

uint32_t size

uint32_t width

uint32_t height

uint16_t planes

uint16_t bit_count

uint32_t compression

uint32_t image_size

uint32_t x_pels_per_meter

uint32_t y_pels_per_meter

uint32_t colors_used

uint32_t colors_important

struct WaveFormateX_t

Public Members

uint16_t format_tag

uint16_t channels

uint32_t samples_per_sec

uint32_t ave_bytes_per_sec

uint16_t block_align

uint16_t bits_per_sample

uint16_t size_extra

struct IndexList_t

Public Members

uint32_t indexID

uint32_t index_size

struct IndexItem_t

Public Members

uint32_t chunk_ID

uint32_t flags

uint32_t offset

uint32_t size

struct AviMoviChunk_t

Public Members

uint32_t offset

uint32_t len

uint32_t type

struct gui_video_t

stb img widget information structure

Public Members

gui_obj_t base

gui_img_t *img

void *data

uint32_t num_frame

uint8_t **array

gui_rgb_data_head_t header

uint8_t *frame_buff

uint8_t *frame_buff_raw

void *decoder

uint32_t frame_time

uint32_t frame_step

int32_t frame_cur

int32_t frame_last

int32_t repeat_cnt

uint8_t img_type

uint8_t storage_type

uint8_t state

uint32_t frame_chunk_cur

uint32_t chunk_num

uint8_t rgb_type