dfplayer.DFPlayer

class documentation

class DFPlayer: (source)

Constructor: DFPlayer(uart_id, busy_pin_id, timeout, timeout_feedback, ...)

Controller for the DFPlayer module.

⚠️ All async methods may raise a DFPlayerError on communication failure or on internal errors reported by the module.

Method	`__init__`	Construct a new DFPlayer object to control a DFPlayer module using UART communication.
Method	`available`	Get if the player is booted and ready to be interfaced with.
Async Method	`dac`	Enable or disable the internal DAC (enabled on DFPlayer boot).
Method	`deinit`	Turn off the DFPlayer connection.
Async Method	`eq`	Query or set an equalizer preset.
Async Method	`gain`	Set DAC output gain.
Method	`init`	Initialize the DFPlayer.
Async Method	`mode`	Query or set a playback mode.
Async Method	`next`	Play the next track.
Async Method	`num_files_device`	Query the number of files on a given storage device.
Async Method	`num_files_folder`	Query the number of files in a numeric folder.
Async Method	`num_folders`	Query the number of available folders.
Method	`off_done`	Remove one or all event handler(s) for completion of file playback.
Method	`off_eject`	Remove one or all event handler(s) for storage device ejection.
Method	`off_insert`	Remove one or all event handler(s) for storage device insertion.
Method	`off_ready`	Remove one or all event handler(s) for player / storage device readying.
Method	`on_done`	Register an event handler for completion of file playback.
Method	`on_eject`	Register an event handler for storage device ejection.
Method	`on_insert`	Register an event handler for storage device insertion.
Method	`on_ready`	Register an event handler for player / storage device readying.
Async Method	`pause`	Pause playback (can be resumed via `resume`).
Async Method	`play`	Start playback of a track or advert.
Async Method	`play_advert`	Alias of `play(DFPlayer.FOLDER_ADVERT, ...)`.
Async Method	`play_id`	Start playback via track's id.
Async Method	`play_mp3`	Alias of `play(DFPlayer.FOLDER_MP3, ...)`.
Async Method	`playing`	Fetch whether playback is in progress.
Async Method	`previous`	Play the previous track.
Async Method	`reset`	Resets (reboots) the player.
Async Method	`resume`	Resume playback.
Async Method	`send_cmd`	Send a raw command to the player.
Async Method	`send_query`	Send a raw query command to the player and return the responded value.
Async Method	`sleep`	Set the player into sleep mode.
Async Method	`source`	Set the playback source device.
Async Method	`standby`	Enable or disable the player's standby mode.
Async Method	`state`	Query playback state.
Async Method	`stop`	Stop playback.
Async Method	`stop_advert`	Stop playback of running advert, continuing regular track.
Async Method	`track_id`	Query the currently playing/internally selected track's id on a given storage device.
Async Method	`version`	Query the player's software version.
Async Method	`volume`	Query or set the player's volume.
Method	`wait_available`	Await DFPlayer availability (see `available`)
Async Method	`wake`	Wake the player from sleep mode.
Constant	`EQ_BASS`	Bass-heavy equalizer mode.
Constant	`EQ_CLASSIC`	Classic equalizer mode.
Constant	`EQ_FLAT`	Flat (default/balanced) equalizer mode.
Constant	`EQ_JAZZ`	Jazz equalizer mode.
Constant	`EQ_POP`	Pop equalizer mode.
Constant	`EQ_ROCK`	Rock equalizer mode.
Constant	`FOLDER_ADVERT`	'ADVERT' folder on the storage device.
Constant	`FOLDER_MP3`	'MP3' folder on the storage device.
Constant	`MODE_RANDOM_ALL`	Randomize through all tracks (includes adverts).
Constant	`MODE_REPEAT_ALL`	Repeat all tracks sequentially (includes adverts).
Constant	`MODE_REPEAT_FILE`	Repeat a single file.
Constant	`MODE_REPEAT_FOLDER`	Repeat all tracks of a numeric folder.
Constant	`MODE_SINGLE`	Play files once (default).
Constant	`STATE_PAUSED`	Playback halted, track can be resumed.
Constant	`STATE_PLAYING`	Playback in progress.
Constant	`STATE_STOPPED`	Playback halted, no track progress retained.
Instance Variable	`log_level`	Print additional communication information (expects `DFPlayer.LOG_`... constant).
Instance Variable	`retries`	How often to re-send a command on communication failure.
Instance Variable	`skip_ack`	Set of command bytes (see source) to not require/request command ACK for.
Instance Variable	`timeout`	Milliseconds allowed for the player to process and acknowledge (ACK) sent commands.
Instance Variable	`timeout_busy`	Milliseconds allowed between command ACK and busy pin activating (relevant commands only).
Instance Variable	`timeout_feedback`	Milliseconds allowed between command ACK and feedback (error/query value).
Method	`_bytes_to_uint16`	Undocumented
Async Method	`_exec_cmd`	Undocumented
Async Method	`_fetch_available`	Undocumented
Method	`_get_checksum`	Undocumented
Method	`_handle_event`	Undocumented
Method	`_off`	Undocumented
Method	`_on`	Undocumented
Async Method	`_read`	Undocumented
Async Method	`_read_loop`	Undocumented
Async Method	`_receive_message`	Undocumented
Method	`_require_lock`	Undocumented
Method	`_uint16_to_bytes`	Undocumented
Method	`_validate_read`	Undocumented
Instance Variable	`_buffer_read`	Undocumented
Instance Variable	`_buffer_send`	Undocumented
Instance Variable	`_busy_flag`	Undocumented
Instance Variable	`_busy_pin`	Undocumented
Instance Variable	`_error`	Undocumented
Instance Variable	`_events`	Undocumented
Instance Variable	`_init`	Undocumented
Instance Variable	`_last_mode`	Undocumented
Instance Variable	`_last_selected_device`	Undocumented
Instance Variable	`_lock`	Undocumented
Instance Variable	`_log`	Undocumented
Instance Variable	`_message_receive_done`	Undocumented
Instance Variable	`_message_receive_ready`	Undocumented
Instance Variable	`_read_task`	Undocumented
Instance Variable	`_stream`	Undocumented
Instance Variable	`_uart`	Undocumented

def __init__(self, uart_id: int, busy_pin_id: int|None = None, timeout=200, timeout_feedback=50, timeout_busy=300, retries=5, skip_ack: set[int] = _ALL_QUERIES, log_level=_LOG_NONE): (source) ¶

Construct a new DFPlayer object to control a DFPlayer module using UART communication.

Parameters
uart_id:`int`	Hardware UART id
busy_pin_id:`int\|None`	Optional pin id that is connected to the BUSY pin of the DFPlayer (uses up one interrupt slot)
timeout	Milliseconds allowed for the player to process and acknowledge (ACK) sent commands
timeout_feedback	Milliseconds allowed between command ACK and feedback (error/query value)
timeout_busy	Milliseconds allowed between command ACK and busy pin activating (relevant commands only)
retries	How often to re-send a command on communication failure
skip_ack:`set[int]`	Set of command bytes (see source) to not require/request command ACK for (by default excludes all queries as original DFPlayer will never ACK query commands)
log_level	Print additional communication information (expects `DFPlayer.LOG_`... constant)

def available(self) -> bool: (source) ¶

Get if the player is booted and ready to be interfaced with.

⚠️ The player may still not process commands if in standby or sleep mode.

async def dac(self, enable=True): (source) ¶

Enable or disable the internal DAC (enabled on DFPlayer boot).

def deinit(self): (source) ¶

Turn off the DFPlayer connection.

Turns off the underlying UART bus and frees an interrupt handler for the busy pin (if used).

async def eq(self, eq: int|None = None): (source) ¶

Query or set an equalizer preset.

Parameters
eq:`int\|None`	Set equalizer to one of the `DFPlayer.EQ_`... constants.

async def gain(self, gain: int): (source) ¶

Set DAC output gain.

Parameters
gain:`int`	Set gain to a value between 0-31 inclusive.

def init(self, **kwargs): (source) ¶

Initialize the DFPlayer.

Needs to be called before any commands can be sent or events can be received. Additional keyword-only parameters will be passed to UART.init of the underlying UART bus used for communicating with the player.

async def mode(self, mode: int|None = None, folder: int|None = None): (source) ¶

Query or set a playback mode.

⚠️ While DFPlayer.MODE_SINGLE and DFPlayer.MODE_REPEAT_FILE passively change the playback mode, the other modes will actively start playback.

⚠️ DFPlayer.MODE_REPEAT_ALL and DFPlayer.MODE_RANDOM_ALL will also consider adverts.

Parameters
mode:`int\|None`	Set mode to one of the `DFPlayer.MODE_`... constants.
folder:`int\|None`	Folder to repeat (only with `DFPlayer.MODE_REPEAT_FOLDER`).

async def next(self): (source) ¶

Play the next track.

async def num_files_device(self, device: int|None = None): (source) ¶

Query the number of files on a given storage device.

If no device is specified, the last active one known to this driver is queried.

Parameters
device:`int\|None`	`DFPlayer.DEVICE_`... constant to query.

async def num_files_folder(self, folder: int): (source) ¶

Query the number of files in a numeric folder.

Parameters
folder:`int`	Folder number to query.

async def num_folders(self): (source) ¶

Query the number of available folders.

def off_done(self, handler: Callable[[int, int]]|None = None): (source) ¶

Remove one or all event handler(s) for completion of file playback.

Parameters
handler:`Callable[[int, int]]\|None`	Handler to remove (all when `None`)

def off_eject(self, handler: Callable[[int]]|None = None): (source) ¶

Remove one or all event handler(s) for storage device ejection.

Parameters
handler:`Callable[[int]]\|None`	Handler to remove (all when `None`)

def off_insert(self, handler: Callable[[int]]|None = None): (source) ¶

Remove one or all event handler(s) for storage device insertion.

Parameters
handler:`Callable[[int]]\|None`	Handler to remove (all when `None`)

def off_ready(self, handler: Callable[[int]]|None = None): (source) ¶

Remove one or all event handler(s) for player / storage device readying.

Parameters
handler:`Callable[[int]]\|None`	Handler to remove (all when `None`)

def on_done(self, handler: Callable[[int, int]]): (source) ¶

⚠️ Some DFPlayer versions may not report this event for adverts or might report it multiple times in quick succession for any file type.

Parameters
handler:`Callable[[int, int]]`	Takes integer parameters: `(device, track_id)`

def on_eject(self, handler: Callable[[int]]): (source) ¶

Parameters
handler:`Callable[[int]]`	Takes integer parameter: `(device)`

def on_insert(self, handler: Callable[[int]]): (source) ¶

⚠️ Some DFPlayer versions may not (always) report this event for device insertion, but always or sometimes report the 'ready' event instead.

Parameters
handler:`Callable[[int]]`	Takes integer parameter: `(device)`

def on_ready(self, handler: Callable[[int]]): (source) ¶

⚠️ Some DFPlayer versions may not (always) report this event for device readying, but always or sometimes report the 'insert' event instead.

Example:

df.on_ready(lambda d: print("Ready! SD-card available?", bool(d & df.DEVICE_SDCARD)))

Parameters
handler:`Callable[[int]]`	Takes integer parameter (bit field of `DFPlayer.DEVICE_`... constants): `(devices)`

async def pause(self): (source) ¶

Pause playback (can be resumed via resume).

async def play(self, folder: int, file: int, await_start=False): (source) ¶

Start playback of a track or advert.

Adverts will temporarily interrupt tracks.

⚠️ On some DFPlayer versions, adverts may only be played while a regular track is playing.

⚠️ Playback from numeric folders and files prefixed with 0 seems to work but may report an out-of-bounds error.

Examples:

done = await df.play(df.FOLDER_MP3, 24)
await done
print("Playback finished.")

from asyncio import sleep
from asyncio.funcs import gather
done = []
done.append(await df.play(8, 64))
await sleep(4)
done.append(await df.play(df.FOLDER_ADVERT, 12))
await gather(*done)
print("Playback finished.")

Parameters
folder:`int`	Folder of the track to be played (either numeric 1-99 or `DFPlayer.FOLDER_`... constant).
file:`int`	Numeric file prefix (1-3000 in folders 1-15; 1-256 in folders 16-99; 0-9999 in MP3; 0-9999 in ADVERT)
await_start	If set, this coroutine only returns once the player starts playback (is busy). `busy_pin_id` must have been passed to constructor.
Returns
An awaitable that will finish at the end of playback. When looping is enabled, the awaitable will still finish when the first iteration ends.

async def play_advert(self, file: int, await_start=False): (source) ¶

Alias of play(DFPlayer.FOLDER_ADVERT, ...).

async def play_id(self, track_id: int, await_start=False): (source) ¶

Start playback via track's id.

The id refers to the index of the file on the filesystem (starting at 1). This usually resembles the order in which files were copied onto the storage device and can target files in any folder.

⚠️ Using this method is seldom the best approach. Other playback methods are more robust when playing specific files on the filesystem.

async def play_mp3(self, file: int, await_start=False): (source) ¶

Alias of play(DFPlayer.FOLDER_MP3, ...).

async def playing(self): (source) ¶

Fetch whether playback is in progress.

Will use the busy pin, if specified in the constructor. Otherwise is equivalent to (await self.state()) == DFPlayer.STATE_PLAYING.

async def previous(self): (source) ¶

Play the previous track.

async def reset(self): (source) ¶

Resets (reboots) the player.

The reboot can take up to 3 seconds and can be awaited using wait_available

Example:

await df.reset()
await df.wait_available()
# ...

async def resume(self): (source) ¶

Resume playback.

Can also start playback of the file currently internally selected by the player.

@_require_lock
async def send_cmd(self, cmd: int, param1=0, param2: int|None = None, await_busy=False): (source) ¶

Send a raw command to the player.

While usually unnecessary as the full feature-set of the DFPlayer is supported by the API, raw commands can be sent to directly interface with the DFPlayer.

Parameters
cmd:`int`	DFPlayer command byte
param1	uint8 when first of two parameters or single uint16 parameter
param2:`int\|None`	uint8 second parameter
await_busy	If set, an error is raised if the player does not report busy state in response

@_require_lock
async def send_query(self, cmd: int, param1=0, param2: int|None = None): (source) ¶

Send a raw query command to the player and return the responded value.

While usually unnecessary as the full feature-set of the DFPlayer is supported by the API, raw query commands can be sent to directly interface with the DFPlayer.

Parameters
cmd:`int`	DFPlayer command byte
param1	uint8 when first of two parameters or single uint16 parameter
param2:`int\|None`	uint8 second parameter

async def sleep(self): (source) ¶

Set the player into sleep mode.

This changes the playback source to an idle 'sleep' device.

async def source(self, device: int): (source) ¶

Set the playback source device.

Parameters
device:`int`	Set device to one of the `DFPlayer.DEVICE_`... constants.

async def standby(self, enable=True): (source) ¶

Enable or disable the player's standby mode.

This is supposed to be a power-saving mode but does not seem to have a power-saving effect on most or all DFPlayer versions. Due to the player not processing any commands in this mode, disabling standby mode via standby(False) does not actually seem to work.

async def state(self): (source) ¶

Query playback state.

Returns
One of the `DFPlayer.STATE_`... constants.

async def stop(self): (source) ¶

Stop playback.

async def stop_advert(self): (source) ¶

Stop playback of running advert, continuing regular track.

async def track_id(self, device: int|None = None): (source) ¶

Query the currently playing/internally selected track's id on a given storage device.

If no device is specified, the last active one known to this driver is queried.

Parameters
device:`int\|None`	`DFPlayer.DEVICE_`... constant to query.

async def version(self): (source) ¶

Query the player's software version.

async def volume(self, volume: int|None = None): (source) ¶

Query or set the player's volume.

Parameters
volume:`int\|None`	Set volume to a value between 0-30 inclusive.

def wait_available(self): (source) ¶

Await DFPlayer availability (see available)

Can be used at program start to ensure the player is booted up before taking commands.

Example:

df = DFPlayer(0)
df.init()
await df.wait_available()
# ...

Returns
Awaitable that finishes once the player is available to be interfaced with.

async def wake(self): (source) ¶

Wake the player from sleep mode.

This changes the playback source to the last active one known to this driver, defaulting to the SD card.

EQ_BASS = (source) ¶

Bass-heavy equalizer mode.

Value

const(5)

EQ_CLASSIC = (source) ¶

Classic equalizer mode.

Value

const(4)

EQ_FLAT = (source) ¶

Flat (default/balanced) equalizer mode.

Value

const(0)

EQ_JAZZ = (source) ¶

Jazz equalizer mode.

Value

const(3)

EQ_POP = (source) ¶

Pop equalizer mode.

Value

const(1)

EQ_ROCK = (source) ¶

Rock equalizer mode.

Value

const(2)

FOLDER_ADVERT = (source) ¶

'ADVERT' folder on the storage device.

Value

const((-2))

FOLDER_MP3 = (source) ¶

'MP3' folder on the storage device.

Value

const((-1))

MODE_RANDOM_ALL = (source) ¶

Randomize through all tracks (includes adverts).

Value

const(4)

MODE_REPEAT_ALL = (source) ¶

Repeat all tracks sequentially (includes adverts).

Value

const(1)

MODE_REPEAT_FILE = (source) ¶

Repeat a single file.

Value

const(2)

MODE_REPEAT_FOLDER = (source) ¶

Repeat all tracks of a numeric folder.

Value

const(3)

MODE_SINGLE = (source) ¶

Play files once (default).

Value

const(5)

STATE_PAUSED = (source) ¶

Playback halted, track can be resumed.

Value

const(2)

STATE_PLAYING = (source) ¶

Playback in progress.

Value

const(1)

STATE_STOPPED = (source) ¶

Playback halted, no track progress retained.

Value

const(0)

log_level: int = (source) ¶

Print additional communication information (expects DFPlayer.LOG_... constant).

retries: int = (source) ¶

How often to re-send a command on communication failure.

skip_ack: set[int] = (source) ¶

Set of command bytes (see source) to not require/request command ACK for.

timeout: int = (source) ¶

Milliseconds allowed for the player to process and acknowledge (ACK) sent commands.

timeout_busy: int = (source) ¶

Milliseconds allowed between command ACK and busy pin activating (relevant commands only).

timeout_feedback: int = (source) ¶

Milliseconds allowed between command ACK and feedback (error/query value).

def _bytes_to_uint16(self, bytes: tuple[int, int]): (source) ¶

Undocumented

async def _exec_cmd(self, cmd: int, param1=0, param2: int|None = None, use_ack=False): (source) ¶

Undocumented

@_require_lock
async def _fetch_available(self): (source) ¶

Undocumented

def _get_checksum(self, bytes: bytearray): (source) ¶

Undocumented

def _handle_event(self): (source) ¶

Undocumented

def _off(self, event: int, handler: Callable|None): (source) ¶

Undocumented

def _on(self, event: int, handler: Callable): (source) ¶

Undocumented

async def _read(self): (source) ¶

Undocumented

async def _read_loop(self): (source) ¶

Undocumented

async def _receive_message(self, timeout: int): (source) ¶

Undocumented

def _require_lock(func): (source) ¶

Undocumented

def _uint16_to_bytes(self, value: int): (source) ¶

Undocumented

def _validate_read(self, stop: int): (source) ¶

Undocumented

_buffer_read = (source) ¶

Undocumented

_buffer_send = (source) ¶

Undocumented

_busy_flag = (source) ¶

Undocumented

_busy_pin = (source) ¶

Undocumented

_error: DFPlayerError|None = (source) ¶

Undocumented

_events = (source) ¶

Undocumented

_init = (source) ¶

Undocumented

_last_mode = (source) ¶

Undocumented

_last_selected_device = (source) ¶

Undocumented

_lock = (source) ¶

Undocumented

_log = (source) ¶

Undocumented

_message_receive_done = (source) ¶

Undocumented

_message_receive_ready = (source) ¶

Undocumented

_read_task: Task|None = (source) ¶

Undocumented

_stream = (source) ¶

Undocumented

_uart = (source) ¶

Undocumented