adafruit_soundboard API

A CircuitPython library for the Adafruit Sound Boards in UART mode!

This library has been adapted from the library written by Adafruit for Arduino, available at https://github.com/adafruit/Adafruit_Soundboard_library.

  • Author(s): Mike Mabey
adafruit_soundboard.MIN_VOL = 0

Minimum volume level.

adafruit_soundboard.MAX_VOL = 204

Maximum volume level.

adafruit_soundboard.SB_BAUD = 9600

The baud rate for the sound boards. This shouldn’t ever change, since all of the sound board models use the same value.

See also

Adafruit Audio FX Sound Board Tutorial Adafruit’s tutorial on the sound boards.

adafruit_soundboard.DEBUG = False

A flag for turning on/off debug messages.

adafruit_soundboard.CMD_DELAY = 0.01

Seconds to delay after sending a command.

adafruit_soundboard.UART_TIMEOUT = 30

Default UART command timeout in milliseconds. This differs from the default timeout in the UART class, which is 1000 (1 second). Setting a low timeout greatly improves the performance in the absence of an any() method in UART.

class adafruit_soundboard.Soundboard(uart_tx, uart_rx, rst_pin=None, *, vol=None, orig_get_files=False, debug=None, timeout=30, **uart_kwargs)[source]

Control an Adafruit Sound Board via UART.

The Soundboard class handles all communication with the sound board via UART, making it easy to get information about the sound files on the sound board and control playback.

If you need to reset the sound board from your CircuitPython code, be sure to provide the rst_pin parameter. The sound board sometimes gets out of UART mode and reverts to the factory default of GPIO trigger mode. When this happens, it will appear as if the sound board has stoped working for no apparent reason. This library is designed to automatically attempt resetting the board if a command fails, since that is a common cause. So, it is a good idea to provide this parameter.

Parameters:
  • uart_tx (str) – Pin name to use for the transmission (tx) pin for the UART bus to use, (e.g. 'D1'). Acceptable values vary by board. Check your board’s documentation for more info.
  • uart_rx (str) – Pin name to use for the reception (rx) pin for the UART bus to use, (e.g. 'D0'). Acceptable values vary by board. Check your board’s documentation for more info.
  • rst_pin (str) – Identifier for the pin (on the CircuitPython board) connected to the RST pin of the sound board. Valid identifiers vary by board, but should be something like 'D5'.
  • vol (int or float) – Initial volume level to set. See vol for more info.
  • orig_get_files (bool) – Uses the original method to get the list of track file names. See use_alt_get_files() method for more info.
  • debug (bool) – When not None, will set the debug output flag to the boolean value of this argument using the toggle_debug() method.
  • timeout (int) – Timeout parameter passed to the UART object, which is in milliseconds. Should be an int no greater than 1000. If not an int, will fall back to the default value specified in this method’s signature, UART_TIMEOUT. If an int but not in the range [1, 1000], will fall back to the UART class’s default of 1000.
  • uart_kwargs (dict) – Additional values passed to the constructor of the UART object. Acceptable values here also vary by board. It is not necessary to include the baud rate among these keyword values, because it will be set to SB_BAUD when the UART object is instantiated.
_send_simple(cmd, check=None, strip=True)[source]

Send the command, optionally do a check on the output.

The sound board understands the following commands:

  • L: List files on the board
  • #: Play a file by number
  • P: Play a file by name
  • +: Volume up (range is 0-204, increments of 2)
  • -: Volume down
  • =: Pause playback
  • >: Un-pause playback
  • q: Stop playback
  • t: Give current position of playback and total time of track
  • s: Current track size and total size
Parameters:
  • cmd (bytes) – Command to send over the UART bus. A newline character will be appended to the command before sending it, so it’s not necessary to include one as part of the command.
  • check (str or bytes or None or bool) – Depending on the type of check, has three different behaviors. When None (default), the return value will be whatever the output from the command was. When a str or bytes, the return value will be True/False, indicating whether the command output starts with the value in check. When it otherwise evaluates to True, return value will be True/False, indicating the output started with the first character in cmd.
Returns:

Varies depending on the value of check.

Return type:

bytes or bool

files

Return a list of the files on the sound board.

Warning

The filenames are always of type bytes, not str.

Return type:list(bytes)
sizes

Return a list of the files’ sizes on the sound board.

Return type:list
lengths

Return a list of the track lengths in seconds.

Note

In my own testing of this method, the board always returns a value of zero seconds for the length for every track, no matter if it’s a WAV or OGG file, short or long track.

Return type:list
file_name(n)[source]

Return the name of track n.

Parameters:n (int) – Index of a file on the sound board or False if the track number doesn’t exist.
Returns:Filename of track n.
Return type:bytes or bool
track_num(file_name)[source]

Return the track number of the given file name.

Parameters:file_name (bytes) – File name of the track. Should be one of the values from the files property.
Returns:The track number of the file name or False if not found.
Return type:int or bool
play(track)[source]

Play a track on the board.

Parameters:track (int or bytes) – The index (int) or filename (bytes) of the track to play.
Returns:If the command was successful.
Return type:bool
play_now(track)[source]

Play a track on the board now, stopping current track if necessary.

Parameters:track (int or bytes) – The index (int) or filename (bytes) of the track to play.
Returns:If the command was successful.
Return type:bool
vol

Current volume.

This is implemented as a class property, so you can get and set its value directly. When setting a new volume, you can use an int or a float (assuming your board supports floats). When setting to an int, it should be in the range of 0-204. When set to a float, the value will be interpreted as a percentage of MAX_VOL.

Return type:int
vol_up(vol=None)[source]

Turn volume up by 2 points, return current volume level [0-204].

Parameters:vol (int) – Target volume. When not None, volume will be turned up to be greater than or equal to this value.
Return type:int
vol_down(vol=None)[source]

Turn volume down by 2 points, return current volume level [0-204].

Parameters:vol (int) – Target volume. When not None, volume will be turned down to be less than or equal to this value.
Return type:int
pause()[source]

Pause playback, return if the command was successful.

Return type:bool
unpause()[source]

Continue playback, return if the command was successful.

Return type:bool
stop()[source]

Stop playback, return if the command was successful.

Return type:bool
track_time()[source]

Return the current position of playback and total time of track.

Return type:tuple
track_size()[source]

Return the remaining size and total size.

It seems the remaining track size refers to the number of bytes left for the sound board to process before the playing of the track will be over.

Returns:Remaining track size and total size
Return type:tuple
reset()[source]

Reset the sound board.

Soft reset the board by bringing the RST pin low momentarily (10 ms). This only has effect if the reset pin has been initialized in the constructor.

Doing a soft reset on the board before doing any other actions can help ensure that it has been started in UART control mode, rather than GPIO trigger mode.

See also

Soundboard Pinout
Documentation on the sound boards’ pinouts.
Returns:Whether the reset was successful. If the reset pin was not initialized in the constructor, this will always return False.
Return type:bool
use_alt_get_files(now=False)[source]

Get list of track files using an alternate method.

If the list of files is missing tracks you know are on the sound board, try calling this method. It doesn’t depend on the sound board’s internal command for returning a list of files. Instead, it plays each of the tracks using their track numbers and gets the filename and size from the output of the play command.

Parameters:now (bool) – When set to True, the alternate method of getting the files list will be called immediately. Otherwise, the list of files will be populated the next time the files property is accessed (lazy loading).
Return type:None
static toggle_debug(debug=None)[source]

Turn on/off DEBUG flag.

Parameters:debug – If None, the DEBUG flag will be toggled to have the value opposite of its current value. Otherwise, DEBUG will be set to the boolean value of debug.
Return type:None
adafruit_soundboard.printif(*values, **kwargs)[source]

Print a message if DEBUG is set to True.

adafruit_soundboard.int_to_bytes(num)[source]

Convert the given integer to bytes.

For example, giving the int 1 would return the byte string b'1'.

Parameters:num (int) – The number to convert. Should be non-negative, but works either way.
Returns:The number as a byte string.
Return type:bytes