Player Service API

Overview

The player service provides audio playback functionality and supports playing audio data from various sources such as arrays, VFS (Virtual File System), and URLs. It also supports different audio decoders for various audio formats.

For developer guide about the player service, please refer to:
- Player Service Developer Guide
For example projects of the player service, please refer to:
- Player Service Example Project

API Reference

Header File

bk_player_service.h

Functions

bk_player_handle_t bk_player_create(bk_player_cfg_t *cfg)

Create a player handle. Supports creating a player that plays directly. For configuration, please refer to DEFAULT_PLAYER_WITH_PLAYBACK_CONFIG(). Supports creating a player that does not play directly. The decoded PCM data can be output to other components for playback. For configuration, please refer to DEFAULT_PLAYER_NOT_PLAYBACK_CONFIG().

Parameters

cfg – [in] The player configuration.

Returns

The player handle.

Not NULL: Success.
NULL: Failed.

bk_err_t bk_player_destroy(bk_player_handle_t player_handle)

Destroy a player handle.

Parameters

player_handle – [in] The player handle.

Returns

Error code.

0: Success.
Non-zero: Failed.

bk_err_t bk_player_start(bk_player_handle_t player_handle)

Start a player.

Parameters

player_handle – [in] The player handle.

Returns

Error code.

0: Success.
Non-zero: Failed.

bk_err_t bk_player_stop(bk_player_handle_t player_handle)

Stop a player.

Parameters

player_handle – [in] The player handle.

Returns

Error code.

0: Success.
Non-zero: Failed.

bk_err_t bk_player_set_uri(bk_player_handle_t player_handle, player_uri_info_t *uri_info)

Set the URI of a player.

Parameters

player_handle – [in] The player handle.
uri_info – [in] The uri information

Returns

Error code.

0: Success.
Non-zero: Failed.

bk_err_t bk_player_get_state(bk_player_handle_t player_handle, bk_player_state_t *state)

Get the state of a player.

Parameters

player_handle – [in] The player handle.
state – [out] The pointer to store the player state.

Returns

Error code.

0: Success.
Non-zero: Failed.

bk_err_t bk_player_set_decode_type(bk_player_handle_t player_handle, audio_dec_type_t dec_type)

Set the decode type of a player.

Parameters

player_handle – [in] The player handle.
dec_type – [in] The decode type.

Returns

Error code.

0: Success.
Non-zero: Failed.

bk_err_t bk_player_set_output_port(bk_player_handle_t player_handle, audio_port_handle_t port)

Set the output port of a player. Use this interface to set the output port when the created player is not playing data. Do not use this interface to set the output port when the player is playing data.

Parameters

player_handle – [in] The player handle.
port – [in] The output port handle.
port_type – [in] The output port type.

Returns

Error code.

0: Success.
Non-zero: Failed.

API Typedefs

Header File

bk_player_service_types.h

Structures

struct player_uri_info_t

Player URI information structure.

This structure defines the URI information for audio playback.

Public Members

player_uri_type_t uri_type: URI type

char *uri: URI string

uint32_t total_len: Total length of audio data

struct bk_player_cfg_t

Player service configuration structure.

This structure defines the complete configuration for the player service, including speaker settings and event handling.

Public Members

spk_type_t spk_type: Speaker type

onboard_speaker_stream_cfg_t onboard_spk_cfg: Onboard speaker configuration

uac_speaker_stream_cfg_t uac_spk_cfg: USB audio class speaker configuration

uint8_t reserve: Reserved for future use

union bk_player_cfg_t::[anonymous] spk_cfg: Speaker configuration union

player_event_handle_cb event_handle: Player event handle callback function

void *args: User defined arguments for the event handle function

Macros

DEFAULT_PLAYER_NOT_PLAYBACK_CONFIG()

Default player configuration without playback.

This configuration creates a player that reads and decodes audio data to PCM data, but does not play back the PCM data.

DEFAULT_PLAYER_WITH_PLAYBACK_CONFIG()

Default player configuration with playback.

This configuration creates a player that reads, decodes and plays back audio data using the onboard speaker with default settings.

Type Definitions

typedef struct player *bk_player_handle_t

Player handle type.

This typedef defines a pointer to the player service structure.

typedef int (*player_event_handle_cb)(int event, void *data, void *args)

Player event handler callback type.

This typedef defines the function pointer type for handling player service events.

Param event: Event type
Param data: Event data
Param args: User defined arguments
Return: int Returns 0 on success, other values indicate error

Enumerations

enum bk_player_state_t

Generic Player Service Types.

This file defines the common data types, enumerations, and structures used by the player service module. These types are used to configure and control player service operations including playing audio data from various sources.

Player service state enumeration

This enumeration defines the operational states of the player service.

Values:

enumerator PLAYER_STATE_NONE: Player service is in an undefined state

enumerator PLAYER_STATE_IDLE: Player service is initialized but not active

enumerator PLAYER_STATE_STOPED: Player service has been stopped

enumerator PLAYER_STATE_PLAYING: Player service is actively playing audio

enumerator PLAYER_STATE_PAUSED: Player service is paused

enum bk_player_event_t

Player service event enumeration.

This enumeration defines the events that can be generated by the player service.

Values:

enumerator PLAYER_EVENT_START: Player service start event

enumerator PLAYER_EVENT_STOP: Player service stop event

enumerator PLAYER_EVENT_FAILURE: Player service failure event

enumerator PLAYER_EVENT_PAUSE: Player service pause event

enumerator PLAYER_EVENT_RESUME: Player service resume event

enumerator PLAYER_EVENT_FINISH: Player service finish event

enumerator PLAYER_EVENT_MUSIC_INFO: Player service music information event

enum player_uri_type_t

Player URI type enumeration.

This enumeration defines the types of audio sources supported by the player service.

Values:

enumerator PLAYER_URI_TYPE_ARRAY: Array stream source type

enumerator PLAYER_URI_TYPE_VFS: VFS (Virtual File System) source type

enumerator PLAYER_URI_TYPE_URL: URL source type