API Reference

This page documents all public functions and classes provided by the blurt package.

blurtpy - Cross-platform voice feedback library for Python.

This package provides: - Global utility functions: say, beep, play_sound, list_voices - Decorators: notify_when_done, announce_during - Blurt class for custom configurations

class blurt.Blurt(config: Dict | None = None)

Bases: object

Blurt is a cross-platform voice utility class that lets you speak messages, beep, or play sounds. It supports macOS, Linux, and Windows, and automatically chooses the correct driver.

beep()

Play a beep sound.

list_voices() → List[str]

Return available voices on the system.

play_sound(path: str | None = None)

Play a sound file. Defaults to alert.mp3.

say(message: str)

Speak a message aloud.

set_rate(rate: int)

Set the speaking rate.

set_voice(voice: str)

Set the system voice.

set_volume(volume: float)

Set the speaking volume.

blurt.announce_during(start: str = 'Started', end: str = 'Completed')

Context manager that announces messages before and after a code block.

Example

with announce_during(“Processing started”, “Processing finished”):

do_something()

blurt.beep()

Play a simple beep sound using the global Blurt instance.

blurt.list_voices() → List[str]

Return a list of available voices supported on this system.

blurt.notify_when_done(message: str = 'Task completed')

Decorator that announces a message after the decorated function completes.

blurt.play_sound(path: str | None = None)

Play a sound file. If no path is provided, play the default alert sound.

blurt.say(message: str)

Speak the given message aloud using the global Blurt instance.

Global Functions

say(message: str)

Speaks a message out loud using the system’s speech engine.

• Parameters: message (str): The message to speak.

• Behavior: Uses say on macOS, espeak or spd-say on Linux, and pyttsx3 on Windows.

• Mute option: Set environment variable BLURT_MUTE=true to disable speaking.

beep()

Plays a short beep sound.

• Platform-specific behavior: - macOS: plays a system sound - Windows: uses winsound.Beep - Linux: uses aplay or prints ASCII bell (a)

play_sound(path: str = None)

Plays a custom sound file.

• Parameters: path (str, optional): Path to .mp3 or .wav file. If omitted, default sound is used.

• Platform-specific behavior: - macOS: uses afplay - Windows: uses winsound.PlaySound - Linux: uses aplay

list_voices() -> List[str]

Returns a list of available system voices.

notify_when_done(message: str = “Task completed”)

A decorator that speaks a message when a function finishes executing.

• Parameters: message (str): The message to announce when the function completes.

• Usage: Use @notify_when_done(“All done!”) before your function.

announce_during(start: str = “Started”, end: str = “Completed”)

Context manager to announce the beginning and end of a block of code.

• Parameters: - start (str): Message spoken before the block runs. - end (str): Message spoken after the block finishes.

Class-based API

Blurt(config: dict = None)

A class for advanced and configurable voice/sound notifications.

• Parameters: - config (dict, optional): Configuration for rate, volume, voice, pitch, language.

• Methods: - say(message: str) - beep() - play_sound(path: str = None) - list_voices() -> List[str] - set_rate(rate: int) - set_volume(volume: float) - set_voice(voice: str)

See Configuration for all config options.