🔊 Play sounds in Python scripts

play_sounds provides a simple cross-platform API to play sounds in Python scripts. It includes a synchronous API and an equivalent asynchronous API that is compatible with asyncio and trio.

For code examples, you can check out onhold and ding, or scroll down to the Usage section.

Why play_sounds?

boombox is great and 90% of the way there, however it is limited to only playing WAV files on Windows. playsound will play other formats than WAV on Windows, but it requires GStreamer and PyGObject bindings on Linux, while boombox has several playback backends for Linux other than, and including, GStreamer.

Neither boombox or playsound provide asyncio and async/await compatible APIs, but play_sounds does.

If you're targeting multiple desktop platforms and don't want to get mired down in the details of when and where to use playsound or boombox, or if your project uses async/await, you can just reach for play_sounds and call it a day.

Installation

$ python3 -m pip install play_sounds

Usage

This library uses pathlib.Path objects when pointing to filenames and paths. It can use aiopath.AsyncPath objects, too.

There's a synchronous API and an asynchronous API that you can use with the async/await syntax and asyncio.

Synchronous API

Play a file

from pathlib import Path
from play_sounds import play_file


DEFAULT_SONG: Path = Path("/path/to/song.mp3")


play_file(DEFAULT_SONG)  # blocks by default

# play without blocking
play_file(DEFAULT_SONG, block=False) 

Play while work completes

from time import sleep
from pathlib import Path
from play_sounds import play_while_running


DEFAULT_SONG: Path = Path("/path/to/song.mp3")
WAIT: int = 60


with play_while_running(DEFAULT_SONG):
  sleep(WAIT)

Play a file after work completes

from time import sleep
from pathlib import Path
from play_sounds import play_after


DEFAULT_SOUND: Path = Path("/path/to/song.mp3")
WAIT: int = 60


with play_after(DEFAULT_SOUND):  # blocks by default
  sleep(WAIT)

# play without blocking
with play_after(DEFAULT_SOUND, block=False):
  sleep(WAIT)

Ring the terminal bell

from play_sounds import bell, bell_after


# play bell
bell()

# ensure the bell is played even if an exception is thrown
with bell_after():
  raise Exception("Bye")

Asynchronous API

To run the following examples with top-level await expressions, launch an asynchronous Python REPL using python3 -m asyncio or an IPython shell.

Play a file

from pathlib import Path
from play_sounds import play_file_async


DEFAULT_SONG: Path = Path("/path/to/song.mp3")
WAIT: int = 60


await play_file_async(DEFAULT_SONG)  # blocks by default

# play without blocking
await play_file_async(DEFAULT_SONG, block=False) 

Play while work completes

from asyncio import sleep
from pathlib import Path
from play_sounds import play_while_running_async


DEFAULT_SONG: Path = Path("/path/to/song.mp3")
WAIT: int = 60


async with play_while_running_async(DEFAULT_SONG):
  await sleep(WAIT)

Play a file after work completes

from asyncio import sleep
from pathlib import Path
from play_sounds import play_after_async


DEFAULT_SOUND: Path = Path("/path/to/song.mp3")
WAIT: int = 60


async with play_after_async(DEFAULT_SOUND):  # blocks by default
  await sleep(WAIT)

# play without blocking
async with play_after_async(DEFAULT_SOUND, block=False):
  await sleep(WAIT)

Support

Want to support this project and other open-source projects like it?

Copyright

See CREDIT.md.

License

See LICENSE.