play_sound

Signature:

BoosterRobot.play_sound(
    audio: str | PathLike[str] | AudioData | Iterable[AudioData],
    *,
    volume: float | None = None,
    on_done: Callable[[TaskHandle[None]], None] | None = None,
    on_status_change: Callable[[TaskHandle[None]], None] | None = None,
) -> TaskHandle[None]

Description:

Play audio asynchronously.

Parameters:

Parameter	Type	Default	Description
audio	str | PathLike[str] | AudioData | Iterable[AudioData]	Required	Local audio file path directly accessible in the robot runtime environment (e.g., /data/hello.wav), a single AudioData object, or a finite sequence of AudioData; file paths support .wav, .mp3, .pcm.
volume	float | None	None	Playback volume, range 0.0 to 1.0; None uses the default volume.
on_done	Callable[[TaskHandle[None]], None] | None	None	Callback invoked when the task enters a terminal state.
on_status_change	Callable[[TaskHandle[None]], None] | None	None	Callback invoked when the task status changes.

Returns:

TaskHandle[None], see "Tasks and Subscriptions / TaskHandle"

Raises:

TypeError: audio is not a file path, AudioData, or a finite AudioData sequence.

ValueError: File path is an empty string, or volume is outside 0.0 to 1.0.

RuntimeError: Audio manager failed to initialize successfully, an audio task in the same group is running, or playback startup failed. When the file does not exist, is not a local file, or has an unsupported extension, it will also be raised as RuntimeError during startup. In-memory audio format validation and playback errors are typically written to handle.error and cause the task to enter FAILED.

Example:

from boosteros.robots.booster import BoosterRobot

robot = BoosterRobot()
handle = robot.play_sound("/data/hello.wav")
status = handle.wait(timeout=30.0)
print(status)
# Example output: 'SUCCEEDED'

robot.audio_manager.start_recording()
input("Press Enter to stop recording")
audio = robot.audio_manager.stop_recording()
handle = robot.play_sound(audio, volume=0.3)
status = handle.wait(timeout=audio.duration.seconds + 10.0)
print(status)
# Example output: 'SUCCEEDED'