Video Player API

[中文]

Overview

This section describes the Video Player APIs and core data structures. The player supports container parsing (AVI/MP4) and stream decoding (e.g. MJPEG/H264 video and PCM/AAC audio), depending on enabled parsers/decoders.

• For detailed information about Video Player, please refer to:

  • Video File Playback Guide

• For Video Player example projects, please refer to:

  • Video Player Example Project

Related headers

• ap/include/components/bk_video_player/bk_video_player_engine.h

• ap/include/components/bk_video_player/bk_video_player_playlist.h

• ap/include/components/bk_video_player/bk_video_player_types.h

API Reference (Engine)

1. bk_video_player_engine_new

Create a new player engine instance.

avdk_err_t bk_video_player_engine_new(bk_video_player_engine_handle_t *handle, bk_video_player_config_t *config);

• Parameters: - handle: [out] engine handle - config: [in] player configuration (callbacks, buffers, output format, etc.)

• Return: - AVDK_ERR_OK: success - others: failure

2. bk_video_player_engine_delete

Delete the engine instance and release resources.

avdk_err_t bk_video_player_engine_delete(bk_video_player_engine_handle_t handle);

3. bk_video_player_engine_open / bk_video_player_engine_close

Open/close the engine.

avdk_err_t bk_video_player_engine_open(bk_video_player_engine_handle_t handle);
avdk_err_t bk_video_player_engine_close(bk_video_player_engine_handle_t handle);

4. bk_video_player_engine_set_file_path

Set media file path (must be called before play).

avdk_err_t bk_video_player_engine_set_file_path(bk_video_player_engine_handle_t handle, const char *file_path);

5. bk_video_player_engine_play / bk_video_player_engine_stop

Start/stop playback.

avdk_err_t bk_video_player_engine_play(bk_video_player_engine_handle_t handle);
avdk_err_t bk_video_player_engine_stop(bk_video_player_engine_handle_t handle);

6. bk_video_player_engine_set_pause

Set pause state.

avdk_err_t bk_video_player_engine_set_pause(bk_video_player_engine_handle_t handle, bool pause);

7. bk_video_player_engine_seek

Seek to a specific time position (milliseconds).

avdk_err_t bk_video_player_engine_seek(bk_video_player_engine_handle_t handle, uint64_t time_ms);

8. bk_video_player_engine_fast_forward / bk_video_player_engine_rewind

Fast forward / rewind by the specified time (milliseconds).

avdk_err_t bk_video_player_engine_fast_forward(bk_video_player_engine_handle_t handle, uint32_t time_ms);
avdk_err_t bk_video_player_engine_rewind(bk_video_player_engine_handle_t handle, uint32_t time_ms);

9. bk_video_player_engine_play_file

Play a file from the beginning (best-effort stop -> set_file_path -> play).

avdk_err_t bk_video_player_engine_play_file(bk_video_player_engine_handle_t handle, const char *file_path);

10. bk_video_player_engine_set_volume / volume_up / volume_down

Set/adjust audio volume (0-100).

avdk_err_t bk_video_player_engine_set_volume(bk_video_player_engine_handle_t handle, uint8_t volume);
avdk_err_t bk_video_player_engine_volume_up(bk_video_player_engine_handle_t handle, uint8_t step);
avdk_err_t bk_video_player_engine_volume_down(bk_video_player_engine_handle_t handle, uint8_t step);

Note

Volume APIs require bk_video_player_config_t.audio.audio_set_volume_cb. If not provided, they return an unsupported error.

11. bk_video_player_engine_set_mute

Set mute state.

avdk_err_t bk_video_player_engine_set_mute(bk_video_player_engine_handle_t handle, bool mute);

12. bk_video_player_engine_register_* (decoder/parser registration)

Register audio decoder, video decoder, and container parser.

avdk_err_t bk_video_player_engine_register_audio_decoder(bk_video_player_engine_handle_t handle,
                                                         const video_player_audio_decoder_ops_t *decoder_ops);
avdk_err_t bk_video_player_engine_register_video_decoder(bk_video_player_engine_handle_t handle,
                                                         video_player_video_decoder_ops_t *decoder_ops);
avdk_err_t bk_video_player_engine_register_container_parser(bk_video_player_engine_handle_t handle,
                                                            video_player_container_parser_ops_t *parser_ops);

13. bk_video_player_engine_get_current_time / get_status / get_media_info

Query current playback time, playback status, and media information.

avdk_err_t bk_video_player_engine_get_current_time(bk_video_player_engine_handle_t handle, uint64_t *time_ms);
avdk_err_t bk_video_player_engine_get_status(bk_video_player_engine_handle_t handle, video_player_status_t *status);
avdk_err_t bk_video_player_engine_get_media_info(bk_video_player_engine_handle_t handle,
                                                 const char *file_path,
                                                 video_player_media_info_t *media_info);

Note

If file_path is NULL, get_media_info queries the currently opened (cached) file info.

Important

File probing/parsing in get_media_info depends on registered container parsers (register_container_parser). Without parsers registered, the player cannot select a parser to open and parse the file.

API Reference (Playlist)

Playlist APIs provide playlist management and track switching. Typical APIs include (see headers for prototypes):

• Create/delete: bk_video_player_playlist_new / bk_video_player_playlist_delete

• Open/close: bk_video_player_playlist_open / bk_video_player_playlist_close

• Playlist management: add_file / remove_file / clear / get_file_count / get_current_file

• Playback control: play_file / stop / set_pause / seek / fast_forward / rewind

• Navigation/strategy: play_next / play_prev / play_at_index / set_play_mode

• Volume/mute: set_volume / volume_up / volume_down / set_mute

• Decoder/parser registration: register_audio_decoder / register_video_decoder / register_container_parser

• Status queries: get_current_time / get_status / get_media_info

Play mode (Playlist)

The playlist provides a play mode to define what to do when playback reaches end of file (EOF):

typedef enum
{
    BK_VIDEO_PLAYER_PLAYLIST_PLAY_MODE_STOP = 0, // Stop playback (default)
    BK_VIDEO_PLAYER_PLAYLIST_PLAY_MODE_REPEAT,   // Repeat current file
    BK_VIDEO_PLAYER_PLAYLIST_PLAY_MODE_LOOP,     // Loop playlist (wrap to first when reaching the end)
} bk_video_player_playlist_play_mode_t;

avdk_err_t bk_video_player_playlist_set_play_mode(bk_video_player_playlist_handle_t handle,
                                                  bk_video_player_playlist_play_mode_t mode);

Type definitions (excerpt)

1. video_player_status_t

typedef enum
{
    VIDEO_PLAYER_STATUS_NONE = 0,
    VIDEO_PLAYER_STATUS_OPENED,
    VIDEO_PLAYER_STATUS_CLOSED,
    VIDEO_PLAYER_STATUS_PLAYING,
    VIDEO_PLAYER_STATUS_PAUSED,
    VIDEO_PLAYER_STATUS_STOPPED,
    VIDEO_PLAYER_STATUS_FINISHED,
} video_player_status_t;

2. video_player_media_info_t

typedef struct
{
    video_player_video_params_t video;
    video_player_audio_params_t audio;
    uint64_t duration_ms;
    uint64_t file_size_bytes;
} video_player_media_info_t;

3. bk_video_player_config_t

The player configuration structure that contains audio/video buffer configurations and callbacks. Upper-layer callbacks should return quickly to avoid blocking the pipeline.